@graphty/graphty-element 2.6.1 → 3.0.0

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

@@ -0,0 +1,132 @@
+/**
+ * @file The derivation lane: how every change to project state reaches the screen.
+ *
+ * Each slice registers hooks, `hook(rendered, target, dirty)`: from the state the picture last
+ * showed, to the state it must show, with the keys of that slice changed since. Forward commits,
+ * undo, redo, restore and rollback all mark keys dirty the same way (the project store reports
+ * every write), so restoring state restores the picture by construction.
+ *
+ * Every change schedules one pass as a microtask, so a burst of synchronous changes (a held
+ * Ctrl+Z, a restore across thirty steps) costs one pass that sees the net change. A change that
+ * arrives while a pass is running waits for the next one. Hooks run in a fixed order: `graph`,
+ * `layout`, `pins`, `arrangement`, then the rest, so the layout engine exists before pins are
+ * applied to it and the arrangement is loaded last. See design/undo/undo-design.md section 9.
+ *
+ * The lane runs apart from the operation queue, whose obsolescence rules cancel work and whose
+ * batch sort reorders it. Nothing here reaches Babylon.js, Lit or the DOM: the renderer registers
+ * its hooks on the session's lane.
+ */
+import type { ProjectState } from "./state";
+/** A slice of project state, as the lane marks and derives it. */
+type DerivedSlice = keyof ProjectState;
+/**
+ * Brings one slice of the picture from `rendered` to `target`. `dirty` holds the keys changed
+ * since the last pass ("" for a whole-value slice); a key may be dirty with no net change, so a
+ * hook compares the two states. It may return a promise; the pass waits for it.
+ */
+type DeriveHook = (rendered: ProjectState, target: ProjectState, dirty: ReadonlySet<string>) => unknown;
+interface LaneOptions {
+    /** Told when a hook throws; the pass goes on. By default the error is rethrown unhandled. */
+    readonly onError?: (error: unknown) => void;
+}
+/** The lane: `rendered` state, dirty keys per slice, one pass per burst of changes. */
+export declare class DerivationLane {
+    private readonly state;
+    private readonly onError;
+    private readonly hooks;
+    private dirty;
+    /** How many writes each slice has had, whoever wrote it. */
+    private readonly counts;
+    private shown;
+    /** The pass that will take the changes made since the running one started. */
+    private next;
+    private current;
+    private restoringFlag;
+    private restoreCause;
+    /** Moves on every restore, so a pass clears the flag only for restores made before it began. */
+    private restores;
+    /**
+     * Strict state's invariant check, run at the end of a pass that leaves nothing more to derive,
+     * with live state; what it throws goes where hook errors go. Null outside strict state.
+     */
+    afterPass: ((target: ProjectState) => void) | null;
+    /** What the running pass, or the last one, catches up with. */
+    private passCauseValue;
+    /**
+     * Create a lane over live state. The picture is taken to show that state already.
+     * @param state - The live state, which the lane reads and never writes.
+     * @param options - Where hook errors go.
+     */
+    constructor(state: ProjectState, options?: LaneOptions);
+    /**
+     * The state the picture shows: the target of the last finished pass.
+     * @returns A frozen copy.
+     */
+    get rendered(): ProjectState;
+    /**
+     * True from an undo, redo, restore or rollback until the `arrangement` hook of the pass that
+     * derives it has run. While it is set, hooks feed the layout without stepping or starting it.
+     * @returns The flag.
+     */
+    get restoring(): boolean;
+    /**
+     * Add a hook for one slice. Hooks of one slice run in the order registered.
+     * @param slice - The slice.
+     * @param hook - The hook.
+     * @returns A function that removes it.
+     */
+    register(slice: DerivedSlice, hook: DeriveHook): () => void;
+    /**
+     * How many writes a slice has had so far: a cache key that moves at once on every write,
+     * before the pass that derives it.
+     * @param slice - The slice.
+     * @returns The count.
+     */
+    writes(slice: DerivedSlice): number;
+    /**
+     * Mark a key of a slice changed, and schedule a pass.
+     * @param slice - The slice.
+     * @param key - The key; "" for a whole-value slice.
+     */
+    touch(slice: DerivedSlice, key: string): void;
+    /**
+     * Take live state as what the picture shows, with nothing left to derive: the baseline is
+     * drawn by the renderer's first draw, not by a pass.
+     */
+    adoptBaseline(): void;
+    /**
+     * What the pass being derived is catching up with: `"command"` for a forward change, or the
+     * history call or rollback that set the restoring flag.
+     * @returns The cause.
+     */
+    get cause(): "command" | "undo" | "redo" | "restore" | "rollback";
+    /**
+     * What the pass running now catches up with, for the whole of the pass: `cause` turns back to
+     * `"command"` once the `arrangement` hook has run, which hooks after it still need to know.
+     * @returns The cause the pass started with.
+     */
+    get passCause(): "command" | "undo" | "redo" | "restore" | "rollback";
+    /**
+     * Set the restoring flag until the next pass has run its `arrangement` hook.
+     * @param cause - What is restoring: an undo, a redo, a restore or a rollback.
+     */
+    restore(cause?: "undo" | "redo" | "restore" | "rollback"): void;
+    /**
+     * Settles when the picture has caught up with every change made so far.
+     * @returns The promise of the pass that takes the latest change; resolved at once when none
+     * is scheduled or running.
+     */
+    settled(): Promise<void>;
+    /** Make sure a pass will take the changes made so far. */
+    private schedule;
+    /** Run passes until nothing is dirty. */
+    private drain;
+    /**
+     * Call one hook, reporting what it throws.
+     * @param hook - The hook.
+     * @param target - The state the pass derives to.
+     * @param keys - The slice's dirty keys.
+     */
+    private call;
+}
+export {};

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

@@ -0,0 +1,33 @@
+/**
+ * @file The canonical state digest: one string that is equal for two states exactly when they
+ * hold the same project. The round-trip and random-sequence tests compare it before and after
+ * undo and redo.
+ *
+ * Canonical means order-free where order carries no meaning: map and set entries are sorted, and
+ * object keys are sorted. Functions (a compiled selector's predicate) are left out, because they
+ * are derived from data that is hashed.
+ *
+ * The graph part hashes the `graph` slice (the records by id and the graph-level values), and,
+ * given the snapshot, the rows behind it: node ids in row order, edges in row order
+ * with their endpoints and weights, and every column of the snapshot's tables except the two the
+ * positions lane lends it. With `arrangement`, those two are hashed as well: the coordinates and
+ * pin bytes the lane holds now, which is the arrangement undo and redo restore. The `arrangement`
+ * slice itself is not hashed: it names the last capture, a record of how the lane got there.
+ */
+import type { GraphSnapshot } from "@graphty/graph-format";
+import type { ProjectState } from "./state";
+/** Which optional parts a digest includes. */
+interface DigestOptions {
+    /** Hash the positions lane too: its coordinates and pin bytes. Needs `snapshot`. */
+    readonly arrangement?: boolean;
+    /** The snapshot of the graph the state holds, whose rows are hashed with the slice. */
+    readonly snapshot?: GraphSnapshot;
+}
+/**
+ * The canonical digest of a project state.
+ * @param state - The state.
+ * @param options - Which optional parts to include.
+ * @returns A digest, equal for equal states.
+ */
+export declare function stateDigest(state: ProjectState, options?: DigestOptions): string;
+export {};

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

@@ -0,0 +1,194 @@
+/**
+ * @file The only writer of project state: drafts, the patches they seal into, and applying a
+ * patch forward or backward.
+ *
+ * A draft writes through to live state as it goes and records, for each key it writes, the key's
+ * value just before its first write (its prior) and the value it last wrote (its next). Undo puts
+ * the priors back and redo puts the nexts back, as the identical objects.
+ *
+ * Two drafts can be open at once. When one writes a key the other has already written, the key
+ * is handed over: the later writer takes the earlier one's prior as its own, and the earlier one
+ * drops the key. So each key is in exactly one open draft, a rollback never undoes somebody
+ * else's later write, and undoing every step still returns to the state before all of them. See
+ * design/undo/undo-design.md section 4.3, "Value slices hand the key over".
+ *
+ * This module covers the value slices. The op-log slices (`graph`, `pins`) have writers of their
+ * own (`./graphOps.ts`), which write live state themselves and hand the draft an {@link OpLogEntry}
+ * saying how to put the write back and do it again; the draft keeps those entries in order, and
+ * undo, redo and rollback run them. The coordinates a `positions.set` writes are kept as a row
+ * patch beside them (`./arrangement.ts`); the history, not the draft, restores them.
+ */
+import type { CameraState } from "../../camera/types";
+import type { RunId, SetId } from "../../catalog/types";
+import type { ElementSet } from "../sets/types";
+import type { CompiledLayer } from "../styles/Layer";
+import { type RowPatch } from "./arrangement";
+import type { TouchedIds } from "./graphOps";
+import type { LayoutChoice, ProjectState, RunEntry, VisibilityState } from "./state";
+/** Stands for "the key had no value": a map key that was not there. */
+export declare const ABSENT: unique symbol;
+/** The slices a draft writes by value. */
+type ValueSlice = "config" | "layout" | "runs" | "styles" | "visibility" | "sets" | "views";
+/** One key a patch wrote: what it held before, and what the patch left in it. */
+interface PatchEntry {
+    readonly slice: ValueSlice;
+    /** The key within the slice; "" for the whole-value slices `styles` and `layout`. */
+    readonly key: string;
+    readonly prior: unknown;
+    readonly next: unknown;
+}
+/** A slice a patch can touch, by value, as an op-log, or as coordinates. */
+export type Slice = ValueSlice | "graph" | "pins" | "arrangement";
+/**
+ * One write to an op-log slice, recorded by the primitive that made it: live state already holds
+ * the write, and this says how to undo and redo it on resolved values. An entry may still grow
+ * while its draft is open (a chunked writer appends rows to it); it is never changed once sealed.
+ */
+export interface OpLogEntry {
+    readonly slice: "graph" | "pins";
+    /** Put the write back. `rollback` is true when the group never recorded it. */
+    undo(rollback: boolean): void;
+    /** Write it again, exactly as it was written. */
+    redo(): void;
+    /** What it retains, approximately, in bytes. */
+    bytes(): number;
+    /**
+     * Report the node and edge ids it wrote, for the selection after an undo or a redo.
+     * @param into - Where to report them.
+     */
+    touched(into: TouchedIds): void;
+}
+/** What a sealed draft recorded. Frozen. */
+export interface Patch {
+    readonly entries: readonly PatchEntry[];
+    /** The op-log writes, in the order they were made. */
+    readonly log: readonly OpLogEntry[];
+    /** The rows `positions.set` wrote, or null. */
+    readonly rows: RowPatch | null;
+}
+/**
+ * Whether a patch recorded anything.
+ * @param patch - The patch.
+ * @returns True when it wrote a value key or an op-log entry.
+ */
+export declare function isEmptyPatch(patch: Patch): boolean;
+/**
+ * A patch without the value entries that wrote what was there already, so a command that set
+ * something to its current value records no step.
+ * @param patch - The patch.
+ * @returns It, or a copy without those entries.
+ */
+export declare function withoutNoOps(patch: Patch): Patch;
+/**
+ * What a patch retains, for the history's byte budget.
+ * @param patch - The patch.
+ * @returns Bytes; value entries are held by reference and count nothing here.
+ */
+export declare function patchBytes(patch: Patch): number;
+/**
+ * Report the node and edge ids a patch touched: its op-log writes, the rows `positions.set` wrote,
+ * and the node members of a fixed set it wrote or removed. Value slices name no element.
+ * @param patch - The patch.
+ * @param into - Where to report them.
+ */
+export declare function touchedBy(patch: Patch, into: TouchedIds): void;
+/**
+ * What the run results and the kept sets a patch holds retain, counted once across the history:
+ * each result's columns and caches, each id index that is not the resident snapshot's, and each
+ * set record (design/undo/undo-design.md section 7).
+ * @param patch - The patch.
+ * @param token - The resident snapshot's graph token.
+ * @param seen - Results and indexes already counted against an older step.
+ * @returns Bytes.
+ */
+export declare function patchCharge(patch: Patch, token: number, seen: WeakSet<object>): number;
+/** Writes one key of a keyed slice. */
+interface KeyedWriter<K extends string, V> {
+    set(key: K, value: V): void;
+    delete(key: K): void;
+}
+/** An open draft: typed writers per value slice, and nothing else. */
+export interface Draft {
+    styles: readonly CompiledLayer[];
+    layout: LayoutChoice | null;
+    readonly config: KeyedWriter<string, unknown>;
+    readonly runs: KeyedWriter<RunId, RunEntry>;
+    readonly sets: KeyedWriter<SetId, ElementSet>;
+    readonly views: KeyedWriter<string, CameraState>;
+    readonly visibility: {
+        set<K extends keyof VisibilityState>(key: K, value: VisibilityState[K]): void;
+    };
+    /**
+     * Keep an op-log write, made to live state already, so undo, redo and rollback can reach it.
+     * @param entry - How to put it back and do it again.
+     */
+    log(entry: OpLogEntry): void;
+    /**
+     * Keep rows `positions.set` wrote to the lane already, merged with any the draft holds.
+     * @param rows - The rows, with their prior and new values.
+     */
+    arrange(rows: RowPatch): void;
+    /** Close the draft and hand back what it recorded. */
+    seal(): Patch;
+    /**
+     * Close the draft and put back every key it still holds, through `applyBackward`.
+     * @returns What was reverted; no entries when nothing live changed.
+     */
+    rollback(): Patch;
+    /**
+     * Remember what the draft holds now.
+     * @returns A function that puts back every key written since, releases the keys first written
+     * since, and returns the slices it changed. Keys handed to another draft since are theirs.
+     */
+    checkpoint(): () => readonly Slice[];
+}
+/** Project state plus the drafts that write it. */
+export interface ProjectStore {
+    readonly state: ProjectState;
+    open(): Draft;
+    /** Redo: write every key's `next`. */
+    applyForward(patch: Patch): void;
+    /** Undo: write every key's `prior`. */
+    applyBackward(patch: Patch): void;
+}
+/**
+ * Wrap a state as a store. The store is the state's only writer from here on.
+ * @param initial - The state; its maps must be the store's alone (see `createProjectState`).
+ * @param onWrite - Told of every key written to live state, whoever wrote it: a draft, undo,
+ * redo or a rollback. The derivation lane marks the key dirty.
+ * @returns The store.
+ */
+export declare function createProjectStore(initial: ProjectState, onWrite?: (slice: ValueSlice, key: string) => void): ProjectStore;
+/**
+ * One patch doing what `older` and then `newer` did: each key keeps its first prior and takes
+ * its last written value. How a coalesced step absorbs the next edit.
+ * @param older - The patch recorded first.
+ * @param newer - The patch recorded after it.
+ * @returns The merged patch, frozen.
+ */
+export declare function mergePatches(older: Patch, newer: Patch): Patch;
+/**
+ * Freeze an object and everything reachable from it, in place.
+ * @param value - The value.
+ * @returns The same value.
+ */
+export declare function deepFreeze<T>(value: T): T;
+/**
+ * A node or edge record as the `graph` slice keeps it: deep-frozen. Plain objects and arrays not
+ * frozen yet are copied as they are frozen, so the caller's own object is never frozen under it;
+ * anything else is copied with `structuredClone`. A value already frozen is kept as it is, which
+ * is what makes patching one key of a large record cost that key and not the record.
+ * @param value - The record, or a value inside one.
+ * @returns The frozen value.
+ */
+export declare function frozenRecord<T>(value: T): T;
+/**
+ * Copy a command argument that will be stored, and deep-freeze the copy, so a caller mutating
+ * its own object afterwards changes nothing in state.
+ * @param value - The argument, as the caller handed it in.
+ * @param byReference - Keys whose values are kept as the caller's own objects, wherever they
+ * appear, neither copied nor frozen (a style layer's `userData`).
+ * @returns A frozen copy.
+ */
+export declare function deepFreezeArgs<T>(value: T, byReference?: readonly string[]): T;
+export {};

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

@@ -0,0 +1,304 @@
+/**
+ * @file The graph primitives: the only writers of the `graph` slice and of the builder behind it.
+ *
+ * The `pins` slice is an op-log too, written here: a pin or a release, and the pins a removal
+ * takes with the rows it removes, so undoing the removal pins them again.
+ *
+ * A primitive writes live state at once and records, beside the write, the resolved values its
+ * inverse needs: the ids it added, the prior records of what it patched, an edge's endpoints,
+ * weight and element-assigned id. Undo and redo write those values straight back into the builder
+ * and the slice. They never go through ingest, so a change of the id path, the repeated-edge policy
+ * or the weight path made after the write does not change what redo writes. See
+ * design/undo/undo-design.md section 3.4, "The `graph` slice is an op-log".
+ *
+ * A {@link GraphWriter} is what ingest writes through. One bound to a command's draft records one
+ * op-log entry per writer. A writer with no draft is a write outside the dispatcher: strict state
+ * throws, and production logs it once. Only a data manager built without a session, which has no
+ * history to bypass, writes with no draft.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import { type GraphSnapshot } from "@graphty/graph-format";
+import type { EdgeId, NodeId } from "../../catalog/types";
+import type { GraphStore } from "../../data/GraphStore";
+import { type Draft, type OpLogEntry } from "./draft";
+import { type GraphRecord, type GraphSlice } from "./state";
+/** Which kind of element a record belongs to. */
+type RecordTarget = "node" | "edge";
+/** What became of a file's declared direction when it reached the builder. */
+export type DirectionOutcome = "applied" | "unchanged" | "config-wins" | "edges-present";
+/** Where the graph slice lives, and who hears of a write to it. */
+interface GraphHome {
+    /** The slice now. */
+    read(): GraphSlice;
+    /** Replace the slice object (its maps are shared): how a new token lands. */
+    write(slice: GraphSlice): void;
+    /** A key of the slice changed; the derivation lane marks it. */
+    touch(key: string): void;
+    /** The `pins` slice now. */
+    pins(): Set<NodeId>;
+    /** A node's pin changed; the derivation lane marks it. */
+    touchPin(id: NodeId): void;
+    /** Whether strict state is on for this home. */
+    readonly strict: boolean;
+    /** Whether a history lives here: false for a data manager built without a session. */
+    readonly session: boolean;
+}
+/**
+ * The lane key of a node's record and row.
+ * @param id - The node id.
+ * @returns The key; JSON, so 1 and "1" stay two keys.
+ */
+export declare const nodeKey: (id: NodeId) => string;
+/**
+ * The node id a lane key names.
+ * @param key - A key {@link nodeKey} made.
+ * @returns The id.
+ */
+export declare const nodeOfKey: (key: string) => NodeId;
+/**
+ * The lane key of an edge's record and row.
+ * @param id - The edge id.
+ * @returns The key.
+ */
+export declare const edgeKey: (id: EdgeId) => string;
+/** The lane key marking that node rows were added: a forward pass starts the layout and frames. */
+export declare const NODES_ADDED = "rows:nodes";
+/** The lane key marking that edge rows were added: a forward pass starts the layout. */
+export declare const EDGES_ADDED = "rows:edges";
+/**
+ * The key touched with any write that changes the graph's rows, weights or direction rather than
+ * only its records' attributes: what tells a hook that a record edit is all a pass has to follow.
+ */
+export declare const ROWS_MOVED = "rows:moved";
+/**
+ * What a snapshot holds, estimated from its storage: the adjacency arrays, every column's arrays,
+ * and an id slot and a map entry per node. Arrays a snapshot derives on first access are not
+ * counted until something asks for them.
+ * @param snapshot - The snapshot.
+ * @returns Bytes.
+ */
+export declare function snapshotBytes(snapshot: GraphSnapshot): number;
+/** The three maps of the `graph` slice. */
+interface GraphMaps {
+    readonly nodes: ReadonlyMap<NodeId, GraphRecord>;
+    readonly edges: ReadonlyMap<EdgeId, GraphRecord>;
+    readonly values: ReadonlyMap<string, unknown>;
+}
+/** What a removal took out, by id. */
+interface Removed {
+    readonly nodes: readonly NodeId[];
+    readonly edges: readonly EdgeId[];
+}
+/**
+ * What ingest writes through: one command's writes.
+ *
+ * Every method writes live state before it returns, so a getter reads the write at once.
+ */
+export interface GraphWriter {
+    /** The store written, for reads. */
+    readonly store: GraphStore;
+    /**
+     * Add a node row and its record, or give a row the builder already holds (an endpoint an edge
+     * created) its record.
+     * @param id - The extracted id; one graph-format will not store keeps its record and gets no row.
+     * @param record - The record.
+     * @param seed - The file coordinate, in file units, or null.
+     * @returns The row, INVALID_INDEX for an id with none, and whether the builder already held it.
+     */
+    addNode(id: NodeId, record: GraphRecord, seed: readonly [number, number, number] | null): {
+        index: number;
+        merged: boolean;
+    };
+    /**
+     * Add an edge row with a fresh element-assigned id, and its record.
+     * @param source - The resolved source id.
+     * @param target - The resolved target id.
+     * @param weight - The resolved weight.
+     * @param record - The record.
+     * @param fileId - The file's own id for the edge, read at `edgeIdPath`, when it has one.
+     * @returns The row and the id; INVALID_INDEX for both when either endpoint cannot be stored.
+     */
+    addEdge(source: unknown, target: unknown, weight: number, record: GraphRecord, fileId?: string | number): {
+        index: number;
+        edgeId: number;
+    };
+    /**
+     * Fold a repeated edge record into the edge it repeats: a new weight, and for the `last`
+     * policy its record too.
+     * @param edgeIndex - The row of the edge that survives.
+     * @param weight - Its new weight.
+     * @param record - Its new record, or null to keep the one it has.
+     */
+    mergeEdge(edgeIndex: number, weight: number, record: GraphRecord | null): void;
+    /**
+     * Patch one record: the named keys take the new values, the rest are kept.
+     * @param target - Node or edge.
+     * @param id - Its id.
+     * @param values - The new values.
+     * @returns False when the graph holds no such element.
+     */
+    setAttributes(target: RecordTarget, id: NodeId, values: GraphRecord): boolean;
+    /**
+     * Set graph-level values: the import report, graph-level results.
+     * @param values - The values by name.
+     */
+    setGraphValues(values: Readonly<Record<string, unknown>>): void;
+    /**
+     * Give the builder the direction a file declared, without overruling the consumer.
+     * @param directed - The declared direction.
+     * @param statedBy - The text that declared it.
+     * @returns What happened.
+     */
+    setDirected(directed: boolean, statedBy: string): DirectionOutcome;
+    /**
+     * Remove nodes and every edge attached to them, keeping everything their undo needs.
+     * @param ids - The node ids; one the graph does not hold is skipped.
+     * @returns What was removed.
+     */
+    removeNodes(ids: readonly NodeId[]): Removed;
+    /**
+     * Remove edges, keeping everything their undo needs.
+     * @param ids - The edge ids; one the graph does not hold is skipped.
+     * @returns What was removed.
+     */
+    removeEdges(ids: readonly EdgeId[]): Removed;
+    /** Empty the graph: every row, record and graph-level value. */
+    clear(): void;
+}
+/** The graph primitives of one session (or of one data manager with no session). */
+export declare class GraphOps {
+    private readonly home;
+    private readonly tokens;
+    private readonly epochs;
+    private warned;
+    /** The store the last writer wrote, which strict state checks for writes made around it. */
+    private store;
+    /**
+     * Primitives over a slice held somewhere else, a session's project state.
+     * @param home - Where the slice lives and who hears of writes.
+     */
+    constructor(home: GraphHome);
+    /**
+     * Primitives with nothing to record into: a data manager built without a session. There is
+     * no history for a write to bypass, so every write is accepted and recorded nowhere.
+     * @returns The primitives, over a slice of their own.
+     */
+    static standalone(): GraphOps;
+    /**
+     * The slice now.
+     * @returns The `graph` slice.
+     */
+    get slice(): GraphSlice;
+    /**
+     * A writer whose writes are recorded in a command's draft, or, handed no draft, a write
+     * outside the dispatcher: refused under strict state, logged once otherwise.
+     * @param draft - The command's draft, or null.
+     * @param store - The store to write.
+     * @returns The writer.
+     */
+    writer(draft: Draft | null, store: GraphStore): GraphWriter;
+    /**
+     * Strict: throw when the builder of the store last written was mutated outside the graph
+     * primitives, or its resident snapshot's arrays were written in place. The dispatcher asks at
+     * each dispatch and each commit.
+     */
+    checkStore(): void;
+    /**
+     * Take a token never issued before and make it the slice's.
+     * @returns The token.
+     */
+    retoken(): number;
+    /**
+     * Put a recorded token back: undo and redo restore the rows it names exactly.
+     * @param token - The token.
+     */
+    restoreToken(token: number): void;
+    /**
+     * Take an epoch never issued before and make it the slice's: the graph is a new dataset, whose
+     * coordinates are never mapped from another's.
+     * @returns The epoch.
+     */
+    newEpoch(): number;
+    /**
+     * Put a recorded epoch back.
+     * @param epoch - The epoch.
+     */
+    restoreEpoch(epoch: number): void;
+    /**
+     * Mark a key dirty on the lane.
+     * @param key - The key.
+     */
+    touch(key: string): void;
+    /**
+     * Pin or release nodes in the `pins` slice, recording the change in `draft`.
+     * @param draft - The command's draft, or null for a write with no history to record into.
+     * @param ids - The nodes.
+     * @param pinned - Pin, or release.
+     * @returns The ids whose pin changed.
+     */
+    setPinned(draft: Draft | null, ids: readonly NodeId[], pinned: boolean): NodeId[];
+    /**
+     * The `pins` slice, for the entries that write it.
+     * @returns The set.
+     */
+    pins(): Set<NodeId>;
+    /**
+     * Mark a node's pin dirty on the lane.
+     * @param id - The node.
+     */
+    touchPin(id: NodeId): void;
+    /**
+     * Swap the slice's three maps, keeping the token.
+     * @param maps - The maps to hold from now on.
+     */
+    swapMaps(maps: GraphMaps): void;
+}
+/**
+ * The node and edge ids the steps an undo, a redo or a restore passed touched, which the session
+ * then selects (design/undo/undo-design.md section 8). Collection stops, and nothing is selected,
+ * once a replace or a clear passes or more ids than the limit are touched: selecting everything
+ * says nothing, and a selection built only to be truncated says less.
+ */
+export declare class TouchedIds {
+    private readonly limit;
+    readonly nodes: Set<NodeId>;
+    readonly edges: Set<string>;
+    /** Whether to leave the selection as it is. */
+    skip: boolean;
+    /**
+     * An empty collection.
+     * @param limit - The most ids worth selecting: the selection cap.
+     */
+    constructor(limit: number);
+    /**
+     * A node was touched.
+     * @param id - The node.
+     */
+    node(id: NodeId): void;
+    /**
+     * An edge was touched.
+     * @param id - The edge.
+     */
+    edge(id: EdgeId): void;
+    /** Everything was touched: a replace or a clear. Select nothing. */
+    all(): void;
+    /** Give up once past the limit. */
+    private check;
+}
+/**
+ * Whether undoing a patch puts removed nodes back. Their rows come back at the coordinates they
+ * had when they were removed, which is not the arrangement below the step when the layout had
+ * moved them since the last rest point.
+ * @param log - The patch's op-log writes.
+ * @returns True when one of them removed a node.
+ */
+export declare function restoresNodes(log: readonly OpLogEntry[]): boolean;
+/**
+ * Whether an op log added or removed nodes or edges, or changed an edge's weight: what sets a
+ * running layout moving. A record or value edit does not.
+ * @param log - The op log.
+ * @returns True when it changed the graph's shape.
+ */
+export declare function reshapes(log: readonly OpLogEntry[]): boolean;
+export {};