@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/invariants/child-id-parity.js

@@ -0,0 +1,39 @@
+/**
+ * A keyed container's `childIds` hold one id per child, at every depth: a container whose
+ * `children` outgrow its ids hands the keyed each block undefined keys, and the redraw after undo
+ * reconciles to something other than the tree. A container that never mounted has no `childIds`
+ * yet and passes, unless the caller seeded every container first and asks for `everyKeyed`.
+ */
+export function checkChildIdParity(node, options = {}) {
+    const [first] = childIdDrifts(node, options, 1);
+    if (!first)
+        return null;
+    return {
+        code: 'child-id-parity',
+        message: `${first.trail}: ${first.ids ?? 'no'} child ids for ${first.children} children`,
+        detail: { kind: first.kind, children: first.children, ids: first.ids }
+    };
+}
+/** Every container under `node` (itself included) whose ids are out of step, in document order. */
+export function childIdDrifts(node, options = {}, limit = Infinity) {
+    const drifts = [];
+    const everyKeyed = options.everyKeyed ?? false;
+    const stack = [
+        { node, path: [], trail: node.kind }
+    ];
+    while (stack.length > 0 && drifts.length < limit) {
+        const { node: at, path, trail } = stack.pop();
+        if (!at.children)
+            continue;
+        const ids = at.childIds;
+        if (ids === undefined ? everyKeyed : ids.length !== at.children.length) {
+            drifts.push({ path, kind: at.kind, children: at.children.length, ids: ids?.length, trail });
+        }
+        // Reversed push, so the pops come out in document order.
+        for (let i = at.children.length - 1; i >= 0; i--) {
+            const child = at.children[i];
+            stack.push({ node: child, path: [...path, i], trail: `${trail}[${i}] ${child.kind}` });
+        }
+    }
+    return drifts;
+}

package/dist/invariants/commit-paths.d.ts

@@ -1,8 +1,8 @@
 /**
- * G1.16 — every path a commit declares is doc-absolute: each prefix resolves to an
- * existing child from the document root. The final index may be one past the end, since
- * insert-shaped ops legitimately name the slot they create. The `DocPath` param is the
- * compile-time gate; this stays the runtime belt for the JS callers types don't bind.
+ * G1.16: every path a commit declares is document-absolute, so each prefix resolves to an
+ * existing child from the document root. The last index may be one past the end, because an
+ * insert names the position it is about to create. The `DocPath` type checks this at compile
+ * time; this is the runtime check for the JavaScript callers types do not bind.
  */
 import type { Document } from '../core/nodes';
 import type { DocPath } from '../selection/path-math';

package/dist/invariants/commit-paths.js

@@ -1,8 +1,8 @@
 /**
- * G1.16 — every path a commit declares is doc-absolute: each prefix resolves to an
- * existing child from the document root. The final index may be one past the end, since
- * insert-shaped ops legitimately name the slot they create. The `DocPath` param is the
- * compile-time gate; this stays the runtime belt for the JS callers types don't bind.
+ * G1.16: every path a commit declares is document-absolute, so each prefix resolves to an
+ * existing child from the document root. The last index may be one past the end, because an
+ * insert names the position it is about to create. The `DocPath` type checks this at compile
+ * time; this is the runtime check for the JavaScript callers types do not bind.
  */
 export function checkCommitPathAddressable(doc, path, role) {
     let parent = doc;

package/dist/invariants/commit-scope.d.ts

@@ -1,8 +1,8 @@
 /**
- * Commit-in-progress flag. The ceremony (editor-actions) brackets its synchronous body; the
- * decoration engine (reactivity) reads it to keep a source off a half-applied tree. A leaf,
- * so both read it downward — a flag in editor-actions would close a cycle. Never behind a
- * build flag: the deferral is production behavior (G4.61).
+ * Says whether a commit is running. The commit steps in `editor-actions` bracket their synchronous
+ * body with it, and `reactivity` reads it so decorations never read a half-applied tree. It lives
+ * here because both sides import downward, and it ships in production because the deferral it
+ * drives is production behavior (G4.61).
  */
 export declare function beginCommit(): void;
 export declare function endCommit(): void;

package/dist/invariants/commit-scope.js

@@ -1,16 +1,17 @@
 /**
- * Commit-in-progress flag. The ceremony (editor-actions) brackets its synchronous body; the
- * decoration engine (reactivity) reads it to keep a source off a half-applied tree. A leaf,
- * so both read it downward — a flag in editor-actions would close a cycle. Never behind a
- * build flag: the deferral is production behavior (G4.61).
+ * Says whether a commit is running. The commit steps in `editor-actions` bracket their synchronous
+ * body with it, and `reactivity` reads it so decorations never read a half-applied tree. It lives
+ * here because both sides import downward, and it ships in production because the deferral it
+ * drives is production behavior (G4.61).
  */
-let inCommit = false;
+// A depth, not a boolean: a commit started from an `edit` handler must not end the outer one.
+let depth = 0;
 export function beginCommit() {
-    inCommit = true;
+    depth++;
 }
 export function endCommit() {
-    inCommit = false;
+    depth--;
 }
 export function isCommitInProgress() {
-    return inCommit;
+    return depth > 0;
 }

package/dist/invariants/context-keys.d.ts

@@ -1,7 +1,4 @@
 import type { InvariantViolation } from '../assert';
-/**
- * G1.4 — a container's provided context keys must not include the editor's
- * HISTORY_KEY. Containers re-provide nested action contexts to descendants but
- * must let history flow from the root; shadowing it would split the undo stack.
- */
+/** G1.4: a container may not provide `HISTORY_KEY` to its descendants: history reaches nested
+ *  action contexts from the root, and shadowing the key would split the undo stack. */
 export declare function checkNoContainerHistoryKey(setKeys: symbol[], historyKey: symbol): InvariantViolation | null;

package/dist/invariants/context-keys.js

@@ -1,13 +1,10 @@
-/**
- * G1.4 — a container's provided context keys must not include the editor's
- * HISTORY_KEY. Containers re-provide nested action contexts to descendants but
- * must let history flow from the root; shadowing it would split the undo stack.
- */
+/** G1.4: a container may not provide `HISTORY_KEY` to its descendants: history reaches nested
+ *  action contexts from the root, and shadowing the key would split the undo stack. */
 export function checkNoContainerHistoryKey(setKeys, historyKey) {
     if (setKeys.includes(historyKey)) {
         return {
             code: 'container-sets-history-key',
-            message: 'container provides HISTORY_KEY to descendants — undo stack would split'
+            message: 'container provides HISTORY_KEY to descendants: undo stack would split'
         };
     }
     return null;

package/dist/invariants/descriptor.d.ts

@@ -1,10 +1,6 @@
 import type { CstNode } from '../core/nodes';
 import { type ContentRange } from '../core/inline';
 import type { InvariantViolation } from '../assert';
-/**
- * G1.8 — a content range stays within its raw: `0 <= start <= end <= displayLength(raw)`.
- * Every kind that HAS a range is covered, not just the prose ones: a non-prose kind may declare
- * `getContentRange` (the directive leaf does) and the range is consumed unconditionally.
- * `getRange` is a parameter so a negative test can inject a bad range without touching the registry.
- */
+/** G1.8: a content range stays inside its raw bytes, for every kind that declares one, since
+ *  callers use the range unchecked. `getRange` is a parameter so a test can inject a bad range. */
 export declare function checkContentRange(node: CstNode, getRange?: (node: CstNode) => ContentRange): InvariantViolation | null;

package/dist/invariants/descriptor.js

@@ -1,12 +1,8 @@
 import { displayLength } from '../core/lines';
 import { getBlockKindDescriptor } from '../schema/block-kind-descriptor';
 import { getContentRange } from '../core/inline';
-/**
- * G1.8 — a content range stays within its raw: `0 <= start <= end <= displayLength(raw)`.
- * Every kind that HAS a range is covered, not just the prose ones: a non-prose kind may declare
- * `getContentRange` (the directive leaf does) and the range is consumed unconditionally.
- * `getRange` is a parameter so a negative test can inject a bad range without touching the registry.
- */
+/** G1.8: a content range stays inside its raw bytes, for every kind that declares one, since
+ *  callers use the range unchecked. `getRange` is a parameter so a test can inject a bad range. */
 export function checkContentRange(node, getRange = getContentRange) {
     const descriptor = getBlockKindDescriptor(node.kind);
     if (!descriptor.supportsInline && descriptor.getContentRange === undefined)

package/dist/invariants/inline-transitions.d.ts

@@ -1,23 +1,16 @@
 /**
- * Predicates for the inline layer's transition guards (G1.25–G1.27): the widget-pool pass
- * bracket, the reveal kernel's source-length precondition, and the IME composition window.
+ * The checks behind the inline transition guards (G1.25 to G1.27): the widget pool's
+ * begin/sweep bracket, the source-length rule for a revealed construct, and the window during
+ * which an IME composition is open.
  */
 import type { InvariantViolation } from '../assert';
 export type PoolBracketAction = 'acquire' | 'beginPass' | 'sweep';
-/**
- * G1.25 — every pool mutation respects the beginPass/sweep bracket. Outside one, adoption
- * flags and pass tallies are meaningless and key-only lookup cannot tell byte-identical
- * duplicate widgets apart.
- */
+/** G1.25: every pool change happens between `beginPass` and `sweep`; outside that bracket a
+ *  lookup by key alone cannot tell two byte-identical widgets apart. */
 export declare function checkPoolBracket(passOpen: boolean, action: PoolBracketAction): InvariantViolation | null;
-/**
- * G1.26 (kernel leg) — a reveal's source bytes span exactly its [sourceStart, sourceEnd)
- * range; a mismatch shifts every raw offset outside the source, desyncing the offset walk.
- */
+/** G1.26, the shared editable core's half: a revealed construct's source bytes span exactly
+ *  `[sourceStart, sourceEnd)`, or every raw offset after the source shifts. */
 export declare function checkRevealSourceLength(sourceLength: number, sourceStart: number, sourceEnd: number): InvariantViolation | null;
-/**
- * G1.27 — a compositionend lands only inside a composition the surface saw start. Browsers
- * pair the events per element, so an unpaired end means a consumer wired `compositionend`
- * without `compositionstart` and every composition keystroke reached the CST mid-IME.
- */
+/** G1.27: a `compositionend` arrives only inside a composition the element saw start, so an
+ *  unpaired end means `compositionstart` was never wired and IME keystrokes reached the tree. */
 export declare function checkCompositionEndPaired(composing: boolean): InvariantViolation | null;

package/dist/invariants/inline-transitions.js

@@ -1,14 +1,11 @@
-/**
- * G1.25 — every pool mutation respects the beginPass/sweep bracket. Outside one, adoption
- * flags and pass tallies are meaningless and key-only lookup cannot tell byte-identical
- * duplicate widgets apart.
- */
+/** G1.25: every pool change happens between `beginPass` and `sweep`; outside that bracket a
+ *  lookup by key alone cannot tell two byte-identical widgets apart. */
 export function checkPoolBracket(passOpen, action) {
     if (action === 'beginPass') {
         return passOpen
             ? {
                 code: 'begin-unswept',
-                message: 'beginPass while a bracket is already open — the previous pass was never swept'
+                message: 'beginPass while a bracket is already open: the previous pass was never swept'
             }
             : null;
     }
@@ -17,17 +14,15 @@ export function checkPoolBracket(passOpen, action) {
     return action === 'acquire'
         ? {
             code: 'acquire-outside-bracket',
-            message: 'acquire outside a beginPass/sweep bracket — adoption is only meaningful inside a rebuild pass'
+            message: 'acquire outside a beginPass/sweep bracket: adoption is only meaningful inside a rebuild pass'
         }
         : {
             code: 'sweep-outside-bracket',
-            message: 'sweep without an open bracket — nothing was adopted, so it would destroy every live widget'
+            message: 'sweep without an open bracket, nothing was adopted, so it would destroy every live widget'
         };
 }
-/**
- * G1.26 (kernel leg) — a reveal's source bytes span exactly its [sourceStart, sourceEnd)
- * range; a mismatch shifts every raw offset outside the source, desyncing the offset walk.
- */
+/** G1.26, the shared editable core's half: a revealed construct's source bytes span exactly
+ *  `[sourceStart, sourceEnd)`, or every raw offset after the source shifts. */
 export function checkRevealSourceLength(sourceLength, sourceStart, sourceEnd) {
     if (sourceLength === sourceEnd - sourceStart)
         return null;
@@ -37,16 +32,13 @@ export function checkRevealSourceLength(sourceLength, sourceStart, sourceEnd) {
         detail: { sourceLength, sourceStart, sourceEnd }
     };
 }
-/**
- * G1.27 — a compositionend lands only inside a composition the surface saw start. Browsers
- * pair the events per element, so an unpaired end means a consumer wired `compositionend`
- * without `compositionstart` and every composition keystroke reached the CST mid-IME.
- */
+/** G1.27: a `compositionend` arrives only inside a composition the element saw start, so an
+ *  unpaired end means `compositionstart` was never wired and IME keystrokes reached the tree. */
 export function checkCompositionEndPaired(composing) {
     if (composing)
         return null;
     return {
         code: 'end-without-start',
-        message: 'compositionend with no open composition — the surface never saw compositionstart'
+        message: 'compositionend with no open composition: the surface never saw compositionstart'
     };
 }

package/dist/invariants/install.d.ts

@@ -1,36 +1,27 @@
 /**
- * Seam-side glue between the pure predicates and the `assertInvariant` channel, so the
- * predicates themselves stay pure and unaware of it.
+ * Wires the pure predicates to `assertInvariant`, so the predicates stay pure and know nothing
+ * about how a violation is reported.
  */
 import type { CstNode, Document } from '../core/nodes';
+import type { GrammarView } from '../schema/block-openers';
 import type { DocPath } from '../selection/path-math';
 import { type SnapshotEntry } from './snapshot-integrity';
-/**
- * Per-commit check for the nodes a commit touched, never a whole-tree walk. Each predicate
- * self-filters by kind. Run AFTER the commit's rebuildRaw, so a strip container's raw is
- * its freshly-rebuilt output.
- */
-export declare function assertCommittedNodes(nodes: CstNode[]): void;
-/**
- * Pre-mutate commit-seam check that both declared coordinates are doc-absolute (G1.16,
- * `commit-paths.ts`). Null skips a coordinate the commit doesn't carry.
- */
+/** Checks only the nodes a commit touched. Call it after the commit's `rebuildRaw`, so a strip
+ *  container's raw is that rebuild's output. */
+export declare function assertCommittedNodes(nodes: CstNode[], grammar: GrammarView): void;
+/** Checks, before the commit mutates anything, that both declared paths are document-absolute
+ *  (G1.16); null skips a path the commit does not carry. */
 export declare function assertCommitPaths(doc: Document, snapshotPath: DocPath | null, eventPath: DocPath | null): void;
-/**
- * G1.9 per-commit seam: the freshest undo entry is the one this commit's mutations could
- * have corrupted, so only its digest is re-verified. Deeper entries stay covered by the
- * restore-time check in `editor-actions/commit/history.ts`.
- */
+/** G1.9, once per commit: only the newest undo entry can have been corrupted by this commit, so
+ *  only its digest is re-checked; older entries are checked when they are restored. */
 export declare function assertUndoTopIntegrity(entry: SnapshotEntry | undefined): void;
-/**
- * G1.36 consumer half, at each publish seam: the descriptor's own bounds check cannot see a
- * change that fits its array while describing the wrong window, and a short id array reaches
- * Svelte's keyed each as missing keys.
- */
+/** G1.41, after every structural commit publishes: `wasOpen` is `endsOpen` read before it mutated. */
+export declare function assertLastLineKept(doc: Document, wasOpen: boolean): void;
+/** G1.44, after every structural commit publishes: `touched` is what the commit wrote. */
+export declare function assertKeepsABlock(doc: Document, touched: CstNode[]): void;
+/** G1.36, the reading half, run wherever ids are written to state: an id array that is too short
+ *  reaches Svelte's keyed each as missing keys. */
 export declare function assertIdsInLockstep(seam: string, idCount: number, childCount: number): void;
-/**
- * Registry-wide checks at the mount seam. The flush owns the once-latch: the first sweeps
- * the whole world, later mounts validate only registrations since the previous flush. The
- * inline-policy check sits outside it — mount-only, and table-wide on every mount (G1.31).
- */
+/** The registry-wide checks, run on mount: the full sweep the first time, then only the
+ *  registrations added since. The inline-policy check runs on every mount (G1.31). */
 export declare function runStartupInvariantChecks(): void;

package/dist/invariants/install.js

@@ -1,34 +1,34 @@
 /**
- * Seam-side glue between the pure predicates and the `assertInvariant` channel, so the
- * predicates themselves stay pure and unaware of it.
+ * Wires the pure predicates to `assertInvariant`, so the predicates stay pure and know nothing
+ * about how a violation is reported.
  */
 import { assertInvariant } from '../assert';
 import { checkCommitPathAddressable } from './commit-paths';
 import { flushPendingRegistrationChecks, checkInlineConstructPoliciesAtMount } from '../schema/registration-checks';
-import { checkStaleRaw, checkOpaqueStaleRaw, checkOpaqueRebuildDeterminism, checkReservedChromeSlot, checkCategoryFields } from './node-shape';
+import { checkStaleRaw, checkOpaqueStaleRaw, checkOpaqueRebuildDeterminism, checkReservedChromeSlot, checkCategoryFields, checkTaskMarkerSlot } from './node-shape';
 import { checkContentRange } from './descriptor';
+import { checkChildIdParity } from './child-id-parity';
 import { checkChildSpansLockstep, checkIdsChildrenLockstep } from './structural-descriptor';
 import { checkSnapshotIntegrity } from './snapshot-integrity';
-/**
- * Per-commit check for the nodes a commit touched, never a whole-tree walk. Each predicate
- * self-filters by kind. Run AFTER the commit's rebuildRaw, so a strip container's raw is
- * its freshly-rebuilt output.
- */
-export function assertCommittedNodes(nodes) {
+import { checkLastLineKept } from './open-tail';
+import { checkKeepsABlock } from './keeps-a-block';
+/** Checks only the nodes a commit touched. Call it after the commit's `rebuildRaw`, so a strip
+ *  container's raw is that rebuild's output. */
+export function assertCommittedNodes(nodes, grammar) {
     for (const node of nodes) {
-        assertInvariant('stale-raw', () => checkStaleRaw(node));
-        assertInvariant('opaque-stale-raw', () => checkOpaqueStaleRaw(node));
+        assertInvariant('stale-raw', () => checkStaleRaw(node, grammar));
+        assertInvariant('opaque-stale-raw', () => checkOpaqueStaleRaw(node, grammar));
         assertInvariant('opaque-rebuild-determinism', () => checkOpaqueRebuildDeterminism(node));
         assertInvariant('reserved-chrome-slot', () => checkReservedChromeSlot(node));
         assertInvariant('category-fields', () => checkCategoryFields(node));
         assertInvariant('content-range', () => checkContentRange(node));
         assertInvariant('child-spans-lockstep', () => checkChildSpansLockstep(node));
+        assertInvariant('child-id-parity', () => checkChildIdParity(node));
+        assertInvariant('task-marker-slot', () => checkTaskMarkerSlot(node, grammar));
     }
 }
-/**
- * Pre-mutate commit-seam check that both declared coordinates are doc-absolute (G1.16,
- * `commit-paths.ts`). Null skips a coordinate the commit doesn't carry.
- */
+/** Checks, before the commit mutates anything, that both declared paths are document-absolute
+ *  (G1.16); null skips a path the commit does not carry. */
 export function assertCommitPaths(doc, snapshotPath, eventPath) {
     if (snapshotPath) {
         assertInvariant('commit-path-dialect', () => checkCommitPathAddressable(doc, snapshotPath, 'snapshot.path'));
@@ -37,29 +37,28 @@ export function assertCommitPaths(doc, snapshotPath, eventPath) {
         assertInvariant('commit-path-dialect', () => checkCommitPathAddressable(doc, eventPath, 'eventPath'));
     }
 }
-/**
- * G1.9 per-commit seam: the freshest undo entry is the one this commit's mutations could
- * have corrupted, so only its digest is re-verified. Deeper entries stay covered by the
- * restore-time check in `editor-actions/commit/history.ts`.
- */
+/** G1.9, once per commit: only the newest undo entry can have been corrupted by this commit, so
+ *  only its digest is re-checked; older entries are checked when they are restored. */
 export function assertUndoTopIntegrity(entry) {
     if (!entry)
         return;
     assertInvariant('snapshot-integrity', () => checkSnapshotIntegrity(entry));
 }
-/**
- * G1.36 consumer half, at each publish seam: the descriptor's own bounds check cannot see a
- * change that fits its array while describing the wrong window, and a short id array reaches
- * Svelte's keyed each as missing keys.
- */
+/** G1.41, after every structural commit publishes: `wasOpen` is `endsOpen` read before it mutated. */
+export function assertLastLineKept(doc, wasOpen) {
+    assertInvariant('last-line-kept', () => checkLastLineKept(doc, wasOpen));
+}
+/** G1.44, after every structural commit publishes: `touched` is what the commit wrote. */
+export function assertKeepsABlock(doc, touched) {
+    assertInvariant('keeps-a-block', () => checkKeepsABlock(doc, touched));
+}
+/** G1.36, the reading half, run wherever ids are written to state: an id array that is too short
+ *  reaches Svelte's keyed each as missing keys. */
 export function assertIdsInLockstep(seam, idCount, childCount) {
     assertInvariant('ids-children-lockstep', () => checkIdsChildrenLockstep(seam, idCount, childCount));
 }
-/**
- * Registry-wide checks at the mount seam. The flush owns the once-latch: the first sweeps
- * the whole world, later mounts validate only registrations since the previous flush. The
- * inline-policy check sits outside it — mount-only, and table-wide on every mount (G1.31).
- */
+/** The registry-wide checks, run on mount: the full sweep the first time, then only the
+ *  registrations added since. The inline-policy check runs on every mount (G1.31). */
 export function runStartupInvariantChecks() {
     flushPendingRegistrationChecks();
     checkInlineConstructPoliciesAtMount();

package/dist/invariants/keeps-a-block.d.ts

@@ -0,0 +1,7 @@
+/**
+ * G1.44: after a structural commit the document holds a block, and no container the commit
+ * touched that must hold a child is left with none.
+ */
+import type { DocumentView, NodeView } from '../core/node-views';
+import type { InvariantViolation } from '../assert';
+export declare function checkKeepsABlock(doc: DocumentView, touched: readonly NodeView[]): InvariantViolation | null;

package/dist/invariants/keeps-a-block.js

@@ -0,0 +1,14 @@
+/**
+ * G1.44: after a structural commit the document holds a block, and no container the commit
+ * touched that must hold a child is left with none.
+ */
+import { mustHoldChild } from '../schema/block-kind-descriptor';
+export function checkKeepsABlock(doc, touched) {
+    if (doc.children.length === 0)
+        return violation('the document holds no block');
+    const emptied = touched.find((n) => mustHoldChild(n.kind) && (n.children?.length ?? 0) === 0);
+    return emptied ? violation(`a ${emptied.kind} holds no block`) : null;
+}
+function violation(message) {
+    return { code: 'keeps-a-block', message };
+}

package/dist/invariants/landable-caret.d.ts

@@ -1,11 +1,9 @@
 /**
- * G1.33 — a block a caret is being seated in, under an editable marker-hiding rung, paints at
- * least one landable caret position. A surface whose whole content is a hidden marker run takes
- * the keystroke at an element boundary between `display:none` spans, and the engine seats the
- * byte on whichever side it likes. Built-ins satisfy it by painting chrome that stands over no
- * content (`docs/design/live-mode.md` § 4.1); this catches a plugin surface that does not.
- * Reported at block-host granularity: a table cell has no host of its own, so a cell violation
- * names its table's path while the predicate still resolves the cell's own surface.
+ * G1.33: in a mode that hides markers, a block the caret is about to enter paints at least one
+ * position the caret can sit at; if every content byte is a hidden marker, the browser puts the
+ * keystroke on whichever side of the hidden spans it likes. Built-in blocks paint markers that
+ * stand over no content (`docs/design/live-mode.md` § 4.1 What live never writes); the check is
+ * for plugin blocks. A table cell has no block host, so it reports its table's path.
  */
 import { type PresentationMode } from '../presentation-mode';
 import type { InvariantViolation } from '../assert';

package/dist/invariants/landable-caret.js

@@ -1,11 +1,9 @@
 /**
- * G1.33 — a block a caret is being seated in, under an editable marker-hiding rung, paints at
- * least one landable caret position. A surface whose whole content is a hidden marker run takes
- * the keystroke at an element boundary between `display:none` spans, and the engine seats the
- * byte on whichever side it likes. Built-ins satisfy it by painting chrome that stands over no
- * content (`docs/design/live-mode.md` § 4.1); this catches a plugin surface that does not.
- * Reported at block-host granularity: a table cell has no host of its own, so a cell violation
- * names its table's path while the predicate still resolves the cell's own surface.
+ * G1.33: in a mode that hides markers, a block the caret is about to enter paints at least one
+ * position the caret can sit at; if every content byte is a hidden marker, the browser puts the
+ * keystroke on whichever side of the hidden spans it likes. Built-in blocks paint markers that
+ * stand over no content (`docs/design/live-mode.md` § 4.1 What live never writes); the check is
+ * for plugin blocks. A table cell has no block host, so it reports its table's path.
  */
 import { hidesMarkers } from '../presentation-mode';
 import { paintsNoLandableContent } from '../cursor/widget-offset';
@@ -18,13 +16,12 @@ export function checkLandableCaret(focused, mode, blockPath) {
         return null;
     return {
         code: 'landable-caret',
-        message: `the block at [${blockPath}] is every byte a hidden marker run, so "${mode}" paints it nowhere and the caret being seated there has no position of its own — paint the chrome while it stands over no content`,
+        message: `the block at [${blockPath}] is every byte a hidden marker run, so "${mode}" paints it nowhere and the caret being placed there has no position of its own: paint the chrome while it stands over no content`,
         detail: { path: [...blockPath], mode }
     };
 }
-/** The walk container behind a focus landing: the seam offers every landing, block chrome and
- *  inner spans included, and only a surface that takes a keystroke can trap a caret. By
- *  attribute, not `isContentEditable`, which jsdom leaves false on an editable div. */
+/** The editable element behind the focus, which may sit on a marker or an inner span. Read from
+ *  the attribute, since jsdom leaves `isContentEditable` false on an editable div. */
 function editableSurfaceOf(focused) {
     const el = focused.closest('[contenteditable]');
     return el && el.getAttribute('contenteditable') !== 'false' ? el : null;

package/dist/invariants/landing-focus-scroll.d.ts

@@ -0,0 +1,7 @@
+/**
+ * G1.45: a caret landing's focus call and DOM placement scroll nothing. The landing's reveal policy
+ * is the one scroll it makes, through the scroll owner; a focus without `preventScroll` is a
+ * second writer nobody owns.
+ */
+import type { InvariantViolation } from '../assert';
+export declare function checkLandingFocusScrollsNothing(before: number | null, after: number | null): InvariantViolation | null;

package/dist/invariants/landing-focus-scroll.js

@@ -0,0 +1,13 @@
+/**
+ * G1.45: a caret landing's focus call and DOM placement scroll nothing. The landing's reveal policy
+ * is the one scroll it makes, through the scroll owner; a focus without `preventScroll` is a
+ * second writer nobody owns.
+ */
+export function checkLandingFocusScrollsNothing(before, after) {
+    if (before === null || after === null || before === after)
+        return null;
+    return {
+        code: 'landing-focus-scrolls-nothing',
+        message: `a caret landing's focus moved the scroll position (${before} to ${after}): pass \`preventScroll\` and let the reveal policy scroll`
+    };
+}

package/dist/invariants/landing-value.d.ts

@@ -0,0 +1,13 @@
+/**
+ * G1.43: reading a commit's landing moves no caret. The landing is a value the commit puts down
+ * itself, so a landing function that focuses or selects is placing a second caret behind its back.
+ */
+import type { InvariantViolation } from '../assert';
+/** Where focus and the selection's anchor are, compared by identity. */
+export interface CaretWhereabouts {
+    readonly active: Element | null;
+    readonly anchorNode: Node | null;
+    readonly anchorOffset: number;
+}
+export declare function readCaretWhereabouts(): CaretWhereabouts | null;
+export declare function checkLandingIsAValue(before: CaretWhereabouts | null, after: CaretWhereabouts | null): InvariantViolation | null;

package/dist/invariants/landing-value.js

@@ -0,0 +1,27 @@
+/**
+ * G1.43: reading a commit's landing moves no caret. The landing is a value the commit puts down
+ * itself, so a landing function that focuses or selects is placing a second caret behind its back.
+ */
+export function readCaretWhereabouts() {
+    if (typeof document === 'undefined')
+        return null;
+    const selection = document.getSelection();
+    return {
+        active: document.activeElement,
+        anchorNode: selection?.anchorNode ?? null,
+        anchorOffset: selection?.anchorOffset ?? 0
+    };
+}
+export function checkLandingIsAValue(before, after) {
+    if (!before || !after)
+        return null;
+    const moved = before.active !== after.active ||
+        before.anchorNode !== after.anchorNode ||
+        before.anchorOffset !== after.anchorOffset;
+    if (!moved)
+        return null;
+    return {
+        code: 'landing-is-a-value',
+        message: "a commit's landing function moved focus or the selection: return the position and let the commit put the caret there"
+    };
+}

package/dist/invariants/marker-css-parity.d.ts

@@ -1,10 +1,9 @@
 /**
- * CSS↔TS parity for the hidden-run predicate: `cursor/widget-offset.ts` mirrors the
- * stylesheet's class scoping structurally, because a getComputedStyle per keystroke is
- * unaffordable — so the two can drift. This probe pays for the comparison once per mode
- * change, per marker family, over three answers: the stylesheet's, the walk's, and the
- * node-space model both are stated over. It declines wherever no stylesheet demonstrably hides
- * anything (jsdom, source mode); the presentation e2e battery is the real assertion there.
+ * Checks that the stylesheet and `cursor/widget-offset.ts` agree on which marker runs are hidden:
+ * the TypeScript side mirrors the stylesheet by hand, since `getComputedStyle` per keystroke is
+ * too slow. Once per mode change it compares, per marker family, the stylesheet, the DOM-to-offset
+ * traversal and the node-space rule both are stated over. Where no stylesheet hides anything
+ * (jsdom, source mode) it does nothing, and the presentation e2e battery asserts instead.
  */
 import type { InvariantViolation } from '../assert';
 export declare function checkMarkerCssParity(editorRoot: HTMLElement): InvariantViolation | null;