@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/reactivity/use-window-floor.svelte.d.ts

@@ -0,0 +1,2 @@
+import type { WindowResult } from './block-window.svelte';
+export declare function useWindowFloor(getBox: () => HTMLElement | null | undefined, getWindow: () => WindowResult | undefined): void;

package/dist/reactivity/use-window-floor.svelte.js

@@ -0,0 +1,27 @@
+/**
+ * Holds a windowed list's box at its table height while a window change renders (VR-16). The new
+ * blocks mount one at a time, and a layout read between two of them would otherwise see a list
+ * short by the rest and clamp the scroll to it. Call during init of the component that renders
+ * the list's spacers.
+ */
+import { untrack } from 'svelte';
+export function useWindowFloor(getBox, getWindow) {
+    let held = null;
+    $effect.pre(() => {
+        const win = getWindow();
+        const box = untrack(getBox);
+        if (!box || !win?.active || win.floorPx <= 0)
+            return;
+        box.style.minHeight = `${win.floorPx}px`;
+        held = box;
+    });
+    // Gone before the browser's next size reports: a box held past a child's shrink would move
+    // the container around it inside that delivery, which the browser reports as a loop.
+    $effect(() => {
+        void getWindow();
+        if (!held)
+            return;
+        held.style.minHeight = '';
+        held = null;
+    });
+}

package/dist/reactivity/window-slice.d.ts

@@ -1,8 +1,8 @@
 /**
- * The one home for the windowed-slice bounds. A consumer renders `children.slice(start,
- * end)` and MUST key/index each rendered child by its ABSOLUTE index `start + localIndex`,
- * never the local loop index — leaking the local index corrupts paths and structural ops
- * invisibly (`docs/design/virtual-rendering.md`).
+ * The one place the mounted range's bounds are computed. A consumer renders
+ * `children.slice(start, end)` and must key and index each rendered child by its absolute
+ * index, `start + localIndex`, never the local loop index: letting the local index escape
+ * corrupts paths and structural operations invisibly (`docs/design/virtual-rendering.md`).
  */
 import type { WindowResult } from './block-window.svelte';
 export declare function sliceWindow(childCount: number, win: WindowResult | undefined): {

package/dist/reactivity/window-slice.js

@@ -1,8 +1,6 @@
 export function sliceWindow(childCount, win) {
     if (!win?.active)
         return { start: 0, end: childCount };
-    // A window derived from a prior, longer children array can arrive one reactive tick
-    // before the slice re-derives against the new length.
     const start = Math.min(win.start, childCount);
     const end = Math.min(win.end, childCount);
     return { start, end: Math.max(start, end) };

package/dist/renderer-slot.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The one place a plugin's injected renderer (KaTeX, mermaid) is set and cached. The editor's
+ * theme is part of every cache key, so a render is never reused under another theme, and a
+ * missing or throwing renderer comes back as the plugin's own fallback output, never an exception.
+ * `docs/guide/plugin-guide.md` § Recipe: a render-primary block.
+ */
+/** What every render call carries besides its input. `theme` is required, so no render can be
+ *  drawn or cached without it. */
+export interface RenderContext {
+    readonly theme: string;
+}
+/** How a slot keys a render and what it returns instead of one; the slot joins the theme to
+ *  `key(input)` itself. */
+export interface RendererSlotSpec<Input, Output> {
+    key(input: Input): string;
+    /** Shown while no renderer is set; never cached. */
+    missing(input: Input): Output;
+    /** Shown for a throw or a rejection, and cached like a success. */
+    failed(input: Input, error: unknown): Output;
+    /** Maximum cached renders, least recently used evicted first. Defaults to 256. */
+    cap?: number;
+}
+/** The synchronous slot's spec; the async slot caches a promise, so it has nothing to copy. */
+export interface SyncRendererSlotSpec<Input, Output> extends RendererSlotSpec<Input, Output> {
+    /** Hands each caller its own copy of a cached value, for output holding a live DOM node,
+     *  which can only sit in one place. */
+    cloneOnRead?(value: Output): Output;
+}
+/** A synchronous renderer's slot: set once from a plugin's setup, read from every render. */
+export interface RendererSlot<Input, Output> {
+    /** `null` removes the renderer. Either way the cache empties. */
+    set(renderer: ((input: Input, ctx: RenderContext) => Output) | null): void;
+    readonly configured: boolean;
+    render(input: Input, ctx: RenderContext): Output;
+}
+/** The slot for a renderer that returns a promise; the promise is what gets cached, so two
+ *  blocks asking for the same render share one call. */
+export interface AsyncRendererSlot<Input, Output> {
+    /** `null` removes the renderer. Either way the cache empties. */
+    set(renderer: ((input: Input, ctx: RenderContext) => Promise<Output>) | null): void;
+    readonly configured: boolean;
+    render(input: Input, ctx: RenderContext): Promise<Output>;
+}
+export declare function createRendererSlot<Input, Output>(spec: SyncRendererSlotSpec<Input, Output>): RendererSlot<Input, Output>;
+export declare function createAsyncRendererSlot<Input, Output>(spec: RendererSlotSpec<Input, Output>): AsyncRendererSlot<Input, Output>;
+/** The typed source in the code font, with `message` on hover: what a view drawn by a renderer
+ *  shows in its place. Styled inline, since it can land where no plugin sheet loads. */
+export declare function renderSourceFallback(source: string, message: string): HTMLElement;

package/dist/renderer-slot.js

@@ -0,0 +1,85 @@
+/**
+ * The one place a plugin's injected renderer (KaTeX, mermaid) is set and cached. The editor's
+ * theme is part of every cache key, so a render is never reused under another theme, and a
+ * missing or throwing renderer comes back as the plugin's own fallback output, never an exception.
+ * `docs/guide/plugin-guide.md` § Recipe: a render-primary block.
+ */
+import { createBoundedMemo } from './bounded-memo';
+import { enrollTestReset } from './schema/registry-reset';
+const DEFAULT_CAP = 256;
+// ── Public API ──────────────────────────────────────────────────────────────
+export function createRendererSlot(spec) {
+    const cache = createSlotCache(spec.cap, spec.cloneOnRead);
+    return {
+        set: cache.set,
+        get configured() {
+            return cache.renderer() !== null;
+        },
+        render(input, ctx) {
+            const renderer = cache.renderer();
+            if (!renderer)
+                return spec.missing(input);
+            return cache.read(ctx.theme, spec.key(input), () => {
+                try {
+                    return renderer(input, ctx);
+                }
+                catch (error) {
+                    return spec.failed(input, error);
+                }
+            });
+        }
+    };
+}
+export function createAsyncRendererSlot(spec) {
+    const cache = createSlotCache(spec.cap);
+    return {
+        set: cache.set,
+        get configured() {
+            return cache.renderer() !== null;
+        },
+        render(input, ctx) {
+            const renderer = cache.renderer();
+            if (!renderer)
+                return Promise.resolve(spec.missing(input));
+            return cache.read(ctx.theme, spec.key(input), () => {
+                let pending;
+                try {
+                    pending = Promise.resolve(renderer(input, ctx));
+                }
+                catch (error) {
+                    pending = Promise.reject(error);
+                }
+                return pending.catch((error) => spec.failed(input, error));
+            });
+        }
+    };
+}
+/** The typed source in the code font, with `message` on hover: what a view drawn by a renderer
+ *  shows in its place. Styled inline, since it can land where no plugin sheet loads. */
+export function renderSourceFallback(source, message) {
+    const span = document.createElement('span');
+    span.textContent = source;
+    span.title = message;
+    span.style.fontFamily = 'var(--font-code, ui-monospace, monospace)';
+    span.style.fontSize = '0.9em';
+    span.style.cursor = 'help';
+    return span;
+}
+// ── Shared cache ────────────────────────────────────────────────────────────
+function createSlotCache(cap = DEFAULT_CAP, cloneOnRead) {
+    const newMemo = () => createBoundedMemo({ cap, cloneOnRead });
+    let renderer = null;
+    let memo = newMemo();
+    const set = (next) => {
+        renderer = next;
+        memo = newMemo();
+    };
+    // A renderer is process-global like a registration, so the platform's test reset drops it too.
+    enrollTestReset(() => set(null));
+    return {
+        set,
+        renderer: () => renderer,
+        // NUL-joined so no (theme, key) pair can run into another pair's key.
+        read: (theme, key, compute) => memo(`${theme}\0${key}`, compute)
+    };
+}

package/dist/scan-index.d.ts

@@ -1,8 +1,8 @@
 /**
- * The bounded decline for a recognizer whose grammar has no early-stop byte: candidate
- * positions are collected once per block and each consultation is a binary search, so a
- * trigger-dense paragraph costs one scan instead of one per trigger. The index memoizes
- * per raw, bounded (cap 2) rather than weak-keyed because a string cannot key a WeakMap.
+ * How a recognizer declines cheaply when its grammar has no early-stop byte: candidate
+ * positions are collected once per block and each lookup is a binary search, so a paragraph
+ * full of triggers costs one scan instead of one per trigger. The index memoizes per raw
+ * string, with room for two, rather than by weak key: a string cannot key a `WeakMap`.
  */
 /**
  * `collect` scans one block's raw left to right into ascending positions; the returned

package/dist/scan-index.js

@@ -1,8 +1,8 @@
 /**
- * The bounded decline for a recognizer whose grammar has no early-stop byte: candidate
- * positions are collected once per block and each consultation is a binary search, so a
- * trigger-dense paragraph costs one scan instead of one per trigger. The index memoizes
- * per raw, bounded (cap 2) rather than weak-keyed because a string cannot key a WeakMap.
+ * How a recognizer declines cheaply when its grammar has no early-stop byte: candidate
+ * positions are collected once per block and each lookup is a binary search, so a paragraph
+ * full of triggers costs one scan instead of one per trigger. The index memoizes per raw
+ * string, with room for two, rather than by weak key: a string cannot key a `WeakMap`.
  */
 import { createBoundedMemo } from './bounded-memo';
 /**

package/dist/schema/block-commands.d.ts

@@ -1,44 +1,46 @@
 /**
- * The `(kind, id) → handler` block-command registry and every dispatch seam over it. A chord
- * (leaf or container bubble), the `runCommand` door and its admissibility read all resolve the
- * same tiers here, so the rules that hold regardless of invocation live at one seam.
- * Register-once, throw-on-duplicate (casebook.md "Registries are code, not state"). Here, not
- * `./commands`: `commands → block-commands → command-id` cycles.
+ * The `(kind, id) → handler` registry of block commands and every dispatch path over it. A chord
+ * on a leaf or a container, `EditorInstance.runCommand`, and the "can this run" read all resolve
+ * through the same lookup, so a rule that holds however a command was invoked is enforced once.
+ * Register-once, throw on duplicate. Not in `./commands`: `commands → block-commands → command-id`
+ * would be an import cycle.
  */
 import type { AnyBlockKind } from '../core/nodes';
 import type { NodeView } from '../core/node-views';
 import { type AnyCommandId, type PluginCommandId } from './command-id';
+import type { PluginActivation } from './plugin-activation';
 import { type GlobalCommandContext } from './commands';
 import type { KeybindingOverrideMap } from './keybinding-overrides';
 import { type EditorContext } from './plugin-install';
+import { type PresentationMode } from '../presentation-mode';
 export interface BlockCommandContext {
-    /** Read context — a bytes-readonly view; metadata edits go through `updateMetadata`. */
+    /** A read-only view of the node; metadata edits go through `updateMetadata`. */
     node: NodeView;
     arg: unknown;
     updateMetadata(patch: Record<string, unknown>): void;
     /**
-     * The mounted component's view-state hooks, which a render-primary plugin casts to its own
-     * hooks type. `undefined` when no component is mounted, and a handler must decline
-     * gracefully then; the platform never learns the shape (`unknown` by design).
+     * The mounted component's view-state hooks, cast by the plugin to its own type. `undefined`
+     * when no component is mounted, and a handler must then decline cleanly.
      */
     hooks?: unknown;
-    /** The dispatching instance's per-plugin EditorContext (document/events/options reads).
-     *  Undefined when the target surface has no instance wiring. */
+    /** The dispatching editor's `EditorContext` for the plugin that registered the command.
+     *  Undefined when the dispatch is not wired to an editor instance. */
     editor?: EditorContext;
 }
 export type BlockCommandHandler = (ctx: BlockCommandContext) => boolean;
+/** What the focused block supplies; the dispatch adds the argument and the editor context. */
+export type BlockTargetContext = Omit<BlockCommandContext, 'arg' | 'editor'>;
 /**
- * Register-once check precedes the mint, so a duplicate `(kind, name)` reports as
- * "register-once" rather than as an already-minted collision. The name-validating mint runs
- * inside `apply` before the map write, so an invalid name never leaves an orphaned handler.
+ * A duplicate `(kind, name)` reports as a register-once conflict, not an id collision, and the
+ * name is validated before the handler is stored, so an invalid name leaves no orphaned handler.
  */
 export declare function registerBlockCommand(kind: AnyBlockKind, name: string, handler: BlockCommandHandler): PluginCommandId;
-export declare function getBlockCommand(kind: AnyBlockKind, id: AnyCommandId): BlockCommandHandler | undefined;
-export declare function __resetBlockCommandsForTests(): void;
+/** The handler where `activation` resolves the plugin that registered it. */
+export declare function getBlockCommand(kind: AnyBlockKind, id: AnyCommandId, activation: PluginActivation): BlockCommandHandler | undefined;
 /**
- * The cross-block arm a range command routes to, injected because this schema leaf may not
- * import selection machinery. `canRun` is reachability, not participation: a press whose range
- * reaches no block still consumes the chord and writes nothing.
+ * The cross-block handler a range command routes to, injected because this schema module may not
+ * import the selection code. `canRun` asks whether the handler is reachable, not whether it will
+ * act: a keypress whose range reaches no block still consumes the chord and writes nothing.
  */
 export interface CrossBlockCommandRouter {
     canRun(id: AnyCommandId): boolean;
@@ -46,32 +48,53 @@ export interface CrossBlockCommandRouter {
     isActive(id: AnyCommandId): boolean;
 }
 /**
- * Editor state a command's admissibility reads, whatever invoked it. Getters, never values:
- * they change under a live editor between one dispatch and the next. Every field is required,
- * so a new dispatch site cannot silently skip the reading-mode gate, the range decline, or the
- * cross-block route — `undefined` for the router is the answer a bubble caller gives.
+ * The editor state that decides whether a command may run, whatever invoked it. Getters, never
+ * values: they change between one dispatch and the next.
  */
 export interface CommandGates {
-    getPresentationMode: GlobalCommandContext['getPresentationMode'];
+    getPresentationMode: () => PresentationMode;
+    /** The plugins the editor activated: a plugin's command resolves only where it is listed. */
+    activation: PluginActivation;
     /** True while a cross-block range is painted. */
     isCrossBlockRange(): boolean;
-    crossBlockCommands: CrossBlockCommandRouter | undefined;
+    crossBlockCommands: CrossBlockCommandRouter;
+}
+/** Moves the block at a path one step among its siblings: the editor's reorder action. Resolves to
+ *  whether the move landed. */
+export interface BlockMover {
+    nudgeReorderUnit(path: number[], dir: -1 | 1): Promise<boolean>;
+}
+/** Everything a chord or `EditorInstance.runCommand` dispatches against, built once per editor so
+ *  every dispatch site shares one history, one set of overrides and one error channel. */
+export interface CommandDispatchContext extends CommandGates {
+    history: GlobalCommandContext['history'];
+    pluginEditor: GlobalCommandContext['pluginEditor'];
+    keybindingOverrides(): KeybindingOverrideMap | undefined;
+    onCommandError: CommandErrorSink;
+    /** Runs `block.moveUp` and `block.moveDown` for every block, against the target's path. */
+    reorder: BlockMover;
 }
-/** What leaf dispatch and the `runCommand` door hand the seam: the gates plus the global tier. */
-export type CommandDispatchContext = GlobalCommandContext & CommandGates;
 export interface KindCommandTarget {
     kind: AnyBlockKind;
-    runCommand(id: AnyCommandId, arg?: unknown): boolean;
-    getCommandContext?(): Omit<BlockCommandContext, 'arg'>;
-    /** The id's toggle-state at the surface's own caret or selection — what a toolbar paints
-     *  pressed. Absent means the surface has no toggle-state to report, which reads inactive. */
+    /** The block's own built-in commands. Absent on a block that owns none (a plugin container),
+     *  where a built-in id declines. */
+    runCommand?(id: AnyCommandId, arg?: unknown): boolean;
+    getCommandContext?(): BlockTargetContext;
+    /** Whether the id is toggled on at this block's caret or selection, which a toolbar shows as
+     *  pressed. Absent means the block has no toggle state to report, which reads as inactive. */
     isCommandActive?(id: AnyCommandId): boolean;
+    /** The focused block's path, which `block.moveUp` and `block.moveDown` move. A container a key
+     *  bubbles up to supplies none: the block below it already ran the move. */
+    getPath?(): number[];
+    /** Runs `run` once a source the block shows is hidden and written, so a move takes the written
+     *  bytes along. Absent runs it at once. */
+    afterSourceCommit?(run: () => void): void;
 }
 /**
- * A contained plugin command failure. A block command reports its `kind`; a global command
- * reports its `plugin` and carries no kind. The dispatch seam hands this to the caller's sink,
- * which routes it to the editor's error channel (`origin: 'command'`, `editor-events.ts`) —
- * caller-injected so this schema leaf keeps no edge to the shell owning the event surface.
+ * A caught plugin command failure, naming the plugin that registered the command; a block command
+ * also reports its `kind`. Dispatch hands it to the caller's callback, which routes it to the
+ * editor's error event (`origin: 'command'`, `editor-events.ts`), injected so this schema module
+ * imports nothing from the editor shell.
  */
 export interface CommandErrorReport {
     kind?: AnyBlockKind;
@@ -81,25 +104,17 @@ export interface CommandErrorReport {
 }
 export type CommandErrorSink = (report: CommandErrorReport) => void;
 /**
- * The door's admissibility read: the gates plus the same tier walk the dispatch spends, never a
- * second derivation of them. Silent by design — a host may ask on every selection change, so an
- * unreachable id spends none of the dispatch's one-time dead-key diagnostics.
- * See `editor-props.ts` for the contract this answers.
+ * The read behind `EditorInstance.canRunCommand`, through the dispatch's own checks and lookup.
+ * Silent, since a host may ask on every selection change and must not spend the dead-key warnings.
  */
 export declare function canRunCommandById(id: AnyCommandId, target: KindCommandTarget | null, gates: CommandGates): boolean;
-/** The door's pressed-state read, `canRunCommandById`'s sibling: state rather than
- *  admissibility, so a disabled affordance may still paint pressed. Whoever would spend the
- *  press answers — the cross-block arm over a range, the focused surface at a caret. */
+/** The read behind `EditorInstance.isCommandActive`: state, not permission, so a disabled button
+ *  may still show pressed. Whoever would run the command answers. */
 export declare function isCommandActiveById(id: AnyCommandId, target: KindCommandTarget | null, gates: CommandGates): boolean;
-/** The `EditorInstance.runCommand` door: an id with no keystroke behind it. */
-export declare function runCommandById(id: AnyCommandId, arg: unknown, target: KindCommandTarget | null, ctx: CommandDispatchContext, onCommandError?: CommandErrorSink): boolean;
-/** Leaf-path chord dispatch (the focused editable/chrome surface). */
-export declare function dispatchKeyCommand(chord: string, target: KindCommandTarget, ctx: CommandDispatchContext, overrides?: KeybindingOverrideMap, onCommandError?: CommandErrorSink): boolean;
-/**
- * Container-bubble dispatch. Kind-only, no global tier: undo/redo belong to the focused leaf,
- * and a container bubble re-firing them would double-fire (`resolveKindBinding` in `./commands`).
- * The bubble callers hold no GlobalCommandContext, so they pass the gates directly — and an
- * override that resolves a GLOBAL id here resolves DEAD, declining loudly rather than being
- * dropped by a `runCommand` that has no arm for it.
- */
-export declare function dispatchKindCommand(chord: string, target: KindCommandTarget, gates: CommandGates, overrides?: KeybindingOverrideMap, onCommandError?: CommandErrorSink): boolean;
+/** The `EditorInstance.runCommand` entry point: an id with no keystroke behind it. */
+export declare function runCommandById(id: AnyCommandId, arg: unknown, target: KindCommandTarget | null, ctx: CommandDispatchContext): boolean;
+/** Chord dispatch on the focused leaf: an editable block, or a container's title row. */
+export declare function dispatchKeyCommand(chord: string, target: KindCommandTarget, ctx: CommandDispatchContext): boolean;
+/** Dispatch for a chord at a container: kind commands only, since undo/redo and the range
+ *  commands belong to the focused leaf and would otherwise fire twice. */
+export declare function dispatchKindCommand(chord: string, target: KindCommandTarget, ctx: CommandDispatchContext): boolean;