@bendyline/squisq-editor-react 1.6.0 → 1.6.1

package/dist/index.d.ts

@@ -7,11 +7,12 @@ import { ContentContainer } from '@bendyline/squisq/storage';
 import { DocumentVersionManager, SaveVersionOptions, SaveVersionResult, PrunePolicy } from '@bendyline/squisq/versions';
 import * as _tiptap_core from '@tiptap/core';
 import { Editor, Extension } from '@tiptap/core';
+import * as monaco_editor from 'monaco-editor';
 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 { Editor as Editor$1 } from '@tiptap/react';
+import * as _tiptap_extension_heading from '@tiptap/extension-heading';
 import { Node } from '@tiptap/pm/model';
 import { SquisqAnnotatedSchema, JsonFormValidator, JsonFormValidationError } from '@bendyline/squisq/jsonForm';
 import { ImageEditExportFormat, ImageEditVersionManager } from '@bendyline/squisq/imageEdit';
@@ -90,7 +91,13 @@ interface DocumentLinkCandidate {
  */
 type DocumentLinkProvider = (query: string) => Promise<DocumentLinkCandidate[]>;
 type EditorView = 'raw' | 'wysiwyg' | 'preview';
-type EditorTheme = 'light' | 'dark';
+/**
+ * Light/dark chrome mode for the editor shell (toolbar, tabs, status bar,
+ * side panes). This is the editor's *UI color scheme* — distinct from a
+ * Squisq `Theme` object, which styles the rendered document. Renamed from
+ * the former `EditorTheme` to remove that ambiguity.
+ */
+type EditorColorScheme = 'light' | 'dark';
 /**
  * Document layout mode. `'document'` shows the whole markdown document in
  * the active view (the historical behavior). `'block'` is the
@@ -126,8 +133,8 @@ interface EditorState {
     parseError: string | null;
     /** Whether a parse is pending */
     isParsing: boolean;
-    /** Current color theme */
-    theme: EditorTheme;
+    /** Current light/dark chrome color scheme for the editor shell. */
+    colorScheme: EditorColorScheme;
     /** Operating mode — 'markdown' for the full shell, 'code' for Monaco-only. */
     editorMode: EditorMode;
     /** Monaco language ID for the Raw editor. */
@@ -237,8 +244,8 @@ interface EditorActions {
     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;
+    /** Set the light/dark chrome color scheme for the editor shell. */
+    setColorScheme: (colorScheme: EditorColorScheme) => 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). */
@@ -340,8 +347,8 @@ interface EditorProviderProps {
     initialView?: EditorView;
     /** Article ID used when generating the Doc */
     articleId?: string;
-    /** Color theme */
-    theme?: EditorTheme;
+    /** Light/dark chrome color scheme for the editor shell. */
+    colorScheme?: EditorColorScheme;
     /**
      * Workspace-scoped `ContentContainer` for this document — the folder
      * holding the doc, its `_files/` sidecar, sibling documents, and any
@@ -476,7 +483,83 @@ interface ViewPreferences {
     /** Document vs. block-at-a-time layout. */
     layoutMode?: LayoutMode;
 }
-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, layoutMode, viewPreferences, onViewPreferencesChange, children, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
+declare function EditorProvider({ initialMarkdown, initialView, articleId, colorScheme: initialColorScheme, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, mediaProvider, imageDisplayMode, mentionProvider, documentLinkProvider, allowRecording, fileName, language, inlinePreview, showStatusBar, outline, blockTags, themeInheritance, layoutMode, viewPreferences, onViewPreferencesChange, children, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Host-supplied context sections rendered INSIDE the Monaco (raw/code)
+ * surface: collapsible markdown blurbs injected above anchor lines, plus an
+ * optional file-top summary. Squisq stays host-agnostic — anchors are plain
+ * line numbers, ids are opaque strings, links are intercepted via callback.
+ *
+ * Accessibility note: Monaco marks its view-zone layer `aria-hidden`, so
+ * sections are invisible to screen readers in v1.
+ */
+/**
+ * One host-supplied markdown blurb anchored above a line of the code buffer.
+ * Rendered as a compact one-line strip that expands in place to the full
+ * markdown body.
+ */
+interface CodeContextSection {
+    /**
+     * Stable identity used to reconcile zones across prop updates — e.g. a
+     * symbol id like 'resolveImportEdges@60'. Zones are diffed by id: same id +
+     * new line moves the zone; same id + new markdown re-renders in place; a
+     * new id creates a new zone.
+     */
+    id: string;
+    /**
+     * 1-based line the section renders ABOVE. Out-of-range values are clamped
+     * by Monaco. In editable buffers the zone rides Monaco's whitespace
+     * semantics — it shifts as lines are inserted/deleted above it and
+     * collapses onto the previous line if its anchor lines are deleted. Squisq
+     * never re-derives anchors from edits; the host re-supplies lines when it
+     * re-analyzes the file.
+     */
+    line: number;
+    /**
+     * Compact markdown for the collapsed strip. Rendered on one line (block
+     * structure flattened, overflow ellipsized). Links work here too and go
+     * through `onLinkClick`.
+     */
+    summaryMarkdown: string;
+    /**
+     * Full markdown body shown when expanded. Omit while still loading — the
+     * expanded view shows a muted loading row and fills in when a later prop
+     * update supplies it.
+     */
+    markdown?: string;
+    /** Start expanded. The user's toggle wins after first interaction. Default false. */
+    defaultExpanded?: boolean;
+}
+/** The full context dictionary passed to `EditorShell.codeContext`. */
+interface CodeContext {
+    /**
+     * Section pinned above line 1 (file summary). Rendered before any line-1
+     * `sections` entry. `line` is implicit.
+     */
+    fileTop?: Omit<CodeContextSection, 'line'>;
+    /** Line-anchored sections. Array order is preserved for equal lines. */
+    sections?: CodeContextSection[];
+    /**
+     * Extra URI schemes section links may use (e.g. `['gezel-nav']`).
+     * http/https/mailto/tel are always allowed; executable schemes
+     * (javascript:, data:) are never allowed regardless.
+     */
+    linkSchemes?: readonly string[];
+    /**
+     * Intercepts link clicks inside sections, receiving the href exactly as
+     * authored in the markdown. Return `false` to let the browser's default
+     * navigation proceed; any other return (or void) suppresses it. Fragment
+     * links of the form `#L<digits>` are handled natively by squisq (reveal
+     * that line in the editor) and never reach this callback. When omitted:
+     * http(s)/mailto links open normally, custom-scheme links do nothing.
+     */
+    onLinkClick?: (href: string, meta: {
+        sectionId: string;
+    }) => boolean | undefined;
+    /** Notified on expand/collapse — lets hosts lazy-load bodies on first expand. */
+    onToggleSection?: (sectionId: string, expanded: boolean) => void;
+}
 
 interface EditorShellProps {
     /** Initial markdown content */
@@ -490,8 +573,13 @@ interface EditorShellProps {
     basePath?: string;
     /** Called when markdown source changes */
     onChange?: (source: string) => void;
-    /** Color theme: 'light' or 'dark' (default: 'light') */
-    theme?: 'light' | 'dark';
+    /**
+     * Light/dark chrome color scheme for the editor shell — toolbar, tabs,
+     * status bar, and side panes (default: `'light'`). This is the editor's
+     * UI mode, **not** a Squisq `Theme` object; the rendered document's
+     * styling is controlled separately via `themeOverride` / `Doc.themeId`.
+     */
+    colorScheme?: 'light' | 'dark';
     /** Additional class name */
     className?: string;
     /** CSS height for the shell container (default: '100vh') */
@@ -586,6 +674,13 @@ interface EditorShellProps {
      * (Slack, Discord). When omitted, the editor behaves normally.
      */
     submitOnEnter?: () => void;
+    /**
+     * Host-supplied context dictionary rendered inside the Monaco (raw / code)
+     * surface: collapsible markdown sections injected above anchor lines, plus
+     * an optional file-top summary. See {@link CodeContext}. Ignored in
+     * WYSIWYG / preview / image surfaces.
+     */
+    codeContext?: CodeContext;
     /**
      * Let the WYSIWYG editing surface fill its container instead of rendering
      * as a centered 800px "page" column. Useful when embedding in chat
@@ -744,9 +839,11 @@ interface EditorShellProps {
      */
     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).
+     * Fixed width in pixels for the outline pane. When omitted, the pane sizes
+     * responsively — never narrower than 260px, growing with the window and
+     * capped at 460px — so it stretches out when there's horizontal space to
+     * spare. Only takes effect when {@link EditorShellProps.outline} is true (or
+     * the View menu has toggled it on).
      */
     outlineWidth?: number;
     /**
@@ -791,7 +888,18 @@ interface EditorShellProps {
  * Complete markdown editor shell with toolbar, view switcher, and three
  * editing modes: Raw (Monaco), WYSIWYG (Tiptap), and Preview.
  */
-declare function EditorShell({ initialMarkdown, initialView, 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;
+declare function EditorShell({ initialMarkdown, initialView, articleId, basePath, onChange, colorScheme, className, height, minHeight, maxHeight, mediaProvider, workspaceContainer, container, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, showFilesToggle, toolbarSlotLeft, toolbarSlotAfterActions, toolbarSlotRight, showPlayTab, submitOnEnter, codeContext, 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;
+
+/**
+ * Bridges a host-supplied {@link CodeContext} onto the live Monaco editor:
+ * owns a {@link CodeContextZoneManager} per editor instance, reconciles zones
+ * when the context prop changes, and portals a `CodeContextSectionView` into
+ * each zone's dom node. Mounted by EditorShell in code mode; also exported
+ * for hosts composing a custom shell around `RawEditor`.
+ */
+declare function CodeContextZones({ options }: {
+    options: CodeContext;
+}): react_jsx_runtime.JSX.Element | null;
 
 /**
  * One entry in a {@link FolderView} — a file or subfolder. Host-defined
@@ -1080,8 +1188,14 @@ declare function ImageViewer({ src, alt, className, theme }: ImageViewerProps):
  * Syncs changes back to EditorContext on every keystroke (debounced).
  */
 interface RawEditorProps {
-    /** Monaco editor theme (default: 'vs-dark') */
-    theme?: string;
+    /**
+     * Monaco editor theme name (default: `'vs'`). Accepts Monaco's built-in
+     * theme ids (`'vs'`, `'vs-dark'`, `'hc-black'`) — which are transparently
+     * mapped to the Squisq-tinted variants — or any custom theme registered
+     * via `monaco.editor.defineTheme`. This is the *code editor* color
+     * theme, distinct from the shell's light/dark `colorScheme`.
+     */
+    monacoTheme?: string;
     /** Show minimap (default: false) */
     minimap?: boolean;
     /** Font size in pixels (default: 14) */
@@ -1102,7 +1216,7 @@ interface RawEditorProps {
  * 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;
+declare function RawEditor({ monacoTheme, minimap, fontSize, wordWrap, className, submitOnEnter, readOnly, }: RawEditorProps): react_jsx_runtime.JSX.Element;
 
 /**
  * WysiwygEditor
@@ -1337,9 +1451,85 @@ interface ThemePickerProps {
 }
 declare function ThemePicker({ value, onChange, includeDefault, variant, ariaLabel, customThemes, onCreateCustom, onEditCustom, onDeleteCustom, }: ThemePickerProps): react_jsx_runtime.JSX.Element;
 
+interface CustomThemeContextValue {
+    /** Themes inlined into the current doc's frontmatter. */
+    docThemes: Theme[];
+    /** Themes the user has saved to their browser-local library. */
+    libraryThemes: Theme[];
+    /**
+     * Convenience: the union of doc + library, with library entries skipped
+     * when a doc theme of the same id already exists. Used by the picker so a
+     * single "Custom" section covers both sources without duplicates.
+     */
+    allThemes: Theme[];
+    /**
+     * Persist a theme into the current doc. Replaces any existing entry with
+     * the same `id`. Triggers the host's `onDocThemesChange` so the doc's
+     * frontmatter ends up updated.
+     */
+    upsertDocTheme: (theme: Theme) => void;
+    /** Persist a theme into the user's library (replaces by id). */
+    upsertLibraryTheme: (theme: Theme) => void;
+    /** Remove a doc-level theme by id. */
+    removeDocTheme: (id: string) => void;
+    /** Remove a library theme by id. */
+    removeLibraryTheme: (id: string) => void;
+    /**
+     * Apply a theme to the current doc. If the theme is already in the doc,
+     * this is a no-op. If it's only in the library, it's copied into the doc
+     * so SSR / export work. Returns the resolved definition so callers can
+     * also write the `squisq-theme` selection.
+     */
+    applyTheme: (theme: Theme) => Theme;
+}
+interface CustomThemeProviderProps {
+    /** The current doc's custom themes (from `Doc.customThemes`). */
+    docThemes: Theme[];
+    /**
+     * Callback the host uses to persist a new doc-theme list back into the doc
+     * (e.g. by writing the encoded payload into the markdown's
+     * `squisq-custom-themes` frontmatter key).
+     */
+    onDocThemesChange: (next: Theme[]) => void;
+    children: ReactNode;
+}
+declare function CustomThemeProvider({ docThemes, onDocThemesChange, children, }: CustomThemeProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook returning the current context. Returns null when no provider is
+ * mounted — callers can degrade to "no custom themes" rather than throwing,
+ * since the feature is optional.
+ */
+declare function useCustomThemes(): CustomThemeContextValue | null;
+
+/**
+ * useDocCustomThemes — read + persist the active doc's custom themes (the
+ * list inlined into the doc's frontmatter under `squisq-custom-themes`).
+ *
+ * The theme analog of `useDocCustomTemplates`. Both the CustomThemeProvider
+ * and any manager surface need the same two things: the current
+ * `Doc.customThemes` array and a way to write a new list back into the
+ * markdown source. Centralizing the frontmatter encoding here keeps call
+ * sites from drifting.
+ */
+
+interface DocCustomThemes {
+    /** Custom themes inlined in the active doc's frontmatter. */
+    docThemes: Theme[];
+    /**
+     * Persist a new custom-themes list back into the markdown source's
+     * frontmatter so the doc round-trips through save/load. The whole list is
+     * encoded as a single compact JSON string per the flat YAML frontmatter
+     * parser's constraint.
+     */
+    onDocThemesChange: (next: Theme[]) => void;
+}
+declare function useDocCustomThemes(): DocCustomThemes;
+
 /** Where a saved theme lands — mirrors `DesignerSaveTarget` for templates. */
 type ThemeSaveTarget = 'doc' | 'library';
 
+/** Caption selection: off, or one of the two enabled styles. */
+type CaptionMode = 'off' | CaptionStyle;
 interface PreviewSettings {
     activePreset: ViewportPreset;
     setSelectedPreset: (preset: ViewportPreset | null) => void;
@@ -1351,8 +1541,14 @@ interface PreviewSettings {
     activeTheme: Theme;
     activeTransformStyle: string;
     setSelectedTransformStyle: (id: string | null) => void;
+    /** The caption style used when captions are enabled. */
     activeCaptionStyle: CaptionStyle;
-    setSelectedCaptionStyle: (style: CaptionStyle | null) => void;
+    /** Whether captions are shown at all (the 'off' arm of the tri-state). */
+    activeCaptionsEnabled: boolean;
+    /** Set the caption mode: 'off' hides captions, 'standard'/'social' enable
+     *  that style. The single entry point so the toggle buttons persist in one
+     *  frontmatter write. */
+    setCaptionMode: (mode: CaptionMode) => void;
     /** User-authored themes (doc + browser library) for the picker's "Custom" group. */
     customThemes: Theme[];
     /** Open the custom-theme designer for a theme (or null to create a new one). */
@@ -1385,9 +1581,31 @@ interface PreviewSettingsProviderProps {
 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.
+ *
+ * Collapse is *progressive* (a priority-plus pattern): rather than switch the
+ * whole row in and out at a fixed window-width breakpoint, the controls
+ * measure how many of them actually fit in the width the toolbar gives them
+ * and keep that many inline, folding the rest — from the low-priority end of
+ * {@link CONTROL_KEYS} — into a single settings (gear) button's popover. As
+ * the toolbar widens or narrows, controls migrate one at a time between the
+ * inline row and the menu, so the available space is always well used and the
+ * row never wraps onto a second line.
  */
 declare function PreviewToolbarControls(): react_jsx_runtime.JSX.Element;
+/**
+ * Segmented display-mode switch (Video / Slideshow / Document / Page) rendered
+ * as four connected buttons on the left of the Play toolbar — the prominent,
+ * one-click counterpart to the old "Mode:" dropdown. Reads and writes the same
+ * `activeDisplayMode` in preview settings.
+ */
+declare function PreviewModeSwitch(): react_jsx_runtime.JSX.Element;
+/**
+ * Segmented aspect-ratio switch (16:9 / 1:1 / 9:16 / 4:3) rendered as connected
+ * icon buttons on the left of the Play toolbar, next to the mode switch — the
+ * one-click counterpart to the old "Format:" dropdown. Reads and writes the
+ * same `activePreset` in preview settings.
+ */
+declare function PreviewFormatSwitch(): react_jsx_runtime.JSX.Element;
 
 /**
  * ViewSwitcher
@@ -1412,6 +1630,10 @@ interface ToolbarProps {
     onToggleFiles?: () => void;
     /** Content rendered at the left edge of the toolbar, before the view tabs. */
     slotLeft?: ReactNode;
+    /** Content rendered immediately after the view tabs, on the left side of the
+     *  toolbar (before the formatting controls). Used for the preview mode
+     *  switch in Play view. */
+    slotAfterTabs?: 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. */
@@ -1428,7 +1650,7 @@ interface ToolbarProps {
  * - 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;
+declare function Toolbar({ className, showFiles, onToggleFiles, slotLeft, slotAfterTabs, slotAfterActions, slotRight, showPlayTab, }: ToolbarProps): react_jsx_runtime.JSX.Element;
 
 /**
  * VersionHistoryPanel
@@ -1457,17 +1679,12 @@ declare function VersionHistoryPanel(): react_jsx_runtime.JSX.Element | null;
  */
 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). */
+    /**
+     * Fixed width of the pane in pixels. When omitted, the pane sizes
+     * responsively from `--squisq-outline-width` (falling back to
+     * {@link OUTLINE_RESPONSIVE_WIDTH}) so it stretches on wider screens.
+     */
     width?: number;
     /** Optional CSS class for the outer container. */
     className?: string;
@@ -1868,6 +2085,155 @@ declare function processTextFile(file: File): Promise<string>;
  */
 declare function processTextFiles(files: File[]): Promise<string>;
 
+/**
+ * useMonacoLoader
+ *
+ * Idempotently dynamic-imports `monaco-editor` and points the
+ * `@monaco-editor/react` singleton loader at the bundled copy. Replaces
+ * the historical top-of-module `import * as monaco from 'monaco-editor';
+ * loader.config({ monaco })` pattern, which forced every consumer of
+ * `@bendyline/squisq-editor-react` — including ones that only import
+ * `JsonEditor` or a type — to drag in monaco's ~9MB worth of language
+ * services and workers at module evaluation time.
+ *
+ * Hosts that want the smallest possible bundle can keep aliasing
+ * `monaco-editor` to a slim entry as before; the behavior is identical
+ * once the dynamic import settles.
+ *
+ * The promise is cached at module scope so the first subscriber
+ * anywhere in the app pays the import cost and every later subscriber
+ * reuses the same settled value.
+ */
+interface UseMonacoLoaderResult {
+    /** The monaco namespace once loaded, or `null` while the import is in flight. */
+    monaco: typeof monaco_editor | null;
+    /** Flips to `true` after the import settles. Gate `<Editor>` / `<DiffEditor>` renders on this. */
+    ready: boolean;
+}
+/**
+ * Subscribe to the lazy-loaded monaco namespace. The first caller
+ * triggers `import('monaco-editor')` and configures the
+ * `@monaco-editor/react` loader; subsequent callers receive the same
+ * cached value.
+ */
+declare function useMonacoLoader(): UseMonacoLoaderResult;
+
+interface CustomTemplateContextValue {
+    /** Templates inlined into the current doc's frontmatter. */
+    docTemplates: CustomTemplateDefinition[];
+    /** Templates the user has saved to their browser-local library. */
+    libraryTemplates: CustomTemplateDefinition[];
+    /**
+     * Convenience: the union of doc + library, with library entries
+     * skipped when a doc template of the same name already exists.
+     * Used by the picker so a single "Custom" section covers both
+     * sources without duplicates.
+     */
+    allTemplates: CustomTemplateDefinition[];
+    /**
+     * Persist a template into the current doc. Replaces any existing
+     * entry with the same `name`. Triggers the host's
+     * `onDocTemplatesChange` so the doc's frontmatter ends up updated.
+     */
+    upsertDocTemplate: (def: CustomTemplateDefinition) => void;
+    /** Persist a template into the user's library (replaces by name). */
+    upsertLibraryTemplate: (def: CustomTemplateDefinition) => void;
+    /** Remove a doc-level template by name. */
+    removeDocTemplate: (name: string) => void;
+    /** Remove a library template by name. */
+    removeLibraryTemplate: (name: string) => void;
+    /**
+     * Apply a template to the current doc. If the template is already in
+     * the doc, this is a no-op. If it's only in the library, it's
+     * copied into the doc so SSR / export work. Returns the resolved
+     * definition so callers can also write the heading annotation.
+     */
+    applyTemplate: (def: CustomTemplateDefinition) => CustomTemplateDefinition;
+}
+interface CustomTemplateProviderProps {
+    /** The current doc's custom templates (from `Doc.customTemplates`). */
+    docTemplates: CustomTemplateDefinition[];
+    /**
+     * Callback the host uses to persist a new doc-template list back
+     * into the doc (e.g. by writing the encoded payload into the
+     * markdown's `squisq-custom-templates` frontmatter key).
+     */
+    onDocTemplatesChange: (next: CustomTemplateDefinition[]) => void;
+    children: ReactNode;
+}
+declare function CustomTemplateProvider({ docTemplates, onDocTemplatesChange, children, }: CustomTemplateProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook returning the current context. Returns null when no provider is
+ * mounted — callers can degrade to "no custom templates" rather than
+ * throwing, since the feature is optional.
+ */
+declare function useCustomTemplates(): CustomTemplateContextValue | null;
+
+/**
+ * useDocCustomTemplates — read + persist the active doc's custom
+ * templates (the list inlined into the doc's frontmatter under
+ * `squisq-custom-templates`).
+ *
+ * Both the WYSIWYG editor and the standalone Custom Layout Manager need
+ * the same two things: the current `Doc.customTemplates` array and a way
+ * to write a new list back into the markdown source. Centralizing the
+ * frontmatter encoding here keeps the two call sites from drifting.
+ */
+
+interface DocCustomTemplates {
+    /** Custom templates inlined in the active doc's frontmatter. */
+    docTemplates: CustomTemplateDefinition[];
+    /**
+     * Persist a new custom-templates list back into the markdown source's
+     * frontmatter so the doc round-trips through save/load. The whole list
+     * is encoded as a single base64-JSON string per the flat YAML
+     * frontmatter parser's constraint.
+     */
+    onDocTemplatesChange: (next: CustomTemplateDefinition[]) => void;
+}
+declare function useDocCustomTemplates(): DocCustomTemplates;
+
+/**
+ * Read diagram nodes + edges from the live Tiptap state.
+ *
+ * For a given parent heading position, walks the diagram section's child
+ * headings, builds synthetic `Block` objects from their text + Pandoc
+ * attributes, runs `computeDiagramLayout` from core to fill in missing
+ * positions, and returns the result in the shape React Flow consumes.
+ *
+ * The hook re-derives on every editor transaction — no caching layer
+ * means there's nothing to invalidate when the user types or the markdown
+ * is reloaded from disk.
+ */
+
+interface DiagramRFNode {
+    id: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: {
+        label: string;
+    };
+    type?: string;
+    /** Per-node width override (from the heading's `w=` Pandoc param). */
+    width?: number;
+    /** Per-node height override (from the heading's `h=` Pandoc param). */
+    height?: number;
+}
+interface DiagramRFEdge {
+    id: string;
+    source: string;
+    target: string;
+    label?: string;
+}
+interface DiagramData {
+    nodes: DiagramRFNode[];
+    edges: DiagramRFEdge[];
+    warnings: string[];
+}
+declare function useDiagramData(editor: Editor$1, parentPos: number): DiagramData;
+
 /**
  * Tiptap Bridge
  *
@@ -1955,47 +2321,6 @@ interface DiagramExtensionOptions {
 }
 declare const DiagramExtension: Extension<DiagramExtensionOptions, any>;
 
-/**
- * Read diagram nodes + edges from the live Tiptap state.
- *
- * For a given parent heading position, walks the diagram section's child
- * headings, builds synthetic `Block` objects from their text + Pandoc
- * attributes, runs `computeDiagramLayout` from core to fill in missing
- * positions, and returns the result in the shape React Flow consumes.
- *
- * The hook re-derives on every editor transaction — no caching layer
- * means there's nothing to invalidate when the user types or the markdown
- * is reloaded from disk.
- */
-
-interface DiagramRFNode {
-    id: string;
-    position: {
-        x: number;
-        y: number;
-    };
-    data: {
-        label: string;
-    };
-    type?: string;
-    /** Per-node width override (from the heading's `w=` Pandoc param). */
-    width?: number;
-    /** Per-node height override (from the heading's `h=` Pandoc param). */
-    height?: number;
-}
-interface DiagramRFEdge {
-    id: string;
-    source: string;
-    target: string;
-    label?: string;
-}
-interface DiagramData {
-    nodes: DiagramRFNode[];
-    edges: DiagramRFEdge[];
-    warnings: string[];
-}
-declare function useDiagramData(editor: Editor$1, parentPos: number): DiagramData;
-
 type DiagramCommand = {
     kind: 'moveNode';
     nodeId: string;
@@ -2231,8 +2556,8 @@ 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;
+    /** Which capture pipeline to use (default: `'mic'`). */
+    source?: RecorderSource;
     /**
      * Preferred MIME type override. When the browser supports it, this
      * wins over the default candidate list. When unset (or unsupported),
@@ -2309,7 +2634,7 @@ interface UseMediaRecorderResult {
  * (e.g. headless tests) can resolve a format up front.
  */
 declare function getCaptureKind(source: RecorderSource): CaptureKind;
-declare function useMediaRecorder(options: UseMediaRecorderOptions): UseMediaRecorderResult;
+declare function useMediaRecorder(options?: UseMediaRecorderOptions): UseMediaRecorderResult;
 
 interface RecorderModalProps {
     /** Required — recordings are written here. */
@@ -2732,4 +3057,4 @@ interface UseImageEditorReturn {
 }
 declare function useImageEditor(options: UseImageEditorOptions): UseImageEditorReturn;
 
-export { ALL_EMOJIS, BlockCardView, type BlockCardViewProps, type BlockNavigator, BlockPropertiesPopover, type BlockPropertiesPopoverProps, type BlockRange, type BlockSlice, type CameraStreamOptions, type CanvasRect, type CaptureKind, DiagramCanvas, type DiagramCommand, type DiagramData, DiagramExtension, type DiagramRFEdge, type DiagramRFNode, DiagramWidget, type DirectionModel, type DocumentLinkCandidate, type DocumentLinkProvider, DocumentSettingsDialog, type DocumentSettingsDialogProps, type DragContentType, type DropTarget, DropZoneOverlay, type DropZoneOverlayProps, EMOJI_CATEGORIES, EMPTY_TRANSITION, 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, type FolderEntry, FolderView, type FolderViewProps, HeadingWithTemplate, type ImageDisplayMode, ImageEditor, type ImageEditorAction, type ImageEditorProps, type ImageEditorState, type ImageEditorTool, ImageViewer, type ImageViewerProps, InlinePreviewGutter, type InlinePreviewGutterProps, JsonEditor, type JsonEditorProps, type LayoutMode, MediaBin, type MediaBinProps, type MediaClipPatch, 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, TRANSITION_ENTRIES, TRANSITION_GROUPS, TemplatePicker, ThemeCustomizerPanel, type ThemeCustomizerPanelProps, type ThemeInheritance, ThemePicker, type ThemePickerProps, TimelineTrack, type TimelineTrackProps, type TimingJson, Toolbar, type ToolbarProps, TooltipLayer, type TransitionCatalogEntry, type TransitionFields, type TransitionGroup, TransitionPicker, type TransitionPickerProps, type UseBlockNavigatorOptions, type UseFileDropOptions, type UseFileDropResult, type UseImageEditorOptions, type UseImageEditorReturn, type UseMediaRecorderOptions, type UseMediaRecorderResult, VersionHistoryPanel, ViewMenuPanel, type ViewPreferences, ViewSwitcher, type ViewSwitcherProps, WysiwygEditor, type WysiwygEditorProps, addConnection, addNode, buildFilename, buildPreviewDoc, buildTimingJson, classifyFile, detectLanguageFromFileName, encodeTimingJson, findTransitionEntry, formatSeconds, getBlockSlices, getCaptureKind, imageEditorReducer, initialImageEditorState, lineToOffset, listDiagramChildren, markdownToTiptap, moveNode, offsetToLine, partitionFiles, processMediaFiles, processTextFile, processTextFiles, readBlockAttrsParams, readBlockAttrsTransition, readBlockAttrsValue, readHeadingLineTransition, removeConnection, removeNode, renameNode, requestCameraStream, requestMicStream, requestScreenStream, resolveFileKind, resolveFormat, searchEmojis, setBlockAttrsTransition, setBlockAttrsValue, setBlockDurationInSource, setHeadingLineTransition, setMediaClipInSource, sliceIndexAtOffset, spliceBlock, summarizeBlockProps, supportsDisplayMedia, supportsMediaRecorder, supportsUserMedia, templateLabel, timingPathFor, tiptapToMarkdown, transitionLabel, useBlockNavigator, useDiagramData, useEditorContext, useFileDrop, useImageEditor, useMediaRecorder, usePreviewSettings, useStreamPreview };
+export { ALL_EMOJIS, BlockCardView, type BlockCardViewProps, type BlockNavigator, BlockPropertiesPopover, type BlockPropertiesPopoverProps, type BlockRange, type BlockSlice, type CameraStreamOptions, type CanvasRect, type CaptureKind, type CodeContext, type CodeContextSection, CodeContextZones, type CustomTemplateContextValue, CustomTemplateProvider, type CustomTemplateProviderProps, type CustomThemeContextValue, CustomThemeProvider, type CustomThemeProviderProps, DiagramCanvas, type DiagramCommand, type DiagramData, DiagramExtension, type DiagramRFEdge, type DiagramRFNode, DiagramWidget, type DirectionModel, type DocCustomTemplates, type DocCustomThemes, type DocumentLinkCandidate, type DocumentLinkProvider, DocumentSettingsDialog, type DocumentSettingsDialogProps, type DragContentType, type DropTarget, DropZoneOverlay, type DropZoneOverlayProps, EMOJI_CATEGORIES, EMPTY_TRANSITION, type EditorActions, type EditorColorScheme, type EditorContextValue, type EditorMode, EditorProvider, type EditorProviderProps, EditorShell, type EditorShellProps, type EditorState, type EditorView, type EmojiCategory, type EmojiEntry, EmojiPicker, type EmojiPickerProps, type FileCategory, type FileKind, type FolderEntry, FolderView, type FolderViewProps, HeadingWithTemplate, type ImageDisplayMode, ImageEditor, type ImageEditorAction, type ImageEditorProps, type ImageEditorState, type ImageEditorTool, ImageViewer, type ImageViewerProps, InlinePreviewGutter, type InlinePreviewGutterProps, JsonEditor, type JsonEditorProps, type LayoutMode, MediaBin, type MediaBinProps, type MediaClipPatch, type MentionCandidate, type MentionProvider, OutlinePanel, type OutlinePanelProps, PlainHtmlPreview, type PlainHtmlPreviewProps, PreviewFormatSwitch, PreviewModeSwitch, 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, TRANSITION_ENTRIES, TRANSITION_GROUPS, TemplatePicker, ThemeCustomizerPanel, type ThemeCustomizerPanelProps, type ThemeInheritance, ThemePicker, type ThemePickerProps, TimelineTrack, type TimelineTrackProps, type TimingJson, Toolbar, type ToolbarProps, TooltipLayer, type TransitionCatalogEntry, type TransitionFields, type TransitionGroup, TransitionPicker, type TransitionPickerProps, type UseBlockNavigatorOptions, type UseFileDropOptions, type UseFileDropResult, type UseImageEditorOptions, type UseImageEditorReturn, type UseMediaRecorderOptions, type UseMediaRecorderResult, type UseMonacoLoaderResult, VersionHistoryPanel, ViewMenuPanel, type ViewPreferences, ViewSwitcher, type ViewSwitcherProps, WysiwygEditor, type WysiwygEditorProps, addConnection, addNode, buildFilename, buildPreviewDoc, buildTimingJson, classifyFile, detectLanguageFromFileName, encodeTimingJson, findTransitionEntry, formatSeconds, getBlockSlices, getCaptureKind, imageEditorReducer, initialImageEditorState, lineToOffset, listDiagramChildren, markdownToTiptap, moveNode, offsetToLine, partitionFiles, processMediaFiles, processTextFile, processTextFiles, readBlockAttrsParams, readBlockAttrsTransition, readBlockAttrsValue, readHeadingLineTransition, removeConnection, removeNode, renameNode, requestCameraStream, requestMicStream, requestScreenStream, resolveFileKind, resolveFormat, searchEmojis, setBlockAttrsTransition, setBlockAttrsValue, setBlockDurationInSource, setHeadingLineTransition, setMediaClipInSource, sliceIndexAtOffset, spliceBlock, summarizeBlockProps, supportsDisplayMedia, supportsMediaRecorder, supportsUserMedia, templateLabel, timingPathFor, tiptapToMarkdown, transitionLabel, useBlockNavigator, useCustomTemplates, useCustomThemes, useDiagramData, useDocCustomTemplates, useDocCustomThemes, useEditorContext, useFileDrop, useImageEditor, useMediaRecorder, useMonacoLoader, usePreviewSettings, useStreamPreview };