@voithos-labs/aragonite 0.10.2 → 0.10.4

package/docs/guide/plugin-api.md

@@ -26,6 +26,7 @@ The groups, in page order:
 | [Kind declaration](#kind-declaration)                   | Minting 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                   |
@@ -39,6 +40,7 @@ The groups, in page order:
 | [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 |
@@ -118,7 +120,7 @@ _(pre-freeze / unstable)_ The recipe: [Typing a multi-line construct into existe
 | 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                                                           |
+| `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 |
 
 ### Registration probes
@@ -152,17 +154,17 @@ _(pre-freeze / unstable)_ The `:::name` grammar itself is the [directives guide]
 
 _(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 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                                                                                                                              |
 
 ### Editable-leaf authoring
 
@@ -177,27 +179,51 @@ _(pre-freeze / unstable)_ The container factory's sibling for leaves; the full s
 | `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                           |
 
+### Code-block languages
+
+_(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.
+
+| 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 language once, under its canonical name, sorted: the rows the code block's language picker 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) |
+
+```ts
+import { registerLanguage } from '@voithos-labs/aragonite/plugin';
+import elixir from 'highlight.js/lib/languages/elixir';
+
+registerLanguage('elixir', elixir, ['ex', 'exs']);
+```
+
+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`, and `rewriteImage`                                                                                                                                                                                                          |
-| `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, 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                                                                                                                                                                                          |
+| 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, which offset a press on the rendered widget names via `revealOffsetAtPoint` so a click seats 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
 
@@ -206,6 +232,10 @@ _(pre-freeze / unstable)_ Which tier dispatches what: [Block commands](plugin-gu
 | 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                                                                                     |
@@ -264,6 +294,20 @@ _(pre-freeze / unstable)_ What a kind fills its descriptor's `caretTargetAtPoint
 | `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 island inside your own editable text is the inline widget's door instead). 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.

package/docs/guide/plugin-guide.md

@@ -260,7 +260,9 @@ cNo.....................................oc
 		font-size: 1.1em;
 		line-height: 1.1;
 		letter-spacing: 0.05em;
-		/* one frame tall, in the reel's own rows so a step lands on the next frame exactly */
+		/* one frame tall, in the reel's own rows so a step lands on the next frame exactly; the
+		   em line is the same height for engines without lh (Safari before 16.4) */
+		height: calc(var(--parrot-rows) * 1.1em);
 		height: calc(var(--parrot-rows) * 1lh);
 		/* wider than a phone column, and the editor root pans if it isn't contained; the bar
 		   would sit across the bird, which is decoration rather than a pane to scroll */
@@ -878,20 +880,25 @@ Three rules for that file, each earned the hard way:
 
 The factory returns more than the walkthrough destructures:
 
-| Return                | When you reach for it                                                                                                                                                                                                                                                               |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `updateOwnMetadata`   | Your component writes its own node's metadata (a collapse toggle, an edited setting). The sanctioned commit path; in reading mode, which writes no bytes, it declines as a no-op and dev builds warn                                                                                |
-| `moveFocusOut`        | A plugin-owned editing surface whose caret ran off its own edge; hands the caret to the neighbour a plain arrow points at, through the editor's focus traversal, so the landing skips non-focusable blocks, enters containers, and reveals an unmounted target like any other arrow |
-| `getPresentationMode` | Your rendering or a gesture needs the live presentation mode ([Presentation modes](#presentation-modes))                                                                                                                                                                            |
-| `getTheme`            | Your content's colors are painted by an engine rather than styled by CSS; token-styled chrome needs neither this nor `getPresentationMode`, it rethemes through the cascade                                                                                                         |
-| `getOptions`          | This editor instance's options for the plugin owning your kind, typed `unknown`; the per-instance channel a factory argument can't reach ([the options recipe](#recipe-per-instance-options-and-the-factory-closure-trap))                                                          |
+| Return                  | When you reach for it                                                                                                                                                                                                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `updateOwnMetadata`     | Your component writes its own node's metadata (a collapse toggle, an edited setting). The sanctioned commit path; in reading mode, which writes no bytes, it declines as a no-op and dev builds warn                                                                                                                |
+| `moveFocusOut`          | A plugin-owned editing surface whose caret ran off its own edge; hands the caret to the neighbour a plain arrow points at, through the editor's focus traversal, so the landing skips non-focusable blocks, enters containers, and reveals an unmounted target like any other arrow                                 |
+| `getPresentationMode`   | Your rendering or a gesture needs the live presentation mode ([Presentation modes](#presentation-modes))                                                                                                                                                                                                            |
+| `getTheme`              | Your content's colors are painted by an engine rather than styled by CSS; token-styled chrome needs neither this nor `getPresentationMode`, it rethemes through the cascade                                                                                                                                         |
+| `getOptions`            | This editor instance's options for the plugin owning your kind, typed `unknown`; the per-instance channel a factory argument can't reach ([the options recipe](#recipe-per-instance-options-and-the-factory-closure-trap))                                                                                          |
+| `captureScrollPosition` | Your component is about to swap its view for one of a different height (a tall diagram for its short source card) and the reader is scrolled right at it. Call it before the swap, await what it hands back after, and the page stays where the reader left it instead of clamping to the shorter layout in between |
 
 ```ts
-const { updateOwnMetadata, getPresentationMode, getTheme, getOptions } = createContainerBlock(deps);
+const { updateOwnMetadata, getPresentationMode, getTheme, getOptions, captureScrollPosition } =
+	createContainerBlock(deps);
 updateOwnMetadata({ name: 'debunked' }); // one undo entry; rebuildRaw re-emits the opener line as :::debunked
 getPresentationMode(); // 'source'
 getTheme(); // 'dark'
 getOptions(); // whatever this editor's { plugin, options } entry carried; undefined for a bare unit
+const restore = captureScrollPosition(); // before the swap...
+editing = true;
+await restore(); // ...and after; a no-op when nothing moved
 ```
 
 One dep is worth knowing about too. A marker-bearing container (a footnote definition's `[^label]: `, mirroring a list item's `- `) hands the factory a **`getAmbientPrefix`** getter. Its first child then paints that prefix as a dimmed, read-only run before its own bytes, and the caret and offset walk skip it exactly as they do a list marker. Read it live, so a marker derived from metadata re-renders after an edit. Return a string, or `{ text, interactive }` to make ranges of it clickable: each range gets its own span, class and click handler, which is how a task list's checkbox toggles and how a footnote definition's `[^label]` takes the click back to its reference.
@@ -1161,9 +1168,11 @@ leaf.getOptions(); // this editor's options for your plugin, typed unknown
 
 **Native parity is the tier's whole claim**: the editor's caret enters and leaves your block like any built-in text block (including keeping its column as it walks up or down lines), IME composition is respected, undo batches like prose, the clipboard is intercepted for plain-Markdown copy/cut/paste like every editable surface, and a cross-block selection sweeps through your text.
 
-**One spread wires the source surface.** Write `<div {...leaf.surfaceProps}>` on your source contenteditable and the nine DOM handlers, the `contenteditable` / `role` / `tabindex` / `spellcheck` attributes, and two view-lifecycle contracts all land at once, so a forgotten handler (a dropped `oncompositionend` that silently breaks IME) simply can't happen to you. The two contracts the spread owns are the ones every consumer used to hand-write: the source is populated as a **single text node** (so `textContent === source` and the walk that maps DOM positions to byte offsets stays exact), and focus is parked on the editor root when the source unmounts.
+**One spread wires the source surface.** Write `<div {...leaf.surfaceProps}>` on your source contenteditable and the DOM handlers, the `contenteditable` / `role` / `tabindex` / `spellcheck` attributes, and two view-lifecycle contracts all land at once, so a forgotten handler (a dropped `oncompositionend` that silently breaks IME) simply can't happen to you. The two contracts the spread owns are the ones every consumer used to hand-write: the source is populated so that **`textContent === source`** (the walk that maps DOM positions to byte offsets depends on it), and focus is parked on the editor root when the source unmounts.
 
-That single text node carries every newline your source holds, which makes **`white-space: pre-wrap` (or `pre`) on your source element part of the contract** for any leaf whose bytes can span lines. Without it the browser collapses the line breaks on screen while the offset walk goes on counting them, and the caret sits nowhere near where it looks.
+That text carries every newline your source holds, which makes **`white-space: pre-wrap` (or `pre`) on your source element part of the contract** for any leaf whose bytes can span lines. Without it the browser collapses the line breaks on screen while the offset walk goes on counting them, and the caret sits nowhere near where it looks.
+
+**A painted source.** By default the source is one text node. A `renderSource(text)` dep paints it as DOM instead (fence lines the marker-hiding modes collapse, highlight tokens; the `highlightCode` export is the code block's own tokenizer), and the factory asserts `textContent === text` on every paint, so a painter that drops a byte fails loudly in dev rather than corrupting a commit. A painted source takes its plain-text edits from the leaf, not the browser: typing, Enter, deletes and pastes splice the text and repaint, each reported through `onSourceEdit(text)` so a live preview can follow the draft, and undo inside the open reveal walks those edits back before it reaches the document's history. `repaintSource()` re-runs the painter after a native edit (an IME commit), and `completeBareSource(text)` lets a kind complete a chrome-only source (a `$$` straight over `$$`) to the shape a caret can sit in, asked as the source is revealed and again after any edit that empties it, so a one-line `$$x^2$$` that loses its `x^2` never shows bare fences. Block math is the worked example.
 
 A leaf whose bytes are one line (the parrot's opener claims exactly one) declares `singleLine: true` and needs none of that. Enter in one of those ends the block: the text after the caret becomes a paragraph below and the caret goes with it, which is what Enter does in a heading. With the flag off, the default, Enter types a newline.
 
@@ -1188,7 +1197,7 @@ Editing past your own fence therefore re-splits the document instead of wedging
 
 **Per-instance configuration.** `leaf.getOptions()` returns this editor instance's options for the plugin owning your kind, typed `unknown` for you to narrow. It's the same route as the container factory's `getOptions()`, one tier down, and the same rule applies ([the options recipe](#recipe-per-instance-options-and-the-factory-closure-trap)). The bundled toc block resolves `maxDepth` this way and falls back to the factory argument, which then serves as the default for an instance declaring none.
 
-Block math (`$$…$$` in the bundled `@voithos-labs/aragonite/plugins/latex` plugin) is the worked example, and it's smaller than you'd expect: its component script is the factory call, one render effect (KaTeX), a `{...leaf.surfaceProps}` spread on the source, and one-line re-exports of the returned surface. Registration is the ordinary leaf recipe: `registerBlockKind` (no container group), `registerBlockOpener`, `registerBlockComponent`.
+Block math (`$$…$$` in the bundled `@voithos-labs/aragonite/plugins/latex` plugin) is the worked example, and it's smaller than you'd expect: its component script is the factory call, one render effect (KaTeX), a `{...leaf.surfaceProps}` spread on the source, and one-line re-exports of the returned surface. Registration is the ordinary leaf recipe: `registerBlockKind` (no container group), `registerBlockOpener`, `registerBlockComponent`. Its `caretTargetAtPoint` is the other half of the parrot's: where the parrot's caption is the source bytes minus a prefix, KaTeX paints glyphs no offset maps back to, so the render effect stamps the body's span on the rendered element and the hook walks that span in proportion to how far along the press fell.
 
 ## Presentation modes
 
@@ -1268,7 +1277,7 @@ fence claim ──▶ opaque container, NO children ──▶ component renders
 - **Edit mode commits through `updateOwnMetadata`.** The component swaps its body to a plugin-owned `<textarea>` seeded from metadata; commit (Ctrl+Enter, blur) writes the new code with the container factory's `updateOwnMetadata`, which is one undoable entry, with your `rebuildRaw` re-emitting the fence so `getSource()` reflects the edit byte-exactly. Escape cancels without touching the tree.
 - **Inject the renderer, memoize it, own its CSS.** The engine is the consumer's dependency: take it as a plugin option (`mermaidPlugin({ renderer })`) and pass it by module to the component. Wrap it in `createBoundedMemo` so re-renders of unchanged code do zero engine work. An async renderer stores the render promise as the cached value (in-flight work is shared, and a failure is cached like a success), and a renderer whose result holds a live DOM node passes a `cloneOnRead` so each caller gets its own copy. Resolve failures to a legible inline error, never a throw, and render a static code fallback with a note when no renderer is configured. The engine's stylesheet travels with the renderer module, so import it there, where no route can forget it: a KaTeX-based renderer needs `katex/dist/katex.min.css`, or its MathML accessibility tree lays out unclipped and every equation paints twice.
 - **If the engine paints its own colors, the theme is a render input.** An engine that emits markup carrying color literals (a diagram SVG) can't be rethemed by a stylesheet after the fact; the diagram has to be redrawn. So the theme belongs in three places at once, and any one of them alone leaves a broken half: **the renderer's parameters** (so it can draw for the theme), **the memo key** (so a flip misses and a flip back is still a hit, never a cache reset, which throws away work you'll want again), and **the component's render read** (`getTheme()` off the container or leaf factory), because THAT read is what subscribes the block to the flip. Mermaid keys `theme\0code`; its engine adapter maps the editor theme name to a mermaid theme and re-initializes when it changes, serializing renders because that config is process-global. An engine styled by CSS variables needs none of this.
-- **Interior interactivity stays inside your DOM.** Pan/zoom, buttons, overlays: anything draggable must `stopPropagation()` on pointerdown, or the drag starts a cross-block selection instead. A focus view is just a fixed-position overlay in the component's own tree, so mount it in place, focus it on open, close on Escape.
+- **Interior interactivity stays inside your DOM.** Pan/zoom, buttons, overlays: put `POINTER_GESTURE_ATTR` on the element whose drags are yours (only while the gesture is armed, if it isn't always), or the editor reads the press as the start of a selection and paints a range over your pan. `stopPropagation()` on pointerdown can't do this, since Svelte delivers pointer events from the app root and the editor's listener has already run. A focus view is just a fixed-position overlay in the component's own tree, so mount it in place, focus it on open, close on Escape.
 - **View-state commands reach the component through `ctx.hooks`.** See [Block commands](#block-commands).
 
 The two helpers from that list, with what they hand back:
@@ -1381,6 +1390,8 @@ If your `revealSource` widget takes a click of its own, declare `claimsActivatio
 
 If your widget derives from the whole document, read the version inside the same `$derived` and use it as your memo key. The document itself isn't a usable key: the editor mutates it in place, so its identity never changes, and an identity-keyed memo hits forever on a stale answer. Reading the version inside the derived is also what subscribes your widget to edits anywhere, so N widgets sharing one memoized walk stay as live as N widgets each walking the document.
 
+**A symmetric delimiter can close itself as it is typed.** Pass `autoPair: true` on a bare trigger whose construct opens and closes on the same byte, the way the bundled latex plugin does for `$…$`: typing the trigger lands its twin after the caret, typing it again over that twin steps past it, and a first body byte that leaves the pair no construct (`$5` is a price) drops the twin again. Without it a lone `$` typed ahead of an existing formula pairs with that formula's closer and wraps the prose between them. The built-in backtick, `*`, `_` and `~~` behave this way without registration.
+
 **A bare trigger must be a character no built-in scanner claims.** Registering a bare recognizer on a reserved trigger (`` ` ``, `&`, `<`, `*`, `_`, `~`, `[`, `]`, `!`, `\`, or newline) throws: built-in dispatch runs first, so a bare recognizer there would never fire, and a silent no-op is the one failure a public API must not have.
 
 The bundled **emoji** plugin (`@voithos-labs/aragonite/plugins/emoji`) is this bare-trigger recipe end to end and the worked reference for an inline kind on an unreserved trigger: `:shortcode:` recognizes on the bare `:` trigger, renders as an atomic glyph widget through `buildWidget` + `mintWidgetShell`, and carries the `{ deleteGranularity: 'atomic', onEdge: 'step-over' }` edge policy so a caret-adjacent Backspace removes the whole `:name:` in one press and a plain arrow steps over it. It shares the `:` trigger with the directive text tier, because disjoint grammars coexist happily on one trigger: a table-lookup miss declines and falls through with the bytes untouched. The literal `:name:` bytes stay in the raw, so an uninstalled document round-trips as ordinary prose.
@@ -1400,7 +1411,7 @@ The scanner consults the rung ahead of the built-in `[` case, but only when `[^`
 
 A rung on `!` is consulted ahead of the built-in `!` case, so it outranks the image grammar wherever its prefix matches. And the two grammars do overlap: an image whose alt text opens with `[` starts on `![[` as well, so `![[a.png]]` carrying a parenthesized destination after it is a built-in image with the alt text `[a.png]`, not an embed. Deciding that overlap is your recognizer's job. Decline it (return `null`) and the built-in image reads the bytes unchanged. **Getting it wrong fails silently.** An ungated `![[` recognizer swallows the image with no throw and no dev-warn, and since the raw bytes are untouched the document still round-trips cleanly, so no round-trip check and no conformance cell in your own suite will ever see it. The first report comes from a reader whose picture stopped rendering.
 
-**Bound the decline, not just the claim.** Your recognizer is consulted at every occurrence of its trigger, so a decline that searches to the end of the block costs one block scan per trigger, which goes quadratic on a large paragraph, and the trigger is often ordinary prose (`$HOME $PATH …` for `$`). Stop at the first character your grammar can't contain, the way the emoji recognizer stops at the first non-shortcode byte. Where the grammar has no such character, index the candidate positions once per block with `createScanIndex` (hand it your position collector, get back a "first candidate at or after this offset" lookup), the way the bundled math and footnote recognizers index their closers:
+**Bound the decline, not just the claim.** Your recognizer is consulted at every occurrence of its trigger, so a decline that searches to the end of the block costs one block scan per trigger, which goes quadratic on a large paragraph, and the trigger is often ordinary prose (`$HOME $PATH …` for `$`). Stop at the first character your grammar can't contain, the way the emoji recognizer stops at the first non-shortcode byte. Where the grammar has no such character, index the candidate positions once per block with `createScanIndex` (hand it your position collector, get back a "first candidate at or after this offset" lookup), the way the bundled math recognizer indexes every `$` and the footnote one its closers:
 
 ```ts
 const dollarAt = createScanIndex((raw) => {
@@ -1444,17 +1455,19 @@ Three edges the snippet above is shaped by, and each one bites if you drop it:
 
 **Errors in a component widget are half yours.** A **synchronous mount-time throw** is caught, so the widget falls back to its raw source and an `error` event fires, but the component mounts as its own effect root and nothing catches its post-mount runtime errors. Render a legible error for bad input instead of throwing (the KaTeX widget shows an inline message). A render engine's stylesheet is likewise yours: import it in the module that owns the renderer, so no route can forget it.
 
-**The inline tier isn't the block surface in miniature.** An inline kind gets recognition, rendering, atomic caret addressing at its edges, and an editing policy on its widget registration. The policy has five fields, all optional:
+**The inline tier isn't the block surface in miniature.** An inline kind gets recognition, rendering, atomic caret addressing at its edges, and an editing policy on its widget registration. The policy's fields, all optional:
 
-| Field                   | What it decides                                                                                                           |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `revealSource`          | Open the source (the `$…$` bytes) for editing on caret entry; inline math's model                                         |
-| `onSelectedKey`         | A handler for keys while the widget is selected; image resize rides it                                                    |
-| `onEdge`                | `'select' \| 'step-over'`: an edge press selects the whole widget, or steps transparently over it                         |
-| `deleteGranularity`     | `'atomic' \| 'select-then-delete'`: one press deletes the whole widget, or the first press selects and the second deletes |
-| `claimsActivationClick` | Your component handles the activation click itself, so the surface's reveal stands down for it; the footnote jump's model |
+| Field                   | What it decides                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `revealSource`          | Open the source (the `$…$` bytes) for editing on caret entry; inline math's model                                                                                                                                                                                                                                                                            |
+| `revealContentSpan`     | Where the editable content sits inside the source (`$x$` answers `{ start: 1, end: 2 }`), so a caret entering the source stays between the delimiters; absent, it keeps the leading edge                                                                                                                                                                     |
+| `revealOffsetAtPoint`   | Which source offset a press on the rendered widget names, so a click seats the caret where it landed; inline math walks its KaTeX glyphs for this, and `null` falls back to the content span's end                                                                                                                                                           |
+| `onSelectedKey`         | A handler for keys while the widget is selected; image resize rides it                                                                                                                                                                                                                                                                                       |
+| `onEdge`                | `'select' \| 'step-over'`: an edge press selects the whole widget, or steps transparently over it; `'step-over'` also makes a press on the widget seat the caret at the edge it landed by, where `'select'` leaves the island its own click; and Up or Down onto a block holding only a step-over widget seats the caret beside it, one press in and one out |
+| `deleteGranularity`     | `'atomic' \| 'select-then-delete'`: one press deletes the whole widget, or the first press selects and the second deletes                                                                                                                                                                                                                                    |
+| `claimsActivationClick` | Your component handles the activation click itself, so the surface's reveal stands down for it; the footnote jump's model                                                                                                                                                                                                                                    |
 
-Both edge fields are live today: the built-in decoded-entity widget (`&copy;` → ©) ships `{ deleteGranularity: 'atomic', onEdge: 'step-over' }`, so a caret-adjacent Backspace removes it whole and a plain arrow walks the caret across it like a character, the caret-edge dispatch reading both off the widget registration. The inline tier gets **no keymap, no minted commands, and no per-node metadata**: `InlineNode` has no metadata field, so unlike a block kind it stores nothing at all on the node.
+Both edge fields are live today: the built-in decoded-entity widget (`&copy;` → ©) ships `{ deleteGranularity: 'atomic', onEdge: 'step-over' }`, so a caret-adjacent Backspace removes it whole and a plain arrow walks the caret across it like a character, the caret-edge dispatch and the click seat reading both off the widget registration. The inline tier gets **no keymap, no minted commands, and no per-node metadata**: `InlineNode` has no metadata field, so unlike a block kind it stores nothing at all on the node.
 
 ## Decorations
 
@@ -1606,6 +1619,25 @@ registerGlobalCommand('mine.bold', handler, { chord: 'Mod+B' }); // fine: fires
 
 Chord strings follow the consumer guide's chord model: fixed-order `Mod` / `Alt` / `Shift` plus the key's own value. Shifted-symbol chords aren't modeled, so bind plain digits and letters.
 
+## Block context actions
+
+**`registerBlockContextActions(kind, provider)`**
+
+The right-click menu on a block of `kind` (a code block, a table, a plugin's own block) lists what its providers return, ahead of the editor's own rows (copy, replace with the clipboard, remove). Register from `setup`. The provider is consulted on every open, so it reads the block as it is then; several may stack on one kind, and `EVERY_KIND` (`'*'`) registers for every kind. Prose is the page's background: a paragraph or heading keeps the browser's own menu and consults no provider.
+
+```ts
+registerBlockContextActions(conspiracy, (node) => [
+	{
+		id: 'conspiracy.debunk',
+		label: 'Mark debunked',
+		icon: 'check',
+		run: (ctx) => ctx.replaceRaw(node.raw.replace(/^:::conspiracy/, ':::debunked'))
+	}
+]);
+```
+
+`run` receives a `BlockActionContext`: the node, its path, `deleteBlock()`, and `replaceRaw(raw)`, which rewrites the block's bytes wholesale and reparses them, the road the default replace row takes. Each is one undo entry. `icon` names a glyph the editor's menus already draw (the same set the code rail and the table menu use); a row without one shows none. `danger` paints the row in the error colour, for an action that is not one undo away.
+
 ## Paste transforms
 
 `registerPasteTransform` records a **content-keyed, pre-parse** rewrite of pasted plain text. Each transform is a `{ name, transform(text) }` unit: `transform` returns a replacement string, or `null` to decline ("not mine"). Transforms run at every paste site before the clipboard text is parsed, in **install order**, each one seeing the previous transform's output, so a plugin keys off the _content_ it recognizes rather than the block it lands in. The name is unique (register-once; a duplicate throws, naming the owning plugin) and scopes the transform for attribution.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@voithos-labs/aragonite",
-	"version": "0.10.2",
-	"description": "Svelte 5 block editor for GFM Markdown with byte-for-byte lossless round-trip and a plugin platform",
+	"version": "0.10.4",
+	"description": "cute svelte-based markdown editor lib",
 	"keywords": [
 		"markdown",
 		"gfm",
@@ -188,7 +188,7 @@
 	},
 	"peerDependencies": {
 		"katex": "^0.17.0 || ^0.18.0",
-		"mermaid": "^11.16.0",
+		"mermaid": "^11.16.0 || ^12.0.0",
 		"svelte": "^5.29.0"
 	},
 	"peerDependenciesMeta": {
@@ -202,6 +202,8 @@
 	"devDependencies": {
 		"@axe-core/playwright": "^4.13.0",
 		"@eslint/js": "^10.0.1",
+		"@fontsource/inter": "^5.3.0",
+		"@fontsource/jetbrains-mono": "^5.3.0",
 		"@playwright/test": "^1.62.0",
 		"@sveltejs/adapter-static": "^3.0.0",
 		"@sveltejs/kit": "^2.70.3",
@@ -209,7 +211,7 @@
 		"@sveltejs/vite-plugin-svelte": "^7.3.0",
 		"@types/commonmark": "^0.27.10",
 		"@types/node": "^26.2.0",
-		"@vitest/browser": "^4.1.11",
+		"@vitest/browser": "^5.0.0",
 		"commonmark": "0.31.2",
 		"eslint": "^10.9.0",
 		"eslint-plugin-svelte": "^3.23.0",
@@ -217,7 +219,7 @@
 		"globals": "^17.11.0",
 		"jsdom": "^30.0.0",
 		"katex": "^0.18.4",
-		"mermaid": "^11.17.0",
+		"mermaid": "^12.0.0",
 		"prettier": "^3.9.6",
 		"prettier-plugin-svelte": "^4.1.1",
 		"svelte": "^5.56.10",
@@ -226,8 +228,8 @@
 		"typescript": "^6.0.3",
 		"typescript-eslint": "^8.67.0",
 		"vite": "^8.2.2",
-		"vitest": "^4.1.0",
-		"wrangler": "4.125.0"
+		"vitest": "^5.0.0",
+		"wrangler": "4.131.1"
 	},
 	"overrides": {
 		"cookie": "^0.7.2"

package/dist/components/blocks/code/CodeLanguageChip.svelte

@@ -1,127 +0,0 @@
-<script lang="ts">
-	import { tick } from 'svelte';
-	import { CODE_LANGUAGE_FIELD, codeLanguageLabel } from '../../../a11y-strings';
-
-	// The fence-info door for the modes that paint no fence. The draft lives here and only a
-	// commit reaches the tree.
-	let {
-		info,
-		editable,
-		onCommit,
-		onCancel
-	}: {
-		/** The opener's full info string; the button shows its first token. */
-		info: string;
-		/** False in reading mode, which writes no bytes — the chip is then a label. */
-		editable: boolean;
-		/** Only Enter calls this, and it owns the caret's landing afterwards. */
-		onCommit: (info: string) => void;
-		/** Nothing written. Escape asks for the caret back; a blur must not yank it from
-		 *  wherever the user just clicked, so it does not. */
-		onCancel: (returnCaret: boolean) => void;
-	} = $props();
-
-	const language = $derived(info.split(/\s+/)[0] || 'text');
-
-	let editing = $state(false);
-	let draft = $state('');
-	let inputEl: HTMLInputElement | undefined = $state();
-
-	function open(): void {
-		if (!editable) return;
-		draft = info;
-		editing = true;
-		void tick().then(() => {
-			inputEl?.focus();
-			inputEl?.select();
-		});
-	}
-
-	function onFieldKeyDown(e: KeyboardEvent): void {
-		// The field owns its keys while open: no Escape of this state may reach whatever else
-		// listens for one. A composing Enter/Escape is the IME's, never the field's.
-		e.stopPropagation();
-		if (e.isComposing) return;
-		if (e.key === 'Enter') {
-			e.preventDefault();
-			const committed = draft;
-			editing = false;
-			onCommit(committed);
-		} else if (e.key === 'Escape') {
-			e.preventDefault();
-			editing = false;
-			onCancel(true);
-		}
-	}
-
-	function onFieldBlur(): void {
-		if (!editing) return;
-		editing = false;
-		onCancel(false);
-	}
-</script>
-
-<span class="code-lang-chip">
-	{#if editing}
-		<input
-			bind:this={inputEl}
-			bind:value={draft}
-			type="text"
-			spellcheck="false"
-			aria-label={CODE_LANGUAGE_FIELD}
-			onkeydown={onFieldKeyDown}
-			onfocusout={onFieldBlur}
-		/>
-	{:else}
-		<button type="button" aria-label={codeLanguageLabel(language)} onclick={open}>{language}</button
-		>
-	{/if}
-</span>
-
-<style>
-	/* Positioned against the block host, whose box the code box fills, and out of the code
-	   box's own scroller so a horizontal scroll leaves it where it is. */
-	.code-lang-chip {
-		position: absolute;
-		top: 5px;
-		right: 5px;
-		z-index: 1;
-		display: flex;
-		font-family: var(--font-editor, ui-monospace, monospace);
-		font-size: 0.75em;
-		line-height: 1;
-		opacity: 0;
-		pointer-events: none;
-	}
-
-	/* Transient, like the drag handle: the pointer over the block or the caret inside it, plus
-	   the open field, which outlives both. Child and sibling combinators, so an outer container's
-	   hover never reveals a nested block's chip. */
-	:global(.block-host:hover) > .code-lang-chip,
-	:global(.code-block:focus) ~ .code-lang-chip,
-	.code-lang-chip:focus-within {
-		opacity: 1;
-		pointer-events: auto;
-	}
-
-	button,
-	input {
-		padding: 2px 6px;
-		border: 1px solid var(--color-ui-muted, #a4a4a4);
-		border-radius: var(--radius-ui, 3px);
-		background: var(--color-bg-elevated, #2a2a2a);
-		color: var(--color-accent, #567b67);
-		font: inherit;
-		cursor: pointer;
-	}
-
-	button:hover {
-		background: var(--color-ui-faint, rgba(255, 255, 255, 0.07));
-	}
-
-	input {
-		width: 9ch;
-		color: var(--color-text-secondary, #eee);
-		cursor: text;
-	}
-</style>

package/dist/components/blocks/code/CodeLanguageChip.svelte.d.ts

@@ -1,14 +0,0 @@
-type $$ComponentProps = {
-    /** The opener's full info string; the button shows its first token. */
-    info: string;
-    /** False in reading mode, which writes no bytes — the chip is then a label. */
-    editable: boolean;
-    /** Only Enter calls this, and it owns the caret's landing afterwards. */
-    onCommit: (info: string) => void;
-    /** Nothing written. Escape asks for the caret back; a blur must not yank it from
-     *  wherever the user just clicked, so it does not. */
-    onCancel: (returnCaret: boolean) => void;
-};
-declare const CodeLanguageChip: import("svelte").Component<$$ComponentProps, {}, "">;
-type CodeLanguageChip = ReturnType<typeof CodeLanguageChip>;
-export default CodeLanguageChip;