@ossclip/core 0.1.31 → 0.1.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.31",
+  "version": "0.1.34",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/browser.ts

@@ -35,6 +35,11 @@ export {
 // set need the bundled font" (2026-08-17 — two conditions would drift).
 export {
   backfillSrcStart,
+  // The editor rebuilds the caption track over REVIVED material with the
+  // same builder + packing matrix produce renders with (cut-review rework
+  // follow-up) — a second packer is how preview and render would drift.
+  buildCaptionLines,
+  captionPackingFor,
   captionsNeedNastaliq,
   lineDirection,
   NASTALIQ_FONT_NAME,
@@ -69,9 +74,15 @@ export { COVER_MAX_WORDS, coverHeadline } from "./cover-headline";
 export {
   applyCleanupChoices,
   cleanupVetoable,
+  dismissedRemovals,
   vetoedRemovals,
   type CleanupChoices,
 } from "./cutlist";
+// Revived-material carving (cut-review rework 2026-08-26), browser-safe:
+// kept-takes.ts imports only scene-schema, timemap and overrides types —
+// all already in this surface's graph. Editor and produce carve with the
+// SAME function (the applyCleanupChoices pattern).
+export { carveKeptTakes, keptTakeId, type KeptRange, type CarveResult } from "./kept-takes";
 // The live post-veto preview (cut review step 4), VALUE exports and
 // browser-safe: retime-preview.ts composes cutlist + recut + timemap — all
 // already in this surface's runtime graph (recut.ts imports only overrides
@@ -99,6 +110,14 @@ export {
   type RetimeablePreviewProps,
   type RetimedPreviewFields,
 } from "./retime-preview";
+// The caption re-key half of the re-transcribe splice (Phase A 2026-08-26),
+// browser-safe by construction: restamp.ts imports `captionKeyFor` from
+// ./overrides (already on this surface) plus types, and NOTHING else — see its
+// header for why the token normalizer is restated there rather than imported
+// from analyze.ts (which reaches child_process). The `useEdits` reducer owns
+// `overrides.json`; the server that re-decodes the audio never writes it, so
+// the re-key has to run in the browser.
+export { rekeyCaptionRecords, type RekeyResult, type StampMove } from "./restamp";
 export type {
   Probe,
   Production,

package/src/captions.ts

@@ -143,8 +143,103 @@ export interface CaptionOptions {
  * the start toward it. Display-only: cuts, analysis and the transcript
  * itself never see this, and `srcStart` keeps the RAW source stamp so the
  * §137 edit anchor does not move.
+ *
+ * 2.0 → 1.5 (field case 2026-08-26, a revived retake): its smears SLIPPED
+ * UNDER the 2.0 bar — `dedicated` was stamped 2.43s, so the clamp still left
+ * the word squatting on screen for a full 2.0s with the karaoke highlight
+ * stuck on it, and 8 more words in that one transcript were the same shape.
+ * 1.5s exceeds any genuinely spoken English word, so the tighter bar cannot
+ * truncate real speech, and the 2026-08-17 incident still shows "Okay," for
+ * its final 1.5s. ONE lever, by doctrine: the end side is the trustworthy
+ * edge and is never clamped, so how hard the start pulls toward it is the
+ * only number here — a second constant would just be this one, twice.
+ */
+export const MAX_CAPTION_WORD_LEAD_SEC = 1.5;
+
+/**
+ * The floor on how long a caption LINE stays on screen. Whisper's stamps can
+ * cram a burst of words into no time at all — field case 2026-08-26, a
+ * revived retake: ten words ("context could read 50 files and then gives a
+ * clean") inside 0.25s, 0.01–0.05s each, which packs into 3-word lines with
+ * ~0.06s windows. Rendered faithfully that is a flash nobody can read at any
+ * speed, so the display repairs it: a too-short line borrows from the GAP
+ * that follows it.
+ *
+ * SLACK ONLY, and there usually is none. On the transcript this came from,
+ * 98% of adjacent word pairs have a gap of ≤0 (the §18 contiguous-stamp
+ * chain, `parseWhisperJson` sets `next.start = w.end`), so on a zero-gap run
+ * of flash lines this sweep does NOTHING and the captions stay fast. That is
+ * the honest limit: a display cannot slow speech down, only spend slack that
+ * exists — which is also why the sweep is monotone and single-pass, never
+ * pushing a later line to make room. The slack it does find is largely what
+ * `MAX_CAPTION_WORD_LEAD_SEC` above creates by pulling a smeared start
+ * forward.
+ */
+export const MIN_CAPTION_LINE_DWELL_SEC = 0.7;
+
+/**
+ * Extend every line that would flash by less than `MIN_CAPTION_LINE_DWELL_SEC`
+ * into the gap after it — the display-side repair of a crammed stamp burst.
+ *
+ * Forward, single-pass, monotone: only line ENDS move, and only later, so the
+ * caps below can be read off the ORIGINAL lines and no line can be pushed by
+ * one before it. Bounds, all three of which the packer already respects for
+ * `hold` (`buildCaptionLines` below) and which therefore cannot be dropped
+ * here without re-opening what they were added for:
+ *  - the next line's START — never overlap, never reorder (§115,
+ *    `packages/scenes/src/frames.ts`: no two lines may share a frame);
+ *  - the next BREAKPOINT — a line held across a scene-cue edge sits in the
+ *    WRONG layout's caption band and can land on a card or the face
+ *    (FINDINGS §6b), and readability is not worth that;
+ *  - `maxEnd`, the output duration — there are no frames past it to draw on.
+ * The last line is free of the NEIGHBOUR bound only; the other two still hold.
+ *
+ * Never shortens a line, and never touches `words`: the dwell is the LINE's
+ * window, and stretching the last word's karaoke stamp to fill it would just
+ * move the stuck-highlight bug from `MAX_CAPTION_WORD_LEAD_SEC`'s case into
+ * this one. Lines with no slack to take are returned VERBATIM. Pure, so the
+ * whole bounds matrix is testable without a packer.
+ */
+export function enforceLineDwell(
+  lines: readonly CaptionLine[],
+  opts: { breakpoints?: readonly number[]; maxEnd?: number } = {},
+): CaptionLine[] {
+  const breakpoints = [...(opts.breakpoints ?? [])].sort((a, b) => a - b);
+  return lines.map((line, i) => {
+    if (line.end - line.start >= MIN_CAPTION_LINE_DWELL_SEC) return line;
+    let end = line.start + MIN_CAPTION_LINE_DWELL_SEC;
+    const next = lines[i + 1];
+    if (next) end = Math.min(end, next.start);
+    // Same predicate as the hold clamp, so the two agree on which boundary is
+    // "this line's": strictly after its start, with the packer's epsilon.
+    const boundary = breakpoints.find((b) => b > line.start + 1e-6);
+    if (boundary !== undefined) end = Math.min(end, boundary);
+    if (opts.maxEnd !== undefined) end = Math.min(end, opts.maxEnd);
+    // A cap at or before where the line already ended is no slack at all —
+    // return the line itself, so an untouched track stays byte-identical.
+    if (end <= line.end) return line;
+    return { ...line, end };
+  });
+}
+
+/**
+ * Landscape draws captions at 44px on a 1920px frame against portrait's
+ * 64px on 1080px (`captionFontSizeFor`) — roughly 2.6× the horizontal text
+ * budget — so the portrait default's 3-word lines look sparse there;
+ * landscape packs 6 words over 2.4s, double the core defaults. Portrait
+ * returns those defaults VERBATIM — the core defaults are portrait's
+ * contract and its output must stay byte-identical. Lived in produce.ts
+ * until the cut-review follow-up; the editor's live caption rebuild packs
+ * with this same matrix, so it moved to the one browser-safe home.
  */
-export const MAX_CAPTION_WORD_LEAD_SEC = 2;
+export function captionPackingFor(landscape: boolean): {
+  maxWordsPerLine: number;
+  maxLineDuration: number;
+} {
+  return landscape
+    ? { maxWordsPerLine: 6, maxLineDuration: 2.4 }
+    : { maxWordsPerLine: 3, maxLineDuration: 1.2 };
+}
 
 export function buildCaptionLines(
   transcript: Transcript,
@@ -211,5 +306,9 @@ export function buildCaptionLines(
     // A single word physically spanning a boundary stays readable to its end.
     line.end = Math.min(Math.max(end, lastWordEnd), map.outputDuration);
   }
-  return lines;
+  // LAST, on the finished windows: `hold` has already had its say, so the
+  // dwell floor caps at an absolute `start + MIN_CAPTION_LINE_DWELL_SEC`
+  // rather than adding to what the hold produced — a line already long
+  // enough is returned untouched instead of held twice.
+  return enforceLineDwell(lines, { breakpoints, maxEnd: map.outputDuration });
 }

package/src/config.ts

@@ -67,6 +67,15 @@ export interface OssclipConfig {
    * `--watermark` / `--no-watermark` win over this per run.
    */
   watermark?: boolean;
+  /**
+   * Overlay the cover image on the opening frames of every produce run, for
+   * the platforms that ignore an uploaded cover and use frame 1. DEFAULT OFF:
+   * the overlay costs the first fraction of the hook, so it is a choice about
+   * where you publish, not a default anyone should inherit.
+   * `--cover-in-video` / `--no-cover-in-video` win over this per run
+   * (`resolveCoverInVideo`), the `watermark` contract exactly.
+   */
+  coverInVideo?: boolean;
   /**
    * Terms of art the speaker uses — "JSON", "ossclip", "Genkit" — biasing
    * transcription (whisper `--prompt`), vouching repair corrections, and
@@ -133,6 +142,24 @@ export interface OssclipConfig {
    * one warning and the default, never a coerced tab count.
    */
   renderConcurrency?: number;
+  /**
+   * Base URL of the user's own self-hosted Postiz instance
+   * (https://postiz.com), the backend `ossclip publish` posts through —
+   * "https://postiz.example.com" or "http://localhost:5000". Non-secret, so
+   * it may live here; the API key is `OSSCLIP_POSTIZ_API_KEY` in the
+   * ENVIRONMENT only (env.ts's documented rule — secrets never live in
+   * config.json). File-only like `audience`; validated at the consumer
+   * (`publishConfigured` in the CLI), never coerced.
+   */
+  postizUrl?: string;
+  /**
+   * `--resolution`'s default for this machine: "auto" (keep what the source
+   * has, capped at 2160), "1080" (the built-in default), "1440" or "2160".
+   * File-only, the `watermark` posture: validated where it is USED
+   * (`resolveResolution` in produce.ts), so a hand-edited "4k" earns one
+   * warning and the 1080 default rather than a coerced render size.
+   */
+  resolution?: string;
   /**
    * USD per million tokens, keyed by model id or family substring — overrides
    * the built-in assumptions in `producer/usage.ts` so a run's cost line
@@ -199,28 +226,50 @@ export function loadConfig(): OssclipConfig {
   } catch {
     // no config file — fine
   }
+  return resolveConfig(fileCfg, process.env);
+}
+
+/**
+ * The pure half of `loadConfig` — the file-vs-env-vs-default resolution with
+ * no homedir read, so the mapping itself is testable (config.test.ts). Split
+ * out after the 2026-08-27 publish E2E: `postizUrl` sat on the TYPE and in
+ * the docs but this hand-written mapping never copied it, so publish reported
+ * "missing postizUrl" against a config.json that plainly had it — a key that
+ * exists only in the type is invisible at runtime, and nothing could say so
+ * while the mapping lived behind the filesystem.
+ */
+export function resolveConfig(
+  fileCfg: Partial<OssclipConfig>,
+  env: NodeJS.ProcessEnv,
+): OssclipConfig {
   return {
-    ffmpegPath: process.env.OSSCLIP_FFMPEG ?? fileCfg.ffmpegPath ?? DEFAULTS.ffmpegPath,
-    ffprobePath: process.env.OSSCLIP_FFPROBE ?? fileCfg.ffprobePath ?? DEFAULTS.ffprobePath,
-    whisperPath: process.env.OSSCLIP_WHISPER ?? fileCfg.whisperPath ?? DEFAULTS.whisperPath,
-    modelDir: process.env.OSSCLIP_MODEL_DIR ?? fileCfg.modelDir ?? DEFAULTS.modelDir,
-    model: process.env.OSSCLIP_MODEL ?? fileCfg.model ?? DEFAULTS.model,
-    fastModel: process.env.OSSCLIP_FAST_MODEL ?? fileCfg.fastModel,
+    ffmpegPath: env.OSSCLIP_FFMPEG ?? fileCfg.ffmpegPath ?? DEFAULTS.ffmpegPath,
+    ffprobePath: env.OSSCLIP_FFPROBE ?? fileCfg.ffprobePath ?? DEFAULTS.ffprobePath,
+    whisperPath: env.OSSCLIP_WHISPER ?? fileCfg.whisperPath ?? DEFAULTS.whisperPath,
+    modelDir: env.OSSCLIP_MODEL_DIR ?? fileCfg.modelDir ?? DEFAULTS.modelDir,
+    model: env.OSSCLIP_MODEL ?? fileCfg.model ?? DEFAULTS.model,
+    fastModel: env.OSSCLIP_FAST_MODEL ?? fileCfg.fastModel,
     // File-only, the `dictionary` posture — and deliberately NO env spelling
     // (flag + config are the whole interface): validated where it is USED
     // (`resolveLlmEffort` in produce.ts), so a hand-edited `"max"` earns one
     // warning there and agy's default, never a coerced effort.
     llmEffort: fileCfg.llmEffort,
-    speaker: process.env.OSSCLIP_SPEAKER ?? fileCfg.speaker,
-    openEditorAfterProduce: (process.env.OSSCLIP_OPEN_EDITOR ??
-      fileCfg.openEditorAfterProduce) as OpenEditorPref | undefined,
-    browserExecutable: process.env.OSSCLIP_BROWSER ?? fileCfg.browserExecutable,
+    speaker: env.OSSCLIP_SPEAKER ?? fileCfg.speaker,
+    openEditorAfterProduce: (env.OSSCLIP_OPEN_EDITOR ?? fileCfg.openEditorAfterProduce) as
+      | OpenEditorPref
+      | undefined,
+    browserExecutable: env.OSSCLIP_BROWSER ?? fileCfg.browserExecutable,
     // File-only, like `pricing`: an env spelling would arrive as a string,
     // and "false" is truthy — parse-don't-coerce says no such trap. The
     // strict `=== true` check lives at the consumer (produce's
     // resolveWatermark), so a hand-edited non-boolean stays OFF, the safe
     // default for a credit.
     watermark: fileCfg.watermark,
+    // File-only, `watermark`'s posture verbatim: the strict `=== true` lives
+    // at the consumer (produce's resolveCoverInVideo), so a hand-edited
+    // non-boolean stays OFF — the safe default for something that paints over
+    // the first frames of the hook.
+    coverInVideo: fileCfg.coverInVideo,
     // File-only for the same reason as `watermark`: these are structured
     // values a hand-editable JSON file supplies, and parse-don't-coerce says
     // the strict checks live at the consumer — `validDictionary` /
@@ -248,5 +297,10 @@ export function loadConfig(): OssclipConfig {
     thumbnailBrief: fileCfg.thumbnailBrief,
     thumbnailModel: fileCfg.thumbnailModel,
     pricing: fileCfg.pricing,
+    // File-only, non-secret by declaration (the field's own doc): the API key
+    // deliberately lives in the environment (publish.ts's
+    // `publishConfigured`), so this is only the instance URL.
+    postizUrl: fileCfg.postizUrl,
+    resolution: fileCfg.resolution,
   };
 }

package/src/cover-in-video.ts

@@ -0,0 +1,56 @@
+/**
+ * `--cover-in-video` (§93): the cover image OVERLAID on the short's opening
+ * frames, for the platforms that ignore an uploaded cover and use frame 1.
+ *
+ * OVERLAY, never insertion. Inserting a still at the head would shift every
+ * output instant after it — audio, spans, splits, pinned timing, caption
+ * stamps — which is the §93 A/V-sync trap the roadmap item refused to rush.
+ * Painting over frames that already exist changes no clock at all, so nothing
+ * downstream has to be re-anchored and an off run stays byte-identical.
+ *
+ * The cost of the overlay is the mirror image: whatever it covers is LOST for
+ * its duration, not delayed. That is what bounds the window below.
+ */
+
+/**
+ * Longest the cover may sit on top of the video. Half a second is about the
+ * shortest a still reads as a deliberate first frame in a feed scrub; more
+ * than that and the overlay is eating the hook the whole pipeline exists to
+ * put in the first two seconds.
+ */
+export const COVER_IN_VIDEO_CAP_SEC = 0.5;
+
+/**
+ * Shortest window worth rendering. A take whose first word lands at 0.04s
+ * would otherwise get a one-or-two-frame flash that reads as a glitch rather
+ * than a cover — and the floor deliberately eats the head of that first word,
+ * because a cover nobody can see is not a cover.
+ */
+export const COVER_IN_VIDEO_FLOOR_SEC = 0.2;
+
+/**
+ * How long the cover overlay lasts, in OUTPUT seconds.
+ *
+ * It ends at the FIRST WORD's start: the moment speech begins is the moment
+ * the overlay starts costing content, and the head of a take is usually a
+ * breath or a settle nobody misses. Clamped into `[floorSec, capSec]` — see
+ * the two constants for what each bound is protecting.
+ *
+ * `words` are OUTPUT-clock words (caption words, post-cut): the caller owns
+ * the clock, this owns the arithmetic. No words at all — a `--no-produce` run,
+ * a silent take, a transcript that came back empty — takes the cap, since
+ * there is no speech for the overlay to be in the way of.
+ *
+ * Pure so the whole matrix is testable without a transcript on disk.
+ */
+export function coverInVideoWindow(
+  words: readonly { start: number }[],
+  opts: { capSec: number; floorSec: number },
+): number {
+  const first = words[0]?.start;
+  // `Number.isFinite`, not a truthiness check: a first word at exactly 0 is a
+  // real value (it floors below), while a NaN start from a mangled transcript
+  // must fall back to the cap rather than propagate into a frame count.
+  if (first === undefined || !Number.isFinite(first)) return opts.capSec;
+  return Math.min(opts.capSec, Math.max(opts.floorSec, first));
+}

package/src/cutlist.ts

@@ -349,6 +349,15 @@ export interface CleanupChoices {
   /** Individual vetoes, SOURCE seconds — see `vetoedRemovals` for the
    * overlap-based matching rule. */
   kept?: readonly { srcIn: number; srcOut: number }[];
+  /**
+   * Dismissed proposals ("not a retake") — the classification itself was
+   * wrong, so the material is ordinary footage and the marker disappears.
+   * SOURCE seconds, overlap-matched like `kept`. Kept in its own list, NOT
+   * folded into `kept`: `vetoedRemovals` feeds the "kept · <reason>" visual
+   * state and produce's kept-N line, and a dismissed marker must read as
+   * neither. `applyCleanupChoices` re-keeps both.
+   */
+  dismissed?: readonly { srcIn: number; srcOut: number }[];
 }
 
 /**
@@ -413,11 +422,39 @@ export function vetoedRemovals(
  * (via `@ossclip/core/browser`) to mark vetoed seams. A preview that
  * disagrees with the render is worse than no preview.
  */
+/**
+ * The `remove` spans of `cutlist` that `choices.dismissed` reclassifies away
+ * — `vetoedRemovals`' exact matching rule (overlap, never float equality; a
+ * partial overlap dismisses the WHOLE removal — one decision, not divisible)
+ * over the other list. Separate function on purpose: the two lists mean
+ * different things to every DISPLAY surface (a veto is "kept", a dismissal
+ * is "there was never anything here"), while `applyCleanupChoices` re-keeps
+ * the union because the RENDER outcome is identical.
+ */
+export function dismissedRemovals(
+  cutlist: readonly Segment[],
+  choices: CleanupChoices | undefined,
+): Segment[] {
+  const dismissed = choices?.dismissed ?? [];
+  if (dismissed.length === 0) return [];
+  return cutlist.filter(
+    (seg) =>
+      seg.kind === "remove" &&
+      cleanupVetoable(seg.reason) &&
+      dismissed.some((d) => d.srcIn < seg.srcOut && d.srcOut > seg.srcIn),
+  );
+}
+
 export function applyCleanupChoices(
   cutlist: readonly Segment[],
   choices: CleanupChoices | undefined,
 ): Segment[] {
-  const vetoed = new Set(vetoedRemovals(cutlist, choices));
+  const vetoed = new Set([
+    ...vetoedRemovals(cutlist, choices),
+    // Dismissed proposals re-keep identically — the difference is display
+    // state and permanence, not render outcome (dismissedRemovals' doc).
+    ...dismissedRemovals(cutlist, choices),
+  ]);
   if (vetoed.size === 0) return [...cutlist];
   const out: Segment[] = [];
   for (const seg of cutlist) {

package/src/exec.ts

@@ -12,13 +12,24 @@ export interface ExecResult {
 export function run(
   bin: string,
   args: string[],
-  opts: { allowNonZero?: boolean; stdin?: string } = {},
+  opts: {
+    allowNonZero?: boolean;
+    stdin?: string;
+    /** Per-chunk stdout tap, IN ADDITION to collection — the delivery
+     * encode's `-progress pipe:1` stream needs live chunks, not the
+     * post-mortem transcript. */
+    onStdout?: (chunk: string) => void;
+  } = {},
 ): Promise<ExecResult> {
   return new Promise((resolve, reject) => {
     const child = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
-    child.stdout.on("data", (c: Buffer) => (stdout += c.toString()));
+    child.stdout.on("data", (c: Buffer) => {
+      const text = c.toString();
+      stdout += text;
+      opts.onStdout?.(text);
+    });
     child.stderr.on("data", (c: Buffer) => (stderr += c.toString()));
     child.on("error", (err) => reject(new Error(`${bin} failed to start: ${err.message}`)));
     child.on("close", (code) => {

package/src/grounding.ts

@@ -102,6 +102,39 @@ function stringsOf(value: unknown): string[] {
   return [];
 }
 
+/**
+ * The tokens in `text` that the transcript nowhere supports, in text order,
+ * duplicates kept. This IS the grounding rule — `checkGrounding` walks scene
+ * fields through it, and the publish panel's caption regenerate runs it over
+ * a rewritten caption as an ADVISORY (captions legitimately contain brand and
+ * platform words never spoken, so its callers show notes, never a block).
+ * One spelling on purpose: the module header's §17 history is what a second
+ * copy of the supported() relaxation would eventually re-earn.
+ *
+ * The spoken set is rebuilt per call — cheap at real transcript sizes, and
+ * the price of keeping the rule callable on a single string.
+ *
+ * The transcript parameter demands only spoken text, which is all the rule
+ * reads: a full `Transcript` satisfies it, and so does the edit server's
+ * leniently-read transcript.json (words filtered to those with string text,
+ * timing not re-validated for a check that never looks at it).
+ */
+export function ungroundedTokens(
+  text: string,
+  transcript: { words: ReadonlyArray<{ text: string }> },
+  speaker?: string,
+): string[] {
+  const spoken = new Set([
+    ...transcript.words.flatMap((w) => tokenize(w.text)),
+    ...(speaker ? tokenize(speaker) : []),
+  ]);
+  const supported = (token: string): boolean =>
+    spoken.has(token) ||
+    spoken.has(`${token}s`) ||
+    (token.endsWith("s") && spoken.has(token.slice(0, -1)));
+  return tokenize(text).filter((token) => needsSupport(token) && !supported(token));
+}
+
 export function checkGrounding(
   scenes: readonly Scene[],
   transcript: Transcript,
@@ -113,25 +146,14 @@ export function checkGrounding(
    */
   speaker?: string,
 ): GroundingIssue[] {
-  const spoken = new Set([
-    ...transcript.words.flatMap((w) => tokenize(w.text)),
-    ...(speaker ? tokenize(speaker) : []),
-  ]);
-  const supported = (token: string): boolean =>
-    spoken.has(token) ||
-    spoken.has(`${token}s`) ||
-    (token.endsWith("s") && spoken.has(token.slice(0, -1)));
-
   const issues: GroundingIssue[] = [];
   for (const scene of scenes) {
     const fields = CHECKED_FIELDS[scene.component] ?? [];
     const merged = { ...scene.props, ...scene.overrides };
     for (const field of fields) {
       for (const text of stringsOf(merged[field])) {
-        for (const token of tokenize(text)) {
-          if (needsSupport(token) && !supported(token)) {
-            issues.push({ sceneId: scene.id, component: scene.component, field, token });
-          }
+        for (const token of ungroundedTokens(text, transcript, speaker)) {
+          issues.push({ sceneId: scene.id, component: scene.component, field, token });
         }
       }
     }

package/src/index.ts

@@ -10,6 +10,7 @@ export * from "./recut";
 export * from "./ingest";
 export * from "./concat";
 export * from "./transcribe";
+export * from "./restamp";
 export * from "./analyze";
 export * from "./cutlist";
 export * from "./retime-preview";
@@ -28,6 +29,9 @@ export * from "./normalize";
 export * from "./framing";
 export * from "./face";
 export * from "./cover";
+export * from "./cover-in-video";
+export * from "./publish/index";
+export * from "./kept-takes";
 export * from "./thumbnail";
 export * from "./source-text";
 export * from "./report";
@@ -38,4 +42,5 @@ export * from "./export-premiere-xml";
 export * from "./export-premiere-project";
 export * from "./export-xmeml-util";
 export * from "./config";
+export * from "./resolution";
 export { run } from "./exec";

package/src/ingest.ts

@@ -85,6 +85,40 @@ export async function extractAudio(tools: IngestTools, src: string, outWav: stri
   ]);
 }
 
+/**
+ * Extract ONE span of an existing wav, same 16 kHz mono PCM shape
+ * (2026-08-26, the caption re-alignment pass).
+ *
+ * Fed the workdir's `audio.wav`, which `extractAudio` above already wrote at
+ * 16k/mono/pcm_s16le — so this is a sample-exact cut, not a re-encode, and it
+ * costs milliseconds even on a long source. Re-slicing from the ORIGINAL video
+ * would decode video frames for nothing and hand whisper an audio stream
+ * conditioned differently from the one the first pass decoded, which is
+ * exactly the variable a re-transcription is trying to hold still.
+ *
+ * `-ss` goes BEFORE `-i`: as an input option ffmpeg seeks the demuxer and
+ * starts decoding at the span, instead of decoding the whole file and
+ * discarding everything ahead of it. On PCM that seek is exact, so the clip's
+ * stamps are `spanStart`-relative with no drift to compensate for
+ * (`alignRestamp` adds the offset back).
+ */
+export async function extractAudioSpan(
+  tools: IngestTools,
+  wav: string,
+  outWav: string,
+  fromSec: number,
+  durSec: number,
+): Promise<void> {
+  await run(tools.ffmpegPath, [
+    "-y",
+    "-ss", fromSec.toFixed(3),
+    "-i", wav,
+    "-t", durSec.toFixed(3),
+    "-vn", "-ar", "16000", "-ac", "1", "-c:a", "pcm_s16le",
+    outWav,
+  ]);
+}
+
 /**
  * Headroom over the exact displayed size so a zoomed span never renders from
  * below-native pixels (2026-08-17 render-speed pass). The two motion drivers
@@ -103,7 +137,7 @@ export interface MezzanineScale {
 }
 
 /** Nearest even dimension — yuv420 chroma subsampling needs both axes even. */
-function evenDim(v: number): number {
+export function evenDim(v: number): number {
   return Math.max(2, 2 * Math.round(v / 2));
 }