ossclip 0.1.34 → 0.1.36

package/src/edit.ts

@@ -4,7 +4,7 @@ import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
 import { copyFile, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { homedir } from "node:os";
-import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod/v4";
 import {
@@ -18,6 +18,11 @@ import {
   ThumbnailConceptApprovedSchema,
   ThumbnailConceptSchema,
   appendUsageRun,
+  // The SFX plan route's word-space derivation (Phase 4) — the repaired
+  // transcript rebuilt from production.json's own stored pair, which is the
+  // index space `production.sfx.placements[].word` counts in.
+  applyRepairs,
+  ProductionSfxSchema,
   approvedOverlayText,
   buildThumbnailPrompt,
   captionCap,
@@ -43,6 +48,22 @@ import {
   // only when a regenerate actually runs.
   generateThumbnailImage,
   loadConfig,
+  // The SFX palette's one source of sounds (2026-08-29): the same loader
+  // produce plans against, so the dropdown can never offer a sound a render
+  // would not find.
+  loadSfxLibrary,
+  // …and the config gate that decides whether the bundled pack is part of it.
+  // Resolved here too, not just in produce: an editor that offered stock sounds
+  // the config excludes would let a user pick one the next render drops.
+  resolveSfxBundledPack,
+  // The Color panel's .cube menu (2026-08-30): the same loader produce's LUT
+  // bake resolves against, the loadSfxLibrary rule for grades.
+  loadLutLibrary,
+  // …and the validator every grade layer goes through — the /api/luts payload
+  // carries the CONFIG grade so the panel can label its "Default" entry, and
+  // a malformed config value must read as "no default" there exactly as it
+  // reads in produce (`resolveProductionColorGrade` falls through to off).
+  resolveColorGrade,
   outInsideInputFolderMessage,
   outPathInsideInput,
   PORTRAIT_MIME_TYPES,
@@ -68,6 +89,10 @@ import {
 // server startup — open.ts is node:child_process + node:path and pure command
 // building, with nothing to defer.
 import { loadEnvFiles } from "./env";
+// The identity endpoint's one spelling, shared with the CLI-side probe in
+// edit-port.ts (which imports only the TYPE of this module's server, so there
+// is no cycle and nothing interactive rides in here).
+import { EDIT_HEALTH_PATH, editHealthBody } from "./edit-health";
 import { revealInFileManager } from "./open";
 import { REVIEWED_SCENES_BASENAME, renderReplayArgs } from "./render-replay-args";
 // The recorded-invocation reads live in cover.ts (2026-08-19): `ossclip
@@ -102,6 +127,7 @@ import { lastFlagValue, thumbnailPanelState } from "./thumbnail-panel";
 import { captionRegenProvider } from "./caption-regen-panel";
 import { binOnPath } from "./llm-detect";
 import {
+  YOUTUBE_PRIVACIES,
   attachDeliveryMedia,
   buildPublishPosts,
   publishConfigured,
@@ -135,6 +161,29 @@ export function resolveEditorPageDir(): string | null {
   return candidates[0] ?? null;
 }
 
+/**
+ * This package's version for `/api/health`, read from the manifest exactly as
+ * `--version` does (R22 §113: never a literal, or it reports the number a
+ * developer typed). Memoized because it sits on a request path, and
+ * `undefined` when unreadable — the health body's `version` is optional
+ * precisely so an odd install still identifies itself as ossclip.
+ */
+let cachedVersion: string | undefined | null = null;
+function packageVersion(): string | undefined {
+  if (cachedVersion === null) {
+    try {
+      cachedVersion = (
+        JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+          version: string;
+        }
+      ).version;
+    } catch {
+      cachedVersion = undefined;
+    }
+  }
+  return cachedVersion;
+}
+
 /**
  * The config keys `/api/retranscribe-range` needs. Spelled structurally
  * rather than as `OssclipConfig` so the `loadCfg` seam keeps accepting a test
@@ -271,6 +320,12 @@ const MIME: Record<string, string> = {
   // the type is stated while the change is one line rather than a debugging
   // session.
   ".wav": "audio/wav",
+  // The sound-effect preview (`/api/sfx/audio`) and the staged `sfx/` copies
+  // the workdir serves over `/media/`: the starter pack is mono mp3, and an
+  // `<audio>` element handed an octet-stream is exactly the sniffing-dependent
+  // preview the `.jpg` note below refuses to rely on. Anything else a user
+  // pack ships still falls back to octet-stream rather than being refused.
+  ".mp3": "audio/mpeg",
   // The `--cover-in-video` overlay: produce stages the cover into the workdir
   // as well as the render's public dir, and the Player fetches it through
   // `/media/`. Browsers do sniff an image served as octet-stream, but a
@@ -386,6 +441,14 @@ export async function startEditServer(
       /** The caption-regenerate spend report prices through the same table
        * produce does — absent in a stub, the defaults apply. */
       pricing?: Record<string, ModelPrice>;
+      /** Whether the bundled starter pack feeds the SFX routes' library —
+       * `unknown` because it is file-only and typed at the consumer
+       * (`resolveSfxBundledPack`), the `audience` rule. */
+      sfxBundledPack?: unknown;
+      /** The config-level default grade the Color panel's "Default" entry
+       * names — `unknown` because it is file-only and typed at the consumer
+       * (`resolveColorGrade`), the `sfxBundledPack` rule. */
+      colorGrade?: unknown;
     } & RetranscribeConfig;
     /** Env seam for the publish endpoints — tests inject their own so the
      * runner's real OSSCLIP_POSTIZ_API_KEY (or its absence) never decides a
@@ -421,6 +484,20 @@ export async function startEditServer(
      */
     sliceAudio?: typeof extractAudioSpan;
     runWhisper?: typeof runWhisper;
+    /**
+     * The sound library the SFX routes serve (`loadCfg`'s rule applied to the
+     * pack loader): tests inject a hand-written library over a tmp dir, so the
+     * suite never depends on the bundled pack riding a given runner's checkout
+     * — nor on whatever the developer happens to have in ~/.ossclip/sfx, which
+     * the real loader merges in. It is called with the resolved `includeBundled`
+     * (see `sfxLibrary` below), so a test can assert the config gate reached the
+     * loader rather than only that the routes serve what they were handed.
+     */
+    loadSfx?: typeof loadSfxLibrary;
+    /** The LUT library `/api/luts` serves — the `loadSfx` seam for grades:
+     * tests inject a hand-written library instead of depending on whatever
+     * the developer keeps in ~/.ossclip/luts. */
+    loadLuts?: typeof loadLutLibrary;
   } = {},
 ): Promise<EditServer> {
   // MUTABLE since R17 §83: the server can start with no project (the page
@@ -631,6 +708,27 @@ export async function startEditServer(
     const cfg = (opts.loadCfg ?? loadConfig)();
     return { ffmpegPath: cfg.ffmpegPath ?? "ffmpeg", ffprobePath: cfg.ffprobePath ?? "ffprobe" };
   };
+  /**
+   * The sound library the SFX routes serve, loaded through the SAME config gate
+   * produce's sfx step uses (`sfxBundledPack` → `resolveSfxBundledPack`). One
+   * helper rather than the resolution inline at each route, because /library
+   * and /audio must agree: a menu offering `pop` while /audio 404s it — or
+   * worse, while the next render drops it — is the exact mismatch the gate
+   * exists to avoid.
+   *
+   * Read per request, like every other `loadCfg` consumer here: the server
+   * outlives config edits (R17 §83's mutable-workdir posture), and a user who
+   * flips the key gets it on the next refresh instead of on a restart.
+   *
+   * The malformed-value warning is dropped on purpose — this is a request path
+   * with no console the user is watching, and produce prints it on the run that
+   * actually places effects. The loader's own issues DO reach the panel, which
+   * is where a `~/.ossclip/sfx` author sees them.
+   */
+  const sfxLibrary = (): ReturnType<typeof loadSfxLibrary> =>
+    (opts.loadSfx ?? loadSfxLibrary)({
+      includeBundled: resolveSfxBundledPack((opts.loadCfg ?? loadConfig)().sfxBundledPack).include,
+    });
   const approvedPackPath = (): string => join(workdir!, YOUTUBE_APPROVED_BASENAME);
   /** The pack the panel shows: the approved file first (the user's
    * decision), else the newest valid `youtube-<key>.json` cache (what the
@@ -689,6 +787,18 @@ export async function startEditServer(
       try {
         const url = new URL(req.url ?? "/", "http://localhost");
 
+        if (url.pathname === EDIT_HEALTH_PATH && req.method === "GET") {
+          // Who is on this port (edit-health.ts owns the contract). This is
+          // what makes a second `ossclip edit` on the same project an ATTACH
+          // instead of an EADDRINUSE stack, and it answers with the CURRENT
+          // workdir — mutable since R17 §83, so a server whose project was
+          // switched from the page identifies as the project it is serving now.
+          return send(
+            200,
+            editHealthBody({ version: packageVersion(), workdir, pid: process.pid }),
+          );
+        }
+
         if (url.pathname === "/api/production" && req.method === "GET") {
           if (!workdir) {
             // Not an error — the picker state (R17 §83). Recents ride along
@@ -1878,6 +1988,14 @@ export async function startEditServer(
               // What uploads (the CLI's --delivery): auto (default) builds
               // the cached delivery encode, master sends the untouched render.
               delivery: z.enum(["auto", "master"]).optional(),
+              // YouTube's privacy status (the CLI's --youtube-privacy),
+              // spelled ONCE — the flag's own value list, so the panel and
+              // the CLI can never accept different words. Absent leaves
+              // buildPostsPayload's safe private default alone: until this
+              // rode along, every panel publish landed private with no way
+              // to say otherwise, and two videos the user believed were
+              // published sat private on the channel (2026-08-29).
+              youtubePrivacy: z.enum(YOUTUBE_PRIVACIES).optional(),
             })
             .safeParse(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
           if (!parsed.success) return send(400, { error: parsed.error.message });
@@ -1984,7 +2102,14 @@ export async function startEditServer(
               }
               capGroups = sizeCapGroups(picked);
             }
-            const posts = buildPublishPosts(pack, picked).map((p) => ({
+            // Same options object the CLI's publish path passes — undefined
+            // stays undefined so buildPostsPayload's safe private default is
+            // still the ONE place that decides an absent privacy.
+            const posts = buildPublishPosts(pack, picked, {
+              ...(parsed.data.youtubePrivacy !== undefined
+                ? { youtubePrivacy: parsed.data.youtubePrivacy }
+                : {}),
+            }).map((p) => ({
               ...p,
               caption: parsed.data.captions?.[p.target.id] ?? p.caption,
             }));
@@ -2395,6 +2520,203 @@ export async function startEditServer(
           }
         }
 
+        if (url.pathname === "/api/sfx/plan" && req.method === "GET") {
+          // The MODEL's placement plan plus the word space it is written in
+          // (Phase 4). Two values, one route, because they are useless apart:
+          // a placement is `{soundId, word}` and `word` is an INDEX, so the
+          // editor can only draw a marker — or write one — against the exact
+          // array produce counted.
+          //
+          // And that array is NOT `transcript.json`, which is what
+          // /api/transcript serves: produce writes that file straight off
+          // whisper (produce.ts, `writeFile(transcriptCache, …)`) and only
+          // THEN applies repairs and the `--clip` slice, planning sound
+          // effects against the result. `applyRepairs` splices, so the two
+          // index spaces need not line up at all — clip.ts's own note on
+          // slicing says it outright ("repairs may change word counts, so raw
+          // and repaired index spaces need not line up"). An editor drawing
+          // this lane off transcript.json would place every marker on the
+          // wrong word the moment one repair changed a word count, and its
+          // drags would WRITE those wrong indices into overrides.json, where
+          // produce reads them in the other space. So the derivation happens
+          // HERE, once, on the server that has the pieces.
+          //
+          // The derivation is `ProductionSchema.repairs`' own stated contract:
+          // `applyRepairs(transcript, repairs.filter(r => r.applied))`
+          // reconstructs exactly what was rendered. No clip windowing on top:
+          // production.json's `transcript` is ALREADY the sliced raw one and
+          // its `repairs` were re-indexed with it (produce.ts's `--clip`
+          // block: `rawTranscript = rawSlice.transcript` / `repairs =
+          // sliceRepairs(…)`), so a second slice here would shift every index
+          // by the clip's offset — the very bug this route exists to avoid.
+          //
+          // Its own route rather than a field on /api/production: that endpoint
+          // is the page's hot load path and reads render-props.json, and this
+          // needs production.json plus a repair replay. Lenient throughout —
+          // any missing or corrupt piece answers `null` and the editor hides
+          // the lane, exactly the /api/cleanup posture. A sound-effect lane is
+          // never worth a 500.
+          if (!workdir) return send(409, { error: "no workdir open" });
+          let production: Record<string, unknown> | null = null;
+          try {
+            production = JSON.parse(
+              await readFile(join(workdir, "production.json"), "utf8"),
+            ) as Record<string, unknown>;
+          } catch {
+            return send(200, { sfx: null, words: null });
+          }
+          // Parsed, never cast (CLAUDE.md) — production.json is a file a user
+          // can hand-edit, and the editor has no zod of its own, so the parse
+          // that guards this payload has to be this one. A `sfx` field that
+          // fails it is the same as none: no lane.
+          const parsedSfx = ProductionSfxSchema.safeParse(production.sfx);
+          const parsedTranscript = TranscriptSchema.safeParse(production.transcript);
+          let words: Array<{ text: string; start: number; end: number }> | null = null;
+          if (parsedTranscript.success) {
+            const stored = Array.isArray(production.repairs)
+              ? (production.repairs as Array<Record<string, unknown>>)
+              : [];
+            const applied = stored.filter((r) => r.applied === true);
+            if (applied.length === 0) {
+              words = parsedTranscript.data.words;
+            } else {
+              // The dictionary rides along for the reason produce's own repair
+              // REPLAY passes it (its cached-repairs block): a
+              // dictionary-vouched correction clears the phonetic gate only
+              // when the vouched set is present, and `applyRepairs` re-decides
+              // every proposal it is handed rather than trusting the stored
+              // verdict.
+              // `dictionary` is `unknown` on the config (file-only, validated
+              // at the consumer — config.ts's posture), narrowed here the same
+              // way `retranscribeSettings` narrows it a few hundred lines up.
+              const rawDict = (opts.loadCfg ?? loadConfig)().dictionary;
+              const dictionary =
+                Array.isArray(rawDict) && rawDict.every((t) => typeof t === "string")
+                  ? (rawDict as string[])
+                  : undefined;
+              const decided = applyRepairs(
+                parsedTranscript.data,
+                applied.map((r) => ({
+                  startWord: Number(r.startWord),
+                  endWord: Number(r.endWord),
+                  heard: String(r.heard),
+                  correction: String(r.correction),
+                })),
+                { dictionary },
+              );
+              // A repair that produce APPLIED but this replay refuses means the
+              // reconstruction is not the array the placements were counted
+              // against — and a refused splice can change the word count, so
+              // every index after it would be off by one with nothing to say
+              // so. Refuse the whole word list rather than serve a plausible
+              // wrong one (§137's never-misapply rule): the lane hides, and no
+              // gesture can write an index into the wrong space.
+              words = decided.applied.every((r) => r.applied)
+                ? decided.transcript.words
+                : null;
+            }
+          }
+          return send(200, {
+            sfx: parsedSfx.success ? parsedSfx.data : null,
+            // METADATA only, like the library route: text and SOURCE seconds,
+            // which is all the client needs to map an index through its own
+            // live TimeMap.
+            words:
+              words === null
+                ? null
+                : words.map((w) => ({ text: w.text, start: w.start, end: w.end })),
+          });
+        }
+
+        if (url.pathname === "/api/sfx/library" && req.method === "GET") {
+          // The sound palette: what the swap dropdown offers and what a
+          // click-to-preview can play. NO workdir guard, unlike its siblings —
+          // the library is machine-global (every pack in ~/.ossclip/sfx, plus
+          // the bundled one unless `sfxBundledPack` excludes it), so it has
+          // nothing to do with which project is open, and the panel can render
+          // its menu before one is.
+          const library = sfxLibrary();
+          return send(200, {
+            // METADATA only: `absPath` stays server-side. The client addresses
+            // a sound by id through /api/sfx/audio, which is what keeps the
+            // filesystem out of a value the page could ever hand back (the
+            // audio route's path rule is the other half of the same decision).
+            sounds: library.sounds.map((s) => ({
+              id: s.id,
+              whenToUse: s.whenToUse,
+              tags: s.tags,
+              gain: s.gain,
+              ...(s.durationSec !== undefined ? { durationSec: s.durationSec } : {}),
+              packName: s.packName,
+            })),
+            // A user pack with a typo is a thing to SHOW, not to swallow: the
+            // loader already degraded rather than throwing, and the panel is
+            // the only surface a `~/.ossclip/sfx` author ever sees.
+            issues: library.issues,
+          });
+        }
+
+        if (url.pathname === "/api/luts" && req.method === "GET") {
+          // The Color panel's .cube menu plus the config-level default grade.
+          // NO workdir guard, /api/sfx/library's rule: both halves are
+          // machine-global (~/.ossclip/luts and config.json), so the panel can
+          // build its dropdown before a project is open. Read per request like
+          // every other loadCfg consumer — a LUT dropped while the editor is
+          // up appears on the next refresh, not on a restart.
+          const library = (opts.loadLuts ?? loadLutLibrary)();
+          // The config grade rides along VALIDATED, not raw: a malformed
+          // config value is what produce ignores (`resolveProductionColorGrade`
+          // warns and proceeds without it), so a "Default (…)" entry built
+          // from it would offer an inherit that renders as nothing. Null means
+          // the panel shows no Default entry, and the warning is dropped for
+          // the sfxLibrary helper's reason — no console here, produce prints
+          // it on the run that grades.
+          const configGrade = resolveColorGrade(
+            (opts.loadCfg ?? loadConfig)().colorGrade,
+            "config",
+          ).grade;
+          return send(200, {
+            // METADATA only, the sfx library rule: the absolute `path` stays
+            // server-side. `file` (the basename, extension and all) is what an
+            // editor-written override must carry — `ColorGrade.lut` documents
+            // the basename, produce joins it against ~/.ossclip/luts verbatim,
+            // and a stem-only id would drop the `.CUBE` an exporter spelled.
+            items: library.items.map((l) => ({ id: l.id, title: l.title, file: basename(l.path) })),
+            // A ~/.ossclip/luts author's only surface, like the sfx panel:
+            // the loader degraded instead of throwing, so show the reason.
+            issues: library.issues,
+            configGrade: configGrade ?? null,
+          });
+        }
+
+        if (url.pathname === "/api/sfx/audio" && req.method === "GET") {
+          // Click-to-preview. The path comes from the LOADED LIBRARY, never
+          // from the client: the query carries an id, the id is looked up, and
+          // the file that answers is whatever `loadSfxLibrary` resolved for it.
+          // A traversal attempt is therefore not a path to reject but an id
+          // nothing answers to — a plain 404, the same as any other unknown id
+          // (and `SfxSoundSchema.id` is a slug, so no id can ever spell a path
+          // in the first place).
+          const id = url.searchParams.get("id") ?? "";
+          const sound = sfxLibrary().sounds.find((s) => s.id === id);
+          // Existence is re-checked here for `resolveSfxCues`' reason: a pack
+          // deleted since the library was read must be a 404, not a 500 out of
+          // `statSync` inside `sendFile`.
+          if (sound === undefined || !existsSync(sound.absPath)) {
+            return send(404, { error: `no sound "${id}" in the library` });
+          }
+          // No range support: these are sub-second files an `<audio>` element
+          // plays whole, and a preview has nothing to seek through.
+          sendFile(
+            req,
+            res,
+            sound.absPath,
+            MIME[extname(sound.absPath).toLowerCase()] ?? "application/octet-stream",
+            false,
+          );
+          return;
+        }
+
         if (url.pathname.startsWith("/media/")) {
           if (!workdir) return send(409, { error: "no workdir open" });
           const file = join(workdir, decodeURIComponent(url.pathname.slice("/media/".length)));
@@ -2420,7 +2742,22 @@ export async function startEditServer(
     })();
   });
 
-  await new Promise<void>((r) => server.listen(opts.port ?? 5174, "127.0.0.1", r));
+  // REJECT on a failed bind, don't crash. Without the error listener an
+  // EADDRINUSE is an unhandled 'error' event on the server object, which is
+  // fatal to the whole process — that raw Node stack (plus the package
+  // manager's ELIFECYCLE after it) is exactly what a busy 5174 printed at
+  // users, and `openEditServer` (edit-port.ts) cannot offer to attach to the
+  // editor already running there unless the failure comes back as a rejection
+  // it can catch. The listener is removed on success so a LATER runtime error
+  // (a client resetting a connection) keeps whatever handling http gives it.
+  await new Promise<void>((res, rej) => {
+    const onError = (err: Error): void => rej(err);
+    server.once("error", onError);
+    server.listen(opts.port ?? 5174, "127.0.0.1", () => {
+      server.off("error", onError);
+      res();
+    });
+  });
   const addr = server.address();
   const port = typeof addr === "object" && addr ? addr.port : (opts.port ?? 5174);
   return {

package/src/interactive/offer-editor.ts

@@ -11,7 +11,17 @@ import { renderCommand } from "./render";
  */
 export async function offerEditor(
   result: ProduceResult,
-  opts: { flag: boolean | undefined; port: number },
+  opts: {
+    flag: boolean | undefined;
+    port: number;
+    /**
+     * Whether the user TYPED `--editor-port`. Commander's 5174 default is not
+     * a choice anybody made, so the common case must be free to attach or step
+     * around a busy port; only a typed port is defended (edit-port.ts's
+     * `pinned`, and the `--port` half of the same rule in program.ts).
+     */
+    portPinned: boolean;
+  },
 ): Promise<void> {
   const pref: OpenEditorPref = loadConfig().openEditorAfterProduce ?? "ask";
   const decision = decideOpenEditor({
@@ -64,8 +74,23 @@ export async function offerEditor(
     );
     return;
   }
-  const server = await startEditServer(result.workdir, { port: opts.port, pageDir });
-  console.log(`▸ editor at ${server.url}`);
+  // The same busy-port ladder `ossclip edit` runs (edit-port.ts): a produce
+  // finishing into an already-open editor on THIS project attaches to it
+  // instead of dying on EADDRINUSE — which here would throw away the run's
+  // whole summary behind a stack trace. `liveEditPortDeps` reads the real
+  // `isInteractive()`, so the three-way prompt is available exactly where this
+  // offer already asks questions, and absent in a piped run.
+  const { openEditServer, liveEditPortDeps } = await import("../edit-port");
+  const opened = await openEditServer(
+    result.workdir,
+    { port: opts.port, pinned: opts.portPinned },
+    liveEditPortDeps((port) => startEditServer(result.workdir, { port, pageDir })),
+  );
+  if (opened.kind === "cancelled") return;
+  const url = opened.kind === "attached" ? opened.url : opened.server.url;
+  // The attach path already printed "▸ already open at …"; a second line
+  // underneath it would read as a second server.
+  if (opened.kind === "started") console.log(`▸ editor at ${url}`);
   const { openInBrowser } = await import("../open");
-  openInBrowser(server.url);
+  openInBrowser(url);
 }

package/src/interactive/produce-argv.ts

@@ -1,4 +1,4 @@
-import type { ProviderName } from "@ossclip/core";
+import type { ProviderName, SfxLevel } from "@ossclip/core";
 
 /**
  * Wizard answers → the argv a user could have typed.
@@ -35,6 +35,16 @@ export interface ProduceExtras {
    * it exists to beat a future config-off, and emitting it here would
    * restate the default. */
   jumpCuts?: boolean;
+  /** Sound effects, the watermark's polarity with a level attached: PRESENT
+   * means on (the wizard only ever turns it ON — off is the default, there is
+   * no `--no-sfx` spelling to mirror, and a config-on user who wants silence
+   * for one run edits the config's `sfx` key), and the value is whatever the
+   * level follow-up answered. Typed as core's `SfxLevel`, not an inline
+   * union, for `llm`'s reason: a level added to `SfxLevelSchema` must not be
+   * silently unofferable here. Only reachable under graphics — sound effects
+   * are placed against the producer's beat sheet, so `extrasFor` gates the
+   * entry the way it gates `--clip`. */
+  sfx?: SfxLevel;
   /** The YouTube pack (Y2): the wizard only ever turns it ON — off is the
    * default, and a config-on user who wants it off for one run types
    * `--no-youtube`, flags-only like `--no-watermark`. */
@@ -116,6 +126,13 @@ export function produceArgv(a: ProduceAnswers): string[] {
   // negative spelling — auto must stay an ABSENT flag, or the taught
   // command line restates a default.
   if (e.jumpCuts === false) argv.push("--no-jump-cuts");
+  // One flag, never both: `--sfx-level` already implies `--sfx` (program.ts's
+  // `sfxFlag`), which is why replay-argv pins a level WITHOUT the switch too —
+  // emitting the pair would teach a flag that changes nothing. And `normal` is
+  // the CLI's own default, so naming it would restate a default per the
+  // elision rule above: a normal-level run's whole sound design is `--sfx`.
+  if (e.sfx === "normal") argv.push("--sfx");
+  else if (e.sfx !== undefined) argv.push("--sfx-level", e.sfx);
   // Watermark's shape: only the ON tick emits (off is the default, elided),
   // and the portrait only rides along with a value — the wizard already
   // dropped empty answers.

package/src/interactive/produce-wizard.ts

@@ -10,13 +10,20 @@ import { produceArgv, type ProduceAnswers, type ProduceExtras } from "./produce-
 import { assertInteractive, confirm, intro, multiselect, select, text, unwrap } from "./prompts";
 
 /**
- * The produce wizard. Forty-one flags (plus the positional input path)
+ * The produce wizard. Forty-three flags (plus the positional input path)
  * sorted into three tiers: six prompts asked directly — the input path, plus
- * five flags (--out, --cleanup, --aspect, --produce, --intent) — eleven
- * behind one "anything else?" multiselect, and the remaining stay flags-only:
+ * five flags (--out, --cleanup, --aspect, --produce, --intent) — twelve
+ * behind one "anything else?" multiselect (--sfx being the twelfth, with
+ * --sfx-level as its follow-up prompt rather than an entry of its own), and the remaining stay flags-only:
  * debug/internal surfaces, replay-only fields, --no-watermark (the
  * multiselect only turns the credit ON; off is already the default),
  * --no-youtube (the same shape: the pack entry only turns it ON),
+ * --color-grade (2026-08-30, the --resolution shape: a channel's look is a
+ * durable machine preference, set once as `colorGrade` in
+ * ~/.ossclip/config.json rather than re-picked per wizard run — and an
+ * honest prompt would need to enumerate ~/.ossclip/luts and preview five
+ * presets, a design nobody has made; --no-color-grade then mirrors
+ * --no-watermark's tier for the same off-is-default reason),
  * --captions (the mirror case: ON is already the default, so the
  * multiselect entry is the OFF switch and the positive flag exists only for
  * replay pinning), --add-jump-cuts (same mirror: auto already punches, the
@@ -48,6 +55,11 @@ const EXTRAS = [
   { value: "sourceIsEdited", label: "Source already has burned-in text", hint: "--source-is-edited" },
   { value: "captionsOff", label: "Turn the burned-in captions off", hint: "--no-captions" },
   { value: "jumpCutsOff", label: "No punch-in zooms at cuts", hint: "--no-jump-cuts" },
+  // Watermark/youtube polarity: OFF is the default and the entry only ever
+  // turns it ON — `--no-sfx` does not exist (program.ts declares `--sfx`
+  // alone so the config's `sfx` key can still supply it), so there is no OFF
+  // spelling to mirror in a second entry.
+  { value: "sfx", label: "Add sound effects (whoosh, ding…)", hint: "--sfx" },
   { value: "watermark", label: 'Credit the tool with a small "made with ossclip"', hint: "--watermark" },
   // The hint says the approval part out loud (thumbnail UX, 2026-08-16):
   // ticking this adds an interactive stop before the render, and a surprise
@@ -69,6 +81,15 @@ const EXTRAS = [
  * graphics is already on. Exported and kept pure so this can be asserted
  * without a TTY.
  *
+ * The sfx entry is gated on the same precedent (2026-08-29). Sound effects
+ * are placed against the producer's beat sheet, so a `--sfx` run without
+ * `--produce` reaches produce.ts's own "sound effects are placed against the
+ * producer's beat sheet — add --produce" warning and renders silent (a
+ * previous run's plan in the workdir is the only thing that saves it, which
+ * is not something a menu can promise). A guaranteed-inert menu item is the
+ * same broken offer as the clip one, softer only in that it warns instead of
+ * throwing — so it is only ever listed once graphics is already on.
+ *
  * `watermarkFromConfig` (review, minor a): on a config-on machine the
  * watermark entry sits UNCHECKED while the credit will render anyway —
  * unchecked is "don't emit the flag", not "off", and the multiselect has no
@@ -81,7 +102,9 @@ export function extrasFor(
   graphics: boolean,
   opts: { watermarkFromConfig?: boolean } = {},
 ): { value: (typeof EXTRAS)[number]["value"]; label: string; hint: string }[] {
-  const list = graphics ? [...EXTRAS] : EXTRAS.filter((e) => e.value !== "graphicsClip");
+  const list = graphics
+    ? [...EXTRAS]
+    : EXTRAS.filter((e) => e.value !== "graphicsClip" && e.value !== "sfx");
   if (opts.watermarkFromConfig !== true) return [...list];
   return list.map((e) =>
     e.value === "watermark"
@@ -346,6 +369,26 @@ export async function produceWizard(
   // Same OFF-switch shape (the punch defaults ON, face-only): a tick maps
   // to `jumpCuts: false` and produceArgv emits `--no-jump-cuts`.
   if (chosen.includes("jumpCutsOff")) extras.jumpCuts = false;
+  if (chosen.includes("sfx")) {
+    // Follow-up under the same extra, like --clip's seconds prompt: the level
+    // only means anything once effects are on. `normal` is preselected
+    // because it is the CLI's own default — and picking it still emits the
+    // bare `--sfx` rather than `--sfx-level normal`, produceArgv's
+    // default-elision rule. The hints say what the level actually CHANGES
+    // (density, and whether the meme-tagged sounds are eligible at all),
+    // because "subtle/normal/meme" alone reads as a volume knob.
+    extras.sfx = unwrap(
+      await select({
+        message: "How much sound design?",
+        initialValue: "normal",
+        options: [
+          { value: "subtle", label: "subtle", hint: "a couple of accents a minute" },
+          { value: "normal", label: "normal", hint: "recommended" },
+          { value: "meme", label: "meme", hint: "denser, and meme-tagged sounds become eligible" },
+        ],
+      }),
+    ) as ProduceExtras["sfx"];
+  }
   if (chosen.includes("watermark")) extras.watermark = true;
   if (chosen.includes("youtube")) {
     extras.youtube = true;