@graphty/graphty-element 2.6.1 → 3.0.0

package/dist/src/Node.d.ts

@@ -19,21 +19,45 @@ export type NodeRenderState = "visible" | "hidden" | "context";
 interface NodeOpts {
     pinOnDrag?: boolean;
 }
+/**
+ * Move a node to a row of the current snapshot. Only the data manager calls it, as a node reaches
+ * the builder, leaves it, or is renumbered by a freeze.
+ * @param node - The node.
+ * @param row - Its row, or INVALID_INDEX.
+ */
+export declare function placeNodeRow(node: Node, row: number): void;
+/**
+ * Hand an node the record the graph now holds for it. Only the data manager calls it, from the
+ * render half of the graph's derivation, when a command, an undo or a redo changed the record;
+ * no entry point exports it, so `node.data` is always the graph's record.
+ * @param node - The node.
+ * @param record - The record.
+ */
+export declare function adoptNodeRecord(node: Node, record: AdHocData<string | number>): void;
 /**
  * Represents a node in the graph visualization with its mesh, label, and associated data.
  * Manages node rendering, styling, drag behavior, and interactions with the layout engine.
  */
 export declare class Node {
+    #private;
     parentGraph: Graph | GraphContext;
     opts: NodeOpts;
-    id: NodeIdType;
+    readonly id: NodeIdType;
+    private row;
     /**
      * This node's index in the element's current GraphSnapshot, assigned at add time as
      * `builder.addNode(id)` and walked through `report.nodeRemap` on a renumbering freeze
      * (graph-format design 14.4 rule 5). INVALID_INDEX until the node reaches the builder.
+     * @returns The row.
      */
-    index: number;
-    data: AdHocData<string | number>;
+    get index(): number;
+    private set index(value);
+    /**
+     * The record this node carries, as the graph holds it: deep-frozen, so a write to it throws. A
+     * change goes through the graph (`updateNodes`, `session.data.updateNodes`, ...), which is what undo sees.
+     * @returns The record.
+     */
+    get data(): AdHocData<string | number>;
     mesh: AbstractMesh;
     label?: RichTextLabel;
     /**
@@ -407,6 +431,9 @@ export declare class Node {
      * of the element's bit and never a second source of truth. The order is load-bearing: the bit
      * is recorded FIRST, so an engine that calls back into {@link Node.isPinned} while being told
      * sees the pin.
+     *
+     * In a graph with a session the pin is an undoable step: it is recorded in the session's
+     * `pins`, which writes the byte and tells the engine.
      */
     pin(): void;
     /**
@@ -418,6 +445,12 @@ export declare class Node {
      * been told about.
      */
     unpin(): void;
+    /**
+     * Pin or release this node as a step of its graph's session, when it has one.
+     * @param pinned - Pin, or release.
+     * @returns False when there is no session to dispatch through.
+     */
+    private dispatchPin;
     /**
      * Tell the current layout engine about a pin the element has already recorded.
      *

package/dist/src/NodeBehavior.d.ts

@@ -11,6 +11,7 @@ export declare class NodeDragHandler {
     private node;
     private dragState;
     private clickState;
+    private gesture;
     private scene;
     private pointerObserver;
     private hoverObserver;
@@ -46,6 +47,28 @@ export declare class NodeDragHandler {
      * @param newPosition - New position to set for the node
      */
     setPositionDirect(newPosition: Vector3): void;
+    /**
+     * Open the drag's transaction. Its body waits for the drop; an undo while it is open aborts
+     * it, which ends the drag (design/undo/undo-design.md section 5.3).
+     * @returns The gesture, or null for a graph with no session.
+     */
+    private openGesture;
+    /**
+     * The drop: place the node where the pointer left it and, when it pins, pin it, both
+     * through the drag's transaction, then let the transaction record.
+     * @param gesture - The drag's gesture, or null for a graph with no session.
+     * @param pins - Whether the drop pins: `pinOnDrag` and the pointer placed the node.
+     */
+    private drop;
+    /**
+     * An undo aborted the drag: the dispatcher has rolled it back, restoring where everything
+     * was at drag start and stopping the layout. Release the node in the engine and give the
+     * camera its input back; the rest of the gesture is ignored until the pointer is released.
+     * @param gesture - The aborted gesture.
+     */
+    private abortGesture;
+    /** Give the camera its input back after a drag. */
+    private releaseCamera;
     /**
      * Get the node being dragged.
      * Used by XRInputHandler to access the node's mesh for position calculations.
@@ -57,6 +80,11 @@ export declare class NodeDragHandler {
      * Setup hover detection for emitting node-hover events.
      */
     private setupHoverEvents;
+    /**
+     * Whether the pointer placed the node, which is what `pinOnDrag` pins for.
+     * @returns True for a real drag; false for a click, however the hand shook during it.
+     */
+    private placedByPointer;
     /**
      * Check if the current pointer interaction qualifies as a click.
      * A click is defined as a short duration interaction with minimal movement.

package/dist/src/Styles.d.ts

@@ -17,12 +17,23 @@ import { StyleSchemaV1 } from "./config";
  * the element's own properties.
  */
 export declare class Styles {
-    readonly config: StyleSchemaV1;
+    #private;
     /**
-     * Creates a new Styles instance from a configuration document.
-     * @param config - The parsed document.
+     * Creates a new Styles instance from a configuration document, or from a function that reads
+     * one.
+     * @param config - The parsed document, or the reader a graph builds its frozen view with.
      */
-    constructor(config: StyleSchemaV1);
+    constructor(config: StyleSchemaV1 | (() => StyleSchemaV1));
+    /**
+     * The configuration document.
+     *
+     * On a graph it is a FROZEN VIEW: the project settings from the session's `config` slice,
+     * merged with the graph's view settings, rebuilt only when one of them changes. Two reads with
+     * no change between them return the same object, and writing into it throws. Change a setting
+     * through the element's properties, `Graph`'s setters or `session.config.set`.
+     * @returns The document.
+     */
+    get config(): StyleSchemaV1;
     /**
      * Creates a Styles instance from a JSON string.
      * @param json - JSON string containing the configuration

package/dist/src/acceleration/AccelerationController.d.ts

@@ -35,6 +35,14 @@ export interface AcceleratedWork {
     readonly capability: string;
     /** How many nodes this work is over. Compared against `acceleration.minNodes`. */
     readonly nodeCount: number;
+    /**
+     * False when this piece of work never goes to an accelerator, whatever the accelerator
+     * implements: the run asks for something no accelerator does, such as a walk that stops at a
+     * target. The decision is then the one for
+     * an accelerator without the capability -- the CPU path, or `E_NO_ACCELERATOR` under
+     * `"required"`. Absent means true.
+     */
+    readonly forwarded?: boolean;
 }
 /**
  * Where a piece of work will run, decided before any of it starts.

package/dist/src/acceleration/narrow.d.ts

@@ -23,6 +23,12 @@
 import type { AlgorithmAccelerator } from "@graphty/algorithms";
 import type { LayoutAccelerator } from "@graphty/layout";
 import type { GraphAccelerator } from "./types";
+/**
+ * Whether the element offers this capability to an accelerator at all.
+ * @param capability - A dispatcher member name, such as `"pageRank"`.
+ * @returns True when {@link narrowAlgorithms} copies a member of that name.
+ */
+export declare function forwardsAlgorithm(capability: string): boolean;
 /**
  * Narrows the attached accelerator to the layout seam `createSimulation` feature-tests.
  *
@@ -45,6 +51,8 @@ export declare function narrowLayout(accelerator: GraphAccelerator): LayoutAccel
  * implements, each bound to it, so the dispatcher runs the accelerated implementation where one
  * exists and the CPU port everywhere else.
  * @param accelerator - The accelerator the controller has attached.
+ * @param onCall - Called whenever the dispatcher reaches one of the members, so a caller can tell
+ *   an answer the device computed from one the dispatcher routed to the CPU port.
  * @returns The algorithm half of it, for `accelerated()`.
  * @example
  * ```ts
@@ -53,4 +61,4 @@ export declare function narrowLayout(accelerator: GraphAccelerator): LayoutAccel
  * );
  * ```
  */
-export declare function narrowAlgorithms(accelerator: GraphAccelerator): AlgorithmAccelerator;
+export declare function narrowAlgorithms(accelerator: GraphAccelerator, onCall?: () => void): AlgorithmAccelerator;

package/dist/src/acceleration/types.d.ts

@@ -461,6 +461,16 @@ export declare const ACCELERATION_MIN_NODES_MEASUREMENT = "RTX 4070 SUPER, headl
  * each. Carrying them is what makes the element's behaviour and that record agree; raising the
  * render ceiling (issue #419) is what would let any of the three be measured here and sharpened.
  *
+ * HITS, KATZ AND EIGENVECTOR CENTRALITY ARE FLOORED FROM THE SAME RECORD AND SIT BELOW THE CEILING.
+ * No sweep through the element has measured them yet. The record's section "Re-derived against the
+ * measured ports" times the kernels at 100 iterations against the index-based CPU ports in Chromium:
+ * HITS at 0.72x and 5.71x, Katz at 0.36x and 3.66x, at 10,000 and 100,000 nodes, so both LOSE at
+ * 10,000. The floors are where the speedup crosses 1x between those two measured sizes, taken on a
+ * straight line in log size against log speedup and rounded up: 15,000 nodes for HITS and 28,000
+ * for Katz. Eigenvector centrality shares Katz's floor: the record costs the two as one row, runs
+ * the same power iteration for both, and has no re-derivation of its own. All three are inside
+ * what the element can hold; a sweep through the element is what would sharpen them.
+ *
  * A floor is the smallest measured size at which the device's median was at or below the CPU
  * port's IN EVERY RUN, so a size that won under one load and lost under another is below it. A
  * capability that is not listed has no floor and follows {@link ACCELERATION_MIN_NODES_DEFAULT}.

package/dist/src/ai/AiController.d.ts

@@ -86,16 +86,28 @@ export declare class AiController {
      * @returns Formatted schema section or empty string if no schema
      */
     private buildSchemaSection;
+    /**
+     * One message, inside its transaction: ask the model, then run the tools it calls.
+     * @param input - The user's natural language input
+     * @param tx - The message's transaction, which the tools write through
+     * @param signal - Fires when the message is cancelled or its transaction aborted
+     * @returns The execution result
+     */
+    private converse;
     /**
      * Execute a list of tool calls.
      * @param toolCalls - Tool calls to execute
+     * @param tx - The message's transaction
+     * @param signal - Fires when the message is cancelled
      * @param llmText - Text response from LLM (if any)
      * @returns Combined execution result
+     * @throws MessageRolledBack when a tool threw, so the message's transaction rolls back.
      */
     private executeToolCalls;
     /**
      * Execute a single tool call.
      * @param toolCall - The tool call to execute
+     * @param tx - The message's transaction, handed to the command as `ctx.tx`
      * @returns Command result
      */
     private executeToolCall;

package/dist/src/ai/AiManager.d.ts

@@ -80,6 +80,13 @@ export declare class AiManager {
     private registerBuiltinCommands;
     /**
      * Register a custom command.
+     *
+     * Each assistant message is one undoable step. A command joins it by writing through
+     * `ctx.tx` (`ctx.tx.styles.add`, `ctx.tx.layout.set`, `ctx.tx.run`): those changes are undone
+     * with the rest of the message, and rolled back if a command throws. A change made through
+     * `ctx.graph` is a step of its own and is not rolled back. A command stops when
+     * `ctx.abortSignal` fires, which happens when the message is cancelled or undone while it is
+     * still going.
      * @param command - The command to register
      */
     registerCommand(command: Parameters<CommandRegistry["register"]>[0]): void;

package/dist/src/ai/commands/AlgorithmCommands.d.ts

@@ -2,7 +2,7 @@
  * AlgorithmCommands - Commands for running and listing graph algorithms.
  * @module ai/commands/AlgorithmCommands
  */
-import type { GraphCommand } from "./types";
+import { type GraphCommand } from "./types";
 /**
  * Run a graph algorithm.
  */

package/dist/src/ai/commands/LayoutCommands.d.ts

@@ -2,7 +2,7 @@
  * Layout Commands Module - Commands for changing graph layout and dimension.
  * @module ai/commands/LayoutCommands
  */
-import type { GraphCommand } from "./types";
+import { type GraphCommand } from "./types";
 /**
  * Command to change the graph layout algorithm.
  */

package/dist/src/ai/commands/StyleCommands.d.ts

@@ -14,7 +14,7 @@
  * reports and what a layer, a filter and a legend all use.
  * @module ai/commands/StyleCommands
  */
-import type { GraphCommand } from "./types";
+import { type GraphCommand } from "./types";
 /**
  * Command to find and style nodes matching a selector.
  */

package/dist/src/ai/commands/types.d.ts

@@ -4,6 +4,7 @@
  */
 import type { z } from "zod";
 import type { Graph } from "../../Graph";
+import type { TransactionScope } from "../../session/types";
 import type { AiStatus } from "../AiStatus";
 /**
  * Result of executing a command.
@@ -26,13 +27,31 @@ export interface CommandResult {
 export interface CommandContext {
     /** The graph instance to operate on */
     graph: Graph;
-    /** Signal to check for cancellation */
+    /**
+     * The message's transaction. Everything a command changes through `tx` -- `tx.styles.add`,
+     * `tx.layout.set`, `tx.run` -- joins the message's one undoable step, and is rolled back with
+     * the rest of the message when a command throws. A change made through `graph` instead is a
+     * step of its own and is not rolled back.
+     */
+    tx: TransactionScope;
+    /**
+     * Fires when the message is cancelled, or undone while it is still going. A command stops
+     * on it: once it has fired, every `tx` call rejects.
+     */
     abortSignal: AbortSignal;
     /** Function to emit events */
     emitEvent: (type: string, data: unknown) => void;
     /** Function to update AI status */
     updateStatus: (updates: Partial<AiStatus>) => void;
 }
+/**
+ * Where a command writes: the message's transaction, so its changes join the message's step, or
+ * the graph's own session when the command is called outside a message.
+ * @param graph - The graph the command was handed.
+ * @param context - The command's context, when it has one.
+ * @returns The session to write through.
+ */
+export declare function writerOf(graph: Graph, context?: CommandContext): TransactionScope;
 /**
  * Example of how a command can be invoked.
  */

package/dist/src/algorithms/Algorithm.d.ts

@@ -1,6 +1,7 @@
 import { type AcceleratedAlgorithms, type Graph as AlgorithmGraph } from "@graphty/algorithms";
 import { type GraphSnapshot, type U32 } from "@graphty/graph-format";
 import { type AccelerationPrecision } from "../acceleration/types";
+import { type RegisterOptions } from "../catalog/pluginRegistry";
 import type { AlgorithmDescriptor, EdgeId, FieldDescriptor, NodeId } from "../catalog/types";
 import { type OptionsSchema as ZodOptionsSchema } from "../config";
 import { Graph } from "../Graph";
@@ -65,8 +66,11 @@ export interface AlgorithmStatics {
      * `cubic`. The element divides them by the rate it measured for that class on this device,
      * so the estimate follows the machine and reports "calibrated" once the device is probed,
      * exactly as a built-in's does. Wins over {@link cost} when both are declared.
+     *
+     * `options` are the values the run would use -- the caller's, with the declared defaults
+     * filled in -- so an option that multiplies the work (a number of passes) is priced.
      */
-    costUnits?: (n: number, m: number) => number;
+    costUnits?: (n: number, m: number, options: Readonly<Record<string, unknown>>) => number;
     /**
      * The plugin's own version, recorded on every run this algorithm produces.
      *
@@ -276,13 +280,22 @@ export declare abstract class Algorithm<TOptions extends Record<string, unknown>
      * THE DECISION IS TAKEN ONCE, HERE, BEFORE ANY WORK STARTS. The controller answers "the policy
      * is off", "no accelerator", "below `acceleration.minNodes`" or "this accelerator does not
      * implement that" up front, and under `acceleration="required"` it throws `E_NO_ACCELERATOR`
-     * rather than answering quietly. After the work has started there is no second decision: a
+     * rather than answering quietly. Two answers stay on the CPU even under `"required"`, because
+     * the device is not the element's to offer for them: a capability the element does not
+     * forward (betweenness and closeness today) never asks the controller, and a call the
+     * dispatcher itself keeps on the CPU port (an option or a graph shape the device's kernel is
+     * not defined for) runs there. Both say `f64`. After the work has started there is no second decision: a
      * failure from the accelerator propagates with its code and fails the run, because a number
      * that silently came from somewhere else is worse than no number.
      * @param capability - The accelerator member this work would use, such as `"pageRank"`.
      * @param mode - The shape this algorithm needs; see {@link AlgorithmGraphMode}. `"undirected"`
      *   takes the snapshot's undirected view, which is what collapses a reciprocal pair into one
      *   edge.
+     * @param options - What the decision needs to know about this run.
+     * @param options.accelerable - False when the options of this run are ones no accelerator
+     *   answers, such as a walk that stops at a target, so the decision is the CPU port's (and
+     *   `E_NO_ACCELERATOR` under `acceleration="required"`). A capability the element does not
+     *   forward to an accelerator is never accelerable, whatever this says.
      * @returns The snapshot, the edge map onto it, and the runner.
      * @example
      * ```ts
@@ -291,7 +304,9 @@ export declare abstract class Algorithm<TOptions extends Record<string, unknown>
      * const group = value.labels[snapshot.ids.indexOf(nodeId)];
      * ```
      */
-    protected accelerated(capability: string, mode: AlgorithmGraphMode): AcceleratedAlgorithmRun;
+    protected accelerated(capability: string, mode: AlgorithmGraphMode, options?: {
+        accelerable?: boolean;
+    }): AcceleratedAlgorithmRun;
     /**
      * The dense row of a node the reader named in an option.
      *
@@ -347,9 +362,11 @@ export declare abstract class Algorithm<TOptions extends Record<string, unknown>
     /**
      * Registers an algorithm class in the global registry
      * @param cls - The algorithm class to register
+     * @param options - Whether a different class under a key already taken throws instead of
+     *   replacing it.
      * @returns The registered algorithm class
      */
-    static register<T extends AlgorithmClass>(cls: T): T;
+    static register<T extends AlgorithmClass>(cls: T, options?: RegisterOptions): T;
     /**
      * Gets an algorithm instance from the registry
      * @param g - The graph to run the algorithm on

package/dist/src/algorithms/BFSAlgorithm.d.ts

@@ -53,14 +53,5 @@ export declare class BFSAlgorithm extends DeclaredAlgorithm<BFSOptions> {
      * @returns The layered result, or null when there is nothing to walk.
      */
     compute(context: AlgorithmRunContext): Promise<AlgorithmOutput | null>;
-    /**
-     * Walk with an early stop at a target, on the CPU reference implementation.
-     * @param context - What the element gave the run.
-     * @param nodeIds - The nodes to publish for.
-     * @param source - Where the walk starts.
-     * @param targetNode - Where it stops.
-     * @returns The layered result, or null when the source is not in the graph.
-     */
-    private legacyWalk;
 }
 export {};

package/dist/src/algorithms/BellmanFordAlgorithm.d.ts

@@ -49,19 +49,5 @@ export declare class BellmanFordAlgorithm extends DeclaredAlgorithm<BellmanFordO
      * @returns The route, or null when there are no nodes to search.
      */
     compute(context: AlgorithmRunContext): Promise<AlgorithmOutput | null>;
-    /**
-     * Reconstruct the shortest path from predecessors
-     * @param predecessors - Map of node to its predecessor in the shortest path
-     * @param source - The source node
-     * @param target - The target node
-     * @returns Array of node IDs representing the shortest path
-     */
-    private reconstructPath;
-    /**
-     * Get set of edge keys that are part of the path
-     * @param path - Array of node IDs representing the path
-     * @returns Set of edge keys in "srcId:dstId" format
-     */
-    private getPathEdges;
 }
 export {};

package/dist/src/algorithms/DFSAlgorithm.d.ts

@@ -10,7 +10,7 @@ interface DFSOptions extends Record<string, unknown> {
     source: number | string | null;
     /** Target node for early termination (optional) */
     targetNode: number | string | null;
-    /** Use recursive implementation vs iterative */
+    /** Accepted and ignored; see the option's description. */
     recursive: boolean;
     /** Use pre-order traversal (visit before children) vs post-order */
     preOrder: boolean;

package/dist/src/algorithms/FloydWarshallAlgorithm.d.ts

@@ -1,3 +1,4 @@
+import type { SimplifyPolicy } from "./input/derivedInputs";
 import { type ScopeInputDeclaration } from "./input/ScopedInput";
 import { type AlgorithmOutput, type AlgorithmRunContext, DeclaredAlgorithm } from "./results";
 /**
@@ -8,6 +9,8 @@ export declare class FloydWarshallAlgorithm extends DeclaredAlgorithm {
     static type: string;
     /** Measures every pair of the run's scope: the node list and the graph both come from the input. */
     static scopeInput: ScopeInputDeclaration;
+    /** A distance: of a group of parallel edges, the cheapest is the one a shortest path takes. */
+    static parallelEdges: SimplifyPolicy;
     /**
      * Measure the distance between every pair of nodes, and give each node the distance to the
      * node furthest from it.
@@ -24,6 +27,8 @@ export declare class FloydWarshallAlgorithm extends DeclaredAlgorithm {
      * either, which is the case that has to be fixed here rather than worked around outside.
      * @param context - What the element gave the run.
      * @returns The all-pairs measurement, or null when there are no nodes to measure.
+     * @throws A `GraphtyError` with `E_TOO_LARGE` when the run is over more nodes than the
+     *   all-pairs matrix is bounded to, before any of it is allocated.
      */
     compute(context: AlgorithmRunContext): Promise<AlgorithmOutput | null>;
 }

package/dist/src/algorithms/GirvanNewmanAlgorithm.d.ts

@@ -29,6 +29,11 @@ export declare class GirvanNewmanAlgorithm extends DeclaredAlgorithm<GirvanNewma
      * The method produces a dendrogram -- one partition per cut -- and the run publishes the cut
      * that scored the highest modularity, with that score. A graph with no edges falls apart at
      * the first step, and every node is then its own community.
+     *
+     * Modularity counts a self-loop twice in its node's degree, the standard (NetworkX) reading.
+     * The object-graph route this replaced counted it once, so on a graph with a self-loop the
+     * published modularity differs from that route's, and because the best-scoring cut is the one
+     * published, the partition can differ too. Without a self-loop both are unchanged.
      * @param context - What the element gave the run.
      * @returns The community result, or null when there are no nodes to group.
      */

package/dist/src/algorithms/LeidenAlgorithm.d.ts

@@ -31,6 +31,11 @@ export declare class LeidenAlgorithm extends DeclaredAlgorithm<LeidenOptions> {
      * Publishes the community shape's uniform fields: a group per node, and the modularity the
      * method reported. How many passes it took qualifies those numbers rather than being one of
      * them, so it travels in the caveats.
+     *
+     * The modularity counts a self-loop twice in its node's degree, the standard (NetworkX)
+     * reading; the object-graph route this replaced counted it once. The partition is a
+     * randomised heuristic's and not the replaced route's: on small graphs without self-loops its
+     * modularity lands within about 0.05 of that route's either way, and no lower on average.
      * @param context - What the element gave the run.
      * @returns The community result, or null when there are no nodes to group.
      */

package/dist/src/algorithms/PageRankAlgorithm.d.ts

@@ -1,4 +1,4 @@
-import { type NodeId as AlgorithmNodeId } from "@graphty/algorithms";
+import type { NodeId as AlgorithmNodeId } from "@graphty/algorithms";
 import { z } from "zod/v4";
 import type { FieldDescriptor, NodeId } from "../catalog/types";
 import { type InferOptions } from "../config";

package/dist/src/algorithms/StronglyConnectedComponentsAlgorithm.d.ts

@@ -1,7 +1,7 @@
 import { type ScopeInputDeclaration } from "./input/ScopedInput";
 import { type AlgorithmOutput, type AlgorithmRunContext, DeclaredAlgorithm } from "./results";
 /**
- *
+ * Strongly connected components: the pieces a directed path can cross both ways.
  */
 export declare class StronglyConnectedComponentsAlgorithm extends DeclaredAlgorithm {
     static namespace: string;

package/dist/src/algorithms/metrics/fields.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file The field list a node-metric result publishes.
+ * @file The field lists a metric or a community result publishes.
  *
  * The names are fixed by the result's SHAPE rather than by the algorithm -- `results.<run>.value`
  * means the same thing for every metric -- so they are built here once instead of being written
@@ -46,4 +46,26 @@ interface MetricValueName {
  * @returns The uniform field list for the node-metric shape.
  */
 export declare function nodeMetricFields(value: MetricValueName): readonly FieldDescriptor[];
+/**
+ * Build the fields every edge-metric result publishes: {@link nodeMetricFields} for a value
+ * measured per edge.
+ * @param value - What this metric's primary value is called.
+ * @returns The uniform field list for the edge-metric shape.
+ */
+export declare function edgeMetricFields(value: MetricValueName): readonly FieldDescriptor[];
+/**
+ * Build the fields every community result publishes: the group, and the sizes and count the
+ * element derives from it; modularity only when asked for, because only a method that scores its
+ * own partition may publish one. A run fills what `communityFieldSpecs` lists.
+ * @param value - What one group is called, and whether the method publishes modularity.
+ * @param value.plainName - What one group is called in plain words, such as "Community".
+ * @param value.technicalName - What a paper calls the grouping.
+ * @param value.modularity - Whether the method scores its partition with modularity.
+ * @returns The uniform field list for the community shape.
+ */
+export declare function communityFields(value: {
+    readonly plainName: string;
+    readonly technicalName: string;
+    readonly modularity?: boolean;
+}): readonly FieldDescriptor[];
 export {};

package/dist/src/algorithms/utils/graphUtils.d.ts

@@ -1,7 +1,19 @@
 /**
  * @file Helpers the adapters share: matching an `@graphty/algorithms` answer back onto an edge,
- * and refusing a node option that names no node.
+ * refusing a node option that names no node, and the neighbour order a walk tries.
  */
+import type { GraphSnapshot, U32 } from "@graphty/graph-format";
+/**
+ * The order a walk tries each node's neighbours in: the order their edges were declared.
+ *
+ * An index-based walk tries a node's arcs in row order, which is neighbour index order. The
+ * element's walks have always tried them in the order the edges were declared, and a depth-first
+ * order, a strongly connected component's number and the nodes a breadth-first walk expands
+ * before it reaches its target all depend on it. Passed to a port as `arcOrder`, this keeps them.
+ * @param snapshot - The snapshot the walk runs over.
+ * @returns A permutation of the arc indices, each row's slice sorted by the edge each arc is of.
+ */
+export declare function declarationArcOrder(snapshot: GraphSnapshot): U32;
 /**
  * The key an `@graphty/algorithms` result is matched back onto the element's edges by: the two
  * endpoint ids, in the orientation the record declared.

package/dist/src/catalog/paletteRegistry.d.ts

@@ -28,16 +28,16 @@
  * closing one.
  */
 import { type RegisterOptions } from "./pluginRegistry";
-import { type PaletteDescriptor, type PaletteId } from "./types";
+import { type PaletteDescriptor, type PaletteId, type PaletteRegistration } from "./types";
 /**
  * Register a palette so that a style layer, a legend and a saved document can all name it.
- * @param descriptor - The palette: an id, a plain name, a kind, its colour anchors, its capacity
- *   and whatever colour-blindness safety it claims.
+ * @param descriptor - The palette: an id, a plain name, a kind and its colour anchors, and
+ *   optionally its capacity (derived when left off) and whatever colour-blindness safety it claims.
  * @param options - Whether a collision with an existing registration throws instead of replacing.
  * @throws A `GraphtyError` with `E_BAD_COMMAND` when the descriptor is malformed, naming the
  * field, or with `E_DUPLICATE_PLUGIN` when the id is one the element ships.
  */
-export declare function registerPalette(descriptor: PaletteDescriptor, options?: RegisterOptions): void;
+export declare function registerPalette(descriptor: PaletteRegistration, options?: RegisterOptions): void;
 /**
  * What those palettes publish, in registration order.
  *

package/dist/src/catalog/registry.d.ts

@@ -65,9 +65,10 @@ export interface RegisteredAlgorithm {
      * A cost model in work units of the descriptor's cost class, read from `static costUnits`.
      *
      * The estimator divides it by this device's rate for that class, so calibration scales it.
-     * Wins over {@link cost} when both are present.
+     * Wins over {@link cost} when both are present. `options` are the run's option values, the
+     * declared defaults filled in.
      */
-    readonly costUnits?: (n: number, m: number) => number;
+    readonly costUnits?: (n: number, m: number, options: Readonly<Record<string, unknown>>) => number;
     /**
      * The plugin's own version, read from `static version`.
      *

package/dist/src/catalog/types.d.ts

@@ -182,8 +182,16 @@ export interface OptionChoice {
     value: string;
     label: string;
 }
+/**
+ * Which kind of element an "attribute" or "partition" option reads. Without it, neither a form nor
+ * the element can tell whether "confidence" names a node attribute or an edge attribute.
+ */
+export interface OptionDescriptorDomain {
+    /** Nodes (the default) or edges. Meaningful only for type "attribute" or "partition". */
+    on?: "node" | "edge";
+}
 /** One configurable option, as plain JSON a form can render with no knowledge of Zod. */
-export interface OptionDescriptor {
+export interface OptionDescriptor extends OptionDescriptorDomain {
     name: string;
     plainName: string;
     technicalName?: string;
@@ -480,6 +488,15 @@ export interface PaletteDescriptor {
     capacity: number | null;
     colorblindSafe: readonly ("deuteranopia" | "protanopia" | "tritanopia")[];
 }
+/**
+ * What `registerPalette` accepts: a {@link PaletteDescriptor} whose derived and optional members
+ * may be left off. `capacity` is derived from the kind and the colours, and a missing
+ * `colorblindSafe` is no claim.
+ */
+export type PaletteRegistration = Omit<PaletteDescriptor, "capacity" | "colorblindSafe"> & {
+    capacity?: number | null;
+    colorblindSafe?: PaletteDescriptor["colorblindSafe"];
+};
 /**
  * One camera view: a named way of deciding where the viewer stands and what they look at.
  *