ossclip 0.1.33 → 0.1.35

package/src/produce.ts

@@ -156,6 +156,8 @@ import {
   sliceTranscript,
   type Analysis,
   type AppliedRepair,
+  type BeatSheet,
+  BeatSheetSchema,
   type BeatsValidationIssue,
   type CleanupLevel,
   type ClipWindow,
@@ -166,7 +168,40 @@ import {
   AGY_PRINT_TIMEOUT,
   type Production,
   ossclipOutputPathFor,
+  resolveOutputFrame,
+  RESOLUTION_CHOICES,
+  smallestSource,
+  ResolutionChoiceSchema,
+  // The --sfx path (2026-08-29): the library loader, the placement call, its
+  // deterministic gate, and the resolver that turns word anchors into cues.
+  loadSfxLibrary,
+  sfxLibraryHash,
+  // The `sfxBundledPack` config gate. It lives in core, not beside `resolveSfx`
+  // below, because the edit server has to resolve it identically — its own
+  // doc-comment has the reason.
+  resolveSfxBundledPack,
+  generateSfxPlan,
+  resolveSfxCues,
+  // Scene id → final start second, the scene-anchored placements' clock
+  // (2026-08-29). Built from `sceneCues`, never from the raw plan.
+  sceneStartSeconds,
+  // The user's layer over that plan (Phase 3), and the schema the carried
+  // forward plan is parsed back through.
+  applySfxOverrides,
+  ProductionSfxSchema,
+  sfxStagedFile,
+  formatSfxAccounting,
+  SfxLevelSchema,
+  SfxPlanSchema,
+  SfxValidationIssueSchema,
+  SFX_PROMPT_VERSION,
+  type LoadedSfxSound,
+  type SfxCue,
+  type SfxLevel,
+  type SfxPlacement,
+  type SfxValidationIssue,
   type ProviderName,
+  type ResolutionChoice,
   type Scene,
   type SceneComponentId,
   type Segment,
@@ -256,6 +291,14 @@ export const TranscriptKeySchema = z.object({
    * runs) means "no biasing".
    */
   dictionary: z.array(z.string()).optional(),
+  /**
+   * Whether whisper ran its TRANSLATE task (`-tr`, 2026-08-29). It changes
+   * the decoded TEXT — Urdu speech comes back as English words — so it
+   * re-keys the cache exactly like the language does, or a warm workdir
+   * serves the Urdu-script transcript to a translate run. Absent (old key
+   * files) means "no translation", the `dictionary` contract.
+   */
+  translate: z.boolean().optional(),
 });
 export type TranscriptKey = z.infer<typeof TranscriptKeySchema>;
 
@@ -280,6 +323,9 @@ export function transcriptCacheReusable(
       // "" and absent both mean whisper's en default — program.ts rejects an
       // empty code, but a key file predating that guard must not wedge.
       (effective.language ?? "") === (requested.language ?? "") &&
+      // Absent and false are the same "no translation", so pre-flag key
+      // files reuse under a non-translate request.
+      (effective.translate ?? false) === (requested.translate ?? false) &&
       // ORDER-SENSITIVE by choice: the dictionary becomes whisper's --prompt
       // text verbatim, so a reordered list genuinely is a different decoder
       // input — treating it as equal would serve a transcript biased by a
@@ -401,6 +447,38 @@ export function existingProducerStamp(work: string): Production["producer"] | un
   }
 }
 
+/**
+ * The `sfx` plan the workdir's LAST run wrote, or undefined (Phase 3).
+ *
+ * This is how a `--scenes` replay keeps its sound design. The editor's Render
+ * pins the reviewed plan with `--scenes` and drops `--produce`
+ * (render-replay-args.ts), so the run never reaches the placement call — and
+ * the placement call is not what should decide, because the SCENES-REVIEWED
+ * doctrine says a render started from the editor must reproduce what the user
+ * reviewed. For SFX that reviewed state is exactly `production.json`'s plan
+ * plus `overrides.json`'s edits on top of it: re-placing would hand the user a
+ * different set of effects than the ones they just dragged, and skipping would
+ * hand them silence.
+ *
+ * Tolerant like `existingProducerStamp` above — a missing, unreadable or
+ * sfx-less file all mean "no prior sound design", which is what a first run
+ * says too. Parsed through `ProductionSfxSchema`, never cast: production.json
+ * is as hand-editable as anything else in the workdir, and a level of "MEME"
+ * must not reach the report as a level.
+ */
+export function priorSfxPlan(work: string): { level: SfxLevel; placements: SfxPlacement[] } | undefined {
+  try {
+    const raw = JSON.parse(readFileSync(join(work, "production.json"), "utf8")) as {
+      sfx?: unknown;
+    };
+    if (raw.sfx === undefined) return undefined;
+    const parsed = ProductionSfxSchema.safeParse(raw.sfx);
+    return parsed.success ? parsed.data : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function beatCacheKeyCandidates(
   parts: Omit<Parameters<typeof beatSheetCacheKey>[0], "providerName">,
   providerName: string,
@@ -537,6 +615,13 @@ export interface ProduceOptions {
    * decodes garbage (Urdu field test 2026-08-05).
    */
   whisperLanguage?: string;
+  /**
+   * `--whisper-translate`: whisper's TRANSLATE task (`-tr`) — non-English
+   * speech decoded straight to ENGLISH text. Distinct from
+   * `whisperLanguage`, which says what is SPOKEN; the two are passed
+   * together (whisper decodes better knowing the source language).
+   */
+  whisperTranslate?: boolean;
   /**
    * Vocabulary terms for this run (`--dictionary`, F4 2026-08-16), already
    * split/trimmed by the action. Wholesale beats the config's `dictionary`
@@ -584,6 +669,16 @@ export interface ProduceOptions {
    * platform chrome to dodge and a landscape source needs no cropping at all.
    */
   aspect?: "9:16" | "16:9";
+  /**
+   * `--resolution <height>`: how big the output actually renders. `auto`
+   * keeps what the source has (capped at 2160); an explicit height scales the
+   * 1080-wide composition to it. Already validated by commander (or by
+   * `ResolutionChoiceSchema` when it comes from the config), so this is a
+   * choice, never a raw string. `resolveOutputFrame` owns the math and the
+   * why; the value reaches THREE stages that would otherwise each pin 1080p:
+   * the folder-concat target, the mezzanine, and the render's own scale.
+   */
+  resolution?: ResolutionChoice;
   /**
    * `--concurrency <n>`: how many browser tabs the render opens at once,
    * beating the config's `renderConcurrency` and the cpus-2 default
@@ -682,6 +777,21 @@ export interface ProduceOptions {
    * a file input.
    */
   sort?: "name" | "mtime";
+  /**
+   * `--sfx` (2026-08-29): place sound effects from the loaded pack on the
+   * beats the producer planned. Tri-state like `watermark` — true/false when
+   * TYPED, undefined when not, so the config's `sfx` key can supply the
+   * default (`resolveSfx`). Requires a beat sheet, so it rides `--produce`;
+   * without one the step says so and skips.
+   */
+  sfx?: boolean;
+  /**
+   * `--sfx-level`: how much sound design (`subtle | normal | meme`). Already
+   * zod-parsed to the union by program.ts, which also folds the implication
+   * (`sfxFlag`: a typed level turns `sfx` on); the CONFIG's `sfxLevel` arrives
+   * separately as an unvalidated value and `resolveSfxLevel` arbitrates.
+   */
+  sfxLevel?: SfxLevel;
   /**
    * Whether `--sort` was TYPED, as opposed to commander filling in its
    * `"name"` default. `sort` alone can't tell those apart, and `--sort` does
@@ -709,6 +819,32 @@ export function resolveWatermark(
   return flag ?? configValue === true;
 }
 
+/**
+ * The effective `--resolution` — `resolveWatermark`'s precedence verbatim: a
+ * TYPED flag always wins, and only then does the config supply the default.
+ *
+ * The config side is ZOD-PARSED rather than trusted: `loadConfig` hands back
+ * whatever the hand-editable JSON held, and an unparsed `"4k"` would reach
+ * `Number("4k")` inside `resolveOutputFrame` as NaN and size the whole render
+ * off it. A malformed value earns one warning naming the key and falls back
+ * to 1080 — the value every existing run already produces, so a typo costs a
+ * message rather than a surprise 4K render (CLAUDE.md: parse, never coerce).
+ * Pure, so the flag × config matrix is testable without a config file.
+ */
+export function resolveResolution(
+  flag: ResolutionChoice | undefined,
+  configValue: unknown,
+): ResolutionChoice {
+  if (flag !== undefined) return flag;
+  if (configValue === undefined) return "1080";
+  const parsed = ResolutionChoiceSchema.safeParse(configValue);
+  if (parsed.success) return parsed.data;
+  console.log(
+    `⚠ config resolution ignored — expected one of ${RESOLUTION_CHOICES.join(", ")}, using 1080`,
+  );
+  return "1080";
+}
+
 /**
  * The effective `--cover-in-video` switch — resolveWatermark's semantics
  * verbatim: a TYPED flag always wins (so `--no-cover-in-video` beats a
@@ -725,6 +861,103 @@ export function resolveCoverInVideo(
   return flag ?? configValue === true;
 }
 
+/**
+ * `--sfx-level` implies `--sfx`: typing a level is asking for sound effects,
+ * and a run that quietly did nothing because the boolean was missing is the
+ * worst possible reading of it. Returns the tri-state `--sfx` carries —
+ * `undefined` when neither was typed, so the config's `sfx` key still gets its
+ * turn (`resolveSfx`). Pure, so the implication is testable without commander,
+ * the `jumpCutsFlag` posture.
+ */
+export function sfxFlag(
+  sfx: boolean | undefined,
+  sfxLevel: SfxLevel | undefined,
+): boolean | undefined {
+  return sfxLevel !== undefined ? true : sfx;
+}
+
+/**
+ * The effective `--sfx` switch — `resolveCoverInVideo`'s semantics verbatim: a
+ * TYPED flag wins, and only then does the config's `sfx` supply the default,
+ * `=== true` rather than truthy so a hand-edited `"sfx": "yes"` cannot coerce
+ * sound effects onto every render.
+ */
+export function resolveSfx(flag: boolean | undefined, configValue: unknown): boolean {
+  return flag ?? configValue === true;
+}
+
+/**
+ * The effective `--sfx-level`. `resolveLlmEffort`'s shape — the warning is
+ * RETURNED, not printed, so the resolution stays pure — and its precedence: a
+ * typed flag beats a config key, and a malformed config key costs a warning
+ * and the default rather than a coerced level. The default matters: `meme`
+ * unlocks the meme-tagged sounds, so a typo must never fall UP into it.
+ */
+export function resolveSfxLevel(
+  flag: SfxLevel | undefined,
+  configValue: unknown,
+): { level: SfxLevel; warning?: string } {
+  if (flag !== undefined) return { level: flag };
+  if (configValue === undefined) return { level: "normal" };
+  const parsed = SfxLevelSchema.safeParse(configValue);
+  if (parsed.success) return { level: parsed.data };
+  return {
+    level: "normal",
+    warning: `⚠ config sfxLevel ignored — expected ${SfxLevelSchema.options.join("|")}, using normal`,
+  };
+}
+
+/**
+ * What `sfx-<key>.json` holds: the normalized plan plus the accounting a
+ * cached re-run would otherwise have to invent — `planned` is the count the
+ * MODEL returned, which nothing on disk could re-derive, and `issues` are the
+ * planning drops the report explains the shortfall with (the beat-sheet
+ * cache's `graphics`/`issues` rule, §78).
+ *
+ * Parsed on read, never trusted: a workdir file is as hand-editable as
+ * anything else here, and a mangled one must cost a re-plan, not a crash.
+ */
+const SfxPlanCacheSchema = SfxPlanSchema.extend({
+  planned: z.number().int().nonnegative().default(0),
+  issues: z.array(SfxValidationIssueSchema).default([]),
+});
+
+/**
+ * The placement-plan cache key: everything that changes the PLAN — which
+ * prompt asked, about which words, against which beat sheet, at what level,
+ * over which library. The §78 posture the beat sheet's key carries, and pure
+ * for the same reason: "a change that changes the answer must change the key"
+ * has to be assertable without a workdir or an LLM.
+ *
+ * `beatKey` folds the whole beat-sheet key in (provider, model, intent,
+ * framing, clip window…) rather than restating it: the graphics plan is IN the
+ * placement prompt, so a re-plan of the beats is a different question about
+ * the same words. `libraryHash` is pack METADATA only (`sfxLibraryHash`), so
+ * dropping a user pack in `~/.ossclip/sfx` invalidates while re-encoding an
+ * mp3 does not.
+ */
+export function sfxCacheKey(parts: {
+  promptVersion: number;
+  beatKey: string;
+  level: SfxLevel;
+  libraryHash: string;
+  /** The repaired transcript's TEXT — the beat key's rule, for the same reason. */
+  words: readonly string[];
+}): string {
+  return createHash("sha1")
+    .update(
+      JSON.stringify([
+        parts.promptVersion,
+        parts.beatKey,
+        parts.level,
+        parts.libraryHash,
+        parts.words,
+      ]),
+    )
+    .digest("hex")
+    .slice(0, 8);
+}
+
 /**
  * Where the cover image lives right now, most-specific first — the EDITOR
  * panel's ladder (`currentCoverImage` in edit.ts), deliberately the same one:
@@ -2078,6 +2311,46 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
 
   const tools = { ffmpegPath: cfg.ffmpegPath, ffprobePath: cfg.ffprobePath };
 
+  // `--resolution` (2026-08-27), resolved before ANY stage that sizes pixels:
+  // the folder concat, the mezzanine and the render each used to pin 1080p
+  // independently, so a 4K take lost three quarters of its pixels before
+  // anything looked at it. `auto` needs the SOURCE's size, which for a folder
+  // means probing the clips here — the concat target is chosen before the
+  // concatenated file (and its probe) exists.
+  const resolution = resolveResolution(opts.resolution, cfg.resolution);
+  const autoSource = async (): Promise<{ width: number; height: number } | null> => {
+    if (resolution !== "auto") return null;
+    if (isFolder && folderListing) {
+      // Metadata-only probes, and only under `auto`: the default path adds no
+      // ffprobe calls at all (the 4m32s probe-storm lesson, concat.ts:272).
+      const sizes: Array<{ width: number; height: number }> = [];
+      for (const entry of folderListing.entries) {
+        try {
+          const p = await probe(tools, join(input, entry.name));
+          sizes.push({ width: p.width, height: p.height });
+        } catch {
+          // A clip that will not probe is the concat guard's problem, not
+          // this sizing pass's — skip it rather than fail the run here.
+        }
+      }
+      return smallestSource(sizes);
+    }
+    try {
+      const p = await probe(tools, input);
+      return { width: p.width, height: p.height };
+    } catch {
+      return null;
+    }
+  };
+  const output = resolveOutputFrame({
+    frame,
+    source: (await autoSource()) ?? { width: 0, height: 0 },
+    resolution,
+  });
+  if (output.scale !== 1) {
+    console.log(`▸ resolution: ${output.width}x${output.height} (${resolution})`);
+  }
+
   // Resolved ONCE for the whole run — whisper biasing, repair vouching and
   // caption casing must all see the same list, or the passes disagree about
   // what a term is spelled like. A typed --dictionary wholesale beats the
@@ -2182,9 +2455,12 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   if (isFolder && folderListing) {
     const sort = opts.sort ?? "name";
     const result = await phases.time("ffmpeg", () =>
+      // The concat target carries the RESOLVED size, not the base frame:
+      // letterboxing every take into 1080p here would throw the pixels away
+      // before the mezzanine or the render ever saw them (`--resolution`).
       concatFolder(tools, input, folderListing!, work, sort, {
-        w: frame.width,
-        h: frame.height,
+        w: output.width,
+        h: output.height,
       }),
     );
     console.log(
@@ -2304,6 +2580,9 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   const requestedKey: TranscriptKey = {
     model: requestedModel,
     ...(whisperLang.language !== undefined ? { language: whisperLang.language } : {}),
+    // Omitted when off, so a non-translate run's key stays byte-identical to
+    // every pre-flag key file (the dictionary posture).
+    ...(opts.whisperTranslate === true ? { translate: true } : {}),
     // Omitted when empty, not written as [] — pre-dictionary key files have
     // no `dictionary` at all, and transcriptCacheReusable reads absent and
     // empty as the same "no biasing", so old workdirs must not re-transcribe.
@@ -2374,6 +2653,9 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
           language: requestedKey.language,
           // Vocabulary biasing (F4) — undefined for an empty dictionary, so
           // the spawned args stay byte-identical to every pre-dictionary run.
+          // From the KEY, like the language: whatever re-keys the cache is
+          // what actually ran, so the two can never disagree.
+          ...(requestedKey.translate === true ? { translate: true } : {}),
           prompt: whisperPromptFor(dictionary),
         },
         audioPath,
@@ -2713,11 +2995,52 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   let scenes: Scene[] = [];
   /** Editorial output kept for the cover (§31): hook + its thumbnail form. */
   let beatSheet: { hook: string; coverText?: string } | undefined;
+  /**
+   * The FULL sheet, moments included — the graphics plan the SFX call needs in
+   * context (a whoosh syncs with a graphic entrance). Separate from
+   * `beatSheet` above, which is deliberately the cover's two fields: this one
+   * exists only while a plan is in hand this run, and is undefined on the
+   * paths that never had one (`--scenes`, a pre-`--sfx` scenes cache).
+   */
+  let fullSheet: BeatSheet | undefined;
   /** The graphics accounting line for report.txt (§118b), and the beat-sheet
    * issues that explain it. Cached alongside the beat sheet so a cached
    * re-run's report keeps the accounting instead of erasing it (§78). */
   let graphicsLine: string | undefined;
   let beatIssues: BeatsValidationIssue[] = [];
+  /**
+   * The `--sfx` plan: the level it was planned at and the placements that
+   * survived `normalizeSfxPlan`, stored on production.json and resolved to
+   * cues once the cut is final (`resolveSfxCues`). Undefined = this run has no
+   * sound design at all, which is what an absent `sfx` field means.
+   */
+  let sfxPlan: { level: SfxLevel; placements: SfxPlacement[] } | undefined;
+  /** The library the plan was made against — the resolver needs the same
+   * sounds (gain, absPath) it planned over, and the stager needs their files. */
+  let sfxSounds: LoadedSfxSound[] = [];
+  /** Planning drops + the count the MODEL returned, carried to the one
+   * accounting line the console and report.txt share (§118b's contract). */
+  let sfxIssues: SfxValidationIssue[] = [];
+  let sfxPlanned = 0;
+  /** Whether the placement step actually ran — see the notice below the
+   * scenes block for the runs where `--sfx` cannot reach it. */
+  let sfxAttempted = false;
+  // Resolved HERE, above the branch that uses it, so BOTH the placement step
+  // and the "this run has no beat sheet" notice read one answer. Typed beats
+  // config for the switch; the level is zod-parsed out of the config, never
+  // coerced (`resolveSfxLevel`).
+  const sfxOn = resolveSfx(opts.sfx, cfg.sfx);
+  const sfxLevelResolved = resolveSfxLevel(opts.sfxLevel, cfg.sfxLevel);
+  if (sfxOn && sfxLevelResolved.warning) console.log(sfxLevelResolved.warning);
+  const sfxLevel = sfxLevelResolved.level;
+  // Which packs this machine offers (`sfxBundledPack`) — resolved next to the
+  // level, and for the same reason: BOTH library loads below (the placement
+  // step and the carry-forward branch) must read one answer, or a run would
+  // plan against one library and stage from another.
+  const sfxBundled = resolveSfxBundledPack(cfg.sfxBundledPack);
+  if (sfxOn && sfxBundled.warning) console.log(sfxBundled.warning);
+  /** The loader's opts, shared by both library loads. */
+  const sfxLoad = { includeBundled: sfxBundled.include };
   /** Who planned this run (R16 §78) — stamped into production.json below. */
   let producerStamp: Production["producer"];
   /** The resolved `--clip` window (R19 §93) — set only on a clip run; feeds
@@ -2900,6 +3223,7 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       // cache under the post-resolution key so re-runs and replays hit it.
       scenes = clipFresh.scenes;
       beatSheet = { hook: clipFresh.beatSheet.hook, coverText: clipFresh.beatSheet.coverText };
+      fullSheet = clipFresh.beatSheet;
       console.log(`▸ hook: ${clipFresh.beatSheet.hook}`);
       console.log(
         `▸ planned ${clipFresh.beatSheet.moments.length} moments, ${scenes.length} scenes` +
@@ -2927,7 +3251,11 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       await writeFile(join(work, `scenes-${adoptKey}.json`), JSON.stringify(scenes, null, 2));
       await writeFile(
         join(work, `beatsheet-${adoptKey}.json`),
-        JSON.stringify({ ...beatSheet, graphics: graphicsLine, issues: beatIssues }, null, 2),
+        JSON.stringify(
+          { ...beatSheet, moments: fullSheet.moments, graphics: graphicsLine, issues: beatIssues },
+          null,
+          2,
+        ),
       );
     } else if (existsSync(sceneCache)) {
       scenes = z.array(SceneSchema).parse(JSON.parse(await readFile(sceneCache, "utf8")));
@@ -2946,12 +3274,26 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
         const cached = JSON.parse(await readFile(beatCache, "utf8")) as {
           hook: string;
           coverText?: string;
+          moments?: unknown;
           graphics?: string;
           issues?: BeatsValidationIssue[];
         };
         beatSheet = { hook: cached.hook, coverText: cached.coverText };
         graphicsLine = cached.graphics;
         beatIssues = cached.issues ?? [];
+        // The MOMENTS ride the cache too (2026-08-29, --sfx): this file used to
+        // keep only the cover's two fields, so a cached run had no graphics
+        // plan to put in front of the placement call — and "produce once, add
+        // --sfx later" is the normal way anyone reaches this feature. Parsed,
+        // not trusted (a hand-edited or pre-`--sfx` file simply has no
+        // `moments`), and its absence costs the SFX step alone: everything the
+        // cache did before this is read above and unaffected.
+        const sheet = BeatSheetSchema.safeParse({
+          hook: cached.hook,
+          coverText: cached.coverText,
+          moments: cached.moments,
+        });
+        if (sheet.success) fullSheet = sheet.data;
       }
     } else {
       const aiAnim = isInteractive()
@@ -2998,6 +3340,7 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       if (aiAnim) aiAnim.stop();
       scenes = result.scenes;
       beatSheet = { hook: result.beatSheet.hook, coverText: result.beatSheet.coverText };
+      fullSheet = result.beatSheet;
       console.log(`▸ hook: ${result.beatSheet.hook}`);
       console.log(
         `▸ planned ${result.beatSheet.moments.length} moments, ${scenes.length} scenes` +
@@ -3024,8 +3367,136 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       await writeFile(join(work, `scenes-${freshKey}.json`), JSON.stringify(scenes, null, 2));
       await writeFile(
         join(work, `beatsheet-${freshKey}.json`),
-        JSON.stringify({ ...beatSheet, graphics: graphicsLine, issues: beatIssues }, null, 2),
+        JSON.stringify(
+          { ...beatSheet, moments: fullSheet.moments, graphics: graphicsLine, issues: beatIssues },
+          null,
+          2,
+        ),
+      );
+    }
+
+    // ---- Sound effects (`--sfx`): the placement call -----------------------
+    // HERE, inside the producer branch, because the placement prompt needs the
+    // graphics plan in front of it (Approach A: a whoosh syncs with a graphic
+    // entrance) — and because a beat sheet is the one thing this feature
+    // cannot do without. `--scenes` and a plain run never reach this block;
+    // the notice for that case is printed by the caller below.
+    if (sfxOn) {
+      sfxAttempted = true;
+      const library = loadSfxLibrary(sfxLoad);
+      for (const issue of library.issues) console.log(`  ⚠ sfx pack ${issue.pack}: ${issue.issue}`);
+      if (library.sounds.length === 0) {
+        // Warn and continue, never kill: an empty library is a packaging or a
+        // user-pack problem, and it costs sound effects, not the video.
+        console.log("  ⚠ sfx: no usable sounds in the library — skipping sound effects");
+      } else {
+        sfxSounds = library.sounds;
+        const sfxKey = sfxCacheKey({
+          promptVersion: SFX_PROMPT_VERSION,
+          // The beat key, not its parts: the graphics plan is IN this prompt,
+          // so a different sheet is a different question (see `sfxCacheKey`).
+          beatKey: hitKey,
+          level: sfxLevel,
+          libraryHash: sfxLibraryHash(library.sounds),
+          words: beatKeyParts.words,
+        });
+        const sfxCache = join(work, `sfx-${sfxKey}.json`);
+        if (existsSync(sfxCache)) {
+          // Parsed, never trusted — a cache file is as hand-editable as any
+          // other artefact in the workdir. A malformed one is a re-plan, not a
+          // crash, so it falls through to the call below.
+          const cached = SfxPlanCacheSchema.safeParse(
+            JSON.parse(await readFile(sfxCache, "utf8")),
+          );
+          if (cached.success) {
+            sfxPlan = { level: sfxLevel, placements: cached.data.placements };
+            sfxPlanned = cached.data.planned;
+            sfxIssues = cached.data.issues;
+            console.log(`▸ sfx cached (${sfxPlan.placements.length} placement(s), level ${sfxLevel})`);
+          }
+        }
+        if (!sfxPlan && fullSheet === undefined) {
+          // The one case the cache cannot cover: a workdir planned before
+          // `--sfx` existed (or by a pre-2026-08-29 build) has scenes but no
+          // moments, so there is no graphics plan to place against. Say what
+          // to do rather than silently rendering a mute video.
+          console.log(
+            "  ⚠ sfx: this workdir's cached plan has no beat sheet to place against — " +
+              "re-plan (delete its scenes-*.json) to get sound effects",
+          );
+        } else if (!sfxPlan) {
+          console.log(`▸ placing sound effects (level ${sfxLevel})…`);
+          const result = await phases.time("llm", () =>
+            generateSfxPlan(provider!, transcript, fullSheet!, library.sounds, sfxLevel),
+          );
+          sfxPlan = { level: sfxLevel, placements: result.plan.placements };
+          sfxPlanned = result.planned;
+          sfxIssues = result.issues;
+          await writeFile(
+            sfxCache,
+            // The accounting rides the cache for §78's reason, the same one
+            // `graphics`/`issues` ride the beat-sheet cache: a cached re-run
+            // must be able to print the SAME accounting line rather than
+            // erasing it, and `planned` is a count only the call itself knew.
+            JSON.stringify(
+              { placements: sfxPlan.placements, planned: sfxPlanned, issues: sfxIssues },
+              null,
+              2,
+            ),
+          );
+        }
+        for (const issue of sfxIssues) {
+          console.log(`  ⚠ sfx placement ${issue.placement}: ${issue.issue}`);
+        }
+      }
+    }
+  }
+
+  // `--sfx` on a run that never reached the placement call — `--scenes` (which
+  // is what the editor's Render replays), or a plain cut with no producer at
+  // all.
+  //
+  // The plan carries FORWARD from the workdir's last `production.json` here
+  // (Phase 3), and that is the scenes-reviewed doctrine applied to sound: an
+  // editor render replays the REVIEWED state, and for SFX the reviewed state
+  // is the prior plan plus overrides.json's edits on top of it (`priorSfxPlan`
+  // has the full argument). The level comes from that record too — the user
+  // reviewed effects placed at THAT level, and re-reading `--sfx-level` here
+  // would describe them with a number they were never planned under. It is
+  // written back below like any other run's plan, so a chain of editor renders
+  // never breaks.
+  //
+  // No prior record is the only case left with nothing to carry: never a
+  // silent ignore, and the message names the missing half rather than the flag
+  // the user typed.
+  if (sfxOn && !sfxAttempted) {
+    const prior = priorSfxPlan(work);
+    if (prior === undefined) {
+      console.log(
+        "  ⚠ sfx: sound effects are placed against the producer's beat sheet — " +
+          "add --produce (the editor's re-plan) to get them",
       );
+    } else {
+      // The same library the producer branch loads, and for the same two
+      // consumers: the resolver needs each sound's gain and path, the stager
+      // needs its file. An empty library costs the effects, never the video.
+      const library = loadSfxLibrary(sfxLoad);
+      for (const issue of library.issues) console.log(`  ⚠ sfx pack ${issue.pack}: ${issue.issue}`);
+      if (library.sounds.length === 0) {
+        console.log("  ⚠ sfx: no usable sounds in the library — skipping sound effects");
+      } else {
+        sfxSounds = library.sounds;
+        sfxPlan = prior;
+        // `planned` is the reviewed plan's own size: this run made no model
+        // call, so the only honest denominator for "N of M planned placed" is
+        // what the user approved (the cached-plan branch's rule — the count
+        // belongs to the plan, not to the run).
+        sfxPlanned = prior.placements.length;
+        console.log(
+          `▸ sfx carried forward from the reviewed plan ` +
+            `(${prior.placements.length} placement(s), level ${prior.level})`,
+        );
+      }
     }
   }
 
@@ -3798,6 +4269,77 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     );
   }
 
+  // ---- Sound effects: word anchors → cues, and the files they name --------
+  // AFTER the cut is final (`applyUserCuts` above) and after the public dir is
+  // known, because both are inputs: a placement anchored to a word the user's
+  // own cut removed is dropped here, and the copies must land where
+  // `staticFile()` will look.
+  let sfxCues: SfxCue[] = [];
+  /** Planning drops + render drops, counted together by the one accounting
+   * line the console and report.txt share (`formatSfxAccounting`). */
+  let sfxAllIssues: SfxValidationIssue[] = sfxIssues;
+  let sfxLine: string | undefined;
+  if (sfxPlan) {
+    // The user's layer FIRST (Phase 3): retimes, swaps, gains, mutes and the
+    // placements they added themselves, applied before any of the resolver's
+    // arithmetic so a dragged effect is timed, cut-checked and mixed exactly
+    // like a planned one. `sfxPlan` itself is left alone — production.json
+    // stores the MODEL's plan, which is what these edit keys are derived from
+    // (`sfxPlacementKey`), and folding them in would re-key the whole layer on
+    // the next run.
+    const edited = applySfxOverrides(sfxPlan.placements, overrideDoc.sfx);
+    for (const d of edited.dropped) {
+      console.log(
+        d.reason === "stale key"
+          ? `  ⚠ sfx edit "${d.key}" no longer matches any planned placement — ` +
+              `the re-plan dropped it`
+          : `  ⚠ sfx edit "${d.key}" matches more than one placement — applied to the first`,
+      );
+    }
+    // The accounting's denominator moves with the user's layer, because the
+    // layer changes the SIZE of the plan the resolver saw: a mute REMOVES a
+    // placement (it was un-planned by the user, not dropped by the pipeline)
+    // and an add appends one. Without this, muting an effect would print as a
+    // reasonless "1 dropped" and adding one as "6 of 5 planned placed".
+    sfxPlanned += edited.placements.length - sfxPlan.placements.length;
+    const resolved = resolveSfxCues(edited.placements, transcript, map, sfxSounds, {
+      // The real check, injected (the resolver stays pure): a pack deleted
+      // between planning and this render must cost the cue here, not a
+      // Remotion 404 after the render has spent its minutes.
+      exists: existsSync,
+      // The scene timing context, from `sceneCues` — the FINAL list, with the
+      // user's moves, trims, splits, pins and deletes already applied. That is
+      // the whole point of the scene link (2026-08-29): a whoosh placed "as
+      // the TitleCard enters" fired at a word, so moving the card in the
+      // editor left the sound behind. Reading the producer's raw `scenes`
+      // here instead would rebuild that bug exactly.
+      sceneStarts: sceneStartSeconds(sceneCues),
+    });
+    sfxCues = resolved.cues;
+    sfxAllIssues = [...sfxIssues, ...resolved.dropped];
+    for (const d of resolved.dropped) console.log(`  ⚠ sfx: ${d.issue}`);
+    // Staged into the render's public dir AND the workdir when they differ,
+    // for the Nastaliq font's reason verbatim: the render bundles
+    // `dirname(renderVideo)`, `ossclip edit` serves the workdir, and both
+    // mounts fetch the same served name. Only the sounds actually CUED are
+    // copied — the library is a menu, not a payload.
+    const staged = new Set(sfxCues.map((c) => c.soundFile));
+    for (const sound of sfxSounds) {
+      const rel = sfxStagedFile(sound);
+      if (!staged.has(rel)) continue;
+      for (const dir of new Set([renderPublicDirPath, work])) {
+        // `join` on the filesystem side where `rel` itself stays
+        // POSIX-literal — it is a served URL, these are paths (the
+        // `sideImageDestRel` split).
+        const dest = join(dir, ...rel.split("/"));
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(sound.absPath, dest);
+      }
+    }
+    sfxLine = formatSfxAccounting(sfxCues.length, sfxPlanned, sfxPlan.level, sfxAllIssues);
+    console.log(`▸ ${sfxLine}`);
+  }
+
   const production: Production = {
     version: 1,
     // `originalInput`, not `input`: for a folder run `input` is by now
@@ -3827,9 +4369,18 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       ? { clip: { targetSec: clipTargetSec, ...clipWindow } }
       : {}),
     scenes: scenes.length > 0 ? scenes : undefined,
+    // The PLAN, not the cues: word anchors survive a re-cut and the editor
+    // edits them (Phase 3), while `render-props.json` carries the resolved
+    // instants. Absent when this run has no sound design, so a no-`--sfx`
+    // production.json is byte-identical to a pre-feature one.
+    sfx: sfxPlan,
     producer: producerStamp,
     theme,
-    render: { ...frame, fps: 30 },
+    // The EFFECTIVE output size, not the base frame (`--resolution`): this is
+    // what the file on disk actually is, and it is read downstream by the
+    // mezzanine's scale decision, the NLE exports and the editor — all of
+    // which would otherwise describe a 1080p file that isn't there.
+    render: { width: output.width, height: output.height, fps: 30 },
   };
   await writeFile(join(work, "production.json"), JSON.stringify(production, null, 2));
 
@@ -3910,6 +4461,16 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
         .map((i) => `  ⚠ moment ${i.moment}: ${i.issue}\n`)
         .join("");
   }
+  // The SFX accounting, the graphics block's contract exactly (§118b): ONE
+  // formatter feeds the console line printed above and this one, so the two
+  // can never say different things about the same run. The drops are listed
+  // under it for the same reason the beat issues are listed under the graphics
+  // line — the number alone does not say WHICH effect went missing.
+  if (sfxLine) {
+    report +=
+      `\n${sfxLine}\n` +
+      sfxAllIssues.map((i) => `  ⚠ placement ${i.placement}: ${i.issue}\n`).join("");
+  }
   if (provider) {
     report += formatUsageReport(provider.usage, cfg.pricing);
     // A cached run has no usage block to print, and used to leave the report
@@ -4383,7 +4944,15 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     // ~/.ossclip/config.json's theme the first time anyone touched a color.
     baseTheme: configBaseTheme,
     baseCaptionLines,
-    settings: production.render,
+    // The COMPOSITION's size, which is the BASE frame — never
+    // `production.render` (2026-08-27). `production.render` describes the
+    // FILE, and under `--resolution` those differ by the render's `scale`:
+    // Remotion enlarges this composition by that factor, so sizing the
+    // composition from the scaled dims applies it TWICE (2160×3840 became
+    // 4320×7680 frames, which h264_videotoolbox refuses outright, at stitch
+    // time, after every frame had been paid for). The Player reads these too,
+    // and previewing at the base size is what keeps the editor cheap.
+    settings: { ...frame, fps: production.render.fps },
     outputDurationSec: map.outputDuration,
     // The aspect travels with the measurement because the crop math needs it:
     // `object-fit: cover` spills vertically for a portrait source and
@@ -4494,6 +5063,12 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     // actually render.
     ...(captionsHidden ? { captionsHidden: true } : {}),
     ...(opts.captions === false ? { captionsHiddenByFlag: true } : {}),
+    // `--sfx`, written only when there is something to play (the watermark's
+    // absent-means-off contract): a run without sound effects keeps a
+    // render-props.json — and an audio graph — byte-identical to a pre-feature
+    // one, and the composition reads an absent key as silence, not as an empty
+    // track it still has to mount.
+    ...(sfxCues.length > 0 ? { sfxCues } : {}),
   };
   await writeFile(join(work, "render-props.json"), JSON.stringify(props, null, 2));
 
@@ -4665,6 +5240,16 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     portrait,
     audience,
     thumbnailBrief,
+    // The SFX switch and level, RESOLVED (flag + config folded) — the
+    // watermark's rationale on a flag whose default is config-dependent
+    // (`sfx`/`sfxLevel` in ~/.ossclip/config.json). Unpinned, the editor's
+    // Render would place a DIFFERENT amount of sound design the moment that
+    // config is edited, or none at all on a machine without it — and since
+    // the replay carries the reviewed plan forward rather than re-placing
+    // (`priorSfxPlan`), an unpinned `--sfx` is the difference between the
+    // reviewed sound design and a silent video.
+    sfx: sfxOn,
+    sfxLevel,
   });
   // produce is the ONLY command that may write command.json — edit.ts's §129
   // heal prepends the "produce" literal to any record that doesn't start
@@ -4890,6 +5475,10 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
         outPath: rawPath,
         browserExecutable: cfg.browserExecutable,
         concurrency: renderConcurrency.concurrency,
+        // The composition stays 1080-wide and Remotion renders it larger
+        // (`--resolution`) — rebuilding the stage at 2160 would keep
+        // `captionFontSizeFor`'s absolute 64px and draw quarter-size captions.
+        scale: output.scale,
         cancelSignal: renderCancel.cancelSignal,
         onPhase: (phase: RenderPhase) => {
           signalPhase = renderSignalPhaseOf(phase);