@graphty/graphty-element 2.0.1 → 2.2.0

package/dist/graphty.js

@@ -1,79 +1,81 @@
-import { A as e, a as r, b as E, D as O, E as o, d as S, G as R, e as t, I as _, L, N as C, O as A, R as N, S as n, f as g, g as T, h as p, U as I, i as d } from "./chunks/index-uohvGegX.js";
-import { a as G, S as l, b as f } from "./chunks/paletteRegistry-B-oS4YxP.js";
-import { D as h, E as y } from "./chunks/DataSource-DK4GZBKg.js";
-import { A as m } from "./chunks/Algorithm-BdcqHKps.js";
-import { e as u, E as x, N as P, a as c, P as B, R as V, S as H, d as b, b as Y, c as F } from "./chunks/NodeStyle-CS7dj20m.js";
-import { A as K, a as k, G as v, i as w, b as Q } from "./chunks/GraphtyError-B3eKs4yg.js";
-import { A as j, a as q, C as z } from "./chunks/types-Dwm9waL2.js";
-import { B as Z, a as $, b as aa, C as sa, G as ea, c as ra, I as Ea, O as Oa, d as oa, e as Sa, f as Ra, P as ta, g as _a, h as La, R as Ca, T as Aa, i as Na, V as na, Y as ga } from "./chunks/sequential-Zym81qm7.js";
-import { a as pa, G as Ia, V as da, i as ia } from "./chunks/GraphStyle-D0PXnZKu.js";
-import { c as la } from "./chunks/common-DWNKjpH_.js";
+import { A as e, a as E, b as r, D as O, E as o, d as S, G as R, e as _, I as t, L, N as C, O as A, R as N, S as n, f as I, g as T, h as g, U as i, i as l } from "./chunks/index-2VIpMJZP.js";
+import { a as p, S as G, b as f } from "./chunks/paletteRegistry-NrWOKT-A.js";
+import { D as y, E as D } from "./chunks/DataSource-DEg3igzS.js";
+import { k as P, l as U, g as c, h as m, A as u, C as x, i as B } from "./chunks/Algorithm-RQ629NLb.js";
+import { e as H, E as b, N as Y, a as F, P as W, R as k, S as K, d as v, b as w, c as Q } from "./chunks/NodeStyle-Cup9O1lu.js";
+import { A as j, a as q, G as z, i as J, b as Z } from "./chunks/GraphtyError-BwcnblTH.js";
+import { B as aa, a as sa, b as ea, C as Ea, G as ra, c as Oa, I as oa, O as Sa, d as Ra, e as _a, f as ta, P as La, g as Ca, h as Aa, R as Na, T as na, i as Ia, V as Ta, Y as ga } from "./chunks/sequential-Zym81qm7.js";
+import { a as la, G as da, V as pa, i as Ga } from "./chunks/GraphStyle-D0PXnZKu.js";
+import { c as ha } from "./chunks/common-DWNKjpH_.js";
 export {
-  K as ACCELERATION_ERROR_CODES,
-  j as ACCELERATION_MIN_NODES_DEFAULT,
-  q as ACCELERATION_MIN_NODES_KEY,
-  m as Algorithm,
+  j as ACCELERATION_ERROR_CODES,
+  P as ACCELERATION_MIN_NODES_DEFAULT,
+  U as ACCELERATION_MIN_NODES_KEY,
+  c as ACCELERATION_POLICIES,
+  m as ACCELERATION_POLICY_DEFAULT,
+  u as Algorithm,
   e as AlgorithmManager,
-  r as AnimationCancelledError,
-  Z as BLUES_COLORS,
-  $ as BLUE_HIGHLIGHT,
-  aa as BLUE_ORANGE_COLORS,
-  E as BUILTIN_PRESETS,
-  sa as CARBON_COLORS,
-  z as CPU_PRECISION,
-  pa as DEFAULT_VIEW_MODE,
+  E as AnimationCancelledError,
+  aa as BLUES_COLORS,
+  sa as BLUE_HIGHLIGHT,
+  ea as BLUE_ORANGE_COLORS,
+  r as BUILTIN_PRESETS,
+  Ea as CARBON_COLORS,
+  x as CPU_PRECISION,
+  la as DEFAULT_VIEW_MODE,
   O as DataManager,
-  h as DataSource,
-  u as EDGE_CONSTANTS,
+  y as DataSource,
+  H as EDGE_CONSTANTS,
   o as Edge,
-  x as EdgeStyle,
-  y as ErrorAggregator,
+  b as EdgeStyle,
+  D as ErrorAggregator,
   S as EventManager,
-  k as GRAPHTY_ERROR_CODES,
-  ea as GREENS_COLORS,
-  ra as GREEN_SUCCESS,
+  q as GRAPHTY_ERROR_CODES,
+  ra as GREENS_COLORS,
+  Oa as GREEN_SUCCESS,
   R as Graph,
-  Ia as GraphBackground,
-  t as Graphty,
-  v as GraphtyError,
-  Ea as INFERNO_COLORS,
-  _ as InputManager,
-  G as LayoutEngine,
+  da as GraphBackground,
+  _ as Graphty,
+  z as GraphtyError,
+  oa as INFERNO_COLORS,
+  t as InputManager,
+  p as LayoutEngine,
   L as LayoutManager,
   C as Node,
-  P as NodeShapes,
-  c as NodeStyle,
-  Oa as OKABE_ITO_COLORS,
-  oa as ORANGES_COLORS,
-  Sa as ORANGE_WARNING,
-  Ra as OTHER_GROUP_COLOR,
+  Y as NodeShapes,
+  F as NodeStyle,
+  Sa as OKABE_ITO_COLORS,
+  Ra as ORANGES_COLORS,
+  _a as ORANGE_WARNING,
+  ta as OTHER_GROUP_COLOR,
   A as OperationQueueManager,
-  ta as PASTEL_COLORS,
-  _a as PLASMA_COLORS,
-  La as PURPLE_GREEN_COLORS,
-  B as PolyhedronType,
-  Ca as RED_BLUE_COLORS,
+  La as PASTEL_COLORS,
+  Ca as PLASMA_COLORS,
+  Aa as PURPLE_GREEN_COLORS,
+  W as PolyhedronType,
+  Na as RED_BLUE_COLORS,
   N as RenderManager,
-  V as RichTextStyle,
-  H as SHAPE_CONSTANTS,
+  k as RichTextStyle,
+  K as SHAPE_CONSTANTS,
   n as ScreenshotError,
-  g as ScreenshotErrorCode,
+  I as ScreenshotErrorCode,
   T as SelectionManager,
-  l as SimpleLayoutConfig,
+  G as SimpleLayoutConfig,
   f as SimpleLayoutEngine,
-  p as StatsManager,
-  Aa as TOL_MUTED_COLORS,
-  Na as TOL_VIBRANT_COLORS,
-  I as UpdateManager,
-  da as VIEW_MODE_VALUES,
-  na as VIRIDIS_COLORS,
+  g as StatsManager,
+  na as TOL_MUTED_COLORS,
+  Ia as TOL_VIBRANT_COLORS,
+  i as UpdateManager,
+  pa as VIEW_MODE_VALUES,
+  Ta as VIRIDIS_COLORS,
   ga as YLORBR_COLORS,
-  la as colorToHex,
-  b as defaultEdgeStyle,
-  Y as defaultNodeStyle,
-  F as defaultRichTextLabelStyle,
-  d as defaultXRConfig,
-  w as isGraphtyError,
-  Q as isGraphtyErrorCode,
-  ia as isViewMode
+  ha as colorToHex,
+  v as defaultEdgeStyle,
+  w as defaultNodeStyle,
+  Q as defaultRichTextLabelStyle,
+  l as defaultXRConfig,
+  B as isAccelerationPolicy,
+  J as isGraphtyError,
+  Z as isGraphtyErrorCode,
+  Ga as isViewMode
 };

package/dist/index.d.ts

@@ -70,4 +70,4 @@ export { BUILTIN_PRESETS } from "./src/camera/presets";
 export type { AccelerationErrorCode, GraphtyErrorCode, GraphtyErrorInit, GraphtyErrorJson, GraphtyErrorSource, GraphtyErrorTarget, } from "./src/errors";
 export { ACCELERATION_ERROR_CODES, GRAPHTY_ERROR_CODES, GraphtyError, isGraphtyError, isGraphtyErrorCode, } from "./src/errors";
 export type { AccelerationCapabilities, AccelerationPolicy, AccelerationPrecision, AccelerationState, AccelerationStatus, AcceleratorDeviceInfo, AcceleratorFactory, AcceleratorFactoryOptions, CalibrationRecord, Capabilities, CaptureCapability, GraphAccelerator, Limits, WorkerCapability, XrCapability, } from "./src/acceleration";
-export { ACCELERATION_MIN_NODES_DEFAULT, ACCELERATION_MIN_NODES_KEY, CPU_PRECISION } from "./src/acceleration";
+export { ACCELERATION_MIN_NODES_DEFAULT, ACCELERATION_MIN_NODES_KEY, ACCELERATION_POLICIES, ACCELERATION_POLICY_DEFAULT, CPU_PRECISION, isAccelerationPolicy, } from "./src/acceleration";

package/dist/logging.js

@@ -1,5 +1,5 @@
-import { d as c, p } from "./chunks/GraphtyLogger-CK03SnJi.js";
-import { G, e as C, f as M, g as w, h as N, i as V, j as I, k as P, m as U, n as T, o as x } from "./chunks/GraphtyLogger-CK03SnJi.js";
+import { d as c, p } from "./chunks/GraphtyLogger-5KEttFUo.js";
+import { G, e as C, f as M, g as w, h as N, i as V, j as I, k as P, m as U, n as T, o as x } from "./chunks/GraphtyLogger-5KEttFUo.js";
 const g = "graphty-element-logging-config";
 function O(t) {
   try {

package/dist/schema.js

@@ -2,7 +2,7 @@ import { R as N, e as x } from "./chunks/types-B7bX5c0K.js";
 import { M as A, h as y, i as M } from "./chunks/interpolation-DY-PNpqX.js";
 import { B as D, a as U, b as B, C as P, G as H, c as V, I as $, O as w, d as F, e as W, f as Y, P as j, g as k, h as q, R as K, T as v, i as z, V as J, Y as Q } from "./chunks/sequential-Zym81qm7.js";
 import { D as Z, a as tt, G as nt, b as at, V as st, i as et } from "./chunks/GraphStyle-D0PXnZKu.js";
-import { E as rt, N as ct, a as it, R as Ot, d as St, b as Rt, c as lt } from "./chunks/NodeStyle-CS7dj20m.js";
+import { E as rt, N as ct, a as it, R as Ot, d as St, b as Rt, c as lt } from "./chunks/NodeStyle-Cup9O1lu.js";
 import { c as ft } from "./chunks/common-DWNKjpH_.js";
 function l(t) {
   const n = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(t);

package/dist/session.d.ts

@@ -93,7 +93,8 @@ export type { Binding, BindingOverflow, Channel, EdgeId, Encoding, FieldDescript
 export { isResultShape, RESULT_SHAPES } from "./src/catalog/types";
 export type { ChannelExplanation, ElementLayerSpec, EncodingRun, EncodingSpec, ExplainTarget, FieldWords, HighlightSpec, Layer, LayerPosition, LayerProblem, LegendBlock, LegendSwatch, RepaintReason, RepaintReport, SessionStylesApi, StyleChange, StyleContribution, StyleExplanation, StylesApi, TemplateOptions, TemplateReport, UnboundLayer, ValidationResult, } from "./src/session/styles";
 export { quotePath } from "./src/session/styles";
-export type { AccelerationCapabilities, AccelerationPolicy, AccelerationState, AccelerationStatus, Capabilities, CaptureCapability, Limits, WorkerCapability, XrCapability, } from "./src/acceleration";
+export type { AccelerationCapabilities, AccelerationPolicy, AccelerationPrecision, AccelerationState, AccelerationStatus, AcceleratorDeviceInfo, Capabilities, CaptureCapability, GraphAccelerator, Limits, WorkerCapability, XrCapability, } from "./src/acceleration";
+export { ACCELERATION_POLICIES, ACCELERATION_POLICY_DEFAULT, isAccelerationPolicy, } from "./src/acceleration";
 export type { DefaultableLimits } from "./src/session";
 export { DEFAULT_LIMITS } from "./src/session";
 export type { AccelerationErrorCode, GraphtyErrorCode, GraphtyErrorInit, GraphtyErrorJson, GraphtyErrorSource, GraphtyErrorTarget, } from "./src/errors";

package/dist/session.js

@@ -1,9 +1,10 @@
-import { R, e as c } from "./chunks/types-B7bX5c0K.js";
-import { A, a as g, G as m, i as C, b as O } from "./chunks/GraphtyError-B3eKs4yg.js";
-import { D as h } from "./chunks/GraphSession-D87eymV8.js";
-import { a as U, b as y, c as N, Q as I, R as P, d as D, e as w, S as b, T as v, f as G, i as x, g as z, h as F, j as M } from "./chunks/GraphSession-D87eymV8.js";
-import { R as H, w as k, x as Y, y as q, z as Q, A as X } from "./chunks/paletteRegistry-B-oS4YxP.js";
-import { a as n } from "./chunks/scales-DvGid5Ln.js";
+import { R as A, e as R } from "./chunks/types-B7bX5c0K.js";
+import { A as _, a as C, G as g, i as m, b as L } from "./chunks/GraphtyError-BwcnblTH.js";
+import { g as U, h as I, i as N } from "./chunks/Algorithm-RQ629NLb.js";
+import { D as h } from "./chunks/GraphSession-CtqyVNsw.js";
+import { a as y, b as D, c as w, Q as b, R as v, d as G, e as x, S as z, T as F, f as M, i as j, g as H, h as Y, j as k } from "./chunks/GraphSession-CtqyVNsw.js";
+import { R as Q, w as X, x as B, y as J, z as K, A as V } from "./chunks/paletteRegistry-NrWOKT-A.js";
+import { a as n } from "./chunks/scales-BUS7NWy2.js";
 const u = Object.freeze({
   /** Above this node count the element draws less visual detail. A shipped default, not measured. */
   largeGraphThreshold: 1e4,
@@ -64,34 +65,37 @@ function f(e, a = {}) {
   });
 }
 export {
-  A as ACCELERATION_ERROR_CODES,
-  U as DEFAULT_COST_GATE_LIMITS,
-  y as DEFAULT_EXACT_COMPUTATION_CAP_SECONDS,
+  _ as ACCELERATION_ERROR_CODES,
+  U as ACCELERATION_POLICIES,
+  I as ACCELERATION_POLICY_DEFAULT,
+  y as DEFAULT_COST_GATE_LIMITS,
+  D as DEFAULT_EXACT_COMPUTATION_CAP_SECONDS,
   u as DEFAULT_LIMITS,
-  N as DEFAULT_SCOPE_SAMPLE,
+  w as DEFAULT_SCOPE_SAMPLE,
   h as DEFAULT_SELECTION_CAP,
-  g as GRAPHTY_ERROR_CODES,
-  m as GraphtyError,
-  I as QUEUE_POLICIES,
-  H as RESULT_FIELD_NAMES,
-  k as RESULT_ROOT,
-  R as RESULT_SHAPES,
-  Y as RESULT_SHAPE_CONTRACTS,
-  P as RUN_ID_PATTERN,
-  D as RUN_PHASES,
-  w as RUN_STATUSES,
-  b as SET_OPS,
-  v as TERMINAL_RUN_STATUSES,
-  G as createGraphSession,
-  q as defaultReading,
-  x as isAlgorithmRunCommand,
-  C as isGraphtyError,
-  O as isGraphtyErrorCode,
-  c as isResultShape,
-  z as isRunId,
-  F as isRunStatus,
-  M as isTerminalRunStatus,
-  Q as quotePath,
+  C as GRAPHTY_ERROR_CODES,
+  g as GraphtyError,
+  b as QUEUE_POLICIES,
+  Q as RESULT_FIELD_NAMES,
+  X as RESULT_ROOT,
+  A as RESULT_SHAPES,
+  B as RESULT_SHAPE_CONTRACTS,
+  v as RUN_ID_PATTERN,
+  G as RUN_PHASES,
+  x as RUN_STATUSES,
+  z as SET_OPS,
+  F as TERMINAL_RUN_STATUSES,
+  M as createGraphSession,
+  J as defaultReading,
+  N as isAccelerationPolicy,
+  j as isAlgorithmRunCommand,
+  m as isGraphtyError,
+  L as isGraphtyErrorCode,
+  R as isResultShape,
+  H as isRunId,
+  Y as isRunStatus,
+  k as isTerminalRunStatus,
+  K as quotePath,
   f as recommendLayout,
-  X as resultPath
+  V as resultPath
 };

package/dist/src/Edge.d.ts

@@ -249,7 +249,7 @@ export declare class Edge {
      * (it disposes a per-element ShaderMaterial that Babylon's default flags would leave behind),
      * so it is routed to that rather than to `AbstractMesh.dispose`.
      *
-     * A DISPOSED EDGE STILL RECEIVES CALLS, which is why {@link Edge.disposed} exists: the layout
+     * A DISPOSED EDGE STILL RECEIVES CALLS, which is why {@link Edge.isDisposed} exists: the layout
      * engine keeps its own edge list and `UpdateManager` walks it every frame regardless of what
      * DataManager holds. Calling this twice is safe.
      */

package/dist/src/Graph.d.ts

@@ -4,6 +4,7 @@ import "./algorithms/index";
 import "@babylonjs/core/Culling/ray";
 import "@babylonjs/core/Animations/animatable";
 import { AbstractMesh, Engine, Scene, WebGPUEngine, WebXRDefaultExperience } from "@babylonjs/core";
+import { AccelerationController } from "./acceleration";
 import { VoiceInputAdapter } from "./ai/input/VoiceInputAdapter";
 import type { ApiKeyManager } from "./ai/keys";
 import type { CameraState } from "./camera/types.js";
@@ -49,6 +50,16 @@ export declare class Graph implements GraphContext {
     enableDetailedProfiling?: boolean;
     private wasSettled;
     private resizeHandler;
+    /**
+     * The one acceleration controller this graph, its session and its element share.
+     *
+     * Built here because it is the earliest owner both the element's `acceleration` attribute and
+     * the session can reach: the element builds its Graph in its own constructor, before Lit has
+     * parsed an attribute, and the Graph builds the session in its. It is disposed by
+     * {@link shutdown}, so it lives and dies with the graph.
+     * @since 2.0.0
+     */
+    readonly acceleration: AccelerationController;
     /** Event manager for adding/removing event listeners */
     readonly eventManager: EventManager;
     private renderManager;
@@ -94,6 +105,20 @@ export declare class Graph implements GraphContext {
      * Shuts down the graph, stopping animations and disposing all resources.
      */
     shutdown(): void;
+    /**
+     * Frees the accelerator's device buffers for a snapshot the graph has stopped showing.
+     *
+     * `release` is feature-tested, never required: `GraphAccelerator` declares it through the index
+     * signature, so a third party may implement one layout and no residency at all. The undirected
+     * copy is released beside the snapshot because that is the copy the device usually holds -- a
+     * layout simulation loads the undirected view of every snapshot -- and is skipped when the
+     * graph is undirected already, where the two are one object.
+     * @param snapshot - The snapshot to release; null before the first freeze, and nothing is done.
+     * @param undirected - Its undirected copy, when the caller already holds it. Left out, it is
+     * looked up here -- and only once there is something to release it to, so a graph running on
+     * the CPU never derives a copy nobody asked for.
+     */
+    private releaseSnapshot;
     /**
      * Executes all algorithms specified in the style template configuration.
      */
@@ -251,7 +276,7 @@ export declare class Graph implements GraphContext {
      * @returns Promise that resolves when nodes are added
      * @since 1.0.0
      * @see {@link addEdges} for adding edges
-     * @see {@link https://graphty.app/storybook/element/?path=/story/data--default | Data Loading Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/data--basic | Data Loading Examples}
      * @example
      * ```typescript
      * // Add nodes with default ID field
@@ -296,7 +321,7 @@ export declare class Graph implements GraphContext {
      * @returns Promise that resolves when edges are added
      * @since 1.0.0
      * @see {@link addNodes} for adding nodes first
-     * @see {@link https://graphty.app/storybook/element/?path=/story/data--default | Data Loading Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/data--basic | Data Loading Examples}
      * @example
      * ```typescript
      * // Add edges with default source/target fields
@@ -350,8 +375,8 @@ export declare class Graph implements GraphContext {
      * @returns Promise that resolves when layout is initialized
      * @since 1.0.0
      * @see {@link waitForSettled} to wait for layout completion
-     * @see {@link https://graphty.app/storybook/element/?path=/story/layout--default | 3D Layout Examples}
-     * @see {@link https://graphty.app/storybook/element/?path=/story/layout2d--default | 2D Layout Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/layout-3d--circular | 3D Layout Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/layout-2d--circular | 2D Layout Examples}
      * @example
      * ```typescript
      * // Use force-directed layout with custom settings
@@ -398,8 +423,8 @@ export declare class Graph implements GraphContext {
      * @since 1.0.0
      * @see {@link Graph.run} for the verb that replaces this one
      * @see {@link applySuggestedStyles} to visualize results
-     * @see {@link https://graphty.app/storybook/element/?path=/story/algorithms-centrality--degree | Centrality Examples}
-     * @see {@link https://graphty.app/storybook/element/?path=/story/algorithms-community--louvain | Community Detection}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/algorithms-centrality--degree | Centrality Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/algorithms-community--louvain | Community Detection}
      * @example
      * ```typescript
      * // This entry point starts the work and hands nothing back. Everything below reads the
@@ -721,6 +746,12 @@ export declare class Graph implements GraphContext {
      * @returns The EventManager instance
      */
     getEventManager(): EventManager;
+    /**
+     * Get the acceleration controller this graph owns, for a manager reached through GraphContext.
+     * @returns The acceleration controller
+     * @since 2.0.0
+     */
+    getAcceleration(): AccelerationController;
     /**
      * Get the currently selected node.
      *
@@ -750,7 +781,7 @@ export declare class Graph implements GraphContext {
      * @since 1.0.0
      * @see {@link deselectNode} to clear selection
      * @see {@link getSelectedNode} to get current selection
-     * @see {@link https://graphty.app/storybook/element/?path=/story/selection--default | Selection Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/selection--mode-3-d | Selection Examples}
      * @example
      * ```typescript
      * // Select a node and show its details
@@ -919,6 +950,9 @@ export declare class Graph implements GraphContext {
     isRunning(): boolean;
     /**
      * Set whether the layout engine should run.
+     *
+     * Resuming a simulation layout that had settled restarts it, so "play" moves nodes again;
+     * pausing stops the per-frame stepping and nothing else.
      * @param running - True to start the layout, false to stop it
      */
     setRunning(running: boolean): void;

package/dist/src/Node.d.ts

@@ -263,7 +263,7 @@ export declare class Node {
      * `removeFromHighlight` call below is what is safe to do: it removes THIS mesh, which for an
      * instanced node the layer never held.
      *
-     * A DISPOSED NODE STILL RECEIVES CALLS, which is why {@link Node.disposed} exists rather than
+     * A DISPOSED NODE STILL RECEIVES CALLS, which is why the private `disposed` flag exists rather than
      * this method simply freeing things. `DataManager.clear()` does not notify the layout engine
      * (its own standing TODO), so `UpdateManager` keeps iterating the engine's node and edge
      * lists; and `SelectionManager.selectedNode` holds a Node across a dataset boundary and calls

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

@@ -129,9 +129,18 @@ export declare class AccelerationController {
     get status(): AccelerationStatus;
     /**
      * The published capabilities subset, which is the `graphty-capabilities-change` detail.
+     *
+     * The same object is returned until the next transition, so `prev === next` is a valid
+     * staleness test for a reader that caches it.
      * @returns The capabilities the acceleration subsystem publishes.
      */
     get capabilities(): AccelerationCapabilities;
+    /**
+     * Whether {@link dispose} has already run, so a caller can skip {@link start} on a
+     * controller whose graph has been shut down.
+     * @returns True once the controller has been disposed.
+     */
+    get disposed(): boolean;
     /**
      * The one-word state, for a caller that wants only that.
      * @returns The state.
@@ -234,6 +243,24 @@ export declare class AccelerationController {
      * (`AbortError`, `TimeoutError`) propagates unchanged.
      */
     run<T>(work: AcceleratedWork, fn: (accelerator: GraphAccelerator) => T | Promise<T>): Promise<AccelerationOutcome<T>>;
+    /**
+     * Marks the start of a span of accelerated work that this controller does not itself drive.
+     *
+     * {@link run} covers work shaped like a call: one function, one promise, `"active"` for as
+     * long as it takes. A simulation is not shaped like that -- the element hands the graph to
+     * the accelerator once and then steps it every frame until the arrangement settles -- so the
+     * layout bridge marks the span instead. Without it the state a consumer reads would say
+     * `"idle"`, which its own documentation defines as nothing using the accelerator, for the
+     * whole of a GPU layout.
+     *
+     * Counted the way `run()` is: spans overlap freely and the state falls back to `"idle"` when
+     * the last one ends. The returned function is idempotent, so a caller may end its span at a
+     * settle and again at a dispose without counting out twice. On a disposed controller the
+     * call is a no-op rather than a throw: there is no state left to publish, and a frame loop is
+     * the wrong place for a shutdown to surface.
+     * @returns Ends the span.
+     */
+    beginWork(): () => void;
     /**
      * Releases the accelerator and stops publishing.
      *

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

@@ -9,4 +9,4 @@ export { AccelerationController } from "./AccelerationController";
 export type { AcceleratorRegistration, RegisterAcceleratorOptions } from "./registry";
 export { AcceleratorRegistry, acceleratorRegistry, registerAccelerator } from "./registry";
 export type { AccelerationCapabilities, AccelerationPolicy, AccelerationPrecision, AccelerationState, AccelerationStatus, AcceleratorDeviceInfo, AcceleratorFactory, AcceleratorFactoryOptions, CalibrationRecord, Capabilities, CaptureCapability, GraphAccelerator, Limits, WorkerCapability, XrCapability, } from "./types";
-export { ACCELERATION_MIN_NODES_DEFAULT, ACCELERATION_MIN_NODES_KEY, CPU_PRECISION, DEFAULT_ACCELERATOR_PRECISION, } from "./types";
+export { ACCELERATION_MIN_NODES_DEFAULT, ACCELERATION_MIN_NODES_KEY, ACCELERATION_POLICIES, ACCELERATION_POLICY_DEFAULT, CPU_PRECISION, DEFAULT_ACCELERATOR_PRECISION, isAccelerationPolicy, } from "./types";

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

@@ -0,0 +1,56 @@
+/**
+ * @file Narrowing the element's accelerator to the seam a CPU package's dispatcher feature-tests.
+ *
+ * The element attaches ONE {@link GraphAccelerator}, whose accelerated members are open-ended:
+ * `webgpu.ts` forwards every callable the peer implements by name, so the object grows a member
+ * each time the GPU package ports another layout or algorithm and the element needs no edit.
+ * The CPU packages' dispatchers take a narrower thing -- `@graphty/layout`'s `LayoutAccelerator`
+ * is three optional layout members plus `release`, and `@graphty/algorithms`'s
+ * `AlgorithmAccelerator` is one optional member per algorithm -- and they decide CPU or
+ * accelerator by asking whether the member EXISTS (`accelerator?.forceAtlas2 !== undefined` in
+ * `createSimulation`, `acc?.pageRank !== undefined` in `accelerated`).
+ *
+ * That is why this copies only the members that are functions rather than spelling out
+ * `forceAtlas2: accelerator.forceAtlas2` for each: an accelerator that implements ForceAtlas2 and
+ * nothing else must hand the dispatcher an object with no `fruchtermanReingold` key at all, which
+ * is the GPU package's own rule for its accelerator ("an unimplemented member must not exist").
+ * A key present and undefined would read as implemented to anything testing with `in`.
+ *
+ * `dispose` is never copied. The element's controller owns the accelerator's lifetime -- it
+ * disposes one it built and leaves an injected one alone -- and a layout that could dispose the
+ * device out from under the next run would take that decision away from it.
+ */
+import type { AlgorithmAccelerator } from "@graphty/algorithms";
+import type { LayoutAccelerator } from "@graphty/layout";
+import type { GraphAccelerator } from "./types";
+/**
+ * Narrows the attached accelerator to the layout seam `createSimulation` feature-tests.
+ *
+ * The returned object is fresh on every call and holds only the members the accelerator actually
+ * implements, each bound to it, so a simulation built from it keeps working however the caller
+ * stores it.
+ * @param accelerator - The accelerator the controller has attached.
+ * @returns The layout half of it, for `createSimulation`'s third argument.
+ * @example
+ * ```ts
+ * const decision = controller.plan({ capability: "forceAtlas2", nodeCount });
+ * const simulation = createSimulation("forceatlas2", options, decision.accelerated ? narrowLayout(decision.accelerator) : null);
+ * ```
+ */
+export declare function narrowLayout(accelerator: GraphAccelerator): LayoutAccelerator;
+/**
+ * Narrows the attached accelerator to the algorithm seam `accelerated()` feature-tests.
+ *
+ * The returned object is fresh on every call and holds only the members the accelerator actually
+ * 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.
+ * @returns The algorithm half of it, for `accelerated()`.
+ * @example
+ * ```ts
+ * const outcome = await controller.run({ capability: "pageRank", nodeCount }, (acc) =>
+ *     accelerated(narrowAlgorithms(acc)).pageRank(snapshot, options),
+ * );
+ * ```
+ */
+export declare function narrowAlgorithms(accelerator: GraphAccelerator): AlgorithmAccelerator;