ossclip 0.1.18 → 0.1.20

package/editor-dist/assets/index-ChRVBVLj.css

@@ -0,0 +1 @@
+.ossclip-scroll-list{scrollbar-width:thin;scrollbar-color:#3a3a44 transparent}.ossclip-scroll-list::-webkit-scrollbar{width:8px}.ossclip-scroll-list::-webkit-scrollbar-track{background:transparent}.ossclip-scroll-list::-webkit-scrollbar-thumb{background:#3a3a44;border-radius:4px}.ossclip-picker-row{color:#c9c9d4;background:transparent;border:1px solid transparent}.ossclip-picker-row.is-workdir{color:#ededf2;background:#1a1a21;border-color:#2a2a33}.ossclip-picker-row:disabled{cursor:default;opacity:.5}.ossclip-picker-row:hover:not(:disabled){background:#1f1f28;border-color:#3a3a48}.ossclip-picker-row:focus{outline:none;background:#23232e;border-color:#8ab4f8}.ossclip-picker-row:active:not(:disabled){background:#2a2a36}

package/editor-dist/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ossclip editor</title>
-    <script type="module" crossorigin src="/assets/index-CdwzWN3j.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-C8IPo60X.css">
+    <script type="module" crossorigin src="/assets/index-B44I-xE4.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-ChRVBVLj.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Local-first CLI video producer: cuts silence and fillers, word-timed captions, face-aware framing, and LLM-planned code-rendered graphics — transcription and rendering never leave your machine",
   "type": "module",
   "license": "MIT",
@@ -36,9 +36,9 @@
     "commander": "^12.1.0",
     "tsx": "^4.19.0",
     "zod": "^3.25.76",
-    "@ossclip/core": "0.1.18",
-    "@ossclip/renderer": "0.1.18",
-    "@ossclip/scenes": "0.1.18"
+    "@ossclip/scenes": "0.1.20",
+    "@ossclip/renderer": "0.1.20",
+    "@ossclip/core": "0.1.20"
   },
   "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
   "bugs": {

package/src/analyse.ts

@@ -0,0 +1,101 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { z } from "zod/v4";
+import {
+  ProductionSchema,
+  buildFcpxmlMarkers,
+  type CleanupLevel,
+} from "@ossclip/core";
+import { produce } from "./produce";
+import type { PhaseTimings } from "./phase-timing";
+
+/**
+ * `ossclip analyse` (next-directions §2–3; design doc
+ * 2026-08-12-analyse-fcpxml-export-design.md): the analyser without the
+ * renderer. §140 measured the render at 85% of wall time on two machines —
+ * this command is the product of skipping it: the same pipeline up to the
+ * cut report (no LLM, no Remotion), plus an export file an editor's own NLE
+ * can review. Markers, not applied cuts, by design — see the exporter.
+ */
+
+/**
+ * zod enum, not a string: a typo'd `--format fcpxmll` must error naming the
+ * choice, never fall back to a default that silently writes the wrong file
+ * (CLAUDE.md's `--source-fit containn` rule, verbatim).
+ */
+export const ExportFormatSchema = z.enum(["fcpxml"]);
+export type ExportFormat = z.infer<typeof ExportFormatSchema>;
+
+/** Same shape as produce's `defaultOutPath`: beside the input, new extension. */
+export function defaultExportPath(input: string, format: ExportFormat): string {
+  return input.replace(/(\.[^.]+)?$/, `.${format}`);
+}
+
+export interface AnalyseOptions {
+  cleanup: CleanupLevel;
+  format: ExportFormat;
+  out?: string;
+  transcript?: string;
+  workdir?: string;
+  noiseDb?: number;
+  whisperModel?: string;
+  whisperLanguage?: string;
+  blooperMarker?: string;
+  collapseRetakes?: boolean;
+  sort?: "name" | "mtime";
+  sortExplicit?: boolean;
+}
+
+export interface AnalyseResult {
+  workdir: string;
+  outPath: string;
+  markerCount: number;
+  sourceDurationSec: number;
+  phaseTimings: PhaseTimings;
+}
+
+/**
+ * The I/O glue: run the existing no-render pipeline, read back the
+ * `production.json` it wrote, hand it to the pure exporter, write the file.
+ * The read-back goes through `ProductionSchema.parse` even though this very
+ * run just wrote it — the file is user-visible and hand-editable, and a
+ * truncated or tweaked one must error here, not export garbage markers.
+ */
+export async function runAnalyse(
+  inputArg: string,
+  opts: AnalyseOptions,
+): Promise<AnalyseResult> {
+  const result = await produce(inputArg, {
+    cleanup: opts.cleanup,
+    transcript: opts.transcript,
+    render: false,
+    mezzanine: false,
+    workdir: opts.workdir,
+    noiseDb: opts.noiseDb,
+    whisperModel: opts.whisperModel,
+    whisperLanguage: opts.whisperLanguage,
+    blooperMarker: opts.blooperMarker,
+    collapseRetakes: opts.collapseRetakes,
+    sort: opts.sort,
+    sortExplicit: opts.sortExplicit,
+    cover: false,
+  });
+  const production = ProductionSchema.parse(
+    JSON.parse(await readFile(join(result.workdir, "production.json"), "utf8")),
+  );
+  const xml = buildFcpxmlMarkers(production);
+  const markerCount = (production.cutlist ?? []).filter((s) => s.kind === "remove").length;
+  const outPath = resolve(opts.out ?? defaultExportPath(resolve(inputArg), opts.format));
+  await writeFile(outPath, xml);
+  console.log(
+    `✓ ${opts.format} → ${outPath} (${markerCount} marker${markerCount === 1 ? "" : "s"} — ` +
+      "import into Resolve/Premiere and review before cutting)",
+  );
+  return {
+    workdir: result.workdir,
+    outPath,
+    markerCount,
+    sourceDurationSec: result.sourceDurationSec,
+    phaseTimings: result.phaseTimings,
+  };
+}

package/src/caption-report.ts

@@ -0,0 +1,217 @@
+import {
+  applyCaptionEdits,
+  captionEditsToKeep,
+  isLegacyCaptionKey,
+  migrateCaptionKeys,
+  MIGRATION_SEARCH_RADIUS,
+} from "@ossclip/core";
+import type {
+  AppliedCaptionEdits,
+  CaptionEdit,
+  CaptionKeyMigration,
+  CaptionLine,
+  OverrideDoc,
+} from "@ossclip/core";
+
+/**
+ * What `produce` does with the user's retyped caption words, and what it says
+ * about the ones that did not land (§137).
+ *
+ * Pure, and in its own module rather than inline in `produce.ts`, for the
+ * house reason: this is a decision about the user's data (which edits are
+ * re-anchored, which are applied, and why the others were not) and a
+ * `produce()` run needs ffmpeg, a transcript and a workdir before it reaches
+ * any of it. `produce.ts` keeps the `console.log` and the file writes.
+ */
+
+/** One drop, as a console line. Three cases, and the caller must not merge them. */
+export function captionDropLine(drop: AppliedCaptionEdits["dropped"][number]): string {
+  // `found: null` used to be interpolated straight into the sentence, so a
+  // word the cut removed reported `the transcript now has "null"` — the one
+  // case §137 exists for, described as a JSON literal. The three cases carry
+  // genuinely different advice, so they get genuinely different sentences.
+  if (drop.reason === "duplicate-anchor") {
+    // NOT a stale edit: the edit almost certainly applied, to the FIRST word
+    // carrying this anchor. Two words share one source instant by design
+    // (captions.ts:44-50 — backfilled seam preimages and cut-clamped words),
+    // so this is a note about reach, not a failure.
+    return (
+      `  ⚠ caption edit "${drop.expected}" (${drop.key}): a second word shares that ` +
+      `source moment and was left as it is — only the first was retyped`
+    );
+  }
+  if (drop.found === null) {
+    // A key that is a POSITION, not a source anchor, never had a moment to
+    // lose — it is a pre-§137 doc the migration could not upgrade. Saying "the
+    // cut removed it" there sends the user to redo work that is sitting intact
+    // on screen (§137 Task 6 review, Important 2). Reachable whenever an edit
+    // reaches `applyCaptionEdits` without going through `migrateCaptionKeys`.
+    if (isLegacyCaptionKey(drop.key)) {
+      return (
+        `  ⚠ caption edit "${drop.expected}" (position ${drop.key}) not applied: it is keyed ` +
+        `by word POSITION, from a project saved before source anchors, and nothing ` +
+        `re-anchored it — open the project in the editor, or retype it there`
+      );
+    }
+    return (
+      `  ⚠ caption edit "${drop.expected}" (${drop.key}) dropped: no word starts at that ` +
+      `source moment any more — the cut removed the word it was typed over. ` +
+      `Retype it in the editor if you still want it.`
+    );
+  }
+  return (
+    `  ⚠ caption edit "${drop.expected}" (${drop.key}) dropped: the transcript now says ` +
+    `"${drop.found}" there`
+  );
+}
+
+/**
+ * How many stored edits actually landed.
+ *
+ * NOT `keys.length - dropped.length` (§137): `dropped` is not one entry per
+ * key. A `duplicate-anchor` entry is pushed for every EXTRA word carrying an
+ * anchor, so a single key can appear in `dropped` two or three times — and it
+ * may have applied anyway. The old subtraction therefore undercounted, and
+ * with enough duplicates went NEGATIVE, which the `> 0` guard then hid
+ * entirely: the run printed nothing at all about edits that had applied.
+ *
+ * The rule comes straight from `applyCaptionEdits`' own contract: a key is
+ * marked `seen` by the first word carrying it, and that word either applied
+ * the edit or was reported with `reason` ABSENT. So an edit landed exactly
+ * when nothing was reported for its key without a `reason`.
+ */
+export function appliedCaptionEditCount(
+  edits: Record<string, CaptionEdit>,
+  dropped: AppliedCaptionEdits["dropped"],
+): number {
+  const failed = new Set(dropped.filter((d) => d.reason === undefined).map((d) => d.key));
+  return Object.keys(edits).filter((key) => !failed.has(key)).length;
+}
+
+/**
+ * One console line for a legacy edit the migration would not place (§137).
+ *
+ * One sentence per CAUSE, like the editor's own notice: three of the four
+ * leave the word sitting right there in the transcript, and a single message
+ * blaming the cut would send the user hunting for it.
+ */
+export function captionMigrationLine(u: CaptionKeyMigration["unresolved"][number]): string {
+  const head = `  ⚠ caption edit "${u.was}" (${u.key}) could not be re-anchored`;
+  switch (u.reason) {
+    case "out-of-range":
+      // The word is ON SCREEN. Blaming the cut here (which the shared
+      // `not-found` sentence did until the final review) sends the user to
+      // retype something that is sitting intact in the transcript — and the
+      // edit is kept in the doc, so the next run against a different cut may
+      // place it without them doing anything at all.
+      // No promise that retyping fixes it, either: the word this found may
+      // itself be unanchorable (a pre-§137 render-props.json with nothing to
+      // backfill from), and "re-anchors it for good" would be a guarantee this
+      // line cannot make.
+      return `${head}: the word is still here, but more than ${MIGRATION_SEARCH_RADIUS} words from where the edit was stored, so it was left alone rather than applied to the wrong one — it is kept in overrides.json, so retype it in the editor if that is the word you meant`;
+    case "ambiguous":
+      return `${head}: more than one word says it here, so it was left alone rather than applied to the wrong one — retype the one you meant in the editor`;
+    case "unanchorable":
+      return `${head}: the word is here but carries no source timing to key on`;
+    case "collision":
+      return `${head}: two stored edits point at the same word — neither was applied, retype the one you meant in the editor`;
+    case "superseded":
+      return `${head}: a newer edit already covers that word — the newer one was kept`;
+    default:
+      return `${head}: no word says it any more — the cut or a re-plan removed it. Retype it in the editor if you still want it.`;
+  }
+}
+
+/**
+ * How many edits came out under a key they did not go in under — the ones the
+ * migration actually moved.
+ *
+ * NOT `Object.keys(migration.edits).length`, which is what the count in the log
+ * line was first written as: a MIXED doc (`{"0": …, "w6000": …}` over one word)
+ * keeps its already-source-keyed edit and retires the legacy one, so that
+ * count announced "1 caption edit re-anchored" about a key nothing had
+ * touched. A number the user can check against their own file has to be true
+ * for the same reason the drop lines do.
+ */
+export function reanchoredKeyCount(
+  before: Record<string, CaptionEdit>,
+  migration: CaptionKeyMigration,
+): number {
+  return Object.keys(migration.edits).filter((key) => !(key in before)).length;
+}
+
+export interface CaptionReconciliation {
+  /** The doc with its caption keys upgraded — what produce writes back. */
+  doc: OverrideDoc;
+  /** The caption lines with every edit that could be applied, applied. */
+  lines: CaptionLine[];
+  /**
+   * Whether the migration actually MOVED an edit onto a source anchor — the
+   * write-back gate, and the only thing that earns spending the `.bak`.
+   *
+   * It used to be `captionKeysMigrated`: true whenever anything was
+   * unresolved, including when nothing at all was placed. That is a write with
+   * no repair in it, and on the field workdir (`cutResult.changed` false,
+   * because the cut already carries `src`) it was a NEW write on a run that
+   * previously touched nothing — spending `overrides.json.bak`, the user's
+   * only surviving pre-cut save and the sole route back to the split half they
+   * deleted, on a copy of the already-damaged document (final review, Critical
+   * 2). A run that placed nothing has nothing to write and no business
+   * touching the `.bak`. Renamed as well as re-defined, because "keys changed"
+   * is no longer even true of it: a `superseded` retirement changes the keys
+   * and deliberately does not fire this.
+   */
+  reanchored: boolean;
+  /** Everything produce should print about this, in order. */
+  log: string[];
+}
+
+/**
+ * Migrate, then apply, then account for the difference — the whole caption
+ * half of a produce run, in one pure pass.
+ *
+ * MIGRATE FIRST, and against these same lines: `applyCaptionEdits` addresses
+ * words by source anchor, so a pre-§137 positional key matches nothing at all
+ * and every retype in an old project would be silently absent from the render
+ * (§137 Task 6 review, Critical 1). Nothing needs backfilling here — produce
+ * builds these lines itself, with a real `srcStart` on every word — which is
+ * exactly why this migration belongs in produce even though the same call in
+ * the edit server would be inert.
+ *
+ * WHAT IS APPLIED AND WHAT IS KEPT ARE DIFFERENT SETS, deliberately (final
+ * review, Critical 1). Only the edits the migration PLACED are applied — an
+ * unresolved key addresses no word, so handing it to `applyCaptionEdits` would
+ * buy nothing but a second, worse-worded report of the same edit. The doc
+ * written back keeps them anyway (`captionEditsToKeep`), because a run that
+ * cannot place an edit today is not a licence to delete it.
+ *
+ * The caller must hand a doc that has been through `OverrideDocSchema`
+ * (`produce.ts` parses it at the top of the run). On raw `JSON.parse` output a
+ * literal `"__proto__"` key would be assigned THROUGH rather than kept, and
+ * the migration would report nothing lost while losing it.
+ */
+export function reconcileCaptionEdits(
+  doc: OverrideDoc,
+  baseLines: readonly CaptionLine[],
+): CaptionReconciliation {
+  const log: string[] = [];
+  const migration = migrateCaptionKeys(doc.captions, baseLines);
+  // The MOVED count is both the log gate and the write gate. As a log gate:
+  // announcing "0 caption edit(s) re-anchored" above the lines saying why is
+  // noise on the one run where the user is reading carefully. As a write gate:
+  // see `CaptionReconciliation.reanchored` — a run that placed nothing must
+  // not spend the `.bak`.
+  const reanchored = reanchoredKeyCount(doc.captions, migration);
+  if (reanchored > 0) {
+    log.push(
+      `▸ ${reanchored} caption edit(s) re-anchored from word positions to source time (§137)`,
+    );
+  }
+  for (const u of migration.unresolved) log.push(captionMigrationLine(u));
+  const migrated = { ...doc, captions: captionEditsToKeep(doc.captions, migration) };
+  const { lines, dropped } = applyCaptionEdits(baseLines, migration.edits);
+  const live = appliedCaptionEditCount(migration.edits, dropped);
+  if (live > 0) log.push(`▸ ${live} caption word(s) retyped by the editor`);
+  for (const d of dropped) log.push(captionDropLine(d));
+  return { doc: migrated, lines, reanchored: reanchored > 0, log };
+}

package/src/edit.ts

@@ -259,9 +259,29 @@ export async function startEditServer(
             return send(200, { noWorkdir: true, recent: await readRecentProjects(opts.recentDir) });
           }
           const renderProps = JSON.parse(await readFile(propsPath(), "utf8"));
+          // Parsed, never cast — and that parse is also what makes the doc
+          // safe to migrate downstream: a literal `"__proto__"` caption key
+          // survives `JSON.parse` as an own property, and any later pass that
+          // rebuilds the record would assign through it instead of keeping it.
           const overrides = existsSync(overridesPath())
             ? OverrideDocSchema.parse(JSON.parse(await readFile(overridesPath(), "utf8")))
             : emptyOverrideDoc();
+          // §137 DECISION (Task 6): the pre-§137 caption-key migration does
+          // NOT run here. It resolves a positional key by finding the word it
+          // named and taking that word's source anchor — and these render
+          // props are served exactly as they sit on disk, where a pre-§137
+          // file's caption words have no `srcStart` at all. Every word would
+          // answer "no anchor", every edit would land in `unresolved`, and the
+          // migration would report total loss while doing nothing: a call that
+          // passes its own tests and is inert in production.
+          // Anchoring them here instead would mean a second copy of the "no
+          // usable map, no repair" rule (`anchorCaptionLines`, apps/editor) in
+          // this package — the CLI cannot import the editor's source, which it
+          // only ever ships as a built `editor-dist/` — and that rule is
+          // exactly the one §137 refuses to have two of. So the EDITOR owns
+          // the repair, at the one point that holds anchored lines and the doc
+          // at the same time (App.tsx's load path), and it loses no reach:
+          // this endpoint has exactly one consumer.
           return send(200, {
             renderProps,
             overrides,
@@ -450,6 +470,24 @@ export async function startEditServer(
           for await (const c of req) chunks.push(c as Buffer);
           const parsed = OverrideDocSchema.safeParse(JSON.parse(Buffer.concat(chunks).toString()));
           if (!parsed.success) return send(400, { error: parsed.error.message });
+          // NO `.bak` HERE, and that is a decision, not an omission (final
+          // review, Important 5). This write is safe without one only because
+          // it ROUND-TRIPS: whatever the editor loaded, it saves back, plus
+          // the change the user just made. §137 briefly broke that property —
+          // `migrateLoadedDoc` stripped the caption edits the migration could
+          // not place before `edits.load` (which also clears undo), so the
+          // first save after opening a legacy project deleted them
+          // permanently. The fix is in `migrateLoadedDoc`, which now keeps
+          // them, rather than here.
+          //
+          // Adding produce's `.bak` to this handler was the other option and
+          // is actively worse: `overrides.json.bak` is single-generation and
+          // SHARED with produce's write, so a routine ⌘S would spend the one
+          // the user's pre-cut save is sitting in — which on the §137 field
+          // workdir is the only artefact their deleted split half can ever be
+          // recovered from (`legacySplitId`). That is the review's own
+          // Critical 2 reintroduced through the editor.
+          //
           // Atomic: the producer may read this file at any moment, and a
           // half-written document would be worse than a stale one.
           const tmp = `${overridesPath()}.tmp`;

package/src/overrides-write.ts

@@ -0,0 +1,77 @@
+import { readFile, rename, writeFile } from "node:fs/promises";
+import type { OverrideDoc } from "@ossclip/core";
+
+/**
+ * The one sanctioned `overrides.json` write (PLAN 2026-08-04 Task 4), and the
+ * rule about when it may spend the `.bak`.
+ *
+ * Lifted out of `produce.ts` so the backup rule is testable at all: nothing in
+ * the repo invokes `produce()` (it needs ffmpeg, a transcript, a workdir and a
+ * render), and "the previous copy is still on disk, byte for byte" is a claim
+ * about a FILE — there is no pure form of it. `produce.ts` keeps the decision
+ * of WHETHER to write, the ordering relative to `render-props.json`, and the
+ * `console.log`.
+ */
+
+/**
+ * Replace `overrides.json`, optionally refreshing `overrides.json.bak` first.
+ *
+ * REFRESHING THE BACKUP IS NOT PART OF WRITING (final review round 2, Critical
+ * 2 residual). The `.bak` is single-generation, so every refresh SPENDS
+ * whatever it held, and the two writers have very different claims on it:
+ *
+ *  - A CUT re-anchoring rewrites absolute output-second VALUES all over the
+ *    doc — split times, pins, framing — from a frame the pipeline just
+ *    recomputed. That is unreadable in a diff and irreversible by hand, so the
+ *    copy it replaces is worth keeping and this is the write the `.bak` exists
+ *    for.
+ *  - A CAPTION-KEY migration differs from the copy on disk in caption KEYS
+ *    only, every one of which the run just printed by name, and (since
+ *    `captionEditsToKeep`) it deletes nothing. There is nothing in the old
+ *    copy worth recovering — while the `.bak` it would overwrite may be the
+ *    user's last PRE-CUT save, which on the §137 field workdir is the only
+ *    artefact holding `splits: [0.6]` and so the only route back to the split
+ *    half they deleted (`legacySplitId` can no longer derive `600` from a
+ *    re-anchored `splits: [0]`).
+ *
+ * The first cut of the §137 fix refreshed unconditionally, which meant the
+ * branch's own marquee scenario — three of that user's four retypes recovered
+ * — destroyed the evidence for the other half of the same bug. Gating the
+ * WRITE on work done (`produce.ts`) only removed the zero-repair case; this is
+ * the rest of it.
+ *
+ * Atomic via tmp+rename either way, matching the edit server's own
+ * `PUT /overrides` handler: the producer or a live editor session may read
+ * this file at any moment, and a half-written document would be worse than a
+ * stale one.
+ */
+export async function writeOverrideDoc(
+  overridesPath: string,
+  doc: OverrideDoc,
+  opts: { refreshBackup: boolean },
+): Promise<void> {
+  if (opts.refreshBackup) {
+    try {
+      const raw = await readFile(overridesPath, "utf8");
+      await writeFile(`${overridesPath}.bak`, raw);
+    } catch {
+      // Nothing on disk to back up (first cut ever applied here) — fine.
+    }
+  }
+  const tmp = `${overridesPath}.tmp`;
+  await writeFile(tmp, JSON.stringify(doc, null, 2));
+  await rename(tmp, overridesPath);
+}
+
+/**
+ * What the run says about that write. Pure, and separate from the write for
+ * the house reason — but also because the two halves of this sentence are the
+ * two halves of the decision above, and a line that claims a backup nobody
+ * took is how a user finds out too late (final review round 2).
+ */
+export function overridesWriteLine(cutChanged: boolean): string {
+  return cutChanged
+    ? "▸ overrides.json re-anchored to the new cut and saved (previous copy kept as .bak)"
+    : "▸ overrides.json re-anchored to source-time caption keys and saved " +
+        "(overrides.json.bak left alone — it may be an older, pre-cut copy worth more than this one)";
+}

package/src/phase-timing.ts

@@ -0,0 +1,140 @@
+/**
+ * Per-phase timing for `produce` (FINDINGS §140). "3 hours" was
+ * unattributed: `produce_completed` carried one `duration_ms` for the whole
+ * run, so nothing could say WHICH of the four candidate phases — whisper,
+ * LLM planning, the Remotion render, ffmpeg concat/normalize — the time went
+ * to, and each has a completely different fix if it dominates. Everything in
+ * this file is pure (clock injected, no I/O), per the house split; produce()
+ * owns the wrapping and program.ts owns the telemetry event.
+ */
+
+/**
+ * The four attributed phases, exactly the candidates from the §140 table.
+ * Everything ELSE produce does (audio extraction, silence/level analysis,
+ * content-rect and face sampling, the mezzanine) lands in the log line's
+ * `other` remainder rather than a fifth phase — the remainder is PRINTED, so
+ * if it ever dominates a real run it accuses itself and earns a phase then.
+ */
+export type ProducePhase = "transcribe" | "llm" | "render" | "ffmpeg";
+
+/** Milliseconds per phase; a phase that never ran is ABSENT, never 0. */
+export type PhaseTimings = Partial<Record<ProducePhase, number>>;
+
+/** Pipeline order — the log line reads like the run did. */
+const PHASE_ORDER: ProducePhase[] = ["transcribe", "llm", "render", "ffmpeg"];
+
+/**
+ * The log labels name the TOOL, not the internal phase id, because the §140
+ * table (and any hardware decision made from it) is about the tools:
+ * "whisper 12m" tells the user what to swap; "transcribe 12m" makes them ask.
+ */
+const PHASE_LABELS: Record<ProducePhase, string> = {
+  transcribe: "whisper",
+  llm: "llm",
+  render: "render",
+  ffmpeg: "ffmpeg",
+};
+
+export class PhaseTimer {
+  private readonly ms: PhaseTimings = {};
+  private readonly startedAt: number;
+
+  constructor(private readonly now: () => number = () => performance.now()) {
+    this.startedAt = this.now();
+  }
+
+  /**
+   * Accumulates — the llm phase is repair + window selection + scenes, and
+   * the ffmpeg phase is concat + loudnorm, so a phase is a SUM of calls, not
+   * one interval. Recorded in a `finally` so time spent is time recorded even
+   * when the phase throws: the throw aborts the run either way, but a future
+   * `produce_failed` that wants to say where the time went must not find the
+   * books cooked.
+   */
+  async time<T>(phase: ProducePhase, fn: () => Promise<T>): Promise<T> {
+    const t0 = this.now();
+    try {
+      return await fn();
+    } finally {
+      this.ms[phase] = (this.ms[phase] ?? 0) + (this.now() - t0);
+    }
+  }
+
+  timings(): PhaseTimings {
+    return { ...this.ms };
+  }
+
+  /** Wall clock since construction — the phases never sum to it; `other` is the gap. */
+  totalMs(): number {
+    return this.now() - this.startedAt;
+  }
+}
+
+/**
+ * Three scales, matched to what a human checks at each: one decimal under a
+ * minute (an 8.2s llm phase must not flatten to "8s" when comparing runs),
+ * zero-padded seconds under an hour ("1m03s", so it can't be misread as
+ * 1m30s), minutes only above it.
+ */
+export function formatPhaseDuration(ms: number): string {
+  const sec = ms / 1000;
+  if (sec < 60) return `${sec.toFixed(1)}s`;
+  if (sec < 3600) {
+    return `${Math.floor(sec / 60)}m${String(Math.floor(sec % 60)).padStart(2, "0")}s`;
+  }
+  return `${Math.floor(sec / 3600)}h${String(Math.floor((sec % 3600) / 60)).padStart(2, "0")}m`;
+}
+
+/**
+ * The run log's one-line breakdown, in the ▸ voice, real seconds — this is
+ * the user's own machine, so unlike telemetry there is nothing to bucket.
+ * Absent phases are omitted (a cached transcript is not a 0.0s whisper run),
+ * the remainder is printed as `other` so unattributed time stays visible,
+ * and a run with no measured phases prints only the total — an `other` at
+ * 100% would just restate it. The remainder clamps at zero: the phases and
+ * the total read the clock at different instants, and a -0.0s from that skew
+ * would read as a bug in the very line meant to build trust in the numbers.
+ */
+export function formatPhaseLine(timings: PhaseTimings, totalMs: number): string {
+  const measured = PHASE_ORDER.filter((p) => timings[p] !== undefined);
+  const total = `▸ time: total ${formatPhaseDuration(totalMs)}`;
+  if (measured.length === 0) return total;
+  const parts = measured.map((p) => `${PHASE_LABELS[p]} ${formatPhaseDuration(timings[p]!)}`);
+  const other = totalMs - measured.reduce((sum, p) => sum + timings[p]!, 0);
+  if (other > 0) parts.push(`other ${formatPhaseDuration(other)}`);
+  return `${total} — ${parts.join(" · ")}`;
+}
+
+/**
+ * Same idea as telemetry.ts's `durationBucket` — the exact seconds never
+ * leave the machine — but with sub-minute resolution, because the question
+ * this answers ("which phase dominates?") has phases that legitimately live
+ * in seconds: an llm plan at 8s and a render at 40 minutes both being ">1m"
+ * would erase the very comparison §140 exists to make.
+ */
+export function phaseDurationBucket(
+  seconds: number,
+): "<10s" | "10-60s" | "1-5m" | "5-15m" | ">15m" {
+  if (seconds < 10) return "<10s";
+  if (seconds <= 60) return "10-60s";
+  if (seconds <= 300) return "1-5m";
+  if (seconds <= 900) return "5-15m";
+  return ">15m";
+}
+
+/**
+ * The `produce_completed` props for the phases that ran: `<phase>_bucket`,
+ * bucketed, never raw milliseconds (§134 floor — a raw per-phase duration is
+ * even closer to fingerprinting a specific take than the total the floor
+ * already buckets). Keys are pinned against `assertSafeProps` in
+ * phase-timing.test.ts, since a spread into `telemetry.record` is invisible
+ * to telemetry.test.ts's source-text drift check.
+ */
+export function phaseBucketProps(timings: PhaseTimings): Record<string, string> {
+  const props: Record<string, string> = {};
+  for (const p of PHASE_ORDER) {
+    const ms = timings[p];
+    if (ms !== undefined) props[`${p}_bucket`] = phaseDurationBucket(ms / 1000);
+  }
+  return props;
+}