@voithos-labs/aragonite 0.10.4 → 0.10.7

package/docs/guide/plugin-testing.md

@@ -1,36 +1,36 @@
 # Testing Your Plugin
 
-The testing half of the plugin story: what to check once your block works, and the tools your suite imports from `@voithos-labs/aragonite/testing` to check it. Three neighbouring docs carry what this one leans on:
+A plugin can look perfect on screen and still be quietly eating bytes. Screenshots prove nothing here. Verify the damn bytes.
 
-- [plugin-guide.md](plugin-guide.md): building the plugin in the first place. The `%%parrot` block and the `:::conspiracy` container below are its running examples.
-- [plugin-api.md](plugin-api.md): the catalog of every authoring export, if a name below reads unfamiliar.
-- [consumer-guide.md](consumer-guide.md): the editor's props and instance methods; the mounting section below uses both.
+The proof comes in three layers, cheapest first, and this doc walks them in order:
 
-And a map, so you can jump straight at your question:
+1. **Round-trip checks you write yourself.** Parse, serialize, compare. A few lines, no editor mounted.
+2. **The editor's own warnings, turned into failures.** A dev build already watches your plugin for contract violations, and your suite can go red on them.
+3. **The conformance kits.** The same checks every built-in block kind is held to, pointed at your kind. You supply fixtures; the kit supplies the suspicion.
 
-| Section                                                                   | What it covers                                                                                           |
-| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| [Round-trip is the contract](#round-trip-is-the-contract)                 | The three byte checks to write first: without an editor, in a live one, and with your plugin uninstalled |
-| [A blank slate per test](#a-blank-slate-per-test)                         | Why a plugin registers only once per process, and the reset that lets a test suite live with that        |
-| [Turning warnings into failures](#turning-warnings-into-failures)         | Making the editor's dev-mode warnings fail your suite instead of scrolling by                            |
-| [Proving a paste transform is wired](#proving-a-paste-transform-is-wired) | Driving the real paste pipeline over a string, no clipboard involved                                     |
-| [Mounting the editor under jsdom](#mounting-the-editor-under-jsdom)       | Rendering your component in a simulated browser, and the helper that fills the gaps                      |
-| [The conformance kits](#the-conformance-kits)                             | The checks the built-in blocks are held to, pointed at yours, and the vocabulary the three kits share    |
-| [The kind checkup](#the-kind-checkup-runkindconformance)                  | The checks every block kind owes: bytes survive, one edit is one undo step, copying invents nothing      |
-| [The container checkup](#the-container-checkup-runcontainerconformance)   | Extra checks for a block that holds other blocks, starring the body line that ends the container early   |
-| [The inline checkup](#the-inline-checkup-runinlinekindconformance)        | Checks for syntax recognized mid-sentence: claiming your own bytes, declining everyone else's            |
+Everything test-specific imports from one subpath, `@voithos-labs/aragonite/testing`, and each export gets its section below. The running examples are the plugin guide's `%%parrot` block and `:::conspiracy` container. Three neighbouring docs carry what this one leans on:
 
-## Verifying your plugin
+- [plugin-guide.md](plugin-guide.md): building the plugin in the first place.
+- [plugin-api.md](plugin-api.md): the catalog of every authoring export, if a name below reads unfamiliar.
+- [consumer-guide.md](consumer-guide.md): the editor's props and instance methods, which the mounting section uses.
 
-A plugin can look perfect on screen and still be quietly eating bytes. Screenshots prove nothing here. Verify the damn bytes.
+And a map, so you can jump straight at your question:
 
-The proof comes in three layers, cheapest first, and this doc walks them in order:
+| Section                                                                   | What it covers                                                                                             |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| [Round-trip is the contract](#round-trip-is-the-contract)                 | The three byte checks to write first: without an editor, in a live one, and with your plugin uninstalled   |
+| [A blank slate per test](#a-blank-slate-per-test)                         | Why a plugin registers only once per process, and the reset that lets a test suite live with that          |
+| [Turning warnings into failures](#turning-warnings-into-failures)         | Making the editor's dev-mode warnings fail your suite instead of scrolling by                              |
+| [Proving a paste transform is wired](#proving-a-paste-transform-is-wired) | Driving the real paste pipeline over a string, no clipboard involved                                       |
+| [Mounting the editor under jsdom](#mounting-the-editor-under-jsdom)       | Rendering your component in a simulated browser, and the helper that fills the gaps                        |
+| [The conformance kits](#the-conformance-kits)                             | The checks the built-in blocks are held to, pointed at yours, and the vocabulary the three kits share      |
+| [The kind checkup](#the-kind-checkup-runkindconformance)                  | The checks every block kind has to pass: bytes survive, one edit is one undo step, copying invents nothing |
+| [The container checkup](#the-container-checkup-runcontainerconformance)   | Extra checks for a block that holds other blocks, starring the body line that ends the container early     |
+| [The inline checkup](#the-inline-checkup-runinlinekindconformance)        | Checks for syntax recognized mid-sentence: claiming your own bytes, declining everyone else's              |
 
-1. **Round-trip checks you write yourself.** Parse, serialize, compare. A few lines, no editor mounted.
-2. **The editor's own warnings, turned into failures.** A dev build already watches your plugin for contract violations; your suite can go red on them.
-3. **The conformance kits.** The same checks every built-in block kind is held to, pointed at your kind. You supply fixtures; the kit supplies the suspicion.
+## Verifying your plugin
 
-Everything test-specific imports from one subpath, `@voithos-labs/aragonite/testing`, and each export gets its section below.
+The checks, cheapest first, one section each.
 
 ### Round-trip is the contract
 
@@ -84,8 +84,8 @@ isPluginInstalled('parrot'); // false, and declaredPluginKind('parrot') throws u
 
 What that clears, and what it deliberately leaves alone:
 
-- Cleared: every non-built-in registration. Kinds, components, openers, completers, commands and keymaps, the inline syntax and widget registries, the paste surfaces and transform pipelines, the `:::` directive registry, and the installed-plugin set.
-- Built-in registrations survive, exactly as in production. One exception: paste surfaces are wiped whole, built-ins included, so a case that pastes into a built-in block after a reset re-registers or skips the reset. Parse and round-trip cases don't care.
+- Cleared: every non-built-in registration. Kinds, components, openers, completers, commands and keymaps, block context actions, insert entries, code languages, the inline syntax and widget registries, the paste surfaces and transform pipelines, the `:::` directive registry, the renderer a plugin set on a renderer slot, and the installed-plugin set.
+- Built-in registrations survive, exactly as in production, the built-in paste surfaces and code languages included, so a case that pastes into a built-in block after a reset needs nothing re-registered.
 - Runtime state is untouched. The undo stack, the selection, and any live document are yours to set up.
 - It's test-only and throws outside a detected test environment. Detection is Vitest-specific (it reads `process.env.VITEST`), so a suite on another runner opts in first and puts the detected defaults back after:
 
@@ -104,7 +104,7 @@ afterAll(() => resetEditorEnv());
 
 ### Turning warnings into failures
 
-The editor reports contract violations it can contain, rather than crash on, as dev warnings under an `[aragonite:…]` console head. A suite that wants those red rather than scrolling past registers a sink:
+The editor reports contract violations it can contain, rather than crash on, as dev warnings under an `[aragonite:…]` console head. A suite that wants those red rather than scrolling past registers a callback for them:
 
 ```ts
 import { setDevWarnSink } from '@voithos-labs/aragonite/testing';
@@ -117,7 +117,7 @@ afterEach(() => {
 });
 ```
 
-While a sink is registered it takes over reporting completely (nothing reaches the console), and every entry is a small object. A paste transform that throws, for instance, is contained as a decline and reported like this:
+While a callback is registered it takes over reporting completely (nothing reaches the console), and every entry is a small object. A paste transform that throws, for instance, is contained as a decline and reported like this:
 
 ```ts
 registerPasteTransform({
@@ -136,13 +136,13 @@ fires[0];
 // }
 ```
 
-`setDevWarnSink` returns the sink it replaced, so a nested harness restores rather than clears.
+`setDevWarnSink` returns the callback it replaced, so a nested harness restores rather than clears.
 
-One prerequisite: warnings only emit while the editor believes it's in a dev build, and a sink over a production build stays empty for the wrong reason. A Vitest suite gets the dev flag automatically, because its build resolves it. Under another runner, or a bundler that resolves no export conditions, call `configureEditorEnv({ isDev: true })` in your setup (add `isTest: true` if the suite also uses the reset) and `resetEditorEnv()` in teardown.
+One prerequisite: warnings and invariant checks only run while the editor believes it's in a dev build, and a callback over a production build stays empty for the wrong reason. A Vitest suite gets the dev flag automatically, because its build resolves it. Under another runner, or a bundler that resolves no export conditions, call `configureEditorEnv({ isDev: true, isTest: true })` in your setup and `resetEditorEnv()` in teardown. `isDev` alone turns both on, and `isTest` beside it keeps the test-process rules: the reset works, and a duplicate registration throws instead of being replaced in place the way a dev server does it.
 
 ### Proving a paste transform is wired
 
-`registerPasteTransform` writes into a registry nothing else on the public surface reads, so the subpath ships the driver. `applyPasteTransforms(text)` is the very function every clipboard-to-parse route runs, so driving it proves your transform is **wired**, not merely that your pure function works:
+`registerPasteTransform` writes into a registry nothing else on the public surface reads, so the subpath ships the driver. `applyPasteTransforms(text)` is the very function every clipboard-to-parse route runs, so driving it proves your transform is **wired**, not merely that your pure function works. By default it runs every installed plugin's transforms, the way an editor with no `plugins` prop would. Pass a list of plugin names, `applyPasteTransforms(text, ['parrot'])`, to run it as an editor listing only those (so a transform your plugin's setup registered runs only when your plugin is in the list):
 
 ```ts
 import { applyPasteTransforms } from '@voithos-labs/aragonite/testing';
@@ -168,7 +168,7 @@ applyPasteTransforms('quiet please\n'); // 'quiet please\n' (declined, so nothin
 
 ### Mounting the editor under jsdom
 
-A component is only really verified mounted, and a jsdom mount is a supported way to do it. Three things stand in the way. Two are jsdom gaps, and `installEditorDomStubsForTests` closes both by stubbing the browser APIs a mounted editor calls and jsdom lacks (`ResizeObserver` and `scrollIntoView`), each only where absent, so the call is inert in a real browser:
+A component is only really verified mounted, and a jsdom mount is a supported way to do it. Two things stand in the way. The first is the browser APIs a mounted editor calls and jsdom doesn't have (`ResizeObserver`, `scrollIntoView`, and a text range's rects, which the editor reads to keep the caret on screen). `installEditorDomStubsForTests` fills those in, each only where it's missing, so the call does nothing in a real browser:
 
 ```ts
 // @vitest-environment jsdom
@@ -183,7 +183,7 @@ const editor = mount(Editor, { target, props: { source: MY_SOURCE, plugins, scro
 flushSync(); // the first render has to land before you can assert on it
 ```
 
-`scrollMode: 'host'` is the third thing: it drops the editor's own scroll container and the chrome a jsdom box can't size anyway ([host scroll mode](consumer-guide.md#host-scroll-mode)). And keep the fixture document short. The editor stops mounting blocks past an estimated-height budget in either scroll mode, jsdom reports a zero-height viewport, and a fixture tall enough to trip that unmounts the very block you're asserting on.
+`scrollMode: 'host'` is the second thing: it drops the editor's own scroll container and the chrome a jsdom box can't size anyway ([host scroll mode](consumer-guide.md#host-scroll-mode)). And keep the fixture document short. The editor stops mounting blocks past an estimated-height budget in either scroll mode, jsdom reports a zero-height viewport, and a fixture tall enough to trip that unmounts the very block you're asserting on.
 
 From there `target.querySelector` reaches your component's own markup, and `editor.getSource()` hands you the bytes to compare:
 
@@ -198,7 +198,7 @@ Conformance here means: your kind behaves the way the built-in kinds are require
 
 - Each kit runs **cells**, one check per behavior, and each cell is covered one of three ways. `assert` runs the real check. `exempt` means the invariant has nothing to bite on for your kind (there's no such operation to test). `boundary` means checking it needs something headless code can't reach (a browser, a mounted component).
 - You declare an excused cell rather than skipping it, and both excuse modes want a reason that's a real sentence (a bare token like `'n/a'` fails the run). An excuse the kit can falsify, it falsifies.
-- Every kit resolves with a report of what was asserted and what was excused, and otherwise throws a plain `Error` naming every failed cell, so a run drops straight into a test case under any runner.
+- Every kit resolves with a report, and all three write a cell the same way: its `cell` name, its `status` (`asserted`, `exempt` or `boundary`), and usually a `detail` saying what ran or why nothing did (`CellReport`, if you want the type). A failing run throws a plain `Error` naming every failed cell instead, so a run drops straight into a test case under any runner.
 
 ### The kind checkup: `runKindConformance`
 
@@ -211,8 +211,13 @@ Takes your kind (the value `declaredPluginKind` returns) and executes the headle
 - A `clipboard: inherit-default` cell proves a copy is a plain byte slice, with your kind at each end of the copied range in turn.
 - An `undo: inherit-default` cell proves one structural operation pushes exactly one undo entry.
 - A `searchPaint: not-supported` cell proves the document scan genuinely finds nothing in your kind.
+- The raw-write cell, which reads your descriptor's `rawWrite` rule rather than your closure block (so it comes last in the report and carries no `mode`):
+  - With no `rawWrite`, it cuts the fixture's closing line and checks the block after it stays its own. It fails if the cut swallows that block (an unclosed fence reads everything below as its body), and the failure asks you to declare the rule.
+  - With one, it drives the rule through the closing line cut, everything past the first line cut, and an empty write, plus, for a fixture of two or more lines, the first line cut (the opener gone, the closer left behind) and the closing line copied into the body. Each result has to come back unchanged from a second pass of the rule and leave the block after it alone, and when the fixture has three or more lines the first write also has to keep your kind.
+  - Your `mapOffset` is checked against `normalize` at every offset of each write: an offset before every byte the rule changed stays put, one after them moves by what the rule added or dropped, and none goes backwards.
+  - It's `boundary` for a kind with the rule and no top-level fixture (none at all, or one sitting inside a container), and `exempt` for a kind with neither the rule nor a top-level fixture.
 
-Cells whose mechanism only exists in a browser (focus, selection and search painting, reorder, and the note-taking simulation the platform runs over the kinds it enrolls) are recorded `boundary`; the kit won't fake them green. Covering those is a browser test's job (the editor's own e2e sweep does it for every registered kind that declares a `conformanceFixture`). For the parrot, the whole checkup is the test the [guide's quickstart](plugin-guide.md#the-first-fifteen-minutes) ends on:
+Cells whose mechanism only exists in a browser (focus, selection and search painting, reorder, and the note-taking simulation aragonite runs over its own kinds) are recorded `boundary`; the kit won't fake them green. Covering those is your own browser tests' job (aragonite's repository runs a sweep like that over the kinds it registers itself, but it never sees yours). For the parrot, the whole checkup is the test the [guide's quickstart](plugin-guide.md#the-first-fifteen-minutes) ends on:
 
 ```ts
 it('parrot conforms', async () => {
@@ -220,31 +225,32 @@ it('parrot conforms', async () => {
 });
 ```
 
-It resolves with a report, one cell per closure column. For the parrot exactly as the guide declares it:
+It resolves with a report, one cell per closure column and then the raw-write cell. For the parrot exactly as the guide declares it:
 
 ```ts
 const report = await runKindConformance(declaredPluginKind(PARROT));
-report.cells.map((c) => `${c.column}: ${c.status}`);
+report.cells.map((c) => `${c.cell}: ${c.status}`);
 // [
-//   'roundTrip: executed',      // the fixture round-trips
+//   'roundTrip: asserted',      // the fixture round-trips
 //   'focus: boundary',          // browser only
-//   'mergeBackspace: executed', // eligibility matches mergeRole
+//   'mergeBackspace: asserted', // eligibility matches mergeRole
 //   'selectionPaint: boundary', // browser only
 //   'searchPaint: boundary',    // you declared it implemented, so it's yours to prove
 //   'reorder: boundary',        // browser only
 //   'undo: boundary',           // implemented too, so the kit can't drive it generically
-//   'clipboard: executed',      // copy is a raw byte slice
-//   'simOracle: boundary'       // the platform sweep's, never this runner's
+//   'clipboard: asserted',      // copy is a raw byte slice
+//   'simOracle: boundary',      // aragonite's own simulation, never this runner
+//   'rawWrite: asserted'        // no rule, and cutting the closing line swallows nothing
 // ]
 ```
 
-Each cell also carries the `mode` you declared and a `detail` string saying what ran, or why nothing did. When something's wrong the run throws instead of resolving; a fixture that stopped producing your kind reads like this:
+Each closure cell also carries the `mode` you declared. When something's wrong the run throws instead of resolving; a fixture that stopped producing your kind reads like this:
 
 ```
 Error: kind conformance failed for "parrot": conformanceFixture parses to no "parrot" node
 ```
 
-**The fixture contract.** Your `conformanceFixture` has to hold your kind inside its **first** top-level block, or the run fails outright: the undo and clipboard cells drive the fixture's first block and ride a throwaway neighbour block the kit adds beside it (after it for the undo cell, on each side in turn for the clipboard cell). A kind that only ever appears nested still enrolls, seated inside the first block; its clipboard cell then reports `boundary`, because its bytes get copied as part of the enclosing container.
+**The fixture contract.** Your `conformanceFixture` has to hold your kind inside its **first** top-level block, or the run fails outright: the undo and clipboard cells drive the fixture's first block and ride a throwaway neighbour block the kit adds beside it (after it for the undo cell, on each side in turn for the clipboard cell). A kind that only ever appears nested still enrolls, sitting inside the first block; its clipboard cell then reports `boundary`, because its bytes get copied as part of the enclosing container.
 
 Where a cell claims a mechanism the runner can't reach generically (a kind-specific copy, say), supply the check yourself: `runKindConformance(kind, { cells: { clipboard: { check: async (ctx) => … } } })`, where `ctx` hands you the parsed fixture and your kind's node. A custom check is only accepted on a cell you declared `implemented`; anywhere else it would contradict the declaration and silence the check for the mode you did declare.
 
@@ -254,18 +260,19 @@ The clipboard executor is also exported on its own as `checkCopyIsRawByteSlice(k
 
 **`runContainerConformance(kind, profile)`**
 
-The harness the built-in containers are held to, pointed at your own container kind. The profile carries your fixtures plus a coverage declaration per cell; the kit parses its way to your kind, so register the plugin before running it. The cells:
+The harness the built-in containers are held to, pointed at your own container kind. The profile carries your fixtures plus a coverage declaration per cell; the kit parses its way to your kind, so register the plugin before running it. Each cell checks the node of your kind its fixture points at: the end of `containerChain` for `localIndex`, the first block of `terminatorCollisionFixture`, the first one anywhere in `focusSource` and `deepNesting`. If something else sits there, the cell fails, so a chain that drifted onto a blockquote can't pass on the blockquote's behalf. The cells:
 
-| Cell                  | What it holds you to                                                                                                                                                                                                                                                                                                                                           |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `localIndex`          | Children are addressed by their index inside your container at each nesting level, not by a document-wide count                                                                                                                                                                                                                                                |
-| `ancestry`            | An edit deep inside rebuilds bytes innermost-first, so the outermost block's raw reflects the leaf change                                                                                                                                                                                                                                                      |
-| `multiScope`          | One operation spanning two nesting levels pushes exactly one undo entry. The kit only owns such an operation for the built-in list and table, so a plugin kind declares this cell `exempt`                                                                                                                                                                     |
-| `focusBubble`         | A focus move leaving your top edge reaches the document root exactly once, with no loop and no double-escape                                                                                                                                                                                                                                                   |
-| `terminatorCollision` | A body line reproducing your container's own closing line stays inside the container                                                                                                                                                                                                                                                                           |
-| `declarations`        | The kit's own cell, always on. Your `unwrapRole` names strategies that exist, `containerPaste` is shaped right, `rebuildRaw` re-emits the parsed bytes and answers its changed-child shortcut with the same bytes as a full rebuild, `bodyWrap` matches what your parse does, and a declared `contentStartSpace` gives the user's space back on a content line |
+| Cell                  | What it holds you to                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `localIndex`          | Children are addressed by their index inside your container at each nesting level, not by a document-wide count. A grid container declares it `boundary`, since the kit only knows how to drive a grid operation for the built-in table                                                                                                                                                                                                                                          |
+| `ancestry`            | An edit deep inside rebuilds bytes innermost-first, so the outermost block's raw reflects the leaf change                                                                                                                                                                                                                                                                                                                                                                        |
+| `multiScope`          | One operation spanning two nesting levels pushes exactly one undo entry. The kit only drives such an operation for the built-in list and table, so a plugin kind declares this cell `exempt` (or `boundary`, if it does own one)                                                                                                                                                                                                                                                 |
+| `focusBubble`         | A focus move leaving your top edge reaches the document root exactly once, with no loop and no double-escape                                                                                                                                                                                                                                                                                                                                                                     |
+| `terminatorCollision` | A body line reproducing your container's own closing line stays inside the container                                                                                                                                                                                                                                                                                                                                                                                             |
+| `titleRow`            | Always on, and excused for a kind with no title row (`reservedChrome`) or one that isn't opaque. It needs your kind's own `conformanceFixture` to type in: it types into your title row the way a keystroke does, then checks your block against a fresh parse of its bytes, metadata included. The editor doesn't re-read your metadata on a title keystroke, so none of it may come from the title's bytes                                                                     |
+| `declarations`        | The kit's own cell, always on, and it also needs your kind's `conformanceFixture` (a top-level block of your kind; a grid container needs none). Your `unwrapRole` names strategies that exist, `containerPaste` is shaped right, `rebuildRaw` re-emits the parsed bytes and answers its changed-child shortcut with the same bytes as a full rebuild, `bodyWrap` matches what your parse does, and a declared `contentStartSpace` gives the user's space back on a content line |
 
-You supply the fixtures. For the guide's `:::conspiracy` container ([the walkthrough](plugin-guide.md#walkthrough-a-conspiracy-container-end-to-end)), a full profile looks like this:
+You supply the fixtures, on top of the `conformanceFixture` your descriptor already carries. For the guide's `:::conspiracy` container ([the walkthrough](plugin-guide.md#walkthrough-a-conspiracy-container-end-to-end)), a full profile looks like this:
 
 ```ts
 import { declaredPluginKind } from '@voithos-labs/aragonite/plugin';
@@ -282,7 +289,7 @@ it('the conspiracy container conforms', async () => {
 		// Nested fences need the outer one longer, hence the four colons.
 		localIndexFixture: {
 			source:
-				'::::conspiracy Big Bird is three kids in a coat\neyewitness sketch\n:::debunked The coat theory\nwool receipts\nthe coat has an alibi\n:::\n::::\n',
+				'::::conspiracy Big Bird is three kids in a coat\neyewitness sketch\n:::debunked The coat theory\nwool receipts\n\nthe coat has an alibi\n:::\n::::\n',
 			containerChain: [0, 2],
 			targetChild: 2
 		},
@@ -310,9 +317,10 @@ report.cells.map((c) => `${c.cell}: ${c.status}`);
 // [
 //   'localIndex: asserted',
 //   'ancestry: asserted',
-//   'multiScope: exempt',   // report.cells[2].reason is your sentence
+//   'multiScope: exempt',   // report.cells[2].detail is your sentence
 //   'focusBubble: asserted',
 //   'terminatorCollision: asserted',
+//   'titleRow: asserted',
 //   'declarations: asserted'
 // ]
 ```
@@ -326,14 +334,14 @@ Error: container conformance failed for "conspiracy":
 
 Two notes on those fixtures. `localIndexFixture` has to edit a non-first child **or** descend through a non-zero chain position (that's the failure above): at chain `[0, 0]`, child 0, a local path and a flat global offset are the same number and the check proves nothing (the fixture above does both, since Big Bird deserves rigor). And `terminatorCollisionFixture.bodyRaw` names the bytes a **user types**, not the bytes that reach the tree: the kit writes them through your `bodyWrite` rule, the same route a real commit uses.
 
-**`terminatorCollision` is the cell most container authors haven't considered**, and the profile type requires a declaration, so a profile written before the cell existed stops compiling until you answer it. If your container wraps body bytes between an opener and a closing line, a body line that reproduces that closing line ends it early, and everything below leaves the container the next time the document is parsed. A byte round-trip can't catch it, because the bytes come back out verbatim either way; only the live tree disagrees with them. So this cell's oracle is convergence instead: the live tree has to agree with a fresh parse of its own bytes.
+**`terminatorCollision` is the cell most container authors haven't considered**, and the profile type requires a declaration, so a profile written before the cell existed stops compiling until you answer it. If your container wraps body bytes between an opener and a closing line, a body line that reproduces that closing line ends it early, and everything below leaves the container the next time the document is parsed. A byte round-trip can't catch it, because the bytes come back out verbatim either way; only the live tree disagrees with them. So this cell checks convergence instead: the live tree has to agree with a fresh parse of its own bytes, block by block, on the kind, the children, and every key of the metadata.
 
 Whether you may excuse it, and how to fix a real collision, depends on your terminator's shape:
 
 - **Fence-shaped** terminators escalate: the `:::` containers lengthen their fence past the body's runs, and the editor does that for you, so the conspiracy above asserts the cell and passes without writing a line.
-- A **strip** container (one that prefixes every line it emits, the blockquote shape) is immune, and is the one shape allowed to declare the cell `exempt`. An opaque container may not: the `declarations` cell fails a profile that tries.
+- A **strip** container (one that prefixes every line it emits, the blockquote shape) is immune, and is the one shape allowed to declare the cell `exempt`. An opaque container may not: the kit fails the cell if you excuse it.
 - A **fixed-token** terminator, an HTML close tag say, can neither escalate nor prefix; it repairs the collision with [`bodyWrite`](#making-body-bytes-legal-bodywrite), rewriting the offending bytes on the way **in**, so the child's own raw carries the rewrite and nothing diverges.
-- A **childless** container whose body lives in metadata supplies the optional `writeBody` on the fixture, so the collision probe reaches a body no child carries.
+- A **childless** container whose body lives in metadata supplies the optional `writeBody` on the fixture, so the collision probe reaches a body no child carries. The kit then rebuilds the way a commit does, so a fence your rebuild grew is already re-read into your metadata when the compare runs.
 
 Escaping at the rebuild is the one repair that doesn't work, and it's the tempting one: an opaque container's raw is checked against its live children, so rewriting a child on the way out reads as staleness. Rewriting on the way in, before the bytes are reparsed, leaves no such gap.
 
@@ -349,9 +357,9 @@ It has to be `true` for a container whose `rebuildRaw` reads only its direct chi
 
 A container whose opener parses its body through `parseContainerBody` declares the same wrap as `container.bodyWrap`, and the `declarations` cell probes your parse in both directions, failing a declaration that doesn't match what the parse actually does. Why the editor needs telling at all:
 
-- The parse peels the blank line against your opener into `innerPrefix` (the node field that holds it), so that line belongs to the wrap rather than being an empty first row. The editor's blank-line bookkeeping has to know that, or a delete that frees a blank line above your body's first block eats the line the peel owns, and that block disappears on the next load.
+- The parse moves the blank line against your opener into `innerPrefix` (the node field that holds it), so that line belongs to the wrap rather than being an empty first row. The editor's blank-line bookkeeping has to know that, or a delete that frees a blank line above your body's first block eats the line the peel owns, and that block disappears on the next load.
 - A strip container whose body starts at its own first line declares nothing, and then carries no `innerPrefix` either; a dev-mode check on the node's shape fails a wrap-less container that fills that slot.
-- A childless container whose body lives in metadata has no body child to peel a line from, so it declares nothing too, and the kit fails a declaration there as well.
+- A childless container whose body lives in metadata has no body child to take a line from, so it declares nothing too, and the kit fails a declaration there as well.
 
 #### Making body bytes legal: `bodyWrite`
 
@@ -362,8 +370,8 @@ container: {
 	contract: 'opaque',
 	rebuildRaw: rebuildMyRaw,
 	bodyWrite: {
-		normalize: (raw) => /* raw, made legal as a child of this container */,
-		mapOffset: (raw, offset) => /* where a caret at `offset` ends up after that */
+		normalize: (raw, ctx) => /* raw, made legal as a child of this container */,
+		mapOffset: (raw, offset, ctx) => /* where a caret at `offset` ends up after that */
 	}
 }
 ```
@@ -373,13 +381,13 @@ container: {
 - **Idempotent**: re-committing already-legal bytes changes nothing.
 - **Line-local**: it may read the whole raw to decide which lines to rewrite, but it never moves bytes across a line boundary.
 
-`mapOffset` is the rewrite's caret image: where a caret sitting at some offset in the typed bytes ends up in the committed ones. The pair ships as one object because a rewrite without its caret image strands the caret. The bundled `details` container's pair, over a body line that would close it early:
+`mapOffset` is the rewrite's caret image: where a caret sitting at some offset in the typed bytes ends up in the committed ones. The pair ships as one object, the `WriteRule` shape a kind's own `rawWrite` shares, because a rewrite without its caret image strands the caret. `ctx.node` is the container, and a body write is always `literal`. The bundled `details` container's pair, over a body line that would close it early:
 
 ```ts
 const typed = 'exhibit A\n</details>\nexhibit B\n';
-normalize(typed); // 'exhibit A\n&lt;/details>\nexhibit B\n'
-mapOffset(typed, 5); // 5, nothing changed before it
-mapOffset(typed, 21); // 24, the escape ahead of it grew the text by three
+normalize(typed, ctx); // 'exhibit A\n&lt;/details>\nexhibit B\n'
+mapOffset(typed, 5, ctx); // 5, nothing changed before it
+mapOffset(typed, 21, ctx); // 24, the escape ahead of it grew the text by three
 ```
 
 Two rules of thumb from that container. Ask the **grammar**, not your own spelling: what breaks `details` is everything the Markdown spec hands to raw-HTML passthrough, indented, upper-cased and trailing-space spellings included, which is looser than the canonical form your `rebuildRaw` emits, and `htmlBlockTagLineMatcher` from `@voithos-labs/aragonite/plugin` answers that question for a tag name. And rewrite the **minimum**: `details` escapes one `<` to `&lt;`, which renders as the literal tag both in the editor and on GitHub while matching no tag line, so the author still sees what they typed.
@@ -388,12 +396,12 @@ Two rules of thumb from that container. Ask the **grammar**, not your own spelli
 
 **`runInlineKindConformance(profile)`**
 
-The same idea one layer down: register your rung (one level in the ordered ladder of recognizers consulted for your trigger), then point the kit at it and it drives the behaviors a rung can break without moving a byte. The profile's fields, before the cells:
+The same idea one layer down: register your recognizer (the `registerInlineSyntax` call, one of possibly several asked in priority order at your trigger character), then point the kit at it and it drives the behaviors a recognizer can break without moving a byte. The profile's fields, before the cells:
 
 - `trigger`: the single character you registered on.
 - `prefix`: your multi-character opener. Omit it for a bare-trigger registration.
-- `priority`: only when two rungs share a prefix at different priorities; it says which one is yours.
-- `kind`: the inline kind you mint (minted: created by the one authorized place; a duplicate throws). Omit it for a recognizer that only builds built-in nodes over its own bytes.
+- `priority`: only when two registrations share a prefix at different priorities; it says which one is yours.
+- `kind`: the inline kind you created with `declarePluginInlineKind`. Omit it for a recognizer that only builds built-in nodes over its own bytes.
 - `fixtures`: single-line sources your recognizer claims; `overlapFixtures`: sources it must decline (the star cell below).
 
 The cells:
@@ -405,16 +413,16 @@ The cells:
 | `overlapDecline` | Where your prefix also opens something the built-in scanner owns, you decline it                                                                                      |
 | `widget`         | Your claimed bytes are one atomic unit, and your rendered widget spans exactly the bytes it stands for                                                                |
 | `editingPolicy`  | Your widget's editing declaration exists, is in the vocabulary the caret-edge dispatch actually reads, and (for one-press delete) leaves bytes behind that round-trip |
-| `imageClaim`     | A rung whose recognizer builds built-in nodes carries the `rewriteImage` hook the write paths need                                                                    |
-| `registration`   | Your rung is actually registered where your profile says it is                                                                                                        |
+| `imageClaim`     | A recognizer that builds built-in nodes comes with the `rewriteImage` hook the write paths need                                                                       |
+| `registration`   | Your recognizer is registered the way your profile says, alone at its prefix and priority                                                                             |
 
-`claims`, `roundTrip`, and `registration` always run; the other four you declare. For the [guide's](plugin-guide.md#inline-kinds) `![[…]]` embed, in the variant that mints its own kind:
+`claims`, `roundTrip`, and `registration` always run; the other four you declare. Here's a profile for an `![[…]]` embed like the [guide's](plugin-guide.md#inline-kinds), in a variant that declares its own `EMBED` kind and renders it with a Svelte component (the guide's own builds built-in images instead):
 
 ```ts
 import { runInlineKindConformance } from '@voithos-labs/aragonite/testing';
 
-it('the embed recognizer conforms', () => {
-	runInlineKindConformance({
+it('the embed recognizer conforms', async () => {
+	await runInlineKindConformance({
 		trigger: '!',
 		prefix: '![[',
 		kind: declaredPluginInlineKind(EMBED),
@@ -428,36 +436,42 @@ it('the embed recognizer conforms', () => {
 });
 ```
 
-(The guide's other embed variant builds real built-in images; that one asserts `imageClaim` instead, and excuses `widget` and `editingPolicy`, since a built-in kind renders through the built-in widget.)
+(The guide's own embed, the one that builds real built-in images, asserts `imageClaim` instead, and excuses `widget` and `editingPolicy`, since a built-in kind renders through the built-in widget.)
 
-This kit answers synchronously, and its `detail` strings say how much each cell actually chewed through. For that profile, with the embed rendered by a Svelte `component`, under jsdom:
+Its `detail` strings say how much each cell actually chewed through. For that profile, with the embed rendered by a Svelte `component`, under jsdom:
 
 ```ts
-const report = runInlineKindConformance(profile);
+const report = await runInlineKindConformance(profile);
 report.cells.map((c) => `${c.cell}: ${c.status} (${c.detail})`);
 // [
 //   'claims: asserted (2 claim(s) across 2 fixture(s))',
 //   'roundTrip: asserted (20 source(s) round-trip byte-for-byte and tile their scan range)',
 //   'overlapDecline: asserted (1 prefix position(s) declined across 1 overlap fixture(s))',
-//   'widget: boundary (recognition + self-delimiting claim executed; the island wrapper of a `component` kind is minted by the render layer ...)',
+//   'widget: boundary (recognition + self-delimiting claim executed; the widget wrapper of a `component` kind is created by the render layer ...)',
 //   'editingPolicy: asserted (policy vocabulary)', // plus a whole-delete check if your policy says atomic
 //   'imageClaim: exempt (this recognizer builds only its own kind, never a built-in one)',
 //   'registration: asserted (prefix rung at priority 40, below the built-in boundary)'
 // ]
 ```
 
-Twenty sources on the round-trip cell, from two fixtures: the kit interleaves each one with ten neighbours (emphasis around it, a link around it, a blockquote in front, your own trigger on either edge, and so on). A profile the kit refuses throws before any cell runs, with the plain reason:
+Twenty sources on the round-trip cell, from two fixtures: the kit runs each one alone and in nine interleavings with other syntax (emphasis around it, a link around it, a blockquote in front, your own trigger on either edge, and so on). A profile the kit refuses throws before any cell runs, with the plain reason:
 
 ```
 Error: overlapDecline asserts but the profile supplies no overlapFixtures
 ```
 
-`fixtures` is required and non-empty, and a fixture your recognizer doesn't claim **fails** rather than being skipped: every cell reads the nodes a fixture produces, so an unclaimed one would enroll your syntax without testing it.
+`fixtures` is required and non-empty, and a fixture your recognizer doesn't claim **fails** rather than being skipped: every cell reads the nodes a fixture produces, so an unclaimed one would enroll your syntax without testing it. `widget` and `editingPolicy` only look at the nodes of your `kind` (built-in nodes your recognizer builds are `imageClaim`'s job), so if none of your fixtures produce your kind, an asserted `widget` fails instead of passing over some images, and so does an asserted `editingPolicy` whose policy deletes the widget in one press.
 
-**`overlapDecline` is the cell most inline authors haven't considered, and on a reserved trigger it's required.** Registering on a trigger the built-in scanner owns (`[`, `!`, `*`, `` ` ``, and friends) puts your recognizer ahead of the built-in case, so wherever your prefix matches you're claiming those bytes whether or not they spell something the built-in owns. `![[a]](https://x.dev)` is a plain image whose alt text is `[a]`; a recognizer that claims every `![[…]]` takes it, and the document still round-trips, as a wiki embed nobody ever wrote. Supply the sources where your grammar and a built-in one collide; the kit consults your recognizer at every position the scanner would and requires a decline at each, which is exactly what leaves the built-in reading unchanged bytes. A rung on a reserved trigger may not excuse this cell at all, since the overlap exists by construction.
+**`overlapDecline` is the cell most inline authors haven't considered, and on a reserved trigger it's required.** Registering on a trigger the built-in scanner owns (`[`, `!`, `*`, `` ` ``, and friends) puts your recognizer ahead of the built-in case, so wherever your prefix matches you're claiming those bytes whether or not they spell something the built-in owns. `![[a]](https://x.dev)` is a plain image whose alt text is `[a]`; a recognizer that claims every `![[…]]` takes it, and the document still round-trips, as a wiki embed nobody ever wrote. Supply the sources where your grammar and a built-in one collide; the kit consults your recognizer at every position the scanner would and requires a decline at each, which is exactly what leaves the built-in reading unchanged bytes. A recognizer on a reserved trigger may not excuse this cell at all, since the overlap exists by construction.
 
-The other three cells you declare, because only you know whether they have anything to bite on. But an excuse the kit can falsify, it falsifies: declaring `imageClaim` exempt while a fixture produces a stamped built-in (a built-in node the scan marked as your rung's) fails, as does excusing `widget` for a kind that **is** a registered live widget, or `editingPolicy` for a kind that declares one.
+The other three cells you declare, because only you know whether they have anything to bite on. But an excuse the kit can falsify, it falsifies: declaring `imageClaim` exempt while a fixture produces a stamped built-in (a built-in node the scan marked as your recognizer's) fails, as does excusing `widget` for a kind that **is** a registered live widget, or `editingPolicy` for a kind that declares one.
 
 Two things worth knowing about `widget`. It asserts your claimed slice is **self-delimiting**: re-scanning the slice alone must re-form the same kind over its whole length, because that slice is exactly what the widget's `data-source-*` attributes (the ones saying which bytes it stands for) hand the clipboard and a source reveal. And where your kind builds its own widget DOM (`buildWidget`), the kit renders your fixture and measures the caret walk across it, which must equal the source length: a widget counts as its source span, never as what it draws, so an emoji showing one glyph for seven bytes still walks seven. A `component` kind's wrapper is built by the editor, not by you, so that half doesn't run and the cell reports `boundary` rather than claiming a pass (that's the report above). Run the suite under a DOM (`// @vitest-environment jsdom` for Vitest); without one the rendering half can't run either, and the cell again reports `boundary` naming what you lost, while the recognition and self-delimiting checks still execute.
 
-`registration` is the thinnest cell and the one that caught a real bug. `registerInlineSyntax` already refuses most bad registrations up front, so those are cross-checks on the editor rather than things you can get wrong. What you _can_ get wrong is your rung not being there at all: a setup step that ran under the wrong guard, or an install order that let another plugin's registration on a shared trigger stand in for yours. That's what this cell goes red on, and it's how the bundled directive text tier's own recognizer was once found missing.
+`registration` is the thinnest cell. It checks three things:
+
+- yours is the only registration at its prefix and priority;
+- on a reserved trigger, your prefix is two or more characters and your priority sits below `INLINE_PRIORITIES.builtin`;
+- on a trigger no built-in owns, the scan actually visits that character.
+
+`registerInlineSyntax` already refuses most of that up front, so those are cross-checks on the editor rather than things you can get wrong. What you _can_ get wrong is your recognizer not being there at all (a setup step that ran under the wrong guard, say), and that one doesn't wait for the cell: the run throws before any cell starts, telling you to register the plugin first.

package/package.json

@@ -1,21 +1,11 @@
 {
 	"name": "@voithos-labs/aragonite",
-	"version": "0.10.4",
+	"version": "0.10.7",
 	"description": "cute svelte-based markdown editor lib",
 	"keywords": [
-		"markdown",
-		"gfm",
 		"editor",
-		"block-editor",
-		"wysiwyg",
-		"contenteditable",
-		"syntax-tree",
-		"svelte",
-		"markdown-editor",
-		"lossless",
-		"plugin",
-		"commonmark",
-		"svelte5"
+		"markdown",
+		"svelte"
 	],
 	"homepage": "https://aragonite.dev",
 	"bugs": {
@@ -99,6 +89,11 @@
 			"svelte": "./dist/plugins/highlight-occurrences/index.js",
 			"default": "./dist/plugins/highlight-occurrences/index.js"
 		},
+		"./plugins/slash-commands": {
+			"types": "./dist/plugins/slash-commands/index.d.ts",
+			"svelte": "./dist/plugins/slash-commands/index.js",
+			"default": "./dist/plugins/slash-commands/index.js"
+		},
 		"./testing": {
 			"types": "./dist/testing.d.ts",
 			"svelte": "./dist/testing.js",
@@ -217,7 +212,7 @@
 		"eslint-plugin-svelte": "^3.23.0",
 		"fast-check": "^4.9.0",
 		"globals": "^17.11.0",
-		"jsdom": "^30.0.0",
+		"jsdom": "30.0.1",
 		"katex": "^0.18.4",
 		"mermaid": "^12.0.0",
 		"prettier": "^3.9.6",
@@ -229,10 +224,11 @@
 		"typescript-eslint": "^8.67.0",
 		"vite": "^8.2.2",
 		"vitest": "^5.0.0",
-		"wrangler": "4.131.1"
+		"wrangler": "4.144.0"
 	},
 	"overrides": {
-		"cookie": "^0.7.2"
+		"cookie": "^0.7.2",
+		"lodash-es": "^4.18.0"
 	},
 	"publishConfig": {
 		"access": "public"

package/dist/ambient/ambient-cursor.d.ts

@@ -1,41 +0,0 @@
-/**
- * Ambient-aware cursor I/O for prose contenteditable surfaces: raw ↔ DOM offset
- * translation that respects the leading ambient marker span a container block contributes
- * to its first prose child. Zero-ambient surfaces are first-class consumers —
- * `getAmbientLength: () => 0` reduces this to plain widget-aware translation.
- */
-import { type RawOffset } from '../cursor/coordinate-spaces';
-export interface AmbientCursorDeps {
-    getEl: () => HTMLElement | null | undefined;
-    getAmbientLength: () => number;
-    /**
-     * Logical caret position (raw units) when the live DOM range is gone or trapped — the
-     * "user clicked here" intent that survives Chromium dropping element-level carets
-     * across event-loop yields. Null when no snap intent is active.
-     */
-    getSnapTarget?: () => number | null;
-}
-export interface AmbientCursorIO {
-    /** Raw offset of the collapsed caret, or null if no selection inside `el`. */
-    getRaw(): RawOffset | null;
-    /** Move the caret to the given raw offset. Offsets at/before the ambient
-     * boundary land just after the marker span. */
-    setRaw(offset: RawOffset): void;
-    /** Raw offsets of the anchor/focus endpoints of the current selection, or null. */
-    getRawSelection(): {
-        start: RawOffset;
-        end: RawOffset;
-    } | null;
-    /** Raw offsets of an arbitrary range inside this surface — an InputEvent's target range, which
-     *  a word delete reports at a COLLAPSED caret and the selection therefore cannot answer. */
-    rawRangeOf(range: AbstractRange): {
-        start: RawOffset;
-        end: RawOffset;
-    } | null;
-    /** Ensure the caret sits outside the ambient marker region. No-op when `el`
-     * isn't the active element or the caret is already out. */
-    clampOutOfAmbient(): void;
-    /** Park the caret immediately after the ambient span — used as the raw-0 landing. */
-    setToAmbientBoundary(): void;
-}
-export declare function createAmbientCursorIO(deps: AmbientCursorDeps): AmbientCursorIO;