@bendyline/squisq-editor-react 2.1.0 → 2.2.0

package/src/teleprompter/floatingWindow.ts

@@ -1,352 +0,0 @@
-/**
- * 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

@@ -1,61 +0,0 @@
-/**
- * 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

@@ -1,62 +0,0 @@
-/**
- * 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

@@ -1,80 +0,0 @@
-/**
- * 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

@@ -1,134 +0,0 @@
-/**
- * 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 };
-}