@ossclip/core 0.1.34 → 0.1.36

package/src/ingest.ts

@@ -190,11 +190,56 @@ export function mezzanineScale(
  * the legacy names so existing workdir caches stay valid; a scaled run
  * rebuilds once under its own name and old workdirs' render-props keep
  * referencing (and rendering from) the file they were emitted against.
+ *
+ * The LUT hash is in the name for the same reason: grading is baked into the
+ * mezzanine at build time, so a warm workdir keyed only on crop/scale would
+ * satisfy a graded run with UNGRADED frames (or a re-graded run with the old
+ * look). No LUT keeps today's names byte-for-byte, so existing warm workdirs
+ * stay valid.
  */
-export function mezzanineFileName(cropped: boolean, scale: MezzanineScale | null): string {
+export function mezzanineFileName(cropped: boolean, scale: MezzanineScale | null, lutHash?: string): string {
   const base = cropped ? "mezzanine-content" : "mezzanine";
-  if (!scale) return `${base}.mp4`;
-  return `${base}-${scale.width}x${scale.height}@${Math.round(scale.fps)}.mp4`;
+  const scaleSeg = scale ? `-${scale.width}x${scale.height}@${Math.round(scale.fps)}` : "";
+  const lutSeg = lutHash ? `-lut${lutHash}` : "";
+  return `${base}${scaleSeg}${lutSeg}.mp4`;
+}
+
+/** A 3D LUT to bake into the mezzanine; `hash` keys the cache (see `mezzanineFileName`). */
+export interface MezzanineLut {
+  path: string;
+  hash: string;
+}
+
+/**
+ * Escape a filesystem path for use as an ffmpeg filter option value.
+ *
+ * A `-vf` string is parsed twice: once as a filtergraph (where `\` `'` `[`
+ * `]` `,` `;` are special) and once as the filter's option value (where `:`
+ * `\` `'` are special — `:` is the option separator, so an unescaped drive
+ * letter like `C:` truncates the path there). Each level strips one layer of
+ * backslashes, so the option-level escapes must themselves be escaped for
+ * the graph level: `:` → `\\:`, `'` → `\\\'`, `\` → `\\\\`. Spaces need
+ * nothing — the argv goes straight to ffmpeg, no shell in between.
+ */
+export function escapeFilterPath(p: string): string {
+  // Level 1: filter option value — `:` `\` `'` are special.
+  const option = p.replace(/[\\':]/g, (c) => `\\${c}`);
+  // Level 2: filtergraph — escape again so level-1 backslashes survive.
+  return option.replace(/[\\'[\],;]/g, (c) => `\\${c}`);
+}
+
+/**
+ * The mezzanine's `-vf` chain, pure so the ordering contract is testable:
+ * LUT strictly AFTER crop/scale — grading the letterbox bars would be
+ * wasted math, and grading pre-scale pixels the render never sees changes
+ * nothing but costs full-res per-pixel lookups.
+ */
+export function mezzanineVf(opts: { cropVf?: string; scale?: MezzanineScale; lut?: MezzanineLut }): string {
+  return [
+    ...(opts.cropVf ? [opts.cropVf] : []),
+    ...(opts.scale ? [`scale=${opts.scale.width}:${opts.scale.height}`] : []),
+    ...(opts.lut ? [`lut3d=file=${escapeFilterPath(opts.lut.path)}:interp=tetrahedral`] : []),
+  ].join(",");
 }
 
 /**
@@ -206,17 +251,15 @@ export function mezzanineFileName(cropped: boolean, scale: MezzanineScale | null
  *
  * `scale` (from `mezzanineScale`) downsizes to display size in the SAME
  * pass, crop first — the scale dims are computed on the post-crop picture.
+ * `lut` bakes a 3D grade in last, on exactly the pixels the render will see.
  */
 export async function makeMezzanine(
   tools: IngestTools,
   src: string,
   out: string,
-  opts: { cropVf?: string; scale?: MezzanineScale } = {},
+  opts: { cropVf?: string; scale?: MezzanineScale; lut?: MezzanineLut } = {},
 ): Promise<void> {
-  const vf = [
-    ...(opts.cropVf ? [opts.cropVf] : []),
-    ...(opts.scale ? [`scale=${opts.scale.width}:${opts.scale.height}`] : []),
-  ].join(",");
+  const vf = mezzanineVf(opts);
   await run(tools.ffmpegPath, [
     "-y", "-i", src,
     ...(vf ? ["-vf", vf] : []),

package/src/lut-library.ts

@@ -0,0 +1,81 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { CONFIG_DIR } from "./config";
+import { parseCubeLut } from "./color-grade";
+
+/**
+ * The user's .cube LUT directory, discovered — the `sfx-pack.ts` shape for
+ * color grades. `parseCubeLut` stays pure; this module is the thin fs layer
+ * that walks `~/.ossclip/luts` and reports, per file, either a usable LUT or
+ * the reason it is not one. Nothing here throws: a hand-dropped .cube is user
+ * input, and a broken one must cost that one menu entry, not the editor.
+ */
+
+/** Where user LUTs live: `~/.ossclip/luts/<name>.cube`. */
+export function userLutDir(): string {
+  return join(CONFIG_DIR, "luts");
+}
+
+/** One LUT the menu can offer. `path` stays server-side, like SFX `absPath`. */
+export interface LutLibraryItem {
+  /** The filename stem — what `ColorGrade.lut` (basename) resolves against. */
+  id: string;
+  /** The .cube's own TITLE when it has one, else the stem. */
+  title: string;
+  /** Absolute path — the caller's I/O concern, never sent to a client. */
+  path: string;
+}
+
+/** Why one file is not in the library — `SfxPackIssue`'s shape, per file. */
+export interface LutLibraryIssue {
+  /** The .cube filename (basename) that failed. */
+  file: string;
+  message: string;
+}
+
+export interface LutLibrary {
+  items: LutLibraryItem[];
+  issues: LutLibraryIssue[];
+}
+
+/**
+ * Every parseable `.cube` under `dir`, plus an issue per file that is not one.
+ * Each file is fully parsed here — not just listed — because the menu is the
+ * ONLY surface where a broken LUT can be reported before a render silently
+ * drops it: `parseCubeLut` is strict about content on purpose, and offering a
+ * file the bake will refuse is the exact mismatch the SFX library gate exists
+ * to avoid.
+ *
+ * A missing directory is the normal case (most users never drop a LUT), not
+ * an issue. `dir` is a parameter with a default rather than a `homedir()`
+ * read inside, so tests point it at a tmp dir and never touch a real home
+ * (`loadSfxLibrary`'s rule).
+ */
+export function loadLutLibrary(dir: string = userLutDir()): LutLibrary {
+  let names: string[] = [];
+  try {
+    names = readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.toLowerCase().endsWith(".cube"))
+      .map((e) => e.name)
+      // Sorted so the menu reads the same on every machine — readdir order is
+      // not a promise (loadSfxLibrary's merge-order rule).
+      .sort();
+  } catch {
+    return { items: [], issues: [] };
+  }
+  const items: LutLibraryItem[] = [];
+  const issues: LutLibraryIssue[] = [];
+  for (const name of names) {
+    const path = join(dir, name);
+    const stem = basename(name, extname(name));
+    try {
+      const lut = parseCubeLut(readFileSync(path, "utf8"));
+      // TITLE when the exporter wrote one — a human-readable label the stem
+      // (often `Vendor_Look_33pt_v2`) cannot match. Empty titles fall back.
+      items.push({ id: stem, title: lut.title?.trim() || stem, path });
+    } catch (e) {
+      issues.push({ file: name, message: e instanceof Error ? e.message : String(e) });
+    }
+  }
+  return { items, issues };
+}

package/src/overrides.ts

@@ -1,4 +1,5 @@
 import { z } from "zod/v4";
+import { ColorGradeSchema } from "./color-grade";
 import {
   LayoutSchema,
   SceneAnchorSchema,
@@ -9,7 +10,7 @@ import {
   type SceneComponentId,
   type Theme,
 } from "./scene-schema";
-import { RemovalReasonSchema } from "./schema";
+import { RemovalReasonSchema, type ProductionSfx } from "./schema";
 import type { TimeMap } from "./timemap";
 import { resolveSceneProps } from "./scene-registry";
 import type { CaptionLine, CaptionWord } from "./captions";
@@ -142,6 +143,19 @@ export const SceneOverrideSchema = z.object({
       dx: z.number().optional(),
       /** `false` switches the automatic idle-zoom layer off for this scene. */
       autoZoom: z.boolean().optional(),
+      /**
+       * Audio gain for this window's footage, 1 = as recorded (field report
+       * 2026-08-31: one concatenated clip was recorded quieter than the
+       * rest). Lives inside `video` on purpose — it is a property of this
+       * window's playback, and the key already merges per scene, inherits
+       * across split halves, and has patch/clear plumbing. 0 mutes. Above 1
+       * amplifies — in the render via allowAmplificationDuringRender, and in
+       * the preview via the Player's own WebAudio gain (Remotion ≥4.0.5xx,
+       * use-amplification). Max 4: a field clip arrived quiet enough that 2x
+       * did not reach its neighbours (2026-08-31); past 4x you are boosting
+       * noise floor, not speech.
+       */
+      volume: z.number().min(0).max(4).optional(),
     })
     .optional(),
   /**
@@ -443,9 +457,108 @@ export function mintSplitId(at: number, existing: readonly Split[]): string {
   }
 }
 
+/**
+ * The key an SFX edit is stored under: `${soundId}@${word}` of the PLANNED
+ * placement it edits.
+ *
+ * Content-derived, not positional, for §137's reason applied to a track of
+ * instants: an index into `production.json`'s `sfx.placements` is exactly the
+ * key a re-plan renumbers, and the placement a user muted would come back as
+ * the placement after it. The pair (which sound, which word) IS the identity
+ * of a placement — the plan cannot hold two of them (`normalizeSfxPlan`'s
+ * spacing pass drops the second effect within 1.5s, and two placements on one
+ * word are 0s apart) — so the key survives a re-plan whenever the placement
+ * itself does, and stales exactly when it does not.
+ *
+ * `@` is the separator the split-half namespace already uses (`splitCues`),
+ * and it is why an ADDED placement's id may not contain one (see
+ * `SfxAddedPlacementSchema`): the two namespaces share this record's
+ * vocabulary in the editor, and one spelling must never read as the other.
+ */
+export function sfxPlacementKey(placement: { soundId: string; word: number }): string {
+  return `${placement.soundId}@${placement.word}`;
+}
+
+/**
+ * One edited planned placement. Every field is optional and ABSENT MEANS
+ * "as planned" — this is a patch over the plan, not a replacement for it, so
+ * a user who only dragged a marker stores `{word}` and still inherits a later
+ * re-plan's gain for that sound.
+ *
+ * `muted` NEGATES a planned placement rather than deleting the entry (the
+ * plan's own record is in production.json and produce rewrites it every run,
+ * so there is nothing to delete there): the placement drops out of the render
+ * and the editor still has something to show as a restorable ghost, the
+ * `SceneOverrideSchema.hidden` contract. Restore DELETES the key rather than
+ * writing `muted: false` — an override with nothing to say (the
+ * clearVideo/restoreScene rule).
+ *
+ * `gain` shares the sound library's own 0–2 range (`SfxSoundSchema.gain`), and
+ * the two multiply at resolve time (`resolveSfxCues` does the ONE
+ * multiplication).
+ */
+export const SfxPlacementEditSchema = z.object({
+  /** Retimed to another transcript word — word indices, never seconds. */
+  word: z.number().int().nonnegative().optional(),
+  /** Swapped for another sound in the library. */
+  soundId: z.string().min(1).optional(),
+  gain: z.number().min(0).max(2).optional(),
+  muted: z.boolean().optional(),
+});
+export type SfxPlacementEdit = z.infer<typeof SfxPlacementEditSchema>;
+
+/**
+ * A placement the USER added, which the model never planned.
+ *
+ * It carries its own `id` because it has no plan entry to be keyed against:
+ * `${soundId}@${word}` would re-key itself the moment the user dragged or
+ * swapped it, and an array index would renumber on every delete —
+ * `mintSplitId`'s reasoning, and the id is a persisted name for the same
+ * reason (it must be reproducible from the doc alone, so it is minted once and
+ * never recomputed).
+ *
+ * The pattern forbids `@` deliberately: `sfxPlacementKey` builds planned keys
+ * with it, and an added id that could spell one would let a stale-key report
+ * name something that is not a plan key at all — the kept-takes rule ("minting
+ * `@` names here would collide with the split-id namespace"). It also forbids
+ * `/`, `.` and everything else that could read as a path: this id is a NAME,
+ * and nothing may ever resolve a file against it.
+ *
+ * Uniqueness is the minter's job, not the schema's: nothing in this module
+ * indexes by the id (an added placement is a plain array entry here), so a
+ * duplicate costs the editor a confused selection, and REFUSING the document
+ * would cost the user their whole edit layer — produce throws on an invalid
+ * overrides.json by design.
+ */
+export const SfxAddedPlacementSchema = z.object({
+  id: z.string().regex(/^[A-Za-z0-9_-]+$/),
+  soundId: z.string().min(1),
+  word: z.number().int().nonnegative(),
+  gain: z.number().min(0).max(2).optional(),
+});
+export type SfxAddedPlacement = z.infer<typeof SfxAddedPlacementSchema>;
+
 export const OverrideDocSchema = z.object({
   /** Global style tokens — the look is a system, so these are not per-element. */
   theme: ThemeSchema.partial().default({}),
+  /**
+   * Doc-global color grade — the `ColorGradeSchema` shape, or `false` for
+   * "explicitly no grade on this project". Doc-global like `theme`: a grade
+   * is one decision about the whole output, not a per-scene key. Optional
+   * with NO default (the `captionsHidden` rule) so every overrides.json
+   * written before the key existed parses byte-identically — but UNLIKE
+   * `captionsHidden`, an explicit `false` is meaningful and kept: it
+   * disables a config-level default grade for this one project, which
+   * deleting the key cannot express (absent means "let the flag, then the
+   * config, decide" — `resolveProductionColorGrade` in produce.ts owns that
+   * precedence). Schema-valid is not yet USABLE: an unknown preset id passes
+   * here (the schema cannot list what exists without going stale) and is
+   * caught by `resolveColorGrade` at the consumer, where it warns and falls
+   * through to the next layer instead of failing the whole doc. Timeless —
+   * no seconds anywhere — so `remapOverridesThroughRecut`'s `...doc` spreads
+   * carry it through a recut untouched.
+   */
+  colorGrade: z.union([ColorGradeSchema, z.literal(false)]).optional(),
   /**
    * Captions OFF for the whole video. Doc-global like `theme`, deliberately
    * NOT a per-scene key: visibility is one decision about the output —
@@ -729,6 +842,37 @@ export const OverrideDocSchema = z.object({
         .default([]),
     })
     .default({ reasons: {}, kept: [], dismissed: [] }),
+  /**
+   * The user's layer over the `--sfx` placement plan (2026-08-29): retime,
+   * swap, gain and mute on what the model planned, plus placements of the
+   * user's own. Applied by `applySfxOverrides` in produce, between loading the
+   * plan and resolving it to cues.
+   *
+   * ONE record, in overrides.json, and deliberately NOT a `sfx-reviewed.json`
+   * beside `scenes-reviewed.json`: scene review needed its own file because it
+   * predates the override doc, and SFX has this doc from day one. So there is
+   * exactly one write path (the editor's `PUT /api/overrides`) and exactly one
+   * thing a render replays.
+   *
+   * Optional with NO default, the `captionsHidden` rule: every overrides.json
+   * written before this key existed parses byte-identically, and a project
+   * that never touched a sound effect grows no key. Absent means "the plan, as
+   * planned".
+   *
+   * RECUT-IMMUNE BY CONSTRUCTION, so it deliberately has no entry in
+   * `remapOverridesThroughRecut` (the `cleanup.kept`/`captionLineWindows`
+   * property): every value in here is a WORD INDEX or an id, and
+   * `transcript.words` is never spliced — a re-cut moves output seconds, which
+   * this record does not hold. The output instant is re-derived through the
+   * new TimeMap on every run (`resolveSfxCues`).
+   */
+  sfx: z
+    .object({
+      /** Keyed by `sfxPlacementKey` — see `SfxPlacementEditSchema`. */
+      edits: z.record(z.string(), SfxPlacementEditSchema).default({}),
+      added: z.array(SfxAddedPlacementSchema).default([]),
+    })
+    .optional(),
 });
 export type OverrideDoc = z.infer<typeof OverrideDocSchema>;
 
@@ -2602,3 +2746,138 @@ export function reclampPinnedTiming(cues: readonly SceneCue[]): ReclampResult {
   }
   return { cues: out, adjusted };
 }
+
+/** A placement as `production.json` stores it — the editor-safe shape
+ * (`ProductionSfxSchema`), never the producer's: this module is in the
+ * EDITOR's runtime graph and `producer/sfx.ts` reaches node:child_process
+ * (schema.ts's ProductionSfxSchema docstring has the whole argument). */
+export type SfxPlannedPlacement = ProductionSfx["placements"][number];
+
+export interface AppliedSfxOverrides {
+  /** The plan the resolver should place — edits applied, mutes removed, the
+   * user's own placements appended. */
+  placements: SfxPlannedPlacement[];
+  /**
+   * Edit keys that matched no planned placement. `"stale key"` is the re-plan
+   * case: the placement the user edited is not in the plan any more, so their
+   * work on it is lost and saying so is the whole point (the `was`-guard
+   * posture — `applyCaptionEdits` reports rather than guessing at a nearby
+   * word, and the field failure §137 pins was a DROP nobody printed).
+   * `"duplicate key"` is a second placement answering to a key an earlier one
+   * already claimed: the edit applied, to the first, and the later one is left
+   * as planned rather than edited twice (`applyCaptionEdits`'
+   * `duplicate-anchor` rule).
+   *
+   * A plain TS union rather than a zod enum, unlike `SfxDropReasonSchema`:
+   * these reasons are computed here and printed, never written to a file and
+   * read back, so there is no boundary for a parse to guard.
+   */
+  dropped: Array<{ key: string; reason: "stale key" | "duplicate key" }>;
+}
+
+/**
+ * The user's SFX layer over a placement plan (`OverrideDocSchema.sfx`).
+ *
+ * Applied in produce between loading the plan and `resolveSfxCues`, so the
+ * resolver's word→output arithmetic, its cut-word drops and its gain product
+ * all run over what the USER approved rather than what the model wrote. The
+ * plan itself is never rewritten: `production.json` keeps the model's
+ * placements, which is what the edit keys are derived from — folding the edits
+ * into the stored plan would re-key every one of them on the next run and
+ * stale the user's whole layer (the same reason `cuts[].startSec` is left as
+ * the user drew it).
+ *
+ * Deliberately does NOT re-run the spacing or density passes
+ * (`normalizeSfxPlan`): those price the MODEL's plan, and a user who drags two
+ * effects together or adds a ninth to a `subtle` video has said what they want
+ * — an explicit user action outranks a deterministic budget, exactly as a user
+ * cut outranks a cleanup veto in produce. The resolver's own drops (unknown
+ * sound, missing file, cut word) still apply, because those are about whether
+ * the effect can be PLAYED at all.
+ *
+ * Pure: no filesystem, no library — an edit naming a sound that does not exist
+ * is the resolver's "unknown sound", reported there with every other one.
+ */
+export function applySfxOverrides(
+  planned: readonly SfxPlannedPlacement[],
+  sfx: OverrideDoc["sfx"],
+): AppliedSfxOverrides {
+  const dropped: AppliedSfxOverrides["dropped"] = [];
+  if (sfx === undefined) return { placements: [...planned], dropped };
+
+  const claimed = new Set<string>();
+  const placements: SfxPlannedPlacement[] = [];
+  for (const p of planned) {
+    const key = sfxPlacementKey(p);
+    const edit = sfx.edits[key];
+    if (edit === undefined) {
+      placements.push(p);
+      continue;
+    }
+    if (claimed.has(key)) {
+      dropped.push({ key, reason: "duplicate key" });
+      placements.push(p);
+      continue;
+    }
+    claimed.add(key);
+    // A mute keeps the ENTRY (the editor draws a restorable ghost from it) and
+    // removes the PLACEMENT — `SceneOverrideSchema.hidden`'s contract for a
+    // track of instants.
+    if (edit.muted === true) continue;
+    const retimed = edit.word !== undefined;
+    const next: SfxPlannedPlacement = {
+      ...p,
+      ...(edit.soundId !== undefined ? { soundId: edit.soundId } : {}),
+      ...(retimed ? { word: edit.word! } : {}),
+      ...(edit.gain !== undefined ? { gain: edit.gain } : {}),
+    };
+    // An explicit retime BREAKS the scene link (2026-08-29). `sceneId` says
+    // "fire when this graphic enters" — an intent the MODEL inferred — and a
+    // user dragging the marker onto a word says "fire HERE". An explicit user
+    // position outranks an inferred sync, the same doctrine that lets a user
+    // cut outrank a cleanup veto and a user's own placement outrank the
+    // density budget above. Without this the marker would snap back to the
+    // graphic on the next render and the drag would look like it never
+    // happened.
+    //
+    // It is also why `sfxPlacementKey` stays `${soundId}@${word}` and never
+    // takes `sceneId` into it: the key has to survive the link being cut, and
+    // a re-plan that keeps the sound and the word keeps the edit regardless of
+    // whether it re-linked the scene.
+    if (retimed) delete next.sceneId;
+    placements.push(next);
+  }
+  for (const key of Object.keys(sfx.edits)) {
+    if (!claimed.has(key)) dropped.push({ key, reason: "stale key" });
+  }
+
+  // The user's own placements, appended as plain placements: past this
+  // function an added effect is indistinguishable from a planned one, which is
+  // what makes the resolver, the stager and the accounting need no idea the
+  // override layer exists. The `id` does not travel — it names the doc entry
+  // the editor edits, and nothing downstream addresses a placement by name.
+  //
+  // No `sceneId` either, and `SfxAddedPlacementSchema` has no field for one:
+  // the user chose this word themselves, which is the same explicit-position
+  // fact the retime above cuts the link for.
+  for (const add of sfx.added) {
+    placements.push({
+      soundId: add.soundId,
+      word: add.word,
+      ...(add.gain !== undefined ? { gain: add.gain } : {}),
+    });
+  }
+
+  // Word order, stable: a retimed or added placement would otherwise sit where
+  // the model happened to put it, and the plan handed to the resolver is also
+  // what the accounting indexes into (`SfxValidationIssue.placement`) — a
+  // human reading a warning against production.json should meet the same order
+  // `normalizeSfxPlan` left the plan in.
+  return {
+    placements: placements
+      .map((p, i) => ({ p, i }))
+      .sort((a, b) => a.p.word - b.p.word || a.i - b.i)
+      .map((e) => e.p),
+    dropped,
+  };
+}

package/src/producer/index.ts

@@ -27,6 +27,7 @@ export * from "./provider";
 export * from "./usage";
 export * from "./beats";
 export * from "./youtube";
+export * from "./sfx";
 export * from "./caption-regen";
 export * from "./scene-props";
 export * from "./repair";

package/src/producer/mock.ts

@@ -26,7 +26,9 @@ export class MockProvider implements LlmProvider {
           ? // A deterministic no-op: the offline path must exercise the repair
             // call without inventing corrections a real provider would justify.
             req.schema.parse({ repairs: [] })
-          : this.sceneProps(req.user, req.schema, req.schemaName);
+          : req.schemaName === "sfx_plan"
+            ? this.sfxPlan(req.user, req.schema)
+            : this.sceneProps(req.user, req.schema, req.schemaName);
     // Estimated, and costing exactly nothing — but recorded, because the
     // offline path is first-class and "how big are the prompts this pipeline
     // sends" is worth answering without spending anything to find out.
@@ -77,6 +79,37 @@ export class MockProvider implements LlmProvider {
     return schema.parse(sheet);
   }
 
+  /**
+   * A scripted SFX plan (`--sfx`): the budget the prompt states, spread evenly
+   * across the take, cycling through the menu the prompt offered.
+   *
+   * Reads the MENU rather than naming sounds, so the fixture pipeline keeps
+   * working when the starter pack changes and so a `--sfx-level` below `meme`
+   * can never be handed a meme sound the menu withheld. Evenly spread because
+   * the deterministic gate is the point of the offline path: bunched
+   * placements would be eaten by the 1.5s spacing pass and the fixture would
+   * assert whatever survived rather than what was planned.
+   */
+  private sfxPlan<T>(user: string, schema: z.ZodType<T>): T {
+    // The `- <id>: <whenToUse>` menu lines only — the graphics plan's bullets
+    // read `- words [3..7] …`, which has no `<slug>:` head.
+    const ids = [...user.matchAll(/^- ([a-z0-9-]+): /gm)].map((m) => m[1]!);
+    const wordCount = (user.match(/\[\d+\]/g) ?? []).length;
+    const max = Number.parseInt(/Place AT MOST (\d+) sound effects/.exec(user)?.[1] ?? "0", 10);
+    const n = Math.min(Number.isFinite(max) ? max : 0, ids.length > 0 ? wordCount : 0);
+    const placements = [];
+    for (let k = 0; k < n; k++) {
+      placements.push({
+        soundId: ids[k % ids.length]!,
+        // Interior anchors (k+1 of n+1): word 0 is the hook's first syllable,
+        // and an effect on it fires before the viewer has heard anything.
+        word: Math.min(wordCount - 1, Math.floor(((k + 1) * wordCount) / (n + 1))),
+        rationale: `mock: evenly spaced placement ${k + 1} of ${n}`,
+      });
+    }
+    return schema.parse({ placements });
+  }
+
   private sceneProps<T>(_user: string, schema: z.ZodType<T>, schemaName: string): T {
     const canned: Record<string, unknown> = {
       TitleCard_props: { eyebrow: "MOCK", title: "THE RAW TAKE", emphasis: "861%", sub: "becomes a clean edit" },

package/src/producer/scene-props.ts

@@ -11,6 +11,24 @@ import {
   type FramingContext,
 } from "../framing";
 
+/**
+ * The id `generateScenes` mints for the scene a moment becomes.
+ *
+ * Exported because a SECOND caller depends on the formula now (2026-08-29):
+ * the SFX placement prompt offers these ids to the model so a whoosh can
+ * anchor to a graphic's ENTRANCE (`buildSfxUserPrompt`), and
+ * `normalizeSfxPlan` checks the ids that come back against them. Two copies
+ * of `scene-${i}` is exactly §154's two-copies failure — the prompt would
+ * offer ids the plan never mints, and every scene link would strip on
+ * arrival.
+ *
+ * The index is the MOMENT's, not a running scene counter: talking-head
+ * moments mint no scene, so scene ids are sparse by design.
+ */
+export function momentSceneId(momentIndex: number): string {
+  return `scene-${momentIndex}`;
+}
+
 export interface ScenePropsFailure {
   momentIndex: number;
   component: SceneComponentId;
@@ -186,7 +204,7 @@ export async function generateScenes(
       const fallbackTitle = moment.onScreenCopy.slice(0, 48) || "—";
       failures.push({ momentIndex: i, component, error: lastError, fellBackTo: "TitleCard" });
       scenes.push({
-        id: `scene-${i}`,
+        id: momentSceneId(i),
         anchor: { startWord: moment.startWord, endWord: moment.endWord },
         layout: SCENE_REGISTRY.TitleCard.defaultLayout,
         component: "TitleCard",
@@ -198,7 +216,7 @@ export async function generateScenes(
     }
 
     scenes.push({
-      id: `scene-${i}`,
+      id: momentSceneId(i),
       anchor: { startWord: moment.startWord, endWord: moment.endWord },
       layout,
       component,