@bendyline/squisq-editor-react 2.11.16 → 2.11.18

package/dist/{shell-X0EoQbbN.d.ts → shell-Cb0P_ln8.d.ts}

@@ -7,9 +7,10 @@ import { ReactNode, RefObject, ReactElement } from 'react';
 import { Doc, MediaProvider, ViewportPreset, Theme } from '@bendyline/squisq/schemas';
 import { FenceRendererMap } from '@bendyline/squisq/fence';
 import { CodeBlockCopyHandler } from '@bendyline/squisq-react';
-import { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { MarkdownSourceEdit, MarkdownDocument } from '@bendyline/squisq/markdown';
 import { ContentContainer } from '@bendyline/squisq/storage';
 import { a as ProofingCapability, c as ProofingIgnoreStore } from './types-De4z-gGb.js';
+import { DictationControl, SpeechInputCapability } from './speech/index.js';
 import { DocumentVersionManager, SaveVersionOptions, SaveVersionResult, PrunePolicy } from '@bendyline/squisq/versions';
 import { Editor } from '@tiptap/core';
 import { editor } from 'monaco-editor';
@@ -207,6 +208,102 @@ declare function offsetToLine(source: string, offset: number): number;
 /** Index of the slice whose range contains `offset`, or -1. */
 declare function sliceIndexAtOffset(slices: BlockSlice[], offset: number): number;
 
+/**
+ * sourceEdits
+ *
+ * Pure helpers behind the editor's undoable source-edit actions
+ * (`applySourceEdits`, `insertBlockAfterCursor`) and usable by any host that
+ * plans edits against a markdown string:
+ *
+ * - validating and applying `{ start, end, text }` edits to a source string;
+ * - the smallest single edit that turns one source into another;
+ * - where a new block may go relative to a cursor, without splitting a
+ *   container template (drawing, layout, diagram) or letting a new heading
+ *   capture the paragraphs that follow it.
+ *
+ * Placement is decided on an abstract outline of top-level blocks so the Write
+ * view (ProseMirror nodes) and the Source view (markdown AST) share one rule.
+ */
+
+/**
+ * Where `insertBlockAfterCursor` puts a block.
+ *
+ * - `afterBlock`: straight after the top-level block holding the cursor. Right
+ *   for fences, tables and paragraphs.
+ * - `sectionEnd`: at the end of the cursor's section, just before the next
+ *   heading. Right for heading-based blocks, which would otherwise capture
+ *   the paragraphs after them.
+ */
+type BlockPlacement = 'afterBlock' | 'sectionEnd';
+/** The heading structure around an insertion point. */
+interface BlockInsertionContext {
+    /** Depth of the section the insertion point belongs to; 0 before any heading. */
+    sectionDepth: number;
+    /** Depth of the first heading after the insertion point, or null at the end. */
+    nextHeadingDepth: number | null;
+    /**
+     * Deepest heading depth a heading-based block may use here. Normally 6;
+     * lower straight after a container template, whose children any deeper
+     * heading would join.
+     */
+    maxHeadingDepth: number;
+}
+/** One top-level block, as an outline sees it. */
+interface OutlineBlock {
+    /** Heading depth, or null for any non-heading block. */
+    headingDepth: number | null;
+    /** True for a heading whose template consumes the headings under it. */
+    container: boolean;
+}
+/** An insertion point in an outline: insert before `blocks[index]`. */
+interface OutlineInsertion extends BlockInsertionContext {
+    index: number;
+}
+/** Validate edits against `source` and sort them by position; null if any is unusable. */
+declare function normalizeSourceEdits(source: string, edits: readonly MarkdownSourceEdit[]): MarkdownSourceEdit[] | null;
+/** Apply edits to `source`. Throws on edits `normalizeSourceEdits` rejects. */
+declare function applySourceEditsToText(source: string, edits: readonly MarkdownSourceEdit[]): string;
+/** The smallest single edit turning `previous` into `next`, or null when they are equal. */
+declare function minimalReplaceEdit(previous: string, next: string): MarkdownSourceEdit | null;
+/**
+ * Decide where a block goes in an outline, given the block holding the cursor
+ * (`cursorIndex`, -1 when the cursor is before every block).
+ *
+ * A cursor inside a container template never puts a block among its children:
+ * `afterBlock` moves before the container and `sectionEnd` after its subtree.
+ */
+declare function resolveOutlineInsertion(blocks: readonly OutlineBlock[], cursorIndex: number, placement: BlockPlacement): OutlineInsertion;
+/**
+ * Heading depth for a heading-based block inserted at this point, so the
+ * heading that follows closes it instead of being captured, and it does not
+ * join a preceding container's children. `childLevels` reserves depth for the
+ * block's own child headings (1 for drawing and layout). Null when nothing fits.
+ */
+declare function headingDepthForInsertion(context: BlockInsertionContext, options?: {
+    childLevels?: number;
+}): number | null;
+/** Top-level blocks of a markdown source with their character ranges. */
+declare function sourceOutline(source: string): {
+    blocks: OutlineBlock[];
+    ranges: Array<{
+        start: number;
+        end: number;
+    }>;
+};
+/**
+ * Where a block goes in a markdown source for a cursor at `cursorOffset`.
+ * `offset` is the end of the block the new one follows (or the body start);
+ * pass it to {@link joinBlockAt}.
+ */
+declare function blockInsertionPoint(source: string, cursorOffset: number, placement: BlockPlacement): BlockInsertionContext & {
+    offset: number;
+};
+/**
+ * The edit that puts `block` at `offset` with exactly one blank line on each
+ * side, absorbing whatever whitespace already surrounds that point.
+ */
+declare function joinBlockAt(source: string, offset: number, block: string): MarkdownSourceEdit;
+
 /**
  * Configuration a Scene host (diagram / drawing / layout widget) supplies
  * so the shared inline text editor knows how to read and write the text of
@@ -288,6 +385,25 @@ interface DocumentLinkCandidate {
  */
 type DocumentLinkProvider = (query: string) => Promise<DocumentLinkCandidate[]>;
 type EditorView = 'raw' | 'wysiwyg' | 'preview';
+/** Options for {@link EditorActions.applySourceEdits}. */
+interface ApplySourceEditsOptions {
+    /**
+     * The source the edits were planned against. When the document no longer
+     * matches it, nothing is applied and the action returns false.
+     */
+    baseSource?: string;
+}
+/**
+ * Builds the markdown for {@link EditorActions.insertBlockAfterCursor} once the
+ * insertion point is known, so a heading-based block can pick a depth that
+ * fits there. Return null to cancel.
+ */
+type BlockInsertionBuilder = (context: BlockInsertionContext) => string | null;
+/** Options for {@link EditorActions.insertBlockAfterCursor}. */
+interface InsertBlockOptions {
+    /** Defaults to `'afterBlock'`. Use `'sectionEnd'` for heading-based blocks. */
+    placement?: BlockPlacement;
+}
 /** What is selected in the active editing surface. */
 interface EditorSelectionInfo {
     /** Which surface reported it. */
@@ -525,8 +641,34 @@ interface EditorActions {
     getBlockAtCursor: () => BlockSlice | null;
     /** Insert text at the current cursor position in the active editor */
     insertAtCursor: (text: string) => void;
-    /** Replace all editor content with the given text */
+    /**
+     * Replace all editor content with the given text. Undoable as one step in
+     * Write and Source views (Document layout); elsewhere it replaces the
+     * source directly.
+     */
     replaceAll: (text: string) => void;
+    /**
+     * Apply `{ start, end, text }` edits to the full markdown source as ONE
+     * undoable step. Offsets refer to `markdownSource` (frontmatter included).
+     *
+     * Source view edits Monaco's model in place, so the cursor, scroll and undo
+     * history survive. Write view loads the result as a minimal change.
+     * Returns false, applying nothing, in Preview, outside the Document layout,
+     * when the edits overlap or fall outside the source, or when the source no
+     * longer matches `options.baseSource`.
+     */
+    applySourceEdits: (edits: readonly MarkdownSourceEdit[], options?: ApplySourceEditsOptions) => boolean;
+    /**
+     * Insert a markdown block near the cursor as ONE undoable step, leaving the
+     * selection where it is.
+     *
+     * `'afterBlock'` (default) puts it after the top-level block holding the
+     * cursor; `'sectionEnd'` puts it just before the next heading. Neither ever
+     * lands among a drawing's or layout's child headings. Pass a builder to
+     * choose the markdown once the surrounding heading depths are known.
+     * Returns false when the surface cannot be edited or the builder cancels.
+     */
+    insertBlockAfterCursor: (block: string | BlockInsertionBuilder, options?: InsertBlockOptions) => boolean;
     /**
      * Request the modal image editor open on the given relative media path.
      * The path must resolve through the active `mediaProvider`. No-op when
@@ -645,6 +787,13 @@ interface EditorContextValue extends EditorState, EditorActions {
      * for the session.
      */
     proofingIgnoreStore: ProofingIgnoreStore | null;
+    /**
+     * Imperative dictation control for the host-injected `speechInput`
+     * capability — e.g. to drive dictation from a native menu command in a
+     * component rendered inside the shell's slots. `null` when no capability
+     * was injected. See docs/speech-input.md.
+     */
+    dictation: DictationControl | null;
     /** The document's article id — part of the proofing document ref. */
     articleId: string;
     /**
@@ -760,6 +909,11 @@ interface EditorProviderProps {
     proofingGrammarEnabled?: boolean;
     /** Host-owned per-document storage for dismissed proofing findings. */
     proofingIgnoreStore?: ProofingIgnoreStore | null;
+    /**
+     * Speech-input (dictation) capability. Omit for no dictation; see
+     * `EditorShellProps.speechInput`.
+     */
+    speechInput?: SpeechInputCapability | null;
     /**
      * Async provider for sibling-document suggestions in the link dialog.
      * Omit to fall back to URL-only link insertion.
@@ -897,7 +1051,7 @@ interface ViewPreferences {
     /** Document vs. block-at-a-time layout. */
     layoutMode?: LayoutMode;
 }
-declare function EditorProvider({ initialMarkdown, initialView, articleId, colorScheme: initialColorScheme, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, mediaProvider, mediaEditRenders, imageDisplayMode, mentionProvider, proofing, proofingDefaultEnabled, proofingSpellingEnabled, proofingGrammarEnabled, proofingIgnoreStore, documentLinkProvider, fenceRenderers, onCopyCode, linkSchemes, allowRecording, allowNarrate, preserveSourceWrapping, fileName, saveCoverImageOutput, saveDashboardImageOutput, language, findMode: controlledFindMode, onFindModeChange, inlinePreview, showStatusBar, outline, blockTags, blockTagVisibility: initialBlockTagVisibility, themeInheritance, layoutMode, viewPreferences, onViewPreferencesChange, children, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
+declare function EditorProvider({ initialMarkdown, initialView, articleId, colorScheme: initialColorScheme, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, mediaProvider, mediaEditRenders, imageDisplayMode, mentionProvider, proofing, proofingDefaultEnabled, proofingSpellingEnabled, proofingGrammarEnabled, proofingIgnoreStore, speechInput, documentLinkProvider, fenceRenderers, onCopyCode, linkSchemes, allowRecording, allowNarrate, preserveSourceWrapping, fileName, saveCoverImageOutput, saveDashboardImageOutput, language, findMode: controlledFindMode, onFindModeChange, inlinePreview, showStatusBar, outline, blockTags, blockTagVisibility: initialBlockTagVisibility, themeInheritance, layoutMode, viewPreferences, onViewPreferencesChange, children, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Host-supplied context sections rendered INSIDE the Monaco (raw/code)
@@ -1350,6 +1504,17 @@ interface EditorShellProps {
      * store and Ignore still works, lasting for the session only.
      */
     proofingIgnoreStore?: ProofingIgnoreStore | null;
+    /**
+     * Dictation capability — a `SpeechInputProvider` (or factory) from
+     * `@bendyline/squisq-editor-react/speech`. Omit and the feature is off:
+     * no microphone button, no capture code loaded. With it, the toolbar
+     * gains a microphone in the Write and Source views that inserts
+     * recognized phrases as literal text at the caret; hosts can also drive
+     * it via `useEditorContext().dictation`. Instance = host-owned; factory =
+     * created on mount, disposed on unmount. Ignored when `readOnly`. Host
+     * guide: docs/speech-input.md.
+     */
+    speechInput?: SpeechInputCapability | null;
     /**
      * Optional async provider for sibling-document suggestions in the
      * link insert dialog. When supplied, the dialog gains a "Browse
@@ -1527,7 +1692,7 @@ interface EditorShellProps {
  * Complete markdown editor shell with toolbar, view switcher, and three
  * editing modes: Raw (Monaco), WYSIWYG (Tiptap), and Preview.
  */
-declare function EditorShell({ initialMarkdown, initialView, hostMode, defaultViewportPreset, articleId, basePath, onChange, onLinkClick, showCodeCopyButton, onCopyCode, colorScheme, className, height, minHeight, maxHeight, mediaProvider, mediaEditRenders, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, showFilesToggle, showFilesWhenNotEmpty, showFormattingControls, showInsertControls, allowBinaryDownloads, toolbarSlotLeft, toolbarSlotAfterActions, toolbarSlotRight, statusBarSlotRight, sidePanelSlot, reviewProviders, showPlayTab, allowPresentationWindow, allowPresentationFullscreen, allowPrint, submitOnEnter, calcEngineFactory, codeContext, fullWidth, uxFont, thinMargins, writeCanvasSettings, showStatusBar, imageDisplayMode, fileName, saveCoverImageOutput, saveDashboardImageOutput, language, findMode, onFindModeChange, mentionProvider, proofing, proofingDefaultEnabled, proofingSpellingEnabled, proofingGrammarEnabled, proofingIgnoreStore, documentLinkProvider, fenceRenderers, linkSchemes, allowRecording, allowNarrate, preserveSourceWrapping, placeholder, readOnly, imageSrc, imageAlt, imageMode, imageEditorContainer, onImageExport, inlinePreview, inlinePreviewWidth, outline, outlineWidth, blockTags, blockTagVisibility, themeInheritance, viewPreferences, onViewPreferencesChange, themeOverride, }: EditorShellProps): react_jsx_runtime.JSX.Element;
+declare function EditorShell({ initialMarkdown, initialView, hostMode, defaultViewportPreset, articleId, basePath, onChange, onLinkClick, showCodeCopyButton, onCopyCode, colorScheme, className, height, minHeight, maxHeight, mediaProvider, mediaEditRenders, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, showFilesToggle, showFilesWhenNotEmpty, showFormattingControls, showInsertControls, allowBinaryDownloads, toolbarSlotLeft, toolbarSlotAfterActions, toolbarSlotRight, statusBarSlotRight, sidePanelSlot, reviewProviders, showPlayTab, allowPresentationWindow, allowPresentationFullscreen, allowPrint, submitOnEnter, calcEngineFactory, codeContext, fullWidth, uxFont, thinMargins, writeCanvasSettings, showStatusBar, imageDisplayMode, fileName, saveCoverImageOutput, saveDashboardImageOutput, language, findMode, onFindModeChange, mentionProvider, proofing, proofingDefaultEnabled, proofingSpellingEnabled, proofingGrammarEnabled, proofingIgnoreStore, speechInput, documentLinkProvider, fenceRenderers, linkSchemes, allowRecording, allowNarrate, preserveSourceWrapping, placeholder, readOnly, imageSrc, imageAlt, imageMode, imageEditorContainer, onImageExport, inlinePreview, inlinePreviewWidth, outline, outlineWidth, blockTags, blockTagVisibility, themeInheritance, viewPreferences, onViewPreferencesChange, themeOverride, }: EditorShellProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Shared editor context menu.
@@ -1677,4 +1842,4 @@ interface PreviewPanelProps {
  */
 declare function PreviewPanel({ basePath, className, workspaceContainer, onLinkClick, showCodeCopyButton, onCopyCode, }: PreviewPanelProps): react_jsx_runtime.JSX.Element;
 
-export { sliceIndexAtOffset as $, type MentionProvider as A, type BlockRange as B, type CodeContext as C, type DashboardImageSaveOutput as D, type EditorHostMode as E, type FormulaEditRecord as F, type PreviewPanelProps as G, type RawEditorProps as H, type ImageDisplayMode as I, WysiwygEditor as J, type WysiwygEditorProps as K, type LayoutMode as L, type MentionCandidate as M, XLSX_LOCKED_REASON as N, type XlsxFormulaSession as O, PreviewPanel as P, createXlsxFormulaSession as Q, RawEditor as R, type SceneTextChannel as S, type ThemeInheritance as T, getBlockSlices as U, type ViewPreferences as V, type WriteCanvasSettings as W, type XlsxSourceMeta as X, ingestSidecarBytes as Y, lineToOffset as Z, offsetToLine as _, type CalcEngineFactory as a, spliceBlock as a0, useEditorContext as a1, useEditorContextMenuItems as a2, type CsvSourceMeta as b, type BlockSlice as c, type BlockTagVisibility as d, type CodeContextSection as e, type CoverImageSaveOutput as f, type DocumentLinkCandidate as g, type DocumentLinkProvider as h, type EditorActions as i, type EditorColorScheme as j, type EditorContextMenuContext as k, type EditorContextMenuItem as l, type EditorContextMenuItemVisibility as m, EditorContextMenuProvider as n, type EditorContextMenuProviderProps as o, type EditorContextValue as p, type EditorMode as q, EditorProvider as r, type EditorProviderProps as s, type EditorSelectionInfo as t, EditorShell as u, type EditorShellProps as v, type EditorState as w, type EditorView as x, type FormulaSessionOptions as y, type IngestedSidecar as z };
+export { XLSX_LOCKED_REASON as $, type ApplySourceEditsOptions as A, type BlockInsertionBuilder as B, type CodeContext as C, type DashboardImageSaveOutput as D, type EditorHostMode as E, type FormulaEditRecord as F, type EditorView as G, type FormulaSessionOptions as H, type ImageDisplayMode as I, type IngestedSidecar as J, type InsertBlockOptions as K, type LayoutMode as L, type MentionCandidate as M, type MentionProvider as N, type OutlineBlock as O, type OutlineInsertion as P, PreviewPanel as Q, type PreviewPanelProps as R, type SceneTextChannel as S, RawEditor as T, type RawEditorProps as U, type ThemeInheritance as V, type ViewPreferences as W, type XlsxSourceMeta as X, type WriteCanvasSettings as Y, WysiwygEditor as Z, type WysiwygEditorProps as _, type CalcEngineFactory as a, type XlsxFormulaSession as a0, applySourceEditsToText as a1, blockInsertionPoint as a2, createXlsxFormulaSession as a3, getBlockSlices as a4, headingDepthForInsertion as a5, ingestSidecarBytes as a6, joinBlockAt as a7, lineToOffset as a8, minimalReplaceEdit as a9, normalizeSourceEdits as aa, offsetToLine as ab, resolveOutlineInsertion as ac, sliceIndexAtOffset as ad, sourceOutline as ae, spliceBlock as af, useEditorContext as ag, useEditorContextMenuItems as ah, type CsvSourceMeta as b, type BlockInsertionContext as c, type BlockPlacement as d, type BlockRange as e, type BlockSlice as f, type BlockTagVisibility as g, type CodeContextSection as h, type CoverImageSaveOutput as i, type DocumentLinkCandidate as j, type DocumentLinkProvider as k, type EditorActions as l, type EditorColorScheme as m, type EditorContextMenuContext as n, type EditorContextMenuItem as o, type EditorContextMenuItemVisibility as p, EditorContextMenuProvider as q, type EditorContextMenuProviderProps as r, type EditorContextValue as s, type EditorMode as t, EditorProvider as u, type EditorProviderProps as v, type EditorSelectionInfo as w, EditorShell as x, type EditorShellProps as y, type EditorState as z };

package/dist/speech/index.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The speech-input (dictation) capability contract between an editor host and
+ * the shell.
+ *
+ * A host that can turn speech into text passes a {@link SpeechInputProvider}
+ * (or a factory) to `EditorShell`'s `speechInput` prop — the same
+ * capability-injection semantics as `proofing`: absent means the feature is
+ * off, no dictation code loads, and no microphone button renders.
+ *
+ * The editor owns everything up to the recognizer: microphone capture, phrase
+ * segmentation, WAV encoding, the toolbar button, the caret indicator and the
+ * literal-text insertion. The provider owns only recognition. Audio crosses
+ * the boundary as one self-contained mono 16-bit PCM WAV at 16 kHz per take,
+ * which every whisper.cpp build accepts and which keeps IPC payloads small.
+ * The surface is plain data end to end, so a provider can be a local engine
+ * behind IPC, a call to a service, or a test fake.
+ */
+/** Sample rate (Hz) of every WAV take handed to {@link SpeechInputProvider.transcribe}. */
+declare const SPEECH_INPUT_SAMPLE_RATE = 16000;
+/** Coarse readiness of a provider, as the editor's button presents it. */
+type SpeechInputReadinessState = 
+/** Dictation can start now. */
+'ready'
+/**
+ * The host needs a one-time setup (typically a model download) first.
+ * Clicking the microphone calls {@link SpeechInputProvider.requestSetup}
+ * instead of starting.
+ */
+ | 'download-required'
+/** Dictation can never work in this host/session. The button is hidden. */
+ | 'unavailable'
+/**
+ * The host still needs a permission (e.g. the OS microphone grant).
+ * Starting proceeds — the microphone request is what prompts for it.
+ */
+ | 'permission-required';
+interface SpeechInputReadiness {
+    readonly state: SpeechInputReadinessState;
+    /** Optional human-readable detail, shown in the button's tooltip/errors. */
+    readonly reason?: string;
+}
+interface SpeechInputTranscribeOptions {
+    /**
+     * The recent dictated text of this session (a word-aligned tail of at most
+     * 1,000 characters), for engines that accept a priming prompt — Whisper's
+     * `prompt`. Absent on the first take.
+     */
+    readonly prompt?: string;
+    /** BCP-47-ish language hint. The editor does not currently set it. */
+    readonly language?: string;
+    /**
+     * Aborted when the user cancels dictation or the editor unmounts. A
+     * provider should stop promptly; a rejection after abort is ignored.
+     */
+    readonly signal: AbortSignal;
+}
+interface SpeechInputTranscript {
+    /** Recognized text. Blank (or Whisper's `[BLANK_AUDIO]`) means silence. */
+    readonly text: string;
+}
+interface SpeechInputProvider {
+    /** Stable identifier, e.g. `whisper-local`. */
+    readonly id: string;
+    /** Human-readable name, e.g. `On-device speech recognition`. */
+    readonly label: string;
+    /**
+     * Current readiness. Called once when the editor mounts with the
+     * capability (to decide whether to render the microphone at all) and again
+     * each time the user starts dictation. Must be cheap.
+     */
+    status(): Promise<SpeechInputReadiness>;
+    /** Optional readiness push (e.g. a model finished downloading). Returns unsubscribe. */
+    onStatus?(listener: (readiness: SpeechInputReadiness) => void): () => void;
+    /** Called when the user starts dictation so the host can warm its engine; may reject. */
+    prepare?(signal: AbortSignal): Promise<void>;
+    /** Called when the user clicks the mic while readiness is 'download-required'; the host shows its own setup UI. */
+    requestSetup?(): void;
+    /** Transcribe one self-contained take: mono 16-bit PCM WAV at 16 kHz. */
+    transcribe(wav: ArrayBuffer, options: SpeechInputTranscribeOptions): Promise<SpeechInputTranscript>;
+    /** Release resources. Called by the editor only for a provider it created from a factory. */
+    dispose?(): void;
+}
+/**
+ * Deferred construction. The shell creates the provider when it mounts with
+ * the capability (it needs `status()` to decide whether to render the
+ * microphone) and disposes it on unmount or when the capability changes. A
+ * host that passes an instance owns its lifetime — which is what lets one warm
+ * engine survive shell remounts.
+ */
+type SpeechInputProviderFactory = () => SpeechInputProvider;
+/** What the `speechInput` shell prop accepts. */
+type SpeechInputCapability = SpeechInputProvider | SpeechInputProviderFactory;
+/**
+ * Resolve a capability to a provider instance. A factory is invoked (and the
+ * caller then owns — must dispose — what it returns); an instance is returned
+ * as-is and stays host-owned.
+ */
+declare function resolveSpeechInputProvider(capability: SpeechInputCapability): SpeechInputProvider;
+/**
+ * Whether a capability is a factory, i.e. whether the provider resolved from
+ * it is owned (and must be disposed) by the resolver's caller.
+ */
+declare function isSpeechInputProviderFactory(capability: SpeechInputCapability): capability is SpeechInputProviderFactory;
+/**
+ * Imperative dictation control on the editor context
+ * (`useEditorContext().dictation`), for a host component rendered inside the
+ * shell's slots — e.g. to drive dictation from a native menu command. `null`
+ * when the host injected no `speechInput` capability.
+ */
+interface DictationControl {
+    /** True from the moment dictation starts until its last take is inserted. */
+    readonly active: boolean;
+    /**
+     * True when `toggle()` would do something: the provider is not
+     * `unavailable` and a text-editing view (Write or Source) is showing.
+     */
+    readonly available: boolean;
+    /**
+     * Start dictation when idle (or ask the host to set up when readiness is
+     * `download-required`); finish and stop when listening; cancel while the
+     * microphone is still starting.
+     */
+    toggle(): void;
+}
+
+export { type DictationControl, SPEECH_INPUT_SAMPLE_RATE, type SpeechInputCapability, type SpeechInputProvider, type SpeechInputProviderFactory, type SpeechInputReadiness, type SpeechInputReadinessState, type SpeechInputTranscribeOptions, type SpeechInputTranscript, isSpeechInputProviderFactory, resolveSpeechInputProvider };

package/dist/speech/index.js

@@ -0,0 +1,10 @@
+import {
+  SPEECH_INPUT_SAMPLE_RATE,
+  isSpeechInputProviderFactory,
+  resolveSpeechInputProvider
+} from "../chunk-DNEVUOBZ.js";
+export {
+  SPEECH_INPUT_SAMPLE_RATE,
+  isSpeechInputProviderFactory,
+  resolveSpeechInputProvider
+};

package/dist/styles/index.css

@@ -8145,6 +8145,131 @@
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+.squisq-dictation {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+.squisq-dictation-button--active,
+.squisq-dictation-button--active:hover {
+  background: var(--squisq-danger-soft);
+  color: var(--squisq-danger-strong);
+}
+.squisq-dictation-button--listening {
+  width: auto;
+  gap: 6px;
+  padding: 2px 8px 0;
+}
+.squisq-dictation-button[aria-busy=true] > i {
+  animation: squisq-dictation-pulse 1.2s ease-in-out infinite;
+}
+.squisq-dictation-meter {
+  display: inline-flex;
+  align-items: center;
+  gap: 1px;
+  height: 16px;
+}
+.squisq-dictation-meter-bar {
+  width: 2px;
+  min-height: 2px;
+  border-radius: 1px;
+  background: currentColor;
+  transition: height 0.05s linear;
+}
+.squisq-dictation-error {
+  position: absolute;
+  top: calc(100% + 6px);
+  right: 0;
+  z-index: 110;
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  width: max-content;
+  max-width: min(320px, calc(100vw - 24px));
+  padding: 8px 8px 8px 12px;
+  border: 1px solid var(--squisq-danger-border);
+  border-radius: 8px;
+  background: var(--squisq-surface);
+  box-shadow: var(--squisq-shadow-md);
+  color: var(--squisq-danger-text);
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 1.4;
+  white-space: normal;
+}
+.squisq-dictation-error-text {
+  flex: 1;
+}
+.squisq-dictation-error-dismiss {
+  flex-shrink: 0;
+  padding: 0 2px;
+  border: 0;
+  background: transparent;
+  color: var(--squisq-text-muted);
+  cursor: pointer;
+  font-size: 12px;
+  line-height: 1.4;
+}
+.squisq-dictation-error-dismiss:hover {
+  color: var(--squisq-text-strong);
+}
+.squisq-dictation-interim {
+  display: inline-block;
+  margin-left: 2px;
+  padding: 0 6px;
+  border-radius: 999px;
+  background: var(--squisq-danger-soft);
+  color: var(--squisq-text-muted);
+  font-size: 0.78em;
+  font-style: italic;
+  font-weight: 400;
+  line-height: 1.5;
+  vertical-align: baseline;
+  white-space: nowrap;
+  user-select: none;
+  pointer-events: none;
+}
+.squisq-dictation-interim::before {
+  content: "";
+  display: inline-block;
+  width: 6px;
+  height: 6px;
+  margin-right: 5px;
+  border-radius: 50%;
+  background: var(--squisq-danger);
+  vertical-align: 0.1em;
+  animation: squisq-dictation-pulse 1.2s ease-in-out infinite;
+}
+.squisq-dictation-interim--source {
+  display: inline;
+  margin-left: 0.5ch;
+  padding: 0;
+  background: transparent;
+  font-size: inherit;
+  line-height: inherit;
+  opacity: 0.8;
+}
+.squisq-dictation-interim--source::before {
+  content: none;
+}
+@keyframes squisq-dictation-pulse {
+  0%, 100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.35;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .squisq-dictation-interim::before,
+  .squisq-dictation-button[aria-busy=true] > i {
+    animation: none;
+  }
+  .squisq-dictation-meter-bar {
+    transition: none;
+  }
+}
 
 /* src/styles/template-picker.css */
 .squisq-mermaid-type-menu {
@@ -8710,35 +8835,6 @@
   height: 100%;
   display: block;
 }
-.squisq-template-gallery-content-preview-fallback {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 100%;
-  height: 100%;
-}
-.squisq-template-gallery-content-preview-fallback > svg {
-  width: 100%;
-  height: 100%;
-  display: block;
-}
-.squisq-template-gallery-content-preview-warning {
-  position: absolute;
-  left: 50%;
-  top: 50%;
-  max-width: calc(100% - 16px);
-  padding: 3px 6px;
-  transform: translate(-50%, -50%);
-  border: 1px solid var(--squisq-template-gallery-preview-warning-border);
-  border-radius: 4px;
-  background: var(--squisq-template-gallery-preview-warning-bg);
-  color: var(--squisq-template-gallery-preview-warning-text);
-  font-size: 10px;
-  font-weight: 600;
-  line-height: 1.2;
-  text-align: center;
-  pointer-events: none;
-}
 .squisq-template-gallery-card-body {
   display: flex;
   flex-direction: column;
@@ -15543,6 +15639,43 @@
 .squisq-image-edit-modal__error {
   color: var(--squisq-danger);
 }
+.squisq-image-placeholder {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  box-sizing: border-box;
+  width: 260px;
+  max-width: 100%;
+  min-height: 80px;
+  padding: 16px;
+  border: 1px dashed var(--squisq-editor-control-border);
+  border-radius: 8px;
+  background: var(--squisq-editor-control-bg);
+  color: var(--squisq-text-muted);
+  font: 500 13px/1.4 var(--squisq-ux-font, system-ui, sans-serif);
+  user-select: none;
+}
+.squisq-image-placeholder svg {
+  flex-shrink: 0;
+}
+.squisq-image-placeholder[data-error=true] {
+  border-style: solid;
+}
+.squisq-image-placeholder__text {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+.squisq-image-placeholder__label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 12px;
+  font-weight: 400;
+}
+.squisq-image-placeholder--thumbnail {
+  width: 100px;
+}
 
 /* src/styles/media-edit.css */
 .squisq-media-edit-modal {

package/dist/teleprompter/index.d.ts

@@ -1,9 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Doc, Theme, MediaProvider } from '@bendyline/squisq/schemas';
 import { ContentContainer } from '@bendyline/squisq/storage';
-import { o as TeleprompterRecordingDeps, g as NarrationStageHandle, T as TeleprompterController, c as FloatingWindowHandle } from '../useNarrationStage-DopDr_P5.js';
-export { C as CanvasSink, D as DEFAULT_TELEPROMPTER_PREFS, F as FloatOpenOptions, b as FloatTier, d as FloatingWindowManager, M as MicAnalysisHandle, e as MicAnalysisStatus, N as NarrationRecorderController, f as NarrationRecorderState, h as NarrationTake, P as PrompterTransport, J as TELEPROMPTER_PREF_LIMITS, n as TeleprompterPrefs, q as UseNarrationStageOptions, s as createFloatingWindowManager, t as detectFloatTiers, K as normalizeTeleprompterPrefs, z as useFloatingWindow, B as useMicAnalysis, E as useNarrationRecorder, G as useNarrationStage, H as useTeleprompter, I as vadConfigForSensitivity } from '../useNarrationStage-DopDr_P5.js';
-import { NarrationTimingJsonV3, NarrationScript, NarrationAlignment } from '@bendyline/squisq/narration';
+import { o as TeleprompterRecordingDeps, g as NarrationStageHandle, T as TeleprompterController, c as FloatingWindowHandle } from '../useNarrationStage-vKtk6H-V.js';
+export { C as CanvasSink, D as DEFAULT_TELEPROMPTER_PREFS, F as FloatOpenOptions, b as FloatTier, d as FloatingWindowManager, M as MicAnalysisHandle, e as MicAnalysisStatus, N as NarrationRecorderController, f as NarrationRecorderState, h as NarrationTake, P as PrompterTransport, J as TELEPROMPTER_PREF_LIMITS, n as TeleprompterPrefs, q as UseNarrationStageOptions, s as createFloatingWindowManager, t as detectFloatTiers, K as normalizeTeleprompterPrefs, z as useFloatingWindow, B as useMicAnalysis, E as useNarrationRecorder, G as useNarrationStage, H as useTeleprompter, I as vadConfigForSensitivity } from '../useNarrationStage-vKtk6H-V.js';
+import { NarrationTimingJsonV3, NarrationScript, NarrationAlignment, NarrationTimingGenerator } from '@bendyline/squisq/narration';
 import { ReactNode } from 'react';
 
 interface TeleprompterViewProps {
@@ -88,10 +88,18 @@ interface NarrationSavePlanArgs {
     durationSec: number;
     audioExt: string;
     cameraExt: string | null;
-    baseWpm: number;
+    /** Speaking rate the take was paced at; recorded as `generator.baseWpm`. */
+    baseWpm?: number;
     cameraOffsetSec?: number;
     /** User-chosen filename base for the audio file; default timestamped `narration-…`. */
     audioBasename?: string;
+    /**
+     * Provenance written to the sidecar's `generator`. Defaults to the
+     * teleprompter aligner (`squisq-teleprompter` / `dsp-align`); a host that
+     * produced the timings itself names itself here — e.g.
+     * `{ name: 'my-tts', method: 'tts' }` for generated narration.
+     */
+    generator?: NarrationTimingGenerator;
 }
 interface NarrationSavePlan {
     audioRelativeName: string;
@@ -305,4 +313,4 @@ declare function prompterVarsFromTheme(theme: Theme): Record<string, string>;
 declare function ensureTeleprompterStyles(doc: Document): void;
 declare const TELEPROMPTER_CSS = "\n.squisq-teleprompter-root {\n  display: flex;\n  flex-direction: column;\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n  background: var(--squisq-bg, #f5f5f5);\n  outline: none;\n}\n.squisq-teleprompter-stage {\n  position: relative;\n  flex: 1;\n  min-height: 0;\n  display: flex;\n}\n\n.squisq-teleprompter-surface {\n  position: relative;\n  flex: 1;\n  min-height: 0;\n  overflow: hidden;\n  background: var(--squisq-prompter-bg, #101014);\n  color: var(--squisq-prompter-text, #f5f5f2);\n  font-family: var(--squisq-prompter-font, system-ui, sans-serif);\n  user-select: none;\n}\n.squisq-teleprompter-flip {\n  position: absolute;\n  inset: 0;\n}\n.squisq-teleprompter-surface--mirrored .squisq-teleprompter-flip {\n  transform: scaleX(-1);\n}\n.squisq-teleprompter-scroll {\n  position: absolute;\n  left: 0;\n  right: 0;\n  top: 0;\n  will-change: transform;\n  padding: 40vh 8% 60vh;\n  box-sizing: border-box;\n}\n.squisq-teleprompter-line-guide {\n  position: absolute;\n  left: 0;\n  right: 0;\n  pointer-events: none;\n  z-index: 2;\n}\n.squisq-teleprompter-line-guide::before,\n.squisq-teleprompter-line-guide::after {\n  content: '';\n  position: absolute;\n  top: 50%;\n  border: 9px solid transparent;\n  transform: translateY(-50%);\n}\n.squisq-teleprompter-line-guide::before {\n  left: 6px;\n  border-left-color: var(--squisq-prompter-accent, #e8b64c);\n}\n.squisq-teleprompter-line-guide::after {\n  right: 6px;\n  border-right-color: var(--squisq-prompter-accent, #e8b64c);\n}\n.squisq-teleprompter-guide-band {\n  position: absolute;\n  left: 0;\n  right: 0;\n  background: color-mix(in srgb, var(--squisq-prompter-accent, #e8b64c) 9%, transparent);\n  pointer-events: none;\n  z-index: 1;\n}\n\n.squisq-teleprompter-block-marker {\n  display: block;\n  margin: 1.1em 0 0.35em;\n  font-size: 0.38em;\n  font-weight: 600;\n  letter-spacing: 0.14em;\n  text-transform: uppercase;\n  color: var(--squisq-prompter-muted, #9a9aa0);\n  border-top: 1px solid color-mix(in srgb, var(--squisq-prompter-muted, #9a9aa0) 35%, transparent);\n  padding-top: 0.6em;\n}\n.squisq-teleprompter-para {\n  margin: 0 0 0.55em;\n  line-height: 1.4;\n  font-weight: 500;\n}\n.squisq-teleprompter-word {\n  opacity: 0.45;\n  transition: color 0.1s linear, opacity 0.1s linear;\n}\n.squisq-teleprompter-word--read {\n  opacity: 0.9;\n}\n.squisq-teleprompter-word--active {\n  opacity: 1;\n  font-weight: 800;\n  color: var(--squisq-prompter-accent, #e8b64c);\n}\n\n.squisq-teleprompter-countdown {\n  position: absolute;\n  inset: 0;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  z-index: 3;\n  background: color-mix(in srgb, var(--squisq-prompter-bg, #101014) 72%, transparent);\n}\n.squisq-teleprompter-countdown-digit {\n  font-size: 18vmin;\n  font-weight: 800;\n  color: var(--squisq-prompter-accent, #e8b64c);\n  animation: squisq-prompter-pulse 1s ease-in-out infinite;\n}\n.squisq-teleprompter-recdot {\n  position: absolute;\n  top: 14px;\n  right: 16px;\n  z-index: 4;\n  width: 14px;\n  height: 14px;\n  border-radius: 50%;\n  background: #e5484d;\n  box-shadow: 0 0 0 3px color-mix(in srgb, #e5484d 30%, transparent);\n  animation: squisq-prompter-pulse 1.4s ease-in-out infinite;\n}\n/* Counter-flip overlays so they stay readable in mirror mode. */\n.squisq-teleprompter-surface--mirrored .squisq-teleprompter-countdown,\n.squisq-teleprompter-surface--mirrored .squisq-teleprompter-recdot {\n  transform: scaleX(-1);\n}\n\n.squisq-teleprompter-selfview {\n  position: absolute;\n  right: 14px;\n  bottom: 14px;\n  width: 160px;\n  border-radius: 8px;\n  border: 2px solid color-mix(in srgb, #e5484d 60%, transparent);\n  z-index: 5;\n  background: #000;\n}\n\n.squisq-teleprompter-review {\n  display: flex;\n  align-items: center;\n  flex-wrap: wrap;\n  gap: 10px;\n  padding: 8px 12px;\n  border-top: 1px solid var(--squisq-border, #e5e7eb);\n  background: var(--squisq-surface, var(--squisq-bg, #fff));\n  color: var(--squisq-text, #111827);\n  font-size: 12.5px;\n}\n.squisq-teleprompter-review audio {\n  height: 28px;\n  max-width: 260px;\n}\n.squisq-teleprompter-review button {\n  font: inherit;\n  color: inherit;\n  background: var(--squisq-input-bg, #fff);\n  border: 1px solid var(--squisq-border, #d1d5db);\n  border-radius: 6px;\n  padding: 4px 10px;\n  cursor: pointer;\n}\n\n.squisq-teleprompter-float-note {\n  flex: 1;\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  justify-content: center;\n  gap: 12px;\n  color: var(--squisq-text-muted, #4b5563);\n  font-size: 14px;\n}\n\n.squisq-teleprompter-controls {\n  display: flex;\n  align-items: center;\n  flex-wrap: wrap;\n  gap: 10px;\n  padding: 8px 12px;\n  border-top: 1px solid var(--squisq-border, #e5e7eb);\n  background: var(--squisq-surface, var(--squisq-bg, #fff));\n  color: var(--squisq-text, #111827);\n  font-size: 12.5px;\n}\n.squisq-teleprompter-controls .squisq-teleprompter-group {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  white-space: nowrap;\n}\n.squisq-teleprompter-controls button {\n  font: inherit;\n  color: inherit;\n  background: var(--squisq-input-bg, #fff);\n  border: 1px solid var(--squisq-border, #d1d5db);\n  border-radius: 6px;\n  padding: 4px 10px;\n  cursor: pointer;\n}\n.squisq-teleprompter-controls button:hover {\n  background: var(--squisq-surface-hover, #f3f4f6);\n}\n.squisq-teleprompter-controls button[aria-pressed='true'] {\n  background: var(--squisq-text, #111827);\n  color: var(--squisq-bg, #fff);\n  border-color: var(--squisq-text, #111827);\n}\n.squisq-teleprompter-controls select,\n.squisq-teleprompter-controls input[type='range'] {\n  font: inherit;\n  color: inherit;\n  background: var(--squisq-input-bg, #fff);\n  border: 1px solid var(--squisq-border, #d1d5db);\n  border-radius: 6px;\n  max-width: 170px;\n}\n.squisq-teleprompter-controls input[type='range'] {\n  border: none;\n  background: transparent;\n  width: 110px;\n}\n.squisq-teleprompter-meter {\n  position: relative;\n  width: 64px;\n  height: 8px;\n  border-radius: 4px;\n  overflow: hidden;\n  background: var(--squisq-border, #e5e7eb);\n}\n.squisq-teleprompter-meter-fill {\n  position: absolute;\n  inset: 0 auto 0 0;\n  background: #9ca3af;\n  transition: width 0.08s linear;\n}\n.squisq-teleprompter-meter--voice .squisq-teleprompter-meter-fill {\n  background: #30a46c;\n}\n\n@keyframes squisq-prompter-pulse {\n  0%, 100% { opacity: 1; }\n  50% { opacity: 0.45; }\n}\n@media (prefers-reduced-motion: reduce) {\n  .squisq-teleprompter-countdown-digit,\n  .squisq-teleprompter-recdot {\n    animation: none;\n  }\n  .squisq-teleprompter-word {\n    transition: none;\n  }\n}\n";
 
-export { EYE_LINE_FRACTION, FloatingWindowHandle, type NarrationSavePlan, type NarrationSaveResult, NarrationStage, NarrationStageHandle, type NarrationStageProps, PCM_WORKLET_NAME, PCM_WORKLET_SOURCE, TELEPROMPTER_CSS, TeleprompterController, TeleprompterControls, type TeleprompterControlsProps, TeleprompterRecordingDeps, TeleprompterSurface, type TeleprompterSurfaceProps, TeleprompterView, type TeleprompterViewProps, type TokenLineMap, buildNarrationSavePlan, cameraVideoLine, ensureTeleprompterStyles, executeNarrationSave, insertNarrationPreamble, measureTokenLines, narrationAnnotationLine, prompterVarsFromTheme, registerPcmWorklet, stepScroll, targetOffsetFor };
+export { EYE_LINE_FRACTION, type ExecuteNarrationSaveDeps, FloatingWindowHandle, type NarrationSavePlan, type NarrationSavePlanArgs, type NarrationSaveProgress, type NarrationSaveResult, NarrationStage, NarrationStageHandle, type NarrationStageProps, PCM_WORKLET_NAME, PCM_WORKLET_SOURCE, TELEPROMPTER_CSS, TeleprompterController, TeleprompterControls, type TeleprompterControlsProps, TeleprompterRecordingDeps, TeleprompterSurface, type TeleprompterSurfaceProps, TeleprompterView, type TeleprompterViewProps, type TokenLineMap, buildNarrationSavePlan, cameraVideoLine, ensureTeleprompterStyles, executeNarrationSave, insertNarrationPreamble, measureTokenLines, narrationAnnotationLine, prompterVarsFromTheme, registerPcmWorklet, stepScroll, targetOffsetFor };