@bycrux/editor 0.11.2 → 1.0.1

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

@@ -0,0 +1,257 @@
+/// <reference types="vitest/globals" />
+/**
+ * SP5 T5 — the one snapping model. At 100px/second the default radii convert to
+ * round numbers, which is what makes the hysteresis assertions readable:
+ *
+ *   attract 20px → 0.20s     release 44px → 0.44s
+ *
+ * The gap between them is the feature, not an implementation detail: a magnet
+ * you can leave as easily as you entered it reads as the timeline refusing to
+ * go where you put it. Several assertions below exist purely to pin that gap,
+ * so widening or narrowing it is always a deliberate edit.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  DEFAULT_SNAP_CONFIG,
+  applySnap,
+  createSnapState,
+  snapPointsExcluding,
+  snapPointsForSpan,
+  type SnapPoint,
+} from '../snap'
+import type { Viewport } from '../viewport'
+
+const VIEWPORT: Viewport = { pxPerSecond: 100, scrollSeconds: 0, widthPx: 1000 }
+
+/** Same-track boundaries — the full-strength magnet. */
+const strong = (...times: number[]): SnapPoint[] => times.map(time => ({ time, strength: 'strong' }))
+/** Boundaries on some other row: 6px in, 10px out. */
+const weak = (...times: number[]): SnapPoint[] => times.map(time => ({ time, strength: 'weak' }))
+
+const POINTS = strong(5)
+
+describe('applySnap — attraction', () => {
+  it('captures a candidate inside the attract radius', () => {
+    const result = applySnap(5.1, POINTS, VIEWPORT, createSnapState())
+    expect(result.time).toBe(5)
+    expect(result.snappedTo).toBe(5)
+  })
+
+  it('leaves a candidate outside the attract radius alone', () => {
+    const result = applySnap(5.25, POINTS, VIEWPORT, createSnapState())
+    expect(result.time).toBe(5.25)
+    expect(result.snappedTo).toBeNull()
+    expect(result.state.snappedTo).toBeNull()
+  })
+
+  it('brackets the attract radius', () => {
+    expect(applySnap(5.201, POINTS, VIEWPORT, createSnapState()).snappedTo).toBeNull()
+    expect(applySnap(5.199, POINTS, VIEWPORT, createSnapState()).snappedTo).toBe(5)
+  })
+
+  it('attracts from either side', () => {
+    expect(applySnap(4.9, POINTS, VIEWPORT, createSnapState()).time).toBe(5)
+  })
+})
+
+describe('applySnap — hysteresis', () => {
+  it('holds a captured point until the release radius is cleared', () => {
+    let state = createSnapState()
+
+    // Approach and stick.
+    let result = applySnap(5.15, POINTS, VIEWPORT, state)
+    expect(result.time).toBe(5)
+    state = result.state
+
+    // Pull past the ATTRACT radius — still held, because release is wider.
+    result = applySnap(5.25, POINTS, VIEWPORT, state)
+    expect(result.time).toBe(5)
+    expect(result.snappedTo).toBe(5)
+    state = result.state
+
+    // Just short of release — still held.
+    result = applySnap(5.439, POINTS, VIEWPORT, state)
+    expect(result.time).toBe(5)
+    state = result.state
+
+    // Past release — free, and reporting the true candidate.
+    result = applySnap(5.44, POINTS, VIEWPORT, state)
+    expect(result.time).toBe(5.44)
+    expect(result.snappedTo).toBeNull()
+    state = result.state
+
+    // Coming back inside attract re-captures.
+    expect(applySnap(5.1, POINTS, VIEWPORT, state).time).toBe(5)
+  })
+
+  it('cannot immediately re-capture the point it just released', () => {
+    const held = applySnap(5.05, POINTS, VIEWPORT, createSnapState()).state
+    const released = applySnap(5.5, POINTS, VIEWPORT, held)
+    expect(released.time).toBe(5.5)
+    expect(released.snappedTo).toBeNull()
+  })
+
+  it('hands off to a different point when the escape lands near one', () => {
+    const points = strong(5, 5.6)
+    const held = applySnap(5.02, points, VIEWPORT, createSnapState()).state
+    const moved = applySnap(5.5, points, VIEWPORT, held)
+    // 0.50 from the held point clears release (0.44); 0.10 from the neighbour
+    // is well inside attract.
+    expect(moved.time).toBe(5.6)
+    expect(moved.snappedTo).toBe(5.6)
+  })
+})
+
+describe('applySnap — strength tiers', () => {
+  it('reports which tier caught the gesture', () => {
+    expect(applySnap(5.1, strong(5), VIEWPORT, createSnapState()).strength).toBe('strong')
+    expect(applySnap(5.03, weak(5), VIEWPORT, createSnapState()).strength).toBe('weak')
+    expect(applySnap(9, strong(5), VIEWPORT, createSnapState()).strength).toBeNull()
+  })
+
+  it('ignores a cross-track boundary that a same-track one would have caught', () => {
+    // 0.1s is 10px: inside the 20px strong radius, well outside the 6px weak
+    // one. This is the whole point of the split — an overlay row full of cuts
+    // must not grab a clip being dragged on the row below.
+    expect(applySnap(5.1, strong(5), VIEWPORT, createSnapState()).snappedTo).toBe(5)
+    expect(applySnap(5.1, weak(5), VIEWPORT, createSnapState()).snappedTo).toBeNull()
+  })
+
+  it('lets a strong point beat a NEARER weak one', () => {
+    // Nearest-wins holds within a tier, never across it: the same-track cut at
+    // 0.15s out takes it, not the overlay edge 0.02s away.
+    const points = [...weak(5.02), ...strong(5.15)]
+    const result = applySnap(5, points, VIEWPORT, createSnapState())
+    expect(result.snappedTo).toBe(5.15)
+    expect(result.strength).toBe('strong')
+  })
+
+  it('falls back to a weak point when no strong one is in range', () => {
+    const points = [...weak(5.02), ...strong(9)]
+    expect(applySnap(5, points, VIEWPORT, createSnapState()).snappedTo).toBe(5.02)
+  })
+
+  it('lets a weak capture go on weak terms — 10px, not 44', () => {
+    // A subtle magnet has to be subtle to LEAVE as well as to enter, or it is
+    // just a strong magnet that was hard to trigger.
+    const held = applySnap(5.02, weak(5), VIEWPORT, createSnapState()).state
+    expect(applySnap(5.09, weak(5), VIEWPORT, held).snappedTo).toBe(5)
+    expect(applySnap(5.11, weak(5), VIEWPORT, held).snappedTo).toBeNull()
+
+    // The same distance would not have shaken off a strong one.
+    const heldStrong = applySnap(5.02, strong(5), VIEWPORT, createSnapState()).state
+    expect(applySnap(5.11, strong(5), VIEWPORT, heldStrong).snappedTo).toBe(5)
+  })
+})
+
+describe('applySnap — multiple candidates', () => {
+  it('takes the nearest point, not the first in range', () => {
+    expect(applySnap(5, strong(4.9, 5.05), VIEWPORT, createSnapState()).time).toBe(5.05)
+    expect(applySnap(5, strong(5.05, 4.9), VIEWPORT, createSnapState()).time).toBe(5.05)
+  })
+
+  it('breaks an exact tie in favour of the earlier entry', () => {
+    expect(applySnap(5, strong(4.9, 5.1), VIEWPORT, createSnapState()).time).toBe(4.9)
+    expect(applySnap(5, strong(5.1, 4.9), VIEWPORT, createSnapState()).time).toBe(5.1)
+  })
+
+  it('ignores points outside the radius entirely', () => {
+    expect(applySnap(5, strong(1, 9), VIEWPORT, createSnapState()).snappedTo).toBeNull()
+  })
+})
+
+describe('applySnap — configuration and degenerate viewports', () => {
+  it('ships radii whose release is more than double its attract', () => {
+    expect(DEFAULT_SNAP_CONFIG).toEqual({ attractPx: 20, releasePx: 44, weakAttractPx: 6, weakReleasePx: 10 })
+    // The detent. Pinned as a ratio as well as absolutes so a future tweak to
+    // either number has to keep the asymmetry that makes the magnet hold.
+    expect(DEFAULT_SNAP_CONFIG.releasePx).toBeGreaterThan(DEFAULT_SNAP_CONFIG.attractPx * 2)
+  })
+
+  it('holds well past the distance that captured it', () => {
+    // The user-facing promise: sliding a clip a little way past a cut does not
+    // shake it off. 0.3s is 30px — half again the attract radius — and the
+    // gesture is still pinned to the boundary.
+    const held = applySnap(5.05, POINTS, VIEWPORT, createSnapState()).state
+    expect(applySnap(5.3, POINTS, VIEWPORT, held).snappedTo).toBe(5)
+  })
+
+  it('honours a config override', () => {
+    const tight = { attractPx: 4, releasePx: 6, weakAttractPx: 2, weakReleasePx: 3 }
+    // 0.03s is 3px — inside a 4px magnet, and well inside the default 20px one.
+    expect(applySnap(5.03, POINTS, VIEWPORT, createSnapState(), tight).time).toBe(5)
+    expect(applySnap(5.1, POINTS, VIEWPORT, createSnapState(), tight).snappedTo).toBeNull()
+    expect(applySnap(5.1, POINTS, VIEWPORT, createSnapState()).snappedTo).toBe(5)
+    // …and the tighter release lets go sooner.
+    const held = applySnap(5.03, POINTS, VIEWPORT, createSnapState(), tight).state
+    expect(applySnap(5.07, POINTS, VIEWPORT, held, tight).snappedTo).toBeNull()
+  })
+
+  it('scales the radii with zoom, so the magnet is the same size on screen', () => {
+    const zoomedIn: Viewport = { ...VIEWPORT, pxPerSecond: 1000 }
+    // 0.1s is 100px out at this scale — far outside the magnet.
+    expect(applySnap(5.1, POINTS, zoomedIn, createSnapState()).snappedTo).toBeNull()
+    // 0.01s is 10px — inside it.
+    expect(applySnap(5.01, POINTS, zoomedIn, createSnapState()).time).toBe(5)
+  })
+
+  it('does not snap before the surface has a scale', () => {
+    const unscaled: Viewport = { pxPerSecond: 0, scrollSeconds: 0, widthPx: 0 }
+    const result = applySnap(5.0001, POINTS, unscaled, createSnapState())
+    expect(result.time).toBe(5.0001)
+    expect(result.snappedTo).toBeNull()
+  })
+
+  it('does not snap when there are no points', () => {
+    expect(applySnap(5, [], VIEWPORT, createSnapState()).time).toBe(5)
+  })
+
+  it('defaults to a free state when none is threaded', () => {
+    expect(applySnap(5.1, POINTS, VIEWPORT).time).toBe(5)
+    expect(createSnapState().snappedTo).toBeNull()
+  })
+})
+
+describe('snapPointsForSpan', () => {
+  it('offers each point to both edges of the span', () => {
+    expect(snapPointsForSpan(strong(2, 8), 3)).toEqual(strong(2, 8, -1, 5))
+  })
+
+  it('carries each point\'s strength onto its trailing-edge twin', () => {
+    // Otherwise a cross-track boundary would pull weakly on a clip's head and
+    // at full strength on its tail, which is indefensible either way round.
+    expect(snapPointsForSpan(weak(8), 3)).toEqual(weak(8, 5))
+  })
+
+  it('lets a moving item catch a boundary by its trailing edge', () => {
+    // A 3s item whose end should land on t=8 must start at t=5.
+    const points = snapPointsForSpan(strong(8), 3)
+    expect(applySnap(5.1, points, VIEWPORT, createSnapState()).time).toBe(5)
+  })
+})
+
+describe('snapPointsExcluding', () => {
+  it('drops the values the gesture is itself moving', () => {
+    expect(snapPointsExcluding(strong(0, 2, 5, 10), [2, 5])).toEqual(strong(0, 10))
+  })
+
+  it('de-duplicates and drops non-finite entries', () => {
+    expect(snapPointsExcluding(strong(3, 3, Infinity, NaN, 7), [])).toEqual(strong(3, 7))
+  })
+
+  it('upgrades a duplicate to strong, whichever order the rows arrived in', () => {
+    // A cut on this track that happens to line up with one two rows up is a
+    // same-track boundary. Losing that to a weak twin would silently punch a
+    // hole in the strong tier.
+    expect(snapPointsExcluding([...weak(4), ...strong(4)], [])).toEqual(strong(4))
+    expect(snapPointsExcluding([...strong(4), ...weak(4)], [])).toEqual(strong(4))
+  })
+
+  it('matches within a float epsilon, so recomputed times still cancel', () => {
+    expect(snapPointsExcluding(strong(0.1 + 0.2), [0.3])).toEqual([])
+  })
+
+  it('keeps everything when nothing is excluded', () => {
+    expect(snapPointsExcluding(strong(1, 2), [])).toEqual(strong(1, 2))
+  })
+})

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

@@ -0,0 +1,399 @@
+/**
+ * SP5 T4 — the canvas timeline's viewport math. Everything asserted here is
+ * pure: the surface plumbing (ResizeObserver, matchMedia) is exercised only
+ * through its size arithmetic, which is the part that can be wrong silently.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import {
+  EDGE_SCROLL_MAX_PX_PER_SEC,
+  EDGE_SCROLL_RAMP_PX,
+  EDGE_SCROLL_ZONE_PX,
+  MAX_PX_PER_SECOND,
+  MIN_FIT_MULTIPLE,
+  MIN_PX_PER_SECOND,
+  OVERSCROLL_FRACTION,
+  applyWheelIntent,
+  backingStoreSize,
+  clampPxPerSecond,
+  clampScrollSeconds,
+  createViewportStore,
+  edgeScrollDelta,
+  fitPxPerSecond,
+  fitViewport,
+  formatZoomMultiple,
+  maxScrollSeconds,
+  panByPixels,
+  reclampForDuration,
+  scaleContextToDpr,
+  syncCanvasBackingStore,
+  timeToX,
+  visibleDuration,
+  visibleRange,
+  wheelIntent,
+  withSurfaceWidth,
+  xToTime,
+  zoomAtPivot,
+  zoomMultiple,
+  type Viewport,
+} from '../viewport'
+
+function vp(overrides: Partial<Viewport> = {}): Viewport {
+  return { pxPerSecond: 10, scrollSeconds: 0, widthPx: 1000, ...overrides }
+}
+
+describe('time ↔ pixel conversion', () => {
+  it('maps time to x through scroll and scale', () => {
+    const v = vp({ pxPerSecond: 20, scrollSeconds: 5 })
+    expect(timeToX(5, v)).toBe(0)
+    expect(timeToX(10, v)).toBe(100)
+    expect(timeToX(0, v)).toBe(-100)
+  })
+
+  it('round-trips x → time → x', () => {
+    const v = vp({ pxPerSecond: 37.5, scrollSeconds: 12.25 })
+    for (const x of [0, 1, 250, 999.5]) {
+      expect(xToTime(timeToX(xToTime(x, v), v), v)).toBeCloseTo(xToTime(x, v), 10)
+    }
+  })
+
+  it('reports the visible window from width and scale', () => {
+    const v = vp({ pxPerSecond: 50, scrollSeconds: 3, widthPx: 500 })
+    expect(visibleDuration(v)).toBe(10)
+    expect(visibleRange(v)).toEqual({ start: 3, end: 13 })
+  })
+
+  it('degrades safely before the first layout (no width, no scale)', () => {
+    const v = vp({ pxPerSecond: 0, widthPx: 0 })
+    expect(visibleDuration(v)).toBe(0)
+    expect(xToTime(123, v)).toBe(v.scrollSeconds)
+  })
+})
+
+describe('zoom clamping', () => {
+  it('fits the project across the surface', () => {
+    expect(fitPxPerSecond(1000, 50)).toBe(20)
+    expect(fitPxPerSecond(0, 50)).toBe(0)
+    expect(fitPxPerSecond(1000, 0)).toBe(0)
+  })
+
+  it('allows zooming out below fit — the DOM model could not', () => {
+    const widthPx = 1000
+    const totalDuration = 50
+    const fit = fitPxPerSecond(widthPx, totalDuration) // 20 px/s
+    expect(clampPxPerSecond(fit * 0.5, widthPx, totalDuration)).toBe(fit * 0.5)
+    // …but not indefinitely: the floor is a quarter of fit.
+    expect(clampPxPerSecond(0.001, widthPx, totalDuration)).toBe(fit * MIN_FIT_MULTIPLE)
+  })
+
+  it('never goes below the absolute floor on very long projects', () => {
+    // fit here is 0.1 px/s; a quarter of that is unusable, so the floor wins.
+    expect(clampPxPerSecond(0.0001, 1000, 10_000)).toBe(MIN_PX_PER_SECOND)
+  })
+
+  it('caps zoom-in', () => {
+    expect(clampPxPerSecond(1e6, 1000, 50)).toBe(MAX_PX_PER_SECOND)
+  })
+
+  it('reports zoom as a fit-relative multiple, for continuity with the DOM badge', () => {
+    expect(zoomMultiple(vp({ pxPerSecond: 20, widthPx: 1000 }), 50)).toBe(1)
+    expect(zoomMultiple(vp({ pxPerSecond: 40, widthPx: 1000 }), 50)).toBe(2)
+    expect(zoomMultiple(vp({ pxPerSecond: 5, widthPx: 1000 }), 50)).toBe(0.25)
+    expect(zoomMultiple(vp({ widthPx: 0 }), 50)).toBe(1)
+  })
+
+  it('formats the badge with one decimal below 10×', () => {
+    expect(formatZoomMultiple(1)).toBe('1.0')
+    expect(formatZoomMultiple(2.34)).toBe('2.3')
+    expect(formatZoomMultiple(12.4)).toBe('12')
+    expect(formatZoomMultiple(Number.NaN)).toBe('1')
+  })
+})
+
+describe('scroll clamping', () => {
+  it('stops at the content end plus a fraction of a screenful', () => {
+    const v = vp({ pxPerSecond: 10, widthPx: 1000 }) // 100s visible
+    const totalDuration = 300
+    expect(maxScrollSeconds(v, totalDuration)).toBe(300 - 100 + 100 * OVERSCROLL_FRACTION)
+    expect(clampScrollSeconds(1e6, v, totalDuration)).toBe(maxScrollSeconds(v, totalDuration))
+  })
+
+  it('pins to zero when the whole project already fits', () => {
+    const v = vp({ pxPerSecond: 10, widthPx: 1000 }) // 100s visible
+    expect(maxScrollSeconds(v, 30)).toBe(0)
+    expect(clampScrollSeconds(20, v, 30)).toBe(0)
+  })
+
+  it('never scrolls before t=0', () => {
+    expect(clampScrollSeconds(-12, vp(), 500)).toBe(0)
+  })
+
+  it('pans by pixels in the current scale', () => {
+    const v = vp({ pxPerSecond: 50, scrollSeconds: 10, widthPx: 500 })
+    expect(panByPixels(v, 250, 1000).scrollSeconds).toBe(15)
+    expect(panByPixels(v, -250, 1000).scrollSeconds).toBe(5)
+    expect(panByPixels(v, -1e6, 1000).scrollSeconds).toBe(0)
+  })
+})
+
+describe('edge auto-scroll delta', () => {
+  // A round scale (100 px/s) keeps the arithmetic legible: 1 content px is
+  // 0.01s, so the 1400 px/s cap is 14s of timeline per second of hold.
+  const pxPerSecond = 100
+  const canvasWidth = 1000
+  const zone = EDGE_SCROLL_ZONE_PX // 40
+  const maxSpeed = EDGE_SCROLL_MAX_PX_PER_SEC // 1400 px/s
+  const ramp = EDGE_SCROLL_RAMP_PX // 70 — the last 30px of it lie PAST the surface edge
+
+  /** The pan the curve owes for a given depth past the zone's outer boundary:
+   *  `(depth / ramp) ^ 1.5` of the cap, converted to timeline seconds. Spelled
+   *  out once here so the expectations below read as the curve's definition
+   *  rather than as copied magic numbers. */
+  const expectedSpeed = (depthPx: number) =>
+    (maxSpeed * Math.pow(Math.min(1, depthPx / ramp), 1.5)) / pxPerSecond
+
+  /** `edgeScrollDelta` against the fixture above; `dt` defaults to a full
+   *  second so the returned value reads directly as seconds/second. */
+  const at = (pointerX: number, dt = 1) =>
+    edgeScrollDelta(pointerX, canvasWidth, pxPerSecond, dt, zone, maxSpeed, ramp)
+
+  it('is zero for a pointer in the middle of the surface', () => {
+    expect(at(500)).toBe(0)
+  })
+
+  it('is zero exactly at the zone boundary, on either side', () => {
+    expect(at(zone)).toBe(0)
+    expect(at(canvasWidth - zone)).toBe(0)
+  })
+
+  it('pans left (negative) inside the left zone, right (positive) inside the right zone', () => {
+    expect(at(10)).toBeLessThan(0)
+    expect(at(canvasWidth - 10)).toBeGreaterThan(0)
+  })
+
+  it('ramps with how deep past the zone boundary the pointer sits, eased rather than linear', () => {
+    // Depths of 10px and 30px past the boundary, both still inside the surface.
+    const shallow = at(zone - 10)
+    const deep = at(zone - 30)
+    expect(Math.abs(shallow)).toBeCloseTo(expectedSpeed(10), 10)
+    expect(Math.abs(deep)).toBeCloseTo(expectedSpeed(30), 10)
+    // Eased, so tripling the depth MORE than triples the speed — a linear ramp
+    // would land exactly on 3x.
+    expect(Math.abs(deep)).toBeGreaterThan(Math.abs(shallow) * 3)
+
+    const shallowRight = at(canvasWidth - (zone - 10))
+    const deepRight = at(canvasWidth - (zone - 30))
+    expect(shallowRight).toBeCloseTo(-shallow, 10) // mirror image of the left side
+    expect(deepRight).toBeCloseTo(-deep, 10)
+  })
+
+  it('keeps accelerating PAST the surface edge, not only inside the zone', () => {
+    // This is the whole reason the ramp is wider than the zone. A drag reaches
+    // the surface edge in one flick, so a curve that maxed out there would make
+    // every drag feel like one flat speed no matter how hard it was pushed.
+    const atEdge = at(0)
+    const past15 = at(-15)
+    const past30 = at(-30)
+    expect(Math.abs(past15)).toBeGreaterThan(Math.abs(atEdge))
+    expect(Math.abs(past30)).toBeGreaterThan(Math.abs(past15))
+    // And the edge itself is well under the cap — a nudge, not a launch.
+    expect(Math.abs(atEdge)).toBeCloseTo(expectedSpeed(zone), 10)
+    expect(Math.abs(atEdge)).toBeLessThan(maxSpeed / pxPerSecond / 2)
+
+    // Mirrored on the right edge, same depths.
+    expect(at(canvasWidth)).toBeCloseTo(-atEdge, 10)
+    expect(at(canvasWidth + 15)).toBeCloseTo(-past15, 10)
+    expect(at(canvasWidth + 30)).toBeCloseTo(-past30, 10)
+  })
+
+  it('clamps at the max once the pointer is a full ramp past the boundary', () => {
+    // The document-level drag listeners can report an x arbitrarily far outside
+    // the surface once the real cursor leaves it — depth must clamp there, not
+    // keep growing. `zone - ramp` is exactly where the ramp is spent.
+    const rampSpent = at(zone - ramp)
+    expect(rampSpent).toBeCloseTo(-maxSpeed / pxPerSecond, 10)
+    expect(at(-500)).toBe(rampSpent)
+
+    const rightRampSpent = at(canvasWidth - zone + ramp)
+    expect(rightRampSpent).toBeCloseTo(maxSpeed / pxPerSecond, 10)
+    expect(at(canvasWidth + 500)).toBe(rightRampSpent)
+  })
+
+  it('scales with the frame delta — framerate independent', () => {
+    const oneFrame = at(10, 1 / 60)
+    const doubleFrame = at(10, 2 / 60)
+    expect(doubleFrame).toBeCloseTo(oneFrame * 2, 10)
+  })
+
+  it('is zero for a non-positive frame delta, px/second, zone, ramp, or surface width', () => {
+    expect(edgeScrollDelta(10, canvasWidth, pxPerSecond, 0, zone, maxSpeed, ramp)).toBe(0)
+    expect(edgeScrollDelta(10, canvasWidth, 0, 1, zone, maxSpeed, ramp)).toBe(0)
+    expect(edgeScrollDelta(10, canvasWidth, pxPerSecond, 1, 0, maxSpeed, ramp)).toBe(0)
+    expect(edgeScrollDelta(10, canvasWidth, pxPerSecond, 1, zone, maxSpeed, 0)).toBe(0)
+    expect(edgeScrollDelta(10, 0, pxPerSecond, 1, zone, maxSpeed, ramp)).toBe(0)
+  })
+
+  it('converts content px/second to timeline seconds through the current scale', () => {
+    // At the surface edge, a 200 px/s zoom halves the seconds moved compared to
+    // the 100 px/s fixture above for the same content speed.
+    const atZoomedIn = edgeScrollDelta(0, canvasWidth, 200, 1, zone, maxSpeed, ramp)
+    expect(atZoomedIn).toBeCloseTo(at(0) / 2, 10)
+  })
+})
+
+describe('pivot-preserving zoom', () => {
+  it('keeps the time under the cursor stationary', () => {
+    // Scrolled well into the timeline, so zooming out either way has room and
+    // the clamps (covered separately below) never enter the picture.
+    const v = vp({ pxPerSecond: 20, scrollSeconds: 100, widthPx: 1000 })
+    const totalDuration = 600
+    const pivotX = 320
+    const pivotTime = xToTime(pivotX, v)
+
+    for (const factor of [1.25, 0.8, 2, 0.5]) {
+      const next = zoomAtPivot(v, factor, pivotX, totalDuration)
+      expect(next.pxPerSecond).toBeCloseTo(v.pxPerSecond * factor, 10)
+      expect(xToTime(pivotX, next)).toBeCloseTo(pivotTime, 10)
+    }
+  })
+
+  it('holds the pivot across a chain of wheel ticks', () => {
+    let v = vp({ pxPerSecond: 20, scrollSeconds: 30, widthPx: 1000 })
+    const totalDuration = 600
+    const pivotX = 640
+    const pivotTime = xToTime(pivotX, v)
+    for (let i = 0; i < 12; i++) {
+      v = zoomAtPivot(v, Math.exp(-(-100) * 0.002), pivotX, totalDuration)
+    }
+    expect(xToTime(pivotX, v)).toBeCloseTo(pivotTime, 8)
+  })
+
+  it('gives up the pivot only where scroll would leave the legal range', () => {
+    // Pivot near the left edge while already scrolled to 0: holding it would
+    // require scrolling before t=0.
+    const v = vp({ pxPerSecond: 20, scrollSeconds: 0, widthPx: 1000 })
+    const next = zoomAtPivot(v, 0.5, 10, 600)
+    expect(next.scrollSeconds).toBe(0)
+  })
+
+  it('clamps the scale, and keeps scroll legal when it does', () => {
+    const v = vp({ pxPerSecond: 1900, scrollSeconds: 100, widthPx: 1000 })
+    const next = zoomAtPivot(v, 4, 500, 600)
+    expect(next.pxPerSecond).toBe(MAX_PX_PER_SECOND)
+    expect(next.scrollSeconds).toBeGreaterThanOrEqual(0)
+    expect(next.scrollSeconds).toBeLessThanOrEqual(maxScrollSeconds(next, 600))
+  })
+
+  it('fits to the surface and rewinds to the start', () => {
+    const fitted = fitViewport(vp({ pxPerSecond: 900, scrollSeconds: 42 }), 50)
+    expect(fitted.pxPerSecond).toBe(20)
+    expect(fitted.scrollSeconds).toBe(0)
+    expect(zoomMultiple(fitted, 50)).toBe(1)
+  })
+})
+
+describe('wheel semantics (ported from useTimelineZoom)', () => {
+  const at = (over: Partial<Parameters<typeof wheelIntent>[0]>) =>
+    wheelIntent({ deltaX: 0, deltaY: 0, ctrlKey: false, metaKey: false, altKey: false, ...over }, 400)
+
+  it('⌘/Ctrl-wheel zooms at the cursor with the DOM path exp() step', () => {
+    const ctrl = at({ ctrlKey: true, deltaY: -100 })
+    expect(ctrl).toEqual({ kind: 'zoom', factor: Math.exp(0.2), pivotX: 400 })
+    const meta = at({ metaKey: true, deltaY: 100 })
+    expect(meta).toEqual({ kind: 'zoom', factor: Math.exp(-0.2), pivotX: 400 })
+  })
+
+  it('Alt-wheel pans horizontally by deltaY', () => {
+    expect(at({ altKey: true, deltaY: 60 })).toEqual({ kind: 'pan', deltaPx: 60 })
+  })
+
+  it('leaves a plain vertical wheel to the page', () => {
+    expect(at({ deltaY: 120 })).toEqual({ kind: 'none' })
+  })
+
+  it('consumes a horizontally-dominant plain wheel (trackpad swipe)', () => {
+    expect(at({ deltaX: 80, deltaY: 5 })).toEqual({ kind: 'pan', deltaPx: 80 })
+  })
+
+  it('applies an intent to the viewport', () => {
+    const v = vp({ pxPerSecond: 20, scrollSeconds: 10, widthPx: 1000 })
+    const zoomed = applyWheelIntent(v, { kind: 'zoom', factor: 2, pivotX: 0 }, 600)
+    expect(zoomed.pxPerSecond).toBe(40)
+    expect(zoomed.scrollSeconds).toBe(10) // pivot at x=0 is the left edge
+    expect(applyWheelIntent(v, { kind: 'pan', deltaPx: 200 }, 600).scrollSeconds).toBe(20)
+    expect(applyWheelIntent(v, { kind: 'none' }, 600)).toBe(v)
+  })
+})
+
+describe('surface size changes', () => {
+  it('starts fitted on the first layout', () => {
+    const first = withSurfaceWidth({ pxPerSecond: 0, scrollSeconds: 0, widthPx: 0 }, 800, 40)
+    expect(first.widthPx).toBe(800)
+    expect(first.pxPerSecond).toBe(20)
+  })
+
+  it('preserves scale when the window is resized', () => {
+    const v = vp({ pxPerSecond: 60, scrollSeconds: 5, widthPx: 1000 })
+    const wider = withSurfaceWidth(v, 1400, 600)
+    expect(wider.pxPerSecond).toBe(60)
+    expect(wider.scrollSeconds).toBe(5)
+  })
+
+  it('re-clamps scroll when the project shrinks under the playhead', () => {
+    const v = vp({ pxPerSecond: 10, scrollSeconds: 400, widthPx: 1000 })
+    const shrunk = reclampForDuration(v, 60)
+    expect(shrunk.scrollSeconds).toBe(0)
+  })
+})
+
+describe('DPR-crisp sizing', () => {
+  it('sizes the backing store in device pixels', () => {
+    expect(backingStoreSize(800, 120, 2)).toEqual({ width: 1600, height: 240 })
+    expect(backingStoreSize(800.4, 120.6, 1)).toEqual({ width: 800, height: 121 })
+    expect(backingStoreSize(0, 0, 2)).toEqual({ width: 1, height: 1 })
+    expect(backingStoreSize(800, 120, 0)).toEqual({ width: 800, height: 120 })
+  })
+
+  it('only rewrites canvas dimensions when they actually change', () => {
+    const canvas = document.createElement('canvas')
+    expect(syncCanvasBackingStore(canvas, { cssWidth: 400, cssHeight: 100, dpr: 2 })).toBe(true)
+    expect(canvas.width).toBe(800)
+    expect(canvas.height).toBe(200)
+    expect(syncCanvasBackingStore(canvas, { cssWidth: 400, cssHeight: 100, dpr: 2 })).toBe(false)
+    // Same CSS box, new monitor: the backing store must follow the DPR.
+    expect(syncCanvasBackingStore(canvas, { cssWidth: 400, cssHeight: 100, dpr: 1 })).toBe(true)
+    expect(canvas.width).toBe(400)
+  })
+
+  it('puts the context in CSS-pixel space idempotently', () => {
+    const setTransform = vi.fn()
+    scaleContextToDpr({ setTransform } as unknown as CanvasRenderingContext2D, 3)
+    scaleContextToDpr({ setTransform } as unknown as CanvasRenderingContext2D, 3)
+    expect(setTransform).toHaveBeenNthCalledWith(1, 3, 0, 0, 3, 0, 0)
+    expect(setTransform).toHaveBeenNthCalledWith(2, 3, 0, 0, 3, 0, 0)
+  })
+})
+
+describe('viewport store', () => {
+  it('notifies subscribers on change and skips no-op writes', () => {
+    const store = createViewportStore(vp())
+    const seen = vi.fn()
+    const unsubscribe = store.subscribe(seen)
+
+    store.set(v => ({ ...v, scrollSeconds: 4 }))
+    expect(store.get().scrollSeconds).toBe(4)
+    expect(seen).toHaveBeenCalledTimes(1)
+
+    store.set(v => ({ ...v })) // same numbers, new object
+    expect(seen).toHaveBeenCalledTimes(1)
+
+    unsubscribe()
+    store.set(v => ({ ...v, scrollSeconds: 9 }))
+    expect(seen).toHaveBeenCalledTimes(1)
+    expect(store.get().scrollSeconds).toBe(9)
+  })
+
+  it('keeps snapshot identity stable so useSyncExternalStore does not loop', () => {
+    const store = createViewportStore(vp())
+    expect(store.get()).toBe(store.get())
+  })
+})