auricui-skill 0.0.0-stage → 0.1.2

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/theme-changes.ts

@@ -0,0 +1,31 @@
+/**
+ * How many times the theme (`<html data-theme>`) has changed since the page loaded, for what draws the theme's colors
+ * on a canvas (the audio meters, the waveforms): a canvas keeps the colors it was drawn with, so it draws again when
+ * this changes. One observer for the whole page, made when the first one asks.
+ */
+import React from 'react';
+
+let changes = 0;
+const listeners = new Set<() => void>();
+let watching = false;
+
+function watch(): void {
+  if (watching || typeof MutationObserver === 'undefined' || typeof document === 'undefined') return;
+  watching = true;
+  let theme = document.documentElement.dataset.theme;
+  new MutationObserver(() => {
+    if (document.documentElement.dataset.theme === theme) return;
+    theme = document.documentElement.dataset.theme;
+    changes += 1;
+    for (const fn of listeners) fn();
+  }).observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
+}
+
+/** A number that changes when the theme does: put it among an effect's dependencies to draw again. */
+export function useThemeChanges(): number {
+  return React.useSyncExternalStore(
+    (fn) => { watch(); listeners.add(fn); return () => { listeners.delete(fn); }; },
+    () => changes,
+    () => 0,
+  );
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/thumb-cache.ts

@@ -0,0 +1,63 @@
+/**
+ * Which thumbnails the timeline wants: the cell width shared by shooting and drawing, and the step shots are taken at.
+ */
+
+/**
+ * How wide one thumbnail cell is on the timeline — the one number shooting and drawing share. If they ever differ,
+ * shooting follows the film's steps and drawing the clip's, and every cell shows its neighbor's frame.
+ */
+export const THUMB_CELL_PX = 80;
+
+/**
+ * The step snapped up to a fixed ladder (1 · 2 · 2.5 · 5 × 10ⁿ ms). The raw step (cell width / px per ms) changes with
+ * every zoom, which would make every zoom a new set of times and keys and shoot the whole timeline again. On the
+ * ladder, zooming within a rung keeps the same times; cells are at most 2.5× sparser and still filled (each cell takes
+ * the nearest shot).
+ */
+const LADDER = [1, 2, 2.5, 5];
+export function ladderStepMs(rawMs: number): number {
+  if (!(rawMs > 0)) return rawMs;
+  let scale = 10 ** Math.floor(Math.log10(rawMs));
+  for (;;) {
+    for (const k of LADDER) {
+      const step = k * scale;
+      if (step >= rawMs - 1e-9) return step;
+    }
+    scale *= 10;
+  }
+}
+
+/** The stretch one picture clip takes on the timeline. */
+export interface ThumbSpan {
+  startMs: number;
+  endMs: number;
+}
+
+/**
+ * One extra shot for every clip no step falls into (times and spans in the clip's source ms). Zoomed out, a step can
+ * be longer than a clip, and that clip would show its neighbors' frames, at that zoom for good. The extra shot is ~28% into the clip (its first frames
+ * often still fade in), fixed by the clip alone so it stays cached across zooms.
+ */
+export function thumbAnchorTimes(opts: {
+  times: readonly number[];
+  spans: readonly ThumbSpan[];
+  fromMs?: number;
+  toMs?: number;
+}): number[] {
+  const from = opts.fromMs ?? -Infinity;
+  const to = opts.toMs ?? Infinity;
+  const out: number[] = [];
+  for (const span of opts.spans) {
+    const dur = span.endMs - span.startMs;
+    if (!(dur > 0)) continue;
+    if (span.endMs <= from || span.startMs >= to) continue;
+    if (opts.times.some((t) => t >= span.startMs && t < span.endMs)) continue;
+    /* 28% in, not before 240 ms, not past the end; clips under 240 ms take the middle */
+    const into = dur <= 240
+      ? dur / 2
+      : Math.min(Math.max(240, dur * 0.28), Math.max(0, dur - 40));
+    const t = Math.round(span.startMs + into);
+    if (!out.includes(t)) out.push(t);
+  }
+  return out;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/thumb-cell.ts

@@ -0,0 +1,8 @@
+/**
+ * How a cell of a clip's thumbnail row is drawn (BlockThumbs): at its own width. An <img> takes the page's
+ * `max-width: 100%`, so in a clip narrower than a cell every picture was squeezed to the clip's width while the
+ * cells kept their steps, and the clip color showed between them, as if the pictures were broken.
+ */
+export function thumbCellStyle(left: number, width: number, height: number) {
+  return { left, width, maxWidth: 'none', height, opacity: 0.9 } as const;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/thumb-frame.ts

@@ -0,0 +1,76 @@
+/**
+ * Thumbnail keys: which clip, and which millisecond within itself, a thumbnail shows.
+ *
+ * ProjectView builds the keys as `mtime:clipId@intoMs#v` (the source file's mtime, the clip, the in-clip millisecond).
+ * Keyed by the clip's own millisecond (counting its trim) rather than film time, moving a clip keeps its pictures;
+ * only trimming it or changing its file gives new keys.
+ */
+
+/** A thumbnail key back to "which clip, which in-clip millisecond". Null for keys it does not recognize. */
+function parseClipFrameKey(key: string): { id: string; intoMs: number } | null {
+  const hash = key.lastIndexOf('#');
+  const at = key.lastIndexOf('@', hash);
+  if (at < 0 || hash <= at) return null;
+  const intoMs = Number(key.slice(at + 1, hash));
+  if (!Number.isFinite(intoMs)) return null;
+  const left = key.slice(0, at);
+  const colon = left.lastIndexOf(':');
+  if (colon < 0) return null;
+  return { id: left.slice(colon + 1), intoMs };
+}
+
+/** Which thumbnails belong to a clip on the timeline. */
+export function clipThumbId(block: { clipId?: string; loc?: string; id: string }): string {
+  return block.clipId || block.loc || block.id;
+}
+
+/**
+ * The in-clip millisecond at the clip's left edge. A move keeps the left edge's frame; pulling the left edge reaches
+ * deeper into the source, as a video seek would.
+ */
+export function thumbIntoOrigin(opts: {
+  committedStart: number;
+  committedEnd: number;
+  visualStart: number;
+  visualEnd: number;
+  trimFromMs: number;
+  /** source ms per film ms: the keys are the source's, so a left trim of a sped-up clip reaches `speed` times deeper */
+  speed?: number;
+}): number {
+  const visualDur = opts.visualEnd - opts.visualStart;
+  const committedDur = opts.committedEnd - opts.committedStart;
+  const leftMoved = Math.abs(opts.visualStart - opts.committedStart) > 0.5;
+  const durChanged = Math.abs(visualDur - committedDur) > 0.5;
+  return opts.trimFromMs + (leftMoved && durChanged ? (opts.visualStart - opts.committedStart) * (opts.speed ?? 1) : 0);
+}
+
+/** The thumbnails in memory, per clip: in-clip ms → address. What BlockThumbs draws, detached from film time. */
+export function indexClipThumbs(
+  thumbs: ReadonlyMap<string, string>,
+): Map<string, Map<number, string>> {
+  const by = new Map<string, Map<number, string>>();
+  for (const [key, url] of thumbs) {
+    const parsed = parseClipFrameKey(key);
+    if (!parsed) continue;
+    let strip = by.get(parsed.id);
+    if (!strip) {
+      strip = new Map();
+      by.set(parsed.id, strip);
+    }
+    if (!strip.has(parsed.intoMs)) strip.set(parsed.intoMs, url);
+  }
+  return by;
+}
+
+/**
+ * A page clip's thumbnails are drawn with its overrides (SPEC §1), the changes made inside it in Studio: as a short
+ * token for a frame's address and key, '' when it has none of a layer's (its fades alone change no picture). Another
+ * change, another token: the timeline asks for the clip's pictures again.
+ */
+export function overridesToken(overrides: readonly unknown[] | undefined): string {
+  if (!overrides?.some((o) => typeof o === 'object' && o !== null && 'at' in o)) return '';
+  const text = JSON.stringify(overrides);
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) { h ^= text.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+  return (h >>> 0).toString(36);
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/thumb-pick.ts

@@ -0,0 +1,42 @@
+/**
+ * Which shot a cell of a clip's thumbnail row shows (BlockThumbs). The cells sit on the source's own time grid, the
+ * first one straddling the clip's start; a cell stands for the part of it inside the clip, so the straddling one asks
+ * for the clip's start, not for the grid time before it (a trimmed clip's row must not open on a frame from before its
+ * in-point, often the source's black first frame). A shot from inside the clip beats a nearer one from outside it;
+ * with none inside yet, the nearest of any: a far picture beats a half-empty clip, and exact shots replace it as they
+ * arrive.
+ */
+
+/** Index of the sorted time nearest to `want` (binary search: dozens of cells, each scanning would be thousands of steps). */
+function nearestIndex(sorted: readonly number[], want: number, lo = 0, hi = sorted.length - 1): number {
+  const first = lo;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (sorted[mid]! < want) lo = mid + 1; else hi = mid;
+  }
+  return lo > first && want - sorted[lo - 1]! < sorted[lo]! - want ? lo - 1 : lo;
+}
+
+/** First index whose time is at least `at` (sorted.length when none is). */
+function firstAtLeast(sorted: readonly number[], at: number): number {
+  let lo = 0;
+  let hi = sorted.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (sorted[mid]! < at) lo = mid + 1; else hi = mid;
+  }
+  return lo;
+}
+
+/**
+ * The shot for a cell standing at `cellMs` on the grid of a clip that shows `fromMs`–`toMs` of its source (in-clip
+ * source ms): `undefined` when there are no shots at all.
+ */
+export function pickShot(sorted: readonly number[], cellMs: number, fromMs: number, toMs: number): number | undefined {
+  if (!sorted.length) return undefined;
+  const want = Math.min(Math.max(cellMs, fromMs), toMs);
+  const lo = firstAtLeast(sorted, fromMs);
+  const hi = firstAtLeast(sorted, toMs + 1) - 1;
+  if (lo <= hi) return sorted[nearestIndex(sorted, want, lo, hi)];
+  return sorted[nearestIndex(sorted, want)];
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/timecode.ts

@@ -0,0 +1,161 @@
+/**
+ * Timecode: `00:00:47:29`, hours:minutes:seconds:frames, the way editors read a position.
+ *
+ * The film has no frames: time is milliseconds and the picture is drawn live in the browser. The last two digits are
+ * a reading scale, not a unit of the document: people cut by frame ("second 47, frame 29"). The scale is the
+ * project's frame rate (kept in `.film/settings.json`, see lib/project-settings), 30 until a project says otherwise.
+ * It also sets the grid a click, a drag and the arrow keys land on.
+ *
+ * At 23.976, 29.97 and 59.94 the timecode is the clock's: the seconds are the film's own seconds, and the frames count
+ * the frames that start within that second (29 or 30 of them at 29.97). It never drifts from the ruler, which a
+ * non-drop SMPTE timecode does (3.6 s an hour), and it skips no numbers the way drop-frame timecode (`;`) does; the
+ * price is that the last frame number of a second is missing about once a thousand frames.
+ *
+ * Fixed width (`00:` even under an hour): a timecode is read while it changes, and a changing width makes it jitter.
+ */
+import { useSyncExternalStore } from 'react';
+
+/** The frame rate before a project says otherwise, and the grid the ruler's steps are counted in. */
+export const DISPLAY_FPS = 30;
+
+/**
+ * The rates a project can be set to and a video exported at: the common ones (the NTSC 23.976, 29.97 and 59.94 are
+ * what cameras and phones record), and 120 for high frame rate.
+ */
+export const FRAME_RATES = [23.976, 24, 25, 29.97, 30, 48, 50, 59.94, 60, 120] as const;
+
+/** A rate as it really is: the NTSC ones are 24000/1001, 30000/1001 and 60000/1001. */
+export function exactRate(fps: number): number {
+  if (!(fps > 0) || !Number.isFinite(fps)) return DISPLAY_FPS;
+  const whole = Math.round(fps);
+  /* 23.976, 29.97, 59.94: a whole rate slowed by 1000/1001 */
+  if (Math.abs(fps - whole) > 0.001 && Math.abs(fps - (whole * 1000) / 1001) < 0.01) return (whole * 1000) / 1001;
+  return fps;
+}
+
+/** The rate an editor names: a probed 29.97002997 is 29.97, 24.0 is 24; another rate is kept as it is. */
+export function namedRate(fps: number): number {
+  const named = FRAME_RATES.find((r) => Math.abs(r - fps) < 0.01);
+  return named ?? Math.round(fps * 1000) / 1000;
+}
+
+/**
+ * A project's rate before one is chosen: the first footage's that is a rate a project can have (in the order given:
+ * the film's footage clips by time, then the project's other videos), else 30.
+ */
+export function footageFps(rates: readonly (number | null | undefined)[]): number {
+  for (const r of rates) {
+    if (r == null || !(r > 0)) continue;
+    const named = namedRate(r);
+    if ((FRAME_RATES as readonly number[]).includes(named)) return named;
+  }
+  return DISPLAY_FPS;
+}
+
+/** How many frames ⇧ + an arrow steps: a second's worth, whole. */
+export function secondFrames(fps = currentFps): number {
+  return Math.max(1, Math.round(fps));
+}
+
+/* ── the project's rate, for everything that shows or snaps to frames ── */
+
+let currentFps: number = DISPLAY_FPS;
+const listeners = new Set<() => void>();
+
+/** The rate frames are counted in now (the project open). */
+export function timecodeFps(): number {
+  return currentFps;
+}
+
+/** Count frames at this rate from now on (a project opened, or its rate changed). */
+export function setTimecodeFps(fps: number): void {
+  const next = fps > 0 && Number.isFinite(fps) ? fps : DISPLAY_FPS;
+  if (next === currentFps) return;
+  currentFps = next;
+  for (const fn of listeners) fn();
+}
+
+/** The rate, kept up to date: a component that shows frames renders again when the project's rate changes. */
+export function useTimecodeFps(): number {
+  return useSyncExternalStore(
+    (fn) => { listeners.add(fn); return () => { listeners.delete(fn); }; },
+    timecodeFps,
+    () => DISPLAY_FPS,
+  );
+}
+
+function pad(n: number): string {
+  return String(n).padStart(2, '0');
+}
+
+/**
+ * The frame a time falls on, counted from 0. Rounded to the nearest: a frame at 30 lasts 33.33… ms, which no float or
+ * whole millisecond holds exactly — rounded down, 500 ms (14.999… frames) read as frame 14 and a time written to the
+ * millisecond (1033 ms) as the frame before its own.
+ */
+export function frameAt(ms: number, fps = currentFps): number {
+  return Number.isFinite(ms) && ms > 0 ? Math.round((ms * exactRate(fps)) / 1000) : 0;
+}
+
+/** The time of a frame. */
+export function frameMs(frame: number, fps = currentFps): number {
+  return (frame * 1000) / exactRate(fps);
+}
+
+/**
+ * The frame nearest `ms`, in ms. What an edit on the timeline writes: a drag lands between frames (a second is 1998 ms
+ * of pointer travel), and film.html should hold the moments a person sees on the frame grid.
+ */
+export function snapToFrame(ms: number, fps = currentFps): number {
+  return frameMs(frameAt(ms, fps), fps);
+}
+
+/**
+ * `frames` frames on from `ms` (negative = back), landing exactly on a frame: stepping by adding 33.33… ms gathers
+ * float error until one frame shows twice and the next is skipped.
+ */
+export function stepFrames(ms: number, frames: number, fps = currentFps): number {
+  return frameMs(Math.max(0, frameAt(ms, fps) + frames), fps);
+}
+
+/** A frame as the clock reads it: the whole second it starts in, and which frame of that second it is. */
+function clockOf(frame: number, fps: number): { secs: number; frames: number } {
+  const rate = exactRate(fps);
+  const secs = Math.floor(frame / rate + 1e-9);
+  /* the first frame that starts in this second */
+  const first = Math.ceil(secs * rate - 1e-9);
+  return { secs, frames: frame - first };
+}
+
+/**
+ * The time, in seconds, a timecode's second and frame name: clockOf's way back, so a typed `00:00:17:00` is the frame
+ * that shows as it. At 29.97 the 17th second's first frame starts 17 ms after 17 s; `17 + 0 / 29.97` lands a frame
+ * early, on the one that reads `00:00:16:29`.
+ */
+export function timecodeSeconds(secs: number, frames: number, fps = currentFps): number {
+  const rate = exactRate(fps);
+  return (Math.ceil(secs * rate - 1e-9) + frames) / rate;
+}
+
+export function formatTimecode(ms: number, opts?: { hours?: boolean; fps?: number }): string {
+  const { secs, frames } = clockOf(frameAt(ms, opts?.fps), opts?.fps ?? currentFps);
+  const tail = `${pad(Math.floor((secs % 3600) / 60))}:${pad(secs % 60)}:${pad(frames)}`;
+  /* `hours: false` drops the always-`00:` hour of a film under an hour; the caller decides once per film, so the
+     width still never changes */
+  if (opts?.hours === false && secs < 3600) return tail;
+  return `${pad(Math.floor(secs / 3600))}:${tail}`;
+}
+
+/**
+ * The short label on the ruler: `mm:ss` on whole seconds (with hours past an hour), `12f` in between. Full timecodes
+ * on every tick would be a wall of `00:00:47:29`.
+ */
+export function formatRulerLabel(ms: number, fps = currentFps): string {
+  /* a tick is a place on the clock, not a frame: a whole second is labeled as one even where no frame starts on it */
+  const secs = Math.max(0, Math.floor(ms / 1000 + 1e-6));
+  const frames = frameAt(ms, fps) - Math.ceil(secs * exactRate(fps) - 1e-9);
+  if (ms - secs * 1000 >= 0.5 && frames > 0) return `${frames}f`;
+  const h = Math.floor(secs / 3600);
+  const clock = `${pad(Math.floor((secs % 3600) / 60))}:${pad(secs % 60)}`;
+  return h > 0 ? `${h}:${clock}` : clock;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/timeline-clipboard.ts

@@ -0,0 +1,279 @@
+/**
+ * Copy and paste on the timeline.
+ *
+ * The clipboard holds clips by their id in film.html, not by their place: a split, a delete or an undo renumbers the
+ * places (`film.html#t.c`), and a place copied before then would paste whichever clip sits there now. A paste copies
+ * the clip as film.html has it then; a clip that is gone by then is reported, not swapped for another.
+ *
+ * Start times are kept so several clips keep their spacing; tracks are kept so clips copied from several tracks go
+ * back to their own tracks. Only clips copied from one track follow a track the person points at.
+ */
+import type { Op } from '../api.ts';
+import { newTrackSide } from './timeline-drag.ts';
+import {
+  TOUCH_MS, freshLink, insertPointOn, mainTrackOf, magnetOn, planRoom,
+  type EditModel, type EditPlan, type Placed, type Switches, type TrackDest,
+} from './timeline-edit.ts';
+import type { TimelineBlock, TimelineTrack } from './timeline-layout';
+
+export type TimelineClipboardItem = {
+  /** The clip's id in film.html. */
+  clipId: string;
+  startMs: number;
+  /** The clip's length: a paste checks whether the spot is free. */
+  durMs: number;
+  lane: string;
+};
+
+export function laneOfBlock(tracks: readonly TimelineTrack[], id: string): string | null {
+  for (const track of tracks) {
+    if (track.blocks.some((b) => b.id === id)) return track.lane;
+  }
+  return null;
+}
+
+/** The row by name; when a spread row is gone, the same film.html track. */
+export function trackByLane(
+  tracks: readonly TimelineTrack[],
+  lane: string,
+): TimelineTrack | undefined {
+  const exact = tracks.find((tr) => tr.lane === lane);
+  if (exact) return exact;
+  const doc = /^doc-(\d+)/.exec(lane)?.[1];
+  if (doc == null) return undefined;
+  return tracks.find((tr) => tr.docIndex === Number(doc));
+}
+
+export function clipboardItemsOf(
+  blocks: readonly TimelineBlock[],
+  tracks: readonly TimelineTrack[],
+): TimelineClipboardItem[] {
+  return blocks
+    .filter((b) => b.clipId)
+    .map((b) => ({
+      clipId: b.clipId!,
+      startMs: b.startMs,
+      durMs: Math.max(1, b.endMs - b.startMs),
+      lane: laneOfBlock(tracks, b.id) ?? '',
+    }))
+    .sort((a, b) => a.startMs - b.startMs);
+}
+
+/**
+ * The copied clips as the timeline has them now, and how many are gone (deleted, or undone since the copy). Length and
+ * track are taken afresh, since the paste copies the clip as it is now; the start times stay as copied, for spacing.
+ */
+export function clipboardNow(
+  clipboard: readonly TimelineClipboardItem[],
+  tracks: readonly TimelineTrack[],
+): { items: TimelineClipboardItem[]; missing: number } {
+  const items: TimelineClipboardItem[] = [];
+  for (const item of clipboard) {
+    const track = tracks.find((tr) => tr.blocks.some((b) => b.clipId === item.clipId));
+    const block = track?.blocks.find((b) => b.clipId === item.clipId);
+    if (!track || !block) continue;
+    items.push({ ...item, durMs: Math.max(1, block.endMs - block.startMs), lane: track.lane });
+  }
+  return { items, missing: clipboard.length - items.length };
+}
+
+/** The film.html track a row belongs to (`doc-3#2` is a spread row of track 3). */
+function docIndexOfLane(lane: string): number | null {
+  const doc = /^doc-(\d+)/.exec(lane)?.[1];
+  return doc == null ? null : Number(doc);
+}
+
+/**
+ * The links copies get: copies of clips linked together and pasted together are linked to each other, with a link
+ * of their own (not the originals', or moving a copy would move the original); a copy pasted without the clips its
+ * original is linked to is linked to nothing. Clip id → the link for its copy (null: none); unlinked clips are left
+ * out.
+ */
+export function copyLinks(clipIds: readonly string[], model: EditModel): Map<string, string | null> {
+  const linkOf = new Map(model.flatMap((t) => t.clips.flatMap((c) => (c.link ? [[c.id, c.link] as const] : []))));
+  const count = new Map<string, number>();
+  for (const id of clipIds) {
+    const link = linkOf.get(id);
+    if (link) count.set(link, (count.get(link) ?? 0) + 1);
+  }
+  const fresh = new Map<string, string>();
+  const taken = new Set<string>();
+  const out = new Map<string, string | null>();
+  for (const id of clipIds) {
+    const link = linkOf.get(id);
+    if (!link) continue;
+    if ((count.get(link) ?? 0) < 2) { out.set(id, null); continue; }
+    if (!fresh.has(link)) {
+      const made = freshLink(model, `${id}-copy`, taken);
+      taken.add(made);
+      fresh.set(link, made);
+    }
+    out.set(id, fresh.get(link)!);
+  }
+  return out;
+}
+
+/** A copy to put down: of clip `from`, at this time, onto this track; `source` is the track it was copied from. */
+type CopySpan = { from: string; startMs: number; endMs: number; dest: TrackDest; source: number };
+
+const overlap = (a: { startMs: number; endMs: number }, b: { startMs: number; endMs: number }): boolean => (
+  a.startMs < b.endMs - TOUCH_MS && a.endMs > b.startMs + TOUCH_MS
+);
+
+/**
+ * Copies put down, never cutting or moving what is there. Onto their track where that time is free; where it is taken
+ * (by a clip there, or by another copy) the copies headed there all go to a new track beside it instead (newTrackSide),
+ * and one more for each that would still overlap another. `keepOff` (the main track with the magnet) is
+ * always taken: copies headed there go to a new track right above it. Copies headed for a new track (`{ insert }`)
+ * open one per track they came from, so a group keeps its rows. The inserts onto tracks that are there go first, then
+ * the new tracks from the last place up, so every place written holds. `placed`: where each copy lands, by the id it
+ * was copied from.
+ */
+function placeCopies(
+  model: EditModel,
+  spans: readonly CopySpan[],
+  links: ReadonlyMap<string, string | null>,
+  keepOff: number | null = null,
+): { ops: Op[]; placed: Map<string, Placed> } {
+  const there: CopySpan[] = [];
+  /* a new track: where it opens, and how low it ends among those opened at that place (higher = lower down) */
+  const opened: { at: number; low: number; key: string; spans: CopySpan[] }[] = [];
+  const openAt = (at: number, low: number, key: string, span: CopySpan) => {
+    const found = opened.find((o) => o.at === at && o.key === key);
+    if (found) found.spans.push(span);
+    else opened.push({ at, low, key, spans: [span] });
+  };
+  const byTrack = new Map<number, CopySpan[]>();
+  for (const s of spans) {
+    if (typeof s.dest === 'object') openAt(s.dest.insert, s.source, `from-${s.source}`, s);
+    else byTrack.set(s.dest, [...(byTrack.get(s.dest) ?? []), s]);
+  }
+  for (const [index, group] of byTrack) {
+    const track = model.find((t) => t.index === index);
+    const clips = track?.clips ?? [];
+    const taken = index === keepOff
+      || group.some((s, i) => clips.some((c) => overlap(s, c)) || group.slice(0, i).some((o) => overlap(s, o)));
+    if (!taken) {
+      there.push(...group);
+      continue;
+    }
+    const side = newTrackSide(index, track?.role);
+    const rows: CopySpan[][] = [];
+    for (const s of [...group].sort((a, b) => a.startMs - b.startMs)) {
+      const row = rows.find((r) => !r.some((o) => overlap(s, o)));
+      if (row) row.push(s);
+      else rows.push([s]);
+    }
+    /* the first row next to the track, the others further away: above a picture track, below a sound one */
+    rows.forEach((row, n) => {
+      for (const s of row) openAt(side, side === index ? -n : n, `beside-${index}-${n}`, s);
+    });
+  }
+  const insertOf = (s: CopySpan, track: TrackDest): Op => ({
+    op: 'insert',
+    from: s.from,
+    at: Math.round(s.startMs) / 1000,
+    track,
+    ...(links.has(s.from) ? { link: links.get(s.from)! } : {}),
+  });
+  const ops: Op[] = there.map((s) => insertOf(s, s.dest));
+  const placed = new Map<string, Placed>(there.map((s) => [s.from, { startMs: s.startMs, endMs: s.endMs, track: s.dest }]));
+  /* a track opened at a place goes above those opened there before it: the lowest of them opens first */
+  for (const o of [...opened].sort((a, b) => b.at - a.at || b.low - a.low)) {
+    [...o.spans].sort((a, b) => a.startMs - b.startMs).forEach((s, i) => {
+      ops.push(insertOf(s, i === 0 ? { insert: o.at } : o.at));
+      placed.set(s.from, { startMs: s.startMs, endMs: s.endMs, track: { insert: o.at } });
+    });
+  }
+  return { ops, placed };
+}
+
+/**
+ * A paste: copied from one track, the copies go onto the track pointed at (`forceLane`) if any; from several, each
+ * back onto its own. The group's earliest clip lands at `atMs`, the rest keep their spacing. Put down (`place`), they
+ * never cut or move what is there: a taken spot opens a track beside it (placeCopies), and with the magnet a copy
+ * headed for the main track goes to a new track right above it. An insert makes room there instead,
+ * pushing what follows on, on the tracks they go in on (with linkage, what rides on the main track along). Null when a
+ * track it goes onto is locked or gone.
+ */
+export function pasteEdit(
+  clipboard: readonly TimelineClipboardItem[],
+  tracks: readonly TimelineTrack[],
+  model: EditModel,
+  atMs: number,
+  forceLane: string | null,
+  opts: { mode: 'place' | 'insert' } & Partial<Switches>,
+): Op[] | null {
+  if (!clipboard.length) return [];
+  const base = Math.min(...clipboard.map((item) => item.startMs));
+  const copiedTracks = new Set(clipboard.map((item) => docIndexOfLane(item.lane) ?? item.lane));
+  const force = forceLane && copiedTracks.size === 1 ? forceLane : null;
+  const spans = clipboard.map((item) => {
+    const row = trackByLane(tracks, force || item.lane);
+    const startMs = Math.round(Math.max(0, atMs) + (item.startMs - base));
+    return { item, track: row?.docIndex, locked: Boolean(row?.locked), startMs, endMs: startMs + item.durMs };
+  });
+  if (spans.some((s) => s.track == null || s.locked)) return null;
+  const links = copyLinks(clipboard.map((item) => item.clipId), model);
+  if (opts.mode === 'place') {
+    return placeCopies(model, spans.map((s) => ({
+      from: s.item.clipId, startMs: s.startMs, endMs: s.endMs, dest: s.track!, source: s.track!,
+    })), links, opts.magnet ? mainTrackOf(model) : null).ops;
+  }
+  const insertOf = (s: (typeof spans)[number]): Op => ({
+    op: 'insert',
+    from: s.item.clipId,
+    at: s.startMs / 1000,
+    track: s.track!,
+    ...(links.has(s.item.clipId) ? { link: links.get(s.item.clipId)! } : {}),
+  });
+  /* the copies go in first, so a clip pasted inside itself is copied whole before the insert cuts it */
+  const room = planRoom(model, spans.map((s) => ({ track: s.track!, startMs: s.startMs, endMs: s.endMs })), { ...opts, mode: 'insert' });
+  return [...spans.map(insertOf), ...room.ops];
+}
+
+/**
+ * Copies of clips put down where a drag lets them go (⌥-drag): the clips stay, a copy of each lands
+ * `deltaMs` later (earlier when negative) on its track or the one in `to`, never cutting what is there (placeCopies).
+ * With the magnet, when the grabbed one's copy goes onto the main track, the copies headed there go in end to end at
+ * the insert point under the hand (`pointerMs`), what follows moving on. Copies of clips linked together are linked to
+ * each other. `placed`: where each copy lands, by the clip it copies. Null when a track it goes onto is locked.
+ */
+export function planCopies(
+  model: EditModel,
+  spec: { ids: readonly string[]; deltaMs: number; to?: ReadonlyMap<string, TrackDest>; pointerMs?: number } & Partial<Switches>,
+): EditPlan | null {
+  const clips = model.flatMap((t) => t.clips.map((c) => ({ c, track: t.index })));
+  const picked = spec.ids.flatMap((id) => clips.filter((x) => x.c.id === id));
+  if (!picked.length) return null;
+  /* the group keeps its shape; none goes before 0 */
+  const shift = Math.max(spec.deltaMs, -Math.min(...picked.map((x) => x.c.startMs)));
+  const spans = picked.map(({ c, track }): CopySpan => {
+    const startMs = Math.max(0, c.startMs + shift);
+    return { from: c.id, startMs, endMs: startMs + c.endMs - c.startMs, dest: spec.to?.get(c.id) ?? track, source: track };
+  });
+  if (spans.some((s) => typeof s.dest === 'number' && model.find((t) => t.index === s.dest)?.locked)) return null;
+  const links = copyLinks(spec.ids, model);
+  const main = mainTrackOf(model);
+  const lead = spans[0]!;
+  if (!(spec.magnet && main != null && lead.dest === main && magnetOn(model, main, true))) {
+    const { ops, placed } = placeCopies(model, spans, links, spec.magnet ? main : null);
+    return { ops, placed, shortMs: 0 };
+  }
+  /* onto the main track with the magnet: in end to end at the insert point, what follows (and rides on it) moving on */
+  const going = spans.filter((s) => s.dest === main).sort((a, b) => a.startMs - b.startMs);
+  let at = insertPointOn(model, main, spec.pointerMs ?? lead.startMs, lead.startMs);
+  const inserts: Op[] = [];
+  const placed = new Map<string, Placed>();
+  const startAt = at;
+  for (const s of going) {
+    const len = s.endMs - s.startMs;
+    inserts.push({ op: 'insert', from: s.from, at: Math.round(at) / 1000, track: main, ...(links.has(s.from) ? { link: links.get(s.from)! } : {}) });
+    placed.set(s.from, { startMs: at, endMs: at + len, track: main });
+    at += len;
+  }
+  const room = planRoom(model, [{ track: main, startMs: startAt, endMs: at }], { mode: 'insert', magnet: spec.magnet, linkage: spec.linkage });
+  const rest = placeCopies(model, spans.filter((s) => s.dest !== main), links, main);
+  for (const [id, p] of rest.placed) placed.set(id, p);
+  return { ops: [...inserts, ...room.ops, ...rest.ops], placed, shortMs: room.shortMs };
+}