@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/testing/kind-conformance.js

@@ -1,101 +1,94 @@
 /**
- * The generic per-kind conformance battery — the executable half of the closure matrix.
- * Registering a block kind enrolls it: one cell per `ClosureColumn`, derived from the
- * kind's `closure` block and `conformanceFixture`. A cell is executed only where its
- * mechanism is headlessly observable; everything else is recorded as `boundary` or
- * `exempt`, never stubbed green. Runner-agnostic — plain `Error`s, no runner import.
+ * The generic per-kind conformance battery: registering a block kind enrolls it, one cell per
+ * `ClosureColumn` plus the raw-write cell, read from its descriptor and `conformanceFixture`. A
+ * cell runs only where headless code can observe what it checks; the rest is reported `boundary`
+ * or `exempt`, never stubbed green.
  */
-import { displayLength, trimTrailingLineEnding } from '../core/lines';
+import { displayLength, documentLineEnding, ownTrailingLineEnding, trimTrailingLineEnding } from '../core/lines';
 import { parse } from '../core/parser';
 import { serialize } from '../core/serializer';
-import { getBlockKindDescriptor } from '../schema/block-kind-descriptor';
+import { CLOSURE_COLUMNS } from '../schema/closure';
+import { getBlockKindDescriptor, isGridDescriptor } from '../schema/block-kind-descriptor';
 import { isMergeEligible } from '../schema/merge-rules';
 import { isWholeBlockUnit } from '../schema/whole-block-unit';
 import { collectCrossBlockText } from '../selection/clipboard-text';
+import { coverRange, rangeCoverage } from '../selection/range-coverage';
 import { createSelectionState } from '../selection/selection-state.svelte';
 import { pathsEqual } from '../selection/path-math';
 import { scanDocument } from '../search/document-scan';
 import { compileMatcher } from '../search/matcher';
 import { createBlockEditActions } from '../editor-actions/block-edit';
 import { createUndoController } from '../editor-actions/commit/undo-controller';
-import { assert, assertIs, assertReasonDocumented, assertRebuildIsParseCanonical, fail, findFirstPathOfKind, nodeAtPath } from './conformance-core';
+import { assert, assertIs, assertRebuildIsParseCanonical, fail, nodeAtPath, runCells, show, subjectNode, subjectPath } from './conformance-core';
+import { installOwnRaw } from '../tree-operations/node-primitives';
+import { defaultGrammarView } from '../schema/block-openers';
 import { createHeadlessActions } from './headless-actions';
-// ── Runner ───────────────────────────────────────────────────────────────────
-const CLOSURE_ORDER = [
-    'roundTrip',
-    'focus',
-    'mergeBackspace',
-    'selectionPaint',
-    'searchPaint',
-    'reorder',
-    'undo',
-    'clipboard',
-    'simOracle'
-];
+import { assertParseConverged } from './parse-convergence';
 /**
- * Execute every headless closure cell for `kind`, or throw an `Error` naming each failed
- * cell. A `conformanceFixture` parsing to no node of the kind fails the run outright.
+ * Runs every headless closure cell for `kind`, or throws an `Error` naming each failed cell. A
+ * `conformanceFixture` that parses to no node of the kind fails the run outright.
  */
 export async function runKindConformance(kind, profile = {}) {
     const descriptor = getBlockKindDescriptor(kind);
-    const ctx = buildContext(kind, descriptor);
-    const cells = [];
-    const failures = [];
-    for (const column of CLOSURE_ORDER) {
-        const cell = descriptor.closure[column];
-        try {
+    const run = { kind, descriptor, parsed: buildContext(kind, descriptor) };
+    const columns = Object.keys(CLOSURE_COLUMNS);
+    const cells = [
+        ...columns.map((column) => {
             const custom = profile.cells?.[column]?.check;
-            const result = custom
-                ? await runCustomCheck(kind, column, cell, custom, ctx)
-                : await executeCell(column, cell, kind, descriptor, ctx);
-            if (result.status === 'exempt') {
-                assertReasonDocumented(result.detail, `${kind} ${column} exempt reason`);
-            }
-            cells.push({ column, mode: cell.mode, ...result });
-        }
-        catch (error) {
-            failures.push(`${column}: ${error.message}`);
-        }
-    }
-    if (failures.length > 0) {
-        fail(`kind conformance failed for "${kind}":\n  - ${failures.join('\n  - ')}`);
-    }
-    return { kind, cells };
+            return {
+                cell: column,
+                run: custom
+                    ? () => runCustomCheck(column, custom, run)
+                    : () => executeCell(column, descriptor.closure[column], run)
+            };
+        }),
+        { cell: 'rawWrite', run: execRawWrite }
+    ];
+    const reports = await runCells(cells, run, {
+        subject: kind,
+        heading: `kind conformance failed for "${kind}"`
+    });
+    return {
+        kind,
+        cells: reports.map((report) => report.cell === 'rawWrite'
+            ? report
+            : { ...report, mode: descriptor.closure[report.cell].mode })
+    };
 }
 function buildContext(kind, descriptor) {
     const fixture = descriptor.conformanceFixture;
     if (fixture === undefined)
         return null;
     const doc = parse(fixture);
-    const nodePath = findFirstPathOfKind(doc, kind);
-    if (!nodePath) {
-        fail(`kind conformance failed for "${kind}": conformanceFixture parses to no "${kind}" node`);
-    }
-    // The one place every executor receives the fixture, so the position contract they drive
-    // `doc.children[0]` on (undo deletes it, the byte-slice copy sweeps from it) is settled here.
+    const nodePath = subjectPath(doc, kind, 'first', `kind conformance failed for "${kind}": conformanceFixture`);
+    // Every check receives the fixture here, so the rule they rely on (the node at
+    // `doc.children[0]`) is enforced once: undo deletes it and the byte-slice copy starts from it.
     if (nodePath[0] !== 0) {
         fail(`kind conformance failed for "${kind}": conformanceFixture must open with the "${kind}" ` +
             `block (found under top-level index ${nodePath[0]}) — the kit drives the fixture's first ` +
             `block and rides its own sentinel beside it`);
     }
-    return { kind, descriptor, fixture, doc, node: nodeAtPath(doc, nodePath), nodePath };
+    return { kind, fixture, doc, node: nodeAtPath(doc, nodePath), nodePath };
 }
-async function runCustomCheck(kind, column, cell, check, ctx) {
-    // On any mode but `implemented` a custom check contradicts the declaration and would
-    // silence the declared-mode executor, so reverting a profiled cell's mode goes red.
-    if (cell.mode !== 'implemented') {
+async function runCustomCheck(column, check, { kind, descriptor, parsed }) {
+    const mode = descriptor.closure[column].mode;
+    // In any mode but `implemented` a custom check contradicts the declaration and would silence
+    // the check that mode would run, so changing a profiled cell's mode back fails.
+    if (mode !== 'implemented') {
         fail(`profile supplies a "${column}" check for "${kind}", but its declared mode is ` +
-            `"${cell.mode}" — a custom check is only valid on an 'implemented' cell`);
+            `"${mode}" — a custom check is only valid on an 'implemented' cell`);
     }
-    if (!ctx) {
+    if (!parsed) {
         fail(`profile supplies a "${column}" check but "${kind}" has no conformanceFixture to run it over`);
     }
-    await check(ctx);
-    return { status: 'executed', detail: 'profile custom check' };
+    await check(parsed);
+    return 'profile custom check';
 }
 // ── Cell executors ─────────────────────────────────────────────────────────
-const BROWSER_SWEEP = 'browser cell — executed in the browser sweep';
-async function executeCell(column, cell, kind, descriptor, ctx) {
+// aragonite's own e2e sweep runs these for the kinds its repository registers, never a plugin's.
+const BROWSER_ONLY = 'browser-only cell, for a browser test of your own';
+const NO_FIXTURE = 'no conformanceFixture, so unchecked: declare one for the kit to parse';
+async function executeCell(column, cell, { kind, descriptor, parsed: ctx }) {
     switch (column) {
         case 'roundTrip':
             return execRoundTrip(kind, descriptor, ctx);
@@ -108,16 +101,16 @@ async function executeCell(column, cell, kind, descriptor, ctx) {
         case 'clipboard':
             return execClipboard(cell, ctx);
         case 'focus':
-            return { status: 'boundary', detail: `native caret / focus policy — ${BROWSER_SWEEP}` };
+            return { status: 'boundary', detail: `native caret / focus policy: ${BROWSER_ONLY}` };
         case 'selectionPaint':
-            return { status: 'boundary', detail: `selection cover paint — ${BROWSER_SWEEP}` };
+            return { status: 'boundary', detail: `selection cover paint: ${BROWSER_ONLY}` };
         case 'reorder':
             return execReorder(cell);
         case 'simOracle':
             return {
                 status: 'boundary',
-                detail: 'note-taking simulation under the corruption oracles — run by the platform sweep ' +
-                    'over the kinds it enrolls, never by this runner'
+                detail: 'note-taking simulation under the corruption checks: run by aragonite over the ' +
+                    'kinds its own repository registers, never by this runner'
             };
     }
 }
@@ -125,28 +118,23 @@ function execRoundTrip(kind, descriptor, ctx) {
     if (!ctx) {
         return {
             status: 'boundary',
-            detail: `no conformanceFixture — round-trip runs in the ${BROWSER_SWEEP}`
+            detail: `round-trip: ${NO_FIXTURE}`
         };
     }
     assertIs(serialize(parse(ctx.fixture)), ctx.fixture, `serialize(parse(fixture)) round-trips for "${kind}"`);
     if (descriptor.rebuildRaw) {
-        const first = rebuildRawOf(kind, ctx.fixture, descriptor);
-        const second = rebuildRawOf(kind, ctx.fixture, descriptor);
+        const first = rebuildRawOf(ctx, descriptor);
+        const second = rebuildRawOf(ctx, descriptor);
         assertIs(first, second, `"${kind}" rebuildRaw is deterministic`);
-        assertRebuildIsParseCanonical(descriptor, nodeAtPath(parse(ctx.fixture), ctx.nodePath), `"${kind}"`);
-        return {
-            status: 'executed',
-            detail: descriptor.containerContract === 'grid'
-                ? 'byte round-trip + rebuildRaw determinism'
-                : 'byte round-trip + rebuildRaw parse-identity + determinism'
-        };
+        assertRebuildIsParseCanonical(descriptor, freshSubject(ctx), `"${kind}"`);
+        return isGridDescriptor(descriptor)
+            ? 'byte round-trip + rebuildRaw determinism'
+            : 'byte round-trip + rebuildRaw parse-identity + determinism';
     }
-    return { status: 'executed', detail: 'byte round-trip' };
+    return 'byte round-trip';
 }
-/**
- * An independent restatement of the merge-role → Backspace-merge table
- * (docs/design/editor.md); re-deriving it from `isMergeEligible` would be vacuous.
- */
+/** An independent restatement of the merge-role table (`docs/design/editor.md` § Merge
+ *  eligibility: roles, not pairs); derived from `isMergeEligible` it would test nothing. */
 const MERGE_ROLE_EXPECTATION = {
     prose: { currentIntoProse: true, prevForProse: true, self: true },
     'prose-absorber': { currentIntoProse: false, prevForProse: true, self: false },
@@ -159,11 +147,11 @@ function execMergeBackspace(kind, role) {
     assertIs(isMergeEligible('paragraph', kind), expected.currentIntoProse, `"${kind}" (${role}) Backspace-merges as the current block into a prose predecessor`);
     assertIs(isMergeEligible(kind, 'paragraph'), expected.prevForProse, `"${kind}" (${role}) absorbs a following prose block`);
     assertIs(isMergeEligible(kind, kind), expected.self, `"${kind}" (${role}) self-merge eligibility`);
-    return { status: 'executed', detail: `mergeRole=${role} eligibility` };
+    return `mergeRole=${role} eligibility`;
 }
 function execSearchPaint(cell, ctx) {
     if (cell.mode !== 'not-supported') {
-        return { status: 'boundary', detail: `search-match mark overlay — ${BROWSER_SWEEP}` };
+        return { status: 'boundary', detail: `search-match mark overlay: ${BROWSER_ONLY}` };
     }
     if (!ctx)
         return { status: 'exempt', detail: cell.reason };
@@ -173,19 +161,19 @@ function execSearchPaint(cell, ctx) {
     const compiled = compileMatcher(needle, { caseSensitive: true, wholeWord: false, regex: false });
     if (!compiled.ok)
         return { status: 'exempt', detail: cell.reason };
-    // Non-vacuity: the needle IS present in the raw, so no match can only mean the scan
-    // deliberately skips this non-searchable kind.
+    // The needle is present in the raw, so no match can only mean the search deliberately
+    // skips this non-searchable kind.
     assert(compiled.matcher.findAll(ctx.node.raw).length > 0, `needle "${needle}" is present in the "${ctx.kind}" raw`);
     const hits = scanDocument(ctx.doc, compiled.matcher).filter((m) => pathsEqual(m.path, ctx.nodePath));
     assertIs(hits.length, 0, `the document scan finds no match in the non-searchable "${ctx.kind}"`);
-    return { status: 'executed', detail: 'document scan finds no match (degradation)' };
+    return 'document scan finds no match (degradation)';
 }
 function execReorder(cell) {
     if (cell.mode === 'not-supported')
         return { status: 'exempt', detail: cell.reason };
     return {
         status: 'boundary',
-        detail: `block reorder is an Alt+Arrow / drag gesture — ${BROWSER_SWEEP}`
+        detail: `block reorder is an Alt+Arrow / drag gesture: ${BROWSER_ONLY}`
     };
 }
 async function execUndo(cell, ctx) {
@@ -194,25 +182,27 @@ async function execUndo(cell, ctx) {
     if (cell.mode === 'implemented') {
         return {
             status: 'boundary',
-            detail: `kind-specific undo mechanism — supply a profile check or run it in the ${BROWSER_SWEEP}`
+            detail: `kind-specific undo mechanism: supply a profile check or cover it in a browser test`
         };
     }
     if (!ctx)
         return {
             status: 'boundary',
-            detail: `no conformanceFixture — undo depth runs in the ${BROWSER_SWEEP}`
+            detail: `undo depth: ${NO_FIXTURE}`
         };
     const doc = parse(ctx.fixture + '\n\nundo sentinel\n');
     assert(doc.children.length > 1, `the kit's trailing sentinel parses beside the "${ctx.kind}" fixture rather than being ` +
         `swallowed by it, so there is a second block to delete`);
-    const { deps } = createHeadlessActions(doc.children);
+    // Block 0 is the one deleted, so the kind has to still sit under it with the sentinel added.
+    subjectPath(doc, ctx.kind, ctx.nodePath, 'conformanceFixture with the undo sentinel');
+    const { deps } = createHeadlessActions(doc);
     const controller = createUndoController(deps);
     const blockEdit = createBlockEditActions(deps, controller);
     const before = deps.undoManager.getStacks().undo.length;
-    await blockEdit.deleteBlock(0);
+    await blockEdit.deleteBlock(0, 'keyless');
     const after = deps.undoManager.getStacks().undo.length;
     assertIs(after - before, 1, `one structural op pushes exactly one undo entry over the "${ctx.kind}" fixture`);
-    return { status: 'executed', detail: 'one structural op → one undo entry' };
+    return 'one structural op → one undo entry';
 }
 function execClipboard(cell, ctx) {
     if (cell.mode === 'not-supported')
@@ -220,45 +210,61 @@ function execClipboard(cell, ctx) {
     if (cell.mode === 'implemented') {
         return {
             status: 'boundary',
-            detail: `kind-specific clipboard mechanism — supply a profile check or run it in the ${BROWSER_SWEEP}`
+            detail: `kind-specific clipboard mechanism: supply a profile check or cover it in a browser test`
         };
     }
     if (!ctx)
         return {
             status: 'boundary',
-            detail: `no conformanceFixture — copy runs in the ${BROWSER_SWEEP}`
+            detail: `copy: ${NO_FIXTURE}`
         };
     if (ctx.nodePath.length !== 1) {
         return {
             status: 'boundary',
-            detail: 'nested kind — copied as part of its container; the enclosing container cell covers its bytes'
+            detail: 'nested kind: copied as part of its container; the enclosing container cell covers its bytes'
         };
     }
     checkCopyIsRawByteSlice(ctx.kind, ctx.fixture);
-    return { status: 'executed', detail: 'copy is a raw byte slice (no synthesis)' };
+    return 'copy is a raw byte slice (no synthesis)';
+}
+function execRawWrite({ kind, descriptor, parsed: ctx }) {
+    const hasTopLevelFixture = ctx !== null && ctx.nodePath.length === 1;
+    if (!descriptor.rawWrite) {
+        if (!hasTopLevelFixture) {
+            return {
+                status: 'exempt',
+                detail: 'declares no rawWrite and has no top-level conformanceFixture to cut'
+            };
+        }
+        checkClosingCutNeedsNoRule(kind, ctx.fixture);
+        return 'declares no rawWrite, and the closing line cut leaves the next block its own';
+    }
+    if (!hasTopLevelFixture) {
+        return {
+            status: 'boundary',
+            detail: 'declares rawWrite but has no top-level conformanceFixture to write over'
+        };
+    }
+    checkLeafRawWrite(kind, ctx.fixture);
+    return 'five writes, each idempotent, leaving the next block its own, caret map agreeing';
 }
 // ── Exported executors (direct-drive for regression tests) ───────────────────
 const TRAILING_SENTINEL = '\n\nclipboard sentinel\n';
 const LEADING_SENTINEL = 'clipboard lead\n\n';
-/**
- * Assert the default cross-block copy over `kind`'s fixture carries its bytes with no
- * kind-specific synthesis, at BOTH endpoint roles — the honest meaning of
- * `clipboard: inherit-default`. Endpoints ride the real selection funnel, so the expectation is
- * the contract, never a re-derivation of the slice under test. Fixture contract: `fixture`
- * parses to `kind` at `children[0]`; the kit adds its sentinel block on the sweeping side.
- */
+/** Asserts the default cross-block copy over `kind`'s fixture is a raw byte slice at both endpoint
+ *  roles, which is what `clipboard: inherit-default` means; the fixture opens with `kind`. */
 export function checkCopyIsRawByteSlice(kind, fixture) {
-    assertIs(parse(fixture).children[0]?.kind, kind, `"${kind}" is the top-level copy subject: a conformanceFixture must parse to its kind ` +
-        `at children[0], and the kit adds its own sentinel block on the sweeping side`);
+    subjectNode(parse(fixture), kind, [0], `the copy fixture (a conformanceFixture must parse to its kind at children[0], and the kit ` +
+        `adds its own sentinel block on the sweeping side)`);
     checkCopyFromKind(kind, fixture);
     checkCopyIntoKind(kind, fixture);
 }
-/** The kind as the range START: its tail, then the sentinel's head. */
+/** The kind as the start of the range: its tail, then the sentinel's head. */
 function checkCopyFromKind(kind, fixture) {
     const doc = parse(fixture + TRAILING_SENTINEL);
     const lastIndex = doc.children.length - 1;
     assert(lastIndex >= 1, 'fixture + sentinel yields a second block to copy across');
-    const kindNode = doc.children[0];
+    const kindNode = subjectNode(doc, kind, [0], 'the copy fixture');
     const sentinel = doc.children[lastIndex];
     const startOffset = interiorOffset(kindNode);
     const endOffset = displayLength(sentinel.raw);
@@ -269,13 +275,14 @@ function checkCopyFromKind(kind, fixture) {
         sentinel.leadingTrivia +
         sentinel.raw.slice(0, endOffset), `"${kind}" copy is a raw byte slice — no kind-specific synthesis`);
 }
-/** The kind as the range END, the role a start-only check never exercises. */
+/** The kind as the end of the range, the role a start-only check never exercises. */
 function checkCopyIntoKind(kind, fixture) {
     const doc = parse(LEADING_SENTINEL + fixture);
-    const kindIndex = doc.children.length - 1;
+    // Counted from the end, since a fixture may carry blocks after its kind.
+    const kindIndex = doc.children.length - parse(fixture).children.length;
     assert(kindIndex >= 1, 'sentinel + fixture yields a block to copy across from');
     const sentinel = doc.children[0];
-    const kindNode = doc.children[kindIndex];
+    const kindNode = subjectNode(doc, kind, [kindIndex], 'the copy fixture after the sentinel');
     const startOffset = interiorOffset(sentinel);
     const copied = copyThroughFunnel(doc, { path: [0], offset: startOffset }, { path: [kindIndex], offset: interiorOffset(kindNode) });
     const head = isWholeBlockUnit(kindNode)
@@ -293,26 +300,27 @@ function bytesBetween(children, from, to) {
         .map((node) => node.leadingTrivia + node.raw)
         .join('');
 }
-/**
- * The production mint→store→slice chain: endpoints normalize in `SelectionState` exactly as a
- * gesture's would, so a kind whose offsets the funnel rewrites is copied as the editor copies it.
- */
+/** Copies through the production selection code, so a kind whose endpoints `SelectionState`
+ *  normalizes is copied the way the editor copies it. */
 function copyThroughFunnel(doc, anchor, focus) {
     const selection = createSelectionState({ getDoc: () => doc });
     selection.enterCrossBlock(anchor, focus);
     const { start, end } = selection;
     if (!start || !end)
         fail('the selection funnel refused the cross-block endpoint pair');
-    return collectCrossBlockText(doc, start, end);
+    return collectCrossBlockText(doc, rangeCoverage(doc, coverRange(doc, start, end)));
 }
 /** An offset strictly inside the block, so a kind that snaps its endpoints is seen doing it. */
 function interiorOffset(node) {
     return displayLength(node.raw) > 1 ? 1 : 0;
 }
 // ── Internal helpers ─────────────────────────────────────────────────────────
-function rebuildRawOf(kind, fixture, descriptor) {
-    const doc = parse(fixture);
-    const node = nodeAtPath(doc, findFirstPathOfKind(doc, kind));
+/** The kind's node in a fresh parse of the fixture, for a check that writes to it. */
+function freshSubject(ctx) {
+    return subjectNode(parse(ctx.fixture), ctx.kind, ctx.nodePath, 'conformanceFixture');
+}
+function rebuildRawOf(ctx, descriptor) {
+    const node = freshSubject(ctx);
     descriptor.rebuildRaw(node);
     return node.raw;
 }
@@ -323,3 +331,82 @@ function firstVisibleChar(raw) {
     }
     return null;
 }
+const RAW_WRITE_SENTINEL = 'raw write sentinel\n';
+function fixtureLines(fixture) {
+    const ending = ownTrailingLineEnding(fixture) || '\n';
+    const lines = trimTrailingLineEnding(fixture).split(ending);
+    return { ending, lines, closingCut: lines.slice(0, -1).join(ending) + ending };
+}
+/**
+ * For a kind with no `rawWrite`: the fixture with its closing line cut must not absorb
+ * the block after it, or a range delete over the closer turns the document below into its body.
+ */
+function checkClosingCutNeedsNoRule(kind, fixture) {
+    const { ending, closingCut } = fixtureLines(fixture);
+    const following = parse(closingCut + ending + RAW_WRITE_SENTINEL).children.at(-1);
+    if (following?.raw === RAW_WRITE_SENTINEL)
+        return;
+    fail(`"${kind}" declares no rawWrite, and the closing line cut (${show(closingCut)}) ` +
+        `swallows the next block (${show(RAW_WRITE_SENTINEL)}): declare rawWrite to ` +
+        `put the closer back`);
+}
+/** Drives five writes over `kind`'s fixture through its `rawWrite` rule; each result must be a
+ *  fixed point of the rule, leave the next block its own, and have an agreeing caret map. */
+export function checkLeafRawWrite(kind, fixture, rule = getBlockKindDescriptor(kind).rawWrite) {
+    if (!rule)
+        fail(`"${kind}" declares no rawWrite to drive`);
+    const { ending, lines, closingCut } = fixtureLines(fixture);
+    const writes = [
+        ['the closing line cut', closingCut, lines.length > 2],
+        ['everything past the first line cut', lines[0] + ending, false],
+        ['an empty write', '', false]
+    ];
+    if (lines.length > 1) {
+        const closer = lines[lines.length - 1];
+        const closerInBody = [lines[0], closer, ...lines.slice(1)];
+        writes.push(['the first line cut', lines.slice(1).join(ending) + ending, false], ['the closing line copied into the body', closerInBody.join(ending) + ending, false]);
+    }
+    for (const [label, written, keepsKind] of writes) {
+        const doc = parse(fixture + ending + RAW_WRITE_SENTINEL);
+        const node = subjectNode(doc, kind, [0], 'the rawWrite fixture');
+        const ctx = { node, mode: 'literal', lineEnding: documentLineEnding(doc) };
+        const legal = rule.normalize(written, ctx);
+        assertIs(rule.normalize(legal, ctx), legal, `"${kind}" rule is idempotent on ${label}`);
+        checkCaretMap(`"${kind}" caret map on ${label}`, written, legal, (offset) => rule.mapOffset(written, offset, ctx));
+        const following = parse(legal + ending + RAW_WRITE_SENTINEL).children.at(-1);
+        assertIs(following?.raw, RAW_WRITE_SENTINEL, `"${kind}" after ${label} (${show(legal)}) leaves the next block its own`);
+        if (!keepsKind)
+            continue;
+        const reparsed = parse(legal).children;
+        assertIs(reparsed[0]?.kind, kind, `"${kind}" stays its kind after ${label}`);
+        installOwnRaw(node, legal, defaultGrammarView);
+        assertParseConverged(doc, `"${kind}" written in place after ${label}`);
+    }
+}
+/** A caret map agrees with its rule when offsets stay ordered and in range, one before every
+ *  change stays, and one after every change moves by the length the rule added or dropped. */
+function checkCaretMap(label, written, legal, mapOffset) {
+    const shorter = Math.min(written.length, legal.length);
+    let prefix = 0;
+    while (prefix < shorter && written[prefix] === legal[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < shorter - prefix &&
+        written[written.length - 1 - suffix] === legal[legal.length - 1 - suffix]) {
+        suffix++;
+    }
+    const grown = legal.length - written.length;
+    let previous = 0;
+    for (let offset = 0; offset <= written.length; offset++) {
+        const mapped = mapOffset(offset);
+        const at = `${label} at ${offset} (${show(written)} to ${show(legal)})`;
+        assert(mapped >= previous && mapped <= legal.length, `${at}: ${mapped} is out of order`);
+        previous = mapped;
+        if (written === legal || offset < prefix) {
+            assertIs(mapped, offset, `${at} stays, since the rule changed nothing before it`);
+        }
+        else if (offset > written.length - suffix) {
+            assertIs(mapped, offset + grown, `${at} moves by what the rule changed before it`);
+        }
+    }
+}

package/dist/testing/kit-reading.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The reading a kit gives the editor parts it builds without mounting an editor: every installed
+ * plugin's syntax, no link-reference definitions, and a mode the caller may set.
+ */
+import { type PresentationMode } from '../presentation-mode';
+import type { Reading } from '../schema/reading';
+export declare function kitReading(mode?: () => PresentationMode): Reading;

package/dist/testing/kit-reading.js

@@ -0,0 +1,16 @@
+/**
+ * The reading a kit gives the editor parts it builds without mounting an editor: every installed
+ * plugin's syntax, no link-reference definitions, and a mode the caller may set.
+ */
+import { hidesDelimitersAtCaret } from '../presentation-mode';
+import { defaultGrammarView } from '../schema/block-openers';
+export function kitReading(mode = () => 'source') {
+    return {
+        grammar: defaultGrammarView,
+        resolver: undefined,
+        resolverSignature: '',
+        resolverEpoch: 0,
+        mode,
+        hidesDelimitersAtCaret: () => hidesDelimitersAtCaret(mode())
+    };
+}

package/dist/testing/mount-dom-stubs.d.ts

@@ -1,8 +1,7 @@
 /**
- * Install the jsdom gaps a mounted editor hits — the block-height `ResizeObserver` and the
- * reveal's `scrollIntoView` — once, before the first mount. Each lands only where absent, so a
- * runner supplying a real one keeps it and the call is inert in a browser. Windowing activates
- * on ESTIMATED height in either scroll mode, so keep fixture documents small if a test asserts
- * on a block being mounted; jsdom reports a zero viewport and mounts only the first few.
+ * Fills the jsdom gaps a mounted editor hits (`ResizeObserver`, `scrollIntoView`, a range's
+ * rects) where they are missing; call once before the first mount. jsdom's viewport has no
+ * height, so only a few blocks mount: keep fixture documents small when a test asserts a block is
+ * mounted.
  */
 export declare function installEditorDomStubsForTests(): void;

package/dist/testing/mount-dom-stubs.js

@@ -4,11 +4,10 @@ class NoopResizeObserver {
     disconnect() { }
 }
 /**
- * Install the jsdom gaps a mounted editor hits — the block-height `ResizeObserver` and the
- * reveal's `scrollIntoView` — once, before the first mount. Each lands only where absent, so a
- * runner supplying a real one keeps it and the call is inert in a browser. Windowing activates
- * on ESTIMATED height in either scroll mode, so keep fixture documents small if a test asserts
- * on a block being mounted; jsdom reports a zero viewport and mounts only the first few.
+ * Fills the jsdom gaps a mounted editor hits (`ResizeObserver`, `scrollIntoView`, a range's
+ * rects) where they are missing; call once before the first mount. jsdom's viewport has no
+ * height, so only a few blocks mount: keep fixture documents small when a test asserts a block is
+ * mounted.
  */
 export function installEditorDomStubsForTests() {
     const globals = globalThis;
@@ -16,4 +15,8 @@ export function installEditorDomStubsForTests() {
     if (typeof Element !== 'undefined' && !Element.prototype.scrollIntoView) {
         Element.prototype.scrollIntoView = () => { };
     }
+    if (typeof Range !== 'undefined' && !Range.prototype.getClientRects) {
+        Range.prototype.getClientRects = () => [];
+        Range.prototype.getBoundingClientRect = () => new DOMRect();
+    }
 }

package/dist/testing/parse-convergence.d.ts

@@ -1,14 +1,14 @@
 /**
- * The parse-convergence oracle. A byte round-trip after a mutation is a tautology (G2.1 makes
- * `serialize∘parse` identity), so this compares the LIVE tree against `parse(serialize(live))`
- * STRUCTURALLY instead: kinds, children shape, and parse-derived metadata. The comparison is
- * exact: the parser materializes blank lines as blocks, so an empty paragraph reparses as itself.
- * The reparse uses the ambient grammar, so an unregistered kind reads as a false divergence.
+ * Compares the live tree's structure (kinds, children, every metadata key) with a fresh parse
+ * of its own bytes; a byte round-trip would pass trivially, since `serialize(parse(s)) === s` for
+ * every input. `parseConverges` and `describeConvergence` take the editor's `grammar` when it
+ * has one; `assertParseConverged` reads with the default grammar.
  */
 import type { Document } from '../core/nodes';
-/** True when the live tree converges structurally with a fresh parse of its serialization. */
-export declare function parseConverges(doc: Document): boolean;
-/** The FIRST structural divergence from `parse(serialize(doc))`, or null when converged. */
-export declare function describeConvergence(doc: Document): string | null;
-/** Assert convergence, throwing a plain `Error` (runner-agnostic) on divergence. */
+import type { GrammarView } from '../schema/block-openers';
+/** True when the live tree matches a fresh parse of its own serialization, structurally. */
+export declare function parseConverges(doc: Document, grammar?: GrammarView): boolean;
+/** The first structural difference from `parse(serialize(doc))`, or null when they match. */
+export declare function describeConvergence(doc: Document, grammar?: GrammarView): string | null;
+/** Asserts the two match, throwing a plain `Error` on a difference so any runner can use it. */
 export declare function assertParseConverged(doc: Document, label?: string): void;