@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/invariants/marker-css-parity.js

@@ -1,14 +1,13 @@
 /**
- * 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 { familyHidesText, markerFamilyOf } from '../core/inline/visibility';
 import { CONTENT_EMPTY_ATTR, isHiddenMarkerRoot, screenVisibilityOf } from '../cursor/widget-offset';
-/** One case per stylesheet arm the predicate mirrors, both host-focus states. */
+/** One case per stylesheet branch the check mirrors, in both host-focus states. */
 const CASES = ['md-marker', 'md-fence-line', 'md-ref-label'].flatMap((family) => [
     { name: family, family, focusedHost: false },
     { name: `${family} (focused host)`, family, focusedHost: true },
@@ -37,13 +36,13 @@ export function checkMarkerCssParity(editorRoot) {
         const read = probes.map(({ probe, span, block }) => ({
             name: probe.name,
             predicate: isHiddenMarkerRoot(span, block),
-            // The model claims the families and the chrome fold; the REVEAL arms are the walk's
-            // alone, so a focused host is where the two are allowed to differ.
+            // The node-space rule covers the families and the markers-only case; the reveal
+            // branches belong to the traversal alone, so the two may differ on a focused host.
             model: probe.focusedHost ? null : modelHides(span, screenVisibilityOf(block)),
             css: getComputedStyle(span).display === 'none'
         }));
-        // No case computes hidden: either source mode (nothing hides by design) or an engine
-        // that applies no stylesheet — no signal to compare against, so the probe stands down.
+        // Nothing came out hidden: either source mode, where nothing hides by design, or an
+        // environment that applies no stylesheet. There is nothing to compare against, so skip.
         if (!read.some((entry) => entry.css))
             return null;
         const diverged = read.find((entry) => entry.predicate !== entry.css || (entry.model !== null && entry.model !== entry.css));
@@ -51,7 +50,7 @@ export function checkMarkerCssParity(editorRoot) {
             return null;
         return {
             code: 'marker-css-parity',
-            message: `the hidden-run answers disagree about "${diverged.name}" — the families in core/inline/visibility.ts, the walk in cursor/widget-offset.ts and styles/editor.css moved apart`,
+            message: `the hidden-run answers disagree about "${diverged.name}": the families in core/inline/visibility.ts, the walk in cursor/widget-offset.ts and styles/editor.css moved apart`,
             detail: read
         };
     }

package/dist/invariants/measures-in-own-list.d.ts

@@ -0,0 +1,6 @@
+/**
+ * G1.47: a windowed child measures into its own block list, the one whose direct child it is. A
+ * child that reached a list further up would write a height table that doesn't index it.
+ */
+import type { InvariantViolation } from '../assert';
+export declare function checkMeasuresInOwnList(childPath: readonly number[], listPath: readonly number[]): InvariantViolation | null;

package/dist/invariants/measures-in-own-list.js

@@ -0,0 +1,13 @@
+/**
+ * G1.47: a windowed child measures into its own block list, the one whose direct child it is. A
+ * child that reached a list further up would write a height table that doesn't index it.
+ */
+export function checkMeasuresInOwnList(childPath, listPath) {
+    const own = childPath.length === listPath.length + 1 && listPath.every((at, i) => childPath[i] === at);
+    if (own)
+        return null;
+    return {
+        code: 'measures-in-own-list',
+        message: `the child at ${JSON.stringify(childPath)} registered with the list at ${JSON.stringify(listPath)}, which isn't its own: call \`useMeasuredChild\` before the component provides a list of its own`
+    };
+}

package/dist/invariants/node-shape.d.ts

@@ -1,44 +1,25 @@
 import { type CstNode } from '../core/nodes';
 import type { NodeView } from '../core/node-views';
+import { type GrammarView } from '../schema/block-openers';
 import type { InvariantViolation } from '../assert';
-/**
- * G1.5 — a node's fields match its kind's category. One-directional: a container may be
- * transiently childless mid-edit, so illegal fields are forbidden but none are required.
- * Editor-level fields (`childIds`, `ownerEpoch`) are legal on every kind and unchecked;
- * `mergeRole` is per-KIND, checked once at registration (G1.30).
- */
+/** G1.5: a node's fields match its kind's category. It only forbids, never requires, since a
+ *  container can be briefly childless mid-edit. */
 export declare function checkCategoryFields(node: CstNode): InvariantViolation | null;
-/**
- * G1.1 — a strip container's `raw` agrees with its `children`:
- * `strip(raw) === serialize(children)`. Computed by re-parsing `node.raw` and byte-comparing
- * stripped-inner: canonicalization-proof (a `rebuildRaw` comparison false-fires on any
- * faithful-but-non-canonical parse) and tolerant of the editor's empty-paragraph
- * placeholder, whose bytes match the parser's `innerSuffix`. Strip containers only, recursively.
- */
-export declare function checkStaleRaw(node: CstNode): InvariantViolation | null;
-/**
- * G1.12 — the same staleness class as G1.1 for opaque containers, compared through the
- * parse channel because a faithful parse may be non-canonical. When `raw` does not reparse
- * to exactly one block of this kind, the outcome splits on recognizer existence: with one,
- * the raw has genuinely drifted and fires; without one it cannot be validated at all, so
- * it bails.
- */
-export declare function checkOpaqueStaleRaw(node: CstNode): InvariantViolation | null;
-/**
- * G1.13 — a plugin-authored `rebuildRaw` is deterministic over the committed state, which
- * is what G1.12's single reparse trusts. The two probes are compared to each other, never
- * to `node.raw`, which a faithful non-canonical parse legally differs from.
- */
+/** G1.1: a strip container's raw agrees with its children, `strip(raw) === serialize(children)`,
+ *  reparsed in the editor's grammar and checked recursively. */
+export declare function checkStaleRaw(node: CstNode, grammar: GrammarView): InvariantViolation | null;
+/** G1.12: G1.1's staleness check for opaque containers, over children and every metadata key. Raw
+ *  that stops reparsing to one block of this kind fires only when the parser can recognize it. */
+export declare function checkOpaqueStaleRaw(node: CstNode, grammar: GrammarView): InvariantViolation | null;
+/** G1.13: a plugin's `rebuildRaw` gives the same bytes every time for the same state, which G1.12's
+ *  single reparse relies on. The two trial runs compare to each other, never to `node.raw`. */
 export declare function checkOpaqueRebuildDeterminism(node: CstNode): InvariantViolation | null;
-/**
- * G1.14 — a container declaring `reservedChrome` always holds a chrome leaf of the
- * declared kind at child 0. Firing here means an op deleted or downgraded the chrome
- * instead of clearing it.
- */
+/** G1.14: a container declaring `reservedChrome` holds a leaf of that kind at child 0; a failure
+ *  means an operation deleted or replaced that child instead of emptying it. */
 export declare function checkReservedChromeSlot(node: CstNode): InvariantViolation | null;
-/**
- * G1.6 — metadata survives the one-level undo clone: every value is a primitive or an
- * array of primitives. Anything deeper would stay shared by reference with the snapshot
- * and corrupt undo.
- */
+/** G1.6: metadata survives undo's one-level copy, so every value is a primitive or an array of
+ *  primitives; anything deeper would stay shared with the snapshot and corrupt undo. */
 export declare function checkCloneSafeMetadata(node: NodeView): InvariantViolation | null;
+/** G1.42: every list item under `node` holds the checkbox a reload of `node`'s own bytes gives it,
+ *  and a to-do the reload's block kinds too. Dev only: it reparses the touched node. */
+export declare function checkTaskMarkerSlot(node: NodeView, grammar: GrammarView): InvariantViolation | null;

package/dist/invariants/node-shape.js

@@ -1,17 +1,14 @@
-import { makeBlockNode } from '../core/nodes';
-import { parse } from '../core/parser';
+import { makeBlockNode, metadataOf } from '../core/nodes';
+import { readBlocks } from '../core/parser';
 import { concatChildren } from '../core/serializer';
-import { getBlockKindDescriptor } from '../schema/block-kind-descriptor';
+import { countsCells, getBlockKindDescriptor } from '../schema/block-kind-descriptor';
 import { reservedChromeKindOf } from '../schema/reserved-chrome';
 import { listRegisteredOpeners } from '../schema/block-openers';
 import { isDirectiveKind } from '../core/directive/registry';
+import { describeMetadataDivergence } from '../core/metadata-parity';
 // ── G1.5: category ↔ field legality ──────────────────────────────────────────
-/**
- * G1.5 — a node's fields match its kind's category. One-directional: a container may be
- * transiently childless mid-edit, so illegal fields are forbidden but none are required.
- * Editor-level fields (`childIds`, `ownerEpoch`) are legal on every kind and unchecked;
- * `mergeRole` is per-KIND, checked once at registration (G1.30).
- */
+/** G1.5: a node's fields match its kind's category. It only forbids, never requires, since a
+ *  container can be briefly childless mid-edit. */
 export function checkCategoryFields(node) {
     const d = getBlockKindDescriptor(node.kind);
     if (!d.isContainer && node.children !== undefined) {
@@ -23,9 +20,8 @@ export function checkCategoryFields(node) {
     if (!d.isContainer && node.innerSuffix !== undefined) {
         return illegalField(node.kind, 'innerSuffix', 'leaf carries container structural field');
     }
-    // Only a body sitting under a chrome line of the container's own can peel a blank into
-    // `innerPrefix` (`core/parser.parseContainerBody`); elsewhere the body opens on the
-    // container's first line and a filled slot emits a line no parse can produce.
+    // Only a body under the container's own title line can strip a blank into `innerPrefix`
+    // (`core/parser.parseContainerBody`); elsewhere a filled field emits a line no parse produces.
     if (d.bodyWrap?.afterOpenerLine !== true && node.innerPrefix) {
         return illegalField(node.kind, 'innerPrefix', 'container declares no opener-line body wrap');
     }
@@ -39,36 +35,49 @@ function illegalField(kind, field, why) {
     };
 }
 // ── G1.1: container raw not stale ─────────────────────────────────────────────
-/**
- * G1.1 — a strip container's `raw` agrees with its `children`:
- * `strip(raw) === serialize(children)`. Computed by re-parsing `node.raw` and byte-comparing
- * stripped-inner: canonicalization-proof (a `rebuildRaw` comparison false-fires on any
- * faithful-but-non-canonical parse) and tolerant of the editor's empty-paragraph
- * placeholder, whose bytes match the parser's `innerSuffix`. Strip containers only, recursively.
- */
-export function checkStaleRaw(node) {
+/** G1.1: a strip container's raw agrees with its children, `strip(raw) === serialize(children)`,
+ *  reparsed in the editor's grammar and checked recursively. */
+export function checkStaleRaw(node, grammar) {
     if (getBlockKindDescriptor(node.kind).containerContract !== 'strip')
         return null;
-    // Document scope because the oracle gets no document position: fragment would fire on
-    // every legitimate position-scoped node at the top.
-    const correspondent = soleCorrespondent(parse(node.raw, { scope: 'document' }).children, node);
+    // Document scope because the check is handed no document position: fragment scope would
+    // fire on every legitimate position-scoped node at the top.
+    const correspondent = soleCorrespondent(readBlocks(node.raw, { grammar, scope: 'document' }).children, node);
     if (!rawFaithful(correspondent, node)) {
         return {
             code: 'stale-container-raw',
-            // `raw` is carried so a violation caught in CI is self-diagnosing without
-            // re-instrumenting; clamped so a large container can't flood the console.
+            // `raw` travels with the violation so a CI failure explains itself without a second
+            // run, clamped so a large container cannot flood the console.
             message: `${node.kind} raw is stale relative to its children`,
             detail: { kind: node.kind, raw: clampForDetail(node.raw) }
         };
     }
+    const metadata = stripMetadataDrift(correspondent, node);
+    if (metadata) {
+        return {
+            code: 'stale-container-raw',
+            message: `strip metadata is stale relative to its raw: ${metadata}`,
+            detail: { kind: node.kind, reason: 'metadata-diverges', raw: clampForDetail(node.raw) }
+        };
+    }
     return null;
 }
-/**
- * The one block `node.raw` must reparse to, or undefined. Singularity is the invariant's other
- * half: bytes belonging to a following sibling leave the first block's inner content intact, so
- * comparing that block alone would read a container whose raw has grown as faithful. `listItem`
- * is never a top-level block, so its raw reparses to a wrapping `list` holding it alone.
- */
+/** The first strip container, this one or one below, whose metadata its reparse doesn't give. */
+function stripMetadataDrift(reparsed, node) {
+    const found = describeMetadataDivergence(node, reparsed);
+    if (found)
+        return found;
+    const reparsedContainers = stripContainerChildren(reparsed);
+    const actualContainers = stripContainerChildren(node);
+    for (let i = 0; i < actualContainers.length; i++) {
+        const below = stripMetadataDrift(reparsedContainers[i], actualContainers[i]);
+        if (below)
+            return below;
+    }
+    return null;
+}
+/** The one block `node.raw` must reparse to, or undefined: bytes that parse as a following sibling
+ *  leave the first block intact. A `listItem`'s raw reparses to a `list` wrapping it alone. */
 function soleCorrespondent(blocks, node) {
     if (blocks.length !== 1)
         return undefined;
@@ -82,11 +91,8 @@ const MAX_RAW_IN_DETAIL = 200;
 function clampForDetail(raw) {
     return raw.length > MAX_RAW_IN_DETAIL ? raw.slice(0, MAX_RAW_IN_DETAIL) + '…' : raw;
 }
-/**
- * `strip(node.raw) === serialize(node.children)` at this level, then recurse: the
- * parent-level byte concat can't see a child whose own raw↔children diverge while its raw
- * still matches.
- */
+/** Checks this level, then recurses: a child whose own raw and children disagree can still leave
+ *  its parent's joined bytes matching. */
 function rawFaithful(reparsed, node) {
     if (!reparsed)
         return false;
@@ -110,19 +116,14 @@ function stripContainerChildren(node) {
     return (node.children ?? []).filter((c) => getBlockKindDescriptor(c.kind).containerContract === 'strip');
 }
 // ── G1.12: opaque container raw not stale ─────────────────────────────────────
-/**
- * G1.12 — the same staleness class as G1.1 for opaque containers, compared through the
- * parse channel because a faithful parse may be non-canonical. When `raw` does not reparse
- * to exactly one block of this kind, the outcome splits on recognizer existence: with one,
- * the raw has genuinely drifted and fires; without one it cannot be validated at all, so
- * it bails.
- */
-export function checkOpaqueStaleRaw(node) {
+/** G1.12: G1.1's staleness check for opaque containers, over children and every metadata key. Raw
+ *  that stops reparsing to one block of this kind fires only when the parser can recognize it. */
+export function checkOpaqueStaleRaw(node, grammar) {
     if (getBlockKindDescriptor(node.kind).containerContract !== 'opaque')
         return null;
-    // Document scope for the same reason as G1.1's probe: the node arrives without its
-    // document position, and fragment would fire on a legitimate position-scoped node.
-    const blocks = parse(node.raw, { scope: 'document' }).children;
+    // Document scope for the same reason as G1.1: the node arrives without its document
+    // position, and fragment scope would fire on a legitimate position-scoped node.
+    const blocks = readBlocks(node.raw, { grammar, scope: 'document' }).children;
     if (blocks.length !== 1 || blocks[0].kind !== node.kind) {
         if (!hasStandaloneRecognizer(node.kind))
             return null;
@@ -139,22 +140,23 @@ export function checkOpaqueStaleRaw(node) {
             detail: { kind: node.kind, raw: clampForDetail(node.raw) }
         };
     }
+    const metadata = describeMetadataDivergence(node, blocks[0]);
+    if (metadata) {
+        return {
+            code: 'opaque-stale-raw',
+            message: `opaque metadata is stale relative to its raw: ${metadata}`,
+            detail: { kind: node.kind, reason: 'metadata-diverges', raw: clampForDetail(node.raw) }
+        };
+    }
     return null;
 }
-/**
- * Can `parse(raw)` reproduce this kind at all? Both registries answer: a kind owns a block
- * opener, or is a directive whose shared `:::` opener recognizes it. Probing openers alone
- * would exempt the whole directive tier as unrecognizable.
- */
+/** Whether `readBlocks(raw)` can produce this kind: it owns a block opener, or it is a directive
+ *  the shared `:::` opener recognizes. */
 function hasStandaloneRecognizer(kind) {
     return listRegisteredOpeners().some((o) => o.kind === kind) || isDirectiveKind(kind);
 }
-/**
- * Chrome-aware faithfulness: a reservedChrome child's bytes live in the container's opener
- * line, so a reparse mints the chrome before any body trivia while the live tree may
- * legally hold a transient blank after it. Compare the chrome raw positionally and the
- * body bytes as a unit; a missing or displaced slot is G1.14's finding, not staleness.
- */
+/** The same check with a reserved title child, whose bytes sit in the opener line: the live tree
+ *  may hold a blank after it, so the title compares by position and the body as one unit. */
 function opaqueRawFaithful(reparsed, node) {
     const chromeKind = reservedChromeKindOf(node.kind);
     const liveChrome = node.children?.[0];
@@ -166,15 +168,12 @@ function opaqueRawFaithful(reparsed, node) {
     }
     if (liveChrome.raw !== reparsedChrome.raw)
         return false;
-    // Spreading the union widens `kind`, so re-mint through the construction funnel.
+    // Spreading the union widens `kind`, so rebuild through the node constructor.
     return rawFaithful(makeBlockNode({ ...reparsed, children: reparsed.children.slice(1) }), makeBlockNode({ ...node, children: node.children.slice(1) }));
 }
 // ── G1.13: opaque rebuild determinism ─────────────────────────────────────────
-/**
- * G1.13 — a plugin-authored `rebuildRaw` is deterministic over the committed state, which
- * is what G1.12's single reparse trusts. The two probes are compared to each other, never
- * to `node.raw`, which a faithful non-canonical parse legally differs from.
- */
+/** G1.13: a plugin's `rebuildRaw` gives the same bytes every time for the same state, which G1.12's
+ *  single reparse relies on. The two trial runs compare to each other, never to `node.raw`. */
 export function checkOpaqueRebuildDeterminism(node) {
     const descriptor = getBlockKindDescriptor(node.kind);
     if (descriptor.containerContract !== 'opaque' || !descriptor.rebuildRaw)
@@ -189,11 +188,8 @@ export function checkOpaqueRebuildDeterminism(node) {
         detail: { kind: node.kind, first: clampForDetail(first), second: clampForDetail(second) }
     };
 }
-/**
- * `rebuildRaw` may write only `raw`; the probe isolates that write and copies the children
- * array and metadata record, shielding the live node from a misbehaving rebuilder. Child
- * NODES stay shared — defending those would cost a per-commit deep clone.
- */
+/** `rebuildRaw` writes only `raw` (the editor re-reads metadata from it), so the trial copies the
+ *  children array and metadata and shares the child nodes, since copying those is a deep clone. */
 function probeRebuild(node, rebuildRaw) {
     const probe = { ...node };
     if (probe.children)
@@ -204,11 +200,8 @@ function probeRebuild(node, rebuildRaw) {
     return probe.raw;
 }
 // ── G1.14: reserved-chrome slot ───────────────────────────────────────────────
-/**
- * G1.14 — a container declaring `reservedChrome` always holds a chrome leaf of the
- * declared kind at child 0. Firing here means an op deleted or downgraded the chrome
- * instead of clearing it.
- */
+/** G1.14: a container declaring `reservedChrome` holds a leaf of that kind at child 0; a failure
+ *  means an operation deleted or replaced that child instead of emptying it. */
 export function checkReservedChromeSlot(node) {
     const chromeKind = reservedChromeKindOf(node.kind);
     if (chromeKind === undefined)
@@ -223,11 +216,8 @@ export function checkReservedChromeSlot(node) {
     };
 }
 // ── G1.6: clone-safe metadata ─────────────────────────────────────────────────
-/**
- * G1.6 — metadata survives the one-level undo clone: every value is a primitive or an
- * array of primitives. Anything deeper would stay shared by reference with the snapshot
- * and corrupt undo.
- */
+/** G1.6: metadata survives undo's one-level copy, so every value is a primitive or an array of
+ *  primitives; anything deeper would stay shared with the snapshot and corrupt undo. */
 export function checkCloneSafeMetadata(node) {
     if (!node.metadata)
         return null;
@@ -256,3 +246,57 @@ function isPrimitive(value) {
     const t = typeof value;
     return t !== 'object' && t !== 'function';
 }
+// ── G1.42: a list item says what its reload reads ─────────────────────────────
+/** G1.42: every list item under `node` holds the checkbox a reload of `node`'s own bytes gives it,
+ *  and a to-do the reload's block kinds too. Dev only: it reparses the touched node. */
+export function checkTaskMarkerSlot(node, grammar) {
+    if (!holdsListItem(node))
+        return null;
+    const reread = readBlocks(node.raw, { grammar, scope: 'fragment' }).children;
+    const reloaded = node.kind === 'listItem' ? soleItem(reread) : reread.length === 1 ? reread[0] : null;
+    return reloaded ? itemDrift(node, reloaded) : null;
+}
+/** The first list item whose checkbox or first block kind differs between the two trees, walked
+ *  together only where they have the same shape (other drift is another check's). */
+function itemDrift(tree, reload) {
+    if (tree.kind === 'listItem' && reload.kind === 'listItem') {
+        const task = metadataOf(tree, 'listItem')?.taskItem === true;
+        const reloadTask = metadataOf(reload, 'listItem')?.taskItem === true;
+        const blocks = kindsOf(tree);
+        const reloadBlocks = kindsOf(reload);
+        // A to-do's blocks are compared whole; a plain item's block drift is no checkbox question.
+        if (task !== reloadTask || (task && blocks !== reloadBlocks)) {
+            return {
+                code: 'task-marker-slot',
+                message: `a list item holds ${task ? 'a' : 'no'} checkbox before [${blocks}], where its reload reads ${reloadTask ? 'a' : 'no'} checkbox before [${reloadBlocks}]`,
+                detail: { taskItem: task, blocks, reloadTaskItem: reloadTask, reloadBlocks, raw: tree.raw }
+            };
+        }
+    }
+    const children = tree.children ?? [];
+    const reloadChildren = reload.children ?? [];
+    if (countsCells(tree) || children.length !== reloadChildren.length)
+        return null;
+    for (let i = 0; i < children.length; i++) {
+        if (children[i].kind !== reloadChildren[i].kind)
+            continue;
+        const found = itemDrift(children[i], reloadChildren[i]);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function kindsOf(node) {
+    return (node.children ?? []).map((child) => child.kind).join(', ');
+}
+function holdsListItem(node) {
+    if (node.kind === 'listItem')
+        return true;
+    if (countsCells(node))
+        return false;
+    return (node.children ?? []).some(holdsListItem);
+}
+function soleItem(blocks) {
+    const list = blocks.length === 1 && blocks[0].kind === 'list' ? blocks[0] : null;
+    return list?.children?.length === 1 ? list.children[0] : null;
+}

package/dist/invariants/open-tail.d.ts

@@ -0,0 +1,7 @@
+/**
+ * G1.41: after a structural commit only the document's last line may lack a line ending, and it
+ * lacks one exactly when it did before the commit, unless it is blank.
+ */
+import type { DocumentView } from '../core/node-views';
+import type { InvariantViolation } from '../assert';
+export declare function checkLastLineKept(doc: DocumentView, wasOpen: boolean): InvariantViolation | null;

package/dist/invariants/open-tail.js

@@ -0,0 +1,45 @@
+/**
+ * G1.41: after a structural commit only the document's last line may lack a line ending, and it
+ * lacks one exactly when it did before the commit, unless it is blank.
+ */
+import { ownTrailingLineEnding } from '../core/lines';
+import { holdsBlankLastLine } from '../tree-operations/open-tail';
+import { getBlockKindDescriptor, isGridDescriptor, isGridKind } from '../schema/block-kind-descriptor';
+export function checkLastLineKept(doc, wasOpen) {
+    const last = doc.children.at(-1);
+    if (!last)
+        return null;
+    const open = doc.suffix === '' && ownTrailingLineEnding(last.raw) === '';
+    const blank = doc.suffix !== '' || holdsBlankLastLine(last);
+    if (wasOpen && !open && !blank) {
+        return violation('the document had no final line break and gained one on a written line');
+    }
+    if (!wasOpen && open)
+        return violation('the document ended in a line break and lost it');
+    const glued = unendedAboveLastLine(doc.children, 'document');
+    return glued ? violation(`${glued} ends with no line break above the last line`) : null;
+}
+function violation(message) {
+    return { code: 'last-line-kept', message };
+}
+/** The first node on the last line's path, from the top down, whose sibling above it lacks an
+ *  ending: those two lines read as one. */
+function unendedAboveLastLine(children, trail) {
+    const last = children.at(-1);
+    if (!last)
+        return null;
+    const above = children.at(-2);
+    if (above && ownTrailingLineEnding(above.raw) === '')
+        return `${trail} > ${above.kind}`;
+    const next = holdsLastLineInChildren(last) ? last.children : undefined;
+    return next ? unendedAboveLastLine(next, `${trail} > ${last.kind}`) : null;
+}
+/** The last line runs through a strip container's last child and a grid's last row; an opaque
+ *  body and a row's cells sit inside the container's own lines. */
+function holdsLastLineInChildren(node) {
+    if (!node.children?.length)
+        return false;
+    const descriptor = getBlockKindDescriptor(node.kind);
+    return (descriptor.containerContract === 'strip' ||
+        (isGridDescriptor(descriptor) && isGridKind(node.children.at(-1).kind)));
+}

package/dist/invariants/placement-ends-widget.d.ts

@@ -0,0 +1,8 @@
+/**
+ * G1.46: a caret or range the editor puts down leaves no widget selected whole. Taking the caret
+ * ends the widget through the selection state's clears; a clear that skipped it would leave the
+ * image looking selected while the keys go to the caret.
+ */
+import type { InvariantViolation } from '../assert';
+import type { WidgetTarget } from '../selection/primitives';
+export declare function checkPlacementEndsWidget(widget: WidgetTarget | null): InvariantViolation | null;

package/dist/invariants/placement-ends-widget.js

@@ -0,0 +1,13 @@
+/**
+ * G1.46: a caret or range the editor puts down leaves no widget selected whole. Taking the caret
+ * ends the widget through the selection state's clears; a clear that skipped it would leave the
+ * image looking selected while the keys go to the caret.
+ */
+export function checkPlacementEndsWidget(widget) {
+    if (widget === null)
+        return null;
+    return {
+        code: 'placement-ends-widget',
+        message: `a caret or range was put down while the widget at ${JSON.stringify(widget.paragraphPath)}:${widget.sourceStart} stayed selected: end it through the selection state's clear`
+    };
+}