@bycrux/editor 0.12.0 → 1.0.1

package/src/video/__tests__/clipboard-ops.test.ts

@@ -0,0 +1,430 @@
+import { describe, it, expect } from 'vitest'
+import { copySelection, pasteAt, duplicateSelection, pasteAttributes } from '../clipboard-ops'
+import type { EditorProject as Project, VisualItem, VisualTrack, AudioTrack } from '../../schema'
+
+/** Object-shape visual tracks, carrying the ids `normalizeTracks` would hand
+ *  out — mirrors `cuts.test.ts`'s `vtracks` helper. */
+function vtracks(...items: VisualItem[][]): VisualTrack[] {
+  return items.map((its, i) => ({ id: `trk-${i}`, items: its }))
+}
+
+// Minimal project factory — only the fields the clipboard ops touch.
+function makeProject(over: Partial<Project> = {}): Project {
+  return {
+    id: 'p1',
+    status: 'draft',
+    settings: { resolution: [1080, 1920] },
+    tracks: vtracks([]),
+    ...over,
+  }
+}
+
+describe('copySelection', () => {
+  it('returns null for an empty selection', () => {
+    const p = makeProject({ tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5 }]) })
+    expect(copySelection(p, [])).toBeNull()
+  })
+
+  it('returns null when selectedIds names only caption ids', () => {
+    const p = makeProject({
+      tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5 }]),
+      captions: { style: 'subtitle', segments: [{ id: 'c1', text: 'hi', start: 0, end: 1 }] },
+    })
+    expect(copySelection(p, ['c1'])).toBeNull()
+  })
+
+  it('captures visual items with their source track id, deep-cloned', () => {
+    const item: VisualItem = { id: 'a', type: 'video', start: 0, end: 5, inPoint: 0, outPoint: 5 }
+    const p = makeProject({ tracks: vtracks([item]) })
+    const payload = copySelection(p, ['a'])
+    expect(payload).not.toBeNull()
+    expect(payload!.items).toEqual([{ item, sourceTrackId: 'trk-0' }])
+    expect(payload!.items[0].item).not.toBe(item) // deep clone, not the same reference
+  })
+
+  it('captures audio tracks, deep-cloned', () => {
+    const track: AudioTrack = { id: 'aud1', src: 'x.mp3', start: 0, end: 5 }
+    const p = makeProject({ audio: { tracks: [track] } })
+    const payload = copySelection(p, ['aud1'])
+    expect(payload!.audioTracks).toEqual([track])
+    expect(payload!.audioTracks[0]).not.toBe(track)
+  })
+
+  it('drops caption ids from a mixed selection, keeping only the visual item', () => {
+    const p = makeProject({
+      tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5 }]),
+      captions: { style: 'subtitle', segments: [{ id: 'c1', text: 'hi', start: 0, end: 1 }] },
+    })
+    const payload = copySelection(p, ['a', 'c1'])!
+    expect(payload.items).toHaveLength(1)
+    expect(payload.items[0].item.id).toBe('a')
+    expect(payload.audioTracks).toHaveLength(0)
+  })
+})
+
+describe('pasteAt', () => {
+  it('returns the same project reference for a null payload', () => {
+    const p = makeProject()
+    expect(pasteAt(p, null, 5)).toBe(p)
+  })
+
+  it('returns the same project reference for an empty payload', () => {
+    const p = makeProject()
+    expect(pasteAt(p, { items: [], audioTracks: [] }, 5)).toBe(p)
+  })
+
+  it('pastes a single item verbatim at the anchor with a fresh id', () => {
+    const p = makeProject({
+      tracks: vtracks([
+        { id: 'a', type: 'video', start: 0, end: 5, inPoint: 2, outPoint: 7, volume: 0.5 },
+      ]),
+    })
+    const payload = copySelection(p, ['a'])!
+    const out = pasteAt(p, payload, 20)
+    const items = out.tracks![0].items
+    expect(items).toHaveLength(2)
+    const pasted = items.find(i => i.id !== 'a')!
+    expect(pasted.id).not.toBe('a')
+    expect(pasted).toMatchObject({ type: 'video', start: 20, end: 25, inPoint: 2, outPoint: 7, volume: 0.5 })
+  })
+
+  it('preserves relative offsets across multiple pasted items, earliest at the anchor', () => {
+    const p = makeProject({
+      tracks: vtracks([
+        { id: 'a', type: 'video', start: 0, end: 5 },
+        { id: 'b', type: 'video', start: 10, end: 12 },
+      ]),
+    })
+    const payload = copySelection(p, ['a', 'b'])!
+    const out = pasteAt(p, payload, 100)
+    const items = out.tracks![0].items
+    expect(items.some(i => i.id !== 'a' && i.id !== 'b' && i.start === 100 && i.end === 105)).toBe(true)
+    expect(items.some(i => i.id !== 'a' && i.id !== 'b' && i.start === 110 && i.end === 112)).toBe(true)
+  })
+
+  it('lands back on the source track when it still exists', () => {
+    const p = makeProject({
+      tracks: vtracks(
+        [{ id: 'a', type: 'video', start: 0, end: 5 }],
+        [{ id: 'b', type: 'overlay', start: 0, end: 5 }],
+      ),
+    })
+    const payload = copySelection(p, ['b'])!
+    const out = pasteAt(p, payload, 20)
+    expect(out.tracks![0].items).toHaveLength(1) // track 0 untouched
+    expect(out.tracks![1].items).toHaveLength(2) // pasted back onto trk-1
+  })
+
+  it('falls back to track 0 when the source track no longer exists', () => {
+    const item: VisualItem = { id: 'a', type: 'video', start: 0, end: 5 }
+    const source = makeProject({ tracks: vtracks([], [item]) })
+    const payload = copySelection(source, ['a'])!
+    expect(payload.items[0].sourceTrackId).toBe('trk-1')
+
+    // Paste into a DIFFERENT project that has no trk-1 at all.
+    const target = makeProject({ tracks: vtracks([{ id: 'x', type: 'video', start: 0, end: 3 }]) })
+    const out = pasteAt(target, payload, 50)
+    expect(out.tracks).toHaveLength(1)
+    const ids = out.tracks![0].items.map(i => i.id)
+    expect(ids).toContain('x')
+    expect(out.tracks![0].items).toHaveLength(2)
+  })
+
+  it('shifts right to the earliest gap that fits when the target span collides', () => {
+    const p = makeProject({
+      tracks: vtracks([
+        { id: 'a', type: 'video', start: 0, end: 5 },
+        { id: 'blocker', type: 'video', start: 10, end: 13 },
+      ]),
+    })
+    const payload = copySelection(p, ['a'])! // duration 5
+    const out = pasteAt(p, payload, 10) // collides with blocker (10-13)
+    const pasted = out.tracks![0].items.find(i => i.id !== 'a' && i.id !== 'blocker')!
+    expect(pasted.start).toBe(13) // earliest fitting gap: blocker's end
+    expect(pasted.end).toBe(18)
+  })
+
+  it('does not materialize an empty `audio` object when pasting visual-only items into an audio-less project', () => {
+    const p = makeProject({
+      tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5 }]),
+      // No `audio` key at all.
+    })
+    expect(p.audio).toBeUndefined()
+    const payload = copySelection(p, ['a'])!
+    const out = pasteAt(p, payload, 20)
+    expect(out.audio).toBeUndefined()
+  })
+
+  it('still attaches `audio` when the paste itself adds audio tracks, even starting from an audio-less project', () => {
+    const source = makeProject({ audio: { tracks: [{ id: 'aud1', src: 'x.mp3', start: 0, end: 4 }] } })
+    const payload = copySelection(source, ['aud1'])!
+    const target = makeProject() // no `audio` key
+    const out = pasteAt(target, payload, 10)
+    expect(out.audio!.tracks).toHaveLength(1)
+    expect(out.audio!.tracks[0]).toMatchObject({ src: 'x.mp3', start: 10, end: 14 })
+  })
+
+  it('preserves an existing (possibly empty-after-paste) `audio` object rather than dropping it', () => {
+    const p = makeProject({
+      tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5 }]),
+      audio: { tracks: [] },
+    })
+    const payload = copySelection(p, ['a'])!
+    const out = pasteAt(p, payload, 20)
+    expect(out.audio).toEqual({ tracks: [] })
+  })
+
+  it('clones an audio track verbatim with a fresh id, shifted to the anchor', () => {
+    const track: AudioTrack = { id: 'aud1', src: 'x.mp3', start: 0, end: 4, volume: 0.8, muted: true }
+    const p = makeProject({ audio: { tracks: [track] } })
+    const payload = copySelection(p, ['aud1'])!
+    const out = pasteAt(p, payload, 30)
+    const pasted = out.audio!.tracks.find(t => t.id !== 'aud1')!
+    expect(pasted).toMatchObject({ src: 'x.mp3', start: 30, end: 34, volume: 0.8, muted: true })
+    expect(pasted.id).not.toBe('aud1')
+  })
+
+  it('gap-resolves a pasted audio track against its OWN lane only, not every audio track flattened', () => {
+    // Music bed (lane 0) runs the whole timeline; voiceover (lane 1) is much
+    // shorter and overlaps it freely, as parallel lanes are meant to. Pasting
+    // a copy of the voiceover back at t=0 collides with the ORIGINAL voiceover
+    // (same lane, still on the timeline) and must resolve to its end (30) —
+    // NOT past the bed's end (60), which the old flattened check wrongly used.
+    const bed: AudioTrack = { id: 'bed', src: 'bed.mp3', start: 0, end: 60, lane: 0 }
+    const vo: AudioTrack = { id: 'vo', src: 'vo.mp3', start: 0, end: 30, lane: 1 }
+    const p = makeProject({ audio: { tracks: [bed, vo] } })
+    const payload = copySelection(p, ['vo'])!
+    const out = pasteAt(p, payload, 0)
+    const pasted = out.audio!.tracks.find(t => t.id !== 'bed' && t.id !== 'vo')!
+    expect(pasted.start).toBe(30) // shifted past the original voiceover, lane 1's only occupant
+    expect(pasted.end).toBe(60)
+    expect(pasted.lane).toBe(1)
+  })
+
+  it('preserves the original relative offset between a visual item and an audio track pasted together, earliest landing exactly on the anchor', () => {
+    const p = makeProject({
+      tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5 }]),
+      audio: { tracks: [{ id: 'aud1', src: 'x.mp3', start: 20, end: 23 }] }, // 20s gap from the visual item
+    })
+    const payload = copySelection(p, ['a', 'aud1'])!
+    const out = pasteAt(p, payload, 100)
+
+    const pastedVisual = out.tracks![0].items.find(i => i.id !== 'a')!
+    const pastedAudio = out.audio!.tracks.find(t => t.id !== 'aud1')!
+
+    expect(pastedVisual.start).toBe(100)                 // earliest member lands exactly on the anchor
+    expect(pastedAudio.start).toBe(120)                  // later member keeps its original 20s offset from the anchor
+    expect(pastedAudio.end - pastedAudio.start).toBe(3)  // duration preserved
+  })
+})
+
+describe('duplicateSelection', () => {
+  it('returns the same project reference for an empty selection', () => {
+    const p = makeProject()
+    expect(duplicateSelection(p, [])).toBe(p)
+  })
+
+  it('returns the same project reference when selectedIds names only captions', () => {
+    const p = makeProject({
+      tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5 }]),
+      captions: { style: 'subtitle', segments: [{ id: 'c1', text: 'hi', start: 0, end: 1 }] },
+    })
+    expect(duplicateSelection(p, ['c1'])).toBe(p)
+  })
+
+  it('duplicates a visual item verbatim at its own end', () => {
+    const p = makeProject({
+      tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5, inPoint: 0, outPoint: 5 }]),
+    })
+    const out = duplicateSelection(p, ['a'])
+    const items = out.tracks![0].items
+    expect(items).toHaveLength(2)
+    const dup = items.find(i => i.id !== 'a')!
+    expect(dup).toMatchObject({ type: 'video', start: 5, end: 10, inPoint: 0, outPoint: 5 })
+    expect(dup.id).not.toBe('a')
+  })
+
+  it('gap-resolves a duplicate that collides with a following clip', () => {
+    const p = makeProject({
+      tracks: vtracks([
+        { id: 'a', type: 'video', start: 0, end: 5 },
+        { id: 'b', type: 'video', start: 5, end: 10 },
+      ]),
+    })
+    const out = duplicateSelection(p, ['a'])
+    const dup = out.tracks![0].items.find(i => i.id !== 'a' && i.id !== 'b')!
+    expect(dup.start).toBe(10) // shifted past 'b'
+    expect(dup.end).toBe(15)
+  })
+
+  it('duplicates an audio track verbatim at its own end', () => {
+    const track: AudioTrack = { id: 'aud1', src: 'x.mp3', start: 0, end: 4, volume: 0.6 }
+    const p = makeProject({ audio: { tracks: [track] } })
+    const out = duplicateSelection(p, ['aud1'])
+    const dup = out.audio!.tracks.find(t => t.id !== 'aud1')!
+    expect(dup).toMatchObject({ src: 'x.mp3', start: 4, end: 8, volume: 0.6 })
+  })
+
+  it('gap-resolves a duplicated audio track against its OWN lane only, not every audio track flattened', () => {
+    // Music bed [0,60] in lane 0 + voiceover [0,30] in lane 1. Duplicating the
+    // voiceover must land the copy at [30,60] in lane 1 (right after the
+    // original, overlapping the bed is fine) — NOT shoved to [60,90] by
+    // wrongly treating the longer bed as a same-lane collision.
+    const bed: AudioTrack = { id: 'bed', src: 'bed.mp3', start: 0, end: 60, lane: 0 }
+    const vo: AudioTrack = { id: 'vo', src: 'vo.mp3', start: 0, end: 30, lane: 1 }
+    const p = makeProject({ audio: { tracks: [bed, vo] } })
+    const out = duplicateSelection(p, ['vo'])
+    const dup = out.audio!.tracks.find(t => t.id !== 'bed' && t.id !== 'vo')!
+    expect(dup.start).toBe(30)
+    expect(dup.end).toBe(60)
+    expect(dup.lane).toBe(1)
+  })
+
+  it('mints fresh, unique ids for every duplicated item, colliding with nothing', () => {
+    const p = makeProject({
+      tracks: vtracks([
+        { id: 'a', type: 'video', start: 0, end: 2 },
+        { id: 'b', type: 'video', start: 2, end: 4 },
+        { id: 'c', type: 'video', start: 4, end: 6 },
+      ]),
+    })
+    const out = duplicateSelection(p, ['a', 'b', 'c'])
+    const ids = out.tracks![0].items.map(i => i.id)
+    expect(ids).toHaveLength(6)
+    expect(new Set(ids).size).toBe(6)
+  })
+})
+
+describe('pasteAttributes', () => {
+  it('returns the same project reference for an empty selection', () => {
+    const p = makeProject()
+    expect(pasteAttributes(p, { items: [], audioTracks: [] }, [])).toBe(p)
+  })
+
+  it('returns the same project reference for a null payload', () => {
+    const p = makeProject({ tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5 }]) })
+    expect(pasteAttributes(p, null, ['a'])).toBe(p)
+  })
+
+  it('returns the same project reference when selectedIds names only captions', () => {
+    const source: VisualItem = { id: 's', type: 'video', start: 0, end: 5, offsetX: 10 }
+    const p = makeProject({
+      tracks: vtracks([source]),
+      captions: { style: 'subtitle', segments: [{ id: 'c1', text: 'hi', start: 0, end: 1 }] },
+    })
+    const payload = copySelection(p, ['s'])!
+    expect(pasteAttributes(p, payload, ['c1'])).toBe(p)
+  })
+
+  it('returns the same project reference when the gated patch is empty for every target', () => {
+    // source carries only video-only fields; target is an overlay, which qualifies for none of them.
+    const source: VisualItem = { id: 's', type: 'video', start: 0, end: 5, volume: 0.5, speed: 2, muted: true }
+    const target: VisualItem = { id: 't', type: 'overlay', start: 10, end: 15 }
+    const p = makeProject({ tracks: vtracks([source, target]) })
+    const payload = copySelection(p, ['s'])!
+    expect(pasteAttributes(p, payload, ['t'])).toBe(p)
+  })
+
+  it('transfers common look fields to every visual item type', () => {
+    const source: VisualItem = {
+      id: 's', type: 'video', start: 0, end: 5,
+      offsetX: 10, offsetY: 20, scale: 1.5, opacity: 0.9, rotation: 45,
+    }
+    const target: VisualItem = { id: 't', type: 'overlay', start: 10, end: 15 }
+    const p = makeProject({ tracks: vtracks([source, target]) })
+    const payload = copySelection(p, ['s'])!
+    const out = pasteAttributes(p, payload, ['t'])
+    const patched = out.tracks![0].items.find(i => i.id === 't')!
+    expect(patched).toMatchObject({ offsetX: 10, offsetY: 20, scale: 1.5, opacity: 0.9, rotation: 45 })
+  })
+
+  it('never lands image-only `fit` on a video target', () => {
+    const source: VisualItem = { id: 's', type: 'image', start: 0, end: 5, fit: 'contain' }
+    const target: VisualItem = { id: 't', type: 'video', start: 10, end: 15 }
+    const p = makeProject({ tracks: vtracks([source, target]) })
+    const payload = copySelection(p, ['s'])!
+    const out = pasteAttributes(p, payload, ['t'])
+    expect(out.tracks![0].items.find(i => i.id === 't')!.fit).toBeUndefined()
+  })
+
+  it('lands `fit` only on an image target', () => {
+    const source: VisualItem = { id: 's', type: 'image', start: 0, end: 5, fit: 'contain' }
+    const target: VisualItem = { id: 't', type: 'image', start: 10, end: 15 }
+    const p = makeProject({ tracks: vtracks([source, target]) })
+    const payload = copySelection(p, ['s'])!
+    const out = pasteAttributes(p, payload, ['t'])
+    expect(out.tracks![0].items.find(i => i.id === 't')!.fit).toBe('contain')
+  })
+
+  it('never lands video-only `speed` on an image or overlay target', () => {
+    const source: VisualItem = { id: 's', type: 'video', start: 0, end: 5, speed: 2 }
+    const image: VisualItem = { id: 'img', type: 'image', start: 10, end: 15 }
+    const overlay: VisualItem = { id: 'ov', type: 'overlay', start: 20, end: 25 }
+    const p = makeProject({ tracks: vtracks([source, image, overlay]) })
+    const payload = copySelection(p, ['s'])!
+    const out = pasteAttributes(p, payload, ['img', 'ov'])
+    const items = out.tracks![0].items
+    expect(items.find(i => i.id === 'img')!.speed).toBeUndefined()
+    expect(items.find(i => i.id === 'ov')!.speed).toBeUndefined()
+  })
+
+  it('lands volume/muted/speed on a video target', () => {
+    const source: VisualItem = { id: 's', type: 'video', start: 0, end: 5, volume: 0.4, muted: true, speed: 1.5 }
+    const target: VisualItem = { id: 't', type: 'video', start: 10, end: 15 }
+    const p = makeProject({ tracks: vtracks([source, target]) })
+    const payload = copySelection(p, ['s'])!
+    const out = pasteAttributes(p, payload, ['t'])
+    expect(out.tracks![0].items.find(i => i.id === 't')).toMatchObject({ volume: 0.4, muted: true, speed: 1.5 })
+  })
+
+  it('never transfers sourceCrop', () => {
+    const source: VisualItem = {
+      id: 's', type: 'video', start: 0, end: 5, sourceCrop: { x: 0.1, y: 0.1, w: 0.5, h: 0.5 },
+    }
+    const target: VisualItem = { id: 't', type: 'video', start: 10, end: 15 }
+    const p = makeProject({ tracks: vtracks([source, target]) })
+    const payload = copySelection(p, ['s'])!
+    const out = pasteAttributes(p, payload, ['t'])
+    expect(out.tracks![0].items.find(i => i.id === 't')!.sourceCrop).toBeUndefined()
+  })
+
+  it('transfers audio look fields from the first copied audio track to selected audio targets', () => {
+    const source: AudioTrack = {
+      id: 's', src: 'a.mp3', start: 0, end: 5, volume: 0.3, muted: true, fadeIn: 1, fadeOut: 2,
+    }
+    const target: AudioTrack = { id: 't', src: 'b.mp3', start: 10, end: 15 }
+    const p = makeProject({ audio: { tracks: [source, target] } })
+    const payload = copySelection(p, ['s'])!
+    const out = pasteAttributes(p, payload, ['t'])
+    expect(out.audio!.tracks.find(t => t.id === 't')).toMatchObject({
+      volume: 0.3, muted: true, fadeIn: 1, fadeOut: 2,
+    })
+  })
+})
+
+describe('verbatim clone (type + inPoint/outPoint survive copy/paste and duplicate)', () => {
+  it('never coerces type to video, and preserves inPoint/outPoint on a trimmed clip, through both pasteAt and duplicateSelection', () => {
+    // The reason `pasteAt`/`duplicateSelection` don't route through `insertClipAt`
+    // (cuts.ts) is that it unconditionally mints a whole-source `type:'video'`
+    // item, which would coerce an image/overlay's type and un-trim a video clip.
+    // This pins the negative: none of that happens here.
+    const image: VisualItem = { id: 'img', type: 'image', start: 0, end: 3, offsetX: 5 }
+    const overlay: VisualItem = { id: 'ov', type: 'overlay', start: 3, end: 6, props: { text: 'hi' } }
+    const trimmedVideo: VisualItem = { id: 'v', type: 'video', start: 6, end: 9, inPoint: 2, outPoint: 5 }
+    const p = makeProject({ tracks: vtracks([image, overlay, trimmedVideo]) })
+    const originalIds = new Set(['img', 'ov', 'v'])
+
+    const payload = copySelection(p, ['img', 'ov', 'v'])!
+    const pasted = pasteAt(p, payload, 100)
+    const pastedItems = pasted.tracks![0].items.filter(i => !originalIds.has(i.id))
+    expect(pastedItems.find(i => i.type === 'image')).toMatchObject({ type: 'image', offsetX: 5 })
+    expect(pastedItems.find(i => i.type === 'overlay')).toMatchObject({ type: 'overlay', props: { text: 'hi' } })
+    expect(pastedItems.find(i => i.type === 'video')).toMatchObject({ type: 'video', inPoint: 2, outPoint: 5 })
+
+    const duplicated = duplicateSelection(p, ['img', 'ov', 'v'])
+    const dupItems = duplicated.tracks![0].items.filter(i => !originalIds.has(i.id))
+    expect(dupItems.find(i => i.type === 'image')).toMatchObject({ type: 'image', offsetX: 5 })
+    expect(dupItems.find(i => i.type === 'overlay')).toMatchObject({ type: 'overlay', props: { text: 'hi' } })
+    expect(dupItems.find(i => i.type === 'video')).toMatchObject({ type: 'video', inPoint: 2, outPoint: 5 })
+  })
+})

package/src/video/__tests__/cuts.insert.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect } from 'vitest'
+import { insertClipAt, newClipId } from '../cuts'
+import type { EditorProject as Project, VisualItem, VisualTrack } from '../../schema'
+
+/** Object-shape visual tracks carrying the ids `normalizeTracks` would hand out
+ *  — mirrors the fixture helper in `cuts.test.ts`. */
+function vtracks(...items: VisualItem[][]): VisualTrack[] {
+  return items.map((its, i) => ({ id: `trk-${i}`, items: its }))
+}
+
+// Minimal project factory — only the fields the insert helper touches.
+function makeProject(over: Partial<Project> = {}): Project {
+  return {
+    id: 'p1',
+    status: 'draft',
+    settings: { resolution: [1080, 1920] },
+    tracks: vtracks([]),
+    ...over,
+  }
+}
+
+const EPS = 1e-6
+
+/** No two items on a track overlap by more than float slop. */
+function assertNoOverlaps(items: VisualItem[]): void {
+  const sorted = [...items].sort((a, b) => a.start - b.start)
+  for (let i = 1; i < sorted.length; i++) {
+    expect(sorted[i].start).toBeGreaterThanOrEqual(sorted[i - 1].end - EPS)
+  }
+}
+
+/** Every id present except the known source ids — the freshly inserted clip. */
+function inserted(items: VisualItem[], sourceIds: string[]): VisualItem {
+  const found = items.find(i => !sourceIds.includes(i.id))
+  expect(found).toBeDefined()
+  return found!
+}
+
+describe('insertClipAt — ripple', () => {
+  it('shifts later clips right by exactly the new length and drops at the drop time', () => {
+    const p = makeProject({
+      tracks: vtracks([
+        { id: 'a', type: 'video', start: 0, end: 5 },
+        { id: 'b', type: 'video', start: 5, end: 10 },
+        { id: 'c', type: 'video', start: 10, end: 15 },
+      ]),
+    })
+    const out = insertClipAt(p, 'trk-0', { src: 'n.mp4', sourceDuration: 3 }, 5, { ripple: true })
+    const items = out.tracks![0].items
+
+    expect(items).toHaveLength(4)
+    expect(items.find(i => i.id === 'a')).toMatchObject({ start: 0, end: 5 })   // before the drop — unchanged
+    expect(items.find(i => i.id === 'b')).toMatchObject({ start: 8, end: 13 })  // shifted right by 3
+    expect(items.find(i => i.id === 'c')).toMatchObject({ start: 13, end: 18 }) // shifted right by 3
+
+    const clip = inserted(items, ['a', 'b', 'c'])
+    expect(clip).toMatchObject({ start: 5, end: 8 })
+
+    assertNoOverlaps(items)
+    // returned items are sorted by start
+    const starts = items.map(i => i.start)
+    expect(starts).toEqual([...starts].sort((x, y) => x - y))
+  })
+
+  it('snaps to the nearest edge of a straddling clip instead of dropping inside it', () => {
+    const p = makeProject({
+      tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 10 }]),
+    })
+    const out = insertClipAt(p, 'trk-0', { src: 'n.mp4', sourceDuration: 3 }, 5, { ripple: true })
+    const items = out.tracks![0].items
+
+    expect(items).toHaveLength(2)
+    assertNoOverlaps(items)
+
+    const clip = inserted(items, ['a'])
+    // the new clip must sit at a boundary of the straddled clip, never inside it
+    expect([0, 10]).toContain(clip.start)
+  })
+
+  it('snaps a straddled drop to the START at/before the midpoint (including exactly 50%), and to the END past it', () => {
+    // Sam's product call (2026-08-25): never split a clip. A drop in the
+    // first half of a clip — including dead center — means "put the new
+    // clip before this one"; only a drop strictly past the midpoint pushes
+    // the new clip after it. See insertClipAt's doc comment.
+    const straddler = (): VisualItem[] => [{ id: 'a', type: 'video', start: 0, end: 10 }]
+
+    const before = insertClipAt(
+      makeProject({ tracks: vtracks(straddler()) }), 'trk-0', { src: 'n.mp4', sourceDuration: 2 }, 4, { ripple: true },
+    )
+    expect(inserted(before.tracks![0].items, ['a']).start).toBe(0)
+
+    const tie = insertClipAt(
+      makeProject({ tracks: vtracks(straddler()) }), 'trk-0', { src: 'n.mp4', sourceDuration: 2 }, 5, { ripple: true },
+    )
+    expect(inserted(tie.tracks![0].items, ['a']).start).toBe(0)
+
+    const after = insertClipAt(
+      makeProject({ tracks: vtracks(straddler()) }), 'trk-0', { src: 'n.mp4', sourceDuration: 2 }, 6, { ripple: true },
+    )
+    expect(inserted(after.tracks![0].items, ['a']).start).toBe(10)
+  })
+
+  it('snaps to the nearest edge when the drop point straddles the second of two clips', () => {
+    const p = makeProject({
+      tracks: vtracks([
+        { id: 'a', type: 'video', start: 0, end: 10 },
+        { id: 'b', type: 'video', start: 10, end: 20 },
+      ]),
+    })
+    const out = insertClipAt(p, 'trk-0', { src: 'n.mp4', sourceDuration: 4 }, 15, { ripple: true })
+    const items = out.tracks![0].items
+
+    expect(items).toHaveLength(3)
+    assertNoOverlaps(items)
+
+    // order preserved: 'a' still precedes 'b' on the timeline
+    const a = items.find(i => i.id === 'a')!
+    const b = items.find(i => i.id === 'b')!
+    expect(a.start).toBeLessThan(b.start)
+
+    const clip = inserted(items, ['a', 'b'])
+    // the new clip must sit at a boundary of the straddled clip 'b', never inside it
+    expect([10, 20]).toContain(clip.start)
+  })
+})
+
+describe('insertClipAt — non-ripple', () => {
+  it('places at the drop time inside a free gap and leaves others untouched', () => {
+    const p = makeProject({
+      tracks: vtracks([
+        { id: 'a', type: 'video', start: 0, end: 5 },
+        { id: 'b', type: 'video', start: 10, end: 15 },
+      ]),
+    })
+    const out = insertClipAt(p, 'trk-0', { src: 'n.mp4', sourceDuration: 2 }, 6, { ripple: false })
+    const items = out.tracks![0].items
+
+    expect(items.find(i => i.id === 'a')).toMatchObject({ start: 0, end: 5 })
+    expect(items.find(i => i.id === 'b')).toMatchObject({ start: 10, end: 15 })
+    expect(inserted(items, ['a', 'b'])).toMatchObject({ start: 6, end: 8 })
+    assertNoOverlaps(items)
+  })
+
+  it('snaps into the nearest fitting gap when the drop window overlaps a clip', () => {
+    const p = makeProject({
+      tracks: vtracks([
+        { id: 'a', type: 'video', start: 0, end: 5 },
+        { id: 'b', type: 'video', start: 6, end: 20 },
+      ]),
+    })
+    // Drop at 3 overlaps 'a'; the [5,6] gap fits a length-1 clip exactly.
+    const out = insertClipAt(p, 'trk-0', { src: 'n.mp4', sourceDuration: 1 }, 3, { ripple: false })
+    const items = out.tracks![0].items
+
+    expect(items.find(i => i.id === 'a')).toMatchObject({ start: 0, end: 5 })
+    expect(items.find(i => i.id === 'b')).toMatchObject({ start: 6, end: 20 })
+    expect(inserted(items, ['a', 'b'])).toMatchObject({ start: 5, end: 6 })
+    assertNoOverlaps(items)
+  })
+
+  it('appends after the last item when no gap at/after the drop fits', () => {
+    const p = makeProject({
+      tracks: vtracks([
+        { id: 'a', type: 'video', start: 0, end: 5 },
+        { id: 'b', type: 'video', start: 5, end: 10 },
+      ]),
+    })
+    // Drop at 3, length 4: overlaps both, [5,10] gap too small → appended at 10.
+    const out = insertClipAt(p, 'trk-0', { src: 'n.mp4', sourceDuration: 4 }, 3, { ripple: false })
+    const items = out.tracks![0].items
+
+    expect(items.find(i => i.id === 'a')).toMatchObject({ start: 0, end: 5 })
+    expect(items.find(i => i.id === 'b')).toMatchObject({ start: 5, end: 10 })
+    expect(inserted(items, ['a', 'b'])).toMatchObject({ start: 10, end: 14 })
+    assertNoOverlaps(items)
+  })
+})
+
+describe('insertClipAt — the built item', () => {
+  it('is a whole-source video item with inPoint 0, outPoint sourceDuration, and a distinct id', () => {
+    const p = makeProject({ tracks: vtracks([{ id: 'clip-0', type: 'video', start: 0, end: 4 }]) })
+    const out = insertClipAt(
+      p,
+      'trk-0',
+      { src: 'n.mp4', proxySrc: 'n_proxy.mp4', sourceDuration: 7, sourceWidth: 1920, sourceHeight: 1080 },
+      100, // beyond all content → placed at the drop point
+      { ripple: false },
+    )
+    const clip = inserted(out.tracks![0].items, ['clip-0'])
+
+    expect(clip.type).toBe('video')
+    expect(clip.src).toBe('n.mp4')
+    expect(clip.proxySrc).toBe('n_proxy.mp4')
+    expect(clip.inPoint).toBe(0)
+    expect(clip.outPoint).toBe(7)
+    expect(clip.end - clip.start).toBe(7)
+    expect(clip.sourceDuration).toBe(7)
+    expect(clip.sourceWidth).toBe(1920)
+    expect(clip.sourceHeight).toBe(1080)
+    expect(clip.id).not.toBe('clip-0')
+  })
+
+  it('omits proxySrc / sourceWidth / sourceHeight when not provided', () => {
+    const p = makeProject({ tracks: vtracks([]) })
+    const clip = insertClipAt(p, 'trk-0', { src: 'n.mp4', sourceDuration: 2 }, 0, { ripple: false })
+      .tracks![0].items[0]
+
+    expect('proxySrc' in clip).toBe(false)
+    expect('sourceWidth' in clip).toBe(false)
+    expect('sourceHeight' in clip).toBe(false)
+  })
+})
+
+describe('insertClipAt — misc', () => {
+  it('clamps a negative drop time to 0', () => {
+    const p = makeProject({ tracks: vtracks([]) })
+    const clip = insertClipAt(p, 'trk-0', { src: 'n.mp4', sourceDuration: 3 }, -5, { ripple: false })
+      .tracks![0].items[0]
+    expect(clip).toMatchObject({ start: 0, end: 3 })
+  })
+
+  it('returns the project unchanged when the track id is unknown', () => {
+    const p = makeProject({ tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5 }]) })
+    expect(insertClipAt(p, 'nope', { src: 'n.mp4', sourceDuration: 2 }, 1, { ripple: true })).toBe(p)
+  })
+
+  it('does not mutate the input project, its items, or the clip descriptor', () => {
+    const clipInput = { src: 'n.mp4', sourceDuration: 2 }
+    const p = makeProject({ tracks: vtracks([{ id: 'a', type: 'video', start: 0, end: 5 }]) })
+    const before = JSON.stringify(p)
+    insertClipAt(p, 'trk-0', clipInput, 1, { ripple: true })
+    expect(JSON.stringify(p)).toBe(before)
+    expect(clipInput).toEqual({ src: 'n.mp4', sourceDuration: 2 })
+  })
+})
+
+describe('newClipId', () => {
+  it('returns distinct ids that never look like a clip-<n> source id', () => {
+    const ids = new Set<string>()
+    for (let i = 0; i < 500; i++) ids.add(newClipId())
+    expect(ids.size).toBe(500)
+    for (const id of ids) expect(id).not.toMatch(/^clip-\d+$/)
+  })
+})