@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/invariants/registry.d.ts

@@ -1,15 +1,10 @@
 import type { AnyBlockKind, AnyInlineKind, BlockKind } from '../core/nodes';
 import type { InvariantViolation } from '../assert';
-/**
- * G1.2 — every BlockKind resolves to a descriptor, and to a component unless it
- * renders inside a parent (see `NO_STANDALONE_COMPONENT`). Returns the first gap.
- */
+/** G1.2: every BlockKind resolves to a descriptor, and to a component unless it renders inside a
+ *  parent. Returns the first gap. */
 export declare function checkRegistryCompleteness(kinds: readonly BlockKind[], hasDescriptor: (kind: BlockKind) => boolean, hasComponent: (kind: BlockKind) => boolean): InvariantViolation | null;
-/**
- * G1.10 — opener-registry coherence: every registered opener belongs to a registered kind,
- * and priorities are unique. Equal priorities are deterministic (dispatch falls back to
- * kind name) but usually unintended, so they still warn.
- */
+/** G1.10: every opener belongs to a registered kind, and no two share a priority. A tie still
+ *  dispatches by kind name but is almost always a mistake, so it warns. */
 export declare function checkOpenerRegistry(entries: readonly {
     kind: AnyBlockKind;
     priority: number;
@@ -21,28 +16,18 @@ export interface KeymapCoherenceEntry {
         command: string;
     }[];
 }
-/**
- * G1.11 — keymap coherence: every binding uses a well-formed chord naming a known command,
- * and a kind's chords are unique after normalization. A mistyped `Ctrl+B` collapses to a
- * bare `B` that fires on every keypress; duplicates make dispatch order
- * declaration-dependent. Chords are scoped per kind.
- */
-export declare function checkKeymapCoherence(entries: readonly KeymapCoherenceEntry[], isKnownCommand: (id: string) => boolean, normalizeChord: (chord: string) => string, isChordWellFormed: (chord: string) => boolean): InvariantViolation | null;
-/**
- * G1.17 — opener registered after the grammar was consumed. Parsed documents never
- * re-parse, so the new kind silently misses every open document.
- */
+/** G1.11: every binding names a known command, and a kind binds each chord once. Checked at the flush,
+ *  not at registration, since a plugin can register its kind before the command. */
+export declare function checkKeymapCoherence(entries: readonly KeymapCoherenceEntry[], isKnownCommand: (id: string) => boolean): InvariantViolation | null;
+/** G1.17: an opener registered after the grammar was read. Parsed documents never reparse, so the
+ *  new kind misses every document already open. */
 export declare function checkLateOpenerRegistration(kind: AnyBlockKind, grammarConsumed: boolean): InvariantViolation | null;
 export interface ReservedChromeCoherenceEntry {
     kind: AnyBlockKind;
-    isContainer: boolean;
     reservedChromeKind?: AnyBlockKind;
 }
-/**
- * G1.18 — reservedChrome bootstrap coherence: a declaring kind must be a container, and
- * its chrome kind must resolve to both a descriptor and a component. Validates the
- * registration shape at bootstrap, unlike the per-commit slot check (G1.14).
- */
+/** G1.18: the title-row kind a container's `reservedChrome` names has a descriptor and a
+ *  component. G1.14 checks the child itself on every commit. */
 export declare function checkReservedChromeCoherence(entries: readonly ReservedChromeCoherenceEntry[], hasDescriptor: (kind: AnyBlockKind) => boolean, hasComponent: (kind: AnyBlockKind) => boolean): InvariantViolation | null;
 type ClosureCellMode = 'implemented' | 'inherit-default' | 'not-supported';
 export interface ClosureCoherenceEntry {
@@ -59,12 +44,8 @@ export interface ClosureCoherenceEntry {
     declaresReservedChrome: boolean;
     clipboardMode: ClosureCellMode;
 }
-/**
- * G1.24 — closure-block coherence: cross-checks between a kind's closure cells and the
- * rest of its descriptor that a compiler can't reach. Each violation message below states
- * its own rule. The fixture-parses-to-kind check runs in the unit sweep instead — a
- * `parse` import here would close a `schema → core/parser → schema` cycle.
- */
+/** G1.24: cross-checks between a kind's closure cells and the rest of its descriptor that the
+ *  compiler cannot reach. The fixture-parse check is in the unit suite, which avoids a cycle. */
 export declare function checkClosureCoherence(entries: readonly ClosureCoherenceEntry[]): InvariantViolation | null;
 export interface InlineConstructPolicyEntry {
     kind: AnyInlineKind;
@@ -77,50 +58,30 @@ export interface InlineConstructPolicyEntry {
         command: string;
     };
 }
-/**
- * G1.31 — inline-construct policy coherence: a row names a kind the inline vocabulary holds; the
- * marker-rewriting behaviors belong only to kinds whose markers the reveal can address; no two mark
- * rows claim one nesting rank or one command; and no plugin row's mark claims a built-in command id.
- * A mistyped kind is silent, a rewrite on a never-revealed kind edits markers the author cannot see,
- * and a tied or built-in command leaves which meaning answers to each surface's own lookup order.
- */
+/** G1.31: each inline-policy row names a real kind, gives marker rewrites only to kinds that show
+ *  their markers, and holds a unique nesting rank and command, never a built-in one. */
 export declare function checkInlineConstructPolicy(entries: readonly InlineConstructPolicyEntry[], isKnownInlineKind: (kind: AnyInlineKind) => boolean, isBuiltinInlineKind: (kind: AnyInlineKind) => boolean, isBuiltinCommandId: (id: string) => boolean): InvariantViolation | null;
 export interface DescriptorFieldEntry {
     kind: AnyBlockKind;
-    declaresWholeBlockFocus: boolean;
-    supportsInline: boolean;
-    declaresReservedChrome: boolean;
     contextDependentKind: boolean;
     hasOpener: boolean;
-    unwrapLiftsFirstChild: boolean;
-    unwrapKeepsReservedChrome: boolean;
 }
-/**
- * G1.37 — descriptor-vs-descriptor coherence: field pairs the type can represent and the kind
- * cannot mean together. Each is silently inert rather than loud, so nothing fails until a
- * gesture reaches the kind. G1.24 is the sibling over closure cells; this one reads the
- * declarations alone.
- */
+/** G1.37: a context-dependent kind registers no opener. The two live in separate registries, so
+ *  the registration type can't see the pair; it fails silently until a gesture reaches the kind. */
 export declare function checkDescriptorFieldCoherence(entries: readonly DescriptorFieldEntry[]): InvariantViolation | null;
-export interface ContentStartBackspaceEntry {
-    kind: AnyBlockKind;
-    demotesFirst: boolean;
-    declaresContentRange: boolean;
-}
-/**
- * G1.32 — a kind demoting on Backspace at its content start declares where that content starts.
- * Without the hook the content range IS the whole display, so the arm never fires and the
- * declaration reads as behavior the kind does not have — silent, and only at the keystroke.
- */
-export declare function checkContentStartBackspace(entries: readonly ContentStartBackspaceEntry[]): InvariantViolation | null;
 export interface MergeRoleEntry {
     kind: AnyBlockKind;
     mergeRole: string;
 }
-/**
- * G1.30 — every registered kind declares a `mergeRole` from the known vocabulary. A
- * per-KIND fact, validated once at registration: an unknown role makes the merge
- * dispatcher fall through silently on every gesture that reaches the kind.
- */
+/** G1.30: every kind declares a known `mergeRole`, checked once at registration, since an unknown
+ *  role makes the merge dispatcher fall through silently. */
 export declare function checkMergeRoleVocabulary(entries: readonly MergeRoleEntry[], isKnownMergeRole: (role: string) => boolean): InvariantViolation | null;
+export interface PresentationFactEntry {
+    kind: AnyBlockKind;
+    declaresPageRole: boolean;
+    declaresEstimateHeight: boolean;
+}
+/** G1.40: every built-in kind declares how it reads on the page and its likely height; a built-in
+ *  left on the defaults would take a plugin's guesses unnoticed. */
+export declare function checkBuiltinPresentationFacts(entries: readonly PresentationFactEntry[]): InvariantViolation | null;
 export {};

package/dist/invariants/registry.js

@@ -1,17 +1,13 @@
 /**
- * Registry predicates take every lookup as a parameter — pure by construction, and a
- * schema import here would cycle with the registration seam
- * (`schema/registration-checks.ts`) that supplies the real registries.
- */
-/**
- * `listItem` renders inside its parent `ListBlock`, never via a `BlockHost` kind lookup,
- * so it is the one BlockKind with no component-registry entry by design.
+ * The registry checks take every lookup as a parameter, so they stay pure and so this file never
+ * imports `schema`: `schema/registration-checks.ts` supplies the real registries, and importing
+ * it back would close a cycle.
  */
+/** `listItem` renders inside its parent `ListBlock`, never through a `BlockHost` lookup, so it is
+ *  the one kind with no component-registry entry. */
 const NO_STANDALONE_COMPONENT = new Set(['listItem']);
-/**
- * G1.2 — every BlockKind resolves to a descriptor, and to a component unless it
- * renders inside a parent (see `NO_STANDALONE_COMPONENT`). Returns the first gap.
- */
+/** G1.2: every BlockKind resolves to a descriptor, and to a component unless it renders inside a
+ *  parent. Returns the first gap. */
 export function checkRegistryCompleteness(kinds, hasDescriptor, hasComponent) {
     for (const kind of kinds) {
         if (!hasDescriptor(kind)) {
@@ -31,11 +27,8 @@ export function checkRegistryCompleteness(kinds, hasDescriptor, hasComponent) {
     }
     return null;
 }
-/**
- * G1.10 — opener-registry coherence: every registered opener belongs to a registered kind,
- * and priorities are unique. Equal priorities are deterministic (dispatch falls back to
- * kind name) but usually unintended, so they still warn.
- */
+/** G1.10: every opener belongs to a registered kind, and no two share a priority. A tie still
+ *  dispatches by kind name but is almost always a mistake, so it warns. */
 export function checkOpenerRegistry(entries, hasDescriptor) {
     const seen = new Map();
     for (const { kind, priority } of entries) {
@@ -50,7 +43,7 @@ export function checkOpenerRegistry(entries, hasDescriptor) {
         if (holder !== undefined) {
             return {
                 code: 'opener-registry',
-                message: `kinds "${holder}" and "${kind}" share opener priority ${priority} — order falls back to kind name; give each kind its own priority`,
+                message: `kinds "${holder}" and "${kind}" share opener priority ${priority}: order falls back to kind name; give each kind its own priority`,
                 detail: { kinds: [holder, kind], priority }
             };
         }
@@ -58,25 +51,14 @@ export function checkOpenerRegistry(entries, hasDescriptor) {
     }
     return null;
 }
-/**
- * G1.11 — keymap coherence: every binding uses a well-formed chord naming a known command,
- * and a kind's chords are unique after normalization. A mistyped `Ctrl+B` collapses to a
- * bare `B` that fires on every keypress; duplicates make dispatch order
- * declaration-dependent. Chords are scoped per kind.
- */
-export function checkKeymapCoherence(entries, isKnownCommand, normalizeChord, isChordWellFormed) {
+/** G1.11: every binding names a known command, and a kind binds each chord once. Checked at the flush,
+ *  not at registration, since a plugin can register its kind before the command. */
+export function checkKeymapCoherence(entries, isKnownCommand) {
     for (const { kind, keymap } of entries) {
         if (!keymap)
             continue;
         const seenChords = new Set();
         for (const binding of keymap) {
-            if (!isChordWellFormed(binding.chord)) {
-                return {
-                    code: 'keymap-coherence',
-                    message: `kind "${kind}" binds malformed chord "${binding.chord}" — modifiers must be Mod/Alt/Shift and the key non-empty`,
-                    detail: { kind, chord: binding.chord, issue: 'malformed' }
-                };
-            }
             if (!isKnownCommand(binding.command)) {
                 return {
                     code: 'keymap-coherence',
@@ -84,7 +66,7 @@ export function checkKeymapCoherence(entries, isKnownCommand, normalizeChord, is
                     detail: { kind, chord: binding.chord, command: binding.command }
                 };
             }
-            const chord = normalizeChord(binding.chord);
+            const chord = binding.chord;
             if (seenChords.has(chord)) {
                 return {
                     code: 'keymap-coherence',
@@ -97,35 +79,23 @@ export function checkKeymapCoherence(entries, isKnownCommand, normalizeChord, is
     }
     return null;
 }
-/**
- * G1.17 — opener registered after the grammar was consumed. Parsed documents never
- * re-parse, so the new kind silently misses every open document.
- */
+/** G1.17: an opener registered after the grammar was read. Parsed documents never reparse, so the
+ *  new kind misses every document already open. */
 export function checkLateOpenerRegistration(kind, grammarConsumed) {
     if (!grammarConsumed)
         return null;
     return {
         code: 'late-opener-registration',
-        message: `opener for "${kind}" registered after documents were parsed — already-parsed documents will not re-parse; register plugins before first mount`,
+        message: `opener for "${kind}" registered after documents were parsed: already-parsed documents will not re-parse; register plugins before first mount`,
         detail: { kind }
     };
 }
-/**
- * G1.18 — reservedChrome bootstrap coherence: a declaring kind must be a container, and
- * its chrome kind must resolve to both a descriptor and a component. Validates the
- * registration shape at bootstrap, unlike the per-commit slot check (G1.14).
- */
+/** G1.18: the title-row kind a container's `reservedChrome` names has a descriptor and a
+ *  component. G1.14 checks the child itself on every commit. */
 export function checkReservedChromeCoherence(entries, hasDescriptor, hasComponent) {
-    for (const { kind, isContainer, reservedChromeKind } of entries) {
+    for (const { kind, reservedChromeKind } of entries) {
         if (reservedChromeKind === undefined)
             continue;
-        if (!isContainer) {
-            return {
-                code: 'reserved-chrome-coherence',
-                message: `kind "${kind}" declares reservedChrome but is not a container`,
-                detail: { kind, chromeKind: reservedChromeKind, issue: 'not-container' }
-            };
-        }
         if (!hasDescriptor(reservedChromeKind)) {
             return {
                 code: 'reserved-chrome-coherence',
@@ -143,32 +113,25 @@ export function checkReservedChromeCoherence(entries, hasDescriptor, hasComponen
     }
     return null;
 }
-/**
- * Fixed phrases rather than a loose pattern: the claim is what a plugin author copies out
- * of the shipped descriptors, and "moves focus" (what an ordinary not-mergeable leaf does
- * at its edge) must stay outside the set.
- */
+/** Fixed phrases, not a pattern: plugin authors copy them from the shipped descriptors, and
+ *  "moves focus" (an ordinary leaf's edge) must stay outside the set. */
 const FOCUS_THEN_DELETE_CLAIMS = ['focus-then-delete', 'a second press deletes'];
 const claimsFocusThenDelete = (via) => via !== undefined && FOCUS_THEN_DELETE_CLAIMS.some((phrase) => via.includes(phrase));
-/**
- * G1.24 — closure-block coherence: cross-checks between a kind's closure cells and the
- * rest of its descriptor that a compiler can't reach. Each violation message below states
- * its own rule. The fixture-parses-to-kind check runs in the unit sweep instead — a
- * `parse` import here would close a `schema → core/parser → schema` cycle.
- */
+/** G1.24: cross-checks between a kind's closure cells and the rest of its descriptor that the
+ *  compiler cannot reach. The fixture-parse check is in the unit suite, which avoids a cycle. */
 export function checkClosureCoherence(entries) {
     for (const entry of entries) {
         if (entry.hasContainerContract && entry.roundTripMode === 'inherit-default') {
             return {
                 code: 'closure-coherence',
-                message: `kind "${entry.kind}" declares a container contract but its closure roundTrip is inherit-default — the container's rebuildRaw is the round-trip mechanism; declare roundTrip: implemented`,
+                message: `kind "${entry.kind}" declares a container contract but its closure roundTrip is inherit-default: the container's rebuildRaw is the round-trip mechanism; declare roundTrip: implemented`,
                 detail: { kind: entry.kind, column: 'roundTrip' }
             };
         }
         if (entry.notMergeable && entry.mergeBackspaceMode === 'inherit-default') {
             return {
                 code: 'closure-coherence',
-                message: `kind "${entry.kind}" is not-mergeable but its closure mergeBackspace is inherit-default — a not-mergeable kind has no default merge to inherit; name the non-merge mechanism (implemented) or mark it not-supported`,
+                message: `kind "${entry.kind}" is not-mergeable but its closure mergeBackspace is inherit-default: a not-mergeable kind has no default merge to inherit; name the non-merge mechanism (implemented) or mark it not-supported`,
                 detail: { kind: entry.kind, column: 'mergeBackspace' }
             };
         }
@@ -181,7 +144,7 @@ export function checkClosureCoherence(entries) {
             if (column !== undefined) {
                 return {
                     code: 'closure-coherence',
-                    message: `kind "${entry.kind}" claims the focus-then-delete model in its closure ${column} cell but declares no blockFocus: 'whole-block' — without it the caret-adjacent merge fallback deletes on the first press; declare the field or rewrite the cell to say what the kind actually does`,
+                    message: `kind "${entry.kind}" claims the focus-then-delete model in its closure ${column} cell but declares no blockFocus: 'whole-block'; without it the caret-adjacent merge fallback deletes on the first press; declare the field or rewrite the cell to say what the kind actually does`,
                     detail: { kind: entry.kind, column }
                 };
             }
@@ -189,20 +152,15 @@ export function checkClosureCoherence(entries) {
         if (entry.declaresReservedChrome && entry.clipboardMode === 'inherit-default') {
             return {
                 code: 'closure-coherence',
-                message: `kind "${entry.kind}" declares reservedChrome but its closure clipboard is inherit-default — the chrome bytes live in the container's own opener line, so a slice crossing that boundary has no default semantics; name what a copy produces (implemented) or mark it not-supported`,
+                message: `kind "${entry.kind}" declares reservedChrome but its closure clipboard is inherit-default: the chrome bytes live in the container's own opener line, so a slice crossing that boundary has no default semantics; name what a copy produces (implemented) or mark it not-supported`,
                 detail: { kind: entry.kind, column: 'clipboard' }
             };
         }
     }
     return null;
 }
-/**
- * G1.31 — inline-construct policy coherence: a row names a kind the inline vocabulary holds; the
- * marker-rewriting behaviors belong only to kinds whose markers the reveal can address; no two mark
- * rows claim one nesting rank or one command; and no plugin row's mark claims a built-in command id.
- * A mistyped kind is silent, a rewrite on a never-revealed kind edits markers the author cannot see,
- * and a tied or built-in command leaves which meaning answers to each surface's own lookup order.
- */
+/** G1.31: each inline-policy row names a real kind, gives marker rewrites only to kinds that show
+ *  their markers, and holds a unique nesting rank and command, never a built-in one. */
 export function checkInlineConstructPolicy(entries, isKnownInlineKind, isBuiltinInlineKind, isBuiltinCommandId) {
     const ranks = new Map();
     const commands = new Map();
@@ -210,7 +168,7 @@ export function checkInlineConstructPolicy(entries, isKnownInlineKind, isBuiltin
         if (!isKnownInlineKind(entry.kind)) {
             return {
                 code: 'inline-construct-policy',
-                message: `inline-construct policy registered for "${entry.kind}", which is neither a built-in inline kind nor a declared plugin one — the row is unreachable`,
+                message: `inline-construct policy registered for "${entry.kind}", which is neither a built-in inline kind nor a declared plugin one: the row is unreachable`,
                 detail: { kind: entry.kind, issue: 'unknown-kind' }
             };
         }
@@ -218,13 +176,12 @@ export function checkInlineConstructPolicy(entries, isKnownInlineKind, isBuiltin
             const clash = markClashOf(entry.kind, entry.mark, ranks, commands);
             if (clash)
                 return clash;
-            // The built-in vocabulary is closed and every id in it already answers somewhere, so a
-            // plugin mark claiming one shadows that meaning on whichever surface consults the mark
-            // table first — and the surfaces do not agree on where in their lookup that is.
+            // A built-in command id already means something, so a plugin mark taking one would shadow
+            // that meaning wherever the mark table is consulted first.
             if (!isBuiltinInlineKind(entry.kind) && isBuiltinCommandId(entry.mark.command)) {
                 return {
                     code: 'inline-construct-policy',
-                    message: `kind "${entry.kind}" claims built-in command "${entry.mark.command}" for its mark — that id already has a built-in meaning; mint a plugin command id for the mark`,
+                    message: `kind "${entry.kind}" claims built-in command "${entry.mark.command}" for its mark: that id already has a built-in meaning; create a plugin command id for the mark`,
                     detail: { kind: entry.kind, command: entry.mark.command, issue: 'builtin-command' }
                 };
             }
@@ -239,7 +196,7 @@ export function checkInlineConstructPolicy(entries, isKnownInlineKind, isBuiltin
         if (column !== undefined) {
             return {
                 code: 'inline-construct-policy',
-                message: `kind "${entry.kind}" is not revealable but its ${column} rewrites markers — a never-revealed construct's markers stay hidden, so the rewrite is invisible; mark the kind revealable or make the behavior atomic`,
+                message: `kind "${entry.kind}" is not revealable but its ${column} rewrites markers: a never-revealed construct's markers stay hidden, so the rewrite is invisible; mark the kind revealable or make the behavior atomic`,
                 detail: { kind: entry.kind, column }
             };
         }
@@ -251,7 +208,7 @@ function markClashOf(kind, mark, ranks, commands) {
     if (rankHolder !== undefined) {
         return {
             code: 'inline-construct-policy',
-            message: `kinds "${rankHolder}" and "${kind}" share mark nesting rank ${mark.nestingRank} — which one wraps the other would fall to registration order`,
+            message: `kinds "${rankHolder}" and "${kind}" share mark nesting rank ${mark.nestingRank}: which one wraps the other would fall to registration order`,
             detail: { kinds: [rankHolder, kind], nestingRank: mark.nestingRank }
         };
     }
@@ -259,7 +216,7 @@ function markClashOf(kind, mark, ranks, commands) {
     if (commandHolder !== undefined) {
         return {
             code: 'inline-construct-policy',
-            message: `kinds "${commandHolder}" and "${kind}" both claim command "${mark.command}" — one press cannot toggle two marks`,
+            message: `kinds "${commandHolder}" and "${kind}" both claim command "${mark.command}": one press cannot toggle two marks`,
             detail: { kinds: [commandHolder, kind], command: mark.command }
         };
     }
@@ -267,74 +224,22 @@ function markClashOf(kind, mark, ranks, commands) {
     commands.set(mark.command, kind);
     return null;
 }
-/**
- * G1.37 — descriptor-vs-descriptor coherence: field pairs the type can represent and the kind
- * cannot mean together. Each is silently inert rather than loud, so nothing fails until a
- * gesture reaches the kind. G1.24 is the sibling over closure cells; this one reads the
- * declarations alone.
- */
+/** G1.37: a context-dependent kind registers no opener. The two live in separate registries, so
+ *  the registration type can't see the pair; it fails silently until a gesture reaches the kind. */
 export function checkDescriptorFieldCoherence(entries) {
     for (const entry of entries) {
         if (entry.contextDependentKind && entry.hasOpener) {
             return {
                 code: 'descriptor-field-coherence',
-                message: `kind "${entry.kind}" declares contextDependentKind but registers an opener — the field suppresses the reparse that would re-derive the kind, so a kind the parser CAN recognize stops re-deriving; drop one`,
+                message: `kind "${entry.kind}" declares contextDependentKind but registers an opener: the field suppresses the reparse that would re-derive the kind, so a kind the parser can recognize stops re-deriving; drop one`,
                 detail: { kind: entry.kind, fields: ['contextDependentKind', 'opener'] }
             };
         }
-        if (entry.declaresWholeBlockFocus && entry.supportsInline) {
-            return {
-                code: 'descriptor-field-coherence',
-                message: `kind "${entry.kind}" declares blockFocus: 'whole-block' and supportsInline — a whole-block unit's only addressable offsets are 0 and its display length, so inline constructs parsed from its raw have no caret positions to live at`,
-                detail: { kind: entry.kind, fields: ['blockFocus', 'supportsInline'] }
-            };
-        }
-        if (entry.declaresWholeBlockFocus && entry.declaresReservedChrome) {
-            return {
-                code: 'descriptor-field-coherence',
-                message: `kind "${entry.kind}" declares blockFocus: 'whole-block' and reservedChrome — the chrome slot is always present, so the kind is never childless and the focus-then-delete model it declares can never engage`,
-                detail: { kind: entry.kind, fields: ['blockFocus', 'reservedChrome'] }
-            };
-        }
-        if (entry.declaresReservedChrome && entry.unwrapLiftsFirstChild) {
-            return {
-                code: 'descriptor-field-coherence',
-                message: `kind "${entry.kind}" declares reservedChrome and a lifting firstChildBackspace — child 0 is the chrome row, so Backspace at its start would carry the container's own title out as a sibling block; declare 'keep-reserved-chrome'`,
-                detail: { kind: entry.kind, fields: ['reservedChrome', 'firstChildBackspace'] }
-            };
-        }
-        if (entry.unwrapKeepsReservedChrome && !entry.declaresReservedChrome) {
-            return {
-                code: 'descriptor-field-coherence',
-                message: `kind "${entry.kind}" declares firstChildBackspace: 'keep-reserved-chrome' without reservedChrome — child 0 is body, so the declared decline makes Backspace at the body start a dead key; declare a lifting strategy`,
-                detail: { kind: entry.kind, fields: ['reservedChrome', 'firstChildBackspace'] }
-            };
-        }
-    }
-    return null;
-}
-/**
- * G1.32 — a kind demoting on Backspace at its content start declares where that content starts.
- * Without the hook the content range IS the whole display, so the arm never fires and the
- * declaration reads as behavior the kind does not have — silent, and only at the keystroke.
- */
-export function checkContentStartBackspace(entries) {
-    for (const { kind, demotesFirst, declaresContentRange } of entries) {
-        if (!demotesFirst || declaresContentRange)
-            continue;
-        return {
-            code: 'content-start-backspace',
-            message: `kind "${kind}" declares contentStartBackspace but no getContentRange — its content starts at raw 0, where the demote arm never fires and the declaration is silently inert`,
-            detail: { kind }
-        };
     }
     return null;
 }
-/**
- * G1.30 — every registered kind declares a `mergeRole` from the known vocabulary. A
- * per-KIND fact, validated once at registration: an unknown role makes the merge
- * dispatcher fall through silently on every gesture that reaches the kind.
- */
+/** G1.30: every kind declares a known `mergeRole`, checked once at registration, since an unknown
+ *  role makes the merge dispatcher fall through silently. */
 export function checkMergeRoleVocabulary(entries, isKnownMergeRole) {
     for (const { kind, mergeRole } of entries) {
         if (!isKnownMergeRole(mergeRole)) {
@@ -347,3 +252,22 @@ export function checkMergeRoleVocabulary(entries, isKnownMergeRole) {
     }
     return null;
 }
+/** G1.40: every built-in kind declares how it reads on the page and its likely height; a built-in
+ *  left on the defaults would take a plugin's guesses unnoticed. */
+export function checkBuiltinPresentationFacts(entries) {
+    for (const { kind, declaresPageRole, declaresEstimateHeight } of entries) {
+        const missing = !declaresPageRole
+            ? 'pageRole'
+            : !declaresEstimateHeight
+                ? 'estimateHeight'
+                : null;
+        if (missing === null)
+            continue;
+        return {
+            code: 'builtin-presentation-facts',
+            message: `built-in kind "${kind}" declares no ${missing}; declare it in built-in-descriptors.ts`,
+            detail: { kind, missing }
+        };
+    }
+    return null;
+}

package/dist/invariants/render-fidelity.d.ts

@@ -1,8 +1,8 @@
 /**
- * G1.28 — rendered text fidelity. A renderer round-tripping bytes through an HTML parser
- * inherits engine-defined normalizations (U+0000, line endings, surrogates), and a gesture
- * that reads `textContent` back would commit the loss away. jsdom preserves all of them,
- * so this runtime belt is the only thing that can catch it — a unit suite cannot.
+ * G1.28: the text a block renders still matches its raw bytes. A renderer that passes bytes
+ * through an HTML parser inherits whatever that browser normalizes (U+0000, line endings,
+ * surrogates), and a gesture that reads `textContent` back would commit the loss. jsdom preserves
+ * all of them, so only this runtime check can catch it, never a unit test.
  */
 import type { InvariantViolation } from '../assert';
 export declare function checkRenderedTextFidelity(rendered: string, expected: string): InvariantViolation | null;

package/dist/invariants/render-fidelity.js

@@ -1,8 +1,8 @@
 /**
- * G1.28 — rendered text fidelity. A renderer round-tripping bytes through an HTML parser
- * inherits engine-defined normalizations (U+0000, line endings, surrogates), and a gesture
- * that reads `textContent` back would commit the loss away. jsdom preserves all of them,
- * so this runtime belt is the only thing that can catch it — a unit suite cannot.
+ * G1.28: the text a block renders still matches its raw bytes. A renderer that passes bytes
+ * through an HTML parser inherits whatever that browser normalizes (U+0000, line endings,
+ * surrogates), and a gesture that reads `textContent` back would commit the loss. jsdom preserves
+ * all of them, so only this runtime check can catch it, never a unit test.
  */
 /** First index at which the strings differ, or -1. */
 function firstDivergence(rendered, expected) {
@@ -21,7 +21,7 @@ export function checkRenderedTextFidelity(rendered, expected) {
     const window = (text) => text.slice(Math.max(0, at - context), at + context);
     return {
         code: 'rendered-text-fidelity',
-        message: `rendered text diverges from the block's raw at index ${at} — the HTML parser normalized a byte the CST still holds`,
+        message: `rendered text diverges from the block's raw at index ${at}: the HTML parser normalized a byte the CST still holds`,
         detail: {
             at,
             renderedLength: rendered.length,

package/dist/invariants/selection-endpoints.d.ts

@@ -1,15 +1,14 @@
 /**
- * G1.29 — a cross-block endpoint's offset means what its block's coordinate space says: a cell
- * index on a table (a char offset there corrupts the grid through rangeDelete's generic branch),
- * a char offset inside [0, displayLength(raw)] elsewhere, and one of those two ends inside a
- * kind with no character positions (an interior one slices an opaque unit in half). Same-path
- * pairs are exempt (an intra-table rectangle's focus is unflagged by convention).
+ * G1.29: a stored endpoint's offset is read in its own block's coordinates. On a block that counts
+ * cells (a table) it is a flagged cell index inside the grid, a rectangle's corners included.
+ * Elsewhere it's a character offset inside `[0, displayLength(raw)]`, and inside a kind with no
+ * character positions one of those two ends, because anything between them cuts an opaque block.
  */
 import type { DocumentView } from '../core/node-views';
 import type { InvariantViolation } from '../assert';
 /**
- * Structural, NOT `selection/`'s `SelectionPoint`: no `invariants/` predicate takes a
- * dependency — runtime or type — on the selection model.
+ * A plain structural point, not `selection/`'s `SelectionPoint`: no check in `invariants/` depends
+ * on the selection model, at runtime or in its types.
  */
 export interface EndpointCoordinate {
     readonly path: readonly number[];

package/dist/invariants/selection-endpoints.js

@@ -1,12 +1,12 @@
 /**
- * G1.29 — a cross-block endpoint's offset means what its block's coordinate space says: a cell
- * index on a table (a char offset there corrupts the grid through rangeDelete's generic branch),
- * a char offset inside [0, displayLength(raw)] elsewhere, and one of those two ends inside a
- * kind with no character positions (an interior one slices an opaque unit in half). Same-path
- * pairs are exempt (an intra-table rectangle's focus is unflagged by convention).
+ * G1.29: a stored endpoint's offset is read in its own block's coordinates. On a block that counts
+ * cells (a table) it is a flagged cell index inside the grid, a rectangle's corners included.
+ * Elsewhere it's a character offset inside `[0, displayLength(raw)]`, and inside a kind with no
+ * character positions one of those two ends, because anything between them cuts an opaque block.
  */
 import { displayLength } from '../core/lines';
 import { isWholeBlockUnit } from '../schema/whole-block-unit';
+import { countsCells, tableCellCount } from '../schema/block-kind-descriptor';
 function resolve(doc, path) {
     let parent = doc;
     for (const idx of path) {
@@ -17,12 +17,7 @@ function resolve(doc, path) {
     }
     return parent === doc ? null : parent;
 }
-function samePath(a, b) {
-    return a.length === b.length && a.every((v, i) => v === b[i]);
-}
 export function checkCrossBlockEndpointCoordinates(doc, anchor, focus) {
-    if (samePath(anchor.path, focus.path))
-        return null;
     for (const [role, point] of [
         ['anchor', anchor],
         ['focus', focus]
@@ -38,11 +33,18 @@ export function checkCrossBlockEndpointCoordinates(doc, anchor, focus) {
     }
     return null;
 }
-/** The flag's other direction: a cell index against a block with no cells reads as a character
- *  offset downstream, so the same corruption arrives from the opposite producer. */
+/** The same mistake the other way round: a cell index on a block with no cells is read further
+ *  down as a character offset, so the corruption arrives from the opposite side. */
 function checkCellCoordinate(role, point, node) {
-    if (node.kind === 'table')
-        return null;
+    if (countsCells(node)) {
+        if (point.offset >= 0 && point.offset < tableCellCount(node))
+            return null;
+        return {
+            code: 'endpoint-cell-index-out-of-range',
+            message: `cross-block ${role} [${point.path.join(',')}] carries cell index ${point.offset}, outside the table's 0..${tableCellCount(node) - 1}`,
+            detail: { role, path: [...point.path], offset: point.offset }
+        };
+    }
     return {
         code: 'endpoint-cell-coordinate-off-table',
         message: `cross-block ${role} [${point.path.join(',')}] carries a cell index (${point.offset}) against a "${node.kind}", which has no cells`,
@@ -52,7 +54,7 @@ function checkCellCoordinate(role, point, node) {
 function checkCharOffset(role, point, node) {
     const detail = { role, path: [...point.path], offset: point.offset };
     const at = `cross-block ${role} [${point.path.join(',')}]`;
-    if (node.kind === 'table') {
+    if (countsCells(node)) {
         return {
             code: 'endpoint-cell-coordinate',
             message: `${at} addresses a table but carries a character offset (${point.offset})`,
@@ -70,7 +72,7 @@ function checkCharOffset(role, point, node) {
     if (isWholeBlockUnit(node) && point.offset !== 0 && point.offset !== end) {
         return {
             code: 'endpoint-whole-block-offset',
-            message: `${at} carries offset ${point.offset} inside "${node.kind}", which has no character positions — only 0 and ${end} address it`,
+            message: `${at} carries offset ${point.offset} inside "${node.kind}", which has no character positions: only 0 and ${end} address it`,
             detail
         };
     }