@elabs-ai/components-editor 4.0.0

package/dist/markdown/index.d.ts

@@ -0,0 +1,1486 @@
+import { S as SlashCommand, I as IterationEditHandler, c as EditorSelection, E as EditorContentAccess, h as EditorCompletionProvider, M as MonacoCodeEditor, i as CalcEditorHooks, d as EmbedAssetFn, j as EvaluateCalc, k as CalcValue, l as CalcTokenKind } from '../markdown-editor-DfBZibAn.js';
+export { B as BRAND_SLASH_COMMANDS, n as BasicBlockId, o as CALC_FENCE_SEED, p as CalcComplete, q as CalcCompletion, r as CalcCompletionContext, s as CalcCompletionKind, t as CalcContext, u as CalcLineResult, v as CalcRule, w as CalcSheet, x as CalcTint, y as CalcToken, z as CalcTokenize, A as CalcValueKind, D as CompletionMatch, F as CompletionReplaceRange, G as EditorCompletionContext, H as EditorCompletionItem, J as InsertableDirective, K as IterationEditContext, L as IterationEditRequest, e as MarkdownEditor, f as MarkdownEditorHandle, g as MarkdownEditorProps, N as SlashInsertContext, O as SlashRange, P as SourceSlashContext, Q as collectCompletions, R as filterSlashCommands, T as groupSlashCommands, U as insertBasicBlock, V as insertBrandDirective, W as insertCalcFence, m as monacoContentAccess, X as resolveCalcInsert, Y as resolveReplaceRange, Z as triggerQueryStart } from '../markdown-editor-DfBZibAn.js';
+import { MilkdownPlugin } from '@milkdown/kit/ctx';
+import { EditorView } from '@milkdown/kit/prose/view';
+import * as monaco from 'monaco-editor';
+import { IRange } from 'monaco-editor';
+import { useWidgetViewFactory } from '@prosemirror-adapter/react';
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+import { MetricCardProps, BentoGridSize, ProseHeadingLevel } from '@elabs-ai/components-ui';
+export { ProseBlockquote as Blockquote, ProseHeading as Heading, ProseHeadingLevel as HeadingLevel, ProseHeadingProps as HeadingProps, ProseInlineCode as InlineCode, ProseLink as Link, ProseLinkProps as LinkProps, ProseList as List, ProseListItem as ListItem, ProseListProps as ListProps, ProseText as Text, ProseTextProps as TextProps, Timeline, TimelineEntry as TimelineItem, TimelineProps } from '@elabs-ai/components-ui';
+import { PluggableList } from 'unified';
+import { Root } from 'mdast';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import '@milkdown/kit/prose/model';
+import '@milkdown/kit/prose/state';
+
+/**
+ * The brand slash-menu Milkdown plugin (the ProseMirror half).
+ *
+ * A self-owned raw ProseMirror plugin (`$prose`) — NOT `@milkdown/kit/plugin/slash`
+ * — so the editor pulls zero new dependencies and we keep full control of the
+ * interaction. It owns the STATE and the KEYBOARD; the React widget
+ * (slash-widget.tsx) owns the rendered popup. They share one
+ * {@link SlashController} (the command list + a Milkdown `Ctx` getter + the
+ * insert/close helpers), built once in `MarkdownEditorView` so both the plugin's
+ * Enter handler and the widget's click handler run a command the SAME way.
+ *
+ * Responsibilities here:
+ *   1. Detect a `/` typed at a textblock START or after whitespace; track
+ *      `{ active, from, query, index }` as the user keeps typing (a literal `/`
+ *      mid-word is never hijacked; a space ends the query).
+ *   2. Render the React `<SlashMenu>` as a ProseMirror WIDGET decoration at the
+ *      caret (via the `useWidgetViewFactory()` factory passed in).
+ *   3. ↑/↓ move the selection, Enter inserts the active command (replacing the
+ *      `/query` range), Esc / deleting the `/` closes.
+ */
+
+/**
+ * The factory `useWidgetViewFactory()` returns: `(options) => (pos, spec?) =>
+ * Decoration`. We borrow the exact type from the hook so we never name the
+ * (un-re-exported) `@prosemirror-adapter/core` internals.
+ */
+type SlashWidgetFactory = ReturnType<typeof useWidgetViewFactory>;
+
+interface SlashMenuProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    /** The (already filtered) commands to show. */
+    commands: SlashCommand[];
+    /** The id of the active (highlighted) command, for `aria-selected`. */
+    activeId?: string;
+    /** Called when a command is chosen (click or via the plugin's Enter). */
+    onSelect: (command: SlashCommand) => void;
+    /** DOM id prefix so each option id is stable + unique (matches `aria-activedescendant`). */
+    idPrefix?: string;
+    /** Shown when the query matches nothing. */
+    emptyLabel?: string;
+}
+declare const SlashMenu: react.ForwardRefExoticComponent<SlashMenuProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Brand slash-menu — public surface for the WYSIWYG markdown editor.
+ *
+ * Typing `/` at a block start (or after whitespace) opens a branded command menu
+ * that inserts the brand `:::` directives + basic blocks live in the editor. The
+ * load-bearing pieces:
+ *   - `brand-slash-commands` — the typed, tree-shakeable command registry.
+ *   - `insert-directive` — the pure ProseMirror insertion commands (unit-tested).
+ *   - `brand-slash-plugin` — the `$prose` plugin (state + keyboard).
+ *   - `slash-widget` / `slash-menu` — the React widget + the branded popup.
+ *
+ * `brandSlashViewPlugins(widgetFactory, options)` wires it all together — call it
+ * with the factory from `useWidgetViewFactory()` (so it runs under
+ * `<ProsemirrorAdapterProvider>`), exactly like `directiveViewPlugins`.
+ */
+
+/** Options for {@link brandSlashViewPlugins}. */
+interface BrandSlashViewOptions {
+    /** Override the default command list. */
+    commands?: SlashCommand[];
+    /** The trigger character. Defaults to `"/"`. */
+    trigger?: string;
+    /**
+     * Keyboard shortcut that opens the menu at the caret in BOTH panes (#271).
+     * Defaults to `DEFAULT_SLASH_SHORTCUT` (`"Mod-Shift-O"`). Set to `undefined` or
+     * an empty string to disable the shortcut binding.
+     */
+    shortcut?: string;
+    /**
+     * Resolve the live `IterationEditContext` handler (#223, internal —
+     * `MarkdownEditorView` wires this from `useContext`). When present, a
+     * `guided` command (`/iterate` `/pivot`) opens its modal instead of a bare
+     * insert. Not part of the public `slashMenu` prop surface.
+     */
+    getIterationEditHandler?: () => IterationEditHandler | null | undefined;
+}
+/**
+ * Build the slash-menu Milkdown plugins. Call with the widget factory from
+ * `useWidgetViewFactory()` (must run inside a `<ProsemirrorAdapterProvider>`),
+ * then `.use()` the result on the editor.
+ */
+declare function brandSlashViewPlugins(widgetFactory: SlashWidgetFactory, options?: BrandSlashViewOptions): MilkdownPlugin[];
+
+/**
+ * ProseMirror / Milkdown adapter for the engine-agnostic EditorContentAccess.
+ *
+ * ISOLATION: this file is MARKDOWN-ONLY — it imports `@milkdown/kit/*` at runtime.
+ * It is exported ONLY from `packages/editor/src/markdown/index.ts` (`./markdown`
+ * subpath) and NEVER from `src/index.ts` (`.` barrel), so `@milkdown` never leaks
+ * into the Monaco-only graph (#271-inverse). The TYPES from `editor-content-access`
+ * are type-erased imports — no runtime edge back to the monaco file.
+ */
+
+interface ProseMirrorContentAccessOptions {
+    /** "markdown" (default) round-trips formatting; "plainText" uses raw text only. */
+    fidelity?: "markdown" | "plainText";
+}
+/**
+ * Dependency-injected shape for the Milkdown content-access adapter.
+ *
+ * The handle owns the serialize/parse closures (built via `getInstance().action(ctx
+ * => ...)`) and passes them here. This keeps the adapter free of `Ctx` token
+ * plumbing and matches the `readBodyMarkdown`/`writeBodyMarkdown` technique in
+ * `directive-views.tsx` exactly.
+ */
+interface ProseMirrorContentAccessDeps {
+    /** Return the live `EditorView`, or null while the engine is booting. */
+    getView: () => EditorView | null;
+    /** Return the full document serialized to markdown. */
+    getText: () => string;
+    /**
+     * Serialize the CURRENT selection's slice to markdown (or "" for a collapsed
+     * selection). Built by the handle from `serializerCtx`.
+     */
+    serializeSlice: (view: EditorView) => string;
+    /**
+     * Parse `md` as a markdown fragment and replace the current selection with the
+     * parsed content. On parse failure degrades to a plain-text insert. Built by
+     * the handle from `parserCtx`.
+     */
+    parseAndReplace: (view: EditorView, md: string) => void;
+    /**
+     * The registered `onSelectionChange` listeners set. Shared between the adapter
+     * and the `selectionWatchPlugin` so the plugin can notify subscribers without
+     * coupling to the adapter instance.
+     */
+    listeners: Set<(sel: EditorSelection) => void>;
+}
+/**
+ * Build the ProseMirror selection-watch plugin as a Milkdown `$prose` plugin.
+ * Compares `prevState.selection` to `view.state.selection` on every transaction and
+ * notifies listeners in the shared `listeners` set when they differ.
+ *
+ * Add to the editor `.use(...)` chain ONCE (always-present; the listeners set is
+ * populated / depopulated at subscription time — no per-subscription state in the
+ * plugin). Follows the `calcProsePlugins` pattern exactly.
+ *
+ * @param getListeners - Thunk returning the current listener set. Using a thunk
+ *   (rather than the set directly) lets the adapter swap the set out if needed —
+ *   in practice the set is stable; the thunk keeps this composable.
+ * @param getSerializeSlice - Thunk: serialize the current selection → markdown.
+ */
+declare function selectionWatchPlugin(getListeners: () => Set<(sel: EditorSelection) => void>, getSerializeSlice: () => (view: EditorView) => string): MilkdownPlugin;
+/**
+ * Wrap a Milkdown ProseMirror view as {@link EditorContentAccess}.
+ *
+ * Receives dependency-injected closures (`serializeSlice`, `parseAndReplace`) that
+ * the `MarkdownEditorHandle` builds via `getInstance().action(ctx => ...)`, reusing
+ * the `serializerCtx`/`parserCtx` round-trip already shipped in `directive-views.tsx`.
+ *
+ * The `selectionWatchPlugin` must be added to the editor's `.use(...)` chain so it
+ * is installed when the editor boots. The `deps.listeners` set is shared between the
+ * plugin and this adapter.
+ *
+ * Markdown fidelity (default): selection → markdown, incoming text parsed as
+ * markdown fragment, with a graceful plain-text fallback on parse failure.
+ * Normalization (the WI-1 lesson): the serializer may re-emit formatting differently
+ * (e.g. `*` vs `_`). This is the same normalization the WYSIWYG editor applies on
+ * every keystroke — consistent, not new. For raw text use `plainText`.
+ *
+ * D5: content manipulation only — no model/transport.
+ */
+declare function proseMirrorContentAccess(deps: ProseMirrorContentAccessDeps, options?: ProseMirrorContentAccessOptions): EditorContentAccess;
+
+/**
+ * Monaco registration lifecycle for the declarative completion-provider API
+ * (#283) — the engine that backs the `completions` prop on `MarkdownWorkspace`.
+ *
+ * `monaco.languages.registerCompletionItemProvider` is GLOBAL PER LANGUAGE, not
+ * per editor instance (the root cause #283 exists to fix — see the issue). So
+ * this module owns a single, REFCOUNTED registration for the "markdown"
+ * language: the first `attachCompletionsMonaco` call registers it, each
+ * subsequent call (a second mounted `MarkdownWorkspace`) bumps the refcount,
+ * and the registration is disposed ONLY when the LAST attached editor's
+ * disposer runs — no leak, no double-registration (#283 acceptance).
+ *
+ * Suggestions are scoped to the models THIS module attached (a `REGISTRY` keyed
+ * by `ITextModel`) — any other "markdown" model in the app (one the host built
+ * itself, outside `@elabs-ai/components-editor`) is ignored, never suggested into.
+ *
+ * `getProviders` is read fresh from the registry on every `provideCompletionItems`
+ * call — NOT captured as a closure at registration time — so a rebuilt provider
+ * list (a new `completions` array identity from React state/props) is picked up
+ * WITHOUT re-registering (#283 acceptance). Mirrors the calc layer's
+ * `REGISTRY`/`getHooks` pattern in `calc-block/calc-editor-monaco.ts`.
+ */
+
+/** Resolver of the latest provider list for a model (read fresh on every call). */
+type ProvidersGetter = () => EditorCompletionProvider[] | undefined;
+/**
+ * Attach the declarative completion providers to a Monaco editor instance.
+ * `getProviders` is read live on every suggestion request (see module doc) —
+ * pass a ref-backed getter so a fresh `completions` array identity on every
+ * render never forces a re-attach.
+ *
+ * Also force-opens Monaco's native suggest widget (`editor.action.triggerSuggest`)
+ * whenever the user types a character matching one of the CURRENTLY-configured
+ * providers' `triggerCharacters` — read live, so changing that set never needs a
+ * re-registration either. Markdown punctuation like `[` doesn't extend a "word",
+ * so without this Monaco's own quick-suggestions heuristic would never invoke a
+ * provider on it.
+ *
+ * Returns a disposer. Call it on unmount / when `completions` is removed —
+ * refcounted, so the GLOBAL "markdown" registration is only torn down once the
+ * LAST attached editor calls its disposer (#283 acceptance: no leak, no
+ * double-registration with two workspaces mounted).
+ */
+declare function attachCompletionsMonaco(editor: monaco.editor.IStandaloneCodeEditor, getProviders: ProvidersGetter): () => void;
+
+interface MonacoSlashMenuProps {
+    /** The live Monaco editor instance (source pane). */
+    editor: MonacoCodeEditor;
+    /**
+     * Commands to show in the source pane — filtered by the workspace to
+     * `snippet != null || typeof runInSource === "function"` (#299): a command
+     * needs a text snippet, a source-pane handler, or both to appear here (a
+     * run-only WYSIWYG command with neither is Milkdown-only and stays excluded).
+     */
+    commands: SlashCommand[];
+    /** Controlled open state — the workspace toggles it via the Layer-1 action. */
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /**
+     * Insert the selected snippet at the Monaco caret + refocus.
+     * Defaults to `insertDirective` from `markdown-commands.ts`.
+     */
+    onInsert?: (editor: MonacoCodeEditor, snippet: string) => void;
+    /**
+     * When the menu was opened by typing `/` (not the hotkey), the model range of
+     * that `/`. On select the `/` is REPLACED by the inserted block; on cancel
+     * (Escape / Backspace past the trigger) it is removed. `null`/omitted = the
+     * hotkey path, which inserts via `onInsert`/`insertDirective` and leaves the
+     * document otherwise untouched.
+     */
+    triggerRange?: IRange | null;
+    /** Merged onto the positioned popup container (the inline `position:fixed` anchor stays). */
+    className?: string;
+}
+declare function MonacoSlashMenu({ editor, commands, open, onOpenChange, onInsert, triggerRange, className, }: MonacoSlashMenuProps): react.JSX.Element | null;
+
+type MarkdownWorkspaceMode = "source" | "wysiwyg" | "split";
+/**
+ * Imperative handle exposed via `MarkdownWorkspace`'s `ref` (#273, DECISION A).
+ *
+ * Migration note: the forwarded ref type changed from `HTMLDivElement` to this
+ * handle. Replace any `ref.current` DOM access with `ref.current?.getElement()`.
+ *
+ * Extends {@link EditorContentAccess} — all AI content-access methods delegate to
+ * the active engine: Monaco (source/split) or the Milkdown WYSIWYG handle.
+ *
+ * **`onSelectionChange` caveat:** the subscription is scoped to the engine active at
+ * call time. A mode switch (source ↔ wysiwyg) does NOT auto-rebind the listener —
+ * re-subscribe from an effect whose deps include the mode. A self-rebinding v2 is a
+ * noted future enhancement, out of v1 scope.
+ */
+interface MarkdownWorkspaceHandle extends EditorContentAccess {
+    /**
+     * Scroll the active editor so FULL-SOURCE 1-based `line` is visible (Monaco
+     * coordinates). No-op (never throws) while the engine is booting or `line` is
+     * out of range. In WYSIWYG it is best-effort: resolves the nearest preceding
+     * heading via `parseMarkdownOutline` + `fmOffset`, then delegates to
+     * `scrollToHeading`. No-op if no preceding heading found.
+     */
+    revealLine(line: number, opts?: {
+        center?: boolean;
+    }): void;
+    /**
+     * Scroll to a heading by its outline slug (same slugs as `DocumentOutline` /
+     * `useMarkdownOutline` / `parseMarkdownOutline`). In Source/Split mode
+     * resolves the line via `parseMarkdownOutline` then calls `revealLine`. In
+     * WYSIWYG delegates to the `MarkdownEditorHandle.scrollToHeading`.
+     */
+    scrollToHeading(slug: string): void;
+    /**
+     * The live Monaco source editor instance, or `null` when not mounted or when
+     * the active mode is `"wysiwyg"` (source pane not rendered).
+     */
+    getEditor(): MonacoCodeEditor | null;
+    /**
+     * The workspace root DOM element. Preserves the old `HTMLDivElement` ref
+     * access that existed before DECISION A (ref type change in #273).
+     */
+    getElement(): HTMLDivElement | null;
+}
+interface MarkdownWorkspaceProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (markdown: string) => void;
+    mode?: MarkdownWorkspaceMode;
+    defaultMode?: MarkdownWorkspaceMode;
+    onModeChange?: (mode: MarkdownWorkspaceMode) => void;
+    /**
+     * Start with FOCUS WRITING on (wysiwyg mode): typewriter scrolling keeps
+     * the caret vertically centered and inactive paragraphs dim. Toggleable in
+     * the editor's mode row.
+     */
+    defaultFocusWriting?: boolean;
+    /**
+     * The `/` command menu in the WYSIWYG (preview-edit) pane AND the Monaco source
+     * pane. `true` (default) uses the built-in brand commands; pass a config to
+     * extend/replace them, or `false` to disable. Forwarded to {@link MarkdownEditor}.
+     *
+     * `shortcut` (default `"Mod-Shift-O"`) opens the menu at the caret in BOTH panes —
+     * in the WYSIWYG pane via the ProseMirror plugin's `handleKeyDown`, and in the
+     * source/split pane via a `CodeEditor` action (no `/` is inserted into the
+     * doc). (#271)
+     */
+    slashMenu?: boolean | {
+        commands?: SlashCommand[];
+        trigger?: string;
+        shortcut?: string;
+    };
+    /**
+     * Customize the source / split toolbar's **Insert** menu (A4). Defaults to the
+     * same commands as the WYSIWYG slash menu (so `/calc`, `/iterate`, `/pivot` and
+     * any consumer commands are insertable in source mode too). Only commands with
+     * a `snippet` appear; pass your own list to override.
+     */
+    insertCommands?: SlashCommand[];
+    /**
+     * Opt-in calc authoring inside ```calc fences (off by default). Wired to BOTH
+     * surfaces: the Monaco source pane (highlight + autocomplete + result inlays)
+     * and the WYSIWYG pane (highlight + result inlays). Supply the consumer's
+     * `tokenize` / `evaluate` / `complete` hooks; the library bundles no calc engine.
+     */
+    calc?: CalcEditorHooks;
+    /**
+     * Declarative completion providers (#283) — e.g. `[[wikilink]]` autocomplete.
+     * Off by default; mirrors the `slashMenu`/`calc` opt-in pattern. The library
+     * owns the Monaco `registerCompletionItemProvider` registration lifecycle
+     * (registered once, refcounted across mounted workspaces, disposed with the
+     * last one — see `lib/editor-completions-monaco.ts`) for the Source/Split
+     * panes, and mirrors providers into the WYSIWYG pane via `MarkdownEditor`'s
+     * `completions` prop (a deliberately minimal mirror — see
+     * `markdown-editor/completions/completions-prose.ts` for the exact gaps).
+     * Zero `monaco-editor` imports needed in consumer code.
+     */
+    completions?: EditorCompletionProvider[];
+    /**
+     * Host-provided callback for image paste/drop embedding in the WYSIWYG pane.
+     * Forwarded to {@link MarkdownEditor}. See `MarkdownEditorProps.onEmbedAsset`
+     * for the full contract.
+     */
+    onEmbedAsset?: EmbedAssetFn;
+    /**
+     * Show the built-in "Focus writing" toggle in the WYSIWYG (preview-edit)
+     * toolbar row. `false` HIDES and DISABLES it (no keyboard path) and forces
+     * focus-writing OFF. `undefined`/`true` keep current behavior. The INITIAL
+     * on/off state still comes from `defaultFocusWriting`. (#270)
+     */
+    focusWriting?: boolean;
+    /**
+     * Show the built-in Source / Split / Preview-edit mode switch. `false` hides
+     * it in both toolbar branches so the host owns the view switch (controlled
+     * `mode`/`onModeChange` still drive the panes). Default `true`. (#272)
+     */
+    modeSwitch?: boolean;
+    /**
+     * Host-supplied controls rendered in the toolbar's trailing slot (where the
+     * built-in mode switch sits). Use with `modeSwitch={false}` to supply your
+     * own switch / actions. (#272)
+     */
+    toolbarActions?: ReactNode;
+}
+declare const MarkdownWorkspace: react.ForwardRefExoticComponent<MarkdownWorkspaceProps & react.RefAttributes<MarkdownWorkspaceHandle>>;
+
+interface MarkdownToolbarProps extends HTMLAttributes<HTMLDivElement> {
+    /** The Monaco editor instance to act on (from CodeEditor ref/onMount). */
+    editor: MonacoCodeEditor | null;
+    /** Extra controls rendered on the right (e.g. a mode switch). */
+    actions?: ReactNode;
+    /**
+     * Drives the **Insert** menu. When set, the menu lists every command that
+     * carries a `snippet` (grouped by `group`), inserting that markdown at the
+     * caret — so the source / split pane reaches the SAME blocks as the WYSIWYG
+     * slash menu (`/calc`, `/iterate`, `/pivot`, plus any consumer commands).
+     * When omitted, the menu falls back to the four built-in directive snippets.
+     * (A4)
+     */
+    insertCommands?: SlashCommand[];
+}
+declare const MarkdownToolbar: react.ForwardRefExoticComponent<MarkdownToolbarProps & react.RefAttributes<HTMLDivElement>>;
+
+/** Wrap the current selection (or insert a placeholder) with `before`/`after`. */
+declare function wrapSelection(editor: MonacoCodeEditor, before: string, after?: string, placeholder?: string): void;
+/** Toggle a line prefix (`# `, `> `, `- `, `1. `) on every selected line. */
+declare function toggleLinePrefix(editor: MonacoCodeEditor, prefix: string): void;
+/** Insert `[selection](url)` (or a placeholder link). */
+declare function insertLink(editor: MonacoCodeEditor): void;
+/** Insert a horizontal rule on its own line below the cursor. */
+declare function insertHorizontalRule(editor: MonacoCodeEditor): void;
+/** Insert a brand directive block at the cursor (e.g. card/callout/metric/timeline). */
+declare function insertDirective(editor: MonacoCodeEditor, snippet: string): void;
+
+type MarkdownHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Canonical heading font-size per level, in rem — derived from the @elabs-ai/components-ui
+ * prose reading scale (h2/h4/h5/h6 == the title/subtitle/body role rems;
+ * h1/h3 are intermediate reading rungs).
+ */
+declare const MARKDOWN_HEADING_REM: Record<MarkdownHeadingLevel, number>;
+/** Canonical heading weight (Tailwind `font-semibold`) — derived from @elabs-ai/components-ui. */
+declare const MARKDOWN_HEADING_WEIGHT = 600;
+/** Canonical heading letter-spacing (Tailwind `tracking-tight`) — derived from @elabs-ai/components-ui. */
+declare const MARKDOWN_HEADING_TRACKING = "-0.025em";
+/** Canonical reading measure (max content width). Mirrors `max-w-3xl`. */
+declare const MARKDOWN_MEASURE = "48rem";
+/**
+ * The scale as CSS custom properties, to set on the editor host (`.milkdown-host`)
+ * so `markdown-editor.css` reads the SAME numbers as the prose components instead of
+ * hardcoding its own. Spread onto a `style` prop:
+ *   `<div className="milkdown-host" style={markdownScaleVars()} />`
+ */
+declare function markdownScaleVars(): Record<string, string>;
+
+type MetricBlockProps = MetricCardProps;
+declare const MetricBlock: react.ForwardRefExoticComponent<MetricCardProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Shared remark pipeline for the brand markdown dialect.
+ *
+ * `remark-directive` parses generic container/leaf/text directives (`:::name`,
+ * `::name`, `:name`). `remarkBrandDirectives` then rewrites the four brand blocks
+ * — :::card / :::callout / ::metric / :::timeline — into a single `<brand-directive>`
+ * element carrying a JSON `data-brand` payload, which the preview's components map
+ * turns into real @brand components. Unknown directive names are preserved + flagged
+ * so the preview can surface an "unknown block" error instead of silently dropping.
+ *
+ * One JSON attribute (not many) keeps it robust against Streamdown's HTML
+ * sanitization (we only need to allow a single attribute through). The SAME plugin
+ * array is fed to Streamdown (preview) and can be fed to Milkdown via `$remark`
+ * (editor), so both sides parse `:::card` identically.
+ */
+
+declare const BRAND_DIRECTIVES: readonly ["card", "callout", "metric", "timeline"];
+type BrandDirectiveName = (typeof BRAND_DIRECTIVES)[number];
+/** Which directive syntax produced a node: `:::block`, `::leaf`, or `:inline`. */
+type MarkdownDirectiveKind = "container" | "leaf" | "inline";
+/** Context handed to a consumer directive renderer. */
+interface MarkdownDirectiveContext {
+    name: string;
+    /** Which syntax matched — a renderer can branch (e.g. inline chip vs block card). */
+    kind: MarkdownDirectiveKind;
+    /** Directive attributes (`{key=value}`), strings only. */
+    attributes: Record<string, string>;
+    /** Rendered body (container), label (inline), or empty (leaf). */
+    children: ReactNode;
+    /**
+     * RAW label text for inline/leaf directives (markdown-significant characters
+     * preserved). Use this — not `children` — when you need the verbatim source
+     * (e.g. a calc expression `85 * 32`). `undefined` for container directives.
+     */
+    textValue?: string;
+    /**
+     * RAW container body markdown (the source between the `:::name` fences). Only
+     * populated for directives registered with `rawBodyNames` (e.g. `iterate` /
+     * `pivot`), where the body is a TEMPLATE to interpolate + render per cell, not
+     * to display pre-rendered. `undefined` otherwise.
+     */
+    rawBody?: string;
+}
+/** Register a custom `:::name` / `::name` / `:name` directive renderer. */
+interface MarkdownDirectiveRenderer {
+    /** Directive name, e.g. `"decision"`, `"entity"`. */
+    name: string;
+    /** Accepted syntaxes. Default: all three. */
+    kinds?: readonly MarkdownDirectiveKind[];
+    render: (ctx: MarkdownDirectiveContext) => ReactNode;
+}
+/** Context handed to a consumer fence renderer. */
+interface MarkdownFenceContext {
+    /** The fence body (trailing newline stripped). */
+    source: string;
+    /** The info-string language, e.g. `"calc"`. */
+    lang: string;
+}
+/** Register a custom ```lang fenced-block renderer (the mermaid/calc seam). */
+interface MarkdownFenceRenderer {
+    /** Info-string this renderer claims, e.g. `"calc"`. */
+    lang: string;
+    render: (ctx: MarkdownFenceContext) => ReactNode;
+}
+/**
+ * Consumer extensions to the brand markdown dialect — passed to `MarkdownPreview`
+ * via the `extensions` prop. Registered directive NAMES are also fed to the parser
+ * (so `:entity[…]` is rewritten, while an unregistered `:foo` in prose stays
+ * literal text), and the renderers drive the preview's dispatch. The engine is
+ * never forked: new blocks register here.
+ */
+interface MarkdownExtensions {
+    directives?: readonly MarkdownDirectiveRenderer[];
+    fences?: readonly MarkdownFenceRenderer[];
+}
+/**
+ * remark transform: brand directives → `<brand-directive data-brand="{json}">`
+ * (block/leaf) or `<brand-directive-inline …>` (inline).
+ *
+ * `knownNames` is the set of directive names to TREAT AS KNOWN — i.e. rewrite
+ * rather than restore. It defaults to the four built-ins; `MarkdownPreview`
+ * extends it with the names a consumer registered via `extensions`, so a
+ * registered `:entity[…]` is rewritten while an unregistered `:foo` (or a stray
+ * prose colon) is still restored to literal text.
+ */
+declare function remarkBrandDirectives(knownNames?: readonly string[], rawBodyNames?: readonly string[]): (tree: unknown, file?: {
+    value?: unknown;
+}) => void;
+/** Options for {@link buildMarkdownPlugins}. */
+interface BuildMarkdownPluginsOptions {
+    /**
+     * Extra directive names to treat as known (rewritten, not restored as literal
+     * text). The four built-ins are always known; pass the names a consumer
+     * registered via `extensions.directives`.
+     */
+    directiveNames?: readonly string[];
+    /**
+     * Container directive names whose RAW body should be captured (as
+     * `payload.body` / `ctx.rawBody`) instead of pre-rendered — for templated
+     * blocks like `iterate` / `pivot` whose body is interpolated per cell.
+     */
+    rawBodyNames?: readonly string[];
+}
+/**
+ * The shared remark plugin array (directive parsing + brand mapping). Pass
+ * `directiveNames` to recognize consumer-registered directives without forking
+ * the engine; with no options it parses exactly the four built-ins (backward
+ * compatible).
+ */
+declare function buildMarkdownPlugins(options?: BuildMarkdownPluginsOptions): PluggableList;
+
+/**
+ * Line-level markdown diff → block annotations for `MarkdownPreview` (#L18).
+ *
+ * `computeMarkdownAnnotations(before, after)` diffs two markdown sources and
+ * returns the annotation set the preview renders as a "ghost diff": added /
+ * modified blocks get a wash + accent rail, pure deletions become a slim
+ * "removed here" marker before the next surviving block.
+ *
+ * Lines are 1-based and refer to the AFTER source **including** any YAML
+ * frontmatter — `MarkdownPreview` shifts them when it strips frontmatter, so
+ * callers never have to think about the offset.
+ *
+ * The diff is a classic LCS (O(n·m) DP) — markdown documents are
+ * authoring-sized. Inputs beyond {@link MAX_DIFF_LINES} lines fall back to an
+ * empty annotation set (the UI simply shows no wash) instead of freezing.
+ */
+type MarkdownAnnotationKind = "added" | "modified" | "removed-before";
+interface MarkdownAnnotation {
+    kind: MarkdownAnnotationKind;
+    /**
+     * For `added`/`modified`: the 1-based inclusive line range in the AFTER
+     * source. For `removed-before`: `startLine === endLine` is the line in the
+     * AFTER source that now sits where the removed content used to be.
+     */
+    startLine: number;
+    endLine: number;
+    /** For `removed-before`: how many lines were removed. */
+    removedCount?: number;
+}
+/**
+ * Diff two markdown sources into preview annotations.
+ *
+ * Hunk semantics: a run of only-added lines → `added`; a run that replaces
+ * removed lines → `modified`; a run of only-removed lines → `removed-before`
+ * anchored on the first surviving AFTER line at-or-after the removal.
+ */
+declare function computeMarkdownAnnotations(before: string, after: string): MarkdownAnnotation[];
+/** Honest "+a −r" totals for an annotation set (commit churn, drift rows). */
+declare function summarizeAnnotations(annotations: MarkdownAnnotation[]): {
+    added: number;
+    removed: number;
+};
+/**
+ * Shift annotation lines by `-offset` (used when frontmatter is stripped before
+ * rendering). Annotations that fall entirely inside the stripped region drop out.
+ */
+declare function shiftAnnotations(annotations: MarkdownAnnotation[], offset: number): MarkdownAnnotation[];
+/** Does the annotation set wash the given block line range? Most specific wins. */
+declare function annotationForRange(annotations: MarkdownAnnotation[], startLine: number, endLine: number): MarkdownAnnotation | undefined;
+/** The removed-marker (if any) anchored exactly at this block's first line. */
+declare function removedMarkerAt(annotations: MarkdownAnnotation[], startLine: number): MarkdownAnnotation | undefined;
+
+interface CalcBlockProps extends Omit<HTMLAttributes<HTMLElement>, "children" | "title"> {
+    /** The ```calc fence body. */
+    source: string;
+    /** Consumer-supplied evaluator (sync). The library bundles no math engine. */
+    evaluate: EvaluateCalc;
+    /**
+     * Block title shown in the header bar. By default a leading `# Heading` line in
+     * `source` is lifted here; with neither prop nor heading the header shows the
+     * neutral `calc` code-label. Pass `title` to override the displayed text.
+     */
+    title?: ReactNode;
+    /** Show the running-total footer. Default true. */
+    showTotal?: boolean;
+    /**
+     * Override the footer total. Defaults to `sheet.total`. Pass a `CalcValue`
+     * (rendered tabular via its `.display`) or any ReactNode to replace the
+     * computed total — e.g. a different aggregate the evaluator didn't surface.
+     */
+    total?: CalcValue | ReactNode;
+    /** Footer label. Default `Total`. */
+    totalLabel?: ReactNode;
+    /**
+     * Parse trailing author markers (`@success`, `@line`, …) out of each source
+     * line — applying the row's tint/rule and stripping the marker from the
+     * rendered text. Default `true`. Set `false` if your calc dialect uses a
+     * trailing `@token` for something else.
+     */
+    markers?: boolean;
+    /** Reserved for the editing variant (CalcWorkspace); preview is read-only. */
+    readOnly?: boolean;
+}
+declare const CalcBlock: react.ForwardRefExoticComponent<CalcBlockProps & react.RefAttributes<HTMLDivElement>>;
+
+interface CalcInlineProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** The inline expression, e.g. `85 USD * 32`. */
+    source: string;
+    /** Consumer-supplied evaluator (sync). The library bundles no math engine. */
+    evaluate: EvaluateCalc;
+}
+declare const CalcInline: react.ForwardRefExoticComponent<CalcInlineProps & react.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * Resolved citation data, returned by the consumer's `resolveCitation` hook.
+ * Provide `formatted` (your CSL/citeproc output) for a verbatim bibliography
+ * entry; otherwise the built-in assembler uses `author` / `year` / `title` /
+ * `container`. The library does NOT format CSL.
+ */
+interface CitationData {
+    /** The citation key (echoed back; optional). */
+    key?: string;
+    /** Inline author label for author-year + bibliography lead (e.g. `"Smith et al."`). */
+    author?: string;
+    /** Publication year. */
+    year?: string | number;
+    /** Work title. */
+    title?: string;
+    /** Container — journal, book, publisher, or site. */
+    container?: string;
+    /** Canonical URL (the bibliography link). */
+    url?: string;
+    /** DOI — linked as `https://doi.org/<doi>` when no `url` is given. */
+    doi?: string;
+    /** Fully-formatted reference (app's CSL output) — rendered verbatim when set. */
+    formatted?: string;
+}
+/** Consumer hook: citation key → data, or `null` when unknown (renders `[?]`). */
+type ResolveCitation = (key: string) => CitationData | null;
+/** Inline citation rendering style. */
+type CitationStyle = "numeric" | "author-year";
+/** One resolved citation with its assigned number (numbers skip unresolved keys). */
+interface ResolvedCitation {
+    key: string;
+    /** 1-based number (numeric style + bibliography); `undefined` when unresolved. */
+    n?: number;
+    data: CitationData | null;
+}
+/** A single `@key` reference inside a citation bracket. */
+interface CiteItem {
+    key: string;
+    /** Locator text after the key, e.g. `"p. 5"`. */
+    locator?: string;
+    /** `-@key` → suppress the author in author-year style. */
+    suppressAuthor?: boolean;
+    /** Prose before the key, e.g. `"see"`. */
+    prefix?: string;
+}
+interface CollectedCitations {
+    /** Resolved citations in first-appearance order (the bibliography list). */
+    order: ResolvedCitation[];
+    /** Lookup by key — both resolved and unresolved keys. */
+    byKey: Map<string, ResolvedCitation>;
+}
+/**
+ * Scan the markdown body once, in document order, resolving each unique citation
+ * key and numbering the resolved ones. The inline transform stays numbering-free
+ * and reads back from `byKey`, so inline `[1]` and bibliography entry 1 agree.
+ */
+declare function collectCitations(markdown: string, resolve: ResolveCitation): CollectedCitations;
+interface BibliographyProps extends Omit<HTMLAttributes<HTMLElement>, "children" | "style"> {
+    /** Resolved citations; defaults to the citations collected by `MarkdownPreview`. */
+    entries?: ResolvedCitation[];
+    /** Numbering style; defaults to the preview's `citationStyle`. */
+    style?: CitationStyle;
+    /** Section heading label. Default `"References"`. */
+    title?: string;
+}
+/**
+ * The generated reference list. Reads the preview's collected citations by default
+ * (the `::bibliography` block), or accepts an explicit `entries` array standalone.
+ * One focal separation gesture — a top `Separator` — over a quiet label + list.
+ */
+declare const Bibliography: react.ForwardRefExoticComponent<BibliographyProps & react.RefAttributes<HTMLElement>>;
+
+type IterationLayout = "stacked" | "grid" | "matrix" | "bento";
+/** The parsed `:::iterate` / `:::pivot` specification handed to `evaluate`. */
+interface IterationSpec {
+    /** `iterate` (1D repeat) or `pivot` (2D cross-tab). */
+    kind: "iterate" | "pivot";
+    /** How the cells are laid out. */
+    layout: IterationLayout;
+    /** The per-cell markdown template (the directive body). */
+    template: string;
+    /** Loop-variable name exposed to `interpolate` (default `"item"`). */
+    as: string;
+    /** Opaque data-source reference; resolved by the consumer's `evaluate`. */
+    source?: string;
+    /** Pivot row / column dimension field names (`pivot`). */
+    rows?: string;
+    cols?: string;
+    /** Explicit grid column count (`grid`). */
+    columns?: number;
+    /** All raw directive attributes (escape hatch for `evaluate`). */
+    attributes: Record<string, string>;
+}
+/** One resolved cell. */
+interface IterationCell {
+    /** Interpolation context (the row record / pivot-cell scope). */
+    context: Record<string, unknown>;
+    /** Stable key (defaults to the index). */
+    key?: string;
+    /** `matrix`: the row / column header this cell sits at. */
+    row?: string;
+    col?: string;
+    /** `bento`: tile size preset. Defaults to a deterministic per-index rhythm. */
+    size?: BentoGridSize;
+    /** Pre-rendered markdown — skips `interpolate` when the app already templated. */
+    markdown?: string;
+}
+/** What the consumer's `evaluate` returns. */
+interface IterationData {
+    /** Cells in render order. */
+    cells: IterationCell[];
+    /** `matrix`: ordered row + column header labels. */
+    rowHeaders?: string[];
+    colHeaders?: string[];
+    /** `grid`: column header labels (also sets the column count). */
+    columns?: string[];
+}
+/** Consumer hook: resolve a spec to its data, or `null` when unavailable. */
+type EvaluateIteration = (spec: IterationSpec) => IterationData | null;
+/** Consumer hook: fill a template with a cell context. */
+type InterpolateTemplate = (template: string, context: Record<string, unknown>) => string;
+/**
+ * Minimal `{{ path.to.value }}` substitution over the cell context (dot paths).
+ * Safe (no eval). An UNRESOLVED token is left **literal** — so a nested
+ * `:::iterate`'s tokens survive the outer pass and resolve in the inner one (use
+ * the `as` loop variable in nested templates to avoid scope collisions). Replace
+ * it with your own engine (Mustache/Handlebars/…) via the `interpolate` prop.
+ */
+declare function defaultInterpolate(template: string, context: Record<string, unknown>): string;
+interface IterationBlockProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** The parsed iteration spec (from the directive, or hand-built). */
+    spec: IterationSpec;
+    /** Resolve the spec to data (consumer data source). */
+    evaluate: EvaluateIteration;
+    /** Fill a template with a cell context. Default: `{{path}}` substitution. */
+    interpolate?: InterpolateTemplate;
+    /** Render a resolved cell's markdown → node (e.g. a nested `MarkdownPreview`). */
+    render: (markdown: string) => ReactNode;
+    /** Override `spec.layout`. */
+    layout?: IterationLayout;
+    /** Empty-state message when there are no cells. */
+    emptyLabel?: string;
+}
+declare const IterationBlock: react.ForwardRefExoticComponent<IterationBlockProps & react.RefAttributes<HTMLDivElement>>;
+
+/** Build an `IterationSpec` from a directive's name + attributes + raw body. */
+declare function specFromDirective(name: "iterate" | "pivot", attributes: Record<string, string>, rawBody: string | undefined): IterationSpec;
+
+/**
+ * Hover affordances beside headings (#L6 companion): a generic render-prop —
+ * the preview knows nothing about what the action does (pinning, anchors,
+ * copy-link…). Revealed on heading hover / focus, and kept visible while the
+ * slot contains a pressed toggle (`aria-pressed="true"`).
+ */
+interface MarkdownHeadingInfo {
+    level: ProseHeadingLevel;
+    /** Plain text content of the heading. */
+    text: string;
+    /** 1-based start line in the frontmatter-STRIPPED source (= `data-sourcepos`). */
+    line?: number;
+}
+type MarkdownUrlKind = "image" | "link";
+/**
+ * Options passed to `resolveWikilink` for each wikilink found in the document.
+ */
+interface WikilinkResolveOptions {
+    /** The `#anchor` fragment, if present — e.g. `[[target#Section 1]]` → `"Section 1"`. */
+    anchor?: string;
+}
+/**
+ * Options passed to `resolveTransclusion` for each transclusion embed found.
+ */
+interface TransclusionResolveOptions {
+    /**
+     * A `#section` heading, if present — e.g. `![[target#Introduction]]` → `"Introduction"`.
+     * The consumer can use this to extract only that section from the document.
+     */
+    section?: string;
+}
+interface MarkdownPreviewProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Markdown source. */
+    children: string;
+    /** Strip a leading YAML frontmatter block before rendering. Default true. */
+    stripFrontmatter?: boolean;
+    /**
+     * Ghost-diff annotations (#L18) — typically from `computeMarkdownAnnotations`.
+     * Lines are 1-based relative to the FULL `children` source (frontmatter
+     * included); the preview shifts them when `stripFrontmatter` removes lines.
+     */
+    annotations?: MarkdownAnnotation[];
+    /**
+     * Rewrite image/link URLs (#L4) — e.g. resolve repo-relative paths or swap
+     * private-repo asset URLs for authenticated blob URLs. Synchronous by design:
+     * async consumers cache upstream and re-render when the URL is ready.
+     */
+    resolveUrl?: (url: string, kind: MarkdownUrlKind) => string;
+    /**
+     * In-document search term (≥2 chars): mermaid diagrams mark matching nodes.
+     * Pair with an app-side text highlighter (CSS Custom Highlight API) for the
+     * prose occurrences.
+     */
+    searchTerm?: string;
+    /**
+     * 1-based line of the ACTIVE search hit, relative to the FULL `children`
+     * source (same convention as `annotations`). Its block gets a primary wash;
+     * in a mermaid fence the matching node gets the active stroke.
+     */
+    activeSearchLine?: number;
+    /**
+     * Render hover affordances beside each heading (pin/anchor/copy-link…).
+     * Presentational slot — revealed on heading hover/focus and kept visible
+     * while it contains a pressed toggle. `line` is in frontmatter-STRIPPED
+     * coordinates (the same space as `data-sourcepos` / `parseMarkdownOutline`).
+     */
+    headingActions?: (heading: MarkdownHeadingInfo) => ReactNode;
+    /**
+     * Evaluate a ```calc fence to a `CalcSheet` (the library renders, the app
+     * computes — mirrors `resolveUrl`). With no `evaluate`, a ```calc fence renders
+     * as a normal code block; the math engine stays in the consumer.
+     *
+     * Sugar over `extensions.fences`: it registers a built-in `calc` fence renderer.
+     * Register your own `calc` fence via `extensions` to override it.
+     */
+    evaluate?: EvaluateCalc;
+    /**
+     * Extend the markdown dialect without forking the engine: register custom
+     * `:::`/`::`/`:` directive renderers and ```lang fence renderers. Registered
+     * directive names are also fed to the parser (so `:entity[…]` is recognized
+     * while an unregistered prose colon stays literal). Domain logic stays in the
+     * consumer's renderer (the library renders; the app computes).
+     */
+    extensions?: MarkdownExtensions;
+    /**
+     * Resolve an Obsidian-style wikilink (`[[target]]`, `[[target|alias]]`,
+     * `[[target#anchor]]`, `[[target#anchor|alias]]`) to a URL.
+     *
+     * - Return a string href to produce a real `<a>` (flows through `resolveUrl`
+     *   and `renderLinkPreview` like any other link).
+     * - Return `null` to leave the wikilink as literal plain text `[[target]]`
+     *   (graceful — never a broken link).
+     *
+     * Supported forms:
+     * - `[[target]]` → `resolveWikilink("target", {})`
+     * - `[[target|alias]]` → `resolveWikilink("target", {})`, link text = alias
+     * - `[[target#anchor]]` → `resolveWikilink("target", { anchor: "anchor" })`
+     * - `[[target#anchor|alias]]` → `resolveWikilink("target", { anchor: "anchor" })`, text = alias
+     */
+    resolveWikilink?: (target: string, opts: WikilinkResolveOptions) => string | null;
+    /**
+     * Resolve an Obsidian-style transclusion embed (`![[target]]`,
+     * `![[target#section]]`) to the markdown TEXT to embed.
+     *
+     * - Return the markdown string to embed; it will be recursively rendered as a
+     *   visually-nested, AT-labelled block (depth cap: 3 levels).
+     * - Return `null` to leave the embed as literal plain text `![[target]]`.
+     *
+     * The library never fetches — the consumer owns the vault index and resolution.
+     */
+    resolveTransclusion?: (target: string, opts: TransclusionResolveOptions) => string | null;
+    /**
+     * Wrap every rendered `<a>` to attach a hover/inline link preview (e.g. a
+     * `@elabs-ai/components-ui` HoverCard showing metadata). The library does NOT fetch; the
+     * consumer owns the preview content.
+     *
+     * Return `children` unchanged if the href should not trigger a preview.
+     * Default (not supplied) → the plain `Link` component.
+     */
+    renderLinkPreview?: (href: string, children: ReactNode) => ReactNode;
+    /**
+     * Branded GFM footnotes (`[^1]` … `[^1]: definition`) — quiet superscript refs
+     * + a footnote section at the document end with working same-page back-refs.
+     * Default `false` (footnotes parse but render with the plain GFM treatment).
+     */
+    footnotes?: boolean;
+    /**
+     * Math via `remark-math` + KaTeX — `$inline$` and `$$block$$` (on their own
+     * lines). KaTeX runs untrusted-safe (`trust:false`, bounded macro expansion);
+     * MathML is emitted for assistive tech. **The consumer must load KaTeX CSS once**
+     * (`import "katex/dist/katex.min.css"`). Default `false`.
+     */
+    math?: boolean;
+    /**
+     * Resolve a Pandoc / Better-BibTeX citation key (`[@smith2020]`,
+     * `[@a; @b]`, `[@a, p. 5]`, `[-@a]`) to {@link CitationData}, or `null` when
+     * unknown. The BibTeX/CSL database + any CSL formatting live in the app — the
+     * library renders inline cites + the `::bibliography` / `::references` block with
+     * consistent numbering. Setting this enables citations (the same way `evaluate`
+     * enables calc).
+     */
+    resolveCitation?: ResolveCitation;
+    /** Inline citation style: `"numeric"` `[1]` (default) or `"author-year"` `(Smith 2020)`. */
+    citationStyle?: CitationStyle;
+    /**
+     * Enable the generated `::toc` block (a quiet in-flow table of contents) and
+     * stamp stable slug `id`s on headings so the anchors resolve. Reuses the same
+     * heading extractor as `DocumentOutline`. Default `false`.
+     */
+    toc?: boolean;
+    /**
+     * Resolve a `:::iterate` / `:::pivot` block's {@link IterationSpec} (parsed from
+     * the directive's attributes + body template) to its data. The data source +
+     * any query live in the app — the library renders the repeated/cross-tabbed
+     * cells. Setting this enables the `iterate` + `pivot` directives (the way
+     * `evaluate` enables calc).
+     */
+    evaluateIteration?: EvaluateIteration;
+    /**
+     * Fill a `:::iterate` cell template with its row/cell context. Default: a
+     * minimal `{{path}}` substitution — pass your own engine for anything richer.
+     */
+    interpolate?: InterpolateTemplate;
+}
+declare const MarkdownPreview: react.ForwardRefExoticComponent<MarkdownPreviewProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * `@elabs-ai/components-editor/markdown/parse` — a Monaco-free markdown parser.
+ *
+ * `parseMarkdown(md)` returns the mdast `Root` for the SAME dialect the branded
+ * preview parses: GitHub-flavored markdown + `:::`/`::`/`:` directives + YAML
+ * frontmatter. Split onto its own leaf subpath (like `./markdown/frontmatter`) so
+ * SERVER, RSC, and unit-test consumers can parse markdown WITHOUT pulling the
+ * editor engines (Milkdown, Monaco, Streamdown) into their bundle — the whole
+ * reason the `.` vs `./markdown` split exists. Depends only on `unified` +
+ * `remark-*` (no React, no Monaco).
+ *
+ * It returns RAW directive mdast (`containerDirective` / `leafDirective` /
+ * `textDirective` nodes) — it does NOT run `remarkBrandDirectives` (that rewrites
+ * directives into the `<brand-directive>` hast tag, which is a RENDER concern).
+ * Walk the tree by `node.type` + `node.name` yourself. The match is at the
+ * DIALECT level (same plugins/extensions); it is not byte-identical to the tree
+ * Streamdown builds internally (which also applies a streaming block-splitter).
+ */
+
+/** Parse markdown to mdast (gfm + directives + frontmatter). Monaco-free. */
+declare function parseMarkdown(md: string): Root;
+
+interface ParsedDocument {
+    /** Parsed frontmatter object ({} when there is no frontmatter block). */
+    frontmatter: Record<string, unknown>;
+    /** Markdown body with the frontmatter block removed. */
+    content: string;
+    hasFrontmatter: boolean;
+}
+declare function parseFrontmatter(source: string): ParsedDocument;
+declare function serializeFrontmatter(frontmatter: Record<string, unknown>, content: string): string;
+
+interface MermaidDiagramProps extends HTMLAttributes<HTMLDivElement> {
+    /** Mermaid source (the fence body). */
+    chart: string;
+    /** Accessible name for the rendered diagram. Default "Diagram". */
+    label?: string;
+    /** Show the hover copy-source button. Default true. */
+    copyable?: boolean;
+    /** Show the hover expand-to-modal button. Default true. */
+    expandable?: boolean;
+    /**
+     * In-document search term (≥2 chars): nodes/edge labels whose text contains
+     * it get the hit stroke — the diagram participates in document search.
+     */
+    highlightTerm?: string;
+    /**
+     * Source text of the ACTIVE search hit (the clicked finding's line). The
+     * matching hit is promoted to the primary "active" stroke.
+     */
+    activeText?: string;
+}
+declare const MermaidDiagram: react.ForwardRefExoticComponent<MermaidDiagramProps & react.RefAttributes<HTMLDivElement>>;
+
+interface MermaidWorkspaceProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (source: string) => void;
+    /** Debounce (ms) before the diagram re-renders while typing. Default 350. */
+    debounceMs?: number;
+}
+declare const MermaidWorkspace: react.ForwardRefExoticComponent<MermaidWorkspaceProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Shared, engine-agnostic helpers for the calc AUTHORING surfaces (#220).
+ *
+ * Both editor surfaces — the Monaco source editor and the Milkdown WYSIWYG
+ * editor — need the same things: find the ```calc fences, ask the consumer's
+ * hooks for highlight tokens + results, and turn those into decorations. The
+ * decoration *application* differs per engine (Monaco `inlineClassName` vs a
+ * ProseMirror `DecorationSet`), but the *logic* here is pure and shared, so it is
+ * unit-testable without rendering either engine (Monaco can't render in jsdom).
+ *
+ * Governing rule (D5): the library decorates, the consumer computes. Nothing here
+ * does any math — it only calls the consumer-supplied {@link CalcEditorHooks} and
+ * shapes the results. A throwing hook degrades to "no decorations" rather than
+ * blanking the editor (mirrors how `CalcBlock` never throws on a bad block).
+ */
+
+/** A located ```calc fence within a markdown document. Lines are 1-based. */
+interface CalcFence {
+    /** 1-based line of the opening fence (` ```calc `). */
+    openLine: number;
+    /** 1-based line of the closing fence, or `lines + 1` when unterminated. */
+    closeLine: number;
+    /** 1-based line of the first body line (`openLine + 1`). */
+    bodyStartLine: number;
+    /** 1-based line of the last body line (`closeLine - 1`); `< bodyStartLine` if empty. */
+    bodyEndLine: number;
+    /** The fence body (body lines joined by `"\n"`). */
+    source: string;
+}
+/**
+ * Scan a markdown string for ```calc fences. Tolerant of leading indentation,
+ * `~~~` fences, and an unterminated trailing fence (treated as running to EOF) —
+ * which is the normal state while the author is still typing the block.
+ */
+declare function findCalcFences(text: string): CalcFence[];
+/**
+ * Class string for a highlight token. Hue comes from the `--calc-*` tokens (via
+ * `calc-editor.css`), but — exactly like `CalcBlock.tokenClass` — hue is never
+ * the SOLE cue: a `var-def` carries weight and an unresolved token a dotted
+ * underline, so roles stay distinct in the high-contrast theme (where the calc
+ * colors collapse toward the foreground).
+ */
+declare function calcTokenClassName(kind: CalcTokenKind, resolved: boolean): string;
+
+/**
+ * Monaco calc layer (#220) — live highlighting + autocomplete + result inlays for
+ * ```calc fences inside a markdown Monaco model.
+ *
+ * - HIGHLIGHT is a decoration pass (not a Monarch language): the model is markdown,
+ *   so we tokenize each calc fence body via the consumer's `tokenize` hook and apply
+ *   `inlineClassName` decorations colored from the `--calc-*` tokens (calc-editor.css).
+ * - COMPLETIONS come from a markdown `CompletionItemProvider` scoped to calc fences,
+ *   delegating to the consumer's `complete` hook.
+ * - INLAYS are Monaco inlay hints (themed via the theme bridge's `editorInlayHint.*`
+ *   colors, so they re-apply on theme change), built from the consumer's `evaluate`.
+ *
+ * The providers register ONCE per language and look the active hooks up per-model via
+ * a registry, so any number of markdown editors can be wired independently. All the
+ * column/position math lives in `calc-editor.ts` (engine-neutral + unit-tested);
+ * this module only maps those specs to Monaco objects and owns the lifecycle.
+ */
+
+/** Resolver of the latest hooks for a model (read through a ref so prop-identity churn is free). */
+type HooksGetter = () => CalcEditorHooks | undefined;
+/**
+ * Wire calc highlighting + completion + inlays onto a markdown Monaco editor.
+ * `getHooks` is read fresh on each update, so changing the `calc` prop's identity
+ * never forces a re-attach. Returns a disposer; call it on unmount / when `calc`
+ * is removed.
+ */
+declare function attachCalcMonaco(editor: monaco.editor.IStandaloneCodeEditor, getHooks: HooksGetter): () => void;
+
+/**
+ * Milkdown / ProseMirror calc layer (#220) — live highlighting + result inlays for
+ * ```calc fences inside the WYSIWYG editor.
+ *
+ * A self-owned raw `$prose` plugin (zero new deps) that builds a `DecorationSet`
+ * over every `code_block` whose language is `calc`:
+ *   - inline decorations color each token from the `--calc-*` tokens (calc-editor.css);
+ *   - a widget decoration after each line shows the computed result inlay.
+ * The set is recomputed when the document changes. Hooks are read through a getter
+ * so a fresh `calc` prop identity never rebuilds the editor (mirrors `slashConfigRef`).
+ *
+ * The position math reuses the engine-neutral helpers in `calc-editor.ts`; a
+ * ProseMirror code block stores its body as plain text with literal `\n`, so a
+ * line's absolute position is `codeBlockContentStart + lineOffset + column`.
+ */
+
+/**
+ * Build the calc decoration plugin. `getHooks` is read on every recompute so the
+ * editor never rebuilds when the `calc` prop identity changes. Returns a Milkdown
+ * plugin array to `.use()` (only when calc authoring is enabled).
+ */
+declare function calcProsePlugins(getHooks: () => CalcEditorHooks | undefined): MilkdownPlugin[];
+
+/**
+ * Normalization-aware merge for WYSIWYG markdown editing (review WI-1).
+ *
+ * Problem: Milkdown serializes the WHOLE document on every edit, normalizing
+ * formatting it never touched (list markers, wrapping, spacing). Feeding that
+ * back into the buffer turns a one-line edit into a whole-file rewrite —
+ * destroying git blame and making PR review impossible.
+ *
+ * Fix: three-way line merge.
+ * - `original`  — the byte-exact source the editor was opened with.
+ * - `baseline`  — the editor's serialization of `original` BEFORE any edit
+ *                 (pure normalization drift).
+ * - `edited`    — the editor's serialization after user edits.
+ *
+ * `diff(baseline, edited)` isolates what the USER changed; an
+ * `original ↔ baseline` alignment maps those hunks back onto `original`.
+ * Everything the user didn't touch keeps its original bytes. Granularity is
+ * the contiguous normalized run — markdown's blank lines survive
+ * serialization byte-exact, so in practice that's a single block.
+ *
+ * Guarantees:
+ * - no user edit (`baseline === edited`) → returns `original` byte-exact;
+ * - no normalization drift (`original === baseline`) → returns `edited`;
+ * - a user hunk inside a normalized block replaces exactly that block;
+ * - oversized inputs (> {@link MAX_DIFF_LINES}) fall back to `edited`.
+ */
+/**
+ * Merge a WYSIWYG serialization back onto the original source, keeping
+ * original bytes for everything the user didn't touch.
+ */
+declare function mergeNormalizedEdit(original: string, baseline: string, edited: string): string;
+
+interface MarkdownOutlineItem {
+    /** Stable slug (GitHub-style, deduped with `-n` suffixes). */
+    id: string;
+    /** Plain heading text (inline markdown stripped). */
+    text: string;
+    /** Heading level 1–6. */
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    /** 1-based line in the frontmatter-stripped source (matches `data-sourcepos`). */
+    line: number;
+}
+declare function parseMarkdownOutline(markdown: string): MarkdownOutlineItem[];
+
+/** Memoized outline of a markdown source. */
+declare function useMarkdownOutline(markdown: string): MarkdownOutlineItem[];
+interface DocumentOutlineProps extends Omit<HTMLAttributes<HTMLElement>, "onSelect"> {
+    items: MarkdownOutlineItem[];
+    /** The outline item currently in view. */
+    activeId?: string;
+    onSelect?: (item: MarkdownOutlineItem) => void;
+    /**
+     * Per-entry hover affordances (pin/copy-link…), rendered at the row end.
+     * Revealed on row hover/focus; stays visible while it contains a pressed
+     * toggle (`aria-pressed="true"`).
+     */
+    itemActions?: (item: MarkdownOutlineItem) => ReactNode;
+}
+declare const DocumentOutline: react.ForwardRefExoticComponent<DocumentOutlineProps & react.RefAttributes<HTMLElement>>;
+
+declare const DECISION_STATUSES: readonly ["accepted", "rejected", "proposed", "superseded"];
+type DecisionStatus = (typeof DECISION_STATUSES)[number];
+declare const decisionCardVariants: (props?: ({
+    status?: "accepted" | "rejected" | "proposed" | "superseded" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface DecisionCardProps extends HTMLAttributes<HTMLElement> {
+    /**
+     * Decision outcome. One of the four canonical states; anything unrecognised
+     * renders as "proposed".
+     */
+    status?: string;
+    /**
+     * ISO date or human-readable date of the decision
+     * (e.g. `"2026-06-15"` or `"June 2026"`).
+     */
+    date?: string;
+    /**
+     * Comma-separated alternative options considered before this decision.
+     * E.g. `"Redis cache, in-memory map, SQLite"`.
+     */
+    alternatives?: string;
+    /** The rationale body (rendered markdown children of the directive). */
+    children?: ReactNode;
+}
+declare const DecisionCard: react.ForwardRefExoticComponent<DecisionCardProps & react.RefAttributes<HTMLElement>>;
+
+declare const ENTITY_KINDS: readonly ["org", "person", "place", "product", "concept"];
+type EntityKind = (typeof ENTITY_KINDS)[number];
+declare const entityChipVariants: (props?: ({
+    kind?: "default" | "product" | "org" | "person" | "place" | "concept" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface EntityChipProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Entity kind — drives icon and tone. */
+    kind?: string;
+    /** Display label (the directive's label text or `name` attribute). */
+    children?: ReactNode;
+}
+declare const EntityChip: react.ForwardRefExoticComponent<EntityChipProps & react.RefAttributes<HTMLSpanElement>>;
+interface EntityCardProps extends HTMLAttributes<HTMLElement> {
+    /** Entity kind — drives the icon and header tone. */
+    kind?: string;
+    /** Entity name. Falls back to children when absent. */
+    name?: string;
+    /** Description body (rendered markdown children of the directive). */
+    children?: ReactNode;
+}
+declare const EntityCard: react.ForwardRefExoticComponent<EntityCardProps & react.RefAttributes<HTMLElement>>;
+
+interface KnowledgeSourceResolved {
+    href: string;
+    title?: string;
+}
+/**
+ * Consumer-supplied resolver: path → link data, or `null` when the path cannot
+ * be resolved (stale vault link, missing file, etc.). The card degrades
+ * gracefully — the source renders as a plain label rather than a broken link.
+ */
+type KnowledgeSourceResolver = (path: string) => KnowledgeSourceResolved | null;
+interface KnowledgeCardProps extends HTMLAttributes<HTMLElement> {
+    /**
+     * Comma-separated source paths (e.g. `"notes/a.md, notes/b.md"`).
+     * Each path is handed to `resolve`; unresolved paths render as plain labels.
+     */
+    sources?: string;
+    /**
+     * Consumer-supplied resolver. `undefined` → all sources render as plain labels
+     * (safe default — never throws, never reads files).
+     */
+    resolve?: KnowledgeSourceResolver;
+    /** The fact body (rendered markdown children of the directive). */
+    children?: ReactNode;
+}
+declare const KnowledgeCard: react.ForwardRefExoticComponent<KnowledgeCardProps & react.RefAttributes<HTMLElement>>;
+
+/**
+ * `decisionDirective()` — registers the `:::decision` container renderer.
+ *
+ * Authoring shape:
+ *   :::decision{status=accepted date=2026-06-15 alternatives="Redis, SQLite"}
+ *   We chose PostgreSQL because it already runs in prod.
+ *   :::
+ */
+declare function decisionDirective(): MarkdownDirectiveRenderer;
+/**
+ * `entityDirective()` — registers the `entity` directive for BOTH container
+ * (block card) and inline (chip) syntaxes.
+ *
+ * Authoring shapes:
+ *   Container: :::entity{kind=org name="Acme Corp"}
+ *              Acme Corp is the primary vendor.
+ *              :::
+ *   Inline:    :entity[Acme Corp]{kind=org}
+ */
+declare function entityDirective(): MarkdownDirectiveRenderer;
+/**
+ * `knowledgeDirective({ resolve })` — registers the `:::knowledge` container
+ * renderer. The `resolve` hook is consumer-supplied; omitting it causes all
+ * sources to render as plain unlinked labels (safe default).
+ *
+ * Authoring shape:
+ *   :::knowledge{sources="notes/a.md, notes/b.md"}
+ *   PostgreSQL was chosen because …
+ *   :::
+ */
+declare function knowledgeDirective(options?: {
+    resolve?: KnowledgeSourceResolver;
+}): MarkdownDirectiveRenderer;
+interface AiObjectDirectivesOptions {
+    /** Consumer-supplied resolver for `:::knowledge` source paths. */
+    resolveKnowledge?: KnowledgeSourceResolver;
+}
+/**
+ * `aiObjectDirectives(options)` — returns all three directive renderers as an
+ * array ready to pass to `extensions.directives`:
+ *   - `decisionDirective()`
+ *   - `entityDirective()`
+ *   - `knowledgeDirective({ resolve: options.resolveKnowledge })`
+ *
+ * @example
+ *   <MarkdownPreview
+ *     extensions={{ directives: aiObjectDirectives({ resolveKnowledge }) }}
+ *   />
+ */
+declare function aiObjectDirectives(options?: AiObjectDirectivesOptions): MarkdownDirectiveRenderer[];
+
+interface MathProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** Raw TeX source. */
+    tex: string;
+}
+/** Inline math (`$…$`) → KaTeX, in the text flow. */
+declare function MathInline({ tex, className, ...props }: MathProps): react.JSX.Element;
+/** Block math (`$$…$$`) → centered display KaTeX. */
+declare function MathBlock({ tex, className, ...props }: MathProps): react.JSX.Element;
+
+type FootnoteListProps = HTMLAttributes<HTMLElement>;
+/**
+ * The branded footnote-definition section. One focal separation gesture — a top
+ * `Separator` (the classic footnote rule) — over a quiet label + the definition
+ * list; no fill, no border box. The label id is per-instance (`useId`) so two
+ * previews on one page don't collide.
+ */
+declare const FootnoteList: react.ForwardRefExoticComponent<FootnoteListProps & react.RefAttributes<HTMLElement>>;
+
+interface TableOfContentsProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** Heading outline; defaults to the outline collected by `MarkdownPreview`. */
+    items?: MarkdownOutlineItem[];
+    /** Section heading label. Default `"Contents"`. */
+    title?: string;
+    /** Deepest heading level to include (1–6). Default 3. */
+    maxLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+}
+/**
+ * Quiet generated TOC. Standalone with an explicit `items` array, or fed from the
+ * preview context inside a `::toc` block. Indentation tracks heading depth; no
+ * fill or border — the indent + links are the only gestures.
+ */
+declare const TableOfContents: react.ForwardRefExoticComponent<TableOfContentsProps & react.RefAttributes<HTMLElement>>;
+
+interface IterationTemplateDialogProps {
+    /** Whether the dialog is open. */
+    open: boolean;
+    /** Open-state change handler (Radix Dialog contract). */
+    onOpenChange: (open: boolean) => void;
+    /** The initial template markdown (the directive body). */
+    template: string;
+    /** Called with the edited template when the user saves. */
+    onSave: (template: string) => void;
+    /** Tunes the title + helper copy. Default `"iterate"`. */
+    kind?: "iterate" | "pivot";
+    /** Initial workspace mode. Default `"split"`. */
+    mode?: MarkdownWorkspaceMode;
+}
+declare function IterationTemplateDialog({ open, onOpenChange, template, onSave, kind, mode, }: IterationTemplateDialogProps): react.JSX.Element;
+/**
+ * One-liner wiring for the node-view `⋯` re-edit: provides the
+ * {@link IterationEditContext} handler AND renders the `IterationTemplateDialog`
+ * it opens. Wrap your `MarkdownEditor` / `MarkdownWorkspace` in it to enable the
+ * `⋯` "Edit template…" affordance on `:::iterate` / `:::pivot` node-views.
+ */
+declare function IterationTemplateProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * Iteration BUILDER model (A5) — the data layer behind the guided
+ * `:::iterate` / `:::pivot` authoring dialog.
+ *
+ * The existing `IterationTemplateDialog` only edits the per-cell TEMPLATE. The
+ * guided builder also collects the DATA (the value list(s) + bind name + the
+ * pivot's second axis + layout) and writes a **fully-bound** directive whose
+ * value lists live in its attributes — so the block renders a populated result
+ * with the built-in {@link evaluateEmbedded} (no consumer data engine needed) and
+ * the `⋯` re-edit can reopen it losslessly.
+ *
+ * Pure + React-free so it is unit-testable on its own:
+ *   serialize  →  `:::iterate{as="item" layout="stacked" values="A, B, C"}\n…\n:::`
+ *                 `:::pivot{layout="matrix" rows="Q1, Q2" cols="N, S"}\n…\n:::`
+ *   parse      ←  the inverse (for the `⋯` reopen)
+ *   evaluate   →  {@link evaluateEmbedded} turns the embedded lists into cells.
+ *
+ * Value lists are comma-separated in the attribute (values containing a literal
+ * comma aren't supported — the dialog enters one value per line and joins them).
+ */
+
+/** The dialog's working value — the collected data + template for one directive. */
+interface IterationBuilderValue {
+    kind: "iterate" | "pivot";
+    /** Loop-variable name (iterate). Default `"item"`. */
+    as: string;
+    layout: IterationLayout;
+    /** iterate: the list of items. pivot: the ROW values. */
+    values: string[];
+    /** pivot: the COLUMN values. */
+    cols?: string[];
+    /** The per-cell markdown template (directive body). */
+    template: string;
+}
+/** Default per-cell template per kind (so a fresh block renders something). */
+declare const DEFAULT_TEMPLATE: Record<"iterate" | "pivot", string>;
+/** Split a comma-separated attribute into trimmed, non-empty values. */
+declare function splitList(value: string | undefined): string[];
+/** Parse a directive attribute string (`a="x" b="y"`) into a record. */
+declare function parseAttributes(attrString: string): Record<string, string>;
+/** Build the `{ attributes, template }` for a builder value (the write-back shape). */
+declare function directivePartsFromValue(value: IterationBuilderValue): {
+    attributes: Record<string, string>;
+    template: string;
+};
+/** Serialize a builder value to a fully-bound `:::iterate` / `:::pivot` directive. */
+declare function serializeIterationDirective(value: IterationBuilderValue): string;
+/** Build a builder value from a directive's kind + attributes + body template. */
+declare function builderValueFromParts(kind: "iterate" | "pivot", attributes: Record<string, string>, template: string): IterationBuilderValue;
+/**
+ * Parse a full `:::iterate` / `:::pivot` directive string into a builder value.
+ *
+ * The fence length is variable (`:{3,}`) and the close is matched by BACKREFERENCE
+ * (`\1`) to the same length as the open, so a directive whose body contains a
+ * nested `:::card` (3 colons) is opened/closed with `::::` (4) and the inner fence
+ * is not mistaken for the outer close. The non-greedy body anchored to end-of-input
+ * keeps the canonical 3-colon form round-tripping unchanged.
+ */
+declare function parseIterationDirective(markdown: string): IterationBuilderValue | null;
+/** An empty builder value for a fresh insert. */
+declare function emptyBuilderValue(kind: "iterate" | "pivot"): IterationBuilderValue;
+/**
+ * Built-in iteration evaluator: resolve the value list(s) embedded in the
+ * directive attributes into cells — so a block authored with the guided builder
+ * renders a populated result with no consumer data engine. iterate reads
+ * `values=`; pivot reads `rows=` × `cols=`. Assignable to `EvaluateIteration`
+ * (it never returns null — it degrades to an empty cell list).
+ */
+declare function evaluateEmbedded(spec: IterationSpec): IterationData;
+/**
+ * Swap a pivot's ROW and COLUMN value lists (the node-menu "Transpose" action).
+ * A no-op for `iterate` (it has no second axis) — the menu item hides itself in
+ * that case, but the function stays total (never throws) so a stale/misrouted
+ * call is harmless. `transposeIterationValue(transposeIterationValue(v)) === v`
+ * for any pivot value (a lossless round-trip).
+ */
+declare function transposeIterationValue(value: IterationBuilderValue): IterationBuilderValue;
+/**
+ * Render a builder value's RESOLVED cells as plain, static markdown — the
+ * "Convert to static" node-menu action. Reuses {@link evaluateEmbedded} (the same
+ * resolver the live preview renders through), so the output matches what the
+ * block currently shows, with no ProseMirror/dialog dependency:
+ *   - `matrix` (with both header axes present) → a GFM table.
+ *   - anything else (`stacked` / `grid` / `bento`) → cells joined as sequential
+ *     markdown blocks, separated by a blank line.
+ * An empty result set (no values entered yet) returns an empty string.
+ */
+declare function staticMarkdownFromValue(value: IterationBuilderValue, interpolate?: InterpolateTemplate): string;
+
+interface IterationBuilderDialogProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Which block to author. Default `"iterate"`. Ignored when `value` is set. */
+    kind?: "iterate" | "pivot";
+    /** Seed the whole builder (the `⋯` re-edit path). */
+    value?: IterationBuilderValue;
+    /** Seed the value list of a fresh block (e.g. a selection split to lines). */
+    initialValues?: string[];
+    /** Receives the fully-bound directive markdown when the user saves. */
+    onSave: (directiveMarkdown: string) => void;
+    /**
+     * Resolve a ```calc fence to a `CalcSheet` so calc cells COMPUTE in the live
+     * preview (the same hook `MarkdownPreview` takes — the library renders, the app
+     * computes). Without it a calc cell still renders as a code block; with it, the
+     * preview matches production. Pass your app's calc engine.
+     */
+    evaluate?: EvaluateCalc;
+    /** Fill a cell template with its context. Defaults to `{{path}}` substitution. */
+    interpolate?: InterpolateTemplate;
+}
+declare function IterationBuilderDialog({ open, onOpenChange, kind: kindProp, value, initialValues, onSave, evaluate, interpolate, }: IterationBuilderDialogProps): react.JSX.Element;
+/**
+ * One-liner wiring for the node-view `⋯` re-edit using the GUIDED builder (A5).
+ * Drop it above a `MarkdownEditor` / `MarkdownWorkspace` to make the `⋯` on a
+ * `:::iterate` / `:::pivot` reopen the full builder seeded with the block's DATA
+ * (value lists + bind name + layout) and template, writing both back losslessly.
+ *
+ * Prefer this over {@link IterationTemplateProvider} when the consumer authors
+ * blocks with embedded value lists (the builder flow); the template-only provider
+ * remains for the lighter "edit just the template" affordance.
+ */
+declare function IterationBuilderProvider({ children, evaluate, interpolate, }: {
+    children: ReactNode;
+    /** Forwarded to the builder's live preview so calc cells COMPUTE on re-edit. */
+    evaluate?: EvaluateCalc;
+    /** Forwarded to the builder's live preview cell interpolation. */
+    interpolate?: InterpolateTemplate;
+}): react.JSX.Element;
+
+export { type AiObjectDirectivesOptions, BRAND_DIRECTIVES, Bibliography, type BibliographyProps, type BrandDirectiveName, type BrandSlashViewOptions, type BuildMarkdownPluginsOptions, CalcBlock, type CalcBlockProps, CalcEditorHooks, type CalcFence, CalcInline, type CalcInlineProps, CalcTokenKind, CalcValue, type CitationData, type CitationStyle, type CiteItem, type CollectedCitations, DECISION_STATUSES, DEFAULT_TEMPLATE, DecisionCard, type DecisionCardProps, type DecisionStatus, DocumentOutline, type DocumentOutlineProps, ENTITY_KINDS, EditorCompletionProvider, EditorContentAccess, EditorSelection, EmbedAssetFn, EntityCard, type EntityCardProps, EntityChip, type EntityChipProps, type EntityKind, EvaluateCalc, type EvaluateIteration, FootnoteList, type FootnoteListProps, type InterpolateTemplate, IterationBlock, type IterationBlockProps, IterationBuilderDialog, type IterationBuilderDialogProps, IterationBuilderProvider, type IterationBuilderValue, type IterationCell, type IterationData, IterationEditHandler, type IterationLayout, type IterationSpec, IterationTemplateDialog, type IterationTemplateDialogProps, IterationTemplateProvider, KnowledgeCard, type KnowledgeCardProps, type KnowledgeSourceResolved, type KnowledgeSourceResolver, MARKDOWN_HEADING_REM, MARKDOWN_HEADING_TRACKING, MARKDOWN_HEADING_WEIGHT, MARKDOWN_MEASURE, type MarkdownAnnotation, type MarkdownAnnotationKind, type MarkdownDirectiveContext, type MarkdownDirectiveKind, type MarkdownDirectiveRenderer, type MarkdownExtensions, type MarkdownFenceContext, type MarkdownFenceRenderer, type MarkdownHeadingInfo, type MarkdownHeadingLevel, type MarkdownOutlineItem, MarkdownPreview, type MarkdownPreviewProps, MarkdownToolbar, type MarkdownToolbarProps, type MarkdownUrlKind, MarkdownWorkspace, type MarkdownWorkspaceHandle, type MarkdownWorkspaceMode, type MarkdownWorkspaceProps, MathBlock, MathInline, type MathProps, MermaidDiagram, type MermaidDiagramProps, MermaidWorkspace, type MermaidWorkspaceProps, MetricBlock, type MetricBlockProps, MonacoSlashMenu, type MonacoSlashMenuProps, type ParsedDocument, type ProseMirrorContentAccessDeps, type ProseMirrorContentAccessOptions, type ResolveCitation, type ResolvedCitation, SlashCommand, SlashMenu, type SlashMenuProps, TableOfContents, type TableOfContentsProps, aiObjectDirectives, annotationForRange, attachCalcMonaco, attachCompletionsMonaco, brandSlashViewPlugins, buildMarkdownPlugins, builderValueFromParts, calcProsePlugins, calcTokenClassName, collectCitations, computeMarkdownAnnotations, decisionCardVariants, decisionDirective, defaultInterpolate, directivePartsFromValue, emptyBuilderValue, entityChipVariants, entityDirective, evaluateEmbedded, findCalcFences, insertDirective, insertHorizontalRule, insertLink, knowledgeDirective, markdownScaleVars, mergeNormalizedEdit, parseAttributes, parseFrontmatter, parseIterationDirective, parseMarkdown, parseMarkdownOutline, proseMirrorContentAccess, remarkBrandDirectives, removedMarkerAt, selectionWatchPlugin, serializeFrontmatter, serializeIterationDirective, shiftAnnotations, specFromDirective, splitList, staticMarkdownFromValue, summarizeAnnotations, toggleLinePrefix, transposeIterationValue, useMarkdownOutline, wrapSelection };