How Splotch keeps up with a toddler's finger

Start here

Everything has to fit inside one frame

A screen never shows motion. It shows a stack of still pictures, one after another, fast enough that the eye fills in the movement. Each picture has a deadline. Every mechanism on this page exists to hit that deadline while a child scribbles as fast as they can.

The map

Six habits explain almost every mechanism

A hundred and one optimizations sound like a pile. They are not. Read the code and the same six habits show up again and again. The first four do most of the work; the last two cover the edges. Each card is a section below.

A touch digitizer reports finger positions faster than the screen can show them. On the iPad the engine measured 1.9 to 4.2 movement samples per painted frame. If every sample triggered painting, the same frame would be drawn two to four times over, and the extra passes would be invisible.

function flushAll() {
  if (rasterFrame !== 0) {
    cancelAnimationFrame(rasterFrame);
    rasterFrame = 0;
  }
  drainQueues();          // finger lifted: paint what is left right now
}

function schedule() {
  if (rasterFrame !== 0) return;   // a frame is already booked
  rasterFrame = requestAnimationFrame(() => {
    rasterFrame = 0;
    drainQueues();        // every pointer's queued samples become one op each
  });
}

The same habit, elsewhere

A stroke changes a sliver of the paper. If the app treated the paper as one big bitmap, every stroke, every undo, and every theme switch would pay for the whole surface. So the paper is not one bitmap. It is twenty.

for (const [index, tile] of liveTiles.entries()) {
  if (geometryIntersectsTile(op, tile)) {
    ensureNormalTileBacking(tile);            // first touch allocates the bitmap
    prepareTileForMutation(tile, index);
    if (command && !command.wasEmpty) {
      undoPatches.capture(command, tile, index, opDeviceBounds(tile, op));
    }
    // ...render the op into this one tile
  }
}

Undo is a pixel patch, not a replay

const budget =
  liveTiles.reduce((total, tile) => total + tile.width * tile.height * 4, 0) *
  TILED_UNDO_PATCH_BUDGET_PAPER_MULTIPLE;               // 6 papers of RGBA
let bytes = history
  .slice(-undoableCommands)
  .reduce((total, command) => total + undoPatches.bytes(command), 0);
while (undoableCommands > MIN_TILED_UNDO_COMMANDS && bytes > budget) {
  // drop the oldest patch; the command stays replayable from its vectors
}

The same habit, elsewhere

Plenty of work is worth doing but not worth doing now: warming a font, mounting a dialog nobody has opened, folding old undo history, checking whether the eraser emptied the page. All of it goes through one scheduler that refuses to run while a child is drawing.

frame = requestAnimationFrame((first) => {
  frame = requestAnimationFrame((second) => {
    if (cancelled) return;
    if (second - first > FRAME_BUSY_GAP_MS || !signalsAreQuiet()) {
      requeue();          // a frame ran long, or input arrived: try again later
      return;
    }
    fn();                 // two clean frames in a row: the lane is free
  });
});

What waits for idle

A toddler does not wait for a spinner. The page arrives as finished HTML with its styles inlined, the drawing engine starts before the framework has even loaded, and everything that is not needed for the first stroke is loaded later, in a separate file, with a test that fails if it creeps back in.

1. HTML arrives already rendered, with every stylesheet inlined in its head.
2. The state stamp runs inline and paints the saved theme and layout before anything else.
3. The drawing engine boots and starts accepting strokes.
4. Hydration runs its ~375 ms task while the engine keeps drawing underneath it.
5. Idle work begins only after that: the overlay chunk, fonts, coloring packs.
6. The service worker registers after the third committed stroke.

Not to scale. The point is the ordering: the engine is live before hydration starts, and the idle work only begins after it ends.

export function adoptDrawingCanvas(canvasElement: HTMLCanvasElement, options: InitOptions = {}) {
  if (!engineOwnsCanvas(canvasElement)) return initDrawingCanvas(canvasElement, options);
  attachCallbacks(options);                      // earlyBoot already drew the first strokes
  callbacks.onUndoStateChange?.(canUndo);
  callbacks.onCanvasEmptyChange?.(canvasEmpty);
  notifyViewChange();
  return { teardown: teardownEngine };
}

What is in the startup bundle, and what is not

function loadScreenshotModule() {
  if (screenshotModulePromise) return screenshotModulePromise;
  const loading = import('$lib/drawing/screenshot').catch((error) => {
    if (screenshotModulePromise === loading) screenshotModulePromise = null;  // retry next tap
    throw error;
  });
  screenshotModulePromise = loading;
  return loading;
}

The same habit, elsewhere

The main thread is where strokes are painted, so anything else that can run somewhere else, should. Two "somewhere elses" exist in a browser: the compositor, which applies transforms and blends on the GPU, and web workers, which run JavaScript on a separate thread.

.live-paper-view {
  position: absolute;
  top: 0;
  left: 0;
  transform-origin: 0 0;
  /* Permanent promotion avoids the rotation undo spike; engine-rotation.spec.ts enforces it. */
  will-change: transform;
}

The crayon: three ways to deposit wax, two of them shipping

configureCrayonDeposition(
  __IS_CAPACITOR__ ? 'glaze-direct' : 'restamp',
  () => activePointers.size > 0
);

The same habit, elsewhere

The network is the one resource the app cannot schedule. So the rules are about not needing it: cache what has already been seen, fetch in the background, and make sure nothing on screen ever waits on a byte that has not arrived.

const img = new Image();
img.fetchPriority = 'high';
img.src = url;
const show = () => {
  if (!stale) {
    displayedOverlayUrl = url;      // swap only when the pixels are ready
  }
};
img.decode().then(show, show);      // on failure, show anyway: same broken state

The same habit, elsewhere

Putting it together

One stroke, start to finish

Here is everything above in the order a child experiences it. Each step names the habit at work, so you can see that the six are not six separate systems. They are one system, read from different angles.

1. 4 · startup

   The page arrives

   Prerendered HTML with every stylesheet inlined. An inline script stamps the saved theme and layout onto the document before the first paint. The drawing engine boots from a side-effect import and is accepting strokes before the framework's 375 ms hydration task even starts. The save pipeline, the dialogs, the coloring-pack downloader, and the native plugins are in other files that have not been requested yet.

2. 1 · per frame

   A finger touches the glass

   The pointer is captured. Its screen position maps to paper through a cached rectangle, not a layout query. The input canvas is 1 pixel wide, so the compositor pays nothing for it. A halo ring appears on a GPU-composited transform.

3. 1 · per frame

   The finger moves

   Every batched digitizer sample is read, so the curve is smooth, and pushed onto the pointer's queue. One animation frame is requested if none is booked. When it arrives, the queue drains into one render operation carrying every sample as its own curve segment.

4. 2 · only what changed

   The operation is painted

   Its padded bounding box is tested against the 20 tiles. Only intersecting tiles allocate a backing on first touch, capture a one-time undo snapshot, are un-hidden, and run the brush. The crayon re-glazes only the operation's rectangle on the web, or applies its glaze per op directly on the tile in the native app.

5. 3 · at idle

   Meanwhile, everything else waits

   A pointer is down, so the idle scheduler refuses every deferred job: no dialog mounts, no history fold, no wax warm-up, no coloring-pack fetch, no font warm. The rotation hold, the resize settle timer, and the drawer's motion marker make sure a device rotation mid-stroke costs one layer transform and not a repaint.

6. 2 · only what changed

   The finger lifts

   The queue drains synchronously so no sample is lost. The command commits: each touched tile's snapshot is cropped to the dirty rectangle and joins a byte-budgeted history. If it was an eraser stroke, the "is the page blank now?" scan is scheduled for 400 ms of idle rather than run on the spot. On the third committed stroke of a first visit, the service worker is allowed to register.

7. 3 · at idle

   The quiet after

   After 300 ms of quiet and two clean frames, deferred work drains one slice at a time: the overlay chunk imports, the color picker mounts, the coloring book mounts, the oldest command outside the undo window folds into the raster base, the export compositor and its paper texture warm, and a coloring book downloads file by file. Any tap on a dialog jumps that queue and mounts it at once.

8. 5 · off main thread

   The camera button

   The screenshot module loads at press. The tiles are captured as transferable bitmaps at pointer-down, composed and encoded to PNG in a worker, and previewed from a worker-side downscale. A second tap inside 4 s is folded into the first so MobileSafari can reclaim its surfaces.

9. 6 · network

   A coloring page is picked

   The picker shows raster selectors, not live SVG. The chosen page's line art fetches at high priority, decodes off-screen, and swaps in by opacity only when ready; every other in-flight warm is canceled so it gets the bandwidth. The picker itself retires on the compositor before the paper changes underneath it, and under a finger it has no backdrop blur to pay for.

Receipts

The measured wins

Every mechanism above was kept because a number moved. These are the before-and-after pairs recorded in the ADRs, issue threads, and scratchpad notes, on the device they were measured on.

Where it stands

Lost frame time on the physical devices, today

The performance matrix captured on September 3, 2026 at product commit d17100cb. Each cell is the worst of four modes (portrait and landscape, light and dark) for that device and brush. Darker means more lost time; a red outline would mean a gate breach. There are none.

The native apps are noticeably cleaner than the same code in a browser tab. That gap is not the app's code; it is Safari and Chrome doing more per frame than a WKWebView or Android WebView does. Open the full matrix for every mode, the undo and action rows, and the provenance behind each cell.

How the numbers are earned

A capture has to prove itself before it is scored

A performance number is only as honest as the recording behind it. The harness that produced the chart above refuses more captures than it scores, and the rules for refusing are the interesting part.

The full terminology and the two validation grids live in docs/PERFORMANCE.md; the profiling runbooks are under docs/PROFILING*.md.

The graveyard

Tried, measured, and taken out

A performance page that only lists wins is a sales pitch. These are the mechanisms that looked right, were built, and lost to a number.

The full list

Every mechanism, sorted by habit

The complete inventory from docs/PERFORMANCE.md, re-checked entry by entry against the source at commit 3c01779. Entries whose description changed since the doc was written are marked revised; mechanisms the doc did not list yet are marked new. Every file link points at the verified commit, so the line numbers hold.

Keep beside the code

Jargon decoder

Beat

The steady gap between frames the display holds: 16.7 ms at 60 Hz, 8.3 ms at 120 Hz. Measured from each capture, never assumed.

Bounding box

The smallest rectangle that could contain an operation's ink, padded for stroke width and anti-aliasing. Drives culling and undo cropping.

Bundle / chunk

One JavaScript file the browser must download and parse before running it. The startup bundle is what the first frame needs.

Coalesced events

The digitizer samples the browser batched between two pointer events, exposed by getCoalescedEvents().

Compositor

The browser stage that stacks painted layers into the final picture, usually on the GPU. Transforms, opacity, and blends can run there without repainting.

Culling

Skipping tiles whose bounds cannot intersect an operation.

Device pixel ratio (DPR)

Physical pixels per CSS pixel. Splotch renders at min(DPR, 2).

Dirty rectangle

The smallest conservative pixel box a command may have changed.

Fold

Rasterize an old, no-longer-undoable command into the offscreen raster base so its vectors can be dropped.

Hydration

The framework attaching behavior to prerendered HTML. About 375 ms of main-thread work on the iPad.

Idle

A stretch where the main thread has nothing urgent. Splotch's definition: no pointer down, input quiet, two clean frames.

ImageBitmap / OffscreenCanvas

A decoded bitmap that can be transferred to a worker, and a canvas that lives there.

Layout (reflow)

The browser recomputing element positions. Reading getBoundingClientRect() after a change forces one.

Lost frame time

Share of in-contact time spent inside late frames. Gate: 1%.

Main thread

The single lane running JavaScript, style, layout, and paint. A busy lane means a late frame.

P95 / P99

The value 95% (or 99%) of samples fall under. A P95 of 20 ms means one frame in twenty was slower.

Paint latency

Finger movement to the frame that showed its ink.

Patch

A cropped pre-command pixel snapshot used to reverse the newest command.

Precache

Files the service worker downloads on install so they open offline: the app shell and the starter book only.

rAF

requestAnimationFrame: run this once, right before the next frame. The loop only continues if the callback re-requests it.

Readback

Copying pixels from the GPU back to JavaScript. Slow, and it can push a canvas off the GPU permanently.

Service worker

A background script that intercepts the page's network requests and can answer from a cache.

Single flight

Overlapping callers share one in-flight promise instead of starting duplicate work.

Tile

One cell in the 4 × 5 grid of live canvases that together present the paper.

will-change

A CSS hint that an element will animate a property, so the browser gives it its own compositor layer up front.

Worker

A JavaScript thread separate from the main one. No DOM access, but it can own an OffscreenCanvas.

WKWebView / WebView

The embedded browser engine inside the iOS and Android native apps. Same code, different compositor behavior from Safari and Chrome.

Where to read the production implementation

Architectural records behind this page