auricui-skill 0.0.0-stage → 0.1.2

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/layers-tree.ts

@@ -0,0 +1,133 @@
+/**
+ * The Layers panel's tree (components/LayersPanel): the picture clips shown at the playhead, the top one first, and a
+ * page's layers inside it, each level in the order it is drawn (the one on top first), as the stage reads them
+ * (studio/server/stage.js `tree`). Reordering a level writes z-index overrides (stage.js `restack`).
+ */
+
+export type LayerRowKind = 'text' | 'image' | 'shape' | 'box' | 'group';
+
+export interface LayerRow {
+  /** The element's handle in the page (good while the page is loaded). */
+  handle: number;
+  /** The handle of the element the row is restacked by: the child of its parent row's element that holds it. */
+  branch: number;
+  /** Its selector, with `#n` when the selector finds several (the override target). */
+  loc: string;
+  instance?: number;
+  tag: string;
+  kind: LayerRowKind;
+  label: string;
+  /** Hidden by the person (an override's visibility: hidden). */
+  hidden: boolean;
+  locked: boolean;
+  /** Not drawn at this moment (faded out, hidden by the page, no size). */
+  off: boolean;
+  children: LayerRow[];
+}
+
+export interface LayerClip {
+  clip: string;
+  kind: 'page' | 'video' | 'image' | string;
+  layers: LayerRow[];
+}
+
+/** One line of the panel as drawn: a clip, or a layer `depth` levels in, with the rows it sits among. */
+export interface LayerLine {
+  key: string;
+  clipId: string;
+  depth: number;
+  row: LayerRow | null;
+  /** The level it is in (its parent's children), and its place there; none for a clip. */
+  siblings: readonly LayerRow[];
+  index: number;
+  /** The key of the line its level is under. */
+  parentKey: string;
+  open: boolean;
+  canOpen: boolean;
+}
+
+export const clipKey = (clipId: string) => `clip:${clipId}`;
+export const layerKey = (clipId: string, loc: string) => `layer:${clipId}:${loc}`;
+
+/**
+ * Whether a line starts open: a clip does, and a row alone in its level (a page's one wrapper is no stop on the way
+ * in); the person's `toggled` lines are the other way round.
+ */
+const startsOpen = (siblings: number | null) => siblings == null || siblings === 1;
+
+/** The lines shown: each clip, then the layers of the open ones and of their open rows. */
+export function layerLines(clips: readonly LayerClip[], toggled: ReadonlySet<string>): LayerLine[] {
+  const out: LayerLine[] = [];
+  const walk = (clipId: string, rows: readonly LayerRow[], depth: number, parentKey: string) => {
+    rows.forEach((row, index) => {
+      const key = layerKey(clipId, row.loc);
+      const canOpen = row.children.length > 0;
+      const isOpen = canOpen && startsOpen(rows.length) !== toggled.has(key);
+      out.push({ key, clipId, depth, row, siblings: rows, index, parentKey, open: isOpen, canOpen });
+      if (isOpen) walk(clipId, row.children, depth + 1, key);
+    });
+  };
+  for (const c of clips) {
+    const key = clipKey(c.clip);
+    const canOpen = c.layers.length > 0;
+    const isOpen = canOpen && startsOpen(null) !== toggled.has(key);
+    out.push({ key, clipId: c.clip, depth: 0, row: null, siblings: [], index: 0, parentKey: '', open: isOpen, canOpen });
+    if (isOpen) walk(c.clip, c.layers, 1, key);
+  }
+  return out;
+}
+
+/** The person's toggled lines with the clip and the rows around the layer at `loc` open (the same set when they are). */
+export function openTo(clips: readonly LayerClip[], toggled: ReadonlySet<string>, clipId: string, loc: string): ReadonlySet<string> {
+  const c = clips.find((x) => x.clip === clipId);
+  if (!c) return toggled;
+  const around: Array<{ key: string; siblings: number | null }> = [];
+  const find = (rows: readonly LayerRow[]): boolean => rows.some((row) => {
+    if (row.loc === loc) return true;
+    around.push({ key: layerKey(clipId, row.loc), siblings: rows.length });
+    if (find(row.children)) return true;
+    around.pop();
+    return false;
+  });
+  if (!find(c.layers)) return toggled;
+  const shut = [{ key: clipKey(clipId), siblings: null }, ...around].filter((l) => startsOpen(l.siblings) === toggled.has(l.key));
+  if (!shut.length) return toggled;
+  const next = new Set(toggled);
+  for (const l of shut) { if (next.has(l.key)) next.delete(l.key); else next.add(l.key); }
+  return next;
+}
+
+/**
+ * The line that moves when a dragged row is let go over line `over`: CSS restacks only within a level, so a row can be
+ * dropped in its own level or in the level of any row around it, and there the row around it moves, with all it holds.
+ * Null when `over` is in none of those levels (another clip, a group it is not in).
+ */
+export function moverFor(lines: readonly LayerLine[], dragged: LayerLine, over: LayerLine): LayerLine | null {
+  const byKey = new Map(lines.map((l) => [l.key, l]));
+  /* per level (the key of the line it is under), the row of the dragged one's chain in it */
+  const chain = new Map<string, LayerLine>();
+  for (let c: LayerLine | undefined = dragged; c?.row; c = byKey.get(c.parentKey)) chain.set(c.parentKey, c);
+  for (let c: LayerLine | undefined = over; c?.row; c = byKey.get(c.parentKey)) {
+    const mover = chain.get(c.parentKey);
+    if (mover) return mover;
+  }
+  return null;
+}
+
+/**
+ * A level reordered: the row at `from` dropped at `to` (a gap, 0 above the first row … length below the last), as the
+ * handles to restack by, the top one first. Null when it lands where it was.
+ */
+export function movedOrder(siblings: readonly LayerRow[], from: number, to: number): number[] | null {
+  if (from < 0 || from >= siblings.length) return null;
+  const at = to > from ? to - 1 : to;
+  if (at === from) return null;
+  const rest = siblings.filter((_, i) => i !== from);
+  rest.splice(Math.max(0, Math.min(rest.length, at)), 0, siblings[from]!);
+  return rest.map((r) => r.branch);
+}
+
+/** Two reads of the tree are the same picture of it (the panel redraws only when they differ). */
+export function sameTree(a: readonly LayerClip[] | null, b: readonly LayerClip[] | null): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}

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

@@ -0,0 +1,83 @@
+/**
+ * The inspector's look controls over one or several things (layers inside a page, or clips): what each reads of their
+ * CSS, and how an edit is shown (previewed) and written (committed) for each of them.
+ */
+import { MIXED, type Mixed } from './mixed.ts';
+
+/** One thing's CSS property (kebab-case), as it is now. */
+export type LookRead = (prop: string) => string | undefined;
+/** Properties to write: a value, or null — "none of mine" (the panel decides what that leaves). */
+export type LookSet = Record<string, string | null>;
+/** What a control does to one thing, from that thing's own values. */
+export type LookEdit = (read: LookRead) => LookSet;
+
+export interface Look {
+  /** How many things it is. */
+  n: number;
+  /** What `fn` makes of every thing's values, when they agree; MIXED when they do not. */
+  common<V>(fn: (read: LookRead) => V): V | Mixed;
+  /** Shows an edit on the picture, nothing written. */
+  preview(edit: LookEdit): void;
+  /** Writes an edit, as one change. */
+  commit(edit: LookEdit): void;
+  /** Takes a preview back off the picture. */
+  revert(): void;
+}
+
+/**
+ * A Look over `targets`: read each through `readOf`, and hand each one's properties to `write` (the panel stores
+ * them). `write` gets only the things an edit changes.
+ */
+export function makeLook<Tg>(
+  targets: readonly Tg[],
+  readOf: (t: Tg) => LookRead,
+  write: {
+    commit: (sets: [Tg, LookSet][]) => void;
+    preview?: (sets: [Tg, LookSet][]) => void;
+    revert?: () => void;
+  },
+): Look {
+  const reads = targets.map(readOf);
+  const sets = (edit: LookEdit, kept?: ReadonlyMap<string, string | undefined>[] | null): [Tg, LookSet][] => targets.flatMap((tg, i) => {
+    const read = reads[i]!;
+    /* what was there before a preview: the layer is measured again while previewed, so by now it reads as the
+       preview. The edit is worked out from it (a preview may have changed what the edit decides by, as text color
+       taking over the words' own fill), and unchanged properties are not written: the agent reads the diff, a no-op
+       would be an undo step, and a kept preview would read as no change */
+    const was = (k: string) => (kept?.[i]?.has(k) ? kept[i]!.get(k) : read(k));
+    const set = edit(was);
+    const changed = Object.entries(set).filter(([k, v]) => (v ?? undefined) !== was(k));
+    return changed.length ? [[tg, Object.fromEntries(changed)] as [Tg, LookSet]] : [];
+  });
+  return {
+    n: targets.length,
+    common(fn) {
+      if (!reads.length) return MIXED;
+      const first = fn(reads[0]!);
+      const key = JSON.stringify(first);
+      return reads.every((r) => JSON.stringify(fn(r)) === key) ? first : MIXED;
+    },
+    /* shown as said, unchanged or not: a layer reads as its kept change while a preview paints over it, so painting
+       back what was there would read as no change */
+    preview(edit) {
+      if (!previewedBefore || previewedBefore.length !== targets.length) previewedBefore = targets.map(() => new Map());
+      const list = targets.flatMap((tg, i) => {
+        const set = edit(reads[i]!);
+        for (const k of Object.keys(set)) if (!previewedBefore![i]!.has(k)) previewedBefore![i]!.set(k, reads[i]!(k));
+        return Object.keys(set).length ? [[tg, set] as [Tg, LookSet]] : [];
+      });
+      write.preview?.(list);
+    },
+    commit(edit) {
+      const list = sets(edit, previewedBefore);
+      previewedBefore = null;
+      if (list.length) write.commit(list);
+    },
+    revert() { previewedBefore = null; write.revert?.(); },
+  };
+}
+
+/** What each previewed property of the things in hand was before its first preview (see makeLook's `sets`). */
+let previewedBefore: Map<string, string | undefined>[] | null = null;
+/** A preview was painted back by hand (as a preview of what was there): nothing previewed stands any more. */
+export const previewSettled = () => { previewedBefore = null; };

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

@@ -0,0 +1,58 @@
+/**
+ * Loudness normalization: a clip's `volume` set so the part of its file it plays measures a target loudness. Studio
+ * measures the integrated loudness of that part (EBU R128, LUFS; studio/server/derived.mjs `loudness`); the gain is
+ * the difference, within the volume a clip can have (0–500%, the inspector's range).
+ */
+
+/** The targets offered: web video, podcasts, broadcast (EBU R128). */
+export const LOUDNESS_TARGETS = [
+  { id: 'web', lufs: -14 },
+  { id: 'podcast', lufs: -16 },
+  { id: 'broadcast', lufs: -23 },
+] as const;
+
+/** The loudest a clip's volume goes (500%), as the inspector's slider. */
+export const VOLUME_MAX = 5;
+
+/** The volume slider's range in dB: its bottom is silence, its top the loudest a clip goes (500%, +14 dB). */
+export const VOLUME_DB_MIN = -60;
+export const VOLUME_DB_MAX = Math.round(20 * Math.log10(VOLUME_MAX) * 10) / 10;
+
+/** A clip's volume as the slider shows it: dB to the tenth, silence at the bottom. */
+export function volumeToDb(volume: number): number {
+  if (!(volume > 0)) return VOLUME_DB_MIN;
+  const db = Math.round(20 * Math.log10(volume) * 10) / 10;
+  return Math.max(VOLUME_DB_MIN, Math.min(VOLUME_DB_MAX, db));
+}
+
+/** The volume a dB on the slider writes, to the thousandth: silent at its bottom, at most 500%. */
+export function dbToVolume(db: number): number {
+  if (!(db > VOLUME_DB_MIN)) return 0;
+  return Math.round(Math.min(VOLUME_MAX, 10 ** (db / 20)) * 1000) / 1000;
+}
+
+/** Quieter than this is silence: EBU R128 gates out anything under −70 LUFS. */
+const SILENT_LUFS = -70;
+
+export type NormalizePlan =
+  | { volume: number; reached: true }
+  /** the volume it would need, past what a clip can have: it is set to the most it can, and that is said */
+  | { volume: number; reached: false; wantedVolume: number; lufs: number }
+  | { silent: true };
+
+/** The volume that brings `measured` LUFS to `target` LUFS, kept to 0–500%, to the thousandth. */
+export function normalizeVolume(measured: number | null, target: number): NormalizePlan {
+  if (measured == null || !Number.isFinite(measured) || measured <= SILENT_LUFS) return { silent: true };
+  const wanted = 10 ** ((target - measured) / 20);
+  const volume = Math.round(Math.min(VOLUME_MAX, wanted) * 1000) / 1000;
+  if (wanted <= VOLUME_MAX + 0.0005) return { volume, reached: true };
+  /* the loudness it gets at the most it can have */
+  const lufs = Math.round((measured + 20 * Math.log10(VOLUME_MAX)) * 10) / 10;
+  return { volume, reached: false, wantedVolume: Math.round(wanted * 1000) / 1000, lufs };
+}
+
+/** The part of a clip's file it plays, in the file's seconds: what is measured. */
+export function measuredSpan(clip: { inMs?: number; speed?: number; startMs: number; endMs: number }): { from: number; to: number } {
+  const from = (clip.inMs ?? 0) / 1000;
+  return { from, to: from + ((clip.endMs - clip.startMs) * (clip.speed ?? 1)) / 1000 };
+}

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

@@ -0,0 +1,152 @@
+/**
+ * Markers: named, colored places on the film (M on the ruler), or on a clip (M with a clip selected under the
+ * playhead), which then moves with the clip. Studio's own, kept in `.film/markers.json` (studio/server/markers.mjs),
+ * never in film.html: a marker changes nothing in the film.
+ *
+ * A film marker is a film second. A clip marker is a second of its clip's file, so it stays on the same moment of the
+ * footage when the clip is moved or trimmed; it is shown only while that moment is in the clip.
+ */
+import { snapToFrame } from './timecode.ts';
+import type { TimelineBlock, TimelineTrack } from './timeline-layout';
+
+export const MARKER_COLORS = ['blue', 'green', 'yellow', 'orange', 'red', 'purple'] as const;
+export type MarkerColor = (typeof MARKER_COLORS)[number];
+
+/** The colors as the timeline paints them. */
+export const MARKER_PAINT: Record<MarkerColor, string> = {
+  blue: '#4c8dff',
+  green: '#3fbf6f',
+  yellow: '#e8c547',
+  orange: '#f08a3c',
+  red: '#e5484d',
+  purple: '#a57cf0',
+};
+
+export interface Marker {
+  id: string;
+  /** Film seconds; on a clip, seconds of the clip's file. */
+  t: number;
+  /** The clip it is on (film.html id); absent for a marker on the film. */
+  clip?: string;
+  name?: string;
+  color: MarkerColor;
+}
+
+/** The most a project keeps, and the longest name. */
+export const MARKERS_MAX = 1000;
+export const MARKER_NAME_MAX = 80;
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/** Markers as kept: what is not one is left out (the server keeps the same rule, see markers.mjs). */
+export function parseMarkers(raw: unknown): Marker[] {
+  if (!Array.isArray(raw)) return [];
+  const out: Marker[] = [];
+  const ids = new Set<string>();
+  for (const m of raw) {
+    if (!isRecord(m) || typeof m.id !== 'string' || !m.id || ids.has(m.id)) continue;
+    if (typeof m.t !== 'number' || !Number.isFinite(m.t) || m.t < 0) continue;
+    ids.add(m.id);
+    const name = typeof m.name === 'string' ? m.name.trim().slice(0, MARKER_NAME_MAX) : '';
+    out.push({
+      id: m.id,
+      t: Math.round(m.t * 1000) / 1000,
+      ...(typeof m.clip === 'string' && m.clip ? { clip: m.clip } : {}),
+      ...(name ? { name } : {}),
+      color: (MARKER_COLORS as readonly string[]).includes(String(m.color)) ? (m.color as MarkerColor) : 'blue',
+    });
+    if (out.length >= MARKERS_MAX) break;
+  }
+  return out;
+}
+
+/** An id no marker has. */
+export function markerId(list: readonly Marker[]): string {
+  const taken = new Set(list.map((m) => m.id));
+  let n = list.length + 1;
+  while (taken.has(`m${n}`)) n++;
+  return `m${n}`;
+}
+
+/** A clip as a marker on it needs it: where it is on the film and which part of its file it plays. */
+type ClipPlace = Pick<TimelineBlock, 'clipId' | 'startMs' | 'endMs' | 'inMs' | 'speed'>;
+
+/** Where a clip marker is on the film (ms), or null while that moment of the file is not in the clip. */
+export function clipMarkerMs(m: Marker, clip: ClipPlace): number | null {
+  const ms = clip.startMs + (m.t * 1000 - (clip.inMs ?? 0)) / (clip.speed ?? 1);
+  return ms >= clip.startMs - 0.5 && ms <= clip.endMs + 0.5 ? ms : null;
+}
+
+/** A marker on the film as it is drawn: where (ms), and the clip it is on. */
+export type PlacedMarker = { marker: Marker; ms: number; clip?: TimelineBlock };
+
+/** Every marker that shows, with its film time, in time order. A clip marker shows while its clip and moment do. */
+export function placeMarkers(list: readonly Marker[], tracks: readonly TimelineTrack[]): PlacedMarker[] {
+  const clips = new Map<string, TimelineBlock>();
+  for (const tr of tracks) for (const b of tr.blocks) if (b.clipId && b.loc) clips.set(b.clipId, b);
+  const out: PlacedMarker[] = [];
+  for (const marker of list) {
+    if (!marker.clip) { out.push({ marker, ms: marker.t * 1000 }); continue; }
+    const clip = clips.get(marker.clip);
+    const ms = clip ? clipMarkerMs(marker, clip) : null;
+    if (clip && ms != null) out.push({ marker, ms, clip });
+  }
+  return out.sort((a, b) => a.ms - b.ms);
+}
+
+/**
+ * The markers once one is added at `atMs` (on a frame): on `clip` when given, else on the film. A marker already on
+ * that frame is not added twice; `added` is the one there.
+ */
+export function addMarker(list: readonly Marker[], atMs: number, clip?: ClipPlace | null, color: MarkerColor = 'blue'): { list: Marker[]; added: Marker } {
+  const ms = snapToFrame(Math.max(0, atMs));
+  const t = clip?.clipId
+    ? Math.round(((clip.inMs ?? 0) + (ms - clip.startMs) * (clip.speed ?? 1))) / 1000
+    : Math.round(ms) / 1000;
+  const same = list.find((m) => (m.clip ?? null) === (clip?.clipId ?? null) && Math.abs(m.t - t) < 0.0005);
+  if (same) return { list: [...list], added: same };
+  const added: Marker = { id: markerId(list), t: Math.max(0, t), ...(clip?.clipId ? { clip: clip.clipId } : {}), color };
+  return { list: [...list, added], added };
+}
+
+/** One marker changed: its name (empty takes it away), color, or film time. */
+export function changeMarker(list: readonly Marker[], id: string, change: { name?: string; color?: MarkerColor; t?: number }): Marker[] {
+  return list.map((m) => {
+    if (m.id !== id) return m;
+    const next: Marker = { ...m };
+    if (change.name !== undefined) {
+      const name = change.name.trim().slice(0, MARKER_NAME_MAX);
+      if (name) next.name = name;
+      else delete next.name;
+    }
+    if (change.color) next.color = change.color;
+    if (change.t !== undefined && Number.isFinite(change.t)) next.t = Math.max(0, Math.round(change.t * 1000) / 1000);
+    return next;
+  });
+}
+
+export function removeMarker(list: readonly Marker[], id: string): Marker[] {
+  return list.filter((m) => m.id !== id);
+}
+
+/** The next marker after `nowMs` (`dir` 1), or the one before (-1); null when there is none that way. */
+export function nextMarker(placed: readonly PlacedMarker[], nowMs: number, dir: 1 | -1): PlacedMarker | null {
+  /* within a millisecond is where the playhead already is */
+  if (dir > 0) return placed.find((p) => p.ms > nowMs + 1) ?? null;
+  for (let i = placed.length - 1; i >= 0; i--) if (placed[i]!.ms < nowMs - 1) return placed[i]!;
+  return null;
+}
+
+/**
+ * What M marks: the selected clip under the playhead (the first), else nothing (a marker on the film). A locked
+ * track's clips take markers too: a marker changes nothing in the film.
+ */
+export function markerClip(tracks: readonly TimelineTrack[], selectedClipIds: readonly string[], atMs: number): TimelineBlock | null {
+  if (!selectedClipIds.length) return null;
+  for (const tr of tracks) {
+    for (const b of tr.blocks) {
+      if (b.clipId && b.loc && selectedClipIds.includes(b.clipId) && atMs >= b.startMs && atMs < b.endMs) return b;
+    }
+  }
+  return null;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/media-bar.ts

@@ -0,0 +1,58 @@
+/**
+ * The media pane's top bar at the pane's width, worked out from what its words measure in the person's language and
+ * font. The search field takes whatever room is left, so nothing is left empty. As the pane narrows, Upload loses its
+ * word first, then the field gets shorter (its hint cut, or gone, down to its icon), and only when even that does not
+ * fit does the search become a button. A field too short to type in opens over the bar when clicked. The square
+ * buttons (view, filter, sort, new folder, close) always stay.
+ */
+
+/** What the words measure, in px, at the bar's type. */
+export interface BarWords {
+  /** The search's hint ("Search"). */
+  hint: number;
+  /** Upload's word. */
+  upload: number;
+}
+
+export interface BarLayout {
+  /** The search as a field (else a button). */
+  field: boolean;
+  /** Upload with its word (else its icon). */
+  uploadWord: boolean;
+  /** Tighter padding and gaps: the narrowest form. */
+  tight: boolean;
+  /** The field is too short to type in: clicked, it opens over the bar. */
+  cramped: boolean;
+}
+
+/** A square button. */
+export const BAR_BUTTON = 28;
+/* the search field around its hint: padding 8 + icon 13 + gap 6 + padding 8, and room for the caret */
+const FIELD_CHROME = 39;
+/** The shortest field: its icon. */
+export const MIN_FIELD = 44;
+/** The shortest field to type in where it is: its icon and a few letters. */
+export const TYPING_FIELD = 72;
+/* the clear button, while something is typed */
+const CLEAR = 18;
+/* Upload around its word: padding 10 + icon 13 + gap 6 + padding 10 */
+const UPLOAD_CHROME = 39;
+
+/** The bar for `width` px, with `buttons` square buttons after Upload; `typed`: the search has text. */
+export function barLayout(width: number, words: BarWords, buttons: number, typed: boolean): BarLayout {
+  const clear = typed ? CLEAR : 0;
+  /* Upload keeps its word while the field still shows its whole hint beside it */
+  if (rest(width, false, UPLOAD_CHROME + words.upload, buttons) >= FIELD_CHROME + words.hint + clear) {
+    return { field: true, uploadWord: true, tight: false, cramped: false };
+  }
+  const room = rest(width, false, BAR_BUTTON, buttons);
+  if (room >= MIN_FIELD) return { field: true, uploadWord: false, tight: false, cramped: room < TYPING_FIELD + clear };
+  return { field: false, uploadWord: false, tight: true, cramped: true };
+}
+
+/** The room the search field gets: the width less padding, Upload, the square buttons and the gaps between. */
+export function rest(width: number, tight: boolean, upload: number, buttons: number): number {
+  const pad = tight ? 16 : 20;
+  const gap = tight ? 2 : 4;
+  return width - pad - upload - buttons * BAR_BUTTON - (buttons + 1) * gap;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/media-folders.ts

@@ -0,0 +1,45 @@
+/**
+ * The media pane's folders (MediaPool): those directly in the folder shown, each with how many files it holds (at any
+ * depth) and the four on its cover (pictures first, they say the most; sounds after; by name). Worked out in one pass
+ * over the files, with one collator: a project holds thousands of files, the pane is laid out again whenever its
+ * listing changes, and a filter and a sort per folder (a collator made for each comparison) took tens of ms each time.
+ */
+
+/** Names in their natural order (shot 2 before shot 10). */
+export const byName = new Intl.Collator(undefined, { numeric: true }).compare;
+
+type File = { path: string; name: string; kind: string };
+export type FolderFace<F extends File> = { rel: string; name: string; count: number; covers: F[] };
+
+/** Pictures before sounds, then by name: the order of a folder's cover. */
+const coverOrder = (a: File, b: File) => Number(a.kind === 'audio') - Number(b.kind === 'audio') || byName(a.name, b.name);
+const COVERS = 4;
+
+/**
+ * The folders of `dirs` (paths under the media folder) directly in `at` ('' its top), in name order. `relOf` gives a
+ * file's path under the media folder, or null for one outside it (a project's own page).
+ */
+export function folderFaces<F extends File>(files: readonly F[], dirs: readonly string[], at: string, relOf: (path: string) => string | null): FolderFace<F>[] {
+  const parentOf = (rel: string) => (rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : '');
+  const faces = new Map<string, FolderFace<F>>();
+  for (const rel of [...dirs].filter((d) => parentOf(d) === at).sort(byName)) faces.set(rel, { rel, name: rel.split('/').pop()!, count: 0, covers: [] });
+  if (!faces.size) return [];
+  const prefix = at ? `${at}/` : '';
+  for (const f of files) {
+    const rel = relOf(f.path);
+    if (rel == null || !rel.startsWith(prefix)) continue;
+    const slash = rel.indexOf('/', prefix.length);
+    if (slash < 0) continue;                                         // a file of `at` itself
+    const face = faces.get(rel.slice(0, slash));
+    if (!face) continue;
+    face.count++;
+    /* the cover's four, kept in order as they come (no sort of the whole folder) */
+    const covers = face.covers;
+    if (covers.length === COVERS && coverOrder(f, covers[COVERS - 1]!) >= 0) continue;
+    let i = covers.length;
+    while (i > 0 && coverOrder(f, covers[i - 1]!) < 0) i--;
+    covers.splice(i, 0, f);
+    if (covers.length > COVERS) covers.pop();
+  }
+  return [...faces.values()];
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/media-place.ts

@@ -0,0 +1,102 @@
+/**
+ * A file from the media pane put on the timeline without dragging it: its "+" button and Enter, and `,` / `.` from the
+ * source viewer (insert / overwrite). The part of the file marked in the source viewer (I and O
+ * there), else all of it, as one clip — a video carries its own sound.
+ *
+ * Where it goes: at the playhead on the targeted track (the track last clicked on the timeline), or without one at
+ * the end of the main track (V1) for a picture, of a sound track for a sound (the first with room, else a new one
+ * under the others). How, without `,` / `.`: on the main track with the magnet it goes in between at the playhead (as a
+ * clip dragged there does); anywhere else it is put down, never cutting what is there — a taken spot opens a track
+ * beside it.
+ */
+import type { Op } from '../api.ts';
+import { assetClipElement, assetClipKindOf, dropDurMsOf, type StageSize } from './asset-timeline.ts';
+import type { ResourceDragItem } from './resource-drag';
+import { newTrackSide } from './timeline-drag.ts';
+import { insertPointOn, magnetOn, planRoom, soundTrackFor, TOUCH_MS, type EditMode, type EditModel, type Switches, type TrackDest } from './timeline-edit.ts';
+import { snapToFrame } from './timecode.ts';
+
+export type PlaceFile = Pick<ResourceDragItem, 'path' | 'kind' | 'durationMs' | 'endless' | 'reflows' | 'w' | 'h'>;
+
+/** A part of the file, in its own ms (the source viewer's in and out). */
+export type SourceRange = { inMs: number; outMs: number };
+
+export interface PlaceSpec extends Partial<Switches> {
+  file: PlaceFile;
+  range?: SourceRange | null;
+  /** The targeted track (film.html index), or null for the lowest picture track. */
+  target: number | null;
+  /** Where: the playhead (ms), or `end`, after the last clip of the track it goes on. */
+  at: number | 'end';
+  /** Insert or overwrite, asked for (the source viewer's keys); not given, as the timeline's switches say. */
+  mode?: EditMode;
+  /** The canvas: a picture of another shape gets a box in its own (asset-timeline assetFitBox). */
+  stage?: StageSize | null;
+}
+
+export type PlacePlan = { ops: Op[]; track: TrackDest; startMs: number; durMs: number } | { error: 'not-clip' | 'locked' };
+
+const isSoundTrack = (role: string | undefined) => role === 'audio';
+
+/** The clip as film.html takes it: the file, trimmed to the part marked (a still keeps its length). */
+function elementOf(file: PlaceFile, range: SourceRange | null | undefined, stage: StageSize | null | undefined): { element: Record<string, unknown>; durMs: number } | null {
+  const element = assetClipElement(file, stage);
+  if (!element) return null;
+  const still = Array.isArray(element.time);
+  if (range && range.outMs > range.inMs && !(still && assetClipKindOf(file) === 'video')) {
+    return { element: { ...element, time: [Math.round(range.inMs) / 1000, Math.round(range.outMs) / 1000] }, durMs: Math.round(range.outMs) - Math.round(range.inMs) };
+  }
+  return { element, durMs: dropDurMsOf(file) };
+}
+
+export function placeMedia(model: EditModel, spec: PlaceSpec): PlacePlan {
+  const kind = assetClipKindOf(spec.file);
+  const made = kind ? elementOf(spec.file, spec.range, spec.stage) : null;
+  if (!kind || !made) return { error: 'not-clip' };
+  const sound = kind === 'audio';
+  const fits = (role: string | undefined) => (sound ? isSoundTrack(role) : !isSoundTrack(role));
+  const targeted = spec.target != null ? model.find((t) => t.index === spec.target) : undefined;
+  /* a targeted track of the other family (a sound aimed at a picture track) is passed over for the usual one */
+  if (targeted && fits(targeted.role) && targeted.locked) return { error: 'locked' };
+  const endOf = (index: number) => Math.max(0, ...(model.find((t) => t.index === index)?.clips ?? []).map((c) => c.endMs));
+  let track: TrackDest;
+  /* a sound track picked for having room: nothing there to push on or cut */
+  let roomy = false;
+  if (targeted && fits(targeted.role)) {
+    track = targeted.index;
+  } else if (sound) {
+    const sounds = model.filter((t) => isSoundTrack(t.role) && !t.locked);
+    if (spec.at === 'end' && sounds.length) {
+      /* at the end of a sound track: the first with any sound, or the first */
+      track = (sounds.find((t) => t.clips.length) ?? sounds[0]!).index;
+    } else {
+      const from = spec.at === 'end' ? 0 : snapToFrame(spec.at);
+      track = soundTrackFor(model, { startMs: from, endMs: from + made.durMs }, -1);
+      roomy = true;
+    }
+  } else {
+    /* the main track: the lowest picture track (V1), film.html's last picture track */
+    const pictures = model.filter((t) => !isSoundTrack(t.role));
+    const lowest = pictures.at(-1);
+    if (lowest?.locked) return { error: 'locked' };
+    track = lowest ? lowest.index : { insert: 0 };
+  }
+  let startMs = spec.at === 'end' ? (typeof track === 'number' ? endOf(track) : 0) : Math.max(0, snapToFrame(spec.at));
+  if (typeof track !== 'number') return { ops: [{ op: 'insert', clip: made.element as never, at: Math.round(startMs) / 1000, track }], track, startMs, durMs: made.durMs };
+  const switches = { magnet: Boolean(spec.magnet), linkage: Boolean(spec.linkage) };
+  /* on the main track with the magnet: in between, where the playhead is (before or after the clip under it) */
+  const mode: EditMode | 'place' = spec.mode ?? (magnetOn(model, track, switches.magnet) ? 'insert' : 'place');
+  if (!spec.mode && mode === 'insert') startMs = insertPointOn(model, track, startMs, startMs);
+  const clips = model.find((t) => t.index === track)?.clips ?? [];
+  if (mode === 'place' && clips.some((c) => c.startMs < startMs + made.durMs - TOUCH_MS && c.endMs > startMs + TOUCH_MS)) {
+    /* the time is taken: a new track beside, nothing cut */
+    const role = model.find((t) => t.index === track)?.role;
+    const beside: TrackDest = { insert: newTrackSide(track, role) };
+    return { ops: [{ op: 'insert', clip: made.element as never, at: Math.round(startMs) / 1000, track: beside }], track: beside, startMs, durMs: made.durMs };
+  }
+  const insert: Op = { op: 'insert', clip: made.element as never, at: Math.round(startMs) / 1000, track };
+  /* at the very end nothing follows: no room to make */
+  const after = clips.some((c) => c.endMs > startMs + TOUCH_MS);
+  const room = after && !roomy && mode !== 'place' ? planRoom(model, [{ track, startMs, endMs: startMs + made.durMs }], { mode, ...switches }).ops : [];
+  return { ops: [insert, ...room], track, startMs, durMs: made.durMs };
+}