@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/debug/diagnostics-report.d.ts

@@ -1,16 +1,16 @@
 /**
- * The attachable field report `getDiagnostics().serializeDiagnostics()` produces:
- * a fenced-markdown snapshot a consumer pastes into a bug report. Pure over its
- * inputs so the privacy pin — the document source is EXCLUDED unless the consumer
- * opts in — is unit-testable without mounting the editor.
+ * The report `getDiagnostics().serializeDiagnostics()` produces: a fenced-markdown snapshot
+ * a consumer pastes into a bug report. A pure function of its inputs, so the privacy rule
+ * (the document source is left out unless the consumer opts in) can be unit-tested without
+ * mounting the editor.
  */
 export interface DiagnosticsReportInput {
     timestamp: string;
-    /** Tails pre-rendered by the debug engine. */
+    /** Tails already rendered by the debug helpers. */
     trace: string;
     opsLog: string;
     selection: string;
-    /** Raw document Markdown. Emitted ONLY when `includeSource` is true. */
+    /** Raw document Markdown. Emitted only when `includeSource` is true. */
     source: string;
     includeSource: boolean;
 }

package/dist/debug/diagnostics-report.js

@@ -1,8 +1,8 @@
 /**
- * The attachable field report `getDiagnostics().serializeDiagnostics()` produces:
- * a fenced-markdown snapshot a consumer pastes into a bug report. Pure over its
- * inputs so the privacy pin — the document source is EXCLUDED unless the consumer
- * opts in — is unit-testable without mounting the editor.
+ * The report `getDiagnostics().serializeDiagnostics()` produces: a fenced-markdown snapshot
+ * a consumer pastes into a bug report. A pure function of its inputs, so the privacy rule
+ * (the document source is left out unless the consumer opts in) can be unit-tested without
+ * mounting the editor.
  */
 import { escalatedFenceLength } from '../core/parsers/fence-syntax';
 // A trace tail or a document body routinely holds a fence of its own, which would close the
@@ -18,7 +18,7 @@ export function buildDiagnosticsReport(input) {
         fenced('Operations log', input.opsLog),
         fenced('Selection', input.selection)
     ];
-    // Default-excluded: a field report must not leak the document unless asked.
+    // Left out by default: a bug report must not leak the document unless asked.
     if (input.includeSource)
         sections.push(fenced('Source', input.source));
     return `# aragonite editor diagnostics — ${input.timestamp}\n\n${sections.join('\n\n')}\n`;

package/dist/debug/dump-tree.js

@@ -59,8 +59,8 @@ function formatMetadata(node, opts) {
     if (!m)
         return '';
     const frags = [];
-    // Narrowing to the built-in union lets each arm read its own metadata directly, with no
-    // `'field' in m` probing.
+    // Narrowing to the built-in union lets each branch read its own metadata directly, with no
+    // `'field' in m` checks.
     if (isBuiltinBlockNode(node)) {
         switch (node.kind) {
             case 'heading':

package/dist/debug/editor-diagnostics.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `getDiagnostics()` entry point: the switches for the interaction trace, and the fenced
+ * report (`diagnostics-report.ts`). The document source is left out unless the consumer opts in.
+ */
+import type { EditorDiagnostics } from '../editor-props';
+import type { EditorSelection } from '../selection/primitives';
+import type { OperationsLog } from './operations-log';
+export interface EditorDiagnosticsDeps {
+    /** The public snapshot, so it covers the single-block carets the cross-block state never
+     *  holds. */
+    getSelection(): EditorSelection | null;
+    getSource(): string;
+    operationsLog: OperationsLog;
+}
+export declare function createEditorDiagnostics(deps: EditorDiagnosticsDeps): EditorDiagnostics;

package/dist/debug/editor-diagnostics.js

@@ -0,0 +1,33 @@
+/**
+ * The `getDiagnostics()` entry point: the switches for the interaction trace, and the fenced
+ * report (`diagnostics-report.ts`). The document source is left out unless the consumer opts in.
+ */
+import { buildDiagnosticsReport } from './diagnostics-report';
+import { dumpInteractionTrace, dumpOperationsLog } from './inspect';
+import { disableInteractionTrace, enableInteractionTrace, interactionTraceSnapshot, isInteractionTraceEnabled } from './interaction-trace';
+export function createEditorDiagnostics(deps) {
+    function selectionSummary() {
+        const sel = deps.getSelection();
+        if (!sel)
+            return '(no selection)';
+        const fmt = (p) => `[${p.path.join(',')}]@${p.offset}`;
+        return `anchor=${fmt(sel.anchor)} focus=${fmt(sel.focus)}`;
+    }
+    return {
+        enableTrace: enableInteractionTrace,
+        disableTrace: disableInteractionTrace,
+        isTraceEnabled: isInteractionTraceEnabled,
+        traceSnapshot: interactionTraceSnapshot,
+        serializeDiagnostics: (opts) => {
+            const includeSource = opts?.includeSource ?? false;
+            return buildDiagnosticsReport({
+                timestamp: new Date().toISOString(),
+                trace: dumpInteractionTrace(interactionTraceSnapshot()),
+                opsLog: dumpOperationsLog(deps.operationsLog),
+                selection: selectionSummary(),
+                source: includeSource ? deps.getSource() : '',
+                includeSource
+            });
+        }
+    };
+}

package/dist/debug/inspect.d.ts

@@ -1,6 +1,6 @@
 /**
- * Internal debug engine — never exported from the public barrel (`src/lib/index.ts`).
- * Output format is disposable: assert on structured accessors (getSource, kinds, paths).
+ * Internal debug helpers, never exported from the public barrel (`src/lib/index.ts`). The
+ * output format is disposable: assert on the structured accessors (`getSource`, kinds, paths).
  */
 import type { InlineNode } from '../core/nodes';
 import type { SelectionState } from '../selection/selection-state.svelte';

package/dist/debug/inspect.js

@@ -1,6 +1,6 @@
 /**
- * Internal debug engine — never exported from the public barrel (`src/lib/index.ts`).
- * Output format is disposable: assert on structured accessors (getSource, kinds, paths).
+ * Internal debug helpers, never exported from the public barrel (`src/lib/index.ts`). The
+ * output format is disposable: assert on the structured accessors (`getSource`, kinds, paths).
  */
 import { isGapSelection } from '../undo/types';
 export { dumpTree } from './dump-tree';
@@ -95,8 +95,8 @@ function renderTraceEntry(e, now) {
         .join(' ');
     return detail ? `${base} ${detail}` : base;
 }
-/** Detail fields worth printing, per op. An op whose detail carries nothing a reader needs
- *  is simply absent; a variant missing any listed field prints none of them. */
+/** The detail fields worth printing, per operation. An operation whose detail says nothing
+ *  useful is simply absent; one missing any listed field prints none of them. */
 const DETAIL_FIELDS = {
     split: ['at'],
     merge: ['direction'],

package/dist/debug/interaction-trace.d.ts

@@ -1,12 +1,11 @@
 /**
- * Bounded ring buffer of the inline layer's transient state transitions, read through the debug
- * panel and `getDiagnostics()`. Unlike `perf/instruments.ts` it arms from anywhere, production
- * included, so a consumer app can attach it to a bug report — which is why entries carry cheap
- * primitives ONLY, never node references or raw document text. The buffer is module-global, so
- * two editors on one page interleave.
+ * A fixed-size ring buffer of the inline code's short-lived state changes, read through the
+ * debug panel and `getDiagnostics()`. It can run in production so a consumer app can attach it
+ * to a bug report, so an entry holds only cheap values, never node references or document text.
+ * The buffer is module-global: two editors on one page interleave their entries.
  */
 export interface InteractionTraceEntry {
-    /** `performance.now()` at record time — monotonic, no wall clock. */
+    /** `performance.now()` at record time: it only ever goes up, and is not a wall clock. */
     t: number;
     site: string;
     kind: string;
@@ -15,29 +14,29 @@ export interface InteractionTraceEntry {
 export declare function enableInteractionTrace(): void;
 export declare function disableInteractionTrace(): void;
 export declare function isInteractionTraceEnabled(): boolean;
-/** Empty the buffer without touching the enabled flag — test isolation. */
+/** Empty the buffer without touching the enabled flag, so tests stay isolated. */
 export declare function resetInteractionTrace(): void;
 export declare function interactionTraceKeydownCount(): number;
 export declare function interactionTraceSnapshot(): InteractionTraceEntry[];
 /** `changed` names the differing render-key segments, comma-joined. */
 export declare function traceRebuild(changed: string, force: boolean): void;
-export declare function traceCursorCapture(walk: number): void;
-export declare function traceCursorRestore(walk: number): void;
+export declare function traceCursorCapture(raw: number): void;
+export declare function traceCursorRestore(raw: number): void;
 export declare function tracePendingCursorSet(source: string, offset: number | null): void;
-/** `applied` false = the block lost focus before the effect ran, so the caret restore was
- *  legally skipped. */
+/** `applied` false means the block lost focus before the effect ran, so skipping the caret
+ *  restore was correct. */
 export declare function tracePendingCursorConsume(offset: number, applied: boolean): void;
-/** `construct` carries a `kind:start-end` descriptor; other tiers record the tier alone. */
+/** `construct` holds a `kind:start-end` descriptor; the other levels record the level alone. */
 export declare function traceRevealOpen(tier: 'inline' | 'leaf' | 'construct', construct?: string): void;
 export type RevealFoldReason = 'commit' | 'cancel' | 'no-edit' | 'selection-escape' | 'blur' | 'caret-exit';
 export declare function traceRevealFold(reason: RevealFoldReason, construct?: string): void;
-/** One record per rebuild bracket, counted inside the pool rather than per widget. */
+/** One record per rebuild, counted once for the pool rather than once per widget. */
 export declare function tracePoolPass(adopt: number, build: number, destroyed: number): void;
 export declare function traceCompositionStart(): void;
 export declare function traceCompositionEnd(): void;
 export declare function traceIslandsApplied(count: number): void;
 export declare function traceStickyCapture(x: number): void;
 export declare function traceStickyReset(): void;
-/** `handled` is the event's own `defaultPrevented`: whether the editor claimed the press.
- *  Recorded once per keydown, after the surface handler's await chain has settled. */
+/** `handled` is the event's own `defaultPrevented`: whether the editor took the keystroke.
+ *  Recorded once per keydown, after the block's handler has finished awaiting. */
 export declare function traceKeydownVerdict(key: string, handled: boolean): void;

package/dist/debug/interaction-trace.js

@@ -1,15 +1,14 @@
 /**
- * Bounded ring buffer of the inline layer's transient state transitions, read through the debug
- * panel and `getDiagnostics()`. Unlike `perf/instruments.ts` it arms from anywhere, production
- * included, so a consumer app can attach it to a bug report — which is why entries carry cheap
- * primitives ONLY, never node references or raw document text. The buffer is module-global, so
- * two editors on one page interleave.
+ * A fixed-size ring buffer of the inline code's short-lived state changes, read through the
+ * debug panel and `getDiagnostics()`. It can run in production so a consumer app can attach it
+ * to a bug report, so an entry holds only cheap values, never node references or document text.
+ * The buffer is module-global: two editors on one page interleave their entries.
  */
 const CAPACITY = 200;
 let enabled = false;
 let buf = [];
-// Monotonic, so the harness poll costs one read and the ring buffer's eviction cannot
-// retract a verdict it already counted.
+// Only ever goes up, so a polling harness costs one read and the ring buffer dropping an
+// old entry cannot take back a result it already counted.
 let keydownVerdicts = 0;
 // ── Switch and readout ──────────────────────────────────────────────────────
 export function enableInteractionTrace() {
@@ -21,7 +20,7 @@ export function disableInteractionTrace() {
 export function isInteractionTraceEnabled() {
     return enabled;
 }
-/** Empty the buffer without touching the enabled flag — test isolation. */
+/** Empty the buffer without touching the enabled flag, so tests stay isolated. */
 export function resetInteractionTrace() {
     buf = [];
     keydownVerdicts = 0;
@@ -38,37 +37,37 @@ function record(site, kind, detail) {
         buf.splice(0, buf.length - CAPACITY);
 }
 // ── Recorders (one per transition family) ────────────────────────────────────
-// Every recorder opens with the disabled gate. Detail assembly that would allocate stays
-// behind an `isInteractionTraceEnabled()` guard at the call site.
+// Every recorder starts by returning when recording is off. Building a detail that would
+// allocate stays behind an `isInteractionTraceEnabled()` check at the call site.
 /** `changed` names the differing render-key segments, comma-joined. */
 export function traceRebuild(changed, force) {
     if (!enabled)
         return;
     record('text-render', 'rebuild', { changed, force });
 }
-export function traceCursorCapture(walk) {
+export function traceCursorCapture(raw) {
     if (!enabled)
         return;
-    record('text-render', 'cursor-capture', { walk });
+    record('text-render', 'cursor-capture', { raw });
 }
-export function traceCursorRestore(walk) {
+export function traceCursorRestore(raw) {
     if (!enabled)
         return;
-    record('text-render', 'cursor-restore', { walk });
+    record('text-render', 'cursor-restore', { raw });
 }
 export function tracePendingCursorSet(source, offset) {
     if (!enabled)
         return;
     record('pending-cursor', 'set', { source, offset: offset ?? -1, cleared: offset === null });
 }
-/** `applied` false = the block lost focus before the effect ran, so the caret restore was
- *  legally skipped. */
+/** `applied` false means the block lost focus before the effect ran, so skipping the caret
+ *  restore was correct. */
 export function tracePendingCursorConsume(offset, applied) {
     if (!enabled)
         return;
     record('pending-cursor', 'consume', { offset, applied });
 }
-/** `construct` carries a `kind:start-end` descriptor; other tiers record the tier alone. */
+/** `construct` holds a `kind:start-end` descriptor; the other levels record the level alone. */
 export function traceRevealOpen(tier, construct) {
     if (!enabled)
         return;
@@ -79,7 +78,7 @@ export function traceRevealFold(reason, construct) {
         return;
     record('reveal', 'fold', construct === undefined ? { reason } : { reason, construct });
 }
-/** One record per rebuild bracket, counted inside the pool rather than per widget. */
+/** One record per rebuild, counted once for the pool rather than once per widget. */
 export function tracePoolPass(adopt, build, destroyed) {
     if (!enabled)
         return;
@@ -110,8 +109,8 @@ export function traceStickyReset() {
         return;
     record('sticky-column', 'reset');
 }
-/** `handled` is the event's own `defaultPrevented`: whether the editor claimed the press.
- *  Recorded once per keydown, after the surface handler's await chain has settled. */
+/** `handled` is the event's own `defaultPrevented`: whether the editor took the keystroke.
+ *  Recorded once per keydown, after the block's handler has finished awaiting. */
 export function traceKeydownVerdict(key, handled) {
     if (!enabled)
         return;

package/dist/debug/operations-log.d.ts

@@ -10,5 +10,5 @@ export interface OperationsLog {
     snapshot(): OperationEntry[];
     subscribe(listener: (entry: OperationEntry) => void): () => void;
 }
-/** Bounded FIFO; oldest entries evicted past `capacity`. */
+/** First in, first out; the oldest entries are dropped past `capacity`. */
 export declare function createOperationsLog(capacity?: number): OperationsLog;

package/dist/debug/operations-log.js

@@ -1,5 +1,5 @@
 import { devWarn } from '../dev-warn';
-/** Bounded FIFO; oldest entries evicted past `capacity`. */
+/** First in, first out; the oldest entries are dropped past `capacity`. */
 export function createOperationsLog(capacity = 100) {
     const buf = [];
     const listeners = new Set();

package/dist/decorations/buckets.d.ts

@@ -3,7 +3,8 @@
  * overlay reads only its own bucket instead of scanning every decoration per render.
  */
 import type { Decoration, MarkDecoration } from './types';
-/** A decoration paired with its flat-list position — the stable key overlays render against. */
+/** A decoration paired with its position in the flat list: the stable key overlays render
+ *  against. */
 export interface IndexedDecoration<D extends Decoration = Decoration> {
     dec: D;
     index: number;
@@ -17,11 +18,8 @@ export declare function groupByPathKey<T extends {
 }, E>(items: readonly T[], wrap: (item: T, index: number) => E): Map<string, E[]>;
 /** Group decorations by owning leaf path, preserving each one's flat index. */
 export declare function groupDecorationsByPath(decs: readonly Decoration[]): Map<string, IndexedDecoration[]>;
-/**
- * Group decorations under every strict ancestor prefix of their owning path. Grid
- * surfaces paint descendant cell decorations themselves, cells having no BlockHost
- * overlay, so this lets them read one bucket instead of the full list.
- */
+/** Group decorations under every strict ancestor of their own path, so a grid, which paints
+ *  its cells' decorations itself, reads one bucket instead of the full list. */
 export declare function groupDecorationsByAncestor(decs: readonly Decoration[]): Map<string, IndexedDecoration[]>;
 /** One whole-cell rect: the union of every mark's class tokens, plus a representative
  *  decoration for the rect's attrs/interactive. */
@@ -31,10 +29,6 @@ export interface CollapsedCellMark {
     class: string;
     dec: MarkDecoration;
 }
-/**
- * Collapse a grid's descendant cell marks to one entry per `(row, col)`, unioning their
- * class tokens so two sources in one cell cascade-compose instead of stacking translucent
- * rects. `containerDepth` is the grid container's path length; the cell coordinates sit at
- * `path[depth]` and `path[depth + 1]`.
- */
+/** Collapse a grid's cell marks to one entry per `(row, col)`, unioning class tokens so two
+ *  sources in one cell compose instead of stacking translucent rects. */
 export declare function collapseCellMarks(descMarks: readonly IndexedDecoration<MarkDecoration>[], containerDepth: number): CollapsedCellMark[];

package/dist/decorations/buckets.js

@@ -24,11 +24,8 @@ export function groupByPathKey(items, wrap) {
 export function groupDecorationsByPath(decs) {
     return groupByPathKey(decs, (dec, index) => ({ dec, index }));
 }
-/**
- * Group decorations under every strict ancestor prefix of their owning path. Grid
- * surfaces paint descendant cell decorations themselves, cells having no BlockHost
- * overlay, so this lets them read one bucket instead of the full list.
- */
+/** Group decorations under every strict ancestor of their own path, so a grid, which paints
+ *  its cells' decorations itself, reads one bucket instead of the full list. */
 export function groupDecorationsByAncestor(decs) {
     const byAncestor = new Map();
     decs.forEach((dec, index) => {
@@ -45,12 +42,8 @@ function push(map, key, dec, index) {
     else
         map.set(key, [{ dec, index }]);
 }
-/**
- * Collapse a grid's descendant cell marks to one entry per `(row, col)`, unioning their
- * class tokens so two sources in one cell cascade-compose instead of stacking translucent
- * rects. `containerDepth` is the grid container's path length; the cell coordinates sit at
- * `path[depth]` and `path[depth + 1]`.
- */
+/** Collapse a grid's cell marks to one entry per `(row, col)`, unioning class tokens so two
+ *  sources in one cell compose instead of stacking translucent rects. */
 export function collapseCellMarks(descMarks, containerDepth) {
     const byCell = new Map();
     for (const { dec } of descMarks) {

package/dist/decorations/decoration-state.svelte.d.ts

@@ -8,9 +8,8 @@ export interface DecorationEngineDeps {
 export type DecorationEngine = {
     addSource(source: DecorationSource): DecorationSourceHandle;
     readonly sourceCount: number;
-    /** Bump the edit epoch, then re-run every provide. `handle.invalidate()` re-runs one
-     *  source WITHOUT the bump, which is what lets a memoized source tell "document
-     *  changed" from "my own state changed". */
+    /** Re-runs every source after bumping the edit counter. `handle.invalidate()` skips the bump,
+     *  so a memoized source can tell a document change from a change in its own state. */
     notifyEdit(): void;
     marksForPath(path: number[]): IndexedDecoration<MarkDecoration>[];
     marksForDescendants(path: number[]): IndexedDecoration<MarkDecoration>[];

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

@@ -1,4 +1,6 @@
-import { DEV } from 'esm-env';
+/** One editor's decoration sources, their merged results, and the per-path lookups the
+ *  overlays and inline widgets read. A source never runs inside a commit. */
+import { isDevChecks } from '../env';
 import { tick } from 'svelte';
 import { groupDecorationsByAncestor, groupDecorationsByPath, pathKey } from './buckets';
 import { islandPosition } from './island-dom';
@@ -12,14 +14,14 @@ 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.
+    // Lined up with `results` by index. A handle closes over the source object, not its index,
+    // so disposing one never leaves another pointing at the wrong entry.
     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.
+    // 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));
@@ -35,33 +37,29 @@ export function createDecorationEngine(deps) {
         }
         catch (error) {
             deps.onSourceError?.(source.name, error);
-            return; // keep the source's prior decorations — a throw never blanks the view
+            return; // keep the source's previous 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.
+        // A re-run that was empty and stays empty must not reassign `results`, or every keystroke
+        // would rebuild the derived buckets for sources that never emit anything.
         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.
-     */
+    /** Why the render path will apply nothing for this inline widget, or null when it will.
+     *  Asked here because only this pass sees the decoration beside the document it came from. */
     function islandDefect(dec, node) {
-        // Non-prose kinds run no inline pass, so they apply no islands.
+        // Non-prose kinds run no inline pass, so they apply no inline widgets.
         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`
+                message: `on a non-prose ${node.kind} block; decorations 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.
+        // An end offset, not a count: a heading's content starts past its marker, so reporting 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') {
@@ -74,7 +72,7 @@ export function createDecorationEngine(deps) {
         return { key: 'range', message: `at ${dec.start}..${dec.end}, but ${held}` };
     }
     function warnUnrenderableIslands(sourceName, decs) {
-        if (!DEV)
+        if (!isDevChecks())
             return;
         const doc = deps.getDoc();
         for (const dec of decs) {
@@ -90,11 +88,11 @@ export function createDecorationEngine(deps) {
             if (warnedUnrenderableIslands.has(key))
                 continue;
             warnedUnrenderableIslands.add(key);
-            devWarn('decorations', `source '${sourceName}' places a ${dec.type} island ${defect.message}`, { path: dec.path });
+            devWarn('decorations', `source '${sourceName}' places a ${dec.type} decoration ${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.
+    // A source that invalidates from its own `edit` handler is asking to re-run inside the
+    // commit that emitted the event; deferred to one run per source once the commit is done.
     const deferred = new Set();
     let flushQueued = false;
     function runAfterCommit(source) {
@@ -123,8 +121,8 @@ export function createDecorationEngine(deps) {
         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.
+        // Not `sources.indexOf`: disposing frees the name, so the same source object may be
+        // registered again, and this handle must do nothing for that second registration.
         let live = true;
         return {
             invalidate: () => {
@@ -184,12 +182,12 @@ export function createDecorationEngine(deps) {
         }
     };
 }
-// A re-run inside the commit ceremony would let a source read a half-applied tree.
+// A re-run inside a commit 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'
+            message: 'the decorations subsystem re-ran inside the commit sequence'
         }
         : null);
 }

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

@@ -1,12 +1,8 @@
 /**
- * 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 type { ContentLength } from '../core/inline';
 import type { IndexedDecoration } from './buckets';
@@ -19,17 +15,13 @@ export interface ApplyIslandsOpts {
     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. */
+/** Mutates `root`, the freshly built inline fragment. Returns one destroy function per
+ *  mounted widget; the caller runs them on the 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). */
+/** 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 declare function islandRenderKeyPart(islands: IndexedDecoration<WidgetDecoration | ReplaceDecoration>[]): string;
-/** 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 declare function islandPosition(dec: WidgetDecoration | ReplaceDecoration): number;