@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/decorations/island-dom.js

@@ -1,24 +1,17 @@
 /**
- * In-flow decoration islands: zero-width `widget` insertions and byte-carrying `replace`
- * covers. An island is an atomic inline widget, so the shared raw-offset walk reads the
- * block back byte-exact with no walker changes — a widget island spans zero bytes, and a
- * replace island's `data-source-*` span equals the raw span of the DOM it displaced.
- *
- * Whether a range is one the author could place at all is decided where the source and the
- * document it read are provably the same version (`decoration-state.svelte.ts`); a range
- * this pass cannot honour is one the document has since outgrown, so it drops silently.
+ * Decoration widgets placed in the text flow: a zero-width `widget`, and a `replace` covering
+ * real bytes. Each renders as an inline widget the caret cannot enter whose `data-source-*` span
+ * equals the bytes it stands for, so the offset walk reads the block back byte-exact. A range
+ * this pass cannot place drops silently; `decoration-state.svelte.ts` warns about it.
  */
-import { DEV } from 'esm-env';
-import { ambientSpanOf } from '../ambient/ambient-dom';
-import { asRawOffset, toDomTextOffset, toRawOffset } from '../cursor/coordinate-spaces';
-import { createRangeAtDomTextOffsets, rawTextOfNode, widgetSpanContainingOffset } from '../cursor/widget-offset';
+import { isDevChecks } from '../env';
+import { rawOfWalkOffset, rawRangeToDomRange, rawTextOfNode, walkOffsetOfRaw, widgetSpanContainingOffset } from '../cursor/widget-offset';
 import { devWarn } from '../dev-warn';
-/** Mutates `root` (the freshly built inline fragment). Returns destroy handles for
- *  mounted widgets — the caller sweeps them next rebuild. */
+/** Mutates `root`, the freshly built inline fragment. Returns one destroy function per
+ *  mounted widget; the caller runs them on the next rebuild. */
 export function applyIslandDecorations(root, raw, islands, opts) {
     if (islands.length === 0)
         return [];
-    const ambientLength = opts.ambientLength ?? 0;
     const contentLength = opts.contentLength;
     const destroys = [];
     for (const { dec } of orderForApplication(islands)) {
@@ -31,8 +24,7 @@ export function applyIslandDecorations(root, raw, islands, opts) {
     function applyWidget(dec) {
         if (dec.offset < 0 || dec.offset > contentLength)
             return;
-        const walkOffset = toDomTextOffset(asRawOffset(dec.offset), ambientLength);
-        const range = createRangeAtDomTextOffsets(root, walkOffset, walkOffset);
+        const range = rawRangeToDomRange(root, dec.offset, dec.offset);
         if (!range) {
             opts.onSkipped?.(dec, 'no DOM position at offset');
             return;
@@ -45,37 +37,34 @@ export function applyIslandDecorations(root, raw, islands, opts) {
         destroys.push(mounted.destroy);
         const island = buildIsland(dec.offset, dec.offset);
         island.appendChild(mounted.el);
-        insertHoistedOutOfAmbient(range, island);
+        range.insertNode(island);
     }
     function applyReplace(dec) {
         if (dec.start < 0 || dec.end > contentLength || dec.start >= dec.end)
             return;
-        // A boundary strictly inside an atomic widget snaps outward to whole-element
-        // coverage, so the island's span still equals the bytes it displaces.
+        // A boundary strictly inside a widget snaps outward to cover the whole element, so the
+        // span still equals the bytes it displaces.
         let start = dec.start;
         let end = dec.end;
-        const startSpan = widgetSpanContainingOffset(root, toDomTextOffset(asRawOffset(start), ambientLength));
+        const startSpan = widgetSpanContainingOffset(root, walkOffsetOfRaw(root, start));
         if (startSpan)
-            start = toRawOffset(startSpan.start, ambientLength);
-        const endSpan = widgetSpanContainingOffset(root, toDomTextOffset(asRawOffset(end), ambientLength));
+            start = rawOfWalkOffset(root, startSpan.start);
+        const endSpan = widgetSpanContainingOffset(root, walkOffsetOfRaw(root, end));
         if (endSpan)
-            end = toRawOffset(endSpan.end, ambientLength);
+            end = rawOfWalkOffset(root, endSpan.end);
         if (startSpan || endSpan) {
             devWarn('decorations', `replace boundary inside an atomic widget; snapped ${dec.start}..${dec.end} outward to ${start}..${end}`);
         }
-        const range = createRangeAtDomTextOffsets(root, toDomTextOffset(asRawOffset(start), ambientLength), toDomTextOffset(asRawOffset(end), ambientLength));
+        const range = rawRangeToDomRange(root, start, end);
         if (!range) {
             opts.onSkipped?.(dec, 'no DOM range for span');
             return;
         }
-        const ambient = ambientSpanOf(root);
-        if (ambient && ambient.contains(range.startContainer))
-            range.setStartAfter(ambient);
         const extracted = range.extractContents();
-        if (DEV) {
+        if (isDevChecks()) {
             const displaced = rawTextOfNode(extracted, raw);
             if (displaced !== raw.slice(start, end)) {
-                devWarn('decorations', 'replace island span disagrees with the displaced DOM bytes', {
+                devWarn('decorations', 'replace decoration span disagrees with the displaced DOM bytes', {
                     span: [start, end],
                     displaced
                 });
@@ -93,20 +82,9 @@ export function applyIslandDecorations(root, raw, islands, opts) {
         }
         range.insertNode(island);
     }
-    // The walk resolves a position at the ambient boundary to the END of the span's text,
-    // but an island must land after the span, never inside the read-only marker.
-    function insertHoistedOutOfAmbient(range, island) {
-        const ambient = ambientSpanOf(root);
-        if (ambient && ambient.contains(range.startContainer)) {
-            ambient.after(island);
-            return;
-        }
-        range.insertNode(island);
-    }
 }
-/** Gated island signature for a render key. No islands ⇒ '', keeping an undecorated
- *  block's key byte-identical to the island-free format. Widget identity is deliberately
- *  untracked: same position + class ⇒ equal signature (see DecorationWidgetSpec). */
+/** What these widgets add to a render key: `''` for none, so an undecorated block's key is
+ *  unchanged. Widget identity is ignored (see `DecorationWidgetSpec`). */
 export function islandRenderKeyPart(islands) {
     if (islands.length === 0)
         return '';
@@ -115,17 +93,14 @@ export function islandRenderKeyPart(islands) {
 const islandSig = (d) => d.type === 'widget'
     ? `w:${d.offset}:${d.side ?? 'after'}`
     : `r:${d.start}-${d.end}:${d.class ?? ''}:${d.widget ? 1 : 0}`;
-/** An island's ordering position, shared by the application pass and the render order. */
+/** A decoration's position for ordering, shared by the pass that applies them and the
+ *  render order. */
 export function islandPosition(dec) {
     return dec.type === 'widget' ? dec.offset : dec.start;
 }
 // ── Internal ────────────────────────────────────────────────────────────────
-/**
- * Descending position order, so a replace extraction never spans an island inserted
- * earlier in the pass. Ties put replaces first, since a same-start widget island would be
- * swallowed by the extraction; `side: 'after'` widgets follow, leaving the final DOM order
- * at one offset as [before, after].
- */
+/** Descending position order, so a `replace` extraction never spans a widget inserted earlier.
+ *  On a tie `replace` goes first, since a widget at the same start would be swallowed by it. */
 function orderForApplication(islands) {
     return [...islands].sort((a, b) => islandPosition(b.dec) - islandPosition(a.dec) ||
         tieRank(a.dec) - tieRank(b.dec) ||

package/dist/decorations/reserved-attrs.d.ts

@@ -1,12 +1,10 @@
 /**
- * The `data-` names a block decoration may not spell. `.block-host` is an ancestor of every walk
- * container, so an attribute here answers the ancestor lookups the CSS families, the offset walk
- * and selection/windowing all make — a decoration spelling one diverges the readers from what the
- * DOM actually holds. The list is what those consumers read via `closest()` or an ancestor
- * combinator; a name read only on the element that writes it is not in scope.
+ * The `data-` names a block decoration may not set: the ones the editor sets on a decorated element
+ * (a block host, a list item's box, a table row or cell) or reads there through a lookup or a
+ * stylesheet rule. A decoration taking one would answer that lookup or paint a state the editor
+ * never set. `reserved-block-attrs.test.ts` derives this list from the source and holds it to it.
  */
 export declare const RESERVED_BLOCK_ATTRS: ReadonlySet<string>;
-/** A block decoration's attributes minus the names it may not spell, which are dropped with a dev
- *  warn. Reserved is asked in lowercase: `setAttribute` lowercases, so a capital is not a
- *  different name, only a different spelling of the same one. */
+/** Drops the names a block decoration may not use, with a dev warning. Compared lowercase,
+ *  since `setAttribute` lowercases and a capital is only another spelling. */
 export declare function acceptedBlockAttrs(attrs: Record<string, string> | undefined, path: number[]): Array<[string, string]>;

package/dist/decorations/reserved-attrs.js

@@ -1,40 +1,54 @@
 /**
- * The `data-` names a block decoration may not spell. `.block-host` is an ancestor of every walk
- * container, so an attribute here answers the ancestor lookups the CSS families, the offset walk
- * and selection/windowing all make — a decoration spelling one diverges the readers from what the
- * DOM actually holds. The list is what those consumers read via `closest()` or an ancestor
- * combinator; a name read only on the element that writes it is not in scope.
+ * The `data-` names a block decoration may not set: the ones the editor sets on a decorated element
+ * (a block host, a list item's box, a table row or cell) or reads there through a lookup or a
+ * stylesheet rule. A decoration taking one would answer that lookup or paint a state the editor
+ * never set. `reserved-block-attrs.test.ts` derives this list from the source and holds it to it.
  */
 import { devWarn } from '../dev-warn';
 export const RESERVED_BLOCK_ATTRS = new Set([
-    'data-block-path',
     'data-block-kind',
+    'data-block-path',
     'data-content-empty',
-    'data-cross-block',
     'data-decoration-island',
     'data-focused',
-    'data-gap-caret',
     'data-image-overlay',
     'data-image-widget',
     'data-inline-widget',
+    'data-kind-cue',
     'data-link-card',
+    'data-list-marker',
+    'data-pointer-gesture',
     'data-presentation',
-    'data-table-row-idx'
+    'data-source-start',
+    'data-table-row-idx',
+    'data-task-checked',
+    'data-whole-block-input'
+]);
+/** The attributes every decorated element renders itself. A decoration's cleanup removes what
+ *  it set, so an overwrite would outlive the source: a row without `table-row`, a cell uneditable. */
+const ELEMENT_OWNED_ATTRS = new Set([
+    'class',
+    'contenteditable',
+    'role',
+    'style',
+    'tabindex'
 ]);
-/** The name production `setAttribute` enforces: a name it refuses throws inside the decoration
- *  effect, taking the whole mount rather than one attribute. */
+/** The name grammar `setAttribute` enforces: a name it refuses throws inside the decoration
+ *  effect, taking down the whole mount rather than one attribute. */
 const ATTR_NAME = /^[A-Za-z_:][A-Za-z0-9_.:-]*$/;
-/** A block decoration's attributes minus the names it may not spell, which are dropped with a dev
- *  warn. Reserved is asked in lowercase: `setAttribute` lowercases, so a capital is not a
- *  different name, only a different spelling of the same one. */
+/** Drops the names a block decoration may not use, with a dev warning. Compared lowercase,
+ *  since `setAttribute` lowercases and a capital is only another spelling. */
 export function acceptedBlockAttrs(attrs, path) {
     const accepted = [];
     for (const [name, value] of Object.entries(attrs ?? {})) {
+        const lowered = name.toLowerCase();
         const refusal = !ATTR_NAME.test(name)
             ? 'is not a valid attribute name'
-            : RESERVED_BLOCK_ATTRS.has(name.toLowerCase())
-                ? 'is reserved by the editor'
-                : null;
+            : lowered === 'class'
+                ? "is reserved by the editor (use the decoration's class field)"
+                : RESERVED_BLOCK_ATTRS.has(lowered) || ELEMENT_OWNED_ATTRS.has(lowered)
+                    ? 'is reserved by the editor'
+                    : null;
         if (refusal !== null) {
             devWarn('decorations', `block decoration attribute '${name}' ${refusal} and was dropped`, {
                 path

package/dist/decorations/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * View-only annotations layered over the rendered document. Decorations never enter the
- * CST: pure sources produce them per-instance, and overlays/islands consume them.
+ * CST: pure sources produce them per editor instance, and the overlays and inline widgets
+ * consume them.
  */
 import type { DocumentView } from '../core/node-views';
 export interface MarkDecoration {
@@ -47,8 +48,8 @@ export type DecorationWidgetSpec = {
     buildDom: (dec: Decoration) => HTMLElement;
 };
 export interface ProvideContext {
-    /** Bumped once per document change, never by invalidate(). The memo key for sources that
-     *  cache their scan; `doc.children` identity is NOT one, since typing mutates in place. */
+    /** Bumped once per document change, never by `invalidate()`. The memo key for a source that
+     *  caches its scan; `doc.children` identity is not one, since typing mutates in place. */
     editEpoch: number;
 }
 export interface DecorationSource {
@@ -56,10 +57,8 @@ export interface DecorationSource {
     provide: (doc: DocumentView, ctx: ProvideContext) => Decoration[];
 }
 export interface DecorationSourceHandle {
-    /** Synchronous by contract: decorations and buckets reflect the new result before this
-     *  returns. Search's setQuery relies on it — never defer. The one exception is a call
-     *  from inside a commit (an `edit` handler): those coalesce to one run once it publishes,
-     *  since a source must never read a half-applied tree. */
+    /** Synchronous: the decorations show the new result before it returns, which search's
+     *  `setQuery` relies on. A call from inside a commit runs once after the commit instead. */
     invalidate(): void;
     dispose(): void;
 }

package/dist/decorations/types.js

@@ -1,5 +1,6 @@
 /**
  * View-only annotations layered over the rendered document. Decorations never enter the
- * CST: pure sources produce them per-instance, and overlays/islands consume them.
+ * CST: pure sources produce them per editor instance, and the overlays and inline widgets
+ * consume them.
  */
 export {};

package/dist/decorations/use-block-decorations.svelte.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Applies the block decorations addressed to one path onto the element that renders that block:
+ * attributes and badges from effects, classes through the returned getter, which the caller
+ * spreads into its own `class` so Svelte keeps owning that attribute.
+ */
+import type { EditorError } from '../editor-events';
+import type { DecorationEngine } from './decoration-state.svelte';
+export interface BlockDecorationDeps {
+    getPath: () => number[];
+    getEl: () => HTMLElement | null;
+    /** Absent when a block mounts without the editor shell, as unit tests do. */
+    engine: DecorationEngine | undefined;
+    onRenderError: (error: EditorError) => void;
+    /** Why this element cannot hold a badge; when set, every badge is dropped with a dev warning. */
+    badgeRefusal?: string;
+}
+export declare function useBlockDecorations(deps: BlockDecorationDeps): {
+    readonly classes: string[];
+};

package/dist/decorations/use-block-decorations.svelte.js

@@ -0,0 +1,71 @@
+import { devWarn } from '../dev-warn';
+import { acceptedBlockAttrs } from './reserved-attrs';
+import { mountDecorationWidget } from './widget-dom';
+const NO_BLOCK_DECORATIONS = [];
+export function useBlockDecorations(deps) {
+    const decorations = $derived(deps.engine ? deps.engine.blockDecorationsForPath(deps.getPath()) : NO_BLOCK_DECORATIONS);
+    const classes = $derived(decorations.flatMap((d) => d.class ?? []));
+    // Set imperatively, not spread, so a source change or dispose removes exactly the
+    // keys it applied and leaves the element's own attributes alone.
+    $effect(() => {
+        const decs = decorations;
+        const el = deps.getEl();
+        if (!el || decs.length === 0)
+            return;
+        const appliedKeys = [];
+        for (const dec of decs) {
+            for (const [key, value] of acceptedBlockAttrs(dec.attrs, deps.getPath())) {
+                el.setAttribute(key, value);
+                appliedKeys.push(key);
+            }
+        }
+        return () => {
+            for (const key of appliedKeys)
+                el.removeAttribute(key);
+        };
+    });
+    // Badges go in ahead of the block's content, so BLOCK_CONTENT_SELECTOR
+    // (block-content-selector.ts) excludes `.decoration-badge`; keep the two in step.
+    $effect(() => {
+        const decs = decorations;
+        const el = deps.getEl();
+        if (!el || decs.length === 0)
+            return;
+        const destroys = [];
+        const badges = document.createDocumentFragment();
+        for (const dec of decs) {
+            if (!dec.badge)
+                continue;
+            if (deps.badgeRefusal !== undefined) {
+                devWarn('decorations', `block decoration badge dropped: ${deps.badgeRefusal}`, {
+                    path: deps.getPath()
+                });
+                continue;
+            }
+            const handle = mountDecorationWidget(dec.badge, dec, (error) => deps.onRenderError({ origin: 'render', error, context: { path: deps.getPath() } }));
+            if (!handle)
+                continue;
+            const wrapper = document.createElement('div');
+            wrapper.className = 'decoration-badge';
+            wrapper.setAttribute('contenteditable', 'false');
+            wrapper.appendChild(handle.el);
+            badges.appendChild(wrapper);
+            destroys.push(() => {
+                handle.destroy();
+                wrapper.remove();
+            });
+        }
+        if (destroys.length === 0)
+            return;
+        el.insertBefore(badges, el.firstChild);
+        return () => {
+            for (const destroy of destroys)
+                destroy();
+        };
+    });
+    return {
+        get classes() {
+            return classes;
+        }
+    };
+}

package/dist/decorations/widget-dom.d.ts

@@ -1,6 +1,6 @@
 /**
- * The one mounting seam for decoration widget specs, so error containment and teardown
- * semantics can't drift between block badges and inline islands.
+ * The one place a decoration widget is mounted, so error handling and teardown cannot drift
+ * between block badges and inline widgets.
  */
 import type { Decoration, DecorationWidgetSpec } from './types';
 export interface DecorationWidgetHandle {
@@ -9,7 +9,7 @@ export interface DecorationWidgetHandle {
     destroy(): void;
 }
 /**
- * Build a widget spec's DOM. A synchronous throw is contained and surfaced as null, so the
+ * Build a widget spec's DOM. A synchronous throw is caught and reported as null, so the
  * caller renders without the widget instead of tearing down the block.
  */
 export declare function mountDecorationWidget(spec: DecorationWidgetSpec, dec: Decoration, reportError?: (error: unknown) => void): DecorationWidgetHandle | null;

package/dist/decorations/widget-dom.js

@@ -1,10 +1,10 @@
 /**
- * The one mounting seam for decoration widget specs, so error containment and teardown
- * semantics can't drift between block badges and inline islands.
+ * The one place a decoration widget is mounted, so error handling and teardown cannot drift
+ * between block badges and inline widgets.
  */
 import { mount, unmount } from 'svelte';
 /**
- * Build a widget spec's DOM. A synchronous throw is contained and surfaced as null, so the
+ * Build a widget spec's DOM. A synchronous throw is caught and reported as null, so the
  * caller renders without the widget instead of tearing down the block.
  */
 export function mountDecorationWidget(spec, dec, reportError) {
@@ -12,8 +12,8 @@ export function mountDecorationWidget(spec, dec, reportError) {
         if ('component' in spec) {
             const el = document.createElement('span');
             const instance = mount(spec.component, { target: el, props: { decoration: dec } });
-            // The flag is what makes the documented idempotence real: a second `unmount` of the same
-            // instance is not a no-op the way a second `remove()` is.
+            // The flag is what makes `destroy` safe to call twice: a second `unmount` of the same
+            // instance is not harmless the way a second `remove()` is.
             let unmounted = false;
             return {
                 el,

package/dist/dev-warn.d.ts

@@ -5,9 +5,12 @@ export interface DevWarnEntry {
 }
 export type DevWarnSink = (entry: DevWarnEntry) => void;
 /**
- * Route fires to `next` instead of the console, and return the sink it replaced. For a
- * harness that must read fires structurally; runner-agnostic by contract, so nothing here
+ * Send warnings to `next` instead of the console, and return the callback it replaced. For
+ * a harness that needs to read them as data; it must work with any runner, so nothing here
  * may know about a test runner. Nothing registers one in production or on a dev server.
  */
 export declare function setDevWarnSink(next: DevWarnSink | null): DevWarnSink | null;
 export declare function devWarn(tag: string, message: string, details?: unknown): void;
+/** The tag a console line carries: the editor's own, or `svelte:<code>` for a Svelte runtime
+ *  warning, so one waiver list covers both; null for any other line. */
+export declare function warnTagOfLine(text: string): string | null;

package/dist/dev-warn.js

@@ -1,8 +1,8 @@
 import { editorEnv } from './env';
 let sink = null;
 /**
- * Route fires to `next` instead of the console, and return the sink it replaced. For a
- * harness that must read fires structurally; runner-agnostic by contract, so nothing here
+ * Send warnings to `next` instead of the console, and return the callback it replaced. For
+ * a harness that needs to read them as data; it must work with any runner, so nothing here
  * may know about a test runner. Nothing registers one in production or on a dev server.
  */
 export function setDevWarnSink(next) {
@@ -17,8 +17,8 @@ export function devWarn(tag, message, details) {
         sink({ tag, message, details });
         return;
     }
-    // The `aragonite:` sentinel is what the e2e watchers key on: a console head no page
-    // script or dependency shares, so a browser-side gate can fail on ours alone.
+    // The `aragonite:` prefix is what the e2e watchers key on: a console prefix no page
+    // script or dependency shares, so a browser-side check can fail on ours alone.
     if (details !== undefined) {
         console.warn(`[aragonite:${tag}] ${message}`, details);
     }
@@ -26,3 +26,15 @@ export function devWarn(tag, message, details) {
         console.warn(`[aragonite:${tag}] ${message}`);
     }
 }
+const EDITOR_TAG = /\[aragonite:([^\]]+)\]/;
+/** Svelte's runtime warnings lead with their code, after any `%c` styling. */
+const SVELTE_CODE = /\[svelte\]\s+([a-z0-9_]+)/;
+/** The tag a console line carries: the editor's own, or `svelte:<code>` for a Svelte runtime
+ *  warning, so one waiver list covers both; null for any other line. */
+export function warnTagOfLine(text) {
+    const tag = EDITOR_TAG.exec(text)?.[1];
+    if (tag)
+        return tag;
+    const code = SVELTE_CODE.exec(text)?.[1];
+    return code ? `svelte:${code}` : null;
+}

package/dist/editor-actions/ancestry-folds.d.ts

@@ -1,32 +1,27 @@
 /**
- * Publishing side of the ancestry settle (`tree-operations/chain-rebuild.ts`): a fold at a container's
- * own slot splices its PARENT's children, a scope the commit's own change descriptor never
- * covers, so that scope's ids and refs are resynced here instead.
+ * Writes the ancestor fix-up's results to state (`tree-operations/chain-rebuild.ts`): a
+ * container that collapsed after an edit (an `AncestrySeamFold`) splices its parent's children,
+ * a list the commit's own change never covers, so that list's ids and refs are resynced here.
  */
 import type { CstNode } from '../core/nodes';
 import type { AncestrySeamFold } from '../tree-operations/chain-rebuild';
 import { type StructuralChange } from '../tree-operations/structural-change';
 import type { EditorActionsDeps } from './deps';
-/** Where the folded container's first byte ended up, as a document path. */
+/** Where the collapsed container's first byte ended up, as a document path. */
 export interface FoldLanding {
     path: number[];
     offset: number;
 }
 /**
- * Resync every folded scope's ids/refs and return the unwind for them, which a commit rolling
- * back runs beside its own registers.
+ * Resync ids and refs for every collapse and return the function that undoes them, which a
+ * commit rolling back runs beside its own restores.
  */
 export declare function publishAncestryFolds(deps: EditorActionsDeps, folds: readonly AncestrySeamFold[]): () => void;
-/**
- * The landing a fold owes the caret: the container's slot is always gone (the reparse re-mints
- * every block in the folded window), so a door whose focus addressed it has nothing to land on.
- * `scopePath` is the committing scope's own path, from which the fold's depth names the parent.
- * The chain rebuilds innermost-first, so the LAST fold is the outermost one — the one whose slot
- * swallowed the others, and the only landing still addressable after them all.
- */
+/** Where the caret goes after a collapse recreated the blocks in its range. The last collapse is
+ *  the outermost (innermost rebuilds first), so its index is the only one still addressable. */
 export declare function foldLandingFor(folds: readonly AncestrySeamFold[], scopePath: readonly number[]): FoldLanding | null;
 /**
- * A splice made outside the commit ceremony, published as the ceremony publishes the change its
+ * A splice made outside a commit, written to state the way a commit writes the change its
  * mutate returns. `owner` is the container whose children moved, or undefined for the document.
  */
 export declare function publishScopeFold(deps: EditorActionsDeps, owner: CstNode | undefined, change: StructuralChange): void;

package/dist/editor-actions/ancestry-folds.js

@@ -1,7 +1,7 @@
 /**
- * Publishing side of the ancestry settle (`tree-operations/chain-rebuild.ts`): a fold at a container's
- * own slot splices its PARENT's children, a scope the commit's own change descriptor never
- * covers, so that scope's ids and refs are resynced here instead.
+ * Writes the ancestor fix-up's results to state (`tree-operations/chain-rebuild.ts`): a
+ * container that collapsed after an edit (an `AncestrySeamFold`) splices its parent's children,
+ * a list the commit's own change never covers, so that list's ids and refs are resynced here.
  */
 import { applyStructuralChangeToIdsRefs } from '../tree-operations/structural-change';
 import { spliceMany } from '../tree-operations/splice-many';
@@ -9,8 +9,8 @@ import { assignIds } from '../block-id';
 import { getStateForNode } from '../reactivity/state-registry';
 import { replaceRefs } from '../reactivity/publish-ref.svelte';
 /**
- * Resync every folded scope's ids/refs and return the unwind for them, which a commit rolling
- * back runs beside its own registers.
+ * Resync ids and refs for every collapse and return the function that undoes them, which a
+ * commit rolling back runs beside its own restores.
  */
 export function publishAncestryFolds(deps, folds) {
     const restores = [];
@@ -22,13 +22,8 @@ export function publishAncestryFolds(deps, folds) {
             restores[i]();
     };
 }
-/**
- * The landing a fold owes the caret: the container's slot is always gone (the reparse re-mints
- * every block in the folded window), so a door whose focus addressed it has nothing to land on.
- * `scopePath` is the committing scope's own path, from which the fold's depth names the parent.
- * The chain rebuilds innermost-first, so the LAST fold is the outermost one — the one whose slot
- * swallowed the others, and the only landing still addressable after them all.
- */
+/** Where the caret goes after a collapse recreated the blocks in its range. The last collapse is
+ *  the outermost (innermost rebuilds first), so its index is the only one still addressable. */
 export function foldLandingFor(folds, scopePath) {
     const fold = folds[folds.length - 1];
     if (!fold)
@@ -39,7 +34,7 @@ export function foldLandingFor(folds, scopePath) {
     };
 }
 /**
- * A splice made outside the commit ceremony, published as the ceremony publishes the change its
+ * A splice made outside a commit, written to state the way a commit writes the change its
  * mutate returns. `owner` is the container whose children moved, or undefined for the document.
  */
 export function publishScopeFold(deps, owner, change) {
@@ -59,13 +54,12 @@ function publishDocScope(deps, change) {
 }
 /**
  * Ids live on the owner node, which is what an unmounted container's BlockListState reads back;
- * refs live on the state and only exist while the scope is mounted.
+ * refs live on the state and only exist while the container is mounted.
  */
 function publishContainerScope(owner, change) {
     const state = getStateForNode(owner);
-    // A container that never mounted has no ids to carry across, and this runs AFTER the fold —
-    // so one fresh id per surviving child is the whole answer, where a descriptor over a window
-    // the seeded array never held would mis-shape it (G1.36).
+    // A never-mounted container has no ids to keep, so fresh ids for the surviving children are
+    // the whole answer; the change applied to an array that never held them misshapes it (G1.36).
     if (!owner.childIds) {
         owner.childIds = assignIds(owner.children ?? []);
         return;
@@ -100,7 +94,8 @@ function publishContainerFold(deps, fold) {
         restoreChildren(fold);
     };
 }
-/** The whole pre-splice array: a fold re-mints plural slots, so no narrower register covers it. */
+/** The whole pre-splice array: a collapse recreates several nodes, so nothing narrower
+ *  restores them. */
 function restoreChildren(fold) {
     spliceMany(fold.siblings, 0, fold.siblings.length, fold.before);
 }