@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/components/editor-root-document-swap.js

@@ -0,0 +1,54 @@
+/**
+ * The `source` prop's whole-document replacement. Every piece of per-document state resets here
+ * in one fixed order, so a swap cannot skip a step.
+ */
+import { documentLineEnding } from '../core/lines';
+import { readBlocks } from '../core/parser';
+import { buildLinkReferenceMap } from '../core/inline/link-reference-resolver';
+import { emptyParagraph, ensureEditableContainers } from '../tree-operations';
+/** The parse every document goes through, at mount and at each swap, in the editor's grammar. */
+export function initDocument(source, grammar) {
+    const doc = readBlocks(source, { grammar, scope: 'document' });
+    if (doc.children.length === 0) {
+        // Only the empty source parses to zero blocks (a blank line is a block of its own), so
+        // there is no authored ending to inherit and LF is the whole answer.
+        doc.children.push(emptyParagraph('', '\n'));
+    }
+    const lineEnding = documentLineEnding(doc);
+    for (const child of doc.children)
+        ensureEditableContainers(child, lineEnding);
+    const refs = buildLinkReferenceMap(doc.children);
+    return { doc, resolver: refs.resolve, signature: refs.signature };
+}
+export function createDocumentSwap(deps) {
+    // Plain, never reactive: the code that reads it runs inside decoration `provide`, which
+    // must register no dependency.
+    let generation = 0;
+    return {
+        swapTo(source) {
+            deps.flushDebouncedCheckpoint();
+            deps.noteTreeSwap();
+            const reset = initDocument(source, deps.grammar);
+            deps.adoptDocument(reset.doc);
+            deps.bumpContentVersion();
+            deps.clearBlockRefs();
+            // Block ids never recur, so every measured height belongs to a block that can't come back.
+            deps.layout.forgetMeasuredHeights();
+            deps.undoManager.clear();
+            deps.caretMemory.forget();
+            deps.closeMenus();
+            deps.widgetSelection.clear();
+            // Announced explicitly: on a native-only caret the clear sees no change, and subscribers
+            // would keep the outgoing document's selection. Batched, so a real range emits once.
+            deps.selection.batch(() => {
+                deps.selection.clear();
+                deps.selection.announceSelection();
+            });
+            generation++;
+            deps.adoptLinkReferences(reset.resolver, reset.signature);
+            // Last, so a subscriber reading the document sees the new tree, selection and resolver.
+            deps.events.emit('sourceSwap', { generation });
+        },
+        generation: () => generation
+    };
+}

package/dist/components/editor-root-focus.d.ts

@@ -1,8 +1,7 @@
 /**
- * Editor-root focus attribution: which block host holds the caret. The path drives each
- * windowing scope's per-level pin, so a scroll that pushes the caret off-screen never tears
- * down native focus/IME; the `data-focused` attribute is what both preview modes' CSS key
- * their focused-block reveal off. The installing `$effect`s stay in `Editor.svelte`.
+ * Tracks which block host holds the caret. Each windowing list keeps that block mounted, so a
+ * scroll that pushes the caret off-screen never drops native focus or the IME. The preview modes
+ * style the focused block's markers off `data-focused`, which moves only while no pointer is down.
  */
 import { type PresentationMode } from '../presentation-mode';
 export interface FocusAttributionDeps {
@@ -14,6 +13,8 @@ export interface FocusAttribution {
     install(root: HTMLElement): () => void;
     /** Entering a preview mode marks the already-focused block, since no re-focus fires. */
     applyForMode(): void;
+    /** The focused block's path as it stands now, read off its element: a keyed move that keeps
+     *  focus renumbers the block, so a path noted when focus arrived would name its old neighbour. */
     getFocusedPath(): number[] | null;
 }
 export declare function createFocusAttribution(deps: FocusAttributionDeps): FocusAttribution;

package/dist/components/editor-root-focus.js

@@ -1,8 +1,7 @@
 /**
- * Editor-root focus attribution: which block host holds the caret. The path drives each
- * windowing scope's per-level pin, so a scroll that pushes the caret off-screen never tears
- * down native focus/IME; the `data-focused` attribute is what both preview modes' CSS key
- * their focused-block reveal off. The installing `$effect`s stay in `Editor.svelte`.
+ * Tracks which block host holds the caret. Each windowing list keeps that block mounted, so a
+ * scroll that pushes the caret off-screen never drops native focus or the IME. The preview modes
+ * style the focused block's markers off `data-focused`, which moves only while no pointer is down.
  */
 import { assertInvariant } from '../assert';
 import { checkLandableCaret } from '../invariants/landable-caret';
@@ -12,28 +11,50 @@ import { onRoot, removeAll } from './editor-root-listeners';
 export function createFocusAttribution(deps) {
     // Plain fields, never reactive: focusout fires mid-teardown during a structural commit,
     // where a reactive write would trip state_unsafe_mutation.
-    let focusedPath = null;
     let focusedHostEl = null;
-    // Mode-gated so source/reading DOM stays byte-identical.
+    let paintedHostEl = null;
+    let pressHeld = false;
+    let readAttr = null;
+    let readPath = null;
+    // Preview modes only, so source and reading DOM stay byte-identical; a held press keeps the prior
+    // paint so markers can't move the text the caret is about to land in.
     function applyFocusedAttr() {
-        if (focusedHostEl && isPreviewMode(deps.mode)) {
-            focusedHostEl.setAttribute('data-focused', '');
-        }
-        else {
-            focusedHostEl?.removeAttribute('data-focused');
-        }
+        if (pressHeld)
+            return;
+        const next = isPreviewMode(deps.mode) ? focusedHostEl : null;
+        if (paintedHostEl !== next)
+            paintedHostEl?.removeAttribute('data-focused');
+        next?.setAttribute('data-focused', '');
+        paintedHostEl = next;
     }
     function setFocusedHost(host) {
         if (focusedHostEl === host)
             return;
-        focusedHostEl?.removeAttribute('data-focused');
         focusedHostEl = host;
         applyFocusedAttr();
     }
     function clear() {
-        focusedPath = null;
         setFocusedHost(null);
     }
+    // Parsed only when the attribute changes, since windowing reads it on every height correction.
+    function focusedPath() {
+        if (!focusedHostEl?.isConnected)
+            return null;
+        const attr = focusedHostEl.getAttribute('data-block-path');
+        if (attr !== readAttr) {
+            readAttr = attr;
+            const path = readBlockPath(focusedHostEl);
+            readPath = path && path.length > 0 ? path : null;
+        }
+        return readPath;
+    }
+    // A release the page never hears (focus or the window left mid-press) must not strand the paint.
+    function endPress() {
+        if (!pressHeld)
+            return;
+        pressHeld = false;
+        applyFocusedAttr();
+    }
     function install(root) {
         const onFocusIn = (e) => {
             const host = e.target?.closest('[data-block-path]');
@@ -42,26 +63,34 @@ export function createFocusAttribution(deps) {
                 return;
             }
             setFocusedHost(host);
-            const path = readBlockPath(host);
-            focusedPath = path && path.length > 0 ? path : null;
-            // G1.33 at the seam every caret door crosses: a door seats a caret by focusing the
-            // surface, whoever minted it, so a consumer's own door inherits the guard here.
+            // Every way of placing a caret focuses its editable element, whoever wrote the code,
+            // so a consumer's own caret placement is checked here too (G1.33).
             const landed = e.target;
             if (landed instanceof HTMLElement) {
-                assertInvariant('landable-caret', () => checkLandableCaret(landed, deps.mode, path ?? []));
+                assertInvariant('landable-caret', () => checkLandableCaret(landed, deps.mode, focusedPath() ?? []));
             }
         };
         const onFocusOut = (e) => {
             const next = e.relatedTarget;
             if (next && root.contains(next))
-                return; // moving between blocks — keep the pin
+                return; // moving between blocks: keep the focused path
+            pressHeld = false;
             clear();
         };
-        return removeAll(onRoot(root, 'focusin', onFocusIn), onRoot(root, 'focusout', onFocusOut));
+        const onPress = (e) => {
+            if (e.button === 0)
+                pressHeld = true;
+        };
+        const doc = root.ownerDocument;
+        return removeAll(onRoot(root, 'focusin', onFocusIn), onRoot(root, 'focusout', onFocusOut), onRoot(root, 'pointerdown', onPress, { capture: true }), onRoot(doc, 'pointerup', endPress, { capture: true }), 
+        // A tap focuses on the mousedown the browser sends after the finger lifts.
+        onRoot(root, 'mousedown', onPress, { capture: true }), onRoot(doc, 'mouseup', endPress, { capture: true }), 
+        // A drag of the selection itself ends in pointercancel, never pointerup.
+        onRoot(doc, 'pointercancel', endPress, { capture: true }), onRoot(doc.defaultView ?? window, 'blur', endPress));
     }
     return {
         install,
         applyForMode: applyFocusedAttr,
-        getFocusedPath: () => focusedPath
+        getFocusedPath: focusedPath
     };
 }

package/dist/components/editor-root-focused-surface.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The editable block behind `document.activeElement`, for the public entry points that address
+ * it. A gap caret is refused: its stand-in element is not a block, and a nested gap's stand-in
+ * sits inside its container's host, which must not receive what was aimed at the gap. Every rule
+ * an entry point must apply (the reading-mode check, the paste pipeline) lives in the block.
+ */
+import type { BlockComponent } from '../block-component';
+import type { DocumentGetter } from '../editor-keys';
+import type { InsertMarkdownOptions } from '../editor-props';
+import type { KindCommandTarget } from '../schema/block-commands';
+import type { SelectionState } from '../selection/selection-state.svelte';
+export interface FocusedSurfaceDeps {
+    /** A getter, never a value: the root binds after construction. */
+    get editorEl(): HTMLElement | undefined;
+    selection: Pick<SelectionState, 'gapCaret'>;
+    getDoc: DocumentGetter;
+    getBlockComponent(path: number[]): BlockComponent | null;
+    isReading(): boolean;
+    /** Makes an empty top-level paragraph at `boundary` and focuses it. */
+    insertParagraph(boundary: number, text: string): Promise<boolean>;
+    /** One undo entry for the paragraph `below` makes and the paste into it. */
+    undoStep(path: number[], offset: number, run: () => Promise<unknown>): Promise<void>;
+    /** The counter every byte write bumps (`reactivity/content-version.svelte.ts`). */
+    contentVersion(): number;
+}
+export interface FocusedSurface {
+    path(): number[] | null;
+    /** Null for a gap caret's stand-in element; global commands still reach the dispatch,
+     *  exactly as the gap caret's own chord handling does. */
+    commandTarget(): KindCommandTarget | null;
+    /** Routed like a paste event, so the rules live in the block; `below` pastes into a new
+     *  paragraph after the top-level block. Resolves once the insert has landed. */
+    insertMarkdown(md: string, options?: InsertMarkdownOptions): Promise<boolean>;
+}
+export declare function createFocusedSurface(deps: FocusedSurfaceDeps): FocusedSurface;

package/dist/components/editor-root-focused-surface.js

@@ -0,0 +1,65 @@
+/**
+ * The editable block behind `document.activeElement`, for the public entry points that address
+ * it. A gap caret is refused: its stand-in element is not a block, and a nested gap's stand-in
+ * sits inside its container's host, which must not receive what was aimed at the gap. Every rule
+ * an entry point must apply (the reading-mode check, the paste pipeline) lives in the block.
+ */
+import { findSurfacePathForElement } from '../selection/path-lookup';
+import { blockNodeAt } from '../tree-operations/node-primitives';
+export function createFocusedSurface(deps) {
+    function path() {
+        if (deps.selection.gapCaret)
+            return null;
+        const active = document.activeElement;
+        if (!(active instanceof HTMLElement) || !deps.editorEl?.contains(active))
+            return null;
+        return findSurfacePathForElement(active);
+    }
+    // True only when bytes moved: a block answers for the paste it handled, and a write the
+    // commit then refused (a switch to reading mid-insert) moves none.
+    async function insertAtFocus(md) {
+        const at = path();
+        if (!at)
+            return false;
+        const before = deps.contentVersion();
+        const handled = (await deps.getBlockComponent(at)?.insertMarkdown?.(md)) ?? false;
+        return handled && deps.contentVersion() !== before;
+    }
+    async function insertBelow(topIndex, md) {
+        let inserted = false;
+        await deps.undoStep([topIndex], 0, async () => {
+            await deps.insertParagraph(topIndex + 1, '');
+            inserted = await insertAtFocus(md);
+        });
+        return inserted;
+    }
+    return {
+        path,
+        commandTarget() {
+            const at = path();
+            if (!at)
+                return null;
+            const component = deps.getBlockComponent(at);
+            const node = blockNodeAt(deps.getDoc(), at);
+            if (!component || !node)
+                return null;
+            const { runCommand, isCommandActive, afterSourceCommit } = component;
+            return {
+                kind: node.kind,
+                runCommand: runCommand && ((id, arg) => runCommand.call(component, id, arg)),
+                isCommandActive: isCommandActive && ((id) => isCommandActive.call(component, id)),
+                getPath: () => at,
+                afterSourceCommit: afterSourceCommit && ((run) => afterSourceCommit.call(component, run))
+            };
+        },
+        insertMarkdown(md, options) {
+            if (options?.placement !== 'below')
+                return insertAtFocus(md);
+            const at = path();
+            if (!at || deps.isReading() || !deps.getBlockComponent(at)?.insertMarkdown) {
+                return Promise.resolve(false);
+            }
+            return insertBelow(at[0], md);
+        }
+    };
+}

package/dist/components/editor-root-geometry.d.ts

@@ -1,39 +1,30 @@
 /**
- * Editor-root geometry observers: the width and viewport-height watchers, the type-scale probe
- * and the header-slot compensation. Each observes the element its installing `$effect`
- * captured and returns the teardown; the reactive signals they feed (`widthVersion`,
- * `typeScale`, `viewportHeightVersion`) stay in `Editor.svelte`, which is what the rest of the
- * root reads. ResizeObserver's per-callback batching is the coalescing; no timer debounce (G4.4).
+ * The editor root's size observers: each watches the element it is handed and returns its
+ * teardown, and the values they feed stay in `Editor.svelte`. ResizeObserver already batches
+ * per callback, so there is no timer (G4.4).
  */
 import type { UserScrollport } from '../cursor/scroll-ancestors';
-import type { Scrollport } from '../cursor/scrollport';
-/** Calls `onWidthChange` when `el`'s width moves. A height-only resize is ignored: only a
- *  re-wrap stales the measured heights. */
+import type { RootListScroll, ScrollOwner } from '../cursor/scroll-owner';
+/** Calls `onWidthChange` when `el`'s width changes. A height-only resize is ignored: only a
+ *  re-wrap makes the measured heights wrong. */
 export declare function installWidthWatcher(el: HTMLElement, onWidthChange: () => void): () => void;
-/** Calls `bump` on a height change of the resolved scrollport `target`. */
+/** Calls `bump` when the resolved scroll container `target` changes height. */
 export declare function installViewportHeightWatcher(target: UserScrollport, bump: () => void): () => void;
 export interface TypeScaleProbeDeps {
     /** Read at each report, so the sub-percent guard compares against the scale in force. */
     getScale(): number;
     onScale(next: number): void;
 }
-/**
- * The width watcher's sibling: a font-size move puts the height estimates off several-fold, so
- * a document whose true height clears the activation watermark can fail to window at all. No
- * other box in the root reports it, hence the `1em` probe; the scale is relative to the size
- * `HEIGHT_ESTIMATES` were calibrated at.
- */
+/** A font-size change can throw the height estimates off enough that windowing never starts;
+ *  the `1em` element reports it, as a scale against `HEIGHT_ESTIMATES`. */
 export declare function installTypeScaleProbe(el: HTMLElement, deps: TypeScaleProbeDeps): () => void;
 export interface HeaderSlotCompensationDeps {
     el: HTMLElement;
-    port: Pick<Scrollport, 'scrollTop' | 'scrollBy'>;
-    ownsScrollCorrection(): boolean;
-    revealHoldsScroll(): boolean;
+    port: ScrollOwner['port'];
+    /** The root list's correction: a held target is re-placed, since the root list's top already
+     *  counts the header. */
+    compensate: RootListScroll['compensate'];
 }
-/**
- * The header slot's height lives outside the height model, so while the editor owns the
- * correction a growing header would slide the document under the reader. Compensating from
- * the SLOT's own resize composes with `correctAnchor` instead of double-correcting; a reveal
- * already holding the scroll outranks it.
- */
+/** The header is not in the height table, so its own resize adds to the scroll correction, or a
+ *  growing header would slide the document. */
 export declare function installHeaderSlotCompensation(deps: HeaderSlotCompensationDeps): () => void;

package/dist/components/editor-root-geometry.js

@@ -1,15 +1,13 @@
 /**
- * Editor-root geometry observers: the width and viewport-height watchers, the type-scale probe
- * and the header-slot compensation. Each observes the element its installing `$effect`
- * captured and returns the teardown; the reactive signals they feed (`widthVersion`,
- * `typeScale`, `viewportHeightVersion`) stay in `Editor.svelte`, which is what the rest of the
- * root reads. ResizeObserver's per-callback batching is the coalescing; no timer debounce (G4.4).
+ * The editor root's size observers: each watches the element it is handed and returns its
+ * teardown, and the values they feed stay in `Editor.svelte`. ResizeObserver already batches
+ * per callback, so there is no timer (G4.4).
  */
 import { ESTIMATE_BASE_FONT_SIZE } from '../cursor/typography-estimates';
 import { onRoot, removeAll } from './editor-root-listeners';
 // ── Width and height ────────────────────────────────────────────────
-/** Calls `onWidthChange` when `el`'s width moves. A height-only resize is ignored: only a
- *  re-wrap stales the measured heights. */
+/** Calls `onWidthChange` when `el`'s width changes. A height-only resize is ignored: only a
+ *  re-wrap makes the measured heights wrong. */
 export function installWidthWatcher(el, onWidthChange) {
     let lastWidth = el.clientWidth;
     const observer = new ResizeObserver(() => {
@@ -22,16 +20,16 @@ export function installWidthWatcher(el, onWidthChange) {
     observer.observe(el);
     return () => observer.disconnect();
 }
-/** Calls `bump` on a height change of the resolved scrollport `target`. */
+/** Calls `bump` when the resolved scroll container `target` changes height. */
 export function installViewportHeightWatcher(target, bump) {
     if (target === window) {
-        // The page viewport has no box to observe, and a visualViewport move (a mobile URL
-        // bar retracting) never touches documentElement's height — hence both, ungated.
+        // The page viewport has no box to observe, and a visualViewport change (a mobile URL
+        // bar retracting) never touches documentElement's height, so both run unconditionally.
         const visual = window.visualViewport;
         return removeAll(onRoot(window, 'resize', bump), visual ? onRoot(visual, 'resize', bump) : () => { });
     }
-    // Cast, not a narrowing: `UserScrollport` is a union of object types, which `=== window`
-    // does not narrow — the same cast `createScrollport` makes on the same split.
+    // A cast, not a narrowing: `UserScrollport` is a union of object types, which `=== window`
+    // does not narrow; `createScrollport` casts the same way at the same split.
     const el = target;
     let lastHeight = el.clientHeight;
     const observer = new ResizeObserver(() => {
@@ -43,16 +41,12 @@ export function installViewportHeightWatcher(target, bump) {
     observer.observe(el);
     return () => observer.disconnect();
 }
-/**
- * The width watcher's sibling: a font-size move puts the height estimates off several-fold, so
- * a document whose true height clears the activation watermark can fail to window at all. No
- * other box in the root reports it, hence the `1em` probe; the scale is relative to the size
- * `HEIGHT_ESTIMATES` were calibrated at.
- */
+/** A font-size change can throw the height estimates off enough that windowing never starts;
+ *  the `1em` element reports it, as a scale against `HEIGHT_ESTIMATES`. */
 export function installTypeScaleProbe(el, deps) {
     const apply = (fontSizePx) => {
         const next = fontSizePx / ESTIMATE_BASE_FONT_SIZE;
-        // Sub-percent moves are sub-pixel on a line box — not worth a full rebuild.
+        // A change under one percent is sub-pixel on a line box, not worth a full rebuild.
         if (!(next > 0) || Math.abs(next - deps.getScale()) < 0.01)
             return;
         deps.onScale(next);
@@ -62,29 +56,31 @@ export function installTypeScaleProbe(el, deps) {
     observer.observe(el);
     return () => observer.disconnect();
 }
-// Border boxes throughout, seed and fallback alike, so a browser without `borderBoxSize`
-// computes the same delta.
+// Border boxes throughout, first measurement and fallback alike, so a browser without
+// `borderBoxSize` computes the same difference.
 function borderBoxHeight(entries, el) {
     const box = entries[0]?.borderBoxSize?.[0];
     return box ? box.blockSize : el.getBoundingClientRect().height;
 }
-/**
- * The header slot's height lives outside the height model, so while the editor owns the
- * correction a growing header would slide the document under the reader. Compensating from
- * the SLOT's own resize composes with `correctAnchor` instead of double-correcting; a reveal
- * already holding the scroll outranks it.
- */
+// ── Header height ───────────────────────────────────────────────────
+// The header has already resized when its observer fires; there is no change left to run.
+const noChange = () => { };
+/** The header is not in the height table, so its own resize adds to the scroll correction, or a
+ *  growing header would slide the document. */
 export function installHeaderSlotCompensation(deps) {
-    const { el, port } = deps;
+    const { el, port, compensate } = deps;
     let lastHeight = el.getBoundingClientRect().height;
     const observer = new ResizeObserver((entries) => {
         const height = borderBoxHeight(entries, el);
         const delta = height - lastHeight;
         lastHeight = height;
-        if (delta === 0 || !deps.ownsScrollCorrection() || port.scrollTop() === 0)
+        if (delta === 0)
             return;
-        if (!deps.revealHoldsScroll())
-            port.scrollBy(delta);
+        // At the top the header is on screen, so the document moving down under it is expected.
+        compensate(noChange, (run) => {
+            run();
+            return port()?.scrollTop() === 0 ? 0 : delta;
+        });
     });
     observer.observe(el);
     return () => observer.disconnect();

package/dist/components/editor-root-gestures.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Editor-root pointer gestures: clicks in priority order (the link card, link activation, the
+ * caret for empty space, a block's own box), the margin drag the browser cannot start from a
+ * non-editable element, multi-click selection, and where a right-click leaves the caret.
+ */
+import type { BlockComponent } from '../block-component';
+import type { CaretMemory } from '../cursor/caret-memory';
+import type { CaretLanding } from '../selection/caret-landing';
+import type { UserScrollport } from '../cursor/scroll-ancestors';
+import type { BlockElLookup, DocumentGetter } from '../editor-keys';
+import type { SelectionState } from '../selection/selection-state.svelte';
+import type { WidgetSelectionState } from './image/widget-selection-state.svelte';
+import type { LinkCardState } from './link-card/link-card-state.svelte';
+import type { Reading } from '../schema/reading';
+export interface RootGesturesDeps {
+    getDoc: DocumentGetter;
+    selection: SelectionState;
+    caretMemory: Pick<CaretMemory, 'forget'>;
+    getBlockElByPath: BlockElLookup;
+    getBlockComponent(path: number[]): BlockComponent | null;
+    /** How a click below the last mounted block puts the caret at the document's end. */
+    land: CaretLanding['land'];
+    getScrollHost(): UserScrollport | null;
+    getLifetime(): AbortSignal;
+    isHostChrome(node: Node | null): boolean;
+    activateLink(href: string, event: MouseEvent): void;
+    linkCard: Pick<LinkCardState, 'open'>;
+    /** Read at the gesture: every branch below checks the mode in force then. */
+    reading: Reading;
+    /** Which inline widget is selected whole, so the click order can leave a run on it alone. */
+    widgetSelection: Pick<WidgetSelectionState, 'isSelected'>;
+}
+export interface RootGestures {
+    /** `root` is the element the installing effect captured, not a live binding. */
+    install(root: HTMLElement): () => void;
+    /** Where a click on empty space puts the caret, for a point the caller chose to answer. */
+    placeCaretAtPoint(root: HTMLElement, x: number, y: number): boolean;
+}
+export declare function createRootGestures(deps: RootGesturesDeps): RootGestures;