@voithos-labs/aragonite 0.10.1

package/dist/editor-rects.js

@@ -0,0 +1,114 @@
+/**
+ * Viewport-space geometry over the rendered document, the public face of the measurement
+ * primitives block components expose. Offsets inherit `measurePartialRects`' per-surface
+ * meaning (raw offsets on prose leaves, cell-index coordinates on grid surfaces). Rects
+ * are real only in a browser — jsdom reports ~0-sized boxes — so e2e covers this surface,
+ * not unit tests.
+ */
+import { tick } from 'svelte';
+// Post-mount measure passes settle within a few Svelte flushes; `tick` is the repo's only
+// sequencing primitive, so the wait is a bounded count of them.
+const REVEAL_SETTLE_TICKS = 12;
+export function createEditorRects(deps) {
+    function isInView(el, root) {
+        const br = el.getBoundingClientRect();
+        // Self mode: the root IS the scrollport, and what lies outside it is the host
+        // page's business, not the editor's.
+        if (!deps.isHostScroll()) {
+            const er = root.getBoundingClientRect();
+            return br.top < er.bottom && br.bottom > er.top;
+        }
+        if (br.top >= window.innerHeight || br.bottom <= 0)
+            return false;
+        for (const bound of deps.getClipBounds()) {
+            const cr = bound.getBoundingClientRect();
+            if (br.top >= cr.bottom || br.bottom <= cr.top)
+                return false;
+        }
+        return true;
+    }
+    // The anchor's re-assertion (`correctAnchor`) is model-based and runs pre-flush, so it
+    // can lag the DOM by a boundary block's height; each tick refines placement AFTER the
+    // flush, when DOM reads are exact, and stops once the target stops moving. A SUPERSEDED
+    // claim bails at once (the viewport belongs to the newer reveal), but one that merely
+    // lost its pin to a user gesture keeps refining — it is still arriving.
+    async function settleInView(path, block, claim) {
+        const root = deps.getEditorRoot();
+        if (!root)
+            return deps.getBlockElByPath(path) != null;
+        let placedTop = null;
+        for (let i = 0; i < REVEAL_SETTLE_TICKS; i++) {
+            await tick();
+            if (claim.isSuperseded())
+                break;
+            const el = deps.getBlockElByPath(path);
+            if (!el) {
+                placedTop = null; // transiently unmounted mid re-slice — keep settling
+                continue;
+            }
+            // Converged: the anchor correction no longer disturbs the prior precise placement.
+            const afterAnchor = el.getBoundingClientRect().top;
+            if (afterAnchor === placedTop)
+                break;
+            el.scrollIntoView({ block });
+            placedTop = el.getBoundingClientRect().top;
+        }
+        const el = deps.getBlockElByPath(path);
+        return el != null && isInView(el, root);
+    }
+    return {
+        blockRect(path) {
+            return deps.getBlockElByPath(path)?.getBoundingClientRect() ?? null;
+        },
+        rangeRects(path, start, end) {
+            return deps.getBlockComponentByPath(path)?.measurePartialRects?.(start, end) ?? [];
+        },
+        caretRect() {
+            // Read SelectionState, not the `data-cross-block` DOM mirror: that attribute is
+            // written by a deferred $effect and lags the synchronous selectionChange emit, so
+            // a subscriber reading mid-emit would get the parked range as a caret.
+            if (deps.isCrossBlock())
+                return null;
+            const root = deps.getEditorRoot();
+            if (!root)
+                return null;
+            const selection = window.getSelection();
+            if (!selection || selection.rangeCount === 0)
+                return null;
+            const range = selection.getRangeAt(0);
+            if (!root.contains(range.commonAncestorContainer))
+                return null;
+            // A caret in the host's header slot is inside the root but is not a document
+            // caret; reporting it would float caret-following chrome over the host's field.
+            if (deps.isHostChrome(range.commonAncestorContainer))
+                return null;
+            return range.getBoundingClientRect();
+        },
+        async reveal(path) {
+            await deps.revealPath(path);
+            return deps.getBlockElByPath(path) != null;
+        },
+        async scrollTo(path, opts) {
+            const p = [...path];
+            const block = opts?.block ?? 'nearest';
+            // Claim before the first await so the pin survives a clearing gesture that
+            // triggered this reveal (a match click's pointerdown releases, then this re-claims).
+            const claim = deps.revealAnchor.claim(p, block);
+            await deps.revealPath(p);
+            // Gated: a claim superseded during a long mount wait would otherwise yank the
+            // viewport once, before the settle's first tick could bail it.
+            if (!claim.isSuperseded())
+                deps.getBlockElByPath(p)?.scrollIntoView({ block });
+            const landed = await settleInView(p, block, claim);
+            // Release on 'center': the anchor holds only a coarse pin, whose later corrections
+            // would drift a target the settle already placed exactly. 'nearest' holds by
+            // default — the coarse top-pin IS its contract. A failed reveal never pins.
+            if (block === 'center' || !landed || opts?.hold === false)
+                claim.release();
+            return landed;
+        },
+        navigateTo(path, offset = 0) {
+            return deps.landCaretAt([...path], offset);
+        }
+    };
+}

package/dist/env.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The editor's toolchain-coupling seam: build flags come from `esm-env`, here and at the
+ * `if (DEV)` gates whose constant a production build folds away. The override door for a
+ * toolchain those defaults read wrong (a bundler resolving no export conditions, a runner
+ * other than Vitest) is published on the `@voithos-labs/aragonite/testing` subpath, not from here.
+ */
+export declare const editorEnv: {
+    isDev: boolean;
+    isTest: boolean;
+};
+export declare function configureEditorEnv(partial: Partial<typeof editorEnv>): void;
+export declare function resetEditorEnv(): void;

package/dist/env.js

@@ -0,0 +1,20 @@
+/**
+ * The editor's toolchain-coupling seam: build flags come from `esm-env`, here and at the
+ * `if (DEV)` gates whose constant a production build folds away. The override door for a
+ * toolchain those defaults read wrong (a bundler resolving no export conditions, a runner
+ * other than Vitest) is published on the `@voithos-labs/aragonite/testing` subpath, not from here.
+ */
+import { DEV } from 'esm-env';
+function computeDefaults() {
+    return {
+        isDev: DEV,
+        isTest: typeof process !== 'undefined' && !!process?.env?.VITEST
+    };
+}
+export const editorEnv = computeDefaults();
+export function configureEditorEnv(partial) {
+    Object.assign(editorEnv, partial);
+}
+export function resetEditorEnv() {
+    Object.assign(editorEnv, computeDefaults());
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export { default as Editor } from './components/Editor.svelte';
+export type { EditorProps, EditorInstance } from './editor-props';
+export type { EditorDiagnostics, InteractionTraceEntry } from './editor-props';
+export type { BlockComponent } from './block-component';
+export type { ResolveImageUrl, ResolveLinkUrl, PastedImage, PasteImageHook } from './editor-keys';
+export type { ImageLoadPolicy } from './core/inline-render';
+export type { PresentationMode } from './presentation-mode';
+export type { SearchState, SearchOptions } from './search/search-state.svelte';
+export type { Match } from './search/document-scan';
+export { installPlugins } from './schema/plugin-install';
+export type { EditorPlugin, EditorPluginEntry } from './schema/plugin-install';
+export type { EditorSelection, SelectionPoint } from './selection/primitives';
+export { normalize as normalizeSelection } from './selection/primitives';
+export type { KeybindingOverride } from './schema/keybinding-overrides';
+export type { CommandId } from './schema/commands';
+export { TOOLBAR_COMMANDS } from './schema/commands';
+export { parse, type ParseScope } from './core/parser';
+export { serialize } from './core/serializer';
+export { parseInline, getContentRange, isProseKind } from './core/inline';
+export type { ContentRange } from './core/inline';
+export type { BlockKind, LeafBlockKind, ContainerBlockKind, AnyBlockKind, CstNode, Document, BlockMetadata, HeadingMetadata, SetextHeadingMetadata, FencedCodeMetadata, ThematicBreakMetadata, LinkReferenceDefinitionMetadata, TableMetadata, BlockquoteMetadata, ListMetadata, ListItemMetadata, InlineNodeKind, InlineNode } from './core/nodes';
+export type { NodeView, DocumentView } from './core/node-views';
+export type { EditorEvents, EditEvent, EditorEventMap, EditorError, SelectionChangeEvent } from './editor-events';
+export type { Decoration, MarkDecoration, WidgetDecoration, ReplaceDecoration, BlockDecoration, DecorationWidgetSpec, ProvideContext, DecorationSource, DecorationSourceHandle, DecorationRegistry } from './decorations/types';
+export type { EditorRects } from './editor-rects';
+export { SELECTION_END } from './block-component';
+export type { SelectionEnd } from './block-component';

package/dist/index.js

@@ -0,0 +1,19 @@
+// Public, supported surface of the editor module: adding an export is non-breaking,
+// removing one is breaking. Anything not re-exported here is internal.
+// ── Component ────────────────────────────────────────────────────────────────
+export { default as Editor } from './components/Editor.svelte';
+// ── Plugins ────────────────────────────────────────────────────────────────────
+// installPlugins is for editor-less `parse()` pipelines that need the grammar live
+// without mounting <Editor>.
+export { installPlugins } from './schema/plugin-install';
+// Document order over a selection's endpoints, so a host anchoring UI to a range needn't
+// re-derive path-lexicographic comparison.
+export { normalize as normalizeSelection } from './selection/primitives';
+// ── Commands (pre-freeze: the id space opens up when the command registry unifies) ──
+// The ids `editor.runCommand()` supports — what a selection toolbar needs.
+export { TOOLBAR_COMMANDS } from './schema/commands';
+// ── CST utilities ────────────────────────────────────────────────────────────
+export { parse } from './core/parser';
+export { serialize } from './core/serializer';
+export { parseInline, getContentRange, isProseKind } from './core/inline';
+export { SELECTION_END } from './block-component';

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

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+import type { Document } from '../core/nodes';
+import type { DocPath } from '../selection/path-math';
+import type { InvariantViolation } from '../assert';
+export declare function checkCommitPathAddressable(doc: Document, path: DocPath, role: 'eventPath' | 'snapshot.path'): InvariantViolation | null;

package/dist/invariants/commit-paths.js

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+export function checkCommitPathAddressable(doc, path, role) {
+    let parent = doc;
+    for (let i = 0; i < path.length; i++) {
+        const children = parent.children;
+        const idx = path[i];
+        const isLast = i === path.length - 1;
+        const limit = (children?.length ?? 0) + (isLast ? 1 : 0);
+        if (!children || idx < 0 || idx >= limit) {
+            return {
+                code: 'commit-path-dialect',
+                message: `commit ${role} [${path.join(',')}] does not resolve from the document root`,
+                detail: { role, path, failedAt: i }
+            };
+        }
+        if (!isLast)
+            parent = children[idx];
+    }
+    return null;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * 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).
+ */
+export declare function beginCommit(): void;
+export declare function endCommit(): void;
+export declare function isCommitInProgress(): boolean;

package/dist/invariants/commit-scope.js

@@ -0,0 +1,16 @@
+/**
+ * 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).
+ */
+let inCommit = false;
+export function beginCommit() {
+    inCommit = true;
+}
+export function endCommit() {
+    inCommit = false;
+}
+export function isCommitInProgress() {
+    return inCommit;
+}

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

@@ -0,0 +1,7 @@
+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.
+ */
+export declare function checkNoContainerHistoryKey(setKeys: symbol[], historyKey: symbol): InvariantViolation | null;

package/dist/invariants/context-keys.js

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+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'
+        };
+    }
+    return null;
+}

package/dist/invariants/descriptor.d.ts

@@ -0,0 +1,10 @@
+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.
+ */
+export declare function checkContentRange(node: CstNode, getRange?: (node: CstNode) => ContentRange): InvariantViolation | null;

package/dist/invariants/descriptor.js

@@ -0,0 +1,24 @@
+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.
+ */
+export function checkContentRange(node, getRange = getContentRange) {
+    const descriptor = getBlockKindDescriptor(node.kind);
+    if (!descriptor.supportsInline && descriptor.getContentRange === undefined)
+        return null;
+    const { start, end } = getRange(node);
+    const len = displayLength(node.raw);
+    if (!(0 <= start && start <= end && end <= len)) {
+        return {
+            code: 'content-range-out-of-bounds',
+            message: `content range [${start}, ${end}] out of bounds for "${node.kind}" (len ${len})`,
+            detail: { kind: node.kind, start, end, len }
+        };
+    }
+    return null;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export declare function checkCompositionEndPaired(composing: boolean): InvariantViolation | null;

package/dist/invariants/inline-transitions.js

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+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'
+            }
+            : null;
+    }
+    if (passOpen)
+        return null;
+    return action === 'acquire'
+        ? {
+            code: 'acquire-outside-bracket',
+            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'
+        };
+}
+/**
+ * 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.
+ */
+export function checkRevealSourceLength(sourceLength, sourceStart, sourceEnd) {
+    if (sourceLength === sourceEnd - sourceStart)
+        return null;
+    return {
+        code: 'source-length-mismatch',
+        message: 'reveal source length differs from its [sourceStart, sourceEnd) range',
+        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.
+ */
+export function checkCompositionEndPaired(composing) {
+    if (composing)
+        return null;
+    return {
+        code: 'end-without-start',
+        message: 'compositionend with no open composition — the surface never saw compositionstart'
+    };
+}

package/dist/invariants/install.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Seam-side glue between the pure predicates and the `assertInvariant` channel, so the
+ * predicates themselves stay pure and unaware of it.
+ */
+import type { CstNode, Document } from '../core/nodes';
+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.
+ */
+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`.
+ */
+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.
+ */
+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).
+ */
+export declare function runStartupInvariantChecks(): void;

package/dist/invariants/install.js

@@ -0,0 +1,66 @@
+/**
+ * Seam-side glue between the pure predicates and the `assertInvariant` channel, so the
+ * predicates themselves stay pure and unaware of it.
+ */
+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 { checkContentRange } from './descriptor';
+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) {
+    for (const node of nodes) {
+        assertInvariant('stale-raw', () => checkStaleRaw(node));
+        assertInvariant('opaque-stale-raw', () => checkOpaqueStaleRaw(node));
+        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));
+    }
+}
+/**
+ * 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.
+ */
+export function assertCommitPaths(doc, snapshotPath, eventPath) {
+    if (snapshotPath) {
+        assertInvariant('commit-path-dialect', () => checkCommitPathAddressable(doc, snapshotPath, 'snapshot.path'));
+    }
+    if (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`.
+ */
+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.
+ */
+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).
+ */
+export function runStartupInvariantChecks() {
+    flushPendingRegistrationChecks();
+    checkInlineConstructPoliciesAtMount();
+}

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

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+import { type PresentationMode } from '../presentation-mode';
+import type { InvariantViolation } from '../assert';
+export declare function checkLandableCaret(focused: HTMLElement, mode: PresentationMode, blockPath: readonly number[]): InvariantViolation | null;

package/dist/invariants/landable-caret.js

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+import { hidesMarkers } from '../presentation-mode';
+import { paintsNoLandableContent } from '../cursor/widget-offset';
+export function checkLandableCaret(focused, mode, blockPath) {
+    // Reading takes no keystrokes, so a construct that paints nothing is correct there.
+    if (mode === 'reading' || !hidesMarkers(mode))
+        return null;
+    const el = editableSurfaceOf(focused);
+    if (!el || !paintsNoLandableContent(el))
+        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`,
+        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. */
+function editableSurfaceOf(focused) {
+    const el = focused.closest('[contenteditable]');
+    return el && el.getAttribute('contenteditable') !== 'false' ? el : null;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+import type { InvariantViolation } from '../assert';
+export declare function checkMarkerCssParity(editorRoot: HTMLElement): InvariantViolation | null;