auricui-skill 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,160 @@
+/**
+ * What the editor's keys act on, worked out from the timeline as it is drawn: the cuts ↑ / ↓ jump between, the clips
+ * ⌘B and ⇧⌘B split, and a selection moved a frame with ⌥ ← / →. Pure: the keys call these, the edits are written by
+ * the editor (components/ProjectView).
+ */
+import { MIN_BLOCK_MS } from './timeline-drag.ts';
+import { NO_SWITCHES, TOUCH_MS, mainTrackOf, planMove, type EditModel, type EditPlan, type Switches } from './timeline-edit.ts';
+import { stepFrames } from './timecode.ts';
+import type { TimelineBlock, TimelineTrack } from './timeline-layout';
+
+/**
+ * Every clip edge on the tracks that can be cut (not locked) and are seen (not hidden), in order, once each: what
+ * ↑ / ↓ go to. Clips not on film.html yet (a drop being written) are left out.
+ */
+export function cutPoints(tracks: readonly TimelineTrack[]): number[] {
+  const out = new Set<number>();
+  for (const tr of tracks) {
+    if (tr.locked || tr.hidden) continue;
+    for (const b of tr.blocks) {
+      if (!b.loc) continue;
+      out.add(Math.round(b.startMs));
+      out.add(Math.round(b.endMs));
+    }
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
+/** The next cut after `nowMs` (`dir` 1), or the one before it (-1); null when there is none that way. */
+export function nextCut(points: readonly number[], nowMs: number, dir: 1 | -1): number | null {
+  /* within a millisecond is where the playhead already is */
+  if (dir > 0) return points.find((p) => p > nowMs + 1) ?? null;
+  for (let i = points.length - 1; i >= 0; i--) if (points[i]! < nowMs - 1) return points[i]!;
+  return null;
+}
+
+/** Whether a cut at `atMs` falls inside a clip, far enough from both its ends (the split button's own rule). */
+export function splitsAt(b: Pick<TimelineBlock, 'startMs' | 'endMs'>, atMs: number): boolean {
+  return atMs > b.startMs + MIN_BLOCK_MS && atMs < b.endMs - MIN_BLOCK_MS;
+}
+
+const lockedRows = (tracks: readonly TimelineTrack[]) => new Set(tracks.filter((tr) => tr.locked).flatMap((tr) => tr.blocks.map((b) => b.id)));
+
+/**
+ * What ⌘B splits at the playhead: the selected clips it is inside; with nothing selected, the clip it is inside on the
+ * main track (the lowest picture track); else on the targeted track (`targetLane`), else on the topmost
+ * track that is seen and has one. Never a clip on a locked track. The clips linked to them are the caller's to add.
+ */
+export function splitTargets(
+  tracks: readonly TimelineTrack[],
+  selectedIds: readonly string[],
+  atMs: number,
+  targetLane: string | null,
+): TimelineBlock[] {
+  const locked = lockedRows(tracks);
+  const can = (b: TimelineBlock) => Boolean(b.loc && b.clipId) && !locked.has(b.id) && splitsAt(b, atMs);
+  if (selectedIds.length) return tracks.flatMap((tr) => tr.blocks).filter((b) => selectedIds.includes(b.id) && can(b));
+  const pictures = tracks.filter((tr) => tr.docIndex != null && tr.role !== 'audio');
+  const mainIndex = pictures.length ? Math.max(...pictures.map((tr) => tr.docIndex!)) : null;
+  const main = tracks.filter((tr) => tr.docIndex === mainIndex && !tr.hidden).flatMap((tr) => tr.blocks).find(can);
+  if (main) return [main];
+  const target = targetLane ? tracks.find((tr) => tr.lane === targetLane) : undefined;
+  if (target) {
+    const hit = target.blocks.find(can);
+    return hit ? [hit] : [];
+  }
+  for (const tr of tracks) {
+    if (tr.hidden) continue;
+    const hit = tr.blocks.find(can);
+    if (hit) return [hit];
+  }
+  return [];
+}
+
+/**
+ * What [ / ] select: every clip with a part before the playhead (`dir` -1) or after it
+ * (`dir` 1), on every track not locked — what to move when the film before or after a point moves along.
+ */
+export function sideTargets(tracks: readonly TimelineTrack[], atMs: number, dir: -1 | 1): TimelineBlock[] {
+  return tracks.filter((tr) => !tr.locked).flatMap((tr) => tr.blocks)
+    .filter((b) => Boolean(b.loc) && (dir > 0 ? b.endMs > atMs + 1 : b.startMs < atMs - 1));
+}
+
+/** What ⇧⌘B splits: every clip the playhead is inside, on every track not locked. */
+export function splitAllTargets(tracks: readonly TimelineTrack[], atMs: number): TimelineBlock[] {
+  return tracks.filter((tr) => !tr.locked).flatMap((tr) => tr.blocks).filter((b) => Boolean(b.loc && b.clipId) && splitsAt(b, atMs));
+}
+
+/**
+ * Clips (by id, the first leading) moved `frames` frames along their tracks, landing on the frame grid; a clip in the
+ * way stops them against it, uncut. Null when nothing can move (a locked track, the film's start, a clip right there,
+ * the main track with the magnet, which stays closed up).
+ */
+export function planNudge(model: EditModel, ids: readonly string[], frames: number, sw: Switches = NO_SWITCHES): EditPlan | null {
+  const lead = model.flatMap((t) => t.clips).find((c) => c.id === ids[0]);
+  if (!lead || !frames) return null;
+  const main = mainTrackOf(model);
+  if (sw.magnet && model.find((t) => t.index === main)?.clips.some((c) => ids.includes(c.id))) return null;
+  let deltaMs = stepFrames(lead.startMs, frames) - lead.startMs;
+  /* the room before the nearest clip they would run into, on each of their tracks */
+  const moving = new Set(ids);
+  for (const t of model) {
+    const others = t.clips.filter((c) => !moving.has(c.id));
+    for (const c of t.clips.filter((x) => moving.has(x.id))) {
+      for (const o of others) {
+        if (deltaMs > 0 && o.startMs >= c.endMs - TOUCH_MS) deltaMs = Math.min(deltaMs, o.startMs - c.endMs);
+        if (deltaMs < 0 && o.endMs <= c.startMs + TOUCH_MS) deltaMs = Math.max(deltaMs, o.endMs - c.startMs);
+      }
+    }
+  }
+  if (Math.abs(deltaMs) <= TOUCH_MS) return null;
+  const plan = planMove(model, { ids, deltaMs, pointerMs: lead.startMs + deltaMs, mode: 'place', ...sw });
+  return plan?.ops.length ? plan : null;
+}
+
+/** A track's name as Studio keeps it (`.film/settings.json`): the clips it had when it was named find it again. */
+export type SavedTrackName = { name: string; index: number; clips: string[] };
+
+export type ClipsOf = readonly { clips: readonly { id: string }[] }[];
+
+/**
+ * Which track each thing kept about a track (a name, a height) is on now: the track holding the most of the clips it
+ * had then, else its place (see trackNamesOf).
+ */
+export function placeSaved<T extends { index: number; clips: readonly string[] }>(saved: readonly T[], tracks: ClipsOf): Map<T, number> {
+  const out = new Map<T, number>();
+  const taken = new Set<number>();
+  const late: T[] = [];
+  for (const entry of saved) {
+    const had = new Set(entry.clips);
+    let best = -1;
+    let most = 0;
+    tracks.forEach((tr, i) => {
+      const n = tr.clips.filter((c) => had.has(c.id)).length;
+      if (n > most && !taken.has(i)) { most = n; best = i; }
+    });
+    if (best >= 0) { out.set(entry, best); taken.add(best); } else late.push(entry);
+  }
+  for (const entry of late) {
+    if (entry.index < tracks.length && !taken.has(entry.index)) { out.set(entry, entry.index); taken.add(entry.index); }
+  }
+  return out;
+}
+
+/**
+ * The names kept for tracks, by film.html track index now. A track is found by the clips it had when named (tracks
+ * move, and open and close above it, so its place changes; film.html gives a track no id of its own), the one holding
+ * the most of them; a track named while empty, or whose clips are all gone, by its place, when no other name took it.
+ */
+export function trackNamesOf(saved: readonly SavedTrackName[], tracks: ClipsOf): Map<number, string> {
+  return new Map([...placeSaved(saved, tracks)].map(([entry, i]) => [i, entry.name]));
+}
+
+/** The names to keep once track `index` is named `name` (an empty name takes its name away); names found nowhere go. */
+export function namedTrack(saved: readonly SavedTrackName[], tracks: ClipsOf, index: number, name: string): SavedTrackName[] {
+  const placed = placeSaved(saved, tracks);
+  const kept = saved.filter((entry) => placed.has(entry) && placed.get(entry) !== index)
+    .map((entry) => ({ ...entry, index: placed.get(entry)!, clips: (tracks[placed.get(entry)!]?.clips ?? []).map((c) => c.id) }));
+  const clean = name.trim().slice(0, 40);
+  return clean ? [...kept, { name: clean, index, clips: (tracks[index]?.clips ?? []).map((c) => c.id) }] : kept;
+}

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

@@ -0,0 +1,73 @@
+/**
+ * The timeline's switches, kept on this machine across projects, in the toolbar's order, on by default but the preview
+ * axis:
+ *   · `magnet` (主轨磁吸): the main track (the lowest picture track) stays closed up — a clip put on it goes in between,
+ *     one deleted or taken off it closes up after it, a trim or a new speed there moves what follows. Off, the main
+ *     track is like the others (lib/timeline-edit);
+ *   · `snap` (自动吸附): drags line up with edges and the playhead; off means "it lands exactly where I let go";
+ *   · `linkage` (联动): titles, overlays and sounds riding on a main-track clip move with it and go with it;
+ *   · `previewAxis` (预览轴): the picture follows the pointer over the timeline, the playhead staying where it is. Off
+ *     by default: the picture stays at the playhead until it is turned on.
+ *
+ * Clips sharing a `data-link` (a video and its detached sound) are always selected and edited together; ⌥-click picks
+ * one alone. The inspector reads the switches too (a slower speed pushes the next clip only with the magnet on), so a
+ * change is told to everyone listening.
+ */
+import { useSyncExternalStore } from 'react';
+
+import type { Switches } from './timeline-edit.ts';
+
+export type TimelinePrefs = { snap: boolean; magnet: boolean; linkage: boolean; previewAxis: boolean };
+type Pref = keyof TimelinePrefs;
+
+const DEFAULTS: TimelinePrefs = { snap: true, magnet: true, linkage: true, previewAxis: false };
+const KEY: Record<Pref, string> = {
+  snap: 'openfilm.timeline.snap',
+  /* new keys: the main track came back on 10-19 with its magnet and linkage, so choices made for the switches before
+     do not carry over */
+  magnet: 'openfilm.timeline.mainTrackMagnet',
+  linkage: 'openfilm.timeline.mainTrackLinkage',
+  previewAxis: 'openfilm.timeline.previewAxis',
+};
+
+/** Without localStorage (private window), the choices last this session. */
+const memory: Partial<TimelinePrefs> = {};
+const listeners = new Set<() => void>();
+let current: TimelinePrefs | null = null;
+
+function read(pref: Pref): boolean {
+  try {
+    const raw = localStorage.getItem(KEY[pref]);
+    if (raw != null) return raw !== '0';
+  } catch { /* no localStorage: this session's choice */ }
+  return memory[pref] ?? DEFAULTS[pref];
+}
+
+export function readTimelinePrefs(): TimelinePrefs {
+  current ??= { snap: read('snap'), magnet: read('magnet'), linkage: read('linkage'), previewAxis: read('previewAxis') };
+  return current;
+}
+
+/** What an edit is planned by (lib/timeline-edit Switches), from the switches. */
+export function switchesOf(prefs: Pick<TimelinePrefs, 'magnet' | 'linkage'>): Switches {
+  return { magnet: prefs.magnet, linkage: prefs.linkage };
+}
+
+export function writeTimelinePref(pref: Pref, on: boolean): void {
+  memory[pref] = on;
+  try {
+    localStorage.setItem(KEY[pref], on ? '1' : '0');
+  } catch { /* not stored: `memory` has it */ }
+  current = { ...readTimelinePrefs(), [pref]: on };
+  for (const fn of listeners) fn();
+}
+
+function subscribe(fn: () => void): () => void {
+  listeners.add(fn);
+  return () => { listeners.delete(fn); };
+}
+
+/** The switches, kept up to date wherever one is changed. */
+export function useTimelinePrefs(): TimelinePrefs {
+  return useSyncExternalStore(subscribe, readTimelinePrefs, () => DEFAULTS);
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Where a split cuts a clip, as film.html writes its halves: the left one's trim end, the right one's trim and place.
+ *
+ * film.html writes moments to the millisecond (ops.mjs rounds them), and a clip's length on the film is its trim over
+ * its speed. So the cut is taken on a whole millisecond of the source, and the right half starts where that puts the
+ * left one's end: worked out the other way round (the film moment rounded, the trim from it), a clip at speed 0.5
+ * ends a millisecond past where the rest starts, and the two overlap.
+ */
+export type SplitHalves = {
+  left: { end: number };
+  /** `end` only when the clip writes one: without, the rest plays to the end of its file */
+  right: { start: number; end?: number; at: number };
+};
+
+export function splitHalves(
+  block: { startMs: number; endMs: number; speed?: number; anchor?: { trimFrom?: number; parentStartMs: number } },
+  atMs: number,
+  /** the clip's own trim end in film.html (source seconds), when it writes one */
+  sourceEnd?: number,
+): SplitHalves | null {
+  const k = block.speed && block.speed > 0 ? block.speed : 1;
+  const startMs = Math.round(block.startMs);
+  const fromMs = Math.round((block.anchor?.trimFrom ?? 0) * 1000);
+  /* source ms after the clip's in point: to the cut, and to its end */
+  const cut = Math.round((atMs - startMs) * k);
+  const ends = sourceEnd != null && Number.isFinite(sourceEnd);
+  const total = ends ? Math.round(sourceEnd * 1000) - fromMs : Math.round((block.endMs - startMs) * k);
+  if (!(cut > 0 && cut < total)) return null;
+  const parentMs = block.anchor?.parentStartMs ?? 0;
+  const end = (fromMs + cut) / 1000;
+  /* the first half's length on the film, worked out as the timeline does from film.html (clipSpan's (to − from) /
+     speed, to the ms): the rest starts there, not at its own rounding of the cut (450.5 ms is 450 one way, 451 the other) */
+  const leftMs = Math.round(((end - fromMs / 1000) / k) * 1000);
+  return {
+    left: { end },
+    /* no end written when the clip has none: worked out from its length on the film (to the ms), it could land past
+       the file's own length (10.010667 s → 10.011) and the film would refuse to play */
+    right: { start: end, ...(ends ? { end: (fromMs + total) / 1000 } : {}), at: (startMs - parentMs + leftMs) / 1000 },
+  };
+}

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

@@ -0,0 +1,105 @@
+/**
+ * What the timeline draws of a big film, and how a zoom gesture moves it. Every clip drawn is laid out, layerized and
+ * hit-tested again on each zoom step and scroll, and on a film of hundreds of clips most of them were out of view. So
+ * only the rows near the view get their clips (rowsNear), and while a wheel or pinch zoom goes on, what is drawn is
+ * scaled by transforms the compositor applies (ZoomPreview), and laid out at the new density once it stops.
+ */
+
+/** Rows are drawn this many views above and below the view: a quick scroll does not outrun them. */
+export const ROWS_PAD_VIEWS = 0.5;
+/** The rows drawn follow the vertical scroll in steps of this many views, not every pixel (each step is a render). */
+export const ROWS_STEP_VIEWS = 0.5;
+
+function clamp(n: number, lo: number, hi: number): number {
+  return n < lo ? lo : n > hi ? hi : n;
+}
+
+/** Which step of the vertical scroll the view is at (see ROWS_STEP_VIEWS). */
+export function rowBand(scrollTop: number, viewH: number): number {
+  if (!(viewH > 0)) return 0;
+  return Math.max(0, Math.floor(scrollTop / (viewH * ROWS_STEP_VIEWS)));
+}
+
+/**
+ * The rows drawn at a step of the vertical scroll: the first and last index, inclusive (`last` < `first` when none).
+ * `heights` are the rows' own, top to bottom; each has `gap` above it, the first `padTop` below the content's top.
+ * Before the view has a height every row is drawn.
+ */
+export function rowsNear(
+  heights: readonly number[],
+  at: { gap: number; padTop: number; band: number; viewH: number },
+): { first: number; last: number } {
+  if (!(at.viewH > 0)) return { first: 0, last: heights.length - 1 };
+  const step = at.viewH * ROWS_STEP_VIEWS;
+  const pad = at.viewH * ROWS_PAD_VIEWS;
+  /* every scroll inside the step is covered, with `pad` to spare either side */
+  const from = at.band * step - pad;
+  const to = (at.band + 1) * step + at.viewH + pad;
+  let first = -1;
+  let last = -2;
+  let bottom = at.padTop;
+  for (let i = 0; i < heights.length; i += 1) {
+    const top = bottom + at.gap;
+    bottom = top + heights[i]!;
+    if (bottom <= from) continue;
+    if (top >= to) break;
+    if (first < 0) first = i;
+    last = i;
+  }
+  return first < 0 ? { first: 0, last: -1 } : { first, last };
+}
+
+/**
+ * A zoom gesture under way, against what is laid out now: what is laid out at x (px from the content's left edge) is
+ * drawn at `offset + scale × x` (px from the view's left edge). Laid out again, the density is `scale` times what it
+ * is and the scroll is `-offset`.
+ */
+export interface ZoomPreview {
+  offset: number;
+  scale: number;
+}
+
+/** No gesture: what is laid out, drawn where it is. */
+export function zoomPreviewAt(scrollLeft: number): ZoomPreview {
+  return { offset: -scrollLeft, scale: 1 };
+}
+
+/**
+ * One step of a gesture: `factor` more density around the view x `at`, which stays where it is. The density stays
+ * within `minScale`..`maxScale` and the view within the canvas (`maxScrollAt`: the furthest scroll at a scale), as a
+ * zoom laid out at each step would: near an end, the point slides instead of the view leaving the canvas.
+ */
+export function zoomPreviewStep(
+  p: ZoomPreview,
+  factor: number,
+  at: number,
+  limits: { minScale: number; maxScale: number; maxScrollAt: (scale: number) => number },
+): ZoomPreview {
+  const scale = clamp(p.scale * factor, limits.minScale, Math.max(limits.minScale, limits.maxScale));
+  const offset = at + (scale / p.scale) * (p.offset - at);
+  return { offset: clamp(offset, -Math.max(0, limits.maxScrollAt(scale)), 0), scale };
+}
+
+/** The same gesture against the density laid out next (`toPx` where it was `fromPx`). */
+export function rebaseZoomPreview(p: ZoomPreview, fromPx: number, toPx: number): ZoomPreview {
+  return toPx > 0 && fromPx > 0 ? { offset: p.offset, scale: (p.scale * fromPx) / toPx } : p;
+}
+
+/** Whether a gesture draws things where they are laid out (at this scroll): nothing to transform. */
+export function zoomPreviewIsRest(p: ZoomPreview, scrollLeft: number): boolean {
+  return Math.abs(p.scale - 1) < 1e-6 && Math.abs(p.offset + scrollLeft) < 0.01;
+}
+
+/**
+ * The transform that draws a layer as the gesture has it. `content`: laid out in content px, moved by the scroll
+ * (the clips, the ruler, the subtitle and marker rows). `view`: drawn in view px with the scroll taken off already
+ * (the playhead, the range), its left edge `bleed` px left of the view's. Empty at rest.
+ */
+export function zoomLayerTransform(p: ZoomPreview, scrollLeft: number, kind: 'content' | 'view', bleed = 0): string {
+  if (zoomPreviewIsRest(p, scrollLeft)) return '';
+  const x = kind === 'content' ? p.offset + scrollLeft : p.offset + p.scale * (scrollLeft - bleed) + bleed;
+  return `translate3d(${round3(x)}px,0,0) scaleX(${round6(p.scale)})`;
+}
+
+const round3 = (n: number) => Math.round(n * 1000) / 1000;
+const round6 = (n: number) => Math.round(n * 1e6) / 1e6;

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

@@ -0,0 +1,39 @@
+/**
+ * How long a project name may be. It must fit one line on cards and in the top bar, and characters alone do not
+ * measure that: a CJK glyph is about twice as wide as a Latin one. So the budget is display width — full-width
+ * glyphs cost 2, everything else 1 — which gives "30 CJK or 60 Latin characters" from one rule.
+ */
+export const TITLE_MAX_WIDTH = 60;
+
+const FULL_WIDTH_RANGES: readonly [number, number][] = [
+  [0x1100, 0x115f], // Hangul Jamo
+  [0x2e80, 0x303e], // CJK radicals, Kangxi, CJK symbols & punctuation
+  [0x3041, 0x33ff], // Hiragana, Katakana, Hangul compat, CJK compat
+  [0x3400, 0x4dbf], // CJK ext A
+  [0x4e00, 0x9fff], // CJK unified
+  [0xa000, 0xa4cf], // Yi
+  [0xac00, 0xd7a3], // Hangul syllables
+  [0xf900, 0xfaff], // CJK compat ideographs
+  [0xfe30, 0xfe6f], // CJK compat forms
+  [0xff00, 0xff60], // Full-width forms
+  [0xffe0, 0xffe6],
+  [0x20000, 0x2fffd], // CJK ext B+
+  [0x30000, 0x3fffd],
+];
+
+function charWidth(codePoint: number): number {
+  return FULL_WIDTH_RANGES.some(([lo, hi]) => codePoint >= lo && codePoint <= hi) ? 2 : 1;
+}
+
+/** Cut to the width budget, without an ellipsis (for typing: no "…" after every keystroke). */
+export function limitTitleWidth(raw: string, maxWidth = TITLE_MAX_WIDTH): string {
+  let width = 0;
+  let out = '';
+  for (const ch of raw) {
+    const w = charWidth(ch.codePointAt(0)!);
+    if (width + w > maxWidth) break;
+    width += w;
+    out += ch;
+  }
+  return out;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/track-heights.ts

@@ -0,0 +1,55 @@
+/**
+ * Track heights: how tall each track is drawn on the timeline, set by dragging the bottom edge of its head or picked
+ * small / medium / large from its menu. Studio's own, per project (`.film/settings.json` `trackHeights`), each with
+ * the clips its track had then, so it stays with its track when tracks move (see lib/timeline-nav placeSaved).
+ */
+import { placeSaved, type ClipsOf } from './timeline-nav.ts';
+import type { TimelineLaneKind } from './timeline-layout';
+
+export type SavedTrackHeight = { height: number; index: number; clips: string[] };
+
+/** The heights a track can have, px. */
+export const TRACK_MIN_H = 28;
+export const TRACK_MAX_H = 160;
+
+/** Small, medium (the timeline's own) and large, for a picture track and a sound track. */
+export const TRACK_SIZES = {
+  small: { visual: 36, audio: 30 },
+  medium: { visual: 56, audio: 44 },
+  large: { visual: 96, audio: 80 },
+} as const;
+export type TrackSize = keyof typeof TRACK_SIZES;
+
+/** The main track's own height: taller than the others. */
+export const MAIN_TRACK_H = 68;
+
+/** A track's own height (none set by the person): the main track's, else medium for its kind. */
+export function ownTrackHeight(track: { kind: TimelineLaneKind; main?: boolean }): number {
+  return track.main ? MAIN_TRACK_H : TRACK_SIZES.medium[track.kind];
+}
+
+export function clampTrackHeight(h: number): number {
+  return Math.round(Math.max(TRACK_MIN_H, Math.min(TRACK_MAX_H, h)));
+}
+
+/** The size a height is, when it is one of them. */
+export function sizeOf(height: number, kind: TimelineLaneKind): TrackSize | null {
+  return (Object.keys(TRACK_SIZES) as TrackSize[]).find((s) => TRACK_SIZES[s][kind] === height) ?? null;
+}
+
+/** The heights kept, by film.html track index now. */
+export function trackHeightsOf(saved: readonly SavedTrackHeight[], tracks: ClipsOf): Map<number, number> {
+  return new Map([...placeSaved(saved, tracks)].map(([entry, i]) => [i, clampTrackHeight(entry.height)]));
+}
+
+/**
+ * The heights to keep once tracks `indexes` are `height` tall (null: back to the timeline's own). The others are kept
+ * with the clips their tracks have now; heights found on no track go.
+ */
+export function withTrackHeight(saved: readonly SavedTrackHeight[], tracks: ClipsOf, indexes: readonly number[], height: number | null): SavedTrackHeight[] {
+  const placed = placeSaved(saved, tracks);
+  const kept = saved.filter((entry) => placed.has(entry) && !indexes.includes(placed.get(entry)!))
+    .map((entry) => ({ height: entry.height, index: placed.get(entry)!, clips: (tracks[placed.get(entry)!]?.clips ?? []).map((c) => c.id) }));
+  if (height == null) return kept;
+  return [...kept, ...indexes.map((index) => ({ height: clampTrackHeight(height), index, clips: (tracks[index]?.clips ?? []).map((c) => c.id) }))];
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/track-lock.ts

@@ -0,0 +1,27 @@
+/**
+ * A locked track is the person's (SPEC §1): nothing on it changes until it is unlocked. The timeline's own edits keep
+ * to that (lib/timeline-edit); these are for every other way a clip is changed — its box and its layers moved on the
+ * picture, the arrow keys, the inspector's fields, words typed in place — so the rule holds whichever way an edit comes.
+ */
+import { parseFilmDocLoc } from './film.ts';
+
+/** What a lock does not stop: switching the track itself (locking, hiding, muting, moving it up or down). */
+const TRACK_PROPS: ReadonlySet<string> = new Set(['locked', 'hidden', 'muted', 'trackOrder']);
+
+type LockedTracks = { tracks: readonly { locked?: boolean }[] } | null | undefined;
+
+/** Whether the clip at a film.html place (`film.html#2.0`) is on a locked track. */
+export function trackLockedAt(doc: LockedTracks, loc: string | null | undefined): boolean {
+  const at = loc ? parseFilmDocLoc(loc) : null;
+  return Boolean(at && doc?.tracks[at.track]?.locked);
+}
+
+/** The edits a lock refuses: any change to a clip on a locked track, but not a switch of the track itself. */
+export function lockedEdits<E extends { loc: string; prop: string }>(edits: readonly E[], doc: LockedTracks): E[] {
+  return edits.filter((e) => !TRACK_PROPS.has(e.prop) && trackLockedAt(doc, e.loc));
+}
+
+/** Whether any of these clips (by their film.html place) is on a locked track. */
+export function anyLocked(doc: LockedTracks, locs: readonly (string | null | undefined)[]): boolean {
+  return locs.some((loc) => trackLockedAt(doc, loc));
+}