@bendyline/squisq-editor-react 1.5.0 → 1.5.2

package/dist/index.d.ts

@@ -1,97 +1,1998 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, CSSProperties, RefObject } from 'react';
+import { Doc, MediaProvider, Theme, ViewportPreset, ViewportConfig, SurfaceScheme, ImageEditDoc, ImageEditLayer } from '@bendyline/squisq/schemas';
+import { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { ContentContainer } from '@bendyline/squisq/storage';
+import { DocumentVersionManager, SaveVersionOptions, SaveVersionResult, PrunePolicy } from '@bendyline/squisq/versions';
+import * as _tiptap_core from '@tiptap/core';
+import { Editor } from '@tiptap/core';
+import { editor } from 'monaco-editor';
+import { IconFamily } from '@bendyline/squisq/icons';
+import { DisplayMode, CaptionStyle } from '@bendyline/squisq-react';
+import * as _tiptap_extension_heading from '@tiptap/extension-heading';
+import { SquisqAnnotatedSchema, JsonFormValidator, JsonFormValidationError } from '@bendyline/squisq/jsonForm';
+import { ImageEditExportFormat, ImageEditVersionManager } from '@bendyline/squisq/imageEdit';
+
+/** Monaco standalone code editor instance type */
+type MonacoEditor = editor.IStandaloneCodeEditor;
 /**
- * @bendyline/squisq-editor-react
+ * One candidate returned by a {@link MentionProvider}. Shown in the editor's
+ * `@` popover. `id` is the stable identifier (serialized into the mention
+ * wire format); `label` is what the reader sees; `scheme` is the namespace
+ * (e.g. `'user'`, `'issue'`) written into the markdown as `@[label](scheme:id)`;
+ * `description` and `group` are optional hints for richer suggestion UIs.
  *
- * React component library for editing markdown content with three views:
- * - Raw (Monaco) — Full markdown source editing
- * - WYSIWYG (Tiptap) — Rich text editing
- * - Preview — Rendered block preview
+ * Different candidates in the same result set may carry different schemes —
+ * a provider that returns both users and issues, for example, tags each
+ * candidate with its own namespace and the editor emits mentions accordingly.
+ */
+interface MentionCandidate {
+    id: string;
+    label: string;
+    scheme: string;
+    description?: string;
+    group?: string;
+}
+/**
+ * Looks up mention candidates matching a query. Called as the user types
+ * after `@`. The provider is free to do server-side or client-side filtering;
+ * the editor only cares that candidates come back in relevance order.
+ */
+type MentionProvider = (query: string) => Promise<MentionCandidate[]>;
+/**
+ * A document that the link dialog's "Browse documents" picker can offer.
+ * `path` is what lands in the markdown URL (typically relative to the
+ * current document so `home.md → resume.md` round-trips through file-
+ * system serializers). `label` is the human name shown in the list.
+ * `description` is an optional secondary line (e.g. workspace folder,
+ * last-modified date).
+ */
+interface DocumentLinkCandidate {
+    path: string;
+    label: string;
+    description?: string;
+}
+/**
+ * Resolves sibling / workspace document candidates for the link dialog.
+ * The editor itself has no notion of "neighbors" — hosts that organize
+ * docs in a workspace (e.g. docblocks) implement this to power the
+ * dialog's document picker. Pass `''` as the query for an initial list
+ * (the dialog calls it once on open); subsequent calls narrow by user
+ * input.
+ */
+type DocumentLinkProvider = (query: string) => Promise<DocumentLinkCandidate[]>;
+type EditorView = 'raw' | 'wysiwyg' | 'preview';
+type EditorTheme = 'light' | 'dark';
+/**
+ * How much of the active Squisq theme the WYSIWYG editing surface
+ * mirrors. `'fonts'` is the historical default — body and heading
+ * fonts only. `'fonts-colors'` also borrows the theme canvas / text
+ * colors. `'none'` opts out completely.
+ */
+type ThemeInheritance = 'none' | 'fonts' | 'fonts-colors';
+/**
+ * Editor operating mode. `markdown` is the full experience (WYSIWYG +
+ * Preview tabs, formatting toolbar). `code` is a Monaco-only view used
+ * when the content represents a non-markdown file like `foo.ts`.
+ */
+type EditorMode = 'markdown' | 'code' | 'image';
+interface EditorState {
+    /** Raw markdown source string */
+    markdownSource: string;
+    /** Parsed markdown document (JSON DOM) */
+    markdownDoc: MarkdownDocument | null;
+    /** Generated Doc (block hierarchy) */
+    doc: Doc | null;
+    /** Currently active editor view */
+    activeView: EditorView;
+    /** Parse error, if any */
+    parseError: string | null;
+    /** Whether a parse is pending */
+    isParsing: boolean;
+    /** Current color theme */
+    theme: EditorTheme;
+    /** Operating mode — 'markdown' for the full shell, 'code' for Monaco-only. */
+    editorMode: EditorMode;
+    /** Monaco language ID for the Raw editor. */
+    language: string;
+    /**
+     * Whether the inline preview gutter (per-block card previews next to the
+     * WYSIWYG surface) is currently visible. Initialized from the EditorShell
+     * `inlinePreview` prop; the View menu in the toolbar can toggle it at
+     * runtime.
+     */
+    inlinePreviewVisible: boolean;
+    /**
+     * Whether the bottom status bar is currently visible. Initialized from
+     * the EditorShell `showStatusBar` prop (default true); the View menu in
+     * the toolbar can toggle it at runtime.
+     */
+    statusBarVisible: boolean;
+    /**
+     * Whether the left-side outline pane is currently visible. Initialized
+     * from the EditorShell `outline` prop (default false); the View menu in
+     * the toolbar can toggle it at runtime.
+     */
+    outlineVisible: boolean;
+    /**
+     * Whether inline block-template tags (the chip next to each templated
+     * heading in the WYSIWYG view, plus the subtle affordance chip on plain
+     * headings) are currently visible. Initialized from the EditorShell
+     * `blockTags` prop (default true); the View menu in the toolbar can
+     * toggle it at runtime.
+     */
+    blockTagsVisible: boolean;
+    /**
+     * How much of the active Squisq theme the WYSIWYG editing surface should
+     * inherit. `'none'` shows the default editor styling, `'fonts'` (the
+     * default) matches body and heading fonts only, and `'fonts-colors'`
+     * also borrows the theme's canvas / text colors so authors get a
+     * closer preview while editing.
+     */
+    themeInheritance: ThemeInheritance;
+    /**
+     * Relative path of an image the user requested to edit, or `null` when
+     * no editor is open. Surfaced by `<ImageNodeView>`'s hover affordance
+     * and consumed by `<EditorShell>` to render the modal `<ImageEditor>`.
+     */
+    imageEditTarget: string | null;
+    /**
+     * Monotonic counter bumped whenever a managed media asset is rewritten
+     * (e.g. after the image-editor modal saves back). Image render paths
+     * that cache resolved blob URLs should include this in their effect
+     * deps so the new bytes get picked up.
+     */
+    mediaRevision: number;
+    /**
+     * Whether the in-editor media recorder should be available. Defaults
+     * to true when a `mediaProvider` is wired; hosts that explicitly
+     * don't want the affordance (e.g. read-only embeds, surfaces where
+     * camera/screen prompts would be jarring) can pass `false` on the
+     * shell.
+     */
+    allowRecording: boolean;
+}
+interface EditorActions {
+    /** Set markdown source and trigger re-parse */
+    setMarkdownSource: (source: string) => void;
+    /** Set markdown from a MarkdownDocument (e.g. from WYSIWYG) */
+    setMarkdownDoc: (doc: MarkdownDocument) => void;
+    /** Switch the active view */
+    setActiveView: (view: EditorView) => void;
+    /** Register / unregister the Tiptap editor instance (called by WysiwygEditor) */
+    setTiptapEditor: (editor: Editor | null) => void;
+    /** Register / unregister the Monaco editor instance (called by RawEditor) */
+    setMonacoEditor: (editor: MonacoEditor | null) => void;
+    /** Set the color theme */
+    setTheme: (theme: EditorTheme) => void;
+    /** Show or hide the inline preview gutter at runtime (driven by the View menu). */
+    setInlinePreviewVisible: (visible: boolean) => void;
+    /** Show or hide the bottom status bar at runtime (driven by the View menu). */
+    setStatusBarVisible: (visible: boolean) => void;
+    /** Show or hide the left-side outline pane at runtime (driven by the View menu). */
+    setOutlineVisible: (visible: boolean) => void;
+    /** Show or hide inline block-template tags at runtime (driven by the View menu). */
+    setBlockTagsVisible: (visible: boolean) => void;
+    /** Change how much of the active Squisq theme the WYSIWYG surface mirrors. */
+    setThemeInheritance: (mode: ThemeInheritance) => void;
+    /** Insert text at the current cursor position in the active editor */
+    insertAtCursor: (text: string) => void;
+    /** Replace all editor content with the given text */
+    replaceAll: (text: string) => void;
+    /**
+     * Request the modal image editor open on the given relative media path.
+     * The path must resolve through the active `mediaProvider`. No-op when
+     * no provider is wired — callers should hide the affordance in that
+     * case.
+     */
+    openImageEdit: (relativePath: string) => void;
+    /** Close the image editor modal without saving. */
+    closeImageEdit: () => void;
+    /**
+     * Bump `mediaRevision`. Called after the image editor writes back to
+     * the original media path so dependent `<img>` nodes re-resolve their
+     * blob URL.
+     */
+    bumpMediaRevision: () => void;
+}
+interface EditorContextValue extends EditorState, EditorActions {
+    /** The live Tiptap editor instance (null when WYSIWYG is not mounted) */
+    tiptapEditor: Editor | null;
+    /** The live Monaco editor instance (null when Raw is not mounted) */
+    monacoEditor: MonacoEditor | null;
+    /**
+     * Workspace-scoped `ContentContainer` for this document — the folder
+     * holding the doc, its `_files/` sidecar, sibling documents, and any
+     * version snapshots. Drives audio mapping, version history, and
+     * sibling-doc reads for the recursive HTML export.
+     */
+    workspaceContainer: ContentContainer | null;
+    /**
+     * Version manager — non-null only when the host opted into versioning
+     * (`allowVersioning` + a `workspaceContainer`). Components can call
+     * `saveVersion` directly, or render the version-history panel which
+     * reads it from here.
+     */
+    versioning: DocumentVersionManager | null;
+    /**
+     * Stamp a new snapshot of the current document. No-op (returns
+     * `unchanged`) when content matches the latest version. Always safe
+     * to call — when versioning is disabled, returns `no-document`
+     * without writing.
+     */
+    saveVersion: (options?: SaveVersionOptions) => Promise<SaveVersionResult>;
+    /** MediaProvider for resolving image URLs in the WYSIWYG editor */
+    mediaProvider: MediaProvider | null;
+    /**
+     * How pasted/inserted images should be displayed in the WYSIWYG view.
+     * `'inline'` (default) lets them flow at natural size up to the editor
+     * width; `'thumbnail'` constrains them to a 100×100 box so chat
+     * composers and other dense surfaces don't get dominated by a single
+     * pasted screenshot. The stored image bytes are unchanged — this is a
+     * pure render-time decision.
+     */
+    imageDisplayMode: ImageDisplayMode;
+    /**
+     * Optional provider for `@`-mention suggestions. When set, both the
+     * WYSIWYG (Tiptap) and Raw (Monaco) editors show a mention popover as
+     * the user types `@<query>`. When unset, `@` is just a literal character.
+     */
+    mentionProvider: MentionProvider | null;
+    /**
+     * Optional provider for sibling-document suggestions in the link
+     * dialog. When set, the dialog shows a "Browse documents" picker that
+     * lets authors search neighbor docs by name and insert a relative-
+     * path link. When unset, the dialog falls back to URL-only.
+     */
+    documentLinkProvider: DocumentLinkProvider | null;
+}
+type ImageDisplayMode = 'inline' | 'thumbnail';
+/**
+ * Hook to access the editor context. Must be used within an EditorProvider.
+ */
+declare function useEditorContext(): EditorContextValue;
+interface EditorProviderProps {
+    /** Initial markdown content */
+    initialMarkdown?: string;
+    /** Initial active view */
+    initialView?: EditorView;
+    /** Article ID used when generating the Doc */
+    articleId?: string;
+    /** Color theme */
+    theme?: EditorTheme;
+    /**
+     * Workspace-scoped `ContentContainer` for this document — the folder
+     * holding the doc, its `_files/` sidecar, sibling documents, and any
+     * version snapshots. Required for `allowVersioning` to take effect.
+     */
+    workspaceContainer?: ContentContainer | null;
+    /**
+     * Enable version history. Snapshots are stored at
+     * `.versions/<basename>.<timestamp>.md` inside `workspaceContainer`.
+     * Auto-save fires after `versioningAutoSaveIdleMs` of idle; hosts can
+     * also call `saveVersion()` from the context. Without a
+     * `workspaceContainer`, this prop is ignored (and a `console.warn` is
+     * emitted).
+     */
+    allowVersioning?: boolean;
+    /** Override the basename used in version filenames. Defaults to the
+     * basename of the container's primary document path. */
+    versionBasename?: string;
+    /**
+     * Prune policy applied after each successful auto-save. Defaults to
+     * keeping the last 50 snapshots so the count doesn't grow unbounded.
+     */
+    versioningPrunePolicy?: PrunePolicy;
+    /**
+     * Idle delay (ms) before auto-saving a version. `0` disables auto-save
+     * entirely (versions are saved only via host-driven `saveVersion`
+     * calls). Default: 5000.
+     */
+    versioningAutoSaveIdleMs?: number;
+    /**
+     * Notified after each `saveVersion` attempt — both successful saves
+     * (`reason: 'saved'`) and skips (`'unchanged'`, `'no-document'`,
+     * `'empty'`). Useful for hosts that want a "Last saved" indicator.
+     */
+    onSaveVersion?: (result: SaveVersionResult) => void;
+    /** MediaProvider for resolving image URLs */
+    mediaProvider?: MediaProvider | null;
+    /** Display mode for images in the WYSIWYG view. Defaults to `'inline'`. */
+    imageDisplayMode?: ImageDisplayMode;
+    /**
+     * Async provider for `@`-mention suggestions. Omit to disable mentions
+     * entirely — typing `@` becomes just a literal character again.
+     */
+    mentionProvider?: MentionProvider | null;
+    /**
+     * Async provider for sibling-document suggestions in the link dialog.
+     * Omit to fall back to URL-only link insertion.
+     */
+    documentLinkProvider?: DocumentLinkProvider | null;
+    /**
+     * Whether the in-editor media recorder is available in the toolbar.
+     * Defaults to true. Set to false to suppress the recorder affordance
+     * even when a `mediaProvider` is wired (e.g. read-only embeds,
+     * surfaces where camera/screen prompts would be jarring).
+     */
+    allowRecording?: boolean;
+    /**
+     * File name (e.g. `foo.ts`) or bare extension — used to pick a Monaco
+     * language and decide between markdown vs. code mode.
+     */
+    fileName?: string;
+    /** Explicit Monaco language ID — wins over the fileName-derived one. */
+    language?: string;
+    /**
+     * Initial visibility of the inline preview gutter. Defaults to false.
+     * The toolbar's View menu can toggle it at runtime.
+     */
+    inlinePreview?: boolean;
+    /**
+     * Initial visibility of the bottom status bar. Defaults to true.
+     * The toolbar's View menu can toggle it at runtime.
+     */
+    showStatusBar?: boolean;
+    /**
+     * Initial visibility of the left-side outline pane. Defaults to false.
+     * The toolbar's View menu can toggle it at runtime.
+     */
+    outline?: boolean;
+    /**
+     * Initial visibility of inline block-template tags on headings.
+     * Defaults to true. The toolbar's View menu can toggle it at runtime.
+     */
+    blockTags?: boolean;
+    /**
+     * Initial value for how much of the active Squisq theme the WYSIWYG
+     * editing surface should mirror. Defaults to `'fonts'` — the
+     * historical behavior of inheriting body / heading fonts only. The
+     * toolbar's View menu can change it at runtime.
+     */
+    themeInheritance?: ThemeInheritance;
+    /**
+     * Bundled view preferences — a serializable JSON blob covering all
+     * runtime-toggleable view options. When provided, individual values
+     * here override the matching individual props (`inlinePreview`,
+     * `showStatusBar`, `outline`). Hosts wiring this up typically load
+     * the blob from their own preferences storage and pair it with
+     * {@link onViewPreferencesChange}.
+     */
+    viewPreferences?: ViewPreferences;
+    /**
+     * Notified after each user-driven toggle in the View menu (or any
+     * programmatic call to the corresponding context setters). The
+     * argument is a full snapshot — hosts can persist it as-is.
+     * Not called when {@link viewPreferences} is changed externally.
+     */
+    onViewPreferencesChange?: (prefs: ViewPreferences) => void;
+    children: ReactNode;
+}
+/**
+ * Serializable bundle of all runtime-toggleable view preferences for
+ * the editor shell. Hosts can persist this verbatim (e.g. to
+ * localStorage) and pass it back via {@link EditorProviderProps.viewPreferences}
+ * to restore the user's last view configuration.
+ */
+interface ViewPreferences {
+    /** Whether the left-side outline pane is visible. */
+    outline?: boolean;
+    /** Whether the inline preview gutter (per-block cards) is visible. */
+    inlinePreview?: boolean;
+    /** Whether the bottom status bar is visible. */
+    showStatusBar?: boolean;
+    /** Whether inline block-template tags on headings are visible. */
+    blockTags?: boolean;
+    /** How much of the active Squisq theme the WYSIWYG surface mirrors. */
+    themeInheritance?: ThemeInheritance;
+}
+declare function EditorProvider({ initialMarkdown, initialView, articleId, theme: initialTheme, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, mediaProvider, imageDisplayMode, mentionProvider, documentLinkProvider, allowRecording, fileName, language, inlinePreview, showStatusBar, outline, blockTags, themeInheritance, viewPreferences, onViewPreferencesChange, children, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
+
+interface EditorShellProps {
+    /** Initial markdown content */
+    initialMarkdown?: string;
+    /** Initial active view */
+    /** Initial active view (default: 'wysiwyg') */
+    initialView?: EditorView;
+    /** Article ID for Doc generation */
+    articleId?: string;
+    /** Base path for media URLs in preview */
+    basePath?: string;
+    /** Called when markdown source changes */
+    onChange?: (source: string) => void;
+    /** Color theme: 'light' or 'dark' (default: 'light') */
+    theme?: 'light' | 'dark';
+    /** Additional class name */
+    className?: string;
+    /** CSS height for the shell container (default: '100vh') */
+    height?: string;
+    /**
+     * Minimum CSS height for the shell. When either `minHeight` or
+     * `maxHeight` is set, the shell switches to **auto-grow mode**:
+     * `height` is ignored, the root becomes `height: auto` between the
+     * bounds, and the content area scrolls internally when content
+     * exceeds `maxHeight`. Useful for chat composers that should grow
+     * with content up to some cap.
+     */
+    minHeight?: string;
+    /** See `minHeight`. Upper bound of the auto-grow range. */
+    maxHeight?: string;
+    /** Optional MediaProvider for the Files panel. When set (even to null), a Files toggle appears in the toolbar. */
+    mediaProvider?: MediaProvider | null;
+    /**
+     * The workspace-scoped `ContentContainer` for this document — the
+     * folder that contains the doc, its `_files/` sidecar, sibling
+     * documents, and any version snapshots. Used for:
+     *  - audio mapping (MP3 discovery + timing.json reading);
+     *  - version history snapshots (when `allowVersioning` is true);
+     *  - reading sibling `.md` files for the recursive HTML export;
+     *  - resolving per-document scoped views (e.g. the image-edit
+     *    sidecar derived via `scopeContainer`).
+     * Doc-scoped concerns (per-doc media URLs, per-doc asset writes)
+     * flow through `mediaProvider` instead — typically derived from
+     * this container via `createMediaProviderFromContainer`.
+     */
+    workspaceContainer?: ContentContainer | null;
+    /**
+     * @deprecated Renamed to `workspaceContainer` to make the workspace-
+     * vs. doc-scoped distinction explicit. Still accepted as a fallback
+     * for now; remove in the next breaking release.
+     */
+    container?: ContentContainer | null;
+    /**
+     * Enable version history. Snapshots are stored at
+     * `.versions/<basename>.<timestamp>.md` inside the same
+     * `workspaceContainer`, so they ride along with the document when
+     * the host serializes.
+     *
+     * Snapshots fire on idle (controlled by `versioningAutoSaveIdleMs`)
+     * and can also be triggered host-side via the manager exposed in the
+     * context (`useEditorContext().versioning`). Has no effect without a
+     * `workspaceContainer` — a `console.warn` flags the misconfiguration
+     * in dev.
+     */
+    allowVersioning?: boolean;
+    /**
+     * Override the document basename used in version filenames. Defaults
+     * to the basename of the container's primary document path.
+     */
+    versionBasename?: string;
+    /**
+     * Prune policy applied after each successful save. Defaults to
+     * `{ type: 'keep-last-n', n: 50 }` so the snapshot count stays bounded.
+     */
+    versioningPrunePolicy?: PrunePolicy;
+    /**
+     * Idle delay (ms) before the editor auto-saves a version. `0` disables
+     * auto-save entirely (snapshots are then only saved when the host
+     * calls `versioning.saveVersion()` from the context). Default: 5000.
+     */
+    versioningAutoSaveIdleMs?: number;
+    /**
+     * Notified after each `saveVersion` attempt. Fires for both successful
+     * saves (`reason: 'saved'`) and skips (`'unchanged'`, `'no-document'`,
+     * `'empty'`). Useful for hosts that want a "Last saved" indicator.
+     */
+    onSaveVersion?: (result: SaveVersionResult) => void;
+    /** Show the Files toggle in the toolbar. Defaults to true when mediaProvider is passed. */
+    showFilesToggle?: boolean;
+    /** Content rendered at the left edge of the toolbar, before the view tabs. */
+    toolbarSlotLeft?: ReactNode;
+    /** Content rendered after the formatting controls (in the middle area of the toolbar). */
+    toolbarSlotAfterActions?: ReactNode;
+    /** Content rendered at the rightmost end of the toolbar, after all other elements. */
+    toolbarSlotRight?: ReactNode;
+    /**
+     * Whether to show the "Play" (preview) tab in the toolbar. When false, the
+     * tab and its preview panel are hidden, and ⌘3 becomes a no-op. Use this
+     * when embedding the editor somewhere the slideshow preview doesn't make
+     * sense (e.g. editing free-form prompt documents). Defaults to true.
+     */
+    showPlayTab?: boolean;
+    /**
+     * Optional "submit on Enter" callback. When provided, a plain Enter
+     * keypress fires this callback instead of inserting a newline, and
+     * Cmd/Ctrl+Enter inserts a newline instead. Matches chat-composer UX
+     * (Slack, Discord). When omitted, the editor behaves normally.
+     */
+    submitOnEnter?: () => void;
+    /**
+     * Let the WYSIWYG editing surface fill its container instead of rendering
+     * as a centered 800px "page" column. Useful when embedding in chat
+     * composers, side panels, or any layout where the page metaphor doesn't
+     * fit. Defaults to false (page mode).
+     */
+    fullWidth?: boolean;
+    /**
+     * Font-family stack applied to the editor **chrome** — toolbar buttons,
+     * tabs, status bar, and control surfaces. The actual editing areas
+     * (Tiptap / Monaco) keep their own fonts so document editing isn't
+     * affected. Use this when the editor is embedded in a larger product
+     * that has its own UX type system and you want the controls to blend in.
+     *
+     * @example
+     * ```tsx
+     * <EditorShell uxFont="'Hanken Grotesk', system-ui, sans-serif" ... />
+     * ```
+     */
+    uxFont?: string;
+    /**
+     * Drop the editor's generous page-style padding in favor of a tight
+     * layout that hugs its container. The default WYSIWYG surface uses
+     * 16×24px padding suitable for editing long-form documents; chat
+     * composers want much less. Applies to the editing area only — the
+     * toolbar, tabs, and status bar keep their normal sizing.
+     */
+    thinMargins?: boolean;
+    /**
+     * Render the bottom status bar (word / character / line / block counts
+     * and parse-state indicator). Defaults to `true`. Set to `false` in
+     * embedded surfaces — chat composers and other short-form inputs —
+     * where the stats are noise.
+     */
+    showStatusBar?: boolean;
+    /**
+     * How images should be displayed in the WYSIWYG view. `'inline'`
+     * (default) flows them at natural size up to the container width;
+     * `'thumbnail'` constrains each image to a 100×100 box with
+     * aspect-preserving containment — useful for chat composers and other
+     * dense surfaces where a full-resolution paste would dominate the
+     * layout. Storage bytes are unchanged either way.
+     */
+    imageDisplayMode?: ImageDisplayMode;
+    /**
+     * File name (e.g. `foo.ts`) or bare extension that the content
+     * represents. When set to a non-markdown/text extension, the shell
+     * enters **code mode**: Monaco picks the right language based on the
+     * extension, the WYSIWYG and Preview tabs disappear, and the toolbar
+     * drops its markdown-specific formatting buttons. Markdown-ish
+     * extensions (`.md`, `.markdown`, `.mdown`, `.txt`) keep the full
+     * experience. Omit to get today's markdown behavior unchanged.
+     */
+    fileName?: string;
+    /**
+     * Explicit Monaco language ID override (e.g. `'typescript'`,
+     * `'python'`, `'json'`). Wins over the language derived from
+     * `fileName`. Anything other than `'markdown'` or `'plaintext'`
+     * switches the shell into code mode.
+     */
+    language?: string;
+    /**
+     * Optional async provider for `@`-mention suggestions. When supplied,
+     * typing `@` inside the editor opens a popover of candidates; selecting
+     * one inserts a `@[Label](scheme:id)` mention token. Used by chat
+     * composers and any other surface that wants to address named entities
+     * inline. Omit to disable mentions entirely.
+     */
+    mentionProvider?: MentionProvider | null;
+    /**
+     * Optional async provider for sibling-document suggestions in the
+     * link insert dialog. When supplied, the dialog gains a "Browse
+     * documents" picker so authors can pick a neighbor `.md` by name and
+     * insert a relative-path link without typing the URL by hand. Hosts
+     * that organize docs in a workspace (file-system, IndexedDB slot,
+     * remote API, …) implement this; the editor stays agnostic.
+     */
+    documentLinkProvider?: DocumentLinkProvider | null;
+    /**
+     * Whether the in-editor media recorder is surfaced in the toolbar.
+     * Defaults to true — when a `mediaProvider` is wired, a record
+     * button appears next to the version history. Pass `false` to
+     * suppress it (read-only embeds, surfaces where camera/screen
+     * permission prompts would be jarring). Without a `mediaProvider`,
+     * the button is hidden regardless of this prop.
+     */
+    allowRecording?: boolean;
+    /**
+     * Placeholder text shown in the WYSIWYG editor while the document is
+     * empty. When omitted, the editor rotates through its own generic
+     * "start typing…" prompts; pass a value here to override with copy
+     * that fits the embedding surface (e.g. a chat composer knows who
+     * the message is going to and can say so).
+     */
+    placeholder?: string;
+    /**
+     * When true, both editing surfaces become non-editable: Monaco runs in
+     * `readOnly` mode and Tiptap is set to `editable: false`. The toolbar
+     * still renders — hide it from the host side if you want a pure preview.
+     * Useful for reference panels that show file content without inviting
+     * accidental edits.
+     */
+    readOnly?: boolean;
+    /**
+     * Image source URL used when the resolved file mode is `image` (PNG,
+     * JPEG, GIF, WebP, BMP, ICO, AVIF). When this prop is set, the shell
+     * replaces its text-editing surfaces with a dedicated `ImageViewer`.
+     *
+     * Lifecycle of the URL is the caller's responsibility — when fed a
+     * `blob:` URL, the host should `URL.revokeObjectURL` on unmount or
+     * src change.
+     */
+    imageSrc?: string;
+    /** Alt text passed through to the underlying ImageViewer. */
+    imageAlt?: string;
+    /**
+     * Whether the image surface should render as a read-only viewer
+     * (`'view'`, default) or as the editable {@link ImageEditor}
+     * (`'edit'`). Editing requires {@link EditorShellProps.imageEditorContainer}
+     * — without it the shell falls back to view mode and logs a warning.
+     */
+    imageMode?: 'view' | 'edit';
+    /**
+     * Sidecar `ContentContainer` for the image being edited. Conventionally
+     * scoped to `<basename>_files/` via
+     * `scopeContainer(parentContainer, basename + '_files')`. The image
+     * editor persists `state.json`, layer assets in `assets/`, and (when
+     * `allowVersioning` is true) snapshots in `.versions/` inside it.
+     */
+    imageEditorContainer?: ContentContainer;
+    /**
+     * Called after the user clicks Export in the image editor and the
+     * raster blob is produced. When omitted, the editor triggers a
+     * default browser download.
+     */
+    onImageExport?: (blob: Blob, format: 'png' | 'jpeg' | 'webp') => void;
+    /**
+     * Show an inline preview gutter to the right of the WYSIWYG editor.
+     * The gutter renders one small SVG card per template-annotated block in
+     * the document, letting authors see their rendered output without
+     * leaving Edit mode. Auto-hidden via container query when the editor
+     * body is narrower than ~720px. Defaults to `false`.
+     */
+    inlinePreview?: boolean;
+    /**
+     * Width in pixels for the inline preview gutter. Defaults to 320.
+     * Only takes effect when {@link EditorShellProps.inlinePreview} is true.
+     */
+    inlinePreviewWidth?: number;
+    /**
+     * Show an outline pane on the left of the WYSIWYG editor — a
+     * hierarchical tree of the document's headings (h1 → h2 → h3) with
+     * click-to-scroll. Auto-hidden via container query on narrow editors.
+     * Defaults to `false`. The toolbar's View menu can toggle this at
+     * runtime regardless of the initial value.
+     */
+    outline?: boolean;
+    /**
+     * Width in pixels for the outline pane. Defaults to 240. Only takes
+     * effect when {@link EditorShellProps.outline} is true (or the View
+     * menu has toggled it on).
+     */
+    outlineWidth?: number;
+    /**
+     * Initial visibility of inline block-template tags on headings — the
+     * chip rendered next to each heading in the WYSIWYG view that opens
+     * the block-template picker. Defaults to true; the View menu can
+     * toggle it at runtime regardless of the initial value.
+     */
+    blockTags?: boolean;
+    /**
+     * How much of the active Squisq theme the WYSIWYG editing surface
+     * mirrors. Defaults to `'fonts'` — the historical behavior of
+     * inheriting body / heading fonts only. The View menu can change it
+     * at runtime.
+     */
+    themeInheritance?: ThemeInheritance;
+    /**
+     * Bundled view preferences — a serializable JSON blob covering the
+     * runtime-toggleable view options surfaced in the View menu. When
+     * provided, fields here override the corresponding individual props
+     * (`outline`, `inlinePreview`, `showStatusBar`). Pair with
+     * {@link onViewPreferencesChange} to externalize storage of these
+     * preferences in the host.
+     */
+    viewPreferences?: ViewPreferences;
+    /**
+     * Notified after each user-driven toggle in the View menu. The
+     * argument is a full snapshot of all view preferences — hosts can
+     * persist it as-is. Not called when {@link viewPreferences} is
+     * changed externally.
+     */
+    onViewPreferencesChange?: (prefs: ViewPreferences) => void;
+    /**
+     * Override the preview theme with an explicit `Theme` object. When set,
+     * `Doc.themeId` and the user's theme dropdown selection are ignored for
+     * the preview surface. Used by the theme customizer to live-preview an
+     * in-progress theme without mutating the document.
+     */
+    themeOverride?: Theme | null;
+}
+/**
+ * Complete markdown editor shell with toolbar, view switcher, and three
+ * editing modes: Raw (Monaco), WYSIWYG (Tiptap), and Preview.
+ */
+declare function EditorShell({ initialMarkdown, initialView, articleId, basePath, onChange, theme, className, height, minHeight, maxHeight, mediaProvider, workspaceContainer, container, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, showFilesToggle, toolbarSlotLeft, toolbarSlotAfterActions, toolbarSlotRight, showPlayTab, submitOnEnter, fullWidth, uxFont, thinMargins, showStatusBar, imageDisplayMode, fileName, language, mentionProvider, documentLinkProvider, allowRecording, placeholder, readOnly, imageSrc, imageAlt, imageMode, imageEditorContainer, onImageExport, inlinePreview, inlinePreviewWidth, outline, outlineWidth, blockTags, themeInheritance, viewPreferences, onViewPreferencesChange, themeOverride, }: EditorShellProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * fileKind
+ *
+ * Maps a file name (or bare extension) to a Monaco language ID and decides
+ * whether the editor shell should operate in markdown mode (full WYSIWYG +
+ * Preview experience) or code mode (Monaco-only view with formatting
+ * buttons hidden).
+ *
+ * The mapping favors common web / systems languages that Monaco ships with
+ * out of the box. Unknown extensions fall back to markdown mode so the
+ * existing UX remains the default for anything we don't recognize.
+ */
+interface FileKind {
+    /**
+     * 'markdown' keeps the full editor (WYSIWYG + Preview tabs); 'code' is
+     * Monaco-only; 'image' renders a dedicated image viewer with no text
+     * editing surface.
+     */
+    mode: 'markdown' | 'code' | 'image';
+    /** Monaco language ID — passed to `<Editor defaultLanguage={...} />`. */
+    language: string;
+}
+/**
+ * Detect a Monaco language ID from a file name. Returns null when the
+ * extension (or bare name) is not in the mapping.
+ */
+declare function detectLanguageFromFileName(fileName: string): string | null;
+/**
+ * Resolve the editor mode + Monaco language for a given file. The explicit
+ * `language` argument, if provided, wins over any detection from
+ * `fileName`. When nothing matches, falls back to markdown mode.
+ */
+declare function resolveFileKind(fileName?: string, language?: string): FileKind;
+
+/**
+ * ImageViewer
+ *
+ * Read-only image viewer used when EditorShell runs in `image` file mode
+ * (PNG/JPEG/etc.). Renders a centered image that fits its container with
+ * a small overlay toolbar for fit / 100% / zoom in / zoom out, and a
+ * status row showing intrinsic dimensions and current zoom.
+ *
+ * Lifecycle of the `src` URL is the caller's responsibility — when fed a
+ * blob URL, the host should `URL.revokeObjectURL` on unmount or src change.
+ *
+ * Future image-editing actions (rotate, flip, crop) will slot in alongside
+ * the existing zoom controls.
+ */
+interface ImageViewerProps {
+    /** Image source — typically a blob: URL the host owns and revokes. */
+    src: string;
+    /** Alt text for accessibility. Defaults to empty string (decorative). */
+    alt?: string;
+    /** Additional class name on the outer container. */
+    className?: string;
+    /** Color theme for the chrome around the image. */
+    theme?: 'light' | 'dark';
+}
+declare function ImageViewer({ src, alt, className, theme }: ImageViewerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * RawEditor
+ *
+ * Monaco-based raw markdown editor. Provides full VS Code-like editing
+ * experience with syntax highlighting, minimap, and bracket matching.
+ * Syncs changes back to EditorContext on every keystroke (debounced).
+ */
+interface RawEditorProps {
+    /** Monaco editor theme (default: 'vs-dark') */
+    theme?: string;
+    /** Show minimap (default: false) */
+    minimap?: boolean;
+    /** Font size in pixels (default: 14) */
+    fontSize?: number;
+    /** Word wrap setting (default: 'on') */
+    wordWrap?: 'on' | 'off' | 'wordWrapColumn' | 'bounded';
+    /** Additional class name for the container */
+    className?: string;
+    /**
+     * Chat-composer mode: Enter fires this callback (submit) and Cmd/Ctrl+Enter
+     * inserts a newline. When undefined, behaves normally.
+     */
+    submitOnEnter?: () => void;
+    /** Make Monaco read-only (no edits, no cursor blink). */
+    readOnly?: boolean;
+}
+/**
+ * Raw markdown editor using Monaco Editor.
+ * Binds to the shared EditorContext for source synchronization.
+ */
+declare function RawEditor({ theme, minimap, fontSize, wordWrap, className, submitOnEnter, readOnly, }: RawEditorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * WysiwygEditor
+ *
+ * Tiptap-based rich text editor that provides a WYSIWYG editing experience
+ * for markdown content. Uses squisq's parseMarkdown/stringifyMarkdown for
+ * conversion rather than Tiptap's built-in HTML serialization, ensuring
+ * perfect fidelity with the markdown format.
+ *
+ * Includes extensions for GFM features: tables, task lists, strikethrough,
+ * and code blocks.
+ */
+interface WysiwygEditorProps {
+    /**
+     * Placeholder text when the editor is empty. If omitted, one of several
+     * rotating prompts is picked at random on mount. Pass a fixed string to
+     * override with a host-specific call to action.
+     */
+    placeholder?: string;
+    /** Additional class name for the container */
+    className?: string;
+    /**
+     * If set, a plain Enter keypress fires this callback instead of inserting
+     * a newline, and Cmd/Ctrl+Enter inserts a soft break. Chat-composer UX.
+     */
+    submitOnEnter?: () => void;
+    /** Disable Tiptap editing — renders content but blocks input. */
+    readOnly?: boolean;
+}
+/**
+ * Rich WYSIWYG markdown editor built on Tiptap (ProseMirror).
+ * Binds to the shared EditorContext for source synchronization.
+ */
+declare function WysiwygEditor({ placeholder, className, submitOnEnter, readOnly, }: WysiwygEditorProps): react_jsx_runtime.JSX.Element;
+
+interface PreviewPanelProps {
+    /** Base path for resolving media URLs in DocPlayer */
+    basePath?: string;
+    /** Additional class name for the container */
+    className?: string;
+    /**
+     * Workspace-scoped `ContentContainer` (the folder holding the doc and
+     * its siblings). Used here for audio mapping — MP3 discovery and
+     * `timing.json` reading.
+     */
+    workspaceContainer?: ContentContainer | null;
+}
+/**
+ * Live preview panel that renders the current document as a slideshow
+ * or document view. Controls (viewport, mode, theme, transform, captions)
+ * are rendered in the main toolbar via PreviewToolbarControls.
+ */
+declare function PreviewPanel({ basePath, className, workspaceContainer }: PreviewPanelProps): react_jsx_runtime.JSX.Element;
+
+interface PlainHtmlPreviewProps {
+    /** Raw markdown source. */
+    markdown: string;
+    /** Document title — populates the iframe's `<title>`. */
+    title?: string;
+    /**
+     * Pre-resolved image substitutions (export-time use). Takes precedence
+     * over live `mediaProvider` resolution for any URL it contains.
+     */
+    images?: Map<string, string>;
+    /**
+     * When passed, relative image URLs in the markdown are resolved live
+     * via this provider. Skip for static previews where `images` already
+     * contains everything.
+     */
+    mediaProvider?: MediaProvider | null;
+    /** Token that, when changed, forces re-resolution of media URLs.
+     *  Mirrors the `mediaRevision` bump the editor uses after an image
+     *  edit so saves show up in the preview without remount. */
+    mediaRevision?: number;
+    /**
+     * Squisq theme to apply. When set, the iframe loads any Google-
+     * hosted fonts the theme uses and the rendered HTML adopts the
+     * theme's colors and typography.
+     */
+    theme?: Theme;
+    className?: string;
+    style?: CSSProperties;
+}
+declare function PlainHtmlPreview({ markdown, title, images, mediaProvider, mediaRevision, theme, className, style, }: PlainHtmlPreviewProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Emoji Dataset
+ *
+ * Curated set of common emoji grouped by Unicode CLDR category. Used by
+ * `EmojiPicker` for both the category tabs and the search index.
+ *
+ * Each entry is a flat tuple `[char, name, ...keywords]` so the data
+ * stays compact in source and is cheap to scan for the typeahead
+ * search. Categories follow the official Unicode buckets in display
+ * order (CLDR v44 grouping), trimmed to common picks per category —
+ * we deliberately don't ship the whole Unicode emoji set (thousands)
+ * because the picker is meant for quick insertion, not exhaustive
+ * lookup; the user can paste anything we don't have.
+ */
+interface EmojiEntry {
+    /** The actual emoji glyph (may be multi-codepoint, e.g. ZWJ sequences). */
+    char: string;
+    /** Display name shown in the tooltip. */
+    name: string;
+    /** Lowercase keywords for the search index — name words plus aliases. */
+    keywords: string;
+}
+interface EmojiCategory {
+    id: string;
+    label: string;
+    /** Single-glyph icon shown on the tab. */
+    icon: string;
+    emojis: EmojiEntry[];
+}
+declare const EMOJI_CATEGORIES: EmojiCategory[];
+/**
+ * Flat list of every emoji across all categories — used as the search
+ * corpus and to expose a `getEmojiByChar` lookup.
+ */
+declare const ALL_EMOJIS: EmojiEntry[];
+/** Search for emoji whose name or keywords contain the query (case-insensitive). */
+declare function searchEmojis(query: string, limit?: number): EmojiEntry[];
+
+/**
+ * Discriminated picker entry. The picker UI dispatches on `kind` to
+ * render either an emoji glyph or a FontAwesome `<i>` element. The
+ * Toolbar consumes the selected entry to insert into the editor.
+ */
+type PickerEntry = {
+    kind: 'emoji';
+    char: string;
+    name: string;
+    keywords: string;
+} | {
+    kind: 'icon';
+    family: IconFamily;
+    name: string;
+    label: string;
+    keywords: string;
+    /** Canonical token used in the markdown source (bare or qualified). */
+    token: string;
+};
+
+interface EmojiPickerProps {
+    /** Whether the picker is visible. */
+    open: boolean;
+    /**
+     * Fired when the user picks an entry. Carries either an emoji glyph
+     * or a FontAwesome icon descriptor — the caller dispatches on
+     * `kind` to insert it into the active editor. The caller is also
+     * responsible for closing the popover.
+     */
+    onSelect: (entry: PickerEntry) => void;
+    /** Fired on Escape, click-outside, or selection so the caller can close. */
+    onClose: () => void;
+    /** Optional anchor element — used for click-outside detection. When the
+     *  popover is rendered inside the same container as the trigger, pointer
+     *  events on the trigger don't fire the outside handler. */
+    anchorRef?: React.RefObject<HTMLElement>;
+    /** Optional CSS class for the popover root. */
+    className?: string;
+    /** Optional inline style for the popover root (e.g. positioning). */
+    style?: CSSProperties;
+    /**
+     * Editor theme — `'light'` or `'dark'`. Drives the picker's color
+     * palette. Required for the picker to render correctly when portaled
+     * outside the editor shell, since CSS custom properties defined on
+     * the shell don't cascade to portal targets. Defaults to `'light'`.
+     */
+    theme?: 'light' | 'dark';
+}
+declare function EmojiPicker({ open, onSelect, onClose, anchorRef, className, style, theme, }: EmojiPickerProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * DocumentSettingsDialog
+ *
+ * Modal editor for the frontmatter values that Squisq currently
+ * understands: document title plus the persisted preview keys
+ * (`squisq-theme`, `squisq-transform`, `squisq-captions`). Writes back
+ * to the same `setFrontmatterValues` channel that `PreviewControls`
+ * uses, so any change made here is reflected in the play-mode controls
+ * (and vice versa).
+ *
+ * Title behavior: the placeholder shows the title that
+ * `inferDocumentTitle()` would derive from frontmatter or headings.
+ * When the user-entered title is empty or equal to the inferred title,
+ * the `title:` key is removed from frontmatter — there's no point
+ * storing a redundant value.
+ */
+interface DocumentSettingsDialogProps {
+    /** Current markdown source string (frontmatter + body). */
+    markdownSource: string;
+    /** Called with the rewritten source after the user clicks Save. */
+    onSave: (nextSource: string) => void;
+    /** Called when the dialog is dismissed (Cancel, Escape, backdrop click). */
+    onClose: () => void;
+}
+declare function DocumentSettingsDialog({ markdownSource, onSave, onClose, }: DocumentSettingsDialogProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * ThemePicker
+ *
+ * Custom theme dropdown that replaces a plain `<select>` with a popover
+ * showing each theme as a card: the theme name rendered in the theme's
+ * own background / foreground / title font, plus three color swatches
+ * (primary, secondary, highlight). Used by both the play-mode preview
+ * toolbar and the Document Settings dialog so authors see a
+ * preview-on-hover style listing rather than a wall of names.
+ */
+interface ThemePickerProps {
+    /** Currently selected theme id. Empty string represents "default". */
+    value: string;
+    /** Called with the new theme id. The empty string is emitted when the
+     *  user picks the "Default" option (only available with
+     *  `includeDefault`). */
+    onChange: (id: string) => void;
+    /**
+     * Show a "Default" entry at the top of the popover that emits an empty
+     * string. Used by the Document Settings dialog so the user can choose
+     * "no explicit theme" (frontmatter omits the key entirely).
+     */
+    includeDefault?: boolean;
+    /**
+     * `'compact'` (default) renders a small toolbar trigger; `'full'`
+     * stretches to fill the parent and is sized for dialog layouts.
+     */
+    variant?: 'compact' | 'full';
+    /** Accessible label, e.g. "Theme". */
+    ariaLabel?: string;
+}
+declare function ThemePicker({ value, onChange, includeDefault, variant, ariaLabel, }: ThemePickerProps): react_jsx_runtime.JSX.Element;
+
+interface PreviewSettings {
+    activePreset: ViewportPreset;
+    setSelectedPreset: (preset: ViewportPreset | null) => void;
+    activeViewport: ViewportConfig;
+    activeDisplayMode: DisplayMode;
+    setSelectedDisplayMode: (mode: DisplayMode | null) => void;
+    activeThemeId: string;
+    setSelectedThemeId: (id: string | null) => void;
+    activeTheme: Theme;
+    activeTransformStyle: string;
+    setSelectedTransformStyle: (id: string | null) => void;
+    activeCaptionStyle: CaptionStyle;
+    setSelectedCaptionStyle: (style: CaptionStyle | null) => void;
+}
+declare function usePreviewSettings(): PreviewSettings;
+interface PreviewSettingsProviderProps {
+    doc: Doc | null;
+    children: ReactNode;
+    /**
+     * Optional Theme to use for the preview, regardless of `Doc.themeId` or
+     * the user's theme dropdown selection. Used by the theme customizer to
+     * preview an in-progress theme without mutating the document. When
+     * present, `activeTheme` is this value and `activeThemeId` is its `id`.
+     */
+    themeOverride?: Theme | null;
+}
+declare function PreviewSettingsProvider({ doc, children, themeOverride, }: PreviewSettingsProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Inline preview controls rendered in the main toolbar row.
+ * On narrow viewports, collapses into a single settings button with a dropdown.
+ */
+declare function PreviewToolbarControls(): react_jsx_runtime.JSX.Element;
+
+/**
+ * ViewSwitcher
+ *
+ * Tab bar for switching between Raw, WYSIWYG, and Preview editor views.
+ */
+interface ViewSwitcherProps {
+    /** Additional class name */
+    className?: string;
+}
+/**
+ * Tab-style view switcher for the three editor modes.
+ */
+declare function ViewSwitcher({ className }: ViewSwitcherProps): react_jsx_runtime.JSX.Element | null;
+
+interface ToolbarProps {
+    /** Additional class name */
+    className?: string;
+    /** Whether the Files panel is currently shown */
+    showFiles?: boolean;
+    /** Toggle the Files panel. When provided, a "Files" button appears in the toolbar. */
+    onToggleFiles?: () => void;
+    /** Content rendered at the left edge of the toolbar, before the view tabs. */
+    slotLeft?: ReactNode;
+    /** Content rendered after the formatting controls (in the middle area). */
+    slotAfterActions?: ReactNode;
+    /** Content rendered at the rightmost end of the toolbar, after all other elements. */
+    slotRight?: ReactNode;
+    /**
+     * Whether to include the "Play" (preview) tab in the view switcher.
+     * Defaults to true. Hosts that don't want the slideshow preview — e.g.
+     * editing free-form prompts — can pass false to suppress it.
+     */
+    showPlayTab?: boolean;
+}
+/**
+ * Formatting toolbar.
+ * - WYSIWYG: calls Tiptap chain commands (toggleBold, etc.)
+ * - Raw: appends markdown syntax to the source
+ */
+declare function Toolbar({ className, showFiles, onToggleFiles, slotLeft, slotAfterActions, slotRight, showPlayTab, }: ToolbarProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * VersionHistoryPanel
+ *
+ * Toolbar-anchored popover that lists prior version snapshots and lets
+ * the user revert to one. When a snapshot is selected, a Monaco diff
+ * view appears to the left of the list comparing the snapshot (original,
+ * left) with the current editor content (modified, right).
+ *
+ * Wraps the toolbar trigger button + popover surface. Versioning state
+ * is read from the EditorContext — render this component anywhere inside
+ * a provider that has `allowVersioning` and a `container`.
+ */
+declare function VersionHistoryPanel(): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * ViewMenuPanel
+ *
+ * Toolbar overflow menu (`…` button) for view-related toggles. Currently
+ * houses the inline preview gutter toggle; new view options can be added
+ * as additional `<MenuToggle>` rows without restructuring.
+ *
+ * State lives in EditorContext so the toggle survives view switches and
+ * the host doesn't need to manage it. The initial value comes from the
+ * EditorShell `inlinePreview` prop.
+ */
+declare function ViewMenuPanel(): react_jsx_runtime.JSX.Element;
+
+/**
+ * OutlinePanel
+ *
+ * Left-side companion to the InlinePreviewGutter. Renders a hierarchical
+ * tree of the document's headings (h1 → h2 → h3 …) so the structure is
+ * graspable at a glance and the user can jump to any section. Works in
+ * BOTH the WYSIWYG and Markdown editor views — view-specific positioning
+ * lives in `useHeadingLayout`.
+ */
+interface OutlinePanelProps {
+    /** Width of the pane in pixels (default: 240). */
+    width?: number;
+    /** Optional CSS class for the outer container. */
+    className?: string;
+}
+declare function OutlinePanel({ width, className }: OutlinePanelProps): react_jsx_runtime.JSX.Element;
+
+interface ThemeCustomizerPanelProps {
+    /** Current custom theme (or null to start from defaults). */
+    value: Theme | null;
+    /** Fired on every edit. Host typically registers the theme + previews it. */
+    onChange: (theme: Theme) => void;
+    /** Fired when the user clicks Save. Host typically persists the theme JSON. */
+    onSave?: (theme: Theme, json: string) => void;
+    /** Fired when the user clicks Reset. Host typically clears its persistent storage. */
+    onReset?: () => void;
+}
+declare function ThemeCustomizerPanel({ value, onChange, onSave, onReset, }: ThemeCustomizerPanelProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Convert a camelCase template id to a human-readable label. Accepts both
+ * the canonical short ids (`title`, `quote`, `map`, `list`) and the
+ * legacy long ones (`titleBlock`, `quoteBlock`, `mapBlock`, `listBlock`)
+ * so existing documents keep showing a friendly label without first
+ * normalizing their annotations.
+ */
+declare function templateLabel(name: string): string;
+interface TemplatePickerProps {
+    value: string;
+    onChange: (name: string) => void;
+    /** When true, shows only the trigger button (no popover) — used in the overflow menu. */
+    compact?: boolean;
+    /**
+     * Template names to surface in a "Recommended for this block" section
+     * above the full list. When omitted or empty, the gallery renders as a
+     * single ungrouped grid (legacy behavior).
+     */
+    recommended?: readonly string[];
+}
+declare function TemplatePicker({ value, onChange, compact, recommended }: TemplatePickerProps): react_jsx_runtime.JSX.Element;
+
+interface InlinePreviewGutterProps {
+    /** Width of the gutter in pixels (default: 320). */
+    width?: number;
+    /** Base path for resolving media URLs in card thumbnails. */
+    basePath?: string;
+    /** Viewport used to render each card (default: landscape preset). */
+    viewport?: ViewportConfig;
+    /** Optional CSS class for the outer container. */
+    className?: string;
+    /**
+     * Width in pixels of the connector strip that bridges the editor and
+     * the gutter. Defaults to 24.
+     */
+    connectorWidth?: number;
+    /**
+     * Optional MediaProvider used to resolve relative image src values inside
+     * preview cards. When omitted, images with relative paths fall back to
+     * `basePath`-prefixed URLs (which usually 404 in container-backed editors).
+     */
+    mediaProvider?: MediaProvider | null;
+}
+declare function InlinePreviewGutter({ width, basePath, viewport, className, connectorWidth, mediaProvider, }: InlinePreviewGutterProps): react_jsx_runtime.JSX.Element;
+
+interface MediaBinProps {
+    /** The active MediaProvider (null when no media context is available) */
+    mediaProvider: MediaProvider | null;
+    /** Whether the editor is in dark mode */
+    isDark: boolean;
+    /** Incremented externally to signal a re-scan of the media list */
+    refreshKey?: number;
+    /**
+     * Fired after a successful upload via the MediaBin's own "+ Upload"
+     * button. `relativePath` is what the provider returned (the same
+     * value embedded in markdown refs, e.g. `attachments/xyz.png`);
+     * `name` is the uploader-chosen filename before storage renamed
+     * it. Consumers typically use this to insert a markdown image ref
+     * at the editor's cursor so the file actually participates in the
+     * outgoing message — previously files went to the bin and nowhere
+     * else, leaving the message body empty when the user hit Send.
+     */
+    onMediaUploaded?: (relativePath: string, name: string, mimeType: string) => void | Promise<void>;
+}
+declare function MediaBin({ mediaProvider, isDark, refreshKey, onMediaUploaded }: MediaBinProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * StatusBar
+ *
+ * Bottom status bar showing document statistics and parse status.
+ */
+interface StatusBarProps {
+    /** Additional class name */
+    className?: string;
+}
+/**
+ * Status bar displaying document statistics: character count, word count,
+ * block count, and parse/error status.
+ */
+declare function StatusBar({ className }: StatusBarProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * TooltipLayer
+ *
+ * A single portal-mounted tooltip that activates on hover over any element
+ * with a `data-tooltip` attribute. Shorter delay than native browser
+ * tooltips and fires regardless of window focus, making toolbar hints feel
+ * immediate. Mount once near the root of the editor shell.
+ */
+declare function TooltipLayer(): react.ReactPortal | null;
+
+/**
+ * useFileDrop
+ *
+ * React hook that manages HTML5 drag-and-drop state for file uploads.
+ * Tracks whether files are being dragged over the target element,
+ * classifies dragged file types (media vs text), and dispatches
+ * drop events to callers.
+ */
+type FileCategory = 'media' | 'text' | 'unknown';
+type DragContentType = 'media' | 'text' | 'mixed' | null;
+type DropTarget = 'media' | 'insert' | 'replace';
+declare function classifyFile(file: {
+    name: string;
+    type: string;
+}): FileCategory;
+interface UseFileDropOptions {
+    /** Called when files are dropped on a specific target zone. */
+    onDrop: (files: File[], target: DropTarget) => void;
+    /** Whether drop is enabled (default: true) */
+    enabled?: boolean;
+}
+interface UseFileDropResult {
+    /** Whether a drag-with-files is currently hovering over the container */
+    isDragging: boolean;
+    /** Classification of the dragged content */
+    dragContentType: DragContentType;
+    /** Attach these to the container element */
+    containerProps: {
+        onDragEnter: (e: React.DragEvent) => void;
+        onDragOver: (e: React.DragEvent) => void;
+        onDragLeave: (e: React.DragEvent) => void;
+        onDrop: (e: React.DragEvent) => void;
+    };
+    /** Create props for an individual drop zone target */
+    zoneProps: (target: DropTarget) => {
+        onDragOver: (e: React.DragEvent) => void;
+        onDrop: (e: React.DragEvent) => void;
+    };
+}
+declare function useFileDrop({ onDrop, enabled }: UseFileDropOptions): UseFileDropResult;
+
+interface DropZoneOverlayProps {
+    /** What kind of content is being dragged */
+    dragContentType: DragContentType;
+    /** Factory that creates event props for a specific drop target */
+    zoneProps: UseFileDropResult['zoneProps'];
+    /** Whether a MediaProvider is available (disables media zone when false) */
+    hasMediaProvider: boolean;
+}
+/**
+ * Full-size overlay with contextual drop targets for file uploads.
+ * Rendered conditionally by EditorShell when files are dragged over the editor.
+ */
+declare function DropZoneOverlay({ dragContentType, zoneProps, hasMediaProvider, }: DropZoneOverlayProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Drop Utilities
+ *
+ * File processing pipeline for dropped files. Classifies files by type,
+ * processes media files into a MediaProvider, and converts text files
+ * (.md, .txt, .docx) to markdown strings.
+ */
+
+/**
+ * Partition an array of files into media and text categories.
+ * Files with unknown type are skipped.
+ */
+declare function partitionFiles(files: File[]): {
+    media: File[];
+    text: File[];
+};
+/**
+ * Add media files to a MediaProvider. Returns the relative paths
+ * assigned by the provider, with `null` slots where a file could not
+ * be processed — keeping the result aligned with the input array so
+ * callers can correlate indices.
+ *
+ * Two failure modes are handled defensively:
+ *
+ * 1. `file.arrayBuffer()` throws (`InvalidStateError` — "An operation
+ *    that depends on state cached in an interface object was made but
+ *    the state had changed since it was read from disk"). This happens
+ *    with virtual drag sources whose File reference goes stale before
+ *    the async read completes — Phone Link / iOS continuity / certain
+ *    screenshot tools / etc.
+ *
+ * 2. `file.arrayBuffer()` returns a 0-byte buffer. Some virtual
+ *    sources resolve the read successfully but with no payload,
+ *    leaving an empty file in the media bin. We skip those so the
+ *    bin doesn't accumulate placeholders.
+ *
+ * In both cases we warn via console rather than throwing, so a single
+ * problematic file doesn't abort a multi-file drop.
+ */
+declare function processMediaFiles(files: File[], mediaProvider: MediaProvider): Promise<(string | null)[]>;
+/**
+ * Read a text-content file and return its content as a markdown string.
+ *
+ * - `.md` and `.txt` files are read as UTF-8 text directly
+ * - `.docx` files are converted to markdown via `@bendyline/squisq-formats/docx`
+ */
+declare function processTextFile(file: File): Promise<string>;
+/**
+ * Process multiple text files and concatenate their content.
+ */
+declare function processTextFiles(files: File[]): Promise<string>;
+
+/**
+ * Tiptap Bridge
+ *
+ * Conversion utilities between raw markdown source and Tiptap's JSON/HTML
+ * content format. Uses a lightweight HTML-based approach: we convert markdown
+ * to a simple HTML representation that Tiptap can consume, and parse
+ * Tiptap's HTML output back to markdown.
+ *
+ * This bridge preserves markdown semantics much better than going through
+ * Tiptap's native markdown extension, since we control the conversion
+ * using squisq's own parser.
+ */
+/**
+ * Convert raw markdown source to Tiptap-consumable HTML content.
+ * Uses a simple markdown-to-HTML conversion that maps cleanly to
+ * Tiptap's ProseMirror schema.
+ */
+declare function markdownToTiptap(markdown: string): string;
+/**
+ * Convert Tiptap HTML output back to markdown source.
+ * Extracts semantic structure from HTML and produces clean markdown.
+ */
+declare function tiptapToMarkdown(html: string): string;
+
+/**
+ * buildPreviewDoc — Converts a markdown-derived Doc into a player-ready Doc
+ * with TemplateBlock slides and interleaved images.
+ *
+ * Shared between PreviewPanel (live preview) and export flows (HTML/video).
+ *
+ * Pipeline:
+ * 1. Flatten hierarchical blocks into a linear slide sequence
+ * 2. Convert each block into a TemplateBlock-compatible object
+ * 3. Interleave images as standalone imageWithCaption slides
+ * 4. Synthesize a dummy audio segment for timer-based playback
+ */
+
+/**
+ * Build a player-ready Doc from a markdown-derived Doc.
+ *
+ * Flattens hierarchical blocks, converts each to a TemplateBlock-compatible
+ * slide, interleaves images, recalculates timing, and adds a synthetic
+ * audio segment.
+ */
+declare function buildPreviewDoc(doc: Doc): Doc;
+
+/**
+ * TemplateAnnotation — Tiptap Heading Extension
+ *
+ * Extends Tiptap's built-in Heading node to support `data-template` and
+ * `data-template-params` HTML attributes. These attributes store which block
+ * template should be used for a heading section.
+ *
+ * When present, the heading renders a visible badge (styled CSS chip)
+ * showing the template name, e.g. `[chart]`.
+ *
+ * The tiptapBridge converts `### Title {[chart]}` markdown into
+ * `<h3 data-template="chart">Title</h3>` and back, so this extension
+ * ensures Tiptap's schema preserves those attributes through edits.
+ */
+/**
+ * HeadingWithTemplate — drop-in replacement for Tiptap's Heading that
+ * persists template annotation attributes.
+ */
+declare const HeadingWithTemplate: _tiptap_core.Node<_tiptap_extension_heading.HeadingOptions, any>;
+
+interface JsonEditorProps {
+    /** Schema describing the value's shape (with optional `squisq` hints). */
+    schema: SquisqAnnotatedSchema;
+    /** Controlled value. */
+    value: unknown;
+    /** Called with the new root after each edit. Omit for read-only behavior. */
+    onChange?: (next: unknown) => void;
+    /** Optional theme. Defaults to `DEFAULT_THEME`. */
+    theme?: Theme;
+    /** Light/dark surface override; `'auto'` uses `prefers-color-scheme`. */
+    surface?: SurfaceScheme | 'auto';
+    /** Padding/gap density. Default: 'comfortable'. */
+    density?: 'comfortable' | 'compact';
+    /** Optional consumer-supplied validator (e.g. ajv-backed). */
+    validate?: JsonFormValidator;
+    /** Notified after validation runs. */
+    onValidate?: (errors: readonly JsonFormValidationError[]) => void;
+    /** Optional CSS class for the outer container. */
+    className?: string;
+}
+declare function JsonEditor(props: JsonEditorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Format probing for MediaRecorder.
+ *
+ * Different browsers expose different container/codec combinations. Chrome
+ * and Firefox produce WebM (VP8/VP9 + Opus); Safari produces MP4 (H.264 +
+ * AAC). We probe at runtime via `MediaRecorder.isTypeSupported()` and pick
+ * the best supported option, falling back to whatever the browser hands
+ * back when no probe succeeds.
+ */
+/** What the recorded stream is intended to capture. */
+type CaptureKind = 'audio' | 'video';
+/** A probed format choice — what to pass to `MediaRecorder` and where to write it. */
+interface ResolvedFormat {
+    /** MIME type to pass to `new MediaRecorder(stream, { mimeType })`. Empty string means "let the browser pick". */
+    mimeType: string;
+    /** File extension to use when writing to the container, including the leading dot. */
+    extension: string;
+    /** Container directory inside the `ContentContainer` (no trailing slash). */
+    directory: 'audio' | 'video';
+}
+/**
+ * Resolve the format the recorder will use for a given capture kind. If a
+ * `preferred` MIME type is supported, it wins; otherwise we fall through
+ * the priority list. When nothing matches (extremely old browser), we
+ * return an empty `mimeType` — `MediaRecorder` will pick a default and we
+ * tag the file with `.webm` as a best guess.
+ */
+declare function resolveFormat(kind: CaptureKind, preferred?: string): ResolvedFormat;
+/**
+ * `MediaRecorder` support probe. Returns false when running in a
+ * non-browser environment (e.g. SSR) or on a browser that doesn't
+ * implement the API at all.
+ */
+declare function supportsMediaRecorder(): boolean;
+/**
+ * `getUserMedia` support probe (for mic / camera capture).
+ */
+declare function supportsUserMedia(): boolean;
+/**
+ * `getDisplayMedia` support probe (for screen capture). Browsers may
+ * implement `mediaDevices` without `getDisplayMedia` (Firefox on Android
+ * being the long-standing example), so this is its own probe.
+ */
+declare function supportsDisplayMedia(): boolean;
+/**
+ * Build a default filename for a recording. `basename` is a hint
+ * (e.g. user-typed name); when omitted, a sortable timestamp is used so
+ * concurrent recordings don't collide.
+ */
+declare function buildFilename(kind: CaptureKind, extension: string, basename?: string): string;
+
+/**
+ * useMediaRecorder
+ *
+ * React wrapper around `MediaRecorder` that handles stream acquisition,
+ * the recorder lifecycle, and produces a single `Blob` on stop. Selects
+ * a browser-supported MIME type via {@link resolveFormat}.
+ *
+ * Mirrors the shape of `useVideoExport` in `@bendyline/squisq-video-react`
+ * (request → start → stop → blob), inverted for capture rather than
+ * export.
+ */
+
+/** Which capture source to use. `screen+mic` mixes the microphone into the screen stream. */
+type RecorderSource = 'mic' | 'camera' | 'screen' | 'screen+mic';
+/** Discriminated state describing what the recorder is currently doing. */
+type RecorderState = 'idle' | 'requesting' | 'ready' | 'recording' | 'stopping' | 'stopped' | 'error';
+interface UseMediaRecorderOptions {
+    /** Which capture pipeline to use. */
+    source: RecorderSource;
+    /**
+     * Preferred MIME type override. When the browser supports it, this
+     * wins over the default candidate list. When unset (or unsupported),
+     * the hook probes a built-in priority list.
+     */
+    mimeType?: string;
+    /** Video track constraints for camera / screen sources. */
+    videoConstraints?: MediaTrackConstraints | boolean;
+    /** Audio track constraints for mic / camera / screen+mic sources. */
+    audioConstraints?: MediaTrackConstraints | boolean;
+    /**
+     * Bits-per-second hint passed to `MediaRecorder`. Most browsers cap to
+     * reasonable defaults internally; leaving this undefined is usually
+     * fine.
+     */
+    bitsPerSecond?: number;
+    /**
+     * Whether to attempt to capture system audio when `source === 'screen'`
+     * or `'screen+mic'`. Browser support is limited (desktop Chromium
+     * only); when unsupported the resulting stream simply omits it.
+     */
+    systemAudio?: boolean;
+}
+interface UseMediaRecorderResult {
+    /** Current recorder state. */
+    state: RecorderState;
+    /** Live `MediaStream` after `request()` succeeds; useful for preview. */
+    stream: MediaStream | null;
+    /** Final `Blob` after `stop()` resolves, or `null` while recording. */
+    blob: Blob | null;
+    /** MIME type the recorder actually used (after `request()`). */
+    mimeType: string | null;
+    /** File extension matching `mimeType` (e.g. `.webm`). */
+    extension: string | null;
+    /** Suggested container directory (`'audio'` for mic, `'video'` for camera/screen). */
+    directory: 'audio' | 'video' | null;
+    /** Milliseconds elapsed since `start()` was called. Updates ~10× per second while recording. */
+    durationMs: number;
+    /** Most recent error, if any. */
+    error: Error | null;
+    /**
+     * Acquire the stream and prepare a `MediaRecorder`. After this resolves
+     * the hook is in `'ready'` state and a `<video>`/`<audio>` element can
+     * preview `stream`. Call `start()` to begin recording.
+     */
+    request: () => Promise<void>;
+    /** Start recording. Must be called from `'ready'`. */
+    start: () => void;
+    /**
+     * Stop recording and resolve with the resulting `Blob`. Safe to call
+     * from `'recording'`; a no-op from any other state (resolves with the
+     * existing `blob`, or `null`).
+     */
+    stop: () => Promise<Blob | null>;
+    /**
+     * Tear everything down — stops the recorder if running, releases all
+     * tracks, disposes the AudioContext mixer (if any), and returns to
+     * `'idle'`. Always safe to call.
+     */
+    cancel: () => void;
+    /** Reset state without releasing the stream. Useful for re-recording. */
+    reset: () => void;
+}
+/**
+ * Returns the kind of capture that the given source produces. Exposed
+ * separately from {@link useMediaRecorder} so non-React callers
+ * (e.g. headless tests) can resolve a format up front.
+ */
+declare function getCaptureKind(source: RecorderSource): CaptureKind;
+declare function useMediaRecorder(options: UseMediaRecorderOptions): UseMediaRecorderResult;
+
+interface RecorderModalProps {
+    /** Required — recordings are written here. */
+    mediaProvider: MediaProvider;
+    /**
+     * Optional — when provided, narration-mode recordings drop a
+     * `.timing.json` sidecar at the matching container path so
+     * `resolveAudioMapping()` can auto-link them. Without it, only the
+     * raw recording is saved.
+     */
+    container?: ContentContainer | null;
+    /** Initial capture source. Defaults to `'mic'` (narration). */
+    initialMode?: RecorderSource;
+    /** Called after the modal is dismissed (save or cancel). */
+    onClose: () => void;
+    /**
+     * Fired after a successful save. Hosts typically use this to insert a
+     * markdown reference at the cursor — see {@link RecorderSaveResult}
+     * for the fields a host needs to build that reference.
+     */
+    onSave?: (result: RecorderSaveResult) => void;
+}
+/** Payload handed to {@link RecorderModalProps.onSave} on a successful save. */
+interface RecorderSaveResult {
+    /** Path returned by `mediaProvider.addMedia()` — what the doc should reference. */
+    relativePath: string;
+    /** Filename the modal chose (e.g. `narration-20260516-091200.webm`). */
+    filename: string;
+    /** Capture source the user picked. */
+    source: RecorderSource;
+    /** MIME type of the saved blob. */
+    mimeType: string;
+    /** Recording length in seconds. */
+    duration: number;
+    /** Whether a narration sidecar was written. Always `false` for video sources. */
+    hasTimingSidecar: boolean;
+    /** Script text the user typed (narration only). */
+    sourceText?: string;
+}
+declare function RecorderModal({ mediaProvider, container, initialMode, onClose, onSave, }: RecorderModalProps): react_jsx_runtime.JSX.Element;
+
+interface RecorderButtonProps {
+    /** Where to write the resulting recording. Required. */
+    mediaProvider: MediaProvider;
+    /** Optional container for narration `.timing.json` sidecar writes. */
+    container?: ContentContainer | null;
+    /** Initial capture source. Defaults to `'mic'`. */
+    initialMode?: RecorderSource;
+    /** Fired after a successful save. */
+    onSave?: (result: RecorderSaveResult) => void;
+    /** Button label. Defaults to `'Record'`. */
+    label?: string;
+    /** Optional inline button styles. */
+    style?: CSSProperties;
+    /** Whether the button is disabled. */
+    disabled?: boolean;
+}
+declare function RecorderButton({ mediaProvider, container, initialMode, onSave, label, style, disabled, }: RecorderButtonProps): react_jsx_runtime.JSX.Element;
+
+interface RecorderPanelProps {
+    mediaProvider: MediaProvider;
+    container?: ContentContainer | null;
+    initialMode?: RecorderSource;
+    onSave?: (result: RecorderSaveResult) => void;
+    /** ARIA / tooltip label. Defaults to `'Record media'`. */
+    tooltip?: string;
+    /** Optional className for the trigger button. */
+    className?: string;
+}
+declare function RecorderPanel({ mediaProvider, container, initialMode, onSave, tooltip, className, }: RecorderPanelProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useStreamPreview — binds a `MediaStream` to a `<video>` element's
+ * `srcObject`. Decouples the preview surface from `useMediaRecorder`,
+ * letting hosts compose the preview element however they like.
+ */
+
+/**
+ * Assign `stream` to `<video>.srcObject` whenever either changes; clears
+ * it on unmount or when `stream` is `null`. The element is set to
+ * `playsInline` + `muted` automatically because previewing your own
+ * microphone with audio playthrough creates a feedback loop.
  *
  * @example
  * ```tsx
- * import { EditorShell } from '@bendyline/squisq-editor-react';
- * import '@bendyline/squisq-editor-react/styles';
- *
- * function App() {
- *   return <EditorShell initialMarkdown="# Hello World" />;
- * }
+ * const videoRef = useRef<HTMLVideoElement>(null);
+ * const { stream } = useMediaRecorder({ source: 'camera' });
+ * useStreamPreview(videoRef, stream);
+ * return <video ref={videoRef} autoPlay />;
  * ```
  */
-export { EditorShell } from './EditorShell.js';
-export type { EditorShellProps, EditorTheme } from './EditorShell.js';
-export { EditorProvider, useEditorContext } from './EditorContext.js';
-export type { EditorView, EditorMode, EditorState, EditorActions, EditorContextValue, EditorProviderProps, ImageDisplayMode, MentionCandidate, MentionProvider, DocumentLinkCandidate, DocumentLinkProvider, ViewPreferences, ThemeInheritance, } from './EditorContext.js';
-export { resolveFileKind, detectLanguageFromFileName } from './fileKind.js';
-export type { FileKind } from './fileKind.js';
-export { ImageViewer } from './ImageViewer.js';
-export type { ImageViewerProps } from './ImageViewer.js';
-export { RawEditor } from './RawEditor.js';
-export type { RawEditorProps } from './RawEditor.js';
-export { WysiwygEditor } from './WysiwygEditor.js';
-export type { WysiwygEditorProps } from './WysiwygEditor.js';
-export { PreviewPanel } from './PreviewPanel.js';
-export type { PreviewPanelProps } from './PreviewPanel.js';
-export { PlainHtmlPreview } from './PlainHtmlPreview.js';
-export type { PlainHtmlPreviewProps } from './PlainHtmlPreview.js';
-export { EmojiPicker } from './EmojiPicker.js';
-export type { EmojiPickerProps } from './EmojiPicker.js';
-export { DocumentSettingsDialog } from './DocumentSettingsDialog.js';
-export type { DocumentSettingsDialogProps } from './DocumentSettingsDialog.js';
-export { ThemePicker } from './ThemePicker.js';
-export type { ThemePickerProps } from './ThemePicker.js';
-export { EMOJI_CATEGORIES, ALL_EMOJIS, searchEmojis } from './emojiData.js';
-export type { EmojiEntry, EmojiCategory } from './emojiData.js';
-export { PreviewSettingsProvider, PreviewToolbarControls, usePreviewSettings, } from './PreviewControls.js';
-export type { PreviewSettings } from './PreviewControls.js';
-export { ViewSwitcher } from './ViewSwitcher.js';
-export type { ViewSwitcherProps } from './ViewSwitcher.js';
-export { Toolbar } from './Toolbar.js';
-export type { ToolbarProps } from './Toolbar.js';
-export { VersionHistoryPanel } from './VersionHistoryPanel.js';
-export { ViewMenuPanel } from './ViewMenuPanel.js';
-export { OutlinePanel } from './OutlinePanel.js';
-export type { OutlinePanelProps } from './OutlinePanel.js';
-export { ThemeCustomizerPanel } from './ThemeCustomizerPanel.js';
-export type { ThemeCustomizerPanelProps } from './ThemeCustomizerPanel.js';
-export { TemplatePicker, templateLabel } from './TemplatePicker.js';
-export { InlinePreviewGutter } from './InlinePreviewGutter.js';
-export type { InlinePreviewGutterProps } from './InlinePreviewGutter.js';
-export { MediaBin } from './MediaBin.js';
-export type { MediaBinProps } from './MediaBin.js';
-export { StatusBar } from './StatusBar.js';
-export type { StatusBarProps } from './StatusBar.js';
-export { TooltipLayer } from './Tooltip.js';
-export { DropZoneOverlay } from './DropZoneOverlay.js';
-export type { DropZoneOverlayProps } from './DropZoneOverlay.js';
-export { useFileDrop, classifyFile } from './hooks/useFileDrop.js';
-export type { FileCategory, DragContentType, DropTarget, UseFileDropOptions, UseFileDropResult, } from './hooks/useFileDrop.js';
-export { partitionFiles, processMediaFiles, processTextFile, processTextFiles, } from './utils/dropUtils.js';
-export { markdownToTiptap, tiptapToMarkdown } from './tiptapBridge.js';
-export { buildPreviewDoc } from './buildPreviewDoc.js';
-export { HeadingWithTemplate } from './TemplateAnnotation.js';
-export { JsonEditor } from './jsonEditor/index.js';
-export type { JsonEditorProps } from './jsonEditor/index.js';
-export { RecorderModal } from './recorder/RecorderModal.js';
-export type { RecorderModalProps, RecorderSaveResult } from './recorder/RecorderModal.js';
-export { RecorderButton } from './recorder/RecorderButton.js';
-export type { RecorderButtonProps } from './recorder/RecorderButton.js';
-export { RecorderPanel } from './recorder/RecorderPanel.js';
-export type { RecorderPanelProps } from './recorder/RecorderPanel.js';
-export { useMediaRecorder, getCaptureKind } from './recorder/hooks/useMediaRecorder.js';
-export type { UseMediaRecorderOptions, UseMediaRecorderResult, RecorderSource, RecorderState, } from './recorder/hooks/useMediaRecorder.js';
-export { useStreamPreview } from './recorder/hooks/useStreamPreview.js';
-export { requestMicStream } from './recorder/sources/micStream.js';
-export { requestCameraStream } from './recorder/sources/cameraStream.js';
-export type { CameraStreamOptions } from './recorder/sources/cameraStream.js';
-export { requestScreenStream } from './recorder/sources/screenStream.js';
-export type { ScreenStreamOptions, ScreenStreamHandle } from './recorder/sources/screenStream.js';
-export { resolveFormat, supportsMediaRecorder, supportsUserMedia, supportsDisplayMedia, buildFilename, } from './recorder/formats.js';
-export type { CaptureKind, ResolvedFormat } from './recorder/formats.js';
-export { buildTimingJson, encodeTimingJson, timingPathFor } from './recorder/timingJson.js';
-export type { TimingJson, RecordedBookmark } from './recorder/timingJson.js';
-export { ImageEditor } from './ImageEditor.js';
-export type { ImageEditorProps } from './ImageEditor.js';
-export { useImageEditor } from './imageEditor/useImageEditor.js';
-export type { UseImageEditorOptions, UseImageEditorReturn } from './imageEditor/useImageEditor.js';
-export { imageEditorReducer, initialImageEditorState } from './imageEditor/state.js';
-export type { ImageEditorState, ImageEditorAction, ImageEditorTool, CanvasRect, } from './imageEditor/state.js';
-//# sourceMappingURL=index.d.ts.map
+declare function useStreamPreview(ref: RefObject<HTMLVideoElement | null>, stream: MediaStream | null): void;
+
+/**
+ * Microphone-only capture via `getUserMedia({ audio: true })`.
+ */
+/**
+ * Request a microphone-only `MediaStream`. Caller owns the stream and
+ * must stop its tracks when done.
+ *
+ * @param constraints - Optional audio constraints (sample rate, device
+ *   id, echo cancellation, etc.). Defaults to `true` — let the browser
+ *   pick.
+ * @throws When `mediaDevices` is unavailable, or when the user denies
+ *   permission (the underlying `getUserMedia` rejection propagates).
+ */
+declare function requestMicStream(constraints?: MediaTrackConstraints): Promise<MediaStream>;
+
+/**
+ * Camera + microphone capture via `getUserMedia({ video, audio })`.
+ */
+interface CameraStreamOptions {
+    /** Video track constraints (resolution, facing mode, frame rate). Pass `true` for browser default, or `false` to omit video. */
+    video?: boolean | MediaTrackConstraints;
+    /** Audio track constraints. Pass `true` for browser default, or `false` to omit audio. */
+    audio?: boolean | MediaTrackConstraints;
+}
+/**
+ * Request a camera + mic `MediaStream`. Caller owns the stream and must
+ * stop its tracks when done.
+ *
+ * Both tracks are requested by default. To capture video only, pass
+ * `audio: false`; to capture audio only use {@link requestMicStream}
+ * instead.
+ *
+ * @throws When `mediaDevices` is unavailable, or when the user denies
+ *   permission.
+ */
+declare function requestCameraStream(options?: CameraStreamOptions): Promise<MediaStream>;
+
+/**
+ * Screen capture via `getDisplayMedia`, with optional microphone mixing.
+ *
+ * The browser-native `getDisplayMedia({ audio: true })` flag only
+ * captures *system* audio (and only on Chromium on desktop). For
+ * narrated screencasts, hosts usually want the speaker's voice too —
+ * we provide an opt-in "include mic" path that pulls a parallel
+ * `getUserMedia` audio track and mixes it into the screen stream via
+ * `AudioContext`, so the resulting `MediaStream` carries a single audio
+ * track and a single video track.
+ */
+interface ScreenStreamOptions {
+    /** Video constraints for the screen surface. Pass `true` for browser default. */
+    video?: boolean | MediaTrackConstraints;
+    /**
+     * Whether to attempt to capture the system audio (tab / window / monitor
+     * audio). Browser support is limited (desktop Chromium only); when the
+     * platform doesn't honor this flag, the resulting stream simply omits
+     * the system audio track.
+     */
+    systemAudio?: boolean;
+    /**
+     * Whether to also pull the microphone via `getUserMedia` and mix it
+     * into the resulting stream's audio track. When both `systemAudio` and
+     * `includeMicrophone` produce tracks, they're combined via
+     * `AudioContext` into a single output track.
+     */
+    includeMicrophone?: boolean;
+    /** Microphone track constraints, when `includeMicrophone` is true. */
+    microphoneConstraints?: MediaTrackConstraints;
+}
+/**
+ * Handle returned by {@link requestScreenStream}. The `stream` is what
+ * gets handed to `MediaRecorder`; the `dispose()` callback shuts down
+ * any auxiliary resources (e.g. the mic-mix `AudioContext`). Callers
+ * must also stop the stream's tracks via `stream.getTracks().forEach(t
+ * => t.stop())` when done — `dispose()` cleans up everything that isn't
+ * the stream itself.
+ */
+interface ScreenStreamHandle {
+    stream: MediaStream;
+    /** Auxiliary cleanup beyond the stream tracks. Safe to call multiple times. */
+    dispose: () => void;
+}
+/**
+ * Request a screen-capture `MediaStream`, optionally with a mixed-in
+ * microphone track. Caller owns the resulting stream.
+ *
+ * @throws When `getDisplayMedia` isn't available, or when the user
+ *   cancels the picker / denies permission.
+ */
+declare function requestScreenStream(options?: ScreenStreamOptions): Promise<ScreenStreamHandle>;
+
+/**
+ * Build the `.timing.json` sidecar that pairs with a narration recording.
+ *
+ * The shape matches what `resolveAudioMapping()` in
+ * `@bendyline/squisq` reads at runtime: `sourceText`, `duration`, and
+ * `bookmarks[]`. Sidecars are stored at `<audio-path>.timing.json`
+ * inside the same `ContentContainer`, so the recorder can drop them
+ * alongside its audio file and have the existing audio-mapping pipeline
+ * pick them up with no schema changes.
+ */
+/**
+ * Word-level timing bookmark — same shape as `AudioBookmark` in
+ * `@bendyline/squisq`. Recorder output produces an empty `bookmarks`
+ * array; word-level timing is the domain of TTS pipelines, not
+ * browser-side dictation.
+ */
+interface RecordedBookmark {
+    id: string;
+    time: number;
+    charOffset: number;
+    textFragment?: string;
+}
+interface TimingJson {
+    /** Plain text the user said (or intended to say) during the recording. */
+    sourceText: string;
+    /** Recording length in seconds. */
+    duration: number;
+    /** Word-level timing data. Empty by default — populated only when a downstream tool aligns the audio. */
+    bookmarks: RecordedBookmark[];
+}
+/**
+ * Build a `TimingJson` payload from a user-typed script and the
+ * recording's measured duration. Both fields are required by the
+ * downstream `parseTimingJson()` validator; missing them produces a
+ * sidecar that gets silently dropped by the audio-mapping pipeline.
+ */
+declare function buildTimingJson(sourceText: string, durationSec: number): TimingJson;
+/**
+ * Serialize a `TimingJson` payload to a `Uint8Array` ready to hand to
+ * `ContentContainer.writeFile()`. Pretty-printed so authors can hand-
+ * edit the sidecar if they ever want to.
+ */
+declare function encodeTimingJson(timing: TimingJson): Uint8Array;
+/**
+ * The container path convention `resolveAudioMapping()` expects:
+ * `<audio-path>.timing.json`. Pass the audio file's relative path
+ * (e.g. `'audio/narration-001.webm'`) and the matching sidecar path is
+ * returned (`'audio/narration-001.webm.timing.json'`).
+ */
+declare function timingPathFor(audioRelativePath: string): string;
+
+interface ImageEditorProps {
+    /**
+     * Scoped sidecar container for this image — typically
+     * `scopeContainer(parent, basename + '_files')`.
+     */
+    filesContainer: ContentContainer;
+    /**
+     * Source URL used to seed `assets/source.<ext>` and layer 0 the
+     * first time the sidecar is opened. Ignored once `state.json` exists.
+     */
+    initialSrc?: string;
+    /** Override the state filename. Default: `state.json`. */
+    stateFilename?: string;
+    /** Enable version-history snapshots in `.versions/`. Default: `false`. */
+    allowVersioning?: boolean;
+    /** Auto-save idle delay (ms) for version snapshots. Default: `5000`. */
+    versioningAutoSaveIdleMs?: number;
+    /** Called after the user clicks Export and the blob is produced. */
+    onExport?: (blob: Blob, format: ImageEditExportFormat) => void;
+    /**
+     * What the toolbar's Save button does:
+     *  - `'flush'` (default): write `state.json` to the sidecar.
+     *  - `'export'`: rasterize the canvas in `saveFormat` and fire
+     *    {@link onExport} — the same code path the Export menu uses.
+     *    Hosts that want one-click "save and close" semantics use this.
+     */
+    saveBehavior?: 'flush' | 'export';
+    /** Format used when `saveBehavior === 'export'`. Default: `'png'`. */
+    saveFormat?: ImageEditExportFormat;
+    /** Override the Save button label. Default: `'Save'`. */
+    saveLabel?: string;
+    /** Override the Save button tooltip. */
+    saveTitle?: string;
+    /**
+     * Squisq Theme to color the editor chrome (toolbar, panels, controls).
+     * Defaults to `DEFAULT_THEME`. Combined with {@link surface} the same
+     * way `<JsonView>` and `<LinearDocView>` do.
+     */
+    theme?: Theme;
+    /**
+     * Surface scheme — `LIGHT_SURFACE`, `DARK_SURFACE`, an explicit
+     * `SurfaceScheme` object, or `'auto'` to track the user's OS
+     * `prefers-color-scheme`. When omitted, the theme's own background is
+     * used as-is.
+     */
+    surface?: SurfaceScheme | 'auto';
+    /** Optional className for the root element. */
+    className?: string;
+}
+declare function ImageEditor(props: ImageEditorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure state + reducer for the `<ImageEditor>` component.
+ *
+ * Kept React-free so it's easy to unit-test in isolation. The actual
+ * React hook that wires this to a {@link ContentContainer} (and the
+ * version manager) lives in `useImageEditor.ts`.
+ */
+
+/**
+ * Layer payload accepted by the `add-layer` action — the `id` field is
+ * optional and will be assigned by the underlying `addLayer` helper if
+ * the caller doesn't supply one.
+ */
+type ImageEditLayerInput = ImageEditLayer | (Omit<ImageEditLayer, 'id'> & {
+    id?: string;
+});
+/** The currently active interaction tool. */
+type ImageEditorTool = 'select' | 'text' | 'shape' | 'image' | 'crop';
+/** A pixel-space rectangle in canvas coordinates. */
+interface CanvasRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ImageEditorState {
+    /** The persisted document. */
+    doc: ImageEditDoc;
+    /** Selected layer id, or `null` when nothing is selected. */
+    selectedLayerId: string | null;
+    /** Active tool. */
+    tool: ImageEditorTool;
+    /**
+     * Dirty flag — true when the in-memory doc has unsaved changes
+     * relative to the last `markClean()` call. The hook uses this to
+     * debounce writes back to `state.json`.
+     */
+    dirty: boolean;
+}
+type ImageEditorAction = {
+    type: 'load';
+    doc: ImageEditDoc;
+} | {
+    type: 'mark-clean';
+} | {
+    type: 'set-tool';
+    tool: ImageEditorTool;
+} | {
+    type: 'select';
+    layerId: string | null;
+} | {
+    type: 'set-canvas';
+    canvas: ImageEditDoc['canvas'];
+} | {
+    type: 'add-layer';
+    layer: ImageEditLayerInput;
+    select?: boolean;
+} | {
+    type: 'remove-layer';
+    layerId: string;
+} | {
+    type: 'update-layer';
+    layerId: string;
+    patch: Partial<ImageEditLayer>;
+} | {
+    type: 'reorder-layer';
+    layerId: string;
+    toIndex: number;
+} | {
+    type: 'crop';
+    rect: CanvasRect;
+};
+/** Build the initial state from a freshly-loaded doc. */
+declare function initialImageEditorState(doc: ImageEditDoc): ImageEditorState;
+declare function imageEditorReducer(state: ImageEditorState, action: ImageEditorAction): ImageEditorState;
+
+/**
+ * React hook that bundles the image-editor reducer with sidecar
+ * persistence, versioning, and an object-URL cache for asset bytes.
+ *
+ * Hosts pass an already-scoped {@link ContentContainer} (typically built
+ * with `scopeContainer(parent, basename + '_files')`); the hook never
+ * looks above that root.
+ */
+
+interface UseImageEditorOptions {
+    /** Sidecar container for the image being edited. */
+    container: ContentContainer;
+    /**
+     * Initial source image URL — used to seed layer 0 when the sidecar has
+     * no `state.json` yet. Bytes are fetched and copied into
+     * `assets/source.<ext>` so the doc is portable.
+     */
+    initialSrc?: string;
+    /** Override the state filename. Defaults to `state.json`. */
+    stateFilename?: string;
+    /** Enable version history. Default: `false`. */
+    allowVersioning?: boolean;
+    /** Auto-save idle delay (ms). `0` disables. Default: `5000`. */
+    versioningAutoSaveIdleMs?: number;
+    /** Debounced write delay for state.json (ms). Default: `500`. */
+    persistDebounceMs?: number;
+}
+interface UseImageEditorReturn {
+    /** Current reducer state (or `null` while still loading the initial doc). */
+    state: ImageEditorState | null;
+    /** Dispatch a reducer action. No-op while loading. */
+    dispatch: (action: ImageEditorAction) => void;
+    /** Manually trigger a synchronous write of `state.json`. */
+    flush: () => Promise<void>;
+    /** Resolve an asset path inside the sidecar to a blob URL (cached). */
+    resolveAssetUrl: (path: string) => Promise<string>;
+    /**
+     * Write a new asset (raster image) into `assets/` and return the
+     * sidecar-relative path. The caller is then expected to push a layer
+     * referencing that path.
+     */
+    uploadAsset: (file: Blob, suggestedName?: string) => Promise<string>;
+    /** Versioning handle. `null` when `allowVersioning` is false or no container. */
+    versioning: ImageEditVersionManager | null;
+    /** True after the initial load completes (either an existing doc or seeded). */
+    ready: boolean;
+    /** Last load / persistence error, if any. */
+    error: Error | null;
+}
+declare function useImageEditor(options: UseImageEditorOptions): UseImageEditorReturn;
+
+export { ALL_EMOJIS, type CameraStreamOptions, type CanvasRect, type CaptureKind, type DocumentLinkCandidate, type DocumentLinkProvider, DocumentSettingsDialog, type DocumentSettingsDialogProps, type DragContentType, type DropTarget, DropZoneOverlay, type DropZoneOverlayProps, EMOJI_CATEGORIES, type EditorActions, type EditorContextValue, type EditorMode, EditorProvider, type EditorProviderProps, EditorShell, type EditorShellProps, type EditorState, type EditorTheme, type EditorView, type EmojiCategory, type EmojiEntry, EmojiPicker, type EmojiPickerProps, type FileCategory, type FileKind, HeadingWithTemplate, type ImageDisplayMode, ImageEditor, type ImageEditorAction, type ImageEditorProps, type ImageEditorState, type ImageEditorTool, ImageViewer, type ImageViewerProps, InlinePreviewGutter, type InlinePreviewGutterProps, JsonEditor, type JsonEditorProps, MediaBin, type MediaBinProps, type MentionCandidate, type MentionProvider, OutlinePanel, type OutlinePanelProps, PlainHtmlPreview, type PlainHtmlPreviewProps, PreviewPanel, type PreviewPanelProps, type PreviewSettings, PreviewSettingsProvider, PreviewToolbarControls, RawEditor, type RawEditorProps, type RecordedBookmark, RecorderButton, type RecorderButtonProps, RecorderModal, type RecorderModalProps, RecorderPanel, type RecorderPanelProps, type RecorderSaveResult, type RecorderSource, type RecorderState, type ResolvedFormat, type ScreenStreamHandle, type ScreenStreamOptions, StatusBar, type StatusBarProps, TemplatePicker, ThemeCustomizerPanel, type ThemeCustomizerPanelProps, type ThemeInheritance, ThemePicker, type ThemePickerProps, type TimingJson, Toolbar, type ToolbarProps, TooltipLayer, type UseFileDropOptions, type UseFileDropResult, type UseImageEditorOptions, type UseImageEditorReturn, type UseMediaRecorderOptions, type UseMediaRecorderResult, VersionHistoryPanel, ViewMenuPanel, type ViewPreferences, ViewSwitcher, type ViewSwitcherProps, WysiwygEditor, type WysiwygEditorProps, buildFilename, buildPreviewDoc, buildTimingJson, classifyFile, detectLanguageFromFileName, encodeTimingJson, getCaptureKind, imageEditorReducer, initialImageEditorState, markdownToTiptap, partitionFiles, processMediaFiles, processTextFile, processTextFiles, requestCameraStream, requestMicStream, requestScreenStream, resolveFileKind, resolveFormat, searchEmojis, supportsDisplayMedia, supportsMediaRecorder, supportsUserMedia, templateLabel, timingPathFor, tiptapToMarkdown, useEditorContext, useFileDrop, useImageEditor, useMediaRecorder, usePreviewSettings, useStreamPreview };