@voithos-labs/aragonite 0.10.1

package/dist/editor-actions/block-edit.js

@@ -0,0 +1,111 @@
+/**
+ * Top-level BlockEditActions factory. Structural mutations route through the shared
+ * `block-edit-core` against a top-level `CommitScope`; this factory adds the edge
+ * guards and the one per-level body the core can't share, `updateBlockContent`.
+ */
+import { tick } from 'svelte';
+import { updateNodeContent as performUpdate, ensureUnsharedPath } from '../tree-operations';
+import { publishScopeFold } from './ancestry-folds';
+import { stampStructuralChange } from '../tree-operations/structural-change';
+import { createTopLevelScope } from './block-edit-scope';
+import { createBlockEditCore } from './block-edit-core';
+import { withEnterCompletion } from './enter-completion';
+import { previewContentReparse, focusAfterContentReplace } from './replacement-focus';
+export function createBlockEditActions(deps, controller) {
+    const scope = createTopLevelScope(deps, controller);
+    const core = createBlockEditCore(scope);
+    // The keystroke's own work, split out so `updateBlockContent` owns the batch ceremony
+    // around it and nothing inside can return past the pause arm.
+    async function applyContentUpdate(blockIndex, text, preEditOffset, postEditFocusOffset) {
+        // The structural path's live mutation runs inside the ceremony, so a
+        // multi-block splice never touches the live children array out-of-commit.
+        const preview = previewContentReparse(deps.doc.children[blockIndex], text, deps.grammar, undefined, blockIndex === deps.doc.children.length - 1 ? deps.doc.suffix : '');
+        if (preview.op !== 'noop') {
+            const focusOffset = postEditFocusOffset ?? preEditOffset ?? 0;
+            let settled = { change: { op: 'noop' }, textStart: 0 };
+            await scope.commit({
+                snapshot: 'skip',
+                eventTarget: blockIndex,
+                op: { kind: 'updateContent', detail: { length: text.length } },
+                // ownerKind undefined is the ANSWER, not an omission: the document root
+                // imposes no body grammar. The suffix rides as accessors so the tail
+                // settle folds against the live document.
+                mutate: (view) => {
+                    view.unshareChild(blockIndex);
+                    settled = performUpdate({
+                        children: view.children,
+                        ownerKind: undefined,
+                        owner: undefined,
+                        get suffix() {
+                            return deps.doc.suffix;
+                        },
+                        set suffix(value) {
+                            deps.doc.suffix = value;
+                        }
+                    }, blockIndex, text, deps.grammar, view.sharing);
+                    stampStructuralChange(view.children, settled.change, view.sharing);
+                    return settled.change;
+                },
+                afterTick: () => focusAfterContentReplace([], blockIndex, settled, focusOffset, scope)
+            });
+            return;
+        }
+        // Routine typing: an out-of-ceremony in-place write, so copy the node first when a
+        // snapshot shares it. Slotless parent on purpose — the preview already routed every
+        // suffix materialization into the ceremony, so none can happen here.
+        ensureUnsharedPath(deps.doc, [blockIndex], deps.sharing);
+        const settled = performUpdate({ children: deps.doc.children, ownerKind: undefined, owner: undefined }, blockIndex, text, deps.grammar, deps.sharing);
+        // A blank-fill settle can still FOLD here — the single-node preview probe has no
+        // neighbour to absorb it — so this path publishes its own descriptor and re-lands the
+        // caret, which the ceremony would otherwise have done.
+        if (settled.change.op !== 'noop')
+            publishScopeFold(deps, undefined, settled.change);
+        // After that publish, as the ceremony announces after its own, and ahead of the no-fold
+        // return: the leaf's raw is already written, and the ordinary keystroke settles to `noop`.
+        deps.bumpContentVersion();
+        if (settled.change.op === 'noop')
+            return;
+        await tick();
+        focusAfterContentReplace([], blockIndex, settled, postEditFocusOffset ?? preEditOffset ?? 0, scope);
+    }
+    const actions = {
+        // ── Structural split / merge / delete (shared core) ───────────────────
+        splitBlock: (blockIndex, offset) => core.split(blockIndex, offset),
+        descendToBody: (blockIndex) => core.descendToBody(blockIndex),
+        insertParagraph: (boundaryIndex, text) => core.insertParagraph(boundaryIndex, text),
+        async mergeWithPrevious(blockIndex) {
+            deps.stickyColumn.reset();
+            deps.edgeAffinity.reset();
+            if (blockIndex <= 0)
+                return;
+            await core.mergeWithPreviousInterior(blockIndex);
+        },
+        async mergeWithNext(blockIndex) {
+            deps.stickyColumn.reset();
+            deps.edgeAffinity.reset();
+            if (blockIndex >= deps.doc.children.length - 1)
+                return;
+            await core.mergeWithNextInterior(blockIndex);
+        },
+        deleteBlock: (blockIndex) => core.deleteInterior(blockIndex),
+        updateBlockMetadata: (blockIndex, metadata, options) => core.updateBlockMetadata(blockIndex, metadata, options),
+        replaceBlock: (blockIndex, replacement, focus, options) => core.replaceBlock(blockIndex, replacement, focus, options),
+        // ── Content update (per-level) ────────────────────────────────────────
+        async updateBlockContent(blockIndex, text, preEditOffset, postEditFocusOffset) {
+            deps.stickyColumn.reset();
+            deps.edgeAffinity.reset();
+            // Keyed by block, not by slot: a bare index identifies the position, so a
+            // different block arriving at the same slot would continue its batch.
+            controller.pushUndoSnapshotDebounced([blockIndex], preEditOffset ?? 0, deps.blockIds[blockIndex]);
+            // The pause window opens once this keystroke's own work is done, throw included: an
+            // unarmed batch never ends by pause and would swallow every later keystroke.
+            try {
+                await applyContentUpdate(blockIndex, text, preEditOffset, postEditFocusOffset);
+            }
+            finally {
+                controller.armUndoPause();
+            }
+        }
+    };
+    return withEnterCompletion(actions, (blockIndex) => scope.children()[blockIndex]);
+}

package/dist/editor-actions/commit/history.d.ts

@@ -0,0 +1,9 @@
+/**
+ * HistoryActions factory: capture current state for the swap entry, replay the
+ * entry's snapshot, restore the saved selection. Snapshots share the live tree's
+ * nodes, so a restore re-marks the epoch and re-copies the children array — else a
+ * later publish writes the stack's own entry.
+ */
+import type { HistoryActions } from '../../action-contracts';
+import type { EditorActionsDeps, UndoController } from '../deps';
+export declare function createHistoryActions(deps: EditorActionsDeps, controller: UndoController): HistoryActions;

package/dist/editor-actions/commit/history.js

@@ -0,0 +1,77 @@
+/**
+ * HistoryActions factory: capture current state for the swap entry, replay the
+ * entry's snapshot, restore the saved selection. Snapshots share the live tree's
+ * nodes, so a restore re-marks the epoch and re-copies the children array — else a
+ * later publish writes the stack's own entry.
+ */
+import { tick } from 'svelte';
+import { isGapSelection } from '../../undo/types';
+import { assertInvariant } from '../../assert';
+import { checkSnapshotIntegrity } from '../../invariants/snapshot-integrity';
+import { restoreGapCaret, restoreSelection } from '../../selection/selection-restore';
+export function createHistoryActions(deps, controller) {
+    async function restore(entry, op) {
+        assertInvariant('snapshot-integrity', () => {
+            const violation = checkSnapshotIntegrity(entry);
+            return violation && { ...violation, message: `${op}: ${violation.message}` };
+        });
+        // Ahead of the swap itself, so a landing awaiting across it reads the new stamp
+        // whichever side of the doc write its reveal resolves on.
+        controller.noteHistorySwap();
+        deps.sharing.markSnapshotTaken();
+        deps.setDoc({ ...entry.snapshot, children: [...entry.snapshot.children] });
+        deps.bumpContentVersion();
+        // A copy: live state splices this array in place, and the entry stays on the stack.
+        deps.setBlockIds([...entry.blockIds]);
+        // The tick belongs to the doc swap above, not to the restore: the new tree
+        // must render before the shared seam can reveal or address anything in it.
+        await tick();
+        const restoreDeps = {
+            getDoc: () => deps.doc,
+            selectionState: deps.selectionState,
+            getBlockElByPath: deps.getBlockElByPath,
+            // Mount, not scroll into view: a history swap must not move the viewport for
+            // a target already on screen.
+            revealTarget: async (path) => (await deps.revealPath(path)) !== null
+        };
+        const outcome = isGapSelection(entry.selection)
+            ? await restoreGapCaret(entry.selection.gapCaret, restoreDeps)
+            : await restoreSelection(entry.selection, restoreDeps);
+        // An entry can name a slot that never existed in its own snapshot (append-past-end declares
+        // the one-past-the-end coordinate as its restore fallback). The seam declines without side
+        // effects, so clearing is this caller's policy: the one place that knows the doc changed.
+        if (outcome === 'unresolvable')
+            deps.selectionState.clear();
+        deps.events.emit('edit', { op, path: [], timestamp: Date.now() });
+    }
+    // Flush, not discard: interrupt clears the debounce timer so it can't push a stale
+    // snapshot after the stack moves, AND emits the batch's pending `input` event so
+    // its bytes aren't dropped from the edit channel.
+    function beginHistorySwap() {
+        deps.stickyColumn.reset();
+        deps.edgeAffinity.reset();
+        controller.flushDebouncedCheckpoint();
+    }
+    return {
+        async requestUndo() {
+            beginHistorySwap();
+            // Check the stack before capturing: captureCurrentState marks the whole tree
+            // snapshot-shared, forcing copy-on-write spines on the next edit.
+            if (!deps.undoManager.canUndo)
+                return;
+            const entry = deps.undoManager.undo(controller.captureCurrentState());
+            if (!entry)
+                return;
+            await restore(entry, 'undo');
+        },
+        async requestRedo() {
+            beginHistorySwap();
+            if (!deps.undoManager.canRedo)
+                return;
+            const entry = deps.undoManager.redo(controller.captureCurrentState());
+            if (!entry)
+                return;
+            await restore(entry, 'redo');
+        }
+    };
+}

package/dist/editor-actions/commit/text-batch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Keystroke-batch lifecycle: one undo entry per burst of typing, broken by a
+ * wall-clock pause, a batch-key change, or a structural commit. Snapshot capture
+ * itself stays with the controller, injected.
+ */
+export interface TextBatchDeps {
+    /** Capture the pre-edit snapshot for the first keystroke of a batch. */
+    pushSnapshot(leafPath: number[], offset: number): void;
+    /** Emit the batched `input` edit event when a batch flushes. */
+    emitInput(leafPath: number[], byteLength: number): void;
+}
+export interface TextBatch {
+    /**
+     * The first keystroke of a batch pushes a snapshot. `batchKey` identifies the leaf
+     * being typed in, so sibling leaves never share a batch across a focus move.
+     */
+    keystroke(leafPath: number[], offset: number, batchKey?: string | number): void;
+    /**
+     * Start the pause window, called once the keystroke's own edit has SETTLED. Split from
+     * `keystroke` because the window measures the gap the user leaves, not the gap plus the
+     * editor's own work: armed before the settle, a keystroke whose processing approaches the
+     * window opens a fresh batch every time and undo granularity collapses to one entry per
+     * character. A no-op with no live batch.
+     */
+    armPause(): void;
+    /**
+     * Structural-commit interrupt: cancel the pause timer, flush the pending input
+     * event, and require a fresh snapshot from the next keystroke.
+     */
+    interrupt(): void;
+}
+/** 250 ms, matching Obsidian: longer reverts entire half-words at typical typing speeds. */
+export declare const UNDO_DEBOUNCE_MS = 250;
+export declare function createTextBatch(deps: TextBatchDeps): TextBatch;

package/dist/editor-actions/commit/text-batch.js

@@ -0,0 +1,61 @@
+/**
+ * Keystroke-batch lifecycle: one undo entry per burst of typing, broken by a
+ * wall-clock pause, a batch-key change, or a structural commit. Snapshot capture
+ * itself stays with the controller, injected.
+ */
+/** 250 ms, matching Obsidian: longer reverts entire half-words at typical typing speeds. */
+export const UNDO_DEBOUNCE_MS = 250;
+export function createTextBatch(deps) {
+    let timer = null;
+    let lastBatchKey = -1;
+    let needsCheckpoint = true;
+    let batchPath = null;
+    let batchByteLength = 0;
+    /**
+     * Must run before the batch is repointed or reset, else edit-channel observers
+     * never see the batch's `input` event and under-count keystrokes.
+     */
+    function flushPendingInput() {
+        if (batchByteLength > 0 && batchPath) {
+            deps.emitInput(batchPath, batchByteLength);
+        }
+        batchPath = null;
+        batchByteLength = 0;
+    }
+    function clearTimer() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    return {
+        keystroke(leafPath, offset, batchKey) {
+            const key = batchKey ?? leafPath.join('.');
+            if (lastBatchKey !== key || needsCheckpoint) {
+                flushPendingInput();
+                deps.pushSnapshot(leafPath, offset);
+                lastBatchKey = key;
+                batchPath = leafPath.slice();
+                needsCheckpoint = false;
+            }
+            batchByteLength++;
+        },
+        armPause() {
+            if (needsCheckpoint)
+                return;
+            clearTimer();
+            // Wall-clock pause detection, not async sequencing (G4.4 allowlist):
+            // tick() is microtask-grained and can't express "stopped typing ~250ms".
+            timer = setTimeout(() => {
+                needsCheckpoint = true;
+                timer = null;
+                flushPendingInput();
+            }, UNDO_DEBOUNCE_MS);
+        },
+        interrupt() {
+            clearTimer();
+            flushPendingInput();
+            needsCheckpoint = true;
+        }
+    };
+}

package/dist/editor-actions/commit/undo-controller.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The commit ceremony: snapshot capture, copy-path-on-write unshare, rollback.
+ * Owns G1.9 — snapshot-shared nodes stay byte-readonly until this seam unshares
+ * them. Keystroke batching is delegated to text-batch.ts.
+ */
+import type { EditorActionsDeps, UndoController } from '../deps';
+export declare function createUndoController(deps: EditorActionsDeps): UndoController;