@bycrux/editor 0.11.2 → 1.0.1

package/src/video/timeline/__tests__/TrackGutter.test.tsx

@@ -0,0 +1,372 @@
+/// <reference types="vitest/globals" />
+/**
+ * The left rail that names each track. Its whole job is alignment: a label that
+ * sits at a different y than the clips it describes is worse than no label, so
+ * these assert it positions off the SAME layout the canvas paints from.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { render, screen, cleanup, fireEvent } from '@testing-library/react'
+import TrackGutter, { visualTrackKind } from '../TrackGutter'
+import { computeTimelineLayout } from '../canvas/draw'
+import type { Project } from '../../../types'
+import type { Captions, VisualItem } from '../../../schema'
+
+afterEach(() => cleanup())
+
+const video = (id: string, over: Partial<VisualItem> = {}): VisualItem =>
+  ({ id, type: 'video', src: 'a.mp4', start: 0, end: 2, ...over }) as VisualItem
+const overlay = (id: string, over: Partial<VisualItem> = {}): VisualItem =>
+  ({ id, type: 'overlay', src: '/p/overlays/text_line.jsx', start: 0, end: 2, ...over }) as VisualItem
+const captions = (over: Partial<Captions> = {}): Captions =>
+  ({ style: 'clean', segments: [{ text: 'hello', start: 0, end: 1 }], ...over })
+
+function project(over: Partial<Project> = {}): Project {
+  return {
+    id: 'p',
+    tracks: [[video('c0')], [overlay('o0')]],
+    audio: { tracks: [{ id: 'a0', src: 'v.mp3', start: 0, end: 2, lane: 0 }] },
+    ...over,
+  } as unknown as Project
+}
+
+describe('visualTrackKind', () => {
+  it('reads the kind off the items, since tracks are untyped in the schema', () => {
+    expect(visualTrackKind([video('a'), video('b')])).toBe('video')
+    expect(visualTrackKind([overlay('a')])).toBe('overlay')
+  })
+
+  it('has no answer for an empty track rather than guessing "video"', () => {
+    expect(visualTrackKind([])).toBeNull()
+  })
+
+  it('falls back to the first item on a mixed track', () => {
+    expect(visualTrackKind([overlay('a'), video('b')])).toBe('overlay')
+  })
+})
+
+describe('TrackGutter', () => {
+  it('names each row by what it holds, plus the audio lane and the caption row', () => {
+    // Icon-only cells: the name is the accessible name (and the hover tooltip),
+    // not on-screen text. The caption cell only renders when the layout has a
+    // band to align with (see 'TrackGutter — caption cell alignment' below),
+    // so this project needs actual caption segments.
+    render(<TrackGutter project={project({ captions: captions() })} />)
+    expect(screen.getByLabelText('Video')).toBeTruthy()
+    expect(screen.getByLabelText('Overlay')).toBeTruthy()
+    expect(screen.getByLabelText('Audio')).toBeTruthy()
+    expect(screen.getByLabelText('Captions')).toBeTruthy()
+  })
+
+  it('places every label at the y its own row occupies in the canvas layout', () => {
+    // The alignment invariant. Both surfaces read one `computeTimelineLayout`,
+    // so this fails the moment the rail starts deriving geometry of its own.
+    const p = project()
+    const layout = computeTimelineLayout(p)
+    const { container } = render(<TrackGutter project={p} layout={layout} />)
+
+    const positioned = [...container.querySelectorAll<HTMLElement>('.absolute')]
+    const seen = positioned.map(el => ({ top: el.style.top, height: el.style.height }))
+
+    for (const row of layout.rows) {
+      expect(seen).toContainEqual({ top: `${row.y}px`, height: `${row.height}px` })
+    }
+    for (const lane of layout.lanes) {
+      expect(seen).toContainEqual({ top: `${lane.y}px`, height: `${lane.height}px` })
+    }
+  })
+
+  it('gives the base track its taller cell, not a uniform row height', () => {
+    const p = project()
+    const layout = computeTimelineLayout(p)
+    render(<TrackGutter project={p} layout={layout} />)
+
+    const base = layout.rows.find(r => r.trackIdx === 0)!
+    const overlayRow = layout.rows.find(r => r.trackIdx === 1)!
+    expect(base.height).toBeGreaterThan(overlayRow.height)
+  })
+
+  it('omits the caption cell when showCaptionRow is false, even though the layout carries a caption band', () => {
+    const p = project({ captions: captions() })
+    expect(computeTimelineLayout(p).captions).toBeTruthy()
+    render(<TrackGutter project={p} showCaptionRow={false} />)
+    expect(screen.queryByLabelText('Captions')).toBeNull()
+  })
+
+  it('labels an empty track rather than rendering a blank cell', () => {
+    render(<TrackGutter project={project({ tracks: [{ id: 'trk-0', items: [] }] } as Partial<Project>)} />)
+    expect(screen.getByLabelText('Track')).toBeTruthy()
+  })
+
+  it('renders without an audio lane or captions on a bare project', () => {
+    const bare = { id: 'p', tracks: [[video('c0')]] } as unknown as Project
+    render(<TrackGutter project={bare} showCaptionRow={false} />)
+    expect(screen.getByLabelText('Video')).toBeTruthy()
+    expect(screen.queryByLabelText('Audio')).toBeNull()
+  })
+})
+
+describe('TrackGutter — caption cell alignment', () => {
+  // The caption row moved from a DOM strip below the canvas to a band INSIDE
+  // the canvas layout, so its rail cell has to be positioned like every other
+  // row rather than trail the gutter as its own flex cell.
+
+  it('positions the caption cell at layout.captions[0].y/height, inside the same block the track rows live in', () => {
+    const p = project({ captions: captions() })
+    const layout = computeTimelineLayout(p)
+    expect(layout.captions).toHaveLength(1)
+
+    const { container } = render(<TrackGutter project={p} layout={layout} showCaptionRow />)
+
+    const cell = screen.getByLabelText('Captions')
+    // `.absolute` is the wrapper VisualTrackRailRow/AudioLaneRailRow both use —
+    // finding it via `closest` rather than asserting on RailCell itself proves
+    // the cell is wrapped the SAME way the other rows are, not styled directly.
+    const wrapper = cell.closest('.absolute') as HTMLElement
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.style.top).toBe(`${layout.captions![0].y}px`)
+    expect(wrapper.style.height).toBe(`${layout.captions![0].height}px`)
+
+    // Structural, not a snapshot: the wrapper is a DESCENDANT of the `.relative`
+    // block the track rows and audio lanes are absolutely positioned inside —
+    // not a trailing sibling after it.
+    const relativeBlock = container.querySelector('.relative')!
+    expect(relativeBlock.contains(wrapper)).toBe(true)
+  })
+
+  it('renders no caption cell on a project with no captions, even though showCaptionRow defaults true, and nothing else shifts', () => {
+    const p = project() // no `captions` field — the layout carries no bands at all
+    const layout = computeTimelineLayout(p)
+    expect(layout.captions).toBeUndefined()
+
+    const { container } = render(<TrackGutter project={p} layout={layout} />)
+    expect(screen.queryByLabelText('Captions')).toBeNull()
+
+    // The row/lane cells still land exactly where the (caption-less) layout
+    // says they do — missing bands don't leave a gap or shift anything.
+    const positioned = [...container.querySelectorAll<HTMLElement>('.absolute')]
+    const seen = positioned.map(el => ({ top: el.style.top, height: el.style.height }))
+    for (const row of layout.rows) {
+      expect(seen).toContainEqual({ top: `${row.y}px`, height: `${row.height}px` })
+    }
+    for (const lane of layout.lanes) {
+      expect(seen).toContainEqual({ top: `${lane.y}px`, height: `${lane.height}px` })
+    }
+  })
+
+  it('renders N cells, one per band, each at its own band y — "Captions 1"…"Captions N" once there is more than one', () => {
+    const p = project({
+      captions: captions({
+        segments: [
+          { text: 'a', start: 0, end: 1, lane: 0 },
+          { text: 'b', start: 0, end: 1, lane: 1 },
+          { text: 'c', start: 0, end: 1, lane: 2 },
+        ],
+      }),
+    })
+    const layout = computeTimelineLayout(p)
+    expect(layout.captions).toHaveLength(3)
+
+    render(<TrackGutter project={p} layout={layout} showCaptionRow />)
+
+    // The bare "Captions" label is gone once there is more than one band.
+    expect(screen.queryByLabelText('Captions')).toBeNull()
+    for (const band of layout.captions!) {
+      const cell = screen.getByLabelText(`Captions ${band.lane + 1}`)
+      const wrapper = cell.closest('.absolute') as HTMLElement
+      expect(wrapper.style.top).toBe(`${band.y}px`)
+      expect(wrapper.style.height).toBe(`${band.height}px`)
+    }
+  })
+})
+
+describe('TrackGutter — skip', () => {
+  it('shows no skip control when the host has not wired the edit channel', () => {
+    // A button that silently does nothing is worse than no button.
+    render(<TrackGutter project={project()} />)
+    expect(screen.queryByLabelText(/^Skip /)).toBeNull()
+  })
+
+  it('offers a skip toggle per visual track when wired', () => {
+    render(<TrackGutter project={project()} onToggleTrackEnabled={vi.fn()} />)
+    expect(screen.getByLabelText('Skip video track')).toBeTruthy()
+    expect(screen.getByLabelText('Skip overlay track')).toBeTruthy()
+  })
+
+  it('reports the track index and the NEW enabled value', () => {
+    const onToggle = vi.fn()
+    render(<TrackGutter project={project()} onToggleTrackEnabled={onToggle} />)
+    fireEvent.click(screen.getByLabelText('Skip video track'))
+    expect(onToggle).toHaveBeenCalledWith(0, false)
+  })
+
+  it('re-enables a skipped track', () => {
+    const onToggle = vi.fn()
+    const p = { id: 'p', tracks: [{ id: 't0', items: [video('c0')], enabled: false }] } as unknown as Project
+    render(<TrackGutter project={p} showCaptionRow={false} onToggleTrackEnabled={onToggle} />)
+    fireEvent.click(screen.getByLabelText('Skip video track'))
+    expect(onToggle).toHaveBeenCalledWith(0, true)
+  })
+
+  it('marks a skipped track pressed, so the state is readable without colour', () => {
+    const p = { id: 'p', tracks: [{ id: 't0', items: [video('c0')], enabled: false }] } as unknown as Project
+    render(<TrackGutter project={p} showCaptionRow={false} onToggleTrackEnabled={vi.fn()} />)
+    expect(screen.getByLabelText('Skip video track').getAttribute('aria-pressed')).toBe('true')
+  })
+
+  it('treats a legacy-shaped project as all-enabled', () => {
+    const legacy = { id: 'p', tracks: [[video('c0')]] } as unknown as Project
+    render(<TrackGutter project={legacy} showCaptionRow={false} onToggleTrackEnabled={vi.fn()} />)
+    expect(screen.getByLabelText('Skip video track').getAttribute('aria-pressed')).toBe('false')
+  })
+})
+
+describe('TrackGutter — rail controls and settings', () => {
+  const wired = {
+    onToggleTrackEnabled: vi.fn(),
+    onSetTrackVolume: vi.fn(),
+    onSetTrackMuted: vi.fn(),
+  }
+
+  it('puts mute and skip in the RAIL, and volume behind the gear', () => {
+    // Mute and skip are flipped constantly while cutting and need to be seen at
+    // a glance, so they are inline; the gear is for what you set once.
+    render(<TrackGutter project={project()} {...wired} />)
+    expect(screen.getByRole('button', { name: 'Mute video track' })).toBeTruthy()
+    expect(screen.getByRole('button', { name: 'Skip video track' })).toBeTruthy()
+    expect(screen.queryByRole('dialog')).toBeNull()
+
+    fireEvent.click(screen.getByRole('button', { name: 'Video track settings' }))
+    expect(screen.getByLabelText('Video volume')).toBeTruthy()
+  })
+
+  it('offers NO audio controls on an overlay-only track', () => {
+    // Overlay and image items carry no audio — `VisualItem.volume`/`muted` are
+    // video-only — so a mute button or volume slider there could do nothing.
+    render(<TrackGutter project={project()} {...wired} />)
+    expect(screen.queryByRole('button', { name: 'Mute overlay track' })).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Overlay track settings' })).toBeNull()
+    // Skip still applies — you can hide an overlay track.
+    expect(screen.getByRole('button', { name: 'Skip overlay track' })).toBeTruthy()
+  })
+
+  it('gives a MIXED track audio controls, reading the items not the track kind', () => {
+    const mixed = {
+      id: 'p',
+      tracks: [{ id: 't0', items: [overlay('o0'), video('c0')] }],
+    } as unknown as Project
+    render(<TrackGutter project={mixed} showCaptionRow={false} {...wired} />)
+    expect(screen.getByRole('button', { name: 'Mute overlay track' })).toBeTruthy()
+  })
+
+  it('the type icon is a plain label, never the settings trigger', () => {
+    // It used to double as the trigger, which made it impossible to tell what
+    // was clickable.
+    render(<TrackGutter project={project()} {...wired} />)
+    expect(screen.getByLabelText('Video').tagName).toBe('SPAN')
+  })
+
+  it('renders no gear when volume is not wired', () => {
+    render(<TrackGutter project={project()} onToggleTrackEnabled={vi.fn()} />)
+    expect(screen.queryByRole('button', { name: 'Video track settings' })).toBeNull()
+  })
+
+  it('toggles mute from the rail with the new value', () => {
+    const onSetTrackMuted = vi.fn()
+    render(<TrackGutter project={project()} {...wired} onSetTrackMuted={onSetTrackMuted} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Mute video track' }))
+    expect(onSetTrackMuted).toHaveBeenCalledWith(0, true)
+  })
+
+  it('shows a muted track as pressed, so the state reads without colour', () => {
+    const p = { id: 'p', tracks: [{ id: 't0', items: [video('c0')], muted: true }] } as unknown as Project
+    render(<TrackGutter project={p} showCaptionRow={false} {...wired} />)
+    expect(screen.getByRole('button', { name: 'Mute video track' }).getAttribute('aria-pressed')).toBe('true')
+  })
+
+  it('gives an audio lane mute inline and volume behind the gear, but no skip', () => {
+    render(<TrackGutter project={project()} onSetLaneVolume={vi.fn()} onSetLaneMuted={vi.fn()} />)
+    expect(screen.getByRole('button', { name: 'Mute audio lane' })).toBeTruthy()
+    expect(screen.queryByRole('button', { name: /^Skip audio/ })).toBeNull()
+
+    fireEvent.click(screen.getByRole('button', { name: 'Audio lane settings' }))
+    expect(screen.getByLabelText('Audio lane volume')).toBeTruthy()
+  })
+
+  it('fans a lane mute out over every track id in the lane', () => {
+    const onSetLaneMuted = vi.fn()
+    const twoTrackLane = {
+      id: 'p',
+      tracks: [{ id: 't0', items: [video('c0')] }],
+      audio: { tracks: [
+        { id: 'a0', src: 'v.mp3', start: 0, end: 2, lane: 0 },
+        { id: 'a1', src: 'm.mp3', start: 0, end: 2, lane: 0 },
+      ] },
+    } as unknown as Project
+    render(<TrackGutter project={twoTrackLane} showCaptionRow={false} onSetLaneMuted={onSetLaneMuted} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Mute audio lane' }))
+    expect(onSetLaneMuted).toHaveBeenCalledWith(['a0', 'a1'], true)
+  })
+
+  it('shows no magnet control when the host has not wired onSetLaneMagnet', () => {
+    render(<TrackGutter project={project()} onSetLaneMuted={vi.fn()} />)
+    expect(screen.queryByRole('button', { name: /^Magnetic /i })).toBeNull()
+  })
+
+  it('offers a magnet toggle per audio lane when wired, reflecting the OFF default', () => {
+    render(<TrackGutter project={project()} onSetLaneMagnet={vi.fn()} />)
+    const toggle = screen.getByRole('button', { name: 'Magnetic audio lane' })
+    expect(toggle).toBeTruthy()
+    expect(toggle.getAttribute('aria-pressed')).toBe('false')
+  })
+
+  it('reflects an ON magnetic lane', () => {
+    const p = {
+      id: 'p',
+      tracks: [{ id: 't0', items: [video('c0')] }],
+      audio: { tracks: [{ id: 'a0', src: 'v.mp3', start: 0, end: 2, lane: 0, magnetic: true }] },
+    } as unknown as Project
+    render(<TrackGutter project={p} showCaptionRow={false} onSetLaneMagnet={vi.fn()} />)
+    expect(screen.getByRole('button', { name: 'Magnetic audio lane' }).getAttribute('aria-pressed')).toBe('true')
+  })
+
+  it('fans a lane magnet toggle out over every track id in the lane, with the NEW value', () => {
+    const onSetLaneMagnet = vi.fn()
+    const twoTrackLane = {
+      id: 'p',
+      tracks: [{ id: 't0', items: [video('c0')] }],
+      audio: { tracks: [
+        { id: 'a0', src: 'v.mp3', start: 0, end: 2, lane: 0 },
+        { id: 'a1', src: 'm.mp3', start: 0, end: 2, lane: 0 },
+      ] },
+    } as unknown as Project
+    render(<TrackGutter project={twoTrackLane} showCaptionRow={false} onSetLaneMagnet={onSetLaneMagnet} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Magnetic audio lane' }))
+    expect(onSetLaneMagnet).toHaveBeenCalledWith(['a0', 'a1'], true)
+  })
+
+  it('reads a lane as magnetic only when EVERY track in it is', () => {
+    const mixedLane = {
+      id: 'p',
+      tracks: [{ id: 't0', items: [video('c0')] }],
+      audio: { tracks: [
+        { id: 'a0', src: 'v.mp3', start: 0, end: 2, lane: 0, magnetic: true },
+        { id: 'a1', src: 'm.mp3', start: 0, end: 2, lane: 0 },
+      ] },
+    } as unknown as Project
+    render(<TrackGutter project={mixedLane} showCaptionRow={false} onSetLaneMagnet={vi.fn()} />)
+    expect(screen.getByRole('button', { name: 'Magnetic audio lane' }).getAttribute('aria-pressed')).toBe('false')
+  })
+
+  it('previews a volume drag and commits once on release', () => {
+    const onSetTrackVolume = vi.fn()
+    render(<TrackGutter project={project()} {...wired} onSetTrackVolume={onSetTrackVolume} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Video track settings' }))
+    const slider = screen.getByLabelText('Video volume')
+
+    fireEvent.change(slider, { target: { value: '0.5' } })
+    expect(onSetTrackVolume).toHaveBeenLastCalledWith(0, 0.5, false)
+
+    fireEvent.pointerUp(slider)
+    expect(onSetTrackVolume).toHaveBeenLastCalledWith(0, 0.5, true)
+  })
+})

package/src/video/timeline/__tests__/_canvasSelect.test.tsx

@@ -0,0 +1,273 @@
+/// <reference types="vitest/globals" />
+/**
+ * Coverage for the canvas test helpers themselves (`_canvasSelect.ts`).
+ *
+ * These helpers are about to become the way every migrated DOM-era test
+ * addresses a clip, so a silent mis-aim in here would show up downstream as
+ * "the assertion is wrong" rather than "the click missed". Each thing the
+ * helpers promise is therefore checked against the REAL mounted timeline, not
+ * against a restatement of the same arithmetic:
+ *
+ * - the pinned surface rect is what the mounted surface actually reports;
+ * - the fit viewport the helpers compute is the one the surface settled on
+ *   (proved by seeking: a press at `timeToClientX(t)` lands the clock on `t`);
+ * - a press selects the item the caller named, by kind and by id;
+ * - `metaKey` extends rather than replaces;
+ * - a drag is a drag (many live edits, ONE commit) and a click is a click.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, cleanup, fireEvent, act } from '@testing-library/react'
+import type { Project } from '../../../types'
+import { createPlaybackClock } from '../../playback-clock'
+import Timeline from '../Timeline'
+import { computeDerivedTiming, trackItems } from '../timeline-model'
+import { PLAYHEAD_GRAB_PX } from '../canvas/hit-test'
+import { fitPxPerSecond } from '../canvas/viewport'
+import {
+  SURFACE_LEFT,
+  SURFACE_WIDTH,
+  canvasItemPoint,
+  canvasSurface,
+  canvasViewport,
+  dragCanvasItem,
+  focusCanvasRoot,
+  installCanvasHarness,
+  resolveCanvasTarget,
+  selectCanvasItem,
+  timeToClientX,
+} from './_canvasSelect'
+
+let uninstall: () => void
+
+beforeEach(() => { uninstall = installCanvasHarness() })
+afterEach(() => { cleanup(); uninstall() })
+
+/** The same two-track shape `VideoEditor.keymap.test.tsx` uses, so what is
+ *  proved here is what the migrated tests rely on. Content runs 0–4s, so
+ *  `totalDuration` is 4 + max(5, 0.8) = 9s — the number the fit is against. */
+function makeProject(): Project {
+  return {
+    id: 'p1',
+    status: 'draft',
+    settings: { resolution: [1080, 1920], fps: 30 },
+    tracks: [
+      [{ id: 'clip-0', type: 'video', src: 'a.mp4', start: 0, end: 4, inPoint: 0, outPoint: 4 }],
+      [{ id: 'overlay-1', type: 'overlay', src: 'overlay.jsx', start: 0, end: 4, props: { text: 'Hello' } }],
+    ],
+  } as unknown as Project
+}
+
+function mount(project: Project, selectedIds: string[] = [], clockAt = 0) {
+  const clock = createPlaybackClock(clockAt)
+  const onSelectIds = vi.fn()
+  const onProjectChange = vi.fn()
+  const onOverlayEdit = vi.fn()
+  const utils = render(
+    <Timeline
+      project={project}
+      clock={clock}
+      selectedIds={selectedIds}
+      onSelectIds={onSelectIds}
+      onProjectChange={onProjectChange}
+      onOverlayEdit={onOverlayEdit}
+    />,
+  )
+  return { clock, onSelectIds, onProjectChange, onOverlayEdit, ...utils }
+}
+
+/** A bare press/release at a page point, bypassing the selector plumbing —
+ *  used only to prove the coordinate math against the surface's own viewport. */
+function pressAndRelease(surface: HTMLElement, clientX: number, clientY: number) {
+  fireEvent.mouseDown(surface, { clientX, clientY, button: 0, bubbles: true })
+  act(() => { document.dispatchEvent(new MouseEvent('mouseup', { clientX, clientY, bubbles: true })) })
+}
+
+describe('_canvasSelect — harness', () => {
+  it('pins the canvas surface to a real rect and leaves everything else spanning the column', () => {
+    const { container } = mount(makeProject())
+    const surface = canvasSurface(container)
+
+    expect(surface.getBoundingClientRect().left).toBe(SURFACE_LEFT)
+    expect(surface.getBoundingClientRect().width).toBe(SURFACE_WIDTH)
+    // Anything that isn't the surface starts at the left of the column.
+    expect((container.firstElementChild as HTMLElement).getBoundingClientRect().left).toBe(0)
+  })
+
+  it('restores the real getContext / getBoundingClientRect on teardown', () => {
+    const beforeCtx = HTMLCanvasElement.prototype.getContext
+    const beforeRect = Element.prototype.getBoundingClientRect
+
+    const teardown = installCanvasHarness()
+    expect(HTMLCanvasElement.prototype.getContext).not.toBe(beforeCtx)
+    expect(Element.prototype.getBoundingClientRect).not.toBe(beforeRect)
+
+    teardown()
+    expect(HTMLCanvasElement.prototype.getContext).toBe(beforeCtx)
+    expect(Element.prototype.getBoundingClientRect).toBe(beforeRect)
+  })
+
+  // The DOM timeline is retired, so a mounted `<Timeline>` ALWAYS has a canvas
+  // surface — the only way to miss it now is aiming the helper at a container
+  // that holds no timeline, which is what this guard is left to catch.
+  it('canvasSurface says what is wrong when the container holds no timeline', () => {
+    const { container } = render(<div />)
+    expect(() => canvasSurface(container)).toThrow(/data-timeline-canvas/)
+  })
+
+  it('focusCanvasRoot focuses the tabIndex=0 root the Delete/Enter bindings are scoped to', () => {
+    const { container } = mount(makeProject())
+    focusCanvasRoot(container)
+    expect(document.activeElement).toBe(container.querySelector('[tabindex="0"]'))
+  })
+})
+
+describe('_canvasSelect — coordinates', () => {
+  it('fits the whole timeline INCLUDING drag headroom, not just the content', () => {
+    const project = makeProject()
+    const { contentDuration, totalDuration } = computeDerivedTiming(project)
+
+    expect(contentDuration).toBe(4)
+    expect(totalDuration).toBe(9)
+    // The scale is 1000px / 9s, NOT 1000px / 4s — the fit is against the
+    // padded duration. Anyone hardcoding a round px/second is wrong.
+    expect(canvasViewport(project).pxPerSecond).toBe(fitPxPerSecond(SURFACE_WIDTH, totalDuration))
+    expect(canvasViewport(project).pxPerSecond).toBeCloseTo(1000 / 9, 10)
+  })
+
+  it('maps t=0 to the surface origin and the full duration to its right edge', () => {
+    const project = makeProject()
+    const { totalDuration } = computeDerivedTiming(project)
+    expect(timeToClientX(project, 0)).toBe(SURFACE_LEFT)
+    expect(timeToClientX(project, totalDuration)).toBeCloseTo(SURFACE_LEFT + SURFACE_WIDTH, 10)
+  })
+
+  it('agrees with the viewport the MOUNTED surface actually settled on', () => {
+    // The real proof: press on empty track area at the x the helper computes
+    // for t=6 and the surface's own `xToTime` must land the playhead there. If
+    // the helper's fit differed from the mounted one by so much as a percent,
+    // this seek would miss.
+    const project = makeProject()
+    const { container, clock } = mount(project)
+    const surface = canvasSurface(container)
+    const videoRow = resolveCanvasTarget(project, { type: 'video' })
+
+    pressAndRelease(surface, timeToClientX(project, 6), videoRow.y + videoRow.height / 2)
+    expect(clock.get()).toBeCloseTo(6, 6)
+  })
+
+  it('resolves a target by kind and by id, and names the ids it knows when it cannot', () => {
+    const project = makeProject()
+    expect(resolveCanvasTarget(project, { type: 'video' }).id).toBe('clip-0')
+    expect(resolveCanvasTarget(project, { type: 'overlay' }).id).toBe('overlay-1')
+    expect(resolveCanvasTarget(project, { id: 'overlay-1' }).start).toBe(0)
+    expect(() => resolveCanvasTarget(project, { id: 'nope' })).toThrow(/clip-0/)
+  })
+
+  it('dodges the playhead grab band so a press on a clip selects instead of scrubbing', () => {
+    const project = makeProject()
+    const centred = canvasItemPoint(project, { type: 'video' })
+    // Park the playhead exactly on the clip's middle — where the press would
+    // otherwise land, and where `grabsPlayhead` would turn it into a scrub.
+    const dodged = canvasItemPoint(project, { type: 'video' }, { playheadTime: 2 })
+    expect(centred.clientX).toBeCloseTo(timeToClientX(project, 2), 6)
+    expect(dodged.clientX - centred.clientX).toBeCloseTo(PLAYHEAD_GRAB_PX + 1, 6)
+  })
+
+  it('honours an explicit `at` time instead of the item middle', () => {
+    const project = makeProject()
+    const point = canvasItemPoint(project, { type: 'video' }, { at: 1 })
+    expect(point.clientX).toBeCloseTo(timeToClientX(project, 1), 6)
+  })
+})
+
+describe('_canvasSelect — selectCanvasItem', () => {
+  it('selects the first item of a kind — the canvas equivalent of clicking "▪ video"', () => {
+    const project = makeProject()
+    const { container, onSelectIds } = mount(project)
+    selectCanvasItem(container, project, { type: 'video' })
+    expect(onSelectIds).toHaveBeenCalledWith(['clip-0'])
+  })
+
+  it('selects by id', () => {
+    const project = makeProject()
+    const { container, onSelectIds } = mount(project)
+    selectCanvasItem(container, project, { id: 'overlay-1' })
+    expect(onSelectIds).toHaveBeenCalledWith(['overlay-1'])
+  })
+
+  it('replaces the selection on a plain click', () => {
+    const project = makeProject()
+    const { container, onSelectIds } = mount(project, ['overlay-1'])
+    selectCanvasItem(container, project, { type: 'video' })
+    expect(onSelectIds).toHaveBeenCalledWith(['clip-0'])
+  })
+
+  it('EXTENDS the selection with metaKey — the modifier the DOM helper used', () => {
+    const project = makeProject()
+    const { container, onSelectIds } = mount(project, ['clip-0'])
+    selectCanvasItem(container, project, { type: 'overlay' }, { metaKey: true })
+    expect(onSelectIds).toHaveBeenCalledWith(['clip-0', 'overlay-1'])
+  })
+
+  it('still selects when the playhead is parked on the clip it is aiming at', () => {
+    const project = makeProject()
+    const { container, onSelectIds } = mount(project, [], 2)
+    selectCanvasItem(container, project, { type: 'video' }, { playheadTime: 2 })
+    expect(onSelectIds).toHaveBeenCalledWith(['clip-0'])
+  })
+
+  it('is a CLICK, not a drag: it never commits an edit', () => {
+    const project = makeProject()
+    const { container, onProjectChange, onOverlayEdit } = mount(project)
+    selectCanvasItem(container, project, { type: 'video' })
+    expect(onProjectChange).not.toHaveBeenCalled()
+    expect(onOverlayEdit).not.toHaveBeenCalled()
+  })
+})
+
+describe('_canvasSelect — dragCanvasItem', () => {
+  it('is a DRAG: many live edits, exactly ONE commit', () => {
+    const project = makeProject()
+    const { container, onProjectChange, onOverlayEdit } = mount(project)
+
+    dragCanvasItem(container, project, { type: 'video' }, { dxPx: 200, steps: 5 })
+
+    // One live edit per intermediate move — the property the "a whole drag
+    // undoes in one step" regression test depends on.
+    expect(onProjectChange.mock.calls.length).toBeGreaterThan(1)
+    expect(onOverlayEdit).toHaveBeenCalledTimes(1)
+
+    const committed = onOverlayEdit.mock.calls[0][0] as Project
+    const moved = trackItems(committed).flat().find((i) => i.id === 'clip-0')
+    expect(moved?.start).toBeGreaterThan(0)
+  })
+
+  it('lands the item near the requested time', () => {
+    const project = makeProject()
+    const { container, onOverlayEdit } = mount(project)
+
+    // The clip's body point sits at its middle (t=2); asking to release two
+    // seconds later moves the whole clip two seconds later.
+    dragCanvasItem(container, project, { type: 'video' }, { toTime: 4 })
+
+    const committed = onOverlayEdit.mock.calls[0][0] as Project
+    const moved = trackItems(committed).flat().find((i) => i.id === 'clip-0')
+    expect(moved?.start).toBeCloseTo(2, 1)
+  })
+
+  it('refuses travel that would never cross the drag threshold', () => {
+    const project = makeProject()
+    const { container, onOverlayEdit } = mount(project)
+    expect(() => dragCanvasItem(container, project, { type: 'video' }, { dxPx: 2 }))
+      .toThrow(/DRAG_THRESHOLD_PX/)
+    // Nothing was dispatched — it bailed before the press.
+    expect(onOverlayEdit).not.toHaveBeenCalled()
+  })
+
+  it('needs a destination', () => {
+    const project = makeProject()
+    const { container } = mount(project)
+    expect(() => dragCanvasItem(container, project, { type: 'video' }, {}))
+      .toThrow(/toTime.*dxPx/)
+  })
+})