From 009345a5591b3aac004ee089e205c7c65f529202 Mon Sep 17 00:00:00 2001
From: ishan pandey <ishanpandey@ishans-MacBook-Air.local>
Date: Mon, 27 Apr 2026 21:30:59 +0530
Subject: [PATCH] feat: per-scene sfx via elevenlabs (milestone a of #25)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first audio-bed retention lever from the SFX/Music + Gemini plan
(#25). Per-scene generated sound effects landing on the existing SFX
lane that PR #20 placeholders wired.

**Backend** (`packages/core`)

- `elevenlabs/sfx.ts` — `generateSoundEffect(apiKey, prompt, opts)` mirrors
  the existing `synthesize()` shape: returns mp3 bytes + format. Clamps
  duration to 0.5..22, prompt influence to 0..1. Surfaces ElevenLabsError
  with the raw HTTP detail so the studio can show a meaningful 502.
- `script/sfx/manifest.ts` — append-only manifest at
  `assets/sfx/sfx.manifest.json`. Three anchors (scene-start /
  accent-word / scene-end). Pure-helper `resolveSfxStart` does the
  anchor → absolute-time math; `resolveSfxStartForScene` wraps it with
  scene + cursor lookup so the assembler can call it directly.
- `assemble.ts` reads the manifest once per assemble, groups by sceneId,
  and emits `<audio data-track-index="3" data-timeline-group="sfx">`
  elements alongside the existing voiceover audio. Already-existing SFX
  lane placeholder picks them up natively — no runtime/timeline changes.
- 4 new storyline routes:
    POST  /storyline/sfx-suggest    Haiku 4.5 → 1-3 prompt+anchor ideas
    POST  /storyline/sfx-generate   ElevenLabs → mp3 + manifest append
    GET   /storyline/sfx            current manifest
    DELETE /storyline/sfx/:entryId  manifest remove (audio file kept)

  All four cost-tracked (`script.storyline.sfx.suggest` / `.generate`).
  Suggest is ~$0.001/call; generate is one ElevenLabs SFX credit.

**Frontend** (`packages/studio`)

- New `🔊 Add SFX` per-card AI action. Click → Haiku returns 1-3 prompt
  ideas, rendered in a new amber-tinted suggestion stack below the
  regular Haiku stack. Each row shows label + prompt + duration +
  anchor + rationale + 🔊 Generate button. Clicking Generate calls
  the ElevenLabs route, writes the file, refreshes the manifest, and
  re-reads the script (so the SFX immediately lands on the timeline's
  SFX lane).
- New emerald "SFX on lane" stack on each card lists already-applied
  SFX with HTML5 `<audio controls>` audition + Remove button.
- `StorylineTab` adds three independent state maps (proposed / applied /
  generationStatus) so the UI stays responsive while ElevenLabs
  generates one and the user previews another.

**Tests** (`packages/core`)

- 10 anchor-math cases covering scene-start / scene-end (with SFX
  longer than the scene → clamps to sceneStart, never preceding it),
  accent-word interpolation (0, mid, last, past-last clamps to last,
  negative clamps to 0, empty narration falls back to scene-start),
  custom focal-line fractions.

Tests: 729 core (+10) + 281 studio passing. Lint, format, typecheck
clean. Verified live: 16 scene cards render, 16 "🔊 Add SFX" buttons
visible, zero console errors.

Plan: #25 (Milestone A of six). Next milestones (B Music, C Gemini
render review, D Image analysis, E Scroll test, F Retention map) layer
on this same SFX manifest pattern + applyPatch pipeline.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/core/src/elevenlabs/index.ts         |   2 +
 packages/core/src/elevenlabs/sfx.ts           | 104 ++++++
 packages/core/src/script/assemble.ts          |  28 ++
 packages/core/src/script/sfx/manifest.test.ts | 145 ++++++++
 packages/core/src/script/sfx/manifest.ts      | 204 +++++++++++
 .../core/src/studio-api/routes/storyline.ts   | 335 +++++++++++++++++-
 .../src/components/sidebar/StorylineTab.tsx   | 178 +++++++++-
 .../src/components/storyline/SceneCard.tsx    | 225 +++++++++++-
 8 files changed, 1196 insertions(+), 25 deletions(-)
 create mode 100644 packages/core/src/elevenlabs/sfx.ts
 create mode 100644 packages/core/src/script/sfx/manifest.test.ts
 create mode 100644 packages/core/src/script/sfx/manifest.ts

diff --git a/packages/core/src/elevenlabs/index.ts b/packages/core/src/elevenlabs/index.ts
index 25fc83dc2..977740358 100644
--- a/packages/core/src/elevenlabs/index.ts
+++ b/packages/core/src/elevenlabs/index.ts
@@ -15,3 +15,5 @@ export {
   ElevenLabsError,
 } from "./client.js";
 export type { ElevenLabsVoice, SynthesizeOptions } from "./client.js";
+export { generateSoundEffect, clampSfxDuration, SFX_BOUNDS } from "./sfx.js";
+export type { GenerateSfxOptions, GenerateSfxResult } from "./sfx.js";
diff --git a/packages/core/src/elevenlabs/sfx.ts b/packages/core/src/elevenlabs/sfx.ts
new file mode 100644
index 000000000..6b40469c6
--- /dev/null
+++ b/packages/core/src/elevenlabs/sfx.ts
@@ -0,0 +1,104 @@
+/**
+ * ElevenLabs Sound Generation client.
+ *
+ * Mirrors the existing `synthesize()` shape for voice — single function call
+ * that returns audio bytes + chosen format. Errors surface via the same
+ * `ElevenLabsError` so callers get a uniform try/catch shape across
+ * voice / sfx / music.
+ */
+
+import { ElevenLabsError } from "./client.js";
+
+const API_BASE = "https://api.elevenlabs.io/v1";
+
+export interface GenerateSfxOptions {
+  /** 0.5..22 seconds. ElevenLabs treats this as a target — actual ±20%. */
+  durationSeconds?: number;
+  /**
+   * 0..1. Higher = stick closer to the prompt; lower = more creative
+   * variation. Default 0.3 matches ElevenLabs's own default for the SFX
+   * playground.
+   */
+  promptInfluence?: number;
+  /** Output format. mp3_44100_128 is the cheapest acceptable quality for SFX. */
+  outputFormat?: "mp3_44100_128" | "mp3_44100_192";
+}
+
+export interface GenerateSfxResult {
+  bytes: Uint8Array;
+  format: NonNullable<GenerateSfxOptions["outputFormat"]>;
+}
+
+/**
+ * Generate one sound effect from a text prompt. Returns mp3 bytes — caller
+ * writes them to disk.
+ *
+ *     const { bytes } = await generateSoundEffect(apiKey, "snap zoom whoosh", { durationSeconds: 1.5 });
+ *     fs.writeFileSync("sfx.mp3", bytes);
+ *
+ * Cost is billed per generation, not per duration — short SFX cost the same
+ * as long ones up to the 22-second cap. Surface the count in the cost log.
+ */
+export async function generateSoundEffect(
+  apiKey: string,
+  prompt: string,
+  opts: GenerateSfxOptions = {},
+): Promise<GenerateSfxResult> {
+  if (!prompt || !prompt.trim()) {
+    throw new ElevenLabsError("generateSoundEffect: prompt is required");
+  }
+  const trimmed = prompt.trim();
+  if (trimmed.length > 1000) {
+    throw new ElevenLabsError("generateSoundEffect: prompt too long (max 1000 chars)");
+  }
+  const format = opts.outputFormat ?? "mp3_44100_128";
+  const body: Record<string, unknown> = { text: trimmed, output_format: format };
+  if (typeof opts.durationSeconds === "number") {
+    // ElevenLabs caps at 0.5..22 — clamp here so a misconfigured caller
+    // doesn't get a 422 round-trip.
+    body.duration_seconds = Math.max(0.5, Math.min(22, opts.durationSeconds));
+  }
+  if (typeof opts.promptInfluence === "number") {
+    body.prompt_influence = Math.max(0, Math.min(1, opts.promptInfluence));
+  }
+
+  const res = await fetch(`${API_BASE}/sound-generation`, {
+    method: "POST",
+    headers: {
+      "xi-api-key": apiKey,
+      "Content-Type": "application/json",
+      Accept: "audio/mpeg",
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    let detail = "";
+    try {
+      const text = await res.text();
+      detail = text.length > 500 ? text.slice(0, 500) + "…" : text;
+    } catch {
+      /* ignore */
+    }
+    throw new ElevenLabsError(
+      `generateSoundEffect: ${res.status} ${res.statusText}${detail ? ` — ${detail}` : ""}`,
+      res.status,
+    );
+  }
+  const buf = new Uint8Array(await res.arrayBuffer());
+  return { bytes: buf, format };
+}
+
+/**
+ * Helpers for clamping values before they hit the wire — exported so the
+ * studio API route can reuse the same bounds when validating user input.
+ */
+export const SFX_BOUNDS = {
+  durationMin: 0.5,
+  durationMax: 22,
+  promptMaxChars: 1000,
+} as const;
+
+export function clampSfxDuration(durationSeconds: number): number {
+  if (!Number.isFinite(durationSeconds)) return 2;
+  return Math.max(SFX_BOUNDS.durationMin, Math.min(SFX_BOUNDS.durationMax, durationSeconds));
+}
diff --git a/packages/core/src/script/assemble.ts b/packages/core/src/script/assemble.ts
index 169847e19..8412b9731 100644
--- a/packages/core/src/script/assemble.ts
+++ b/packages/core/src/script/assemble.ts
@@ -8,6 +8,7 @@ import { getLoadedThemeByName } from "./themes/index.js";
 import type { PlannedScene, PlannedScript, SceneTransition } from "./types.js";
 import type { ImageEntry, ImageManifest } from "../images/index.js";
 import type { VisualDirectionPlan } from "./visualDirector.js";
+import { readSfxManifest, resolveSfxStartForScene, type SfxEntry } from "./sfx/manifest.js";
 
 export interface AssembleOptions {
   projectDir: string;
@@ -75,6 +76,17 @@ export function assembleMaster(planned: PlannedScript, opts: AssembleOptions): A
   let cursor = 0;
   const sceneFragments: string[] = [];
   const audioTags: string[] = [];
+
+  // SFX manifest: read once, group entries by sceneId so each scene's loop
+  // iteration can emit them at the right cursor position. The manifest is
+  // optional — projects without it just skip the SFX lane.
+  const sfxManifest = readSfxManifest(opts.projectDir);
+  const sfxBySceneId = new Map<string, SfxEntry[]>();
+  for (const entry of sfxManifest.entries) {
+    const list = sfxBySceneId.get(entry.sceneId) ?? [];
+    list.push(entry);
+    sfxBySceneId.set(entry.sceneId, list);
+  }
   const sceneVisibility: Array<{
     id: string;
     start: number;
@@ -182,6 +194,22 @@ export function assembleMaster(planned: PlannedScript, opts: AssembleOptions): A
         `  <audio id="hf-vo-${scene.id}" src="${escapeAttr(scene.audio.path)}" data-start="${audioStart.toFixed(2)}" data-duration="${audioDur.toFixed(2)}" data-track-index="1" data-timeline-group="voiceover" data-timeline-label="Voiceover" preload="auto"></audio>`,
       );
     }
+
+    // SFX entries land on track 3 with the same audio timing rules as the
+    // voiceover. Each entry's start time is computed from its anchor (scene-
+    // start / accent-word / scene-end) — see resolveSfxStartForScene for
+    // the math. Volume scales the runtime mixer when supplied; the producer
+    // package consumes data-volume-db at render time.
+    const sceneSfx = sfxBySceneId.get(scene.id) ?? [];
+    for (const entry of sceneSfx) {
+      const start = resolveSfxStartForScene(entry, scene, cursor, sceneTotal);
+      const volumeAttr =
+        typeof entry.volumeDb === "number" ? ` data-volume-db="${entry.volumeDb.toFixed(1)}"` : "";
+      const labelAttr = entry.label ? ` data-timeline-label="${escapeAttr(entry.label)}"` : "";
+      audioTags.push(
+        `  <audio id="hf-sfx-${scene.id}-${entry.id}" src="${escapeAttr(entry.path)}" data-start="${start.toFixed(2)}" data-duration="${entry.durationSeconds.toFixed(2)}" data-track-index="3" data-timeline-group="sfx"${labelAttr}${volumeAttr} preload="auto"></audio>`,
+      );
+    }
     const transitionIn: SceneTransition =
       scene.transition ?? defaultTransitionForTemplate(scene.template);
     const transitionInMs = (TRANSITION_DURATIONS[transitionIn] ?? 0) * 1000;
diff --git a/packages/core/src/script/sfx/manifest.test.ts b/packages/core/src/script/sfx/manifest.test.ts
new file mode 100644
index 000000000..9d6ded79c
--- /dev/null
+++ b/packages/core/src/script/sfx/manifest.test.ts
@@ -0,0 +1,145 @@
+import { describe, it, expect } from "vitest";
+import { resolveSfxStart, type SfxEntry } from "./manifest";
+
+const baseEntry: Pick<SfxEntry, "anchor" | "accentWordIndex" | "durationSeconds"> = {
+  anchor: "scene-start",
+  durationSeconds: 1.5,
+};
+
+describe("resolveSfxStart", () => {
+  it("scene-start anchor returns sceneStart + audioStartOffset", () => {
+    expect(
+      resolveSfxStart({
+        sceneStart: 10,
+        sceneDuration: 6,
+        audioStartOffset: 0.15,
+        voiceDurationSeconds: 5,
+        voiceWordCount: 12,
+        entry: { ...baseEntry, anchor: "scene-start" },
+      }),
+    ).toBeCloseTo(10.15, 3);
+  });
+
+  it("scene-start with zero lead-in returns sceneStart exactly", () => {
+    expect(
+      resolveSfxStart({
+        sceneStart: 30,
+        sceneDuration: 4,
+        audioStartOffset: 0,
+        voiceDurationSeconds: 3,
+        voiceWordCount: 8,
+        entry: { ...baseEntry, anchor: "scene-start" },
+      }),
+    ).toBe(30);
+  });
+
+  it("scene-end anchor places SFX so it finishes at scene end", () => {
+    // sceneEnd = 16; SFX is 1.5s long → start at 14.5
+    expect(
+      resolveSfxStart({
+        sceneStart: 10,
+        sceneDuration: 6,
+        audioStartOffset: 0.15,
+        voiceDurationSeconds: 5,
+        voiceWordCount: 12,
+        entry: { ...baseEntry, anchor: "scene-end", durationSeconds: 1.5 },
+      }),
+    ).toBe(14.5);
+  });
+
+  it("scene-end with SFX longer than scene clamps to sceneStart (won't precede the scene)", () => {
+    expect(
+      resolveSfxStart({
+        sceneStart: 50,
+        sceneDuration: 2,
+        audioStartOffset: 0,
+        voiceDurationSeconds: 1.5,
+        voiceWordCount: 4,
+        entry: { ...baseEntry, anchor: "scene-end", durationSeconds: 5 },
+      }),
+    ).toBe(50);
+  });
+
+  it("accent-word anchor interpolates by word index", () => {
+    // 4 words over 5s narration → each word gets ~1.25s; word index 2 = 2 * 1.25 = 2.5s
+    // sceneStart 10 + audioStartOffset 0.15 + 2.5 = 12.65
+    expect(
+      resolveSfxStart({
+        sceneStart: 10,
+        sceneDuration: 6,
+        audioStartOffset: 0.15,
+        voiceDurationSeconds: 5,
+        voiceWordCount: 4,
+        entry: { ...baseEntry, anchor: "accent-word", accentWordIndex: 2 },
+      }),
+    ).toBeCloseTo(12.65, 3);
+  });
+
+  it("accent-word with index 0 = scene-start + offset (the first word fires immediately)", () => {
+    expect(
+      resolveSfxStart({
+        sceneStart: 10,
+        sceneDuration: 6,
+        audioStartOffset: 0.15,
+        voiceDurationSeconds: 5,
+        voiceWordCount: 5,
+        entry: { ...baseEntry, anchor: "accent-word", accentWordIndex: 0 },
+      }),
+    ).toBeCloseTo(10.15, 3);
+  });
+
+  it("accent-word with index past the word count clamps to last word", () => {
+    // wordCount 5, requested index 99 → clamps to 4 (last word).
+    // Each word = 5 / 5 = 1s. Index 4 = 4s offset. 10 + 0.15 + 4 = 14.15
+    expect(
+      resolveSfxStart({
+        sceneStart: 10,
+        sceneDuration: 6,
+        audioStartOffset: 0.15,
+        voiceDurationSeconds: 5,
+        voiceWordCount: 5,
+        entry: { ...baseEntry, anchor: "accent-word", accentWordIndex: 99 },
+      }),
+    ).toBeCloseTo(14.15, 3);
+  });
+
+  it("accent-word falls back to scene-start when narration is empty", () => {
+    expect(
+      resolveSfxStart({
+        sceneStart: 8,
+        sceneDuration: 4,
+        audioStartOffset: 0.2,
+        voiceDurationSeconds: 0,
+        voiceWordCount: 0,
+        entry: { ...baseEntry, anchor: "accent-word", accentWordIndex: 3 },
+      }),
+    ).toBeCloseTo(8.2, 3);
+  });
+
+  it("accent-word with negative index clamps to 0", () => {
+    expect(
+      resolveSfxStart({
+        sceneStart: 10,
+        sceneDuration: 6,
+        audioStartOffset: 0,
+        voiceDurationSeconds: 4,
+        voiceWordCount: 4,
+        entry: { ...baseEntry, anchor: "accent-word", accentWordIndex: -5 },
+      }),
+    ).toBe(10);
+  });
+
+  it("never returns a value before sceneStart", () => {
+    // Defensive: scene-end with bizarre inputs.
+    expect(
+      resolveSfxStart({
+        sceneStart: 100,
+        sceneDuration: 0.1,
+        audioStartOffset: 0,
+        voiceDurationSeconds: 0.05,
+        voiceWordCount: 1,
+        entry: { ...baseEntry, anchor: "scene-end", durationSeconds: 99 },
+      }),
+    ).toBe(100);
+  });
+});
diff --git a/packages/core/src/script/sfx/manifest.ts b/packages/core/src/script/sfx/manifest.ts
new file mode 100644
index 000000000..f8d266d3f
--- /dev/null
+++ b/packages/core/src/script/sfx/manifest.ts
@@ -0,0 +1,204 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { PlannedScene } from "../types.js";
+
+/**
+ * SFX manifest — the contract between the storyline routes (which generate
+ * sound-effects via ElevenLabs) and the assembler (which emits
+ * `<audio data-track-index="3">` elements onto the SFX lane).
+ *
+ * Stored at `<project>/assets/sfx/sfx.manifest.json`. Audio files live next to
+ * it as `<sceneId>-<entryId>.mp3`. Manifests are append-only from the
+ * studio's perspective — the user can delete entries, but each generation
+ * mints a stable id so the assembler's output is reproducible across
+ * re-runs.
+ *
+ * Why a manifest (not script.json fields):
+ *   - Script.json is purely about narration + scene visual decisions. Audio
+ *     assets stay decoupled.
+ *   - The manifest can be regenerated independently if the user wipes
+ *     `assets/sfx/` and wants to re-run.
+ *   - Future tooling (CLI prune, "regenerate all"} can operate on the
+ *     manifest without parsing script.json.
+ */
+
+export const SFX_DIR = "assets/sfx";
+export const SFX_MANIFEST = "sfx.manifest.json";
+export const SFX_MANIFEST_VERSION = 1;
+
+/**
+ * Where this SFX should land on the timeline relative to the scene window.
+ * Three anchors cover ~95% of cinematic usage; resist adding free-form
+ * offsets until a concrete user need shows up.
+ */
+export type SfxAnchor = "scene-start" | "accent-word" | "scene-end";
+
+export interface SfxEntry {
+  /** Stable id per generation. Used as the filename suffix. */
+  id: string;
+  /** Owning scene. Each entry is anchored relative to its scene's window. */
+  sceneId: string;
+  /** The text prompt sent to ElevenLabs. Surfaced in the studio for context. */
+  prompt: string;
+  /** Path under the project root. Always `assets/sfx/<sceneId>-<id>.mp3`. */
+  path: string;
+  /** Measured duration of the file (seconds) — the assembler uses this to
+   *  set `data-duration` so the timeline shows the real footprint. */
+  durationSeconds: number;
+  /** Where in the scene window to anchor playback. */
+  anchor: SfxAnchor;
+  /**
+   * For `accent-word` anchor: the 0-based word index inside the narration to
+   * align to. Ignored for the other anchors. The assembler treats this as a
+   * Phase-A heuristic — see `resolveSfxStart` for the math.
+   */
+  accentWordIndex?: number;
+  /** Optional human label for the SFX (e.g. "broadcast static") — shown on
+   *  the SFX lane clip. Defaults to a truncation of the prompt. */
+  label?: string;
+  /** Volume in dB (0 = full). Surface to the producer's audio mixer. */
+  volumeDb?: number;
+  /** ISO timestamp the entry was created. Used for "regenerate" decisions. */
+  createdAt: string;
+}
+
+export interface SfxManifest {
+  version: number;
+  entries: SfxEntry[];
+}
+
+export function emptyManifest(): SfxManifest {
+  return { version: SFX_MANIFEST_VERSION, entries: [] };
+}
+
+export function readSfxManifest(projectDir: string): SfxManifest {
+  const path = join(projectDir, SFX_DIR, SFX_MANIFEST);
+  if (!existsSync(path)) return emptyManifest();
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8")) as Partial<SfxManifest>;
+    if (!raw || typeof raw !== "object") return emptyManifest();
+    const entries = Array.isArray(raw.entries) ? raw.entries.filter(isValidEntry) : [];
+    return { version: SFX_MANIFEST_VERSION, entries };
+  } catch {
+    return emptyManifest();
+  }
+}
+
+export function writeSfxManifest(projectDir: string, manifest: SfxManifest): void {
+  const path = join(projectDir, SFX_DIR, SFX_MANIFEST);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n");
+}
+
+export function appendSfxEntry(projectDir: string, entry: SfxEntry): SfxManifest {
+  const manifest = readSfxManifest(projectDir);
+  manifest.entries.push(entry);
+  writeSfxManifest(projectDir, manifest);
+  return manifest;
+}
+
+export function removeSfxEntry(projectDir: string, entryId: string): SfxManifest {
+  const manifest = readSfxManifest(projectDir);
+  manifest.entries = manifest.entries.filter((e) => e.id !== entryId);
+  writeSfxManifest(projectDir, manifest);
+  return manifest;
+}
+
+function isValidEntry(value: unknown): value is SfxEntry {
+  if (!value || typeof value !== "object") return false;
+  const e = value as Record<string, unknown>;
+  return (
+    typeof e.id === "string" &&
+    typeof e.sceneId === "string" &&
+    typeof e.prompt === "string" &&
+    typeof e.path === "string" &&
+    typeof e.durationSeconds === "number" &&
+    typeof e.anchor === "string" &&
+    (e.anchor === "scene-start" || e.anchor === "accent-word" || e.anchor === "scene-end") &&
+    typeof e.createdAt === "string"
+  );
+}
+
+/**
+ * Compute the absolute timeline start time for a single SFX entry given the
+ * scene's window on the master timeline.
+ *
+ * Pure helper — exported for tests so the anchor math is exercised without
+ * touching disk or the assembler.
+ *
+ * Inputs:
+ *   - sceneStart: where the scene begins on the master timeline (s)
+ *   - sceneDuration: scene's total window length (s) — INCLUDING lead-in and
+ *     tail-pad, not just the audio duration
+ *   - audioStartOffset: how many seconds into the scene the voiceover starts
+ *     (= scene.audio.leadInSeconds, defaults to 0)
+ *   - voiceDurationSeconds: voiceover length (s); used to interpolate the
+ *     accent-word position
+ *   - voiceWordCount: number of words in the narration; used as the divisor
+ *     for accent-word interpolation
+ *   - entry: the SFX entry whose anchor + duration determine placement
+ *
+ * Returns the absolute scene-start time. The returned value is clamped so it
+ * never lands before the scene starts; the assembler's separate clip-overlap
+ * guard handles the upper bound.
+ */
+export function resolveSfxStart(input: {
+  sceneStart: number;
+  sceneDuration: number;
+  audioStartOffset: number;
+  voiceDurationSeconds: number;
+  voiceWordCount: number;
+  entry: Pick<SfxEntry, "anchor" | "accentWordIndex" | "durationSeconds">;
+}): number {
+  const { sceneStart, sceneDuration, audioStartOffset, entry } = input;
+  if (entry.anchor === "scene-start") {
+    return Math.max(sceneStart, sceneStart + audioStartOffset);
+  }
+  if (entry.anchor === "scene-end") {
+    // End-anchored SFX should land so it FINISHES at scene end — i.e. its
+    // start is `sceneEnd - sfxDuration`. Clamp to never overlap the next
+    // scene by accident.
+    const sceneEnd = sceneStart + sceneDuration;
+    const start = sceneEnd - Math.max(0, entry.durationSeconds);
+    return Math.max(sceneStart, start);
+  }
+  // accent-word: linear-interpolate based on word index. Phase-A heuristic;
+  // Phase-B will replace with ElevenLabs alignment timestamps.
+  if (input.voiceWordCount <= 0 || input.voiceDurationSeconds <= 0) {
+    // No narration to anchor to — fall back to scene-start.
+    return Math.max(sceneStart, sceneStart + audioStartOffset);
+  }
+  const idx = Math.max(0, Math.min(input.voiceWordCount - 1, entry.accentWordIndex ?? 0));
+  const wordOffset = (idx / input.voiceWordCount) * input.voiceDurationSeconds;
+  return sceneStart + audioStartOffset + wordOffset;
+}
+
+/**
+ * Convenience: given a manifest entry and the assembler's PlannedScene
+ * cursor, compute the start. Wraps `resolveSfxStart` with the scene
+ * lookup so callers can pass `(entry, scene, cursor)` directly.
+ */
+export function resolveSfxStartForScene(
+  entry: SfxEntry,
+  scene: Pick<PlannedScene, "text" | "audio">,
+  sceneStart: number,
+  sceneTotalDurationSeconds: number,
+): number {
+  const audio = scene.audio;
+  return resolveSfxStart({
+    sceneStart,
+    sceneDuration: sceneTotalDurationSeconds,
+    audioStartOffset: audio?.leadInSeconds ?? 0,
+    voiceDurationSeconds: audio?.durationSeconds ?? 0,
+    voiceWordCount: countWords(scene.text),
+    entry,
+  });
+}
+
+function countWords(text: string | undefined | null): number {
+  if (!text) return 0;
+  return text
+    .trim()
+    .split(/\s+/)
+    .filter((w) => w.length > 0).length;
+}
diff --git a/packages/core/src/studio-api/routes/storyline.ts b/packages/core/src/studio-api/routes/storyline.ts
index 7fa6cd0b7..1a07e67da 100644
--- a/packages/core/src/studio-api/routes/storyline.ts
+++ b/packages/core/src/studio-api/routes/storyline.ts
@@ -1,5 +1,5 @@
 import type { Hono } from "hono";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { StudioApiAdapter } from "../types.js";
 import { AnthropicError, callStructuredTool, loadAnthropicKey } from "../../anthropic/index.js";
@@ -7,6 +7,21 @@ import type { ToolDefinition } from "../../anthropic/index.js";
 import { CostLogger, loggerSink } from "../../telemetry/cost.js";
 import type { Script, SceneRef } from "../../script/types.js";
 import { listAvailableThemes, loadDesignBrief, resolveActiveTheme } from "../../script/index.js";
+import {
+  ElevenLabsError,
+  generateSoundEffect,
+  loadElevenLabsKey,
+  SFX_BOUNDS,
+  clampSfxDuration,
+} from "../../elevenlabs/index.js";
+import {
+  appendSfxEntry,
+  readSfxManifest,
+  removeSfxEntry,
+  SFX_DIR,
+  type SfxAnchor,
+  type SfxEntry,
+} from "../../script/sfx/manifest.js";
 
 type Scene = SceneRef;
 
@@ -393,9 +408,317 @@ export function registerStorylineRoutes(api: Hono, adapter: StudioApiAdapter): v
       return c.json({ error: msg }, 500);
     }
   });
+
+  // POST /api/projects/:id/storyline/sfx-suggest
+  // Per-scene SFX prompt suggestions. Haiku reads one scene + a small window
+  // of neighbours (focal ±2 by default) and returns 1-3 sound-effect ideas
+  // with text prompts, durations, and anchors. Generation happens in a
+  // separate call (`/sfx-generate`) so the user can scan multiple ideas
+  // before paying ElevenLabs credits.
+  api.post("/projects/:id/storyline/sfx-suggest", async (c) => {
+    const ctx = await loadActionContext(c.req.param("id"), c, adapter);
+    if ("errorRes" in ctx) return ctx.errorRes;
+    const { project, scene } = ctx;
+    const apiKey = loadAnthropicKey(project.dir);
+    if (!apiKey) return c.json({ error: "ANTHROPIC_API_KEY not set" }, 401);
+
+    const script = loadScript(project.dir);
+    if (!script) return c.json({ error: "no planned script found" }, 404);
+    const focalIdx = script.scenes.findIndex((s) => s.id === scene.id);
+    const window = pickSceneWindow(script, focalIdx, 2);
+
+    return callHaikuAction(c, project.dir, apiKey, "sfxSuggest", {
+      tool: SFX_SUGGEST_TOOL,
+      system: buildSfxSuggestSystem(),
+      user: buildSfxSuggestUser(window, scene),
+      buildResponse: (raw: SfxSuggestToolInput): SfxSuggestionResponse =>
+        buildSfxSuggestResponse(raw, scene),
+      meta: { sceneId: scene.id, template: scene.template, windowSize: window.length },
+    });
+  });
+
+  // POST /api/projects/:id/storyline/sfx-generate
+  // Take one suggestion (prompt + durationSeconds + anchor) and turn it
+  // into an actual mp3 on disk. Appends to the SFX manifest. The studio
+  // re-assembles after this returns so the new clip lands on the SFX lane.
+  api.post("/projects/:id/storyline/sfx-generate", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    let body: SfxGenerateBody;
+    try {
+      body = (await c.req.json()) as SfxGenerateBody;
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+    if (!body.sceneId) return c.json({ error: "sceneId is required" }, 400);
+    if (!body.prompt || typeof body.prompt !== "string" || body.prompt.trim().length === 0) {
+      return c.json({ error: "prompt is required" }, 400);
+    }
+    if (body.prompt.length > SFX_BOUNDS.promptMaxChars) {
+      return c.json({ error: `prompt too long (max ${SFX_BOUNDS.promptMaxChars} chars)` }, 400);
+    }
+    const anchor: SfxAnchor =
+      body.anchor === "scene-end" || body.anchor === "accent-word" ? body.anchor : "scene-start";
+
+    const apiKey = loadElevenLabsKey(project.dir);
+    if (!apiKey) {
+      return c.json({ error: "ELEVENLABS_API_KEY not set. Add it to <project>/.env." }, 401);
+    }
+
+    const script = loadScript(project.dir);
+    if (!script) return c.json({ error: "no planned script found" }, 404);
+    const scene = script.scenes.find((s) => s.id === body.sceneId);
+    if (!scene) return c.json({ error: `scene ${body.sceneId} not in script` }, 404);
+
+    const durationSeconds = clampSfxDuration(body.durationSeconds ?? 2);
+    const onCostEvent = loggerSink(new CostLogger(project.dir));
+    const start = Date.now();
+
+    try {
+      const { bytes } = await generateSoundEffect(apiKey, body.prompt.trim(), {
+        durationSeconds,
+        ...(typeof body.promptInfluence === "number"
+          ? { promptInfluence: body.promptInfluence }
+          : {}),
+      });
+      // Mint a stable id and write the mp3 next to the manifest.
+      const entryId = mintSfxId();
+      const relativePath = `${SFX_DIR}/${scene.id}-${entryId}.mp3`;
+      const absPath = join(project.dir, relativePath);
+      mkdirSync(join(project.dir, SFX_DIR), { recursive: true });
+      writeFileSync(absPath, bytes);
+      const entry: SfxEntry = {
+        id: entryId,
+        sceneId: scene.id,
+        prompt: body.prompt.trim(),
+        path: relativePath,
+        durationSeconds,
+        anchor,
+        ...(typeof body.accentWordIndex === "number"
+          ? { accentWordIndex: body.accentWordIndex }
+          : {}),
+        ...(typeof body.label === "string" && body.label.trim().length > 0
+          ? { label: body.label.trim() }
+          : {}),
+        ...(typeof body.volumeDb === "number" ? { volumeDb: body.volumeDb } : {}),
+        createdAt: new Date().toISOString(),
+      };
+      appendSfxEntry(project.dir, entry);
+
+      // Cost telemetry: ElevenLabs SFX is billed per generation, not per
+      // character. Use a synthetic 1-character entry so the existing
+      // `kind: "elevenlabs"` shape applies; the meta carries the actual
+      // op label for filtering.
+      onCostEvent(
+        "script.storyline.sfx.generate",
+        { kind: "elevenlabs", voiceId: "sfx", characters: 1 },
+        Date.now() - start,
+        {
+          sceneId: scene.id,
+          entryId,
+          durationSeconds,
+          anchor,
+          promptLen: body.prompt.length,
+        },
+      );
+
+      return c.json({ ok: true, entry });
+    } catch (err) {
+      if (err instanceof ElevenLabsError) {
+        return c.json({ error: `ElevenLabs SFX failed: ${err.message}` }, 502);
+      }
+      return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
+    }
+  });
+
+  // GET /api/projects/:id/storyline/sfx
+  // Returns the current SFX manifest. Used by the studio to render the SFX
+  // lane and the per-card audition affordances.
+  api.get("/projects/:id/storyline/sfx", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    return c.json({ manifest: readSfxManifest(project.dir) });
+  });
+
+  // DELETE /api/projects/:id/storyline/sfx/:entryId
+  // Remove a single SFX entry from the manifest. Does NOT delete the audio
+  // file on disk — leaves the user free to recover by manually editing the
+  // manifest. Aligns with the principle "manifests are append-only from the
+  // studio; deletes are soft."
+  api.delete("/projects/:id/storyline/sfx/:entryId", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    const entryId = c.req.param("entryId");
+    if (!entryId) return c.json({ error: "entryId required" }, 400);
+    const manifest = removeSfxEntry(project.dir, entryId);
+    return c.json({ ok: true, manifest });
+  });
+}
+
+// ── SFX action types & helpers ───────────────────────────────────────────────
+
+interface SfxGenerateBody {
+  sceneId?: string;
+  prompt?: string;
+  durationSeconds?: number;
+  promptInfluence?: number;
+  anchor?: SfxAnchor;
+  accentWordIndex?: number;
+  label?: string;
+  volumeDb?: number;
+}
+
+interface SfxSuggestToolInput {
+  suggestions?: Array<{
+    prompt?: string;
+    durationSeconds?: number;
+    anchor?: string;
+    accentWordIndex?: number;
+    label?: string;
+    rationale?: string;
+  }>;
+}
+
+interface SfxSuggestionResponse {
+  sceneId: string;
+  suggestions: Array<{
+    id: string;
+    prompt: string;
+    durationSeconds: number;
+    anchor: SfxAnchor;
+    accentWordIndex?: number;
+    label: string;
+    rationale: string;
+  }>;
 }
 
-// ── Action context loader ────────────────────────────────────────────────────
+const SFX_SUGGEST_TOOL: ToolDefinition = {
+  name: "propose_sfx",
+  description:
+    "Propose 1-3 sound-effect ideas for a scene. Each idea is a short text prompt (the model that will generate the SFX), a target duration, an anchor describing when in the scene to play it, and a one-sentence rationale.",
+  input_schema: {
+    type: "object",
+    properties: {
+      suggestions: {
+        type: "array",
+        minItems: 1,
+        maxItems: 3,
+        items: {
+          type: "object",
+          properties: {
+            prompt: {
+              type: "string",
+              description:
+                "Text prompt for ElevenLabs Sound Generation. Be specific and visual — 'low rumble with metallic clang' beats 'big sound'. Avoid musical descriptions; this is SFX, not music.",
+            },
+            durationSeconds: {
+              type: "number",
+              minimum: 0.5,
+              maximum: 22,
+              description:
+                "Target duration in seconds. Most cinematic SFX are 0.5-3s. Use longer (5-8s) only for atmospheric pads.",
+            },
+            anchor: {
+              type: "string",
+              enum: ["scene-start", "accent-word", "scene-end"],
+              description:
+                "When in the scene window the SFX plays. scene-start: cold open / pattern-interrupt. accent-word: punctuates a specific word in the narration. scene-end: outro stinger.",
+            },
+            accentWordIndex: {
+              type: "integer",
+              minimum: 0,
+              description:
+                "Required only when anchor is accent-word. 0-based index into the narration's word list. The studio uses this to interpolate a timing — Phase A is heuristic-only.",
+            },
+            label: {
+              type: "string",
+              description: "Short human label for the SFX (e.g. 'broadcast static'). Optional.",
+            },
+            rationale: {
+              type: "string",
+              description:
+                "One sentence on what this SFX does for the scene's retention. Specific to the scene's content.",
+            },
+          },
+          required: ["prompt", "durationSeconds", "anchor", "rationale"],
+        },
+      },
+    },
+    required: ["suggestions"],
+  },
+};
+
+function buildSfxSuggestSystem(): string {
+  return [
+    "# Sound-effect direction",
+    "",
+    "You're a sound designer proposing SFX for ONE scene in a Reels-style explainer video.",
+    "Read the focal scene + the small neighbour window for context. Propose 1-3 SFX that:",
+    "",
+    "1. Punch the scene's pattern interrupt (scene-start) OR underline a specific word (accent-word) OR seal the close (scene-end).",
+    "2. Are SHORT — 0.5-3s for most cinematic uses. Reserve 5-8s for atmospheric pads.",
+    "3. Are SPECIFIC — 'low rumble with metallic clang' beats 'big sound'.",
+    "4. Avoid musical content (that's the music lane). Pure SFX only: whooshes, impacts, ambient layers.",
+    "5. Don't overcrowd — if the scene's narration is dense, ONE well-placed SFX > three competing ones.",
+    "",
+    "When you pick `accent-word`, also emit `accentWordIndex` — the 0-based word index in the focal scene's narration the SFX should align to.",
+    "",
+    "Each suggestion needs a one-sentence rationale that ties back to the scene's content. Vague rationales get rejected.",
+  ].join("\n");
+}
+
+function buildSfxSuggestUser(window: SceneRef[], focal: SceneRef): string {
+  const lines = window.map((s) => {
+    const isFocal = s.id === focal.id;
+    return [
+      `${isFocal ? "→ FOCAL · " : "   "}${s.id} · ${s.template}${s.hook ? " · HOOK" : ""}`,
+      `   narration: ${s.text}`,
+    ].join("\n");
+  });
+  return [
+    "## Window",
+    lines.join("\n\n"),
+    "",
+    "Now call propose_sfx with 1-3 ideas for the FOCAL scene.",
+  ].join("\n");
+}
+
+function buildSfxSuggestResponse(raw: SfxSuggestToolInput, scene: SceneRef): SfxSuggestionResponse {
+  const suggestions: SfxSuggestionResponse["suggestions"] = [];
+  for (const s of raw.suggestions ?? []) {
+    if (!s || typeof s.prompt !== "string" || s.prompt.trim().length === 0) continue;
+    const anchor: SfxAnchor =
+      s.anchor === "scene-end" || s.anchor === "accent-word" ? s.anchor : "scene-start";
+    const durationSeconds = clampSfxDuration(
+      typeof s.durationSeconds === "number" ? s.durationSeconds : 2,
+    );
+    const label =
+      typeof s.label === "string" && s.label.trim().length > 0
+        ? s.label.trim()
+        : s.prompt.trim().slice(0, 40);
+    suggestions.push({
+      id: mintSfxId(),
+      prompt: s.prompt.trim(),
+      durationSeconds,
+      anchor,
+      ...(anchor === "accent-word" && typeof s.accentWordIndex === "number"
+        ? { accentWordIndex: s.accentWordIndex }
+        : {}),
+      label,
+      rationale: typeof s.rationale === "string" ? s.rationale : "",
+    });
+    if (suggestions.length >= 3) break;
+  }
+  return { sceneId: scene.id, suggestions };
+}
+
+let sfxIdCounter = 0;
+function mintSfxId(): string {
+  // Stable, sortable, no collisions across a session. Format: <ms36>-<counter36>.
+  const ms = Date.now().toString(36);
+  const ctr = (sfxIdCounter++).toString(36).padStart(2, "0");
+  return `sfx-${ms}-${ctr}`;
+}
 
 interface ActionContext {
   project: { dir: string };
@@ -428,21 +751,21 @@ async function loadActionContext(
 
 // ── Generic Haiku-action runner ──────────────────────────────────────────────
 
-interface HaikuActionConfig<T> {
+interface HaikuActionConfig<T, R = SuggestionResponse> {
   tool: ToolDefinition;
   system: string;
   user: string;
-  buildResponse: (raw: T) => SuggestionResponse;
+  buildResponse: (raw: T) => R;
   meta: Record<string, unknown>;
 }
 
-async function callHaikuAction<T>(
+async function callHaikuAction<T, R = SuggestionResponse>(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   c: any,
   projectDir: string,
   apiKey: string,
   opLabel: string,
-  cfg: HaikuActionConfig<T>,
+  cfg: HaikuActionConfig<T, R>,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): Promise<any> {
   const onCostEvent = loggerSink(new CostLogger(projectDir));
diff --git a/packages/studio/src/components/sidebar/StorylineTab.tsx b/packages/studio/src/components/sidebar/StorylineTab.tsx
index c8db4ab69..3955e64f1 100644
--- a/packages/studio/src/components/sidebar/StorylineTab.tsx
+++ b/packages/studio/src/components/sidebar/StorylineTab.tsx
@@ -1,5 +1,11 @@
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { SceneCard, type AIActionId, type SceneSuggestion } from "../storyline/SceneCard";
+import {
+  SceneCard,
+  type AIActionId,
+  type AppliedSfxEntry,
+  type SceneSuggestion,
+  type SfxSuggestion,
+} from "../storyline/SceneCard";
 import {
   applyInlineEdit,
   pickFocalCardIndex,
@@ -84,6 +90,10 @@ const ACTION_PATH: Record<AIActionId, string> = {
   suggestEmphasis: "suggest-emphasis",
   refineReasoning: "refine-reasoning",
   rePickTemplate: "re-pick-template",
+  // addSfx returns multi-suggestion shape, not a single patch — handled in a
+  // dedicated branch in handleAIAction. The path is the same prefix so it
+  // shares the route table.
+  addSfx: "sfx-suggest",
 };
 
 const SUGGESTION_PROMPTS_BY_SCOPE: Record<DirectorScope, string[]> = {
@@ -113,6 +123,18 @@ export const StorylineTab = memo(function StorylineTab({ projectId }: StorylineT
     {},
   );
 
+  // SFX state. Three independent maps — proposed (Haiku output, not yet
+  // generated), applied (in the manifest, audible on the SFX lane), and
+  // per-suggestion generation status (so the Generate button can show a
+  // spinner without freezing the rest of the card).
+  const [sfxSuggestionsByScene, setSfxSuggestionsByScene] = useState<
+    Record<string, SfxSuggestion[]>
+  >({});
+  const [sfxByScene, setSfxByScene] = useState<Record<string, AppliedSfxEntry[]>>({});
+  const [sfxGenerationStatus, setSfxGenerationStatus] = useState<
+    Record<string, "idle" | "running" | "error">
+  >({});
+
   // Director state — single textarea, two scopes (storyline vs project).
   const [directorScope, setDirectorScope] = useState<DirectorScope>("storyline");
   const [intent, setIntent] = useState("");
@@ -179,9 +201,10 @@ export const StorylineTab = memo(function StorylineTab({ projectId }: StorylineT
       setLoading(true);
       setError(null);
       try {
-        const [planned, imagesRes] = await Promise.all([
+        const [planned, imagesRes, sfxRes] = await Promise.all([
           loadGeneratedOrPlanned(),
           fetch(`/api/projects/${projectId}/images`).catch(() => null),
+          fetch(`/api/projects/${projectId}/storyline/sfx`).catch(() => null),
         ]);
         if (cancelled) return;
         setScript(planned);
@@ -193,6 +216,18 @@ export const StorylineTab = memo(function StorylineTab({ projectId }: StorylineT
           }
           if (!cancelled) setImageMap(map);
         }
+        if (sfxRes && sfxRes.ok) {
+          const sfxJson = (await sfxRes.json()) as {
+            manifest?: { entries?: AppliedSfxEntry[] };
+          };
+          const grouped: Record<string, AppliedSfxEntry[]> = {};
+          for (const entry of sfxJson.manifest?.entries ?? []) {
+            const list = grouped[(entry as AppliedSfxEntry & { sceneId: string }).sceneId] ?? [];
+            list.push(entry);
+            grouped[(entry as AppliedSfxEntry & { sceneId: string }).sceneId] = list;
+          }
+          if (!cancelled) setSfxByScene(grouped);
+        }
       } catch (err) {
         if (!cancelled) setError(err instanceof Error ? err.message : String(err));
       } finally {
@@ -255,22 +290,34 @@ export const StorylineTab = memo(function StorylineTab({ projectId }: StorylineT
           const errBody = (await res.json().catch(() => ({}))) as { error?: string };
           throw new Error(errBody.error ?? `HTTP ${res.status}`);
         }
-        const json = (await res.json()) as {
-          preview?: string;
-          rationale?: string;
-          patch?: { template?: string; props?: Record<string, unknown>; reasoning?: string };
-        };
-        const suggestion: SceneSuggestion = {
-          id: `${scene.id}-${action}-${Date.now()}`,
-          action,
-          preview: json.preview ?? "",
-          rationale: json.rationale ?? "",
-          patch: json.patch ?? {},
-        };
-        setSuggestionsByScene((prev) => ({
-          ...prev,
-          [scene.id]: [...(prev[scene.id] ?? []), suggestion],
-        }));
+        if (action === "addSfx") {
+          // Different shape: list of suggestions instead of a single patch.
+          const json = (await res.json()) as {
+            sceneId?: string;
+            suggestions?: SfxSuggestion[];
+          };
+          setSfxSuggestionsByScene((prev) => ({
+            ...prev,
+            [scene.id]: [...(prev[scene.id] ?? []), ...(json.suggestions ?? [])],
+          }));
+        } else {
+          const json = (await res.json()) as {
+            preview?: string;
+            rationale?: string;
+            patch?: { template?: string; props?: Record<string, unknown>; reasoning?: string };
+          };
+          const suggestion: SceneSuggestion = {
+            id: `${scene.id}-${action}-${Date.now()}`,
+            action,
+            preview: json.preview ?? "",
+            rationale: json.rationale ?? "",
+            patch: json.patch ?? {},
+          };
+          setSuggestionsByScene((prev) => ({
+            ...prev,
+            [scene.id]: [...(prev[scene.id] ?? []), suggestion],
+          }));
+        }
         setAiStatus((prev) => ({
           ...prev,
           [scene.id]: { ...(prev[scene.id] ?? {}), [action]: "idle" },
@@ -343,6 +390,94 @@ export const StorylineTab = memo(function StorylineTab({ projectId }: StorylineT
     });
   }, []);
 
+  // ── SFX handlers ───────────────────────────────────────────────────────────
+
+  const handleGenerateSfx = useCallback(
+    async (sceneId: string, suggestion: SfxSuggestion): Promise<void> => {
+      setSfxGenerationStatus((prev) => ({ ...prev, [suggestion.id]: "running" }));
+      try {
+        const res = await fetch(`/api/projects/${projectId}/storyline/sfx-generate`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            sceneId,
+            prompt: suggestion.prompt,
+            durationSeconds: suggestion.durationSeconds,
+            anchor: suggestion.anchor,
+            ...(typeof suggestion.accentWordIndex === "number"
+              ? { accentWordIndex: suggestion.accentWordIndex }
+              : {}),
+            ...(suggestion.label ? { label: suggestion.label } : {}),
+          }),
+        });
+        if (!res.ok) {
+          const err = (await res.json().catch(() => ({}))) as { error?: string };
+          throw new Error(err.error ?? `HTTP ${res.status}`);
+        }
+        const json = (await res.json()) as { ok?: boolean; entry?: AppliedSfxEntry };
+        if (json.entry) {
+          setSfxByScene((prev) => ({
+            ...prev,
+            [sceneId]: [...(prev[sceneId] ?? []), json.entry!],
+          }));
+        }
+        // Drop the matching suggestion from the pending stack — no point
+        // generating it twice.
+        setSfxSuggestionsByScene((prev) => ({
+          ...prev,
+          [sceneId]: (prev[sceneId] ?? []).filter((s) => s.id !== suggestion.id),
+        }));
+        setSfxGenerationStatus((prev) => {
+          const { [suggestion.id]: _, ...rest } = prev;
+          return rest;
+        });
+        // Re-assemble so the new SFX lands on the SFX lane in the timeline.
+        setReloadKey((k) => k + 1);
+      } catch (err) {
+        setSfxGenerationStatus((prev) => ({ ...prev, [suggestion.id]: "error" }));
+        window.alert(`Couldn't generate SFX: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    },
+    [projectId],
+  );
+
+  const handleDismissSfxSuggestion = useCallback((suggestionId: string) => {
+    setSfxSuggestionsByScene((prev) => {
+      const next: typeof prev = {};
+      for (const [sceneId, list] of Object.entries(prev)) {
+        const filtered = list.filter((s) => s.id !== suggestionId);
+        if (filtered.length > 0) next[sceneId] = filtered;
+      }
+      return next;
+    });
+  }, []);
+
+  const handleDeleteAppliedSfx = useCallback(
+    async (entryId: string): Promise<void> => {
+      try {
+        const res = await fetch(`/api/projects/${projectId}/storyline/sfx/${entryId}`, {
+          method: "DELETE",
+        });
+        if (!res.ok) {
+          const err = (await res.json().catch(() => ({}))) as { error?: string };
+          throw new Error(err.error ?? `HTTP ${res.status}`);
+        }
+        setSfxByScene((prev) => {
+          const next: typeof prev = {};
+          for (const [sceneId, list] of Object.entries(prev)) {
+            const filtered = list.filter((e) => e.id !== entryId);
+            if (filtered.length > 0) next[sceneId] = filtered;
+          }
+          return next;
+        });
+        setReloadKey((k) => k + 1);
+      } catch (err) {
+        window.alert(`Couldn't remove SFX: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    },
+    [projectId],
+  );
+
   // ── Storyline intent ───────────────────────────────────────────────────────
 
   const runIntent = useCallback(async (): Promise<void> => {
@@ -855,6 +990,13 @@ export const StorylineTab = memo(function StorylineTab({ projectId }: StorylineT
                     return next;
                   })
                 }
+                sfxSuggestions={sfxSuggestionsByScene[scene.id]}
+                appliedSfx={sfxByScene[scene.id]}
+                onGenerateSfx={handleGenerateSfx}
+                onDismissSfxSuggestion={handleDismissSfxSuggestion}
+                onDeleteAppliedSfx={handleDeleteAppliedSfx}
+                sfxGenerationStatus={sfxGenerationStatus}
+                sfxAuditionUrlPrefix={`/api/projects/${projectId}/preview/`}
               />
             </div>
           );
diff --git a/packages/studio/src/components/storyline/SceneCard.tsx b/packages/studio/src/components/storyline/SceneCard.tsx
index e1c11a006..836159d1c 100644
--- a/packages/studio/src/components/storyline/SceneCard.tsx
+++ b/packages/studio/src/components/storyline/SceneCard.tsx
@@ -35,7 +35,43 @@ import {
  * the editing pipeline lands.
  */
 
-export type AIActionId = "compress" | "suggestEmphasis" | "refineReasoning" | "rePickTemplate";
+export type AIActionId =
+  | "compress"
+  | "suggestEmphasis"
+  | "refineReasoning"
+  | "rePickTemplate"
+  | "addSfx";
+
+/**
+ * One SFX suggestion produced by the per-scene `/sfx-suggest` Haiku action.
+ * Stack of these is rendered below the regular suggestion stack so the user
+ * can scan multiple ideas before paying ElevenLabs credits to generate one.
+ */
+export interface SfxSuggestion {
+  id: string;
+  prompt: string;
+  durationSeconds: number;
+  anchor: "scene-start" | "accent-word" | "scene-end";
+  accentWordIndex?: number;
+  label: string;
+  rationale: string;
+}
+
+/**
+ * One already-generated SFX entry attached to this scene. Surfaced beneath
+ * the suggestion stack so the user can audition it (HTML5 audio) and remove
+ * it (DELETE /storyline/sfx/:entryId). The shape mirrors `SfxEntry` from
+ * core's manifest module — kept duplicated here so the studio doesn't import
+ * core types directly.
+ */
+export interface AppliedSfxEntry {
+  id: string;
+  prompt: string;
+  path: string;
+  durationSeconds: number;
+  anchor: "scene-start" | "accent-word" | "scene-end";
+  label?: string;
+}
 
 /**
  * One pending suggestion produced by a Haiku action. Rendered inline beneath
@@ -93,6 +129,20 @@ interface SceneCardProps {
    *  calls back to clear it. */
   forceEditHeadline?: boolean;
   onConsumeEditHeadlineFlag?: () => void;
+  /** Pending SFX suggestions for this scene (one Haiku call returns 1-3). */
+  sfxSuggestions?: SfxSuggestion[];
+  /** Already-generated SFX entries currently in the manifest, scoped to this scene. */
+  appliedSfx?: AppliedSfxEntry[];
+  /** Generate one SFX suggestion via ElevenLabs. Resolves once the file is on disk. */
+  onGenerateSfx?: (sceneId: string, suggestion: SfxSuggestion) => Promise<void> | void;
+  /** Dismiss a pending SFX suggestion without generating. */
+  onDismissSfxSuggestion?: (suggestionId: string) => void;
+  /** Remove an already-generated SFX entry from the manifest. */
+  onDeleteAppliedSfx?: (entryId: string) => Promise<void> | void;
+  /** Per-suggestion generation status, surfaced as a spinner / disabled state. */
+  sfxGenerationStatus?: Record<string, "idle" | "running" | "error">;
+  /** Project root URL prefix for serving SFX assets in audition playback. */
+  sfxAuditionUrlPrefix?: string;
 }
 
 const AI_ACTIONS: Array<{ id: AIActionId; label: string; tooltip: string }> = [
@@ -116,6 +166,11 @@ const AI_ACTIONS: Array<{ id: AIActionId; label: string; tooltip: string }> = [
     label: "Re-pick template",
     tooltip: "Generate 3 alternative template+props treatments and pick one",
   },
+  {
+    id: "addSfx",
+    label: "🔊 Add SFX",
+    tooltip: "Propose 1-3 sound effects via Haiku; generate them via ElevenLabs",
+  },
 ];
 
 const STATUS_TONE: Record<WordBudgetStatus, { label: string; tone: string }> = {
@@ -144,6 +199,13 @@ export const SceneCard = memo(function SceneCard({
   onSceneIntent,
   forceEditHeadline,
   onConsumeEditHeadlineFlag,
+  sfxSuggestions,
+  appliedSfx,
+  onGenerateSfx,
+  onDismissSfxSuggestion,
+  onDeleteAppliedSfx,
+  sfxGenerationStatus,
+  sfxAuditionUrlPrefix,
 }: SceneCardProps) {
   const [expandedReason, setExpandedReason] = useState(false);
   const [sceneIntentOpen, setSceneIntentOpen] = useState(false);
@@ -495,6 +557,59 @@ export const SceneCard = memo(function SceneCard({
           ))}
         </div>
       )}
+
+      {/* SFX suggestion stack — Haiku proposals that need to be GENERATED via
+          ElevenLabs to become real audio. Different shape than the regular
+          suggestion stack (no `Apply patch` — instead `🔊 Generate`). */}
+      {sfxSuggestions && sfxSuggestions.length > 0 && (
+        <div className="border-t border-amber-400/30 bg-amber-400/[0.03]">
+          <div className="px-3 py-1.5 border-b border-amber-400/15 flex items-center gap-2">
+            <span className="text-[9px] uppercase tracking-[0.22em] font-semibold text-amber-300">
+              SFX proposals
+            </span>
+            <span className="text-[10px] text-neutral-500">
+              click 🔊 to spend ~1 ElevenLabs credit
+            </span>
+          </div>
+          {sfxSuggestions.map((s) => {
+            const status = sfxGenerationStatus?.[s.id] ?? "idle";
+            return (
+              <SfxSuggestionRow
+                key={s.id}
+                suggestion={s}
+                status={status}
+                {...(onGenerateSfx ? { onGenerate: () => onGenerateSfx(scene.id, s) } : {})}
+                {...(onDismissSfxSuggestion
+                  ? { onDismiss: () => onDismissSfxSuggestion(s.id) }
+                  : {})}
+              />
+            );
+          })}
+        </div>
+      )}
+
+      {/* Applied SFX — already on disk, in the manifest, audible on the SFX
+          lane. Audition + delete affordances per entry. */}
+      {appliedSfx && appliedSfx.length > 0 && (
+        <div className="border-t border-emerald-400/20 bg-emerald-400/[0.02]">
+          <div className="px-3 py-1.5 border-b border-emerald-400/10 flex items-center gap-2">
+            <span className="text-[9px] uppercase tracking-[0.22em] font-semibold text-emerald-300">
+              SFX on lane
+            </span>
+            <span className="text-[10px] text-neutral-500">
+              {appliedSfx.length} clip{appliedSfx.length === 1 ? "" : "s"}
+            </span>
+          </div>
+          {appliedSfx.map((entry) => (
+            <AppliedSfxRow
+              key={entry.id}
+              entry={entry}
+              urlPrefix={sfxAuditionUrlPrefix ?? ""}
+              {...(onDeleteAppliedSfx ? { onDelete: () => onDeleteAppliedSfx(entry.id) } : {})}
+            />
+          ))}
+        </div>
+      )}
     </article>
   );
 });
@@ -629,6 +744,9 @@ function SuggestionRow({
     suggestEmphasis: "Emphasis",
     refineReasoning: "Reasoning",
     rePickTemplate: "Alt template",
+    // SFX uses its own SfxSuggestionRow renderer; this label is a defensive
+    // fallback only — never actually rendered.
+    addSfx: "SFX",
   };
   return (
     <div className="px-3 py-2 border-b border-studio-accent/20 last:border-b-0 flex items-start gap-3">
@@ -891,3 +1009,108 @@ function EditableText({
     />
   );
 }
+
+function SfxSuggestionRow({
+  suggestion,
+  status,
+  onGenerate,
+  onDismiss,
+}: {
+  suggestion: SfxSuggestion;
+  status: "idle" | "running" | "error";
+  onGenerate?: () => void;
+  onDismiss?: () => void;
+}): ReactNode {
+  const running = status === "running";
+  return (
+    <div className="px-3 py-2 border-b border-amber-400/15 last:border-b-0 flex items-start gap-3">
+      <div className="flex-1 min-w-0">
+        <div className="flex items-center gap-2 mb-1">
+          <span className="text-[12px] text-neutral-100 font-medium">{suggestion.label}</span>
+          <span className="px-1.5 py-0.5 rounded text-[9px] font-mono border border-neutral-700 text-neutral-400">
+            {suggestion.anchor}
+          </span>
+          <span className="text-[9px] text-neutral-500 tabular-nums">
+            {suggestion.durationSeconds.toFixed(1)}s
+          </span>
+        </div>
+        <div className="text-[11px] text-neutral-300 leading-snug font-mono italic">
+          “{suggestion.prompt}”
+        </div>
+        {suggestion.rationale && (
+          <div className="text-[10px] text-neutral-500 leading-relaxed mt-1 italic">
+            {suggestion.rationale}
+          </div>
+        )}
+      </div>
+      <div className="flex flex-col items-end gap-1 flex-shrink-0">
+        {onGenerate && (
+          <button
+            type="button"
+            onClick={onGenerate}
+            disabled={running}
+            className="h-6 px-2.5 rounded-md text-[10px] font-semibold border border-amber-400/50 bg-amber-400/15 text-amber-200 hover:bg-amber-400/25 disabled:opacity-40 transition-colors"
+          >
+            {running ? "Generating…" : "🔊 Generate"}
+          </button>
+        )}
+        {onDismiss && (
+          <button
+            type="button"
+            onClick={onDismiss}
+            disabled={running}
+            className="h-5 px-2 rounded text-[9px] text-neutral-500 hover:text-neutral-300 transition-colors"
+          >
+            Dismiss
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function AppliedSfxRow({
+  entry,
+  urlPrefix,
+  onDelete,
+}: {
+  entry: AppliedSfxEntry;
+  urlPrefix: string;
+  onDelete?: () => void;
+}): ReactNode {
+  const audioUrl = urlPrefix ? `${urlPrefix}${entry.path}` : entry.path;
+  return (
+    <div className="px-3 py-2 border-b border-emerald-400/10 last:border-b-0 flex items-center gap-3">
+      <div className="flex-1 min-w-0">
+        <div className="flex items-center gap-2 mb-0.5">
+          <span className="text-[11px] text-neutral-100 font-medium">
+            {entry.label || entry.prompt.slice(0, 40)}
+          </span>
+          <span className="px-1.5 py-0.5 rounded text-[9px] font-mono border border-neutral-700 text-neutral-400">
+            {entry.anchor}
+          </span>
+          <span className="text-[9px] text-neutral-500 tabular-nums">
+            {entry.durationSeconds.toFixed(1)}s
+          </span>
+        </div>
+        <audio
+          src={audioUrl}
+          controls
+          preload="none"
+          className="h-7 w-full"
+          aria-label={`Audition SFX ${entry.label ?? entry.id}`}
+        />
+      </div>
+      {onDelete && (
+        <button
+          type="button"
+          onClick={onDelete}
+          className="h-6 px-2 rounded text-[10px] text-neutral-500 hover:text-rose-400 transition-colors"
+          title="Remove this SFX from the manifest"
+        >
+          Remove
+        </button>
+      )}
+    </div>
+  );
+}