auricui-skill 0.0.0-stage → 0.1.2

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/export-spec.ts

@@ -0,0 +1,261 @@
+/**
+ * What an export makes, as the export dialog chooses it: platform presets, codecs, quality, sizes, the estimate of a
+ * file's size. The server (studio/server/exports.mjs) draws the same frames with the same arithmetic.
+ *
+ * No watermark and no end card: the product doesn't make them, so a spec has no place for them.
+ */
+import { filmFrameBox, type FilmFrameFill, type FilmFrameId } from './film-frame.ts';
+
+/**
+ * Video codecs. `png` is a sequence of frames (one zip). The four with transparency each have their place:
+ * prores4444 for editors and compositing, hevc_alpha for Apple's apps and Safari (a fraction of ProRes's size), vp9
+ * for the web, png for anything (game engines, 3D, Nuke), the biggest.
+ */
+export type ExportVideoCodec = 'h264' | 'hevc' | 'vp9' | 'prores422hq' | 'prores4444' | 'hevc_alpha' | 'png';
+export const EXPORT_ALPHA_CODECS: readonly ExportVideoCodec[] = ['prores4444', 'hevc_alpha', 'vp9', 'png'];
+
+export type ExportQuality = 'standard' | 'high' | 'master';
+
+export const CODEC_LABEL: Record<ExportVideoCodec, string> = {
+  h264: 'H.264',
+  hevc: 'HEVC',
+  vp9: 'WebM VP9',
+  prores422hq: 'ProRes 422 HQ',
+  prores4444: 'ProRes 4444',
+  hevc_alpha: 'HEVC + Alpha',
+  png: 'PNG',
+};
+
+/* ── platform presets ──────────────────────────────────────────────────── */
+
+export type ExportPresetGroup = 'landscape' | 'vertical' | 'feed';
+
+/**
+ * A platform preset. Names are not translated (a platform's name is its name). Only limits known for sure are
+ * written (the longest video): a wrong limit is worse than none, since people cut their film to fit it.
+ */
+export interface ExportPreset {
+  id: string;
+  name: string;
+  group: ExportPresetGroup;
+  frame: Exclude<FilmFrameId, 'native'>;
+  shortEdge: number;
+  /** The most frames a second the platform shows: a film is exported at its own rate up to it (presetFps). */
+  fps: number;
+  /** Vertical feeds are mostly watched muted: subtitles burned in by default. */
+  burnSubtitles: boolean;
+  /** The platform's longest video, in seconds. */
+  maxDurationSec?: number;
+  /** A platform of mainland China: offered (first) when Studio speaks Chinese, not otherwise. */
+  china?: boolean;
+}
+
+export const EXPORT_PRESETS: readonly ExportPreset[] = [
+  { id: 'bilibili', name: '哔哩哔哩', group: 'landscape', frame: '16:9', shortEdge: 1080, fps: 60, burnSubtitles: false, china: true },
+  { id: 'douyin', name: '抖音', group: 'vertical', frame: '9:16', shortEdge: 1080, fps: 30, burnSubtitles: true, china: true },
+  { id: 'kuaishou', name: '快手', group: 'vertical', frame: '9:16', shortEdge: 1080, fps: 30, burnSubtitles: true, china: true },
+  { id: 'channels', name: '视频号', group: 'vertical', frame: '9:16', shortEdge: 1080, fps: 30, burnSubtitles: true, china: true },
+  { id: 'xiaohongshu', name: '小红书', group: 'feed', frame: '3:4', shortEdge: 1080, fps: 30, burnSubtitles: true, china: true },
+  { id: 'youtube', name: 'YouTube', group: 'landscape', frame: '16:9', shortEdge: 1080, fps: 60, burnSubtitles: false },
+  { id: 'youtube-4k', name: 'YouTube 4K', group: 'landscape', frame: '16:9', shortEdge: 2160, fps: 60, burnSubtitles: false },
+  { id: 'x', name: 'X', group: 'landscape', frame: '16:9', shortEdge: 1080, fps: 30, burnSubtitles: true, maxDurationSec: 140 },
+  { id: 'shorts', name: 'YouTube Shorts', group: 'vertical', frame: '9:16', shortEdge: 1080, fps: 30, burnSubtitles: true, maxDurationSec: 180 },
+  { id: 'tiktok', name: 'TikTok', group: 'vertical', frame: '9:16', shortEdge: 1080, fps: 30, burnSubtitles: true },
+  { id: 'reels', name: 'Instagram Reels', group: 'vertical', frame: '9:16', shortEdge: 1080, fps: 30, burnSubtitles: true },
+  { id: 'instagram', name: 'Instagram Feed', group: 'feed', frame: '4:5', shortEdge: 1080, fps: 30, burnSubtitles: true },
+  { id: 'square', name: 'LinkedIn · Facebook', group: 'feed', frame: '1:1', shortEdge: 1080, fps: 30, burnSubtitles: true },
+];
+
+/** The platforms offered in a language: China's first in Chinese, and none of them in any other. */
+export function exportPresetsFor(language: string): readonly ExportPreset[] {
+  return language === 'zh-CN' ? [...EXPORT_PRESETS.filter((p) => p.china), ...EXPORT_PRESETS.filter((p) => !p.china)] : EXPORT_PRESETS.filter((p) => !p.china);
+}
+
+/**
+ * A film's frames a second on a platform: its own, up to the most the platform shows. A 30 fps film is not drawn
+ * twice over for a platform that shows 60: no frame of it would be new.
+ */
+export function presetFps(preset: ExportPreset, filmFps: number): number {
+  return filmFps > 0 ? Math.min(preset.fps, filmFps) : preset.fps;
+}
+
+export function exportPreset(id: string | undefined): ExportPreset | null {
+  return EXPORT_PRESETS.find((p) => p.id === id) ?? null;
+}
+
+/* ── sizes ─────────────────────────────────────────────────────────────── */
+
+export const EXPORT_MAX_DIM = 4096;
+
+function even(n: number): number {
+  return Math.max(2, Math.round(n / 2) * 2);
+}
+
+/**
+ * A picture's size with its short side at `shortEdge`, the box's exact shape kept (`ratio`, when it has one: a 16:9
+ * frame at 1080 is 1920 × 1080); no side over 4096.
+ */
+export function exportDimsForShortEdge(box: { w: number; h: number; ratio?: number }, shortEdge: number): { w: number; h: number } {
+  const r = box.ratio ?? box.w / Math.max(1, box.h);
+  let w: number;
+  let h: number;
+  if (r >= 1) {
+    h = even(shortEdge);
+    w = even(h * r);
+  } else {
+    w = even(shortEdge);
+    h = even(w / r);
+  }
+  if (w > EXPORT_MAX_DIM || h > EXPORT_MAX_DIM) {
+    const k = Math.min(EXPORT_MAX_DIM / w, EXPORT_MAX_DIM / h);
+    w = even(w * k);
+    h = even(h * k);
+  }
+  return { w, h };
+}
+
+/** A GIF's size: its long side at `width`. */
+export function exportGifDims(box: { w: number; h: number; ratio?: number }, width: number): { w: number; h: number } {
+  const r = box.ratio ?? box.w / Math.max(1, box.h);
+  return r >= 1 ? { w: even(width), h: even(width / r) } : { w: even(width * r), h: even(width) };
+}
+
+/** The size of a framed picture. */
+export function exportFramedDims(
+  stage: { w: number; h: number },
+  frame: FilmFrameId,
+  fill: FilmFrameFill,
+  shortEdge: number,
+): { w: number; h: number } {
+  return exportDimsForShortEdge(filmFrameBox(stage, frame, fill), shortEdge);
+}
+
+/* ── bitrate and size ──────────────────────────────────────────────────── */
+
+/** Bits per pixel per frame by quality, for the encoders given a bitrate (exports.mjs BPP and `bitrate`). */
+const BITS_PER_PIXEL: Record<ExportQuality, number> = { standard: 0.07, high: 0.11, master: 0.2 };
+
+/** The bitrate an encoder is given (the server's arithmetic): size × fps × quality × `k`, 2 to 120 Mbps. */
+function givenBitrate(size: { w: number; h: number }, fps: number, quality: ExportQuality, k: number): number {
+  return Math.min(120_000_000, Math.max(2_000_000, size.w * size.h * Math.max(1, fps) * BITS_PER_PIXEL[quality] * k));
+}
+
+/**
+ * A file's size depends mostly on what is in the picture, not on the settings: at the same 1080p30 H.264 settings
+ * films measured run from about 0.6 Mbps (a slide of text) to 21 Mbps (a field of particles). So the dialog shows a
+ * range, from a typical film's picture: 0.25× to 4× of it for the codecs given a quality (CRF), ±10% for those near a
+ * fixed size a pixel. A rare busy film still falls above it.
+ */
+const TYPICAL_VIDEO = { w: 1920, h: 1080, fps: 30, bytes: 150_000 };
+const VIDEO_SPREAD: readonly [number, number] = [0.25, 4];
+const FIXED_SPREAD: readonly [number, number] = [0.9, 1.1];
+
+/** How a CRF file's size follows the settings: the quality's CRF, the codec at its CRF. */
+const QUALITY_SIZE: Record<ExportQuality, number> = { standard: 0.58, high: 1, master: 1.6 };
+/* HEVC as libx265 encodes it, at its CRF (an ffmpeg without libx265 uses VideoToolbox, given a bitrate: larger) */
+const CODEC_SIZE: Partial<Record<ExportVideoCodec, number>> = { h264: 1, hevc: 0.6, vp9: 0.7 };
+/** The sound beside the picture, as render encodes it: AAC 192k in an MP4, Opus 160k in WebM, 48 kHz PCM in a MOV. */
+const AUDIO_BYTES_PER_SECOND: Partial<Record<ExportVideoCodec, number>> = { vp9: 20_000, prores422hq: 192_000, prores4444: 192_000, hevc_alpha: 192_000 };
+
+/**
+ * How many of a picture's pixels are the film's: bars cost an encoder almost nothing. The rest of the frame, with
+ * `contain`, is bars; with `cover` the film fills it.
+ */
+export function exportFilmPixels(stage: { w: number; h: number }, frame: FilmFrameId, fill: FilmFrameFill, size: { w: number; h: number }): number {
+  const box = filmFrameBox(stage, frame, fill);
+  const share = Math.min(1, (box.inner.w * box.inner.h) / Math.max(1, box.w * box.h));
+  return size.w * size.h * share;
+}
+
+/**
+ * A video file's likely size in bytes, `[low, high]`, for the dialog's "about 1 MB–10 MB": a typical film's picture
+ * scaled to the pixels of film in it, the frame rate (more frames, each more like the last), the quality and the codec;
+ * ProRes, PNG and HEVC with alpha by their own arithmetic. Plus the sound, at both ends.
+ */
+export function exportEstimateBytes(spec: {
+  codec: ExportVideoCodec;
+  size: { w: number; h: number };
+  /** the pixels of film in the picture (exportFilmPixels); without it, all of them */
+  filmPixels?: number;
+  fps: number;
+  quality: ExportQuality;
+  durationMs: number;
+  audio: boolean;
+}): [number, number] {
+  const sec = Math.max(0, spec.durationMs) / 1000;
+  const px = spec.size.w * spec.size.h;
+  let videoBps: number;
+  let spread = FIXED_SPREAD;
+  switch (spec.codec) {
+    /* ProRes is a fixed-rate family: 422 HQ about 220 Mbps at 1080p30, 4444 about 330, scaled by pixels × fps */
+    case 'prores422hq': videoBps = 220_000_000 * (px / (1920 * 1080)) * (spec.fps / 30); break;
+    case 'prores4444': videoBps = 330_000_000 * (px / (1920 * 1080)) * (spec.fps / 30); break;
+    /* HEVC with alpha (VideoToolbox) is given its bitrate */
+    case 'hevc_alpha': videoBps = givenBitrate(spec.size, spec.fps, spec.quality, 0.8); break;
+    /* a PNG sequence of motion graphics compresses well: about a byte per pixel */
+    case 'png': videoBps = px * 8 * spec.fps; break;
+    default: {
+      const pixels = spec.filmPixels ?? px;
+      videoBps = 8 * TYPICAL_VIDEO.bytes * (pixels / (TYPICAL_VIDEO.w * TYPICAL_VIDEO.h)) ** 0.75
+        * (Math.max(1, spec.fps) / TYPICAL_VIDEO.fps) ** 0.35 * QUALITY_SIZE[spec.quality] * (CODEC_SIZE[spec.codec] ?? 1);
+      spread = VIDEO_SPREAD;
+    }
+  }
+  const audioBytes = spec.audio ? (AUDIO_BYTES_PER_SECOND[spec.codec] ?? 24_000) : 0;
+  const at = (k: number) => Math.round((videoBps / 8 * k + audioBytes) * sec);
+  return [at(spread[0]), at(spread[1])];
+}
+
+/** A typical film's GIF, 640 × 360 at 15 fps, and how far a film's strays from it. */
+const TYPICAL_GIF = { w: 640, h: 360, fps: 15, bytes: 300_000 };
+const GIF_SPREAD: readonly [number, number] = [0.4, 3];
+
+/** A GIF's likely size in bytes, `[low, high]`: a typical film's GIF scaled to the pixels of film and the frame rate. */
+export function exportGifEstimateBytes(spec: {
+  size: { w: number; h: number };
+  filmPixels?: number;
+  fps: number;
+  durationMs: number;
+}): [number, number] {
+  const pixels = spec.filmPixels ?? spec.size.w * spec.size.h;
+  const bytes = TYPICAL_GIF.bytes * (pixels / (TYPICAL_GIF.w * TYPICAL_GIF.h)) ** 0.9 * (Math.max(1, spec.fps) / TYPICAL_GIF.fps) ** 0.6
+    * Math.max(0, spec.durationMs) / 1000;
+  return [Math.round(bytes * GIF_SPREAD[0]), Math.round(bytes * GIF_SPREAD[1])];
+}
+
+/** A place a part of the film can start or end, named by the clips that start (or end) there. */
+export type RangeMark = { ms: number; title: string };
+
+/** Clip edges this close together are one place to cut (a frame or two apart is the same cut to a person). */
+const SAME_CUT_MS = 400;
+
+/**
+ * Where a part of the film can start and end: at its picture clips' edges ("scenes two to four" is what people mean).
+ * A start is named by the clips that start there, an end by the clips that end there. Edges close together are one;
+ * a start goes to the earliest of them and an end to the latest, so the part takes in every clip named. The film's
+ * own start and end are always there (an edge close to one is it).
+ */
+export function rangeMarks(scenes: readonly { startMs: number; durMs: number; label: string }[], totalMs: number): { starts: RangeMark[]; ends: RangeMark[] } {
+  const shown = scenes.filter((sc) => sc.durMs > 0 && sc.startMs < totalMs);
+  const group = (edges: { ms: number; label: string }[], latest: boolean) => {
+    const sorted = [...edges].sort((a, b) => a.ms - b.ms);
+    const groups: { ms: number; last: number; labels: string[] }[] = [];
+    for (const e of sorted) {
+      const g = groups.at(-1);
+      if (g && e.ms - g.last < SAME_CUT_MS) {
+        g.last = e.ms;
+        if (latest) g.ms = e.ms;
+        if (!g.labels.includes(e.label)) g.labels.push(e.label);
+      } else groups.push({ ms: e.ms, last: e.ms, labels: [e.label] });
+    }
+    return groups.map((g) => ({ ms: g.ms, title: g.labels.filter(Boolean).join(', ') }));
+  };
+  const starts = group(shown.map((sc) => ({ ms: Math.max(0, sc.startMs), label: sc.label })), false);
+  const ends = group(shown.map((sc) => ({ ms: Math.min(totalMs, sc.startMs + sc.durMs), label: sc.label })), true);
+  if (starts[0] && starts[0].ms < SAME_CUT_MS) starts[0].ms = 0;
+  else starts.unshift({ ms: 0, title: '' });
+  const last = ends.at(-1);
+  if (last && totalMs - last.ms < SAME_CUT_MS) last.ms = totalMs;
+  else if (totalMs > 0) ends.push({ ms: totalMs, title: '' });
+  return { starts, ends: ends.filter((e) => e.ms > 0) };
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/field-input.ts

@@ -0,0 +1,155 @@
+/**
+ * What a person types into a number field of the inspector, and how it is read: arithmetic
+ * (`1440/2`), a change of the value there (`+20`, `-20`, `*2`, `/2`), and units — `px` is dropped, `50%` is half of
+ * what the field measures against (the stage, for a place or a size), and a time takes seconds (`2.5s`), frames
+ * (`12f`, at the timecode's rate), milliseconds and timecodes (`00:00:02:15`, read as the timecode shows them).
+ *
+ * A leading `-` is a change, like `+`: "20 to the left". A negative value itself is typed in brackets, `(-20)`, or
+ * worked out, `0-20`.
+ */
+
+import { exactRate, timecodeSeconds } from './timecode.ts';
+
+/** A value to set, or a change of the value there (each of several selected things changes from its own). */
+export type FieldInput = { set: number } | { rel: '+' | '-' | '*' | '/'; by: number };
+
+export interface FieldContext {
+  /**
+   * What `100%` is: a number (the stage's width for an X), or `'self'` when the field is a percentage itself (an
+   * opacity, a crop). Without it, `%` is not understood.
+   */
+  percent?: number | 'self';
+  /** A time in seconds: `s`, `ms`, `f` and timecodes are understood (a bare number is seconds). */
+  time?: boolean;
+  /** Frames a second for `f` and timecodes. */
+  fps?: number;
+  /** The field's own unit marks, dropped when typed (`°`, `deg`, `×`, `x`). */
+  units?: readonly string[];
+}
+
+type Token =
+  | { kind: 'num'; value: number }
+  | { kind: 'op'; value: '+' | '-' | '*' | '/' | '(' | ')' };
+
+const DEFAULT_FPS = 30;
+
+/** The tokens of `raw`, units already applied to their numbers; null when something is not understood. */
+function tokenize(raw: string, ctx: FieldContext, inScale: boolean): Token[] | null {
+  const fps = ctx.fps ?? DEFAULT_FPS;
+  const units = [...(ctx.units ?? [])].sort((a, b) => b.length - a.length);
+  const out: Token[] = [];
+  let i = 0;
+  const s = raw.replace(/[−–]/g, '-').replace(/,/g, '.');
+  while (i < s.length) {
+    const ch = s[i]!;
+    if (/\s/.test(ch)) { i += 1; continue; }
+    if ('+-*/()'.includes(ch)) { out.push({ kind: 'op', value: ch as '+' }); i += 1; continue; }
+    const m = /^(?:\d+(?:\.\d*)?|\.\d+)(?::\d+(?:\.\d*)?)*/.exec(s.slice(i));
+    if (!m) return null;
+    i += m[0].length;
+    const rest = s.slice(i);
+    const unit = /^(px|ms|s|f|%)/i.exec(rest)?.[1]?.toLowerCase() ?? units.find((u) => rest.toLowerCase().startsWith(u.toLowerCase()));
+    if (unit) i += unit.length;
+    let value: number;
+    if (m[0].includes(':')) {
+      /* a timecode: SS:FF, MM:SS:FF or HH:MM:SS:FF */
+      if (!ctx.time || unit) return null;
+      const parts = m[0].split(':').map(Number);
+      if (parts.length > 4) return null;
+      const frames = parts.pop()!;
+      const [sec = 0, min = 0, hour = 0] = parts.reverse();
+      value = timecodeSeconds(hour * 3600 + min * 60 + sec, frames, fps);
+    } else {
+      const n = Number(m[0]);
+      if (unit === 'px' || (unit && units.includes(unit))) value = n;
+      else if (unit === '%') {
+        /* a scale (`*50%`) is a fraction; otherwise a share of what the field measures against */
+        if (inScale) value = n / 100;
+        else if (ctx.percent === 'self') value = n;
+        else if (typeof ctx.percent === 'number') value = (n / 100) * ctx.percent;
+        else return null;
+      } else if (unit === 's' || unit === 'ms' || unit === 'f') {
+        if (!ctx.time) return null;
+        value = unit === 's' ? n : unit === 'ms' ? n / 1000 : n / exactRate(fps);
+      } else value = n;
+    }
+    out.push({ kind: 'num', value });
+  }
+  return out;
+}
+
+/** Arithmetic over the tokens: + − × ÷, brackets, a sign before a number. */
+function evaluate(tokens: Token[]): number | null {
+  let at = 0;
+  const peek = () => tokens[at];
+  const isOp = (v: string) => { const t = peek(); return t?.kind === 'op' && t.value === v; };
+  const factor = (): number | null => {
+    const t = peek();
+    if (!t) return null;
+    if (t.kind === 'num') { at += 1; return t.value; }
+    if (t.value === '-' || t.value === '+') {
+      at += 1;
+      const v = factor();
+      return v == null ? null : t.value === '-' ? -v : v;
+    }
+    if (t.value === '(') {
+      at += 1;
+      const v = expr();
+      if (v == null || !isOp(')')) return null;
+      at += 1;
+      return v;
+    }
+    return null;
+  };
+  const term = (): number | null => {
+    let v = factor();
+    while (v != null && (isOp('*') || isOp('/'))) {
+      const op = (peek() as { value: string }).value;
+      at += 1;
+      const r = factor();
+      if (r == null) return null;
+      v = op === '*' ? v * r : r === 0 ? null : v / r;
+    }
+    return v;
+  };
+  const expr = (): number | null => {
+    let v = term();
+    while (v != null && (isOp('+') || isOp('-'))) {
+      const op = (peek() as { value: string }).value;
+      at += 1;
+      const r = term();
+      if (r == null) return null;
+      v = op === '+' ? v + r : v - r;
+    }
+    return v;
+  };
+  const v = expr();
+  return v != null && at === tokens.length && Number.isFinite(v) ? v : null;
+}
+
+/** What was typed, or null when it does not read as a number. */
+export function parseFieldInput(raw: string, ctx: FieldContext = {}): FieldInput | null {
+  const text = raw.trim().replace(/^[−–]/, '-');
+  if (!text) return null;
+  const lead = /^[+\-*/]/.exec(text)?.[0] as '+' | '-' | '*' | '/' | undefined;
+  if (lead) {
+    const tokens = tokenize(text.slice(1), ctx, lead === '*' || lead === '/');
+    const by = tokens && tokens.length ? evaluate(tokens) : null;
+    if (by == null || (lead === '/' && by === 0)) return null;
+    return { rel: lead, by };
+  }
+  const tokens = tokenize(text, ctx, false);
+  const value = tokens ? evaluate(tokens) : null;
+  return value == null ? null : { set: value };
+}
+
+/** The value `input` makes of `base`. */
+export function applyFieldInput(input: FieldInput, base: number): number {
+  if ('set' in input) return input.set;
+  switch (input.rel) {
+    case '+': return base + input.by;
+    case '-': return base - input.by;
+    case '*': return base * input.by;
+    default: return base / input.by;
+  }
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/film-clip-edits.ts

@@ -0,0 +1,82 @@
+/**
+ * The edits the timeline and the Inspector write back to film.html: one property of one clip.
+ *
+ * A whole object is written (or removed), not a dotted path — film.html edits only know a clip's top-level keys.
+ * A box goes through stage-clip's compactBox first, so what follows from the picture is not written.
+ */
+import type { TimelineBlock } from './timeline-layout';
+
+export type ClipEditValue = number | string | boolean | readonly number[] | Record<string, unknown> | null;
+
+export interface ClipEdit {
+  loc: string;
+  prop: string;
+  value: ClipEditValue;
+  from?: number;
+}
+
+/** film.html's field names that the inspector calls otherwise, at the start of a refusal */
+const FIELD_WORDS: Record<string, string> = { at: 'Start' };
+
+/**
+ * A refused clip edit, said for a person: film.html's reader words its problems for an agent (`clip "c1" (a.mp4): #t=2,12
+ * ends past the file's length of 10 s (#t= is a part of the file, …)`). The clip's address and the asides go, the
+ * media fragment is called the trim, and the first sentence stays, starting with a capital.
+ */
+export function plainClipRefusal(message: string): string {
+  const text = message
+    .replace(/^[^:\n]*?\btracks\[\d+\](?:\.clips\[\d+\])?(?: "[^"]*")?:?\s*/, '')
+    .replace(/^(?:[\w.-]+:\d+:|clip "[^"]*" \([^)]*\):)\s*/, '')
+    .replace(/\s*\([^()]*\)/g, '')
+    .split(/\s+—\s+|(?<=\.)\s+/)[0]!
+    .replace(/^#t=([^,\s]+),([^\s]+)/, 'the trim $1–$2 s')
+    .replace(/^its part of the file\b/, 'the trim')
+    .trim();
+  if (!text) return message;
+  const field = /^([a-z]+)\b/.exec(text)?.[1];
+  const named = field && FIELD_WORDS[field] ? `${FIELD_WORDS[field]}${text.slice(field.length)}` : text;
+  const sentence = named.charAt(0).toUpperCase() + named.slice(1);
+  return /[.!?]$/.test(sentence) ? sentence : `${sentence}.`;
+}
+
+/**
+ * Clips on one track do not overlap: a new start (the inspector's) that would put a clip over another on its track
+ * takes it to a new track just above, as a drag does. Edits that already say where the clip goes are left as they are.
+ *
+ * Every clip is checked where the whole batch puts it. Checked against where its neighbors were, three clips slid
+ * left together came apart: the second landed on the first's old place and went to a new track, the third after it.
+ * A trim (`at` with `start` or `end`) keeps its other edge, and the timeline already stops it at its neighbors.
+ */
+export function apartOnTracks(edits: ClipEdit[], blocks: readonly Pick<TimelineBlock, 'loc' | 'startMs' | 'endMs'>[]): ClipEdit[] {
+  const trackOf = (loc?: string) => (loc ? Number(/^film\.html#(\d+)\./.exec(loc)?.[1] ?? NaN) : NaN);
+  const atOf = new Map<string, number>();
+  const trimmed = new Set<string>();
+  const leaving = new Set<string>();
+  for (const e of edits) {
+    if (e.prop === 'at' && typeof e.value === 'number') atOf.set(e.loc, e.value * 1000);
+    if (e.prop === 'start' || e.prop === 'end') trimmed.add(e.loc);
+    if (e.prop === 'track') leaving.add(e.loc);
+  }
+  const landing = (b: Pick<TimelineBlock, 'loc' | 'startMs' | 'endMs'>) => {
+    const at = b.loc ? atOf.get(b.loc) : undefined;
+    if (at == null) return { startMs: b.startMs, endMs: b.endMs };
+    return { startMs: at, endMs: trimmed.has(b.loc!) ? b.endMs : at + (b.endMs - b.startMs) };
+  };
+  /* times are kept to the millisecond, a start and a length each rounded alone: clips that touch can overlap by one */
+  const TOUCH_MS = 1;
+  const out = [...edits];
+  for (const e of edits) {
+    if (e.prop !== 'at' || typeof e.value !== 'number' || leaving.has(e.loc) || trimmed.has(e.loc)) continue;
+    const self = blocks.find((b) => b.loc === e.loc);
+    const track = trackOf(e.loc);
+    if (!self || !Number.isFinite(track)) continue;
+    const me = landing(self);
+    const over = blocks.some((b) => {
+      if (b === self || !b.loc || leaving.has(b.loc) || trackOf(b.loc) !== track) return false;
+      const r = landing(b);
+      return me.startMs < r.endMs - TOUCH_MS && me.endMs > r.startMs + TOUCH_MS;
+    });
+    if (over) out.push({ loc: e.loc, prop: 'track', value: { insert: track } });
+  }
+  return out;
+}

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

@@ -0,0 +1,134 @@
+/**
+ * Delivery frame: fitting a film into a box of another aspect ratio.
+ *
+ * The film stays as it is; the frame goes around it. A 16:9 film delivered vertically gets a 9:16 box with the film
+ * centered and black bars above and below — not a 1080×1920 stage, which would break every px coordinate the film was
+ * laid out with. Re-laying a film out is its author's job, not a button's.
+ *
+ * Two ways to fit it: `contain` (default) scales and centers with bars and never crops; `cover` fills the box and
+ * crops the overflow, so the edges are really gone — a choice, never the default.
+ *
+ * The frame is the export's choice, not part of the film: picked in the export dialog for one export (the film's own
+ * shape is its canvas, which the viewer's ratio button changes).
+ */
+
+/**
+ * A delivery frame: `native` (no frame, the film at its own size), or a ratio written `W:H` ("16:9", "2.39:1"): one of
+ * the presets, or any other the person types, from 1:4 to 4:1.
+ */
+export type FilmFrameId = 'native' | `${number}:${number}`;
+
+/** The presets, as editors offer them: video and social shapes first, then photo and cinema ones. */
+export const FILM_FRAME_IDS: FilmFrameId[] = [
+  'native', '16:9', '9:16', '1:1', '4:5', '4:3', '3:4', '3:2', '2:3', '21:9', '2.39:1', '1.85:1', '2:1',
+];
+
+/** How far a frame may go from square, either way (a custom one past it is refused). */
+export const FRAME_RATIO_LIMIT = 4;
+const RATIO = /^(\d{1,4}(?:\.\d{1,3})?):(\d{1,4}(?:\.\d{1,3})?)$/;
+
+/** Width ÷ height of a frame written `W:H`, or null when it is not one (or too far from square). */
+export function frameRatioOf(frame: string): number | null {
+  const m = RATIO.exec(frame);
+  if (!m) return null;
+  const ratio = Number(m[1]) / Number(m[2]);
+  return Number.isFinite(ratio) && ratio >= 1 / FRAME_RATIO_LIMIT && ratio <= FRAME_RATIO_LIMIT ? ratio : null;
+}
+
+/** A frame from a typed width and height ("2.39" and "1"), or null when they make none. */
+export function customFilmFrame(w: number, h: number): FilmFrameId | null {
+  const num = (n: number) => String(Math.round(n * 1000) / 1000);
+  if (!(w > 0) || !(h > 0)) return null;
+  const id = `${num(w)}:${num(h)}`;
+  return frameRatioOf(id) != null ? id as FilmFrameId : null;
+}
+
+export function filmFrameRatio(frame: FilmFrameId, stage: { w: number; h: number }): number {
+  return (frame === 'native' ? null : frameRatioOf(frame)) ?? stage.w / Math.max(1, stage.h);
+}
+
+/** Even sizes: H.264 samples chroma in 2×2 blocks and refuses odd dimensions. */
+function even(n: number): number {
+  return Math.max(2, Math.round(n / 2) * 2);
+}
+
+export type FilmFrameFill = 'contain' | 'cover';
+
+export interface FilmFrameBox {
+  /** The frame's pixel size (an export comes out this size). */
+  w: number;
+  h: number;
+  /** Its exact shape: the frame's own ratio, not its even-rounded pixels' (16:9 around a 2:1 film is 2160 × 1216). */
+  ratio: number;
+  /** The film inside the frame, scaled. With `cover`, `left`/`top` go negative: the overflow is cut by the frame. */
+  inner: { w: number; h: number; left: number; top: number; scale: number };
+}
+
+/**
+ * Fit `stage` into `frame`: the frame's size and the film's place in it. The frame's long side follows the film's
+ * (a 4K film framed 9:16 stays 4K-sharp; a 720p film is not blown up), so the frame only decides the shape.
+ */
+export function filmFrameBox(
+  stage: { w: number; h: number },
+  frame: FilmFrameId,
+  fill: FilmFrameFill = 'contain',
+): FilmFrameBox {
+  const sw = Math.max(1, stage.w);
+  const sh = Math.max(1, stage.h);
+  const ratio = frame === 'native' ? null : frameRatioOf(frame);
+  if (ratio == null) {
+    return { w: even(sw), h: even(sh), ratio: sw / sh, inner: { w: sw, h: sh, left: 0, top: 0, scale: 1 } };
+  }
+  /* the frame must hold the film both ways: take the larger */
+  const byWidth = { w: sw, h: sw / ratio };
+  const byHeight = { w: sh * ratio, h: sh };
+  const box = byWidth.h >= sh ? byWidth : byHeight;
+  const w = even(box.w);
+  const h = even(box.h);
+  const scale = fill === 'cover'
+    ? Math.max(w / sw, h / sh)
+    : Math.min(w / sw, h / sh);
+  const iw = sw * scale;
+  const ih = sh * scale;
+  return {
+    w,
+    h,
+    ratio,
+    inner: { w: iw, h: ih, left: (w - iw) / 2, top: (h - ih) / 2, scale },
+  };
+}
+
+/** Whether the frame has the film's own shape (then framing it changes nothing). */
+export function filmFrameIsNative(stage: { w: number; h: number }, frame: FilmFrameId): boolean {
+  const ratio = frame === 'native' ? null : frameRatioOf(frame);
+  if (ratio == null) return true;
+  return Math.abs(stage.w / Math.max(1, stage.h) - ratio) < 0.01;
+}
+
+/**
+ * The stage itself in another shape (canvas mode: nothing has been laid out yet, so changing the stage breaks
+ * nothing). 1080p family: the short side is pinned at 1080 (16:9 = 1920×1080, 21:9 = 2520×1080, 9:16 = 1080×1920).
+ */
+const HD = 1080;
+
+export function filmFrameStage(
+  stage: { w: number; h: number },
+  frame: FilmFrameId,
+): { w: number; h: number } {
+  const ratio = frame === 'native' ? null : frameRatioOf(frame);
+  if (ratio == null) return { w: even(stage.w), h: even(stage.h) };
+  return ratio >= 1
+    ? { w: even(HD * ratio), h: even(HD) }
+    : { w: even(HD), h: even(HD / ratio) };
+}
+
+/** Which frame this stage's shape is (`native` when none). Canvas mode ticks this one. */
+export function filmFrameOf(stage: { w: number; h: number }): FilmFrameId {
+  return FILM_FRAME_IDS.find((id) => id !== 'native' && filmFrameIsNative(stage, id)) ?? 'native';
+}
+
+export function parseFilmFrame(raw: unknown): FilmFrameId {
+  return typeof raw === 'string' && (raw === 'native' || frameRatioOf(raw) != null)
+    ? raw as FilmFrameId
+    : 'native';
+}