@ossclip/core 0.1.27 → 0.1.28

package/src/producer/beats.ts

@@ -99,7 +99,37 @@ export const ClipBeatSheetSchema = BeatSheetSchema.extend({
   ),
 });
 
-export const PRODUCER_SYSTEM = `You are the producer for a short-form vertical video (Reels/Shorts/TikTok). You receive a word-indexed transcript of a talking-head take that has already been cut. Your job is EDITORIAL: segment the take into moments, pick which moments deserve a graphic scene, and write the on-screen copy.
+/**
+ * Bump whenever `producerSystem`/`buildBeatsUserPrompt` change what they ask
+ * for: a prompt change changes the answer, so the beat-sheet/scenes cache key
+ * carries this (the §78 cache-key posture, same role as
+ * YOUTUBE_PROMPT_VERSION) — an old cached sheet must not survive a new prompt.
+ *
+ * v2: the system prompt stopped calling every output "vertical" (see
+ * `producerSystem`).
+ */
+export const PRODUCER_PROMPT_VERSION = "v2";
+
+/**
+ * The editorial system prompt, in the shape the output actually has.
+ *
+ * The opening sentence used to hardcode "short-form vertical video
+ * (Reels/Shorts/TikTok)" for every run, while `buildBeatsUserPrompt` has told
+ * 16:9 runs "Output frame: LANDSCAPE 16:9" since R21 §101 — so a landscape
+ * produce handed the model two contradictory descriptions of the same frame
+ * and left it to reconcile them (confirmed on a live 16:9 run, 2026-08).
+ *
+ * ONLY that sentence varies. Everything below it is the tuned 9:16 wording,
+ * byte-identical, and the portrait default must stay byte-identical to what
+ * shipped — the virality grammar was tuned against real runs of it, and a
+ * silent reword is a silent re-tune.
+ */
+export function producerSystem(aspect?: "9:16" | "16:9"): string {
+  const shape =
+    aspect === "16:9"
+      ? "a landscape video (YouTube)"
+      : "a short-form vertical video (Reels/Shorts/TikTok)";
+  return `You are the producer for ${shape}. You receive a word-indexed transcript of a talking-head take that has already been cut. Your job is EDITORIAL: segment the take into moments, pick which moments deserve a graphic scene, and write the on-screen copy.
 
 Virality grammar — follow these as hard policies:
 - The first moment is the hook: the strongest claim or number anywhere in the take, on screen within 2 seconds.
@@ -115,10 +145,19 @@ Virality grammar — follow these as hard policies:
 - The transcript is ASR output and may contain mishearings: an unfamiliar proper noun is more likely a mistranscription of a common phrase than a real entity — write on-screen copy with the common-sense reading, never a suspected mishearing.
 - FRAMING: when the prompt carries a "Camera framing" brief, it is measured from the footage and is a HARD constraint: on words marked CLOSE, never choose a layout listed as UNAVAILABLE there — pick a \`layout\` that keeps the whole head in frame (pip-bubble, graphic-only, full-bleed) or leave the moment as "none". You may set \`layout\` on any moment; omit it to accept the component's default.
 - COVER: also write \`coverText\` — the hook compressed to a thumbnail headline, AT MOST ${COVER_MAX_WORDS} WORDS. It is read at a glance in a profile grid, so it must stand alone without the video: the claim or the number, no lead-in, no ellipsis.`;
+}
+
+/**
+ * The portrait prompt, kept as a named export because it is part of
+ * @ossclip/core's public surface (`export * from "./producer/beats"`) and
+ * removing it would break an importer for nothing. Equal to
+ * `producerSystem()` by construction — never a second copy of the text.
+ */
+export const PRODUCER_SYSTEM = producerSystem();
 
 /**
  * The `--clip` request, appended to the USER prompt (R19 §93d). The tuned
- * PRODUCER_SYSTEM stays untouched — this adds the window request without
+ * system prompt stays untouched — this adds the window request without
  * rewriting the editorial instructions the beat sheet already follows.
  */
 export function buildClipAddendum(targetSec: number): string {
@@ -508,7 +547,9 @@ export async function generateBeatSheet(
     // Same editorial call, extended schema (R19 §93d) — the highlight and the
     // beat sheet come from ONE judgement, so they cannot disagree.
     const raw = await provider.complete({
-      system: PRODUCER_SYSTEM,
+      // Same aspect the user prompt was built with — the two halves of one
+      // call must describe the same frame.
+      system: producerSystem(aspect),
       user,
       schema: ClipBeatSheetSchema,
       schemaName: "clip_beat_sheet",
@@ -517,7 +558,7 @@ export async function generateBeatSheet(
     return { ...normalizeBeatSheet(raw, transcript, null), asked, highlight: raw.highlight };
   }
   const raw = await provider.complete({
-    system: PRODUCER_SYSTEM,
+    system: producerSystem(aspect),
     user,
     schema: BeatSheetSchema,
     schemaName: "beat_sheet",

package/src/producer/claude-cli.ts

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { run } from "../exec";
+import { attemptFactsLine } from "./failure";
 import type { LlmProvider } from "./provider";
 import { estimateTokens, type LlmUsage } from "./usage";
 
@@ -38,6 +39,8 @@ export class ClaudeCliProvider implements LlmProvider {
       `No markdown fences, no commentary, no tool use — just the JSON:\n${schemaText}`;
 
     let lastError = "";
+    /** Wall time of every failed attempt — see `claudeCliFailureMessage`. */
+    const attemptMs: number[] = [];
     for (let attempt = 0; attempt < 2; attempt++) {
       const prompt =
         attempt === 0
@@ -50,6 +53,7 @@ export class ClaudeCliProvider implements LlmProvider {
       try {
         ({ stdout } = await run(this.bin, args, { stdin: prompt }));
       } catch (err) {
+        attemptMs.push(Date.now() - started);
         lastError = err instanceof Error ? err.message : String(err);
         continue;
       }
@@ -75,16 +79,92 @@ export class ClaudeCliProvider implements LlmProvider {
       try {
         return req.schema.parse(JSON.parse(extractJsonObject(unwrapCliEnvelope(stdout))));
       } catch (err) {
+        attemptMs.push(Date.now() - started);
         lastError = err instanceof Error ? err.message : String(err);
       }
     }
     throw new Error(
-      `claude CLI ('${this.bin}') did not produce valid ${req.schemaName} JSON: ${lastError.slice(0, 400)}\n` +
-        `Is Claude Code installed and logged in? (npm i -g @anthropic-ai/claude-code; run 'claude' once to /login)`,
+      claudeCliFailureMessage({ bin: this.bin, schemaName: req.schemaName, lastError, attemptMs }),
     );
   }
 }
 
+/** What the failure text says went wrong. See `classifyClaudeCliFailure`. */
+export type ClaudeCliFailureClass = "auth" | "model" | "timeout" | "schema" | "unknown";
+
+/**
+ * Classify a `claude -p` failure. Pure, and exported so each class is
+ * assertable without spawning the CLI.
+ *
+ * Same disease as agy's (FINDINGS §132): the sign-in hint below used to be
+ * appended to EVERY failure, so a bad model slug or a schema-repair loop told
+ * the user to check a login that was fine. Same cure — classify, print the
+ * attempt facts unconditionally, gate the advice.
+ *
+ * The surfaces are NOT the same, and this one was measured too (Claude Code,
+ * 2026-08-22, a bad `--model` slug): exit 1, a machine-readable
+ * `[claude-code:unrecognized_model] {…}` on STDERR, and a human sentence in
+ * the stdout envelope's `result`. Because it uses stderr — and because the
+ * prompt rides STDIN here, so `run()`'s rejection echoes a short argv rather
+ * than the whole transcript — the rejection message this receives already
+ * carries the reason, and no `allowNonZero` change is needed to see it.
+ *
+ * `auth` is inferred, not measured: establishing it would mean signing the
+ * user out. Its patterns are widened only to things that cannot mean anything
+ * else, so a real auth failure still gets the hint it always got.
+ */
+export function classifyClaudeCliFailure(message: string): ClaudeCliFailureClass {
+  if (/invalid api key|authentication|not logged in|\/login|unauthorized|oauth/i.test(message))
+    return "auth";
+  if (/unrecognized_model|unknown model|invalid model|model .* not (found|recognized)/i.test(message))
+    return "model";
+  if (/timed? ?out|ETIMEDOUT|SIGTERM|SIGKILL/i.test(message)) return "timeout";
+  const schemaish = /no JSON object in reply|is not valid JSON|Unexpected (token|end of)|"code":\s*"/i;
+  if (schemaish.test(message)) return "schema";
+  return "unknown";
+}
+
+/**
+ * The error thrown when both attempts failed. The attempt facts print for
+ * every class because they self-diagnose regardless of the classification
+ * (§132); the sign-in hint is gated to `auth`, and a model failure points at
+ * the flag that actually caused it.
+ */
+export function claudeCliFailureMessage(parts: {
+  bin: string;
+  schemaName: string;
+  lastError: string;
+  attemptMs: readonly number[];
+}): string {
+  const cls = classifyClaudeCliFailure(parts.lastError);
+  const headline =
+    cls === "timeout"
+      ? " — the call timed out"
+      : cls === "schema"
+        ? " — the reply never matched the schema"
+        : "";
+  const lines = [
+    `claude CLI ('${parts.bin}') did not produce valid ${parts.schemaName} JSON${headline}: ` +
+      (parts.lastError.trim().slice(0, 400) || "claude printed nothing"),
+    attemptFactsLine(parts.attemptMs),
+  ];
+  if (cls === "auth") {
+    lines.push(
+      `Is Claude Code installed and logged in? (npm i -g @anthropic-ai/claude-code; run 'claude' once to /login)`,
+    );
+  }
+  if (cls === "model") {
+    lines.push(`Check the --llm-model slug, or drop it to use the CLI's own default model.`);
+  }
+  if (cls === "timeout") {
+    lines.push(
+      `Use --llm antigravity (a logged-in Antigravity subscription) or --llm gemini (needs GEMINI_API_KEY), ` +
+        `or drop --produce to cut and caption without a planner.`,
+    );
+  }
+  return lines.join("\n");
+}
+
 /**
  * The accounting half of the same envelope: tokens, cost and model, all
  * optional because the CLI's envelope shape is not ours to depend on. Every

package/src/producer/failure.ts

@@ -0,0 +1,40 @@
+/**
+ * The facts every failed LLM call can state without guessing why it failed.
+ *
+ * From the 2026-08-22 incident (FINDINGS §132): a `--produce --aspect 16:9`
+ * run on an 11-minute take timed out twice at agy's print timeout — 10m each,
+ * 25 minutes burned — and died with "Is Antigravity installed and logged in?"
+ * on an agy that was installed, logged in and working. What that user needed
+ * was not a better guess, it was the shape of the wait: two attempts, ten
+ * minutes each. Attempt facts self-diagnose a hang, and they stay true when
+ * the classification is wrong — so both CLI providers print them for EVERY
+ * failure class, and gate only the advice.
+ *
+ * Pure, and shared so the two providers cannot drift into two formats for the
+ * same sentence.
+ */
+
+/** `600_000 → "10m0s"`, `1_500 → "1.5s"` — an at-a-glance wall time. */
+export function formatElapsed(ms: number): string {
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  // Floored, not rounded: 1m59.6s must not print as "1m60s".
+  return `${Math.floor(ms / 60_000)}m${Math.floor((ms % 60_000) / 1000)}s`;
+}
+
+/**
+ * "2 attempts, 10m0s and 10m0s" — how many calls ran and how long each took,
+ * with `extra` appended for a provider that has a clock worth naming (agy's
+ * `--print-timeout`). An empty list still says "0 attempts": a call that never
+ * spawned is itself the diagnosis.
+ */
+export function attemptFactsLine(attemptMs: readonly number[], extra?: string): string {
+  const times = attemptMs.map(formatElapsed);
+  const listed =
+    times.length > 1
+      ? `${times.slice(0, -1).join(", ")} and ${times[times.length - 1]}`
+      : (times[0] ?? "");
+  return (
+    `${attemptMs.length} attempt${attemptMs.length === 1 ? "" : "s"}` +
+    `${listed ? `, ${listed}` : ""}${extra ? `, ${extra}` : ""}.`
+  );
+}

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,