@graphty/graphty-element 2.0.0 → 2.2.0

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

@@ -50,6 +50,20 @@ export type AccelerationState = "probing" | "active" | "idle" | "unavailable" |
  * next visit, is the host application's storage and the host application's job.
  */
 export type AccelerationPolicy = "auto" | "off" | "required";
+/** The three values, in the order a control offers them. */
+export declare const ACCELERATION_POLICIES: readonly AccelerationPolicy[];
+/** What the element does when nothing was asked: `auto`. */
+export declare const ACCELERATION_POLICY_DEFAULT: AccelerationPolicy;
+/**
+ * Whether a value is one of the three acceleration policies.
+ *
+ * A host that offers the choice gets the value back from storage, a query string or a change
+ * handler, where it is an unknown string. This is the check the element itself runs on the
+ * `acceleration` attribute, so a host cannot accept a value the element would refuse.
+ * @param value - Anything at all.
+ * @returns True when `value` is `"auto"`, `"off"` or `"required"`.
+ */
+export declare function isAccelerationPolicy(value: unknown): value is AccelerationPolicy;
 /**
  * The arithmetic that produced a set of numbers.
  *
@@ -74,13 +88,21 @@ export declare const DEFAULT_ACCELERATOR_PRECISION: AccelerationPrecision;
  *
  * Three plain strings, so a status chip can render "NVIDIA, ampere" without importing a GPU
  * type or parsing a renderer string.
+ *
+ * This side is ALWAYS PRESENT, MAY BE EMPTY: an accelerator fills in what its driver told it and
+ * `""` for what it did not, so an implementer never has to choose between `""` and `undefined`.
+ * {@link AccelerationStatus}, what a consumer reads, is the opposite -- a field is there only
+ * when the backend reported one -- and `AccelerationController` is the single place that
+ * converts between the two, dropping every empty string on the way out. Keep it that way: a
+ * browser masks the device and the description for an ordinary origin, so empty is the common
+ * case and a consumer must never be handed `""` to render.
  */
 export interface AcceleratorDeviceInfo {
-    /** The hardware vendor, as the driver reports it: `"nvidia"`, `"apple"`, `"intel"`. */
+    /** The hardware vendor, as the driver reports it: `"nvidia"`, `"apple"`, `""` when unknown. */
     readonly vendor: string;
     /** The device family, as the driver reports it: `"ampere"`, `"rdna-3"`, `""` when unknown. */
     readonly architecture: string;
-    /** A human-readable description of the device. May be empty; never undefined. */
+    /** A human-readable description of the device, `""` when unknown. Never undefined. */
     readonly description: string;
 }
 /**
@@ -115,9 +137,42 @@ export interface GraphAccelerator {
     }>;
     /** The arithmetic this accelerator computes in. Absent means {@link DEFAULT_ACCELERATOR_PRECISION}. */
     readonly precision?: AccelerationPrecision;
+    /**
+     * Proves this accelerator computes correctly, before any of the element's work is planned
+     * onto it.
+     *
+     * Hardware that answers is not the same thing as hardware that answers correctly. The
+     * software renderer that ships with Windows miscomputes shaders that pass a value across a
+     * workgroup barrier: it builds, it runs, it returns plausible numbers, and every prefix sum,
+     * sort and grid layout over one of them is wrong. Nothing errors. A backend that can tell
+     * the difference implements this; one that cannot omits it, and the element attaches it on
+     * the strength of the probe as before.
+     *
+     * Resolve when the hardware is trustworthy. Reject with a `GraphtyError` carrying
+     * `E_DEVICE_INCORRECT` when it is not, and the element reports acceleration unavailable with
+     * that code and runs the CPU path -- the same place a missing adapter reaches, because a
+     * device that lies is no more usable than a device that is not there.
+     *
+     * The element calls it once, on an accelerator it built from a registered factory, before
+     * attaching it. An accelerator handed over already built through `setAccelerator` is not
+     * asked -- the element did not construct it and does not own its lifetime, and whoever did
+     * both vouched for it by handing it over.
+     *
+     * It is NOT a way to report a failure part-way through a run: work that has already started
+     * on the accelerator and then fails is that work's failure and throws.
+     * @returns Resolves when the accelerator is fit to be given work.
+     */
+    verify?(): Promise<void>;
     /** Releases the hardware resources. Called by the element when it detaches this accelerator. */
     dispose?(): void;
-    /** An accelerated algorithm or layout, looked up by name and feature-tested before use. */
+    /**
+     * An accelerated algorithm or layout, looked up by name and feature-tested before use.
+     *
+     * `release(snapshot)` is one of these rather than a declared member: an accelerator that keeps
+     * device buffers for a snapshot implements it, and the element calls it when that snapshot
+     * stops being the graph, while an accelerator with no residency to free simply has no such
+     * member. Both are feature-tested the same way, so neither has to pretend to be the other.
+     */
     [algorithmOrLayout: string]: unknown;
 }
 /** What the element tells a factory before the factory builds anything. */
@@ -131,6 +186,14 @@ export interface AcceleratorFactoryOptions {
      * that does not care ignores the parameter.
      */
     readonly exactMaxNodes?: number;
+    /**
+     * Whether a software adapter (SwiftShader, llvmpipe) is acceptable.
+     *
+     * Under `"auto"` it is not: a software rasteriser is slower than the element's own CPU
+     * path, and attaching it would make the graph slower while reporting "active". Under
+     * `"required"` it is: the consumer said "no CPU path", and a software device is a device.
+     */
+    readonly acceptSoftware?: boolean;
 }
 /**
  * Builds an accelerator, or declines.
@@ -161,11 +224,18 @@ export interface AccelerationStatus {
     readonly state: AccelerationState;
     /** The attached accelerator's backend, when one is attached. */
     readonly backend?: "webgpu" | (string & {});
-    /** The hardware vendor, when the backend reported one. */
+    /**
+     * The hardware vendor, when the backend reported one. Absent otherwise, never `""`.
+     *
+     * The three device facts arrive from an accelerator as {@link AcceleratorDeviceInfo}, where
+     * they are always present and an unknown one is `""`. They are published here the other way
+     * round, so a consumer can test one with `??` or `!== undefined` and never render an empty
+     * string. `AccelerationController` is what converts.
+     */
     readonly vendor?: string;
-    /** The device family, when the backend reported one. */
+    /** The device family, when the backend reported one. Absent otherwise, never `""`. */
     readonly architecture?: string;
-    /** The device description, when the backend reported one. */
+    /** The device description, when the backend reported one. Absent otherwise, never `""`. */
     readonly device?: string;
     /** Why acceleration is unavailable or has stopped, in a sentence a person can read. */
     readonly reason?: string;
@@ -278,6 +348,17 @@ export declare const ACCELERATION_MIN_NODES_KEY = "acceleration.minNodes";
  *
  * Raise it when a graph is small enough that uploading it costs more than computing it. There
  * is no defensible non-zero default, because the crossover has to be measured on the machine
- * the graph is drawn on.
+ * the graph is drawn on -- and this zero is a measurement, not a guess. On the dev box
+ * (RTX 4070 SUPER, headless Chromium, 2026-09-22) the accelerated layout's frame time was at or
+ * below the CPU simulation's at every size measured, starting with the smallest: 50.0 against
+ * 50.0 ms at 500 nodes, 116.7 against 116.7 at 1,000 and 183.3 against 216.6 at 2,000, three runs
+ * of sixty working frames per arm, all at average degree 10. A fourth size, 5,000 nodes, read
+ * 466.6 against 566.7 -- but from ONE run of five frames, so read it as indicative and not as what
+ * the default rests on. The crossover is therefore below the smallest graph worth accelerating,
+ * and the default stays 0.
+ *
+ * `scripts/measure-min-nodes.mjs` is the measurement, protocol in its header; the table and what
+ * it does not cover are in section 3 of `graphty-element/docs/decisions/G6.md` IN THE REPOSITORY,
+ * which is not part of the published documentation site.
  */
 export declare const ACCELERATION_MIN_NODES_DEFAULT = 0;

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

@@ -1,5 +1,7 @@
-import type { Graph as AlgorithmGraph } from "@graphty/algorithms";
-import type { AlgorithmDescriptor, FieldDescriptor } from "../catalog/types";
+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 { AlgorithmDescriptor, FieldDescriptor, NodeId } from "../catalog/types";
 import { type OptionsSchema as ZodOptionsSchema } from "../config";
 import { Graph } from "../Graph";
 import type { RunResult } from "../session/results";
@@ -70,6 +72,57 @@ export interface AlgorithmStatics {
     /** Check if this algorithm has a Zod-based options schema */
     hasZodOptions(): boolean;
 }
+/**
+ * One piece of accelerable work, with the decision "accelerator or CPU" already taken.
+ *
+ * An adapter reads the snapshot it is over, runs the work through {@link run}, and writes ONE
+ * loop over an index-aligned result whichever path produced it. The precision that comes back is
+ * what the run publishes as `caveats.precision`: a result computed on an accelerator says `f32`
+ * and one computed on the CPU port says `f64`, and a reader comparing two numbers has the
+ * qualification that explains the difference.
+ *
+ * Exported only because it is the return type of a protected member, which declaration emit
+ * requires to be nameable. An adapter receives one from `Algorithm.accelerated`; nothing outside
+ * this module constructs one or needs to name it.
+ * @internal
+ */
+export interface AcceleratedAlgorithmRun {
+    /**
+     * The snapshot the work runs over: the declared one for `"directed"`, the undirected view for
+     * `"undirected"`, in either case with every group of parallel edges collapsed to one edge
+     * carrying the group's summed weight. Its `ids` map is how a node id becomes the index every
+     * result is keyed by, and the node space is the declared one either way.
+     */
+    readonly snapshot: GraphSnapshot;
+    /**
+     * Declared edge index -> edge index in {@link snapshot}, or null when the edge space is the
+     * declared one.
+     *
+     * This is the direction an edge-carrying result is read in: an adapter walks the element's own
+     * edges, maps each one's `Edge.index` through this, and asks whether that index is in the
+     * result. Read the other way (`edgeOrigin`) a merged group names only its survivor, so every
+     * edge the reader declared but one would silently go unflagged -- both halves of a reciprocal
+     * pair the undirected view collapsed, and every member of a group of parallel edges.
+     */
+    readonly edgeRemap: U32 | null;
+    /**
+     * Runs the work, on the accelerator when the controller said so and on the CPU port when it
+     * did not.
+     *
+     * A property rather than a method, so an adapter may take it out of the object it came in --
+     * `const { run } = this.accelerated(...)` -- which is how every one of them reads.
+     * @param fn - The work, written once against the dispatcher.
+     * @returns What the work produced, and the arithmetic it was produced in.
+     * @throws Whatever the accelerator threw, with its code. A failure after the work started is
+     * the run's failure: nothing is recomputed on the CPU.
+     */
+    readonly run: <T>(fn: (dispatch: AcceleratedAlgorithms, snapshot: GraphSnapshot) => Promise<T>) => Promise<{
+        /** What `fn` returned. */
+        readonly value: T;
+        /** The arithmetic it was computed in. */
+        readonly precision: AccelerationPrecision;
+    }>;
+}
 /**
  * Base class for all graph algorithms
  * @template TOptions - The options type for this algorithm (defaults to empty object)
@@ -151,6 +204,47 @@ export declare abstract class Algorithm<TOptions extends Record<string, unknown>
      * @returns a freshly built Graph for the algorithm package
      */
     protected algorithmGraph(mode: AlgorithmGraphMode): AlgorithmGraph;
+    /**
+     * The route an algorithm with an accelerated implementation takes.
+     *
+     * It is the counterpart of {@link algorithmGraph} for the algorithms `@graphty/algorithms`
+     * can dispatch: instead of copying the snapshot into an object graph, the work runs over the
+     * snapshot itself, on the attached accelerator or on the index-based CPU port, and the adapter
+     * writes one loop over an index-aligned result either way.
+     *
+     * 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
+     * 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.
+     * @returns The snapshot, the edge map onto it, and the runner.
+     * @example
+     * ```ts
+     * const { snapshot, run } = this.accelerated("connectedComponents", "undirected");
+     * const { value, precision } = await run((dispatch, s) => dispatch.connectedComponents(s));
+     * const group = value.labels[snapshot.ids.indexOf(nodeId)];
+     * ```
+     */
+    protected accelerated(capability: string, mode: AlgorithmGraphMode): AcceleratedAlgorithmRun;
+    /**
+     * The dense row of a node the reader named in an option.
+     *
+     * A search takes its source as an id and the snapshot answers in indices, so this is where the
+     * two meet -- and where an id that names no node in the graph is reported as what it is: an
+     * option whose value is outside the permitted range, carrying the option's name and what was
+     * passed, rather than a silent empty result or a search from row zero.
+     * @param snapshot - The graph the work runs over.
+     * @param option - The option the id came from, named in the error.
+     * @param id - The node id the reader gave.
+     * @returns The node's dense row.
+     * @throws A `GraphtyError` with `E_OPTION_RANGE` when the graph has no such node.
+     */
+    protected nodeIndex(snapshot: GraphSnapshot, option: string, id: NodeId): number;
     /**
      * Resolves and validates options against the schema
      * @param options - User-provided options (partial)

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

@@ -50,5 +50,14 @@ 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/DijkstraAlgorithm.d.ts

@@ -9,14 +9,14 @@ interface DijkstraOptions extends Record<string, unknown> {
     source: number | string | null;
     /** Destination node for shortest path (defaults to last node if not provided) */
     target: number | string | null;
-    /** Use bidirectional search optimization for point-to-point queries */
+    /** Accepted and ignored; see the option's description. */
     bidirectional: boolean;
 }
 /**
  * Dijkstra's algorithm for finding shortest paths
  *
  * Computes shortest paths from a source node to all other nodes using
- * non-negative edge weights. Supports bidirectional search optimization.
+ * non-negative edge weights.
  */
 export declare class DijkstraAlgorithm extends DeclaredAlgorithm<DijkstraOptions> {
     static namespace: string;
@@ -53,11 +53,5 @@ export declare class DijkstraAlgorithm extends DeclaredAlgorithm<DijkstraOptions
      * @returns The route, or null when there are no nodes to search.
      */
     compute(context: AlgorithmRunContext): Promise<AlgorithmOutput | null>;
-    /**
-     * 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/PageRankAlgorithm.d.ts

@@ -138,6 +138,14 @@ export declare class PageRankAlgorithm extends MetricAlgorithm<PageRankOptions>
      * Resolved options using the NEW Zod-based validation
      */
     private zodOptions;
+    /**
+     * The two Map-valued options, kept from what the caller passed.
+     *
+     * NEITHER SCHEMA CARRIES THEM -- a Map is not a value a form or a saved document can hold --
+     * and `resolveOptions` returns only the keys its schema declares, so reading them back off the
+     * resolved options found nothing and a personalized run quietly ran an unpersonalized one.
+     */
+    private readonly programmaticOptions;
     /**
      * Creates a new PageRank algorithm instance
      * @param g - The graph to run the algorithm on

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

@@ -15,6 +15,19 @@
  * @returns the lookup key
  */
 export declare function edgePairKey(source: string | number, target: string | number): string;
+/**
+ * Refuse a node id option that names no node in the graph.
+ *
+ * `@graphty/algorithms` answers a query about a missing node with an empty result rather than an
+ * error, so without this check an unknown id publishes zeros as if they were a measurement.
+ * @param algorithm - The algorithm's key, for the message.
+ * @param option - The option name the id came in on.
+ * @param value - The id the caller passed.
+ * @param nodeIds - Every node id in the graph.
+ * @returns The id as the string the algorithms package keys nodes by.
+ * @throws A `GraphtyError` coded `E_OPTION_RANGE` when no node has that id.
+ */
+export declare function requireNodeOption(algorithm: string, option: string, value: string | number, nodeIds: readonly (string | number)[]): string;
 /**
  * Minimal edge data interface required by graph utilities
  */

package/dist/src/cameras/OrbitCameraController.d.ts

@@ -15,6 +15,7 @@ export interface OrbitConfig {
  * Provides trackball-style rotation and keyboard/touch controls.
  */
 export declare class OrbitCameraController {
+    #private;
     scene: Scene;
     camera: UniversalCamera;
     cameraDistance: number;

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

@@ -2,7 +2,7 @@
  * @file The layout catalogue: the arrangements the element offers, and the engines behind them.
  *
  * A public layout name says what the arrangement IS -- "force", "hierarchical", "circular" --
- * and never which library draws it. The element registers sixteen engines whose registered
+ * and never which library draws it. The element registers seventeen engines whose registered
  * names ARE their implementations ("ngraph", "d3", "forceatlas2"), and freezing those into the
  * public API makes swapping an implementation a rename every consumer can see. So the engine is
  * data on the descriptor instead: `LayoutDescriptor.engine` names the implementation the element
@@ -46,6 +46,18 @@ export interface LayoutImplementation {
      * catalogue cannot claim a weight channel an engine does not have.
      */
     honoursWeights: boolean;
+    /**
+     * What has to be true before this engine can run at all, in the same shape an algorithm
+     * declares it.
+     *
+     * `accelerator: true` means the engine is computed on hardware and has no processor
+     * implementation, so a picker greys the entry out when `capabilities.acceleration.state` says
+     * nothing is attached. It belongs to the ENGINE rather than to the arrangement: `force` is
+     * drawn by six engines, five of which need nothing.
+     */
+    requires?: {
+        accelerator?: boolean;
+    };
 }
 /** One semantic layout, with every engine that can draw it. */
 export interface LayoutCatalogEntry {

package/dist/src/config/GraphBehavior.d.ts

@@ -1,6 +1,17 @@
 import { z } from "zod/v4";
 import type { Graph } from "../Graph";
 import type { Node as GraphNode } from "../Node";
+declare const GraphLayoutOpts: z.ZodObject<{
+    type: z.ZodDefault<z.ZodString>;
+    preSteps: z.ZodDefault<z.ZodNumber>;
+    stepMultiplier: z.ZodDefault<z.ZodNumber>;
+    minDelta: z.ZodDefault<z.ZodNumber>;
+    zoomStepInterval: z.ZodDefault<z.ZodNumber>;
+    iterationsPerStep: z.ZodOptional<z.ZodNumber>;
+    maxInFlight: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/** How the element drives a layout, as the behaviour configuration resolves it. */
+export type GraphLayoutBehavior = z.infer<typeof GraphLayoutOpts>;
 /** How the element drives the layout, as a caller supplies it: every field optional. */
 export type GraphBehaviorConfig = z.input<typeof GraphBehaviorOpts>;
 export declare const GraphBehaviorOpts: z.ZodObject<{
@@ -10,6 +21,8 @@ export declare const GraphBehaviorOpts: z.ZodObject<{
         stepMultiplier: z.ZodDefault<z.ZodNumber>;
         minDelta: z.ZodDefault<z.ZodNumber>;
         zoomStepInterval: z.ZodDefault<z.ZodNumber>;
+        iterationsPerStep: z.ZodOptional<z.ZodNumber>;
+        maxInFlight: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
     node: z.ZodPrefault<z.ZodObject<{
         pinOnDrag: z.ZodDefault<z.ZodBoolean>;

package/dist/src/config/GraphStyle.d.ts

@@ -42,7 +42,7 @@ declare const GraphSelectionStyle: z.ZodObject<{
     /** How solid the halo is, in `[0, 1]`. Low enough to read as a highlight rather than a node. */
     opacity: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>;
-/** What a selected node looks like, as it parses. See {@link GraphSelectionStyle}. */
+/** What a selected node looks like, as it parses. See {@link GraphSelectionStyleOpts}. */
 export type GraphSelectionStyleConfig = z.infer<typeof GraphSelectionStyle>;
 /** What a caller may say about the selection highlight: every field optional. */
 export type GraphSelectionStyleInput = z.input<typeof GraphSelectionStyle>;

package/dist/src/config/StyleTemplate.d.ts

@@ -922,6 +922,8 @@ declare const StyleTemplateV1: z.ZodObject<{
             stepMultiplier: z.ZodDefault<z.ZodNumber>;
             minDelta: z.ZodDefault<z.ZodNumber>;
             zoomStepInterval: z.ZodDefault<z.ZodNumber>;
+            iterationsPerStep: z.ZodOptional<z.ZodNumber>;
+            maxInFlight: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>;
         node: z.ZodPrefault<z.ZodObject<{
             pinOnDrag: z.ZodDefault<z.ZodBoolean>;
@@ -1853,6 +1855,8 @@ export declare const StyleTemplate: z.ZodDiscriminatedUnion<[z.ZodObject<{
             stepMultiplier: z.ZodDefault<z.ZodNumber>;
             minDelta: z.ZodDefault<z.ZodNumber>;
             zoomStepInterval: z.ZodDefault<z.ZodNumber>;
+            iterationsPerStep: z.ZodOptional<z.ZodNumber>;
+            maxInFlight: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>;
         node: z.ZodPrefault<z.ZodObject<{
             pinOnDrag: z.ZodDefault<z.ZodBoolean>;

package/dist/src/data/CSVDataSource.d.ts

@@ -1,6 +1,7 @@
 import { type CSVVariant } from "./csv-variant-detection.js";
 import { BaseDataSourceConfig, DataSource, DataSourceChunk } from "./DataSource.js";
 interface CSVDataSourceConfig extends BaseDataSourceConfig {
+    /** The column separator. Worked out from the first line (comma, tab, semicolon or pipe) when unset. */
     delimiter?: string;
     variant?: CSVVariant;
     /**

package/dist/src/data/csv-variant-detection.d.ts

@@ -10,6 +10,17 @@ export interface CSVVariantInfo {
     typeColumn?: string;
     interactionColumn?: string;
 }
+/**
+ * Work out a delimited file's column separator from its first line.
+ *
+ * Papaparse's own guess is not used because it guesses from the rows it previews, and the one-row
+ * preview that reads the header row sees too little to tell a tab from a comma: it answers "," and
+ * the header `source<TAB>target` comes back as one column.
+ * @param content - The file, or at least its first line.
+ * @returns Whichever of comma, tab, semicolon and pipe appears most often outside quotes on the
+ * first line, or a comma when none does.
+ */
+export declare function sniffDelimiter(content: string): string;
 /**
  * Detect CSV variant from headers and sample data
  * @param headers - Array of column header names

package/dist/src/errors/codes.d.ts

@@ -243,6 +243,19 @@ export type GraphtyErrorCode =
  * silence.
  */
  | "E_SOFTWARE_ONLY"
+/**
+ * An adapter was found, it answered, and its answers are wrong. Before any of the element's
+ * work goes to an accelerator, the accelerator is asked to compute something whose answer is
+ * already known; a device that gets that wrong is refused, and the CPU path runs. The
+ * software renderer that ships with Windows is the device this exists for: it miscomputes
+ * shaders that pass a value across a workgroup barrier, so every prefix sum, sort and grid
+ * layout above one comes back wrong -- with plausible numbers and no error anywhere.
+ *
+ * `details` carry what the accelerator reported about the disagreement. Reported through
+ * `capabilities.acceleration` rather than thrown during ordinary use. Nothing the caller
+ * changes helps; a driver update might.
+ */
+ | "E_DEVICE_INCORRECT"
 /**
  * The GPU device was lost mid-session -- a driver reset, a tab suspension, or the browser
  * reclaiming the device. `details.reason` carries what the runtime said. The element reports
@@ -292,7 +305,7 @@ export declare const GRAPHTY_ERROR_CODES: readonly GraphtyErrorCode[];
  * This is the type of `capabilities.acceleration.code`, where a code is reported rather than
  * thrown: absence of acceleration is a state the consumer renders, not a failure it catches.
  */
-export type AccelerationErrorCode = "E_NO_WEBGPU" | "E_NO_ADAPTER" | "E_SOFTWARE_ONLY" | "E_DEVICE_LOST" | "E_TOO_LARGE";
+export type AccelerationErrorCode = "E_NO_WEBGPU" | "E_NO_ADAPTER" | "E_SOFTWARE_ONLY" | "E_DEVICE_INCORRECT" | "E_DEVICE_LOST" | "E_TOO_LARGE";
 /**
  * Every code that can appear on `capabilities.acceleration.code`.
  */

package/dist/src/events.d.ts

@@ -13,7 +13,7 @@ export type GraphEventType = GraphEvent["type"];
 export type NodeEventType = NodeEvent["type"];
 export type EdgeEventType = EdgeEvent["type"];
 type AiEventType = AiEvent["type"];
-export type GraphEvent = GraphSettledEvent | GraphErrorEvent | GraphDataLoadedEvent | GraphDataAddedEvent | GraphSnapshotReplacedEvent | GraphLayoutInitializedEvent | CameraStateChangedEvent | GraphGenericEvent | DataLoadingProgressEvent | DataLoadingErrorEvent | DataLoadingErrorSummaryEvent | DataLoadingCompleteEvent | ElementsRemovedEvent | SelectionChangedEvent;
+export type GraphEvent = GraphSettledEvent | GraphErrorEvent | GraphDataLoadedEvent | GraphDataAddedEvent | GraphSnapshotReplacedEvent | GraphSnapshotDroppedEvent | GraphLayoutInitializedEvent | CameraStateChangedEvent | GraphGenericEvent | DataLoadingProgressEvent | DataLoadingErrorEvent | DataLoadingErrorSummaryEvent | DataLoadingCompleteEvent | ElementsRemovedEvent | SelectionChangedEvent;
 /**
  * The graph event types that stay INSIDE the element: emitted on the internal graph observable so
  * the element's own managers can react, and never re-dispatched to the DOM.
@@ -69,9 +69,11 @@ export interface GraphDataAddedEvent {
  * Emitted by DataManager after every freeze, once the element's position column is attached to the
  * new snapshot (graph-format design 14.4 rule 11).
  *
- * Listeners release per-snapshot resources: at E1 `Graph` releases the accelerator's GPU buffers for
- * `previous` and its derived views, and caches drop their entries. Nothing a WeakMap can do for
- * them -- GPU memory is not garbage collected.
+ * Listeners release per-snapshot resources: `Graph` releases the accelerator's buffers for
+ * `previous` and for its undirected copy when that is a distinct snapshot (the release list of the
+ * WebGPU design 9.4 item 2), and caches drop their entries. Nothing a WeakMap can do for them --
+ * GPU memory is not garbage collected. A dataset that is cleared rather than replaced has no
+ * `next` to freeze and is announced by {@link GraphSnapshotDroppedEvent} instead.
  */
 export interface GraphSnapshotReplacedEvent {
     type: "snapshot-replaced";
@@ -84,6 +86,17 @@ export interface GraphSnapshotReplacedEvent {
     /** freezeWithReport's report, relative to the PREVIOUS freeze of the same builder. */
     report: FreezeReport;
 }
+/**
+ * Emitted by DataManager when the dataset is cleared: the store and every snapshot it froze are
+ * discarded without a replacement, so no `snapshot-replaced` ever carries that boundary.
+ *
+ * Listeners drop their per-snapshot resources exactly as they do on a replacement -- `Graph`
+ * releases the accelerator's buffers for the snapshot it was showing. Emitted while the outgoing
+ * store is still usable, so a listener can still ask it for a derived view of what it is freeing.
+ */
+export interface GraphSnapshotDroppedEvent {
+    type: "snapshot-dropped";
+}
 export interface GraphLayoutInitializedEvent {
     type: "layout-initialized";
     layoutType: string;

package/dist/src/graphty-element.d.ts

@@ -122,7 +122,7 @@ export declare class Graphty extends LitElement {
      * properties can be used in style selectors and accessed via `node.data`.
      * @since 1.0.0
      * @see {@link edgeData} for edge data
-     * @see {@link https://graphty.app/storybook/element/?path=/story/graphty--default | Basic Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/graphty--graphty | Basic Examples}
      * @example HTML attribute (JSON string)
      * ```html
      * <graphty-element
@@ -388,7 +388,7 @@ export declare class Graphty extends LitElement {
      * - `fixed`: Pre-defined positions from node data
      * @since 1.0.0
      * @see {@link layoutConfig} for layout-specific options
-     * @see {@link https://graphty.app/storybook/element/?path=/story/layout--default | Layout Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/layout-3d--circular | Layout Examples}
      * @example
      * ```typescript
      * // Set force-directed layout
@@ -509,7 +509,7 @@ export declare class Graphty extends LitElement {
      *
      * VR and AR modes require WebXR support in the browser.
      * @since 1.0.0
-     * @see {@link https://graphty.app/storybook/element/?path=/story/viewmode--default | View Mode Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/viewmode--switch-view-modes | View Mode Examples}
      * @example
      * ```typescript
      * element.viewMode = "2d";  // Switch to 2D orthographic view
@@ -1526,6 +1526,27 @@ export declare class Graphty extends LitElement {
      * ```
      */
     isRunning(): boolean;
+    /**
+     * Play or pause the layout.
+     *
+     * `setRunning(true)` on a layout that has already settled restarts it, so "play" is
+     * something the reader can see; `setRunning(false)` stops the per-frame stepping and nothing
+     * else -- work already handed to an accelerator lands, the scene keeps rendering, and the
+     * camera, picking and styling stay live. There is no event for this: `isRunning()` reports
+     * the state and `graph-settled` reports the arrangement coming to rest.
+     *
+     * A pause is not a mode the element remembers: anything that (re)starts a layout -- loading
+     * more nodes, an accelerator attaching, setting another layout, dropping a dragged node --
+     * runs it again, so pause it after those, not before.
+     * @param running - True to run the layout, false to pause it.
+     * @since 2.0.0
+     * @example
+     * ```typescript
+     * element.setRunning(false); // pause
+     * element.setRunning(true); // play again, from where it stopped
+     * ```
+     */
+    setRunning(running: boolean): void;
     /**
      * Convert world coordinates to screen coordinates.
      * @param worldPos - Position in world space
@@ -1870,6 +1891,30 @@ export declare class Graphty extends LitElement {
      * healthy.
      */
     set acceleration(value: AccelerationPolicy);
+    /**
+     * The node count at or above which accelerated work uses the accelerator.
+     *
+     * Below it the element takes the CPU path even with an accelerator attached, and
+     * `capabilities.acceleration.state` reads `"idle"`. Default 0: use the accelerator whenever
+     * there is one. Raise it when the graphs you show are small enough that uploading costs more
+     * than computing; the number is machine-specific, which is why the element does not guess.
+     * @since 2.0.0
+     * @example
+     * ```html
+     * <graphty-element acceleration-min-nodes="5000"></graphty-element>
+     * ```
+     * @returns The threshold in force.
+     */
+    get accelerationMinNodes(): number;
+    /**
+     * Sets the threshold and applies it immediately.
+     *
+     * A value that is not a whole number of 0 or more is reported and then ignored, leaving the
+     * previous threshold in force, for the reason the `acceleration` setter states: Lit drives
+     * this from `attributeChangedCallback`, and a throw there would leave the element unrendered.
+     * @param value - The node count at or above which accelerated work uses the accelerator.
+     */
+    set accelerationMinNodes(value: number);
 }
 export type GraphtyElement = Graphty;
 declare global {