@bycrux/editor 0.12.0 → 1.0.1

package/src/video/timeline/canvas/snap.ts

@@ -0,0 +1,232 @@
+/**
+ * Canvas timeline snapping (SP5 T5) — ONE magnetic model for every gesture.
+ *
+ * The DOM timeline snapped in three different ways: the Scrubber's playhead
+ * drag used attract/release hysteresis (18px in, 28px out), while clip drags
+ * and edge trims used a flat 8px "nearest boundary wins" test with no memory.
+ * The flat version has the classic problem — right at the threshold the value
+ * flickers between snapped and free as the hand jitters — and the two radii
+ * disagreed about how strong a magnet feels. Plan decision 7 keeps the good one
+ * and retires the others. (It once applied to the canvas surface only, while
+ * the DOM rows kept the flat test; those rows are gone, so this is simply how
+ * snapping works.)
+ *
+ * The hysteresis is what makes it feel deliberate: a point attracts from one
+ * radius but holds until the cursor clears a wider one. The asymmetry is the
+ * whole trick — with one radius, "just past the edge of the magnet" is an
+ * unstable place to stand. See `DEFAULT_SNAP_CONFIG` for the two numbers and
+ * why they are as far apart as they are.
+ *
+ * Pixels, not seconds, are the unit of feel: a magnet must cover the same
+ * distance on screen whether the timeline shows ten seconds or ten minutes, so
+ * the radii convert through `pxPerSecond` on every call.
+ *
+ * Points come in two strengths. A boundary on the gesture's own track pulls
+ * hard; a boundary on some other track barely pulls at all, and loses to a
+ * same-track point outright when both are in range. Without that split, one
+ * busy overlay row is enough to make the base video track undraggable — see
+ * `SnapStrength`.
+ *
+ * Pure and stateless-by-value: `applySnap` takes a state and returns the next
+ * one, so a gesture threads it and a test drives a whole approach/release
+ * sequence without a component.
+ */
+
+import type { Viewport } from './viewport'
+
+/**
+ * How hard a given snap point pulls.
+ *
+ * `strong` is a boundary on the gesture's OWN track — the next clip along, the
+ * cut you are butting up against. That is the alignment an editor actually
+ * means, and it gets the full magnet.
+ *
+ * `weak` is everything on some other track: an overlay two rows up, an audio
+ * bar below. Those alignments are occasionally useful and constantly in the
+ * way — a busy overlay track puts a boundary every few pixels, and at full
+ * strength they turn a simple drag into a fight. They keep a radius small
+ * enough to catch a deliberate aim and too small to catch a passing one.
+ */
+export type SnapStrength = 'strong' | 'weak'
+
+export interface SnapPoint {
+  time: number
+  strength: SnapStrength
+}
+
+export interface SnapConfig {
+  /** Distance at which an unsnapped gesture is captured by a strong point. */
+  attractPx: number
+  /** Distance a captured strong point must travel to break free. Must exceed
+   *  `attractPx`, or the magnet has no hysteresis at all. */
+  releasePx: number
+  /** The same pair for weak points. */
+  weakAttractPx: number
+  weakReleasePx: number
+}
+
+/**
+ * The magnet's strength.
+ *
+ * These started as Scrubber.tsx's numbers (18/28) and were widened after using
+ * the canvas timeline in anger. Two separate complaints, one fix each:
+ *
+ * - `attractPx` 18 → 20. A cut you are aiming at should catch you slightly
+ *   before you land on it, so the common case (butt this clip against that
+ *   one) needs no precision at all.
+ * - `releasePx` 28 → 44. This is the one that changes how the timeline FEELS.
+ *   A 28px release meant a snapped gesture came free about as easily as it was
+ *   caught, so dragging PAST a boundary — a deliberate act — was
+ *   indistinguishable from drifting off one. At 44px breaking out is a
+ *   decision: the guide holds, you push through it, it lets go. The ratio
+ *   (2.2× attract) is what reads as a detent rather than as friction.
+ *
+ * Widening the release radius is only tolerable because the snap is now VISIBLE
+ * — `drawSnapGuide` puts a line on the boundary you are held to. A strong
+ * magnet with no indicator is just a timeline that refuses to go where you put
+ * it; with the guide, the same magnet reads as help.
+ */
+export const DEFAULT_SNAP_CONFIG: SnapConfig = {
+  attractPx: 20,
+  releasePx: 44,
+  // A third of the strong radius, and barely wider than it is deep. A
+  // cross-track boundary should be catchable when you aim at it and
+  // effectively invisible when you don't — you can drag straight through one
+  // without noticing, which is the point.
+  weakAttractPx: 6,
+  weakReleasePx: 10,
+}
+
+export interface SnapState {
+  /** The point currently held, or null when the gesture is running free. */
+  readonly snappedTo: number | null
+  /** How hard the held point pulls — it decides which release radius applies,
+   *  so a weak capture stays as easy to leave as it was to enter. */
+  readonly strength: SnapStrength | null
+}
+
+const FREE: SnapState = { snappedTo: null, strength: null }
+
+export function createSnapState(): SnapState {
+  return FREE
+}
+
+export interface SnapResult {
+  /** The value to use: the snap point when caught, the candidate otherwise. */
+  time: number
+  snappedTo: number | null
+  /** Which tier caught it, so the caller can draw a guide that matches how
+   *  hard it is holding. Null whenever `snappedTo` is. */
+  strength: SnapStrength | null
+  /** Thread this into the next call of the same gesture. */
+  state: SnapState
+}
+
+/**
+ * Magnetize `candidateT` to the nearest snap point, with hysteresis.
+ *
+ * Tie-break is **nearest wins**, ties going to the earlier entry — deliberately
+ * unlike the Scrubber, which took the first point in array order that happened
+ * to be within range and so gave different answers for different orderings of
+ * the same boundary set. Nearest is what the flat implementations already did
+ * and what a user means by "it snapped to the cut".
+ *
+ * Snapping is off entirely when the viewport has no scale yet (before first
+ * layout), since pixel radii are meaningless without one.
+ */
+export function applySnap(
+  candidateT: number,
+  snapPoints: readonly SnapPoint[],
+  viewport: Viewport,
+  state: SnapState = FREE,
+  config: SnapConfig = DEFAULT_SNAP_CONFIG,
+): SnapResult {
+  const pxPerSecond = viewport.pxPerSecond
+  if (!(pxPerSecond > 0) || snapPoints.length === 0) {
+    return { time: candidateT, snappedTo: null, strength: null, state: FREE }
+  }
+
+  const attract = { strong: config.attractPx / pxPerSecond, weak: config.weakAttractPx / pxPerSecond }
+  const release = { strong: config.releasePx / pxPerSecond, weak: config.weakReleasePx / pxPerSecond }
+
+  // Held: stay put until the cursor escapes the (wider) release radius of the
+  // tier that caught it. A weak capture is let go of on weak terms.
+  if (state.snappedTo !== null && state.strength !== null) {
+    if (Math.abs(candidateT - state.snappedTo) < release[state.strength]) {
+      return { time: state.snappedTo, snappedTo: state.snappedTo, strength: state.strength, state }
+    }
+    // Broken free. Fall through to a fresh scan — the point just released is
+    // by definition beyond its own `release` > `attract`, so it cannot
+    // re-capture at the same tier.
+  }
+
+  // Nearest wins WITHIN a tier; a strong point beats a weak one outright, even
+  // a nearer weak one. That precedence is the whole feature: cross-track
+  // boundaries must never steal a gesture away from the cut it is aiming at on
+  // its own track, and with plain nearest-wins they routinely would.
+  let bestStrong: number | null = null
+  let bestStrongDist = attract.strong
+  let bestWeak: number | null = null
+  let bestWeakDist = attract.weak
+
+  for (const point of snapPoints) {
+    const dist = Math.abs(candidateT - point.time)
+    if (point.strength === 'strong') {
+      if (dist < bestStrongDist) { bestStrongDist = dist; bestStrong = point.time }
+    } else if (dist < bestWeakDist) {
+      bestWeakDist = dist
+      bestWeak = point.time
+    }
+  }
+
+  const best = bestStrong ?? bestWeak
+  if (best === null) return { time: candidateT, snappedTo: null, strength: null, state: FREE }
+  const strength: SnapStrength = bestStrong !== null ? 'strong' : 'weak'
+  return { time: best, snappedTo: best, strength, state: { snappedTo: best, strength } }
+}
+
+/**
+ * Snap points for dragging a whole item of length `duration`, expressed as
+ * candidate START positions: a point can catch the item's leading edge (start
+ * lands on it) or its trailing edge (start lands one duration earlier). Feeding
+ * these to `applySnap` with the raw start makes both edges magnetic through the
+ * same code path — and, because the state is a start position rather than an
+ * "edge + point" pair, hysteresis works across the pair for free.
+ */
+export function snapPointsForSpan(points: readonly SnapPoint[], duration: number): SnapPoint[] {
+  const out: SnapPoint[] = []
+  for (const p of points) out.push(p)
+  for (const p of points) out.push({ time: p.time - duration, strength: p.strength })
+  return out
+}
+
+const EPSILON = 1e-6
+
+/**
+ * Drop points that coincide with values the gesture is itself moving, and
+ * de-duplicate the rest.
+ *
+ * Every item's own start and end are in the boundary set, so without this an
+ * edge trim (or a clip drag) would be captured by the position it started from
+ * and refuse to move until the cursor cleared the 28px release radius. The DOM
+ * paths lived with it because an 8px flat magnet is easy to pull out of; at
+ * these radii it reads as a stuck gesture.
+ */
+export function snapPointsExcluding(points: readonly SnapPoint[], exclude: readonly number[]): SnapPoint[] {
+  const out: SnapPoint[] = []
+  for (const p of points) {
+    if (!Number.isFinite(p.time)) continue
+    if (exclude.some(e => Math.abs(p.time - e) <= EPSILON)) continue
+    const dupeAt = out.findIndex(kept => Math.abs(kept.time - p.time) <= EPSILON)
+    if (dupeAt >= 0) {
+      // One time, two tiers: a cut on this track that happens to line up with
+      // one two rows up is a STRONG point, not a weak one. Upgrading on
+      // collision keeps the strong tier complete no matter what order the
+      // rows were walked in.
+      if (p.strength === 'strong') out[dupeAt] = p
+      continue
+    }
+    out.push(p)
+  }
+  return out
+}

package/src/video/timeline/canvas/viewport.ts

@@ -0,0 +1,457 @@
+/**
+ * Canvas timeline viewport (SP5 T4) — the scroll/zoom model the canvas surface
+ * draws through, plus the DPR-crisp rendering plumbing.
+ *
+ * ── Why a new model ──────────────────────────────────────────────────────
+ * The DOM timeline zooms by widening a container to `zoom × 100%` and letting
+ * the browser scroll it, so its zoom is "multiples of container width" against
+ * a content-dependent `totalDuration`. That model can't zoom out past fit, and
+ * its px/second silently changes whenever a clip moves (totalDuration is
+ * derived from content). The canvas uses the model every NLE uses instead:
+ *
+ *   pxPerSecond   how many CSS pixels one second occupies
+ *   scrollSeconds the time at the left edge of the surface
+ *
+ * Time↔pixel conversion is then a pure affine map, independent of content.
+ * The zoom badge reports a fit-relative multiple (`zoomMultiple`) so the
+ * numbers users knew from the old DOM path's zoom stay recognizable.
+ *
+ * Everything above `createViewportStore` is pure math with no DOM access, so
+ * it is unit-testable and reusable by hit-testing (T5) and the content layers
+ * (T6/T7).
+ */
+
+import { useRef, useSyncExternalStore } from 'react'
+
+export interface Viewport {
+  /** CSS pixels per second of timeline. */
+  pxPerSecond: number
+  /** Time at x=0 of the drawing surface, in seconds. */
+  scrollSeconds: number
+  /** Width of the drawing surface in CSS pixels (0 before first layout). */
+  widthPx: number
+}
+
+/** Absolute floor on zoom-out. One pixel per second is already an hour of
+ *  timeline across a 3600px surface — further out is not a useful view. */
+export const MIN_PX_PER_SECOND = 1
+
+/** Absolute ceiling on zoom-in: ~66px per frame at 30fps, which is as far as
+ *  any frame-accurate trim needs. */
+export const MAX_PX_PER_SECOND = 2000
+
+/** How far below "fit the whole project" zoom-out is allowed to go, as a
+ *  fraction of the fit scale. The DOM model bottomed out AT fit; pulling back
+ *  from the content is a deliberate improvement (it gives drop room past the
+ *  last clip) — but only so far. At `0.5` the content bottoms out filling HALF
+ *  the surface width (one content-length of drop room past the end), instead of
+ *  shrinking to a sliver: CapCut caps its max zoom-out the same way, and a
+ *  quarter-width timeline (the old `0.25`) is more empty canvas than anyone
+ *  needs to reach the end. `MIN_PX_PER_SECOND` still floors this for a project
+ *  long enough that half-width would fall below it. */
+export const MIN_FIT_MULTIPLE = 0.5
+
+/** Extra scroll past the end of the content, as a fraction of one screenful,
+ *  so the rightmost item can always be dragged/trimmed further out. */
+export const OVERSCROLL_FRACTION = 0.25
+
+/** Multiplicative step for the chrome's +/− zoom buttons. */
+export const ZOOM_BUTTON_FACTOR = 1.5
+
+// ── Pure math ────────────────────────────────────────────────────────────
+
+/** px/second at which `totalDuration` exactly fills `widthPx`. 0 when either
+ *  is degenerate (no surface yet, or an empty project). */
+export function fitPxPerSecond(widthPx: number, totalDuration: number): number {
+  if (widthPx <= 0 || totalDuration <= 0) return 0
+  return widthPx / totalDuration
+}
+
+export function clampPxPerSecond(pxPerSecond: number, widthPx: number, totalDuration: number): number {
+  const fit = fitPxPerSecond(widthPx, totalDuration)
+  const lower = Math.min(
+    fit > 0 ? Math.max(MIN_PX_PER_SECOND, fit * MIN_FIT_MULTIPLE) : MIN_PX_PER_SECOND,
+    MAX_PX_PER_SECOND,
+  )
+  if (!Number.isFinite(pxPerSecond)) return lower
+  return Math.min(MAX_PX_PER_SECOND, Math.max(lower, pxPerSecond))
+}
+
+/** Seconds visible across the surface at the current scale. */
+export function visibleDuration(vp: Viewport): number {
+  return vp.pxPerSecond > 0 ? vp.widthPx / vp.pxPerSecond : 0
+}
+
+export function visibleRange(vp: Viewport): { start: number; end: number } {
+  return { start: vp.scrollSeconds, end: vp.scrollSeconds + visibleDuration(vp) }
+}
+
+/** Surface x (CSS px) for a timeline time. */
+export function timeToX(t: number, vp: Viewport): number {
+  return (t - vp.scrollSeconds) * vp.pxPerSecond
+}
+
+/** Timeline time for a surface x (CSS px, relative to the surface's left). */
+export function xToTime(x: number, vp: Viewport): number {
+  return vp.pxPerSecond > 0 ? vp.scrollSeconds + x / vp.pxPerSecond : vp.scrollSeconds
+}
+
+/** Rightmost legal `scrollSeconds`: the end of the content, less a screenful,
+ *  plus overscroll headroom. Zero whenever the content already fits. */
+export function maxScrollSeconds(vp: Viewport, totalDuration: number): number {
+  const visible = visibleDuration(vp)
+  return Math.max(0, totalDuration - visible + visible * OVERSCROLL_FRACTION)
+}
+
+/** Clamp to [0, maxScroll]. Scrolling left of t=0 is never allowed — blank
+ *  space before the start of the timeline reads as a bug, not headroom. */
+export function clampScrollSeconds(scrollSeconds: number, vp: Viewport, totalDuration: number): number {
+  if (!Number.isFinite(scrollSeconds)) return 0
+  return Math.max(0, Math.min(maxScrollSeconds(vp, totalDuration), scrollSeconds))
+}
+
+/** How close to the surface's left/right edge a drag's pointer must sit before
+ *  edge auto-scroll starts panning the view to follow it (CSS px). This is
+ *  only the TRIGGER band — how far the pointer must intrude before panning
+ *  starts at all. It says nothing about how fast that panning ramps up; see
+ *  `EDGE_SCROLL_RAMP_PX` for that. */
+export const EDGE_SCROLL_ZONE_PX = 40
+
+/** Panning speed once the ramp is fully spent (`EDGE_SCROLL_RAMP_PX` past the
+ *  zone's outer boundary), in content CSS px/second — roughly a screen-width
+ *  per second, fast enough to cross a long timeline without feeling like a
+ *  jump. Reachable at all only because the ramp now keeps climbing past the
+ *  surface edge itself (see `edgeScrollDelta`); a pointer merely parked at the
+ *  zone's threshold stays well under this. */
+export const EDGE_SCROLL_MAX_PX_PER_SEC = 1400
+
+/** Total depth, from the edge zone's outer boundary outward, over which
+ *  `edgeScrollDelta`'s speed ramps from 0 up to `EDGE_SCROLL_MAX_PX_PER_SEC`.
+ *  Bigger than `EDGE_SCROLL_ZONE_PX` on purpose: a drag is driven by
+ *  document-level listeners, so shoving the cursor to the surface edge is
+ *  effortless and instantaneous, and a ramp that maxed out AT the edge would
+ *  make every such shove feel identical — one flat speed, no matter how hard
+ *  the user pushed. Letting the ramp keep climbing for the 30px beyond the
+ *  zone (`70 - 40`) means the felt speed keeps responding to how far past the
+ *  edge the pointer travels, which is the only room document-level tracking
+ *  gives a user to express "faster." */
+export const EDGE_SCROLL_RAMP_PX = 70
+
+/**
+ * How many seconds to pan the viewport for one animation frame of an active
+ * drag whose pointer sits at `pointerX` (CSS px from the surface's left edge —
+ * the same `Point.x` a gesture already works in). Zero outside the
+ * `edgeZonePx` band at either edge; from the zone's outer boundary, speed
+ * ramps up over `rampPx` of further depth via `(depth / rampPx) ^ 1.5` — an
+ * ease-in curve, not linear — reaching `maxPxPerSec` once the pointer has
+ * travelled the full ramp distance past that boundary, and holding there for
+ * anything beyond (a drag driven by document-level listeners, not native
+ * pointer capture, can report an x arbitrarily outside [0, canvasWidth] once
+ * the real cursor leaves the surface, so depth must clamp rather than keep
+ * growing forever). The exponent keeps the curve gentle right at the trigger
+ * boundary — where a barely-crossed pointer would otherwise feel like it
+ * suddenly grabbed the view — while still reaching a punchy speed by the time
+ * the user has shoved the cursor visibly past the edge.
+ *
+ * Negative = pan left/earlier, positive = pan right/later, 0 = the pointer is
+ * not near either edge. Framerate-independent: the ramped speed is scaled by
+ * `dtSeconds` and converted from content px/second to timeline seconds via
+ * `pxPerSecond`, so callers can feed it a real frame delta and get a
+ * consistent pan regardless of the display's refresh rate.
+ */
+export function edgeScrollDelta(
+  pointerX: number,
+  canvasWidth: number,
+  pxPerSecond: number,
+  dtSeconds: number,
+  edgeZonePx: number,
+  maxPxPerSec: number,
+  rampPx: number,
+): number {
+  if (canvasWidth <= 0 || pxPerSecond <= 0 || edgeZonePx <= 0 || dtSeconds <= 0 || rampPx <= 0) return 0
+
+  const leftBoundary = edgeZonePx
+  const rightBoundary = canvasWidth - edgeZonePx
+
+  let depthPx: number
+  let direction: -1 | 1
+  if (pointerX < leftBoundary) {
+    depthPx = leftBoundary - pointerX
+    direction = -1
+  } else if (pointerX > rightBoundary) {
+    depthPx = pointerX - rightBoundary
+    direction = 1
+  } else {
+    return 0
+  }
+
+  const ratio = Math.min(1, depthPx / rampPx)
+  const contentPxPerSecond = maxPxPerSec * Math.pow(ratio, 1.5)
+  return (direction * contentPxPerSecond * dtSeconds) / pxPerSecond
+}
+
+/**
+ * Zoom by `factor`, keeping the time under `pivotX` pinned to `pivotX`. Same
+ * semantics as the DOM path's `useTimelineZoom.zoomTo` (which pins a pivot
+ * percentage through a pending scrollLeft write) expressed directly in the
+ * px/second model: solve `pivotTime = scroll' + pivotX / pps'` for `scroll'`.
+ *
+ * The pivot only drifts when the new scroll would leave the legal range —
+ * i.e. at the ends of the timeline, exactly where the DOM path drifts too.
+ */
+export function zoomAtPivot(vp: Viewport, factor: number, pivotX: number, totalDuration: number): Viewport {
+  const pivotTime = xToTime(pivotX, vp)
+  const pxPerSecond = clampPxPerSecond(vp.pxPerSecond * factor, vp.widthPx, totalDuration)
+  const zoomed: Viewport = { ...vp, pxPerSecond }
+  return { ...zoomed, scrollSeconds: clampScrollSeconds(pivotTime - pivotX / pxPerSecond, zoomed, totalDuration) }
+}
+
+/** Horizontal pan by a pixel delta (positive = content moves left / later). */
+export function panByPixels(vp: Viewport, deltaPx: number, totalDuration: number): Viewport {
+  if (vp.pxPerSecond <= 0) return vp
+  return { ...vp, scrollSeconds: clampScrollSeconds(vp.scrollSeconds + deltaPx / vp.pxPerSecond, vp, totalDuration) }
+}
+
+/** Scale so the whole project fills the surface, scrolled to the start. */
+export function fitViewport(vp: Viewport, totalDuration: number): Viewport {
+  return {
+    ...vp,
+    pxPerSecond: clampPxPerSecond(fitPxPerSecond(vp.widthPx, totalDuration), vp.widthPx, totalDuration),
+    scrollSeconds: 0,
+  }
+}
+
+/** The zoom number the chrome shows: 1× is fit, 2× is twice as close in. Keeps
+ *  continuity with the DOM path's badge, whose 1× also meant fit. */
+export function zoomMultiple(vp: Viewport, totalDuration: number): number {
+  const fit = fitPxPerSecond(vp.widthPx, totalDuration)
+  return fit > 0 ? vp.pxPerSecond / fit : 1
+}
+
+export function formatZoomMultiple(multiple: number): string {
+  if (!Number.isFinite(multiple) || multiple <= 0) return '1'
+  if (multiple >= 10) return String(Math.round(multiple))
+  return multiple.toFixed(1)
+}
+
+/** Re-derive the viewport for a new surface width. Scale is preserved (a wider
+ *  window shows more time, it does not rescale the content) except on the very
+ *  first layout, where there is no scale yet and we start fitted. */
+export function withSurfaceWidth(vp: Viewport, widthPx: number, totalDuration: number): Viewport {
+  if (widthPx <= 0) return vp.widthPx === widthPx ? vp : { ...vp, widthPx }
+  const sized: Viewport = { ...vp, widthPx }
+  if (vp.pxPerSecond <= 0) return fitViewport(sized, totalDuration)
+  const rescaled: Viewport = { ...sized, pxPerSecond: clampPxPerSecond(sized.pxPerSecond, widthPx, totalDuration) }
+  return { ...rescaled, scrollSeconds: clampScrollSeconds(rescaled.scrollSeconds, rescaled, totalDuration) }
+}
+
+/** Re-clamp after the project's duration changed (clips added/moved/deleted). */
+export function reclampForDuration(vp: Viewport, totalDuration: number): Viewport {
+  if (vp.widthPx <= 0) return vp
+  if (vp.pxPerSecond <= 0) return fitViewport(vp, totalDuration)
+  const rescaled: Viewport = { ...vp, pxPerSecond: clampPxPerSecond(vp.pxPerSecond, vp.widthPx, totalDuration) }
+  return { ...rescaled, scrollSeconds: clampScrollSeconds(rescaled.scrollSeconds, rescaled, totalDuration) }
+}
+
+export function viewportsEqual(a: Viewport, b: Viewport): boolean {
+  return a.pxPerSecond === b.pxPerSecond && a.scrollSeconds === b.scrollSeconds && a.widthPx === b.widthPx
+}
+
+// ── Wheel semantics (ported from useTimelineZoom) ────────────────────────
+
+export type WheelIntent =
+  | { kind: 'zoom'; factor: number; pivotX: number }
+  | { kind: 'pan'; deltaPx: number }
+  | { kind: 'none' }
+
+export interface WheelLike {
+  deltaX: number
+  deltaY: number
+  ctrlKey: boolean
+  metaKey: boolean
+  altKey: boolean
+}
+
+/**
+ * What a wheel event means to the canvas timeline. Ported from the DOM path:
+ *
+ *   ⌘/Ctrl + wheel  zoom, multiplicatively, pivoted at the cursor. The
+ *                   `exp(-deltaY * 0.002)` step is the DOM path's verbatim, so
+ *                   a wheel tick (deltaY ≈ 100) is the same ≈18% either side.
+ *   Alt + wheel     horizontal pan by deltaY pixels.
+ *   plain wheel     NOT intercepted — the page/container must keep scrolling
+ *                   vertically. The one exception is a horizontally-dominant
+ *                   plain wheel (trackpad two-finger swipe), which the DOM
+ *                   path's `overflow-x: auto` container consumed for free and
+ *                   the canvas must consume explicitly or lose the gesture.
+ */
+export function wheelIntent(e: WheelLike, pivotX: number): WheelIntent {
+  if (e.ctrlKey || e.metaKey) return { kind: 'zoom', factor: Math.exp(-e.deltaY * 0.002), pivotX }
+  if (e.altKey) return { kind: 'pan', deltaPx: e.deltaY }
+  if (Math.abs(e.deltaX) > Math.abs(e.deltaY)) return { kind: 'pan', deltaPx: e.deltaX }
+  return { kind: 'none' }
+}
+
+export function applyWheelIntent(vp: Viewport, intent: WheelIntent, totalDuration: number): Viewport {
+  switch (intent.kind) {
+    case 'zoom': return zoomAtPivot(vp, intent.factor, intent.pivotX, totalDuration)
+    case 'pan':  return panByPixels(vp, intent.deltaPx, totalDuration)
+    default:     return vp
+  }
+}
+
+// ── DPR-crisp surface plumbing ───────────────────────────────────────────
+// No precedent existed in this repo for a resolution-independent 2D canvas
+// (the engine's painter draws into a fixed-size video canvas), so this is the
+// one place that knows about devicePixelRatio. Everything else works in CSS
+// pixels and never sees the backing store.
+
+export interface SurfaceMetrics {
+  cssWidth: number
+  cssHeight: number
+  dpr: number
+}
+
+/** Backing-store pixel size for a CSS box at a given DPR. Rounded, never 0 —
+ *  a zero-sized canvas throws on some `getContext` paths. */
+export function backingStoreSize(cssWidth: number, cssHeight: number, dpr: number): { width: number; height: number } {
+  const scale = dpr > 0 ? dpr : 1
+  return {
+    width: Math.max(1, Math.round(cssWidth * scale)),
+    height: Math.max(1, Math.round(cssHeight * scale)),
+  }
+}
+
+/** Size a canvas' backing store for its CSS box. Returns true when it changed
+ *  (writing `canvas.width` clears the canvas, so callers redraw on true). */
+export function syncCanvasBackingStore(canvas: HTMLCanvasElement, metrics: SurfaceMetrics): boolean {
+  const { width, height } = backingStoreSize(metrics.cssWidth, metrics.cssHeight, metrics.dpr)
+  if (canvas.width === width && canvas.height === height) return false
+  canvas.width = width
+  canvas.height = height
+  return true
+}
+
+/** Put the context in CSS-pixel space. `setTransform` rather than `scale` so
+ *  it is idempotent — a per-frame `scale(dpr, dpr)` would compound. */
+export function scaleContextToDpr(ctx: CanvasRenderingContext2D, dpr: number): void {
+  const scale = dpr > 0 ? dpr : 1
+  ctx.setTransform(scale, 0, 0, scale, 0, 0)
+}
+
+export function currentDpr(): number {
+  if (typeof window === 'undefined') return 1
+  return window.devicePixelRatio || 1
+}
+
+/**
+ * Watch an element's CSS size AND the window's device-pixel ratio, calling
+ * back with both. The DPR half matters when the window is dragged between a
+ * Retina and a non-Retina display: no resize fires, but every backing store is
+ * now the wrong size and text renders blurry (or over-sharp). `matchMedia` on
+ * a `resolution` query is the only event-driven DPR signal browsers give, and
+ * it must be re-armed after each change because the query pins the old value.
+ *
+ * Returns a disposer. Degrades to a window-resize fallback where
+ * ResizeObserver is unavailable (jsdom), and to nothing where matchMedia is.
+ */
+export function observeSurface(el: HTMLElement, onChange: (metrics: SurfaceMetrics) => void): () => void {
+  const emit = () => {
+    const rect = el.getBoundingClientRect()
+    onChange({ cssWidth: rect.width, cssHeight: rect.height, dpr: currentDpr() })
+  }
+
+  const disposers: Array<() => void> = []
+
+  if (typeof ResizeObserver !== 'undefined') {
+    const ro = new ResizeObserver(() => emit())
+    ro.observe(el)
+    disposers.push(() => ro.disconnect())
+  } else if (typeof window !== 'undefined') {
+    const onResize = () => emit()
+    window.addEventListener('resize', onResize)
+    disposers.push(() => window.removeEventListener('resize', onResize))
+  }
+
+  disposers.push(watchDpr(emit))
+  emit()
+
+  return () => { for (const d of disposers) d() }
+}
+
+/** Fire `onChange` whenever devicePixelRatio changes, re-arming the query. */
+export function watchDpr(onChange: () => void): () => void {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return () => {}
+  let disposed = false
+  let detach: () => void = () => {}
+
+  const arm = () => {
+    if (disposed) return
+    const mql = window.matchMedia(`(resolution: ${currentDpr()}dppx)`)
+    const handler = () => {
+      detach()
+      arm()
+      onChange()
+    }
+    // Safari < 14 only has the deprecated addListener/removeListener pair.
+    if (typeof mql.addEventListener === 'function') {
+      mql.addEventListener('change', handler)
+      detach = () => mql.removeEventListener('change', handler)
+    } else if (typeof mql.addListener === 'function') {
+      mql.addListener(handler)
+      detach = () => mql.removeListener(handler)
+    } else {
+      detach = () => {}
+    }
+  }
+
+  arm()
+  return () => { disposed = true; detach() }
+}
+
+// ── Store ────────────────────────────────────────────────────────────────
+// The viewport is an external store, not React state, for the same reason the
+// playhead is (see playback-clock.ts): a wheel-zoom gesture fires dozens of
+// updates a second, and re-rendering Timeline — which owns the caption row's
+// hundreds of DOM nodes — on each one is exactly the cost the canvas exists to
+// avoid. The canvas redraws imperatively from `get()`; only the zoom badge
+// subscribes for rendering.
+
+export interface ViewportStore {
+  get(): Viewport
+  set(next: Viewport | ((prev: Viewport) => Viewport)): void
+  subscribe(cb: () => void): () => void
+}
+
+export const INITIAL_VIEWPORT: Viewport = { pxPerSecond: 0, scrollSeconds: 0, widthPx: 0 }
+
+export function createViewportStore(initial: Viewport = INITIAL_VIEWPORT): ViewportStore {
+  let value = initial
+  const subs = new Set<() => void>()
+  return {
+    get: () => value,
+    set(next) {
+      const resolved = typeof next === 'function' ? next(value) : next
+      if (viewportsEqual(resolved, value)) return
+      value = resolved
+      subs.forEach(cb => cb())
+    },
+    subscribe(cb) {
+      subs.add(cb)
+      return () => { subs.delete(cb) }
+    },
+  }
+}
+
+/** A store whose identity is stable for the lifetime of the component. */
+export function useViewportStore(): ViewportStore {
+  const ref = useRef<ViewportStore | null>(null)
+  if (ref.current === null) ref.current = createViewportStore()
+  return ref.current
+}
+
+/** Subscribe a component to the viewport. Only display chrome (the zoom badge)
+ *  should use this — the canvas itself reads `store.get()` inside its draw. */
+export function useViewportValue(store: ViewportStore): Viewport {
+  return useSyncExternalStore(store.subscribe, store.get, store.get)
+}