@graphty/graphty-element 2.6.1 → 3.0.0

package/dist/src/session/project/History.d.ts

@@ -0,0 +1,382 @@
+/**
+ * @file The undo history: recorded steps, a cursor over them, coalescing of repeated edits, and
+ * a byte and step budget.
+ *
+ * `History` does not know how a patch is made or what is inside one. It is handed three
+ * functions: apply a patch forward (redo), apply it backward (undo), and merge a newer patch into
+ * an older one (coalescing). Steps before the cursor are done; steps from the cursor on are the
+ * redo tail. See design/undo/undo-design.md sections 5, 5.2 and 7.
+ *
+ * It also keeps the arrangement (design section 6.4): each step may hold a before-capture, an
+ * after-capture and a row patch, and the arrangement after steps 1..k is
+ *
+ *     A(k) = after(k), if step k has one, with the rows a merged placement wrote over it since;
+ *            otherwise (before(k) if step k has one, else A(k-1)) with row patch(k) applied.
+ *     A(0) = the baseline capture.
+ *
+ * Undoing step k restores before(k) when it has one and A(k-1) otherwise; redoing it restores
+ * A(k). Each undo and redo leaves the {@link ArrangementOp}s that do this, which the caller takes.
+ *
+ * A group that takes a before-arrangement is opened here ({@link History.open}) while it is
+ * pending, and a capture sealed meanwhile goes to the newest such group as its provisional
+ * after-capture instead of into a step at or below its before (design section 6.4, "The seal
+ * target"). A(0) is a private buffer that eviction folds the evicted steps' arrangements into in
+ * place (design section 7).
+ */
+import { type ArrangementOp, type RowPatch } from "./arrangement";
+import type { ArrangementCapture } from "./state";
+/** Every step counts this much on top of what its patch retains. */
+export declare const STEP_OVERHEAD_BYTES = 512;
+/** Why the history changed. */
+export type HistoryChangeReason = "record" | "merge" | "undo" | "redo" | "restore" | "evict" | "clear" | "size";
+/** How the history reaches the patches it holds. */
+export interface HistoryOptions<P> {
+    /** Redo a patch. */
+    forward(patch: P): void;
+    /** Undo a patch. */
+    backward(patch: P): void;
+    /** One patch doing what `older` then `newer` did: the first prior, the last written value. */
+    merge(older: P, newer: P): P;
+    /** The clock of the coalescing window, in milliseconds. */
+    now?: () => number;
+    coalesceMs?: number;
+    limitBytes?: number;
+    limitSteps?: number;
+    /** Called after every change, once the version has moved. */
+    onChange?: (reason: HistoryChangeReason) => void;
+    /** The row patch a patch carries, if any. */
+    rows?(patch: P): RowPatch | null;
+    /**
+     * Whether undoing a step brings rows back at coordinates other than A(k-1), which must then
+     * be written over them; without it, a step with no capture and no row patch restores nothing.
+     */
+    restoresRows?(id: string): boolean;
+    /**
+     * Whether a patch added or removed nodes or edges, or changed an edge's weight: a change that
+     * sets a running layout moving. Where that layout comes to rest belongs to its step.
+     */
+    reshapes?(patch: P): boolean;
+}
+/** What one recorded group contributes to a step. */
+interface RecordInput<P> {
+    readonly label: string;
+    readonly patch: P;
+    /** Steps with equal keys recorded within the coalescing window become one step. */
+    readonly key?: string | null;
+    /**
+     * True when undoable work was dispatched after the top step was recorded and is still
+     * pending: the patch then starts a step of its own whatever its key, so that step never
+     * reaches back across that work (design section 5.2).
+     */
+    readonly pendingSinceTop?: boolean;
+    /** The ops of the commands in the patch, in the order they ran. */
+    readonly ops?: readonly string[];
+    readonly slices?: readonly string[];
+    readonly provenance?: Readonly<Record<string, string>>;
+    /** What the patch retains while done (for undo) and while undone (for redo). */
+    readonly bytes?: {
+        readonly done: number;
+        readonly undone: number;
+    };
+    /** The arrangement after the step, when it already has one: a large `positions.set`. */
+    readonly after?: ArrangementCapture | null;
+    /** The arrangement when the step's group began changing things, if it took one. */
+    readonly before?: ArrangementCapture | null;
+}
+/**
+ * A pending group that took a before-arrangement, from {@link History.open} until
+ * {@link History.close}.
+ */
+export interface OpenArrangement {
+    /** The arrangement when the group began changing things. */
+    readonly before: ArrangementCapture;
+    /**
+     * Where the lane came to rest since, sealed while the group was the seal target; dropped
+     * when a history call restores the lane.
+     */
+    readonly provisional: ArrangementCapture | null;
+}
+/** A step as the history publishes it. Frozen. */
+interface HistoryStepView {
+    readonly id: string;
+    readonly label: string;
+    /** ISO 8601 of the last record or merge. */
+    readonly at: string;
+    readonly ops: readonly string[];
+    readonly slices: readonly string[];
+    /** Retained on the side of the cursor the step is on, including the fixed overhead. */
+    readonly bytes: number;
+    readonly provenance: Readonly<Record<string, string>>;
+}
+/** Undo history over patches of type `P`. */
+export declare class History<P> {
+    private readonly options;
+    private readonly now;
+    private readonly coalesceMs;
+    private entries;
+    private cursor;
+    private total;
+    private changes;
+    private published;
+    private nextId;
+    /** Whether the top step may take a merge: false once anything but a record has happened. */
+    private mergeable;
+    private maxBytes;
+    private maxSteps;
+    /**
+     * A(0): the arrangement before the first step. `owned` when it is a private copy, which
+     * eviction folds steps into in place; otherwise a capture shared with others, copied before
+     * the first fold.
+     */
+    private baseline;
+    /** The pending groups holding a before-arrangement, oldest first. */
+    private groups;
+    /** What the undos and redos since the last take restore, in order. */
+    private arrangementOps;
+    /** While above zero, a history move is under way and eviction waits for it to land. */
+    private moving;
+    /**
+     * Create an empty history.
+     * @param options - How to apply and merge patches, the clock and the limits.
+     */
+    constructor(options: HistoryOptions<P>);
+    /**
+     * Counts changes; moves on every change.
+     * @returns The version.
+     */
+    get version(): number;
+    /**
+     * The count of done steps.
+     * @returns The cursor.
+     */
+    get position(): number;
+    /**
+     * What the steps retain, each on its side of the cursor.
+     * @returns Bytes.
+     */
+    get bytes(): number;
+    /**
+     * Oldest first; `steps[position..]` are undone. The identical array between changes.
+     * @returns The frozen steps.
+     */
+    get steps(): readonly HistoryStepView[];
+    /**
+     * The byte limit.
+     * @returns Bytes.
+     */
+    get limitBytes(): number;
+    /** Set the byte limit, evicting at once if it is now exceeded. */
+    set limitBytes(value: number);
+    /**
+     * The step limit.
+     * @returns Steps.
+     */
+    get limitSteps(): number;
+    /** Set the step limit, evicting at once if it is now exceeded. */
+    set limitSteps(value: number);
+    /**
+     * Record a patch that has already been applied: merge it into the top step when it coalesces
+     * with it, otherwise discard the redo tail and push a new step.
+     * @param input - The patch and what describes it.
+     * @returns The id of the step the patch is now in.
+     */
+    record(input: RecordInput<P>): string;
+    /**
+     * Merge a patch into the top step whatever its key and however long ago it was recorded: how
+     * work that finishes after its step was recorded (a transaction's deferred member) joins it.
+     * @param id - The step the patch belongs to.
+     * @param input - The patch and what describes it; its label is ignored.
+     * @returns False, merging nothing, when that step is not the top step or is undone.
+     */
+    amend(id: string, input: RecordInput<P>): boolean;
+    /**
+     * What a step keeps as a cache, if anything.
+     * @param id - The step.
+     * @returns The cached value, or undefined when the step keeps none or is gone.
+     */
+    cacheOf(id: string): unknown;
+    /**
+     * Keep a cache on a step, replacing any it had. It is counted in `bytes` and dropped before
+     * any step is evicted.
+     * @param id - The step; nothing happens when it is gone.
+     * @param value - What to keep.
+     * @param bytes - What it costs.
+     */
+    setCache(id: string, value: unknown, bytes: number): void;
+    /**
+     * Re-estimate every step's charge, oldest first, and evict when that puts the history over a
+     * limit. Quiet: the caller calls it straight after the change that moved the charges, whose
+     * own `history:changed` already tells readers to look again.
+     * @param charge - A step's charge from its patch. Called oldest step first, so something
+     * counted once is counted against the oldest step that holds it.
+     */
+    recharge(charge: (patch: P) => number): void;
+    /**
+     * Seal a capture of the lane into the seal target: the newest open group's provisional
+     * after-capture; else the after-capture of the newest applied step that has to do with the
+     * arrangement (it holds a capture or placed rows, or it changed the graph's shape); else the
+     * baseline. A step that moved nothing (a setting, a style) is never the target, so undoing it
+     * never puts back an arrangement older than the one on screen.
+     * @param capture - The capture.
+     */
+    seal(capture: ArrangementCapture): void;
+    /**
+     * A pending group took a before-arrangement: from now until it is closed, it is the seal
+     * target.
+     * @param before - Its before-arrangement.
+     * @returns Its handle; the dispatcher records `before` and `provisional` from it.
+     */
+    open(before: ArrangementCapture): OpenArrangement;
+    /**
+     * A group recorded or rolled back: it stops being a seal target.
+     * @param group - Its handle.
+     */
+    close(group: OpenArrangement): void;
+    /**
+     * What the undos and redos since the last call restore, in the order they happened.
+     * @returns The ops; the list is emptied.
+     */
+    takeArrangement(): ArrangementOp[];
+    /**
+     * Undo the latest done step.
+     * @returns The step undone, or null when there was none.
+     */
+    undo(): HistoryStepView | null;
+    /**
+     * Redo the next undone step.
+     * @returns The step redone, or null when there was none.
+     */
+    redo(): HistoryStepView | null;
+    /**
+     * Move to the state just after a step, or to the baseline, as the equivalent sequence of undos
+     * or redos.
+     * @param id - The step, or null for the baseline.
+     * @returns The steps passed, in the order they were undone or redone.
+     */
+    restoreTo(id: string | null): readonly HistoryStepView[];
+    /**
+     * Drop every step: the current state becomes the baseline.
+     * @param baseline - The arrangement now, the new A(0).
+     */
+    clear(baseline?: ArrangementCapture | null): void;
+    /**
+     * Merge a patch into a done top step: the first prior, the last written value.
+     * @param top - The top step.
+     * @param input - The patch and what describes it.
+     * @param time - `now()` of the merge.
+     * @param at - ISO 8601 of the merge.
+     */
+    private mergeInto;
+    /**
+     * Apply the latest done step backward and move the cursor over it.
+     * @returns The step, or null when none was done.
+     */
+    private back;
+    /**
+     * Apply the next undone step forward and move the cursor over it.
+     * @returns The step, or null when none was undone.
+     */
+    private ahead;
+    /**
+     * A step changed sides: its size and its view change with it.
+     * @param step - The step.
+     * @param delta - The change in what it retains.
+     */
+    private moved;
+    /**
+     * What a step retains on one side of the cursor.
+     * @param step - The step.
+     * @param done - Whether the step is done.
+     * @returns Bytes, with the fixed overhead.
+     */
+    private size;
+    /**
+     * Make one history move: the capture sealed before the cursor moves can take the history over
+     * its budget, and evicting then could take the very step being moved to. Eviction waits until
+     * the cursor has landed, where the step it landed on is protected.
+     * @param move - The seal and the move.
+     * @returns What `move` returned.
+     */
+    moveAs<T>(move: () => T): T;
+    /** Evict the oldest done steps, then the farthest redo steps, down to 90% of both limits. */
+    private evictIfOver;
+    /** A history call restores the lane: what open groups sealed before it no longer holds. */
+    private dropProvisionals;
+    /**
+     * Make a capture A(0), keeping `total` in step.
+     * @param capture - The capture.
+     * @param owned - Whether it is a private copy nothing else references.
+     */
+    private setBaseline;
+    /**
+     * Fold an evicted step's arrangement into A(0), by the recursion: A(k) is after(k) with the
+     * rows written over it since, or else before(k) or A(k-1), with row patch(k) applied. The
+     * buffer is written in place while it has the capture's rows; it is copied only when the rows
+     * differ, which a graph edit between the two makes them.
+     * @param step - The oldest step, being evicted.
+     */
+    private fold;
+    /**
+     * Write a row patch's new values into A(0), in place. A node the baseline does not hold yet (it
+     * was added after the baseline was taken) is appended, and then the buffer names no row order.
+     * @param rows - The patch.
+     */
+    private foldRows;
+    /**
+     * Whether a step has anything to do with the arrangement, so a rest point may seal into it.
+     * @param step - The step.
+     * @returns True when it holds a capture or placed rows, or changed the graph's shape.
+     */
+    private arranges;
+    /**
+     * Give a step a new after-capture, replacing the one it had.
+     * @param step - The step.
+     * @param capture - The capture.
+     */
+    private retake;
+    /**
+     * The row patch of a step, if it has one that counts: an after-capture already holds it.
+     * @param step - The step.
+     * @returns The patch, or null.
+     */
+    private rowsOf;
+    /**
+     * What undoing the step at `index` restores, given that the lane holds A(index + 1).
+     * @param index - The step.
+     * @returns The ops: before(k), or A(k-1).
+     */
+    private undoOps;
+    /**
+     * What redoing the step at `index` restores, given that the lane holds A(index).
+     * @param index - The step.
+     * @returns The ops: A(k).
+     */
+    private redoOps;
+    /**
+     * A(count), the arrangement after the first `count` steps, as ops written over the lane.
+     * @param count - How many steps.
+     * @returns The ops; without the baseline capture when there is none.
+     */
+    private arrangementAt;
+    /**
+     * One node's coordinates in A(count).
+     * @param count - How many steps.
+     * @param id - The node.
+     * @param hint - The row it is expected at.
+     * @returns x, y, z, or null when nothing the history holds places it.
+     */
+    private valueAt;
+    /**
+     * Bump the version, drop the published array and tell the listener.
+     * @param reason - Why.
+     */
+    private changed;
+    /**
+     * The published view of a step, built once per change of the step.
+     * @param step - The step.
+     * @param index - Its index, which says which side of the cursor it is on.
+     * @returns The frozen view.
+     */
+    private view;
+}
+export {};

package/dist/src/session/project/arrangement.d.ts

@@ -0,0 +1,247 @@
+/**
+ * @file The arrangement: where the nodes are, recorded at rest.
+ *
+ * A running layout moves every unpinned node every frame and most commands do not say where
+ * anything goes, so coordinates are not recorded per command. They are recorded as captures of
+ * the positions lane, taken when the lane has moved and something needs to know where it is: a
+ * rest point (the layout settled or was paused), a history call about to move the cursor, and a
+ * `positions.set` about to write. A capture goes into the newest applied step that has to do
+ * with the arrangement (it holds a capture or placed rows, or changed the graph's shape), or into
+ * the baseline when there is none: a step that moved nothing never takes one. `positions.set` writes only a few rows, so it records a row patch
+ * instead: the rows written, with their prior and new values.
+ *
+ * Undo and redo turn what the steps hold into {@link ArrangementOp}s (`History.ts` holds the
+ * rule), and the `arrangement` derivation hook writes them into the lane and hands the lane to
+ * the layout engine, which takes it as its own and stays at rest. Pins are the `pins` slice; the
+ * `pins` hook writes the lane's pin bytes from it and tells the engine. See
+ * design/undo/undo-design.md sections 6.2 and 6.4.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM: the renderer hands in an engine.
+ */
+import { type GraphSnapshot } from "@graphty/graph-format";
+import type { NodeId } from "../../catalog/types";
+import { type ElementPositions } from "../../data/positions";
+import type { PositionEntry } from "../types";
+import type { DerivationLane } from "./derive";
+import type { Draft } from "./draft";
+import { type GraphOps } from "./graphOps";
+import type { ArrangementCapture, ProjectState } from "./state";
+/**
+ * The coordinates a few rows were written with, and what they held before. Row indices are
+ * hints taken when the rows were written; a row is always checked against its id, and found by
+ * id when the rows have moved since.
+ */
+export interface RowPatch {
+    readonly ids: readonly NodeId[];
+    readonly rows: Uint32Array;
+    /** Per row: the prior x, y, z, then the new x, y, z. */
+    readonly values: Float32Array;
+}
+/** One thing the `arrangement` hook writes into the lane, in order. */
+export type ArrangementOp = {
+    readonly capture: ArrangementCapture;
+}
+/** Each row takes its new value, or its prior one when `forward` is false. */
+ | {
+    readonly patch: RowPatch;
+    readonly forward: boolean;
+};
+/** Where the lane lives: the snapshot its rows follow, and the lane itself. */
+interface LaneSource {
+    snapshot(): GraphSnapshot;
+    readonly positions: ElementPositions;
+    /** Whether the graph holds no node rows, answered without freezing; absent, records decide. */
+    holdsNoRows?(): boolean;
+    /** Whether the next read of the graph would freeze a snapshot, which a check must not force. */
+    readonly stale?: boolean;
+}
+/** What moves the lane besides history: the layout engine, as the renderer hands it in. */
+export interface ArrangementEngine {
+    /** Stop moving the lane: a history call is about to restore it. */
+    suspend(): void;
+    /**
+     * Take the lane's coordinates as the engine's own, and drop work that was computing from the
+     * coordinates it held before.
+     * @param restoring - True for undo, redo, a restore or a rollback: the engine is left at rest.
+     *     False for a forward `positions.set`: the engine keeps running if it was.
+     * @param wrote - Whether anything was written into the lane; when nothing was, every row the
+     *     graph held before holds what it did, and only rows the graph just gained are new.
+     */
+    loadArrangement(restoring: boolean, wrote: boolean): void;
+    /**
+     * A node was pinned or released; the lane's pin byte is already written.
+     * @param id - The node.
+     * @param pinned - Whether it is pinned now.
+     */
+    pin(id: NodeId, pinned: boolean): void;
+}
+/** Where a capture is sealed: the history's seal target. */
+interface SealTarget {
+    seal(capture: ArrangementCapture): void;
+}
+/**
+ * What a capture retains.
+ * @param capture - The capture.
+ * @returns Bytes: 12 per row of coordinates and 8 per id.
+ */
+export declare function captureBytes(capture: ArrangementCapture): number;
+/**
+ * What a row patch retains.
+ * @param patch - The patch.
+ * @returns Bytes: 4 for the row, 24 for the values and 8 for the id, per row.
+ */
+export declare function rowPatchBytes(patch: RowPatch): number;
+/**
+ * One patch doing what `older` then `newer` did: each row keeps its first prior and takes its last
+ * new value.
+ * @param older - The patch written first.
+ * @param newer - The patch written after it.
+ * @returns The merged patch.
+ */
+export declare function mergeRowPatches(older: RowPatch, newer: RowPatch): RowPatch;
+/**
+ * A node's coordinates in a capture.
+ * @param capture - The capture.
+ * @param id - The node.
+ * @param hint - The row it is expected at.
+ * @returns x, y, z, or null when the capture does not hold the node.
+ */
+export declare function coordsIn(capture: ArrangementCapture, id: NodeId, hint: number): Float32Array | null;
+/**
+ * The arrangement of one session: the current capture, the generation of the lane it matches,
+ * the `arrangement` and `pins` hooks, and the `positions.*` commands' writes.
+ *
+ * Its invariant: while the lane's generation equals the one recorded here, the lane holds the
+ * arrangement of the history's cursor, A(cursor). A seal, a restore and a `positions.set` keep it;
+ * a layout write breaks it until the next seal.
+ */
+export declare class Arrangement {
+    private readonly state;
+    private readonly lane;
+    private readonly history;
+    private readonly graph;
+    /** The layout engine; the renderer sets it, a test sets a fake. */
+    engine: ArrangementEngine | null;
+    private source;
+    private captured;
+    /**
+     * The capture the lane holds row for row, while nothing has written it since: what a group's
+     * before-arrangement shares instead of copying the lane. Null after a row write.
+     */
+    private exact;
+    /** Whether a forward `positions.set` wrote the lane since the last pass. */
+    private written;
+    private readonly ops;
+    private readonly strict;
+    /**
+     * The arrangement over a dispatcher's state, lane and history.
+     * @param state - The live project state; this writes its `arrangement` and reads its `graph`.
+     * @param lane - The derivation lane: the restoring flag, and where the hooks register.
+     * @param history - Where captures are sealed.
+     * @param graph - The graph primitives, which write the `pins` slice.
+     */
+    constructor(state: ProjectState, lane: DerivationLane, history: SealTarget, graph: GraphOps);
+    /**
+     * Hand in the lane, or take it away when the session is disposed. From here on the lane as it
+     * is counts as unmoved.
+     * @param source - The lane, or null.
+     */
+    bind(source: LaneSource | null): void;
+    /**
+     * Whether something has moved the lane since the last capture, restore or `positions.set`.
+     * @returns True when it has.
+     */
+    get moved(): boolean;
+    /**
+     * Copy the lane now. It becomes the current capture.
+     * @returns The capture, or null when there is no lane.
+     */
+    capture(): ArrangementCapture | null;
+    /**
+     * Seal the lane into the history's seal target when it has moved, unless a restore is still
+     * on its way to the lane: until the `arrangement` hook has run, the lane is not at rest.
+     */
+    seal(): void;
+    /**
+     * The arrangement a group begins from (design section 6.4, "Which groups take a
+     * before-arrangement"): the current capture, shared, when nothing has moved the lane since it
+     * was taken; otherwise the lane is captured, and that capture is sealed into the seal target
+     * first, because it is where the step below the group came to rest.
+     * @returns The capture, or null when there is no lane.
+     */
+    before(): ArrangementCapture | null;
+    /**
+     * Copy the lane now, with every restore still queued written into it first: the capture a
+     * group seals at its commit.
+     * @returns The capture, or null when there is no lane.
+     */
+    settledCapture(): ArrangementCapture | null;
+    /** A rest point: the layout settled, was paused, or finished a placement pass. */
+    rest(): void;
+    /** Stop the engine: a history call is about to move the cursor. */
+    stop(): void;
+    /**
+     * Queue what a history call or a rollback restores; the `arrangement` hook writes it and hands
+     * the lane to the engine. The engine takes the lane even when nothing is written: the graph
+     * under it may have changed, and an engine that recomputed its own arrangement for the new
+     * graph would draw over the restored one.
+     * @param ops - The ops, in order.
+     */
+    restore(ops: readonly ArrangementOp[]): void;
+    /**
+     * Write every restore still queued into the lane now, before a capture or a write reads it.
+     */
+    flush(): void;
+    /**
+     * `positions.set`: write rows of the lane, and record them in the draft as a row patch. When
+     * something has moved the lane since the last capture, that is sealed first, so the rows'
+     * prior values are an arrangement the history holds.
+     * @param entries - The rows and their coordinates.
+     * @param draft - The command's draft.
+     */
+    set(entries: readonly PositionEntry[], draft: Draft): void;
+    /**
+     * Whether a `positions.set` wrote so much of the lane that a capture is cheaper to keep than
+     * its row patch: more than a third of the rows.
+     * @param patch - What it wrote.
+     * @returns True when the step should keep a capture instead.
+     */
+    wantsCapture(patch: RowPatch): boolean;
+    /**
+     * `positions.pin`: pin or release nodes, in the `pins` slice and in the lane's pin bytes. A
+     * node the graph does not hold is skipped, as the element's own `pin` always has.
+     * @param ids - The nodes.
+     * @param pinned - Pin, or release.
+     * @param draft - The command's draft.
+     */
+    pin(ids: readonly NodeId[], pinned: boolean, draft: Draft): void;
+    /**
+     * Strict state: the lane's pin bytes agree with the `pins` slice. Asked at every commit and
+     * once each history call's pass has run, and not while a restore is on its way to the lane.
+     */
+    checkPins(): void;
+    /**
+     * Record a capture as the current one.
+     * @param capture - The capture.
+     */
+    private current;
+    /**
+     * The `arrangement` hook: write the queued ops into the lane, and hand the lane to the engine.
+     * @param restoring - Whether a history call or a rollback queued them.
+     */
+    private apply;
+    /**
+     * The `pins` hook: every node whose pin was written gets its lane byte from the slice, and the
+     * engine is told. Every dirty node, not only those whose pin differs from the last pass: a pin
+     * and its undo in one burst leave the slice as it was, but the pin wrote the byte at once.
+     * @param target - The state the picture must show.
+     * @param dirty - The pins written, as node keys.
+     */
+    private derivePins;
+    /**
+     * The lane, or the error a positions command gets on a session with none.
+     * @returns The lane.
+     */
+    private requireSource;
+}
+export {};