@latentic/live-markdown 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,805 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _codemirror_view from '@codemirror/view';
+import { Decoration, ViewPlugin, DecorationSet, ViewUpdate, EditorView, Command, KeyBinding } from '@codemirror/view';
+import * as _codemirror_state from '@codemirror/state';
+import { EditorState, Facet, Extension } from '@codemirror/state';
+import { syntaxTree } from '@codemirror/language';
+
+/**
+ * Core value types for the editor's public surface.
+ *
+ * `SourceRange` is a half-open byte range into the document; `DocumentTextChange`
+ * describes one edit. They are structurally identical to the host app's own
+ * range/change types, so a host can pass its `onChange` straight through without
+ * adapting — structural typing makes them interchangeable.
+ */
+/** A half-open range into the document, in UTF-8 byte offsets. */
+interface SourceRange {
+    start: number;
+    end: number;
+}
+/** One text edit: the replaced byte range and the text inserted in its place. */
+interface DocumentTextChange {
+    range: SourceRange;
+    text: string;
+}
+
+/**
+ * Rich copy/cut (#135): every copy writes BOTH clipboard flavors —
+ *
+ *   text/plain — the markdown SOURCE of the selection (lossless: editors,
+ *                terminals, and Compose→Compose round trips);
+ *   text/html  — the selection rendered by the host (Google Docs, Slack,
+ *                Word, and Gmail paste it formatted).
+ *
+ * The HTML carries {@link COMPOSE_CLIPBOARD_ATTR} so our own paste handler
+ * prefers the markdown flavor instead of re-converting our rendering.
+ *
+ * Stays out of the way of: the table surface's TSV cell-selection copy (a
+ * capture-phase document listener that preventDefaults first), and CM's
+ * native empty-selection behavior. Without a host renderer the handler still
+ * runs — plain-only, but through one code path.
+ */
+
+/** Host-supplied markdown → HTML renderer for clipboard writes. Null (the
+ *  default) copies plain markdown only. Wired like the other host seams —
+ *  see hostFacets.ts. */
+type RenderClipboardHtml = (markdown: string) => string | null;
+
+/**
+ * The rendering contract: one polymorphic shape for "how does a Lezer node
+ * render", replacing three parallel dispatch surfaces (a data-entry union, a
+ * widget-name union + builders map, and a contextual-override switch).
+ *
+ *   NodeRule  = (ctx) => Paint      — one function per node NAME
+ *   Paint     = which CM6 mechanism  — a CLOSED union
+ *
+ * The openness is split on the right axis: CONSTRUCTS grow (every new node
+ * adds a rule — one entry, one place, usually one line via the combinators
+ * below), while the ways to PAINT don't (line class / span mark / hide /
+ * widget / nothing — CodeMirror's own vocabulary). The single switch over
+ * `Paint` lives in the painter (plugin.ts) and never changes when a
+ * construct is added.
+ *
+ * Context (the bare-URL lesson: a node name can mean different things in
+ * different parents) is not a bolt-on — every rule IS a function of context;
+ * simple rules just ignore it.
+ *
+ * Extensions contribute rules through {@link nodeRulesFacet}: a plugin that
+ * introduces node names ships its rules alongside its grammar, touching no
+ * core file.
+ */
+
+interface NodeLike {
+    readonly name: string;
+    readonly from: number;
+    readonly to: number;
+    readonly parent: NodeLike | null;
+    readonly firstChild: NodeLike | null;
+    readonly nextSibling: NodeLike | null;
+    readonly prevSibling: NodeLike | null;
+    getChild(type: string): NodeLike | null;
+}
+/** Everything a rule may consult. */
+interface NodeContext {
+    readonly name: string;
+    readonly from: number;
+    readonly to: number;
+    /** The parent node's name — the common contextual discriminator. */
+    readonly parentName: string | undefined;
+    /** Full structural node, for rules that need siblings/children. */
+    readonly node: NodeLike;
+    /** Rules are pure over state — no view dependency, so non-editor
+     *  renderers (table cells) can invoke the same rules. */
+    readonly state: EditorState;
+}
+/** One painting instruction, in CodeMirror's own vocabulary. */
+type Paint = 
+/** Stamp a line class — on the node's first line, or every spanned line. */
+{
+    readonly paint: "lineClass";
+    readonly className: string;
+    readonly span: "first" | "all";
+}
+/** Style the node's span. */
+ | {
+    readonly paint: "mark";
+    readonly className: string;
+}
+/**
+ * Hide a range (default: the node, plus its one separator space when
+ * line-leading) and make it atomic to caret motion. `atomicTo` widens the
+ * atom past the hidden range (marker + space move as one unit).
+ */
+ | {
+    readonly paint: "hide";
+    readonly range?: {
+        readonly from: number;
+        readonly to: number;
+    };
+    readonly expandSpace?: boolean;
+    readonly atomicTo?: number;
+}
+/** Replace the (hidden) span with a widget decoration. */
+ | {
+    readonly paint: "widget";
+    readonly deco: Decoration;
+    readonly atomicTo?: number;
+}
+/** Leave the node alone — visible raw source. */
+ | {
+    readonly paint: "none";
+};
+interface RuleMeta {
+    readonly intent: "render-raw" | "structural";
+    readonly why: string;
+}
+/** How one node name renders. `meta` tags the deliberate do-nothing rules so
+ *  the coverage test can insist their reason is documented. */
+type NodeRule = ((ctx: NodeContext) => Paint) & {
+    readonly meta?: RuleMeta;
+};
+type NodeRules = Readonly<Record<string, NodeRule>>;
+/** Style the node's span with a class. */
+declare function mark(className: string): NodeRule;
+/** Stamp a line class on every line the node spans. */
+declare function line(className: string): NodeRule;
+/** Stamp a line class on the node's first line only (headings). */
+declare function headingLine(className: string): NodeRule;
+/** Hide the node (marker chrome), atomically. */
+declare function hideAlways(): NodeRule;
+/** Deliberately unstyled-for-now, visible raw — `why` documents the intent. */
+declare function raw(why: string): NodeRule;
+/** A parser grouping construct, never directly visible — `why` says which. */
+declare function structural(why: string): NodeRule;
+/**
+ * Rules contributed by extensions, merged over the base table (an extension
+ * may also deliberately override a base rule — last provider wins). The
+ * painter reads THIS, never the base table directly.
+ */
+declare const nodeRulesFacet: Facet<Readonly<Record<string, NodeRule>>, Readonly<Record<string, NodeRule>>>;
+
+/**
+ * A syntax tree that reaches `pos`.
+ *
+ * `syntaxTree` returns only what the **viewport** has driven the parser
+ * through, so `resolveInner` past that point reports the position as bare
+ * `Document`. Every command that asks "am I inside a list / a fence / a table?"
+ * then gets "no" and takes the plain-text path: a wrong answer, not a slow one.
+ *
+ * Measured in WebKit, the engine we ship on, with real layout — two regimes.
+ *
+ * On the frame a document opens the parser has covered a few thousand
+ * characters: 3,009 of 7,902, viewport 0–331, for an editor 11,404px tall. The
+ * idle parse then catches up within about half a second, so near the viewport
+ * this is a race — and it heals before a hand-test can see it.
+ *
+ * Further out it never heals. The idle parse stops 100,000 characters past the
+ * viewport: the tree plateaus at 100,739 for a 167k-character document and a
+ * 341k one alike, and stays there. `ensureSyntaxTree` resumes from that plateau
+ * and finishes the 341k document in 43ms — inside the budget above.
+ *
+ * Only for questions about a *position*. Decoration plugins iterate
+ * `view.visibleRanges` and should keep using `syntaxTree` directly: there,
+ * being limited to the viewport is the point.
+ */
+type Tree = ReturnType<typeof syntaxTree>;
+declare function treeAt(state: EditorState, pos: number): Tree;
+
+/**
+ * Markdown decoration plugin — the PAINTER. Walks the Lezer tree against the
+ * visible viewport, asks each node's {@link NodeRule} how to render, and
+ * applies the returned {@link Paint}.
+ *
+ * The painter contains *no* construct knowledge: rules live in the base
+ * table (`NODE_RULES`) merged with any extension-contributed rules
+ * (`nodeRulesFacet`). The one switch here is over `Paint` — CodeMirror's
+ * closed set of mechanisms — so adding a construct, widget, contextual
+ * override, or whole extension never edits this file.
+ *
+ * Perf shape (unchanged from the spike):
+ *   * Walks `view.visibleRanges` against `syntaxTree(view.state)` —
+ *     the work is proportional to the viewport, not the document.
+ *   * Rebuilt on doc change or viewport change.
+ *
+ * Decoration ordering (CM6 requires `from`-then-`startSide` ascending):
+ *   * Line decorations collected in one bucket, mark / replace in
+ *     another. The final `Decoration.set` lets CM6 sort defensively,
+ *     costing ~µs on the typical viewport — cheaper than risking the
+ *     "decorations out of order" runtime error.
+ */
+
+declare const markdownDecorationsPlugin: ViewPlugin<{
+    decorations: DecorationSet;
+    atomic: DecorationSet;
+    update(update: ViewUpdate): void;
+}, undefined>;
+
+/**
+ * Editor theme.
+ *
+ * Lives in `EditorView.baseTheme` rather than in `global.scss` for
+ * three load-bearing reasons:
+ *
+ *   1. **Line-metric integrity.** CM6 measures line heights from the
+ *      DOM through a `requestMeasure` cycle to compute click → byte
+ *      and scroll → viewport mappings. Styles injected via
+ *      `EditorView.theme` participate in that cycle at the right
+ *      moment; styles from an external sheet can land *after* the
+ *      first measurement, so clicks land on the wrong line until the
+ *      next measure fires. (This was the click-drift the spike
+ *      shipped — fixed by moving here.)
+ *   2. **Specificity that beats the base theme without `!important`.**
+ *      CM6 ships its monospace-and-purple base theme via the same
+ *      mechanism; layering `EditorView.theme` on top is the only
+ *      collision-free pattern.
+ *   3. **No margin/padding on heading lines.** Margins between
+ *      `.cm-line` siblings shift visual position without changing
+ *      `offsetTop`, so the metric cache and the eye disagree —
+ *      that's the canonical click-on-wrong-line bug. We change
+ *      `font:` (which doesn't touch line-height), nothing else.
+ *
+ * Zettlr's `markdown-editor/theme/editor.ts` is the canonical
+ * reference for this pattern in the open-source ecosystem.
+ */
+/**
+ * `EditorView.theme` (not `baseTheme`) — `baseTheme` is the
+ * low-priority slot meant for theme packages and gets out-specifity'd
+ * by any app-level CSS (Carbon's globals in our case). `theme` is the
+ * app-priority slot; our intent is to override CM6's defaults, so
+ * this is the right tier.
+ */
+declare const editorBaseTheme: _codemirror_state.Extension;
+
+/**
+ * Display-time resolution of image `src` values for the editor — the
+ * environment-agnostic pieces.
+ *
+ * Markdown stores image references **workspace-relative and portable** (e.g.
+ * `images/pasted-….png`), which is what lands on disk and survives moving the
+ * folder between machines. A WebView, though, can't load a bare relative path
+ * against its app origin, so a host that streams local files needs to map the
+ * reference onto its own asset protocol.
+ *
+ * This module provides the host-independent parts: the POSIX path helpers
+ * (`computeFileDir` / `joinPath` / …), the `hasUriScheme` guard, and
+ * `defaultResolveImageSrc` (render as-is — the browser/SSR default). A desktop
+ * host composes these with its file API (e.g. Tauri `convertFileSrc`) to build
+ * its own resolver and injects it via the editor's `resolveImageSrc` prop. The
+ * stored markdown reference is never rewritten — only the rendered `<img src>`.
+ *
+ * Paths are treated as POSIX (`/`), matching the macOS/Linux workspace folders
+ * this targets. Windows-style drive paths are passed through unresolved.
+ */
+interface ImageResolveContext {
+    /** Absolute OS directory of the markdown file being edited, or null. */
+    fileDir: string | null;
+}
+/**
+ * True when `src` already carries a URI scheme, a protocol-relative `//`, or a
+ * bare fragment — i.e. it's directly loadable and needs no path resolution. A
+ * host's display-src resolver uses this to decide whether to map a relative
+ * workspace path onto its own asset protocol.
+ */
+declare function hasUriScheme(src: string): boolean;
+/**
+ * Environment-agnostic default for the editor's `resolveImageSrcFacet`: render
+ * the reference as-is. Data URLs and absolute/schemed URLs load directly; a
+ * relative ref resolves against the page origin (or shows broken if no backing
+ * file). A desktop host overrides the facet with its own resolver, which maps
+ * relative paths onto a local asset protocol.
+ */
+declare function defaultResolveImageSrc(rawSrc: string, _ctx: ImageResolveContext): string;
+/**
+ * The directory a relative image reference resolves against: the folder
+ * containing the active markdown file. Falls back to the workspace root when
+ * the file path is unknown, and to null when there's no workspace.
+ */
+declare function computeFileDir(workspaceRoot: string | null | undefined, filePath: string | null | undefined): string | null;
+declare function isAbsolutePath(p: string): boolean;
+/** POSIX `dirname`: the parent of a path, with trailing slashes ignored. */
+declare function dirnamePath(p: string): string;
+/**
+ * Join `rel` onto `dir`, normalizing `.` and `..` segments. Absolute-ness is
+ * inherited from `dir`; `..` never escapes above an absolute root.
+ */
+declare function joinPath(dir: string, rel: string): string;
+
+/**
+ * Host-environment injection seams.
+ *
+ * The editor surface is environment-agnostic: it knows how to render and edit
+ * markdown, but NOT how to read/write files, resolve asset URLs, or open links —
+ * those depend on where it's embedded (a Tauri desktop shell, a plain browser, a
+ * server-rendered preview). Each capability is a CM6 facet with a sensible
+ * browser default; the React host overrides it by setting the facet from a prop.
+ *
+ * Keeping these as facets (not React context) lets the non-React CM6 plugins and
+ * widgets — image paste handlers, the inline `<img>` widget, the click model —
+ * read them straight off `view.state`.
+ */
+
+type ResolveImageSrc = (rawSrc: string, ctx: ImageResolveContext) => string;
+type SaveImageBytes = (relPath: string, bytes: Uint8Array) => Promise<void>;
+type OpenExternalUrl = (url: string) => void;
+/** Viewport point a comment composer should anchor to (the right-click point). */
+type CommentAnchor = {
+    x: number;
+    y: number;
+};
+type CommentOnExcerpt = (excerpt: {
+    text: string;
+    range: SourceRange;
+}, anchor: CommentAnchor) => void;
+
+type CodeMirrorEditorMode = "wysiwyg" | "source";
+/** A non-empty editor selection, in document byte offsets. */
+interface EditorSelectionSnapshot {
+    range: SourceRange;
+    text: string;
+}
+interface CodeMirrorMarkdownEditorProps {
+    mode?: CodeMirrorEditorMode;
+    onChange: (value: string, changes: DocumentTextChange[]) => void;
+    value: string;
+    workspaceRoot?: string;
+    filePath?: string;
+    linkTargets?: ReadonlySet<string>;
+    onNavigateToLink?: (path: string) => void;
+    /**
+     * Host-rendered toolbar. The editor owns the live `EditorView` and hands it to
+     * the slot; the host builds whatever toolbar UI it wants (formatting buttons,
+     * file actions, …) around it. Omit for a chromeless editor. Return a STABLE
+     * element shape so the host's own memoisation can hold across keystrokes.
+     */
+    toolbar?: (ctx: {
+        view: EditorView;
+    }) => ReactNode;
+    /**
+     * Host-rendered actions for the current text selection (e.g. a comment / ask
+     * bubble). Called with the live selection (or `null` when collapsed) and a
+     * `dismiss` that collapses the selection back to a caret. Omit for none.
+     */
+    selectionActions?: (ctx: {
+        selection: EditorSelectionSnapshot | null;
+        dismiss: () => void;
+    }) => ReactNode;
+    /**
+     * Map a markdown image `src` to a loadable URL. Default: render the reference
+     * as-is. A desktop host maps workspace-relative paths onto its asset protocol.
+     */
+    resolveImageSrc?: ResolveImageSrc;
+    /**
+     * Persist a pasted/dropped image's bytes at a workspace-relative path.
+     * Default: omitted ⇒ the image is inlined as a `data:` URL.
+     */
+    saveImageBytes?: SaveImageBytes;
+    /**
+     * Open a clicked external link. Default: a new browser tab. A desktop host
+     * overrides this to leave the app's webview.
+     */
+    onOpenExternalUrl?: OpenExternalUrl;
+    /**
+     * Comment on a selected table row/column — wired to the table context menu's
+     * "Comment on this row / column". The host opens its comment composer at the
+     * given anchor, seeded with the excerpt. Default: omitted ⇒ no such menu items.
+     */
+    onCommentOnExcerpt?: CommentOnExcerpt;
+    /**
+     * Render a markdown selection to HTML for the clipboard, so a copy pastes
+     * formatted into Google Docs / Slack / Word (the markdown source always
+     * rides along as text/plain). Default: omitted ⇒ plain-only copies.
+     */
+    renderClipboardHtml?: RenderClipboardHtml;
+    /**
+     * Called once, right after a tab-switch content swap commits and paints.
+     * Used by the host for latency instrumentation; no-op by default.
+     */
+    onAfterContentSwap?: () => void;
+    /**
+     * Receives a synchronous `flush()` that pulls the editor's live (debounce-
+     * lagged) content into the last `onChange` immediately — the host calls it
+     * before persisting. `null` is passed on unmount. Lets a host avoid writing
+     * stale buffers on Cmd+S / tab close.
+     */
+    onFlushReady?: (flush: (() => void) | null) => void;
+}
+declare function CodeMirrorMarkdownEditorInner({ mode, onChange, value, workspaceRoot, filePath, linkTargets, onNavigateToLink, toolbar, selectionActions, resolveImageSrc, saveImageBytes, onOpenExternalUrl, onCommentOnExcerpt, renderClipboardHtml, onAfterContentSwap, onFlushReady, }: CodeMirrorMarkdownEditorProps): react_jsx_runtime.JSX.Element;
+/**
+ * Memoised export — same reason as the Tiptap editor. AppShell
+ * re-renders on every chat-thread token; without memoisation each
+ * token would blow through the editor's render path.
+ */
+declare const CodeMirrorMarkdownEditor: react.MemoExoticComponent<typeof CodeMirrorMarkdownEditorInner>;
+
+declare const formatCommands: {
+    toggleBold: Command;
+    toggleItalic: Command;
+    toggleInlineCode: Command;
+};
+
+declare const blockCommands: {
+    toggleHeading1: Command;
+    toggleHeading2: Command;
+    toggleHeading3: Command;
+    toggleBulletList: Command;
+    toggleOrderedList: Command;
+    toggleTaskList: Command;
+    toggleBlockquote: Command;
+    toggleCodeBlock: Command;
+    insertTable: Command;
+};
+
+/**
+ * Editor-update fan-out that survives `view.setState`.
+ *
+ * Reactive chrome (toolbar pressed-states, the selection-actions bubble)
+ * needs a callback on every selection/doc change. Injecting an
+ * `EditorView.updateListener` with `StateEffect.appendConfig` only patches
+ * the CURRENT state's configuration — the next `view.setState` (tab switch,
+ * file reload) builds a fresh state from the base extensions and the
+ * listener silently dies, freezing the chrome at the previous document's
+ * context.
+ *
+ * The bus lives IN the base extensions, so every created state carries it,
+ * while subscriptions key on the `EditorView` — the object that is stable
+ * across state swaps.
+ */
+
+/**
+ * Subscribe to every update of `view`, across all its future states.
+ * Returns the unsubscribe function — call it in the effect cleanup.
+ */
+declare function onEditorUpdate(view: EditorView, fn: (update: ViewUpdate) => void): () => void;
+
+interface ToolbarContribution {
+    readonly id: string;
+    readonly group: "heading" | "format" | "block" | "insert" | string;
+    readonly label: string;
+    readonly icon: ReactNode;
+    readonly shortcut?: string;
+    readonly isActive?: (caretContext: CaretContextSnapshot) => boolean;
+    readonly run: (view: _codemirror_view.EditorView) => void;
+}
+interface CaretContextSnapshot {
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly code: boolean;
+    readonly link: boolean;
+    readonly heading: 1 | 2 | 3 | 4 | 5 | 6 | 0;
+    readonly bulletList: boolean;
+    readonly orderedList: boolean;
+    readonly blockquote: boolean;
+}
+interface MarkdownExtension {
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string;
+    /** Node rules for constructs this extension's grammar introduces (or
+     *  deliberately overrides) — merged into the decoration painter via
+     *  `nodeRulesFacet`, so an extension never edits the base table. */
+    readonly rules?: NodeRules;
+    readonly extensions?: Extension[];
+    readonly keymap?: KeyBinding[];
+    readonly toolbar?: ToolbarContribution[];
+}
+
+interface ComposedExtension {
+    extensions: Extension[];
+    toolbar: ToolbarContribution[];
+}
+declare function composeExtensions(modules: readonly MarkdownExtension[]): ComposedExtension;
+
+declare const highlightExtension: MarkdownExtension;
+
+declare const footnoteExtension: MarkdownExtension;
+
+declare const mathExtension: MarkdownExtension;
+
+declare const mermaidExtension: MarkdownExtension;
+
+/**
+ * A FACTORY, not a const: each composition gets its own editing surface (the
+ * one-active-edit state), so two mounted editors can never share a cell edit.
+ */
+declare function tableExtension(): MarkdownExtension;
+
+declare const wikilinkExtension: MarkdownExtension;
+
+/**
+ * Mermaid rendering, decoupled from CodeMirror — shared by the editor widget,
+ * the document export (which ships the SVG to the backend), and the clipboard
+ * (which needs a PNG, since Google Docs/Word drop SVG on paste).
+ *
+ * The mermaid library is heavy (~2 MB minified), so it loads lazily on the
+ * first diagram — bundled with the app, never fetched at runtime, so diagrams
+ * work fully offline. Render results are cached by source text; PNGs are
+ * rasterised once per diagram in the background (see {@link warmMermaidPng})
+ * so the SYNCHRONOUS copy event can embed them from cache.
+ */
+type MermaidRenderResult = {
+    ok: true;
+    svg: string;
+} | {
+    ok: false;
+    message: string;
+};
+/** Whether a fence info string denotes a rendered mermaid diagram — the tag
+ *  alone, any casing, no trailing meta ("mermaid title=x" is source, not a
+ *  diagram). The one definition shared by the editor plugin, the export's SVG
+ *  collector, and the clipboard, so every surface classifies identically. */
+declare function isMermaidFenceInfo(info: string): boolean;
+/** Render a mermaid diagram source to SVG, memoised by source. Never rejects —
+ *  a parse error resolves to `{ ok: false, message }`. */
+declare function renderMermaidToSvg(source: string): Promise<MermaidRenderResult>;
+/** The cached PNG data URI for a diagram source, if it has been rasterised. */
+declare function getCachedMermaidPng(source: string): string | null;
+/** Render + rasterise a diagram in the background so a LATER (synchronous)
+ *  clipboard copy can embed it from cache. Fire-and-forget: failures leave the
+ *  cache empty and the copy degrades to the source block. */
+declare function warmMermaidPng(source: string): Promise<void>;
+
+/**
+ * Synchronous fence highlighting for the clipboard (#149).
+ *
+ * A copy event writes `text/html` synchronously, so highlighting must not
+ * await anything. The trick: the grammars are the SAME `@codemirror/language-data`
+ * singletons the editor's nested fence parse loads — any fence visible in the
+ * editor has its grammar warm, so highlighting the copied code is a sync parse.
+ * A cold grammar (copy from a doc whose fence never rendered) kicks the load
+ * and returns null: THIS copy ships plain, the next one is highlighted.
+ *
+ * Output is inline-styled spans (the palette from
+ * [codePalette](./codePalette.ts), same colors as the editor) — pasted HTML
+ * carries no stylesheet, so classes would be dead weight in Docs/Word.
+ */
+interface HighlightedSpan {
+    text: string;
+    /** Inline CSS for the span; absent for unstyled text (incl. line breaks). */
+    style?: string;
+}
+/** Highlight `code` as `lang` into inline-styled spans, or null when no
+ *  grammar matches or the grammar isn't loaded yet (the load is kicked so a
+ *  later copy succeeds). Never throws — a parser hiccup falls back to null. */
+declare function highlightFenceSpans(lang: string, code: string): HighlightedSpan[] | null;
+
+/**
+ * Image-insertion pipeline. Used by both paste-from-clipboard and
+ * drag-and-drop. Both produce a `Blob`; this module turns the blob
+ * into a markdown-reference-able path:
+ *
+ *   * When a `saveBytes` writer is injected (a desktop host): writes
+ *     the bytes to `images/<timestamp>-<hash>.<ext>` and returns the
+ *     relative path. The markdown reference is portable across
+ *     machines because it's a real on-disk file.
+ *   * Otherwise (plain browser, or the write fails): falls back to a
+ *     data URL embedded directly in the markdown. The markdown file
+ *     bloats but the image stays visible through page reload without
+ *     needing a binary file API.
+ *
+ * The writer is injected rather than imported so this module stays
+ * environment-agnostic — the editor reads it off a CM6 facet
+ * ({@link saveImageBytesFacet}) the host wires up.
+ *
+ * Returned `markdownReference` is what the caller drops into
+ * `![alt](…)`. `warning` is set in the data-URL fallback case so
+ * the caller can surface a note to the user.
+ */
+interface ImageInsertOptions {
+    blob: Blob;
+    /**
+     * Persist the bytes at a workspace-relative path. `null`/omitted ⇒
+     * inline as a data URL (browser fallback).
+     */
+    saveBytes?: ((relPath: string, bytes: Uint8Array) => Promise<void>) | null;
+    /**
+     * Alt text the user typed (currently always synthesized as
+     * "pasted-image" or "dropped-image"; in phase 3d the inline
+     * rename UI lets the user edit it post-insert).
+     */
+    alt?: string;
+}
+interface ImageInsertResult {
+    markdownReference: string;
+    alt: string;
+    warning?: string;
+}
+/**
+ * Save the blob and return the markdown reference. Errors are
+ * structured (the caller decides whether to retry with a fallback
+ * or surface a notification).
+ */
+declare function insertImageBlob(opts: ImageInsertOptions): Promise<ImageInsertResult>;
+/**
+ * Build a markdown image insertion string from the result. Keeps
+ * the call site (handlePaste / handleDrop) tidy.
+ */
+declare function buildImageMarkdown(result: ImageInsertResult): string;
+/**
+ * Scan a DataTransferItemList for image blobs. Returns every
+ * image found, in order. Empty array when nothing matches —
+ * caller treats that as "fall through to text paste".
+ */
+declare function extractImageBlobs(items: DataTransferItemList | null | undefined): Blob[];
+/**
+ * Scan a FileList (drag-and-drop's `dataTransfer.files`) for
+ * image files. Drag-drop and paste use different shapes; this
+ * keeps the two paths symmetrical at the call site.
+ */
+declare function extractImageFiles(files: FileList | null | undefined): File[];
+
+declare const imageInsertHandlers: _codemirror_state.Extension;
+/**
+ * Open the browser's native file picker, then run the picked files
+ * through the same insert pipeline. Called by the toolbar's Image
+ * button.
+ */
+declare function pickImageFileForCaret(view: EditorView): void;
+
+interface ShowMenuArgs {
+    x: number;
+    y: number;
+    view: EditorView;
+    alt: string;
+    rawSrc: string;
+    sourceFrom: number;
+    sourceTo: number;
+}
+declare function showImageActionMenu(args: ShowMenuArgs): void;
+
+/**
+ * The "edit this image's alt text" custom-event contract — a plain constant and
+ * type with NO runtime CodeMirror dependency (the `EditorView` reference is
+ * `import type`, erased at build). The lazy-loaded editor dispatches this event;
+ * the host shell listens for it. Keeping the contract here means a host can
+ * import the event name without pulling the whole editor into its initial
+ * bundle (it previously came from `imageActionMenu`, which imports CodeMirror).
+ */
+declare const IMAGE_EDIT_ALT_EVENT = "ai-editor:edit-image-alt";
+interface ImageEditAltEventDetail {
+    view: EditorView;
+    sourceFrom: number;
+    sourceTo: number;
+    currentAlt: string;
+    rawSrc: string;
+}
+
+/**
+ * YAML frontmatter parsing + serialization.
+ *
+ * Convention: `--- yaml ---` block at the very top of a markdown
+ * file (before any other content). Format:
+ *
+ *   ---
+ *   status: draft
+ *   tags:
+ *     - application
+ *     - fellowship
+ *   ---
+ *
+ *   # Real content starts here
+ *
+ * This module separates the YAML chunk from the prose chunk so
+ * the WYSIWYG editor can render only the prose (no raw `key:
+ * value` lines bleeding into the user's writing surface) while a
+ * separate properties UI shows / edits the frontmatter.
+ *
+ * Round-trip rules:
+ *   - If a file has no frontmatter on disk, we MUST NOT add one
+ *     on save just because the properties panel exists.
+ *   - If a file has frontmatter, we serialize it using the same
+ *     keys/order the user wrote (best effort — yaml lib preserves
+ *     scalar formatting but not always blank lines / comments).
+ *   - The fence marker is always exactly `---` on its own line.
+ *     Some Obsidian users prefer `+++` (TOML) — out of scope for
+ *     v1; we round-trip those as body content unchanged.
+ */
+/**
+ * The frontmatter value type. Each entry is whatever YAML can
+ * decode to — strings, numbers, booleans, arrays, nested objects.
+ * The properties UI handles primitives + flat arrays cleanly;
+ * nested objects fall back to a raw YAML editor.
+ */
+type FrontmatterValue = string | number | boolean | null | FrontmatterValue[] | {
+    [key: string]: FrontmatterValue;
+};
+type Frontmatter = Record<string, FrontmatterValue>;
+interface MarkdownDocument {
+    /** Parsed YAML key/values. `null` means "no frontmatter block present". */
+    frontmatter: Frontmatter | null;
+    /** The prose portion — everything after the closing `---`. */
+    body: string;
+}
+/**
+ * Split a markdown string into its frontmatter + body. Tolerant
+ * of:
+ *   - No frontmatter at all → `frontmatter: null, body: input`
+ *   - Malformed YAML → `frontmatter: null, body: input` (we treat
+ *     the whole thing as prose rather than show parse errors)
+ *   - Empty frontmatter block (`---\n---`) → `frontmatter: {}`
+ */
+declare function parseFrontmatter(markdown: string): MarkdownDocument;
+/**
+ * Recombine frontmatter + body into a markdown string. Inverse
+ * of `parseFrontmatter` for legal inputs.
+ *
+ *   - `frontmatter: null` → just the body, no `---` fences added
+ *   - `frontmatter: {}` → no fences either (an empty frontmatter
+ *     block is semantically the same as "no frontmatter" and we
+ *     prefer the cleaner shape on save)
+ *   - Otherwise → `---\n<yaml>\n---\n<body>`
+ */
+declare function serializeMarkdown(doc: MarkdownDocument): string;
+/**
+ * Helper: update a single frontmatter field in a markdown string
+ * without touching the body. Used by the Properties UI when the
+ * user edits one value at a time.
+ *
+ * If the file had no frontmatter, this adds one with just the
+ * one field. If the value is `null` and the key exists, removes
+ * the key (and removes the whole frontmatter block if it becomes
+ * empty).
+ */
+declare function setFrontmatterField(markdown: string, key: string, value: FrontmatterValue | null): string;
+
+/**
+ * Wikilink (`[[target]]` / `[[target|label]]`) parsing + target resolution.
+ *
+ * The canonical rule lives in the `workspace-index` crate
+ * (`wikilink_target_and_label` / `resolve_document_target` / `path_stem_matches`
+ * / `slug_key`) — that's what builds the backlink graph. This is the
+ * **client-side mirror** used to navigate a *clicked* wikilink, so the editor
+ * and chat agree with the sidebar's backlinks. Keep the two in sync; if the
+ * crate's rule changes, change it here too.
+ *
+ * Difference from the crate: an unresolved target returns `null` (we only
+ * navigate to files that exist), whereas the crate keeps a would-be path for
+ * the graph edge.
+ */
+/** Split a wikilink body into its target and display label. */
+declare function parseWikilinkBody(body: string): {
+    target: string;
+    label: string;
+};
+/** Resolve a wikilink target to an existing workspace file path, or `null`. */
+declare function resolveWikilinkTarget(rawTarget: string, options: {
+    fromPath?: string;
+    knownPaths: ReadonlySet<string>;
+}): string | null;
+
+/**
+ * Resolve a markdown link href to a navigation target.
+ *
+ * A link in a document (or an agent's chat reply) is either:
+ *   - **external** — anything with a URI scheme (`https:`, `mailto:`, …) or a
+ *     protocol-relative `//host`; opened in the browser, and
+ *   - **internal** — a workspace-relative path that resolves to a file the
+ *     workspace actually contains; opened in a tab.
+ *
+ * This is pure path resolution (normalize `.`/`..`, reject escaping the vault
+ * root, membership-check against the known files) — it is **not** the index's
+ * link parser. The index already resolves links into `graphEdges`; this just
+ * decides where a *clicked* href points so the UI can navigate. An href that
+ * looks internal but matches no known file returns `null` (a broken link, not
+ * something to navigate to).
+ */
+type ResolvedWorkspaceLink = {
+    kind: "internal";
+    path: string;
+} | {
+    kind: "external";
+    href: string;
+};
+interface ResolveWorkspaceLinkOptions {
+    /** Workspace-relative path of the document the link lives in. Relative hrefs
+     * resolve against this file's directory. Omitted ⇒ resolve from the vault
+     * root (used for agent chat replies, which emit root-relative paths). */
+    fromPath?: string;
+    /** Every workspace-relative file path, for membership checks. */
+    knownPaths: ReadonlySet<string>;
+}
+declare function resolveWorkspaceLink(href: string, options: ResolveWorkspaceLinkOptions): ResolvedWorkspaceLink | null;
+
+export { type CaretContextSnapshot, type CodeMirrorEditorMode, CodeMirrorMarkdownEditor, type CodeMirrorMarkdownEditorProps, type ComposedExtension, type DocumentTextChange, type EditorSelectionSnapshot, type Frontmatter, type FrontmatterValue, type HighlightedSpan, IMAGE_EDIT_ALT_EVENT, type ImageEditAltEventDetail, type ImageInsertOptions, type ImageInsertResult, type ImageResolveContext, type MarkdownDocument, type MarkdownExtension, type MermaidRenderResult, type NodeContext, type NodeRule, type NodeRules, type OpenExternalUrl, type Paint, type ResolveImageSrc, type ResolveWorkspaceLinkOptions, type ResolvedWorkspaceLink, type SaveImageBytes, type SourceRange, type ToolbarContribution, blockCommands, buildImageMarkdown, composeExtensions, computeFileDir, defaultResolveImageSrc, dirnamePath, editorBaseTheme, extractImageBlobs, extractImageFiles, footnoteExtension, formatCommands, getCachedMermaidPng, hasUriScheme, headingLine, hideAlways, highlightExtension, highlightFenceSpans, imageInsertHandlers, insertImageBlob, isAbsolutePath, isMermaidFenceInfo, joinPath, line, mark, markdownDecorationsPlugin, mathExtension, mermaidExtension, nodeRulesFacet, onEditorUpdate, parseFrontmatter, parseWikilinkBody, pickImageFileForCaret, raw, renderMermaidToSvg, resolveWikilinkTarget, resolveWorkspaceLink, serializeMarkdown, setFrontmatterField, showImageActionMenu, structural, tableExtension, treeAt, warmMermaidPng, wikilinkExtension };