@graphty/graphty-element 2.0.1 → 2.2.0

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

@@ -1,56 +1,39 @@
-import { z } from "zod/v4";
+/**
+ * @file The ForceAtlas2 layout: the Gephi arrangement, computed on the CPU or on an accelerator.
+ *
+ * It used to be a one-shot pass -- run `forceatlas2Layout` over a node and edge list, publish the
+ * answer, stop -- which is why the catalogue called it a batch layout. It is now a steppable
+ * simulation from `@graphty/layout`, so it keeps running until the arrangement settles and reheats
+ * on a drag or a pin, and the element decides at every load whether the simulation is the CPU's or
+ * the accelerator's.
+ */
+import type { SimulationType } from "@graphty/layout";
 import { type OptionsSchema } from "../config";
-import { SimpleLayoutEngine } from "./LayoutEngine";
-declare const ForceAtlas2LayoutConfig: z.ZodObject<{
-    pos: z.ZodDefault<z.ZodUnion<[z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodNumber>>, z.ZodNull]>>;
-    maxIter: z.ZodDefault<z.ZodNumber>;
-    jitterTolerance: z.ZodDefault<z.ZodNumber>;
-    scalingRatio: z.ZodDefault<z.ZodNumber>;
-    gravity: z.ZodDefault<z.ZodNumber>;
-    distributedAction: z.ZodDefault<z.ZodBoolean>;
-    strongGravity: z.ZodDefault<z.ZodBoolean>;
-    nodeMass: z.ZodDefault<z.ZodUnion<[z.ZodRecord<z.ZodNumber, z.ZodNumber>, z.ZodNull]>>;
-    nodeSize: z.ZodDefault<z.ZodUnion<[z.ZodRecord<z.ZodNumber, z.ZodNumber>, z.ZodNull]>>;
-    weighted: z.ZodDefault<z.ZodBoolean>;
-    dissuadeHubs: z.ZodDefault<z.ZodBoolean>;
-    linlog: z.ZodDefault<z.ZodBoolean>;
-    seed: z.ZodDefault<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
-    dim: z.ZodDefault<z.ZodNumber>;
-    scalingFactor: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strict>;
-type ForceAtlas2LayoutConfigType = z.infer<typeof ForceAtlas2LayoutConfig>;
-type ForceAtlas2LayoutOpts = Partial<ForceAtlas2LayoutConfigType>;
+import { SimulationLayoutEngine } from "./SimulationLayoutEngine";
 /**
- * ForceAtlas2 layout engine for graph visualization with scaling and gravity options
+ * The ForceAtlas2 engine, as the element declares it.
+ *
+ * Every member is a static the element reads: `LayoutManager` builds the bridge itself, with the
+ * graph's acceleration controller, so this class never runs a layout of its own. It declares no
+ * `static descriptor` because its arrangement is authored in the layout catalogue, where it sits
+ * under `force`.
  */
-export declare class ForceAtlas2Layout extends SimpleLayoutEngine {
+export declare class ForceAtlas2Layout extends SimulationLayoutEngine {
     static type: string;
+    static simulationType: SimulationType;
     static maxDimensions: number;
-    static honoursWeights: boolean;
-    static zodOptionsSchema: OptionsSchema;
-    scalingFactor: number;
-    config: ForceAtlas2LayoutConfigType;
     /**
-     * Create a ForceAtlas2 layout engine
-     * @param opts - Configuration options for the ForceAtlas2 algorithm
+     * A WEIGHT IS AN ATTRACTION STRENGTH HERE, and is passed through as it is stored: a heavier
+     * edge pulls its two nodes closer, which is what a weight means everywhere else in the
+     * element. Kamada-Kawai reads the very same number as a distance and therefore inverts it; the
+     * two engines disagree about the arithmetic so that they agree about the meaning.
      */
-    constructor(opts: ForceAtlas2LayoutOpts);
+    static honoursWeights: boolean;
+    static zodOptionsSchema: OptionsSchema;
     /**
-     * Get dimension-specific options for ForceAtlas2 layout
-     * @param dimension - The desired dimension (2 or 3)
-     * @returns Options object with dim parameter
+     * Get dimension-specific options for ForceAtlas2 layout.
+     * @param dimension - The desired dimension (2 or 3).
+     * @returns Options object with dim parameter.
      */
     static getOptionsForDimension(dimension: 2 | 3): object;
-    /**
-     * Compute node positions using the ForceAtlas2 algorithm
-     *
-     * A WEIGHT IS PASSED THROUGH AS IT IS STORED. ForceAtlas2 reads a weight as an attraction
-     * STRENGTH -- it becomes the adjacency matrix entry the attraction force is scaled by -- which
-     * is already what a weight means everywhere else in the element, so a heavier edge pulls its
-     * two nodes closer and nothing has to be inverted. Kamada-Kawai reads the very same number as
-     * a distance and therefore does invert it; the two engines disagree about the arithmetic so
-     * that they agree about the meaning.
-     */
-    doLayout(): void;
 }
-export {};

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

@@ -48,15 +48,15 @@ export interface LayoutEngineStatics {
     /**
      * Whether this engine arranges a graph differently when its edges carry weights.
      *
-     * Optional, and false for all but two of the element's own sixteen. It exists so that a
+     * Optional, and false for all but two of the element's own seventeen. It exists so that a
      * picker can tell a reader which arrangements the `weighted` option actually does something
-     * for, instead of offering it on fourteen layouts that ignore it.
+     * for, instead of offering it on fifteen layouts that ignore it.
      */
     honoursWeights?: boolean;
     /**
      * What the catalogue publishes about this layout, so a picker can offer it.
      *
-     * REQUIRED OF A THIRD PARTY'S ENGINE and absent from the element's own sixteen, whose
+     * REQUIRED OF A THIRD PARTY'S ENGINE and absent from the element's own seventeen, whose
      * arrangements are authored in `src/catalog/layouts.ts` instead. `descriptor.id` must equal
      * {@link LayoutEngineStatics.type}: one key, so nothing is named twice and `layoutIdForEngine`
      * can answer a plugin's own id.
@@ -94,7 +94,7 @@ export declare abstract class LayoutEngine {
      * Whether this engine reads edge weights. See {@link LayoutEngineStatics.honoursWeights}.
      *
      * False here because most layouts have no weight channel at all: of the element's own
-     * sixteen, only Kamada-Kawai and ForceAtlas2 can read one, and the other fourteen would be
+     * seventeen, only Kamada-Kawai and ForceAtlas2 can read one, and the other fifteen would be
      * advertising a control that changes nothing.
      */
     static honoursWeights: boolean;
@@ -162,7 +162,7 @@ export declare abstract class LayoutEngine {
      * Take a node out of the layout, before the element disposes the mesh that drew it.
      *
      * Declared here, with a default that does nothing, because it used to be duck-typed by the
-     * element's data manager and implemented by none of the sixteen engines that ship here: an
+     * element's data manager and implemented by none of the seventeen engines that ship here: an
      * author learned it existed by reading the element's source, and got no worked example. An
      * engine that keeps its own node list must override this, or it holds every removed node --
      * and everything that node references -- for as long as the engine lives.
@@ -260,7 +260,7 @@ export declare abstract class LayoutEngine {
      * freeze counts as placed, which is what makes a file's own coordinates yield to it.
      *
      * A PINNED ROW REFUSES A LAYOUT STEP. This is the whole of "a pin is meaningful under every
-     * arrangement": fourteen of the element's sixteen engines implement `pin()` as a no-op and
+     * arrangement": twelve of the element's seventeen engines implement `pin()` as a no-op and
      * `setNodePosition` as a no-op too, so before this guard a reader who dragged a node under a
      * static layout watched it snap back the next time the layout recomputed. One refusal here
      * covers every engine, including one written by a third party that has never heard of pinning,
@@ -351,7 +351,7 @@ export declare abstract class LayoutEngine {
      * offered by a picker, described in a reader's language, or found by `layoutIdForEngine`.
      *
      * A third party's class must declare a `static descriptor` whose `id` equals its
-     * `static type`. The element's own sixteen are the one exemption, because their arrangements
+     * `static type`. The element's own seventeen are the one exemption, because their arrangements
      * are authored centrally in the layout catalogue where several engines may sit behind one
      * public name.
      * @param cls - The layout engine class.

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

@@ -0,0 +1,458 @@
+/**
+ * @file The layout bridge: one `LayoutEngine` driving `@graphty/layout`'s `LayoutSimulation`,
+ * on the CPU or on whatever the element's acceleration controller has attached.
+ *
+ * WHERE THE DECISION IS TAKEN. "GPU or CPU" is asked of the controller ONCE per simulation, by
+ * `plan({ capability, nodeCount })`, before any work starts -- at the first load, at every
+ * reload (a freeze can cross the `acceleration.minNodes` threshold in either direction) and at
+ * every swap. Nothing inside a running batch may change the answer: a rejected batch is
+ * reported with its own code and stops the stepping, and only the controller's NEXT transition
+ * -- a recovery, a detach, an injection -- rebuilds the simulation, through
+ * {@link SimulationLayoutEngine.replaceSimulation}. That is the difference between capability
+ * detection, which is required, and a silent CPU fallback after a GPU failure, which is not.
+ *
+ * TWO ARRAYS, TWO UNIT SYSTEMS. The simulations are the only layouts in this element that never
+ * rescale what they compute: a ForceAtlas2 equilibrium grows with the graph, so a settled
+ * hundred-node arrangement is a few hundred units across and a settled fifty-thousand-node one is
+ * tens of thousands, while every visual size in the element -- node size, edge width, label size,
+ * arrow size -- is an absolute scene unit tuned for the plus-or-minus-100 box the one-shot engines
+ * publish into. So the simulation is given an array of ITS OWN, and `publishPositions()` maps it
+ * into the element's: the widest radius about its own centre, over the rows that publish actually
+ * writes, becomes `scalingFactor`, recomputed at every publish so a settling graph holds its
+ * apparent size instead of flying out of frame. Everything written the other way -- a drag, a pin replay, a
+ * `setNodePosition`, the seed -- arrives in scene units and is divided back out, so a dragged node
+ * lands under the pointer. The simulation's own settle rule, trace and statistics never see any of
+ * this: they are computed in its units, and its units do not move.
+ *
+ * WHAT THE SWAP PRESERVES. The bridge owns the simulation's array, so a swap keeps the arrangement
+ * by handing the new simulation the same one. Pins are the STORE's: a byte per row in the position
+ * lane, which a freeze remaps with the coordinates. The bridge packs that lane into the
+ * simulation's `NodeMask` after every load, because the simulation would otherwise keep spending
+ * force on a body the element refuses to move and its own copy of that row would wander away from
+ * where the reader put it. A drag holds the same bit temporarily and is not a pin.
+ *
+ * A FIXED ROW IS THE ONE PLACE THE ELEMENT'S ARRAY IS THE AUTHORITY rather than the simulation's,
+ * so it is not published over at all; see {@link SimulationLayoutEngine.publishPositions} for what
+ * that costs and why the repair that suggests itself is worse.
+ */
+import { type F32, type GraphSnapshot, type NodeMask } from "@graphty/graph-format";
+import { type CommonLayoutOptions, type ForceAtlas2Options, type FruchtermanReingoldOptions, type LayoutSimulation, type SimulationOptions, type SimulationType, type SpringElectricalOptions } from "@graphty/layout";
+import type { AccelerationController } from "../acceleration/AccelerationController";
+import { type AccelerationPrecision, type GraphAccelerator } from "../acceleration/types";
+import type { Edge } from "../Edge";
+import { GraphtyError } from "../errors";
+import type { DataManager } from "../managers/DataManager";
+import type { Node } from "../Node";
+import { type EdgePosition, LayoutEngine, type Position } from "./LayoutEngine";
+/**
+ * How many iterations one `step()` submits.
+ *
+ * The explicit knob decides whenever a host set one. Otherwise the count is the frame loop's own
+ * `stepMultiplier`, raised fourfold once the graph is large enough that reading a million
+ * positions back costs more than a frame: above that size the element computes more per batch and
+ * accepts a lower position refresh rate, which is the trade design 13 row P12 asks for.
+ *
+ * It is re-applied at EVERY load, because a freeze can carry a graph across the line in either
+ * direction.
+ * @param explicit - What a host asked for, or null to let the size decide.
+ * @param stepMultiplier - `behavior.layout.stepMultiplier`, the automatic rule's starting point.
+ * @param nodeCount - The graph this load is over.
+ * @returns The iteration count.
+ */
+export declare function iterationsPerStepFor(explicit: number | null, stepMultiplier: number, nodeCount: number): number;
+/**
+ * Turns a reader's `nodeMass` record into one value per dense row, and leaves every other form to
+ * the simulation.
+ *
+ * A reader may give `nodeMass` as a number per node ID, as the name of a numeric node column, or
+ * not at all. Only the FIRST is resolved here, because it is the only one an accelerator refuses:
+ * a GPU never sees a node ID. A node the record says nothing about gets one more than its degree,
+ * which is what the simulations themselves apply, so a partial record leaves the rest of the graph
+ * exactly as it would have been.
+ *
+ * Exported beside {@link iterationsPerStepFor} so both rules can be read off without a device, a
+ * renderer or a running simulation.
+ * @param spec - What the reader set, in any of its three forms.
+ * @param undirected - The graph the simulation will be loaded with.
+ * @returns The masses, or null when the simulation resolves them itself.
+ */
+export declare function resolveNodeMass(spec: unknown, undirected: GraphSnapshot): F32 | null;
+/**
+ * How a simulation's arrangement maps into the element's scene units.
+ *
+ * See {@link measureEnvelope}.
+ *
+ * Exported only because {@link measureEnvelope} returns it and TypeScript's declaration emit
+ * needs every named type in a published signature to be exported. Nothing outside this module
+ * names the type -- the test destructures the value -- so it is no entry point's surface.
+ * @internal
+ */
+export interface LayoutEnvelope {
+    /** What a simulation-unit offset from {@link LayoutEnvelope.centre} is multiplied by. */
+    readonly scale: number;
+    /** The arrangement's centre, in the simulation's own units. */
+    readonly centre: readonly [number, number, number];
+    /**
+     * How many rows the measurement actually saw.
+     *
+     * Zero is the one answer a caller must not act on: it means the arrangement has nothing in
+     * it to fit, and the scale and centre beside it are the identity rather than a measurement.
+     */
+    readonly placed: number;
+}
+/**
+ * Measures the arrangement a simulation currently holds, and says how to publish it.
+ *
+ * The centre is the mean of the placed rows and the scale is `scalingFactor` divided by the
+ * furthest row's distance from that centre, so a published arrangement is exactly
+ * `scalingFactor` units from its centre at its widest whatever the simulation's own equilibrium
+ * turned out to be. A row that is not finite -- the element's "not laid out yet" -- counts for
+ * neither, and an arrangement that measures as a point (see {@link POINT_RADIUS}) publishes at
+ * its own size rather than being divided by nothing.
+ *
+ * A HELD ROW COUNTS FOR NEITHER EITHER, and that is what `held` is for. The publish does not
+ * write a row a pin or a drag is holding -- its scene coordinate is the reader's -- so measuring
+ * one would fit every OTHER row inside a radius set by a row that is not drawn there: a node
+ * dragged past the envelope would shrink the whole graph under the pointer. The caller decides
+ * which rows those are, because "held" is the element's business rather than this rule's.
+ *
+ * Exported beside {@link iterationsPerStepFor} and {@link resolveNodeMass} so the rule can be read
+ * off without a device, a renderer or a running simulation.
+ * @param positions - A stride-3 array in the simulation's own units, at least `3 * nodeCount` long.
+ * @param nodeCount - How many rows of it to measure.
+ * @param scalingFactor - The scene-unit radius the arrangement is to be published at.
+ * @param held - Answers true for a row the caller will not publish, or null to measure them all.
+ * @returns The centre to publish about, the multiplier to publish with, and how many rows were
+ * measured.
+ */
+export declare function measureEnvelope(positions: ArrayLike<number>, nodeCount: number, scalingFactor: number, held?: ((row: number) => boolean) | null): LayoutEnvelope;
+/**
+ * The resolved options a bridge runs on: the simulation's own knobs, plus the two the frame loop
+ * needs.
+ *
+ * `model` carries whatever the chosen simulation type accepts and WINS over the common members
+ * beside it, so one option is never spelled in two places with two answers.
+ */
+export interface SimulationEngineOptions extends CommonLayoutOptions, Omit<SimulationOptions, "iterationsPerStep"> {
+    /** The type's own options, already mapped from what the consumer asked for. */
+    readonly model: ForceAtlas2Options | FruchtermanReingoldOptions | SpringElectricalOptions;
+    /**
+     * The radius, in scene units, the published arrangement is fitted to.
+     *
+     * The element's own envelope, not the simulation's: see the file header. It is every size
+     * control the layout publishes rolled into one number -- ForceAtlas2 and Spring publish
+     * "Scaling Factor", Spring and spring-electrical publish "Scale" -- because the refit fits
+     * the arrangement to exactly this radius, so a multiplier left out of it changes nothing a
+     * reader can see. `LayoutManager` is what rolls them up.
+     */
+    readonly scalingFactor: number;
+    /** Iterations each `step()` submits, or null for the automatic rule re-applied at every load. */
+    readonly iterationsPerStep: number | null;
+    /** `behavior.layout.stepMultiplier`, which the automatic rule starts from. */
+    readonly stepMultiplier: number;
+}
+/**
+ * Everything a bridge is built with: ONE constructor argument, because `LayoutEngine.register`
+ * accepts only a class whose constructor takes one object and `LayoutEngine.get` calls it with
+ * one.
+ */
+export interface SimulationEngineInit {
+    /** Which simulation to drive. */
+    readonly type: SimulationType;
+    /**
+     * The registered layout name this bridge is standing in for.
+     *
+     * Every other engine answers `type` from its class's `static type`, which cannot work here:
+     * `LayoutManager` builds THIS class for each of the layouts that declare a
+     * `static simulationType`, so the class is the same one for all of them and its own static
+     * would name none of them.
+     */
+    readonly layoutType: string;
+    /** The resolved options. */
+    readonly options: SimulationEngineOptions;
+    /** The controller that decides where each simulation runs and announces every transition. */
+    readonly controller: AccelerationController;
+    /** Where a failure goes: the element's error channel, with `source: "layout"`. */
+    readonly report: (error: GraphtyError) => void;
+    /** The data manager the snapshot, its undirected copy and the position array come from. */
+    readonly dataManager: DataManager;
+}
+/**
+ * A `LayoutEngine` that drives one `LayoutSimulation` from `@graphty/layout`.
+ *
+ * It is registered under no name by itself: `LayoutManager` constructs it for the layout types
+ * that declare a `static simulationType`, which is how it receives the controller a registered
+ * class could not be handed.
+ */
+export declare class SimulationLayoutEngine extends LayoutEngine {
+    #private;
+    /** Which simulation this bridge drives. */
+    readonly simulationType: SimulationType;
+    /** The accelerator member this simulation needs, asked of the controller before every build. */
+    readonly capability: string;
+    /**
+     * Builds a bridge. Nothing is planned and no simulation exists until {@link init} loads one.
+     *
+     * The parameter is declared as a bare `object` because `LayoutEngine.register` files a class
+     * whose constructor takes the options a consumer passed to `setLayout`, and a bridge takes
+     * more than that. A caller that means to build one declares its argument as a
+     * {@link SimulationEngineInit}, which is what `LayoutManager` does; a caller that arrived
+     * through `LayoutEngine.get` is refused on the next line.
+     * @param init - A {@link SimulationEngineInit}: the type, the resolved options, the
+     * controller, the error channel and the data.
+     * @throws A `GraphtyError` with `E_INTERNAL` when no controller was passed.
+     */
+    constructor(init: object);
+    /**
+     * The registered layout name, which every other engine reads off its class's `static type`.
+     *
+     * Without this the manager's `layoutType`, `getStats().layoutType` and the details of every
+     * error this bridge reports would all be undefined, and a 2D/3D switch would ask the element
+     * to set a layout called "undefined".
+     * @returns The name the consumer set.
+     */
+    get type(): string;
+    /**
+     * The running simulation, or null before the first load and while the bridge is stopped.
+     *
+     * Exposed so a caller that has to wait for the device -- a screenshot after a pause -- can
+     * reach an accelerated simulation's own `flush()`.
+     * @returns The simulation.
+     */
+    get simulation(): LayoutSimulation | null;
+    /**
+     * Whether the running simulation is the accelerator's rather than the CPU's.
+     * @returns True when the accelerator built it.
+     */
+    get isAccelerated(): boolean;
+    /**
+     * The arithmetic the running simulation computes in, for a caller that labels its results.
+     * @returns The precision, which is the CPU's whenever the CPU is running the layout.
+     */
+    get precision(): AccelerationPrecision;
+    /**
+     * How many iterations this bridge has submitted since the simulation was built. Submitted,
+     * not retired: an accelerated batch is counted when it goes out, not when it lands.
+     * @returns The count.
+     */
+    get iterationsDone(): number;
+    /**
+     * The node masses the running simulation was handed, when the element resolved them itself.
+     *
+     * A reader may give `nodeMass` as a number per node ID, as the name of a numeric node column,
+     * or not at all. Only the FIRST of those three is resolved here, into one value per dense row,
+     * because it is the only one an accelerator refuses: a GPU never sees a node ID. The other two
+     * are handed to the simulation as they stand and resolved by it at every load, on either path,
+     * which is also what keeps them right when a freeze renumbers the graph.
+     * @returns The masses, or null when the simulation resolves them itself.
+     */
+    get resolvedNodeMass(): F32 | null;
+    /**
+     * The fixed-node mask the simulation is running with, packed from the store's pin lane.
+     * @returns The mask, or an empty one before the first load.
+     */
+    get pinnedMask(): NodeMask;
+    /**
+     * Whether a different accelerator is attached now than when the simulation was built.
+     *
+     * What `LayoutManager` asks on every controller transition before it swaps: `null` is nothing
+     * attached, so a detach, an injection, a device loss and a recovery all answer true, while a
+     * transition that leaves the same accelerator attached answers false -- including for a
+     * simulation the plan put on the CPU because the graph is below `acceleration.minNodes`.
+     * Rebuilding that one on every status change would re-upload the graph and reheat a layout
+     * that had settled, and it is a RELOAD that re-plans the threshold, which it does on its own.
+     * @param accelerator - What the controller holds now.
+     * @returns True when the simulation has to be rebuilt.
+     */
+    builtWithChanged(accelerator: GraphAccelerator | null): boolean;
+    /**
+     * The FIRST load, which is what makes this engine's `init()` different from every other's.
+     *
+     * `LayoutManager._setLayoutInternal` replays the pinned nodes between `init()` and
+     * `setLayoutEngine`, through `setNodePosition` and `pin`, so a load deferred to any later
+     * point would meet those calls with no simulation to tell.
+     * @returns A promise that resolves once the simulation exists and holds the graph.
+     */
+    init(): Promise<void>;
+    /**
+     * Adopts a snapshot and builds the simulation the controller's plan chose for it.
+     * @param snapshot - The graph, as `getSnapshot()` returns it; the bridge derives the
+     * undirected copy the simulations require itself.
+     * @param positions - The element's stride-3 array, written in place by every batch.
+     * @throws A `GraphtyError` with `E_NO_ACCELERATOR` under the `required` policy with nothing
+     * attached, or whatever `createSimulation` throws.
+     */
+    load(snapshot: GraphSnapshot, positions: F32): void;
+    /**
+     * Hands the running simulation a new snapshot, rebuilding it first when the plan flipped.
+     *
+     * The re-plan is the point: a freeze can carry the graph across `acceleration.minNodes` in
+     * either direction, and design 9.4 item 4 re-evaluates the threshold at every load.
+     * @param snapshot - The snapshot that has just replaced the old one.
+     * @param positions - The element's array, re-viewed at the new node count.
+     * @throws A `GraphtyError` with `E_NO_ACCELERATOR` under the `required` policy with nothing
+     * attached.
+     */
+    reload(snapshot: GraphSnapshot, positions: F32): void;
+    /**
+     * Rebuilds the simulation on whatever the controller holds now, keeping the arrangement.
+     *
+     * The old simulation is disposed and the new one is loaded with the SAME positions view and
+     * the same pins, so an accelerator arriving mid-run continues the layout rather than
+     * restarting it, and one leaving hands it to the CPU where the policy allows a CPU.
+     * @throws A `GraphtyError` with `E_NO_ACCELERATOR` when the policy is `"required"` and
+     * nothing is attached. The bridge is then STOPPED -- no simulation, nothing submitted -- and
+     * the next transition that attaches an accelerator brings it back through this same method.
+     */
+    replaceSimulation(): void;
+    /**
+     * Submits one batch, fire and forget.
+     *
+     * The abstract signature returns nothing, and a GPU simulation's `step()` returns a promise,
+     * so the rejection is caught here instead of by a caller. A saturated simulation returns the
+     * OLDEST promise already in flight rather than submitting another, which is how it keeps the
+     * frame loop from queueing work faster than the device retires it -- so the handlers are
+     * attached only when the promise is one this bridge has not seen. They are what closes the
+     * controller's work span: a batch landing on a settled simulation is where a GPU layout
+     * stops being work on the device.
+     */
+    step(): void;
+    /**
+     * Submits one batch and waits for it, which the pre-step loop and the tests need.
+     * @param iterations - Iterations this batch computes.
+     * @returns A promise that resolves when the batch has landed, or rejects with its failure.
+     */
+    stepAsync(iterations: number): Promise<void>;
+    /**
+     * Starts the settle count again, on a simulation that has one.
+     *
+     * `reheat()` is not on the `LayoutSimulation` interface -- both CPU simulations and the GPU
+     * ones have it, and a third party's may not -- so it is feature-tested rather than assumed.
+     */
+    reheat(): void;
+    /**
+     * Holds a node still for the duration of a drag, without pinning it.
+     *
+     * The fixed bit is the same one a pin uses, because it is the only thing that stops a
+     * simulation writing the row; what makes this temporary is that {@link endDrag} clears it
+     * again unless the drag is about to become a pin.
+     * @param n - The node the pointer has taken.
+     */
+    beginDrag(n: Node): void;
+    /**
+     * Gives the node back to the simulation, or leaves it fixed because it is being pinned.
+     * A node that was ALREADY PINNED before the pointer took it keeps its bit whatever `pin`
+     * says: the store's pin stops the row being published over, but only the fixed bit stops the
+     * simulation's own copy of it drifting away from where the reader put it, which the next
+     * refit would then have to drag back. Clearing it would leave a node the store still calls
+     * pinned being pushed around inside the simulation every frame.
+     * @param n - The node the pointer has let go of.
+     * @param pin - True when the drag ends in a pin, so the bit stays set.
+     */
+    endDrag(n: Node, pin: boolean): void;
+    /**
+     * Fixes a pinned node in the simulation. The store already holds the pin.
+     * @param n - The node that was pinned.
+     */
+    pin(n: Node): void;
+    /**
+     * Releases a node the simulation was holding fixed.
+     * @param n - The node that was unpinned.
+     */
+    unpin(n: Node): void;
+    /**
+     * Places one node now. A drag reaches this per pointer move, and `replayPins` once per pin.
+     * @param n - The node that moved.
+     * @param p - Where it moved to.
+     */
+    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.
+     * @returns Its scene-unit position; the origin for a row nothing has placed.
+     */
+    getNodePosition(n: Node): Position;
+    /**
+     * Reads both endpoints of an edge into the one pair this engine reuses.
+     * @param e - The edge to read.
+     * @returns The pair, valid until the next call; the origin for an endpoint nothing has placed.
+     */
+    getEdgePosition(e: Edge): EdgePosition;
+    /**
+     * Nothing: the snapshot IS the graph, and the simulation reads it rather than a node list.
+     */
+    addNode(): void;
+    /**
+     * Nothing, for the same reason as {@link addNode}.
+     */
+    addEdge(): void;
+    /**
+     * Every node of the graph, which is the list the FRAME LOOP walks.
+     *
+     * The bridge keeps no list of its own -- the snapshot is the graph -- but these two getters
+     * are not bookkeeping: `UpdateManager` moves a mesh only for a node this one yields, draws an
+     * edge only for an edge the next one yields, and frames the camera on their count. An empty
+     * iterable would let the simulation rewrite the position array every frame while not one mesh
+     * moved. So they answer with the data manager's own collections, which hold exactly what
+     * `LayoutManager` hands every other engine through `addNodes` / `addEdges`.
+     * @returns The graph's live node collection.
+     */
+    get nodes(): Iterable<Node>;
+    /**
+     * Every edge of the graph; see {@link SimulationLayoutEngine.nodes}.
+     * @returns The graph's live edge collection.
+     */
+    get edges(): Iterable<Edge>;
+    /**
+     * Whether the simulation has stopped moving.
+     *
+     * A bridge with no simulation -- before the first load, or stopped after a swap the policy
+     * refused -- reads settled, because nothing is going to move.
+     * @returns True when the last completed batch settled.
+     */
+    get isSettled(): boolean;
+    /**
+     * Maps the simulation's arrangement into the element's scene units, and writes it.
+     *
+     * This is the seam the file header describes. The mapping is remeasured here rather than
+     * fixed once, because a ForceAtlas2 graph expands for hundreds of iterations before it
+     * settles: a scale taken at the first step would let the arrangement grow out of the frame,
+     * and one taken at the last would not exist until the reader had already watched it happen.
+     * Remeasured, a settling graph holds its apparent size and only its shape changes.
+     *
+     * A FIXED ROW IS NEITHER PUBLISHED NOR MEASURED. Its scene-unit coordinate is the reader's --
+     * the pointer's, or where a pin left it -- and `LayoutEngine.writeNodePosition` refuses a
+     * layout-intent write to a pinned row for every engine in this element, so the skip is that
+     * same rule reaching a row a drag is holding as well. It is left out of the measurement for
+     * the same reason it is left out of the write: a radius taken over a row that is not drawn
+     * there would resize every row that is. The two sides start in step, because
+     * every path that fixes a row leaves them in step: a drag writes both through
+     * {@link SimulationLayoutEngine.setNodePosition}, and a pin, a freeze and a rebuild all fix a
+     * row whose simulation copy this mapping had just published from.
+     *
+     * THEY DRIFT APART AFTERWARDS, and deliberately. A refit rescales the arrangement around a
+     * held row without moving the row, so the longer the arrangement keeps growing the further
+     * the simulation's copy of that row sits from where it is drawn. The obvious repair -- write
+     * the row back into the simulation whenever the mapping moves -- was tried and is worse than
+     * the problem: a simulation treats a written position as a disturbance and reheats, so an
+     * accelerated ForceAtlas2 with one pinned node cleared its settle window on every frame and
+     * ran the full sixty-second test budget without once reporting itself at rest. Worse, the
+     * write changes the arrangement, which changes the refit, which asks for another write. A pin
+     * is a scene-unit promise and it is kept; how far the arrangement moves under it is not part
+     * of that promise.
+     *
+     * WHAT A GRAPH OF NOTHING BUT HELD ROWS COSTS. Fitting only the published rows means that the
+     * fewer of them there are the less there is to fit, and two free rows a hair apart are spread
+     * to the full radius exactly as a two-node graph would be. That is this rule meeting a reader
+     * who has pinned almost everything and taken the size out of the layout's hands; it is bounded
+     * -- an arrangement that measures as a point publishes at its own size -- and a graph with no
+     * free row left keeps the last map rather than falling back to the identity.
+     */
+    publishPositions(): void;
+    /**
+     * Releases the simulation. The accelerator's residency for the snapshot is NOT released here:
+     * it is per snapshot and shared with the algorithm runs, and `Graph` frees it at the next
+     * freeze and at shutdown.
+     */
+    dispose(): void;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * @file The spring-electrical layout: ngraph's force model, computed on an accelerator.
+ *
+ * It is registered whatever hardware is present, and `setLayout("spring-electrical")` without an
+ * accelerator that implements it fails loudly with `E_NO_ACCELERATOR` rather than quietly
+ * arranging the graph some other way. A picker does not have to try it to find out: the layout
+ * catalogue's entry for this engine declares `requires: { accelerator: true }`, which a consumer
+ * reads beside `capabilities.acceleration.state` and greys the entry out.
+ */
+import type { SimulationType } from "@graphty/layout";
+import { type OptionsSchema } from "../config";
+import { SimulationLayoutEngine } from "./SimulationLayoutEngine";
+/**
+ * The spring-electrical engine, as the element declares it.
+ *
+ * Every member is a static the element reads: `LayoutManager` builds the bridge itself, with the
+ * graph's acceleration controller, so this class never runs a layout of its own. It declares no
+ * `static descriptor` because its arrangement is authored in the layout catalogue, where it sits
+ * under `force` beside ngraph, d3, ForceAtlas2, Spring and Kamada-Kawai.
+ */
+export declare class SpringElectricalLayout extends SimulationLayoutEngine {
+    static type: string;
+    static simulationType: SimulationType;
+    static maxDimensions: number;
+    static zodOptionsSchema: OptionsSchema;
+    /**
+     * Get dimension-specific options for the spring-electrical layout.
+     * @param dimension - The desired dimension (2 or 3).
+     * @returns Options object with dim parameter.
+     */
+    static getOptionsForDimension(dimension: 2 | 3): object;
+}