@graphty/graphty-element 2.6.1 → 3.0.0

package/dist/src/layout/KamadaKawaiLayoutEngine.d.ts

@@ -45,5 +45,11 @@ export declare class KamadaKawaiLayout extends SimpleLayoutEngine {
      * reading: heavier means more strongly connected, means drawn closer together.
      */
     doLayout(): void;
+    /**
+     * The `dist` option as the matrix the layout reads, `n * n` distances row by row; a pair the
+     * record does not give is unreachable.
+     * @returns the matrix, or null for no option
+     */
+    private distances;
 }
 export {};

package/dist/src/layout/LayoutEngine.d.ts

@@ -1,10 +1,13 @@
-import { type NodeMask } from "@graphty/graph-format";
+import { type F32, type GraphSnapshot, type NodeMask } from "@graphty/graph-format";
+import { type LayoutResult } from "@graphty/layout";
 import { z } from "zod/v4";
+import { type RegisterOptions } from "../catalog/pluginRegistry";
 import type { AuthoredLayoutDescriptor } from "../catalog/types";
 import type { OptionsSchema } from "../config";
 import { ElementPositions } from "../data/positions";
 import type { Edge } from "../Edge";
-import type { Node, NodeIdType } from "../Node";
+import type { Node } from "../Node";
+import type { ReadonlyElementPositions } from "../session/types";
 export interface Position {
     x: number;
     y: number;
@@ -15,28 +18,6 @@ export interface EdgePosition {
     dst: Position;
 }
 type LayoutEngineClass = new (opts: object) => LayoutEngine;
-/**
- * The smallest weight either weighted layout is allowed to act on.
- *
- * A record may carry `weight: 0`, and both layout functions in `@graphty/layout` read a weight as
- * `getEdgeData(...) || 1`, which turns a deliberate zero into a FULL-strength edge -- the exact
- * opposite of what the author wrote, with nothing on screen to say so. Clamping here means zero
- * reads as "as close to nothing as the solver allows" in both engines: the weakest possible pull
- * in ForceAtlas2, the largest possible distance in Kamada-Kawai.
- */
-export declare const WEIGHT_EPSILON = 0.000001;
-/**
- * The key an ordered endpoint pair is filed under in a {@link LayoutEngine.pairWeights} map.
- *
- * It names a PAIR, not an edge: two parallel edges between the same two nodes share one key, and
- * that is deliberate -- see {@link LayoutEngine.pairWeights}. JSON is used rather than a separator
- * because a node id is a string or a number and may contain any character at all, so `a:b -> c`
- * and `a -> b:c` would collide under any punctuation, and `"1"` would collide with `1`.
- * @param source - the edge's source node id
- * @param target - the edge's target node id
- * @returns a key unique to that ordered pair
- */
-export declare function pairWeightKey(source: NodeIdType, target: NodeIdType): string;
 /**
  * What a layout engine class declares about itself, which is what the element and a picker read
  * without constructing one.
@@ -86,6 +67,37 @@ export interface LayoutEngineStatics {
     getZodOptionsSchema(): OptionsSchema;
     hasZodOptions(): boolean;
 }
+/**
+ * The element's own reach into an engine's protected placement members: the hooks that apply the
+ * `positions` and `pins` slices, and the drag. No entry point exports it; a consumer places and
+ * pins nodes through `session.positions`.
+ */
+export declare const layoutEngineInternals: {
+    /** See `LayoutEngine.setNodePosition`. */
+    setNodePosition(engine: LayoutEngine, n: Node, p: Position): void;
+    /** See `LayoutEngine.pin`. */
+    pin(engine: LayoutEngine, n: Node): void;
+    /** See `LayoutEngine.unpin`. */
+    unpin(engine: LayoutEngine, n: Node): void;
+    /** The engine's writable coordinate array; `LayoutEngine.nodePositions` is its read-only view. */
+    positions(engine: LayoutEngine): ElementPositions;
+    /** See `LayoutEngine.addNode`. */
+    addNode(engine: LayoutEngine, n: Node): void;
+    /** See `LayoutEngine.addEdge`. */
+    addEdge(engine: LayoutEngine, e: Edge): void;
+    /** See `LayoutEngine.addNodes`. */
+    addNodes(engine: LayoutEngine, nodes: Node[]): void;
+    /** See `LayoutEngine.addEdges`. */
+    addEdges(engine: LayoutEngine, edges: Edge[]): void;
+    /** See `LayoutEngine.removeNode`. */
+    removeNode(engine: LayoutEngine, n: Node): void;
+    /** See `LayoutEngine.removeEdge`. */
+    removeEdge(engine: LayoutEngine, e: Edge): void;
+    /** See `LayoutEngine.attachPositions`. */
+    attachPositions(engine: LayoutEngine, positions: ElementPositions): void;
+    /** See `LayoutEngine.edgeProblems`. */
+    edgeProblems(engine: LayoutEngine, drawn: ReadonlyMap<string, Edge>): string[];
+};
 /**
  * Base class for all layout engines
  *
@@ -107,6 +119,15 @@ export interface LayoutEngineStatics {
  * is inexpressible and a frame allocates once per node. With the coordinates in one shared array,
  * a view reads them by index and allocates nothing, and a GPU layout can write into the same rows.
  */
+/**
+ * The edges an engine holds against the edges drawn: each drawn edge held exactly once, and
+ * nothing held that is not drawn.
+ * @param held - What the engine holds.
+ * @param drawn - What the element draws.
+ * @returns One sentence per problem.
+ */
+export declare function heldEdgeProblems(held: Iterable<Edge>, drawn: ReadonlyMap<string, Edge>): string[];
+/** The base every layout engine extends: how the element adds, places, steps and removes. */
 export declare abstract class LayoutEngine {
     static type: string;
     static maxDimensions: number;
@@ -142,7 +163,7 @@ export declare abstract class LayoutEngine {
      * -- which is what happened to the element's own two force engines. The manager rebuilds from
      * the options it was given instead, and this is now the engine's own business.
      */
-    config?: Record<string, unknown>;
+    protected config?: Record<string, unknown>;
     /**
      * NEW: Zod-based options schema for unified validation and UI metadata
      *
@@ -169,14 +190,21 @@ export declare abstract class LayoutEngine {
     /** How many rows {@link hold} covers; a row at or past it is newer than the hold, so held. */
     private holdRows;
     abstract init(): Promise<void>;
-    abstract addNode(n: Node): void;
-    abstract addEdge(e: Edge): void;
+    protected abstract addNode(n: Node): void;
+    protected abstract addEdge(e: Edge): void;
     abstract getNodePosition(n: Node): Position;
-    abstract setNodePosition(n: Node, p: Position): void;
+    /**
+     * Place one node, as a drag or a restore does. Protected: the element reaches it through
+     * {@link layoutEngineInternals}, from the hooks that apply the `positions` and `pins` slices,
+     * so a caller cannot place a node without a step.
+     */
+    protected abstract setNodePosition(n: Node, p: Position): void;
     abstract getEdgePosition(e: Edge): EdgePosition;
     abstract step(): void;
-    abstract pin(n: Node): void;
-    abstract unpin(n: Node): void;
+    /** Hold a node where it is; protected for the reason {@link LayoutEngine.setNodePosition} is. */
+    protected abstract pin(n: Node): void;
+    /** Release a held node; protected for the reason {@link LayoutEngine.setNodePosition} is. */
+    protected abstract unpin(n: Node): void;
     abstract get nodes(): Iterable<Node>;
     abstract get edges(): Iterable<Edge>;
     abstract get isSettled(): boolean;
@@ -184,12 +212,12 @@ export declare abstract class LayoutEngine {
      * Add multiple nodes to the layout engine
      * @param nodes - Array of nodes to add
      */
-    addNodes(nodes: Node[]): void;
+    protected addNodes(nodes: Node[]): void;
     /**
      * Add multiple edges to the layout engine
      * @param edges - Array of edges to add
      */
-    addEdges(edges: Edge[]): void;
+    protected addEdges(edges: Edge[]): void;
     /**
      * Take a node out of the layout, before the element disposes the mesh that drew it.
      *
@@ -200,12 +228,12 @@ export declare abstract class LayoutEngine {
      * and everything that node references -- for as long as the engine lives.
      * @param _n - the node leaving the graph
      */
-    removeNode(_n: Node): void;
+    protected removeNode(_n: Node): void;
     /**
      * The edge half of {@link LayoutEngine.removeNode}, with the same default and the same reason.
      * @param _e - the edge leaving the graph
      */
-    removeEdge(_e: Edge): void;
+    protected removeEdge(_e: Edge): void;
     /**
      * Settle nodes that reached the graph after this layout was already running.
      *
@@ -222,18 +250,39 @@ export declare abstract class LayoutEngine {
      * Release whatever this engine holds. The element calls it when the reader switches layouts
      * and when the graph is torn down, and never uses the engine again afterwards.
      *
-     * Declared with a do-nothing default for the same reason as {@link LayoutEngine.removeNode}:
+     * Declared with a do-nothing default for the same reason as `removeNode`:
      * it was duck-typed, undeclared and unimplemented by every engine here.
      */
     dispose(): void;
     /**
-     * The array this engine publishes node coordinates into.
+     * Strict state: what is wrong with this engine's hold on the drawn edges, checked after every
+     * derivation pass. An engine that keeps a copy of the edges must hold every drawn edge once
+     * and nothing else, or a redraw asks it for a position it cannot give. Reads nothing lazily:
+     * the check must not change what it checks.
+     * @param drawn - The edges the element draws.
+     * @returns One sentence per problem; empty when there is none.
+     */
+    protected edgeProblems(drawn: ReadonlyMap<string, Edge>): string[];
+    /**
+     * The coordinates this engine publishes, read-only.
+     *
+     * Read-only because the array is the element's: a write here would move or pin a node with no
+     * undo step. The engine writes through `writeNodePosition`; a consumer
+     * places and pins nodes through `session.positions`.
+     * @returns the coordinates in use, read-only
+     */
+    get nodePositions(): ReadonlyElementPositions;
+    /** The read-only view {@link LayoutEngine.nodePositions} hands out; reads the array in use now. */
+    private readonly readonlyPositionArray;
+    /**
+     * The array this engine publishes node coordinates into, writable.
      *
      * Allocated on demand, so reading it is enough to make an engine that has never been handed an
-     * element's array produce one of its own.
+     * element's array produce one of its own. The element reaches it through
+     * {@link layoutEngineInternals}.
      * @returns the position array in use
      */
-    get nodePositions(): ElementPositions;
+    private get writablePositions();
     /**
      * Hand this engine the array it must publish into, and stop it adopting any other.
      *
@@ -242,7 +291,7 @@ export declare abstract class LayoutEngine {
      * one place and a re-freeze loses none of them.
      * @param positions - the element-owned array
      */
-    attachPositions(positions: ElementPositions): void;
+    protected attachPositions(positions: ElementPositions): void;
     /**
      * Hold the nodes a scoped layout may not move, or release them all with null.
      *
@@ -277,6 +326,16 @@ export declare abstract class LayoutEngine {
      * an engine that already writes straight into the array overrides it to do nothing.
      */
     publishPositions(): void;
+    /**
+     * Take the coordinates in the position array as this engine's own, and stay at rest.
+     *
+     * Undo and redo write where the nodes were into the array and then call this, so the next
+     * drag, add or `setRunning(true)` starts from the restored arrangement instead of the one the
+     * engine was holding. The default hands every placed node back through
+     * `setNodePosition`, which is right for any engine that keeps coordinates of
+     * its own; an engine that can adopt the array in one pass overrides it.
+     */
+    loadArrangement(): void;
     /**
      * Read a node's published coordinates into an object the CALLER owns.
      *
@@ -335,51 +394,6 @@ export declare abstract class LayoutEngine {
      * @returns true when the row was written
      */
     protected writeNodePosition(n: Node, x: number, y: number, z: number, intent?: "layout" | "placement"): boolean;
-    /**
-     * The weight of every ordered endpoint pair this batch of edges covers, or null when the
-     * graph's weights carry no information.
-     *
-     * WHY A PAIR AND NOT AN EDGE. `@graphty/layout`'s one weight channel is
-     * `graph.getEdgeData(source, target, attr)`, which is asked by endpoint pair, and both layout
-     * functions that read it write the answer into a matrix cell -- `A[i][j]` in ForceAtlas2,
-     * `distances[s][t]` in Kamada-Kawai. There is no cell for a second edge between the same two
-     * nodes, so parallel edges are SUMMED into one number rather than left to last-writer-wins,
-     * where the order the file happened to list them in would decide the arrangement. Summing is
-     * also what the element does when it simplifies a multigraph for an algorithm, so a graph's
-     * weights mean the same thing to a layout and to a metric.
-     *
-     * READ ONCE PER LAYOUT COMPUTATION, not per frame and not per edge: the weights come from the
-     * current snapshot's edge list, indexed by the same logical edge index `Edge.index` holds.
-     *
-     * NULL MEANS "DO NOT ATTACH A CALLBACK". graph-format stores an all-ones graph with no weight
-     * column at all, and a graph whose every weight is 1 carries no information a layout could
-     * arrange by -- so the caller leaves `getEdgeData` off the graph object entirely and the
-     * arrangement is bit-identical to the one the same seed produced before weights existed.
-     *
-     * THIS IS A SLIGHTLY NARROWER QUESTION THAN `statistics().weighted`, deliberately. The status
-     * chip asks whether the SNAPSHOT's weight column carries anything but ones; this asks it of
-     * the edges this engine is actually about to arrange. They answer differently only when the
-     * engine holds a strict subset of the graph's edges whose weights are all 1, and there the
-     * narrower answer is the correct one: a layout cannot be moved by a weight on an edge it is
-     * not laying out. A consumer who sees "weighted" on the status bar and an unmoved arrangement
-     * is looking at that case.
-     * @param edges - the edges this engine is about to lay out
-     * @returns pair key (see {@link pairWeightKey}) to summed weight, or null
-     */
-    protected pairWeights(edges: readonly Edge[]): Map<string, number> | null;
-    /**
-     * Say once, per layout computation, how many pairs were clamped off zero.
-     *
-     * ONCE PER RUN AND NOT PER EDGE: a graph whose weights are all zero would otherwise produce
-     * one line per edge, which buries every other message in the run it happened during. It is
-     * reported at all because a clamp changes the picture -- a zero-weight edge is drawn as the
-     * weakest connection the solver can express rather than as no connection -- and the record
-     * that carried the zero is the reader's, not the element's, so they are the one who can fix
-     * it.
-     * @param layout - the layout name, for the message
-     * @param weights - the pair weights about to be handed to the layout function
-     */
-    protected reportClampedWeights(layout: string, weights: ReadonlyMap<string, number>): void;
     /**
      * The array to use for this node: the one its own graph owns, unless a host attached one.
      *
@@ -411,12 +425,13 @@ export declare abstract class LayoutEngine {
      * are authored centrally in the layout catalogue where several engines may sit behind one
      * public name.
      * @param cls - The layout engine class.
+     * @param options - How to register it; `strict` refuses a different layout under a taken id.
      * @returns The same class, so a declaration can register itself in one expression.
      * @throws A `GraphtyError` with `E_BAD_COMMAND` when the class declares no `static type`, no
      * `static descriptor`, or a descriptor whose `id` disagrees with its `static type`; or with
      * `E_DUPLICATE_PLUGIN` when the name or the descriptor id is one the element itself ships.
      */
-    static register<T extends LayoutEngineClass>(cls: T): T;
+    static register<T extends LayoutEngineClass>(cls: T, options?: RegisterOptions): T;
     /**
      * Get a layout engine instance by type
      * @param type - The layout engine type identifier
@@ -464,15 +479,41 @@ export declare const SimpleLayoutConfig: z.ZodObject<{
 }, z.core.$loose>;
 export type SimpleLayoutConfigType = z.infer<typeof SimpleLayoutConfig>;
 export type SimpleLayoutOpts = Partial<SimpleLayoutConfigType>;
+/** The freeze a static engine is told about: the snapshot it replaced, the new one, and the renumbering. */
+interface SnapshotReplacement {
+    readonly previous: GraphSnapshot | null;
+    readonly next: GraphSnapshot;
+    readonly report: {
+        readonly nodeRemap: Uint32Array | null;
+    };
+}
 /**
- * Base class for simple static layout engines that compute positions synchronously
+ * Base class for static layout engines: an arrangement computed in one pass whenever the graph
+ * changes, rather than stepped frame by frame.
+ *
+ * TWO WAYS TO WRITE ONE. The element's own engines read the protected `graph` -- the
+ * element's undirected graph snapshot, whose row `i` is the node whose `index` is `i` -- and assign
+ * an index-based `@graphty/layout` result to the protected `result` in `doLayout`. An
+ * engine written before that existed fills the id-keyed {@link SimpleLayoutEngine.positions} record
+ * instead, and still works. Either way the base class scales the answer into the element's shared
+ * position array, never over a pinned row.
+ *
+ * AFTER AN ADD, EXISTING NODES STAY PUT. When the graph only grew -- a node added, with or without
+ * edges to the ones already drawn -- and no file is still loading, a re-run of an engine that
+ * reads `graph` places only the new nodes and leaves every existing one where it was. The
+ * existing coordinates are also offered to the layout as its start (`startPositions`), which is
+ * what lets Kamada-Kawai and ARF place a newcomer among its neighbours rather than from scratch.
  */
 export declare abstract class SimpleLayoutEngine extends LayoutEngine {
+    #private;
     static type: string;
     protected _nodes: Node[];
     protected _edges: Edge[];
     stale: boolean;
+    /** What an engine that does not read the protected `graph` computed, keyed by node id, in layout units. */
     positions: Record<string | number, number[]>;
+    /** What an engine that reads the protected `graph` computed: row `i` is row `i` of that graph. */
+    protected result: LayoutResult | null;
     scalingFactor: number;
     /**
      * Create a simple layout engine
@@ -501,14 +542,66 @@ export declare abstract class SimpleLayoutEngine extends LayoutEngine {
      * @param e - The edge to add
      */
     addEdge(e: Edge): void;
+    /**
+     * The graph this run arranges: the element's undirected snapshot, or, for an engine driven
+     * without an element, a graph built from the nodes and edges it was handed, in that order.
+     *
+     * Read it in `doLayout`. Reading it may freeze the element's graph, which is how a node added
+     * since the last run gets a row.
+     * @returns the undirected graph
+     */
+    protected get graph(): GraphSnapshot;
+    /**
+     * The coordinates to start this run from, in layout units, `dim` values per row of
+     * the protected `graph`: the element's current coordinates when the run follows an
+     * add, otherwise null. An unplaced row is NaN.
+     * @param dim - components per row
+     * @returns the start rows, or null
+     */
+    protected startPositions(dim: 2 | 3): F32 | null;
+    /**
+     * The row of a node named in an option, in the protected `graph`.
+     *
+     * A key of an options record is always a string, so a string that misses is tried again as the
+     * number it spells: `{ 1: [...] }` names the node whose id is the number 1.
+     * @param id - the node id, or a record key naming one
+     * @returns the row, or `INVALID_INDEX` when the graph has no such node
+     */
+    protected rowOfId(id: string | number): number;
+    /**
+     * {@link SimpleLayoutEngine.rowOfId} for an option that must name a node.
+     * @param id - the node id
+     * @param what - what the option names, for the message
+     * @returns the row
+     * @throws when the graph has no such node
+     */
+    protected requireRow(id: string | number, what: string): number;
+    /**
+     * Rows of an option that gives coordinates by node id, `dim` values per row of
+     * the protected `graph`; a node the record does not give is NaN.
+     * @param record - the coordinates by node id, in layout units, or null
+     * @param dim - components per row
+     * @returns the rows, or null for no record
+     */
+    protected rowsOfRecord(record: Record<string | number, number[]> | null, dim: 2 | 3): F32 | null;
+    /**
+     * Hear that the element's graph was frozen again.
+     *
+     * The layout is re-run at the next read. When the freeze only added to the graph this engine
+     * last arranged, and the data is not still loading, the re-run keeps every existing node where
+     * it is (see the class comment). A load is excluded because its chunks are one graph arriving,
+     * not a reader adding to a finished one: a circle whose first chunk was held would be drawn as
+     * two overlapping circles.
+     * @param change - the freeze
+     * @param loading - whether a load is still streaming records in
+     */
+    reload(change: SnapshotReplacement, loading: boolean): void;
     /**
      * Get the position of a node, computing layout if stale
      *
-     * The coordinates come from the shared position array, which `SimpleLayoutEngine.refresh`
-     * fills from `positions` as soon as the layout is recomputed. They are the same numbers the
-     * record holds, rounded to the f32 the array stores -- so an arrangement never moves, but a
-     * coordinate may differ in its last digit or two from the double the layout function returned.
-     * A node with no row falls back to the record, which is every node in an engine driven by hand.
+     * The coordinates come from the shared position array, rounded to the f32 it stores. A node
+     * with no row there falls back to what the engine computed, which is every node in an engine
+     * driven by hand.
      * @param n - The node to get position for
      * @returns The node's position coordinates
      */
@@ -516,16 +609,14 @@ export declare abstract class SimpleLayoutEngine extends LayoutEngine {
     /**
      * Record where the reader has just put a node.
      *
-     * A static layout recomputes every coordinate from scratch, so it has no per-node state a
-     * placement could live in -- which is why this used to do nothing at all, and why a drag
-     * under any of the fourteen static arrangements was discarded by the next `refresh()`. The
-     * placement is written into the SHARED array instead, with `"placement"` intent so that it
-     * lands even on a pinned row, and into the computed record so that a read which falls back to
-     * the record (a node with no row of its own) answers the same.
+     * A static layout has no per-node state a placement could live in, so the placement is
+     * written into the SHARED array, with `"placement"` intent so that it lands even on a pinned
+     * row, and into what the engine computed, so that the next publish of the same answer does
+     * not put the node back.
      * @param n - the node that moved
      * @param p - where it moved to
      */
-    setNodePosition(n: Node, p: Position): void;
+    protected setNodePosition(n: Node, p: Position): void;
     /**
      * Get the position of an edge based on its endpoints
      * @param e - The edge to get position for
@@ -547,12 +638,8 @@ export declare abstract class SimpleLayoutEngine extends LayoutEngine {
      *
      * WITHOUT THIS the engine holds the removed node -- and through it the node's Babylon mesh,
      * its data record and its endpoints -- for as long as the engine lives, and the frame loop
-     * keeps walking it, so a node the reader deleted still draws at wherever it last was.
-     *
-     * The computed record is left alone and the layout is marked stale instead. Every layout
-     * function here returns a WHOLE new record, which `doLayout` assigns over the old one, and
-     * `refresh()` runs before any read -- so the removed node's entry is gone by the time anything
-     * could read it, without this method having to reach into a keyed object by a computed name.
+     * keeps walking it, so a node the reader deleted still draws at wherever it last was. The
+     * layout is marked stale, so the next read recomputes it without the node.
      * @param n - the node leaving the graph
      */
     removeNode(n: Node): void;
@@ -566,16 +653,21 @@ export declare abstract class SimpleLayoutEngine extends LayoutEngine {
      *
      * A static layout has nothing of its own to hold still -- it recomputes every position from
      * scratch -- so the pin is kept by the element's position array instead, and
-     * `writeNodePosition` refuses to move a pinned row. That is what makes a
-     * pin mean something under all fourteen of these engines, none of which could hold one.
+     * `writeNodePosition` refuses to move a pinned row.
      */
-    pin(): void;
+    protected pin(): void;
     /**
      * Unpin a node
      *
      * The element's position array holds the pin; see {@link SimpleLayoutEngine.pin}.
      */
-    unpin(): void;
+    protected unpin(): void;
+    /**
+     * Keep the arrangement in the array instead of recomputing one: a static layout that was
+     * marked stale by the graph change an undo made would otherwise lay the graph out afresh at
+     * the next read and write over what was restored.
+     */
+    loadArrangement(): void;
     /**
      * Get all nodes in the layout
      * @returns Iterable of nodes
@@ -587,6 +679,7 @@ export declare abstract class SimpleLayoutEngine extends LayoutEngine {
      */
     get edges(): Iterable<Edge>;
     readonly isSettled = true;
+    /** Compute the layout: assign the protected `result` from `graph`, or fill `positions`. */
     abstract doLayout(): void;
     /**
      * Recompute the layout when it is stale, and publish what it produced.
@@ -597,23 +690,28 @@ export declare abstract class SimpleLayoutEngine extends LayoutEngine {
      */
     protected refresh(): void;
     /**
-     * Write the computed record into the shared array, scaled to scene units.
+     * Write the computed answer into the shared array, scaled to scene units.
      *
-     * A node the layout function returned nothing for is LEFT UNPLACED rather than published at
-     * the origin: the two are indistinguishable once stored, and the origin is a place a reader
-     * would draw at.
+     * A node the layout left unplaced (a NaN row, or no entry in `positions`) is LEFT UNPLACED
+     * rather than published at the origin: the two are indistinguishable once stored, and the
+     * origin is a place a reader would draw at.
      */
-    private publishRecord;
+    private publishComputed;
     /**
-     * A node's published row, or the computed record when it has no row of its own.
+     * A node's published row, or what the engine computed when it has no row of its own.
      *
      * The fallback is not a rare path: an engine driven directly -- by a test, or by a host that
      * keeps no graph -- has nodes whose index is `INVALID_INDEX`, and none of them is ever
      * published. Both branches produce the same arrangement; only the rounding differs.
      * @param n - the node, when the caller has one
-     * @param id - the node's id, which is how the computed record is keyed
-     * @returns a fresh coordinate triple
+     * @returns a fresh coordinate triple; the origin for a node nothing placed
      */
     private publishedOr;
 }
+/**
+ * A dimension option as the index-based layouts take it.
+ * @param dim - the option, a number from a config
+ * @returns 3 for 3, otherwise 2
+ */
+export declare function layoutDim(dim: number): 2 | 3;
 export {};

package/dist/src/layout/NGraphLayoutEngine.d.ts

@@ -80,7 +80,7 @@ export declare class NGraphEngine extends LayoutEngine {
      * @param n - The node to set position for
      * @param newPos - The new position coordinates
      */
-    setNodePosition(n: Node, newPos: Position): void;
+    protected setNodePosition(n: Node, newPos: Position): void;
     /**
      * Get the position of an edge based on its endpoint positions
      * @param e - The edge to get position for
@@ -101,12 +101,12 @@ export declare class NGraphEngine extends LayoutEngine {
      * Pin a node to its current position
      * @param n - The node to pin
      */
-    pin(n: Node): void;
+    protected pin(n: Node): void;
     /**
      * Unpin a node to allow it to move freely
      * @param n - The node to unpin
      */
-    unpin(n: Node): void;
+    protected unpin(n: Node): void;
     /**
      * Holds the nodes a scoped layout may not move, as pinned bodies. A node that is no longer
      * held is released unless the reader pinned it.
@@ -128,6 +128,13 @@ export declare class NGraphEngine extends LayoutEngine {
      * @param e - the edge leaving the graph
      */
     removeEdge(e: Edge): void;
+    /**
+     * Strict state: {@link LayoutEngine.edgeProblems}, and each edge its own link, which ngraph
+     * still holds.
+     * @param drawn - The edges the element draws.
+     * @returns One sentence per problem.
+     */
+    protected edgeProblems(drawn: ReadonlyMap<string, Edge>): string[];
     private _getMappedNode;
     private _getMappedEdge;
 }

package/dist/src/layout/SimulationLayoutEngine.d.ts

@@ -347,6 +347,11 @@ export declare class SimulationLayoutEngine extends LayoutEngine {
      * ones have it, and a third party's may not -- so it is feature-tested rather than assumed.
      */
     reheat(): void;
+    /**
+     * Takes the element's array as the simulation's coordinates, through a reload of the graph it
+     * holds, and drops what batches already in flight read back.
+     */
+    loadArrangement(): void;
     /**
      * Holds a node still for the duration of a drag, without pinning it.
      *
@@ -371,12 +376,12 @@ export declare class SimulationLayoutEngine extends LayoutEngine {
      * Fixes a pinned node in the simulation. The store already holds the pin.
      * @param n - The node that was pinned.
      */
-    pin(n: Node): void;
+    protected pin(n: Node): void;
     /**
      * Releases a node the simulation was holding fixed.
      * @param n - The node that was unpinned.
      */
-    unpin(n: Node): void;
+    protected unpin(n: Node): void;
     /**
      * Holds the rows a scoped layout may not move, in the simulation's own fixed-node mask too.
      * @param mask - One bit per row to hold, or null to hold nothing.
@@ -388,7 +393,7 @@ export declare class SimulationLayoutEngine extends LayoutEngine {
      * @param n - The node that moved.
      * @param p - Where it moved to.
      */
-    setNodePosition(n: Node, p: Position): void;
+    protected setNodePosition(n: Node, p: Position): void;
     /**
      * Reads a node's current coordinates, in scene units, out of the element's own position array.
      * @param n - The node to read.

package/dist/src/managers/AlgorithmManager.d.ts

@@ -1,5 +1,7 @@
 import type { BuiltInAlgorithmDescriptor } from "../catalog/algorithms";
 import type { Graph } from "../Graph";
+import { type AlgoLegacyCommand } from "../session/commands/algo";
+import type { UndoableContext } from "../session/project/Dispatcher";
 import type { RunExecutionContext, RunOutcome } from "../session/runs";
 import type { AlgorithmSpecificOptions } from "../utils/queue-migration";
 import type { EventManager } from "./EventManager";
@@ -51,14 +53,12 @@ export declare class AlgorithmManager implements Manager {
      */
     execute(context: RunExecutionContext, descriptor?: BuiltInAlgorithmDescriptor): Promise<RunOutcome>;
     /**
-     * Run algorithms specified in the template configuration
-     * Called during initialization if runAlgorithmsOnLoad is true
+     * Run algorithms specified in the template configuration, as one undoable step.
      * @param algorithms - Array of algorithm names in "namespace:type" format
      */
     runAlgorithmsFromTemplate(algorithms: string[]): Promise<void>;
     /**
-     * Run a specific algorithm by its 1.10 registry address, publishing the result through side
-     * effects and returning nothing.
+     * Run a specific algorithm by its 1.10 registry address, as one undoable step.
      *
      * This is the path a PLUGIN algorithm takes. A plugin registers itself under a
      * `namespace:type` and publishes no catalogue descriptor, so it cannot be started by key and
@@ -66,12 +66,31 @@ export declare class AlgorithmManager implements Manager {
      * to agree with. Everything this package ships goes through {@link AlgorithmManager.execute}
      * instead, reached from `graph.run` and `session.runs.start`.
      *
-     * It goes when plugin algorithms publish descriptors of their own.
+     * It dispatches `algo.legacy`, which takes its turn on the queue, constructs the plugin with a
+     * facade of the graph and runs it: what it writes to node and edge records and
+     * `graphResults`, and every door it calls on the graph, are one step.
      * @param namespace - Algorithm namespace (e.g., "graphty")
      * @param type - Algorithm type (e.g., "dijkstra")
      * @param algorithmOptions - Optional algorithm-specific options (source, target, etc.)
      */
     runAlgorithm(namespace: string, type: string, algorithmOptions?: AlgorithmSpecificOptions): Promise<void>;
+    /**
+     * Carry out one `algo.legacy` the dispatcher has started: construct the plugin with a
+     * group-tagged facade of the graph, run it with the element's node and edge records read
+     * copy-on-write, and write what it wrote into the command's draft. Registered by the graph
+     * as its session's legacy service; nothing else calls it.
+     * @param command - The command.
+     * @param ctx - The command's context.
+     * @returns Settles once everything the plugin wrote is in the command's draft.
+     * @internal
+     */
+    runLegacy(command: AlgoLegacyCommand, ctx: UndoableContext): Promise<void>;
+    /**
+     * Dispatch one `algo.legacy`, announcing a failure on the graph's error channel.
+     * @param command - The command.
+     * @param dispatch - Where it goes.
+     */
+    private dispatchLegacy;
     /**
      * Check if an algorithm exists
      * @param namespace - Algorithm namespace