@voithos-labs/aragonite 0.10.3 → 0.10.7

package/docs/guide/plugin-api.md

@@ -1,196 +1,206 @@
 # Plugin API Reference
 
-Every export of `@voithos-labs/aragonite/plugin`, grouped by job, so you can find a name and what it does without reading the package's entry module. Nobody reads this page top to bottom; Ctrl+F your way to the name you're after. The recipes behind the names live in the [plugin guide](plugin-guide.md), and each group links to its section there.
+Every export of `@voithos-labs/aragonite/plugin`, grouped by job, so you can find a name and what it does without reading the package's entry module. Nobody reads this page top to bottom; Ctrl+F your way to the name you're after. The recipes behind the names live in the [plugin guide](plugin-guide.md), and most groups link to their section there.
 
 ## API reference
 
 Values are the calls you make, and the types beside them describe what those calls take and hand back.
 
-Five words recur in every table, so here they are once:
+Four words recur in every table, so here they are once:
 
 - A **kind** is aragonite's word for a block type. Paragraph is a kind, fenced code is a kind, your plugin's block is about to be one.
-- A block's **raw** is its exact source bytes, and saving a document is just concatenating them.
+- A block's **raw** is its exact source bytes, and saving a document is just concatenating them (with the blank lines kept between blocks).
 - An **opener** is the piece of the parser that recognizes the line a block starts with.
 - A **leaf** is a block with no child blocks; a **container** holds other blocks.
-- To **mint** is to create a branded, registry-backed identity (a kind, a command id) in the one authorized place; a duplicate throws.
 
-A group tagged _(pre-freeze / unstable)_ may still change shape until the 1.0 freeze; an untagged group already holds its final shape. The tags copy the section notes in the entry module (`src/lib/plugin.ts`).
-
-Adding an export? Give it a row in its group, tagged the way its entry-module section is tagged. A test (`src/lib/test/plugins/plugin-guide-coverage.test.ts`) diffs this page against the entry module and fails naming any export without a row. It finds the catalog by the exact `## API reference` heading above, so if you rename the heading, rename it there too.
+A group tagged _(pre-freeze / unstable)_ may still change shape until the freeze at the public release, and so may a single row tagged the same way inside an untagged group. In an untagged group the model is settled (which calls exist, that each registers once, what a kind is), and the exact call shapes freeze with everything else at the public release. The tags follow the section notes in the package's entry module (`src/lib/plugin.ts`) and the plugin contract (`docs/design/plugin-contract.md` in the repository), which is where `lineStartsOuterBlock`'s row tag comes from.
 
 The groups, in page order:
 
 | Group                                                   | What it covers                                                                               |
 | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | [The plugin unit](#the-plugin-unit)                     | Packaging your extension, installing it, and what each mounted editor hands it back          |
-| [Kind declaration](#kind-declaration)                   | Minting a new block type's identity                                                          |
+| [Kind declaration](#kind-declaration)                   | Creating a new block type's identity                                                         |
 | [The block-kind descriptor](#the-block-kind-descriptor) | Telling the editor how your block type behaves, and the checklist every one must fill in     |
 | [The component registry](#the-component-registry)       | Binding a block type to the Svelte component that renders it                                 |
-| [Code-block languages](#code-block-languages)           | Adding syntax-highlighting grammars beyond the bundled set                                   |
 | [The parser opener](#the-parser-opener)                 | Teaching the parser to recognize your block's syntax                                         |
 | [Enter completion](#enter-completion)                   | Letting one typed line become a construct whose lines must sit together                      |
 | [Registration probes](#registration-probes)             | Checking what's already registered, so a module that runs twice stays safe                   |
 | [Directive authoring](#directive-authoring)             | Owning a `:::name` block without writing your own parsing                                    |
 | [Container authoring](#container-authoring)             | Blocks that hold other blocks, plus their title line                                         |
 | [Editable-leaf authoring](#editable-leaf-authoring)     | A text-editing block with the editor's own caret, undo, and selection                        |
+| [Code-block languages](#code-block-languages)           | Adding syntax-highlighting grammars beyond the bundled set                                   |
 | [Inline authoring](#inline-authoring)                   | Your own syntax inside a paragraph, rendered as a widget                                     |
 | [Commands and keybindings](#commands-and-keybindings)   | Keyboard shortcuts and commands, per block type or editor-wide                               |
 | [Paste transforms](#paste-transforms)                   | Rewriting pasted text before the editor parses it                                            |
 | [Decorations](#decorations)                             | View-only annotations over content your plugin does not own                                  |
+| [Inline menus](#inline-menus)                           | A list under the caret that a typed trigger opens                                            |
+| [Insert catalogue](#insert-catalogue)                   | The blocks the insert menus offer, and adding your own                                       |
 | [Events](#events)                                       | What the editor tells your plugin has happened, and the shapes it says it in                 |
 | [Rects](#rects)                                         | Where things are on screen: block boxes, ranges, the caret, scrolling to a block             |
 | [Caret geometry](#caret-geometry)                       | Answering where a press inside your block puts the caret                                     |
+| [Pointer gestures](#pointer-gestures)                   | Keeping a drag that belongs to your block (a pan, a brush) from starting a selection         |
 | [Selection geometry](#selection-geometry)               | The shapes that describe what the user has selected                                          |
 | [Parse and serialize](#parse-and-serialize)             | Markdown in, tree out, and back again                                                        |
 | [Grammar scanners](#grammar-scanners)                   | The editor's own code-fence, HTML-tag, and blockquote rules, reusable so you never fork them |
 | [Node access and metadata](#node-access-and-metadata)   | Reading the document tree, and storing your own data on a block                              |
+| [Injected renderers](#injected-renderers)               | A library the host hands you to draw your block (KaTeX, mermaid), cached per theme           |
 | [Performance helpers](#performance-helpers)             | A small cache and a scan index for render and recognition work                               |
 
 ### The plugin unit
 
 _(pre-freeze / unstable)_ The installable package, and the per-editor context it gets back. Wiring and the traps: [The plugin unit](plugin-guide.md#the-plugin-unit) and [One process, many editors](plugin-guide.md#one-process-many-editors).
 
-| Export               | Role                                                                                                                                                                                                                |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `definePlugin`       | Validate a `{ name, setup }` unit at definition time and return it, ready for the editor's `plugins` prop                                                                                                           |
-| `definePluginBlock`  | The single-block shortcut: one kind, one component, one register step, packaged as a unit                                                                                                                           |
-| `isPluginInstalled`  | Has a plugin of this name installed? For the rare setup that has to branch on it                                                                                                                                    |
-| `EditorPlugin`       | The unit's shape; the `plugins` prop and the main entry's `installPlugins` take these                                                                                                                               |
-| The `plugins` prop   | Installs once per process, and activates per editor: an editor runs the hooks, kinds, commands and paste transforms of exactly the plugins it lists (no prop at all activates every installed one)                  |
-| `EditorPluginEntry`  | One `plugins` prop entry: a bare unit, or `{ plugin, options }` to vary options per editor                                                                                                                          |
-| `PluginSetupContext` | What `setup(ctx)` receives; its `onEditor(cb)` registers a per-editor callback (call it from `setup`, synchronously)                                                                                                |
-| `OnEditorCallback`   | The callback itself: receives the `EditorContext` of each mounted editor that listed your plugin, may return a cleanup function the editor runs at unmount                                                          |
-| `EditorContext`      | One editor's view for your plugin: `editorId`, the live read-only `document`, subscribe-only `events`, this editor's `options`, its `decorations` and `rects` surfaces, and the live `presentationMode` and `theme` |
-| `PresentationMode`   | The union of the editor's view modes (source, reading, the previews, live); every mode read reports the effective one, meaning the mode actually in force. [Presentation modes](plugin-guide.md#presentation-modes) |
+| Export                  | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `definePlugin`          | Validate a `{ name, setup }` unit at definition time and return it, ready for the editor's `plugins` prop. Optional `defaults` are where every editor's `options` start, and `parseOptions(raw)` checks an editor's entry before it lands on them                                                                                                                                                                                                                                                                           |
+| `definePluginBlock`     | The single-block shortcut: one kind, one component, one register step, packaged as a unit; takes `defaults` and `parseOptions` like `definePlugin`                                                                                                                                                                                                                                                                                                                                                                          |
+| `isPluginInstalled`     | Has a plugin of this name installed? For the rare setup that has to branch on it                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `EditorPlugin`          | The unit's shape; the `plugins` prop and the main entry's `installPlugins` take these                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| The `plugins` prop      | Installs once per process, and activates per editor: an editor runs the hooks, kinds, commands and paste transforms of exactly the plugins it lists (no prop at all activates every installed one)                                                                                                                                                                                                                                                                                                                          |
+| `EditorPluginEntry`     | One `plugins` prop entry: a bare unit, or `{ plugin, options }` to vary options per editor. A field you pass replaces the plugin's default for it (arrays too); the rest keep theirs                                                                                                                                                                                                                                                                                                                                        |
+| `PluginSetupContext`    | What `setup(ctx)` receives; its `onEditor(cb)` registers a per-editor callback (call it from `setup`, synchronously)                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `OnEditorCallback`      | The callback itself: receives the `EditorContext` of each mounted editor that listed your plugin, may return a cleanup function the editor runs at unmount                                                                                                                                                                                                                                                                                                                                                                  |
+| `EditorContext`         | One editor's view for your plugin: `editorId`, the live read-only `document` and its `documentGeneration`, subscribe-only `events`, this editor's `options` (its entry over your `defaults`), its `decorations`, `rects` and `inlineMenus`, the live `insertCatalogue`, `presentationMode` and `theme`, `insertMarkdown` (a promise, resolved when the insert lands) and `runCommand`, which act like the instance's own methods and return false where those would, and `computeInlineContent`, this editor's inline parse |
+| `InsertMarkdownOptions` | `insertMarkdown`'s second argument: `placement: 'below'` puts the text into a new paragraph after the top-level block holding the caret, the way the right-click "Insert block" rows do, the paragraph and the text in one undo entry; the default inserts at the caret                                                                                                                                                                                                                                                     |
+| `PresentationMode`      | The union of the editor's view modes (source, reading, the previews, live); every mode read reports the effective one, meaning the mode actually in force. [Presentation modes](plugin-guide.md#presentation-modes)                                                                                                                                                                                                                                                                                                         |
 
 ### Kind declaration
 
 Every kind starts here. No other call accepts a bare string where a kind goes.
 
-| Export                            | Role                                                                                                    |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `declarePluginKind`               | Mint a block kind from a name and get the kind back; a collision with a built-in or a prior kind throws |
-| `declaredPluginKind`              | Recover an already-declared kind in another module, no cast; throws for a name nobody declared          |
-| `PluginBlockKind`, `AnyBlockKind` | The plugin-declared kind type, and the union of built-in and plugin kinds a node can carry              |
+| Export                            | Role                                                                                                                                                                                                                                             |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `declarePluginKind`               | Create a block kind from a name and get the kind back; a collision with a built-in or a prior kind throws, and so do the reserved names `document` and `global` and a name that isn't a lowercase letter followed by letters, digits and hyphens |
+| `declaredPluginKind`              | Recover an already-declared kind in another module, no cast; throws for a name nobody declared                                                                                                                                                   |
+| `PluginBlockKind`, `AnyBlockKind` | The plugin-declared kind type, and the union of built-in and plugin kinds a node can carry                                                                                                                                                       |
 
 ### The block-kind descriptor
 
 The **descriptor** is a kind's written behavior: how it merges, whether it's editable, its container shape. Its required `closure` field is the kind's answer to each cross-cutting editor system (undo, search, selection, clipboard and friends), so a new kind can't ship silently broken under a subsystem nobody asked about. Cell by cell: [The closure block](plugin-guide.md#the-closure-block).
 
-| Export                                         | Role                                                                                                                                                                                                  |
-| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `registerBlockKind`                            | Register a kind's descriptor; the kind errors at first use without one                                                                                                                                |
-| `augmentBlockKind`                             | Merge extra fields into a kind your own plugin registered; built-in kinds and another plugin's kinds are refused with a throw                                                                         |
-| `BlockKindRegistration`, `BlockKindDescriptor` | What `registerBlockKind` accepts, and the flat read-side shape lookups hand back                                                                                                                      |
-| `BlockKindAugmentation`                        | The patch `augmentBlockKind` merges; a partial `container` group merges into the existing one                                                                                                         |
-| `ContainerDescriptorGroup`                     | The descriptor's container-only half: `rebuildRaw` (the hook that recomputes a container's raw from its children after an edit), the body wrap, the reserved title line, unwrap behavior              |
-| `MergeRole`, `UnwrapRole`                      | Closed sets naming how a kind merges on Backspace, and how a container releases a child at its edge                                                                                                   |
-| `ChildRawChange`                               | `rebuildRaw`'s optional second argument: which one child's bytes just moved, for a rebuilder that re-emits only that region. Ignoring it and re-deriving the whole raw is always correct, just slower |
-| `ClosureBlock`, `ClosureColumn`, `ClosureCell` | The closure matrix: nine columns, one cell each, and a cell is `implemented` (name the mechanism), `inherit-default`, or `not-supported` (name the degradation). A missing column fails the typecheck |
-| `simpleLeafClosure`, `SimpleLeafClosureCells`  | Closure preset for a plain text leaf: bakes the five cells every such leaf answers alike, requires the four your component determines (`focus`, `searchPaint`, `undo`, `simOracle`)                   |
-| `containerClosure`, `ContainerClosureCells`    | Closure preset for a container of real child blocks: bakes the four structural cells plus `roundTrip: implemented`, requires the round trip's `via` string and the four the container determines      |
+| Export                                         | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerBlockKind`                            | Register a kind's descriptor; the kind errors at first use without one                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `augmentBlockKind`                             | Merge extra fields into a kind your own plugin registered; built-in kinds and another plugin's kinds are refused with a throw                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `BlockKindRegistration`                        | What `registerBlockKind` accepts. Its optional `label` is what a screen reader and the block menu call the block, `pageRole` whether it reads as prose (no drag handle) or as an object, `estimateHeight(node, env)` its height guess before it's measured, and `dragLabel` what the drag ghost calls it. Fields that only work as a pair are declared as one (`contentStart: { range, backspace? }` for a kind whose markers sit in front of its text, and the `container` group), so a registration that can't work, like a block focused as one unit that also parses inline syntax, won't compile                                                                                                                                         |
+| `HeightEstimateEnv`                            | What `estimateHeight` reads besides the block: the editor's width, its line heights and character width, the frame it adds to every block, and the floor for an unsized image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `BlockKindAugmentation`                        | The patch `augmentBlockKind` merges; a partial `container` group merges into the existing one. The fields other fields depend on (`blockFocus`, `supportsInline`, `contentStart`, the title row and the unwrap strategies) are fixed at registration, and an augment naming one throws, even from plain JavaScript                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `WriteRule`, `WriteContext`                    | A kind's write rule: `rawWrite` for its own bytes, `container.bodyWrite` for a child's. `normalize(raw, ctx)` makes written bytes legal, and `mapOffset(raw, offset, ctx)` says where a caret in them lands. `ctx` carries the block (`node`), the document's `lineEnding` for any line the rule puts back, and a `mode`: `'authored'` when the user typed the bytes in the block (an editable leaf's commits, and typing in the code, text and cell surfaces), `'literal'` for content that arrives whole (a paste, a replace, a range delete). The editor runs your rule on every content write and moves the caret with your `mapOffset`, so a rule that repairs half-written syntax should check `mode`, or it'll fight the user's typing |
+| `ContainerDescriptorGroup`                     | The descriptor's container-only half: the required `contract` (`'strip'`, `'grid'` or `'opaque'`) and `rebuildRaw` (the hook that recomputes a container's raw from its children after an edit), plus the body wrap, the body write rule, the reserved title line, unwrap behavior, paste merging, a content line's first space (`contentStartSpace`), and whether its children reorder among themselves. A declared title line (`reservedChrome`) already decides what Backspace does at its start, so its `unwrapRole` names only `middleChildBackspace`                                                                                                                                                                                    |
+| `MergeRole`, `ContainerUnwrapRole`             | Closed sets naming how a kind merges on Backspace, and how a container releases a child at its edge                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `ChildRawChange`                               | `rebuildRaw`'s optional second argument: which one child's bytes just moved, for a rebuilder that re-emits only that region. Ignoring it and re-deriving the whole raw is always correct, just slower                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `ClosureBlock`, `ClosureColumn`, `ClosureCell` | The closure matrix: nine columns, one cell each, and a cell is `implemented` (name the mechanism), `inherit-default`, or `not-supported` (name the degradation). A missing column fails the typecheck                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `simpleLeafClosure`, `SimpleLeafClosureCells`  | Closure preset for a plain text leaf: bakes the five cells every such leaf answers alike, requires the four your component determines (`focus`, `searchPaint`, `undo`, `simOracle`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `containerClosure`, `ContainerClosureCells`    | Closure preset for a container of real child blocks: bakes the four structural cells plus `roundTrip: implemented`, requires the round trip's `via` string and the four the container determines                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 
 ### The component registry
 
-| Export                                    | Role                                                                                                                             |
-| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `registerBlockComponent`                  | Bind a kind to the Svelte component that renders it; without one the kind renders as a visible raw-text fallback (you'll notice) |
-| `defineBlockComponent`                    | Wrap your component into the registry's entry shape; a container that forgot to publish its API fails the typecheck here         |
-| `BlockComponentEntry`                     | The registry entry: the component, plus an optional per-node extra-props hook                                                    |
-| `BlockComponent`, `BlockComponentExports` | The surface a block component publishes: a leaf's own members, or a container's single `containerApi` export                     |
-| `BlockComponentProps`                     | The props every block component receives: its node, its position, the read-only whole document, the editor's geometry surface    |
+| Export                                    | Role                                                                                                                                                                                                                                                            |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerBlockComponent`                  | Bind a kind to the Svelte component that renders it; without one the kind renders as a visible raw-text fallback (you'll notice)                                                                                                                                |
+| `defineBlockComponent`                    | Wrap your component into the registry's entry shape; a container that forgot to publish its API fails the typecheck here                                                                                                                                        |
+| `BlockComponentEntry`                     | The registry entry: the component, plus an optional per-node extra-props hook                                                                                                                                                                                   |
+| `BlockComponent`, `BlockComponentExports` | The surface a block component publishes: a leaf's own members, or a container's single `containerApi` export                                                                                                                                                    |
+| `BlockComponentProps`                     | The props every block component receives: its node, its index and path, the marker prefix a container hands its first child (a list item's `- `; a leaf that drops it loses its markers on screen), the read-only whole document, the editor's geometry surface |
 
 ### The parser opener
 
-Where your opener sits on the ladder, and the two placement rules: [Opener priority](plugin-guide.md#opener-priority).
+Where your opener sits in the priority order, and the two placement rules: [Opener priority](plugin-guide.md#opener-priority).
 
-| Export                                   | Role                                                                                                                                                                                                                  |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `registerBlockOpener`                    | Teach the parser to recognize your kind's Markdown syntax                                                                                                                                                             |
-| `BlockOpener`, `OpenContext`             | The opener contract, and the line cursor its `tryOpen` inspects: the lines, the position, the parse's scope and depth                                                                                                 |
-| `BlockOpenerResult`                      | A claim: the node built, plus `consumed`, the count of lines it took                                                                                                                                                  |
-| `OPENER_PRIORITIES`                      | The built-in priorities your opener picks its own number relative to; lower dispatches first _(pre-freeze / unstable)_                                                                                                |
-| `lineStartsOuterBlock`, `OuterBlockScan` | "Does this line start a block at the outer level?" The shared end-of-extent test for a container opener scanning its own lines, and its input flag saying whether a paragraph is open above _(pre-freeze / unstable)_ |
+| Export                                   | Role                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerBlockOpener`                    | Teach the parser to recognize your kind's Markdown syntax                                                                                                                                                                                                                                                                                                                                                  |
+| `BlockOpener`, `OpenContext`             | The opener contract, and the line cursor its `tryOpen` inspects: the lines, the position, the blank lines above (`leadingTrivia`), the parse's scope and depth, and the `grammar` to pass on to any nested parse                                                                                                                                                                                           |
+| `BlockOpenerResult`                      | A claim: the node built, plus `consumed`, the count of lines it took                                                                                                                                                                                                                                                                                                                                       |
+| `OPENER_PRIORITIES`                      | The built-in priorities your opener picks its own number relative to; lower dispatches first _(pre-freeze / unstable)_                                                                                                                                                                                                                                                                                     |
+| `lineStartsOuterBlock`, `OuterBlockScan` | "Does this line start a block at the outer level?" The shared end-of-extent test for a container opener scanning its own lines, and its inputs: whether a paragraph is open above, the grammar (required: pass the one your opener was given, so a syntax the editor left out starts nothing), and optionally the lines around it, for an opener that needs a later line to open _(pre-freeze / unstable)_ |
 
 ### Enter completion
 
 _(pre-freeze / unstable)_ The recipe: [Typing a multi-line construct into existence](plugin-guide.md#typing-a-multi-line-construct-into-existence).
 
-| Export                   | Role                                                                                                                                    |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `registerBlockCompleter` | Let one typed line complete into a grammar whose lines must sit adjacent, which Enter alone can never type                              |
-| `BlockCompleter`         | The contract: `tryComplete(line)` claims with a result, or declines with null; `onType: true` also consults it as the line is typed     |
-| `CompletionResult`       | A claim: the lines to insert, endings omitted (the editor attaches the document's own), plus where the caret seats inside the insertion |
+| Export                   | Role                                                                                                                                                             |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerBlockCompleter` | Let one typed line complete into a grammar whose lines must sit adjacent, which Enter alone can never type                                                       |
+| `BlockCompleter`         | The contract: `tryComplete(line)` claims with a result, or declines with null; `onType: true` also consults it as the line is typed                              |
+| `CompletionResult`       | A claim: the lines to insert, endings omitted (the editor attaches the block's own ending, else the document's), plus where the caret lands inside the insertion |
 
 ### Registration probes
 
-Every registry on this surface is register-once (a duplicate throws, it never overrides). These are the matching is-it-there checks, for a module that may run twice (hot reload, a re-import) to ask before registering. Guard on these rather than on a module-level flag of your own: the flag outlives the test kit's platform reset, and the guide's registration section tells you how that afternoon goes. The directive and inline tiers keep their own probes, `isDirectiveRegistered` and `isInlineKindDeclared`, in their groups below.
+Every process-global registry on this surface is register-once: a duplicate throws in production and under test, and never silently overrides (a dev server replaces the entry and warns, so an edited module takes effect on re-run). These are the matching is-it-there checks, for a module that may run twice (hot reload, a re-import) to ask before registering. Guard on these rather than on a module-level flag of your own: the flag outlives the test kit's platform reset, and the guide's registration section tells you how that goes. The directive and inline tiers keep their own probes, `isDirectiveRegistered` and `isInlineKindDeclared`, in their groups below.
 
-| Export                                                                                                         | Role                                               |
-| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| `isBlockKindDeclared`                                                                                          | Is this kind name already declared?                |
-| `isBlockKindRegistered`, `isBlockComponentRegistered`, `isBlockOpenerRegistered`, `isBlockCompleterRegistered` | One guard per register-once call on the block side |
-| `isPasteTransformRegistered`                                                                                   | The same guard, keyed by a paste transform's name  |
+| Export                                                                                                         | Role                                                  |
+| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `isBlockKindDeclared`                                                                                          | Is this kind name already declared?                   |
+| `isBlockKindRegistered`, `isBlockComponentRegistered`, `isBlockOpenerRegistered`, `isBlockCompleterRegistered` | One guard per register-once call on the block side    |
+| `isPasteTransformRegistered`                                                                                   | The same guard, keyed by a paste transform's name     |
+| `isLanguageRegistered`                                                                                         | The same guard, keyed by a code-block language's name |
 
 ### Directive authoring
 
 _(pre-freeze / unstable)_ The `:::name` grammar itself is the [directives guide](directives.md)'s subject; the worked container is [the walkthrough](plugin-guide.md#walkthrough-a-conspiracy-container-end-to-end).
 
-| Export                                                   | Role                                                                                                                                                                          |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `activateDirectives`                                     | Turn the `:::name` grammar on, once at startup, before the first parse; every other export here is inert until it runs                                                        |
-| `registerDirective`                                      | Map a `(tier, name)` pair to one of your kinds; a container mapping must bring its node factory (`fromDirective`), or registration throws                                     |
-| `isDirectiveRegistered`                                  | The is-it-there check for a directive name                                                                                                                                    |
-| `parseDirectiveAttributes`                               | Opt-in reader pulling a `[label]` and a `{#id .class key=val}` block out of a directive's info string; one-way, it reads and never writes back                                |
-| `serializeDirective`                                     | Re-emit a directive's exact bytes from its parts (colon count, name, verbatim info string, body, closer shape), growing the fences itself so no body line reads as the closer |
-| `escalatedColonCount`                                    | The fence length a body forces, for an emitter building `:::name` text by hand instead of through `serializeDirective`                                                        |
-| `createDirectiveRebuild`                                 | Build the raw-recompute hook (`rebuildRaw`) for a directive container whose child 0 is an editable title; owns the fence bytes, CRLF included                                 |
-| `DIRECTIVE_BODY_WRAP`                                    | The wrap every `:::` body parses with; declare it as your container kind's `bodyWrap` so a blank line against the fence settles where it belongs                              |
-| `DirectiveDefinition`, `ParsedDirective`                 | The registration's shape, and the parsed fence your factory receives: the fence parts, the parsed body, the exact consumed bytes                                              |
-| `DirectiveTier`, `DirectiveFence`, `DirectiveAttributes` | The three tiers (container, leaf, text), one parsed opener line, and what the attribute reader returns                                                                        |
+| Export                                                   | Role                                                                                                                                                                                                                       |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `activateDirectives`                                     | Turn the `:::name` grammar on, once at startup, before the first parse; until it runs no `:::` line parses as a directive, so a `registerDirective` mapping has nothing to act on (the pure helpers below work either way) |
+| `registerDirective`                                      | Map a `(tier, name)` pair to one of your kinds; a container mapping must bring its node factory (`fromDirective`) and a text mapping must not, or registration throws                                                      |
+| `isDirectiveRegistered`                                  | The is-it-there check for a directive, asked as `(tier, name)`                                                                                                                                                             |
+| `parseDirectiveAttributes`                               | Opt-in reader pulling a `[label]` and a `{#id .class key=val}` block out of a directive's info string; one-way, it reads and never writes back                                                                             |
+| `serializeDirective`                                     | Re-emit a directive's exact bytes from its parts (colon count, name, verbatim info string, body, closer shape), growing the fences itself so no body line reads as the closer                                              |
+| `escalatedColonCount`                                    | The fence length a body forces, for an emitter building `:::name` text by hand instead of through `serializeDirective`                                                                                                     |
+| `createDirectiveRebuild`                                 | Build the raw-recompute hook (`rebuildRaw`) for a directive container whose child 0 is an editable title; owns the fence bytes, CRLF included                                                                              |
+| `DIRECTIVE_BODY_WRAP`                                    | The wrap every `:::` body parses with; declare it as your container kind's `bodyWrap` so a blank line against the fence stays with the fence                                                                               |
+| `DirectiveDefinition`, `ParsedDirective`                 | The registration's shape, and the parsed fence your factory receives: the fence parts, the parsed body, the exact consumed bytes                                                                                           |
+| `DirectiveTier`, `DirectiveFence`, `DirectiveAttributes` | The three tiers (container, leaf, text), one parsed opener line, and what the attribute reader returns                                                                                                                     |
 
 ### Container authoring
 
 _(pre-freeze / unstable)_ A container's **chrome** is its own furniture: the border, the title line, an icon if you like. The factory hides everything else (child-list state, ancestor wiring, the mounting of only what's visible), so your component only has to supply the chrome. Worked end to end in [the walkthrough](plugin-guide.md#walkthrough-a-conspiracy-container-end-to-end).
 
-| Export                                          | Role                                                                                                                                                                                                               |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `createContainerBlock`                          | Wire a nested-child-list container so your component is as thin as the built-in blockquote's                                                                                                                       |
-| `BlockList`                                     | The child-list component your container renders, spread with the factory's props, as a direct child of your box                                                                                                    |
-| `registerChromeLeaf`                            | Register a container's title or summary line as a kind of its own, with a sensible default keymap                                                                                                                  |
-| `chromeChild`                                   | Build the reserved child-0 node for that line: the title text plus its newline (an empty title keeps the bare newline)                                                                                             |
-| `isCollapsedContainer`                          | Read a container's collapse state through its descriptor, so your component and the editor's own walks agree                                                                                                       |
-| `ContainerBlock`, `ContainerBlockComponent`     | What the factory returns (the child-list props, the `containerApi` you publish, the keydown handler, plus the commit, focus-exit, mode, theme and options entries), and the shape that `containerApi` must satisfy |
-| `ContainerBlockDeps`, `ContainerBlockListProps` | The factory's inputs, live getters rather than captured values, and the props `BlockList` takes                                                                                                                    |
-| `RefSlots`                                      | The per-child reference accessors the child-list props carry                                                                                                                                                       |
-| `ChromeLeafOptions`                             | `registerChromeLeaf`'s options: a CSS class for styling the line, keymap overrides, the merge role                                                                                                                 |
+| Export                                          | Role                                                                                                                                                                                                                                                                                                                                      |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createContainerBlock`                          | Wire a nested-child-list container so your component is as thin as the built-in blockquote's                                                                                                                                                                                                                                              |
+| `BlockList`                                     | The child-list component your container renders, spread with the factory's props, as a direct child of your box                                                                                                                                                                                                                           |
+| `registerChromeLeaf`                            | Register a container's title or summary line as a kind of its own, with a sensible default keymap                                                                                                                                                                                                                                         |
+| `chromeChild`                                   | Build the reserved child-0 node for that line: the title text plus its newline (an empty title keeps the bare newline)                                                                                                                                                                                                                    |
+| `isCollapsedContainer`                          | Read a container's collapse state through its descriptor, so your component and the editor's own walks agree                                                                                                                                                                                                                              |
+| `ContainerBlock`, `ContainerBlockComponent`     | What the factory returns (the child-list props, the `containerApi` you publish, the keydown handler, plus the commit, focus-exit, mode, theme, options and scroll-hold entries, and `getEditor` for this editor's `EditorContext`), and the shape that `containerApi` must satisfy. The commit can also say where the caret goes after it |
+| `ContainerBlockDeps`, `ContainerBlockListProps` | The factory's inputs, live getters rather than captured values, and the props `BlockList` takes                                                                                                                                                                                                                                           |
+| `RefSlots`                                      | The per-child reference accessors the child-list props carry                                                                                                                                                                                                                                                                              |
+| `ChildList`                                     | A container's children as the editor walks down to one: their references, their render window, and whether the body is collapsed. `containerApi.childList()` returns it; the factory builds yours, so you'd only write one for a hand-rolled container                                                                                    |
+| `ChromeLeafOptions`                             | `registerChromeLeaf`'s options: the name a screen reader and the block menu give the line, a CSS class for styling it, keymap overrides, the merge role                                                                                                                                                                                   |
 
 ### Editable-leaf authoring
 
 _(pre-freeze / unstable)_ The container factory's sibling for leaves; the full story is [The editable leaf](plugin-guide.md#the-editable-leaf).
 
-| Export                                                | Role                                                                                                                                                   |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `createEditableLeaf`                                  | Wire a text-editing leaf with the editor's own caret, IME, undo, selection and clipboard; one spread wires the whole surface                           |
-| `EditableLeaf`                                        | What the factory returns: the spreads, the focus surface your component re-exports, the mode and option reads                                          |
-| `EditableLeafMode`                                    | The two modes: `'plain'` (always-editable source, per-keystroke commits) and `'render-primary'` (rendered view, reveal to edit, one commit on leaving) |
-| `EditableLeafSurfaceProps`, `EditableLeafRenderProps` | The two spreads: the source surface's, and the folded rendered view's (a render-primary block spreads both)                                            |
-| `EditableLeafDeps`                                    | The factory's inputs: live getters for the node, the index, the path, and your source element, plus the static `mode` and `singleLine` settings        |
-| `StickyColumnDirection`                               | Which vertical direction the caret is entering your block from, handed to `focusAtColumn` so the column carries across lines                           |
+| Export                                                | Role                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createEditableLeaf`                                  | Wire a text-editing leaf with the editor's own caret, IME, undo, selection and clipboard; one spread wires the whole surface                                                                                                                                                                                                                                |
+| `EditableLeaf`                                        | What the factory returns: the spreads, the focus surface your component re-exports (`afterSourceCommit` included), `sourceText`, the mode, theme and option reads, `getEditor` for this editor's `EditorContext`, and the programmatic edits (`insertMarkdown`, `reveal`, `commitSource`, `repaintSource`)                                                  |
+| `EditableLeafMode`                                    | The two modes: `'plain'` (always-editable source, per-keystroke commits) and `'render-primary'` (rendered view, reveal to edit, one commit on leaving)                                                                                                                                                                                                      |
+| `EditableLeafSurfaceProps`, `EditableLeafRenderProps` | The two spreads: the source surface's, and the folded rendered view's (a render-primary block spreads both)                                                                                                                                                                                                                                                 |
+| `EditableLeafDeps`                                    | The factory's inputs: live getters for the node, the index, the path, and your source element, the static `mode` and `singleLine` settings, and the optional rest: `isRevealed` / `setRevealed` (required in render-primary mode, where you own the swap), `commandHooks`, and the painted-source trio `renderSource`, `onSourceEdit`, `completeBareSource` |
+| `StickyColumnDirection`                               | Which vertical direction the caret is entering your block from, handed to `focusAtColumn` so the column carries across lines                                                                                                                                                                                                                                |
 
 ### Code-block languages
 
-_(pre-freeze / unstable)_ The syntax-highlighting registry behind fenced code. The editor bootstraps a curated set — javascript, typescript, python, rust, go, bash, json, yaml, sql, html, css, java, c, cpp, ruby, markdown, diff, plus their aliases — because every grammar is static bundle weight for every consumer. A host needing more registers them itself.
+_(pre-freeze / unstable)_ The syntax-highlighting registry behind fenced code. The editor bootstraps a curated couple dozen (the usual suspects: javascript, python, rust, bash, sql, the C family, and friends) plus their aliases, because every grammar is static bundle weight for every consumer. `listLanguages()` tells you exactly which ones you have; a host needing more registers them itself.
 
-Register **before mounting an editor**: a block already on screen re-tokenizes only when its own bytes next change. An unregistered language is not an error — the fence still authors, commits and round-trips, and its body renders untokenized.
+Register **before mounting an editor**: a block already on screen re-tokenizes only when its own bytes next change. An unregistered language is not an error: the fence still authors, commits and round-trips, and its body renders untokenized. A language your plugin's `setup` registers highlights, and shows in the picker, only in the editors that list your plugin. `listLanguages`, `getLanguageAliases` and `highlightCode` have no editor to ask, so they answer for every installed plugin.
 
-| Export             | Role                                                                                                                                   |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `registerLanguage` | Add a grammar under a name, with optional aliases; idempotent, so a repeat call with the same name is a no-op                          |
-| `listLanguages`    | Every registered name and alias, sorted — what the code block's language picker offers                                                 |
-| `highlightCode`    | The code block's tokenizer: `(body, language)` to a text-preserving fragment of `code-tok-*` spans, for a plugin's own source surface  |
-| `LanguageGrammar`  | The registry's read shape: the resolved name and its definition                                                                        |
-| `LanguageFn`       | highlight.js's grammar-definition type, re-exported so you needn't import highlight.js directly (you hold it only as a transitive dep) |
+| Export                              | Role                                                                                                                                                                                                                                                             |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerLanguage`                  | Add a grammar under a name, with optional aliases; register-once, so a repeat call with the same name throws (a dev server replaces it)                                                                                                                          |
+| `listLanguages`                     | Every registered language once, under its canonical name, sorted: the rows a picker with every installed plugin offers                                                                                                                                           |
+| `getLanguageAliases`                | The other spellings a language answers to, asked by any of them: what a picker's filter matches on                                                                                                                                                               |
+| `highlightCode`                     | The code block's tokenizer: `(body, language)` to a text-preserving fragment of `code-tok-*` spans, for a plugin's own source surface                                                                                                                            |
+| `LanguageGrammar`                   | The registry's read shape: the resolved name and its definition                                                                                                                                                                                                  |
+| `LanguageFn`                        | highlight.js's grammar-definition type, re-exported so you needn't import highlight.js directly (you hold it only as a transitive dep)                                                                                                                           |
+| `sliceFencedSource`, `FencedSource` | A fenced source split into its opener line, body and closer line, each keeping its own ending; null when the first line opens no fence                                                                                                                           |
+| `renderFencedSource`                | The code block's own drawing of a fenced source: the fence lines as markers the marker-hiding modes collapse, and the body through the painter you pass (`highlightCode`, say). Text-preserving, and it keeps a line for the caret under an empty last body line |
+| `fenceBodyAsDrawn`                  | The body as `renderFencedSource` draws it: the line break before the closer belongs to the closer's line, unless the body is blank or nothing closes the fence                                                                                                   |
 
 ```ts
 import { registerLanguage } from '@voithos-labs/aragonite/plugin';
@@ -199,55 +209,55 @@ import elixir from 'highlight.js/lib/languages/elixir';
 registerLanguage('elixir', elixir, ['ex', 'exs']);
 ```
 
-Aliases are offered as their own rows in the picker, so a user typing `ex` finds it without knowing it resolves to `elixir`.
+The picker shows `elixir` once, and `ex` and `exs` are search keys for that row, so a user typing `ex` finds it without knowing the full name.
 
 ### Inline authoring
 
-_(pre-freeze / unstable)_ Syntax inside a paragraph: recognize it at a trigger character, render it as an **atomic widget** (one indivisible rendered thing the caret can sit beside but not inside), give it an editing policy. A **rung** is one level in the ordered ladder of recognizers a trigger consults. The render paths and the tier's limits: [Inline kinds](plugin-guide.md#inline-kinds).
-
-| Export                                                    | Role                                                                                                                                                                                                                                                                                       |
-| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `declarePluginInlineKind`                                 | Mint an inline kind, the one-level-down twin of `declarePluginKind`                                                                                                                                                                                                                        |
-| `declaredPluginInlineKind`                                | Recover a declared inline kind in another module                                                                                                                                                                                                                                           |
-| `isInlineKindDeclared`                                    | The is-it-there check for an inline kind                                                                                                                                                                                                                                                   |
-| `registerInlineSyntax`                                    | Hook the inline scanner on one trigger character with your recognizer; a reserved trigger (one a built-in owns, like `[`) takes a prefix rung                                                                                                                                              |
-| `INLINE_PRIORITIES`                                       | The inline ladder, lower consulted first: `prefixOverride` outranks a reserved trigger's built-in case, `plugin` is the bare-trigger default                                                                                                                                               |
-| `InlineSyntaxRecognizer`                                  | The recognizer contract: inspect the raw at the trigger, claim a span by returning a node, or decline with null                                                                                                                                                                            |
-| `InlineSyntaxOptions`                                     | The options bag: the multi-character `prefix`, the `priority`, `rewriteImage`, and `autoPair`                                                                                                                                                                                              |
-| `ImageSyntaxRewriter`, `ImageFields`                      | The `rewriteImage` contract, for a rung whose recognizer builds built-in image nodes and must write edits back in its own syntax, and the edited fields it receives                                                                                                                        |
-| `registerInlineWidgetKind`                                | Render an inline kind as a live atomic widget: a Svelte `component` (recommended) or a hand-built `buildWidget`, never both                                                                                                                                                                |
-| `mintWidgetShell`                                         | Mint the marked, source-stamped span a `buildWidget` returns; its attributes are what the caret's position walk reads                                                                                                                                                                      |
-| `PluginInlineKind`, `InlineNode`                          | The inline kind type, and the node your recognizer builds                                                                                                                                                                                                                                  |
-| `InlineWidgetDescriptor`                                  | The widget registration: the is-this-a-widget test, one render path, the editing policy                                                                                                                                                                                                    |
-| `InlineWidgetComponentProps`                              | A component widget's props: frozen `{ inline, source }`, plus live getters for the mode, the theme, the document, and the content version, and `navigateTo` to jump to another block, optionally at an offset in it (aim at a leaf: a container path scrolls into view but seats no caret) |
-| `InlineWidgetEditingPolicy`, `InlineWidgetEditingContext` | The policy (reveal source on caret entry, where the content sits inside the delimiters so a revealing click seats the caret there, delete granularity, edge behavior, a selected-key handler, whether the widget claims the activation click), and the context that handler receives       |
-| `isWidgetActivationClick`                                 | Whether a click activates a widget: a Ctrl/Cmd chord while editing, a plain click in reading mode                                                                                                                                                                                          |
+_(pre-freeze / unstable)_ Syntax inside a paragraph: recognize it at a trigger character, render it as an **atomic widget** (one indivisible rendered thing the caret can sit beside but not inside), give it an editing policy. Several recognizers can share one trigger character; the editor asks them in priority order, and a **prefix handler** is one that's only asked where its multi-character prefix matches. The render paths and the tier's limits: [Inline kinds](plugin-guide.md#inline-kinds).
+
+| Export                                                    | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `declarePluginInlineKind`                                 | Create an inline kind, the one-level-down twin of `declarePluginKind`                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `declaredPluginInlineKind`                                | Recover a declared inline kind in another module                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `isInlineKindDeclared`                                    | The is-it-there check for an inline kind                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `registerInlineSyntax`                                    | Hook the inline scanner on one trigger character with your recognizer; a reserved trigger (one a built-in owns, like `[`) takes only a prefix handler, priced below `INLINE_PRIORITIES.builtin`                                                                                                                                                                                                                                                                         |
+| `INLINE_PRIORITIES`                                       | The inline priority order, lower asked first: `prefixOverride` (40) outranks a reserved trigger's built-in case, `builtin` (50) is where that case sits and the ceiling a reserved-trigger prefix stays under, `plugin` (100) is the bare-trigger default                                                                                                                                                                                                               |
+| `InlineSyntaxRecognizer`                                  | The recognizer contract: inspect the raw at the trigger, claim a span by returning a node, or decline with null                                                                                                                                                                                                                                                                                                                                                         |
+| `InlineSyntaxOptions`                                     | The options bag: the multi-character `prefix`, the `priority`, `rewriteImage`, and `autoPair`                                                                                                                                                                                                                                                                                                                                                                           |
+| `ImageSyntaxRewriter`, `ImageFields`                      | The `rewriteImage` contract, for a registration whose recognizer builds built-in image nodes and must write edits back in its own syntax, and the edited fields it receives                                                                                                                                                                                                                                                                                             |
+| `registerInlineWidgetKind`                                | Render an inline kind as a live atomic widget: a Svelte `component` (recommended) or a hand-built `buildWidget`, never both                                                                                                                                                                                                                                                                                                                                             |
+| `mintWidgetShell`                                         | Build the marked span a `buildWidget` returns, with the attributes the caret's position walk reads to know which source bytes it stands for                                                                                                                                                                                                                                                                                                                             |
+| `PluginInlineKind`, `InlineNode`                          | The inline kind type, and the node your recognizer builds                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `InlineWidgetDescriptor`                                  | The widget registration: the is-this-a-widget test, one render path, the editing policy                                                                                                                                                                                                                                                                                                                                                                                 |
+| `InlineWidgetComponentProps`                              | A component widget's props: frozen `{ inline, source }`, plus live getters (all always passed, so there's no default to pick) for the mode, the theme, the document, and the content version, `navigateTo` to jump to another block, optionally at an offset in it (a container path with no offset lands at the start of its first line, and an offset into its bytes lands in the child holding that byte), and `computeInlineContent`, the editor's own inline parse |
+| `InlineWidgetEditingPolicy`, `InlineWidgetEditingContext` | The policy (reveal source on caret entry, where the content sits inside the delimiters, which offset a press on the rendered widget names via `revealOffsetAtPoint` so a click puts the caret where it landed, delete granularity, edge behavior, a selected-key handler, whether the widget claims the activation click), and the context that handler receives                                                                                                        |
+| `isWidgetActivationClick`                                 | Whether a click activates a widget: a Ctrl/Cmd chord while editing, a plain click in reading mode                                                                                                                                                                                                                                                                                                                                                                       |
 
 ### Commands and keybindings
 
 _(pre-freeze / unstable)_ Which tier dispatches what: [Block commands](plugin-guide.md#block-commands).
 
-| Export                                       | Role                                                                                                                                                                                                       |
-| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `registerBlockCommand`                       | Mint a `(kind, name)` command and get back its id, for a keymap binding to target                                                                                                                          |
-| `registerBlockContextActions`                | Add the actions a right-click on a block of `kind` offers (its context menu), ahead of the editor's own copy, replace and remove rows                                                                      |
-| `BlockContextAction`                         | One such action: id, label, optional glyph and danger flag, and `run(ctx)`                                                                                                                                 |
-| `BlockActionContext`                         | What `run` receives: the node, its path, `deleteBlock()` and `replaceRaw(raw)`                                                                                                                             |
-| `BlockContextActionProvider`                 | The registered function: `(node, path) => BlockContextAction[]`, consulted on every open                                                                                                                   |
-| `registerGlobalCommand`                      | Mint a process-wide command run against whichever editor dispatched it, optionally on a global chord; also returns its id                                                                                  |
-| `CommandId`                                  | A built-in command's id; a vocabulary your keymaps may bind too                                                                                                                                            |
-| `KeyBinding`                                 | One keymap entry: a chord (fixed-order `Mod` / `Alt` / `Shift` plus the key), a command id, an optional baked argument                                                                                     |
-| `BlockCommandContext`, `BlockCommandHandler` | What a block command's handler receives (the focused node, read-only; the argument; `updateMetadata`, the way to commit a metadata change; the mounted component's own hooks), and the handler's signature |
-| `PluginCommandId`, `AnyCommandId`            | A minted command's id, and the union spanning built-in and minted                                                                                                                                          |
+| Export                                       | Role                                                                                                                                                                                                                                                                                                                                                                             |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerBlockCommand`                       | Create a `(kind, name)` command and get back its id, for a keymap binding to target                                                                                                                                                                                                                                                                                              |
+| `registerBlockContextActions`                | Add, under a name unique to `kind`, the actions a right-click on a block of `kind` offers (its context menu), ahead of the editor's own copy, replace and remove rows; listed only in the editors that activate your plugin                                                                                                                                                      |
+| `BlockContextAction`                         | One such action: id, label, optional glyph and danger flag, and `run(ctx)`                                                                                                                                                                                                                                                                                                       |
+| `BlockActionContext`                         | What `run` receives: the node, its path, `deleteBlock()` and `replaceRaw(raw)` (one undo entry each, and `replaceRaw`'s bytes go through your kind's write rule, every line break in the document's ending), `transformPaste(text)` (the paste transforms of the plugins that editor lists), and `lineEnding`, the document's, for a line you rebuild from the block's own bytes |
+| `BlockContextActionProvider`                 | The registered function: `(node, path, noun) => BlockContextAction[]`, consulted on every open; `noun` is what the menu calls the block                                                                                                                                                                                                                                          |
+| `registerGlobalCommand`                      | Create a process-wide command run against whichever editor dispatched it, optionally on a global chord; also returns its id. The handler receives that editor's `EditorContext` and the argument `runCommand(id, arg)` or the chord's binding carried                                                                                                                            |
+| `CommandId`                                  | A built-in command's id; a vocabulary your keymaps may bind too                                                                                                                                                                                                                                                                                                                  |
+| `KeyBinding`                                 | One keymap entry: a chord (`Mod` / `Alt` / `Shift` plus the key, normalized to that order), a command id, an optional baked argument. A chord with an unknown modifier or no key throws when the kind registers or is augmented                                                                                                                                                  |
+| `BlockCommandContext`, `BlockCommandHandler` | What a block command's handler receives (the focused node, read-only; the argument; `updateMetadata`, the way to commit a metadata change; the mounted component's own hooks; `editor`, the dispatching editor's `EditorContext`), and the handler's signature                                                                                                                   |
+| `PluginCommandId`, `AnyCommandId`            | The id `registerBlockCommand` or `registerGlobalCommand` hands back, and the union of that and a built-in `CommandId`                                                                                                                                                                                                                                                            |
 
 ### Paste transforms
 
 _(pre-freeze / unstable)_ The recipe: [Paste transforms](plugin-guide.md#paste-transforms).
 
-| Export                   | Role                                                                                                                                                                  |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `registerPasteTransform` | Register a pre-parse rewrite of pasted text; transforms run at every paste site, in install order, each seeing the previous one's output, and never on load or typing |
-| `PasteTransform`         | The unit: a process-unique `name`, plus `transform(text)` returning the replacement or null for "not mine"                                                            |
+| Export                   | Role                                                                                                                                                                                                             |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerPasteTransform` | Register a pre-parse rewrite of pasted text; transforms run at every paste site, in install order, each seeing the previous one's output (the first gets CRLF already turned to LF), and never on load or typing |
+| `PasteTransform`         | The unit: a process-unique `name`, plus `transform(text)` returning the replacement or null for "not mine"                                                                                                       |
 
 ### Decorations
 
@@ -263,6 +273,30 @@ _(pre-freeze / unstable)_ View-only annotations drawn over the rendered document
 | `MarkDecoration`, `WidgetDecoration`, `ReplaceDecoration`, `BlockDecoration` | The four: a styled span over an inline range, a zero-width widget at an offset, a widget covering a range whose bytes stay in the document, and a whole-block treatment with an optional badge |
 | `DecorationWidgetSpec`                                                       | How a decoration's widget renders: a Svelte `component`, or a hand-built `buildDom`                                                                                                            |
 
+### Inline menus
+
+_(pre-freeze / unstable)_ A list the editor opens under the caret while the author types after a trigger: `#` for a tag, `[[` for a link to another document. You register a source per editor through `editor.inlineMenus` (your `onEditor` context); a host that owns the data reaches the same registry as `getInlineMenus()`. The editor owns the session: it notices the typed trigger, holds the arrow keys, Enter, Tab and Escape while a list is up, anchors the list to the typed range, and writes the pick over the trigger and the query as one undo entry. The caret never leaves the document. The recipe: [Recipe: a typed-trigger menu](consumer-guide.md#recipe-a-typed-trigger-menu).
+
+| Export                   | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `InlineMenuRegistry`     | The `editor.inlineMenus` surface: `addSource` registers a source and returns its handle, `open(name, { query })` types a source's trigger, then the query if given, at the caret as one undo entry and opens its list over it (what a shortcut or a toolbar button calls; `false`, writing nothing, for an unknown name, in reading mode, with no caret in prose, or a query holding a line break), `close()` dismisses, and `isOpen` is true while a list is on screen                                                                               |
+| `InlineMenuSource`       | A named source: its `trigger` (one line, never empty), an `items(query)` that returns the list or a promise of it, and optionally `opensAt` (decline a trigger by position), `accepts` (end the session on a query that is no longer yours), `onCommit` (after the bytes land, with the range the pick replaced, so the caret is at `start + insert.length`; if it returns a promise, every write that lands while it is pending, up to the author's next input, is part of the pick's undo entry), and a `row` component that paints a row's content |
+| `InlineMenuOpenOptions`  | `open`'s second argument: a `query` typed after the trigger, so the list opens already narrowed                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `InlineMenuSourceHandle` | The handle back: `dispose()` removes the source and closes its list                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `InlineMenuItem`         | One row: an `id` unique within the list, a `label`, an optional dim `detail`, an optional `icon` (a menu glyph name the default row draws), and `insert`, the bytes that replace the trigger and the query. Where two rows share an id the first is kept and the rest are dropped and reported on the `error` event. One line of inline bytes, empty allowed; a line break is refused and reported, and a block belongs in `onCommit`                                                                                                                 |
+| `InlineMenuQuery`        | What `items` is asked: the `query` typed so far, the leaf's `path`, the raw range `[start, end)` a pick would replace, and a `signal` aborted once a later keystroke supersedes the read                                                                                                                                                                                                                                                                                                                                                              |
+| `InlineMenuRowProps`     | What a `row` component receives: the `item`, whether it is `active`, and the `query` (for highlighting the match)                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+
+### Insert catalogue
+
+_(pre-freeze / unstable)_ The blocks the insert menus offer: the built-in lists, quote, divider, code block and table, then the blocks plugins add. Read it through `editor.insertCatalogue` (your `onEditor` context); a host reads the same list as `getInsertCatalogue()`.
+
+| Export                | Role                                                                                                                                                                               |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerInsertEntry` | Add your block to every insert menu, called from `setup`. It is listed only in the editors that activate your plugin. Throws on a duplicate id and on an icon the menu cannot draw |
+| `InsertEntry`         | One entry: an `id`, a `label`, an `icon`, `keywords` a filter should also match, its `markdown`, and an optional `withArgument` giving the Markdown and dim text for `/table 3x4`  |
+| `MenuIconName`        | The glyph names a menu row can draw                                                                                                                                                |
+
 ### Events
 
 _(pre-freeze / unstable)_ The payloads `EditorContext.events` delivers to an `on(name, handler)` subscription. The channel itself: [The plugin unit](plugin-guide.md#the-plugin-unit).
@@ -273,85 +307,135 @@ _(pre-freeze / unstable)_ The payloads `EditorContext.events` delivers to an `on
 | `EditEvent`                           | The `edit` payload: `op`, the `path` it landed at, a per-op `detail`, and a `timestamp`. `op` and `detail` are correlated, so narrowing `op` narrows `detail` with it |
 | `OperationKind`                       | The structural-operation vocabulary `EditEvent.op` draws from                                                                                                         |
 | `SelectionChangeEvent`, `EditorError` | The other two payloads worth naming: the anchor/focus pair (or null), and a contained failure with its `origin` and context                                           |
+| `SourceSwapEvent`                     | The `sourceSwap` payload: the `generation` a `source` write replaced the document at                                                                                  |
 
 ### Rects
 
 _(pre-freeze / unstable)_ Where things are on screen, reached through `editor.rects` (your `onEditor` context) or the `rects` prop every block component receives.
 
-| Export        | Role                                                                                                                                                                                                                                                                                                                                                   |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `EditorRects` | The geometry surface: a block's box, an inline range's rects (one per visual line), the native caret, a `reveal` that mounts a block the editor had skipped (it only mounts blocks in view), a `scrollTo` that mounts then brings a block into view, and a `navigateTo` that also lands the caret there, at the block's start or at an offset you name |
+| Export        | Role                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EditorRects` | The geometry surface: a block's box, an inline range's rects (one per visual line, or one per cell in a table), the native caret, a `reveal` that mounts a block the editor had skipped (it only mounts blocks in view), a `scrollTo` that mounts then brings a block into view, and a `navigateTo` that also lands the caret there, at the block's start or at an offset you name |
 
 ### Caret geometry
 
 _(pre-freeze / unstable)_ What a kind fills its descriptor's `caretTargetAtPoint` with. The rendered view and the source are different strings, so only your kind knows how a press on one lines up with the other; these three are the pieces that don't depend on your grammar. The worked example is the quickstart's parrot: [The first fifteen minutes](plugin-guide.md#the-first-fifteen-minutes).
 
-| Export                    | Role                                                                                                                                                                                                                      |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `caretOffsetAtPoint`      | The character offset in one of your own elements nearest a viewport point; the point clamps into that element's box first, so a press on your chrome still names one, and null means the element holds no position at all |
-| `CaretTarget`             | What the hook answers: the child path to the leaf (empty when your block is the leaf) and the offset inside it                                                                                                            |
-| `CURSOR_END`, `CursorEnd` | The offset meaning "wherever that leaf ends", and its type; a plain `0` is the other end, since that one is a real offset                                                                                                 |
+| Export                    | Role                                                                                                                                                                                                                                                                                                          |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `caretOffsetAtPoint`      | The character offset in one of your own elements nearest a viewport point; the point clamps into that element's box first, so a press on your chrome still names one, and a press in its top or bottom padding takes the column under it on the nearest line; null means the element holds no position at all |
+| `CaretTarget`             | What the hook answers: the child path to the leaf (empty when your block is the leaf) and the offset inside it                                                                                                                                                                                                |
+| `CURSOR_END`, `CursorEnd` | The offset meaning "wherever that leaf ends", and its type; a plain `0` is the other end, since that one is a real offset                                                                                                                                                                                     |
+
+### Pointer gestures
+
+_(pre-freeze / unstable)_ One attribute, for a block whose drags are its own (a diagram you pan, a canvas you draw on). Without it the editor reads the press as the start of a selection, and your pan runs under a painted block range. Calling `stopPropagation()` in your own handler doesn't help: Svelte delivers pointer events from the app root, so the editor's listener has already run.
+
+| Export                 | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `POINTER_GESTURE_ATTR` | Put it on the element whose drags are yours. A press inside it is left alone by drag-to-select, and by the double and triple click too, as long as the element sits outside any `contenteditable` (an inline widget inside your own editable text follows the inline widget's rule instead, where a third click selects the block unless the editor already holds that widget selected whole). The editor reads it at press time, so declare it always or only while your gesture is armed |
+
+```svelte
+<div class="viewport" {...{ [POINTER_GESTURE_ATTR]: focused ? '' : undefined }} onpointerdown={beginPan}>
+```
+
+That is what mermaid does: unfocused, a drag on the diagram selects like it would on any block; focused, it pans.
 
 ### Selection geometry
 
 _(pre-freeze / unstable)_ The selection shapes a decoration source or geometry consumer reads.
 
-| Export                              | Role                                                                                                                                                                                                                                                                                                                                |
-| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `EditorSelection`, `SelectionPoint` | The `selectionChange` payload, an anchor/focus pair, and one endpoint of it: a `{ path, offset }`. Inside a table `offset` counts cells rather than characters, and `cellCoordinate` doesn't reliably say so, so check the block's kind the way [the consumer guide](consumer-guide.md#reading-the-document-and-the-selection) does |
-| `SELECTION_END`, `SelectionEnd`     | The importable "through the end of this block's measurable content" value `rangeRects` accepts as `end`, and its type                                                                                                                                                                                                               |
+| Export                              | Role                                                                                                                                                                                                                                                                                                                |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EditorSelection`, `SelectionPoint` | The `selectionChange` payload, an anchor/focus pair, and one endpoint of it: a `{ path, offset }`. Inside a table `offset` counts cells rather than characters, and `cellCoordinate: true` says so on every such point; [the consumer guide](consumer-guide.md#reading-the-document-and-the-selection) has the rest |
+| `SELECTION_END`, `SelectionEnd`     | The importable "through the end of this block's measurable content" value `rangeRects` accepts as `end`, and its type                                                                                                                                                                                               |
 
 ### Parse and serialize
 
 _(pre-freeze / unstable)_ The editor's own parse and serialize entries, re-exported here so an opener or a transform never digs into the package's internals.
 
-| Export                                    | Role                                                                                                                                                                                               |
-| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `parse`                                   | Parse a body of Markdown into a document you can lift children from                                                                                                                                |
-| `ParseScope`                              | What a parse entry is told about its input: a whole document, or one block's bytes (`'fragment'`)                                                                                                  |
-| `parseContainerBody`, `ContainerBodyWrap` | Parse a body that sits between your container's own fence lines, keeping the separating blank lines out of the children; the wrap says which fence lines exist, and matches your kind's `bodyWrap` |
-| `serialize`                               | A whole document back to its exact source bytes                                                                                                                                                    |
-| `serializeChildren`                       | Child nodes joined back into their exact source bytes                                                                                                                                              |
-| `Document`                                | The parsed-document shape both parse entries return                                                                                                                                                |
-| `splitLines`                              | Split source into the parsed lines every line-scoped helper here consumes                                                                                                                          |
-| `ParsedLine`                              | One source line: its text, its bytes with the ending, the ending itself, its offsets                                                                                                               |
-| `isBlankLine`                             | The GFM blank-line test, spaces and tabs only. Don't substitute `trim()`: it would let a pasted non-breaking space split a block                                                                   |
-| `trimTrailingLineEnding`                  | Cut the one trailing line ending (LF or CRLF) off a block's bytes, giving the text you display                                                                                                     |
-| `normalizeLineEndings`                    | CRLF to LF, for text arriving from outside the document (a plugin-owned input surface)                                                                                                             |
+| Export                                    | Role                                                                                                                                                                                                                                                                                                                                                                                   |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `parse`                                   | Parse a body of Markdown into a document you can lift children from                                                                                                                                                                                                                                                                                                                    |
+| `ParseScope`                              | What a parse entry is told about its input: a whole document, or one block's bytes (`'fragment'`)                                                                                                                                                                                                                                                                                      |
+| `parseContainerBody`, `ContainerBodyWrap` | Parse a body that sits between your container's own fence lines, keeping the separating blank lines out of the children; the wrap says which fence lines exist, and matches your kind's `bodyWrap`. The options take a `scope` and the grammar, both required (pass the grammar your opener was given, so the body reads with the syntaxes the editor has on), and an optional `depth` |
+| `serialize`                               | A whole document back to its exact source bytes                                                                                                                                                                                                                                                                                                                                        |
+| `serializeChildren`                       | Child nodes joined back into their exact source bytes                                                                                                                                                                                                                                                                                                                                  |
+| `Document`                                | The parsed-document shape both parse entries return                                                                                                                                                                                                                                                                                                                                    |
+| `splitLines`                              | Split source into the parsed lines every line-scoped helper here consumes                                                                                                                                                                                                                                                                                                              |
+| `ParsedLine`                              | One source line: its text, its bytes with the ending, the ending itself, its offsets                                                                                                                                                                                                                                                                                                   |
+| `isBlankLine`                             | The GFM blank-line test, spaces and tabs only. Don't substitute `trim()`: it would let a pasted non-breaking space split a block                                                                                                                                                                                                                                                       |
+| `isBlankText`                             | The same test over a whole block's text, line breaks allowed. Use it for "is this block empty?", since `trim()` also throws away a non-breaking space, and that's a character someone typed                                                                                                                                                                                            |
+| `isWhitespaceChar`                        | Whether one character is Markdown whitespace: a space, a tab, or a line-break character (GFM also counts vertical tab and form feed). A non-breaking space isn't, so ask this where your grammar would've reached for `/\s/`                                                                                                                                                           |
+| `trimWhitespace`                          | `trim()`, but Markdown's: the characters `isWhitespaceChar` accepts come off both ends, and a non-breaking space stays. Use it on an info string or a caption before you show it                                                                                                                                                                                                       |
+| `trimTrailingLineEnding`                  | Cut the one trailing line ending (LF or CRLF) off a block's bytes, giving the text you display                                                                                                                                                                                                                                                                                         |
+| `ownTrailingLineEnding`                   | The ending a block's bytes close with (`''` when they have none): what you put back after editing the display                                                                                                                                                                                                                                                                          |
+| `trailingLineEnding`                      | The ending a line rebuilt from a block's bytes takes: the block's own, else the fallback you pass (a write rule's or a context action's `ctx.lineEnding`, or `documentLineEnding` of a document you hold)                                                                                                                                                                              |
+| `firstLineEnding`                         | The first line break in some bytes, or `null`. In a document with one ending (nearly all of them), any break in your block's bytes is the document's                                                                                                                                                                                                                                   |
+| `documentLineEnding`                      | The ending every line written into a document takes: its first line break, else LF                                                                                                                                                                                                                                                                                                     |
+| `LineEnding`                              | `'\n'` or `'\r\n'`                                                                                                                                                                                                                                                                                                                                                                     |
+| `displayLines`                            | A block's display as lines, each line's text apart from its ending, so a `\r` never reaches a line match                                                                                                                                                                                                                                                                               |
+| `joinDisplayLines`                        | Lines from `displayLines` back into their exact bytes                                                                                                                                                                                                                                                                                                                                  |
+| `normalizeLineEndings`                    | CRLF to LF, for text arriving from outside the document (a plugin-owned input surface)                                                                                                                                                                                                                                                                                                 |
 
 ### Grammar scanners
 
 _(pre-freeze / unstable)_ The built-in rules for three grammars a plugin commonly claims, exported so you reuse them instead of forking the spec (the spec is longer than it looks, every time, trust me).
 
-| Export                    | Role                                                                                                                                                                                                        |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `matchFenceOpen`          | Recognize a CommonMark code-fence opener line, keeping the verbatim indent and info bytes a byte-exact rebuild needs                                                                                        |
-| `matchFenceClose`         | Is this line the closer for a matched opener (same marker, at least its run length)?                                                                                                                        |
-| `escalatedFenceLength`    | The fence run a body forces so none of its lines reads as the closer; a floor, never a shortening. A kind that rebuilds its own raw around a body owes this, and grows the closer to match                  |
-| `FenceOpen`               | A matched opener: marker, run length, trimmed `info`, verbatim `indent` and `infoRaw`                                                                                                                       |
-| `htmlBlockTagLineMatcher` | Build a recognizer answering `'open'`, `'close'`, or null for one tag name's HTML block line, in every spelling the spec passes through (indented, upper-cased, trailing space), not just the canonical one |
-| `blockquoteExtent`        | Scan a blockquote's full extent (CommonMark lazy continuation) from a start line: its exact bytes plus the index past it (a slice bound, not a consumed count), no child decomposition                      |
+| Export                                           | Role                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `matchFenceOpen`                                 | Recognize a CommonMark code-fence opener line, keeping the verbatim indent and info bytes a byte-exact rebuild needs                                                                                                                                                                                     |
+| `matchFenceClose`                                | Is this line the closer for a matched opener (same marker, at least its run length)?                                                                                                                                                                                                                     |
+| `escalatedFenceLength`                           | The fence run a body forces so none of its lines reads as the closer; a floor, never a shortening. A kind that rebuilds its own raw around a body has to apply it, and grow the closer to match                                                                                                          |
+| `FenceOpen`                                      | A matched opener: marker, run length, trimmed `info`, verbatim `indent` and `infoRaw`                                                                                                                                                                                                                    |
+| `matchFenceInfo`                                 | Build an opener matcher that claims only fences whose info string's first word is your token: `matchFenceInfo('mermaid')` is how the bundled diagram kind takes ` ```mermaid ` from the code block                                                                                                       |
+| `findFenceCloser`, `FenceRun`                    | The index of the first line in a range that closes a fence of that marker and run length (the closer the parser would pick), or -1                                                                                                                                                                       |
+| `scanFence`, `FenceScan`                         | A fence's extent from its opener line, as an opener's `tryOpen` needs it: the closer's index (-1 when nothing closes it), the lines consumed, the exact bytes, and the body between the fence lines                                                                                                      |
+| `fenceAnatomy`, `FenceAnatomy`                   | Where a fenced block's parts sit in its bytes: the opener's indent, marker run and info string, the body, and the closer line; null when the first line opens no fence                                                                                                                                   |
+| `fenceRawWrite`, `fenceShapeOfRaw`, `FenceShape` | The code block's write rule for any kind that holds its own fence: declare `rawWrite: fenceRawWrite(fenceShapeOfRaw)` and a write from outside your block (a find/replace, a range delete, a paste) keeps one opener and one closer, growing both runs past a body line that would close the block early |
+| `htmlBlockTagLineMatcher`                        | Build a recognizer answering `'open'`, `'close'`, or null for one tag name's HTML block line, in every spelling the spec passes through (indented, upper-cased, trailing space), not just the canonical one                                                                                              |
+| `blockquoteExtent`                               | Scan a blockquote's full extent (CommonMark lazy continuation) from a start line: its exact bytes plus the index past it (a slice bound, not a consumed count), no child decomposition. Its optional grammar argument defaults to every installed plugin's                                               |
 
 ### Node access and metadata
 
 _(pre-freeze / unstable, beyond the stable metadata pair `setPluginMetadata` / `getPluginMetadata`)_ The document tree from a plugin's side of the glass: what you read arrives read-only, and what you build yourself stays writable ([Views](plugin-guide.md#views-what-you-read-what-you-own)).
 
-| Export                                   | Role                                                                                                                                                     |
-| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `CstNode`                                | The writable tree-node shape you construct: what a factory builds and a `rebuildRaw` mutates                                                             |
-| `NodeView`, `DocumentView`               | The read-only views every read surface hands you. Writing bytes through one is a compile error                                                           |
-| `setPluginMetadata`, `getPluginMetadata` | Store and read your kind's own typed per-node data, no casting; keep the stored shape primitive-valued                                                   |
-| `getContentRange`, `ContentRange`        | The content span inside a block's raw, syntax markers excluded (a heading's `#`, a setext underline)                                                     |
-| `headingLevel`                           | A heading's level, ATX or setext, null for anything else: the outline read a table-of-contents plugin wants                                              |
-| `computeInlineContent`                   | Inline-parse a prose leaf, uncached and safe inside a reactive read; reference-style links come back unresolved, since no link resolver reaches a plugin |
-| `isProseKind`                            | Does this kind host inline content? The gate that keeps a code block's bytes out of an inline walk                                                       |
+| Export                                   | Role                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CstNode`                                | The writable tree-node shape you construct: what a factory builds and a `rebuildRaw` mutates                                                                                                                                                                                                 |
+| `NodeView`, `DocumentView`               | The read-only views every read surface hands you. Writing bytes through one is a compile error                                                                                                                                                                                               |
+| `setPluginMetadata`, `getPluginMetadata` | Store and read your kind's own typed per-node data, no casting; keep the stored shape primitive-valued                                                                                                                                                                                       |
+| `getContentRange`, `ContentRange`        | The content span inside a block's raw, syntax markers excluded (a heading's `#`s at either end, a setext underline)                                                                                                                                                                          |
+| `headingLevel`                           | A heading's level, ATX or setext, null for anything else: the outline read a table-of-contents plugin wants                                                                                                                                                                                  |
+| `computeInlineContent`                   | Inline-parse a prose leaf with every installed plugin's syntax, for a pipeline with no editor mounted; inside an editor use `editor.computeInlineContent`, which reads only what that editor lists. Uncached; with no document to define them, reference-style links come back as plain text |
+| `isProseKind`                            | Does this kind host inline content? The gate that keeps a code block's bytes out of an inline walk                                                                                                                                                                                           |
+| `walkBlocks`                             | Visit every block under a document or a block, parents first, each with its path (yours to keep). Return `'skip'` to leave a block's children out, `'stop'` to quit (it returns true). Walking a subtree? Pass its path third to get document paths                                          |
+| `blockNodeAt`                            | The block at a path, or null when there's none. The empty path is the document itself, which isn't a block, so that's null too                                                                                                                                                               |
+
+### Injected renderers
+
+_(pre-freeze / unstable)_ For a block or widget drawn by a library the host hands your plugin (KaTeX, mermaid). A **renderer slot** is the one place that library plugs in: your plugin's setup calls `set`, your component calls `render`, and the slot handles the caching and the fallbacks. The [render-primary recipe](plugin-guide.md#recipe-a-render-primary-block) walks through one.
+
+| Export                              | Role                                                                                                                                                                                                                                                                                                                                                         |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `createRendererSlot`                | A slot for a renderer that answers right away. Each render is cached under the editor's theme plus your `key(input)`, so a theme switch misses the cache and switching back is a hit. With no renderer set you get `missing(input)`; when it throws, `failed(input, error)`, cached like a success. Pass `cloneOnRead` when the output holds a live DOM node |
+| `createAsyncRendererSlot`           | The same for a renderer that returns a promise. The promise is what's cached, so two blocks asking for one diagram share a single call, and a rejection resolves through `failed`                                                                                                                                                                            |
+| `RendererSlot`, `AsyncRendererSlot` | What the two hand back: `set(renderer)` (`null` removes it, and either way the cache empties), `configured`, and `render(input, ctx)`. `resetPluginPlatformForTests` removes the renderer too                                                                                                                                                                |
+| `RendererSlotSpec`                  | What you pass either one: `key`, `missing`, `failed`, and an optional `cap` (256 renders by default)                                                                                                                                                                                                                                                         |
+| `SyncRendererSlotSpec`              | `createRendererSlot`'s spec: a `RendererSlotSpec` plus an optional `cloneOnRead(value)`, which hands each caller its own copy of a cached value. The async slot caches a promise, so it has no use for one                                                                                                                                                   |
+| `RenderContext`                     | `{ theme }`, the second argument to every `render` and to your renderer. It's required, so nothing gets drawn or cached without a theme. Read the theme with `getTheme()` inside your render effect, since that read is what redraws the block on a switch                                                                                                   |
+| `renderSourceFallback`              | `renderSourceFallback(source, message)` builds the typed source in the code font, with `message` on hover: a decent `missing` or `failed` output for anything drawn from source text. It's neutral, so add your own error color where a failure should look like one (math does)                                                                             |
 
 ### Performance helpers
 
-_(pre-freeze / unstable)_ Two small tools the renderer recipe and the inline recognizers lean on.
+_(pre-freeze / unstable)_ Two small tools: the cache under the renderer slot, and a scan index the inline recognizers lean on.
 
 | Export               | Role                                                                                                                                                                                                           |
 | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `createBoundedMemo`  | A bounded, least-recently-used memo for per-source work. Async work stores the promise (in-flight renders shared, failures cached like successes); `cloneOnRead` covers a cached value holding a live DOM node |
 | `BoundedMemoOptions` | The memo's options: the entry `cap`, the optional `cloneOnRead`                                                                                                                                                |
 | `createScanIndex`    | Turn a per-block position collector into a "first candidate at or after this offset" lookup (-1 when none), so a recognizer's decline costs one block scan instead of one per trigger                          |
+
+---
+
+Working on aragonite itself and adding an export? Give it a row in its group, tagged the way its entry-module section is tagged. A test (`src/lib/test/plugins/plugin-guide-coverage.test.ts`) diffs this page against the entry module and fails naming any export without a row. It finds the catalog by the exact `## API reference` heading, so if you rename the heading, rename it there too.