View Transitions and gestures: snapshots, springs, and seizing values mid-flight

startViewTransition: the snapshot machine

Before FLIP and CSS transitions, route changes that animated between two genuinely different page states required keeping old and new DOM simultaneously alive and in sync — the AnimatePresence-style complexity that made animation code brittle. document.startViewTransition(callback) solves this differently: it runs a fixed protocol. The browser captures the old state — a static snapshot of the page, plus a separate snapshot for every element with a view-transition-name. It then runs your callback, which must actually mutate the DOM (and may return a promise the browser awaits). When the callback settles, the browser captures the new state, builds a tree of pseudo-elements layered over the page — ::view-transition at the root, and per name a ::view-transition-group containing an ::view-transition-image-pair with ::view-transition-old (the static bitmap) and ::view-transition-new (a live representation of the new content) — and animates between them. The default is a crossfade for the root plus position-and-size interpolation for each named group; everything is customizable with plain CSS animations targeting the pseudo-elements, because that is all they are: elements the browser owns, styled with CSS you write.

The naming contract matters: view-transition-name must be unique among captured elements in each state — a duplicate makes the transition skip (the ready promise rejects), which is the classic bug when a list of cards all get view-transition-name: card from one CSS rule. And the API is same-document by default; cross-document MPA transitions opt in with the @view-transition { navigation: auto; } CSS rule on both same-origin pages, which is what makes snapshot-based transitions work even when the old document is destroyed mid-navigation.

The React seam: flushSync or nothing visibly changes

The browser snapshots “new” when your callback settles. React state updates are queued, not synchronous — so this is the canonical integration bug:

import { flushSync } from "react-dom";

function navigate(next) {
  if (!document.startViewTransition) {
    setRoute(next);                    // graceful degradation: no animation
    return;
  }
  document.startViewTransition(() => {
    // The DOM must be in its NEW state when this callback returns.
    // A bare setRoute(next) queues the update: the callback returns with the
    // DOM unchanged, the browser snapshots old === new, and the real commit
    // pops in AFTER the transition — fade into the same frame, then a jump.
    flushSync(() => setRoute(next));
  });
}

flushSync forces React to render and commit synchronously inside the callback — exactly the place where the cost of a sync commit is the point, not a smell. React 19’s <ViewTransition> component wraps this machinery declaratively — it activates on transitions started with startTransition, integrates with Suspense reveals, and matches shared elements by name. Honest status: it lives in the experimental release channel only (react@experimental), not in stable React 19 — on a stable channel today, the startViewTransition + flushSync seam above is the production pattern, and it is small enough to own.

Gestures: one pointer model, three disciplines

Pointer events unified mouse, touch, and pen into one stream: pointerdown, pointermove, pointerup, each carrying a pointerId. The structural tool is setPointerCapture(pointerId): the element keeps receiving the stream even when the finger leaves its bounds — no document-level listener bookkeeping, no lost drags when the pointer outruns the sheet. Around that, three disciplines separate 60 fps from the Hook’s 12:

function onPointerDown(e) {
  sheet.setPointerCapture(e.pointerId);
  running.current?.cancel();                       // seize: kill the spring mid-flight
  const m = new DOMMatrixReadOnly(getComputedStyle(sheet).transform);
  grabOffset.current = m.m42 - e.clientY;          // continue from the CURRENT value
  maxTravel.current = sheet.offsetHeight;          // read layout ONCE, here
}

function onPointerMove(e) {
  latestY.current = e.clientY;                     // store only — never read layout here
  raf.current ??= requestAnimationFrame(() => {
    raf.current = null;                            // one write per frame, not per event
    sheet.style.transform = `translateY(${clamp(latestY.current + grabOffset.current)}px)`;
  });
}

Discipline one — rAF-batch the writes. pointermove fires at input frequency, which on modern digitizers exceeds the frame rate; writing styles per event does invisible duplicate work, and handler time directly delays the next frame. Store the latest position; write once per frame. Discipline two — no layout reads in move handlers. The Hook’s offsetHeight per move was a forced synchronous layout multiplied by event frequency; measure everything on pointerdown and cache it. Discipline three — declare intent to the browser. touch-action: none on the drag handle tells the browser the gesture is yours, so it does not wait to see whether you meant to scroll; everywhere else, leave scrolling to the compositor and keep listeners passive so it stays there.

Release and interruption: the finger owns the value

On pointerup, compute release velocity from the last few move samples and hand the value to a spring or inertia animation — WAAPI with generated keyframes, or a rAF spring if you need live retargeting. The hard rule is interruption: a new pointerdown during the animation must seize the value mid-flight — read the current transform (via getComputedStyle and DOMMatrixReadOnly, or from your own spring state), cancel the animation, and start the drag from exactly that value. The two tempting alternatives both read as defects: waiting for finished makes the surface ignore a touching finger (the Hook’s “broken”), and restarting from the animation’s target teleports the sheet under the user’s thumb. Direct manipulation inverts the usual UI contract — for buttons, input is a request; for a dragged surface, input is possession.

Touch budgets: the 12 fps postmortem, quantified

Replay the Hook with numbers. pointermove at ~120 events/s on the digitizer, ~2 events per 60 Hz frame. Each handler: write height (~invalidates layout) then read offsetHeight — forced synchronous layout, 5–8 ms on a mid-range SoC. Two events per frame ≈ 10–16 ms of forced layout, plus the style/paint the height change itself dirties ≈ blown budget every frame: 12 fps. The fixed handler: one rAF-batched transform write per frame (microseconds), zero layout reads after pointerdown, touch-action: none so the browser is not second-guessing scroll intent. Same hardware, 60 fps — the difference was never the phone. Two closing notes: getCoalescedEvents() exposes the full-resolution trail of merged moves if you need ink-level precision without per-event handlers; and prefers-reduced-motion applies to gestures’ release animations too — snap instead of spring for users who asked for that.