@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/testing/headless-actions.d.ts

@@ -1,37 +1,52 @@
 /**
- * Headless editor-actions environment for the published conformance kit. These stubs
- * restate rather than reuse the in-repo `test/harness` mocks, which are `vi.fn()`-based:
- * `@voithos-labs/aragonite/testing` is imported into an author's own suite, so a static runner import
- * would load Vitest for anyone reaching for `resetPluginPlatformForTests` alone.
+ * The one headless `EditorActionsDeps` builder, behind the published conformance kits and the
+ * in-repo test harness alike. Nothing here may import a test runner, since an author's own suite
+ * imports this subpath; a runner's mock enters through the `spy` option.
  */
 import type { BlockEditActions, FocusActions } from '../action-contracts';
 import type { BlockComponent } from '../block-component';
 import type { CstNode, Document } from '../core/nodes';
-import type { StickyColumnState } from '../cursor/sticky-column';
-import type { EdgeAffinityState } from '../cursor/edge-affinity';
+import type { CaretMemory } from '../cursor/caret-memory';
 import type { EditorActionsDeps } from '../editor-actions/deps';
+import type { Reading } from '../schema/reading';
 import { type EditorEvents } from '../editor-events';
-import { type BlockListState } from '../reactivity/block-list-state.svelte';
-export declare function stubBlockComponent(): BlockComponent;
-export declare function stubStickyColumn(): StickyColumnState;
-export declare function stubEdgeAffinity(): EdgeAffinityState;
+import { type LandingOutcome } from '../selection/caret-landing';
+import { type CaretTarget } from '../selection/caret-target';
+export declare function stubBlockComponent(overrides?: Partial<BlockComponent>): BlockComponent;
+export declare function stubCaretMemory(): CaretMemory;
+/** A block list that writes nothing: every edit resolves false, and a content write is admitted
+ *  with its caret where the caller asked. */
 export declare function stubBlockEdit(): BlockEditActions;
-/** A focus bundle that records what bubbled up to it — the focus-bubble check's oracle. */
+/** A focus bundle that records what bubbled up to it, which is what the focus-bubble check reads. */
 export interface RecordingFocus extends FocusActions {
     /** Whole argument lists, so a check pins arity as well as values. */
     readonly moveFocusCalls: readonly unknown[][];
 }
 export declare function recordingFocus(): RecordingFocus;
-/**
- * A BlockListState seeded with one ref per child (the `$effect` that fills refs never
- * runs headlessly). `getNode` must read the LIVE node: the commit primitives replace the
- * spine's nodes, so a captured reference goes stale after the first commit.
- */
-export declare function mountBlockListState(getNode: () => CstNode): BlockListState;
+export interface HeadlessActionsOptions {
+    /** Wraps each stubbed collaborator (the caret memory, every block ref), so a runner's mock
+     *  can record the calls. */
+    spy?: <T extends object>(stub: T) => T;
+    /** A construction option because `SelectionState` cannot take one later. */
+    onSelectionChange?: () => void;
+    /** The editor's reading, for a suite whose editor is in another mode or switched a syntax off.
+     *  Absent, every installed plugin in styled source. */
+    reading?: Reading;
+    bumpContentVersion?: () => void;
+}
+/** A leaf a caret landing resolved to, and whether a mounted block took the caret. */
+export interface RecordedLanding extends CaretTarget {
+    readonly outcome: LandingOutcome;
+}
 export interface HeadlessActions {
     deps: EditorActionsDeps;
     doc: Document;
     events: EditorEvents;
+    /** Every caret landing that resolved to a leaf, in order, with what the landing did there. */
+    landings: readonly RecordedLanding[];
+    getBlockIds(): string[];
+    getBlockRefs(): (BlockComponent | undefined)[];
 }
-/** An `EditorActionsDeps` over `docChildren`, with every block treated as mounted. */
-export declare function createHeadlessActions(docChildren: CstNode[]): HeadlessActions;
+/** An `EditorActionsDeps` over `source`, every block treated as mounted. Pass the whole `Document`
+ *  or source text, not its children, which lose the trailing blank line its `suffix` holds. */
+export declare function createHeadlessActions(source: string | Document | CstNode[], options?: HeadlessActionsOptions): HeadlessActions;

package/dist/testing/headless-actions.js

@@ -1,48 +1,55 @@
 /**
- * Headless editor-actions environment for the published conformance kit. These stubs
- * restate rather than reuse the in-repo `test/harness` mocks, which are `vi.fn()`-based:
- * `@voithos-labs/aragonite/testing` is imported into an author's own suite, so a static runner import
- * would load Vitest for anyone reaching for `resetPluginPlatformForTests` alone.
+ * The one headless `EditorActionsDeps` builder, behind the published conformance kits and the
+ * in-repo test harness alike. Nothing here may import a test runner, since an author's own suite
+ * imports this subpath; a runner's mock enters through the `spy` option.
  */
+import { parse } from '../core/parser';
+import { withStoredCaret } from '../editor-actions/stored-caret';
+import { kitReading } from './kit-reading';
 import { createEditorEvents } from '../editor-events';
-import { createBlockListState } from '../reactivity/block-list-state.svelte';
 import { refSlotsOver, replaceRefs } from '../reactivity/publish-ref.svelte';
 import { createSelectionState } from '../selection/selection-state.svelte';
+import { createCaretLanding } from '../selection/caret-landing';
+import { caretTargetFor } from '../selection/caret-target';
 import { createSharingState } from '../tree-operations/sharing';
 import { createUndoManager } from '../undo/manager';
 // ── Stubs ────────────────────────────────────────────────────────────────────
-export function stubBlockComponent() {
+export function stubBlockComponent(overrides = {}) {
     return {
         focus: () => { },
         parkCaret: () => { },
         getCursorOffset: () => null,
         editable: true,
-        focusable: true
+        focusable: true,
+        ...overrides
     };
 }
-export function stubStickyColumn() {
-    return { get: () => null, reset: () => { }, capture: () => { }, noteKey: () => { } };
-}
-export function stubEdgeAffinity() {
+export function stubCaretMemory() {
     return {
-        get: () => null,
-        reset: () => { },
-        note: () => { },
+        column: () => null,
+        side: () => null,
+        pendingMarks: { get: () => null, toggle: () => { }, consume: () => null, restore: () => { } },
+        noteKey: () => { },
         noteTyping: () => { },
-        noteExtreme: () => { }
+        noteExtreme: () => { },
+        captureColumn: () => { },
+        forget: () => { }
     };
 }
+/** A block list that writes nothing: every edit resolves false, and a content write is admitted
+ *  with its caret where the caller asked. */
 export function stubBlockEdit() {
+    const wroteNothing = async () => false;
     return {
-        splitBlock: () => { },
-        descendToBody: () => { },
-        insertParagraph: () => { },
-        mergeWithPrevious: () => { },
-        mergeWithNext: () => { },
-        deleteBlock: () => { },
-        updateBlockContent: () => { },
-        updateBlockMetadata: () => { },
-        replaceBlock: () => { }
+        splitBlock: wroteNothing,
+        descendToBody: wroteNothing,
+        insertParagraph: wroteNothing,
+        mergeWithPrevious: wroteNothing,
+        mergeWithNext: wroteNothing,
+        deleteBlock: wroteNothing,
+        updateBlockContent: (_index, _text, _mode, preEditOffset, postEditFocusOffset) => withStoredCaret(Promise.resolve(false), postEditFocusOffset ?? preEditOffset),
+        updateBlockMetadata: wroteNothing,
+        replaceBlock: wroteNothing
     };
 }
 export function recordingFocus() {
@@ -52,29 +59,27 @@ export function recordingFocus() {
         moveFocus: (...args) => {
             moveFocusCalls.push(args);
         },
-        // The focus-bubble consumers assert on moveFocus, never on a resolved component.
-        revealPath: async () => null,
-        // Headless: no rendered boundary to park a gap caret at.
-        tryGapStop: () => false
+        // Headless: nothing is rendered, so there is no boundary to put a gap caret at and nothing
+        // to scroll.
+        tryGapStop: () => false,
+        followArrival: () => { }
     };
 }
-// ── Block-list state ─────────────────────────────────────────────────────────
-/**
- * A BlockListState seeded with one ref per child (the `$effect` that fills refs never
- * runs headlessly). `getNode` must read the LIVE node: the commit primitives replace the
- * spine's nodes, so a captured reference goes stale after the first commit.
- */
-export function mountBlockListState(getNode) {
-    const state = createBlockListState(() => getNode());
-    replaceRefs(state.innerBlockRefs, (getNode().children ?? []).map(() => stubBlockComponent()));
-    return state;
-}
-/** An `EditorActionsDeps` over `docChildren`, with every block treated as mounted. */
-export function createHeadlessActions(docChildren) {
-    const doc = { kind: 'document', prefix: '', children: docChildren, suffix: '' };
-    let blockIds = docChildren.map((_, i) => `block-${i}`);
-    const blockRefs = docChildren.map(() => stubBlockComponent());
+/** An `EditorActionsDeps` over `source`, every block treated as mounted. Pass the whole `Document`
+ *  or source text, not its children, which lose the trailing blank line its `suffix` holds. */
+export function createHeadlessActions(source, options = {}) {
+    const whole = documentOf(source);
+    const doc = {
+        kind: 'document',
+        prefix: whole.prefix,
+        children: whole.children,
+        suffix: whole.suffix
+    };
+    const spy = options.spy ?? ((stub) => stub);
+    let blockIds = doc.children.map((_, i) => `block-${i}`);
+    const blockRefs = doc.children.map(() => spy(stubBlockComponent()));
     const events = createEditorEvents();
+    const landings = [];
     const deps = {
         get doc() {
             return doc;
@@ -86,33 +91,79 @@ export function createHeadlessActions(docChildren) {
             return blockRefs;
         },
         blockRefSlots: refSlotsOver(blockRefs),
-        setDoc: (v) => {
-            Object.assign(doc, v);
+        // In place, so `doc` stays the one live document the caller holds.
+        setDoc: (next) => {
+            Object.assign(doc, next);
         },
-        setBlockIds: (v) => {
-            blockIds = v;
+        setBlockIds: (next) => {
+            blockIds = next;
         },
-        setBlockRefs: (v) => {
-            replaceRefs(blockRefs, v);
+        setBlockRefs: (next) => {
+            replaceRefs(blockRefs, next);
         },
-        bumpContentVersion: () => { },
+        bumpContentVersion: options.bumpContentVersion ?? (() => { }),
         undoManager: createUndoManager(),
         sharing: createSharingState(),
-        stickyColumn: stubStickyColumn(),
-        edgeAffinity: stubEdgeAffinity(),
-        selectionState: createSelectionState(),
+        caretMemory: spy(stubCaretMemory()),
+        // Document-aware, as the editor's own is: without the document a deep table endpoint is
+        // stored raw, and every dispatch sees endpoints the editor never makes.
+        selectionState: createSelectionState({
+            getDoc: () => doc,
+            ...(options.onSelectionChange ? { onChange: options.onSelectionChange } : {})
+        }),
         getBlockElByPath: () => null,
-        revealPath: async (path) => {
-            if (path.length === 0)
-                return null;
-            const ref = blockRefs[path[0]];
-            if (!ref)
-                return null;
-            if (path.length === 1)
-                return ref;
-            return ref.getBlockComponentByPath?.(path.slice(1)) ?? null;
+        get caretLanding() {
+            return caretLanding;
         },
-        events
+        events,
+        // An author's suite runs with no editor, so every installed plugin is in the grammar.
+        reading: options.reading ?? kitReading()
+    };
+    // No render window: nothing mounts later, so an empty entry counts as out of range.
+    const rootList = {
+        count: () => doc.children.length,
+        refs: deps.blockRefSlots,
+        windowing: { revealChild: async () => { }, isInWindow: (i) => blockRefs[i] !== undefined }
     };
-    return { deps, doc, events };
+    const caretLanding = recordingLanding(createCaretLanding({
+        getDoc: () => doc,
+        root: rootList,
+        selectionState: deps.selectionState,
+        // Read live: a suite may swap in its own caret memory after building the deps.
+        caretMemory: {
+            forget: () => deps.caretMemory.forget(),
+            noteExtreme: () => deps.caretMemory.noteExtreme()
+        },
+        getBlockElByPath: (path) => deps.getBlockElByPath(path),
+        getEditorRoot: () => null,
+        scroll: null
+    }), () => doc, landings);
+    return {
+        deps,
+        doc,
+        events,
+        landings,
+        getBlockIds: () => blockIds,
+        getBlockRefs: () => blockRefs
+    };
+}
+/** `landing` with each resolved leaf pushed onto `landings` once it has landed. */
+function recordingLanding(landing, getDoc, landings) {
+    return {
+        ...landing,
+        async land(pos, opts) {
+            const target = caretTargetFor(getDoc(), pos);
+            const outcome = await landing.land(pos, opts);
+            if (target)
+                landings.push({ ...target, outcome });
+            return outcome;
+        }
+    };
+}
+function documentOf(source) {
+    if (typeof source === 'string')
+        return parse(source);
+    if (Array.isArray(source))
+        return { kind: 'document', prefix: '', children: source, suffix: '' };
+    return source;
 }

package/dist/testing/headless-block-list.svelte.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The production `BlockListState` for a container no component mounts, as the conformance kits
+ * and the in-repo harness build it. `getNode` must read the live node: a commit replaces the
+ * ancestor nodes, so a captured reference goes stale after the first commit.
+ */
+import type { BlockComponent } from '../block-component';
+import type { CstNode } from '../core/nodes';
+import { type BlockListState } from '../reactivity/block-list-state.svelte';
+export interface HeadlessBlockListOptions {
+    /** The children's ids, written onto the node before the state reads them. */
+    ids?: string[];
+    /** The ref standing in for child `index`; `undefined` models a child outside the render
+     *  window. Defaults to a stub for every child, since no `$effect` fills refs headlessly. */
+    refAt?: (index: number) => BlockComponent | undefined;
+}
+export declare function mountBlockListState(getNode: () => CstNode, options?: HeadlessBlockListOptions): BlockListState;

package/dist/testing/headless-block-list.svelte.js

@@ -0,0 +1,22 @@
+/**
+ * The production `BlockListState` for a container no component mounts, as the conformance kits
+ * and the in-repo harness build it. `getNode` must read the live node: a commit replaces the
+ * ancestor nodes, so a captured reference goes stale after the first commit.
+ */
+import { createBlockListState } from '../reactivity/block-list-state.svelte';
+import { replaceRefs } from '../reactivity/publish-ref.svelte';
+import { stubBlockComponent } from './headless-actions';
+export function mountBlockListState(getNode, options = {}) {
+    if (options.ids)
+        getNode().childIds = [...options.ids];
+    let state;
+    // Its own effect root, since no component owns the state's effect. A server-compiled test
+    // never runs the root's body, and has no effects to own.
+    $effect.root(() => {
+        state = createBlockListState(getNode);
+    });
+    state ??= createBlockListState(getNode);
+    const refAt = options.refAt ?? (() => stubBlockComponent());
+    replaceRefs(state.innerBlockRefs, state.innerBlockIds.map((_, i) => refAt(i)));
+    return state;
+}

package/dist/testing/inline-conformance.d.ts

@@ -1,29 +1,28 @@
 /**
- * The inline-rung conformance kit, published at `@voithos-labs/aragonite/testing` — sibling of the block
- * layer's `runKindConformance` and the container kit. Reads the LIVE registry, so it
- * composes with `resetPluginPlatformForTests()` cycles. The four profile-declared cells are
- * required, not optional, since every one is invisible to byte round-trip; an exemption the
- * kit can falsify, it falsifies. Failures throw a plain `Error`.
+ * The conformance kit for an inline syntax handler (`InlineRung`), published at
+ * `@voithos-labs/aragonite/testing`. It reads the live registry, so it works across
+ * `resetPluginPlatformForTests()` cycles. The four cells a profile declares are required because
+ * byte round-trip sees none of them, and the kit disproves an exemption where it can.
  */
 import { type AnyInlineKind } from '../core/nodes';
-import { type ConformanceCoverage } from './conformance-core';
+import { type CellReport, type ConformanceCoverage } from './conformance-core';
 export interface InlineConformanceProfile {
-    /** The single character the rung registered on. */
+    /** The single character the handler registered on. */
     trigger: string;
-    /** The rung's multi-char prefix; omit for a bare-trigger registration. */
+    /** The handler's multi-character prefix. Omit for a bare-trigger registration. */
     prefix?: string;
-    /** Disambiguator when two rungs share a prefix on one trigger at different priorities. */
+    /** Tells two handlers apart when they share a prefix on one trigger at different priorities. */
     priority?: number;
     /**
-     * The inline kind the rung mints as its own. Omit for a rung that only mints
+     * The inline kind the handler creates as its own. Omit for a handler that only creates
      * built-in kinds over its own bytes (the `![[…]]`-as-`image` shape).
      */
     kind?: AnyInlineKind;
-    /** Single-line sources the rung CLAIMS. Non-empty: every other cell reads their nodes. */
+    /** Single-line sources the handler claims. Non-empty: every other cell reads their nodes. */
     fixtures: string[];
     /**
-     * Single-line sources whose bytes the rung's prefix matches but a built-in (or an
-     * earlier rung) owns. Required when `overlapDecline` asserts.
+     * Single-line sources whose bytes the handler's prefix matches but a built-in construct (or
+     * an earlier handler) owns. Required when `overlapDecline` asserts.
      */
     overlapFixtures?: string[];
     overlapDecline: ConformanceCoverage;
@@ -32,19 +31,13 @@ export interface InlineConformanceProfile {
     imageClaim: ConformanceCoverage;
 }
 export type InlineConformanceCell = 'claims' | 'roundTrip' | 'overlapDecline' | 'widget' | 'editingPolicy' | 'imageClaim' | 'registration';
-export interface InlineCellReport {
-    cell: InlineConformanceCell;
-    status: 'asserted' | 'exempt' | 'boundary';
-    /** Why a cell was excused, or which mechanism an asserted cell drove. */
-    detail?: string;
-}
 export interface InlineConformanceReport {
     trigger: string;
     prefix: string;
-    cells: InlineCellReport[];
+    cells: CellReport<InlineConformanceCell>[];
 }
 /**
- * Run every conformance cell for the registered rung the profile names. Returns the
+ * Runs every conformance cell for the registered handler the profile names. Resolves with the
  * coverage report, or throws an `Error` naming every failed cell.
  */
-export declare function runInlineKindConformance(profile: InlineConformanceProfile): InlineConformanceReport;
+export declare function runInlineKindConformance(profile: InlineConformanceProfile): Promise<InlineConformanceReport>;