@markup-carve/carve-grammars 0.1.2 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 Grammars for the [Carve](https://github.com/markup-carve/carve) markup language:
 
-- a **Tiptap** integration (editor kit + serializer) that turns a Tiptap/ProseMirror document into Carve markup;
+- a **Tiptap** integration (editor kit, Carve loader and serializer) that converts between Carve markup and Tiptap/ProseMirror JSON;
 - **Prism** and **highlight.js** syntax-highlighting grammars for rendering Carve source on the web;
 - a **TextMate** grammar (`textmate/carve.tmLanguage.json`) for TextMate-based highlighters such as Shiki (used by VitePress).
 
@@ -22,8 +22,14 @@ npm install @markup-carve/carve-grammars
 ```
 
 All peer dependencies are optional - install only what you use:
-`@tiptap/core` + `@tiptap/starter-kit` (v2) for the editor, `prismjs` (v1) for
-Prism, `highlight.js` (v11) for highlight.js.
+`@tiptap/core` + `@tiptap/starter-kit` (v2 or v3) for the editor, `prismjs` (v1)
+for Prism, `highlight.js` (v11) for highlight.js. CI runs the suite against both
+Tiptap majors.
+
+On Tiptap 3, `CarveKit` disables StarterKit's bundled Underline and Link, since
+it registers its own (underline carries Carve's `_text_` mapping). Pass
+`starterKit: { underline: true }` to opt back in, at the cost of a duplicate
+mark name.
 
 `CarveKit` also pulls in several standalone Tiptap marks/extensions (highlight,
 subscript, superscript, underline, link, image, table, task-list); install the
@@ -114,6 +120,53 @@ blocks (`` ``` lang ``), horizontal rules (`---`), tables (with `|=` header
 cells and `^` / `<` row / column spans), container divs (`::: class`), and
 definition lists.
 
+## Loading Carve Into Tiptap
+
+Use the AST loader when opening Carve source in an editor. It parses Carve with
+`@markup-carve/carve` and builds the ProseMirror JSON shape consumed by
+`CarveKit`, avoiding the lossy HTML pivot where attributes disappear unless a
+Tiptap extension happens to claim them during `parseHTML`.
+
+```js
+import {
+  CarveKit,
+  carveToProseMirror,
+  serializeToCarve,
+} from '@markup-carve/carve-grammars/tiptap'
+
+const content = carveToProseMirror(source, { unsupported: 'preserve' })
+
+const editor = new Editor({
+  extensions: [CarveKit],
+  content,
+})
+
+const saved = serializeToCarve(editor.getJSON())
+```
+
+Entry points:
+
+- `carveToProseMirror(source, options?)` parses Carve source and returns a
+  ProseMirror `doc`.
+- `astToProseMirror(ast, options?)` converts an already parsed Carve
+  `document` AST.
+
+Unsupported handling:
+
+- `unsupported: 'throw'` is the default. The loader throws `UnsupportedNodeError`
+  instead of silently dropping content.
+- `unsupported: 'preserve'` first builds the richest available document and
+  verifies that serializing it preserves the parsed AST. Unsupported subtrees
+  use opaque `carveUnsupported` blocks; if a mapped document is still lossy,
+  the loader falls back to one whole-document opaque block. `serializeToCarve`
+  writes its source back byte-for-byte, including edge whitespace.
+
+All corpus documents are therefore load/save lossless in preservation mode.
+Some constructs remain opaque rather than directly editable, including parts
+of figures, advanced tables, comments, raw passthrough, and source-layout edge
+cases. `tiptap/schema-map.json` is the public rich-mapping authority;
+`tests/lib/coverage.js` records why structured conversion falls back.
+
 ## Syntax highlighting
 
 Render Carve source as highlighted HTML on the web. Both grammars cover the full
@@ -121,9 +174,104 @@ Carve token set: headings, lists, tables, blockquotes, fenced/raw blocks,
 container divs, front matter and comments, plus inline emphasis
 (`*bold*` `/italic/` `_underline_` `~strike~` `=highlight=`, braced
 `{^sup^}` `{,sub,}`),
-code, links, images, spans, attributes, footnotes, math (`` $`x`$ ``),
+code, links, images, spans, attributes, footnotes, math (`` $`x` ``),
 CriticMarkup (`{+ins+}` `{-del-}`), mentions, tags and emoji.
 
+### Where the three grammars deliberately differ
+
+The TextMate grammar is stricter than the Prism and highlight.js grammars about
+**indented block openers at document level**, and that difference is a decision
+rather than drift.
+
+Carve opens a block at column 0, or at an enclosing container's content column -
+nowhere in between. So at document level these are all ordinary paragraphs:
+
+````
+ # H
+ > q
+ *[HTML]: HyperText
+ ```js
+ x
+ ```
+````
+
+while the same four openers at a list item's content column are real blocks:
+
+````
+- item
+
+  # H
+
+  > quoted
+
+  ```js
+  x
+  ```
+````
+
+Telling those two apart needs block context. Only the TextMate grammar has it:
+its list-item rules track the item's actual content column, so a document-level
+rule can be anchored at column 0 while an `_in_container` twin stays permissive
+and is reachable only from inside a container. Its `heading`, `fenced_code`,
+`blockquote` and `abbreviation` rules are therefore anchored at column 0, and
+`heading_in_container`, `fenced_code_in_container`, `blockquote_in_container`
+and `abbreviation_in_container` carry the indented forms.
+
+Prism and highlight.js are line-based and have no container model, so they
+cannot make that distinction. Anchoring their block rules at column 0 would not
+buy accuracy - it would stop highlighting **every** legitimately indented
+construct inside a list item or a block quote, which is a common valid shape,
+in exchange for correcting a rare invalid one. So both keep their `^[ \t]*`
+anchors and knowingly over-colour the indented-at-document-level case.
+
+The practical consequence: a document that indents a heading, fence, blockquote
+or abbreviation definition by one or two columns at top level is highlighted by
+Prism and highlight.js and left as plain text by the TextMate grammar (Shiki,
+VS Code). The TextMate answer is the one that agrees with the engines.
+
+`tests/lib/constructs.js` is the shared construct inventory all three sweeps
+read, and the same asymmetry is written down there as `skip` entries on the
+column-sensitive cases; the TextMate-only column cases live in the `NEGATIVE`
+list in `tests/textmate-sweep-test.js`.
+
+### One rule, three spellings: a leading byte order mark
+
+A byte order mark at the **start of a document** is not content. The spec says
+so ("Line endings and a byte order mark"), and carve-js, carve-rs and carve-php
+all strip it before the block scanner runs. It is neither a space nor a tab, so
+without an explicit allowance it sits between the line start and the marker and
+defeats every line-anchored opener - a mark in front of a heading left the title
+unscoped, and a mark in front of a fence handed the line to the inline code rule
+instead.
+
+All three grammars now allow it, and the restriction to the document's start is
+load-bearing rather than pedantry. A mark anywhere else is an ordinary
+zero-width character that opens nothing:
+
+```
+# T
+
+<a byte order mark here>- item
+```
+
+renders as a paragraph holding literal text in carve-rs and in carve-php, and as
+a list only in carve-js, whose own `\s` class is Unicode White_Space plus U+FEFF
+(markup-carve/carve#806). Every rule here anchors with `^` under a multiline
+flag, which matches at *every* line start, so the allowance has to carry its own
+document-start assertion - and the three grammars do not share one:
+
+| grammar | spelling | mechanism |
+| --- | --- | --- |
+| prism | `(?:(?<![\s\S])\uFEFF)?` | JavaScript lookbehind: nothing precedes offset 0 |
+| highlightjs | `(?:(?<![\s\S])\uFEFF)?` | the same, and it survives highlight.js compilation |
+| textmate | `(?:\A\x{FEFF})?` | Oniguruma `\A`, which vscode-textmate resolves against the first line only |
+
+The codepoint is always written as an escape. No file in this repo holds a
+literal byte order mark: it is invisible, and an editor or a normalizing filter
+can drop the one character a rule is about. The spec corpus is the exception and
+can afford to be - it marks `tests/corpus/**` as `-text`, so
+`250-line-endings-and-a-byte-order-mark-3.crv` really does begin `ef bb bf`.
+
 ### Prism
 
 The grammar registers itself against the global `Prism`, so `Prism` must be
@@ -193,12 +341,120 @@ Named exports for other setups: `carveGrammar`, `carveLightExtras` /
 `carveDarkExtras`, `carveLightTheme` / `carveDarkTheme`, `extendTheme`,
 `carveStylingTransformer`.
 
+## Diagram rendering
+
+Carve's `FencedRenderExtension` presets emit a `<pre class="LANG">source</pre>`
+hydration element; something on the client turns it into a diagram. Mermaid,
+WaveDrom, Vega-Lite and Chart each render once **you** load their browser
+library. For the rest, `@markup-carve/carve-grammars/diagrams` ships renderers:
+
+| Type | Renderer | Engine | Network |
+|------|----------|--------|---------|
+| `graphviz` (`dot`) | `renderGraphvizDiagrams` | `@viz-js/viz` (WASM) | **offline** |
+| `d2` | `renderD2Diagrams` | `@terrastruct/d2` (WASM) | **offline** |
+| `plantuml` (`puml`) | `renderKrokiDiagrams` | a Kroki server | **network** |
+
+Graphviz and D2 render **entirely in the browser** - no server, no external
+call, works offline (in an IDE, behind a firewall, ...). The rendered SVG is
+placed in an inert `<img>` data URI (like the Kroki path), so even untrusted
+diagram source cannot run script or expose a `javascript:` link. The WASM
+libraries are optional peer dependencies, imported lazily only when a matching
+block is on the page:
+
+```js
+import { renderGraphvizDiagrams } from '@markup-carve/carve-grammars/diagrams/graphviz'
+import { renderD2Diagrams } from '@markup-carve/carve-grammars/diagrams/d2'
+
+await renderGraphvizDiagrams(container)
+await renderD2Diagrams(container)
+```
+
+`renderDiagrams` runs both (and PlantUML, when you opt in) in one call; each
+no-ops when its blocks are absent, so you pay nothing for the types not present:
+
+```js
+import { renderDiagrams } from '@markup-carve/carve-grammars/diagrams'
+
+await renderDiagrams(container)                       // graphviz + d2, offline
+await renderDiagrams(container, { kroki: {} })        // + PlantUML via kroki.io
+await renderDiagrams(container, { kroki: { server: 'https://kroki.internal' } })
+```
+
+### PlantUML (Kroki)
+
+PlantUML is the one preset with no practical in-browser renderer - its only
+pure-JS build is a multi-megabyte JVM-in-WASM. `renderKrokiDiagrams` renders it
+by POSTing the source to a [Kroki](https://kroki.io) server; the returned SVG
+rides in an `<img>` data URI (which cannot execute script). Idempotent, and
+dependency-free (plain-text POST, no deflate/base64).
+
+> ⚠️ **Privacy / GDPR.** The default server is the **public `https://kroki.io`**,
+> so the diagram source is sent to a **third party outside your domain**. For
+> anything sensitive, or to stay offline, point `server` at a **self-hosted or
+> localhost Kroki** so no data leaves your control - and disclose the external
+> call to end users where required. Because of this, `renderDiagrams` leaves the
+> Kroki step **off unless you pass `kroki`**.
+
+```js
+import { renderKrokiDiagrams } from '@markup-carve/carve-grammars/diagrams/kroki'
+
+await renderKrokiDiagrams(container, { server: 'https://kroki.internal' })
+```
+
+Options: `server` (default `https://kroki.io`), `types` (class → Kroki-type map,
+default `KROKI_DIAGRAM_TYPES` = `plantuml`/`puml` only; extend it to Kroki-render
+graphviz/d2 against a self-hosted server), `onError`, `fetch`.
+
+> When the diagram is rendered at build time (SSG) rather than in the browser,
+> prefer the engine's static-render hook (carve-js `renderers.plantuml`,
+> carve-php's own render pipeline) so the page ships finished SVG and needs no
+> client JS at all.
+
 ## API
 
+- `renderDiagrams(container, options?)` - render Graphviz + D2 (offline), and
+  PlantUML via Kroki when `options.kroki` is set. See
+  [Diagram rendering](#diagram-rendering).
+- `renderGraphvizDiagrams(container, options?)` / `renderD2Diagrams(container, options?)` -
+  render `graphviz`/`d2` blocks with the offline WASM engines.
+- `renderKrokiDiagrams(container, options?)` - render PlantUML (and any opted-in
+  type) via a Kroki server; `KROKI_DIAGRAM_TYPES` is the default class→type map.
+- `carveToProseMirror(source, options?)` - parse Carve source and convert it to
+  ProseMirror JSON. `options.unsupported` is `'throw'` by default or
+  `'preserve'` for opaque source-preserving blocks.
+- `astToProseMirror(ast, options?)` - convert an existing `@markup-carve/carve`
+  AST to ProseMirror JSON.
 - `serializeToCarve(doc)` - serialize an `editor.getJSON()` document to Carve markup.
 - `escapeCarve(text)` - contextually escape literal Carve syntax in a plain-text run so it round-trips as text (used internally by `serializeToCarve`).
 - `CarveKit` - the bundled Tiptap extension set.
-- Individual extensions: `CarveInsert`, `CarveDelete`, `CarveDiv`, `CarveSpan`, `CarveFootnote`, `CarveFootnoteDefinition`, `CarveMath`, `CarveEmbed`, `CarveAbbreviation`, `CarveDefinitionList`.
+- Individual extensions: `CarveInsert`, `CarveDelete`, `CarveCriticComment`, `CarveDiv`, `CarveSpan`, `CarveFootnote`, `CarveFootnoteDefinition`, `CarveMath`, `CarveEmbed`, `CarveAbbreviation`, `CarveDefinitionList`, `CarveUnsupported`.
+
+## Schema map (for other engines)
+
+`tiptap/schema-map.json` publishes the Carve-to-ProseMirror vocabulary as data, so
+an engine building a bridge in another language reads it instead of restating it:
+
+```js
+import map from '@markup-carve/carve-grammars/tiptap/schema-map.json'
+
+map.types.strong        // { kind: 'mark', pm: 'bold' }
+map.types.list          // { kind: 'node', pm: ['bulletList', 'orderedList', 'taskList'], ... }
+map.unmapped.figure     // 'figure / caption blocks are not modeled'
+```
+
+Every Carve node type appears exactly once, either in `types` with its
+ProseMirror name(s) or in `unmapped` with the reason it has none - the negative
+space is part of the contract, because a bridge that silently drops table
+alignment or figure captions is worse than one that says it cannot carry them.
+
+`tests/schema-map-test.js` keeps it honest: every ProseMirror name must exist in
+the `CarveKit` schema with the declared node/mark kind, and every type in the
+pinned spec vocabulary must have a decision. Types the map covers ahead of the
+`spec/` pin are declared explicitly and must be removed once the pin catches up.
+
+Restating this mapping per engine is what the spec's own node-vocabulary test was
+written to prevent: carve-php once emitted `citation-group` while every other
+implementation spelled it with underscores.
 
 ## Attributes, math and footnotes
 
@@ -207,8 +463,10 @@ Named exports for other setups: `carveGrammar`, `carveLightExtras` /
   `[text]{#me .note}`, `![alt](src){.wide}`. Inline attrs trail their target;
   block attrs (headings) sit on the **preceding** line (strict djot), e.g.
   `{#slug}` then `# Title`.
-- **Math** - `CarveMath` (inline atom) serializes to `` $`x`$ `` and, with
-  `display: true`, `` $$`x`$$ ``.
+- **Math** - `CarveMath` (inline atom) serializes to `` $`x` `` and, with
+  `display: true`, `` $$`x` ``. Math has no closing `$` sentinel (grammar.ebnf
+  PART 9 §18): the `$` / `$$` prefix opens a verbatim span and the backtick run
+  ends it, which is what keeps currency like `$5` literal.
 - **Footnotes** - `CarveFootnote` is the inline `[^label]` reference;
   `CarveFootnoteDefinition` is the matching body block, serialized as
   `[^label]: body`.

package/diagrams/d2.js

@@ -0,0 +1,55 @@
+/**
+ * D2 diagram renderer for Carve fenced-render output.
+ *
+ * `FencedRenderExtension::d2()` emits `<pre class="d2">SOURCE</pre>`. D2 has a
+ * WebAssembly build (`@terrastruct/d2`), so this renders in the browser with no
+ * server and no external call - it works offline. The WASM is large, so the
+ * library is imported lazily (only when a D2 block is on the page) and the D2
+ * instance is reused across blocks and calls.
+ *
+ * @example
+ * import { renderD2Diagrams } from '@markup-carve/carve-grammars/diagrams/d2'
+ * await renderD2Diagrams(document.querySelector('.carve-output'))
+ */
+import { renderBlocks } from './render-blocks.js';
+
+/** CSS classes claimed as D2 (the FencedRenderExtension cssClass). */
+export const D2_CLASSES = ['d2'];
+
+let d2Instance = null;
+
+/**
+ * Render every `<pre class="d2">` under `container` to inline SVG.
+ *
+ * @param {ParentNode} container
+ * @param {object} [options]
+ * @param {string[]} [options.classes=D2_CLASSES]
+ * @param {object} [options.compileOptions] - Passed to `d2.compile` (e.g. `{ sketch: true }`).
+ * @param {() => Promise<{ compile: Function, render: Function }>} [options.load]
+ *   Resolve the D2 instance; overridable for tests / a self-hosted build.
+ *   Defaults to lazy-importing `@terrastruct/d2`.
+ * @param {(el: Element, message: string) => void} [options.onError]
+ * @returns {Promise<number>} How many blocks were rendered.
+ */
+export async function renderD2Diagrams(container, options = {}) {
+    const classes = options.classes ?? D2_CLASSES;
+    const load = options.load ?? defaultLoad;
+
+    return renderBlocks(container, classes, async (source) => {
+        const d2 = await load();
+        const result = await d2.compile(source, options.compileOptions);
+
+        return d2.render(result.diagram, result.renderOptions);
+    }, { flag: 'd2', onError: options.onError });
+}
+
+async function defaultLoad() {
+    if (!d2Instance) {
+        const { D2 } = await import('@terrastruct/d2');
+        d2Instance = new D2();
+    }
+
+    return d2Instance;
+}
+
+export default renderD2Diagrams;

package/diagrams/graphviz.js

@@ -0,0 +1,59 @@
+/**
+ * Graphviz diagram renderer for Carve fenced-render output.
+ *
+ * `FencedRenderExtension::graphviz()` emits `<pre class="graphviz">DOT</pre>`.
+ * Graphviz has a mature, self-contained WebAssembly build (`@viz-js/viz`), so
+ * this renders entirely in the browser - no server, no external call, works
+ * offline. The library is imported lazily (only when a graphviz block is on
+ * the page) and the Viz instance is reused across blocks and calls.
+ *
+ * @example
+ * import { renderGraphvizDiagrams } from '@markup-carve/carve-grammars/diagrams/graphviz'
+ * await renderGraphvizDiagrams(document.querySelector('.carve-output'))
+ */
+import { renderBlocks } from './render-blocks.js';
+
+/**
+ * CSS classes claimed as Graphviz DOT. `graphviz` is the FencedRenderExtension
+ * cssClass; `dot` covers a block configured with that class directly.
+ */
+export const GRAPHVIZ_CLASSES = ['graphviz', 'dot'];
+
+let vizInstance = null;
+
+/**
+ * Render every `<pre class="graphviz">` under `container` to inline SVG.
+ *
+ * @param {ParentNode} container
+ * @param {object} [options]
+ * @param {string[]} [options.classes=GRAPHVIZ_CLASSES]
+ * @param {() => Promise<{ renderString(dot: string, opts?: object): string }>} [options.load]
+ *   Resolve the Viz instance; overridable for tests / a self-hosted build.
+ *   Defaults to lazy-importing `@viz-js/viz`.
+ * @param {(el: Element, message: string) => void} [options.onError]
+ * @returns {Promise<number>} How many blocks were rendered.
+ */
+export async function renderGraphvizDiagrams(container, options = {}) {
+    const classes = options.classes ?? GRAPHVIZ_CLASSES;
+    const load = options.load ?? defaultLoad;
+
+    return renderBlocks(container, classes, async (source) => {
+        const viz = await load();
+        // renderString (not renderSVGElement) so it works in any host: the
+        // latter needs a browser DOMParser, the former just returns the SVG
+        // string, which renderBlocks wraps. Strip the XML prolog so the markup
+        // starts at <svg>.
+        return viz.renderString(source, { format: 'svg' }).replace(/^\s*<\?xml[^>]*\?>\s*/, '');
+    }, { flag: 'graphviz', onError: options.onError });
+}
+
+async function defaultLoad() {
+    if (!vizInstance) {
+        const { instance } = await import('@viz-js/viz');
+        vizInstance = await instance();
+    }
+
+    return vizInstance;
+}
+
+export default renderGraphvizDiagrams;

package/diagrams/index.js

@@ -0,0 +1,55 @@
+/**
+ * Carve diagram renderers.
+ *
+ * Turns the `FencedRenderExtension` diagram hydration elements
+ * (`<pre class="LANG">source</pre>`) into rendered diagrams in the browser:
+ *
+ * - `renderGraphvizDiagrams` - Graphviz via `@viz-js/viz` (offline WASM)
+ * - `renderD2Diagrams` - D2 via `@terrastruct/d2` (offline WASM)
+ * - `renderKrokiDiagrams` - PlantUML (and any opted-in type) via a Kroki server
+ *
+ * Mermaid, WaveDrom, Vega-Lite and Chart already have their own browser
+ * libraries; load and run those yourself.
+ *
+ * `renderDiagrams` is a convenience that runs all three. Each self-loads its
+ * library lazily and no-ops when its blocks are absent, so calling it costs
+ * nothing for the types not present on the page. The Kroki step is off unless
+ * you opt in (`options.kroki`), because it may call an external server - see
+ * `renderKrokiDiagrams` for the privacy/GDPR note.
+ */
+export { renderGraphvizDiagrams, GRAPHVIZ_CLASSES } from './graphviz.js';
+export { renderD2Diagrams, D2_CLASSES } from './d2.js';
+export { renderKrokiDiagrams, KROKI_DIAGRAM_TYPES } from './kroki.js';
+
+import { renderGraphvizDiagrams } from './graphviz.js';
+import { renderD2Diagrams } from './d2.js';
+import { renderKrokiDiagrams } from './kroki.js';
+
+/**
+ * Render the offline diagram types (Graphviz, D2) under `container`, and -
+ * only when `options.kroki` is set - PlantUML via Kroki.
+ *
+ * @param {ParentNode} container
+ * @param {object} [options]
+ * @param {object} [options.graphviz] - Options for `renderGraphvizDiagrams` (omit to enable with defaults; `false` to skip).
+ * @param {object} [options.d2] - Options for `renderD2Diagrams` (omit to enable with defaults; `false` to skip).
+ * @param {object} [options.kroki] - Options for `renderKrokiDiagrams`; OFF unless provided (opt-in, may call an external server).
+ * @returns {Promise<number>} Total blocks rendered.
+ */
+export async function renderDiagrams(container, options = {}) {
+    const tasks = [];
+    if (options.graphviz !== false) {
+        tasks.push(renderGraphvizDiagrams(container, options.graphviz || {}));
+    }
+    if (options.d2 !== false) {
+        tasks.push(renderD2Diagrams(container, options.d2 || {}));
+    }
+    if (options.kroki) {
+        tasks.push(renderKrokiDiagrams(container, options.kroki));
+    }
+    const counts = await Promise.all(tasks);
+
+    return counts.reduce((a, b) => a + b, 0);
+}
+
+export default renderDiagrams;

package/diagrams/kroki.js

@@ -0,0 +1,147 @@
+/**
+ * Kroki diagram renderer for Carve fenced-render output.
+ *
+ * The one diagram preset with no practical in-browser renderer is **PlantUML**
+ * (its only pure-JS build is a multi-megabyte JVM-in-WASM). This helper renders
+ * it - and any other Kroki-supported type you opt in - by POSTing the source to
+ * a Kroki server. Graphviz and D2 do NOT need this: they have self-contained
+ * WebAssembly renderers (`renderGraphvizDiagrams`, `renderD2Diagrams`) that run
+ * offline, so they are not in the default type map.
+ *
+ * ⚠️ PRIVACY / GDPR: the default server is the PUBLIC `https://kroki.io`, so the
+ * diagram source is sent to a third party outside your control. For anything
+ * sensitive - or to keep rendering offline - point `server` at a self-hosted
+ * Kroki (or a localhost instance) so no data leaves your domain, and disclose
+ * the external call to end users where required.
+ *
+ * It is dependency-free: the diagram source is POSTed to Kroki as plain text
+ * (no deflate/base64 step, so no pako dependency), and the returned SVG is
+ * shown in an `<img>` via a data URI. An `<img>` cannot execute script, so
+ * Kroki's SVG output is inert on the page regardless of its content.
+ *
+ * SVG only, by design: the output rides in a `data:image/svg+xml` URI, which
+ * is text-based and scales cleanly. Binary Kroki formats (PNG, PDF) would need
+ * a different transport and are out of scope for an inline browser renderer.
+ *
+ * @example
+ * import { renderKrokiDiagrams } from '@markup-carve/carve-grammars/diagrams/kroki'
+ * await renderKrokiDiagrams(document.querySelector('.carve-output'))
+ *
+ * @example <caption>Self-hosted Kroki + only PlantUML</caption>
+ * await renderKrokiDiagrams(container, {
+ *   server: 'https://kroki.internal',
+ *   types: { plantuml: 'plantuml', puml: 'plantuml' },
+ * })
+ */
+
+/**
+ * Default map of fenced-block CSS class (the `FencedRenderExtension` cssClass)
+ * to the Kroki diagram type. PlantUML only, because it is the one preset with
+ * no practical in-browser renderer. Graphviz and D2 have offline WASM renderers
+ * (`renderGraphvizDiagrams`, `renderD2Diagrams`); Mermaid, WaveDrom, Vega-Lite
+ * and Chart have their own browser libraries. To Kroki-render one of those
+ * anyway (e.g. against a self-hosted server), pass an extended `types` map.
+ *
+ * @type {Record<string, string>}
+ */
+export const KROKI_DIAGRAM_TYPES = {
+    plantuml: 'plantuml',
+    puml: 'plantuml',
+};
+
+/**
+ * Render every Kroki-supported fenced-render block inside `container`.
+ *
+ * Each matching `<pre class="LANG">` is replaced with an `<img>` of the Kroki
+ * output. Processing is idempotent (a rendered or errored block is marked and
+ * skipped on a later call), so it is safe to run after every content update.
+ *
+ * @param {ParentNode} container - Root to search for diagram blocks.
+ * @param {object} [options]
+ * @param {string} [options.server='https://kroki.io'] - Kroki base URL.
+ * @param {Record<string, string>} [options.types=KROKI_DIAGRAM_TYPES] - CSS
+ *   class to Kroki-type map. Also selects which blocks are claimed.
+ * @param {(el: Element, message: string) => void} [options.onError] - Called
+ *   for a block that fails to render; by default the `<pre>` is left in place
+ *   with a `data-kroki-error` attribute.
+ * @param {typeof fetch} [options.fetch=globalThis.fetch] - Fetch implementation
+ *   (overridable for tests / non-browser hosts).
+ * @returns {Promise<number>} How many blocks were rendered in this call.
+ */
+export async function renderKrokiDiagrams(container, options = {}) {
+    if (!container) {
+        return 0;
+    }
+    const server = (options.server ?? 'https://kroki.io').replace(/\/+$/, '');
+    const types = options.types ?? KROKI_DIAGRAM_TYPES;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const onError = options.onError;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error('renderKrokiDiagrams: no fetch implementation available');
+    }
+
+    const classes = Object.keys(types);
+    if (classes.length === 0) {
+        return 0;
+    }
+    const selector = classes.map((cls) => `pre.${cls}`).join(', ');
+    const blocks = [...container.querySelectorAll(selector)];
+
+    const results = await Promise.all(blocks.map(async (el) => {
+        if (el.dataset.krokiProcessed) {
+            return 0;
+        }
+        el.dataset.krokiProcessed = 'true';
+        // First matching class wins, mirroring the single cssClass a
+        // FencedRenderExtension block carries.
+        const cls = classes.find((c) => el.classList.contains(c));
+        const krokiType = types[cls];
+        const source = el.textContent.trim();
+        try {
+            const response = await fetchImpl(`${server}/${krokiType}/svg`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'text/plain' },
+                body: source,
+            });
+            if (!response.ok) {
+                throw new Error(`Kroki responded ${response.status}`);
+            }
+            const rendered = await response.text();
+            const doc = el.ownerDocument;
+            const img = doc.createElement('img');
+            img.src = svgDataUri(rendered);
+            img.alt = `${krokiType} diagram`;
+            img.loading = 'lazy';
+            img.className = `carve-diagram carve-diagram-${krokiType}`;
+            el.replaceWith(img);
+
+            return 1;
+        } catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            el.dataset.krokiError = message;
+            if (typeof onError === 'function') {
+                onError(el, message);
+            }
+
+            return 0;
+        }
+    }));
+
+    return results.reduce((a, b) => a + b, 0);
+}
+
+/**
+ * Encode an SVG string as a base64 `data:` URI for an `<img src>`.
+ *
+ * @param {string} svg
+ * @returns {string}
+ */
+function svgDataUri(svg) {
+    // btoa needs Latin-1; percent-encode first so any UTF-8 in the diagram
+    // (labels, etc.) survives.
+    const base64 = btoa(unescape(encodeURIComponent(svg)));
+
+    return `data:image/svg+xml;base64,${base64}`;
+}
+
+export default renderKrokiDiagrams;