@ossclip/core 0.1.34 → 0.1.35

package/src/overrides.ts

@@ -9,7 +9,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";
@@ -443,6 +443,87 @@ 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({}),
@@ -729,6 +810,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 +2714,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,