@sigx/lynx-markdown 0.4.8 → 0.4.9

package/README.md

@@ -147,6 +147,24 @@ ctrl?.setHeading(2);
 ctrl?.clear();              // chat send
 ```
 
+### Toolbar
+
+The built-in toolbar mirrors the renderer's override pattern — items are data,
+rendering is replaceable:
+
+```tsx
+<MarkdownEditor toolbar />                       // neutral default, below the input
+<MarkdownEditor toolbar="top" />                 // above instead
+<MarkdownEditor toolbar toolbarItems={items} />  // custom ToolbarItem[]
+<MarkdownEditor toolbar renderToolbarItem={fn} />// re-skin (what daisyUI does)
+```
+
+`<EditorToolbar>` is also exported standalone (pass `controller` + `selection`
+yourself — e.g. inside a keyboard-sticky send bar). `ToolbarItem` is
+`{ id, label, icon?, group?, isActive?(sel), run(ctx) }`; plugins contribute
+items through the same shape (P3). The toolbar root carries `ignore-focus` so
+taps never blur the editor. The daisyUI skin lives in `@sigx/lynx-daisyui`.
+
 v1 models paragraphs, headings, and bold/italic/strike/code/link in-field;
 everything else (lists, tables, code fences) round-trips **losslessly** as raw
 markdown source via `raw` blocks until later phases model them. Conversion

package/dist/ast.d.ts

@@ -8,7 +8,7 @@
  * reconciliation) and `raw` (the exact source slice, used for memo equality and
  * introspection).
  */
-export type InlineNode = InlineText | InlineStrong | InlineEm | InlineDel | InlineCodeSpan | InlineLink | InlineImage | InlineAutolink | InlineBreak;
+export type InlineNode = InlineText | InlineStrong | InlineEm | InlineDel | InlineCodeSpan | InlineLink | InlineImage | InlineAutolink | InlineBreak | InlineExtension;
 /** A run of literal text. */
 export interface InlineText {
     type: 'text';
@@ -58,6 +58,23 @@ export interface InlineAutolink {
 export interface InlineBreak {
     type: 'br';
 }
+/**
+ * A plugin-defined inline construct (e.g. a mention `@[label](id)`), produced
+ * by a `ParserInlineExtension`'s `match`. Opaque to the emphasis stack — same
+ * precedence tier as code spans and links. Rendered through
+ * `components.extension[name]`, falling back to `raw` as literal text.
+ */
+export interface InlineExtension {
+    type: 'extension';
+    /** Extension name; the render dispatch key. */
+    name: string;
+    /** Opaque structured payload (e.g. `{ id, label }` for a mention). */
+    attrs: Record<string, string>;
+    /** Optional nested inline content; absent for leaf extensions. */
+    children?: InlineNode[];
+    /** Exact source slice — the literal-text fallback and round-trip source. */
+    raw: string;
+}
 export interface BlockBase {
     /** Stable reconciliation key, assigned by the incremental engine. */
     key: string;

package/dist/editor/MarkdownEditor.d.ts

@@ -23,6 +23,9 @@
  */
 import { type Define } from '@sigx/lynx';
 import { type SelectionState } from '@sigx/lynx-richtext';
+import { type ToolbarRenderItem } from './toolbar/Toolbar.js';
+import { type ToolbarItem } from './toolbar/items.js';
+import type { MarkdownEditorPlugin } from './plugin.js';
 export type MarkdownEditorMode = 'auto' | 'fixed' | 'fullscreen';
 /** Imperative command surface — what toolbars and plugins drive. */
 export interface MarkdownEditorController {
@@ -33,6 +36,12 @@ export interface MarkdownEditorController {
     /** 1–6 sets a heading; 0 reverts to paragraph. */
     setHeading(level: 0 | 1 | 2 | 3 | 4 | 5 | 6): void;
     insertText(text: string): void;
+    /**
+     * Replace `[start, end)` (UTF-16 offsets in the document text) with
+     * `text`, leaving the caret after it. What trigger plugins use to swap
+     * the typed query for the selected suggestion.
+     */
+    replaceRange(start: number, end: number, text: string): void;
     /** Clear the document (chat send). */
     clear(): void;
     focus(): void;
@@ -42,7 +51,23 @@ export interface MarkdownEditorController {
     /** The current selection state (as of the last selection event). */
     getSelection(): SelectionState | null;
 }
-export type MarkdownEditorProps = Define.Prop<'value', string, false> & Define.Prop<'placeholder', string, false> & Define.Prop<'minLines', number, false> & Define.Prop<'maxLines', number, false> & Define.Prop<'mode', MarkdownEditorMode, false> & Define.Prop<'fontSize', number, false> & Define.Prop<'textColor', string, false> & Define.Prop<'accentColor', string, false> & Define.Prop<'placeholderColor', string, false> & Define.Prop<'confirmType', 'send' | 'search' | 'next' | 'go' | 'done', false> & Define.Prop<'autoFocus', boolean, false> & Define.Prop<'disabled', boolean, false> & Define.Prop<'class', string, false> & Define.Prop<'onChange', (markdown: string) => void, false> & Define.Prop<'onSelectionChange', (sel: SelectionState) => void, false> & Define.Prop<'onFocus', () => void, false> & Define.Prop<'onBlur', () => void, false>
+export type MarkdownEditorProps = Define.Prop<'value', string, false> & Define.Prop<'placeholder', string, false> & Define.Prop<'minLines', number, false> & Define.Prop<'maxLines', number, false> & Define.Prop<'mode', MarkdownEditorMode, false> & Define.Prop<'fontSize', number, false> & Define.Prop<'textColor', string, false> & Define.Prop<'accentColor', string, false> & Define.Prop<'placeholderColor', string, false> & Define.Prop<'confirmType', 'send' | 'search' | 'next' | 'go' | 'done', false> & Define.Prop<'autoFocus', boolean, false> & Define.Prop<'disabled', boolean, false> & Define.Prop<'class', string, false>
+/**
+ * Built-in formatting toolbar. `true` ≡ `'bottom'` — below the input is
+ * the common chat placement (selection handles and the iOS edit menu pop
+ * up *above* the selection, so a toolbar on top would sit under them).
+ */
+ & Define.Prop<'toolbar', boolean | 'top' | 'bottom', false>
+/** Override the built-in toolbar's items (defaults to `defaultToolbarItems`). */
+ & Define.Prop<'toolbarItems', ToolbarItem[], false>
+/** Re-skin the built-in toolbar's item rendering (what daisyUI does). */
+ & Define.Prop<'renderToolbarItem', ToolbarRenderItem, false>
+/**
+ * Editor plugins ({@link MarkdownEditorPlugin}) — inline syntax, trigger
+ * suggestions, extra toolbar items. Pass a stable array (e.g. a module
+ * constant); the set is captured at mount.
+ */
+ & Define.Prop<'plugins', MarkdownEditorPlugin[], false> & Define.Prop<'onChange', (markdown: string) => void, false> & Define.Prop<'onSelectionChange', (sel: SelectionState) => void, false> & Define.Prop<'onFocus', () => void, false> & Define.Prop<'onBlur', () => void, false>
 /** Receives the imperative controller once on mount. */
  & Define.Prop<'controllerRef', (ctrl: MarkdownEditorController) => void, false>;
 export declare const MarkdownEditor: import("@sigx/runtime-core").ComponentFactory<MarkdownEditorProps, void, {}>;

package/dist/editor/MarkdownEditor.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "@sigx/lynx/jsx-runtime";
 /**
  * `<MarkdownEditor>` — true-WYSIWYG markdown editing on the native
  * `<sigx-richtext>` element.
@@ -22,27 +22,89 @@ import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
  * `mode="fixed"` pins the height at `maxLines`; `mode="fullscreen"` fills the
  * parent.
  */
-import { component, signal, watch } from '@sigx/lynx';
+import { component, signal, useElementLayout, watch } from '@sigx/lynx';
 import { RichTextInput, RichTextMethods, docEquals, normalizeDoc, emptyDoc, } from '@sigx/lynx-richtext';
 import { mdToDoc } from './convert/mdToDoc.js';
 import { docToMd } from './convert/docToMd.js';
+import { EditorToolbar } from './toolbar/Toolbar.js';
+import { defaultToolbarItems } from './toolbar/items.js';
+import { createTriggerSessionManager } from './trigger/session.js';
+import { SuggestionPopup } from './trigger/SuggestionPopup.js';
 const DEFAULT_FONT_SIZE = 16;
 /** Vertical padding the element applies internally (8 top + 8 bottom). */
 const ELEMENT_PADDING = 16;
 export const MarkdownEditor = component(({ props }) => {
     let el = null;
+    // --- plugins (captured at mount; pass a stable array) ---
+    const plugins = props.plugins ?? [];
+    const inlinePlugins = plugins.filter((p) => p.inline);
+    // Duplicate identifiers would silently last-win (conversion maps) or make
+    // trigger routing ambiguous (plugin name lookups) — flag the config error.
+    const warnDuplicates = (key, values) => {
+        const seen = new Set();
+        for (const value of values) {
+            if (seen.has(value)) {
+                // Conversion maps resolve last-wins, trigger routing first-wins
+                // — don't promise either; duplicates are a config error.
+                console.warn(`[MarkdownEditor] duplicate plugin ${key} "${value}" — resolution is ambiguous, rename to disambiguate.`);
+            }
+            seen.add(value);
+        }
+    };
+    warnDuplicates('name', plugins.map((p) => p.name));
+    warnDuplicates('syntax.name', inlinePlugins.map((p) => p.inline.syntax.name));
+    warnDuplicates('docMapping.spanType', inlinePlugins.map((p) => p.inline.docMapping.spanType));
+    // Trigger routing is first-match-wins — a duplicate char/pattern means the
+    // later plugin's trigger is silently unreachable.
+    warnDuplicates('trigger', plugins
+        .filter((p) => p.trigger)
+        .map((p) => (p.trigger.char !== undefined ? `char:${p.trigger.char}` : `pattern:${p.trigger.pattern}`)));
+    const convertIn = inlinePlugins.length
+        ? {
+            extensions: inlinePlugins.map((p) => p.inline.syntax),
+            spanMappers: Object.fromEntries(inlinePlugins.map((p) => [p.inline.syntax.name, p.inline.docMapping.toSpan])),
+        }
+        : undefined;
+    const convertOut = inlinePlugins.length
+        ? {
+            serializers: new Map(inlinePlugins.map((p) => [
+                p.inline.docMapping.spanType,
+                (span, text) => p.inline.serialize(span, text),
+            ])),
+        }
+        : undefined;
+    const pluginToolbarItems = plugins.flatMap((p) => p.toolbar ?? []);
     // --- sync state (see module docs) ---
     const initialMd = typeof props.value === 'string' ? props.value : '';
     let lastEmittedMd = initialMd;
-    let lastDocFromElement = normalizeDoc(mdToDoc(initialMd));
+    let lastDocFromElement = normalizeDoc(mdToDoc(initialMd, 0, convertIn));
     let lastSeenVersion = 0;
     let composing = false;
     let pendingExternal = null;
-    let currentSel = null;
+    // Reactive box (not a plain var): the built-in toolbar derives active
+    // states from it, so selection events must re-render.
+    const selBox = signal({ current: null });
     // Auto-grow: the native element reports its (clamped) content height and
     // the editor feeds it back as the element's layout height — Lynx layout
     // sizes views from styles, never from native intrinsic content.
     const reportedHeight = signal(0);
+    // --- trigger sessions (suggestion popup) ---
+    const triggers = plugins
+        .filter((p) => p.trigger)
+        .map((p) => ({ plugin: p.name, spec: p.trigger }));
+    // Boxed like selBox: signal values must be objects.
+    const sessionBox = signal({ current: null });
+    const triggerManager = triggers.length
+        ? createTriggerSessionManager({
+            triggers,
+            onUpdate: (s) => {
+                sessionBox.current = s;
+            },
+        })
+        : null;
+    // Page-absolute frame of the input's relative wrapper — the popup needs
+    // it to relate the element-local caret rect to the keyboard.
+    const { layout: inputFrame, onLayoutChange: onInputLayout } = useElementLayout();
     const applyExternal = (md) => {
         if (md === lastEmittedMd)
             return; // our own echo
@@ -50,7 +112,7 @@ export const MarkdownEditor = component(({ props }) => {
             pendingExternal = md;
             return;
         }
-        const doc = mdToDoc(md, lastSeenVersion);
+        const doc = mdToDoc(md, lastSeenVersion, convertIn);
         if (docEquals(normalizeDoc(doc), lastDocFromElement)) {
             lastEmittedMd = md; // same content, different markdown spelling
             return;
@@ -65,9 +127,10 @@ export const MarkdownEditor = component(({ props }) => {
         composing = isComposing;
         lastSeenVersion = doc.v;
         lastDocFromElement = normalizeDoc(doc);
+        triggerManager?.syncText(doc.text);
         if (isComposing)
             return;
-        const md = docToMd(doc);
+        const md = docToMd(doc, convertOut);
         if (md !== lastEmittedMd) {
             lastEmittedMd = md;
             props.onChange?.(md);
@@ -90,13 +153,35 @@ export const MarkdownEditor = component(({ props }) => {
                 RichTextMethods.setBlockType(el, 'heading', level);
         },
         insertText: (text) => RichTextMethods.insertText(el, text),
+        replaceRange: (start, end, text) => {
+            // insertText replaces the selection — two existing fire-and-forget
+            // commands compose into a range replace (no new native method).
+            RichTextMethods.setSelectionRange(el, start, end);
+            RichTextMethods.insertText(el, text);
+        },
         clear: () => RichTextMethods.setDocument(el, emptyDoc(lastSeenVersion)),
         focus: () => RichTextMethods.focus(el),
         blur: () => RichTextMethods.blur(el),
         getMarkdown: () => lastEmittedMd ?? '',
-        getSelection: () => currentSel,
+        getSelection: () => selBox.current,
     };
     props.controllerRef?.(controller);
+    const handleTriggerSelect = (item) => {
+        const session = triggerManager?.session;
+        if (!session)
+            return;
+        const spec = plugins.find((p) => p.name === session.plugin)?.trigger;
+        if (!spec)
+            return;
+        const range = { start: session.anchor, end: session.caret };
+        const api = {
+            replaceQuery: (text) => controller.replaceRange(range.start, range.end, text),
+            range,
+            controller,
+        };
+        triggerManager.close();
+        spec.onSelect(item, api);
+    };
     return () => {
         const fontSize = props.fontSize ?? DEFAULT_FONT_SIZE;
         const lineHeight = Math.round(fontSize * 1.5);
@@ -109,19 +194,50 @@ export const MarkdownEditor = component(({ props }) => {
             minHeight = maxHeight;
         if (mode === 'fullscreen')
             maxHeight = 0; // unbounded; element fills parent
-        return (_jsx("view", { class: props.class, style: {
+        const toolbarPlacement = props.toolbar === true ? 'bottom' : props.toolbar;
+        // Plugin items append after the base set (explicit `toolbarItems` wins
+        // as the base, otherwise the defaults).
+        const toolbarItems = pluginToolbarItems.length
+            ? [...(props.toolbarItems ?? defaultToolbarItems), ...pluginToolbarItems]
+            : props.toolbarItems;
+        const toolbarNode = toolbarPlacement
+            ? (_jsx(EditorToolbar, { controller: controller, selection: selBox.current, items: toolbarItems, renderItem: props.renderToolbarItem }))
+            : null;
+        const session = sessionBox.current;
+        const activeTrigger = session
+            ? plugins.find((p) => p.name === session.plugin)?.trigger
+            : undefined;
+        // Gate on the wrapper frame being measured — before the first
+        // bindlayoutchange the placement math would clamp against a 0-height
+        // container and misposition the popup.
+        const popupNode = session && activeTrigger && session.items.length > 0 && inputFrame.value
+            ? (_jsx(SuggestionPopup, { items: session.items, caretRect: selBox.current?.caretRect ?? null, containerFrame: inputFrame.value, renderItem: activeTrigger.renderItem, onSelect: handleTriggerSelect }))
+            : null;
+        const inputNode = (_jsx(RichTextInput, { value: mdToDoc(initialMd, 0, convertIn), placeholder: props.placeholder, editable: props.disabled !== true, minHeight: minHeight, maxHeight: maxHeight, fontSize: fontSize, textColor: props.textColor, accentColor: props.accentColor, placeholderColor: props.placeholderColor, confirmType: props.confirmType, autoFocus: props.autoFocus, style: mode === 'fullscreen'
+                ? { flexGrow: 1 }
+                : { height: Math.max(minHeight, Math.min(reportedHeight.value || minHeight, maxHeight)) }, onElement: (handle) => {
+                el = handle;
+            }, onHeightChange: (height) => {
+                reportedHeight.value = height;
+            }, onChange: handleChange, onSelection: (sel) => {
+                selBox.current = sel;
+                triggerManager?.syncCaret(sel.start === sel.end ? sel.start : -1);
+                props.onSelectionChange?.(sel);
+            }, onFocus: () => props.onFocus?.(), onBlur: () => {
+                triggerManager?.close();
+                props.onBlur?.();
+            } }));
+        return (_jsxs("view", { class: props.class, style: {
                 display: 'flex',
                 flexDirection: 'column',
                 ...(mode === 'fullscreen' ? { flexGrow: 1, flexShrink: 1 } : {}),
-            }, children: _jsx(RichTextInput, { value: mdToDoc(initialMd), placeholder: props.placeholder, editable: props.disabled ? false : undefined, minHeight: minHeight, maxHeight: maxHeight, fontSize: fontSize, textColor: props.textColor, accentColor: props.accentColor, placeholderColor: props.placeholderColor, confirmType: props.confirmType, autoFocus: props.autoFocus, style: mode === 'fullscreen'
-                    ? { flexGrow: 1 }
-                    : { height: Math.max(minHeight, Math.min(reportedHeight.value || minHeight, maxHeight)) }, onElement: (handle) => {
-                    el = handle;
-                }, onHeightChange: (height) => {
-                    reportedHeight.value = height;
-                }, onChange: handleChange, onSelection: (sel) => {
-                    currentSel = sel;
-                    props.onSelectionChange?.(sel);
-                }, onFocus: () => props.onFocus?.(), onBlur: () => props.onBlur?.() }) }));
+            }, children: [toolbarPlacement === 'top' ? toolbarNode : null, triggers.length
+                    ? (_jsxs("view", { bindlayoutchange: onInputLayout, style: {
+                            position: 'relative',
+                            ...(mode === 'fullscreen'
+                                ? { display: 'flex', flexDirection: 'column', flexGrow: 1 }
+                                : {}),
+                        }, children: [inputNode, popupNode] }))
+                    : inputNode, toolbarPlacement === 'bottom' ? toolbarNode : null] }));
     };
 });

package/dist/editor/convert/docToMd.d.ts

@@ -10,5 +10,15 @@
  * *normalized* `doc` — emphasis markers, hard breaks (→ paragraph breaks), and
  * blank lines normalize; `raw` blocks round-trip byte-for-byte.
  */
-import type { RichDoc } from '@sigx/lynx-richtext';
-export declare function docToMd(doc: RichDoc): string;
+import type { InlineSpan, RichDoc } from '@sigx/lynx-richtext';
+/** Serialize one plugin-owned span back to markdown (a plugin's `inline.serialize`). */
+export type SpanSerializer = (span: InlineSpan, text: string) => string;
+export interface DocToMdOptions {
+    /**
+     * Plugin serializers keyed by the span type they own
+     * (`docMapping.spanType`). A plugin-owned span is emitted **atomically**:
+     * the serializer's output replaces the covered text entirely.
+     */
+    serializers?: ReadonlyMap<string, SpanSerializer>;
+}
+export declare function docToMd(doc: RichDoc, options?: DocToMdOptions): string;

package/dist/editor/convert/docToMd.js

@@ -11,14 +11,18 @@
  * blank lines normalize; `raw` blocks round-trip byte-for-byte.
  */
 import { computeRuns, markPriority } from './overlap.js';
-export function docToMd(doc) {
+export function docToMd(doc, options) {
     const parts = [];
+    const serializers = options?.serializers;
+    // Plugin-owned spans, prefiltered once for the whole doc — the per-run
+    // lookup searches only these (typically zero or a handful).
+    const pluginSpans = serializers ? doc.spans.filter((s) => serializers.has(s.type)) : [];
     for (const seg of segmentize(doc)) {
         if (seg.type === 'raw') {
             parts.push(doc.text.slice(seg.start, seg.end));
             continue;
         }
-        const inline = serializeInline(doc, seg.start, seg.end, seg.type === 'paragraph');
+        const inline = serializeInline(doc, seg.start, seg.end, seg.type === 'paragraph', serializers, pluginSpans);
         if (seg.type === 'heading') {
             const level = Math.min(6, Math.max(1, seg.level ?? 1));
             parts.push(`${'#'.repeat(level)} ${inline}`);
@@ -84,7 +88,7 @@ function segmentize(doc) {
     return segments;
 }
 /** Serialize one segment's text + spans into markdown inline syntax. */
-function serializeInline(doc, start, end, escapeLineStart) {
+function serializeInline(doc, start, end, escapeLineStart, serializers, pluginSpans = []) {
     const runs = computeRuns(doc.spans, start, end);
     if (runs.length === 0) {
         return escapeText(doc.text.slice(start, end), escapeLineStart);
@@ -107,7 +111,16 @@ function serializeInline(doc, start, end, escapeLineStart) {
     let first = true;
     for (let i = 0; i < runs.length; i++) {
         const run = runs[i];
-        const desired = [...run.active].sort((a, b) => {
+        // A plugin-owned mark serializes atomically: its serializer output
+        // replaces the covered text, and the mark never enters the
+        // close/reopen stack (other marks may still wrap it). Atomic emission
+        // only applies when exactly ONE plugin mark covers the run —
+        // overlapping plugin spans are ambiguous, so the run degrades to its
+        // plain text (content preserved, no plugin syntax emitted).
+        const pluginMarks = serializers ? run.active.filter((m) => serializers.has(m.type)) : [];
+        const pluginMark = pluginMarks.length === 1 ? pluginMarks[0] : undefined;
+        const active = pluginMarks.length ? run.active.filter((m) => !serializers.has(m.type)) : run.active;
+        const desired = [...active].sort((a, b) => {
             const ea = contEnd[i].get(a.key) ?? run.end;
             const eb = contEnd[i].get(b.key) ?? run.end;
             return eb - ea || markPriority(a) - markPriority(b);
@@ -123,6 +136,16 @@ function serializeInline(doc, start, end, escapeLineStart) {
             out += delimiter(desired[j], doc, 'open');
             open.push(desired[j]);
         }
+        if (pluginMark) {
+            // Emit the serialized form once — on the span's first run within
+            // this segment — and suppress the covered text everywhere.
+            const span = pluginSpans.find((s) => s.type === pluginMark.type && s.start <= run.start && s.end >= run.end);
+            if (span && run.start === Math.max(span.start, start)) {
+                out += serializers.get(pluginMark.type)(span, doc.text.slice(span.start, span.end));
+            }
+            first = false;
+            continue;
+        }
         const slice = doc.text.slice(run.start, run.end);
         out += open.some((m) => m.type === 'code')
             ? slice

package/dist/editor/convert/mdToDoc.d.ts

@@ -15,5 +15,18 @@
  * serializes doc lines back as blank-line-separated paragraphs (hard breaks
  * normalize to paragraph breaks — documented).
  */
-import type { RichDoc } from '@sigx/lynx-richtext';
-export declare function mdToDoc(markdown: string, v?: number): RichDoc;
+import type { InlineSpan, RichDoc } from '@sigx/lynx-richtext';
+import type { ParserInlineExtension } from '../../parser/extensions.js';
+import type { InlineExtension } from '../../ast.js';
+/** AST extension node → editor span (a plugin's `docMapping.toSpan`). Must be pure. */
+export type ExtensionSpanMapper = (node: InlineExtension) => {
+    text: string;
+    span: Omit<InlineSpan, 'start' | 'end'>;
+} | null;
+export interface MdToDocOptions {
+    /** Inline extensions to parse with (plugin `inline.syntax`). */
+    extensions?: readonly ParserInlineExtension[];
+    /** Span mappers keyed by extension name (plugin `docMapping.toSpan`). */
+    spanMappers?: Record<string, ExtensionSpanMapper>;
+}
+export declare function mdToDoc(markdown: string, v?: number, options?: MdToDocOptions): RichDoc;

package/dist/editor/convert/mdToDoc.js

@@ -16,8 +16,9 @@
  * normalize to paragraph breaks — documented).
  */
 import { parseBlocks } from '../../parser/blocks.js';
-export function mdToDoc(markdown, v = 0) {
-    const ast = parseBlocks(markdown ?? '');
+export function mdToDoc(markdown, v = 0, options) {
+    const ast = parseBlocks(markdown ?? '', undefined, options?.extensions);
+    const mappers = options?.spanMappers;
     let text = '';
     const spans = [];
     const blocks = [];
@@ -40,23 +41,23 @@ export function mdToDoc(markdown, v = 0) {
     for (const block of ast) {
         switch (block.type) {
             case 'paragraph': {
-                if (!inlineRepresentable(block.children)) {
+                if (!inlineRepresentable(block.children, mappers)) {
                     push(block.raw, { type: 'raw' });
                     break;
                 }
                 for (const line of splitOnBreaks(block.children)) {
-                    const flat = flattenInline(line, text.length);
+                    const flat = flattenInline(line, text.length, mappers);
                     spans.push(...flat.spans);
                     push(flat.text);
                 }
                 break;
             }
             case 'heading': {
-                if (!inlineRepresentable(block.children)) {
+                if (!inlineRepresentable(block.children, mappers)) {
                     push(block.raw, { type: 'raw' });
                     break;
                 }
-                const flat = flattenInline(block.children, text.length);
+                const flat = flattenInline(block.children, text.length, mappers);
                 spans.push(...flat.spans);
                 push(flat.text, { type: 'heading', level: block.level });
                 break;
@@ -76,7 +77,7 @@ export function mdToDoc(markdown, v = 0) {
     return { text, spans, blocks, v };
 }
 /** Inline node types the editor can model in-field. */
-function inlineRepresentable(nodes) {
+function inlineRepresentable(nodes, mappers) {
     for (const node of nodes) {
         switch (node.type) {
             case 'text':
@@ -87,19 +88,36 @@ function inlineRepresentable(nodes) {
             case 'strong':
             case 'em':
             case 'del':
-                if (!inlineRepresentable(node.children))
+                if (!inlineRepresentable(node.children, mappers))
                     return false;
                 break;
             case 'link':
-                if (!inlineRepresentable(node.children))
+                if (!inlineRepresentable(node.children, mappers))
+                    return false;
+                break;
+            case 'extension':
+                // Representable only when a plugin maps it to an editor span
+                // (toSpan is pure, so probing here and mapping later agree).
+                // A throwing mapper means "not representable" — the block
+                // degrades to raw instead of crashing the conversion.
+                if (!tryMap(mappers, node))
                     return false;
                 break;
             default:
-                return false; // image, future extension nodes
+                return false; // image, unmapped extension nodes
         }
     }
     return true;
 }
+/** Run a plugin mapper defensively: a throwing mapper counts as no mapping. */
+function tryMap(mappers, node) {
+    try {
+        return mappers?.[node.name]?.(node) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Split a paragraph's inline children into visual lines at top-level hard breaks. */
 function splitOnBreaks(nodes) {
     const lines = [];
@@ -117,7 +135,7 @@ function splitOnBreaks(nodes) {
     return lines;
 }
 /** Depth-first flatten of an inline tree into text + overlapping spans. */
-function flattenInline(nodes, base) {
+function flattenInline(nodes, base, mappers) {
     let text = '';
     const spans = [];
     const walk = (list) => {
@@ -176,6 +194,22 @@ function flattenInline(nodes, base) {
                     });
                     break;
                 }
+                case 'extension': {
+                    const mapped = tryMap(mappers, node);
+                    if (!mapped) {
+                        // Defense in depth: if the mapper disagrees with the
+                        // earlier representability probe (impure/buggy), keep
+                        // the source text rather than silently dropping it.
+                        text += node.raw;
+                        break;
+                    }
+                    const start = base + text.length;
+                    text += mapped.text;
+                    // Plugin fields first — the converter always controls the
+                    // final range, even if a mapper sneaks in start/end.
+                    spans.push({ ...mapped.span, start, end: base + text.length });
+                    break;
+                }
                 default:
                     break; // unreachable — filtered by inlineRepresentable
             }