@bycrux/editor 0.11.2 → 1.0.1

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

@@ -0,0 +1,2198 @@
+/**
+ * SP5 T4 — the canvas painter. Every draw function is pure, so the tests drive
+ * them with a context stub that records the calls and asserts on the list: the
+ * rectangle a clip lands in IS the observable behaviour of a painter.
+ *
+ * The last block is the acceptance probe for the virtualization claim: with a
+ * long project and a small window, the number of draw calls must be bounded by
+ * what's visible, not by how many items exist.
+ */
+import { describe, it, expect } from 'vitest'
+import type { AudioTrack, CaptionSegment, VisualItem } from '../../../../schema'
+import type { Project } from '../../../../types'
+import {
+  AUDIO_HANDLE_WIDTH_PX,
+  AUDIO_ITEM_INSET_PX,
+  AUDIO_ITEM_RADIUS_PX,
+  CAPTION_PALETTE,
+  CAPTION_RAIL_ACCENT,
+  DARK_TIMELINE_PALETTE,
+  LABEL_SHADOW_COLOR,
+  LIGHT_CAPTION_PALETTE,
+  LIGHT_CAPTION_RAIL_ACCENT,
+  LIGHT_LABEL_SHADOW_COLOR,
+  LIGHT_TIMELINE_COLORS,
+  LIGHT_TIMELINE_PALETTE,
+  LIGHT_TRACK_PALETTE,
+  timelinePalette,
+  drawCursorLine,
+  drawMarquee,
+  drawRuler,
+  type TimelinePalette,
+  CLIP_HANDLE_WIDTH_PX,
+  FADE_GRIP_SIZE_PX,
+  CURSOR_WIDTH_PX,
+  LABEL_PAD_PX,
+  LABEL_TOP_OFFSET_PX,
+  CLIP_GUTTER_PX,
+  CLIP_SELECTED_BORDER_PX,
+  MIN_LABEL_WIDTH_PX,
+  PLAYHEAD_WIDTH_PX,
+  ROW_RADIUS_PX,
+  TIMELINE_COLORS,
+  TRACK_PALETTE,
+  clampRectToSurface,
+  drawRowBackground,
+  computeTimelineLayout,
+  overlapBands,
+  drawAudioItem,
+  drawCaptionBlock,
+  drawClipRect,
+  drawTrimHandle,
+  FADE_ENVELOPE_SEGMENTS,
+  RULER_HEIGHT_PX,
+  SNAP_GUIDE_CAP_HALF_WIDTH_PX,
+  SNAP_GUIDE_WEAK_WIDTH_PX,
+  SNAP_GUIDE_WIDTH_PX,
+  OVERLAP_EDGE_WIDTH_PX,
+  OVERLAP_HATCH_SHADOW_WIDTH_PX,
+  OVERLAP_HATCH_WIDTH_PX,
+  drawItemHandles,
+  drawKeyframeStrip,
+  drawOverlapBand,
+  drawPlayhead,
+  drawSnapGuide,
+  drawTimelineContent,
+  drawTimelineOverlay,
+  type DrawContext,
+  type TimelineScene,
+} from '../draw'
+import { KEYFRAME_DIAMOND_SIZE_PX, KEYFRAME_STRIP_BOTTOM_PAD_PX, keyframeDiamondX } from '../keyframe-strip'
+import { LIGHT_WAVEFORM_COLORS, WAVEFORM_COLORS } from '../waveforms'
+import {
+  AUDIO_LANE_HEIGHT_PX,
+  BASE_VISUAL_ROW_RENDER_HEIGHT_PX,
+  CAPTION_ROW_HEIGHT_PX,
+  ROW_GAP_PX,
+  VISUAL_ROW_RENDER_HEIGHT_PX,
+} from '../../timeline-model'
+import type { Viewport } from '../viewport'
+
+// ── Recording context ────────────────────────────────────────────────────
+
+interface RecordedCall { method: string; args: unknown[] }
+
+interface Recorder {
+  ctx: DrawContext
+  calls: RecordedCall[]
+  of: (method: string) => RecordedCall[]
+  count: (method: string) => number
+}
+
+function recordingContext(): Recorder {
+  const calls: RecordedCall[] = []
+  const props: Record<string, unknown> = {}
+
+  const proxy = new Proxy({}, {
+    get(_target, prop: string) {
+      if (prop in props) return props[prop]
+      if (prop === 'createLinearGradient') {
+        return (...args: unknown[]) => {
+          calls.push({ method: 'createLinearGradient', args })
+          return {
+            addColorStop: (...stop: unknown[]) => calls.push({ method: 'addColorStop', args: stop }),
+          } as unknown as CanvasGradient
+        }
+      }
+      return (...args: unknown[]) => { calls.push({ method: prop, args }) }
+    },
+    set(_target, prop: string, value: unknown) {
+      props[prop] = value
+      calls.push({ method: `set:${prop}`, args: [value] })
+      return true
+    },
+  }) as unknown as DrawContext
+
+  return {
+    ctx: proxy,
+    calls,
+    of: (method: string) => calls.filter(c => c.method === method),
+    count: (method: string) => calls.filter(c => c.method === method).length,
+  }
+}
+
+// ── Fixtures ─────────────────────────────────────────────────────────────
+
+function clip(over: Partial<VisualItem> = {}): VisualItem {
+  return { id: 'c0', type: 'video', src: 'a.mp4', start: 0, end: 2, ...over }
+}
+
+function audio(over: Partial<AudioTrack> = {}): AudioTrack {
+  return { id: 'a0', src: '/media/voice.mp3', start: 0, end: 2, ...over }
+}
+
+function captionSegment(over: Partial<CaptionSegment> = {}): CaptionSegment {
+  return { id: 'seg0', text: 'hello world', start: 0, end: 2, ...over }
+}
+
+function project(over: Partial<Project> = {}): Project {
+  return { id: 'p1', ...over } as unknown as Project
+}
+
+function viewport(over: Partial<Viewport> = {}): Viewport {
+  return { pxPerSecond: 10, scrollSeconds: 0, widthPx: 1000, ...over }
+}
+
+function scene(over: Partial<TimelineScene> = {}): TimelineScene {
+  const p = over.project ?? project()
+  return {
+    project: p,
+    viewport: viewport(),
+    layout: computeTimelineLayout(p),
+    selectedIds: [],
+    surfaceWidth: 1000,
+    surfaceHeight: 200,
+    ...over,
+  }
+}
+
+/** What the ruler alone draws at this viewport — an empty project draws the
+ *  ruler and nothing else. Content-volume assertions subtract this so they keep
+ *  measuring the thing they are about (items, rows) rather than the fixed cost
+ *  of the chrome above them. */
+function rulerBaseline(vp: Viewport) {
+  const empty = project()
+  const r = recordingContext()
+  drawTimelineContent(r.ctx, scene({ project: empty, layout: computeTimelineLayout(empty), viewport: vp }))
+  return { calls: r.calls.length, fillRect: r.count('fillRect'), fillText: r.count('fillText') }
+}
+
+// ── Layout ───────────────────────────────────────────────────────────────
+
+describe('computeTimelineLayout', () => {
+  it('stacks visual tracks reversed, base track last and taller, audio lanes below', () => {
+    const p = project({
+      // ov1/ov2 are overlay-typed (not video), so they stay the short row —
+      // isolates "base track is tall" from the separate "a VIDEO track is
+      // tall" rule below.
+      tracks: [[clip({ id: 'base' })], [clip({ id: 'ov1', type: 'overlay' })], [clip({ id: 'ov2', type: 'overlay' })]],
+      audio: { tracks: [audio({ id: 'm', lane: 0 }), audio({ id: 'v', lane: 1 })] },
+    } as unknown as Partial<Project>)
+
+    const layout = computeTimelineLayout(p)
+
+    // Draw order top→bottom mirrors the DOM's `[...allTracks].reverse()`.
+    expect(layout.rows.map(r => r.trackIdx)).toEqual([2, 1, 0])
+    // Rows start below the ruler strip, which owns the top of the surface.
+    const contentTop = RULER_HEIGHT_PX + ROW_GAP_PX
+    expect(layout.ruler).toEqual({ y: 0, height: RULER_HEIGHT_PX })
+    expect(layout.rows[0]).toMatchObject({ y: contentTop, height: VISUAL_ROW_RENDER_HEIGHT_PX })
+    expect(layout.rows[1]).toMatchObject({ y: contentTop + VISUAL_ROW_RENDER_HEIGHT_PX + ROW_GAP_PX })
+    // The base video track is the tall one (120px vs. 40px for the rest).
+    expect(layout.rows[2].height).toBe(BASE_VISUAL_ROW_RENDER_HEIGHT_PX)
+
+    expect(layout.lanes.map(l => l.laneIndex)).toEqual([0, 1])
+    expect(layout.lanes[0].y).toBe(layout.rows[2].y + BASE_VISUAL_ROW_RENDER_HEIGHT_PX + ROW_GAP_PX)
+    expect(layout.lanes[1].y).toBe(layout.lanes[0].y + AUDIO_LANE_HEIGHT_PX + ROW_GAP_PX)
+    expect(layout.height).toBe(layout.lanes[1].y + AUDIO_LANE_HEIGHT_PX)
+  })
+
+  it('gives every VIDEO-kind track the tall base row height, not just trackIdx 0 — an overlay track stays short', () => {
+    // A second video track carries the same filmstrip+waveform content as
+    // the base track and needs the same room; an overlay/image track has
+    // neither and keeps the short row.
+    const p = project({
+      tracks: [
+        [clip({ id: 'base', type: 'video' })],
+        [clip({ id: 'video2', type: 'video' })],
+        [clip({ id: 'ov', type: 'overlay' })],
+      ],
+    } as unknown as Partial<Project>)
+
+    const layout = computeTimelineLayout(p)
+    expect(layout.rows.find(r => r.trackIdx === 0)!.height).toBe(BASE_VISUAL_ROW_RENDER_HEIGHT_PX)
+    expect(layout.rows.find(r => r.trackIdx === 1)!.height).toBe(BASE_VISUAL_ROW_RENDER_HEIGHT_PX)
+    expect(layout.rows.find(r => r.trackIdx === 2)!.height).toBe(VISUAL_ROW_RENDER_HEIGHT_PX)
+  })
+
+  it('keeps the base track (trackIdx 0) tall even when it has no items yet', () => {
+    // trackIdx 0 is always tall regardless of content, so a blank base row
+    // doesn't jump size the moment footage lands on it.
+    const p = project({ tracks: [[]] } as unknown as Partial<Project>)
+    const layout = computeTimelineLayout(p)
+    expect(layout.rows.find(r => r.trackIdx === 0)!.height).toBe(BASE_VISUAL_ROW_RENDER_HEIGHT_PX)
+  })
+
+  it('reorders a scrambled-input project so the video track is trackIdx 0, even when it was written second on disk (Part B)', () => {
+    // Raw/on-disk order: overlay first, video second — `allTracks` here
+    // comes from `trackItems`, which funnels through `normalizeTracks`
+    // (now order-canonicalizing too), so `computeTimelineLayout` never sees
+    // the raw order — the video track lands at trackIdx 0 regardless of
+    // where it sat in the stored array.
+    const p = project({
+      tracks: [
+        [{ id: 'ov', type: 'overlay', start: 0, end: 1 }],
+        [{ id: 'v0', type: 'video', src: 'v0.mp4', start: 0, end: 1 }],
+      ],
+    } as unknown as Partial<Project>)
+
+    const layout = computeTimelineLayout(p)
+    const baseRow = layout.rows.find(r => r.trackIdx === 0)!
+    expect(baseRow.items.map(i => i.id)).toEqual(['v0'])
+    expect(baseRow.height).toBe(BASE_VISUAL_ROW_RENDER_HEIGHT_PX)
+    const overlayRow = layout.rows.find(r => r.trackIdx === 1)!
+    expect(overlayRow.items.map(i => i.id)).toEqual(['ov'])
+  })
+
+  it('is empty for an empty project, but still reserves the ruler', () => {
+    const layout = computeTimelineLayout(project())
+    expect(layout).toEqual({
+      ruler: { y: 0, height: RULER_HEIGHT_PX },
+      rows: [],
+      lanes: [],
+      height: RULER_HEIGHT_PX,
+    })
+  })
+
+  // ── Captions in the canvas layout (Phase 1: one band. Phase 3: N bands) ──
+
+  describe('the caption band(s)', () => {
+    it('sits strictly between the last overlay row and the base video row', () => {
+      const p = project({
+        // Overlay-typed, not `clip()`'s default video — this test is
+        // specifically about an OVERLAY row above the base, per its own name.
+        tracks: [[clip({ id: 'base' })], [clip({ id: 'ov1', type: 'overlay' })]],
+        captions: { style: 'clean', segments: [captionSegment()] },
+      } as unknown as Partial<Project>)
+
+      const layout = computeTimelineLayout(p)
+      const overlayRow = layout.rows.find(r => r.trackIdx === 1)!
+      const baseRow = layout.rows.find(r => r.trackIdx === 0)!
+
+      expect(layout.captions).toHaveLength(1)
+      expect(layout.captions![0].lane).toBe(0)
+      expect(layout.captions![0].height).toBe(CAPTION_ROW_HEIGHT_PX)
+      expect(layout.captions![0].y).toBeGreaterThan(overlayRow.y + overlayRow.height)
+      expect(layout.captions![0].y).toBeLessThan(baseRow.y)
+      expect(layout.captions![0].segments).toEqual([captionSegment()])
+    })
+
+    it('is absent — not an empty array — with no captions, and every other row is unchanged', () => {
+      const tracks = [[clip({ id: 'base' })], [clip({ id: 'ov1' })]]
+      const noCaptionsAtAll = project({ tracks } as unknown as Partial<Project>)
+      const emptySegments = project({
+        tracks,
+        captions: { style: 'clean', segments: [] },
+      } as unknown as Partial<Project>)
+
+      const baseline = computeTimelineLayout(noCaptionsAtAll)
+      for (const p of [noCaptionsAtAll, emptySegments]) {
+        const layout = computeTimelineLayout(p)
+        expect(layout.captions).toBeUndefined()
+        expect(layout.rows).toEqual(baseline.rows)
+        expect(layout.lanes).toEqual(baseline.lanes)
+        expect(layout.height).toBe(baseline.height)
+      }
+    })
+
+    it('still appears, above where the video row would be, on a project with captions but no visual tracks', () => {
+      const p = project({
+        captions: { style: 'clean', segments: [captionSegment()] },
+      } as unknown as Partial<Project>)
+      const layout = computeTimelineLayout(p)
+
+      expect(layout.rows).toEqual([])
+      expect(layout.captions).toHaveLength(1)
+      expect(layout.captions![0].y).toBe(RULER_HEIGHT_PX + ROW_GAP_PX)
+      expect(layout.height).toBe(layout.captions![0].y + CAPTION_ROW_HEIGHT_PX)
+    })
+
+    // ── Regression guard (Phase 3) ──
+    // Multi-lane captions must not move a single-lane project's band by even
+    // one pixel: the exact geometry a lane-0-only project got in Phase 1 is
+    // reproduced here, numeral for numeral, rather than compared loosely.
+    it('keeps a lane-0-only layout — band y, band height, and total surface height — byte-for-byte identical to before N-lane captions', () => {
+      const p = project({
+        // Overlay-typed, not `clip()`'s default video: this is the SINGLE
+        // -video-track case (only `base` is video) the byte-identical
+        // guarantee is about — the caption band still sits directly above
+        // the base row, exactly where it always has.
+        tracks: [[clip({ id: 'base' })], [clip({ id: 'ov1', type: 'overlay' })]],
+        captions: { style: 'clean', segments: [captionSegment()] },
+      } as unknown as Partial<Project>)
+
+      const layout = computeTimelineLayout(p)
+      // Re-derived from the layout's own rows rather than pinned to a height
+      // constant, so this regression guard survives future height changes.
+      const upperRow = layout.rows.find(r => r.trackIdx === 1)!
+      const baseRow = layout.rows.find(r => r.trackIdx === 0)!
+      const band = layout.captions![0]
+
+      expect(layout.captions).toHaveLength(1)
+      expect(band).toMatchObject({ lane: 0, height: CAPTION_ROW_HEIGHT_PX })
+      expect(band.y).toBe(upperRow.y + upperRow.height + ROW_GAP_PX)
+      expect(baseRow.y).toBe(band.y + band.height + ROW_GAP_PX)
+      expect(layout.height).toBe(baseRow.y + baseRow.height)
+    })
+
+    it('emits N bands in descending lane order, lane 0 landing exactly where the single band sits today', () => {
+      const p = project({
+        // Overlay-typed, not `clip()`'s default video — single-video-track
+        // case, so lane 0 lands directly above `base` with nothing between.
+        tracks: [[clip({ id: 'base' })], [clip({ id: 'ov1', type: 'overlay' })]],
+        captions: {
+          style: 'clean',
+          segments: [
+            captionSegment({ id: 's0', lane: 0 }),
+            captionSegment({ id: 's1', lane: 1, start: 2, end: 4 }),
+            captionSegment({ id: 's2', lane: 2, start: 4, end: 6 }),
+          ],
+        },
+      } as unknown as Partial<Project>)
+
+      const layout = computeTimelineLayout(p)
+      const baseRow = layout.rows.find(r => r.trackIdx === 0)!
+
+      expect(layout.captions).toHaveLength(3)
+      // Index 0 is the HIGHEST lane; the last entry is lane 0.
+      expect(layout.captions!.map(c => c.lane)).toEqual([2, 1, 0])
+
+      const [lane2, lane1, lane0] = layout.captions!
+      // Lane 0 sits immediately above the base row — the exact position a
+      // lane-0-only project's single band has always occupied.
+      expect(lane0.y + lane0.height + ROW_GAP_PX).toBe(baseRow.y)
+      // Higher lanes stack upward (smaller y) toward the overlays.
+      expect(lane1.y).toBeLessThan(lane0.y)
+      expect(lane2.y).toBeLessThan(lane1.y)
+    })
+
+    // ── Part B: track grouping — the caption band sits above the WHOLE
+    // video block, not squeezed between two video tracks ──────────────────
+
+    it('with two video tracks and one overlay track, stacks overlay(top) → captions → video block (topmost video, then base)', () => {
+      const p = project({
+        tracks: [
+          [clip({ id: 'base' })],                      // video, base
+          [clip({ id: 'video2', type: 'video' })],      // video, second track
+          [clip({ id: 'ov1', type: 'overlay' })],       // overlay
+        ],
+        captions: { style: 'clean', segments: [captionSegment()] },
+      } as unknown as Partial<Project>)
+
+      const layout = computeTimelineLayout(p)
+      // Already in canonical order in this fixture (video tracks precede the
+      // overlay track), so trackIdx assignment is unchanged from array order
+      // — but the DRAW order (top of screen first) is still the reverse.
+      expect(layout.rows.map(r => r.trackIdx)).toEqual([2, 1, 0])
+      const overlayRow = layout.rows.find(r => r.trackIdx === 2)!
+      const video2Row = layout.rows.find(r => r.trackIdx === 1)!
+      const baseRow = layout.rows.find(r => r.trackIdx === 0)!
+
+      expect(layout.captions).toHaveLength(1)
+      const band = layout.captions![0]
+      // Captions sit directly above the TOPMOST video track (video2) — NOT
+      // between video2 and base — and directly below the overlay row.
+      expect(band.y).toBe(overlayRow.y + overlayRow.height + ROW_GAP_PX)
+      expect(video2Row.y).toBe(band.y + band.height + ROW_GAP_PX)
+      expect(video2Row.y + video2Row.height + ROW_GAP_PX).toBe(baseRow.y)
+    })
+
+    it('a hole lane still gets its own band, empty of segments, rather than being skipped', () => {
+      const p = project({
+        tracks: [[clip({ id: 'base' })]],
+        captions: {
+          style: 'clean',
+          // Lanes 0 and 2 occupied; lane 1 is a hole.
+          segments: [
+            captionSegment({ id: 's0', lane: 0 }),
+            captionSegment({ id: 's2', lane: 2, start: 4, end: 6 }),
+          ],
+        },
+      } as unknown as Partial<Project>)
+
+      const layout = computeTimelineLayout(p)
+      expect(layout.captions).toHaveLength(3)
+      expect(layout.captions!.map(c => c.lane)).toEqual([2, 1, 0])
+      const holeBand = layout.captions!.find(c => c.lane === 1)!
+      expect(holeBand.segments).toEqual([])
+      expect(holeBand.height).toBe(CAPTION_ROW_HEIGHT_PX)
+    })
+  })
+})
+
+describe('clampRectToSurface', () => {
+  it('trims a clip that runs far past both edges', () => {
+    expect(clampRectToSurface({ x: -50_000, y: 0, width: 100_000, height: 40 }, 1000))
+      .toEqual({ x: -1, y: 0, width: 1002, height: 40 })
+  })
+})
+
+// ── Element painters ─────────────────────────────────────────────────────
+
+describe('drawClipRect', () => {
+  it('insets the body from the clip\'s span, leaving a gutter between touching clips', () => {
+    const r = recordingContext()
+    drawClipRect(r.ctx, {
+      rect: { x: 120, y: 40, width: 200, height: 40 },
+      palette: TRACK_PALETTE[1],
+      selected: false,
+      label: '▪ video',
+    })
+
+    // Inset by CLIP_GUTTER_PX per side — two touching clips therefore show
+    // twice that as dark row background, which is what makes a cut visible
+    // once filmstrip frames run edge to edge.
+    const fills = r.of('fillRect')
+    expect(fills[0].args).toEqual([120 + CLIP_GUTTER_PX, 40, 200 - CLIP_GUTTER_PX * 2, 40])
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TRACK_PALETTE[1].fill)).toBe(true)
+    // Top-left, not vertically centred: the centre of a clip is now the seam
+    // between its frames band and its waveform band.
+    expect(r.of('fillText')[0].args).toEqual(['▪ video', 120 + CLIP_GUTTER_PX + 6, 40 + LABEL_TOP_OFFSET_PX])
+  })
+
+  it('outlines every clip, and a selected one in thick white', () => {
+    const plain = recordingContext()
+    drawClipRect(plain.ctx, { rect: { x: 0, y: 0, width: 100, height: 40 }, palette: TRACK_PALETTE[0], selected: false, label: 'x' })
+    expect(plain.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === TRACK_PALETTE[0].border)).toBe(true)
+    expect(plain.calls.some(c => c.method === 'set:lineWidth' && c.args[0] === 1)).toBe(true)
+
+    const picked = recordingContext()
+    drawClipRect(picked.ctx, { rect: { x: 0, y: 0, width: 100, height: 40 }, palette: TRACK_PALETTE[0], selected: true, label: 'x' })
+    // White, not the track's own hue — the only treatment that reads over an
+    // arbitrary video frame.
+    expect(picked.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === TIMELINE_COLORS.clipSelectedOutline)).toBe(true)
+    expect(picked.calls.some(c => c.method === 'set:lineWidth' && c.args[0] === CLIP_SELECTED_BORDER_PX)).toBe(true)
+    expect(picked.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TRACK_PALETTE[0].fillSelected)).toBe(true)
+  })
+
+  it('clips its content to the rounded body, so frames stop at the corners', () => {
+    const r = recordingContext()
+    drawClipRect(r.ctx, {
+      rect: { x: 0, y: 0, width: 100, height: 40 },
+      palette: TRACK_PALETTE[0], selected: false, label: 'x',
+      drawContent: (c, body) => c.fillRect(body.x, body.y, body.width, body.height),
+    })
+    // A clip path is established before the content paints.
+    const clipAt = r.calls.findIndex(c => c.method === 'clip')
+    const contentAt = r.calls.findIndex(c => c.method === 'fillRect' && (c.args as number[])[2] === 100 - CLIP_GUTTER_PX * 2)
+    expect(clipAt).toBeGreaterThanOrEqual(0)
+    expect(clipAt).toBeLessThan(contentAt)
+  })
+
+  it('hands drawContent the inset body, not the full span', () => {
+    let handed: { x: number; width: number } | null = null
+    const r = recordingContext()
+    drawClipRect(r.ctx, {
+      rect: { x: 120, y: 40, width: 200, height: 40 },
+      palette: TRACK_PALETTE[0], selected: false, label: 'x',
+      drawContent: (_c, body) => { handed = { x: body.x, width: body.width } },
+    })
+    expect(handed).toEqual({ x: 120 + CLIP_GUTTER_PX, width: 200 - CLIP_GUTTER_PX * 2 })
+  })
+
+  it('skips the label on a clip too narrow to read it', () => {
+    const r = recordingContext()
+    drawClipRect(r.ctx, {
+      rect: { x: 0, y: 0, width: MIN_LABEL_WIDTH_PX - 1, height: 40 },
+      palette: TRACK_PALETTE[0], selected: false, label: '▪ video',
+    })
+    expect(r.count('fillText')).toBe(0)
+  })
+
+  it('draws nothing for a zero-width rect', () => {
+    const r = recordingContext()
+    drawClipRect(r.ctx, { rect: { x: 10, y: 0, width: 0, height: 40 }, palette: TRACK_PALETTE[0], selected: false, label: 'x' })
+    expect(r.calls).toHaveLength(0)
+  })
+
+  // ── Trim handles: the affordance selection is FOR ──
+  //
+  // The handles themselves are the row painter's job now (a clip stacked on
+  // top of this one would bury them), so `drawClipRect` must NOT draw them —
+  // only leave room for them.
+
+  it('leaves the handles to the row painter', () => {
+    const r = recordingContext()
+    drawClipRect(r.ctx, { rect: { x: 0, y: 0, width: 200, height: 40 }, palette: TRACK_PALETTE[0], selected: true, label: '' })
+    expect(r.of('set:fillStyle').some(c => c.args[0] === TIMELINE_COLORS.handleFill)).toBe(false)
+  })
+
+  it('indents a selected clip\'s label past its in handle', () => {
+    const free = recordingContext()
+    drawClipRect(free.ctx, { rect: { x: 0, y: 0, width: 200, height: 40 }, palette: TRACK_PALETTE[0], selected: false, label: 'title' })
+    const picked = recordingContext()
+    drawClipRect(picked.ctx, { rect: { x: 0, y: 0, width: 200, height: 40 }, palette: TRACK_PALETTE[0], selected: true, label: 'title' })
+    // Without the indent the pill would sit on top of the first glyph.
+    expect(Number(picked.of('fillText')[0].args[1]) - Number(free.of('fillText')[0].args[1]))
+      .toBe(CLIP_HANDLE_WIDTH_PX)
+  })
+
+  it('dims a row unrelated to the primary selection', () => {
+    const r = recordingContext()
+    drawClipRect(r.ctx, { rect: { x: 0, y: 0, width: 80, height: 40 }, palette: TRACK_PALETTE[0], selected: false, label: 'x', dimmed: true })
+    expect(r.calls.some(c => c.method === 'set:globalAlpha' && c.args[0] === 0.3)).toBe(true)
+  })
+})
+
+describe('drawTrimHandle', () => {
+  // 2 ticks of 1.5px with a 2.5px gap; a 40px-tall row gives the capped 16px
+  // tick height, centred, so the grip sits at y=12.
+  const GRIP_SPAN = 5.5
+
+  it('pins the in handle to the left edge and the out handle to the right', () => {
+    const left = recordingContext()
+    drawTrimHandle(left.ctx, { rect: { x: 0, y: 0, width: 100, height: 40 }, edge: 'in', width: 10 })
+    expect(left.of('fillRect').map(c => c.args)).toEqual([
+      [(10 - GRIP_SPAN) / 2, 12, 1.5, 16],
+      [(10 - GRIP_SPAN) / 2 + 4, 12, 1.5, 16],
+    ])
+
+    const right = recordingContext()
+    drawTrimHandle(right.ctx, { rect: { x: 0, y: 0, width: 100, height: 40 }, edge: 'out', width: 10 })
+    // 100 - 10 = 90 is the pill's left edge; the grip is centred in it.
+    expect(right.of('fillRect')[0].args[0]).toBe(90 + (10 - GRIP_SPAN) / 2)
+  })
+
+  it('draws the pill in the handle white, and its grip dark', () => {
+    const r = recordingContext()
+    drawTrimHandle(r.ctx, { rect: { x: 0, y: 0, width: 100, height: 40 }, edge: 'in', width: 10 })
+    expect(r.of('set:fillStyle').map(c => c.args[0])).toEqual([
+      TIMELINE_COLORS.handleFill,
+      TIMELINE_COLORS.handleGrip,
+    ])
+  })
+
+  it('goes opaque under the pointer, so the grabbable edge is unambiguous', () => {
+    const r = recordingContext()
+    drawTrimHandle(r.ctx, { rect: { x: 0, y: 0, width: 100, height: 40 }, edge: 'in', width: 10, hovered: true })
+    expect(r.of('set:fillStyle').map(c => c.args[0])).toEqual([
+      TIMELINE_COLORS.handleFillHovered,
+      TIMELINE_COLORS.handleGripHovered,
+    ])
+  })
+
+  it('halves itself on a short clip, so two handles can never meet', () => {
+    const r = recordingContext()
+    // 12px of clip, 10px of nominal handle: each takes 6 and the grip, which
+    // no longer fits with a margin, drops out rather than filling the pill.
+    drawTrimHandle(r.ctx, { rect: { x: 0, y: 0, width: 12, height: 40 }, edge: 'out', width: 10 })
+    expect(r.count('fill')).toBe(1)
+    expect(r.count('fillRect')).toBe(0)
+    // The pill starts halfway across, not 10px from the right edge.
+    expect(r.of('moveTo')[0].args[0]).toBeGreaterThanOrEqual(6)
+  })
+
+  it('draws nothing at all once the pill is thinner than its own outline', () => {
+    const r = recordingContext()
+    drawTrimHandle(r.ctx, { rect: { x: 0, y: 0, width: 5, height: 40 }, edge: 'in', width: 10 })
+    expect(r.calls).toHaveLength(0)
+  })
+
+  it('draws nothing for an empty rect', () => {
+    const r = recordingContext()
+    drawTrimHandle(r.ctx, { rect: { x: 0, y: 0, width: 0, height: 0 }, edge: 'in', width: 10 })
+    expect(r.calls).toHaveLength(0)
+  })
+})
+
+describe('drawKeyframeStrip', () => {
+  // 2s–4s overlay, keyframed on offsetX (t=0, t=1) and opacity (t=0 only —
+  // shares the FIRST diamond with offsetX). Union of times is {0, 1}: one
+  // diamond both props share, one offsetX draws alone.
+  function keyframedOverlay(): VisualItem {
+    return clip({
+      id: 'o0', type: 'overlay', src: undefined, start: 2, end: 4,
+      keyframes: [
+        { prop: 'offsetX', points: [{ t: 0, value: 0 }, { t: 1, value: 10 }] },
+        { prop: 'opacity', points: [{ t: 0, value: 1 }] },
+      ],
+    } as unknown as Partial<VisualItem>)
+  }
+
+  // A REALISTIC body, not the clip's raw rect: the real caller (the row loop
+  // below) always hands `drawKeyframeStrip` `clipBodyRect(rect)`, which insets
+  // by `CLIP_GUTTER_PX` per side. `rect.x` for this item (start=2 @ 10px/s) is
+  // 20 and `rect.width` is 20, so `body` is `{ x: 22, width: 16 }` — using
+  // `{ x: 20, width: 20 }` here (rect verbatim) used to mask the endpoint-
+  // diamond clipping bug this file now guards against, because it made
+  // `body.x` coincide with `rect.x` instead of sitting `CLIP_GUTTER_PX` inside
+  // it.
+  const BODY = { x: 20 + CLIP_GUTTER_PX, y: 0, width: 20 - CLIP_GUTTER_PX * 2, height: 40 }
+  const vp = viewport({ pxPerSecond: 10 })
+
+  it('draws one diamond per DISTINCT time in the union, not one per prop', () => {
+    const r = recordingContext()
+    drawKeyframeStrip(r.ctx, keyframedOverlay(), BODY, vp)
+    // Each diamond is one closed 4-point path: moveTo + 3 lineTo + closePath.
+    expect(r.count('moveTo')).toBe(2)
+    expect(r.count('closePath')).toBe(2)
+    expect(r.count('fill')).toBe(2)
+  })
+
+  it('positions each diamond at item.start + t, run through the SAME timeToX everything else uses', () => {
+    const r = recordingContext()
+    drawKeyframeStrip(r.ctx, keyframedOverlay(), BODY, vp)
+    const y = BODY.y + BODY.height - KEYFRAME_DIAMOND_SIZE_PX / 2 - KEYFRAME_STRIP_BOTTOM_PAD_PX
+    const half = KEYFRAME_DIAMOND_SIZE_PX / 2
+    // t=0 -> (2+0)*10=20; t=1 -> (2+1)*10=30.
+    expect(r.of('moveTo').map(c => c.args)).toEqual([
+      [20, y - half],
+      [30, y - half],
+    ])
+  })
+
+  it('fills amber and strokes for definition', () => {
+    const r = recordingContext()
+    drawKeyframeStrip(r.ctx, keyframedOverlay(), BODY, vp)
+    expect(r.of('set:fillStyle').every(c => c.args[0] === TIMELINE_COLORS.keyframeDiamondFill)).toBe(true)
+    expect(r.of('set:strokeStyle').every(c => c.args[0] === TIMELINE_COLORS.keyframeDiamondStroke)).toBe(true)
+  })
+
+  it('paints the diamond matching selectedT with a different fillStyle than the rest', () => {
+    const r = recordingContext()
+    // Union of times is {0, 1} (ascending) — selecting t=1 must mark only the
+    // SECOND diamond, leaving the first one drawn with the ordinary fill.
+    drawKeyframeStrip(r.ctx, keyframedOverlay(), BODY, vp, 1)
+    const fills = r.of('set:fillStyle').map(c => c.args[0])
+    expect(fills).toEqual([TIMELINE_COLORS.keyframeDiamondFill, TIMELINE_COLORS.keyframeDiamondSelectedFill])
+  })
+
+  it('paints every diamond identically when selectedT is null (or omitted)', () => {
+    const r = recordingContext()
+    drawKeyframeStrip(r.ctx, keyframedOverlay(), BODY, vp, null)
+    const fills = r.of('set:fillStyle').map(c => c.args[0])
+    expect(fills[0]).toBe(fills[1])
+    expect(new Set(fills).size).toBe(1)
+  })
+
+  it('clips to a region derived from the clip body, widened past its edges (not the raw body rect)', () => {
+    const r = recordingContext()
+    drawKeyframeStrip(r.ctx, keyframedOverlay(), BODY, vp)
+    // The widened region equals the clip's TRUE (un-gutter-inset) rect, grown
+    // by half a diamond on each side: [rect.x - half, rect.x + rect.width +
+    // half]. rect.x=20, rect.width=20, half=4 -> [16, 44] -> x=16, width=28.
+    const half = KEYFRAME_DIAMOND_SIZE_PX / 2
+    const rectX = BODY.x - CLIP_GUTTER_PX
+    const rectWidth = BODY.width + CLIP_GUTTER_PX * 2
+    expect(r.of('rect')[0].args).toEqual([rectX - half, BODY.y, rectWidth + half * 2, BODY.height])
+    expect(r.count('clip')).toBe(1)
+  })
+
+  it('an ENDPOINT diamond (t=0, at the clip\'s own true left edge) survives WHOLE — the gutter inset no longer slices it to a sliver', () => {
+    const r = recordingContext()
+    const item = keyframedOverlay()
+    drawKeyframeStrip(r.ctx, item, BODY, vp)
+    const [regionX, , regionWidth] = r.of('rect')[0].args as number[]
+    const half = KEYFRAME_DIAMOND_SIZE_PX / 2
+    const cx = keyframeDiamondX(item, 0, vp)
+    // The whole diamond — both edges, not just its centre — must fall inside
+    // the clip region drawKeyframeStrip actually used.
+    expect(regionX).toBeLessThanOrEqual(cx - half)
+    expect(regionX + regionWidth).toBeGreaterThanOrEqual(cx + half)
+  })
+
+  it('draws nothing for an unkeyframed item', () => {
+    const r = recordingContext()
+    drawKeyframeStrip(r.ctx, clip({ id: 'o1', type: 'overlay', src: undefined, start: 2, end: 4 }), BODY, vp)
+    expect(r.calls).toHaveLength(0)
+  })
+
+  it('draws nothing into a zero-width body', () => {
+    const r = recordingContext()
+    drawKeyframeStrip(r.ctx, keyframedOverlay(), { ...BODY, width: 0 }, vp)
+    expect(r.calls).toHaveLength(0)
+  })
+})
+
+/**
+ * The i-th fade envelope's curve `lineTo` calls (0-based: fade-in is drawn
+ * before fade-out when both are set — see `drawAudioItem`'s own call order).
+ * Each curve is exactly `FADE_ENVELOPE_SEGMENTS` `lineTo` calls (one
+ * `moveTo` plus `FADE_ENVELOPE_SEGMENTS` `lineTo`s), and nothing else on a
+ * bar calls `lineTo` before them — the bar body is `arcTo`, the tint band is
+ * `fillRect`, and the fade grips (which DO use `lineTo`) are always drawn
+ * after every envelope — so a fixed-size slice from the FRONT of `lineTo`
+ * calls is exact regardless of what (if anything) is drawn afterward.
+ */
+function envelopeCurveLineTos(r: Recorder, index = 0): number[][] {
+  const lines = r.of('lineTo').map(c => c.args as number[])
+  return lines.slice(index * FADE_ENVELOPE_SEGMENTS, (index + 1) * FADE_ENVELOPE_SEGMENTS)
+}
+
+describe('drawAudioItem', () => {
+  it('fills emerald, labels the bar, and rings it when selected', () => {
+    const r = recordingContext()
+    drawAudioItem(r.ctx, { rect: { x: 10, y: 4, width: 300, height: 32 }, selected: true, muted: false, label: 'Voiceover' })
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.audioFill)).toBe(true)
+    expect(r.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === TIMELINE_COLORS.audioRing)).toBe(true)
+    // Indented past the in-handle: a selected bar grows a 6px pill on each
+    // end, and a label starting under one would lose its first glyph.
+    expect(r.of('fillText')[0].args).toEqual(['Voiceover', 16 + AUDIO_HANDLE_WIDTH_PX, 20])
+  })
+
+  it('leaves its handles to the lane painter too', () => {
+    const r = recordingContext()
+    drawAudioItem(r.ctx, { rect: { x: 0, y: 0, width: 300, height: 32 }, selected: true, muted: false, label: '' })
+    expect(r.of('set:fillStyle').some(c => c.args[0] === TIMELINE_COLORS.handleFill)).toBe(false)
+  })
+
+  it('uses the muted fill and drops the border', () => {
+    const r = recordingContext()
+    drawAudioItem(r.ctx, { rect: { x: 0, y: 0, width: 200, height: 32 }, selected: false, muted: true, label: 'Music' })
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.audioMutedFill)).toBe(true)
+    expect(r.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === TIMELINE_COLORS.audioBorder)).toBe(false)
+  })
+
+  it('tints the WHOLE fade-width band, full height, both sides of the curve — clamped to the bar', () => {
+    const r = recordingContext()
+    drawAudioItem(r.ctx, {
+      rect: { x: 100, y: 0, width: 200, height: 32 },
+      selected: false, muted: false, label: 'Music',
+      fadeInPx: 40, fadeOutPx: 5000, // fade-out longer than the bar
+    })
+    expect(r.count('quadraticCurveTo')).toBe(0)
+    // The tint is a plain full-height rect — NOT a curve-bounded wedge —
+    // spanning the fade's own width. Fade-in: [spanX, spanX+w] = [100, 140].
+    const fills = r.of('fillRect').map(c => c.args as number[])
+    expect(fills).toContainEqual([100, 0, 40, 32])
+    // Fade-out, clamped to the bar's own 200px width, not the requested
+    // 5000: the fade eats the whole bar, so its band is the full [100, 300).
+    expect(fills).toContainEqual([100, 0, 200, 32])
+    const dimFills = r.calls.filter(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.fadeEnvelopeDim)
+    expect(dimFills).toHaveLength(2)
+
+    // The curve itself still traces the fade's own full-volume corner.
+    const fadeInCurve = envelopeCurveLineTos(r, 0)
+    expect(fadeInCurve[fadeInCurve.length - 1]).toEqual([140, 0])
+    const fadeOutCurve = envelopeCurveLineTos(r, 1)
+    expect(fadeOutCurve[fadeOutCurve.length - 1]).toEqual([100, 0])
+  })
+
+  it('samples the exp curve by default: y is monotonic and the endpoints are exact', () => {
+    const r = recordingContext()
+    drawAudioItem(r.ctx, {
+      rect: { x: 0, y: 0, width: 200, height: 32 },
+      selected: false, muted: false, label: 'Music',
+      fadeInPx: 100,
+    })
+    // moveTo[0] is the bar body's OWN rounded-rect path (`roundRectPath`,
+    // unrelated to the envelope); moveTo[1] is the curve's own start — the
+    // silent corner.
+    const moves = r.of('moveTo').map(c => c.args as number[])
+    expect(moves[1]).toEqual([0, 32])
+    const curve = envelopeCurveLineTos(r)
+    expect(curve).toHaveLength(FADE_ENVELOPE_SEGMENTS)
+    // Monotonically non-decreasing gain (y decreasing towards 0/top) as x
+    // increases from silent to full — every curve in fade-curve.ts is
+    // monotonic over [0,1].
+    for (let i = 1; i < curve.length; i++) {
+      expect(curve[i][1]).toBeLessThanOrEqual(curve[i - 1][1] + 1e-9)
+    }
+    // Last sample lands exactly at the full-volume corner.
+    expect(curve[curve.length - 1]).toEqual([100, 0])
+  })
+
+  it('anchors the fade to the clip′s TRUE span, not the clamped rect, so it scrolls with the clip', () => {
+    // A clip scrolled off the left edge: the lane painter clamps `rect` to the
+    // visible surface (x:0) for the bar fill and waveform, but hands the fade
+    // its TRUE unclamped span via fadeSpanX/fadeSpanWidth. The envelope and
+    // grips must anchor to the true span — otherwise they stay pinned to the
+    // viewport edge while the clip scrolls under them (the bug this fixes).
+    // The envelope is still clipped to the visible bar; only its anchor moves.
+    const r = recordingContext()
+    drawAudioItem(r.ctx, {
+      rect: { x: 0, y: 0, width: 200, height: 32 },   // clamped visible portion
+      fadeSpanX: -100, fadeSpanWidth: 300,            // TRUE span: left edge off-screen at -100, 300px wide
+      selected: false, muted: false, label: 'Music',
+      fadeInPx: 40, fadeOutPx: 30,
+    })
+    // Fade-in full-volume x = fadeSpanX + fadeInPx = -60 — NOT rect.x + 40 =
+    // 40, where the old clamped-rect anchor wrongly pinned it on screen.
+    const fadeInCurve = envelopeCurveLineTos(r, 0)
+    expect(fadeInCurve[fadeInCurve.length - 1]).toEqual([-60, 0])
+    // Fade-out: silent at the TRUE right edge (fadeSpanX + fadeSpanWidth =
+    // 200), full-volume 30px in from there (170).
+    const fadeOutCurve = envelopeCurveLineTos(r, 1)
+    expect(fadeOutCurve[fadeOutCurve.length - 1]).toEqual([170, 0])
+    // The tint bands anchor to the same true span.
+    const fills = r.of('fillRect').map(c => c.args as number[])
+    expect(fills).toContainEqual([-100, 0, 40, 32])   // fade-in band: [-100, -60)
+    expect(fills).toContainEqual([170, 0, 30, 32])    // fade-out band: [170, 200)
+    // Both grips ride the same true-span anchors.
+    const half = FADE_GRIP_SIZE_PX / 2
+    const [inGrip, outGrip] = r.of('moveTo').map(c => c.args as number[]).slice(-2)
+    expect(inGrip).toEqual([-60 - half, 0])
+    expect(outGrip).toEqual([170 - half, 0])
+  })
+
+  it('draws the requested curve shape — linear is a straight ramp, not exp′s ease', () => {
+    const linear = recordingContext()
+    drawAudioItem(linear.ctx, {
+      rect: { x: 0, y: 0, width: 200, height: 32 },
+      selected: false, muted: false, label: 'x',
+      fadeInPx: 100, fadeInCurve: 'linear',
+    })
+    const exp = recordingContext()
+    drawAudioItem(exp.ctx, {
+      rect: { x: 0, y: 0, width: 200, height: 32 },
+      selected: false, muted: false, label: 'x',
+      fadeInPx: 100, fadeInCurve: 'exp',
+    })
+    // Midpoint (p=0.5) of the curve: linear sits at half the drop, exp (t²)
+    // has barely started dropping — the two curves must disagree.
+    const midOf = (r: Recorder) => {
+      const curve = envelopeCurveLineTos(r)
+      return curve[Math.floor(curve.length / 2) - 1]
+    }
+    expect(midOf(linear)[1]).not.toBeCloseTo(midOf(exp)[1], 1)
+  })
+
+  it('defaults an unset curve to exp', () => {
+    const withDefault = recordingContext()
+    drawAudioItem(withDefault.ctx, {
+      rect: { x: 0, y: 0, width: 200, height: 32 },
+      selected: false, muted: false, label: 'x',
+      fadeInPx: 100,
+    })
+    const explicit = recordingContext()
+    drawAudioItem(explicit.ctx, {
+      rect: { x: 0, y: 0, width: 200, height: 32 },
+      selected: false, muted: false, label: 'x',
+      fadeInPx: 100, fadeInCurve: 'exp',
+    })
+    expect(withDefault.calls).toEqual(explicit.calls)
+  })
+})
+
+describe('drawAudioItem fade grips', () => {
+  it('draws both grips at the bar′s own corners when no fade is set, in the SUBTLE style', () => {
+    const r = recordingContext()
+    drawAudioItem(r.ctx, { rect: { x: 100, y: 0, width: 200, height: 32 }, selected: false, muted: false, label: 'x' })
+    // No fade → no envelope curves → the fill/border path's own moveTo (0)
+    // is immediately followed by the two grips (1, 2).
+    const gripMoves = r.of('moveTo').map(c => c.args as number[])
+    const half = FADE_GRIP_SIZE_PX / 2
+    expect(gripMoves[1]).toEqual([100 - half, 0])   // in-grip at the LEFT corner
+    expect(gripMoves[2]).toEqual([300 - half, 0])   // out-grip at the RIGHT corner
+    const gripFills = r.calls.filter(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.fadeGripSubtle)
+    expect(gripFills).toHaveLength(2)
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.fadeGripActive)).toBe(false)
+  })
+
+  it('moves a grip to the fade′s INNER edge once a fade is set, not the corner', () => {
+    const r = recordingContext()
+    drawAudioItem(r.ctx, {
+      rect: { x: 100, y: 0, width: 200, height: 32 }, selected: false, muted: false, label: 'x',
+      fadeInPx: 40, fadeOutPx: 30,
+    })
+    // Envelope curves add their own moveTo calls ahead of the grips'; pick
+    // the grips off the END rather than counting in, so this stays correct
+    // regardless of how many moveTo calls `drawFadeEnvelope` itself makes.
+    const half = FADE_GRIP_SIZE_PX / 2
+    const [inGrip, outGrip] = r.of('moveTo').map(c => c.args as number[]).slice(-2)
+    expect(inGrip).toEqual([140 - half, 0])   // rect.x + fadeInPx
+    expect(outGrip).toEqual([270 - half, 0])  // rect.x + rect.width - fadeOutPx
+  })
+
+  it('brightens BOTH grips when the bar is selected', () => {
+    const r = recordingContext()
+    drawAudioItem(r.ctx, { rect: { x: 0, y: 0, width: 200, height: 32 }, selected: true, muted: false, label: 'x' })
+    const gripFills = r.calls.filter(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.fadeGripActive)
+    expect(gripFills).toHaveLength(2)
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.fadeGripSubtle)).toBe(false)
+  })
+
+  it('brightens only the HOVERED grip, leaving the other side subtle', () => {
+    const r = recordingContext()
+    drawAudioItem(r.ctx, {
+      rect: { x: 0, y: 0, width: 200, height: 32 }, selected: false, muted: false, label: 'x',
+      hoveredFadeSide: 'in',
+    })
+    const gripStyles = r.calls
+      .filter(c => c.method === 'set:fillStyle' && (c.args[0] === TIMELINE_COLORS.fadeGripActive || c.args[0] === TIMELINE_COLORS.fadeGripSubtle))
+      .map(c => c.args[0])
+    // In-grip drawn first, out-grip second (see `drawAudioItem`'s own order).
+    expect(gripStyles).toEqual([TIMELINE_COLORS.fadeGripActive, TIMELINE_COLORS.fadeGripSubtle])
+  })
+
+  it('skips both grips on a bar too narrow for them', () => {
+    const r = recordingContext()
+    drawAudioItem(r.ctx, { rect: { x: 0, y: 0, width: FADE_GRIP_SIZE_PX * 2 - 1, height: 32 }, selected: false, muted: false, label: '' })
+    expect(r.calls.some(c =>
+      c.method === 'set:fillStyle' && (c.args[0] === TIMELINE_COLORS.fadeGripActive || c.args[0] === TIMELINE_COLORS.fadeGripSubtle),
+    )).toBe(false)
+  })
+})
+
+describe('drawCaptionBlock', () => {
+  it('fills and borders in the unselected caption color, and centres the label', () => {
+    const r = recordingContext()
+    drawCaptionBlock(r.ctx, { rect: { x: 10, y: 4, width: 200, height: 32 }, selected: false, label: 'hello' })
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === CAPTION_PALETTE.fill)).toBe(true)
+    expect(r.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === CAPTION_PALETTE.border)).toBe(true)
+    // Vertically centred (no frames/waveform split to clear, unlike a clip),
+    // clipped and unindented since nothing is selected.
+    expect(r.of('fillText')[0].args).toEqual(['hello', 10 + LABEL_PAD_PX, 4 + 16])
+  })
+
+  it('swaps fill AND border-for-ring on selection, mirroring the retired DOM row', () => {
+    const r = recordingContext()
+    drawCaptionBlock(r.ctx, { rect: { x: 0, y: 0, width: 200, height: 32 }, selected: true, label: 'x' })
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === CAPTION_PALETTE.fillSelected)).toBe(true)
+    expect(r.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === CAPTION_PALETTE.ring)).toBe(true)
+    // Mutually exclusive with the unselected border — the DOM classes were
+    // never both at once.
+    expect(r.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === CAPTION_PALETTE.border)).toBe(false)
+  })
+
+  it('indents a selected block\'s label past its handle', () => {
+    const free = recordingContext()
+    drawCaptionBlock(free.ctx, { rect: { x: 0, y: 0, width: 200, height: 32 }, selected: false, label: 'title' })
+    const picked = recordingContext()
+    drawCaptionBlock(picked.ctx, { rect: { x: 0, y: 0, width: 200, height: 32 }, selected: true, label: 'title' })
+    expect(Number(picked.of('fillText')[0].args[1]) - Number(free.of('fillText')[0].args[1]))
+      .toBe(AUDIO_HANDLE_WIDTH_PX)
+  })
+
+  it('leaves the handles to the row painter, like drawAudioItem', () => {
+    const r = recordingContext()
+    drawCaptionBlock(r.ctx, { rect: { x: 0, y: 0, width: 200, height: 32 }, selected: true, label: '' })
+    expect(r.of('set:fillStyle').some(c => c.args[0] === TIMELINE_COLORS.handleFill)).toBe(false)
+  })
+
+  it('skips the label on a block too narrow to read it', () => {
+    const r = recordingContext()
+    drawCaptionBlock(r.ctx, { rect: { x: 0, y: 0, width: MIN_LABEL_WIDTH_PX - 1, height: 32 }, selected: false, label: 'hello' })
+    expect(r.count('fillText')).toBe(0)
+  })
+
+  it('draws nothing for a zero-width rect', () => {
+    const r = recordingContext()
+    drawCaptionBlock(r.ctx, { rect: { x: 0, y: 0, width: 0, height: 32 }, selected: false, label: 'x' })
+    expect(r.calls).toHaveLength(0)
+  })
+})
+
+describe('drawPlayhead', () => {
+  it('centres the playhead on its time', () => {
+    const r = recordingContext()
+    drawPlayhead(r.ctx, 400, 0, 160)
+    expect(r.of('fillRect')[0].args).toEqual([400 - PLAYHEAD_WIDTH_PX / 2, 0, PLAYHEAD_WIDTH_PX, 160])
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.playhead)).toBe(true)
+  })
+})
+
+// ── Scene composition ────────────────────────────────────────────────────
+
+describe('drawSnapGuide', () => {
+  it('centres the line on its x and points both caps inward', () => {
+    const r = recordingContext()
+    drawSnapGuide(r.ctx, 300, 0, 120)
+    expect(r.of('fillRect')[0].args).toEqual([300 - SNAP_GUIDE_WIDTH_PX / 2, 0, SNAP_GUIDE_WIDTH_PX, 120])
+    // Each cap's apex sits INSIDE the span — an arrowhead aimed at the
+    // boundary, not away from it.
+    const apexes = r.of('lineTo').filter((_, i) => i % 2 === 1).map(c => c.args)
+    expect(apexes).toEqual([[300, 7], [300, 113]])
+  })
+})
+
+describe('drawItemHandles', () => {
+  it('draws one handle on each end', () => {
+    const r = recordingContext()
+    drawItemHandles(r.ctx, { x: 0, y: 0, width: 200, height: 40 }, CLIP_HANDLE_WIDTH_PX)
+    expect(r.of('set:fillStyle').filter(c => c.args[0] === TIMELINE_COLORS.handleFill)).toHaveLength(2)
+  })
+
+  it('lights only the handle the pointer is on', () => {
+    const r = recordingContext()
+    drawItemHandles(r.ctx, { x: 0, y: 0, width: 200, height: 40 }, CLIP_HANDLE_WIDTH_PX, 'out')
+    const fills = r.of('set:fillStyle').map(c => c.args[0])
+    expect(fills.filter(f => f === TIMELINE_COLORS.handleFill)).toHaveLength(1)
+    expect(fills.filter(f => f === TIMELINE_COLORS.handleFillHovered)).toHaveLength(1)
+  })
+})
+
+describe('overlapBands', () => {
+  it('returns the intersection of each overlapping consecutive pair', () => {
+    expect(overlapBands([{ start: 0, end: 5 }, { start: 4, end: 9 }])).toEqual([{ start: 4, end: 5 }])
+  })
+
+  it('sorts by start first, so array order cannot hide an overlap', () => {
+    expect(overlapBands([{ start: 4, end: 9 }, { start: 0, end: 5 }])).toEqual([{ start: 4, end: 5 }])
+  })
+
+  it('clamps to the shorter item when one is contained in the other', () => {
+    expect(overlapBands([{ start: 0, end: 9 }, { start: 2, end: 4 }])).toEqual([{ start: 2, end: 4 }])
+  })
+
+  it('ignores items that only touch, and gaps', () => {
+    expect(overlapBands([{ start: 0, end: 5 }, { start: 5, end: 9 }])).toEqual([])
+    expect(overlapBands([{ start: 0, end: 4 }, { start: 5, end: 9 }])).toEqual([])
+  })
+
+  it('finds every overlap in a run, not just the first', () => {
+    expect(overlapBands([{ start: 0, end: 3 }, { start: 2, end: 6 }, { start: 5, end: 8 }]))
+      .toEqual([{ start: 2, end: 3 }, { start: 5, end: 6 }])
+  })
+
+  it('has nothing to say about zero or one item', () => {
+    expect(overlapBands([])).toEqual([])
+    expect(overlapBands([{ start: 0, end: 5 }])).toEqual([])
+  })
+})
+
+describe('drawOverlapBand', () => {
+  it('does not share a literal with the muted-audio fill', () => {
+    // Both are near-transparent white. If they ever converge, a muted bar and
+    // an overlap band become indistinguishable by colour, and every test that
+    // keys on one of them starts matching the other.
+    expect(TIMELINE_COLORS.overlapFill).not.toBe(TIMELINE_COLORS.audioMutedFill)
+  })
+
+  it('washes, hatches and rules both edges', () => {
+    const r = recordingContext()
+    drawOverlapBand(r.ctx, { x: 100, y: 0, width: 60, height: 40 })
+    const fills = r.of('set:fillStyle').map(c => c.args[0])
+    expect(fills).toEqual([TIMELINE_COLORS.overlapFill, TIMELINE_COLORS.overlapEdge])
+    // The wash, then a hard rule down each side.
+    const rects = r.of('fillRect').map(c => c.args)
+    expect(rects[0]).toEqual([100, 0, 60, 40])
+    expect(rects[1]).toEqual([100, 0, OVERLAP_EDGE_WIDTH_PX, 40])
+    expect(rects[2]).toEqual([100 + 60 - OVERLAP_EDGE_WIDTH_PX, 0, OVERLAP_EDGE_WIDTH_PX, 40])
+    // The hatch is stroked twice off one path: a wide dark pass, then amber
+    // inside it, so it reads over a bright frame and a dark one alike.
+    expect(r.of('set:strokeStyle').map(c => c.args[0])).toEqual([
+      TIMELINE_COLORS.overlapHatchShadow,
+      TIMELINE_COLORS.overlapHatch,
+    ])
+    expect(r.of('set:lineWidth').map(c => c.args[0])).toEqual([
+      OVERLAP_HATCH_SHADOW_WIDTH_PX,
+      OVERLAP_HATCH_WIDTH_PX,
+    ])
+    expect(r.count('stroke')).toBe(2)
+    expect(r.count('beginPath')).toBe(2)   // the clip rect, then the one hatch path
+  })
+
+  it('clips the hatching so the diagonals stop at the band', () => {
+    const r = recordingContext()
+    drawOverlapBand(r.ctx, { x: 100, y: 0, width: 60, height: 40 })
+    const clipAt = r.calls.findIndex(c => c.method === 'clip')
+    const strokeAt = r.calls.findIndex(c => c.method === 'stroke')
+    expect(clipAt).toBeGreaterThanOrEqual(0)
+    expect(clipAt).toBeLessThan(strokeAt)
+    // …and the edges are painted after the clip is released, so they stay full
+    // weight right up to the band's boundary.
+    expect(r.calls.findIndex(c => c.method === 'restore')).toBeLessThan(
+      r.calls.map(c => c.method === 'set:fillStyle' ? c.args[0] : null).indexOf(TIMELINE_COLORS.overlapEdge),
+    )
+  })
+
+  it('leans its hatching one way, evenly spaced', () => {
+    const r = recordingContext()
+    drawOverlapBand(r.ctx, { x: 0, y: 0, width: 18, height: 10 })
+    // Bottom-left to top-right, every OVERLAP_HATCH_SPACING_PX across a span
+    // of width + height.
+    expect(r.of('moveTo').map(c => c.args)).toEqual([[0, 10], [9, 10], [18, 10], [27, 10]])
+    expect(r.of('lineTo').map(c => c.args)).toEqual([[-10, 0], [-1, 0], [8, 0], [17, 0]])
+  })
+
+  it('never lets the two edge rules cross on a hairline overlap', () => {
+    const r = recordingContext()
+    drawOverlapBand(r.ctx, { x: 100, y: 0, width: 3, height: 40 })
+    const rects = r.of('fillRect').map(c => c.args as number[])
+    expect(rects[1][2]).toBe(1.5)
+    expect(rects[2][0]).toBe(101.5)
+  })
+
+  it('draws nothing for an empty band', () => {
+    const r = recordingContext()
+    drawOverlapBand(r.ctx, { x: 10, y: 0, width: 0, height: 40 })
+    expect(r.calls).toHaveLength(0)
+  })
+})
+
+describe('drawSnapGuide — weak', () => {
+  it('draws a capless hairline for a cross-track boundary', () => {
+    const r = recordingContext()
+    drawSnapGuide(r.ctx, 300, 0, 120, 'weak')
+    expect(r.of('fillRect')[0].args).toEqual([300 - SNAP_GUIDE_WEAK_WIDTH_PX / 2, 0, SNAP_GUIDE_WEAK_WIDTH_PX, 120])
+    expect(r.of('set:fillStyle')[0].args[0]).toBe(TIMELINE_COLORS.snapGuideWeak)
+    // No arrowheads: the caps are what make the strong guide shout, and this
+    // one is meant to be barely there.
+    expect(r.count('closePath')).toBe(0)
+  })
+
+  it('is thinner than the strong guide it sits alongside', () => {
+    expect(SNAP_GUIDE_WEAK_WIDTH_PX).toBeLessThan(SNAP_GUIDE_WIDTH_PX)
+  })
+})
+
+describe('drawRowBackground — panel + divider', () => {
+  it('fills the row and strokes a rowDivider outline as the track divider', () => {
+    const r = recordingContext()
+    drawRowBackground(r.ctx, { x: 0, y: 10, width: 200, height: 40 })
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.rowBackground)).toBe(true)
+    expect(r.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === TIMELINE_COLORS.rowDivider)).toBe(true)
+    const strokes = r.of('strokeRect')
+    expect(strokes).toHaveLength(1)
+    expect(strokes[0].args).toEqual([0.5, 10.5, 199, 39])
+  })
+
+  it('paints the alternate shade when one is passed, so adjacent lanes differ', () => {
+    const r = recordingContext()
+    drawRowBackground(r.ctx, { x: 0, y: 0, width: 100, height: 20 }, TIMELINE_COLORS.rowBackgroundAlt)
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.rowBackgroundAlt)).toBe(true)
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.rowBackground)).toBe(false)
+  })
+})
+
+describe('drawTimelineContent', () => {
+  it('places clips from the viewport, not from a percentage of the project', () => {
+    const p = project({ tracks: [[clip({ id: 'c0', start: 10, end: 14 })]] } as unknown as Partial<Project>)
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({
+      project: p,
+      layout: computeTimelineLayout(p),
+      viewport: viewport({ pxPerSecond: 25, scrollSeconds: 8 }),
+    }))
+
+    // (10 - 8) * 25 = 50px from the left, 4s * 25 = 100px wide — then inset by
+    // the gutter each side, which is paint only and does not move the clip in time.
+    // Located by its width rather than by call order: the ruler and the row
+    // background both fillRect before the clip does.
+    const rowY = computeTimelineLayout(p).rows[0].y
+    const clipFill = r.of('fillRect').find(c => c.args[2] === 100 - CLIP_GUTTER_PX * 2)
+    expect(clipFill?.args).toEqual([50 + CLIP_GUTTER_PX, rowY, 100 - CLIP_GUTTER_PX * 2, BASE_VISUAL_ROW_RENDER_HEIGHT_PX])
+  })
+
+  it('insets audio bars inside their lane, left/right AND top/bottom', () => {
+    const p = project({ audio: { tracks: [audio({ start: 0, end: 4 })] } } as unknown as Partial<Project>)
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), viewport: viewport({ pxPerSecond: 20 }) }))
+
+    // Audio bars are rounded, so their box is a path, not a fillRect: the lane
+    // background's path comes first, the bar's second, inset top and bottom
+    // by AUDIO_ITEM_INSET_PX, AND left/right by CLIP_GUTTER_PX — the same
+    // horizontal gutter a video clip gets, so two touching audio bars show
+    // the same uniform gap two touching video clips do.
+    const barHeight = AUDIO_LANE_HEIGHT_PX - AUDIO_ITEM_INSET_PX * 2
+    // Lane y, not 0: the ruler owns the top of the surface and everything below
+    // it is offset by that strip.
+    const barTop = computeTimelineLayout(p).lanes[0].y + AUDIO_ITEM_INSET_PX
+    // 4s @ 20px/s = 80px span, inset by CLIP_GUTTER_PX on each side.
+    const barLeft = CLIP_GUTTER_PX
+    const barRight = 80 - CLIP_GUTTER_PX
+    expect(r.of('moveTo')[1].args).toEqual([barLeft + 4, barTop])
+    expect(r.of('arcTo').some(c =>
+      JSON.stringify(c.args) === JSON.stringify([barRight, barTop, barRight, barTop + barHeight, 4]),
+    )).toBe(true)
+    // By content, not by index — the ruler's own tick labels are fillText too.
+    const barLabel = r.of('fillText').find(c => c.args[0] === 'voice.mp3')
+    expect(barLabel?.args).toEqual(['voice.mp3', barLeft + 6, barTop + barHeight / 2])
+  })
+
+  it('gives two butted audio bars the same uniform CLIP_GUTTER_PX gap two butted video clips get, not a seamless touch', () => {
+    const p = project({
+      audio: {
+        tracks: [
+          audio({ id: 'a', start: 0, end: 5, lane: 0 }),
+          audio({ id: 'b', start: 5, end: 9, lane: 0 }), // butted to `a` — no gap in time
+        ],
+      },
+    } as unknown as Partial<Project>)
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), viewport: viewport({ pxPerSecond: 10 }) }))
+
+    // Path order: the lane background's own roundRectPath moves first (1);
+    // then each bar's OWN fill path (1 moveTo, unselected/unmuted — fill and
+    // border share the one path), followed by its two fade-grip triangles
+    // (1 moveTo apiece, drawn on every bar regardless of selection — see
+    // `drawFadeGrip`). So track `a` is index 1, and track `b`'s fill-path
+    // moveTo is index 1 + (1 fill + 2 grips) = 4, not a plain "next index".
+    const moveTos = r.of('moveTo').map(c => c.args as number[])
+    const aMoveTo = moveTos[1]
+    const bMoveTo = moveTos[4]
+    const aLeft = aMoveTo[0] - AUDIO_ITEM_RADIUS_PX
+    const bLeft = bMoveTo[0] - AUDIO_ITEM_RADIUS_PX
+    // `a` spans [0,5) → raw x 0; `b` starts immediately after at raw x 50
+    // (5s × 10px/s). Each bar's drawn left edge sits CLIP_GUTTER_PX in from
+    // its raw span start — the identical inset a video clip's `clipBodyRect`
+    // applies — so the two bars show a uniform 2×CLIP_GUTTER_PX gap rather
+    // than touching.
+    expect(aLeft).toBe(CLIP_GUTTER_PX)
+    expect(bLeft).toBe(50 + CLIP_GUTTER_PX)
+  })
+
+  it('marks the overlap between two audio bars as a crossfade band', () => {
+    const p = project({
+      audio: { tracks: [audio({ id: 'a', start: 0, end: 5, lane: 0 }), audio({ id: 'b', start: 4, end: 9, lane: 0 })] },
+    } as unknown as Partial<Project>)
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), viewport: viewport({ pxPerSecond: 10 }) }))
+    expect(r.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === TIMELINE_COLORS.overlapHatch)).toBe(true)
+  })
+
+  it('leaves a muted bar out of the pairing — it is crossfading with nothing', () => {
+    const p = project({
+      audio: { tracks: [audio({ id: 'a', start: 0, end: 5, lane: 0 }), audio({ id: 'b', start: 4, end: 9, lane: 0, muted: true })] },
+    } as unknown as Partial<Project>)
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), viewport: viewport({ pxPerSecond: 10 }) }))
+    expect(r.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === TIMELINE_COLORS.overlapHatch)).toBe(false)
+  })
+
+  // ── Overlaps on a VISUAL row: previously not marked at all ──
+
+  it('marks two overlapping clips on a video track', () => {
+    // The bug this fixes: within a track the later clip simply wins, so this
+    // span is one second of clip `a` that will never be seen — and the only
+    // sign of it was the clip band's wash landing twice.
+    const p = project({ tracks: [[clip({ id: 'a', start: 0, end: 5 }), clip({ id: 'b', start: 4, end: 9 })]] } as unknown as Partial<Project>)
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), viewport: viewport({ pxPerSecond: 10 }) }))
+    expect(r.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === TIMELINE_COLORS.overlapHatch)).toBe(true)
+  })
+
+  it('draws no band for clips that merely touch', () => {
+    // Butted-up clips are the normal case and must stay unmarked, or every
+    // cut on the timeline would be hatched.
+    const p = project({ tracks: [[clip({ id: 'a', start: 0, end: 5 }), clip({ id: 'b', start: 5, end: 9 })]] } as unknown as Partial<Project>)
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), viewport: viewport({ pxPerSecond: 10 }) }))
+    expect(r.calls.some(c => c.method === 'set:strokeStyle' && c.args[0] === TIMELINE_COLORS.overlapHatch)).toBe(false)
+  })
+
+  it('draws the band over the clips it spans, not under them', () => {
+    const p = project({ tracks: [[clip({ id: 'a', start: 0, end: 5 }), clip({ id: 'b', start: 4, end: 9 })]] } as unknown as Partial<Project>)
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), viewport: viewport({ pxPerSecond: 10 }) }))
+    const lastClipFill = r.calls.map(c => c.method === 'set:fillStyle' ? c.args[0] : null).lastIndexOf(TRACK_PALETTE[0].fill)
+    const bandAt = r.calls.findIndex(c => c.method === 'set:strokeStyle' && c.args[0] === TIMELINE_COLORS.overlapHatch)
+    expect(bandAt).toBeGreaterThan(lastClipFill)
+  })
+
+  it('draws a selected clip\'s handles after every clip in the row', () => {
+    // The bug: clip `b` overlaps the end of the selected clip `a`, so painting
+    // handles in stacking order buried a's out handle under b. You could see
+    // the clip was selected and had no way to see — or reach — its trailing
+    // edge.
+    const p = project({ tracks: [[clip({ id: 'a', start: 0, end: 5 }), clip({ id: 'b', start: 4, end: 9 })]] } as unknown as Partial<Project>)
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), selectedIds: ['a'], viewport: viewport({ pxPerSecond: 30 }) }))
+
+    const handleAt = r.calls.map(c => c.method === 'set:fillStyle' ? c.args[0] : null).lastIndexOf(TIMELINE_COLORS.handleFill)
+    const lastClipFill = r.calls.map(c => c.method === 'set:fillStyle' ? c.args[0] : null).lastIndexOf(TRACK_PALETTE[0].fill)
+    expect(handleAt).toBeGreaterThan(lastClipFill)
+    // …and over the overlap hatching as well, since the handle is the control.
+    const bandAt = r.calls.findIndex(c => c.method === 'set:strokeStyle' && c.args[0] === TIMELINE_COLORS.overlapHatch)
+    expect(handleAt).toBeGreaterThan(bandAt)
+  })
+
+  it('never draws the playhead — that is the overlay layer', () => {
+    const p = project({ tracks: [[clip({ start: 0, end: 5 })]] } as unknown as Partial<Project>)
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p) }))
+    expect(r.calls.some(c => c.method === 'set:fillStyle' && c.args[0] === TIMELINE_COLORS.playhead)).toBe(false)
+  })
+
+  it('clears before it paints', () => {
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene())
+    expect(r.calls[0]).toEqual({ method: 'clearRect', args: [0, 0, 1000, 200] })
+  })
+
+  // ── Captions (Phase 1: display only) ──
+
+  describe('the caption band', () => {
+    function projectWithCaptions(segments: CaptionSegment[]): Project {
+      return project({
+        tracks: [[clip({ id: 'base', start: 0, end: 20 })]],
+        captions: { style: 'clean', segments },
+      } as unknown as Partial<Project>)
+    }
+
+    it('draws one block per segment', () => {
+      const p = projectWithCaptions([
+        captionSegment({ id: 's0', start: 0, end: 2, text: 'a' }),
+        captionSegment({ id: 's1', start: 2, end: 4, text: 'b' }),
+        captionSegment({ id: 's2', start: 4, end: 6, text: 'c' }),
+      ])
+      const r = recordingContext()
+      const stats = drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p) }))
+      expect(stats.captionItemsDrawn).toBe(3)
+      expect(r.of('set:fillStyle').filter(c => c.args[0] === CAPTION_PALETTE.fill)).toHaveLength(3)
+    })
+
+    it('highlights the block in scene.selectedIds and gives it handles; the others get neither', () => {
+      const p = projectWithCaptions([
+        captionSegment({ id: 's0', start: 0, end: 2, text: 'a' }),
+        captionSegment({ id: 's1', start: 2, end: 4, text: 'b' }),
+      ])
+      const r = recordingContext()
+      // Caption ids live in the SAME unified selectedIds array as clips/audio —
+      // no separate `selectedCaptionId` scene field.
+      drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), selectedIds: ['s1'] }))
+
+      expect(r.of('set:fillStyle').filter(c => c.args[0] === CAPTION_PALETTE.fillSelected)).toHaveLength(1)
+      expect(r.of('set:fillStyle').filter(c => c.args[0] === CAPTION_PALETTE.fill)).toHaveLength(1)
+      expect(r.of('set:strokeStyle').filter(c => c.args[0] === CAPTION_PALETTE.ring)).toHaveLength(1)
+      // Exactly one block's worth of handles (2 pills: in + out).
+      expect(r.of('set:fillStyle').filter(c => c.args[0] === TIMELINE_COLORS.handleFill)).toHaveLength(2)
+    })
+
+    it('honors hoveredHandle for the selected caption', () => {
+      const p = projectWithCaptions([captionSegment({ id: 's0', start: 0, end: 2, text: 'a' })])
+      const r = recordingContext()
+      drawTimelineContent(r.ctx, scene({
+        project: p,
+        layout: computeTimelineLayout(p),
+        selectedIds: ['s0'],
+        hoveredHandle: { itemId: 's0', edge: 'out' },
+      }))
+      expect(r.of('set:fillStyle').some(c => c.args[0] === TIMELINE_COLORS.handleFillHovered)).toBe(true)
+    })
+
+    it('culls segments outside the visible range', () => {
+      const p = projectWithCaptions([
+        captionSegment({ id: 's0', start: 0, end: 2, text: 'a' }),
+        captionSegment({ id: 's1', start: 500, end: 502, text: 'far away' }),
+      ])
+      const r = recordingContext()
+      const stats = drawTimelineContent(r.ctx, scene({
+        project: p, layout: computeTimelineLayout(p), viewport: viewport({ pxPerSecond: 10 }),
+      }))
+      expect(stats.captionItemsDrawn).toBe(1)
+      expect(stats.itemsCulled).toBeGreaterThanOrEqual(1)
+    })
+
+    it('draws an id-less segment (before backfillCaptionIds runs) but never selects it', () => {
+      const p = projectWithCaptions([{ text: 'no id yet', start: 0, end: 2 } as CaptionSegment])
+      const r = recordingContext()
+      const stats = drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p) }))
+      expect(stats.captionItemsDrawn).toBe(1)
+      expect(r.of('set:fillStyle').some(c => c.args[0] === CAPTION_PALETTE.fillSelected)).toBe(false)
+    })
+
+    it('is a no-op on a project with no captions', () => {
+      const p = project({ tracks: [[clip({ id: 'base' })]] } as unknown as Partial<Project>)
+      const r = recordingContext()
+      const stats = drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p) }))
+      expect(stats.captionItemsDrawn).toBe(0)
+      expect(r.of('set:fillStyle').some(c => c.args[0] === CAPTION_PALETTE.fill)).toBe(false)
+    })
+
+    // ── N bands (Phase 3) ──
+
+    it('paints every band\'s background, including a hole lane that draws no blocks', () => {
+      const p = projectWithCaptions([
+        captionSegment({ id: 's0', lane: 0, start: 0, end: 2, text: 'a' }),
+        captionSegment({ id: 's2', lane: 2, start: 4, end: 6, text: 'c' }),
+        // Lane 1 is a hole — no segment sits there, but it still gets a band.
+      ])
+      const layout = computeTimelineLayout(p)
+      expect(layout.captions).toHaveLength(3)
+      const holeBand = layout.captions!.find(c => c.lane === 1)!
+      expect(holeBand.segments).toEqual([])
+
+      const r = recordingContext()
+      const stats = drawTimelineContent(r.ctx, scene({ project: p, layout, viewport: viewport({ pxPerSecond: 10 }) }))
+
+      // Two real segments drawn; the hole lane draws none.
+      expect(stats.captionItemsDrawn).toBe(2)
+      // Its background is still painted. `drawRowBackground`'s `roundRectPath`
+      // opens with `moveTo(x + radius, y)`, so finding that call at the hole
+      // band's own y proves the fill pass ran for it despite the empty
+      // segment list — this is what stops the timeline jumping by a whole
+      // row height mid-drag when a caption moves out of a lane that was
+      // otherwise alone.
+      expect(r.of('moveTo').some(c => c.args[0] === ROW_RADIUS_PX && c.args[1] === holeBand.y)).toBe(true)
+    })
+  })
+
+  describe('the keyframe strip (SP9b T3.3)', () => {
+    function keyframedOverlay(over: Partial<VisualItem> = {}): VisualItem {
+      return clip({
+        id: 'o0', type: 'overlay', src: undefined, start: 2, end: 4,
+        keyframes: [{ prop: 'offsetX', points: [{ t: 0.5, value: 0 }] }],
+        ...over,
+      } as unknown as Partial<VisualItem>)
+    }
+
+    it('draws diamonds for a selected, keyframed overlay', () => {
+      const p = project({ tracks: [[keyframedOverlay()]] } as unknown as Partial<Project>)
+      const r = recordingContext()
+      drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), selectedIds: ['o0'] }))
+      expect(r.of('set:fillStyle').some(c => c.args[0] === TIMELINE_COLORS.keyframeDiamondFill)).toBe(true)
+    })
+
+    it('draws nothing when the overlay is not selected', () => {
+      const p = project({ tracks: [[keyframedOverlay()]] } as unknown as Partial<Project>)
+      const r = recordingContext()
+      drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), selectedIds: [] }))
+      expect(r.of('set:fillStyle').some(c => c.args[0] === TIMELINE_COLORS.keyframeDiamondFill)).toBe(false)
+    })
+
+    it('draws nothing for a selected overlay with no keyframes', () => {
+      const p = project({ tracks: [[clip({ id: 'o0', type: 'overlay', src: undefined, start: 2, end: 4 })]] } as unknown as Partial<Project>)
+      const r = recordingContext()
+      drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), selectedIds: ['o0'] }))
+      expect(r.of('set:fillStyle').some(c => c.args[0] === TIMELINE_COLORS.keyframeDiamondFill)).toBe(false)
+    })
+
+    it('DRAWS the strip for a selected, keyframed video clip (SP9d)', () => {
+      // Clips became keyframeable when the renderer learned to compile curves
+      // into ffmpeg expressions, so the strip has to show up for them too — a
+      // keyframe you cannot see is a keyframe you cannot drag or delete.
+      const p = project({ tracks: [[keyframedOverlay({ type: 'video' })]] } as unknown as Partial<Project>)
+      const r = recordingContext()
+      drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), selectedIds: ['o0'] }))
+      expect(r.of('set:fillStyle').some(c => c.args[0] === TIMELINE_COLORS.keyframeDiamondFill)).toBe(true)
+    })
+
+    it('still draws nothing for a selected, keyframed item of a NON-visual kind', () => {
+      // The gate must stay a gate — `canKeyframe`, not `isKeyframed` alone.
+      const p = project({ tracks: [[keyframedOverlay({ type: 'audio' } as unknown as Partial<VisualItem>)]] } as unknown as Partial<Project>)
+      const r = recordingContext()
+      drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p), selectedIds: ['o0'] }))
+      expect(r.of('set:fillStyle').some(c => c.args[0] === TIMELINE_COLORS.keyframeDiamondFill)).toBe(false)
+    })
+
+    it('paints the diamond matching scene.selectedKeyframe differently from the other diamond', () => {
+      const p = project({ tracks: [[keyframedOverlay({
+        keyframes: [{ prop: 'offsetX', points: [{ t: 0, value: 0 }, { t: 1, value: 10 }] }],
+      })]] } as unknown as Partial<Project>)
+      const r = recordingContext()
+      drawTimelineContent(r.ctx, scene({
+        project: p,
+        layout: computeTimelineLayout(p),
+        selectedIds: ['o0'],
+        selectedKeyframe: { itemId: 'o0', t: 1 },
+      }))
+      const fills = r.of('set:fillStyle').map(c => c.args[0])
+      expect(fills).toContain(TIMELINE_COLORS.keyframeDiamondSelectedFill)
+      expect(fills).toContain(TIMELINE_COLORS.keyframeDiamondFill)
+    })
+
+    it('paints both diamonds identically when selectedKeyframe is null', () => {
+      const p = project({ tracks: [[keyframedOverlay({
+        keyframes: [{ prop: 'offsetX', points: [{ t: 0, value: 0 }, { t: 1, value: 10 }] }],
+      })]] } as unknown as Partial<Project>)
+      const r = recordingContext()
+      drawTimelineContent(r.ctx, scene({
+        project: p,
+        layout: computeTimelineLayout(p),
+        selectedIds: ['o0'],
+        selectedKeyframe: null,
+      }))
+      const diamondFills = r.of('set:fillStyle')
+        .map(c => c.args[0])
+        .filter(fill => fill === TIMELINE_COLORS.keyframeDiamondFill || fill === TIMELINE_COLORS.keyframeDiamondSelectedFill)
+      expect(diamondFills).toHaveLength(2)
+      expect(new Set(diamondFills).size).toBe(1)
+    })
+
+    it('paints nothing selected when selectedKeyframe.itemId names a different item', () => {
+      const p = project({ tracks: [[keyframedOverlay({
+        keyframes: [{ prop: 'offsetX', points: [{ t: 0, value: 0 }, { t: 1, value: 10 }] }],
+      })]] } as unknown as Partial<Project>)
+      const r = recordingContext()
+      drawTimelineContent(r.ctx, scene({
+        project: p,
+        layout: computeTimelineLayout(p),
+        selectedIds: ['o0'],
+        selectedKeyframe: { itemId: 'some-other-item', t: 1 },
+      }))
+      const diamondFills = r.of('set:fillStyle')
+        .map(c => c.args[0])
+        .filter(fill => fill === TIMELINE_COLORS.keyframeDiamondFill || fill === TIMELINE_COLORS.keyframeDiamondSelectedFill)
+      expect(diamondFills).toHaveLength(2)
+      expect(new Set(diamondFills).size).toBe(1)
+    })
+  })
+})
+
+describe('drawTimelineOverlay', () => {
+  it('redraws only the playhead, at the viewport position', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 2 }),
+      currentTime: 5,
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    expect(r.count('clearRect')).toBe(1)
+    expect(r.of('fillRect')[0].args).toEqual([120 - PLAYHEAD_WIDTH_PX / 2, 0, PLAYHEAD_WIDTH_PX, 160])
+  })
+
+  it('clears but draws nothing when the playhead is off-screen', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 200 }),
+      currentTime: 5,
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    expect(r.count('clearRect')).toBe(1)
+    expect(r.count('fillRect')).toBe(0)
+  })
+
+  // ── The preview-axis cursor, on the same layer as the playhead ──
+
+  it('draws nothing extra when the axis is off (no cursor time)', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 0 }),
+      currentTime: 5,
+      cursorTime: null,
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    expect(r.count('fillRect')).toBe(1)
+  })
+
+  it('draws the cursor in yellow, before the playhead', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 0 }),
+      currentTime: 5,
+      cursorTime: 2,
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    const rects = r.of('fillRect')
+    expect(rects.length).toBe(2)
+    // Cursor first (2s × 40px/s = 80), so the red playhead wins any overlap.
+    expect(rects[0].args).toEqual([80 - CURSOR_WIDTH_PX / 2, 0, CURSOR_WIDTH_PX, 160])
+    expect(rects[1].args).toEqual([200 - PLAYHEAD_WIDTH_PX / 2, 0, PLAYHEAD_WIDTH_PX, 160])
+    const fills = r.of('set:fillStyle').map(c => c.args[0])
+    expect(fills).toEqual([TIMELINE_COLORS.cursor, TIMELINE_COLORS.playhead])
+  })
+
+  it('culls the cursor when it scrolls off-screen, keeping the playhead', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 0 }),
+      currentTime: 5,
+      cursorTime: 400,
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    expect(r.count('fillRect')).toBe(1)
+    expect(r.of('fillRect')[0].args).toEqual([200 - PLAYHEAD_WIDTH_PX / 2, 0, PLAYHEAD_WIDTH_PX, 160])
+  })
+
+  it('draws the cursor independently of the playhead — the two diverge by design', () => {
+    // This is the whole feature: the pointer is at 3s, playback is still at 0.
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 0 }),
+      currentTime: 0,
+      cursorTime: 3,
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    const rects = r.of('fillRect')
+    expect(rects[0].args[0]).toBe(120 - CURSOR_WIDTH_PX / 2)
+    expect(rects[1].args[0]).toBe(0 - PLAYHEAD_WIDTH_PX / 2)
+  })
+
+  // ── The snap guide: what makes a strong magnet legible ──
+
+  it('draws no guide when no gesture is snapped', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 0 }),
+      currentTime: 5,
+      snapTime: null,
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    expect(r.of('set:fillStyle').some(c => c.args[0] === TIMELINE_COLORS.snapGuide)).toBe(false)
+  })
+
+  it('marks the snapped boundary in cyan, with an arrowhead at each end', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 0 }),
+      currentTime: 5,
+      snapTime: 2,
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    const rects = r.of('fillRect')
+    // Playhead first (5s × 40 = 200), then the guide at 2s × 40 = 80.
+    expect(rects).toHaveLength(2)
+    expect(rects[1].args).toEqual([80 - SNAP_GUIDE_WIDTH_PX / 2, 0, SNAP_GUIDE_WIDTH_PX, 160])
+    // Two triangles — the caps are what stop this reading as a third playhead.
+    expect(r.of('closePath')).toHaveLength(2)
+    expect(r.of('moveTo').map(c => c.args)).toEqual([
+      [80 - SNAP_GUIDE_CAP_HALF_WIDTH_PX, 0],
+      [80 - SNAP_GUIDE_CAP_HALF_WIDTH_PX, 160],
+    ])
+  })
+
+  it('draws the guide LAST, so snapping to the playhead still looks snapped', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 0 }),
+      currentTime: 3,
+      cursorTime: 1,
+      snapTime: 3,
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    expect(r.of('set:fillStyle').map(c => c.args[0])).toEqual([
+      TIMELINE_COLORS.cursor,
+      TIMELINE_COLORS.playhead,
+      TIMELINE_COLORS.snapGuide,
+    ])
+  })
+
+  it('carries the tier through to the painter', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 0 }),
+      currentTime: 5,
+      snapTime: 2,
+      snapStrength: 'weak',
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    expect(r.of('set:fillStyle').map(c => c.args[0])).toEqual([
+      TIMELINE_COLORS.playhead,
+      TIMELINE_COLORS.snapGuideWeak,
+    ])
+  })
+
+  it('culls the guide when it scrolls off-screen', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport({ pxPerSecond: 40, scrollSeconds: 0 }),
+      currentTime: 5,
+      snapTime: 400,
+      surfaceWidth: 1000,
+      surfaceHeight: 160,
+    })
+    expect(r.count('fillRect')).toBe(1)
+  })
+})
+
+// ── Culling: the virtualization acceptance probe ─────────────────────────
+
+describe('draw culling', () => {
+  /** 40 clips over two tracks and 60 audio segments, spanning ~400s. */
+  function bigProject(): Project {
+    const base: VisualItem[] = []
+    const overlays: VisualItem[] = []
+    for (let i = 0; i < 20; i++) {
+      base.push(clip({ id: `base-${i}`, start: i * 20, end: i * 20 + 19 }))
+      overlays.push(clip({ id: `ov-${i}`, type: 'overlay', start: i * 20 + 5, end: i * 20 + 12 }))
+    }
+    const audioTracks: AudioTrack[] = []
+    for (let i = 0; i < 60; i++) {
+      audioTracks.push(audio({ id: `au-${i}`, start: i * 6.5, end: i * 6.5 + 6, lane: i % 2 }))
+    }
+    return project({ tracks: [base, overlays], audio: { tracks: audioTracks } } as unknown as Partial<Project>)
+  }
+
+  it('draws only what intersects the visible window', () => {
+    const p = bigProject()
+    const layout = computeTimelineLayout(p)
+    // 1000px surface at 100 px/s = a 10-second window at t=100.
+    const zoomedIn = scene({ project: p, layout, viewport: viewport({ pxPerSecond: 100, scrollSeconds: 100 }) })
+
+    const r = recordingContext()
+    const stats = drawTimelineContent(r.ctx, zoomedIn)
+
+    const totalItems = 40 + 60
+    const drawn = stats.visualItemsDrawn + stats.audioItemsDrawn
+    expect(drawn + stats.itemsCulled).toBe(totalItems)
+
+    // A 10s window can hold at most 1 base clip + 1 overlay + 2 audio bars per
+    // lane. Bound it generously and still be an order below the project size.
+    expect(drawn).toBeLessThanOrEqual(8)
+    expect(stats.itemsCulled).toBeGreaterThanOrEqual(totalItems - 8)
+
+    // And the draw-call list is bounded by the viewport too — rows, the drawn
+    // items and their labels, nothing per-culled-item.
+    const rowCount = layout.rows.length + layout.lanes.length
+    const base = rulerBaseline(zoomedIn.viewport)
+    expect(r.count('fillText') - base.fillText).toBeLessThanOrEqual(drawn)
+    expect(r.count('fillRect') - base.fillRect).toBeLessThanOrEqual(rowCount + drawn * 4)
+  })
+
+  it('bounds draw calls by viewport size, not project size', () => {
+    const small = bigProject()
+    const huge = project({
+      // Ten times the items over ten times the duration, same visible window.
+      tracks: [Array.from({ length: 400 }, (_, i) => clip({ id: `c-${i}`, start: i * 10, end: i * 10 + 9 }))],
+      audio: { tracks: Array.from({ length: 600 }, (_, i) => audio({ id: `a-${i}`, start: i * 6.5, end: i * 6.5 + 6, lane: i % 2 })) },
+    } as unknown as Partial<Project>)
+
+    const window = { pxPerSecond: 100, scrollSeconds: 100 }
+    const a = recordingContext()
+    drawTimelineContent(a.ctx, scene({ project: small, layout: computeTimelineLayout(small), viewport: viewport(window) }))
+    const b = recordingContext()
+    drawTimelineContent(b.ctx, scene({ project: huge, layout: computeTimelineLayout(huge), viewport: viewport(window) }))
+
+    // 10× the project, the same handful of draw calls (within one row's worth).
+    // The ruler is a fixed cost at a fixed viewport, so it cancels in the
+    // difference and is subtracted from the absolute bound.
+    const base = rulerBaseline(viewport(window))
+    expect(Math.abs(b.calls.length - a.calls.length)).toBeLessThan(60)
+    expect(b.calls.length - base.calls).toBeLessThan(200)
+  })
+
+  it('draws more, but still only what fits, when zoomed out to the whole project', () => {
+    const p = bigProject()
+    const layout = computeTimelineLayout(p)
+    const r = recordingContext()
+    const stats = drawTimelineContent(r.ctx, scene({
+      project: p, layout,
+      viewport: viewport({ pxPerSecond: 2.5, scrollSeconds: 0 }), // 400s across 1000px
+    }))
+    expect(stats.visualItemsDrawn + stats.audioItemsDrawn).toBe(100)
+    expect(stats.itemsCulled).toBe(0)
+  })
+})
+
+describe('skipped tracks', () => {
+  it('marks a disabled track\'s row so the painter dims it', () => {
+    const p = {
+      id: 'p',
+      tracks: [
+        { id: 't0', items: [clip({ id: 'c0' })] },
+        { id: 't1', items: [clip({ id: 'o0', type: 'overlay' })], enabled: false },
+      ],
+    } as unknown as Project
+    const layout = computeTimelineLayout(p)
+    expect(layout.rows.find(r => r.trackIdx === 1)?.disabled).toBe(true)
+    expect(layout.rows.find(r => r.trackIdx === 0)?.disabled).toBe(false)
+  })
+
+  it('marks a muted track\'s row so the painter can gray its clips\' waveforms', () => {
+    const p = {
+      id: 'p',
+      tracks: [
+        { id: 't0', items: [clip({ id: 'c0' })] },
+        { id: 't1', items: [clip({ id: 'o0', type: 'overlay' })], muted: true },
+      ],
+    } as unknown as Project
+    const layout = computeTimelineLayout(p)
+    expect(layout.rows.find(r => r.trackIdx === 1)?.trackMuted).toBe(true)
+    expect(layout.rows.find(r => r.trackIdx === 0)?.trackMuted).toBe(false)
+  })
+
+  it('keeps a skipped row at full height and in place — it stays editable', () => {
+    // Dimmed, not collapsed: you have to be able to see a skipped track and
+    // click its clips to turn it back on.
+    const enabled = { id: 'p', tracks: [{ id: 't0', items: [clip({ id: 'c0' })] }] } as unknown as Project
+    const skipped = { id: 'p', tracks: [{ id: 't0', items: [clip({ id: 'c0' })], enabled: false }] } as unknown as Project
+    expect(computeTimelineLayout(skipped).rows[0].height).toBe(computeTimelineLayout(enabled).rows[0].height)
+    expect(computeTimelineLayout(skipped).height).toBe(computeTimelineLayout(enabled).height)
+  })
+
+  it('draws a skipped row at reduced alpha', () => {
+    const p = { id: 'p', tracks: [{ id: 't0', items: [clip({ id: 'c0', start: 0, end: 2 })], enabled: false }] } as unknown as Project
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({ project: p, layout: computeTimelineLayout(p) }))
+    expect(r.calls.some(c => c.method === 'set:globalAlpha' && c.args[0] === 0.3)).toBe(true)
+  })
+})
+
+describe('drawTimelineContent — an audio track with no start/end', () => {
+  // Regression: `intersectsRange(undefined, undefined, range)` is false, so the
+  // lane was culled and the timeline showed an empty row while the export was
+  // correct. See `resolveAudioWindow` in timeline-model.ts.
+  const p = {
+    id: 'p',
+    tracks: [[{ id: 'c0', type: 'video', src: 'a.mp4', start: 0, end: 10 }]],
+    audio: { tracks: [{ id: 'bed', src: 'song.mp3' }] },
+  } as unknown as Project
+
+  it('draws the bar instead of culling it', () => {
+    const layout = computeTimelineLayout(p)
+    expect(layout.lanes).toHaveLength(1)
+    const r = recordingContext()
+    const stats = drawTimelineContent(r.ctx, scene({ project: p, layout }))
+    expect(stats.audioItemsDrawn).toBe(1)
+    expect(stats.itemsCulled).toBe(0)
+  })
+
+  it('gives it a positive width', () => {
+    const layout = computeTimelineLayout(p)
+    const [t] = layout.lanes[0].tracks
+    expect(t.end - t.start).toBeGreaterThan(0)
+  })
+})
+
+// ── Light/dark palette ───────────────────────────────────────────────────
+//
+// The canvas can't read a CSS variable, so the whole light theme reaches these
+// pixels through `timelinePalette(mode)`. Two things have to hold at once and
+// they pull in opposite directions: the LIGHT set must genuinely be a different
+// palette (not the dark numbers nudged), and the DARK set must be
+// byte-identical to what it always was — which is why every painter takes the
+// palette as an OPTIONAL trailing argument and every assertion above this
+// block still calls them without one.
+
+/** Every colour string a palette can put on the canvas, flattened. Used to
+ *  ask "did any value from the OTHER mode leak into this paint?", which is the
+ *  question a per-key spot-check can't answer. */
+function paletteValues(p: TimelinePalette): string[] {
+  return [
+    ...Object.values(p.colors),
+    ...p.tracks.flatMap(t => Object.values(t)),
+    ...Object.values(p.caption),
+    p.captionRailAccent,
+    ...Object.values(p.waveform),
+    p.labelShadow,
+  ]
+}
+
+/** Values this mode uses that the OTHER mode never does — the literals whose
+ *  appearance in a paint proves the wrong palette was consulted. Computed
+ *  rather than listed so a future key can't quietly escape the check. */
+function exclusiveTo(mode: TimelinePalette, other: TimelinePalette): string[] {
+  const otherValues = new Set(paletteValues(other))
+  return [...new Set(paletteValues(mode))].filter(v => !otherValues.has(v))
+}
+
+/** Every colour actually written to the context during a paint. */
+function stylesWritten(r: Recorder): unknown[] {
+  return r.calls
+    .filter(c => c.method === 'set:fillStyle' || c.method === 'set:strokeStyle' || c.method === 'set:shadowColor')
+    .map(c => c.args[0])
+}
+
+/** A project exercising every painter that reads a colour: a clip (row
+ *  background, track fill, selection outline, handles, waveform band), a
+ *  labelled overlay (label text + its shadow), a caption block, an audio bar
+ *  with a fade, and — via `selectedIds` — the selected states of each. */
+function paletteProject(): Project {
+  return project({
+    tracks: [
+      [clip({ id: 'c0', start: 0, end: 4 })],
+      // Wide enough (60px at the fixture viewport) to clear MIN_LABEL_WIDTH_PX,
+      // so the label — and the halo behind it — actually paints.
+      [clip({ id: 'ov0', type: 'overlay', src: 'title.jsx', start: 0, end: 6 })],
+    ],
+    audio: { tracks: [audio({ id: 'a0', start: 0, end: 3, fadeIn: 0.5, fadeOut: 0.5 })] },
+    captions: { segments: [captionSegment({ id: 'seg0', start: 0, end: 2 })] },
+  } as unknown as Partial<Project>)
+}
+
+/** A waveform lookup that always has data, so the clip band and the audio-lane
+ *  bars are actually painted and their colours are observable. */
+const ALWAYS_WAVEFORM = {
+  clipColumns: () => [{ min: -0.5, max: 0.5 }],
+  audioColumns: (_t: unknown, rect: { x: number; y: number; width: number; height: number }) =>
+    ({ rect, columns: [{ min: -0.5, max: 0.5 }] }),
+} as unknown as TimelineScene['waveforms']
+
+describe('timelinePalette', () => {
+  it('resolves dark to the exact constants the module has always exported', () => {
+    // Identity, not deep-equality: `TIMELINE_COLORS` and friends are still the
+    // objects every other module imports, so nothing can have been rebuilt or
+    // re-typed underneath them.
+    const dark = timelinePalette('dark')
+    expect(dark).toBe(DARK_TIMELINE_PALETTE)
+    expect(dark.colors).toBe(TIMELINE_COLORS)
+    expect(dark.tracks).toBe(TRACK_PALETTE)
+    expect(dark.caption).toBe(CAPTION_PALETTE)
+    expect(dark.captionRailAccent).toBe(CAPTION_RAIL_ACCENT)
+    expect(dark.waveform).toBe(WAVEFORM_COLORS)
+    expect(dark.labelShadow).toBe(LABEL_SHADOW_COLOR)
+  })
+
+  it('resolves light to the light constants', () => {
+    const light = timelinePalette('light')
+    expect(light).toBe(LIGHT_TIMELINE_PALETTE)
+    expect(light.colors).toBe(LIGHT_TIMELINE_COLORS)
+    expect(light.tracks).toBe(LIGHT_TRACK_PALETTE)
+    expect(light.caption).toBe(LIGHT_CAPTION_PALETTE)
+    expect(light.captionRailAccent).toBe(LIGHT_CAPTION_RAIL_ACCENT)
+    expect(light.waveform).toBe(LIGHT_WAVEFORM_COLORS)
+    expect(light.labelShadow).toBe(LIGHT_LABEL_SHADOW_COLOR)
+  })
+
+  it('returns the same object every call, so callers can memoize on identity', () => {
+    expect(timelinePalette('light')).toBe(timelinePalette('light'))
+    expect(timelinePalette('dark')).toBe(timelinePalette('dark'))
+  })
+
+  it('differs from dark on the keys that carry the theme', () => {
+    const dark = timelinePalette('dark').colors
+    const light = timelinePalette('light').colors
+    // The row field itself, and the chrome strip above it.
+    expect(light.rowBackground).not.toBe(dark.rowBackground)
+    expect(light.rowBackgroundAlt).not.toBe(dark.rowBackgroundAlt)
+    expect(light.rulerBackground).not.toBe(dark.rulerBackground)
+    // The selection vocabulary — white in dark, and it cannot stay white.
+    expect(light.clipSelectedOutline).not.toBe(dark.clipSelectedOutline)
+    expect(light.handleFill).not.toBe(dark.handleFill)
+    expect(light.marqueeBorder).not.toBe(dark.marqueeBorder)
+    // The colourless overlap treatment.
+    expect(light.overlapHatch).not.toBe(dark.overlapHatch)
+    expect(light.overlapEdge).not.toBe(dark.overlapEdge)
+    // Track/caption labels have to be readable on their own fills.
+    expect(light.audioText).not.toBe(dark.audioText)
+    expect(LIGHT_TRACK_PALETTE[0].text).not.toBe(TRACK_PALETTE[0].text)
+    expect(LIGHT_CAPTION_PALETTE.text).not.toBe(CAPTION_PALETTE.text)
+  })
+
+  it('keeps a light entry for every dark key and vice versa', () => {
+    expect(Object.keys(LIGHT_TIMELINE_COLORS).sort()).toEqual(Object.keys(TIMELINE_COLORS).sort())
+    expect(Object.keys(LIGHT_WAVEFORM_COLORS).sort()).toEqual(Object.keys(WAVEFORM_COLORS).sort())
+    expect(LIGHT_TRACK_PALETTE).toHaveLength(TRACK_PALETTE.length)
+  })
+})
+
+describe('the light palette is a real inversion, not a copy', () => {
+  /** The two entries that are IDENTICAL across modes on purpose:
+   *  - `playhead` is red-500 and unmistakable on either ground;
+   *  - `keyframeDiamondFill` is amber because no other hue on this surface is
+   *    free to mean "keyframe", and a diamond is painted over the clip's own
+   *    content (an arbitrary filmstrip frame), not over the row background, so
+   *    it is not tuned to either ground in the first place.
+   *  Everything else must move. */
+  const DELIBERATELY_SHARED = ['playhead', 'keyframeDiamondFill'] as const
+
+  it('changes every colour except the two that are deliberately shared', () => {
+    const shared = (Object.keys(TIMELINE_COLORS) as (keyof typeof TIMELINE_COLORS)[])
+      .filter(k => LIGHT_TIMELINE_COLORS[k] === TIMELINE_COLORS[k])
+    expect(shared.sort()).toEqual([...DELIBERATELY_SHARED].sort())
+  })
+
+  it('inverts every white-on-dark overlay to a dark-on-light one', () => {
+    // These are the trap: `rgba(255,255,255,…)` reads as "the mark" on a dark
+    // row and as "nothing at all" on a light one. Each must have stopped being
+    // white — asserted structurally rather than by naming the replacement, so
+    // the check survives a future tweak to the exact near-black used.
+    const whiteInDark = [
+      'overlapFill', 'overlapHatch', 'overlapEdge',
+      'fadeEnvelopeLine', 'fadeGripSubtle', 'fadeGripActive',
+      'clipSelectedOutline', 'handleFill', 'handleFillHovered',
+      'keyframeDiamondSelectedFill', 'marqueeFill', 'marqueeBorder',
+      'audioMutedFill',
+    ] as const
+    for (const key of whiteInDark) {
+      expect(TIMELINE_COLORS[key]).toMatch(/^(#ffffff|rgba\(255,255,255)/)
+      expect(LIGHT_TIMELINE_COLORS[key]).not.toMatch(/^(#ffffff|rgba\(255,255,255)/)
+    }
+    expect(WAVEFORM_COLORS.clip).toMatch(/^rgba\(255,255,255/)
+    expect(LIGHT_WAVEFORM_COLORS.clip).not.toMatch(/^rgba\(255,255,255/)
+    expect(LIGHT_WAVEFORM_COLORS.clipMuted).not.toMatch(/^rgba\(255,255,255/)
+  })
+
+  it('flips the hatch under-stroke so a dark hatch still has a ground', () => {
+    // Dark: white stripes over a BLACK under-stroke. Light: near-black stripes
+    // over a WHITE one. The under-stroke exists to be the opposite value of
+    // the stripe, whatever filmstrip frame is behind them.
+    expect(TIMELINE_COLORS.overlapHatchShadow).toMatch(/^rgba\(0,0,0/)
+    expect(LIGHT_TIMELINE_COLORS.overlapHatchShadow).toMatch(/^rgba\(255,255,255/)
+    // Same reasoning for the keyframe diamond's halo and the clip label's.
+    expect(TIMELINE_COLORS.keyframeDiamondStroke).toMatch(/^rgba\(0,0,0/)
+    expect(LIGHT_TIMELINE_COLORS.keyframeDiamondStroke).toMatch(/^rgba\(255,255,255/)
+    expect(LABEL_SHADOW_COLOR).toMatch(/^rgba\(0,0,0/)
+    expect(LIGHT_LABEL_SHADOW_COLOR).toMatch(/^rgba\(255,255,255/)
+  })
+
+  it('keeps "no two meanings share one literal" for the overlap/mute pair', () => {
+    // The dark set says 0.12 rather than the natural 0.1 precisely because
+    // `audioMutedFill` already IS 0.1 — a muted bar and an overlap band must
+    // stay distinguishable by colour alone. That property is a rule about the
+    // palette, not about dark, so it has to hold in light too.
+    expect(TIMELINE_COLORS.overlapFill).not.toBe(TIMELINE_COLORS.audioMutedFill)
+    expect(LIGHT_TIMELINE_COLORS.overlapFill).not.toBe(LIGHT_TIMELINE_COLORS.audioMutedFill)
+    expect(LIGHT_TIMELINE_COLORS.marqueeFill).not.toBe(LIGHT_TIMELINE_COLORS.audioMutedFill)
+  })
+
+  it('gives every track hue its own entry in both modes', () => {
+    // Six distinct hues is the whole point of the cycle — a light palette that
+    // collapsed two of them would silently make two tracks look the same.
+    expect(new Set(LIGHT_TRACK_PALETTE.map(t => t.fill)).size).toBe(LIGHT_TRACK_PALETTE.length)
+    expect(new Set(LIGHT_TRACK_PALETTE.map(t => t.text)).size).toBe(LIGHT_TRACK_PALETTE.length)
+  })
+})
+
+describe('painters use the palette they are handed, not the module global', () => {
+  // This is the assertion that catches the real bug: a painter that still
+  // reads `TIMELINE_COLORS` directly passes any test that only checks the
+  // palette CONSTANTS differ.
+
+  it('drawRowBackground paints the light row and its light divider', () => {
+    const r = recordingContext()
+    drawRowBackground(r.ctx, { x: 0, y: 0, width: 100, height: 20 }, undefined, LIGHT_TIMELINE_PALETTE)
+    expect(r.of('set:fillStyle').map(c => c.args[0])).toContain(LIGHT_TIMELINE_COLORS.rowBackground)
+    expect(r.of('set:strokeStyle').map(c => c.args[0])).toContain(LIGHT_TIMELINE_COLORS.rowDivider)
+    expect(r.of('set:fillStyle').map(c => c.args[0])).not.toContain(TIMELINE_COLORS.rowBackground)
+    expect(r.of('set:strokeStyle').map(c => c.args[0])).not.toContain(TIMELINE_COLORS.rowDivider)
+  })
+
+  it('drawItemHandles paints the light pill and the light grip ticks', () => {
+    const r = recordingContext()
+    drawItemHandles(r.ctx, { x: 0, y: 0, width: 200, height: 40 }, CLIP_HANDLE_WIDTH_PX, 'in', undefined, LIGHT_TIMELINE_PALETTE)
+    const fills = r.of('set:fillStyle').map(c => c.args[0])
+    expect(fills).toContain(LIGHT_TIMELINE_COLORS.handleFillHovered)
+    expect(fills).toContain(LIGHT_TIMELINE_COLORS.handleGripHovered)
+    expect(fills).not.toContain(TIMELINE_COLORS.handleFill)
+    expect(fills).not.toContain(TIMELINE_COLORS.handleGrip)
+  })
+
+  it('drawCaptionBlock takes its hue from the palette, not CAPTION_PALETTE', () => {
+    const r = recordingContext()
+    drawCaptionBlock(r.ctx, { rect: { x: 0, y: 0, width: 120, height: 20 }, selected: false, label: 'hi' }, LIGHT_TIMELINE_PALETTE)
+    const fills = r.of('set:fillStyle').map(c => c.args[0])
+    expect(fills).toContain(LIGHT_CAPTION_PALETTE.fill)
+    expect(fills).toContain(LIGHT_CAPTION_PALETTE.text)
+    expect(fills).not.toContain(CAPTION_PALETTE.fill)
+    expect(r.of('set:strokeStyle').map(c => c.args[0])).toContain(LIGHT_CAPTION_PALETTE.border)
+  })
+
+  it('drawOverlapBand paints the light hatch over the light under-stroke', () => {
+    const r = recordingContext()
+    drawOverlapBand(r.ctx, { x: 0, y: 0, width: 60, height: 40 }, LIGHT_TIMELINE_PALETTE)
+    const strokes = r.of('set:strokeStyle').map(c => c.args[0])
+    expect(strokes).toEqual([LIGHT_TIMELINE_COLORS.overlapHatchShadow, LIGHT_TIMELINE_COLORS.overlapHatch])
+    expect(r.of('set:fillStyle').map(c => c.args[0])).toContain(LIGHT_TIMELINE_COLORS.overlapEdge)
+  })
+
+  it('drawRuler paints the light chrome strip, ticks and labels', () => {
+    const r = recordingContext()
+    drawRuler(r.ctx, viewport(), { y: 0, height: RULER_HEIGHT_PX }, 1000, LIGHT_TIMELINE_PALETTE)
+    const fills = r.of('set:fillStyle').map(c => c.args[0])
+    expect(fills).toContain(LIGHT_TIMELINE_COLORS.rulerBackground)
+    expect(fills).toContain(LIGHT_TIMELINE_COLORS.rulerTick)
+    expect(fills).toContain(LIGHT_TIMELINE_COLORS.rulerText)
+    expect(fills).not.toContain(TIMELINE_COLORS.rulerBackground)
+  })
+
+  it('drawMarquee, drawPlayhead, drawCursorLine and drawSnapGuide take theirs too', () => {
+    const r = recordingContext()
+    drawMarquee(r.ctx, { x: 0, y: 0, width: 40, height: 40 }, LIGHT_TIMELINE_PALETTE)
+    drawPlayhead(r.ctx, 10, 0, 40, LIGHT_TIMELINE_PALETTE)
+    drawCursorLine(r.ctx, 12, 0, 40, LIGHT_TIMELINE_PALETTE)
+    drawSnapGuide(r.ctx, 14, 0, 40, 'strong', LIGHT_TIMELINE_PALETTE)
+    const styles = stylesWritten(r)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.marqueeFill)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.marqueeBorder)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.cursor)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.snapGuide)
+    // Shared on purpose — the light pass still paints red-500 here.
+    expect(styles).toContain(TIMELINE_COLORS.playhead)
+    expect(styles).not.toContain(TIMELINE_COLORS.cursor)
+    expect(styles).not.toContain(TIMELINE_COLORS.marqueeBorder)
+  })
+})
+
+describe('drawTimelineContent / drawTimelineOverlay — mode', () => {
+  it('paints the whole content layer from the light set and never from the dark one', () => {
+    const p = paletteProject()
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({
+      project: p,
+      layout: computeTimelineLayout(p),
+      selectedIds: ['c0', 'ov0', 'a0', 'seg0'],
+      waveforms: ALWAYS_WAVEFORM,
+      mode: 'light',
+    }))
+    const styles = stylesWritten(r)
+
+    // Spot-checks across every painter the pass runs.
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.rowBackground)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.rowBackgroundAlt)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.rulerBackground)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.clipSelectedOutline)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.handleFill)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.audioFill)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.fadeEnvelopeDim)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.fadeEnvelopeLine)
+    expect(styles).toContain(LIGHT_TRACK_PALETTE[0].fillSelected)
+    expect(styles).toContain(LIGHT_TRACK_PALETTE[1].text)
+    expect(styles).toContain(LIGHT_CAPTION_PALETTE.fillSelected)
+    // Threaded into the waveform painters from the SAME resolved palette.
+    expect(styles).toContain(LIGHT_WAVEFORM_COLORS.clipBand)
+    expect(styles).toContain(LIGHT_WAVEFORM_COLORS.clip)
+    expect(styles).toContain(LIGHT_WAVEFORM_COLORS.audioLane)
+    // The clip label's halo (a shadowColor, not a fill) follows too.
+    expect(styles).toContain(LIGHT_LABEL_SHADOW_COLOR)
+
+    // And nothing dark-only leaked through — the check a spot-check can't make.
+    for (const darkOnly of exclusiveTo(DARK_TIMELINE_PALETTE, LIGHT_TIMELINE_PALETTE)) {
+      expect(styles).not.toContain(darkOnly)
+    }
+  })
+
+  it('defaults to dark when no mode is given, with no light value anywhere', () => {
+    // The no-regression proof: every caller and every test that predates modes
+    // goes down this path.
+    const p = paletteProject()
+    const r = recordingContext()
+    drawTimelineContent(r.ctx, scene({
+      project: p,
+      layout: computeTimelineLayout(p),
+      selectedIds: ['c0', 'ov0', 'a0', 'seg0'],
+      waveforms: ALWAYS_WAVEFORM,
+    }))
+    const styles = stylesWritten(r)
+    expect(styles).toContain(TIMELINE_COLORS.rowBackground)
+    expect(styles).toContain(TIMELINE_COLORS.clipSelectedOutline)
+    expect(styles).toContain(WAVEFORM_COLORS.clip)
+    expect(styles).toContain(LABEL_SHADOW_COLOR)
+    for (const lightOnly of exclusiveTo(LIGHT_TIMELINE_PALETTE, DARK_TIMELINE_PALETTE)) {
+      expect(styles).not.toContain(lightOnly)
+    }
+  })
+
+  it('paints an explicit dark mode identically to an omitted one', () => {
+    const p = paletteProject()
+    const omitted = recordingContext()
+    const explicit = recordingContext()
+    const args = { project: p, layout: computeTimelineLayout(p), selectedIds: ['c0'], waveforms: ALWAYS_WAVEFORM }
+    drawTimelineContent(omitted.ctx, scene(args))
+    drawTimelineContent(explicit.ctx, scene({ ...args, mode: 'dark' }))
+    expect(explicit.calls).toEqual(omitted.calls)
+  })
+
+  it('paints the overlay layer from the light set', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport(),
+      currentTime: 1,
+      cursorTime: 1.5,
+      snapTime: 2,
+      snapStrength: 'weak',
+      marquee: { x: 0, y: 0, width: 40, height: 40 },
+      surfaceWidth: 1000,
+      surfaceHeight: 200,
+      mode: 'light',
+    })
+    const styles = stylesWritten(r)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.marqueeFill)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.cursor)
+    expect(styles).toContain(LIGHT_TIMELINE_COLORS.snapGuideWeak)
+    expect(styles).toContain(TIMELINE_COLORS.playhead) // shared on purpose
+    expect(styles).not.toContain(TIMELINE_COLORS.cursor)
+    expect(styles).not.toContain(TIMELINE_COLORS.snapGuideWeak)
+    expect(styles).not.toContain(TIMELINE_COLORS.marqueeFill)
+  })
+
+  it('leaves the overlay dark when no mode is given', () => {
+    const r = recordingContext()
+    drawTimelineOverlay(r.ctx, {
+      viewport: viewport(),
+      currentTime: 1,
+      cursorTime: 1.5,
+      snapTime: 2,
+      marquee: { x: 0, y: 0, width: 40, height: 40 },
+      surfaceWidth: 1000,
+      surfaceHeight: 200,
+    })
+    const styles = stylesWritten(r)
+    expect(styles).toContain(TIMELINE_COLORS.cursor)
+    expect(styles).toContain(TIMELINE_COLORS.snapGuide)
+    expect(styles).not.toContain(LIGHT_TIMELINE_COLORS.cursor)
+    expect(styles).not.toContain(LIGHT_TIMELINE_COLORS.marqueeFill)
+  })
+})