@voithos-labs/aragonite 0.10.3 → 0.10.4

package/docs/guide/plugin-api.md

@@ -40,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 |
@@ -153,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
 
@@ -180,17 +181,18 @@ _(pre-freeze / unstable)_ The container factory's sibling for leaves; the full s
 
 ### 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.
 
-| 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; 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';
@@ -199,29 +201,29 @@ 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                                                                                                                                                                                          |
+| 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
 
@@ -292,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.
@@ -1165,7 +1172,7 @@ leaf.getOptions(); // this editor's options for your plugin, typed unknown
 
 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 as it is revealed. Block math is the worked example.
+**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.
 
@@ -1270,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:
@@ -1383,7 +1390,7 @@ 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 the recognizer rejects (a `$` followed by a digit 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 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.
 
@@ -1404,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) => {
@@ -1448,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
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@voithos-labs/aragonite",
-	"version": "0.10.3",
-	"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": {
@@ -211,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",
@@ -219,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",
@@ -228,8 +228,8 @@
 		"typescript": "^6.0.3",
 		"typescript-eslint": "^8.67.0",
 		"vite": "^8.2.2",
-		"vitest": "^4.1.0",
-		"wrangler": "4.131.0"
+		"vitest": "^5.0.0",
+		"wrangler": "4.131.1"
 	},
 	"overrides": {
 		"cookie": "^0.7.2"

package/dist/selection/double-click-trim.d.ts

@@ -1,17 +0,0 @@
-/**
- * Word selection without its trailing space. Windows Chromium's double-click takes the whitespace
- * after a word (the desktop-Word convention); a formatting toggle over that range would wrap the
- * space too, and every other platform selects the bare word. The browser paints its own range
- * before any `dblclick` handler runs, so the word is selected HERE, on the second press, with
- * the native selection suppressed: the trimmed range is the first one ever painted.
- */
-/** Trim trailing whitespace off the document's current selection when it ends in a text node.
- *  A selection that is only whitespace is left alone: collapsing it would undo the click. */
-export declare function trimDoubleClickSelection(doc: Document): boolean;
-/**
- * Select the word under the point of a double-click's second press, trimmed, synchronously.
- * Word edges come from the engine's own `modify` walk so they match what its double-click would
- * have chosen. False when the point names no text position; the caller then leaves the press to
- * the browser.
- */
-export declare function selectWordAtPoint(doc: Document, x: number, y: number): boolean;

package/dist/selection/double-click-trim.js

@@ -1,57 +0,0 @@
-/**
- * Word selection without its trailing space. Windows Chromium's double-click takes the whitespace
- * after a word (the desktop-Word convention); a formatting toggle over that range would wrap the
- * space too, and every other platform selects the bare word. The browser paints its own range
- * before any `dblclick` handler runs, so the word is selected HERE, on the second press, with
- * the native selection suppressed: the trimmed range is the first one ever painted.
- */
-/** Trim trailing whitespace off the document's current selection when it ends in a text node.
- *  A selection that is only whitespace is left alone: collapsing it would undo the click. */
-export function trimDoubleClickSelection(doc) {
-    const sel = doc.getSelection();
-    if (!sel || sel.rangeCount === 0 || sel.isCollapsed)
-        return false;
-    const range = sel.getRangeAt(0);
-    const endNode = range.endContainer;
-    if (!(endNode instanceof Text))
-        return false;
-    const text = range.toString();
-    const trimmed = text.trimEnd().length;
-    if (trimmed === 0 || trimmed === text.length)
-        return false;
-    const cut = text.length - trimmed;
-    if (cut > range.endOffset)
-        return false;
-    sel.setBaseAndExtent(range.startContainer, range.startOffset, endNode, range.endOffset - cut);
-    return true;
-}
-/**
- * Select the word under the point of a double-click's second press, trimmed, synchronously.
- * Word edges come from the engine's own `modify` walk so they match what its double-click would
- * have chosen. False when the point names no text position; the caller then leaves the press to
- * the browser.
- */
-export function selectWordAtPoint(doc, x, y) {
-    const sel = doc.getSelection();
-    const hit = textPositionAt(doc, x, y);
-    if (!sel || !hit || typeof sel.modify !== 'function')
-        return false;
-    sel.setBaseAndExtent(hit.node, hit.offset, hit.node, hit.offset);
-    sel.modify('move', 'backward', 'word');
-    sel.modify('extend', 'forward', 'word');
-    if (sel.isCollapsed)
-        return false;
-    trimDoubleClickSelection(doc);
-    return true;
-}
-function textPositionAt(doc, x, y) {
-    const position = doc.caretPositionFromPoint?.(x, y);
-    if (position?.offsetNode instanceof Text) {
-        return { node: position.offsetNode, offset: position.offset };
-    }
-    const range = doc.caretRangeFromPoint?.(x, y);
-    if (range?.startContainer instanceof Text) {
-        return { node: range.startContainer, offset: range.startOffset };
-    }
-    return null;
-}