@bendyline/squisq-editor-react 1.6.1 → 2.0.0

package/src/teleprompter/floatingWindow.ts

@@ -0,0 +1,352 @@
+/**
+ * Floating-teleprompter window manager — framework-free.
+ *
+ * Capability ladder, best first:
+ *   1. `document-pip` — Document Picture-in-Picture (Chromium 116+,
+ *      Firefox 151+): a true always-on-top window hosting live DOM; the
+ *      React surface portals into it.
+ *   2. `video-pip`   — canvas → `captureStream(0)` → `<video>` →
+ *      `requestPictureInPicture()` (Safari's only always-on-top path;
+ *      `webkitSetPresentationMode` fallback). Read-only: the main
+ *      window draws frames and calls `requestFrame()` on analysis
+ *      ticks — never rAF, which throttles under occlusion.
+ *   3. `popup`       — `window.open` (positionable, not always-on-top).
+ *   4. `docked`      — no float.
+ *
+ * Every tier is feature-detected at open time and falls through to the
+ * next on ANY failure. All interactive state stays in the main window;
+ * floats are render targets only.
+ */
+
+import type { FloatTier } from './types';
+
+interface DocumentPictureInPictureApi {
+  requestWindow(options?: { width?: number; height?: number }): Promise<Window>;
+}
+
+interface WindowWithDocPip extends Window {
+  documentPictureInPicture?: DocumentPictureInPictureApi;
+}
+
+interface WebKitVideoElement extends HTMLVideoElement {
+  webkitSetPresentationMode?: (mode: 'picture-in-picture' | 'inline') => void;
+  webkitSupportsPresentationMode?: (mode: string) => boolean;
+  webkitPresentationMode?: string;
+}
+
+interface CaptureTrackWithRequestFrame extends MediaStreamTrack {
+  requestFrame?: () => void;
+}
+
+export interface FloatOpenOptions {
+  width: number;
+  height: number;
+  /** Try this tier first; the ladder continues below it on failure. */
+  preferredTier?: FloatTier;
+  title: string;
+}
+
+export interface CanvasSink {
+  canvas: HTMLCanvasElement;
+  width: number;
+  height: number;
+  /** Push the freshly drawn canvas frame into the PiP video. */
+  requestFrame: () => void;
+}
+
+export type FloatEvent = 'closed' | 'tierchange';
+
+export interface FloatingWindowManager {
+  readonly tier: FloatTier;
+  readonly isOpen: boolean;
+  /** Resolves with the tier that actually opened ('docked' if none could). */
+  open(opts: FloatOpenOptions): Promise<FloatTier>;
+  /** Idempotent; restores docked and emits 'closed'. */
+  close(): void;
+  /** Portal container for 'document-pip' | 'popup'; null otherwise. */
+  getPortalTarget(): HTMLElement | null;
+  /** Canvas sink for 'video-pip'; null otherwise. */
+  getCanvasSink(): CanvasSink | null;
+  on(event: FloatEvent, cb: (tier: FloatTier) => void): () => void;
+  /** Tear everything down (unmount); like close() but silent-safe. */
+  dispose(): void;
+}
+
+/** Feature-detect the available float tiers, best first. */
+export function detectFloatTiers(): FloatTier[] {
+  const tiers: FloatTier[] = [];
+  if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+    if ((window as WindowWithDocPip).documentPictureInPicture) tiers.push('document-pip');
+    const video = document.createElement('video') as WebKitVideoElement;
+    const stdPip =
+      document.pictureInPictureEnabled === true &&
+      typeof video.requestPictureInPicture === 'function';
+    const webkitPip =
+      typeof video.webkitSetPresentationMode === 'function' &&
+      (video.webkitSupportsPresentationMode?.('picture-in-picture') ?? true);
+    const canCapture =
+      typeof HTMLCanvasElement !== 'undefined' &&
+      typeof HTMLCanvasElement.prototype.captureStream === 'function';
+    if ((stdPip || webkitPip) && canCapture) tiers.push('video-pip');
+    if (typeof window.open === 'function') tiers.push('popup');
+  }
+  tiers.push('docked');
+  return tiers;
+}
+
+interface ActiveFloat {
+  tier: FloatTier;
+  portalTarget: HTMLElement | null;
+  canvasSink: CanvasSink | null;
+  dispose: () => void;
+}
+
+export function createFloatingWindowManager(deps: { styleCss: string }): FloatingWindowManager {
+  let active: ActiveFloat | null = null;
+  const listeners: Record<FloatEvent, Set<(tier: FloatTier) => void>> = {
+    closed: new Set(),
+    tierchange: new Set(),
+  };
+
+  const emit = (event: FloatEvent, tier: FloatTier) => {
+    for (const cb of listeners[event]) cb(tier);
+  };
+
+  /** Handles user-initiated closes (PiP ✕, popup close, navigation). */
+  const handleExternalClose = () => {
+    if (!active) return;
+    const closing = active;
+    active = null;
+    closing.dispose();
+    emit('tierchange', 'docked');
+    emit('closed', 'docked');
+  };
+
+  const openerPageHide = () => manager.close();
+  if (typeof window !== 'undefined') {
+    window.addEventListener('pagehide', openerPageHide);
+  }
+
+  const writeFloatDocument = (doc: Document, title: string): HTMLElement => {
+    doc.title = title;
+    const style = doc.createElement('style');
+    style.textContent = `${deps.styleCss}\nhtml,body{margin:0;height:100%;}#squisq-float-root{height:100%;display:flex;}`;
+    doc.head.appendChild(style);
+    const root = doc.createElement('div');
+    root.id = 'squisq-float-root';
+    doc.body.appendChild(root);
+    return root;
+  };
+
+  const openDocumentPip = async (opts: FloatOpenOptions): Promise<ActiveFloat> => {
+    const api = (window as WindowWithDocPip).documentPictureInPicture;
+    if (!api) throw new Error('Document PiP unavailable');
+    const pip = await api.requestWindow({ width: opts.width, height: opts.height });
+    // Copy same-origin stylesheets so editor chrome vars resolve; the
+    // injected styleCss below is what the surface actually depends on.
+    for (const sheet of Array.from(document.styleSheets)) {
+      try {
+        const rules = Array.from(sheet.cssRules)
+          .map((rule) => rule.cssText)
+          .join('\n');
+        const style = pip.document.createElement('style');
+        style.textContent = rules;
+        pip.document.head.appendChild(style);
+      } catch {
+        if (sheet.href) {
+          const link = pip.document.createElement('link');
+          link.rel = 'stylesheet';
+          link.href = sheet.href;
+          pip.document.head.appendChild(link);
+        }
+      }
+    }
+    const root = writeFloatDocument(pip.document, opts.title);
+    pip.addEventListener('pagehide', handleExternalClose);
+    return {
+      tier: 'document-pip',
+      portalTarget: root,
+      canvasSink: null,
+      dispose: () => {
+        pip.removeEventListener('pagehide', handleExternalClose);
+        try {
+          pip.close();
+        } catch {
+          // Already closed by the user.
+        }
+      },
+    };
+  };
+
+  const openVideoPip = async (opts: FloatOpenOptions): Promise<ActiveFloat> => {
+    const canvas = document.createElement('canvas');
+    canvas.width = Math.round(opts.width * (window.devicePixelRatio || 1));
+    canvas.height = Math.round(opts.height * (window.devicePixelRatio || 1));
+    const ctx = canvas.getContext('2d');
+    if (!ctx || typeof canvas.captureStream !== 'function') {
+      throw new Error('canvas.captureStream unavailable');
+    }
+    ctx.fillStyle = '#101014';
+    ctx.fillRect(0, 0, canvas.width, canvas.height);
+
+    let stream: MediaStream;
+    let requestFrame: () => void;
+    try {
+      stream = canvas.captureStream(0);
+      const track = stream.getVideoTracks()[0] as CaptureTrackWithRequestFrame;
+      if (typeof track.requestFrame === 'function') {
+        const pushFrame = track.requestFrame.bind(track);
+        requestFrame = () => pushFrame();
+      } else {
+        // No manual-frame API: fall back to a 30 fps capture; draws still
+        // happen on analysis ticks so content stays audio-clock driven.
+        stream = canvas.captureStream(30);
+        requestFrame = () => undefined;
+      }
+    } catch {
+      stream = canvas.captureStream(30);
+      requestFrame = () => undefined;
+    }
+
+    const video = document.createElement('video') as WebKitVideoElement;
+    video.muted = true;
+    video.playsInline = true;
+    video.style.position = 'fixed';
+    video.style.left = '-10000px';
+    video.style.width = `${opts.width}px`;
+    video.srcObject = stream;
+    document.body.appendChild(video);
+
+    const cleanupDom = () => {
+      video.pause();
+      video.srcObject = null;
+      video.remove();
+      for (const track of stream.getTracks()) track.stop();
+    };
+
+    try {
+      await video.play();
+      requestFrame();
+      if (typeof video.requestPictureInPicture === 'function' && document.pictureInPictureEnabled) {
+        await video.requestPictureInPicture();
+        video.addEventListener('leavepictureinpicture', handleExternalClose);
+      } else if (typeof video.webkitSetPresentationMode === 'function') {
+        video.webkitSetPresentationMode('picture-in-picture');
+        video.addEventListener('webkitpresentationmodechanged', () => {
+          if (video.webkitPresentationMode === 'inline') handleExternalClose();
+        });
+      } else {
+        throw new Error('No video PiP API');
+      }
+    } catch (err: unknown) {
+      cleanupDom();
+      throw err instanceof Error ? err : new Error(String(err));
+    }
+
+    return {
+      tier: 'video-pip',
+      portalTarget: null,
+      canvasSink: { canvas, width: canvas.width, height: canvas.height, requestFrame },
+      dispose: () => {
+        video.removeEventListener('leavepictureinpicture', handleExternalClose);
+        if (document.pictureInPictureElement === video) {
+          void document.exitPictureInPicture().catch(() => undefined);
+        } else if (
+          typeof video.webkitSetPresentationMode === 'function' &&
+          video.webkitPresentationMode === 'picture-in-picture'
+        ) {
+          video.webkitSetPresentationMode('inline');
+        }
+        cleanupDom();
+      },
+    };
+  };
+
+  const openPopup = (opts: FloatOpenOptions): ActiveFloat => {
+    const popup = window.open(
+      '',
+      'squisq-teleprompter',
+      `popup=yes,width=${opts.width},height=${opts.height}`,
+    );
+    if (!popup) throw new Error('Popup blocked');
+    const root = writeFloatDocument(popup.document, opts.title);
+    popup.addEventListener('pagehide', handleExternalClose);
+    popup.focus();
+    return {
+      tier: 'popup',
+      portalTarget: root,
+      canvasSink: null,
+      dispose: () => {
+        popup.removeEventListener('pagehide', handleExternalClose);
+        try {
+          popup.close();
+        } catch {
+          // Already closed.
+        }
+      },
+    };
+  };
+
+  const manager: FloatingWindowManager = {
+    get tier() {
+      return active?.tier ?? 'docked';
+    },
+    get isOpen() {
+      return active !== null;
+    },
+    async open(opts: FloatOpenOptions): Promise<FloatTier> {
+      manager.close();
+      const supported = detectFloatTiers();
+      const ladder =
+        opts.preferredTier && supported.includes(opts.preferredTier)
+          ? [opts.preferredTier, ...supported.filter((t) => t !== opts.preferredTier)]
+          : supported;
+      for (const tier of ladder) {
+        if (tier === 'docked') break;
+        try {
+          if (tier === 'document-pip') active = await openDocumentPip(opts);
+          else if (tier === 'video-pip') active = await openVideoPip(opts);
+          else if (tier === 'popup') active = openPopup(opts);
+          if (active) {
+            emit('tierchange', active.tier);
+            return active.tier;
+          }
+        } catch {
+          active = null; // fall through to the next tier
+        }
+      }
+      emit('tierchange', 'docked');
+      return 'docked';
+    },
+    close() {
+      if (!active) return;
+      const closing = active;
+      active = null;
+      closing.dispose();
+      emit('tierchange', 'docked');
+      emit('closed', 'docked');
+    },
+    getPortalTarget() {
+      return active?.portalTarget ?? null;
+    },
+    getCanvasSink() {
+      return active?.canvasSink ?? null;
+    },
+    on(event: FloatEvent, cb: (tier: FloatTier) => void) {
+      listeners[event].add(cb);
+      return () => {
+        listeners[event].delete(cb);
+      };
+    },
+    dispose() {
+      manager.close();
+      if (typeof window !== 'undefined') {
+        window.removeEventListener('pagehide', openerPageHide);
+      }
+      listeners.closed.clear();
+      listeners.tierchange.clear();
+    },
+  };
+
+  return manager;
+}

package/src/teleprompter/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Narrate (teleprompter) display mode — public surface.
+ */
+
+export {
+  TeleprompterView,
+  type TeleprompterViewProps,
+  type TeleprompterRecordingDeps,
+} from './TeleprompterView';
+export {
+  useNarrationRecorder,
+  type NarrationRecorderController,
+  type NarrationRecorderState,
+  type NarrationTake,
+} from './recording/useNarrationRecorder';
+export {
+  buildNarrationSavePlan,
+  executeNarrationSave,
+  type NarrationSavePlan,
+  type NarrationSaveResult,
+} from './recording/narrationSave';
+export {
+  insertNarrationPreamble,
+  narrationAnnotationLine,
+  cameraVideoLine,
+} from './recording/insertPreamble';
+export { TeleprompterSurface, type TeleprompterSurfaceProps } from './TeleprompterSurface';
+export { TeleprompterControls, type TeleprompterControlsProps } from './TeleprompterControls';
+export {
+  useTeleprompter,
+  vadConfigForSensitivity,
+  type TeleprompterController,
+} from './useTeleprompter';
+export { useMicAnalysis, type MicAnalysisHandle, type MicAnalysisStatus } from './useMicAnalysis';
+export { PCM_WORKLET_SOURCE, PCM_WORKLET_NAME, registerPcmWorklet } from './pcmWorklet';
+export {
+  createFloatingWindowManager,
+  detectFloatTiers,
+  type FloatingWindowManager,
+  type FloatOpenOptions,
+  type CanvasSink,
+} from './floatingWindow';
+export { useFloatingWindow, type FloatingWindowHandle } from './useFloatingWindow';
+export {
+  measureTokenLines,
+  targetOffsetFor,
+  stepScroll,
+  EYE_LINE_FRACTION,
+  type TokenLineMap,
+} from './scrollModel';
+export {
+  TELEPROMPTER_CSS,
+  ensureTeleprompterStyles,
+  prompterVarsFromTheme,
+} from './teleprompterTheme';
+export {
+  DEFAULT_TELEPROMPTER_PREFS,
+  type TeleprompterPrefs,
+  type PrompterTransport,
+  type FloatTier,
+} from './types';

package/src/teleprompter/pcmWorklet.ts

@@ -0,0 +1,62 @@
+/**
+ * The PCM tap AudioWorklet, shipped as an inline source string.
+ *
+ * Why inline → Blob URL instead of a bundled asset: `audioWorklet
+ * .addModule(url)` resolves relative to the host DOCUMENT, so a
+ * dist-relative asset would need every consumer's bundler to rewrite
+ * and serve it (editor-react ships zero runtime assets today). The
+ * worklet is ~30 lines with no imports; inlining follows the
+ * `PLAYER_BUNDLE` source-string precedent and needs zero bundler
+ * config. The worklet does NO DSP — it batches 128-sample render
+ * quanta into 1024-sample frames and posts them (transferably) to the
+ * main thread, where the pure engine in `@bendyline/squisq/narration`
+ * runs. The audio render thread never throttles, so pacing keeps
+ * working while the browser window is fully occluded by recording
+ * software — the whole point of the teleprompter's scenario 2.
+ */
+
+export const PCM_WORKLET_NAME = 'squisq-pcm-tap';
+
+export const PCM_WORKLET_SOURCE = `
+class SquisqPcmTap extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this._buf = new Float32Array(1024);
+    this._len = 0;
+  }
+  process(inputs) {
+    const channel = inputs[0] && inputs[0][0];
+    if (channel && channel.length > 0) {
+      let i = 0;
+      while (i < channel.length) {
+        const n = Math.min(channel.length - i, this._buf.length - this._len);
+        this._buf.set(channel.subarray(i, i + n), this._len);
+        this._len += n;
+        i += n;
+        if (this._len === this._buf.length) {
+          const out = this._buf;
+          this._buf = new Float32Array(1024);
+          this._len = 0;
+          // Clone, don't transfer: Chrome recycles buffers transferred out
+          // of the worklet scope once the receiving handler returns, so a
+          // transferred hop reads as zeros if anything retains it. A 4 KB
+          // structured clone at ~47 Hz is negligible.
+          this.port.postMessage({ pcm: out, audioTime: currentTime });
+        }
+      }
+    }
+    return true;
+  }
+}
+registerProcessor('${PCM_WORKLET_NAME}', SquisqPcmTap);
+`;
+
+/** Register the tap on an AudioContext via a same-origin Blob URL. */
+export async function registerPcmWorklet(ctx: AudioContext): Promise<void> {
+  const url = URL.createObjectURL(new Blob([PCM_WORKLET_SOURCE], { type: 'text/javascript' }));
+  try {
+    await ctx.audioWorklet.addModule(url);
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}

package/src/teleprompter/recording/insertPreamble.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure markdown edit: insert (or replace) the narration reference at the
+ * start of the document.
+ *
+ * The narration take is referenced by a preamble media annotation —
+ * `{[audio src=audio/narration-….webm anchor=document]}` — the canonical
+ * authored form `markdownToDoc` lifts into `doc.documentMedia`. A prior
+ * teleprompter take's line (matched by the `audio/narration-` prefix +
+ * `anchor=document`) is replaced, so retakes swap the reference instead
+ * of stacking narrations. The optional camera companion rides on the
+ * next line as an inline `<video>` (deliberately NOT doc-anchored:
+ * document-anchored video renders full-bleed behind every block and is
+ * excluded from export audio — not a talking head).
+ */
+
+const NARRATION_LINE =
+  /^\{\[audio\s[^\]]*src="?audio\/narration-[^\]]*anchor=document[^\]]*\]\}\s*$/;
+const CAMERA_LINE = /^<video\s[^>]*src="video\/narration-cam-[^"]*"[^>]*><\/video>\s*$/;
+
+function quoteSrc(path: string): string {
+  return /[\s"']/.test(path) ? `"${path.replace(/"/g, '\\"')}"` : path;
+}
+
+export function narrationAnnotationLine(audioPath: string): string {
+  return `{[audio src=${quoteSrc(audioPath)} anchor=document]}`;
+}
+
+export function cameraVideoLine(cameraPath: string): string {
+  return `<video src="${cameraPath}" controls width="240"></video>`;
+}
+
+/**
+ * Insert the narration preamble after the frontmatter (or at the top),
+ * replacing any previous teleprompter take's lines.
+ */
+export function insertNarrationPreamble(
+  source: string,
+  audioPath: string,
+  cameraPath: string | null,
+): string {
+  const lines = source.split('\n');
+
+  // Locate the insertion point: after a closing frontmatter fence.
+  let insertAt = 0;
+  if (lines[0]?.trim() === '---') {
+    for (let i = 1; i < lines.length; i++) {
+      if (lines[i].trim() === '---') {
+        insertAt = i + 1;
+        break;
+      }
+    }
+  }
+
+  // Remove a previous take's annotation (+ adjacent camera line).
+  for (let i = 0; i < lines.length; i++) {
+    if (!NARRATION_LINE.test(lines[i])) continue;
+    let removeEnd = i + 1;
+    while (removeEnd < lines.length && lines[removeEnd].trim() === '') removeEnd++;
+    if (removeEnd < lines.length && CAMERA_LINE.test(lines[removeEnd])) removeEnd++;
+    // Also consume one trailing blank so we don't accumulate gaps.
+    if (removeEnd < lines.length && lines[removeEnd].trim() === '') removeEnd++;
+    lines.splice(i, removeEnd - i);
+    if (insertAt > i) insertAt = Math.max(0, insertAt - (removeEnd - i));
+    break;
+  }
+
+  const inserted: string[] = [narrationAnnotationLine(audioPath)];
+  if (cameraPath) {
+    inserted.push('', cameraVideoLine(cameraPath));
+  }
+
+  // Blank-line separation on both sides (unless at the very top with
+  // content immediately following, where only the trailing blank matters).
+  const before = lines.slice(0, insertAt);
+  const after = lines.slice(insertAt);
+  if (before.length > 0 && before[before.length - 1].trim() !== '') before.push('');
+  if (after.length > 0 && after[0].trim() !== '') inserted.push('');
+
+  return [...before, ...inserted, ...after].join('\n');
+}

package/src/teleprompter/recording/narrationSave.ts

@@ -0,0 +1,134 @@
+/**
+ * Pure save-plan builder for a narration take, plus its executor.
+ *
+ * Follows the recorder's conventions (`RecorderModal.handleSave`):
+ * audio at `audio/<narration-…>` via `MediaProvider.addMedia` (the
+ * RETURNED path is authoritative — providers may rename), the timing
+ * sidecar at `<audio>.timing.json` via `container.writeFile` (falling
+ * back to `addMedia` with a warning), and ONE `setMarkdownSource` write
+ * composing every markdown edit from a single snapshot (the single-write
+ * rule — successive writes each derive from stale source and clobber
+ * each other).
+ *
+ * Block timings deliberately do NOT get baked into heading `duration=`
+ * pins: pins outrank narration in `applyNarrationTiming`, so baking
+ * them would shadow every retake. The sidecar owns the timing.
+ */
+
+import {
+  buildNarrationTimingJson,
+  type NarrationAlignment,
+  type NarrationScript,
+  type NarrationTimingJsonV3,
+} from '@bendyline/squisq/narration';
+import type { MediaProvider } from '@bendyline/squisq/schemas';
+import type { ContentContainer } from '@bendyline/squisq/storage';
+import { buildFilename } from '../../recorder/formats';
+import { encodeTimingJson, timingPathFor } from '../../recorder/timingJson';
+import { insertNarrationPreamble } from './insertPreamble';
+
+export interface NarrationSavePlanArgs {
+  script: NarrationScript;
+  /** Null when decode/alignment failed — the sidecar still saves (empty timing). */
+  alignment: NarrationAlignment | null;
+  durationSec: number;
+  audioExt: string;
+  cameraExt: string | null;
+  baseWpm: number;
+  cameraOffsetSec?: number;
+}
+
+export interface NarrationSavePlan {
+  audioRelativeName: string;
+  cameraRelativeName: string | null;
+  sidecarPayload: NarrationTimingJsonV3;
+  /** Sidecar path for a given (possibly renamed) saved audio path. */
+  sidecarPathFor: (savedAudioPath: string) => string;
+  /** Compose ALL markdown edits from one source snapshot. */
+  nextMarkdown: (
+    currentSource: string,
+    savedAudioPath: string,
+    savedCameraPath: string | null,
+  ) => string;
+}
+
+export function buildNarrationSavePlan(args: NarrationSavePlanArgs): NarrationSavePlan {
+  const sidecarPayload: NarrationTimingJsonV3 = args.alignment
+    ? buildNarrationTimingJson(args.script, args.alignment, args.durationSec, {
+        baseWpm: args.baseWpm,
+        ...(args.cameraOffsetSec !== undefined ? { cameraOffsetSec: args.cameraOffsetSec } : {}),
+      })
+    : {
+        version: 3,
+        sourceText: args.script.sourceText,
+        duration: args.durationSec,
+        bookmarks: [],
+        blocks: [],
+        generator: { name: 'squisq-teleprompter', method: 'dsp-align', baseWpm: args.baseWpm },
+      };
+
+  return {
+    audioRelativeName: `audio/${buildFilename('audio', args.audioExt)}`,
+    cameraRelativeName: args.cameraExt
+      ? `video/${buildFilename('video', args.cameraExt, 'narration-cam')}`
+      : null,
+    sidecarPayload,
+    sidecarPathFor: (savedAudioPath) => timingPathFor(savedAudioPath),
+    nextMarkdown: (currentSource, savedAudioPath, savedCameraPath) =>
+      insertNarrationPreamble(currentSource, savedAudioPath, savedCameraPath),
+  };
+}
+
+export interface ExecuteNarrationSaveDeps {
+  mediaProvider: MediaProvider;
+  container: ContentContainer | null;
+  markdownSource: string;
+  setMarkdownSource: (next: string) => void;
+  bumpMediaRevision: () => void;
+}
+
+export interface NarrationSaveResult {
+  audioPath: string;
+  cameraPath: string | null;
+  sidecarPath: string;
+}
+
+/** Execute a save plan: media writes, sidecar, then the single markdown write. */
+export async function executeNarrationSave(
+  plan: NarrationSavePlan,
+  take: { audioBlob: Blob; audioMime: string; cameraBlob: Blob | null; cameraMime: string | null },
+  deps: ExecuteNarrationSaveDeps,
+): Promise<NarrationSaveResult> {
+  const audioPath = await deps.mediaProvider.addMedia(
+    plan.audioRelativeName,
+    take.audioBlob,
+    take.audioMime,
+  );
+
+  const sidecarPath = plan.sidecarPathFor(audioPath);
+  const encoded = encodeTimingJson(plan.sidecarPayload);
+  if (deps.container) {
+    await deps.container.writeFile(sidecarPath, encoded, 'application/json');
+  } else {
+    const storedAt = await deps.mediaProvider.addMedia(sidecarPath, encoded, 'application/json');
+    if (storedAt !== sidecarPath) {
+      console.warn(
+        `Narration timing sidecar stored at "${storedAt}" instead of "${sidecarPath}"; ` +
+          'narration timing will not be discovered until it sits next to the audio file.',
+      );
+    }
+  }
+
+  let cameraPath: string | null = null;
+  if (plan.cameraRelativeName && take.cameraBlob && take.cameraMime) {
+    cameraPath = await deps.mediaProvider.addMedia(
+      plan.cameraRelativeName,
+      take.cameraBlob,
+      take.cameraMime,
+    );
+  }
+
+  deps.setMarkdownSource(plan.nextMarkdown(deps.markdownSource, audioPath, cameraPath));
+  deps.bumpMediaRevision();
+  return { audioPath, cameraPath, sidecarPath };
+}