@bendyline/squisq-editor-react 2.3.4 → 2.4.1

package/dist/useNarrationStage-Bqo18PBw.d.ts

@@ -0,0 +1,313 @@
+import { SyntheticEvent } from 'react';
+import { Doc, MediaProvider } from '@bendyline/squisq/schemas';
+import { ContentContainer } from '@bendyline/squisq/storage';
+import { NarrationScript, VadConfig, NarrationTrace, NarrationAlignment } from '@bendyline/squisq/narration';
+
+/**
+ * Mic capture + PCM transport for the teleprompter.
+ *
+ * getUserMedia → AudioContext → AudioWorklet tap → subscriber callbacks
+ * with 1024-sample Float32Array hops on the main thread. The DSP itself
+ * lives in core (`@bendyline/squisq/narration`) — this hook only moves
+ * samples. Falls back to a ScriptProcessorNode when `audioWorklet` is
+ * unavailable (same push model, so pacing still isn't tied to rAF).
+ */
+type MicAnalysisStatus = 'idle' | 'starting' | 'live' | 'error';
+type PcmHopListener = (pcm: Float32Array, audioTimeSec: number) => void;
+interface MicAnalysisHandle {
+    status: MicAnalysisStatus;
+    error: Error | null;
+    /** The live mic stream (feeds the narration recorder too), or null. */
+    stream: MediaStream | null;
+    /** AudioContext sample rate once live. */
+    sampleRate: number | null;
+    /** Known audio inputs (labels appear after the first grant). */
+    devices: MediaDeviceInfo[];
+    /**
+     * Start (or restart) capture. Resolves with the live stream — callers
+     * that need it immediately must use the return value, not the `stream`
+     * state field, which only updates on the NEXT render (stale-closure
+     * hazard right after an await). Null on failure/supersession.
+     */
+    start: (deviceId: string | null) => Promise<MediaStream | null>;
+    stop: () => void;
+    /** Subscribe to PCM hops; returns an unsubscribe. */
+    subscribeHop: (listener: PcmHopListener) => () => void;
+}
+declare function useMicAnalysis(): MicAnalysisHandle;
+
+/**
+ * Shared types for the Narrate (teleprompter) display mode.
+ */
+interface TeleprompterPrefs {
+    /** Prompter type size in px (28–96). */
+    fontSizePx: number;
+    /** Beam-splitter mirror flip. */
+    mirrored: boolean;
+    /** Base speaking rate in words per minute (80–260). */
+    baseWpm: number;
+    /** Voice-adaptive pacing on/off; off = constant-rate manual mode. */
+    voiceTracking: boolean;
+    /** VAD sensitivity 0–1 (0.5 = engine defaults). */
+    vadSensitivity: number;
+    /** Countdown before the prompter starts rolling. */
+    countdownSec: 0 | 3 | 5 | 10;
+    /** Eye-line chevrons + focus band. */
+    lineGuide: boolean;
+    /** Preferred mic device id (null = system default). */
+    micDeviceId: string | null;
+}
+declare const DEFAULT_TELEPROMPTER_PREFS: TeleprompterPrefs;
+declare const TELEPROMPTER_PREF_LIMITS: Readonly<{
+    fontSizePx: {
+        min: number;
+        max: number;
+    };
+    baseWpm: {
+        min: number;
+        max: number;
+    };
+    vadSensitivity: {
+        min: number;
+        max: number;
+    };
+    micDeviceIdMaxLength: 1024;
+}>;
+/**
+ * Validate persisted or externally supplied preferences and return a complete,
+ * bounded value. Unknown keys are ignored; invalid fields retain `fallback`.
+ */
+declare function normalizeTeleprompterPrefs(value: unknown, fallback?: TeleprompterPrefs): TeleprompterPrefs;
+type PrompterTransport = 'stopped' | 'countdown' | 'rolling' | 'paused' | 'finished';
+/** Floating-surface tier, best first. */
+type FloatTier = 'document-pip' | 'video-pip' | 'popup' | 'docked';
+
+/**
+ * The teleprompter controller — single source of truth, always in the
+ * MAIN window (floats are render targets only).
+ *
+ * Loop-ownership rule: **the audio worklet owns time; the main window
+ * owns state; the visible surface owns pixels.** Voice-mode position
+ * advances on worklet PCM hops (immune to rAF/timer throttling while
+ * the browser is occluded by recording software); manual constant-rate
+ * mode uses rAF and is documented as best-effort under occlusion. React
+ * state publishes at ~15 Hz; per-hop subscribers (`subscribeTick`)
+ * exist for the video-PiP canvas pump.
+ */
+
+interface TeleprompterKeyEvent {
+    readonly defaultPrevented: boolean;
+    readonly key: string;
+    readonly repeat: boolean;
+    readonly target: EventTarget | null;
+    preventDefault: () => void;
+}
+interface TeleprompterController {
+    script: NarrationScript | null;
+    transport: PrompterTransport;
+    countdownRemaining: number | null;
+    /** Fractional word position (published ~15 Hz). */
+    wordPos: number;
+    /** Smoothed mic level 0–1 for the meter. */
+    micLevel: number;
+    /** VAD flag for the meter tint. */
+    voiceActive: boolean;
+    mic: MicAnalysisHandle;
+    prefs: TeleprompterPrefs;
+    setPrefs: (patch: Partial<TeleprompterPrefs>) => void;
+    play: () => void;
+    pause: () => void;
+    restart: () => void;
+    /** Move by spoken words and re-anchor voice tracking. */
+    nudge: (deltaWords: number) => void;
+    /** Jump to an absolute token index (e.g. click a block marker). */
+    seekToToken: (tokenIndex: number) => void;
+    /** Per-analysis-tick subscription (video-PiP pump). Not throttled. */
+    subscribeTick: (cb: (wordPos: number) => void) => () => void;
+    handleKeyDown: (event: TeleprompterKeyEvent) => void;
+}
+/** Map the 0–1 sensitivity pref onto VAD thresholds (0.5 = engine defaults). */
+declare function vadConfigForSensitivity(sensitivity: number): Partial<VadConfig>;
+declare function useTeleprompter(opts: {
+    doc: Doc | null;
+}): TeleprompterController;
+
+/**
+ * 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.
+ */
+
+interface FloatOpenOptions {
+    width: number;
+    height: number;
+    /** Try this tier first; the ladder continues below it on failure. */
+    preferredTier?: FloatTier;
+    title: string;
+}
+interface CanvasSink {
+    canvas: HTMLCanvasElement;
+    width: number;
+    height: number;
+    /** Push the freshly drawn canvas frame into the PiP video. */
+    requestFrame: () => void;
+}
+type FloatEvent = 'closed' | 'tierchange';
+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. */
+declare function detectFloatTiers(): FloatTier[];
+declare function createFloatingWindowManager(deps: {
+    styleCss: string;
+}): FloatingWindowManager;
+
+/**
+ * React binding over {@link createFloatingWindowManager}: exposes the
+ * current tier + portal target as state and guarantees the float closes
+ * when the owning view unmounts (mode switch, Use-tab exit, shell
+ * teardown).
+ */
+
+interface FloatingWindowHandle {
+    tier: FloatTier;
+    isOpen: boolean;
+    /** Non-docked tiers this browser supports, best first. */
+    supportedTiers: FloatTier[];
+    portalTarget: HTMLElement | null;
+    canvasSink: CanvasSink | null;
+    open: (preferredTier?: FloatTier) => Promise<void>;
+    close: () => void;
+}
+declare function useFloatingWindow(styleCss: string): FloatingWindowHandle;
+
+/**
+ * Narration recorder for the teleprompter — an in-place (no modal)
+ * capture flow.
+ *
+ * Audio records THE MIC ANALYSIS STREAM (what paces the prompter is
+ * exactly what lands in the take); the optional camera is a separate
+ * video-only capture whose start skew vs the audio recorder is measured
+ * and persisted (`cameraOffsetSec`) — the audio file is the doc clock,
+ * so camera skew never affects narration timing. While recording, a
+ * sparse live trace of the prompter position is sampled; after stop,
+ * the take is decoded and run through core's offline aligner
+ * (`alignNarration`) to produce word/block timestamps for the sidecar.
+ * Decode/alignment failure degrades gracefully: saving still works,
+ * just without re-timing.
+ */
+
+type NarrationRecorderState = 'idle' | 'starting' | 'recording' | 'processing' | 'review' | 'saving' | 'error';
+interface NarrationTake {
+    audioBlob: Blob;
+    audioMime: string;
+    audioExt: string;
+    cameraBlob: Blob | null;
+    cameraMime: string | null;
+    cameraExt: string | null;
+    durationSec: number;
+    cameraOffsetSec: number | undefined;
+    trace: NarrationTrace;
+    alignment: NarrationAlignment | null;
+    script: NarrationScript;
+}
+interface UseNarrationRecorderOptions {
+    mic: MicAnalysisHandle;
+    getScript: () => NarrationScript | null;
+    /** Live prompter position, sampled into the trace while recording. */
+    getWordPos: () => number;
+    getMicDeviceId: () => string | null;
+    /** Fired when capture actually starts (View starts the prompter). */
+    onRecordingStart?: () => void;
+    onRecordingStop?: () => void;
+}
+interface NarrationRecorderController {
+    state: NarrationRecorderState;
+    error: Error | null;
+    withCamera: boolean;
+    setWithCamera: (on: boolean) => void;
+    /** Live camera stream for the self-view while recording. */
+    cameraStream: MediaStream | null;
+    take: NarrationTake | null;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    retake: () => void;
+    discard: () => void;
+    /** Transition into/out of 'saving'; the View owns the actual I/O. */
+    beginSave: () => void;
+    finishSave: (ok: boolean, error?: Error) => void;
+}
+declare function useNarrationRecorder(options: UseNarrationRecorderOptions): NarrationRecorderController;
+
+/**
+ * useNarrationStage — the state/orchestration half of the narration stage,
+ * extracted from TeleprompterView so other hosts (the Record media dialog)
+ * can mount the same prompter + recorder + save pipeline.
+ *
+ * Owns the teleprompter controller (single source of truth in the main
+ * window), the floating-window handle, the narration recorder, and the
+ * retry-idempotent save flow. Pair with <NarrationStage> for the DOM.
+ *
+ * Recording is prop-gated: pass `recording` deps (media provider + markdown
+ * writers) to enable capture; without them this is a pure prompter with zero
+ * capture code paths.
+ */
+
+/** Editor plumbing the recording flow needs; omit for prompter-only use. */
+interface TeleprompterRecordingDeps {
+    mediaProvider: MediaProvider;
+    container: ContentContainer | null;
+    markdownSource: string;
+    setMarkdownSource: (next: string) => void;
+    bumpMediaRevision: () => void;
+}
+interface UseNarrationStageOptions {
+    doc: Doc | null;
+    /** Recording deps; null/omitted disables the Record affordance. */
+    recording?: TeleprompterRecordingDeps | null;
+    /** Optional user-chosen filename base threaded into the save plan. */
+    getAudioBasename?: () => string | undefined;
+}
+interface NarrationStageHandle {
+    controller: TeleprompterController;
+    float: FloatingWindowHandle;
+    recorder: NarrationRecorderController;
+    /** Pass-through so the stage component can gate its record slot. */
+    recording: TeleprompterRecordingDeps | null;
+    saveNotice: string | null;
+    dismissSaveNotice: () => void;
+    handleSave: () => Promise<void>;
+    handleRetake: () => void;
+    handleDiscard: () => void;
+    reviewAudioUrl: string | null;
+    handleReviewTimeUpdate: (event: SyntheticEvent<HTMLAudioElement>) => void;
+}
+declare function useNarrationStage(opts: UseNarrationStageOptions): NarrationStageHandle;
+
+export { type CanvasSink as C, DEFAULT_TELEPROMPTER_PREFS as D, type FloatOpenOptions as F, type MicAnalysisHandle as M, type NarrationRecorderController as N, type PrompterTransport as P, type TeleprompterController as T, type UseNarrationStageOptions as U, type FloatTier as a, type FloatingWindowHandle as b, type FloatingWindowManager as c, type MicAnalysisStatus as d, type NarrationRecorderState as e, type NarrationStageHandle as f, type NarrationTake as g, type TeleprompterPrefs as h, type TeleprompterRecordingDeps as i, createFloatingWindowManager as j, detectFloatTiers as k, useMicAnalysis as l, useNarrationRecorder as m, useNarrationStage as n, useTeleprompter as o, TELEPROMPTER_PREF_LIMITS as p, normalizeTeleprompterPrefs as q, useFloatingWindow as u, vadConfigForSensitivity as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-editor-react",
-  "version": "2.3.4",
+  "version": "2.4.1",
   "description": "React editor shell with raw/WYSIWYG/preview modes for Squisq documents",
   "license": "MIT",
   "author": "Bendyline",
@@ -23,7 +23,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22.14.0"
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -84,9 +84,9 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@bendyline/squisq": "2.3.3",
-    "@bendyline/squisq-formats": "2.3.3",
-    "@bendyline/squisq-react": "2.3.3",
+    "@bendyline/squisq": "2.4.1",
+    "@bendyline/squisq-formats": "2.3.5",
+    "@bendyline/squisq-react": "2.4.1",
     "@fortawesome/fontawesome-free": "7.2.0",
     "@tiptap/extension-image": "2.27.2",
     "@tiptap/extension-link": "2.27.2",
@@ -116,6 +116,8 @@
     "typescript": "5.9.3"
   },
   "sideEffects": [
-    "**/*.css"
+    "**/*.css",
+    "**/monacoFeatures*",
+    "**/monacoSuggestions*"
   ]
 }

package/dist/chunk-5Q4JN4I5.js

@@ -1,132 +0,0 @@
-// src/recorder/formats.ts
-var AUDIO_CANDIDATES = [
-  "audio/webm;codecs=opus",
-  "audio/webm",
-  "audio/mp4;codecs=mp4a.40.2",
-  "audio/mp4",
-  "audio/ogg;codecs=opus"
-];
-var VIDEO_CANDIDATES = [
-  "video/webm;codecs=vp9,opus",
-  "video/webm;codecs=vp8,opus",
-  "video/webm",
-  "video/mp4;codecs=avc1.42E01E,mp4a.40.2",
-  "video/mp4"
-];
-function extensionForMime(mimeType) {
-  const m = mimeType.toLowerCase();
-  if (m.startsWith("audio/webm")) return ".webm";
-  if (m.startsWith("audio/ogg")) return ".ogg";
-  if (m.startsWith("audio/mp4")) return ".m4a";
-  if (m.startsWith("audio/mpeg")) return ".mp3";
-  if (m.startsWith("audio/wav")) return ".wav";
-  if (m.startsWith("video/webm")) return ".webm";
-  if (m.startsWith("video/mp4")) return ".mp4";
-  return ".bin";
-}
-function probeMimeType(candidates) {
-  if (typeof MediaRecorder === "undefined") return null;
-  for (const candidate of candidates) {
-    try {
-      if (MediaRecorder.isTypeSupported(candidate)) return candidate;
-    } catch {
-    }
-  }
-  return null;
-}
-function resolveFormat(kind, preferred) {
-  const candidates = kind === "audio" ? AUDIO_CANDIDATES : VIDEO_CANDIDATES;
-  const probed = (preferred && probeMimeType([preferred])) ?? probeMimeType(candidates) ?? "";
-  const directory = kind === "audio" ? "audio" : "video";
-  const extension = probed ? extensionForMime(probed) : ".webm";
-  return { mimeType: probed, extension, directory };
-}
-function supportsMediaRecorder() {
-  return typeof MediaRecorder !== "undefined";
-}
-function supportsUserMedia() {
-  return typeof navigator !== "undefined" && typeof navigator.mediaDevices !== "undefined" && typeof navigator.mediaDevices.getUserMedia === "function";
-}
-function supportsDisplayMedia() {
-  return typeof navigator !== "undefined" && typeof navigator.mediaDevices !== "undefined" && typeof navigator.mediaDevices.getDisplayMedia === "function";
-}
-function buildFilename(kind, extension, basename) {
-  const safe = basename ? basename.trim().replace(/[\\/:*?"<>|]+/g, "-").replace(/\s+/g, "-") : "";
-  if (safe) return `${safe}${extension}`;
-  const now = /* @__PURE__ */ new Date();
-  const stamp = now.getFullYear().toString().padStart(4, "0") + (now.getMonth() + 1).toString().padStart(2, "0") + now.getDate().toString().padStart(2, "0") + "-" + now.getHours().toString().padStart(2, "0") + now.getMinutes().toString().padStart(2, "0") + now.getSeconds().toString().padStart(2, "0");
-  const prefix = kind === "audio" ? "narration" : "recording";
-  return `${prefix}-${stamp}${extension}`;
-}
-
-// src/recorder/sources/micStream.ts
-async function requestMicStream(constraints) {
-  if (!supportsUserMedia()) {
-    throw new Error("navigator.mediaDevices.getUserMedia is not available in this environment.");
-  }
-  return navigator.mediaDevices.getUserMedia({
-    audio: constraints ?? true,
-    video: false
-  });
-}
-
-// src/recorder/sources/cameraStream.ts
-async function requestCameraStream(options) {
-  if (!supportsUserMedia()) {
-    throw new Error("navigator.mediaDevices.getUserMedia is not available in this environment.");
-  }
-  const video = options?.video ?? true;
-  const audio = options?.audio ?? true;
-  return navigator.mediaDevices.getUserMedia({ video, audio });
-}
-
-// src/recorder/hooks/useStreamPreview.ts
-import { useEffect } from "react";
-function useStreamPreview(ref, stream) {
-  useEffect(() => {
-    const el = ref.current;
-    if (!el) return;
-    el.muted = true;
-    el.playsInline = true;
-    el.srcObject = stream;
-    if (stream) {
-      void el.play().catch(() => {
-      });
-    }
-    return () => {
-      if (el.srcObject === stream) {
-        el.srcObject = null;
-      }
-    };
-  }, [ref, stream]);
-}
-
-// src/recorder/timingJson.ts
-function buildTimingJson(sourceText, durationSec) {
-  return {
-    sourceText: sourceText ?? "",
-    duration: Number.isFinite(durationSec) && durationSec >= 0 ? durationSec : 0,
-    bookmarks: []
-  };
-}
-function encodeTimingJson(timing) {
-  const text = JSON.stringify(timing, null, 2);
-  return new TextEncoder().encode(text);
-}
-function timingPathFor(audioRelativePath) {
-  return `${audioRelativePath}.timing.json`;
-}
-
-export {
-  resolveFormat,
-  supportsMediaRecorder,
-  supportsUserMedia,
-  supportsDisplayMedia,
-  buildFilename,
-  requestMicStream,
-  requestCameraStream,
-  useStreamPreview,
-  buildTimingJson,
-  encodeTimingJson,
-  timingPathFor
-};