auricui-skill 0.0.0-stage → 0.1.2

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/component-props.ts

@@ -0,0 +1,128 @@
+/**
+ * A page clip's component properties: the few things of its page the person chose to offer for change, each named, as
+ * a design tool's component offers its properties. A property is made from a layer in the page (its words, its
+ * picture, whether it shows) or from one of the page's CSS variables; every clip of the page (a copy, one taken from
+ * Saved) offers the same ones, and each fills them in its own way.
+ *
+ * Where they are kept: the clip's `data-props`, a JSON list (an attribute the film keeps and gives no meaning, SPEC §1).
+ * What each clip fills in is an override, as any change made on the picture is: words as a `text` entry, a picture
+ * as the CSS that draws another file in its place, hidden as `visibility: hidden`, a variable in the `:root` entry's
+ * style. A property at its default has no override. The page itself is never written.
+ *
+ * Pure: no React, no DOM, so `node --test` runs it.
+ */
+
+import type { FilmOverride } from './film.ts';
+import { nextOverrides, overrideOf } from './film-overrides.ts';
+import { changedImage, changedText, changedVar, withImage, withText, withVar } from './template-controls.ts';
+
+/** Where the properties are kept on the clip. */
+export const PROPS_ATTR = 'data-props';
+
+/** Which layer: the CSS selector in the page and which match (none: every match). */
+type Target = { at: string; n?: number };
+
+export type ComponentProp =
+  | ({ name: string; type: 'text' } & Target)
+  | ({ name: string; type: 'image'; kind: 'img' | 'bg' } & Target)
+  | ({ name: string; type: 'boolean' } & Target)
+  | { name: string; type: 'var'; var: string };
+
+export type ComponentPropType = ComponentProp['type'];
+
+/** The value a property is set to: words, a file's place from the page's folder, shown or not, a CSS value. */
+export type PropValue = string | boolean;
+
+const isTarget = (o: Record<string, unknown>): boolean => typeof o.at === 'string' && o.at !== '' && (o.n === undefined || (Number.isInteger(o.n) && Number(o.n) > 0));
+
+/** The clip's properties, as its `data-props` lists them (anything not one left out). */
+export function propsOf(clip: { attrs?: Record<string, string> } | null | undefined): ComponentProp[] {
+  const raw = clip?.attrs?.[PROPS_ATTR];
+  if (!raw) return [];
+  let list: unknown;
+  try { list = JSON.parse(raw); } catch { return []; }
+  if (!Array.isArray(list)) return [];
+  const out: ComponentProp[] = [];
+  for (const item of list) {
+    if (!item || typeof item !== 'object') continue;
+    const o = item as Record<string, unknown>;
+    if (typeof o.name !== 'string' || !o.name.trim() || out.some((p) => p.name === o.name)) continue;
+    const at = { at: o.at as string, ...(o.n !== undefined ? { n: o.n as number } : {}) };
+    if ((o.type === 'text' || o.type === 'boolean') && isTarget(o)) out.push({ name: o.name, type: o.type, ...at });
+    else if (o.type === 'image' && isTarget(o) && (o.kind === 'img' || o.kind === 'bg')) out.push({ name: o.name, type: 'image', kind: o.kind, ...at });
+    else if (o.type === 'var' && typeof o.var === 'string' && o.var.startsWith('--')) out.push({ name: o.name, type: 'var', var: o.var });
+  }
+  return out;
+}
+
+/** The properties as `data-props` keeps them; null when there are none (the attribute goes). */
+export function propsAttr(list: readonly ComponentProp[]): string | null {
+  return list.length ? JSON.stringify(list) : null;
+}
+
+/** A name not taken among `list`: `base`, else `base 2`, `base 3`… */
+export function freshName(list: readonly ComponentProp[], base: string): string {
+  const name = base.trim().slice(0, 40) || 'Property';
+  for (let i = 1; ; i++) {
+    const candidate = i === 1 ? name : `${name} ${i}`;
+    if (!list.some((p) => p.name === candidate)) return candidate;
+  }
+}
+
+const sameTarget = (a: Target, b: Target) => a.at === b.at && (a.n ?? null) === (b.n ?? null);
+
+/** The property made of this layer's words / picture / showing, or of this variable, when there is one. */
+export function propOf(list: readonly ComponentProp[], type: ComponentPropType, of: Target | string): ComponentProp | null {
+  return list.find((p) => p.type === type && (p.type === 'var' ? p.var === of : typeof of !== 'string' && sameTarget(p, of))) ?? null;
+}
+
+/** The list with `prop` added; one of the same type made of the same thing is replaced (its name kept unique). */
+export function withProp(list: readonly ComponentProp[], prop: ComponentProp): ComponentProp[] {
+  const of = prop.type === 'var' ? prop.var : { at: prop.at, ...(prop.n !== undefined ? { n: prop.n } : {}) };
+  const rest = list.filter((p) => p !== propOf(list, prop.type, of));
+  return [...rest, { ...prop, name: freshName(rest, prop.name) }];
+}
+
+/** The list without the property named `name`. */
+export function withoutProp(list: readonly ComponentProp[], name: string): ComponentProp[] {
+  return list.filter((p) => p.name !== name);
+}
+
+/** The list with a property renamed; a name taken or empty leaves it as it was. */
+export function renamedProp(list: readonly ComponentProp[], name: string, next: string): ComponentProp[] {
+  const to = next.trim().slice(0, 40);
+  if (!to || to === name || list.some((p) => p.name === to)) return [...list];
+  return list.map((p) => (p.name === name ? { ...p, name: to } : p));
+}
+
+const targetOf = (p: Exclude<ComponentProp, { type: 'var' }>): Target => ({ at: p.at, ...(p.n !== undefined ? { n: p.n } : {}) });
+
+/**
+ * What the clip set a property to (its override), or null at its default: words, a file's place from the page's folder,
+ * `false` for a layer hidden, a CSS value.
+ */
+export function propValue(overrides: readonly FilmOverride[] | undefined, prop: ComponentProp): PropValue | null {
+  switch (prop.type) {
+    case 'text': return changedText(overrides, prop.at, prop.n);
+    case 'image': return changedImage(overrides, { ...targetOf(prop), kind: prop.kind });
+    case 'boolean': return overrideOf(overrides, targetOf(prop))?.style?.visibility === 'hidden' ? false : null;
+    case 'var': return changedVar(overrides, prop.var);
+  }
+}
+
+/** The clip's next overrides with a property set (null: back to its default). Null when none is left. */
+export function withPropValue(overrides: readonly FilmOverride[] | undefined, prop: ComponentProp, value: PropValue | null): FilmOverride[] | null {
+  switch (prop.type) {
+    case 'text': return withText(overrides, prop.at, prop.n, typeof value === 'string' ? value : null);
+    case 'image': return withImage(overrides, { ...targetOf(prop), kind: prop.kind }, typeof value === 'string' ? value : null);
+    case 'boolean': return nextOverrides(overrides, targetOf(prop), { style: { visibility: value === false ? 'hidden' : null } });
+    case 'var': return withVar(overrides, prop.var, typeof value === 'string' ? value : null);
+  }
+}
+
+/** The clip's next overrides with every property back to its default (its other changes, moves and fades, stay). */
+export function withPropsReset(overrides: readonly FilmOverride[] | undefined, list: readonly ComponentProp[]): FilmOverride[] | null {
+  let next: readonly FilmOverride[] | undefined = overrides;
+  for (const p of list) if (propValue(next, p) != null) next = withPropValue(next, p, null) ?? undefined;
+  return next?.length ? [...next] : null;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/context-length.ts

@@ -0,0 +1,12 @@
+/**
+ * The context length of one of the person's own models, as typed in Settings → Agents: a whole number of tokens from
+ * 32K to 10M (apps/desktop src/pi-config.mjs contextLength), its thousands separated or not.
+ * `{}` when empty (the model gets 128K), `{ context }` when it holds, null when it does not.
+ */
+export function parseContextLength(text: string): { context?: number } | null {
+  const typed = text.trim();
+  if (!typed) return {};
+  if (!/^\d+$|^\d{1,3}([,. '’]\d{3})+$/.test(typed)) return null;
+  const context = Number(typed.replace(/\D/g, ''));
+  return context >= 32_000 && context <= 10_000_000 ? { context } : null;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/desktop-build.ts

@@ -0,0 +1,44 @@
+/**
+ * Which desktop app this computer takes: its system (macOS or Windows; any other has no app) and its chip. Chromium
+ * says both outright; Safari says neither, so a Mac whose graphics are Intel's or AMD's is an Intel Mac and any other
+ * Mac is Apple silicon (the website's download button decides the same way).
+ */
+export type DesktopSystem = 'mac' | 'win';
+export type DesktopArch = 'arm64' | 'x64';
+
+type UAData = { platform?: string; getHighEntropyValues?: (hints: string[]) => Promise<{ architecture?: string; bitness?: string }> };
+const uaData = (): UAData | undefined => (typeof navigator === 'undefined' ? undefined : (navigator as Navigator & { userAgentData?: UAData }).userAgentData);
+
+/** This computer's system, or null when there is no desktop app for it. */
+export function desktopSystem(): DesktopSystem | null {
+  if (typeof navigator === 'undefined') return null;
+  const platform = `${uaData()?.platform ?? ''} ${navigator.platform ?? ''} ${navigator.userAgent ?? ''}`.toLowerCase();
+  if (/iphone|ipad|android/.test(platform)) return null;
+  if (/mac/.test(platform)) return 'mac';
+  if (/win/.test(platform)) return 'win';
+  return null;
+}
+
+/** A Mac's chip, from its graphics. */
+function macChip(): DesktopArch {
+  try {
+    const gl = document.createElement('canvas').getContext('webgl');
+    const info = gl?.getExtension('WEBGL_debug_renderer_info');
+    const renderer = gl && info ? String(gl.getParameter(info.UNMASKED_RENDERER_WEBGL)) : '';
+    return /intel|amd|radeon/i.test(renderer) ? 'x64' : 'arm64';
+  } catch {
+    return 'arm64';
+  }
+}
+
+/** The system and chip whose installer this computer takes, or null when there is no desktop app for it. */
+export async function desktopBuild(): Promise<{ os: DesktopSystem; arch: DesktopArch } | null> {
+  const os = desktopSystem();
+  if (!os) return null;
+  let arch: DesktopArch | null = null;
+  try {
+    const values = await uaData()?.getHighEntropyValues?.(['architecture', 'bitness']);
+    if (values?.architecture) arch = values.architecture === 'arm' && values.bitness !== '32' ? 'arm64' : 'x64';
+  } catch { /* not Chromium */ }
+  return { os, arch: arch ?? (os === 'mac' ? macChip() : 'x64') };
+}

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

@@ -0,0 +1,68 @@
+/**
+ * The diagnostic report Settings → Developer copies: `openfilm doctor` as Studio's server runs it (src/doctor.mjs), what
+ * the browser Studio is open in can do (an agent's built-in browser can lack what Studio needs), and in the desktop
+ * app, its agents (lib/host.ts `diagnostics`).
+ */
+import { chromiumBased } from './browser.ts';
+
+export interface PageFacts {
+  userAgent: string;
+  chromium: boolean;
+  /** what draws WebGL here; null without WebGL */
+  webgl: string | null;
+  /** inside another page's frame (a preview pane), where cookies and storage can be blocked */
+  framed: boolean;
+  cookies: boolean;
+  storage: boolean;
+  /** the screen and window, in CSS px, and the pixel ratio */
+  screen: string;
+}
+
+/** What the page Studio is in can do, read now. */
+export function pageFacts(): PageFacts {
+  let webgl: string | null = null;
+  try {
+    const gl = document.createElement('canvas').getContext('webgl');
+    if (gl) {
+      const info = gl.getExtension('WEBGL_debug_renderer_info');
+      webgl = String(gl.getParameter(info ? info.UNMASKED_RENDERER_WEBGL : gl.RENDERER));
+    }
+  } catch { /* none */ }
+  let storage = false;
+  try { localStorage.setItem('openfilm-doctor', '1'); localStorage.removeItem('openfilm-doctor'); storage = true; } catch { /* blocked */ }
+  let framed = false;
+  try { framed = window.top !== window; } catch { framed = true; }
+  return {
+    userAgent: navigator.userAgent,
+    chromium: chromiumBased(),
+    webgl,
+    framed,
+    cookies: navigator.cookieEnabled,
+    storage,
+    screen: `${screen.width}×${screen.height}, window ${window.innerWidth}×${window.innerHeight} @${window.devicePixelRatio}x`,
+  };
+}
+
+/** The browser's lines of the report, each with ✓ or ✗ as the doctor's, and what to do about a ✗. */
+export function browserLines(f: PageFacts): string[] {
+  const line = (ok: boolean, label: string, text: string) => `${ok ? '✓' : '✗'} ${label.padEnd(10)}${text}`;
+  const fixes: string[] = [];
+  if (!f.chromium) fixes.push('Browser: open Studio in Chrome, Edge or the desktop app; previews can fail in other browsers');
+  if (!f.webgl) fixes.push('WebGL: turn on hardware acceleration in the browser');
+  if (!f.cookies || !f.storage) fixes.push('Storage: allow cookies and site data for 127.0.0.1, or open Studio in its own tab');
+  return [
+    'Browser Studio is open in',
+    '',
+    line(f.chromium, 'Engine', f.chromium ? 'Chromium' : 'not Chromium'),
+    line(true, 'UA', f.userAgent),
+    line(Boolean(f.webgl), 'WebGL', f.webgl ?? 'unavailable'),
+    line(f.cookies && f.storage, 'Storage', `cookies ${f.cookies ? 'on' : 'off'}, site data ${f.storage ? 'on' : 'blocked'}${f.framed ? ', inside another page' : ''}`),
+    line(true, 'Screen', f.screen),
+    ...(fixes.length ? ['', 'To fix:', ...fixes.map((fix) => `  ${fix}`)] : []),
+  ];
+}
+
+/** The whole report: the computer's, the browser's, and the desktop app's when there is one. */
+export function fullReport(computer: string, page: PageFacts, app?: string | null): string {
+  return [computer, browserLines(page).join('\n'), ...(app ? [app] : [])].join('\n\n────────\n\n');
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/double-press.ts

@@ -0,0 +1,22 @@
+/** A press on the picture: where, in the film's own pixels, and when (an event's timeStamp, ms). */
+export interface Press { x: number; y: number; at: number }
+
+/** Two presses this close in time are one double-click (the system's own interval is about this). */
+export const DOUBLE_PRESS_MS = 500;
+
+/** The presses kept: the last two, since a double-click is aimed by the first of its pair. */
+export function keepPress(presses: readonly Press[], press: Press): Press[] {
+  return [...presses.slice(-1), press];
+}
+
+/**
+ * Where a double-click at `now` was aimed: its first press. The picture can move under the hand between the two (the
+ * first click opens the inspector, which shrinks it), so the second press is not where it was meant. The press just
+ * before the second one, not the first in a while: a click elsewhere a moment earlier was not aimed at it. Null when
+ * the last two presses are not the double-click's (the double-click's own point is then the best there is).
+ */
+export function doubleClickAim(presses: readonly Press[], now: number): Press | null {
+  const [first, second] = presses.length >= 2 ? presses.slice(-2) : [];
+  if (!first || !second) return null;
+  return second.at - first.at < DOUBLE_PRESS_MS && now - second.at < DOUBLE_PRESS_MS ? first : null;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/dropped-overrides.ts

@@ -0,0 +1,139 @@
+/**
+ * The person's changes inside pages (film.html `overrides`) that a write from outside Studio left out.
+ *
+ * Agents rewrite film.html whole. One that never read the `overrides` a person made in Studio writes the file back
+ * without them, and the edits vanish with no word (version history still has them, but nobody looks there). When
+ * film.html changes on disk from outside, Studio compares the clips that are still there: an override whose target
+ * (`at` + `n`) is gone entirely was dropped; one the writer changed was meant, and stays as written.
+ *
+ * A clip is the same clip when its name matches: its `id`, or, without one, the name the format gives it (its file's
+ * name, see clipIdFor). So an agent that leaves out an id Studio wrote still means the same clip.
+ */
+import { clipIdFor } from '../../../../src/film-doc.mjs';
+import { filmDocLoc, type FilmClip, type FilmDoc, type FilmOverride } from './film.ts';
+
+export interface DroppedEdits {
+  /** the clip as it is now: `film.html#<track>.<clip>` */
+  loc: string;
+  src: string;
+  /** what was dropped, in its old order */
+  dropped: FilmOverride[];
+  /** the clip's overrides with the dropped ones back (what a restore writes) */
+  restored: FilmOverride[];
+}
+
+/** What an override changes: the element (`at`) and which match of it (`n`). */
+export const overrideTarget = (o: FilmOverride) => `${o.at}\u0000${o.n ?? ''}`;
+
+/** Each clip by its name, the way the format names it: written ids first, then the rest after their files. */
+function clipKeys(doc: FilmDoc): Map<string, { clip: FilmClip; loc: string }> {
+  const keys = new Map<string, { clip: FilmClip; loc: string }>();
+  const taken = new Set<string>();
+  doc.tracks.forEach((track) => track.clips.forEach((clip) => { if (clip.id) taken.add(clip.id); }));
+  doc.tracks.forEach((track, ti) => track.clips.forEach((clip, ci) => {
+    let name = clip.id;
+    if (!name) { name = clipIdFor(clip.src, [...taken]); taken.add(name); }
+    if (!keys.has(name)) keys.set(name, { clip, loc: filmDocLoc(ti, ci) });
+  }));
+  return keys;
+}
+
+export function droppedOverrides(before: FilmDoc | null | undefined, after: FilmDoc | null | undefined): DroppedEdits[] {
+  if (!before?.tracks || !after?.tracks) return [];
+  const now = clipKeys(after);
+  const out: DroppedEdits[] = [];
+  for (const [key, { clip: was }] of clipKeys(before)) {
+    if (!was.overrides?.length) continue;
+    const still = now.get(key);
+    if (!still || still.clip.src !== was.src) continue; /* the clip itself went: removing it was the point */
+    const kept = new Set((still.clip.overrides ?? []).map(overrideTarget));
+    const dropped = was.overrides.filter((o) => !kept.has(overrideTarget(o)));
+    if (!dropped.length) continue;
+    out.push({ loc: still.loc, src: still.clip.src, dropped, restored: [...(still.clip.overrides ?? []), ...dropped] });
+  }
+  return out;
+}
+
+/** A clip field the person set in Studio: the clip's name, the edit's prop (as the timeline and inspector send it), the value. */
+export interface PersonEdit {
+  clip: string;
+  prop: string;
+  value: unknown;
+}
+
+/** A clip field as film.html holds it, for a prop the editor sends (`start` and `end` are the two ends of `time`). */
+function fieldOf(clip: FilmClip, prop: string): unknown {
+  const raw = clip as unknown as Record<string, unknown>;
+  const time = Array.isArray(raw.time) ? (raw.time as number[]) : [];
+  if (prop === 'start') return time[0] ?? 0;
+  if (prop === 'end') return time[1] ?? null;
+  if (prop === 'at') return raw.at ?? 0;
+  if (prop === 'volume' || prop === 'speed') return raw[prop] ?? 1;
+  return raw[prop] ?? null;
+}
+
+/** The props of a clip that are its own fields (a track's switches and moves to other tracks are not). */
+const CLIP_FIELDS = new Set(['at', 'start', 'end', 'volume', 'speed', 'box']);
+
+/** An edit's value as fieldOf reads the field: `null` is the default it sets back (0 for `at` and `start`, 1 for `volume` and `speed`). */
+function editValueOf(e: PersonEdit): unknown {
+  if (e.value != null) return e.value;
+  if (e.prop === 'at' || e.prop === 'start') return 0;
+  if (e.prop === 'volume' || e.prop === 'speed') return 1;
+  return null;
+}
+
+/**
+ * Two field values alike as film.html means them: key order and rounding aside (`{ x, y }` is `{ y, x }`; film.html
+ * writes times to the millisecond, and 1.2 written back as 1.2000000001 is 1.2), so a writer that only reformats
+ * changes nothing.
+ */
+function sameValue(a: unknown, b: unknown): boolean {
+  if (typeof a === 'number' && typeof b === 'number') return Math.abs(a - b) <= 0.0005 + 1e-9;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => sameValue(v, b[i]));
+  }
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    const x = a as Record<string, unknown>, y = b as Record<string, unknown>;
+    const keys = new Set([...Object.keys(x), ...Object.keys(y)]);
+    for (const k of keys) if (!sameValue(x[k] ?? null, y[k] ?? null)) return false;
+    return true;
+  }
+  return a === b || (a == null && b == null);
+}
+
+/**
+ * The person's own edits that a write from outside changed: an agent that wrote film.html back from what it read
+ * before sets the fields the person changed back to what they were, with no word.
+ *
+ * `edits` are every field edit the person has made (their undo history, oldest first); only the latest of each clip
+ * field counts, and only while its value is still in the film shown here (`before`): one the person undid or changed
+ * again, or one already put back or left out (`settled`), is not theirs to watch any more. They are watched across any
+ * number of outside writes, so an agent that saves once with the person's edit and later writes a stale copy without it
+ * is still caught. `undone` are the edits to make again; `gone` the ones whose clip the write removed (on purpose: not
+ * watched any more).
+ */
+export function undoneFields(
+  before: FilmDoc | null | undefined,
+  after: FilmDoc | null | undefined,
+  edits: readonly PersonEdit[],
+  settled: ReadonlySet<PersonEdit> = new Set(),
+): { undone: PersonEdit[]; gone: PersonEdit[] } {
+  const undone: PersonEdit[] = [];
+  const gone: PersonEdit[] = [];
+  if (!before?.tracks || !after?.tracks) return { undone, gone };
+  const was = clipKeys(before);
+  const now = clipKeys(after);
+  const latest = new Map<string, PersonEdit>();
+  for (const e of edits) if (CLIP_FIELDS.has(e.prop)) latest.set(`${e.clip}\u0000${e.prop}`, e);
+  for (const e of latest.values()) {
+    if (settled.has(e)) continue;
+    const a = was.get(e.clip);
+    const value = editValueOf(e);
+    if (!a || !sameValue(fieldOf(a.clip, e.prop), value)) continue;
+    const b = now.get(e.clip);
+    if (!b || a.clip.src !== b.clip.src) { gone.push(e); continue; }
+    if (!sameValue(fieldOf(b.clip, e.prop), value)) undone.push(e);
+  }
+  return { undone, gone };
+}

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

@@ -0,0 +1,191 @@
+/**
+ * Exports run on this machine, in Studio's server (studio/server/exports.mjs): the dialog queues them, the tray
+ * follows them (the project's event stream says every change of a job), cancels them, and opens what they made.
+ */
+import type { FilmFrameFill, FilmFrameId } from '@/lib/film-frame';
+import type { ExportQuality, ExportVideoCodec } from '@/lib/export-spec';
+
+/** `burnSubtitles`: the film's subtitles drawn into the picture, as the editor shows them. */
+type Framing = { frame?: FilmFrameId; fill?: FilmFrameFill; burnSubtitles?: boolean };
+
+/** One export, as the server takes it. `range` is [from, to] in seconds; `name` is what its files are called (the
+ * project's name when there is none). */
+/**
+ * How an editing-program export writes its pages. A draft: `auto` (a page with no clear pixel in any frame as H.264, the
+ * others as lossless PNG), `png`, or `prores` (422 HQ and 4444 the same way). An XML: ProRes 4444 or PNG.
+ */
+export type NleAlpha = 'auto' | 'png' | 'prores' | 'prores4444';
+
+export type ExportRequest = { range?: [number, number]; label?: string; name?: string } & (
+  | (Framing & { kind: 'video'; codec: ExportVideoCodec; shortEdge?: number; fps: number; quality: ExportQuality; audio: boolean;
+    clip?: string; scale?: number; preset?: string; sidecar?: 'srt' | 'vtt' })
+  | (Framing & { kind: 'gif'; width: number; fps: number })
+  | { kind: 'audio'; format: 'wav' | 'm4a' | 'mp3'; mix: boolean; stems: boolean }
+  | (Framing & { kind: 'stills'; format: 'png' | 'jpg'; shortEdge: number; at?: number[] })
+  | (Framing & { kind: 'poster'; format: 'png' | 'jpg'; shortEdge: number; at?: number })
+  | { kind: 'subtitles'; format: 'srt' | 'vtt' | 'txt' }
+  | (Framing & { kind: 'slides'; format: 'pptx' | 'pdf'; shortEdge: number; at?: number[] })
+  /* for an editing program: an XML and media folder; `media: 'link'` points at the sources where they are instead of cloning them */
+  | { kind: 'nle'; format?: 'xml' | 'fcpxml' | 'jianying' | 'capcut'; fps: number; audio: 'clips' | 'stems'; media?: 'copy' | 'link'; subtitles: boolean;
+      /* how the pages, rendered with their alpha, are written */
+      alpha?: NleAlpha }
+  /* the project itself: its work, and the parts of its .film asked; a zip of its folder, or the folder */
+  | { kind: 'project'; parts: ProjectPart[]; as: 'zip' | 'folder' }
+);
+
+/** What a project's export may take besides its work (studio/server/projects.mjs PROJECT_PARTS). */
+export type ProjectPart = 'history' | 'chat' | 'logs';
+export const PROJECT_PARTS: readonly ProjectPart[] = ['history', 'chat', 'logs'];
+
+/** How big a project's export is: its work, and each part it has (null: none), in bytes. */
+export type ProjectSizes = { work: number } & Record<ProjectPart, number | null>;
+
+export type ExportJobStatus = 'waiting' | 'running' | 'done' | 'failed' | 'cancelled';
+
+export interface ExportJob {
+  id: string;
+  project: string;
+  /** The project's name. */
+  name: string;
+  /** What the dialog called it ("YouTube", "ProRes 4444", "Full mix"…); empty for an export asked elsewhere. */
+  label: string;
+  kind: ExportRequest['kind'];
+  status: ExportJobStatus;
+  phase: 'preparing' | 'audio' | 'rendering' | 'encoding' | 'copying' | 'finishing' | null;
+  /** 0 to 1. */
+  progress: number;
+  framesDone: number;
+  framesTotal: number;
+  /** Frames per second drawn. */
+  rate: number;
+  etaMs: number | null;
+  encoder: string | null;
+  /** Absolute paths of the files made (one, or the mix and its stems). */
+  outputs: string[];
+  bytes: number | null;
+  /** Whether a transparent export lets anything through (sampled frames); null when not measured. */
+  alpha: { any: boolean } | null;
+  /** A draft's app's drafts folder that refused the write: the draft is in the exports folder instead. */
+  draftsRefused?: string;
+  /** The export stopped because the disk is full. */
+  diskFull?: boolean;
+  error?: string;
+  /** Cancel was asked and the export is stopping (still `running` until it has). */
+  cancelling?: boolean;
+  at: number;
+  startedAt: number | null;
+  finishedAt: number | null;
+}
+
+/** What this machine's ffmpeg encodes, for the choices that depend on it. */
+export interface ExportCapabilities {
+  h264: boolean;
+  hevc: boolean;
+  hevcAlpha: boolean;
+  vp9: boolean;
+  prores: boolean;
+  mp3: boolean;
+}
+
+const endpoint = (projectId: string) => `/api/projects/${encodeURIComponent(projectId)}/exports`;
+
+async function call<T>(url: string, init?: RequestInit & { json?: unknown }): Promise<T> {
+  const res = await fetch(url, {
+    ...init,
+    ...(init?.json !== undefined ? { headers: { 'content-type': 'application/json' }, body: JSON.stringify(init.json) } : {}),
+  });
+  const body = await res.json().catch(() => ({})) as { error?: string };
+  if (!res.ok) throw new Error(body.error || `Studio answered ${res.status}`);
+  return body as T;
+}
+
+/**
+ * The project's exports, where they go by default, what this machine encodes, how many subtitle cues the film has, and
+ * how big the project and its parts are.
+ */
+export function listExports(projectId: string): Promise<{ exports: ExportJob[]; folder: string; can: ExportCapabilities; drafts?: { jianying: boolean; capcut: boolean }; subtitles?: number; project?: ProjectSizes }> {
+  return call(endpoint(projectId), { cache: 'no-store' });
+}
+
+/** A video file's frame rate (`media?what=probe`); null when it has none or can't be read. */
+export async function probeFps(projectId: string, path: string): Promise<number | null> {
+  const res = await fetch(`/api/projects/${encodeURIComponent(projectId)}/media?what=probe&path=${encodeURIComponent(path)}`, { cache: 'no-store' });
+  if (!res.ok) return null;
+  const body = await res.json().catch(() => null) as { fps?: number } | null;
+  return typeof body?.fps === 'number' && body.fps > 0 ? body.fps : null;
+}
+
+/** Queue exports, all or none. `folder`: where to write them (absolute, or ~/…); missing = the default folder. */
+export async function startExports(projectId: string, jobs: readonly ExportRequest[], folder?: string): Promise<ExportJob[]> {
+  const body = await call<{ exports: ExportJob[] }>(endpoint(projectId), { method: 'POST', json: { jobs, ...(folder ? { folder } : {}) } });
+  return body.exports;
+}
+
+export async function cancelExport(projectId: string, jobId: string): Promise<void> {
+  await call(`${endpoint(projectId)}/${encodeURIComponent(jobId)}`, { method: 'DELETE' });
+}
+
+/** Show the export's file in the system's file manager. */
+export async function revealExport(projectId: string, jobId: string): Promise<void> {
+  await call(`${endpoint(projectId)}/${encodeURIComponent(jobId)}/reveal`, { method: 'POST', json: {} });
+}
+
+/** Open the export's file in the app the system opens it with. */
+export async function openExport(projectId: string, jobId: string): Promise<void> {
+  await call(`${endpoint(projectId)}/${encodeURIComponent(jobId)}/open`, { method: 'POST', json: {} });
+}
+
+export function jobIsActive(job: ExportJob): boolean {
+  return job.status === 'waiting' || job.status === 'running';
+}
+
+export function basenameOf(path: string): string {
+  return path.split(/[\\/]/).filter(Boolean).pop() ?? path;
+}
+
+export function formatBytes(n: number): string {
+  if (!Number.isFinite(n) || n <= 0) return '—';
+  if (n < 1024 * 1024) return `${Math.max(1, Math.round(n / 1024))} KB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(n < 10 * 1024 * 1024 ? 1 : 0)} MB`;
+  return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+export function formatDuration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  return h > 0
+    ? `${h}:${String(m).padStart(2, '0')}:${String(sec).padStart(2, '0')}`
+    : `${m}:${String(sec).padStart(2, '0')}`;
+}
+
+/**
+ * A moment or a length of the film in the export dialog: m:ss, with tenths where it is not a whole second (0:07.5),
+ * so a film of 7.5 s doesn't read as 0:08.
+ */
+export function formatFilmTime(ms: number): string {
+  const tenths = Math.max(0, Math.round(ms / 100));
+  const whole = formatDuration(Math.floor(tenths / 10) * 1000);
+  return tenths % 10 ? `${whole}.${tenths % 10}` : whole;
+}
+
+/**
+ * What the tray's head says once nothing runs: how the exports ended, in the person's words. `tone` picks its mark:
+ * a failure needs reading; all cancelled is neither good nor bad; anything made is done.
+ */
+export function endedHeadline(jobs: readonly ExportJob[], t: (key: string) => string): { tone: 'ok' | 'err' | 'muted'; text: string } {
+  const n = (status: ExportJobStatus) => jobs.filter((j) => j.status === status).length;
+  const done = n('done');
+  const cancelled = n('cancelled');
+  const failed = n('failed');
+  if (failed === jobs.length) return { tone: 'err', text: t(failed === 1 ? 'exportTray.failedOne' : 'exportTray.failedAll') };
+  if (cancelled === jobs.length) return { tone: 'muted', text: t(cancelled === 1 ? 'exportTray.cancelledOne' : 'exportTray.cancelledAll') };
+  if (done === jobs.length) return { tone: 'ok', text: t('exportTray.finished') };
+  const parts = [
+    done ? t('exportTray.countDone').replace('{n}', String(done)) : '',
+    cancelled ? t('exportTray.countCancelled').replace('{n}', String(cancelled)) : '',
+    failed ? t('exportTray.countFailed').replace('{n}', String(failed)) : '',
+  ].filter(Boolean);
+  return { tone: failed ? 'err' : done ? 'ok' : 'muted', text: parts.join(', ') };
+}