ossclip 0.1.34 → 0.1.36

package/src/produce.ts

@@ -124,6 +124,18 @@ import {
   makeMezzanine,
   mezzanineFileName,
   mezzanineScale,
+  // The color-grade pipeline (2026-08-30): validation, the preset/LUT split,
+  // the SVG filter spec preset grades ride render-props as, and the .cube
+  // bake+hash LUT grades ride the mezzanine as.
+  CONFIG_DIR,
+  resolveColorGrade,
+  resolveGradeToLook,
+  gradeToSvgFilterSpec,
+  parseCubeLut,
+  bakeCube,
+  lutHash,
+  type ColorGrade,
+  type SvgGradeFilterSpec,
   scaleContentTimeline,
   scaleFramingWindows,
   measureFace,
@@ -156,6 +168,8 @@ import {
   sliceTranscript,
   type Analysis,
   type AppliedRepair,
+  type BeatSheet,
+  BeatSheetSchema,
   type BeatsValidationIssue,
   type CleanupLevel,
   type ClipWindow,
@@ -170,6 +184,34 @@ import {
   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,
@@ -417,6 +459,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,
@@ -663,6 +737,16 @@ export interface ProduceOptions {
    * ignore an uploaded cover.
    */
   coverInVideo?: boolean;
+  /**
+   * `--color-grade <look>` / `--no-color-grade` — the watermark's tri-state
+   * carrying a VALUE: a string when typed (a preset id, or a `.cube`
+   * filename — `colorGradeFlagValue` classifies by extension), `false` for a
+   * typed --no-color-grade, undefined when neither so overrides.json and
+   * then the config's `colorGrade` decide (`resolveProductionColorGrade`).
+   * Deliberately unparsed in transit: validation warns-and-proceeds at the
+   * use site, because a grade typo must cost the look, never the run.
+   */
+  colorGrade?: string | false;
   /**
    * `--youtube` / `--no-youtube` tri-state, the watermark's exact contract:
    * true/false when TYPED, undefined when not — undefined lets the config's
@@ -715,6 +799,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
@@ -784,6 +883,168 @@ export function resolveCoverInVideo(
   return flag ?? configValue === true;
 }
 
+/**
+ * `--color-grade`'s value classified into the ColorGradeSchema shape: a value
+ * ending in `.cube` names a LUT file in `~/.ossclip/luts`, anything else
+ * names a preset. Sniffed by extension rather than split into two flags
+ * because the user already knows which they typed — `kodak.cube` cannot be a
+ * preset id (presets never carry a dot) and a preset id cannot be a LUT
+ * (`.cube` is the one format the parser reads), so the classification is
+ * lossless. Case-insensitive on the extension: `KODAK.CUBE` is the same file
+ * on the case-preserving filesystems the LUT dir lives on. Validation is NOT
+ * here — the shape goes through `resolveColorGrade` like every other layer.
+ */
+export function colorGradeFlagValue(value: string): { preset?: string; lut?: string } {
+  return value.toLowerCase().endsWith(".cube") ? { lut: value } : { preset: value };
+}
+
+/**
+ * The effective color grade across all three surfaces — override > flag >
+ * config, `resolveWatermark`'s typed-beats-config precedence grown one layer:
+ * the overrides doc is the editor's per-project say, so it beats even a typed
+ * flag (the `resolveSrcTimingPins` rationale — a per-project decision made in
+ * the editor outranks a per-run flag, never merges with it). An explicit
+ * `false` at a switching layer (`colorGrade: false` in the doc, or a typed
+ * `--no-color-grade`) is OFF, not fall-through: "no grade" is a decision, and
+ * letting a lower layer overrule it would make the disable impossible to
+ * express.
+ *
+ * Every layer is validated through `resolveColorGrade`, and an INVALID layer
+ * is ignored — warned about by name, then the NEXT layer applies (decision
+ * 2026-08-30): the alternative, an invalid override going all the way to
+ * "off", would let one stale editor write silently strip the config grade a
+ * channel's whole look depends on. Warnings are RETURNED, not printed
+ * (`resolveSfxLevel`'s shape), so the whole matrix is testable without a TTY.
+ * `source` names the winning layer so the ▸ line can say where a grade came
+ * from — the watermark's "(from config; --no-… overrides)" visibility rule.
+ */
+export function resolveProductionColorGrade(p: {
+  override: ColorGrade | false | undefined;
+  flag: string | false | undefined;
+  config: unknown;
+}): { grade?: ColorGrade; source?: "override" | "flag" | "config"; warnings: string[] } {
+  const warnings: string[] = [];
+  if (p.override === false) return { warnings };
+  if (p.override !== undefined) {
+    // Schema-valid already (OverrideDocSchema parsed the doc), but the
+    // unknown-preset check lives in resolveColorGrade, not the schema — this
+    // is the layer where a preset the editor knew and this build doesn't
+    // falls through instead of failing the doc.
+    const r = resolveColorGrade(p.override, "overrides.json");
+    if (r.grade) return { grade: r.grade, source: "override", warnings };
+    if (r.warning) warnings.push(r.warning);
+  }
+  if (p.flag === false) return { warnings };
+  if (p.flag !== undefined) {
+    const r = resolveColorGrade(colorGradeFlagValue(p.flag), "--color-grade");
+    if (r.grade) return { grade: r.grade, source: "flag", warnings };
+    if (r.warning) warnings.push(r.warning);
+  }
+  // "config", not "config colorGrade": resolveColorGrade's warning already
+  // spells the key (`⚠ <source> colorGrade ignored — …`).
+  const r = resolveColorGrade(p.config, "config");
+  if (r.grade) return { grade: r.grade, source: "config", warnings };
+  if (r.warning) warnings.push(r.warning);
+  return { warnings };
+}
+
+/**
+ * `--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:
@@ -2821,11 +3082,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
@@ -3008,6 +3310,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` +
@@ -3035,7 +3338,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")));
@@ -3054,12 +3361,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()
@@ -3106,6 +3427,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` +
@@ -3132,9 +3454,137 @@ 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})`,
+        );
+      }
+    }
   }
 
   // Every LLM call is behind us — repair, beat sheet, one per scene — so this
@@ -3906,6 +4356,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
@@ -3935,6 +4456,11 @@ 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,
     // The EFFECTIVE output size, not the base frame (`--resolution`): this is
@@ -4022,6 +4548,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
@@ -4265,6 +4801,88 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // on a bar-free source): there is no re-encode to scale, the render plays
   // the source itself, and the window emissions below must then stay in true
   // source pixels — which the identity `mezzFactor` below guarantees.
+  // ---- Color grade (`--color-grade` / config `colorGrade` / the editor's
+  // overrides.json) ---------------------------------------------------------
+  // Resolved HERE, before the mezzanine encode, because the feature's two
+  // halves split at exactly this seam: a PRESET grade rides render-props as
+  // an SVG filter spec (the props assembly below), while a LUT grade is baked
+  // INTO the mezzanine (ingest.ts's `lut` option) — ffmpeg's lut3d on the
+  // encode pass costs nothing per rendered frame, where a 33³ trilinear
+  // lookup in the browser would. Precedence and validation live in
+  // `resolveProductionColorGrade`; every warning it returns prints once here,
+  // and every failure path proceeds UNGRADED — a grade must cost the look at
+  // worst, never the run.
+  const gradeResolution = resolveProductionColorGrade({
+    override: overrideDoc.colorGrade,
+    flag: opts.colorGrade,
+    config: cfg.colorGrade,
+  });
+  for (const w of gradeResolution.warnings) console.log(w);
+  /** Preset grades: the spec render-props carries (absent = no grade). */
+  let colorGradeSpec: SvgGradeFilterSpec | undefined;
+  /** LUT grades: the baked .cube the mezzanine encode applies (absent = none). */
+  let gradeLut: { path: string; hash: string } | undefined;
+  if (gradeResolution.grade !== undefined) {
+    // The watermark's visibility rule: a grade sourced anywhere but the
+    // typed flag says so, so a config- or editor-sourced look never
+    // surprises the author on upload.
+    const gradeFromNote =
+      gradeResolution.source === "config"
+        ? " (from config; --no-color-grade overrides)"
+        : gradeResolution.source === "override"
+          ? " (editor override)"
+          : "";
+    const resolvedLook = resolveGradeToLook(gradeResolution.grade);
+    if (resolvedLook.kind === "preset") {
+      colorGradeSpec = gradeToSvgFilterSpec(resolvedLook);
+      console.log(`▸ color grade: ${gradeResolution.grade.preset}${gradeFromNote}`);
+    } else if (!mezzanineWillBuild) {
+      // --no-mezzanine on a bar-free source: the render plays the source
+      // file itself, so there is no encode to bake the LUT into. Warn and
+      // proceed ungraded rather than force a mezzanine the user refused.
+      console.log(
+        `⚠ color grade skipped — a .cube LUT is baked into the mezzanine, ` +
+          `and --no-mezzanine means this run doesn't build one`,
+      );
+    } else {
+      try {
+        // Basename only, enforced before any path math: `lut` is a NAME the
+        // schema documents as living in ~/.ossclip/luts, and resolving a
+        // separator-carrying value would turn a config key into a file probe
+        // (the SfxAddedPlacement id's "nothing may ever resolve a path
+        // against it" rule, applied at the one place this name meets the
+        // filesystem).
+        if (basename(resolvedLook.lutRef) !== resolvedLook.lutRef) {
+          throw new Error(
+            `"${resolvedLook.lutRef}" is not a bare filename — LUTs live in ${join(CONFIG_DIR, "luts")}`,
+          );
+        }
+        const lutPath = join(CONFIG_DIR, "luts", resolvedLook.lutRef);
+        const baseLut = parseCubeLut(readFileSync(lutPath, "utf8"));
+        // Tweaks + intensity are baked into the cube (bakeCube composes
+        // `params` on top of the base sample), so the hash keys the WHOLE
+        // grade: change the intensity and the mezzanine filename changes
+        // with it (`mezzanineFileName`'s existence-keyed cache).
+        const cubeText = bakeCube({
+          base: baseLut,
+          params: resolvedLook.tweaks,
+          intensity: resolvedLook.intensity,
+        });
+        const hash = lutHash(cubeText);
+        const bakedPath = join(work, `grade-${hash}.cube`);
+        await writeFile(bakedPath, cubeText);
+        gradeLut = { path: bakedPath, hash };
+        console.log(`▸ color grade: LUT ${resolvedLook.lutRef}${gradeFromNote}`);
+      } catch (err) {
+        // ENOENT and a malformed .cube land here alike: name the problem,
+        // proceed ungraded. parseCubeLut's errors already carry the line.
+        console.log(
+          `⚠ color grade skipped — ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
   const mezzScale = mezzanineWillBuild
     ? mezzanineScale(
         { width: contentRect.w, height: contentRect.h, fps: sourceProbe.fps },
@@ -4277,7 +4895,10 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     // why): mezzanine caching is existence-keyed, so a pre-pass full-res
     // mezzanine.mp4 must not satisfy a run that emits mezzanine-sized
     // windows — the scaled file rebuilds once under its own name.
-    const mezz = join(work, mezzanineFileName(!contentRect.full, mezzScale));
+    // `gradeLut?.hash` rides the name so a graded mezzanine can never satisfy
+    // an ungraded run (or vice versa) — the LUT is pixels in the file, and
+    // the cache is existence-keyed.
+    const mezz = join(work, mezzanineFileName(!contentRect.full, mezzScale, gradeLut?.hash));
     if (!existsSync(mezz)) {
       const mezzAnim = isInteractive()
         ? new StageAnimator(
@@ -4298,6 +4919,10 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       await makeMezzanine(tools, input, mezz, {
         cropVf: cropVf || undefined,
         scale: mezzScale ?? undefined,
+        // The LUT grade's whole delivery: baked into the encode, so the
+        // render (and the editor's preview, which plays the same file) see
+        // graded pixels with no per-frame cost.
+        lut: gradeLut,
       });
       if (mezzAnim) mezzAnim.stop();
     }
@@ -4614,6 +5239,20 @@ 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 } : {}),
+    // `--color-grade` PRESET looks, written only when one resolved (the
+    // watermark's absent-means-off contract): the two-stage SVG filter spec
+    // ({tableR, tableG, tableB, colorMatrix}, gradeToSvgFilterSpec) the
+    // composition mounts over the video. A LUT grade deliberately writes
+    // NOTHING here — it was baked into the mezzanine above, so the pixels
+    // the renderer plays already carry it, and a spec on top would grade
+    // twice.
+    ...(colorGradeSpec ? { colorGrade: colorGradeSpec } : {}),
   };
   await writeFile(join(work, "render-props.json"), JSON.stringify(props, null, 2));
 
@@ -4785,6 +5424,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