@ossclip/core 0.1.24 → 0.1.26

package/src/config.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { ModelPrice } from "./producer/usage";
+import type { Theme } from "./scene-schema";
 
 /** Whether a finished `produce` offers to open the editor. */
 export type OpenEditorPref = "ask" | "always" | "never";
@@ -18,6 +19,24 @@ export interface OssclipConfig {
    * sheet always uses the main model. "same" disables tiering (FINDINGS §37).
    */
   fastModel?: string;
+  /**
+   * Download URLs for models the ggerganov mirror doesn't host, keyed by the
+   * bare model name — a user's own fine-tune needs one line:
+   * `"modelSources": {"my-model": "https://…/ggml-my-model.bin"}`. Wins over
+   * the curated table and the default mirror (`modelUrl` in the CLI's setup
+   * manifest). File-only like `dictionary`; validated at the consumer
+   * (`validModelSources`), so a hand-edited non-record is one warning and an
+   * ignored key, never a crash or a coerced URL.
+   */
+  modelSources?: Record<string, string>;
+  /**
+   * Default whisper language code ("ur", "auto", …) — the durable spelling
+   * of `--whisper-language` for someone whose recordings are always in one
+   * language. The flag beats this per run, and this beats the model table's
+   * implied language. File-only like `audience`; validated at the consumer
+   * (`resolveWhisperLanguage` in produce.ts), never coerced.
+   */
+  language?: string;
   /**
    * Who is in the video — "Ahsan, host of the Code with Ahsan channel".
    * Lets the repair pass recognise a mangled proper noun instead of inventing
@@ -38,7 +57,72 @@ export interface OssclipConfig {
    * `--watermark` / `--no-watermark` win over this per run.
    */
   watermark?: boolean;
+  /**
+   * Terms of art the speaker uses — "JSON", "ossclip", "Genkit" — biasing
+   * transcription (whisper `--prompt`), vouching repair corrections, and
+   * canonicalizing caption casing on every run (F4, 2026-08-16: "Jason" for
+   * JSON). `--dictionary` on a run wholesale replaces this, never merges.
+   * File-only like `watermark`; validated at the consumer
+   * (`validDictionary` in produce.ts), so a hand-edited non-array is one
+   * warning and an ignored key, never a crash or a coerced term.
+   */
+  dictionary?: string[];
+  /**
+   * Global base-theme overrides — caption/graphic colors and fonts applied to
+   * every run (F6, 2026-08-16). Partial on purpose: set `accent` alone and
+   * every other token keeps its default. Precedence per run:
+   * overrides.json (the editor's per-project doc) > this > defaultTheme.
+   * File-only; validated at the consumer (`configuredBaseTheme` in
+   * produce.ts) all-or-nothing, so one malformed key voids the whole theme
+   * with a warning instead of silently half-applying.
+   */
+  theme?: Partial<Theme>;
+  /**
+   * Run the `--youtube` pack (SEO metadata + AI thumbnail) on every produce,
+   * so the preference is a one-time config write like `watermark`.
+   * `--youtube` / `--no-youtube` win over this per run (`resolveYoutube`).
+   */
+  youtube?: boolean;
+  /**
+   * Path to the creator's portrait photo, fed to the AI thumbnail as the
+   * likeness reference — a path in the config like `browserExecutable`, set
+   * once rather than typed per run. `--portrait` wins over this. Existence
+   * is checked where the thumbnail is generated, not at load: an absent file
+   * there means a loud skip and the frame-grab cover stands.
+   */
+  portrait?: string;
+  /**
+   * Who watches the channel — "junior web devs learning AI tooling". Feeds
+   * BOTH the `--youtube` pack prompt (titles/tags for the right viewer) and
+   * the AI thumbnail's concept call, so it is set once here rather than
+   * retyped per run. `--audience` wins over this per run. File-only like
+   * `portrait`; validated at the consumer (`typeof === "string"` at use),
+   * never coerced.
+   */
+  audience?: string;
+  /**
+   * The durable thumbnail steer — "always show the terminal, never stock
+   * imagery". Fed to the AI thumbnail's concept call as a must-honor creator
+   * brief on every run. `--thumbnail-brief` wins over this per run.
+   * File-only like `audience`, validated the same way at use.
+   */
+  thumbnailBrief?: string;
+  /**
+   * Image model for the AI thumbnail (Y3). Overrides the built-in default
+   * slug; the GEMINI_API_KEY itself stays in the environment — secrets never
+   * live in config.json (env.ts's documented rule).
+   */
+  thumbnailModel?: string;
   browserExecutable?: string;
+  /**
+   * Browser tabs the render runs in parallel (2026-08-17 render-speed pass).
+   * Unset means cpus-2 with a floor of 2 — the render is decode-bound, and
+   * two cores stay free for OffthreadVideo's ffmpeg extract workers. File-only
+   * like `dictionary`; validated at the consumer (`resolveRenderConcurrency`
+   * in produce.ts) as a positive integer, so a hand-edited `"4"` or `-1` is
+   * one warning and the default, never a coerced tab count.
+   */
+  renderConcurrency?: number;
   /**
    * 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
@@ -122,6 +206,32 @@ export function loadConfig(): OssclipConfig {
     // resolveWatermark), so a hand-edited non-boolean stays OFF, the safe
     // default for a credit.
     watermark: fileCfg.watermark,
+    // 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` /
+    // `configuredBaseTheme` in produce.ts — where a malformed value earns a
+    // warning naming the problem and the safe default, never a coercion.
+    dictionary: fileCfg.dictionary,
+    theme: fileCfg.theme,
+    // File-only, the same posture: both are validated where they are USED —
+    // `validModelSources` / `resolveWhisperLanguage` — so a hand-edited
+    // non-record or non-string earns one warning there, never a coercion.
+    modelSources: fileCfg.modelSources,
+    language: fileCfg.language,
+    // File-only, the `watermark` posture again: `youtube` gets the strict
+    // `=== true` check at its consumer (produce's resolveYoutube), and
+    // `portrait`/`thumbnailModel` are validated where they are USED — a
+    // malformed value earns a loud skip there, never a coercion here.
+    youtube: fileCfg.youtube,
+    // File-only, the `dictionary` posture: a structured value from hand-edited
+    // JSON, validated where it is USED (`resolveRenderConcurrency`) — a
+    // malformed count earns one warning there and the cpus-2 default, never a
+    // coerced concurrency.
+    renderConcurrency: fileCfg.renderConcurrency,
+    portrait: fileCfg.portrait,
+    audience: fileCfg.audience,
+    thumbnailBrief: fileCfg.thumbnailBrief,
+    thumbnailModel: fileCfg.thumbnailModel,
     pricing: fileCfg.pricing,
   };
 }

package/src/content-rect-detect.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { run } from "./exec";
 import {
   contentRectTimeline,
+  materializeTimeline,
   parseCropdetect,
   pickTransition,
   type ContentRect,
@@ -70,7 +71,7 @@ export async function detectContentRect(
       timeline?: ContentRectSegment[];
     };
     if (cached.version === CACHE_VERSION && cached.timeline?.length) {
-      return withUniform(cached.timeline);
+      return withUniform(cached.timeline, probe);
     }
   }
 
@@ -95,7 +96,7 @@ export async function detectContentRect(
   if (cachePath) {
     await writeFile(cachePath, JSON.stringify({ version: CACHE_VERSION, timeline }, null, 2));
   }
-  return withUniform(timeline);
+  return withUniform(timeline, probe);
 }
 
 /** How far around a coarse boundary the refinement pass looks. Must exceed the
@@ -152,8 +153,19 @@ async function refineBoundaries(
   }
 }
 
-function withUniform(timeline: ContentRectSegment[]): ContentRectDetection {
-  return { timeline, uniform: timeline.length === 1 ? timeline[0]!.rect : null };
+function withUniform(
+  timeline: ContentRectSegment[],
+  probe: { width: number; height: number; duration: number },
+): ContentRectDetection {
+  // Materialize BEFORE the single-segment uniform test, and on the cache-hit
+  // path too: the cache stores the RAW measurement, so re-judging it here is
+  // what lets the 2026-08-16 incident's cached content-rect.json re-classify
+  // as uniform on replay without a CACHE_VERSION bump (no re-measure).
+  const materialized = materializeTimeline(timeline, probe.width, probe.height, probe.duration);
+  return {
+    timeline: materialized,
+    uniform: materialized.length === 1 ? materialized[0]!.rect : null,
+  };
 }
 
 /** Total source seconds the framing is NOT the full frame — for reporting. */

package/src/content-rect.ts

@@ -153,6 +153,75 @@ export interface ContentRectSegment {
   rect: ContentRect;
 }
 
+/**
+ * One stretch of the RENDER-TIME framing plan — the props-based successor to
+ * the destructive normalization bake (2026-08-16 incident: the bake's crop
+ * could only be undone by deleting the re-encoded file; expressed as data,
+ * the same window renders as a transform the editor can see and counteract).
+ * Emitted into render-props.json as `framingTimeline`; absent means "no plan"
+ * and every pre-existing render-props renders unchanged.
+ */
+export interface FramingSegment {
+  /** Source seconds — intersects the content timeline and kept spans directly. */
+  startSec: number;
+  endSec: number;
+  /** Crop window in SOURCE pixels, all windows sharing one aspect. */
+  window: { x: number; y: number; w: number; h: number };
+  /** What the window is anchored on; "screen" windows are centered clips. */
+  subject: "face" | "screen";
+  /** The subject's anchor point inside the window, 0..1 both axes. */
+  bias: { x: number; y: number };
+}
+
+/**
+ * Rescale framing windows from TRUE source pixels into the pixel space of a
+ * display-sized mezzanine (2026-08-17 render-speed pass). `planNormalization`
+ * keeps working in true source pixels — analysis runs on the source — and
+ * the render-props emission scales the windows so window space === the space
+ * of the file the render actually plays. Per-axis factors, not one scalar:
+ * yuv420 even-rounding makes the two axes' ratios differ by a fraction of a
+ * percent, and scaling both by one axis's factor could push a right-edge
+ * window past the scaled file's width. Times, subject and bias are
+ * scale-invariant and pass through untouched.
+ */
+export function scaleFramingWindows(
+  timeline: readonly FramingSegment[],
+  factor: { x: number; y: number },
+): FramingSegment[] {
+  return timeline.map((s) => ({
+    ...s,
+    window: {
+      x: s.window.x * factor.x,
+      y: s.window.y * factor.y,
+      w: s.window.w * factor.x,
+      h: s.window.h * factor.y,
+    },
+  }));
+}
+
+/**
+ * The same rescale for the fit-fallback's content timeline — its rects are
+ * source pixels too, and they reach the renderer only alongside a
+ * `sourceSize` that must describe the played file (see the render-props
+ * emission in produce.ts). `full` survives the scale: it means "this rect IS
+ * the whole frame", which a uniform resample does not change.
+ */
+export function scaleContentTimeline(
+  timeline: readonly ContentRectSegment[],
+  factor: { x: number; y: number },
+): ContentRectSegment[] {
+  return timeline.map((s) => ({
+    ...s,
+    rect: {
+      ...s.rect,
+      x: s.rect.x * factor.x,
+      y: s.rect.y * factor.y,
+      w: s.rect.w * factor.x,
+      h: s.rect.h * factor.y,
+    },
+  }));
+}
+
 /**
  * A framing run must survive BOTH of these to be believed. Together they are
  * what replaces the union rule's protection (PLAN Task C, step C2).
@@ -270,6 +339,148 @@ export function contentRectTimeline(
   }));
 }
 
+/**
+ * Materiality thresholds (2026-08-16 landscape screen-recording over-crop — a
+ * 72px dark strip (2.08% inset, 1px past SNAP_FRAC's 69.1px tolerance) plus a
+ * 15.4s/1435s outlier segment destroyed 55% of the picture).
+ *
+ * SNAP_FRAC decides whether a bar is worth TRIMMING; this bound decides
+ * whether a rect difference is worth calling a FRAMING CHANGE — a far more
+ * destructive claim, because a mixed-framing verdict sends the whole take
+ * into normalization. The incident's jitter measured 2.0–2.3% per side, so
+ * the bound sits at 3.5%: comfortably above jitter, comfortably below any
+ * real letterbox (the motivating 144bbfb strip insets 34% per side).
+ */
+export const MATERIAL_INSET_FRAC = 0.035;
+
+/**
+ * A rect keeping at least this share of the frame's area, at (within
+ * MATERIAL_ASPECT_TOL of) the frame's own aspect, is the frame minus
+ * measurement noise — treating it as a distinct framing would re-crop every
+ * downstream geometry to chase pixels nobody can see missing.
+ */
+export const MATERIAL_AREA_FRAC = 0.92;
+const MATERIAL_ASPECT_TOL = 0.05;
+
+/**
+ * A framing class — every segment sharing one rect, contiguous or not —
+ * totalling under this share of the runtime is an anomaly, not a framing
+ * change. MIN_RUN_SEC only guards a single run; the incident's 15.4s outlier
+ * (1.1% of 1435s) sailed past it and single-handedly set the canvas aspect
+ * for the whole take.
+ */
+export const MIN_FRAMING_CLASS_FRAC = 0.05;
+
+/**
+ * Re-judge a measured timeline against what a framing change must AMOUNT TO
+ * before it is believed (2026-08-16 incident above).
+ *
+ * Two passes. First, per segment: a rect whose every side inset is under
+ * MATERIAL_INSET_FRAC, or that keeps MATERIAL_AREA_FRAC of the frame at the
+ * frame's own aspect, is reclassified as the full frame — it differs from the
+ * frame by less than a framing change is worth. Second, per CLASS: framing
+ * classes totalling under MIN_FRAMING_CLASS_FRAC of the runtime are absorbed
+ * into their longer neighbour, same shape as the run-absorption loop in
+ * `contentRectTimeline` (drop one, retry until stable, then merge agreeing
+ * neighbours). A uniform source comes out as exactly one segment.
+ *
+ * Pure — applied on top of the cached raw timeline, so an already-measured
+ * source re-classifies on replay without a cache version bump.
+ */
+export function materializeTimeline(
+  timeline: readonly ContentRectSegment[],
+  width: number,
+  height: number,
+  durationSec: number,
+): ContentRectSegment[] {
+  if (timeline.length === 0 || width <= 0 || height <= 0) {
+    return timeline.map((s) => ({ ...s }));
+  }
+  const whole: ContentRect = { x: 0, y: 0, w: width, h: height, full: true };
+  const frameAspect = width / height;
+
+  const immaterial = (r: ContentRect): boolean => {
+    if (r.full) return true;
+    const insets = [
+      r.x / width,
+      r.y / height,
+      (width - (r.x + r.w)) / width,
+      (height - (r.y + r.h)) / height,
+    ];
+    if (insets.every((f) => f < MATERIAL_INSET_FRAC)) return true;
+    const areaFrac = (r.w * r.h) / (width * height);
+    const aspectDelta = Math.abs(r.w / r.h - frameAspect) / frameAspect;
+    return areaFrac >= MATERIAL_AREA_FRAC && aspectDelta < MATERIAL_ASPECT_TOL;
+  };
+
+  const segs = timeline.map((s) => ({
+    startSec: s.startSec,
+    endSec: s.endSec,
+    rect: immaterial(s.rect) ? whole : s.rect,
+  }));
+
+  // Duration of each segment's whole CLASS — the outlier that motivated this
+  // appeared as one contiguous run, but a strip flickering in and out would
+  // split into several, and each alone dodging the threshold must not let the
+  // class as a whole survive.
+  const classTotals = (list: typeof segs): number[] => {
+    const reps: ContentRect[] = [];
+    const totals: number[] = [];
+    const ids = list.map((s) => {
+      let id = reps.findIndex((r) => sameFraming(r, s.rect, width, height));
+      if (id === -1) {
+        id = reps.length;
+        reps.push(s.rect);
+        totals.push(0);
+      }
+      totals[id]! += s.endSec - s.startSec;
+      return id;
+    });
+    return ids.map((id) => totals[id]!);
+  };
+
+  // Absorb, then retry until stable: dropping one segment changes its
+  // neighbours' class totals and can make them adjacent and mergeable.
+  let changed = true;
+  while (changed && segs.length > 1) {
+    changed = false;
+    const totals = classTotals(segs);
+    for (let i = 0; i < segs.length; i++) {
+      if (totals[i]! >= MIN_FRAMING_CLASS_FRAC * durationSec) continue;
+      const r = segs[i]!;
+      // Absorb into the LONGER neighbour — the one more likely to be the truth.
+      const prev = segs[i - 1];
+      const next = segs[i + 1];
+      const into = !prev
+        ? next
+        : !next
+          ? prev
+          : prev.endSec - prev.startSec >= next.endSec - next.startSec
+            ? prev
+            : next;
+      if (!into) continue;
+      into.startSec = Math.min(into.startSec, r.startSec);
+      into.endSec = Math.max(into.endSec, r.endSec);
+      segs.splice(i, 1);
+      changed = true;
+      break;
+    }
+  }
+
+  // Merge neighbours that now agree, so a source whose every segment was
+  // reclassified collapses to the single-segment (uniform) shape callers test.
+  const merged: typeof segs = [];
+  for (const s of segs) {
+    const last = merged[merged.length - 1];
+    if (last && sameFraming(last.rect, s.rect, width, height)) {
+      last.endSec = Math.max(last.endSec, s.endSec);
+    } else {
+      merged.push({ ...s });
+    }
+  }
+  return merged;
+}
+
 /**
  * The exact framing-change instant inside a densely-sampled window
  * (NORMALIZE plan, boundary refinement).

package/src/cover.ts

@@ -136,9 +136,17 @@ export function laplacianVariance(pixels: Uint8Array, w: number, h: number): num
 }
 
 /**
- * Score a candidate. A face is close to mandatory — a cover without the
- * speaker is a cover for a different video — and among frames that have one,
- * sharpness decides. Earlier frames win ties so the cover matches the opening.
+ * Score a candidate. On a "face" take a face is close to mandatory — a cover
+ * without the speaker is a cover for a different video — and among frames
+ * that have one, sharpness decides. Earlier frames win ties so the cover
+ * matches the opening.
+ *
+ * On a "screen" take the face weight drops to ZERO (2026-08-16): a Facebook
+ * reel playing inside a 21-minute screen recording put a STRANGER'S face on
+ * the cover, because face×2 hunts any face at all and on a screen-subject
+ * take every face in frame is content, not the speaker. Sharpness and
+ * earliness alone pick that cover. Default "face" so portrait/talking-head
+ * runs score exactly as before.
  */
 export function scoreCandidate(c: {
   timeSec: number;
@@ -146,11 +154,13 @@ export function scoreCandidate(c: {
   sharpness: number;
   hasFace: boolean;
   maxSharpness: number;
+  subject?: "face" | "screen";
 }): number {
+  const faceWeight = c.subject === "screen" ? 0 : 2;
   const face = c.hasFace ? 1 : 0;
   const sharp = c.maxSharpness > 0 ? c.sharpness / c.maxSharpness : 0;
   const earliness = 1 - Math.min(1, c.timeSec / Math.max(1e-6, c.durationSec));
-  return face * 2 + sharp + earliness * 0.3;
+  return face * faceWeight + sharp + earliness * 0.3;
 }
 
 export interface PickCoverOptions {
@@ -172,6 +182,12 @@ export interface PickCoverOptions {
    * canvas that is two-thirds baked-in black bar.
    */
   cropVf?: string;
+  /**
+   * The take's whole-frame subject (`faceSubject`'s verdict). "screen" zeroes
+   * the face weight in `scoreCandidate` — see its doc comment for the
+   * 2026-08-16 stranger's-face incident. Default "face".
+   */
+  subject?: "face" | "screen";
 }
 
 /**
@@ -229,7 +245,7 @@ export async function pickCoverFrame(
   for (const r of raw) {
     candidates.push({
       ...r,
-      score: scoreCandidate({ ...r, durationSec: window, maxSharpness }),
+      score: scoreCandidate({ ...r, durationSec: window, maxSharpness, subject: opts.subject }),
     });
   }
   candidates.sort((a, b) => b.score - a.score);

package/src/cutlist.ts

@@ -42,6 +42,18 @@ const SILENCE_PAD_IN = 0.06;
 const SILENCE_PAD_OUT = 0.1;
 /** Kept fragments shorter than this (holding no word) are folded into the cut. */
 const MIN_KEEP = 0.25;
+/**
+ * A WORDED kept gap up to this long is still folded when a flanking removal
+ * is a `retake` cut (2026-08-16 incident): whisper stamped a debris "And" at
+ * 670.0–670.4 between a marker-terminated blooper cut and the silence cut
+ * that followed, and `hasProtectedWordInside` — correctly — refused the
+ * wordless fold, so a 0.4s one-word sliver of an abandoned sentence shipped
+ * as a choppy blip. A retake cut already means "this whole attempt is
+ * unusable", so a sub-0.35s word fragment glued to it is debris of that same
+ * attempt, not content. Silence/silence neighbors get NO such license: their
+ * worded gaps stay protected exactly as §124's follow-up demands.
+ */
+const MIN_KEEP_AFTER_RETAKE = 0.35;
 
 interface Removal {
   start: number;
@@ -74,8 +86,19 @@ export interface BuildCutlistArgs {
    * still has no judgement of its own about what a bad take looks like, it
    * just folds whichever spans two independent detectors handed it into the
    * one partition.
+   *
+   * `confidence` optionally overrides the 0.9 default below — the
+   * exact-prefix restart rule (retake.ts, RESTART_PREFIX_CONFIDENCE) earns
+   * 0.85, one notch less than a full similarity match, and the caller is the
+   * one who knows which rule found the span.
    */
-  retakes?: readonly { startWord: number; endWord: number; startSec: number; endSec: number }[];
+  retakes?: readonly {
+    startWord: number;
+    endWord: number;
+    startSec: number;
+    endSec: number;
+    confidence?: number;
+  }[];
 }
 
 export function buildCutlist({
@@ -88,9 +111,9 @@ export function buildCutlist({
 }: BuildCutlistArgs): Segment[] {
   const keepAll: Segment[] = [{ srcIn: 0, srcOut: duration, kind: "keep" }];
   // `exact` means exact: it is the escape hatch for "touch nothing", and a
-  // blooper or retake cut is still a cut. --blooper-marker or
-  // --collapse-retakes with --cleanup exact is a contradiction, and the flag
-  // the user typed second does not get to win.
+  // blooper or retake cut is still a cut. --blooper-marker (which also
+  // switches on retake collapse, 2026-08-16 gate) with --cleanup exact is a
+  // contradiction, and the flag the user typed second does not get to win.
   if (level === "exact") return keepAll;
   const policy = POLICIES[level];
   const words = transcript.words;
@@ -126,7 +149,7 @@ export function buildCutlist({
       start: r.startSec,
       end: r.endSec,
       reason: "retake",
-      confidence: 0.9,
+      confidence: r.confidence ?? 0.9,
       source: "acoustic",
     });
   }
@@ -268,7 +291,16 @@ export function buildCutlist({
     const overlapping = prev !== undefined && gap <= 1e-6;
     const wordless = prev !== undefined && !hasProtectedWordInside(prev.end, r.start);
     const foldableGap = wordless && gap <= Math.max(MIN_KEEP, policy.pauseMin);
-    if (prev && (overlapping || foldableGap)) {
+    // The one exception to word protection (MIN_KEEP_AFTER_RETAKE's why): a
+    // worded sliver this short survives only between two cuts, and when one
+    // of those cuts is a retake the sliver is debris of the discarded
+    // attempt. Requires the retake FLANK, not just the length — a worded gap
+    // between two silence removals must never fold, whatever its size.
+    const retakeSliver =
+      prev !== undefined &&
+      gap <= MIN_KEEP_AFTER_RETAKE &&
+      (prev.reason === "retake" || r.reason === "retake");
+    if (prev && (overlapping || foldableGap || retakeSliver)) {
       const prevDur = prev.end - prev.start;
       const curDur = r.end - r.start;
       prev.end = Math.max(prev.end, r.end);

package/src/dictionary.ts

@@ -0,0 +1,56 @@
+import type { Transcript } from "./schema";
+
+/**
+ * Deterministic casing for the user's dictionary (F4, 2026-08-16).
+ *
+ * Whisper biasing and the LLM repair pass get a word's SPELLING right; what
+ * neither guarantees is its CASE — a decoder nudged into "json" has still
+ * lost the acronym. This pass is the deterministic last word: any token that
+ * IS a dictionary term (exact case-insensitive match, punctuation aside)
+ * takes the term's canonical casing.
+ *
+ * Deliberately exact-match only: "Jason" is NEVER touched, even with "JSON"
+ * in the dictionary — deciding that a different word is a mishearing of a
+ * term is phonetic judgement, and that is the LLM repair pass's job, behind
+ * its guards. A deterministic pass that rewrote near-misses would be the
+ * un-gated rewrite pass §17 exists to forbid.
+ *
+ * Not on the browser surface: only `produce` runs it, and keeping it out of
+ * browser.ts keeps the Remotion bundle's import graph untouched.
+ */
+
+/**
+ * The same leading/trailing bounds `normalizeToken` (analyze.ts) strips, but
+ * keeping the pieces: the punctuation must survive the swap ("json." →
+ * "JSON.", quotes and commas intact), so the strip is a split here, not a
+ * deletion.
+ */
+const TOKEN_BOUNDS = /^([^\p{L}\p{N}]*)([\s\S]*?)([^\p{L}\p{N}-]*)$/u;
+
+export function canonicalizeDictionaryCasing(
+  transcript: Transcript,
+  dictionary: readonly string[],
+): Transcript {
+  // Keyed on the term's own lowercase, valued with its typed casing. A later
+  // duplicate (differing only in case) loses to the first — the user's list
+  // order is the only precedence signal there is.
+  const canonical = new Map<string, string>();
+  for (const raw of dictionary) {
+    const term = raw.trim();
+    const key = term.toLowerCase();
+    if (term && !canonical.has(key)) canonical.set(key, term);
+  }
+  if (canonical.size === 0) return transcript;
+  return {
+    ...transcript,
+    words: transcript.words.map((w) => {
+      const [, lead = "", core = "", trail = ""] = TOKEN_BOUNDS.exec(w.text) ?? [];
+      const want = canonical.get(core.toLowerCase());
+      // `want !== core` also guards the degenerate empty core; strict
+      // equality-of-lowercase above means this is a CASING change only —
+      // never a respelling, never added punctuation.
+      if (want === undefined || want === core) return w;
+      return { ...w, text: `${lead}${want}${trail}` };
+    }),
+  };
+}

package/src/export-premiere-project.ts

@@ -39,22 +39,34 @@ export interface PremiereProjectInput {
   zoomPlan: readonly ZoomSegment[];
   /** render-props' flag: true disables BOTH motion layers (zoom AND punch). */
   staticCamera?: boolean;
+  /**
+   * render-props' `punch` — the face-only jump-cut plan (2026-08-16, scenes'
+   * punch-plan.ts): its scale replaces the legacy 1.07 and its mask gates
+   * which spans punch. Absent means the LEGACY contract, so a pre-feature
+   * workdir exports exactly the camera its render had.
+   */
+  punch?: { scale: number; allowed: readonly boolean[] } | null;
   /** The OUTPUT frame (production.render), e.g. 1080×1920. */
   frame: { width: number; height: number };
 }
 
 /**
- * The render's jump-cut concealer, replicated from EdlVideo.tsx:41-51 — the
- * alternating toggle, the srcIn−prev.srcOut gap, and the INCLUSIVE >=
- * threshold must all match, or the exported project punches different clips
- * than the render did. Defaults mirror EdlVideoProps; they are parameters so
- * a drift in either place shows up as a failing hand-computed test, not a
- * silent divergence.
+ * The render's jump-cut concealer, replicated from scenes' `punchScalesFor`
+ * (punch-plan.ts, the loop EdlVideo renders) — the alternating toggle, the
+ * srcIn−prev.srcOut gap, and the INCLUSIVE >= threshold must all match, or
+ * the exported project punches different clips than the render did. The
+ * `allowed` mask must match too, down to the parity rule: the toggle flips
+ * on EVERY qualifying gap, masked spans included (stable indexing), and a
+ * masked span renders its punched turn at 1. `allowed[i] !== false` so a
+ * short mask reads as allowed, same as no mask at all. Defaults mirror
+ * EdlVideoProps; they are parameters so a drift in either place shows up as
+ * a failing hand-computed test, not a silent divergence.
  */
 export function punchScales(
   spans: readonly KeptSpan[],
   punchInScale = 1.07,
   punchThresholdSec = 0.15,
+  allowed?: readonly boolean[] | null,
 ): number[] {
   const out: number[] = [];
   let punched = false;
@@ -62,7 +74,7 @@ export function punchScales(
     const prev = spans[i - 1];
     const gap = prev ? spans[i]!.srcIn - prev.srcOut : 0;
     if (i > 0 && gap >= punchThresholdSec) punched = !punched;
-    out.push(punched ? punchInScale : 1);
+    out.push(punched && (!allowed || allowed[i] !== false) ? punchInScale : 1);
   }
   return out;
 }
@@ -174,7 +186,7 @@ export function srtFromCaptionLines(lines: readonly SrtLine[]): string {
 const fmt = (n: number): string => String(Number(n.toFixed(4)));
 
 export function buildPremiereProject(input: PremiereProjectInput): { xml: string; srt: string } {
-  const { production, spans, captionLines, zoomPlan, staticCamera, frame } = input;
+  const { production, spans, captionLines, zoomPlan, staticCamera, punch, frame } = input;
   const { path, probe } = production.source;
   // The whole document runs at the SOURCE rate (the marker exporter's
   // precedent): clip in/out and sequence start/end share one timebase, so no
@@ -189,7 +201,12 @@ export function buildPremiereProject(input: PremiereProjectInput): { xml: string
   const cover = coverTransform(probe, production.source.face, frame);
   // staticCamera kills BOTH motion drivers (produce's render-props contract:
   // zoomPlan alone can't reach the punch) — cover-crop is all that remains.
-  const punches = staticCamera ? spans.map(() => 1) : punchScales(spans);
+  // Otherwise the punch plan's scale and mask apply when present; `punch?.`
+  // collapses both absent and null to undefined, which punchScales reads as
+  // the legacy 1.07-everywhere the render itself falls back to.
+  const punches = staticCamera
+    ? spans.map(() => 1)
+    : punchScales(spans, punch?.scale, undefined, punch?.allowed);
 
   // Per-clip frame geometry. A sub-frame span still occupies one frame on
   // both axes — a zero-length clipitem is undefined importer behavior, same