@bycrux/editor 0.11.2 → 1.0.1

package/src/video/timeline/makeCaptionEdit.ts

@@ -1,5 +1,6 @@
 import type { Project } from '../../types'
 import type { CaptionSegment } from '../../schema'
+import { floorWordDurations } from '../captionWordFloor'
 
 /** Fields `makeCaptionEdit` can patch onto a single caption segment. */
 export type CaptionEditPatch = Partial<CaptionSegment>
@@ -40,11 +41,14 @@ export function makeCaptionEdit(
           const newWords = next.text.split(/\s+/).filter(Boolean)
           const segDur = next.end - next.start
           const wordDur = segDur / (newWords.length || 1)
-          next.words = newWords.map((w, wi) => ({
+          const spreadWords = newWords.map((w, wi) => ({
             word: w,
             start: next.start + wi * wordDur,
             end: next.start + (wi + 1) * wordDur,
           }))
+          // Uniform spread has no minimum of its own — floor it so a short
+          // word never falls below a frame at any fps. See captionWordFloor.ts.
+          next.words = floorWordDurations(spreadWords, next.end)
           return next
         }),
       },

package/src/video/timeline/multiSelectOps.ts

@@ -1,14 +1,19 @@
-// Multi-select project mutations shared by VisualTrackRow and AudioTrackRow.
+// Multi-select project mutations shared by the canvas pointer machine
+// (canvas/pointer-machine.ts) and Timeline.tsx.
 //
 // Selection IDs are unified — a single `selectedIds: string[]` covers visual
-// items (project.tracks[*][*]) and audio tracks (project.audio.tracks[*]).
+// items (project.tracks[*][*]), audio tracks (project.audio.tracks[*]) and
+// caption segments (project.captions.segments[*]).
 // Cross-type ops (e.g. resize a video clip + an audio track in one drag) work
-// because every id is globally unique within a Project.
+// because every id is globally unique within a Project. Captions join only the
+// MOVE op: mute, delete and resize are still clip/audio vocabulary.
 
-import type { VisualItem, AudioTrack } from '../../schema'
+import type { VisualItem, AudioTrack, CaptionSegment, Captions } from '../../schema'
 import type { Project } from '../../types'
+import { laneOf } from '../captionLanes'
+import { mapTrackItems, normalizeTrackOrder, trackItems } from './timeline-model'
+import { computeResizedItem, resizeWindowedItem, type Draggable } from './useItemDragDrop'
 
-const MIN_DURATION = 0.1
 
 export interface ResizeDeltas {
   /** Delta in seconds applied to start-edge resizes. 0 if edge !== 'start'. */
@@ -31,8 +36,8 @@ export function applyResizeDeltaToSelection(
   const targets = new Set(selectedIds.filter(id => id !== originatorId))
   if (targets.size === 0) return project
 
-  const nextTracks = (project.tracks ?? []).map(track =>
-    track.map(item => targets.has(item.id) ? resizeVisualItem(item, edge, deltas) : item)
+  const nextTracks = mapTrackItems(project, items =>
+    items.map(item => targets.has(item.id) ? resizeVisualItem(item, edge, deltas) : item)
   )
   const nextAudio = (project.audio?.tracks ?? []).map(t =>
     targets.has(t.id) ? resizeAudioTrack(t, edge, deltas) : t
@@ -45,54 +50,200 @@ export function applyResizeDeltaToSelection(
   }
 }
 
+/** Delegates to `computeResizedItem` so the span/window invariant is enforced
+ *  in ONE place. This used to hand-roll the same arithmetic with the same
+ *  independent clamps on the edge and the window, and therefore the same bug:
+ *  propagating a trim to the rest of a multi-selection could stretch a clip's
+ *  timeline span past the source it actually has. The only thing added here is
+ *  the timeline floor at t=0, applied to the REQUESTED time so the shared
+ *  function still does all the clamping that matters. */
 function resizeVisualItem(item: VisualItem, edge: 'start' | 'end', { dStart, dEnd }: ResizeDeltas): VisualItem {
-  if (edge === 'start') {
-    const newStart = Math.max(0, Math.min(item.start + dStart, item.end - MIN_DURATION))
-    if (item.type !== 'video') return { ...item, start: newStart }
-    const inP = item.inPoint ?? 0
-    const outP = item.outPoint ?? (inP + (item.end - item.start))
-    const dActual = newStart - item.start
-    return {
-      ...item,
-      start: newStart,
-      inPoint: Math.max(0, Math.min(inP + dActual, outP - MIN_DURATION)),
-    }
-  } else {
-    const newEnd = Math.max(item.start + MIN_DURATION, item.end + dEnd)
-    if (item.type !== 'video') return { ...item, end: newEnd }
-    const inP = item.inPoint ?? 0
-    const outP = item.outPoint ?? (inP + (item.end - item.start))
-    const dActual = newEnd - item.end
-    return {
-      ...item,
-      end: newEnd,
-      outPoint: Math.max(inP + MIN_DURATION, Math.min(outP + dActual, item.sourceDuration ?? Infinity)),
-    }
-  }
+  const requested = edge === 'start'
+    ? Math.max(0, item.start + dStart)
+    : item.end + dEnd
+  return computeResizedItem(item as Draggable, edge, requested) as VisualItem
 }
 
+/** As `resizeVisualItem`, but an audio track is always source-windowed — there
+ *  is no "no window" case to fall through to, so it goes straight to
+ *  `resizeWindowedItem` rather than through the video/non-video branch. */
 function resizeAudioTrack(track: AudioTrack, edge: 'start' | 'end', { dStart, dEnd }: ResizeDeltas): AudioTrack {
-  const inP = track.inPoint ?? 0
-  const outP = track.outPoint ?? (inP + (track.end - track.start))
-  const srcDur = track.sourceDuration ?? Infinity
-
-  if (edge === 'start') {
-    const newStart = Math.max(0, Math.min(track.start + dStart, track.end - MIN_DURATION))
-    const dActual = newStart - track.start
-    return {
-      ...track,
-      start: newStart,
-      inPoint: Math.max(0, Math.min(inP + dActual, outP - MIN_DURATION)),
-    }
-  } else {
-    const newEnd = Math.max(track.start + MIN_DURATION, track.end + dEnd)
-    const dActual = newEnd - track.end
-    return {
-      ...track,
-      end: newEnd,
-      outPoint: Math.max(inP + MIN_DURATION, Math.min(outP + dActual, srcDur)),
+  const requested = edge === 'start'
+    ? Math.max(0, track.start + dStart)
+    : track.end + dEnd
+  return resizeWindowedItem(track as unknown as Draggable, edge, requested) as unknown as AudioTrack
+}
+
+/**
+ * How far the SELECTED captions, as a group, may travel before any one of them
+ * would cross a NON-selected caption's edge IN ITS OWN LANE.
+ *
+ * Captions must never overlap WITHIN A LANE. `activeCaptionSegments`
+ * (timeline-core) hands the preview and every render template EVERY segment
+ * live at `t`, ordered by lane ascending — a lane is a z-order and carries no
+ * vertical offset of its own — so two segments overlapping in one lane paint
+ * at the same place, one straight over the other, in preview AND in export.
+ * With transcripts back-to-back by default that is not an edge case. Segments
+ * on DIFFERENT lanes coinciding is the feature caption rows exist for (each
+ * carries its own `offsetX`/`offsetY`), so a segment in lane 1 is not a bound
+ * on a segment in lane 0 and must not stop it moving.
+ *
+ * For each selected segment this finds its nearest NON-selected same-lane
+ * neighbour on either side (greatest `end <= seg.start` on the left, smallest
+ * `start >= seg.end` on the right) and how much room that neighbour leaves.
+ * The group bound is the TIGHTEST of those per-segment rooms — same shape as
+ * the extent scan below: one number covers the whole body. Selected ids are
+ * excluded from the neighbour search on BOTH sides (a selected segment is
+ * never treated as another selected segment's neighbour, itself included);
+ * that is what lets a run of adjacent selected captions move rigidly, stopping
+ * only at the first caption not coming along for the ride, rather than jamming
+ * against each other one gap in. Absent neighbour reads as unbounded
+ * (`Infinity`) on that side.
+ *
+ * Lanes are read through `laneOf`, never off `seg.lane` directly, so an absent
+ * or hand-edited value collapses the same way it does everywhere else.
+ */
+function captionNeighbourBounds(
+  captions: Captions | undefined,
+  targets: ReadonlySet<string>,
+): { maxLeft: number; maxRight: number } {
+  const segments = captions?.segments ?? []
+  let maxLeft = Infinity
+  let maxRight = Infinity
+  for (const seg of segments) {
+    if (seg.id === undefined || !targets.has(seg.id)) continue
+    const lane = laneOf(seg)
+    let leftEnd = -Infinity
+    let rightStart = Infinity
+    for (const other of segments) {
+      // Skips every selected segment, this one included — see the WHY above.
+      if (other.id !== undefined && targets.has(other.id)) continue
+      // …and every segment on another row: overlap across lanes is legal.
+      if (laneOf(other) !== lane) continue
+      if (other.end <= seg.start && other.end > leftEnd) leftEnd = other.end
+      if (other.start >= seg.end && other.start < rightStart) rightStart = other.start
     }
+    if (leftEnd > -Infinity) maxLeft = Math.min(maxLeft, seg.start - leftEnd)
+    if (rightStart < Infinity) maxRight = Math.min(maxRight, rightStart - seg.end)
   }
+  return { maxLeft, maxRight }
+}
+
+/**
+ * Shift every selected visual item, audio track and caption segment by the same
+ * timeline delta, preserving their relative positions — a rigid move of the
+ * whole selection.
+ *
+ * The delta is clamped ONCE, against the group as a body: the leftmost selected
+ * start cannot cross t=0 and the rightmost selected end cannot cross
+ * `totalDuration`, so the selection keeps its shape at the edges instead of
+ * bunching up when one member hits a wall. Cross-track (vertical) movement is
+ * deliberately not part of a group move — every item stays on its own
+ * track/lane, which is the predictable behaviour when several move at once.
+ *
+ * The SAME clamp also folds in `captionNeighbourBounds`: a selected caption may
+ * not cross a non-selected one SHARING ITS LANE, so a group that includes
+ * captions is clamped by whichever is tighter, the timeline edge or a
+ * same-lane caption neighbour. Vertical movement is not part of a group move
+ * for captions either — every segment keeps the lane it started in, so a
+ * multi-selection drag never changes rows however far the pointer travels up
+ * or down (`applyCaptionMove` in canvas/pointer-machine.ts owns the one gesture
+ * that does).
+ *
+ * The caller rebuilds from the press-time project on every move, so dragging
+ * back and forth cannot compound.
+ */
+export function applyMoveDeltaToSelection(
+  project: Project,
+  selectedIds: readonly string[],
+  requestedDelta: number,
+  totalDuration: number,
+): Project {
+  const targets = new Set(selectedIds)
+  if (targets.size === 0) return project
+
+  // The group's extent, so one clamp keeps every member on the timeline.
+  let minStart = Infinity
+  let maxEnd = -Infinity
+  // `id` is optional only because `CaptionSegment.id` is (a segment briefly
+  // lacks one before `backfillCaptionIds` mints it). An id-less member can
+  // never be in `selectedIds`, so it simply never counts toward the extent.
+  const consider = (it: { id?: string; start: number; end: number }) => {
+    if (it.id === undefined || !targets.has(it.id)) return
+    if (it.start < minStart) minStart = it.start
+    if (it.end > maxEnd) maxEnd = it.end
+  }
+  for (const items of trackItems(project)) items.forEach(consider)
+  for (const t of project.audio?.tracks ?? []) consider(t)
+  // Captions join the SAME extent scan, so one clamp covers a mixed
+  // clip+caption selection rather than letting the captions slide past t=0
+  // while the clips hold.
+  for (const seg of project.captions?.segments ?? []) consider(seg)
+  // None of the selected ids are actually present (e.g. a stale selection).
+  if (!Number.isFinite(minStart)) return project
+
+  // The caption-neighbour bound folds into the SAME lo/hi the timeline edges
+  // use below — one range, not two clamps in sequence (a second clamp would
+  // undo the first, same reasoning `applyCaptionTrim` documents for its own
+  // lo/hi). `maxLeft`/`maxRight` are `Infinity` when nothing selected is a
+  // caption (or no neighbour exists), so `Math.max`/`Math.min` below are then
+  // no-ops and the plain timeline-edge bound is all that's left.
+  const { maxLeft, maxRight } = captionNeighbourBounds(project.captions, targets)
+
+  const lo = Math.max(-minStart, -maxLeft)
+  // Floored at 0: never push a member further out than it already is.
+  // `totalDuration` is derived from clips and audio only (timeline-model.ts),
+  // so a caption can legally outlast it (e.g. clips trimmed/deleted after
+  // captioning) — for clips/audio `maxEnd` never exceeds `totalDuration`, but
+  // an overhanging caption drives `maxEnd` past it, which without the floor
+  // sends `hi` negative and drags the whole group backwards on a rightward
+  // drag (or makes it un-movable when mixed with a clip at lo=0). Mirrors the
+  // `Math.max(ctx.totalDuration, seg.end)` ceiling `applyCaptionTrim` already
+  // uses for the same overhang case.
+  const hi = Math.min(Math.max(0, totalDuration - maxEnd), maxRight)
+  // A group already wider than the timeline (lo > hi) can't move without
+  // pushing a member off an edge, so it doesn't. Same short-circuit now also
+  // catches a group that can't move without crossing a caption neighbour.
+  const delta = lo > hi ? 0 : Math.max(lo, Math.min(hi, requestedDelta))
+  if (delta === 0) return project
+
+  const shift = <T extends { id: string; start: number; end: number }>(it: T): T =>
+    targets.has(it.id) ? { ...it, start: it.start + delta, end: it.end + delta } : it
+
+  const captions = shiftCaptions(project.captions, targets, delta)
+  return {
+    ...project,
+    tracks: mapTrackItems(project, items => items.map(shift)),
+    audio: project.audio
+      ? { ...project.audio, tracks: (project.audio.tracks ?? []).map(shift) }
+      : project.audio,
+    // Same reference back when no caption moved, so a clips-only group move
+    // leaves `project.captions` byte-for-byte what it was — and stays
+    // `undefined` on a project that has none.
+    captions,
+  }
+}
+
+/** The caption half of a group move. Word timings are ABSOLUTE seconds, so
+ *  every word travels with its segment by the same delta; a move preserves
+ *  duration, so nothing needs respreading. `text` is never touched, and
+ *  neither is `lane` — it rides the spread untouched, which is what makes a
+ *  group move horizontal-only for captions. */
+function shiftCaptions(
+  captions: Captions | undefined,
+  targets: ReadonlySet<string>,
+  delta: number,
+): Captions | undefined {
+  if (!captions) return captions
+  let changed = false
+  const segments = captions.segments.map(seg => {
+    if (seg.id === undefined || !targets.has(seg.id)) return seg
+    changed = true
+    const next: CaptionSegment = { ...seg, start: seg.start + delta, end: seg.end + delta }
+    if (seg.words) next.words = seg.words.map(w => ({ ...w, start: w.start + delta, end: w.end + delta }))
+    return next
+  })
+  return changed ? { ...captions, segments } : captions
 }
 
 /** Set `muted` on every selected item to the given target value. Both visual
@@ -108,8 +259,8 @@ export function applyMuteToSelection(
 
   return {
     ...project,
-    tracks: (project.tracks ?? []).map(track =>
-      track.map(item => targets.has(item.id) ? { ...item, muted } : item)
+    tracks: mapTrackItems(project, items =>
+      items.map(item => targets.has(item.id) ? { ...item, muted } : item)
     ),
     audio: project.audio
       ? {
@@ -127,11 +278,13 @@ export function deleteSelection(project: Project, selectedIds: readonly string[]
   const targets = new Set(selectedIds)
   if (targets.size === 0) return project
 
-  return {
+  const next: Project = {
     ...project,
-    tracks: (project.tracks ?? [])
-      .map(track => track.filter(item => !targets.has(item.id)))
-      .filter(track => track.length > 0),
+    // Prune, not a plain map: an emptied track collapses. The surviving TRACK
+    // OBJECTS pass through the filter, so each keeps its own id and settings
+    // rather than inheriting the ones a shifted index used to point at.
+    tracks: mapTrackItems(project, items => items.filter(item => !targets.has(item.id)))
+      .filter(track => track.items.length > 0),
     audio: project.audio
       ? {
           ...project.audio,
@@ -139,6 +292,12 @@ export function deleteSelection(project: Project, selectedIds: readonly string[]
         }
       : project.audio,
   }
+  // Re-group (Part B): a prune can change a track's coarse kind — a mixed
+  // track that loses its only video item becomes overlay-kind — so the
+  // canonical video-block/overlay-block invariant (`normalizeTrackOrder`) is
+  // re-asserted here rather than assumed to survive every prune. A no-op
+  // (same reference) when it already does.
+  return normalizeTrackOrder(next)
 }
 
 /** Selection helper: toggle additive (shift-click) vs replace (plain click).

package/src/video/timeline/placement.ts

@@ -0,0 +1,282 @@
+// The ONE placement rule shared by every entry point that drops brand-new
+// footage onto the timeline — today the footage-bin drag in
+// `canvas/TimelineCanvas.tsx`, and a filesystem drop landing in a later task.
+// Both hand the pointer's drop time and (optionally) which row it released
+// over to `placeDroppedClip` below and get back a project with the clip
+// placed "where you dropped it, without stomping existing footage" — the
+// exact rule lives in exactly one place instead of being reimplemented, and
+// possibly drifting, at each drop site.
+//
+// Pure and DOM-free on purpose: no canvas, no DragEvent, no React — so the
+// rule itself is unit-testable without simulating a real drag, and so a
+// future THIRD drop entry point (there will be one) has nothing to
+// reimplement either.
+
+import type { Project } from '../../types'
+import type { VisualTrack } from '../../schema'
+import { insertClipAt, overlapsAny, type NewClipInput } from '../cuts'
+import { normalizeTracks, nextVisualTrackId } from './timeline-model'
+
+/** What a drop needs to tell `placeDroppedClip` about ITSELF — the pointer's
+ *  drop time, which row (if any) it released over, and the magnet/snap state
+ *  the caller already knows. Everything geometry-shaped (pixel→time, pixel→
+ *  row) is the caller's job; this module only ever sees seconds and track
+ *  indices. */
+export interface DroppedClipPlacement {
+  /** Timeline time (seconds) the pointer released at. Clamped to >= 0. */
+  atTime: number
+  /** Index of the track the pointer released over, in the NORMALIZED track
+   *  order (`normalizeTracks(project).tracks`). Pass -1 for "no preference"
+   *  (e.g. released over the ruler, a caption band, or an audio lane). */
+  preferredTrackIndex: number
+  /** The footage to place. Its `sourceDuration` is the placed clip's length. */
+  clip: NewClipInput
+  /** Ripple/magnet mode — the editor's `rippleMode`. Default false. */
+  ripple?: boolean
+  /** Candidate snap targets in seconds (clip edges, the playhead), supplied by
+   *  the caller because this module knows nothing about the viewport. */
+  snapTimes?: readonly number[]
+  /** Max distance (seconds) at which `atTime` is pulled to a `snapTimes`
+   *  entry. Omitted / <= 0 disables snapping. */
+  snapToleranceSec?: number
+}
+
+/** What `placeDroppedClip` did. */
+export interface PlacedClipResult<P extends Project> {
+  /** The updated project. The SAME reference as the input when nothing was
+   *  placed (see `trackIndex`). */
+  project: P
+  /** Index of the track the clip landed on, in the RETURNED project's
+   *  normalized order. `-1` means nothing was placed. */
+  trackIndex: number
+  /** The placed clip's start time on the timeline. `0` when nothing was placed. */
+  start: number
+  /** The placed item's id. Absent when nothing was placed. */
+  itemId?: string
+  /** True when a NEW video track had to be created to hold the clip. */
+  createdTrack: boolean
+}
+
+/** The no-op result every early return below hands back — same project
+ *  reference, nothing placed. */
+function nothingPlaced<P extends Project>(project: P): PlacedClipResult<P> {
+  return { project, trackIndex: -1, start: 0, createdTrack: false }
+}
+
+/**
+ * Snap `atTime` to the nearest `snapTimes` entry within `snapToleranceSec`,
+ * ties going to the SMALLER time (deterministic — two equidistant snap
+ * targets must resolve the same way on every call, not by array-scan order).
+ * Falls through to `atTime` unchanged when snapping is disabled (no
+ * `snapTimes`, or a tolerance that is absent/<= 0) or nothing is in range.
+ *
+ * Exported (and typed against a `Pick` rather than the full
+ * `DroppedClipPlacement`) so a caller that doesn't yet know WHAT is being
+ * placed can still snap the drop point itself — `TimelineCanvas`'s OS-file
+ * drop branch has no `clip` at drop time (the file hasn't been probed or
+ * ingested yet), but still wants the ghost band and the eventual placement to
+ * land on the same magnetized second a bin drop would.
+ */
+export function resolveDropPoint({
+  atTime,
+  snapTimes,
+  snapToleranceSec,
+}: Pick<DroppedClipPlacement, 'atTime' | 'snapTimes' | 'snapToleranceSec'>): number {
+  if (!snapTimes || snapTimes.length === 0 || !(snapToleranceSec! > 0)) return atTime
+
+  let best: number | null = null
+  let bestDist = Infinity
+  for (const t of snapTimes) {
+    const dist = Math.abs(t - atTime)
+    if (dist > snapToleranceSec!) continue
+    if (dist < bestDist || (dist === bestDist && (best === null || t < best))) {
+      best = t
+      bestDist = dist
+    }
+  }
+  return best ?? atTime
+}
+
+/**
+ * A track at `index` is a video-placement CANDIDATE when either it already
+ * carries a video item (`trackGroupKind`'s own rule, timeline-model.ts), or
+ * it is the empty base row (`index === 0` with no items at all) —
+ * `computeTimelineLayout` (canvas/draw.ts) already draws that row tall,
+ * i.e. treats it as video-kind, regardless of content. Overlay/image tracks
+ * are never candidates. Captions and audio don't live in `project.tracks` at
+ * all, so they can never be selected here — there is nothing to exclude them
+ * with, they simply aren't in the array this function scans.
+ */
+function isVideoCandidate(track: VisualTrack, index: number): boolean {
+  return track.items.some(it => it.type === 'video') || (index === 0 && track.items.length === 0)
+}
+
+/**
+ * Pick the candidate index minimizing `(|i - ref|, i)` — closest to `ref`
+ * first, lower index breaking a tie. `candidates` must be non-empty.
+ *
+ * Index distance stands in for on-screen distance: rows differ in rendered
+ * height (120px for the base video row, 40px for the rest), but the video
+ * block is contiguous from index 0 after normalization (`normalizeTracks`),
+ * so ordering by index distance orders the candidates the same way the eye
+ * would order them by pixel distance.
+ */
+function closestByIndex(candidates: readonly number[], ref: number): number {
+  return candidates.reduce((best, i) =>
+    Math.abs(i - ref) < Math.abs(best - ref) || (Math.abs(i - ref) === Math.abs(best - ref) && i < best)
+      ? i
+      : best,
+  )
+}
+
+/**
+ * Insert `clip` onto the track `trackId` already names via `insertClipAt`,
+ * then read back WHERE it actually landed — `insertClipAt` mints the placed
+ * item's id itself and doesn't hand it back, so the placed item is found by
+ * diffing the track's item ids before/after the call.
+ *
+ * Always re-normalizes the result before reading it back (`normalizeTracks`
+ * is a no-op, same-reference return when order is already canonical — see
+ * its own doc — so this costs nothing on the common path). That matters for
+ * exactly one case here: dropping onto the empty base row (index 0) flips it
+ * from overlay-kind to video-kind the moment it gains a video item, which can
+ * move its position in the canonical video-block/overlay-block stack
+ * (`orderedTrackArray`) — so the track's index has to be re-resolved by id,
+ * never assumed stable across the insert.
+ */
+function placeOnTrack<P extends Project>(
+  project: P,
+  trackId: string,
+  clip: NewClipInput,
+  dropAt: number,
+  ripple: boolean,
+  createdTrack: boolean,
+): PlacedClipResult<P> {
+  const before = new Set(
+    (normalizeTracks(project).tracks ?? []).find(t => t.id === trackId)?.items.map(it => it.id) ?? [],
+  )
+  const normalized = normalizeTracks(insertClipAt(project, trackId, clip, dropAt, { ripple }))
+  const nextTracks = normalized.tracks ?? []
+  const trackIndex = nextTracks.findIndex(t => t.id === trackId)
+  const placedItem = trackIndex >= 0 ? nextTracks[trackIndex].items.find(it => !before.has(it.id)) : undefined
+
+  return {
+    project: normalized,
+    trackIndex,
+    start: placedItem?.start ?? 0,
+    itemId: placedItem?.id,
+    createdTrack,
+  }
+}
+
+/**
+ * Step 5 of the algorithm: no existing video track has room, so mint a fresh
+ * one and place the clip there. The new track is appended empty (overlay-kind
+ * by `trackGroupKind`, since it holds no items), then `placeOnTrack`'s own
+ * re-normalize after the insert is what promotes it into the video block —
+ * at the END of that block, i.e. the TOP-most video row, because
+ * `orderedTrackArray` is a STABLE partition: the new track was the very last
+ * element before the re-sort, so among video-kind tracks (which it now is)
+ * it is still the last one encountered, and "last in the video group" is the
+ * highest index in a contiguous video-first stack.
+ */
+function placeOnNewTrack<P extends Project>(
+  project: P,
+  tracks: readonly VisualTrack[],
+  clip: NewClipInput,
+  dropAt: number,
+  ripple: boolean,
+): PlacedClipResult<P> {
+  const newId = nextVisualTrackId(tracks)
+  const withNewTrack: P = { ...project, tracks: [...tracks, { id: newId, items: [] }] } as P
+  return placeOnTrack(withNewTrack, newId, clip, dropAt, ripple, true)
+}
+
+/**
+ * Place a single newly-dropped clip on the timeline, following the shared
+ * drop rule (see the module doc comment above for who calls this).
+ *
+ * Pure: never mutates `project`, its tracks/items, or `placement.clip`.
+ *
+ * ALGORITHM
+ * 0. Guard — `clip.sourceDuration` must be a finite number > 0, or nothing is
+ *    placed (mirrors the guard the canvas drop handler and the host's
+ *    `FootagePanel.hasPlaceableDuration` already apply before a drag even
+ *    starts).
+ * 1. Resolve the drop point: snap `atTime` to the nearest in-tolerance
+ *    `snapTimes` entry (see `resolveDropPoint`), then clamp to `>= 0`.
+ * 2. Gather video-placement candidate tracks (see `isVideoCandidate`).
+ * 3. `ref` — the preferred index if given, else 0 — is the point every
+ *    "closest" measurement below is relative to.
+ * 4a. Ripple ON: the preferred track if it's a candidate, else the closest
+ *     candidate (ties → lower index), else mint a new track. Collision never
+ *     disqualifies a candidate here — ripple means "push what's in the way",
+ *     so there is nothing to collide with.
+ * 4b. Ripple OFF: the closest candidate (ties → lower index) whose
+ *     `[dropAt, dropAt + sourceDuration]` window is free of existing items
+ *     (`overlapsAny`, cuts.ts — same EPSILON tolerance every other placement
+ *     op in this codebase uses). No free candidate → mint a new track.
+ * 5. New track: see `placeOnNewTrack`.
+ */
+/**
+ * Where a dropped clip WOULD land, WITHOUT placing it — the resolved
+ * video-track index in normalized order, or `normalizeTracks(project).tracks.length`
+ * (a row that does not exist yet) when a NEW video track would be created.
+ *
+ * This is the EXACT selection `placeDroppedClip` makes (it calls this), so a
+ * caller can draw a pre-ingest ghost band on the row the real clip will land on
+ * instead of wherever the pointer happened to be — a filesystem drop that
+ * released over an overlay/image row must still ghost on a VIDEO row, because
+ * that is where the clip resolves to. `closestByIndex` here, and the ghost
+ * renderer's own "unknown index falls back to the base video row" (see
+ * `pendingDropBands`), together guarantee the ghost never sits on an overlay
+ * row. `clip.sourceDuration` matters only in the ripple-OFF free-gap test —
+ * pass the ghost's fast local probe.
+ */
+export function resolveDropTrackIndex<P extends Project>(
+  project: P,
+  placement: Pick<DroppedClipPlacement, 'atTime' | 'preferredTrackIndex' | 'ripple' | 'snapTimes' | 'snapToleranceSec'>
+    & { clip: Pick<NewClipInput, 'sourceDuration'> },
+): number {
+  const { clip, ripple = false, preferredTrackIndex } = placement
+  const dropAt = Math.max(0, resolveDropPoint(placement))
+  const tracks = normalizeTracks(project).tracks ?? []
+  const candidateIdxs: number[] = []
+  tracks.forEach((t, i) => { if (isVideoCandidate(t, i)) candidateIdxs.push(i) })
+  const ref = preferredTrackIndex >= 0 ? preferredTrackIndex : 0
+
+  if (ripple) {
+    // Ripple ON — collision never disqualifies a candidate.
+    if (candidateIdxs.includes(preferredTrackIndex)) return preferredTrackIndex
+    if (candidateIdxs.length > 0) return closestByIndex(candidateIdxs, ref)
+    return tracks.length // no video row exists ⇒ a fresh one would be created
+  }
+
+  // Ripple OFF — only a candidate whose drop window is actually free.
+  const freeIdxs = candidateIdxs.filter(
+    i => !overlapsAny(dropAt, dropAt + clip.sourceDuration, tracks[i].items),
+  )
+  if (freeIdxs.length === 0) return tracks.length
+  return closestByIndex(freeIdxs, ref)
+}
+
+export function placeDroppedClip<P extends Project>(
+  project: P,
+  placement: DroppedClipPlacement,
+): PlacedClipResult<P> {
+  const { clip, ripple = false } = placement
+
+  // 0. Guard — an unplaceable clip places nothing, by reference.
+  if (!(Number.isFinite(clip.sourceDuration) && clip.sourceDuration > 0)) return nothingPlaced(project)
+
+  // 1. Drop point + target row. The row is resolved by `resolveDropTrackIndex`
+  // so placement and the pre-ingest ghost band can never diverge.
+  const dropAt = Math.max(0, resolveDropPoint(placement))
+  const tracks = normalizeTracks(project).tracks ?? []
+  const targetIdx = resolveDropTrackIndex(project, placement)
+
+  // targetIdx past the end of the (same, normalized) array ⇒ no existing video
+  // row fits ⇒ a new track is created.
+  if (targetIdx >= tracks.length) return placeOnNewTrack(project, tracks, clip, dropAt, ripple)
+  return placeOnTrack(project, tracks[targetIdx].id, clip, dropAt, ripple, false)
+}