@marianmeres/stuic 3.108.0 → 3.110.0

package/dist/components/MarkdownEditor/README.md

@@ -0,0 +1,172 @@
+# MarkdownEditor
+
+A textarea-like STUIC field for authoring longer markdown content. It presents a
+**quasi-WYSIWYG** surface ([Milkdown](https://milkdown.dev), the markdown-first
+ProseMirror distribution) that toggles to a **raw markdown source** editor
+([CodeMirror 6](https://codemirror.net)). A single bindable markdown string is
+the source of truth across both modes.
+
+It is shipped as an **optional subpath export**, separate from the main barrel,
+so its (heavy) editor dependencies never reach consumers who don't use it.
+
+## Installation
+
+The editor libraries are **optional peer dependencies** — install them only if
+you use this component:
+
+```sh
+pnpm add @milkdown/core @milkdown/ctx @milkdown/transformer @milkdown/prose \
+  @milkdown/preset-commonmark @milkdown/preset-gfm \
+  @milkdown/plugin-listener @milkdown/plugin-history @milkdown/utils \
+  @codemirror/state @codemirror/view @codemirror/commands \
+  @codemirror/language @codemirror/lang-markdown @codemirror/language-data
+```
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { MarkdownEditor } from "@marianmeres/stuic/markdown-editor";
+
+	let value = $state("# Hello\n\nSome **markdown**.");
+	let mode = $state<"wysiwyg" | "source">("wysiwyg");
+</script>
+
+<MarkdownEditor bind:value bind:mode label="Article body" required />
+```
+
+### Imperative API
+
+Bind the component instance to access:
+
+- `validate()` – run validation now, returns the `ValidationResult`
+- `clearValidation()` – clear the inline message
+- `getValidation()` – current validation state
+- `focus()` – focus the active editor
+- `scrollIntoView(opts?)`
+- `getMarkdown()` – read current markdown from the active editor
+- `toggleMode()` – switch WYSIWYG ⇄ source
+
+## Key props
+
+| Prop             | Type                         | Default     | Notes                                                               |
+| ---------------- | ---------------------------- | ----------- | ------------------------------------------------------------------- |
+| `value`          | `string` (bindable)          | `""`        | Markdown, single source of truth                                    |
+| `mode`           | `"wysiwyg" \| "source"`      | `"wysiwyg"` | Active surface (bindable)                                           |
+| `label`          | `THC \| Snippet`             | –           | Field label                                                         |
+| `description`    | `THC \| Snippet`             | –           | Collapsible hint                                                    |
+| `required`       | `boolean`                    | `false`     | Enforced over the markdown string                                   |
+| `disabled`       | `boolean`                    | `false`     |                                                                     |
+| `validate`       | `boolean \| ValidateOptions` | –           | Pass a `customValidator` to validate markdown                       |
+| `renderSize`     | `"sm" \| "md" \| "lg"`       | `"md"`      |                                                                     |
+| `toolbar`        | `boolean \| ToolbarItem[]`   | `true`      | `true` = default toolbar, `false` = none, or an ordered button list |
+| `showModeToggle` | `boolean`                    | `true`      | Show the WYSIWYG/source toggle                                      |
+| `name`           | `string`                     | –           | Hidden input name for form submission                               |
+
+Plus the standard `InputWrapClassProps` (`classLabel`, `classInputBox`, …),
+`labelLeft*`, `placeholder`, `onChange`, and `classInput` / `classToolbar`.
+
+### Toolbar
+
+Pass an array of `ToolbarItem`s to choose exactly which buttons appear and in
+what order; use `"|"` for a separator. Each button works in both WYSIWYG and
+source modes.
+
+```svelte
+<script lang="ts">
+	import { MarkdownEditor, type ToolbarItem } from "@marianmeres/stuic/markdown-editor";
+	const toolbar: ToolbarItem[] = [
+		"bold",
+		"italic",
+		"|",
+		"blockquote",
+		"codeBlock",
+		"|",
+		"undo",
+		"redo",
+	];
+</script>
+
+<MarkdownEditor bind:value {toolbar} />
+```
+
+Available items: `bold`, `italic`, `heading1`, `heading2`, `heading3`, `link`,
+`image`, `bulletList`, `orderedList`, `blockquote`, `codeBlock`, `hr`,
+`hardBreak`, `undo`, `redo`, and `"|"` (separator). The default layout is
+exported as `DEFAULT_TOOLBAR`.
+
+### Link / image URL prompt
+
+By default the link and image buttons ask for a URL via the native
+`window.prompt`. Pass a `window.prompt`-compatible function (sync or async) to
+the `prompt` prop to replace it — e.g. STUIC's ACP dialog via `createPrompt`:
+
+```svelte
+<script lang="ts">
+	import { MarkdownEditor } from "@marianmeres/stuic/markdown-editor";
+	import {
+		AlertConfirmPrompt,
+		AlertConfirmPromptStack,
+		createPrompt,
+	} from "@marianmeres/stuic";
+
+	const acp = new AlertConfirmPromptStack();
+</script>
+
+<MarkdownEditor bind:value prompt={createPrompt(acp)} />
+
+<!-- mount the ACP provider once, anywhere in the app -->
+<AlertConfirmPrompt {acp} />
+```
+
+### Mobile / touch
+
+`contenteditable` (the WYSIWYG view) is rougher on phones than a plain text
+field, so on touch devices the editor adapts:
+
+- **Starts in `source` mode** (the steadier CodeMirror view) — toggle
+  `autoSourceOnMobile={false}` to keep WYSIWYG.
+- **Shows a reduced toolbar** (`DEFAULT_MOBILE_TOOLBAR`) — override with
+  `mobileToolbar` (same shape as `toolbar`).
+- **Larger touch targets** (40px) via a `(pointer: coarse)` media query.
+
+"Mobile" is defined by `mobileQuery`
+(default `"(pointer: coarse) and (max-width: 640px)"`). The applied-once source
+default never fights a later manual toggle. Both toggles are exported:
+`DEFAULT_MOBILE_TOOLBAR`.
+
+## Theming
+
+All visuals are CSS-variable driven. Component tokens fall back to the shared
+input/global tokens:
+
+```css
+--stuic-markdown-editor-radius      /* → --stuic-input-radius → --stuic-radius */
+--stuic-markdown-editor-border
+--stuic-markdown-editor-border-focus
+--stuic-markdown-editor-bg
+--stuic-markdown-editor-min-height  /* default 12rem (9/16rem for sm/lg) */
+--stuic-markdown-editor-max-height
+--stuic-markdown-editor-font-size
+--stuic-markdown-editor-font-mono
+--stuic-markdown-editor-code-bg
+```
+
+## Notes & caveats
+
+- **CSS is imported locally** by this component (not via the central
+  `src/lib/index.css`). This is a deliberate deviation from the STUIC convention,
+  required so the styles ship only to subpath users. See `index.css` for the
+  rationale.
+- **SSR-safe / lazy-loaded.** Both editors are browser-only and loaded via
+  dynamic `import()` inside a client-only effect, so they never run during SSR
+  and split into their own chunk. The server renders only the field chrome.
+- **Round-trip is normalizing, not byte-preserving.** The WYSIWYG leg sends
+  markdown → ProseMirror → markdown via remark, which normalizes formatting:
+  blank-line collapse, emphasis/bullet marker unification, Setext (`===`)
+  headings → ATX (`#`), hard-break changes, and raw HTML that the schema can't
+  model may be dropped/escaped. GFM constructs (tables, strikethrough, task
+  lists) are supported via `@milkdown/preset-gfm`. **The editor owns canonical
+  formatting after the first edit.** The raw **source** mode is lossless.
+- Switching modes flushes the current content into `value` before tearing the
+  editor down, so no edits are lost on toggle.

package/dist/components/MarkdownEditor/_internal/codemirror.d.ts

@@ -0,0 +1,2 @@
+import type { EditorHandle, MountOptions } from "./types.js";
+export declare function mountCodeMirror(host: HTMLElement, opts: MountOptions): EditorHandle;

package/dist/components/MarkdownEditor/_internal/codemirror.js

@@ -0,0 +1,201 @@
+/**
+ * Raw markdown source backend, built on CodeMirror 6.
+ *
+ * This module statically imports all `@codemirror/*` packages — that is fine
+ * because `MarkdownEditor.svelte` only ever reaches it via a dynamic
+ * `import()` inside a client-only `$effect`, so the code is both code-split and
+ * never evaluated during SSR. CodeMirror ships no CSS file; all theming is done
+ * here via `EditorView.theme` plus `[data-size]` rules in the component's
+ * `index.css`.
+ */
+import { defaultKeymap, history, historyKeymap, redo, undo } from "@codemirror/commands";
+import { markdown } from "@codemirror/lang-markdown";
+import { languages } from "@codemirror/language-data";
+import { EditorState } from "@codemirror/state";
+import { EditorView, keymap, placeholder as cmPlaceholder } from "@codemirror/view";
+/** Theme that inherits STUIC look via CSS vars rather than hard-coded values. */
+const stuicTheme = EditorView.theme({
+    "&": {
+        fontSize: "var(--stuic-markdown-editor-font-size, 0.9375rem)",
+        color: "inherit",
+        backgroundColor: "transparent",
+    },
+    ".cm-content": {
+        fontFamily: "var(--stuic-markdown-editor-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)",
+        padding: "0",
+        caretColor: "currentColor",
+    },
+    "&.cm-focused": { outline: "none" },
+    ".cm-line": { padding: "0" },
+    ".cm-gutters": { display: "none" },
+    ".cm-scroller": { fontFamily: "inherit", lineHeight: "1.6" },
+    ".cm-placeholder": {
+        color: "var(--stuic-input-placeholder, currentColor)",
+        opacity: "0.5",
+    },
+});
+/** Wrap the current selection with `before`/`after` markers (e.g. `**bold**`). */
+function wrapSelection(view, before, after = before) {
+    const { from, to } = view.state.selection.main;
+    const selected = view.state.sliceDoc(from, to);
+    view.dispatch({
+        changes: { from, to, insert: `${before}${selected}${after}` },
+        selection: {
+            anchor: from + before.length,
+            head: to + before.length + selected.length,
+        },
+    });
+    view.focus();
+}
+/** Toggle an ATX heading of `level` on the cursor's line: add it, switch level,
+ *  or strip it when the same level is already present. */
+function toggleHeadingLine(view, level) {
+    const { from } = view.state.selection.main;
+    const line = view.state.doc.lineAt(from);
+    const m = line.text.match(/^(#{1,6}) /);
+    const curLevel = m ? m[1].length : 0;
+    const delLen = m ? m[0].length : 0;
+    const insert = curLevel === level ? "" : `${"#".repeat(level)} `;
+    view.dispatch({ changes: { from: line.from, to: line.from + delLen, insert } });
+    view.focus();
+}
+/** Insert a markdown link, prompting for the URL (parity with the WYSIWYG link). */
+async function insertLink(view, prompt) {
+    // Capture the selection before the (possibly async) prompt — a modal dialog
+    // blocks editing, so these positions stay valid.
+    const { from, to } = view.state.selection.main;
+    const text = view.state.sliceDoc(from, to) || "link";
+    const href = await prompt("Link URL", "https://");
+    if (href === null)
+        return view.focus();
+    const url = href.trim() || "url";
+    view.dispatch({
+        changes: { from, to, insert: `[${text}](${url})` },
+        selection: { anchor: from + 1, head: from + 1 + text.length },
+    });
+    view.focus();
+}
+/**
+ * Toggle a line prefix (list marker, blockquote `> `, …) across the selected
+ * lines. If every non-empty line already matches `marker`, the marker is
+ * stripped (toggle off); otherwise it is added — so repeated clicks behave like
+ * a real toggle instead of stacking `- - ` / `> > ` prefixes.
+ */
+function toggleLinePrefix(view, add, marker) {
+    const { from, to } = view.state.selection.main;
+    const startLine = view.state.doc.lineAt(from).number;
+    const endLine = view.state.doc.lineAt(to).number;
+    const lines = [];
+    let allMarked = true;
+    for (let n = startLine; n <= endLine; n++) {
+        const line = view.state.doc.line(n);
+        lines.push(line);
+        if (line.text.trim() !== "" && !marker.test(line.text))
+            allMarked = false;
+    }
+    const changes = [];
+    for (const line of lines) {
+        const isBlank = line.text.trim() === "";
+        if (allMarked) {
+            const m = line.text.match(marker);
+            if (m)
+                changes.push({ from: line.from, to: line.from + m[0].length, insert: "" });
+        }
+        else if (!isBlank || lines.length === 1) {
+            changes.push({ from: line.from, insert: add });
+        }
+    }
+    view.dispatch({ changes });
+    view.focus();
+}
+/** Insert a markdown image, prompting for the URL (parity with WYSIWYG). */
+async function insertImage(view, prompt) {
+    const { from, to } = view.state.selection.main;
+    const alt = view.state.sliceDoc(from, to) || "alt";
+    const src = await prompt("Image URL", "https://");
+    if (src === null)
+        return view.focus();
+    const url = src.trim() || "url";
+    view.dispatch({
+        changes: { from, to, insert: `![${alt}](${url})` },
+        selection: { anchor: from + 2, head: from + 2 + alt.length },
+    });
+    view.focus();
+}
+/** Wrap the selection in a fenced code block (or insert an empty one). */
+function insertCodeBlock(view) {
+    const { from, to } = view.state.selection.main;
+    const sel = view.state.sliceDoc(from, to);
+    const insert = `\`\`\`\n${sel}\n\`\`\`\n`;
+    view.dispatch({
+        changes: { from, to, insert },
+        selection: { anchor: from + 4 }, // just inside the opening fence
+    });
+    view.focus();
+}
+/** Insert a thematic break (horizontal rule) after the current line. */
+function insertHorizontalRule(view) {
+    const at = view.state.doc.lineAt(view.state.selection.main.from).to;
+    const insert = "\n\n---\n";
+    view.dispatch({
+        changes: { from: at, insert },
+        selection: { anchor: at + insert.length },
+    });
+    view.focus();
+}
+/** Insert a markdown hard line break at the cursor. */
+function insertHardBreak(view) {
+    const { from, to } = view.state.selection.main;
+    view.dispatch({
+        changes: { from, to, insert: "\\\n" },
+        selection: { anchor: from + 2 },
+    });
+    view.focus();
+}
+export function mountCodeMirror(host, opts) {
+    const view = new EditorView({
+        parent: host,
+        state: EditorState.create({
+            doc: opts.value ?? "",
+            extensions: [
+                history(),
+                keymap.of([...defaultKeymap, ...historyKeymap]),
+                markdown({ codeLanguages: languages }),
+                EditorView.lineWrapping,
+                EditorView.editable.of(!opts.disabled),
+                EditorState.readOnly.of(!!opts.disabled),
+                ...(opts.placeholder ? [cmPlaceholder(opts.placeholder)] : []),
+                stuicTheme,
+                EditorView.updateListener.of((u) => {
+                    if (u.docChanged)
+                        opts.onChange(u.state.doc.toString());
+                }),
+            ],
+        }),
+    });
+    return {
+        destroy: () => view.destroy(),
+        getMarkdown: () => view.state.doc.toString(),
+        setMarkdown: (md) => {
+            if (md === view.state.doc.toString())
+                return;
+            view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: md } });
+        },
+        focus: () => view.focus(),
+        commands: {
+            bold: () => wrapSelection(view, "**"),
+            italic: () => wrapSelection(view, "_"),
+            heading: (level) => toggleHeadingLine(view, Math.min(6, Math.max(1, level))),
+            link: () => insertLink(view, opts.prompt),
+            image: () => insertImage(view, opts.prompt),
+            bulletList: () => toggleLinePrefix(view, "- ", /^\s*[-*+] /),
+            orderedList: () => toggleLinePrefix(view, "1. ", /^\s*\d+\. /),
+            blockquote: () => toggleLinePrefix(view, "> ", /^\s*> /),
+            codeBlock: () => insertCodeBlock(view),
+            hr: () => insertHorizontalRule(view),
+            hardBreak: () => insertHardBreak(view),
+            undo: () => undo(view),
+            redo: () => redo(view),
+        },
+    };
+}

package/dist/components/MarkdownEditor/_internal/milkdown.d.ts

@@ -0,0 +1,2 @@
+import type { EditorHandle, MountOptions } from "./types.js";
+export declare function mountMilkdown(host: HTMLElement, opts: MountOptions): Promise<EditorHandle>;

package/dist/components/MarkdownEditor/_internal/milkdown.js

@@ -0,0 +1,199 @@
+/**
+ * WYSIWYG backend, built on Milkdown (the markdown-first ProseMirror
+ * distribution + remark). Headless: Milkdown ships no CSS, so all visuals come
+ * from the component's `index.css` styling `.milkdown .ProseMirror`.
+ *
+ * Like the CodeMirror backend, the heavy `@milkdown/*` imports are static here
+ * but only reached via a dynamic `import()` from the component, keeping them out
+ * of SSR and the main bundle.
+ *
+ * IMPORTANT: never recreate the Editor when `value` changes — only `replaceAll`
+ * (Milkdown #598 double-instance trap). The host component enforces this.
+ */
+import { Editor, defaultValueCtx, editorViewCtx, editorViewOptionsCtx, rootCtx, } from "@milkdown/core";
+import { history, redoCommand, undoCommand } from "@milkdown/plugin-history";
+import { listener, listenerCtx } from "@milkdown/plugin-listener";
+import { commonmark, createCodeBlockCommand, insertHardbreakCommand, insertHrCommand, insertImageCommand, liftListItemCommand, toggleEmphasisCommand, toggleStrongCommand, turnIntoTextCommand, wrapInBlockquoteCommand, wrapInBulletListCommand, wrapInHeadingCommand, wrapInOrderedListCommand, } from "@milkdown/preset-commonmark";
+import { gfm } from "@milkdown/preset-gfm";
+import { lift } from "@milkdown/prose/commands";
+import { callCommand, getMarkdown, replaceAll } from "@milkdown/utils";
+// List node type names differ by Milkdown internals (snake vs camel) — match
+// both so list detection is robust regardless of the registered schema name.
+const BULLET_LIST_NAMES = new Set(["bullet_list", "bulletList"]);
+const ORDERED_LIST_NAMES = new Set(["ordered_list", "orderedList"]);
+/** Which kind of list the selection sits inside, if any. */
+function currentListType(state) {
+    const { $from } = state.selection;
+    for (let d = $from.depth; d > 0; d--) {
+        const name = $from.node(d).type.name;
+        if (BULLET_LIST_NAMES.has(name))
+            return "bullet";
+        if (ORDERED_LIST_NAMES.has(name))
+            return "ordered";
+    }
+    return null;
+}
+/** Heading level of the block the cursor is in, or null if it's not a heading. */
+function currentHeadingLevel(state) {
+    const node = state.selection.$from.parent;
+    if (node?.type.name === "heading")
+        return node.attrs.level ?? null;
+    return null;
+}
+/** Whether the selection sits anywhere inside a blockquote. */
+function inBlockquote(state) {
+    const { $from } = state.selection;
+    for (let d = $from.depth; d > 0; d--) {
+        if ($from.node(d).type.name === "blockquote")
+            return true;
+    }
+    return false;
+}
+export async function mountMilkdown(host, opts) {
+    const editor = await Editor.make()
+        .config((ctx) => {
+        ctx.set(rootCtx, host);
+        ctx.set(defaultValueCtx, opts.value ?? "");
+        ctx.update(editorViewOptionsCtx, (prev) => ({
+            ...prev,
+            editable: () => !opts.disabled,
+            attributes: { class: "stuic-markdown-prose", spellcheck: "true" },
+        }));
+        ctx.get(listenerCtx).markdownUpdated((_ctx, markdown) => {
+            opts.onChange(markdown);
+        });
+    })
+        .use(commonmark)
+        .use(gfm)
+        .use(history)
+        .use(listener)
+        .create();
+    // Real list toggle: `wrapIn*` only wraps non-list content, so a second click
+    // while already in a list is a no-op. Instead, lift out when already in the
+    // same list kind, and lift-then-wrap to switch kinds.
+    const toggleList = (kind) => {
+        editor.action((ctx) => {
+            const view = ctx.get(editorViewCtx);
+            const wrapKey = kind === "bullet" ? wrapInBulletListCommand.key : wrapInOrderedListCommand.key;
+            const current = currentListType(view.state);
+            if (current === kind) {
+                callCommand(liftListItemCommand.key)(ctx); // toggle off
+            }
+            else if (current) {
+                callCommand(liftListItemCommand.key)(ctx); // switch kind
+                callCommand(wrapKey)(ctx);
+            }
+            else {
+                callCommand(wrapKey)(ctx); // wrap fresh content
+            }
+            view.focus();
+        });
+    };
+    // Heading toggle: `wrapInHeadingCommand` sets the block type (level < 1 means
+    // paragraph) but does NOT toggle, so a second click on the same level is a
+    // no-op. Detect the current level and pass 0 to turn it back into a paragraph.
+    const toggleHeading = (level) => {
+        editor.action((ctx) => {
+            const view = ctx.get(editorViewCtx);
+            const next = currentHeadingLevel(view.state) === level ? 0 : level;
+            callCommand(wrapInHeadingCommand.key, next)(ctx);
+            view.focus();
+        });
+    };
+    // Link: `toggleLinkCommand` requires an `href` payload (the link mark has no
+    // default href, so calling it bare throws "No value supplied for attribute
+    // href"). Prompt for a URL and add/update/remove the link mark directly.
+    // The prompt may be async (e.g. STUIC's ACP dialog); selection positions are
+    // captured up front and stay valid because a modal blocks editing.
+    const applyLink = async () => {
+        const view = editor.action((ctx) => ctx.get(editorViewCtx));
+        const linkMark = view.state.schema.marks.link;
+        if (!linkMark)
+            return;
+        const { from, to, empty } = view.state.selection;
+        let existingHref = null;
+        const scanTo = empty ? Math.min(from + 1, view.state.doc.content.size) : to;
+        view.state.doc.nodesBetween(from, scanTo, (node) => {
+            const m = node.marks.find((mk) => mk.type === linkMark);
+            if (m)
+                existingHref = m.attrs.href;
+        });
+        const href = await opts.prompt("Link URL (leave empty to remove)", existingHref ?? "https://");
+        if (href === null)
+            return view.focus(); // cancelled
+        const url = href.trim();
+        if (url === "") {
+            if (!empty)
+                view.dispatch(view.state.tr.removeMark(from, to, linkMark));
+        }
+        else if (empty) {
+            // No selection: insert the URL as linked text.
+            const tr = view.state.tr.insertText(url, from);
+            tr.addMark(from, from + url.length, linkMark.create({ href: url }));
+            view.dispatch(tr);
+        }
+        else {
+            view.dispatch(view.state.tr.addMark(from, to, linkMark.create({ href: url })));
+        }
+        view.focus();
+    };
+    // Blockquote toggle: wrap, or lift back out when already inside one.
+    const toggleBlockquote = () => {
+        editor.action((ctx) => {
+            const view = ctx.get(editorViewCtx);
+            if (inBlockquote(view.state))
+                lift(view.state, view.dispatch);
+            else
+                callCommand(wrapInBlockquoteCommand.key)(ctx);
+            view.focus();
+        });
+    };
+    // Code-block toggle: code-block node types have `spec.code === true`. Turn
+    // into a paragraph when already in one, else create a code block.
+    const toggleCodeBlock = () => {
+        editor.action((ctx) => {
+            const view = ctx.get(editorViewCtx);
+            const inCode = view.state.selection.$from.parent.type.spec.code === true;
+            callCommand(inCode ? turnIntoTextCommand.key : createCodeBlockCommand.key)(ctx);
+            view.focus();
+        });
+    };
+    // Image: prompt for a source URL (insertImageCommand needs a `src` payload).
+    const insertImage = async () => {
+        const view = editor.action((ctx) => ctx.get(editorViewCtx));
+        const src = await opts.prompt("Image URL", "https://");
+        if (src === null || src.trim() === "")
+            return view.focus();
+        editor.action(callCommand(insertImageCommand.key, { src: src.trim() }));
+        view.focus();
+    };
+    return {
+        // editor.destroy() is async; we intentionally don't await — the host's
+        // `disposed` flag guards against mounting into a torn-down node.
+        destroy: () => {
+            void editor.destroy();
+        },
+        getMarkdown: () => editor.action(getMarkdown()),
+        setMarkdown: (md) => {
+            editor.action(replaceAll(md));
+        },
+        focus: () => {
+            editor.action((ctx) => ctx.get(editorViewCtx).focus());
+        },
+        commands: {
+            bold: () => editor.action(callCommand(toggleStrongCommand.key)),
+            italic: () => editor.action(callCommand(toggleEmphasisCommand.key)),
+            heading: (level) => toggleHeading(level),
+            link: () => applyLink(),
+            image: () => insertImage(),
+            bulletList: () => toggleList("bullet"),
+            orderedList: () => toggleList("ordered"),
+            blockquote: () => toggleBlockquote(),
+            codeBlock: () => toggleCodeBlock(),
+            hr: () => editor.action(callCommand(insertHrCommand.key)),
+            hardBreak: () => editor.action(callCommand(insertHardbreakCommand.key)),
+            undo: () => editor.action(callCommand(undoCommand.key)),
+            redo: () => editor.action(callCommand(redoCommand.key)),
+        },
+    };
+}

package/dist/components/MarkdownEditor/_internal/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared contract between the two editor backends (Milkdown WYSIWYG and
+ * CodeMirror raw source). `MarkdownEditor.svelte` only ever talks to an
+ * `EditorHandle`, so the two `_internal` modules are fully interchangeable and
+ * the heavy library code stays behind the dynamic-`import()` boundary.
+ */
+/** Imperative toolbar commands. Each backend implements them in its own way. */
+export interface EditorCommands {
+    bold: () => void;
+    italic: () => void;
+    /** Toggle a heading of the given level (1-6) on the current block/line. */
+    heading: (level: number) => void;
+    link: () => void;
+    image: () => void;
+    bulletList: () => void;
+    orderedList: () => void;
+    blockquote: () => void;
+    codeBlock: () => void;
+    /** Insert a horizontal rule / thematic break. */
+    hr: () => void;
+    /** Insert a hard line break. */
+    hardBreak: () => void;
+    undo: () => void;
+    redo: () => void;
+}
+/** Handle returned by a backend mount fn. The single source of truth is the
+ *  markdown string `value` in the host component — the handle just lets it
+ *  read, write, focus, and destroy whichever editor is currently active. */
+export interface EditorHandle {
+    /** Tear down the editor and release DOM/resources. */
+    destroy: () => void;
+    /** Current document serialized to markdown. Read this before destroying. */
+    getMarkdown: () => string;
+    /** Replace the whole document with `md` (used on external `value` change). */
+    setMarkdown: (md: string) => void;
+    /** Focus the editable surface. */
+    focus: () => void;
+    /** Toolbar command map. */
+    commands: EditorCommands;
+}
+/**
+ * A `window.prompt`-compatible function used for the link/image URL inputs. May
+ * be async — e.g. STUIC's ACP dialog via `createPrompt(acpStack)`. Resolves to
+ * the entered string, or `null` if cancelled.
+ */
+export type PromptFn = (message: string, defaultValue?: string) => string | null | Promise<string | null>;
+export interface MountOptions {
+    /** Initial markdown content. */
+    value: string;
+    /** Called whenever the user edits. Backend echoes from `setMarkdown` are the
+     *  caller's responsibility to guard (see the sync logic in the component). */
+    onChange: (markdown: string) => void;
+    /** Prompt used for link/image URLs (defaults to `window.prompt`). */
+    prompt: PromptFn;
+    disabled?: boolean;
+    placeholder?: string;
+}

package/dist/components/MarkdownEditor/_internal/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared contract between the two editor backends (Milkdown WYSIWYG and
+ * CodeMirror raw source). `MarkdownEditor.svelte` only ever talks to an
+ * `EditorHandle`, so the two `_internal` modules are fully interchangeable and
+ * the heavy library code stays behind the dynamic-`import()` boundary.
+ */
+export {};