@ossclip/core 0.1.26 → 0.1.28

package/src/producer/fallback.ts

@@ -0,0 +1,91 @@
+import type { z } from "zod/v4";
+import { AgyError } from "./antigravity";
+import type { CallTier, LlmProvider } from "./provider";
+import type { LlmUsage } from "./usage";
+
+/**
+ * What a fallback announcement needs to say: who failed, who is answering
+ * instead, on which call, and (first line of) the failure's own sentence.
+ */
+export interface FallbackInfo {
+  from: string;
+  to: string;
+  schemaName: string;
+  detail: string;
+}
+
+/**
+ * Falls back to a second provider when — and only when — the primary TIMES
+ * OUT (2026-08-22, FINDINGS §143). agy is healthy at small scale and then
+ * hangs persistently on the real beat-sheet call: measured 10-minute
+ * `--print-timeout` expiries on an 11-minute take while claude-cli planned
+ * the same video without complaint — and auto-detection picks agy whenever
+ * the CLI is on PATH, so without this every Antigravity user's first real
+ * produce dies after the wait.
+ *
+ * Only the `timeout` class falls back: auth and bad-model failures are
+ * deterministic and must keep failing fast with their own guidance —
+ * answering them from another provider would paper over a config error the
+ * user needs to see. Exactly ONE fallback attempt, no loop: the fallback
+ * provider runs its own internal retries.
+ *
+ * `name` stays the primary's — the detection line already announced it — and
+ * the truth of who actually answered lives in `usage` (each record keeps the
+ * provider that really made the call) plus the caller's out-loud `onFallback`
+ * line. Silent substitution would be worse than the hang.
+ */
+export class FallbackProvider implements LlmProvider {
+  readonly name: string;
+  private readonly records: LlmUsage[] = [];
+
+  constructor(
+    private readonly primary: LlmProvider,
+    private readonly fallback: LlmProvider,
+    private readonly onFallback?: (info: FallbackInfo) => void,
+  ) {
+    this.name = primary.name;
+  }
+
+  /** Merged in call order — the sub-providers each keep their own log. */
+  get usage(): readonly LlmUsage[] {
+    return this.records;
+  }
+
+  async complete<T>(req: {
+    system: string;
+    user: string;
+    schema: z.ZodType<T>;
+    schemaName: string;
+    maxTokens?: number;
+    tier?: CallTier;
+  }): Promise<T> {
+    const beforePrimary = this.primary.usage.length;
+    const beforeFallback = this.fallback.usage.length;
+    try {
+      try {
+        return await this.primary.complete(req);
+      } catch (err) {
+        // Branch on the class as DATA — AgyError carries it precisely so a
+        // fallback decorator never re-parses human-facing prose
+        // (antigravity.ts). Everything that is not an agy timeout rethrows.
+        if (!(err instanceof AgyError) || err.failureClass !== "timeout") throw err;
+        this.onFallback?.({
+          from: this.primary.name,
+          to: this.fallback.name,
+          schemaName: req.schemaName,
+          // First line only: agyFailureMessage is multi-line guidance, and
+          // the announcement needs the sentence, not the manual.
+          detail: err.message.split("\n")[0]!.trim(),
+        });
+        return await this.fallback.complete(req);
+      }
+    } finally {
+      // Drain whatever BOTH sub-providers logged, including for calls that
+      // threw — a failed attempt still spent the tokens (tiered.ts, §37).
+      // Each record keeps the provider that really made the call, which is
+      // the attribution the cache keys and the usage report depend on.
+      this.records.push(...this.primary.usage.slice(beforePrimary));
+      this.records.push(...this.fallback.usage.slice(beforeFallback));
+    }
+  }
+}

package/src/producer/index.ts

@@ -2,11 +2,12 @@ import type { Transcript } from "../schema";
 import type { Scene, SceneComponentId } from "../scene-schema";
 import type { LlmProvider, ProviderName } from "./provider";
 import { AnthropicProvider, DEFAULT_CLAUDE_MODEL } from "./anthropic";
-import { AntigravityProvider } from "./antigravity";
+import { AntigravityProvider, type LlmEffort } from "./antigravity";
 import { ClaudeCliProvider } from "./claude-cli";
 import { GeminiProvider, DEFAULT_GEMINI_MODEL } from "./gemini";
 import { MockProvider } from "./mock";
 import { TieredProvider } from "./tiered";
+import { FallbackProvider, type FallbackInfo } from "./fallback";
 import {
   generateBeatSheet,
   normalizeBeatSheet,
@@ -29,13 +30,22 @@ export * from "./youtube";
 export * from "./scene-props";
 export * from "./repair";
 export { AnthropicProvider, DEFAULT_CLAUDE_MODEL } from "./anthropic";
-export { AntigravityProvider } from "./antigravity";
+export { AntigravityProvider, type LlmEffort } from "./antigravity";
 export { ClaudeCliProvider } from "./claude-cli";
 export { GeminiProvider, DEFAULT_GEMINI_MODEL } from "./gemini";
 export { MockProvider } from "./mock";
 export { TieredProvider } from "./tiered";
+export { FallbackProvider, type FallbackInfo } from "./fallback";
 
-export function createProvider(name: ProviderName, model?: string): LlmProvider {
+export function createProvider(
+  name: ProviderName,
+  model?: string,
+  // A trailing bag, not a third positional per knob: every existing
+  // (name, model) call site keeps compiling. Only antigravity reads `effort`
+  // today (§143) — the other providers have no such flag, and inventing a
+  // mapping for them would be a coercion of intent.
+  opts: { effort?: LlmEffort } = {},
+): LlmProvider {
   switch (name) {
     case "claude":
       return new AnthropicProvider(model ?? DEFAULT_CLAUDE_MODEL);
@@ -48,7 +58,7 @@ export function createProvider(name: ProviderName, model?: string): LlmProvider
       // Rides agy's cached subscription sign-in. No default model on purpose:
       // the editorial tier runs whatever the user configured agy itself to
       // use (FINDINGS §132, antigravity provider).
-      return new AntigravityProvider(model);
+      return new AntigravityProvider(model, undefined, { effort: opts.effort });
     case "mock":
       return new MockProvider();
   }
@@ -80,6 +90,26 @@ export interface TieringOptions {
    * tiering and sends everything to the editorial model.
    */
   fastModel?: string;
+  /**
+   * Provider to fall back to when the editorial call TIMES OUT (2026-08-22,
+   * FINDINGS §143). Honored only when the primary is antigravity — the one
+   * provider measured to hang on the real beat-sheet call. See
+   * `fallbackProviderName` for who is eligible.
+   */
+  fallback?: ProviderName;
+  /**
+   * Fired once, before the fallback call — the caller announces it out loud.
+   * Silent substitution is the failure mode the fallback exists to avoid.
+   */
+  onFallback?: (info: FallbackInfo) => void;
+  /**
+   * `agy --effort` for the EDITORIAL antigravity call only (§143: exposed
+   * after the hang incident — the knob existed and we passed nothing). The
+   * mechanical tier keeps agy's default (its small calls never hung), and the
+   * §143 fallback never sees it — it is a different provider, and the
+   * primary's effort level means nothing to it.
+   */
+  effort?: LlmEffort;
 }
 
 /**
@@ -91,7 +121,16 @@ export function createTieredProvider(
   name: ProviderName,
   opts: TieringOptions = {},
 ): LlmProvider {
-  const editorial = createProvider(name, opts.model);
+  // The §143 effort knob rides the editorial call only — see TieringOptions.
+  let editorial = createProvider(name, opts.model, { effort: opts.effort });
+  // Timeout fallback (2026-08-22, FINDINGS §143): only the editorial tier
+  // wraps — the beat-sheet call is the one measured to outrun agy's print
+  // timeout; mechanical calls are small enough to finish. The fallback gets
+  // NO model override: the primary's model name means nothing to a different
+  // provider, so the fallback runs its own default.
+  if (name === "antigravity" && opts.fallback) {
+    editorial = new FallbackProvider(editorial, createProvider(opts.fallback), opts.onFallback);
+  }
   const fast = opts.fastModel === "same" ? undefined : opts.fastModel ?? DEFAULT_FAST_MODEL[name];
   if (!fast || fast === opts.model) return editorial;
   return new TieredProvider(editorial, createProvider(name, fast));
@@ -132,6 +171,27 @@ export function defaultProviderName(
   return "claude-cli";
 }
 
+/**
+ * Where a timed-out antigravity run falls back to (2026-08-22, FINDINGS
+ * §143). Only antigravity gets one: it is the sole provider measured to hang
+ * persistently on the real beat-sheet call, and handing every provider a
+ * second choice would turn one measured incident into a general substitution
+ * policy. The order is `defaultProviderName`'s with agy removed — a logged-in
+ * claude CLI beats the gemini key for the same §132 subscription-first
+ * reasons — and the `hasBin` default of `() => false` keeps this pure the
+ * same way: callers that can see a filesystem inject a real checker.
+ */
+export function fallbackProviderName(
+  primary: ProviderName,
+  env: NodeJS.ProcessEnv = process.env,
+  hasBin: (bin: string) => boolean = () => false,
+): ProviderName | undefined {
+  if (primary !== "antigravity") return undefined;
+  if (hasBin(env.OSSCLIP_CLAUDE_BIN ?? "claude")) return "claude-cli";
+  if (env.GEMINI_API_KEY) return "gemini";
+  return undefined;
+}
+
 export interface ProduceScenesResult {
   beatSheet: BeatSheet;
   beatIssues: BeatsValidationIssue[];

package/src/producer/usage.ts

@@ -45,6 +45,14 @@ export interface LlmUsage {
   billed: boolean;
   /** Wall-clock milliseconds, so a slow call is visible beside a costly one. */
   ms?: number;
+  /**
+   * True when this ATTEMPT did not produce the artifact (a timed-out or
+   * errored call, §143). The cost is real and stays in every usage report —
+   * the flag exists so ATTRIBUTION can skip it: a production.json stamp that
+   * listed the failed attempt's placeholder model read "planned by
+   * claude-cli (antigravity-default)" after a fallback run (2026-08-22).
+   */
+  failed?: boolean;
 }
 
 export interface ModelPrice {
@@ -288,6 +296,20 @@ export function formatUsageReport(
   if (records.length === 0) return "";
   const t = summarizeUsage(records, pricing);
   const first = records[0]!;
+  // After a §143 timeout fallback (2026-08-22) the records genuinely span two
+  // providers, and a header naming only records[0]'s would credit the whole
+  // run to the one that failed the editorial call. First-seen order joined
+  // " → " says who handed off to whom; the model suffix drops in that case
+  // because one model name would be attributed to calls another model made.
+  // Single-provider runs render byte-identically to before.
+  const providers: string[] = [];
+  for (const r of records) {
+    if (!providers.includes(r.provider)) providers.push(r.provider);
+  }
+  const who =
+    providers.length > 1
+      ? providers.join(" → ")
+      : `${first.provider}${first.model ? ` · ${first.model}` : ""}`;
   // A column of $0.0000 says nothing; an offline run's cost column is a dash.
   const free = t.allUnbilled && t.equivalentUsd === 0;
   const money = (v: number | null): string => (free ? "—" : v === null ? "?" : usd(v));
@@ -326,7 +348,7 @@ export function formatUsageReport(
     notes.push("  Prices are the built-in per-family assumption; override in ~/.ossclip/config.json.");
   }
   return (
-    `\nllm usage (${first.provider}${first.model ? ` · ${first.model}` : ""}` +
+    `\nllm usage (${who}` +
     `${t.ms > 0 ? `, ${secs(t.ms)}` : ""}):\n` +
     rows.join("\n") +
     "\n" +
@@ -387,6 +409,9 @@ function modelsOfLog(log: Pick<UsageLog, "runs" | "records">): string[] {
   }
   const seen: string[] = [];
   for (const r of log.records) {
+    // Failed attempts never contribute a model (§143) — same rule as the
+    // per-run list below.
+    if (r.failed) continue;
     if (r.model && !seen.includes(r.model)) seen.push(r.model);
   }
   return seen;
@@ -404,6 +429,11 @@ export function appendUsageRun(
   const cached = records.length === 0;
   const models: string[] = [];
   for (const r of records) {
+    // A run's model list answers "who made this", not "who was asked" — a
+    // failed attempt's model (the timed-out agy placeholder, §143) stays in
+    // the records and every cost report, but never in the attribution list a
+    // cached run inherits or the production stamp copies.
+    if (r.failed) continue;
     if (r.model && !models.includes(r.model)) models.push(r.model);
   }
   // A cached run inherits the models it is REUSING the output of, exactly as

package/src/recut.ts

@@ -25,8 +25,13 @@ export interface RecutRemap {
  * caption/overlay boundaries, so a value pushed onto a cut lands exactly
  * where the timeline's own dead-region rendering shows the cut's edge.
  * `label` is only for the report string — it carries no behavior.
+ *
+ * Exported since cut review step 4: `retimeForPreview` (retime-preview.ts)
+ * moves every output-timed render prop through THIS function so the editor's
+ * live post-veto preview and produce's own re-anchoring can never disagree
+ * about what "the same moment on the new clock" means.
  */
-function remapPoint(
+export function remapPoint(
   label: string,
   t: number,
   oldMap: TimeMap,

package/src/retime-preview.ts

@@ -0,0 +1,331 @@
+/**
+ * The editor's live post-veto preview (cut review step 4): when the user
+ * declines a removal produce proposed, the preview's own timeline is re-cut
+ * so the player actually PLAYS the revived material, immediately, instead of
+ * marking a seam that only the next render honours.
+ *
+ * Cleanup vetoes ONLY. User `cuts[]` stay marked-not-applied, exactly the
+ * step-3 posture, for two reasons that are not the retired "no client-side
+ * TimeMap" one:
+ *  - produce alone resolves a fresh cut's `src` (the `cuts[].src` schema
+ *    contract, overrides.ts) — the editor must never apply a cut whose
+ *    source range only produce can resolve;
+ *  - a veto RESTORES content the mezzanine already has, so the editor can
+ *    honestly play it; a cut REMOVES content, and the struck band already
+ *    communicates that honestly.
+ *
+ * Pure and browser-safe by construction (the cover-headline.ts split): this
+ * module's whole import graph — cutlist, recut, timemap, and types — has
+ * zero node built-ins, so it rides `@ossclip/core/browser` into the editor
+ * bundle, and every function here is testable without a TTY or a filesystem.
+ */
+
+import type { CaptionLine } from "./captions";
+import { applyCleanupChoices, type CleanupChoices } from "./cutlist";
+import { remapPoint, subtractRangesFromCutlist, type UserCut } from "./recut";
+import type { SceneCue } from "./scene-schema";
+import type { Segment } from "./schema";
+import { mapFromKeptSpans, mapsClose, TimeMap, type KeptSpan } from "./timemap";
+import type { ZoomSegment } from "./zoom";
+
+/** `applyUserCuts`'s EPS — a JSON round-trip plus TimeMap arithmetic is
+ * noise, a real veto is never under a millisecond. */
+const EPS = 1e-6;
+
+/** Both clocks the retime needs: the one the current render-props are timed
+ * against, and the one the user's cleanup choices produce. */
+export interface LivePreviewClocks {
+  oldMap: TimeMap;
+  newMap: TimeMap;
+}
+
+/**
+ * Whether the current cleanup choices change the timeline at all — and the
+ * two clocks to retime through when they do. `null` is the identity signal:
+ * the caller must hand the props through UNTOUCHED (the regression anchor —
+ * a doc with no live veto must leave the preview byte-identical to today's).
+ *
+ * The new clock is produce's own sequence, same functions, same order:
+ * `applyCleanupChoices(proposal, choices)` then user cuts subtract from the
+ * result (`subtractRangesFromCutlist`), so a user cut drawn over a vetoed
+ * pause still cuts here exactly as it does in produce. Only cuts whose `src`
+ * is already resolved subtract — a fresh cut's source range is produce's
+ * alone to resolve (`resolveCutSourceRanges` needs the prior render-props
+ * frame), and that cut is still marked-not-applied on the timeline anyway.
+ * Skipping the subtraction entirely would be worse than incomplete: every
+ * ALREADY-APPLIED cut (src resolved by a past produce, absent from
+ * `oldSpans`) would silently come back the moment any veto went live.
+ *
+ * `null` on any degenerate input — no proposal, no old spans, choices with
+ * no actual veto — and on a proposal `TimeMap`'s constructor rejects (a
+ * hand-mangled production.json): the preview degrades to step 3's honest
+ * marks-rather-than-applies, never a crash, the same lenient posture as
+ * GET /api/cleanup itself.
+ */
+export function livePreviewMap(
+  proposal: readonly Segment[],
+  choices: CleanupChoices | undefined,
+  cuts: readonly UserCut[],
+  oldSpans: readonly KeptSpan[],
+): LivePreviewClocks | null {
+  // "Non-empty" means a veto actually present — a `reasons` map of tolerated
+  // `true` entries restates the default (the schema comment) and must take
+  // the cheap exact exit, not a float comparison of two equal maps.
+  const hasVeto =
+    Object.values(choices?.reasons ?? {}).some((v) => v === false) ||
+    (choices?.kept?.length ?? 0) > 0;
+  if (!hasVeto) return null;
+  if (proposal.length === 0 || oldSpans.length === 0) return null;
+  try {
+    const rekept = applyCleanupChoices(proposal, choices);
+    const ranges = cuts.flatMap((c) =>
+      c.src && c.src.endSec > c.src.startSec
+        ? [{ start: c.src.startSec, end: c.src.endSec }]
+        : [],
+    );
+    const newMap = new TimeMap(subtractRangesFromCutlist(rekept, ranges));
+    const oldMap = mapFromKeptSpans(oldSpans);
+    // Choices that change nothing (a veto already baked into the last
+    // produce's spans, a kept range overlapping no removal) are identity.
+    if (mapsClose(oldMap, newMap, EPS)) return null;
+    return { oldMap, newMap };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The two clocks as POINT mappers, one per direction. `retimeForPreview`
+ * below moves the player's PROPS onto the new clock in one batch, but the
+ * editor also has surfaces that read or write a SINGLE instant at a gesture
+ * — the transcript's click-to-seek, the timeline's ghost bands, the cover
+ * panel's playhead — and each of those needs the same old-output → source →
+ * new-output walk as a plain function it can be handed without knowing the
+ * recut machinery behind it.
+ */
+export interface PreviewClockMappers {
+  /** OLD-clock output seconds (the last render's own timeline — what the
+   * render props, the ghost cues and the pre-retime caption lines are timed
+   * in) → the clock the player is actually on. Exact for every live veto:
+   * vetoes only ever ADD time back, so every old moment survives on the new
+   * clock (`retimeForPreview`'s direction argument); the clamp behind it
+   * only fires for the retracted-veto shape the retime already reports. */
+  toLive: (sec: number) => number;
+  /** The reverse: the player's clock → the last render's own output seconds.
+   * A live moment inside REVIVED material has no old-clock preimage at all —
+   * the rendered mp4 never contained that frame — so it clamps to the
+   * nearest kept edge (`toOutputClamped`'s documented role), the closest
+   * moment the old clock can honestly name. */
+  fromLive: (sec: number) => number;
+  /** Whether a live instant EXISTS on the old clock at all — false exactly
+   * when `fromLive` would have to clamp: the moment sits inside REVIVED
+   * material (a vetoed removal the last render cut away). The WRITE-direction
+   * guard (the follow-up to `fromLive`'s read direction): the doc's own time
+   * slots speak the OLD clock (`splits[].at` per SplitSchema, a fresh cut's
+   * `startSec`/`endSec` per the `cuts` schema comment — overrides.ts), and a
+   * writer facing a moment this answers false for must refuse OUT LOUD
+   * rather than let the clamp silently relocate the user's gesture to the
+   * seam — the recut.ts "reported, never silently dropped" rule, applied
+   * before the write instead of after. Asked as its own question, not an ad
+   * hoc float comparison of `toLive(fromLive(sec))` against `sec` at some
+   * caller-invented tolerance. An instant exactly AT a seam counts as HAVING
+   * a preimage: `toOutput`'s containment is inclusive of both span edges
+   * (timemap.ts), so the seam moment is one the last render still contained.
+   * Always true for the identity pair — no veto, nothing revived. */
+  hasOldClockPreimage: (sec: number) => boolean;
+}
+
+/**
+ * The mappers for the current live re-cut — or the IDENTITY pair when there
+ * is none (`clocks === null`, `livePreviewMap`'s own identity signal). The
+ * identity is literally `(sec) => sec`, so a consumer's no-veto path computes
+ * bit-identical values to what it computed before the mapping existed — the
+ * same regression anchor the `live` memo's null branch holds to.
+ */
+export function previewClockMappers(clocks: LivePreviewClocks | null): PreviewClockMappers {
+  if (clocks === null) {
+    const identity = (sec: number): number => sec;
+    return { toLive: identity, fromLive: identity, hasOldClockPreimage: () => true };
+  }
+  const { oldMap, newMap } = clocks;
+  return {
+    toLive: (sec) => {
+      const src = oldMap.toSource(sec);
+      return newMap.toOutput(src) ?? newMap.toOutputClamped(src);
+    },
+    fromLive: (sec) => {
+      const src = newMap.toSource(sec);
+      return oldMap.toOutput(src) ?? oldMap.toOutputClamped(src);
+    },
+    // `fromLive`'s exact half, asked as a question: `toOutput` is null
+    // precisely when the source instant fell in a region the old map removed
+    // — i.e. the live moment is inside revived material (its own doc comment
+    // above pins the inclusive-seam semantics).
+    hasOldClockPreimage: (sec) => oldMap.toOutput(newMap.toSource(sec)) !== null,
+  };
+}
+
+/** `cutRangeToOldClock`'s verdict on a live-clock window headed for a doc
+ * `cuts[]` slot. `exact`/`shrunk` carry OLD-clock seconds ready to store;
+ * `shrunk` also carries a report (the `remapPoint` posture — a moved value
+ * says so) for the caller's feedback channel; `degenerate` means the window
+ * has NO old-clock extent at all and the write must be refused out loud. */
+export type OldClockCutRange =
+  | { kind: "exact"; startSec: number; endSec: number }
+  | { kind: "shrunk"; startSec: number; endSec: number; report: string }
+  | { kind: "degenerate" };
+
+/**
+ * Convert a cut gesture's LIVE-clock window into the OLD-clock window the
+ * doc's `cuts[]` slots speak (the schema comment on `OverrideDocSchema.cuts`:
+ * a fresh cut's `startSec`/`endSec` are drawn against the LAST render-props'
+ * frame — produce resolves `src` by mapping them through the PRIOR TimeMap,
+ * so a new-clock number stored there lands the cut the revived seconds off).
+ *
+ * Endpoints inside revived material clamp to the nearest kept edge
+ * (`fromLive`'s doc): when only ONE edge clamps the range SHRINKS there and
+ * the cut proceeds on what the old clock can express — the source range
+ * produce resolves from the shrunk window still spans the revived material
+ * BETWEEN the endpoints (a contiguous source interval), so only the revived
+ * sliver past the clamped edge is lost, and the report says so. When the
+ * whole window collapses to one point — both endpoints inside one revived
+ * region, or the window exactly covering it seam to seam (each seam HAS a
+ * preimage, but the same one twice) — there is nothing left to cut and the
+ * verdict is `degenerate`: refuse, the ⌘B-split posture, never a silent
+ * zero-length entry. Checked on the mapped WIDTH first, before the preimage
+ * question, for exactly that seam-to-seam case. The module `EPS`, not 0: the
+ * mapped ends ride TimeMap arithmetic, and a real cut is never under a
+ * microsecond.
+ *
+ * Identity mappers (no live veto) always answer `exact` with the input
+ * values untouched — the no-veto regression anchor.
+ */
+export function cutRangeToOldClock(
+  mappers: Pick<PreviewClockMappers, "fromLive" | "hasOldClockPreimage">,
+  startSec: number,
+  endSec: number,
+): OldClockCutRange {
+  const mappedStart = mappers.fromLive(startSec);
+  const mappedEnd = mappers.fromLive(endSec);
+  if (mappedEnd - mappedStart < EPS) return { kind: "degenerate" };
+  if (mappers.hasOldClockPreimage(startSec) && mappers.hasOldClockPreimage(endSec)) {
+    return { kind: "exact", startSec: mappedStart, endSec: mappedEnd };
+  }
+  return {
+    kind: "shrunk",
+    startSec: mappedStart,
+    endSec: mappedEnd,
+    report:
+      `cut ${startSec.toFixed(3)}s–${endSec.toFixed(3)}s trimmed to the last render's ` +
+      `${mappedStart.toFixed(3)}s–${mappedEnd.toFixed(3)}s — the revived material at its ` +
+      `edge isn't in the last render yet`,
+  };
+}
+
+/** The output-timed subset of the render props the retime reads. Structural
+ * on purpose — the renderer's `ProductionCompProps` satisfies it without
+ * core importing the renderer package. */
+export interface RetimeablePreviewProps {
+  outputDurationSec: number;
+  captionLines: readonly CaptionLine[];
+  sceneCues: readonly SceneCue[];
+  zoomPlan?: readonly ZoomSegment[];
+  ctaWindow?: { startSec: number; endSec: number };
+  sourceTextRegions?: readonly { y: number; h: number; startSec: number; endSec: number }[];
+}
+
+/** Exactly the fields `retimeForPreview` re-timed — the caller spreads them
+ * over the full props (`{ ...props, ...fields }`), so fields this function
+ * never touches (theme, face, framingTimeline — all source-timed or
+ * timeless) cannot be accidentally rewritten here. */
+export interface RetimedPreviewFields {
+  spans: KeptSpan[];
+  outputDurationSec: number;
+  captionLines: CaptionLine[];
+  sceneCues: SceneCue[];
+  zoomPlan?: ZoomSegment[];
+  ctaWindow?: { startSec: number; endSec: number };
+  sourceTextRegions?: { y: number; h: number; startSec: number; endSec: number }[];
+  punch: { scale: number; allowed: boolean[] };
+}
+
+export interface RetimedPreview {
+  fields: RetimedPreviewFields;
+  reports: string[];
+}
+
+/**
+ * Re-time every output-timed render prop from `oldMap`'s clock onto
+ * `newMap`'s: old-output → source → new-output, `remapPoint`'s exact
+ * algorithm — the same one produce re-anchors splits and pins with.
+ *
+ * Vetoes only ever ADD time back (a removal becomes a keep), so every moment
+ * the old clock could express survives on the new one and maps exactly. The
+ * clamped fallback still stands behind each point (`toOutputClamped`'s
+ * documented role) for the one direction that can remove time: the old spans
+ * carrying a veto the doc no longer holds — a moment inside it snaps to the
+ * nearest kept edge and is reported, never silently dropped.
+ *
+ * Word `srcStart` is already SOURCE time (§137's recut-immune key) and is
+ * carried untouched. `punch` comes back provably inert — `{scale: 1,
+ * allowed: []}`: `punchScalesFor` (punch-plan.ts) renders an allowed span's
+ * punched turn at `scale`, and scale 1 is no visible punch; an empty mask
+ * reads all-allowed, which is exactly what makes scale the only knob. It
+ * cannot pass through: `punch.allowed` is INDEXED PER SPAN, the new span
+ * list has different indices, and the face-only verdict that built the mask
+ * cannot be recomputed client-side — a punch on the wrong span (a screen
+ * share sliding) is worse than no punch for the preview's duration. The
+ * zoom plan, by contrast, IS remapped: its segments are pure output time
+ * (`zoomScaleAt` consults nothing but `startSec`/`endSec`), and a revived
+ * stretch simply falls outside every segment, which `zoomScaleAt` already
+ * renders as the static camera.
+ */
+export function retimeForPreview(
+  props: RetimeablePreviewProps,
+  oldMap: TimeMap,
+  newMap: TimeMap,
+): RetimedPreview {
+  const reports: string[] = [];
+  const at = (label: string, t: number): number => remapPoint(label, t, oldMap, newMap, reports);
+  const fields: RetimedPreviewFields = {
+    spans: newMap.spans.map((s) => ({ ...s })),
+    outputDurationSec: newMap.outputDuration,
+    captionLines: props.captionLines.map((line, i) => ({
+      ...line,
+      start: at(`caption line ${i + 1} start`, line.start),
+      end: at(`caption line ${i + 1} end`, line.end),
+      words: line.words.map((w) => ({
+        ...w,
+        start: at(`caption word "${w.text}" start`, w.start),
+        end: at(`caption word "${w.text}" end`, w.end),
+      })),
+    })),
+    sceneCues: props.sceneCues.map((c) => ({
+      ...c,
+      startSec: at(`scene "${c.id}" start`, c.startSec),
+      endSec: at(`scene "${c.id}" end`, c.endSec),
+    })),
+    punch: { scale: 1, allowed: [] },
+  };
+  if (props.zoomPlan) {
+    fields.zoomPlan = props.zoomPlan.map((seg, i) => ({
+      ...seg,
+      startSec: at(`zoom segment ${i + 1} start`, seg.startSec),
+      endSec: at(`zoom segment ${i + 1} end`, seg.endSec),
+    }));
+  }
+  if (props.ctaWindow) {
+    fields.ctaWindow = {
+      startSec: at("CTA window start", props.ctaWindow.startSec),
+      endSec: at("CTA window end", props.ctaWindow.endSec),
+    };
+  }
+  if (props.sourceTextRegions) {
+    fields.sourceTextRegions = props.sourceTextRegions.map((r, i) => ({
+      ...r,
+      startSec: at(`source text region ${i + 1} start`, r.startSec),
+      endSec: at(`source text region ${i + 1} end`, r.endSec),
+    }));
+  }
+  return { fields, reports };
+}

package/src/schema.ts

@@ -147,7 +147,26 @@ export const ProductionSchema = z.object({
     )
     .optional(),
   analysis: AnalysisSchema.optional(),
+  /**
+   * What this run ACTUALLY cut — post cleanup-choices, post user cuts. Every
+   * consumer that treats the cutlist as the applied truth (`formatCutReport`,
+   * the four NLE exporters, `analyze`'s marker count) reads this one, which
+   * is why it stays the resolved list rather than the proposal: recording the
+   * proposal here would make each of them re-apply the choices or lie.
+   */
   cutlist: z.array(SegmentSchema).optional(),
+  /**
+   * The automatic PROPOSAL (cut review step 3) — `buildCutlist`'s output
+   * before `applyCleanupChoices` vetoes and before user cuts subtract. Kept
+   * alongside because the resolution is lossy: a vetoed removal merges into
+   * a plain keep, so `cutlist` alone cannot tell the editor which categories
+   * the user declined — its checkboxes and seams re-derive the veto state
+   * from THIS list + `overrides.json`'s `cleanup`, through the same
+   * `applyCleanupChoices` produce ran. Optional: pre-step-3 files predate it
+   * and must still parse (readers fall back to `cutlist`, which back then
+   * WAS the proposal plus user cuts).
+   */
+  cutlistProposed: z.array(SegmentSchema).optional(),
   /**
    * Present on a `--clip` run (R19 §93): the target and the resolved window.
    * `startWord`/`endWord` are indices into the PRE-slice repaired transcript