@voithos-labs/aragonite 0.10.1

package/dist/decorations/decoration-state.svelte.js

@@ -0,0 +1,195 @@
+import { DEV } from 'esm-env';
+import { tick } from 'svelte';
+import { groupDecorationsByAncestor, groupDecorationsByPath, pathKey } from './buckets';
+import { islandPosition } from './island-dom';
+import { assertInvariant } from '../assert';
+import { isCommitInProgress } from '../invariants/commit-scope';
+import { contentLengthOf, isProseKind } from '../core/inline';
+import { isBlockNode, nodeAt } from '../tree-operations/node-ops';
+import { devWarn } from '../dev-warn';
+import { recordDecorationRun } from '../perf/instruments';
+const EMPTY_MARKS = [];
+const EMPTY_ISLANDS = [];
+const EMPTY_BLOCKS = [];
+export function createDecorationEngine(deps) {
+    // Non-reactive registry state, index-aligned with `results`. Handles close over the source
+    // object, not its index, so a dispose mid-list never staleness-shifts a surviving handle.
+    const sources = [];
+    const names = new Set();
+    const warnedUnrenderableIslands = new Set();
+    let results = $state([]);
+    // Deliberately not reactive: an invalidate() that reads it must not schedule a
+    // recompute of the derived buckets.
+    let editEpoch = 0;
+    const merged = $derived(results.flat());
+    const byPath = $derived(groupDecorationsByPath(merged));
+    const byAncestor = $derived(groupDecorationsByAncestor(merged));
+    function runSource(source) {
+        const i = sources.indexOf(source);
+        if (i < 0)
+            return; // disposed between schedule and run
+        recordDecorationRun();
+        let next;
+        try {
+            next = source.provide(deps.getDoc(), { editEpoch });
+        }
+        catch (error) {
+            deps.onSourceError?.(source.name, error);
+            return; // keep the source's prior decorations — a throw never blanks the view
+        }
+        warnUnrenderableIslands(source.name, next);
+        // An empty→empty re-run must not reassign `results`, or every keystroke would
+        // republish the derived buckets for sources that never emit.
+        if (results[i].length === 0 && next.length === 0)
+            return;
+        const copy = results.slice();
+        copy[i] = next;
+        results = copy;
+    }
+    /**
+     * Why the render path will apply nothing for this island, or null when it will. The
+     * verdict belongs here and nowhere downstream: only this pass holds the decorations
+     * beside the document they were derived from, so only here does an unrenderable island
+     * mean the author placed it wrong rather than the document having moved since.
+     */
+    function islandDefect(dec, node) {
+        // Non-prose kinds run no inline pass, so they apply no islands.
+        if (!isProseKind(node.kind)) {
+            return {
+                key: `non-prose\0${node.kind}`,
+                message: `on a non-prose ${node.kind} block; islands render only in prose blocks`
+            };
+        }
+        // An END offset, not a count: a heading's content starts past its marker, so reporting it as
+        // a byte total would name a number the author cannot place anything at.
+        const contentEnd = contentLengthOf(node);
+        const held = `the block's content ends at ${contentEnd}`;
+        if (dec.type === 'widget') {
+            if (dec.offset >= 0 && dec.offset <= contentEnd)
+                return null;
+            return { key: 'range', message: `at offset ${dec.offset}, but ${held}` };
+        }
+        if (dec.start >= 0 && dec.start < dec.end && dec.end <= contentEnd)
+            return null;
+        return { key: 'range', message: `at ${dec.start}..${dec.end}, but ${held}` };
+    }
+    function warnUnrenderableIslands(sourceName, decs) {
+        if (!DEV)
+            return;
+        const doc = deps.getDoc();
+        for (const dec of decs) {
+            if (dec.type !== 'widget' && dec.type !== 'replace')
+                continue;
+            const node = nodeAt(doc, dec.path);
+            if (!node || !isBlockNode(node))
+                continue;
+            const defect = islandDefect(dec, node);
+            if (!defect)
+                continue;
+            const key = `${sourceName}\0${defect.key}`;
+            if (warnedUnrenderableIslands.has(key))
+                continue;
+            warnedUnrenderableIslands.add(key);
+            devWarn('decorations', `source '${sourceName}' places a ${dec.type} island ${defect.message}`, { path: dec.path });
+        }
+    }
+    // A source invalidating from its own `edit` handler is asking to re-run inside the commit
+    // that emitted the event; deferred here to one run per source once the commit publishes.
+    const deferred = new Set();
+    let flushQueued = false;
+    function runAfterCommit(source) {
+        deferred.add(source);
+        if (flushQueued)
+            return;
+        flushQueued = true;
+        void tick().then(() => {
+            flushQueued = false;
+            const pending = [...deferred];
+            deferred.clear();
+            for (const source of pending)
+                runSource(source);
+        });
+    }
+    function runAll() {
+        assertNotInCommit();
+        for (const source of sources)
+            runSource(source);
+    }
+    function addSource(source) {
+        if (names.has(source.name)) {
+            throw new Error(`addSource: a decoration source named '${source.name}' is already registered`);
+        }
+        names.add(source.name);
+        sources.push(source);
+        results = [...results, []];
+        runSource(source);
+        // Not `sources.indexOf`: dispose frees the name, so the same source object may be
+        // registered again, and this handle must stay inert over that second registration.
+        let live = true;
+        return {
+            invalidate: () => {
+                if (!live)
+                    return;
+                if (isCommitInProgress())
+                    runAfterCommit(source);
+                else
+                    runSource(source);
+            },
+            dispose: () => {
+                if (!live)
+                    return;
+                live = false;
+                const i = sources.indexOf(source);
+                sources.splice(i, 1);
+                names.delete(source.name);
+                results = results.filter((_, idx) => idx !== i);
+            }
+        };
+    }
+    function filterMarks(bucket) {
+        return bucket.filter((d) => d.dec.type === 'mark');
+    }
+    return {
+        addSource,
+        get sourceCount() {
+            return sources.length;
+        },
+        notifyEdit() {
+            assertNotInCommit();
+            editEpoch++;
+            runAll();
+        },
+        marksForPath(path) {
+            const bucket = byPath.get(pathKey(path));
+            return bucket ? filterMarks(bucket) : EMPTY_MARKS;
+        },
+        marksForDescendants(path) {
+            const bucket = byAncestor.get(pathKey(path));
+            return bucket ? filterMarks(bucket) : EMPTY_MARKS;
+        },
+        islandsForPath(path) {
+            const bucket = byPath.get(pathKey(path));
+            if (!bucket)
+                return EMPTY_ISLANDS;
+            const islands = bucket.filter((d) => d.dec.type === 'widget' || d.dec.type === 'replace');
+            return islands.sort((a, b) => islandPosition(a.dec) - islandPosition(b.dec));
+        },
+        blockDecorationsForPath(path) {
+            const bucket = byPath.get(pathKey(path));
+            if (!bucket)
+                return EMPTY_BLOCKS;
+            return bucket
+                .filter((d) => d.dec.type === 'block')
+                .map((d) => d.dec);
+        }
+    };
+}
+// A re-run inside the commit ceremony would let a source read a half-applied tree.
+function assertNotInCommit() {
+    assertInvariant('decoration-run-in-commit', () => isCommitInProgress()
+        ? {
+            code: 'decoration-run-in-commit',
+            message: 'decoration engine re-ran inside the commit ceremony'
+        }
+        : null);
+}

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

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+import type { ContentLength } from '../core/inline';
+import type { IndexedDecoration } from './buckets';
+import type { Decoration, DecorationWidgetSpec, ReplaceDecoration, WidgetDecoration } from './types';
+export interface ApplyIslandsOpts {
+    mountWidget: (spec: DecorationWidgetSpec, dec: Decoration) => {
+        el: HTMLElement;
+        destroy(): void;
+    } | null;
+    onSkipped?: (dec: Decoration, reason: string) => void;
+    /** Raw-space length of the block's rendered content (see {@link ContentLength}). */
+    contentLength: ContentLength;
+    /** Rendered ambient-marker length. Island offsets are raw-relative and the shared walk
+     *  counts ambient text as ordinary text, so every boundary adds this (the
+     *  TextEditableBlock compensation pattern). Default 0. */
+    ambientLength?: number;
+}
+/** Mutates `root` (the freshly built inline fragment). Returns destroy handles for
+ *  mounted widgets — the caller sweeps them next rebuild. */
+export declare function applyIslandDecorations(root: ParentNode, raw: string, islands: IndexedDecoration<WidgetDecoration | ReplaceDecoration>[], opts: ApplyIslandsOpts): Array<() => void>;
+/** 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). */
+export declare function islandRenderKeyPart(islands: IndexedDecoration<WidgetDecoration | ReplaceDecoration>[]): string;
+/** An island's ordering position, shared by the application pass and the render order. */
+export declare function islandPosition(dec: WidgetDecoration | ReplaceDecoration): number;

package/dist/decorations/island-dom.js

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ */
+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 { devWarn } from '../dev-warn';
+/** Mutates `root` (the freshly built inline fragment). Returns destroy handles for
+ *  mounted widgets — the caller sweeps them 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)) {
+        if (dec.type === 'widget')
+            applyWidget(dec);
+        else
+            applyReplace(dec);
+    }
+    return destroys;
+    function applyWidget(dec) {
+        if (dec.offset < 0 || dec.offset > contentLength)
+            return;
+        const walkOffset = toDomTextOffset(asRawOffset(dec.offset), ambientLength);
+        const range = createRangeAtDomTextOffsets(root, walkOffset, walkOffset);
+        if (!range) {
+            opts.onSkipped?.(dec, 'no DOM position at offset');
+            return;
+        }
+        const mounted = opts.mountWidget(dec.widget, dec);
+        if (!mounted) {
+            opts.onSkipped?.(dec, 'widget mount failed');
+            return;
+        }
+        destroys.push(mounted.destroy);
+        const island = buildIsland(dec.offset, dec.offset);
+        island.appendChild(mounted.el);
+        insertHoistedOutOfAmbient(range, 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.
+        let start = dec.start;
+        let end = dec.end;
+        const startSpan = widgetSpanContainingOffset(root, toDomTextOffset(asRawOffset(start), ambientLength));
+        if (startSpan)
+            start = toRawOffset(startSpan.start, ambientLength);
+        const endSpan = widgetSpanContainingOffset(root, toDomTextOffset(asRawOffset(end), ambientLength));
+        if (endSpan)
+            end = toRawOffset(endSpan.end, ambientLength);
+        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));
+        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) {
+            const displaced = rawTextOfNode(extracted, raw);
+            if (displaced !== raw.slice(start, end)) {
+                devWarn('decorations', 'replace island span disagrees with the displaced DOM bytes', {
+                    span: [start, end],
+                    displaced
+                });
+            }
+        }
+        const island = buildIsland(start, end);
+        if (dec.class)
+            island.classList.add(...dec.class.split(/\s+/).filter(Boolean));
+        if (dec.widget) {
+            const mounted = opts.mountWidget(dec.widget, dec);
+            if (mounted) {
+                destroys.push(mounted.destroy);
+                island.appendChild(mounted.el);
+            }
+        }
+        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). */
+export function islandRenderKeyPart(islands) {
+    if (islands.length === 0)
+        return '';
+    return `\0${islands.map((i) => islandSig(i.dec)).join(';')}`;
+}
+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. */
+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].
+ */
+function orderForApplication(islands) {
+    return [...islands].sort((a, b) => islandPosition(b.dec) - islandPosition(a.dec) ||
+        tieRank(a.dec) - tieRank(b.dec) ||
+        b.index - a.index);
+}
+function tieRank(dec) {
+    if (dec.type === 'replace')
+        return 0;
+    return dec.side === 'before' ? 2 : 1;
+}
+function buildIsland(sourceStart, sourceEnd) {
+    const island = document.createElement('span');
+    island.className = 'decoration-island';
+    island.dataset.inlineWidget = '';
+    island.dataset.decorationIsland = '';
+    island.dataset.sourceStart = String(sourceStart);
+    island.dataset.sourceEnd = String(sourceEnd);
+    island.setAttribute('contenteditable', 'false');
+    return island;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+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. */
+export declare function acceptedBlockAttrs(attrs: Record<string, string> | undefined, path: number[]): Array<[string, string]>;

package/dist/decorations/reserved-attrs.js

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+import { devWarn } from '../dev-warn';
+export const RESERVED_BLOCK_ATTRS = new Set([
+    'data-block-path',
+    'data-block-kind',
+    'data-content-empty',
+    'data-cross-block',
+    'data-decoration-island',
+    'data-focused',
+    'data-gap-caret',
+    'data-image-overlay',
+    'data-image-widget',
+    'data-inline-widget',
+    'data-link-card',
+    'data-presentation',
+    'data-table-row-idx'
+]);
+/** The name production `setAttribute` enforces: a name it refuses throws inside the decoration
+ *  effect, taking 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. */
+export function acceptedBlockAttrs(attrs, path) {
+    const accepted = [];
+    for (const [name, value] of Object.entries(attrs ?? {})) {
+        const refusal = !ATTR_NAME.test(name)
+            ? 'is not a valid attribute name'
+            : RESERVED_BLOCK_ATTRS.has(name.toLowerCase())
+                ? 'is reserved by the editor'
+                : null;
+        if (refusal !== null) {
+            devWarn('decorations', `block decoration attribute '${name}' ${refusal} and was dropped`, {
+                path
+            });
+            continue;
+        }
+        accepted.push([name, value]);
+    }
+    return accepted;
+}

package/dist/decorations/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * View-only annotations layered over the rendered document. Decorations never enter the
+ * CST: pure sources produce them per-instance, and overlays/islands consume them.
+ */
+import type { DocumentView } from '../core/node-views';
+export interface MarkDecoration {
+    type: 'mark';
+    path: number[];
+    start: number;
+    end: number;
+    class: string;
+    attrs?: Record<string, string>;
+    interactive?: {
+        onClick: (dec: MarkDecoration, ev: MouseEvent) => void;
+    };
+}
+export interface WidgetDecoration {
+    type: 'widget';
+    path: number[];
+    offset: number;
+    side?: 'before' | 'after';
+    widget: DecorationWidgetSpec;
+}
+export interface ReplaceDecoration {
+    type: 'replace';
+    path: number[];
+    start: number;
+    end: number;
+    widget?: DecorationWidgetSpec;
+    class?: string;
+}
+export interface BlockDecoration {
+    type: 'block';
+    path: number[];
+    class?: string;
+    attrs?: Record<string, string>;
+    badge?: DecorationWidgetSpec;
+}
+export type Decoration = MarkDecoration | WidgetDecoration | ReplaceDecoration | BlockDecoration;
+/** Render keys don't track widget identity: same position + class ⇒ equal. Vary `class`
+ *  to force a re-render. */
+export type DecorationWidgetSpec = {
+    component: import('svelte').Component<{
+        decoration: Decoration;
+    }>;
+} | {
+    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. */
+    editEpoch: number;
+}
+export interface DecorationSource {
+    name: string;
+    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. */
+    invalidate(): void;
+    dispose(): void;
+}
+export interface DecorationRegistry {
+    addSource(source: DecorationSource): DecorationSourceHandle;
+}

package/dist/decorations/types.js

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

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

@@ -0,0 +1,15 @@
+/**
+ * The one mounting seam for decoration widget specs, so error containment and teardown
+ * semantics can't drift between block badges and inline islands.
+ */
+import type { Decoration, DecorationWidgetSpec } from './types';
+export interface DecorationWidgetHandle {
+    el: HTMLElement;
+    /** Unmounts the component (if any) and detaches `el`. Idempotent. */
+    destroy(): void;
+}
+/**
+ * Build a widget spec's DOM. A synchronous throw is contained and surfaced 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

@@ -0,0 +1,35 @@
+/**
+ * The one mounting seam for decoration widget specs, so error containment and teardown
+ * semantics can't drift between block badges and inline islands.
+ */
+import { mount, unmount } from 'svelte';
+/**
+ * Build a widget spec's DOM. A synchronous throw is contained and surfaced as null, so the
+ * caller renders without the widget instead of tearing down the block.
+ */
+export function mountDecorationWidget(spec, dec, reportError) {
+    try {
+        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.
+            let unmounted = false;
+            return {
+                el,
+                destroy: () => {
+                    if (!unmounted)
+                        void unmount(instance);
+                    unmounted = true;
+                    el.remove();
+                }
+            };
+        }
+        const el = spec.buildDom(dec);
+        return { el, destroy: () => el.remove() };
+    }
+    catch (error) {
+        reportError?.(error);
+        return null;
+    }
+}

package/dist/dev-warn.d.ts

@@ -0,0 +1,13 @@
+export interface DevWarnEntry {
+    tag: string;
+    message: string;
+    details?: unknown;
+}
+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
+ * 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;

package/dist/dev-warn.js

@@ -0,0 +1,28 @@
+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
+ * may know about a test runner. Nothing registers one in production or on a dev server.
+ */
+export function setDevWarnSink(next) {
+    const previous = sink;
+    sink = next;
+    return previous;
+}
+export function devWarn(tag, message, details) {
+    if (!editorEnv.isDev)
+        return;
+    if (sink) {
+        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.
+    if (details !== undefined) {
+        console.warn(`[aragonite:${tag}] ${message}`, details);
+    }
+    else {
+        console.warn(`[aragonite:${tag}] ${message}`);
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Publishing side of the ancestry settle (`tree-operations/unshare.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.
+ */
+import type { CstNode } from '../core/nodes';
+import type { AncestrySeamFold } from '../tree-operations/unshare';
+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. */
+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.
+ */
+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.
+ */
+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
+ * 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;