@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/testing/parse-convergence.js

@@ -1,37 +1,21 @@
 /**
- * The parse-convergence oracle. A byte round-trip after a mutation is a tautology (G2.1 makes
- * `serialize∘parse` identity), so this compares the LIVE tree against `parse(serialize(live))`
- * STRUCTURALLY instead: kinds, children shape, and parse-derived metadata. The comparison is
- * exact: the parser materializes blank lines as blocks, so an empty paragraph reparses as itself.
- * The reparse uses the ambient grammar, so an unregistered kind reads as a false divergence.
+ * Compares the live tree's structure (kinds, children, every metadata key) with a fresh parse
+ * of its own bytes; a byte round-trip would pass trivially, since `serialize(parse(s)) === s` for
+ * every input. `parseConverges` and `describeConvergence` take the editor's `grammar` when it
+ * has one; `assertParseConverged` reads with the default grammar.
  */
 import { parse } from '../core/parser';
 import { serialize } from '../core/serializer';
-import { show } from './conformance-core';
-// Typed against BlockMetadataByKind so a renamed or removed field is a compile error;
-// an ADDED field still needs enrolling by hand. Editor-level fields (childIds,
-// ownerEpoch) are not parse-derived, so the reparse never mints them.
-const METADATA_FIELDS = {
-    heading: ['level'],
-    setextHeading: ['level'],
-    fencedCode: ['fenceMarker', 'fenceLength', 'info', 'closed'],
-    thematicBreak: ['marker'],
-    linkReferenceDefinition: ['label', 'url', 'title'],
-    table: ['columnCount', 'alignments'],
-    tableRow: ['isHeader'],
-    blockquote: ['quoteDepth'],
-    list: ['ordered'],
-    listItem: ['marker', 'taskItem', 'taskChecked', 'taskMarker']
-};
-/** True when the live tree converges structurally with a fresh parse of its serialization. */
-export function parseConverges(doc) {
-    return describeConvergence(doc) === null;
+import { describeMetadataDivergence } from '../core/metadata-parity';
+/** True when the live tree matches a fresh parse of its own serialization, structurally. */
+export function parseConverges(doc, grammar) {
+    return describeConvergence(doc, grammar) === null;
 }
-/** The FIRST structural divergence from `parse(serialize(doc))`, or null when converged. */
-export function describeConvergence(doc) {
-    return diffChildren(doc, parse(serialize(doc)), []);
+/** The first structural difference from `parse(serialize(doc))`, or null when they match. */
+export function describeConvergence(doc, grammar) {
+    return diffChildren(doc, parse(serialize(doc), { grammar }), []);
 }
-/** Assert convergence, throwing a plain `Error` (runner-agnostic) on divergence. */
+/** Asserts the two match, throwing a plain `Error` on a difference so any runner can use it. */
 export function assertParseConverged(doc, label = 'parse convergence') {
     const divergence = describeConvergence(doc);
     if (divergence)
@@ -55,27 +39,8 @@ function diffNode(live, reparsed, path) {
     if (live.kind !== reparsed.kind) {
         return `${at} live kind "${live.kind}" != reparsed "${reparsed.kind}"`;
     }
-    const metaDivergence = diffMetadata(live, reparsed, at);
+    const metaDivergence = describeMetadataDivergence(live, reparsed);
     if (metaDivergence)
-        return metaDivergence;
+        return `${at} ${metaDivergence}`;
     return diffChildren(live, reparsed, path);
 }
-function diffMetadata(live, reparsed, at) {
-    const fields = METADATA_FIELDS[live.kind];
-    if (!fields)
-        return null;
-    const liveMeta = (live.metadata ?? {});
-    const reMeta = (reparsed.metadata ?? {});
-    for (const field of fields) {
-        if (!valuesEqual(liveMeta[field], reMeta[field])) {
-            return `${at} ${live.kind}.${field}: live ${show(liveMeta[field])} != reparsed ${show(reMeta[field])}`;
-        }
-    }
-    return null;
-}
-function valuesEqual(a, b) {
-    if (Array.isArray(a) && Array.isArray(b)) {
-        return a.length === b.length && a.every((v, i) => v === b[i]);
-    }
-    return a === b;
-}

package/dist/testing.d.ts

@@ -1,20 +1,24 @@
 /**
  * Reset the plugin platform's process-global registration state so a plugin's test suite
- * can re-install between cases: call it in `beforeEach`, then re-run your setup. Built-in
- * schema registrations and all runtime state (undo stack, selection, DOM/CST) survive —
- * except that the paste-surface reset clears ALL surfaces, so a case exercising built-in
- * paste afterward must re-register. Throws outside a detected test environment.
+ * can re-install between cases: call it in `beforeEach`, then re-run your setup. Every
+ * registration a plugin can make is dropped; the editor's built-ins and all runtime state
+ * (undo stack, selection, DOM/CST) survive. Throws outside a detected test environment.
  */
 export declare function resetPluginPlatformForTests(): void;
 export { configureEditorEnv, resetEditorEnv } from './env';
 export { installEditorDomStubsForTests } from './testing/mount-dom-stubs';
-export { applyPasteTransforms } from './tree-operations/paste/paste-transforms';
+/**
+ * The production paste pipeline, the very function every clipboard-to-parse path runs (G4.11),
+ * over `text` as an editor whose `plugins` prop lists `plugins` would run it; absent, every
+ * installed plugin's transforms run.
+ */
+export declare function applyPasteTransforms(text: string, plugins?: readonly string[]): string;
 export { setDevWarnSink } from './dev-warn';
 export type { DevWarnEntry, DevWarnSink } from './dev-warn';
+export type { CellReport, CellStatus, ConformanceCoverage } from './testing/conformance-core';
 export { runContainerConformance, reversedAncestryLeavesRootStale } from './testing/container-conformance';
-export type { ConformanceCoverage } from './testing/conformance-core';
-export type { ConformanceCell, ConformanceCellReport, ContainerConformanceProfile, ContainerConformanceReport, LocalIndexFixture } from './testing/container-conformance';
+export type { ConformanceCell, ContainerConformanceProfile, ContainerConformanceReport, LocalIndexFixture } from './testing/container-conformance';
 export { runKindConformance, checkCopyIsRawByteSlice } from './testing/kind-conformance';
-export type { KindCellCheck, KindCellContext, KindCellReport, KindCellStatus, KindConformanceProfile, KindConformanceReport } from './testing/kind-conformance';
+export type { KindCell, KindCellCheck, KindCellContext, KindConformanceProfile, KindConformanceReport } from './testing/kind-conformance';
 export { runInlineKindConformance } from './testing/inline-conformance';
-export type { InlineCellReport, InlineConformanceCell, InlineConformanceProfile, InlineConformanceReport } from './testing/inline-conformance';
+export type { InlineConformanceCell, InlineConformanceProfile, InlineConformanceReport } from './testing/inline-conformance';

package/dist/testing.js

@@ -1,61 +1,51 @@
-// The plugin-testing surface, published at the `@voithos-labs/aragonite/testing` subpath. TEST
-// PROCESSES ONLY, and nothing here may import a test runner — the kits run inside an
-// author's own case, so failures surface as plain `Error`s. The registries are
-// register-once with no unregister (docs/contributing/casebook.md), so every registration
-// reachable from `@voithos-labs/aragonite/plugin` must wire its reset into the aggregate below.
+// The plugin-testing API, published at the `@voithos-labs/aragonite/testing` subpath. For test
+// processes only, and nothing here may import a test runner: the kits run inside an author's
+// own case, so failures come back as plain `Error`s.
 import { editorEnv } from './env';
 import { __resetSchemaRegistriesForTests } from './schema/registry-reset';
-import { __resetPasteSurfacesForTests } from './tree-operations/paste-surfaces';
-import { __resetPasteTransformsForTests } from './tree-operations/paste/paste-transforms';
-import { __resetInlineSyntaxForTests } from './core/inline/scan/plugin-syntax';
-import { __resetInlineWidgetsForTests } from './core/inline/inline-widgets';
-import { __clearDeclaredPluginInlineKindsForTests } from './schema/plugin-kind';
-import { __resetDirectiveRegistryForTests } from './core/directive/registry';
+import { activationFor, everyInstalledPlugin } from './schema/plugin-activation';
+import { applyPasteTransforms as runPasteTransforms } from './tree-operations/paste/paste-transforms';
 /**
  * Reset the plugin platform's process-global registration state so a plugin's test suite
- * can re-install between cases: call it in `beforeEach`, then re-run your setup. Built-in
- * schema registrations and all runtime state (undo stack, selection, DOM/CST) survive —
- * except that the paste-surface reset clears ALL surfaces, so a case exercising built-in
- * paste afterward must re-register. Throws outside a detected test environment.
+ * can re-install between cases: call it in `beforeEach`, then re-run your setup. Every
+ * registration a plugin can make is dropped; the editor's built-ins and all runtime state
+ * (undo stack, selection, DOM/CST) survive. Throws outside a detected test environment.
  */
 export function resetPluginPlatformForTests() {
     if (!editorEnv.isTest) {
-        throw new Error('resetPluginPlatformForTests() is test-only — it wipes the process-global plugin ' +
+        throw new Error('resetPluginPlatformForTests() is test-only: it wipes the process-global plugin ' +
             'registries, which is corruption in a running editor. No test environment was ' +
             'detected (process.env.VITEST is unset). Detection is Vitest-specific; another ' +
             'runner opts in with configureEditorEnv({ isTest: true }), exported beside this.');
     }
     __resetSchemaRegistriesForTests();
-    __resetPasteSurfacesForTests();
-    __resetPasteTransformsForTests();
-    __resetInlineSyntaxForTests();
-    __resetInlineWidgetsForTests();
-    __clearDeclaredPluginInlineKindsForTests();
-    __resetDirectiveRegistryForTests();
 }
 // ── Editor env override ──────────────────────────────────────────────────────
-// The door the reset's own error names: a runner other than Vitest declares itself a
-// test environment here, and `resetEditorEnv` puts the detected defaults back.
+// What the reset's own error message points to: a runner other than Vitest declares itself
+// a test environment here, and `resetEditorEnv` puts the detected defaults back.
 export { configureEditorEnv, resetEditorEnv } from './env';
 // ── Mounting the editor under a non-browser DOM ──────────────────────────────
 export { installEditorDomStubsForTests } from './testing/mount-dom-stubs';
 // ── Paste pipeline ───────────────────────────────────────────────────────────
-// The production pipeline itself, not a test-only seam: the very function every
-// clipboard→parse route runs (G4.11), so driving it observes the registered
-// transforms rather than a re-implementation of them.
-export { applyPasteTransforms } from './tree-operations/paste/paste-transforms';
-// ── Dev-warning sink ─────────────────────────────────────────────────────────
-// The channel every editor dev warning reaches, so a suite can build its own
-// fail-on-warn gate: register a sink, drain it per case, red on what nobody claimed.
-// Runner-agnostic by contract, and a registered sink silences the console line.
+/**
+ * The production paste pipeline, the very function every clipboard-to-parse path runs (G4.11),
+ * over `text` as an editor whose `plugins` prop lists `plugins` would run it; absent, every
+ * installed plugin's transforms run.
+ */
+export function applyPasteTransforms(text, plugins) {
+    return runPasteTransforms(text, plugins ? activationFor(plugins) : everyInstalledPlugin);
+}
+// ── Where dev warnings go ────────────────────────────────────────────────────
+// The channel every editor dev warning reaches, for a suite's own fail-on-warning check: register
+// a callback, empty it per case, fail on leftovers. Registering one silences the console line.
 export { setDevWarnSink } from './dev-warn';
-// ── Container conformance kit (G4.3) ─────────────────────────────────────────
+// ── Container conformance kit ────────────────────────────────────────────────
 export { runContainerConformance, reversedAncestryLeavesRootStale } from './testing/container-conformance';
 // ── Generic per-kind conformance battery ─────────────────────────────────────
-// Registering a kind enrolls its headless closure cells; the browser sweep runs
-// the browser-only cells.
+// Registering a kind signs it up for the closure cells that run without a browser;
+// the browser pass runs the browser-only ones.
 export { runKindConformance, checkCopyIsRawByteSlice } from './testing/kind-conformance';
-// ── Inline-rung conformance kit ──────────────────────────────────────────────
-// The behavioral battery a registered inline rung is held to: what it claims, what
-// it declines, and whether its widget is one atomic unit.
+// ── Inline-syntax conformance kit ────────────────────────────────────────────
+// The behavioural tests a registered inline syntax handler is held to: what it takes,
+// what it declines, and whether its widget behaves as a single unit.
 export { runInlineKindConformance } from './testing/inline-conformance';

package/dist/tree-operations/blockquote.d.ts

@@ -1,18 +1,12 @@
 import type { CstNode } from '../core/nodes';
 import type { NodeView } from '../core/node-views';
+import type { GrammarView } from '../schema/block-openers';
+import type { RemainderBuilder } from './container-lift';
+/** A quote-shaped container's remainder is always a plain blockquote, since a marker like
+ *  `[!TYPE]` lives only on the opener line the lift drops. Its depth is its own first line's. */
+export declare function plainQuote(grammar: GrammarView): RemainderBuilder;
 /**
- * Unwrap a quote-shaped container's first child (Rule U2), returning fresh clones without
- * mutating the input. It lifts whatever container it is handed; the `lift-first-child-drop-opener`
- * strategy is what restricts the callers. The remainder is always a plain blockquote: a marker like
- * `[!TYPE]` lives only on the opener line, so lifting a body child out drops it and the rest
- * reparses as an ordinary quote.
+ * The replacement when Enter exits a quote's empty trailing paragraph: the trimmed quote, then the
+ * exit paragraph to focus, separated so a line typed there doesn't continue the quote on reload.
  */
-export declare function unwrapFirstChildFromQuote(container: NodeView): CstNode[];
-/**
- * The parent-level replacement when Enter exits a quote-shaped container's empty trailing
- * paragraph: `[trimmedContainer, exitParagraph]`, the caller's focus target at index 1.
- * Kind-agnostic through the descriptor's `rebuildRaw`; input unmutated. The exit paragraph
- * carries a separator like the list exit's, or a line typed there lazy-continues the
- * container on reload.
- */
-export declare function buildQuoteExitReplacement(container: NodeView): CstNode[];
+export declare function buildQuoteExitReplacement(container: NodeView, grammar: GrammarView): CstNode[];

package/dist/tree-operations/blockquote.js

@@ -1,59 +1,39 @@
-import { cloneMetadata, cloneNode } from './clone';
-import { rebuildBlockquoteRaw } from '../schema/container-rebuilders';
+import { cloneNode } from './clone';
 import { rebuildContainerRaw } from '../schema/container-raw';
 import { assignIds } from '../block-id';
 import { emptyParagraph } from './node-primitives';
-import { trailingLineEnding } from '../core/lines';
-/**
- * Unwrap a quote-shaped container's first child (Rule U2), returning fresh clones without
- * mutating the input. It lifts whatever container it is handed; the `lift-first-child-drop-opener`
- * strategy is what restricts the callers. The remainder is always a plain blockquote: a marker like
- * `[!TYPE]` lives only on the opener line, so lifting a body child out drops it and the rest
- * reparses as an ordinary quote.
- */
-export function unwrapFirstChildFromQuote(container) {
-    if (!container.children || container.children.length === 0) {
-        return [];
-    }
-    const clonedChildren = container.children.map(cloneNode);
-    const lifted = clonedChildren[0];
-    // The container's leading trivia is applied at the caller's splice point.
-    lifted.leadingTrivia = '';
-    if (clonedChildren.length === 1) {
-        return [lifted];
-    }
-    const remainingChildren = clonedChildren.slice(1);
-    remainingChildren[0].leadingTrivia = '';
-    const remaining = {
-        kind: 'blockquote',
-        leadingTrivia: '',
-        raw: '',
-        metadata: container.metadata && 'quoteDepth' in container.metadata
-            ? cloneMetadata(container.metadata)
-            : { quoteDepth: 1 },
-        children: remainingChildren,
-        childIds: assignIds(remainingChildren),
-        innerPrefix: container.innerPrefix ?? '',
-        innerSuffix: container.innerSuffix ?? ''
+import { firstLineEnding } from '../core/lines';
+/** A quote-shaped container's remainder is always a plain blockquote, since a marker like
+ *  `[!TYPE]` lives only on the opener line the lift drops. Its depth is its own first line's. */
+export function plainQuote(grammar) {
+    return (container, children) => {
+        const remaining = {
+            kind: 'blockquote',
+            leadingTrivia: '',
+            raw: '',
+            metadata: { quoteDepth: 1 },
+            children,
+            childIds: assignIds(children),
+            innerPrefix: container.innerPrefix ?? '',
+            innerSuffix: container.innerSuffix ?? ''
+        };
+        rebuildContainerRaw(remaining, grammar);
+        return remaining;
     };
-    rebuildBlockquoteRaw(remaining);
-    return [lifted, remaining];
 }
 /**
- * The parent-level replacement when Enter exits a quote-shaped container's empty trailing
- * paragraph: `[trimmedContainer, exitParagraph]`, the caller's focus target at index 1.
- * Kind-agnostic through the descriptor's `rebuildRaw`; input unmutated. The exit paragraph
- * carries a separator like the list exit's, or a line typed there lazy-continues the
- * container on reload.
+ * The replacement when Enter exits a quote's empty trailing paragraph: the trimmed quote, then the
+ * exit paragraph to focus, separated so a line typed there doesn't continue the quote on reload.
  */
-export function buildQuoteExitReplacement(container) {
+export function buildQuoteExitReplacement(container, grammar) {
     if (!container.children || container.children.length <= 1)
         return [];
     const trimmed = cloneNode(container);
     trimmed.children = trimmed.children.slice(0, -1);
     trimmed.childIds = assignIds(trimmed.children);
-    rebuildContainerRaw(trimmed);
-    // Every byte this op mints is a line ending, so it takes the container's (G4.20).
-    const lineEnding = trailingLineEnding(container.raw);
+    rebuildContainerRaw(trimmed, grammar);
+    // Every byte this op creates is a line ending. The quote spans two lines at least here, so
+    // its bytes hold the document's ending.
+    const lineEnding = firstLineEnding(container.raw) ?? '\n';
     return [trimmed, emptyParagraph(lineEnding, lineEnding)];
 }

package/dist/tree-operations/chain-rebuild.d.ts

@@ -1,22 +1,22 @@
 /**
- * The ancestry rebuild: raws re-derived along an owned spine chain innermost-first, each
- * container's kind re-derived and the seam at its own slot asked on the way out (editor.md § 9).
+ * The ancestor rebuild: raws re-derived up an owned chain of ancestors innermost first, each
+ * container's kind re-derived and the joins at its own position checked on the way out
+ * (`docs/design/editor.md` § The container `raw` contract).
  */
 import type { CstNode } from '../core/nodes';
 import type { SharingState } from './sharing';
-import type { NodeParent } from './node-primitives';
-import type { StructuralChange } from './structural-change';
+import { type NodeParent } from './node-primitives';
+import { type StructuralChange } from './structural-change';
 import type { GrammarView } from '../schema/block-openers';
 import { type TrackedPosition } from './settle';
 /**
- * Longest prefix of `chain` still attached under `root`, identity-checked level by level. A
- * commit mutation can splice a node out mid-ceremony, and rebuilding the detached node's raw
- * against its emptied children writes `raw: ''`; ancestors above the detachment still rebuild.
+ * Longest prefix of `chain` still attached under `root`: a node spliced out mid-commit would
+ * rebuild against its emptied children to `raw: ''`, while the ancestors above it still rebuild.
  */
 export declare function attachedChainPrefix(root: NodeParent, chain: CstNode[]): CstNode[];
 /**
- * One container slot a rebuild re-kinded. `previous` is the rollback register: a commit
- * unwinding after the swap has already published `replacement` into a live children array.
+ * One container position a rebuild gave a new kind. `previous` is what a rollback restores: a
+ * commit unwinding after the swap has already written `replacement` into a live children array.
  */
 export interface ContainerReclassification {
     siblings: CstNode[];
@@ -25,12 +25,12 @@ export interface ContainerReclassification {
     replacement: CstNode;
 }
 /**
- * A fold the rebuilt container's own slot owed: its bytes stopped interrupting a neighbour, so
- * the parent's array reloads as fewer blocks. `before` is the pre-splice array, the rollback
- * register, since the splice lands in an array no commit descriptor covers.
+ * A merge at the rebuilt container's own position: its bytes stopped interrupting a neighbour,
+ * so the parent's array reloads as fewer blocks. `before` is the pre-splice array, kept for
+ * rollback, since the splice lands in an array no commit descriptor covers.
  */
 export interface AncestrySeamFold {
-    /** Chain level of the folded container, so a caller composes the owner's path from its own. */
+    /** Chain level of the merged container, so a caller composes the owner's path from its own. */
     depth: number;
     siblings: CstNode[];
     /** The chain node owning `siblings`, or null when they are the rebuild root's children. */
@@ -40,24 +40,33 @@ export interface AncestrySeamFold {
     landing: TrackedPosition;
 }
 /**
- * What the typing door knows and a bare chain does not: where the chain sits in the document,
- * and the bytes its leaf carried before the write. Both are guesses the rebuild identity-checks.
+ * What the typing path knows and a bare chain does not: where the chain sits in the document,
+ * and the bytes its leaf held before the write. Both are guesses the rebuild checks by identity.
  */
 export interface ChainWriteHint {
     path: number[];
     leafPreviousRaw: string;
 }
 /**
- * Rebuild raws along an owned spine chain innermost-first, re-deriving each container's kind and
- * settling the seams at its own slot; chain- rather than path-based so it survives index shifts.
- * Both passes gate on a boundary line of the rebuilt raw moving. `folds` is required-nullable: a
- * fold splices the PARENT's array, so only a caller that reconciles that scope's ids/refs passes
- * a sink.
+ * One of several chains rebuilt in turn that share ancestors: this chain stops at level `floor`,
+ * leaving the levels above to a later chain, which reads whole any node in `readsWhole`.
  */
-export declare function rebuildUnsharedChain(root: NodeParent | CstNode, chain: CstNode[], sharing: SharingState, folds: AncestrySeamFold[] | null, grammar: GrammarView | undefined, hint?: ChainWriteHint): ContainerReclassification[];
+export interface SharedChainLevels {
+    readonly floor: number;
+    readonly readsWhole: Set<CstNode>;
+}
+/**
+ * The levels each chain rebuilds when the chains are rebuilt in this order, one per chain: a node
+ * several chains hold is left to the last of them, so it's rebuilt once, after everything below it.
+ */
+export declare function sharedChainLevels(chains: readonly (readonly CstNode[])[]): SharedChainLevels[];
+/**
+ * Rebuild raws up an owned chain innermost first, re-deriving kinds and joins where a first or
+ * last line moved. Only a caller that reconciles a merged array's ids and refs passes `folds`.
+ */
+export declare function rebuildUnsharedChain(root: NodeParent | CstNode, chain: CstNode[], sharing: SharingState, folds: AncestrySeamFold[] | null, grammar: GrammarView, hint?: ChainWriteHint, shared?: SharedChainLevels): ContainerReclassification[];
 /**
- * Unshare the spine to `path` and rebuild it innermost-first, tolerating paths that ran out of
- * range mid-walk (post-delete rebuild passes). Prefer `rebuildUnsharedChain` when indices may
- * have shifted since the unshare.
+ * Copy the ancestors down `path` and rebuild them, tolerating a path cut short by a delete.
+ * Prefer `rebuildUnsharedChain` when indices may have shifted since the copy.
  */
-export declare function rebuildUnsharedAncestry(root: NodeParent, path: number[], sharing: SharingState, folds: AncestrySeamFold[] | null, grammar: GrammarView | undefined): ContainerReclassification[];
+export declare function rebuildUnsharedAncestry(root: NodeParent, path: number[], sharing: SharingState, folds: AncestrySeamFold[] | null, grammar: GrammarView): ContainerReclassification[];