@voithos-labs/aragonite 0.10.1

package/dist/assert.js

@@ -0,0 +1,17 @@
+/**
+ * Dev-runtime invariant channel: routes a violation to devWarn and never throws, since a
+ * false positive must not crash a real editor. In production the predicate is not even
+ * invoked. Tests call predicates directly rather than going through here.
+ */
+import { DEV } from 'esm-env';
+import { devWarn } from './dev-warn';
+export function assertInvariant(tag, check) {
+    if (!DEV)
+        return;
+    const violation = check();
+    if (violation) {
+        // `invariant:` namespaces the console marker so the e2e simulation's error
+        // collector catches violations without tripping on benign dev warnings.
+        devWarn(`invariant:${tag}`, violation.message, violation.detail ?? violation.code);
+    }
+}

package/dist/block-component.d.ts

@@ -0,0 +1,274 @@
+/**
+ * The view-layer contract every rendered block satisfies, plus the cursor sentinels and
+ * ambient-prefix shape blocks produce. Orchestration reaches a block only through this flat
+ * interface, so a capability a block lacks is an omitted optional member rather than a kind
+ * check upstream; `ContainerBlockComponent` is the one promoted tier. Authoritative for
+ * external authors: each member's docstring states its own contract.
+ */
+import type { DocumentView, NodeView } from './core/node-views';
+import type { EditorRects } from './editor-rects';
+declare const cursorEndBrand: unique symbol;
+/** Branded `number`: a focus offset meaning "end of content", not a position. */
+export type CursorEnd = number & {
+    readonly [cursorEndBrand]: true;
+};
+declare const cursorStartBrand: unique symbol;
+/** Branded `number`: a focus offset meaning "start of content", not a position. */
+export type CursorStart = number & {
+    readonly [cursorStartBrand]: true;
+};
+declare const cursorExactStartBrand: unique symbol;
+/** Branded `number`: a focus offset meaning "raw byte 0 exactly, unclamped". */
+export type CursorExactStart = number & {
+    readonly [cursorExactStartBrand]: true;
+};
+declare const selectionEndBrand: unique symbol;
+/** Branded `number`: a measurePartialRects endOffset meaning "end of range". */
+export type SelectionEnd = number & {
+    readonly [selectionEndBrand]: true;
+};
+/**
+ * "Place cursor at end of content." Focus walkers fall through to their end-of-content
+ * fallback when the offset exceeds the block's length, so MAX_SAFE_INTEGER always lands
+ * there — a finite sentinel lands mid-block once content outgrows it.
+ */
+export declare const CURSOR_END: CursorEnd;
+/**
+ * "Place cursor at start of content" — {@link CURSOR_END}'s twin, and NOT a synonym for 0. A
+ * mode that paints no marker puts raw 0 out of the caret's reach behind a leading construct, so
+ * an ARRIVAL says this and the door seats it on the first landable offset.
+ */
+export declare const CURSOR_START: CursorStart;
+/**
+ * "Raw byte 0 exactly" — the ONE seat the park door does not clamp. A live split's continuation
+ * reopens a construct at byte 0 and typing must continue inside it (live-mode.md § 4.4), which
+ * the landable clamp would move outside; every other caller wants the clamp (G2.12).
+ */
+export declare const CURSOR_EXACT_START: CursorExactStart;
+/** Cascade focus to the last descendant and place the cursor at its start. */
+export declare const FOCUS_LAST_START = -1;
+/**
+ * "End of this block's measurable range" for measurePartialRects' endOffset. Each
+ * surface interprets it in its own coordinate system: text falls through to native
+ * range clamping, TableBlock matches it explicitly to reach the last cell.
+ */
+export declare const SELECTION_END: SelectionEnd;
+/**
+ * Direction the cursor is entering a block from for sticky-column moves.
+ * `'above'` = downward move; `'below'` = upward move.
+ */
+export type StickyColumnDirection = 'above' | 'below';
+/**
+ * Focus position for moveFocus. The sticky-column variant aligns to the current sticky
+ * X on the target's first/last visual line, falling back to focus(0) / focus(CURSOR_END).
+ */
+export type FocusPosition = 'start' | 'end' | number | {
+    stickyColumnFrom: StickyColumnDirection;
+};
+export interface AmbientInteractiveRange {
+    start: number;
+    end: number;
+    className: string;
+    role?: 'checkbox';
+    ariaChecked?: boolean;
+    /** The click lands on the range's own span, before the leaf's caret handling; a handler
+     *  reading the chord (`isWidgetActivationClick`) stops propagation to keep the gesture. */
+    onClick: (e: MouseEvent) => void;
+}
+export type AmbientPrefix = string | {
+    text: string;
+    interactive?: AmbientInteractiveRange[];
+};
+/**
+ * The props BlockHost passes every block component; a registry `extraProps` may add
+ * kind-specific ones. A component may declare a subset — Svelte ignores props it omits,
+ * but a leaf that drops `ambientPrefix` visually deletes its markers.
+ */
+export interface BlockComponentProps {
+    /** Bytes-readonly view (G1.9): components render the CST; mutation routes through actions. */
+    node: NodeView;
+    index: number;
+    myPath: number[];
+    /** Container-contributed read-only prefix rendered before the block's own raw (a list item's `- `). */
+    ambientPrefix: AmbientPrefix;
+    /** The root document, readonly by type — mutation stays a commit-ceremony concern. */
+    document?: DocumentView;
+    /** The owning instance's rect surface: measure/reveal/scroll by path. The live
+     *  instance object, so a block navigating to another shares the editor's one seam. */
+    rects?: EditorRects;
+}
+export interface BlockComponent {
+    /**
+     * Place the caret at `offset`, focusing the surface, and end any live cross-block range — the
+     * safe default door over {@link parkCaret}, since the range-ending batches with the landing.
+     * Also takes the four caret sentinels above, which stay internal (none is on
+     * `@voithos-labs/aragonite/plugin`). Clamping is required; never throw.
+     */
+    focus(offset: number): void;
+    /**
+     * `focus` WITHOUT the range-ending: seat the caret and touch nothing else. For
+     * selection-extend paths only (G2.12 guards the callers), where a `focus` would
+     * cancel the range still being grown; any other caller wants `focus`.
+     */
+    parkCaret?(offset: number): void;
+    /**
+     * Caret position as a raw offset into this block's own bytes: ambient markers
+     * excluded, a widget counted as the source bytes it stands for. `null` (never 0)
+     * means not in this block — dispatch walks refs to find the focused one.
+     */
+    getCursorOffset(): number | null;
+    /**
+     * The current selection's rendered text, or `''` when unmounted or nothing is
+     * selected. NOT clipped to this block: a cross-block selection returns the whole
+     * range. Rendered, not raw — a caller needing this block's bytes slices `raw`.
+     */
+    getSelectedText?(): string;
+    /**
+     * Select `[start, end)` in the same raw-offset space `getCursorOffset` returns.
+     * A no-op when the block is unmounted or the range doesn't resolve.
+     */
+    setSelection?(start: number, end: number): void;
+    /**
+     * Position the cursor at the offset nearest editor-relative pixel X on the first
+     * (`'above'`) or last (`'below'`) visual line; callers fall back to focus(0) /
+     * CURSOR_END when a block omits it. Inherits {@link parkCaret}'s semantics — it does
+     * NOT end a live cross-block range, which vertical traversal can never reach.
+     */
+    focusAtColumn?(x: number, from: StickyColumnDirection): void;
+    /** Cascade focus down a path of child indices to reach a leaf at the given offset. */
+    focusByPath?(path: number[], offset: number): void;
+    /**
+     * Apply this surface's own click-intent caret snap for a viewport point inside its box,
+     * after a landing has been placed. A caret that fell at an atomic widget's edge has no
+     * visual representation there, so the prose surface moves it onto the edge and paints the
+     * indicator Chromium omits; one that landed in real text is left alone. Omitted by
+     * surfaces with no such snap.
+     */
+    snapCaretToPoint?(clientX: number, clientY: number): void;
+    /**
+     * Descend child indices to the BlockComponent at the leaf, or null if the path
+     * doesn't resolve. Empty `path` returns this component. Containers implement it.
+     */
+    getBlockComponentByPath?(path: number[]): BlockComponent | null;
+    /**
+     * Async sibling of getBlockComponentByPath: at each nested level, scroll the child
+     * into its window and await its mount before recursing, so an off-window target
+     * resolves instead of returning null.
+     */
+    revealByPath?(path: number[]): Promise<BlockComponent | null>;
+    /**
+     * Deep cursor position for nested-block surfaces (table cells): the path from this
+     * block to the leaf holding the cursor, plus the within-leaf offset. Preferred over
+     * getCursorOffset by getSelection() when implemented.
+     */
+    getCursorPosition?(): {
+        path: number[];
+        offset: number;
+    } | null;
+    /**
+     * Viewport-space rects covering [startOffset, endOffset) in this block's visible
+     * text, for cross-block selection painting. Accepts SELECTION_END as endOffset,
+     * which surfaces interpret per their own coordinate system.
+     */
+    measurePartialRects?(startOffset: number, endOffset: number): DOMRect[];
+    /**
+     * Viewport-space rect of a single cell by 2D coordinate — whole-cell highlighting on
+     * grid surfaces, bypassing measurePartialRects' selection-aware range logic. Null
+     * when the cell isn't mounted or the coordinate is out of range.
+     */
+    cellRect?(rowIdx: number, colIdx: number): DOMRect | null;
+    /**
+     * Current mounted row-window `[start, end)` of a row-windowed grid surface. Overlays
+     * read it reactively so a repaint fires once the re-sliced rows are committed —
+     * off-window rows can't paint until mounted.
+     */
+    mountedRowWindow?(): {
+        start: number;
+        end: number;
+    };
+    /**
+     * True when vertical traversal should pass straight through: no caret-able text
+     * positions of its own, only widgets carrying no column meaning. Decided from the
+     * CST, not mounted refs, so a container answers the same for an off-window child.
+     */
+    isVerticallyTransparent?(): boolean;
+    /**
+     * Enter an edge widget instead of placing a caret at its boundary. What "enter" means
+     * belongs to the kind's registered `InlineWidgetEditingPolicy` — an open vocabulary,
+     * not a two-way choice. False lets the caller fall through to focus(0) / CURSOR_END.
+     */
+    enterEdgeWidget?(side: 'start' | 'end'): boolean;
+    /**
+     * Run a named block-local command resolved from a keybinding. `arg` carries the
+     * binding's static argument as `unknown` — the handler must type-guard it and ignore
+     * an out-of-shape value. False lets the caller fall through to later keydown branches.
+     */
+    runCommand?(id: import('./schema/command-id').AnyCommandId, arg?: unknown): boolean;
+    /**
+     * Whether the command's toggle-state reads ON at the surface's own caret or selection —
+     * the read a toolbar paints a pressed state from. Absent, or an id with no toggle-state,
+     * reads inactive.
+     */
+    isCommandActive?(id: import('./schema/command-id').AnyCommandId): boolean;
+    /**
+     * Current raw-offset selection in an editable leaf, a collapsed caret as
+     * `{start: n, end: n}`. Captured before a right-click menu steals focus.
+     */
+    getSelectionOffsets?(): {
+        start: number;
+        end: number;
+    } | null;
+    /**
+     * Claim a copy/cut/paste the editor root received because a selection state this block
+     * owns seats no native caret: a selected inline widget in a block with no text position
+     * leaves the native selection empty, so the browser dispatches at `<body>`. The claim is
+     * unconditional once the root has targeted this block, so there is nothing to report back:
+     * the seam offers the event to one arm only, and never re-offers it elsewhere.
+     */
+    claimRootClipboard?(event: ClipboardEvent): void;
+    /**
+     * Insert markdown at this surface's caret exactly as pasting it would, minus the
+     * clipboard — the block half of `EditorInstance.insertMarkdown`. True means the paste
+     * pipeline took the text, not that its commit has flushed. Omitted by non-editable blocks.
+     */
+    insertMarkdown?(md: string): boolean;
+    /**
+     * Run a clipboard action from the table cell's right-click menu against the offsets
+     * captured at menu-open (focus/selection may have moved since).
+     */
+    applyMenuClipboard?(action: 'cut' | 'copy' | 'paste', sel: {
+        start: number;
+        end: number;
+    }): Promise<void>;
+    /**
+     * Whether this component's own surface takes text input — a REPORT, never a gate. The
+     * kind's descriptor `editable` is the declaration and the only flag the editor gates on
+     * (merge eligibility, search scanning); this mirrors it for the mounted surface.
+     */
+    readonly editable: boolean;
+    /** Whether focus may land on this block at all. This is the flag focus dispatch reads. */
+    readonly focusable: boolean;
+}
+/**
+ * Every member a container owes, promoted to required: a caret entering a container has
+ * to descend, so the descent verbs are not "implement if you can" the way a leaf's
+ * optionals are. `createContainerBlockComponent` returns this.
+ */
+export type ContainerBlockComponent = BlockComponent & Required<Pick<BlockComponent, 'getCursorPosition' | 'focusByPath' | 'getBlockComponentByPath' | 'revealByPath' | 'focusAtColumn' | 'isVerticallyTransparent' | 'enterEdgeWidget' | 'parkCaret'>>;
+/**
+ * What a mounted block component publishes through `bind:this`: a leaf publishes the
+ * surface itself, a container publishes it under the one `containerApi` export (Svelte 5
+ * instance exports are individual declarations with no spread, so re-exporting a dozen
+ * members by hand drops one). The union is the enforcement — a container publishing a
+ * leaf-grade surface is a type error at its `defineBlockComponent` registration site.
+ */
+export type BlockComponentExports = BlockComponent | {
+    readonly containerApi: ContainerBlockComponent;
+};
+/**
+ * The `BlockComponent` behind a published instance — the one point that knows a
+ * container's surface hides under `containerApi`. Returns the object it was handed,
+ * never a wrapper: `publishRefSlot` compares identity, so a fresh one stomps a slot.
+ */
+export declare function resolveBlockSurface(exports: BlockComponentExports | undefined): BlockComponent | undefined;
+export {};

package/dist/block-component.js

@@ -0,0 +1,43 @@
+/**
+ * The view-layer contract every rendered block satisfies, plus the cursor sentinels and
+ * ambient-prefix shape blocks produce. Orchestration reaches a block only through this flat
+ * interface, so a capability a block lacks is an omitted optional member rather than a kind
+ * check upstream; `ContainerBlockComponent` is the one promoted tier. Authoritative for
+ * external authors: each member's docstring states its own contract.
+ */
+/**
+ * "Place cursor at end of content." Focus walkers fall through to their end-of-content
+ * fallback when the offset exceeds the block's length, so MAX_SAFE_INTEGER always lands
+ * there — a finite sentinel lands mid-block once content outgrows it.
+ */
+export const CURSOR_END = Number.MAX_SAFE_INTEGER;
+/**
+ * "Place cursor at start of content" — {@link CURSOR_END}'s twin, and NOT a synonym for 0. A
+ * mode that paints no marker puts raw 0 out of the caret's reach behind a leading construct, so
+ * an ARRIVAL says this and the door seats it on the first landable offset.
+ */
+export const CURSOR_START = -2;
+/**
+ * "Raw byte 0 exactly" — the ONE seat the park door does not clamp. A live split's continuation
+ * reopens a construct at byte 0 and typing must continue inside it (live-mode.md § 4.4), which
+ * the landable clamp would move outside; every other caller wants the clamp (G2.12).
+ */
+export const CURSOR_EXACT_START = -3;
+/** Cascade focus to the last descendant and place the cursor at its start. */
+export const FOCUS_LAST_START = -1;
+/**
+ * "End of this block's measurable range" for measurePartialRects' endOffset. Each
+ * surface interprets it in its own coordinate system: text falls through to native
+ * range clamping, TableBlock matches it explicitly to reach the last cell.
+ */
+export const SELECTION_END = Number.MAX_SAFE_INTEGER;
+/**
+ * The `BlockComponent` behind a published instance — the one point that knows a
+ * container's surface hides under `containerApi`. Returns the object it was handed,
+ * never a wrapper: `publishRefSlot` compares identity, so a fresh one stomps a slot.
+ */
+export function resolveBlockSurface(exports) {
+    if (!exports)
+        return undefined;
+    return 'containerApi' in exports ? exports.containerApi : exports;
+}

package/dist/block-id.d.ts

@@ -0,0 +1,14 @@
+import type { NodeView } from './core/node-views';
+/**
+ * These ids key Svelte's `{#each}`: process uniqueness, not unguessability. `crypto.randomUUID`
+ * answers a question nobody asked here, at a per-block cost a large load pays in full
+ * (`performance.md`), and is secure-context-only besides.
+ */
+export declare function generateBlockId(): string;
+export declare function assignIds(children: readonly NodeView[]): string[];
+/**
+ * Initialize `childIds` before a freshly-parsed subtree is spliced into the live tree: a
+ * reused container reads it in its keyed-each synchronously, so a missing array surfaces
+ * as `undefined` keys.
+ */
+export declare function assignChildIdsDeep(node: NodeView): void;

package/dist/block-id.js

@@ -0,0 +1,34 @@
+// A per-module-instance prefix: a dev-server reload restarts the counter while the live tree
+// still holds ids minted before it, and a repeat collides in Svelte's keyed each.
+const RUN = Math.random().toString(36).slice(2, 8);
+let sequence = 0;
+/**
+ * These ids key Svelte's `{#each}`: process uniqueness, not unguessability. `crypto.randomUUID`
+ * answers a question nobody asked here, at a per-block cost a large load pays in full
+ * (`performance.md`), and is secure-context-only besides.
+ */
+export function generateBlockId() {
+    sequence += 1;
+    return `b${RUN}-${sequence}`;
+}
+// View-typed: one id per slot, content never read — and `childIds` is the
+// bytes-view carve-out, legal to write even on a snapshot-shared node. Sized off `length`
+// rather than mapped, so a `$state` children array costs one proxy read instead of one per slot.
+export function assignIds(children) {
+    const ids = new Array(children.length);
+    for (let i = 0; i < ids.length; i++)
+        ids[i] = generateBlockId();
+    return ids;
+}
+/**
+ * Initialize `childIds` before a freshly-parsed subtree is spliced into the live tree: a
+ * reused container reads it in its keyed-each synchronously, so a missing array surfaces
+ * as `undefined` keys.
+ */
+export function assignChildIdsDeep(node) {
+    if (node.children && node.children.length > 0 && !node.childIds) {
+        node.childIds = assignIds(node.children);
+    }
+    for (const child of node.children ?? [])
+        assignChildIdsDeep(child);
+}

package/dist/bounded-memo.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A bounded, LRU-evicting memo for expensive render work — the cache primitive a plugin
+ * renderer builds on (see the plugin guide's renderer recipe). Async needs no variant:
+ * the caller stores the Promise, so an in-flight render is shared and a rejection is
+ * cached verbatim. `cloneOnRead` covers the one case a bare cache cannot — a value
+ * holding a live DOM node, which cannot occupy two places at once.
+ */
+export interface BoundedMemoOptions<V> {
+    /** Maximum live entries; the least-recently-used is evicted past it. */
+    cap: number;
+    /** Return a per-caller copy of a cached value (e.g. clone a live DOM node). */
+    cloneOnRead?: (value: V) => V;
+}
+export declare function createBoundedMemo<K, V>(options: BoundedMemoOptions<V>): (key: K, compute: () => V) => V;

package/dist/bounded-memo.js

@@ -0,0 +1,32 @@
+/**
+ * A bounded, LRU-evicting memo for expensive render work — the cache primitive a plugin
+ * renderer builds on (see the plugin guide's renderer recipe). Async needs no variant:
+ * the caller stores the Promise, so an in-flight render is shared and a rejection is
+ * cached verbatim. `cloneOnRead` covers the one case a bare cache cannot — a value
+ * holding a live DOM node, which cannot occupy two places at once.
+ */
+import { devWarn } from './dev-warn';
+export function createBoundedMemo(options) {
+    const { cloneOnRead } = options;
+    // Reported at creation, not per read: a non-positive cap would otherwise behave as 1
+    // unnoticed, so the author who meant "no caching" gets caching with nothing to read.
+    if (options.cap < 1) {
+        devWarn('bounded-memo', `cap must be at least 1; got ${options.cap} — using 1`);
+    }
+    const cap = Math.max(1, options.cap);
+    const cache = new Map();
+    return (key, compute) => {
+        let entry;
+        if (cache.has(key)) {
+            entry = cache.get(key);
+            cache.delete(key); // re-insert below so the hit becomes most recent
+        }
+        else {
+            entry = compute();
+            if (cache.size >= cap)
+                cache.delete(cache.keys().next().value);
+        }
+        cache.set(key, entry);
+        return cloneOnRead ? cloneOnRead(entry) : entry;
+    };
+}

package/dist/components/BlockDragHandle.svelte

@@ -0,0 +1,66 @@
+<script lang="ts">
+	import { DRAG_HANDLE_TITLE } from '../a11y-strings';
+</script>
+
+<!-- aria-hidden + non-focusable: keyboard reorder (Alt+Arrow) is the operable,
+	screen-reader-visible path, so this mouse-only grip stays out of the tab/SR flow. -->
+<span class="block-drag-handle" aria-hidden="true" title={DRAG_HANDLE_TITLE}>
+	<span class="grip"><span class="dots"></span></span>
+</span>
+
+<style>
+	.block-drag-handle {
+		position: absolute;
+		/* Sits inside the editor's own 1rem padding, so the grip clears the block's left
+		   border instead of being clipped behind it (overflow-x:auto). */
+		left: -0.85rem;
+		/* Spans gutter to content-left (width === |left|) so a pointer gliding from the
+		   block never crosses an un-hovered gap, which would hide the handle and — being
+		   pointer-events:none once hidden — strand it. Stopping AT content-left keeps
+		   line-start caret/marker clicks from being hijacked into a drag. */
+		width: 0.85rem;
+		/* Full-height hit strip so the handle is reachable at ANY height; the visible
+		   grip aligns to the first line. */
+		top: 0;
+		bottom: 0;
+		display: flex;
+		align-items: flex-start;
+		opacity: 0;
+		pointer-events: none;
+		cursor: grab;
+		user-select: none;
+		color: var(--color-ui-muted, #a4a4a4);
+	}
+
+	/* One line-height box so the dots sit on the first line; a block with a divergent
+	   inner line-height is off by a few px, which is cosmetic — reachability rides the strip. */
+	.grip {
+		display: flex;
+		align-items: center;
+		height: 1lh;
+	}
+
+	.dots {
+		display: block;
+		width: 0.5rem;
+		height: 0.85rem;
+		background-image: radial-gradient(currentColor 40%, transparent 45%);
+		background-size: 0.25rem 0.28rem;
+	}
+
+	/* Touch never fires the hover reveal, so the handle shows unasked. The pointer goes to the
+	   grip rather than the full-height strip, which would make the whole gutter unscrollable. */
+	@media (hover: none) {
+		.block-drag-handle {
+			opacity: 1;
+		}
+		.grip {
+			pointer-events: auto;
+			touch-action: none;
+			/* The whole gutter slot, not just the dots: 1rem of editor padding is all the width
+			   there is, and any more would reach over the line's first character. */
+			width: 100%;
+			justify-content: center;
+		}
+	}
+</style>

package/dist/components/BlockDragHandle.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const BlockDragHandle: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type BlockDragHandle = InstanceType<typeof BlockDragHandle>;
+export default BlockDragHandle;