@voithos-labs/aragonite 0.10.1

package/dist/reactivity/block-list-state.svelte.js

@@ -0,0 +1,46 @@
+/**
+ * A container's inner BlockList scope: the keyed-each id source and the component-ref slot
+ * array. Structural mutations route through the commit primitives on UndoController, which
+ * apply `StructuralChange` descriptors to keep ids/refs aligned with children.
+ */
+import { assignIds } from '../block-id';
+import { registerBlockListState } from './state-registry';
+import { refSlotsOver } from './publish-ref.svelte';
+/** `getNode` must be a live getter — by-value freezes on the initial node and misses
+ *  undo's deep-clone reassignment. A view suffices: the only writes target `childIds`,
+ *  the bytes-view carve-out. */
+export function createBlockListState(getNode) {
+    const initialNode = getNode();
+    if (!initialNode.childIds) {
+        initialNode.childIds = assignIds(initialNode.children ?? []);
+    }
+    const innerBlockRefs = [];
+    const state = {
+        get innerBlockIds() {
+            return getNode().childIds ?? [];
+        },
+        set innerBlockIds(value) {
+            getNode().childIds = value;
+        },
+        innerBlockRefs,
+        refSlots: refSlotsOver(innerBlockRefs)
+    };
+    // Sync so callers outside a reactive context (unit tests) see the entry on creation.
+    registerBlockListState(initialNode, state);
+    // Re-register on node-identity changes (undo replaces nodes via deep clone).
+    $effect(() => {
+        const node = getNode();
+        if (!node.childIds) {
+            node.childIds = assignIds(node.children ?? []);
+        }
+        registerBlockListState(node, state);
+        // A parent-scope replace can reuse this instance with a node prop that has fewer
+        // children than before. Publish cleanup empties departing slots but never shrinks
+        // the array, and refs length must track children exactly, so reconcile it here.
+        const childCount = node.children?.length ?? 0;
+        if (innerBlockRefs.length > childCount) {
+            innerBlockRefs.length = childCount;
+        }
+    });
+    return state;
+}

package/dist/reactivity/block-window.svelte.d.ts

@@ -0,0 +1,41 @@
+import type { HeightModel } from '../cursor/height-model';
+import type { Scrollport } from '../cursor/scrollport';
+export interface WindowInputs {
+    scrollTop: number;
+    viewportHeight: number;
+    overscan: number;
+    pinnedIndex: number | null;
+    pinExtensionCap: number;
+    active: boolean;
+    activateAbovePx: number;
+    deactivateBelowPx: number;
+}
+export interface WindowResult {
+    active: boolean;
+    start: number;
+    end: number;
+    topSpacerPx: number;
+    bottomSpacerPx: number;
+}
+export declare function computeWindow(model: HeightModel, input: WindowInputs): WindowResult;
+export interface BlockWindowDeps {
+    getModel: () => HeightModel;
+    getPort: () => Scrollport | null;
+    /** Map the port's scrollTop into this list's own coordinate range. Identity for the top level. */
+    getLocalScrollTop: () => number;
+    getViewportHeight: () => number;
+    getPinnedIndex: () => number | null;
+    overscan: number;
+    pinExtensionCap: number;
+    activateAbovePx: number;
+    deactivateBelowPx: number;
+}
+export interface BlockWindow {
+    readonly result: WindowResult;
+    /** Push the scroll element's current scrollTop into the window state now. A
+     *  programmatic scrollTop write doesn't fire a `scroll` event, so the passive
+     *  listener wouldn't update the derived in time for a deterministic reveal. */
+    syncScrollTop(): void;
+    dispose(): void;
+}
+export declare function createBlockWindow(deps: BlockWindowDeps): BlockWindow;

package/dist/reactivity/block-window.svelte.js

@@ -0,0 +1,93 @@
+/**
+ * Window math for virtual rendering. `computeWindow` is pure: from a height model and the
+ * scroll viewport it returns the slice to mount (extended to keep a pinned caret block
+ * contiguous), the spacer heights preserving native scroll geometry, and the next
+ * activation state. `createBlockWindow` wires live getters and a scroll listener to it.
+ */
+import { untrack } from 'svelte';
+export function computeWindow(model, input) {
+    const n = model.size;
+    const total = model.total();
+    // The one activation decision in the feature: a scope windows purely on its own modeled
+    // height, so who owns the scroll changes which port is read and nothing else.
+    const active = input.active ? total >= input.deactivateBelowPx : total >= input.activateAbovePx;
+    if (!active || n === 0) {
+        return { active: false, start: 0, end: n, topSpacerPx: 0, bottomSpacerPx: 0 };
+    }
+    const firstVisible = model.indexAtOffset(input.scrollTop);
+    // Probe the last on-screen pixel: the viewport is half-open, so a block whose top sits
+    // exactly on the bottom edge isn't visible.
+    const lastVisible = model.indexAtOffset(input.scrollTop + input.viewportHeight - 1);
+    let start = Math.max(0, firstVisible - input.overscan);
+    let end = Math.min(n, lastVisible + 1 + input.overscan);
+    // Extend the CONTIGUOUS range so Svelte preserves the caret block's DOM node and native
+    // focus/IME survive a scroll — bounded, so a caret parked far away before a large scroll
+    // doesn't mount thousands. Beyond the cap it blurs.
+    const pin = input.pinnedIndex;
+    if (pin !== null && pin >= 0 && pin < n) {
+        if (pin < start && start - pin <= input.pinExtensionCap)
+            start = pin;
+        else if (pin >= end && pin + 1 - end <= input.pinExtensionCap)
+            end = pin + 1;
+    }
+    return {
+        active: true,
+        start,
+        end,
+        topSpacerPx: model.offsetOf(start),
+        bottomSpacerPx: total - model.offsetOf(end)
+    };
+}
+export function createBlockWindow(deps) {
+    let active = $state(false);
+    let scrollTop = $state(0);
+    let unsubscribe = null;
+    const onScroll = () => {
+        scrollTop = deps.getLocalScrollTop();
+    };
+    $effect(() => {
+        const port = deps.getPort();
+        if (!port)
+            return;
+        scrollTop = deps.getLocalScrollTop();
+        unsubscribe = port.subscribe(onScroll);
+        return () => {
+            unsubscribe?.();
+            unsubscribe = null;
+        };
+    });
+    const result = $derived.by(() => {
+        return computeWindow(deps.getModel(), {
+            scrollTop,
+            viewportHeight: deps.getViewportHeight(),
+            overscan: deps.overscan,
+            pinnedIndex: deps.getPinnedIndex(),
+            pinExtensionCap: deps.pinExtensionCap,
+            active,
+            activateAbovePx: deps.activateAbovePx,
+            deactivateBelowPx: deps.deactivateBelowPx
+        });
+    });
+    // Hysteresis state. `result` reads `active` and this effect writes it, so the write is
+    // untracked and change-guarded — otherwise the effect depends on its own write. It
+    // converges: once `active` equals `result.active` the guard writes nothing.
+    $effect(() => {
+        const next = result.active;
+        untrack(() => {
+            if (active !== next)
+                active = next;
+        });
+    });
+    return {
+        get result() {
+            return result;
+        },
+        syncScrollTop() {
+            scrollTop = deps.getLocalScrollTop();
+        },
+        dispose() {
+            unsubscribe?.();
+            unsubscribe = null;
+        }
+    };
+}

package/dist/reactivity/content-version.svelte.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A number that changes whenever a byte-writing door announces it, so a whole-document
+ * derivation can memoize over a `$state` document that is mutated IN PLACE and never changes
+ * identity. Reading it inside a `$derived` subscribes that reader to every edit. The doors are
+ * censused (G4.52): the commit ceremony announces every structural write at its publish, and the
+ * writers outside it announce their own.
+ */
+export interface ContentVersion {
+    /** The current key, stable until a door bumps it. */
+    read(): number;
+    /** Announce that this door moved the document's serialized bytes. */
+    bump(): void;
+}
+export declare function createContentVersion(): ContentVersion;

package/dist/reactivity/content-version.svelte.js

@@ -0,0 +1,16 @@
+/**
+ * A number that changes whenever a byte-writing door announces it, so a whole-document
+ * derivation can memoize over a `$state` document that is mutated IN PLACE and never changes
+ * identity. Reading it inside a `$derived` subscribes that reader to every edit. The doors are
+ * censused (G4.52): the commit ceremony announces every structural write at its publish, and the
+ * writers outside it announce their own.
+ */
+export function createContentVersion() {
+    let version = $state(0);
+    return {
+        read: () => version,
+        bump: () => {
+            version++;
+        }
+    };
+}

package/dist/reactivity/list-windowing.svelte.d.ts

@@ -0,0 +1,100 @@
+import type { HeightOracle } from '../cursor/height-oracle';
+import type { Scrollport } from '../cursor/scrollport';
+import { type WindowResult } from './block-window.svelte';
+import { type MeasureEntry } from './measure-batch';
+import type { NodeView } from '../core/node-views';
+import type { RevealBlock } from '../cursor/reveal-anchor';
+/**
+ * An active reveal target in one scope's coordinates. The model addresses only this
+ * scope's own children, so a nested target arrives as its top-level ancestor's `index`
+ * plus the measured drop down to the target — pinning the block the reveal aimed at
+ * rather than its container.
+ */
+export interface RevealAnchorPlacement {
+    index: number;
+    block: RevealBlock;
+    /** Drop from the ancestor's top to the target's top; 0 when the target IS the ancestor. */
+    innerOffset: number;
+    /** The target's own height, for `'center'`; null when it can't be measured. */
+    height: number | null;
+}
+export interface ListWindowingDeps {
+    oracle: HeightOracle;
+    getChildren: () => readonly NodeView[];
+    getChildIds: () => string[];
+    /** This scope's own list element — its top within the scroll content maps port scrollTop to local. */
+    getListEl: () => HTMLElement | null;
+    /** The single scrollport every scope of this editor windows against: the root under
+     *  `scrollMode="self"`, the host's scroller or the page viewport under `"host"`. */
+    getPort: () => Scrollport | null;
+    /** The focused block's full path, for the per-level pin. */
+    getFocusPath: () => number[] | null;
+    /** Where an active reveal target sits in this scope's coordinates, else null. While set,
+     *  `correctAnchor` holds THAT position instead of the top-of-viewport block. Wired on
+     *  the ROOT scope only — nested scopes would fight over one scrollTop. */
+    getRevealAnchorTarget?: () => RevealAnchorPlacement | null;
+    /** Monotonic counter bumped on an editor WIDTH change (after the oracle's measured
+     *  cache is cleared). Rebuilds the model at the new width and re-measures mounted blocks. */
+    getWidthVersion: () => number;
+    /** Monotonic counter bumped when the PORT's height changes. The slice's extent comes
+     *  from a plain DOM height read, which no reactive edge reaches; this is that edge. */
+    getViewportHeightVersion: () => number;
+    /** This scope's path (the parentPath its children render under). [] at top level. */
+    getParentPath: () => number[];
+    /** This scope's own measurable box; re-measured on inner reflow to report a fresh subtotal upward. Absent at top level. */
+    getOwnEl?: () => HTMLElement | null;
+    /** Report this scope's own box height to the parent scope's setChildSubtotal (undefined at top level). */
+    reportSelfHeight?: (height: number) => void;
+    /** False while the HOST's native scroll anchoring holds the reader instead (host mode below
+     *  the windowing budget): two writers on one scroll position double-correct. */
+    correctsScroll: () => boolean;
+    /** Collapse clamp: while true this scope mounts ONLY its chrome row, a fixed [0,1) with
+     *  zero spacers. The window math is bypassed, not fed — collapse is height removal, and
+     *  a clamped slice through `computeWindow` would emit the body as a giant spacer. */
+    isCollapsed?: () => boolean;
+    overscan: number;
+    pinExtensionCap: number;
+    activateAbovePx: number;
+    deactivateBelowPx: number;
+}
+export interface ListWindowing {
+    readonly window: WindowResult;
+    /** A DIRECTLY-MEASURED leaf: oracle (by id) + model slot. Passive — no scrollTop write. */
+    recordMeasuredChild(index: number, id: string, height: number): void;
+    /** A PROPAGATED child-container subtotal: oracle + model slot, addressed by index. No anchor correction. */
+    setChildSubtotal(index: number, total: number): void;
+    /** Enroll a child in this scope's batched measure pass; returns an unregister fn to call on
+     *  the child's unmount. The scope reads ALL pending children before applying ANY write, so a
+     *  fling that mounts many costs one reflow. */
+    registerChild(id: string, child: MeasureEntry): () => void;
+    /** Re-measure ONE registered child immediately (its content height changed on edit). */
+    measureChildNow(id: string): void;
+    /** ResizeObserver path: O(1)-gate `observedHeight` against the recorded height and
+     *  re-measure only on a genuine post-mount change, so the no-op mount resize on a fling
+     *  costs no DOM read. */
+    measureChildOnResize(id: string, observedHeight: number): void;
+    /**
+     * True when the scroll position IS the reveal target's requested placement. Asked by
+     * any writer that would otherwise add a relative delta to the same scrollTop: the
+     * anchor derives its position from live geometry, so a delta on top double-counts.
+     * A question, never a write — re-placing here would drag the reader to the top pin on
+     * a resize they only wanted compensated. Root scope only; nested scopes answer false.
+     */
+    revealHoldsScroll(): boolean;
+    /** Scroll this scope so child `index` enters its window; resolves after a tick. */
+    revealChild(index: number): Promise<void>;
+    /** True iff `index` is in the CURRENT mounted window (inactive ⇒ always true; collapsed
+     *  ⇒ only the chrome row). Read after `revealChild` to prove a reveal landed before
+     *  waiting on a mount that can otherwise never come (VR-5 termination). */
+    isInWindow(index: number): boolean;
+    dispose(): void;
+}
+/**
+ * Resize-gate decision (pure, unit-tested). Keyed on the height DIFFERING from what is
+ * recorded, never on which callback delivered it: a cached remount can report the grown
+ * size in the very first callback, so a callback-order heuristic would drop it.
+ * `recorded === undefined` means the batched mount pass hasn't measured this block yet —
+ * defer to it rather than racing a lone read in on a fling-dirtied layout.
+ */
+export declare function shouldRemeasureOnResize(recorded: number | undefined, observed: number): boolean;
+export declare function createListWindowing(deps: ListWindowingDeps): ListWindowing;