@bycrux/editor 0.11.2 → 1.0.1

package/src/video/timeline/__tests__/Timeline.keyframeMenu.test.tsx

@@ -0,0 +1,253 @@
+/// <reference types="vitest/globals" />
+/**
+ * The keyframe-strip popup (SP9b T3.3) — `Timeline.fadeCurveMenu.test.tsx`'s
+ * exact sibling. A right-click on a keyframe-strip diamond (selected,
+ * keyframed overlay only — see hit-test.ts's `'keyframe'` kind) opens a small
+ * menu of the six `EASING_NAMES` plus a "Remove keyframe" action; picking an
+ * easing or removing applies to EVERY prop the diamond represents (the
+ * "union of times" the strip draws — see `keyframe-strip.ts`), as ONE undo
+ * entry.
+ *
+ * `TimelineCanvas`'s `contextmenu` handler does its own hit-test and calls
+ * `onKeyframeMenu` with CLIENT coordinates; `Timeline` owns the menu's
+ * open/closed state and renders it as a `position: fixed` DOM overlay —
+ * mirrors `Timeline.fadeCurveMenu.test.tsx`'s own stubbing (`installCanvasHarness`,
+ * see `_canvasSelect.ts`).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, cleanup, fireEvent, screen } from '@testing-library/react'
+import type { Project } from '../../../types'
+import { createPlaybackClock } from '../../playback-clock'
+import Timeline from '../Timeline'
+import { computeTimelineLayout } from '../canvas/draw'
+import { installCanvasHarness, SURFACE_LEFT, timeToClientX } from './_canvasSelect'
+
+let uninstall: () => void
+
+beforeEach(() => {
+  uninstall = installCanvasHarness()
+})
+
+afterEach(() => {
+  cleanup()
+  uninstall()
+})
+
+/** o0 (2s-4s, overlay) keyframed on offsetX at t=0.5 AND t=1.5, and on
+ *  opacity at t=0.5 only. Union of times is {0.5, 1.5} (`keyframe-strip.ts`'s
+ *  merged strip): the diamond at t=0.5 represents BOTH props (used to prove
+ *  an action fans out to every prop sharing an instant), the diamond at
+ *  t=1.5 represents offsetX alone AND is the item's LAST keyframe (used for
+ *  the disabled-easing-picker test). */
+function makeProject(): Project {
+  return {
+    id: 'p1',
+    status: 'draft',
+    settings: { resolution: [1080, 1920], fps: 30 },
+    tracks: [{
+      id: 'trk-0',
+      items: [{
+        id: 'o0', type: 'overlay', start: 2, end: 4,
+        keyframes: [
+          { prop: 'offsetX', points: [{ t: 0.5, value: 0 }, { t: 1.5, value: 10 }] },
+          { prop: 'opacity', points: [{ t: 0.5, value: 1 }] },
+        ],
+      }],
+    }],
+  } as unknown as Project
+}
+
+function mount(project: Project = makeProject()) {
+  const clock = createPlaybackClock()
+  const onProjectChange = vi.fn()
+  const onOverlayEdit = vi.fn()
+  const utils = render(
+    <Timeline
+      project={project}
+      clock={clock}
+      onProjectChange={onProjectChange}
+      onOverlayEdit={onOverlayEdit}
+      selectedIds={['o0']}
+    />,
+  )
+  const surface = utils.container.querySelector('[data-timeline-canvas]') as HTMLElement
+  return { clock, onProjectChange, onOverlayEdit, surface, project, ...utils }
+}
+
+/** CLIENT (x, y) for the diamond at item-relative `t` on `project`'s o0,
+ *  computed the same way `hit-test.ts`'s keyframe zone does: `item.start + t`
+ *  through `timeToClientX` — the SAME fit-to-view viewport the mounted
+ *  surface settles to on render — at a y a couple px above the row's own
+ *  bottom edge (inside the bottom strip zone the diamond hit-tests in). */
+function keyframeClientPoint(project: Project, t: number) {
+  const row = computeTimelineLayout(project).rows[0]
+  const clientX = timeToClientX(project, 2 + t)   // o0.start is 2
+  return { clientX, clientY: row.y + row.height - 2 }
+}
+
+/** Easing buttons render VISIBLE text (unlike the icon-only fade picker), so
+ *  their accessible name is that text — same `getByRole` lookup either way. */
+function easingButton(name: string) {
+  return screen.getByRole('button', { name })
+}
+function queryEasingButton(name: string) {
+  return screen.queryByRole('button', { name })
+}
+function removeButton() {
+  return screen.getByRole('button', { name: 'Remove keyframe' })
+}
+
+describe('Timeline — keyframe-strip popup (right-click a keyframe diamond)', () => {
+  it('opens the picker with all six easing options and a remove action on a diamond right-click', () => {
+    const { surface, project } = mount()
+    fireEvent.contextMenu(surface, keyframeClientPoint(project, 0.5))
+    for (const name of ['Linear', 'Ease', 'Ease In', 'Ease Out', 'Ease In Out', 'Hold']) {
+      expect(easingButton(name)).toBeInTheDocument()
+    }
+    expect(removeButton()).toBeInTheDocument()
+  })
+
+  it('does NOT open the picker from a right-click elsewhere on the clip', () => {
+    const { surface, project } = mount()
+    // Same x as a diamond, but well above the strip's bottom zone.
+    const row = computeTimelineLayout(project).rows[0]
+    fireEvent.contextMenu(surface, { clientX: SURFACE_LEFT + 300, clientY: row.y + 2 })
+    expect(queryEasingButton('Linear')).not.toBeInTheDocument()
+  })
+
+  it('picking an easing applies it to every prop sharing the diamond’s t, as ONE undo entry, and closes the menu', () => {
+    const { surface, onProjectChange, onOverlayEdit, project } = mount()
+    fireEvent.contextMenu(surface, keyframeClientPoint(project, 0.5))
+
+    fireEvent.click(easingButton('Ease In'))
+
+    expect(onProjectChange).toHaveBeenCalledTimes(1)
+    expect(onOverlayEdit).toHaveBeenCalledTimes(1)
+    const committed = onOverlayEdit.mock.calls[0][0] as Project
+    const item = committed.tracks![0].items[0]
+    const offsetX = item.keyframes!.find(t => t.prop === 'offsetX')!
+    const opacity = item.keyframes!.find(t => t.prop === 'opacity')!
+    expect(offsetX.points.find(p => p.t === 0.5)?.easing).toBe('ease-in')
+    expect(opacity.points.find(p => p.t === 0.5)?.easing).toBe('ease-in')
+    // The OTHER keyframe on offsetX (t=1.5) is untouched.
+    expect(offsetX.points.find(p => p.t === 1.5)?.easing).toBeUndefined()
+    expect(queryEasingButton('Linear')).not.toBeInTheDocument()
+  })
+
+  it('removing clears every prop at that t, dropping a track entirely once it has no points left', () => {
+    const { surface, onProjectChange, onOverlayEdit, project } = mount()
+    fireEvent.contextMenu(surface, keyframeClientPoint(project, 0.5))
+
+    fireEvent.click(removeButton())
+
+    expect(onProjectChange).toHaveBeenCalledTimes(1)
+    expect(onOverlayEdit).toHaveBeenCalledTimes(1)
+    const committed = onOverlayEdit.mock.calls[0][0] as Project
+    const item = committed.tracks![0].items[0]
+    // offsetX keeps its OTHER point (t=1.5); its t=0.5 point is gone.
+    const offsetX = item.keyframes!.find(t => t.prop === 'offsetX')!
+    expect(offsetX.points.map(p => p.t)).toEqual([1.5])
+    // opacity had ONLY the t=0.5 point — the whole track is gone, not just
+    // emptied (see keyframeOps.ts's `removeKeyframe`/`withTrack`).
+    expect(item.keyframes!.find(t => t.prop === 'opacity')).toBeUndefined()
+    expect(queryEasingButton('Linear')).not.toBeInTheDocument()
+  })
+
+  it('disables the easing picker on the LAST diamond, but removal still works there', () => {
+    const { surface, onProjectChange, onOverlayEdit, project } = mount()
+    // t=1.5 is offsetX's last (and only remaining) keyframe once t=0.5 is
+    // accounted for by the fixture — the item's overall last keyframe too.
+    fireEvent.contextMenu(surface, keyframeClientPoint(project, 1.5))
+
+    expect(easingButton('Linear')).toBeDisabled()
+    expect(easingButton('Hold')).toBeDisabled()
+    fireEvent.click(easingButton('Linear'))
+    // Disabled buttons don't fire clicks — nothing committed.
+    expect(onProjectChange).not.toHaveBeenCalled()
+
+    fireEvent.click(removeButton())
+    expect(onProjectChange).toHaveBeenCalledTimes(1)
+    expect(onOverlayEdit).toHaveBeenCalledTimes(1)
+    const committed = onOverlayEdit.mock.calls[0][0] as Project
+    const item = committed.tracks![0].items[0]
+    const offsetX = item.keyframes!.find(t => t.prop === 'offsetX')!
+    expect(offsetX.points.map(p => p.t)).toEqual([0.5])
+  })
+
+  it('highlights the shared easing when every prop at t agrees, and none when they disagree', () => {
+    const project = makeProject()
+    // Pre-set offsetX and opacity's t=0.5 points to the SAME easing.
+    project.tracks![0].items[0].keyframes![0].points[0].easing = 'hold'
+    project.tracks![0].items[0].keyframes![1].points[0].easing = 'hold'
+    const { surface } = mount(project)
+    fireEvent.contextMenu(surface, keyframeClientPoint(project, 0.5))
+    expect(easingButton('Hold')).toHaveAttribute('aria-pressed', 'true')
+    expect(easingButton('Linear')).toHaveAttribute('aria-pressed', 'false')
+
+    fireEvent.click(screen.getByTestId('keyframe-menu-backdrop'))
+
+    // Now disagree: offsetX stays 'hold', opacity becomes 'ease'.
+    const disagreeing = makeProject()
+    disagreeing.tracks![0].items[0].keyframes![0].points[0].easing = 'hold'
+    disagreeing.tracks![0].items[0].keyframes![1].points[0].easing = 'ease'
+    const remount = mount(disagreeing)
+    fireEvent.contextMenu(remount.surface, keyframeClientPoint(disagreeing, 0.5))
+    for (const name of ['Linear', 'Ease', 'Ease In', 'Ease Out', 'Ease In Out', 'Hold']) {
+      expect(easingButton(name)).toHaveAttribute('aria-pressed', 'false')
+    }
+  })
+
+  it('Escape closes the picker without committing anything', () => {
+    const { surface, onProjectChange, onOverlayEdit, project } = mount()
+    fireEvent.contextMenu(surface, keyframeClientPoint(project, 0.5))
+    expect(easingButton('Linear')).toBeInTheDocument()
+
+    fireEvent.keyDown(document, { key: 'Escape' })
+
+    expect(queryEasingButton('Linear')).not.toBeInTheDocument()
+    expect(onProjectChange).not.toHaveBeenCalled()
+    expect(onOverlayEdit).not.toHaveBeenCalled()
+  })
+
+  it('clicking outside the menu closes it without touching the project', () => {
+    const { surface, onProjectChange, onOverlayEdit, project } = mount()
+    fireEvent.contextMenu(surface, keyframeClientPoint(project, 0.5))
+    expect(easingButton('Linear')).toBeInTheDocument()
+
+    fireEvent.click(screen.getByTestId('keyframe-menu-backdrop'))
+
+    expect(queryEasingButton('Linear')).not.toBeInTheDocument()
+    expect(onProjectChange).not.toHaveBeenCalled()
+    expect(onOverlayEdit).not.toHaveBeenCalled()
+  })
+
+  it('freezes the value when the removed keyframe was a track\'s LAST point', () => {
+    // Plain `removeKeyframe` drops the track WITHOUT writing the sampled value
+    // into the static scalar, so the overlay would snap back to the stale
+    // `opacity: 0.1`. Both removal paths share `removeKeyframesAt` precisely so
+    // this menu and Delete cannot disagree.
+    const base = makeProject()
+    const stale = {
+      ...base,
+      tracks: [{
+        ...base.tracks![0],
+        items: [{
+          ...base.tracks![0].items[0],
+          opacity: 0.1,
+          keyframes: [
+            { prop: 'offsetX', points: [{ t: 0.5, value: 0 }, { t: 1.5, value: 10 }] },
+            { prop: 'opacity', points: [{ t: 0.5, value: 0.4 }] },
+          ],
+        }],
+      }],
+    } as unknown as Project
+    const { surface, onOverlayEdit, project } = mount(stale)
+    fireEvent.contextMenu(surface, keyframeClientPoint(project, 0.5))
+
+    fireEvent.click(removeButton())
+
+    const item = (onOverlayEdit.mock.calls[0][0] as Project).tracks![0].items[0]
+    expect(item.keyframes!.find(t => t.prop === 'opacity')).toBeUndefined()
+    expect(item.opacity).toBeCloseTo(0.4, 5)   // the curve's value, NOT the stale 0.1
+  })
+})

package/src/video/timeline/__tests__/Timeline.keymap.test.tsx

@@ -0,0 +1,372 @@
+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, { type TimelineActions } from '../Timeline'
+import { installCanvasHarness } from './_canvasSelect'
+
+// SP5 — the DOM timeline is retired, so every Timeline mount is a canvas one
+// and needs the canvas harness (stubbed getContext/getBoundingClientRect) even
+// though none of these tests click or drag — TimelineCanvas paints on mount.
+let uninstallCanvasHarness: () => void
+beforeEach(() => { uninstallCanvasHarness = installCanvasHarness() })
+afterEach(() => {
+  cleanup()
+  uninstallCanvasHarness()
+})
+
+function makeProject(): Project {
+  return {
+    id: 'p1',
+    status: 'draft',
+    settings: { resolution: [1080, 1920], fps: 10 }, // 10fps -> 0.1s frame step, easy to assert
+    tracks: [[{ id: 'clip-0', type: 'video', src: 'a.mp4', start: 0, end: 4, inPoint: 0, outPoint: 4 }]],
+  } as unknown as Project
+}
+
+function makeProjectWithCaptions(): Project {
+  return {
+    ...makeProject(),
+    captions: {
+      style: 'clean',
+      segments: [
+        { id: 'cap-0', text: 'hello', start: 0, end: 1 },
+        { id: 'cap-1', text: 'world', start: 1, end: 2 },
+      ],
+    },
+  } as unknown as Project
+}
+
+/** Delete/Enter are focus-scoped to Timeline's own root (the `tabIndex={0}`
+ *  container), mirroring pre-SP5 behavior — unlike arrows/Escape, which stay
+ *  document-level. Timeline's root is the outermost DOM node it renders
+ *  (`TimelineContext.Provider` contributes no element of its own), so it's
+ *  always `container.firstElementChild` in these tests. */
+function focusTimelineRoot(container: HTMLElement) {
+  (container.firstElementChild as HTMLElement).focus()
+}
+
+describe('Timeline — T9 keymap (arrows / delete / enter / escape)', () => {
+  it('ArrowRight steps the clock forward by one frame on a plain target', () => {
+    const clock = createPlaybackClock(0)
+    render(<Timeline project={makeProject()} clock={clock} />)
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowRight' }) })
+    expect(clock.get()).toBeCloseTo(0.1, 5)
+  })
+
+  // Shift is TEN FRAMES, not one second. At this fixture's 10fps the two
+  // happen to coincide at 1.0s, so both directions are asserted at a second
+  // fps below where they diverge — otherwise the old wall-clock behaviour
+  // would pass this test unchanged.
+  it('Shift+ArrowRight steps ten frames forward, and Shift+ArrowLeft ten back', () => {
+    const clock = createPlaybackClock(2)
+    render(<Timeline project={makeProject()} clock={clock} />)
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowRight', shiftKey: true }) })
+    expect(clock.get()).toBeCloseTo(3, 5)
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowLeft', shiftKey: true }) })
+    expect(clock.get()).toBeCloseTo(2, 5)
+  })
+
+  it('the shifted step is ten FRAMES, so it scales with fps rather than being a flat second', () => {
+    const clock = createPlaybackClock(2)
+    const project = makeProject()
+    render(<Timeline project={{ ...project, settings: { ...project.settings!, fps: 25 } }} clock={clock} />)
+    // 10 frames at 25fps is 0.4s. The old `shiftKey ? 1` would give 3.0.
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowRight', shiftKey: true }) })
+    expect(clock.get()).toBeCloseTo(2.4, 5)
+  })
+
+  // Content end = the furthest item's end across ALL clips/overlays/audio
+  // (`contentDuration` from computeDerivedTiming), not the zoom/scroll
+  // headroom-padded `totalDuration`. This fixture's video track ends at 4s,
+  // but a later audio track pushes the real content end out to 7s — proving
+  // the jump lands on the furthest ELEMENT, not just the longest video clip.
+  // totalDuration would pad that out further still (7 + max(5, 7*0.2) = 12),
+  // so asserting 7 (not 12, not 4) pins down both distinctions at once.
+  function makeProjectWithFurtherAudio(): Project {
+    const project = makeProject()
+    return {
+      ...project,
+      audio: { tracks: [{ id: 'a0', src: 'v.mp3', start: 5, end: 7, lane: 0 }] },
+    } as unknown as Project
+  }
+
+  it('Cmd/Ctrl+ArrowLeft jumps the playhead to the start (0)', () => {
+    const clock = createPlaybackClock(3)
+    render(<Timeline project={makeProjectWithFurtherAudio()} clock={clock} />)
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowLeft', metaKey: true }) })
+    expect(clock.get()).toBe(0)
+  })
+
+  it('Ctrl+ArrowLeft (non-Mac mod) also jumps to the start', () => {
+    const clock = createPlaybackClock(3)
+    render(<Timeline project={makeProjectWithFurtherAudio()} clock={clock} />)
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowLeft', ctrlKey: true }) })
+    expect(clock.get()).toBe(0)
+  })
+
+  it('Cmd/Ctrl+ArrowRight jumps the playhead to the content end (furthest element, not headroom)', () => {
+    const clock = createPlaybackClock(0)
+    render(<Timeline project={makeProjectWithFurtherAudio()} clock={clock} />)
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowRight', metaKey: true }) })
+    // 7, not 4 (the video clip alone) and not 12 (totalDuration's headroom).
+    expect(clock.get()).toBe(7)
+  })
+
+  it('a plain ArrowLeft/ArrowRight still frame-steps and does NOT jump, even with the further-audio fixture', () => {
+    const clock = createPlaybackClock(2)
+    render(<Timeline project={makeProjectWithFurtherAudio()} clock={clock} />)
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowRight' }) })
+    expect(clock.get()).toBeCloseTo(2.1, 5)
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowLeft' }) })
+    expect(clock.get()).toBeCloseTo(2, 5)
+  })
+
+  it('Cmd+ArrowLeft/Right does not ALSO fire the frame-step binding (no double-action)', () => {
+    const clock = createPlaybackClock(3)
+    render(<Timeline project={makeProjectWithFurtherAudio()} clock={clock} />)
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowRight', metaKey: true }) })
+    // If frame-step also fired, this would be 7 + 0.1 instead of 7.
+    expect(clock.get()).toBe(7)
+  })
+
+  it('Cmd/Ctrl+Arrow jump is inert on an empty project (guard: totalDuration > 0)', () => {
+    const clock = createPlaybackClock(0)
+    const emptyProject = { ...makeProject(), tracks: [] } as unknown as Project
+    render(<Timeline project={emptyProject} clock={clock} />)
+    act(() => { fireEvent.keyDown(document.body, { key: 'ArrowRight', metaKey: true }) })
+    expect(clock.get()).toBe(0)
+  })
+
+  it('does not step when the target is an input', () => {
+    const clock = createPlaybackClock(0)
+    const { container } = render(
+      <div>
+        <input data-testid="somewhere-else" />
+        <Timeline project={makeProject()} clock={clock} />
+      </div>,
+    )
+    const input = container.querySelector('input') as HTMLInputElement
+    fireEvent.keyDown(input, { key: 'ArrowRight' })
+    expect(clock.get()).toBe(0)
+  })
+
+  it('does not step when `modalOpen` is true (a host-level dialog is up)', () => {
+    const clock = createPlaybackClock(0)
+    render(<Timeline project={makeProject()} clock={clock} modalOpen />)
+    fireEvent.keyDown(document.body, { key: 'ArrowRight' })
+    expect(clock.get()).toBe(0)
+  })
+
+  // Enter and Escape used to place and clear the A/B range markers. That
+  // feature is gone, so the timeline binds neither: pressing them with the
+  // timeline focused must not move the playhead or touch the project.
+  it('Enter and Escape are not bound', () => {
+    const clock = createPlaybackClock(2)
+    const onProjectChange = vi.fn()
+    const { container } = render(
+      <Timeline project={makeProject()} clock={clock} onProjectChange={onProjectChange} />,
+    )
+    focusTimelineRoot(container)
+    fireEvent.keyDown(document.body, { key: 'Enter' })
+    fireEvent.keyDown(document.body, { key: 'Escape' })
+    expect(clock.get()).toBe(2)
+    expect(onProjectChange).not.toHaveBeenCalled()
+  })
+
+  it('Delete/Backspace two-step delete: fires only with a selection, commits via onProjectChange + onOverlayEdit + clears selection', () => {
+    const clock = createPlaybackClock(0)
+    const onProjectChange = vi.fn()
+    const onOverlayEdit = vi.fn()
+    const onSelectIds = vi.fn()
+    const { container } = render(
+      <Timeline
+        project={makeProject()}
+        clock={clock}
+        selectedIds={['clip-0']}
+        onSelectIds={onSelectIds}
+        onProjectChange={onProjectChange}
+        onOverlayEdit={onOverlayEdit}
+      />,
+    )
+    focusTimelineRoot(container)
+    fireEvent.keyDown(document.body, { key: 'Delete' })
+    expect(onProjectChange).toHaveBeenCalledTimes(1)
+    expect(onOverlayEdit).toHaveBeenCalledTimes(1)
+    expect(onSelectIds).toHaveBeenCalledWith([])
+    const updated = onProjectChange.mock.calls[0][0] as Project
+    expect(updated.tracks?.[0]?.items.find((i) => i.id === 'clip-0')).toBeUndefined()
+  })
+
+  // D1: a caption id can sit in `selectedIds` alongside a clip id (selected on
+  // the canvas timeline like any other item — see Timeline.tsx's
+  // handleSelectItem). `deleteSelection` only knows tracks/audio vocabulary, so
+  // the keymap action must strip selected caption segments itself, folded into
+  // the SAME onProjectChange/onOverlayEdit commit as the clip delete — one undo
+  // entry covering the mixed selection, not two.
+  it('Delete strips a selected caption segment AND a selected clip in one commit', () => {
+    const clock = createPlaybackClock(0)
+    const onProjectChange = vi.fn()
+    const onOverlayEdit = vi.fn()
+    const onSelectIds = vi.fn()
+    const { container } = render(
+      <Timeline
+        project={makeProjectWithCaptions()}
+        clock={clock}
+        selectedIds={['clip-0', 'cap-0']}
+        onSelectIds={onSelectIds}
+        onProjectChange={onProjectChange}
+        onOverlayEdit={onOverlayEdit}
+      />,
+    )
+    focusTimelineRoot(container)
+    fireEvent.keyDown(document.body, { key: 'Delete' })
+    expect(onProjectChange).toHaveBeenCalledTimes(1)
+    expect(onOverlayEdit).toHaveBeenCalledTimes(1)
+    expect(onSelectIds).toHaveBeenCalledWith([])
+    const updated = onProjectChange.mock.calls[0][0] as Project
+    expect(updated.tracks?.[0]?.items.find((i) => i.id === 'clip-0')).toBeUndefined()
+    expect(updated.captions?.segments.map((s) => s.id)).toEqual(['cap-1'])
+  })
+
+  // Deleting every remaining caption segment must leave `captions` as an
+  // empty-segments object, not null the whole track — nulling it is the
+  // sidebar's explicit "Remove all" action, not a side effect of Delete.
+  it('Delete leaves an empty captions object when the last segment is removed, never nulls the track', () => {
+    const clock = createPlaybackClock(0)
+    const onProjectChange = vi.fn()
+    const project = makeProjectWithCaptions()
+    project.captions!.segments = [{ id: 'cap-0', text: 'hello', start: 0, end: 1 }]
+    const { container } = render(
+      <Timeline
+        project={project}
+        clock={clock}
+        selectedIds={['cap-0']}
+        onSelectIds={vi.fn()}
+        onProjectChange={onProjectChange}
+      />,
+    )
+    focusTimelineRoot(container)
+    fireEvent.keyDown(document.body, { key: 'Delete' })
+    const updated = onProjectChange.mock.calls[0][0] as Project
+    expect(updated.captions).not.toBeNull()
+    expect(updated.captions?.segments).toEqual([])
+  })
+
+  // Caption rows: emptying one leaves a HOLE lane, and the row has to collapse
+  // in the SAME commit as the delete that emptied it — otherwise the operator's
+  // Cmd-Z brings the caption back but leaves the row renumbering behind (or
+  // undoes it separately, one keystroke later).
+  it('Delete collapses and renumbers a caption row it empties, in the same commit', () => {
+    const clock = createPlaybackClock(0)
+    const onProjectChange = vi.fn()
+    const onOverlayEdit = vi.fn()
+    const project = {
+      ...makeProject(),
+      captions: {
+        style: 'clean',
+        segments: [
+          { id: 'cap-0', text: 'ground', start: 0, end: 1 },              // lane 0
+          { id: 'cap-1', text: 'middle', start: 0, end: 1, lane: 1 },     // lane 1, alone
+          { id: 'cap-2', text: 'top', start: 0, end: 1, lane: 2 },        // lane 2
+        ],
+      },
+    } as unknown as Project
+    const { container } = render(
+      <Timeline
+        project={project}
+        clock={clock}
+        selectedIds={['cap-1']}
+        onSelectIds={vi.fn()}
+        onProjectChange={onProjectChange}
+        onOverlayEdit={onOverlayEdit}
+      />,
+    )
+    focusTimelineRoot(container)
+    fireEvent.keyDown(document.body, { key: 'Delete' })
+    // ONE commit — the strip and the renumbering are a single undo entry.
+    expect(onProjectChange).toHaveBeenCalledTimes(1)
+    expect(onOverlayEdit).toHaveBeenCalledTimes(1)
+    const updated = onProjectChange.mock.calls[0][0] as Project
+    expect(updated.captions?.segments.map((s) => s.id)).toEqual(['cap-0', 'cap-2'])
+    // cap-2 was on lane 2 with a hole below it; it drops into the vacated row.
+    expect(updated.captions?.segments.map((s) => s.lane ?? 0)).toEqual([0, 1])
+  })
+
+  it('Delete leaves the other rows alone when the row it empties is the TOP one', () => {
+    // Removing the highest lane leaves no hole, so nothing renumbers.
+    const clock = createPlaybackClock(0)
+    const onProjectChange = vi.fn()
+    const project = {
+      ...makeProject(),
+      captions: {
+        style: 'clean',
+        segments: [
+          { id: 'cap-0', text: 'ground', start: 0, end: 1 },
+          { id: 'cap-1', text: 'top', start: 0, end: 1, lane: 1 },
+        ],
+      },
+    } as unknown as Project
+    const { container } = render(
+      <Timeline
+        project={project}
+        clock={clock}
+        selectedIds={['cap-1']}
+        onSelectIds={vi.fn()}
+        onProjectChange={onProjectChange}
+      />,
+    )
+    focusTimelineRoot(container)
+    fireEvent.keyDown(document.body, { key: 'Delete' })
+    const updated = onProjectChange.mock.calls[0][0] as Project
+    expect(updated.captions?.segments.map((s) => s.id)).toEqual(['cap-0'])
+    expect(updated.captions?.segments[0].lane).toBeUndefined()
+  })
+
+  it('Delete does NOT delete the selection when focus is outside the timeline (restored pre-SP5 scoping)', () => {
+    const clock = createPlaybackClock(0)
+    const onProjectChange = vi.fn()
+    render(
+      <Timeline
+        project={makeProject()}
+        clock={clock}
+        selectedIds={['clip-0']}
+        onProjectChange={onProjectChange}
+      />,
+    )
+    // Focus left on document.body (or anywhere outside Timeline's own root) —
+    // never inside the timeline. T9 briefly widened Delete/Enter to fire from
+    // anywhere on the page; this proves that regression stays fixed.
+    ;(document.body as HTMLElement).focus()
+    fireEvent.keyDown(document.body, { key: 'Delete' })
+    expect(onProjectChange).not.toHaveBeenCalled()
+  })
+
+  it('Delete with no selection is a no-op', () => {
+    const clock = createPlaybackClock(0)
+    const onProjectChange = vi.fn()
+    render(<Timeline project={makeProject()} clock={clock} onProjectChange={onProjectChange} />)
+    fireEvent.keyDown(document.body, { key: 'Delete' })
+    expect(onProjectChange).not.toHaveBeenCalled()
+  })
+
+  it('Shift+Delete does NOT trigger Timeline\'s own delete binding (reserved for ripple-delete upstream)', () => {
+    const clock = createPlaybackClock(0)
+    const onProjectChange = vi.fn()
+    render(
+      <Timeline project={makeProject()} clock={clock} selectedIds={['clip-0']} onProjectChange={onProjectChange} />,
+    )
+    fireEvent.keyDown(document.body, { key: 'Delete', shiftKey: true })
+    expect(onProjectChange).not.toHaveBeenCalled()
+  })
+
+  it('exposes zoomFit through actionsRef for a host-level palette', () => {
+    const clock = createPlaybackClock(1)
+    const actionsRef: { current: TimelineActions | null } = { current: null }
+    render(<Timeline project={makeProject()} clock={clock} actionsRef={actionsRef} />)
+    expect(actionsRef.current).not.toBeNull()
+    act(() => { actionsRef.current!.zoomFit() })
+    // Smoke test: it doesn't throw, and the ref stays populated.
+    expect(actionsRef.current).not.toBeNull()
+  })
+})