@graphty/graphty-element 2.0.1 → 2.2.0

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

@@ -1,42 +1,32 @@
-import { z } from "zod/v4";
+/**
+ * @file The Spring layout: Fruchterman-Reingold, computed on the CPU or on an accelerator.
+ *
+ * It used to be a one-shot pass -- run `springLayout` over a node and edge list, publish the
+ * answer, stop -- which is why the catalogue called it a batch layout. It is now a steppable
+ * simulation from `@graphty/layout`, so it keeps running until the arrangement settles and reheats
+ * on a drag or a pin, and the element decides at every load whether the simulation is the CPU's or
+ * the accelerator's.
+ */
+import type { SimulationType } from "@graphty/layout";
 import { type OptionsSchema } from "../config";
-import { SimpleLayoutEngine } from "./LayoutEngine";
-declare const SpringLayoutConfig: z.ZodObject<{
-    k: z.ZodDefault<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
-    pos: z.ZodDefault<z.ZodUnion<[z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodNumber>>, z.ZodNull]>>;
-    fixed: z.ZodDefault<z.ZodUnion<[z.ZodArray<z.ZodNumber>, z.ZodNull]>>;
-    iterations: z.ZodDefault<z.ZodNumber>;
-    scale: z.ZodDefault<z.ZodNumber>;
-    center: z.ZodDefault<z.ZodUnion<[z.ZodArray<z.ZodNumber>, z.ZodNull]>>;
-    dim: z.ZodDefault<z.ZodNumber>;
-    seed: z.ZodDefault<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
-    scalingFactor: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strict>;
-type SpringLayoutConfigType = z.infer<typeof SpringLayoutConfig>;
-type SpringLayoutOpts = Partial<SpringLayoutConfigType>;
+import { SimulationLayoutEngine } from "./SimulationLayoutEngine";
 /**
- * Spring layout engine using Fruchterman-Reingold force-directed algorithm
+ * The Spring engine, as the element declares it.
+ *
+ * Every member is a static the element reads: `LayoutManager` builds the bridge itself, with the
+ * graph's acceleration controller, so this class never runs a layout of its own. It declares no
+ * `static descriptor` because its arrangement is authored in the layout catalogue, where it sits
+ * under `force`.
  */
-export declare class SpringLayout extends SimpleLayoutEngine {
+export declare class SpringLayout extends SimulationLayoutEngine {
     static type: string;
+    static simulationType: SimulationType;
     static maxDimensions: number;
     static zodOptionsSchema: OptionsSchema;
-    scalingFactor: number;
-    config: SpringLayoutConfigType;
-    /**
-     * Create a spring layout engine
-     * @param opts - Configuration options including spring constant and iterations
-     */
-    constructor(opts: SpringLayoutOpts);
     /**
-     * Get dimension-specific options for spring layout
-     * @param dimension - The desired dimension (2 or 3)
-     * @returns Options object with dim parameter
+     * Get dimension-specific options for spring layout.
+     * @param dimension - The desired dimension (2 or 3).
+     * @returns Options object with dim parameter.
      */
     static getOptionsForDimension(dimension: 2 | 3): object;
-    /**
-     * Compute node positions using spring-based force simulation
-     */
-    doLayout(): void;
 }
-export {};

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

@@ -95,6 +95,13 @@ export declare class EventManager implements Manager {
      * @param report - freezeWithReport's report
      */
     emitSnapshotReplaced(graph: Graph | GraphContext, previous: GraphSnapshot | null, next: GraphSnapshot, report: FreezeReport): void;
+    /**
+     * Emit `snapshot-dropped`: the store was discarded and every snapshot it froze is gone.
+     *
+     * ELEMENT-INTERNAL, for the same reason `snapshot-replaced` is. Emitted while the outgoing
+     * store is still alive, so a listener releasing a snapshot can still derive from it.
+     */
+    emitSnapshotDropped(): void;
     /**
      * Emits a layout initialized event when a layout is ready
      * @param layoutType - Type of layout that was initialized

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

@@ -1,4 +1,5 @@
 import type { Scene } from "@babylonjs/core";
+import type { AccelerationController } from "../acceleration";
 import type { XRConfig } from "../config/XRConfig";
 import type { MeshCache } from "../meshes/MeshCache";
 import type { Styles } from "../Styles";
@@ -92,6 +93,11 @@ export interface GraphContext {
      * @since 1.5.0
      */
     getEventManager?(): EventManager | undefined;
+    /**
+     * The acceleration controller the graph owns; absent on a context built without a graph.
+     * @since 2.0.0
+     */
+    getAcceleration?(): AccelerationController;
 }
 /**
  * Configuration options accessible through GraphContext

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

@@ -1,11 +1,37 @@
+import type { SimulationType } from "@graphty/layout";
+import type { GraphLayoutBehavior } from "../config/GraphBehavior";
 import type { Edge } from "../Edge";
 import { LayoutEngine } from "../layout/LayoutEngine";
+import { type SimulationEngineOptions } from "../layout/SimulationLayoutEngine";
 import type { Node } from "../Node";
 import type { Styles } from "../Styles";
 import type { DataManager } from "./DataManager";
 import type { EventManager } from "./EventManager";
 import type { GraphContext } from "./GraphContext";
 import type { Manager } from "./interfaces";
+/**
+ * Turn what the consumer asked a simulation layout for into what the bridge runs on.
+ *
+ * `scalingFactor` travels twice over, and deliberately. The simulation gets it as `scale`, where
+ * it sizes the seed and, in ForceAtlas2, the units the arrangement is computed in; the BRIDGE gets
+ * it as the radius it publishes that arrangement at, which is the only one of the two a reader
+ * sees in the picture. A layout that publishes no such control takes
+ * {@link DEFAULT_SCALING_FACTOR}. What the bridge is given is {@link publishedRadius}, every
+ * size multiplier the layout publishes rolled into one, because the refit fits the arrangement to
+ * that radius and leaves no other way for a reader to change how big the graph comes out.
+ *
+ * The four knobs the frame loop needs -- `iterationsPerStep`, `maxInFlight`, `settleThreshold` and
+ * `settleWindow` -- are NOT in any layout's published schema, because they are the same four for
+ * every simulation and belong to how the element drives one rather than to the arrangement it
+ * draws. They are read from the options a caller passed, where a per-layout value overrides the
+ * behaviour configuration, and `behavior.layout` is where a host sets them once for every layout.
+ * @param type - Which simulation is being configured.
+ * @param options - The merged layout options, as the consumer set them.
+ * @param behavior - `behavior.layout`, which the frame-loop knobs default from.
+ * @returns The resolved options.
+ * @throws A `ZodError` when an option is outside the range its published schema declares.
+ */
+export declare function resolveSimulationOptions(type: SimulationType, options: Record<string, unknown>, behavior: GraphLayoutBehavior): SimulationEngineOptions;
 /**
  * Manages layout engines and their lifecycle
  * Coordinates layout updates and transitions
@@ -34,10 +60,27 @@ export declare class LayoutManager implements Manager {
      */
     get running(): boolean;
     /**
-     * Sets the running state of the layout
+     * Sets the running state of the layout.
+     *
+     * Going false -> true is "play", and a simulation that had SETTLED does nothing when it is
+     * stepped, so a reader who pressed play -- or let go of a node they dragged -- would watch a
+     * still graph. Resuming therefore reheats a settled simulation: the settle count starts
+     * again and the next frame moves nodes. Going true -> false only stops `step()` being
+     * called; batches already in flight land in the position array by themselves, nothing is
+     * disposed and nothing is released.
      */
     set running(value: boolean);
     private graphContext;
+    /**
+     * The graph's acceleration controller, once a context has arrived. A manager built without a
+     * graph -- which is what the manager's own unit tests build -- never gets one, and a
+     * simulation layout refuses to start on one.
+     */
+    private acceleration;
+    /** How to stop listening to the controller. */
+    private unsubscribeAcceleration;
+    /** How to stop listening for a new snapshot. */
+    private unsubscribeSnapshot;
     /**
      * Creates an instance of LayoutManager
      * @param eventManager - Event manager for emitting layout events
@@ -47,9 +90,33 @@ export declare class LayoutManager implements Manager {
     constructor(eventManager: EventManager, dataManager: DataManager, styles: Styles);
     /**
      * Set the GraphContext for error reporting
+     *
+     * This is also where the acceleration controller first becomes reachable: the manager is
+     * built before the graph finishes constructing itself, so it cannot be handed one.
      * @param context - GraphContext instance
      */
     setGraphContext(context: GraphContext): void;
+    /**
+     * Rebuild a running simulation on whatever the controller holds now.
+     *
+     * Every transition reaches here: an accelerator attached, detached, lost or recovered. The
+     * try is load-bearing. Under the `required` policy a detach cannot reach a CPU simulation --
+     * the controller's `plan()` throws `E_NO_ACCELERATOR` instead, which is the point of the
+     * policy -- and the throw has to be REPORTED here rather than escaping into the controller's
+     * listener loop, whose own catch would log it and continue. The layout then stops, and the
+     * next transition that attaches an accelerator brings it back.
+     */
+    private onAccelerationChange;
+    /**
+     * Hand a running simulation the snapshot that has just replaced the one it was laying out.
+     * @param event - The freeze, carrying the snapshot every consumer must switch to.
+     */
+    private onSnapshotReplaced;
+    /**
+     * Report a failure that happened to a layout already running, on the element's error channel.
+     * @param error - Whatever was thrown.
+     */
+    private reportSimulationFailure;
     /**
      * Update the styles reference when a new style template is loaded
      * @param styles - New styles instance
@@ -103,6 +170,9 @@ export declare class LayoutManager implements Manager {
      * @param type - The layout that failed.
      * @param error - Whatever was thrown.
      * @param phase - What the element was doing, in a word that fits "the layout could not be ...".
+     * `"stepped"` is the one that happens to a layout already running: a simulation's batch
+     * rejected minutes after set-up finished, and calling that "initialised" reads as a failure
+     * to start.
      * @returns The error to throw.
      */
     private reportLayoutFailure;
@@ -120,7 +190,19 @@ export declare class LayoutManager implements Manager {
      * `preSteps` is what makes a screenshot of a physics layout the same picture twice: an
      * unstepped force layout is a graph in mid-flight, and how far it has flown depends on when
      * the picture was taken.
+     *
+     * A SIMULATION CANNOT BE STEPPED IN A TIGHT SYNCHRONOUS LOOP, which is why this is
+     * asynchronous and why both the path that spends the pre-steps when a layout is built and the
+     * path that pays owed ones later come through here rather than each writing their own loop. A
+     * simulation's step is a BATCH: an accelerated one is fire-and-forget, and a simulation that
+     * already has a few batches in flight returns the oldest of them instead of submitting
+     * another, so a loop that calls `step()` a thousand times without waiting has all but the
+     * first couple coalesced away and draws a graph the consumer asked to be far more arranged
+     * than it is -- silently, because a coalesced batch is not an error. So a simulation is
+     * awaited one chunk at a time, the chunk being the largest batch the GPU package takes, and
+     * every other engine keeps the plain loop, whose `step()` returns having done the work.
      * @param engine - the engine to settle.
+     * @returns A promise that resolves once every pre-step has been taken and published.
      */
     private spendPreSteps;
     /**
@@ -136,15 +218,27 @@ export declare class LayoutManager implements Manager {
      *
      * So the count is owed rather than spent, and paid here: on the first frame at which there is
      * a node to move. This runs inside the render loop's update, which is called before
-     * `scene.render()`, so the steps really are taken before the frame is drawn -- and because it
-     * waits for a node rather than for a particular call, it does not matter whether the data
-     * arrived in one batch, in ten, or from a fetch that finished a second later.
+     * `scene.render()`, so an engine that steps on the spot really is stepped before the frame is
+     * drawn -- and because it waits for a node rather than for a particular call, it does not
+     * matter whether the data arrived in one batch, in ten, or from a fetch that finished a
+     * second later. A simulation's batches land over the next few frames instead, because no
+     * caller inside a render loop can wait for a device; what {@link LayoutManager.spendPreSteps}
+     * guarantees for one is that every owed iteration is computed rather than coalesced away.
      */
     private runPreStepsOnceThereIsSomethingToStep;
     /**
      * Step the layout engine forward
      */
     step(): void;
+    /**
+     * Step the layout ONCE, whatever the frame loop's multiplier is.
+     *
+     * The name is the difference a reader of `UpdateManager` needs: a simulation layout does its
+     * whole frame's work in one call -- the batch it submits computes `iterationsPerStep`
+     * iterations -- so stepping it `stepMultiplier` times a frame would queue work the device
+     * cannot retire.
+     */
+    stepBatch(): void;
     /**
      * Get node position from layout engine
      * @param node - Node to get position for

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

@@ -23,6 +23,13 @@ export declare class RenderManager implements Manager {
     private renderLoopActive;
     private updateCallback?;
     private resizeHandler;
+    /**
+     * Stands in for Babylon's own pointer handling, which calls preventDefault and then
+     * `canvas.focus()` on every pointer down and up. That focus call scrolls the host page to the
+     * canvas. This one does the same thing without scrolling.
+     * @param evt - The pointer down or up event on the canvas
+     */
+    private focusOnPointer;
     /**
      * Creates a new render manager for Babylon.js scene and rendering
      * @param canvas - HTML canvas element for rendering

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

@@ -330,7 +330,7 @@ export declare class UpdateManager implements Manager {
     /**
      * Update the graph for the current frame.
      *
-     * The pass itself is {@link UpdateManager.runUpdatePass}; what is added here is the one
+     * The pass itself is the private `runUpdatePass()`; what is added here is the one
      * question a consumer cares about and the pass has several exits from -- whether the state it
      * leaves behind is a finished picture.
      */

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

@@ -29,8 +29,8 @@
  * already been run here. So a session's catalogue is the shared tables with its own `metrics()`
  * closed over its own graph.
  *
- * The rest of the graph-dependent half -- resolved option bounds, expression validation -- still
- * waits on the query engine.
+ * The rest of the graph-dependent half -- resolved option bounds, expression validation -- is not
+ * wired to the session's query engine yet.
  */
 import type { AlgorithmDescriptor } from "../catalog/types";
 import { type MetricsSource } from "./metrics";

package/dist/src/session/query.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @file The session's one query engine: `{ where }` predicates and text search.
+ *
+ * A scope, a selection, a visibility filter and an edge filter all accept an expression, and a
+ * selection also accepts typed text. Every one of them reaches THIS object, and this object
+ * evaluates an expression with the compiler the style layers use (`./styles/predicate`) over the
+ * selector source the style layers read (`./styles/sources`). That is the point of it: a layer
+ * selector and a scope with the same text match the same elements, because they are the same
+ * code reading the same values. A second evaluator would drift from the first in exactly the
+ * places nobody tests -- JMESPath truthiness, a column default, an edge's endpoints.
+ *
+ * A path nothing answers matches nothing and is REPORTED through `unresolvedPathsOf`, never
+ * swallowed: "0 matched" and "you misspelled the attribute" must not look the same.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import type { GraphSnapshot } from "@graphty/graph-format";
+import type { EdgeId, NodeId, Path, Query } from "../catalog/types";
+import type { SelectionMatch, SelectionSearchHit, SelectionTextMode } from "./selection";
+import { type SelectorSource, type SelectorTarget } from "./styles/predicate";
+/** Everything the engine reads. */
+interface QueryEngineParts {
+    /**
+     * The snapshot the dense indices address, read on every query.
+     * @returns The snapshot as it stands now.
+     */
+    readonly snapshot: () => GraphSnapshot;
+    /** Where values are read: the same source the style layers read. */
+    readonly elements: Required<Pick<SelectorSource, "edgeIdOf" | "nodeIdOf">> & SelectorSource;
+    /**
+     * Whether this session answers a path for one kind of element. Absent, no path is reported.
+     * @param path - The path as the query spelled it.
+     * @param target - Which kind of element.
+     * @returns True when something in the session answers it.
+     */
+    readonly answers?: (path: Path, target: SelectorTarget) => boolean;
+    /**
+     * The node attribute paths a text search reads, beside the id.
+     * @returns The paths, such as `data.label`.
+     */
+    readonly searchPaths: () => readonly Path[];
+}
+/** The session's query engine. */
+export interface QueryEngine {
+    /**
+     * The nodes an expression matches.
+     * @param where - The expression.
+     * @returns The node ids, in index order.
+     */
+    nodes(where: Query): NodeId[];
+    /**
+     * The edges an expression matches.
+     * @param where - The expression.
+     * @returns The edge ids, in index order.
+     */
+    edges(where: Query): EdgeId[];
+    /**
+     * Both halves an expression matches, and the paths it names that nothing answers.
+     * @param where - The expression.
+     * @returns The match.
+     */
+    select(where: Query): SelectionMatch;
+    /**
+     * The paths an expression names that no node and no edge in this session answers.
+     * @param where - The expression.
+     * @returns The unresolved paths.
+     */
+    unresolvedPathsOf(where: Query): readonly Path[];
+    /**
+     * The nodes a text search finds.
+     * @param text - What was typed.
+     * @param mode - How to match it.
+     * @returns The hits, in index order.
+     */
+    find(text: string, mode: SelectionTextMode): SelectionSearchHit[];
+}
+/**
+ * Build the query engine over a session's selector source.
+ * @param parts - The snapshot, the value source, the path directory and the searchable paths.
+ * @returns The engine.
+ */
+export declare function createQueryEngine(parts: QueryEngineParts): QueryEngine;
+export {};

package/dist/src/session/runs/types.d.ts

@@ -465,10 +465,16 @@ export interface Run<T = RunResult> extends PromiseLike<T> {
     readonly shape: ResultShape;
     /** What qualifies the numbers. */
     readonly caveats: Caveats;
-    /** The result, once there is one. Awaiting the run is the other way to get it. */
-    readonly result?: T;
-    /** Why it failed, when it failed. */
-    readonly error?: GraphtyError;
+    /**
+     * The result, once there is one. Awaiting the run is the other way to get it.
+     *
+     * Spelled `?: T | undefined` rather than `?: T` because the implementation answers with a
+     * getter, and under a consumer's `exactOptionalPropertyTypes` a getter that can return
+     * undefined does not satisfy a property that can only be absent or present.
+     */
+    readonly result?: T | undefined;
+    /** Why it failed, when it failed. Optional-or-undefined for the reason {@link Run.result} gives. */
+    readonly error?: GraphtyError | undefined;
     /** The frozen, structured-cloneable snapshot of everything above. */
     readonly record: RunRecord;
     /** The journal entry this run's command wrote, or null until it lands. */

package/dist/src/session/selection/targets.d.ts

@@ -32,7 +32,15 @@ import type { EdgeId, NodeId, Path, Query, Scope } from "../../catalog/types";
 import type { ResultsApi, RunRef } from "../results/types";
 import { ElementMask, type MaskIdSpace } from "../scope/ElementMask";
 import type { ScopeResolver } from "../scope/ScopeApi";
-/** How a text target decides whether an element matched. */
+/**
+ * How a text target decides whether an element matched.
+ *
+ * - `substring`: the id or an attribute value contains the text, ignoring case.
+ * - `exact`: the id or an attribute value is the text, exactly.
+ * - `regex`: the id or an attribute value matches the text as a regular expression.
+ * - `attribute`: the text is `key:value`, and the node's `key` (or its id, for `id`) is the value,
+ *   ignoring case. A key no node carries is searched as plain substring text.
+ */
 export type SelectionTextMode = "substring" | "exact" | "regex" | "attribute";
 /** Which way a neighbourhood target follows an edge. */
 export type SelectionDirection = "in" | "out" | "all";
@@ -70,14 +78,23 @@ export interface NeighborhoodTarget {
  * second ranking that could disagree with the one on screen.
  */
 export type SelectionTarget = ElementIdTarget | NeighborhoodTarget
-/** Every element a predicate matches. */
+/** Every element a predicate matches, narrowed to a scope when one is named. */
  | {
     readonly where: Query;
+    readonly scope?: Scope;
 }
-/** Every element a text search finds. */
+/**
+ * Every node a text search finds, narrowed to a scope when one is named.
+ *
+ * With no `mode`, the text may carry one as a prefix: `exact:`, `regex:`, or `<attribute>:`
+ * (`id:a17`, `type:person`), and anything else is a case-insensitive substring search over
+ * the node's id and its attribute values. See {@link SelectionTextMode}. A leading `=` makes
+ * the rest an expression, exactly as `{ where }` reads it, which selects edges as well.
+ */
  | {
     readonly text: string;
     readonly mode?: SelectionTextMode;
+    readonly scope?: Scope;
 }
 /** A pasted list of ids, which may name nodes, edges, or nothing at all. */
  | {

package/dist/src/session/styles/StylesApi.d.ts

@@ -494,6 +494,24 @@ export interface StylesSources {
      */
     readonly onChange?: (change: StyleChange) => void;
 }
+/**
+ * What a highlight paints when its caller names no style.
+ *
+ * A highlight is drawn OVER the default indigo node, the default darkgrey edge and the whitesmoke
+ * background, so it is chosen against those three rather than on its own. Okabe-Ito vermilion is
+ * at least Delta E 16 from each of them at normal vision and under all three kinds of colour
+ * blindness, and 3.5:1 against the background. The blue this replaced was Delta E 13 from the
+ * default node and under 4 for tritanopia, so a route through default nodes disappeared into
+ * them. `test/catalog/default-palette-quality.test.ts` measures it.
+ *
+ * Colour alone is not enough for an edge: a thin line at the default width reads as a thin line
+ * whatever its colour, so a highlighted edge is also drawn three times as wide. A node gets no
+ * size, because a size here would flatten whatever size encoding the layers beneath it drew.
+ */
+export declare const DEFAULT_HIGHLIGHT: {
+    readonly color: "#D55E00";
+    readonly edgeWidth: number;
+};
 /**
  * Build the style stack one session holds.
  * @param sources - What a selector compiles against, the element's own layers, the scales, the

package/dist/src/session/styles/legend.d.ts

@@ -184,6 +184,15 @@ export interface LegendSources {
      * @returns The words, or undefined when nothing in the session names that path.
      */
     readonly field?: (path: Path, target: SelectorTarget) => FieldWords | undefined;
+    /**
+     * Whether a layer above selects every element a layer below it selects.
+     *
+     * Absent, only a layer that selects everything is known to cover one below it.
+     * @param above - The higher layer.
+     * @param below - The lower layer.
+     * @returns True only when every element `below` selects is also selected by `above`.
+     */
+    readonly covers?: (above: Layer, below: Layer) => boolean;
 }
 /**
  * Read the legend out of the encoding model.

package/dist/src/session/styles/predicate.d.ts

@@ -104,6 +104,17 @@ export interface SelectorSource {
      * @returns The id at that row.
      */
     readonly edgeIdOf?: (index: number) => EdgeId;
+    /**
+     * The dense indices that carry a value for one column, ascending, when the source can list
+     * them without a walk over every element. A session answers it for a run's column.
+     *
+     * Absent, or answering undefined, nothing asks the question another way: the legend then
+     * reports a layer as painted over only by a layer that selects everything.
+     * @param path - The column path.
+     * @param target - Whether the asking layer paints nodes or edges.
+     * @returns The indices, or undefined when the column cannot be enumerated.
+     */
+    readonly measured?: (path: Path, target: SelectorTarget) => ArrayLike<number> | undefined;
 }
 /**
  * One target's half of a {@link SelectorSource}, resolved once so the predicate never chooses.

package/dist/src/session/styles/sources.d.ts

@@ -132,6 +132,22 @@ export interface SessionSelectorSource extends SelectorSource {
      */
     readonly measured: (path: Path, target: SelectorTarget) => ArrayLike<number> | undefined;
 }
+/**
+ * The id of the node at one end of an edge, for the attribute keys that name an endpoint.
+ *
+ * An edge's endpoints are graph structure, so the importer removes the keys they arrived under
+ * (`src`/`dst`, or whatever the id paths name) from the record a selector reads, to keep the data
+ * table from showing them twice. Without this, `data.source == 'A'` matched no edge at all and
+ * said nothing -- the empty answer looked exactly like a correct zero. So `source` and `target`
+ * are read from the snapshot for an edge whose record holds nothing under that key; an edge that
+ * really carries a `source` attribute (a provenance field, with its endpoints under `src`/`dst`)
+ * keeps it.
+ * @param graph - The snapshot the index addresses.
+ * @param index - The dense (logical) edge index, already bounded by the caller.
+ * @param key - The attribute key, without the `data.` prefix.
+ * @returns The endpoint's node id, or undefined when the key names no endpoint.
+ */
+export declare function edgeEndpointOf(graph: GraphSnapshot, index: number, key: string): NodeId | undefined;
 /**
  * Build the selector source for one session.
  *

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

@@ -14,7 +14,7 @@
  */
 import type { DerivedGraph, GraphSnapshot, NodeId } from "@graphty/graph-format";
 import type { z } from "zod/v4";
-import type { AccelerationCapabilities, AccelerationPolicy } from "../acceleration";
+import type { AccelerationCapabilities, AccelerationPolicy, AccelerationStatus, GraphAccelerator } from "../acceleration";
 import type { AlgorithmKey, AttributeDescriptor, CatalogApi, EdgeId, RunId, Scope } from "../catalog/types";
 import type { DataConfig } from "../config/DataConfig";
 import type { ElementPositions } from "../data/positions";
@@ -349,7 +349,7 @@ export interface SessionDataApi {
  *
  * The rest of the graph-dependent half of {@link CatalogApi} -- what an option's bounds resolve to
  * over a scope, whether an expression references anything real -- is still absent rather than
- * stubbed, because the query engine it reads does not exist yet. A consumer discovers that gap by
+ * stubbed: the session's query engine exists, and the catalogue is not wired to it yet. A consumer discovers that gap by
  * autocomplete finding nothing, not by a call that throws.
  */
 export type SessionCatalogApi = Pick<CatalogApi, "algorithms" | "cameras" | "formats" | "layouts" | "logSinks" | "metrics" | "palettes" | "scales">;
@@ -409,6 +409,10 @@ export interface SessionEventMap {
      * looking at an old picture that reads as an answer.
      */
     "style:problem": StyleProblem;
+    /** Every acceleration transition; the document is the one `capabilities` returns. */
+    "capabilities:changed": {
+        readonly capabilities: AccelerationCapabilities;
+    };
 }
 /**
  * A painting the element started for itself, and why it did not land.
@@ -500,6 +504,22 @@ export interface GraphSession {
     readonly config: SessionConfig;
     /** What this machine can do, measured rather than guessed at by the consumer. */
     readonly capabilities: AccelerationCapabilities;
+    /**
+     * What the consumer asks of the hardware: use an accelerator when there is one, never look,
+     * or refuse to run without one.
+     *
+     * Settable, and the set applies at once: the next piece of accelerated work is planned under
+     * the new policy, and `capabilities:changed` reports where that left the hardware.
+     */
+    acceleration: AccelerationPolicy;
+    /**
+     * Attach an accelerator the caller built, or detach the current one with `null`.
+     *
+     * For tests and third parties. An injected accelerator is never replaced by a probed one and
+     * is not disposed by the session -- whoever built it owns its lifetime.
+     * @param accelerator - The accelerator to attach, or null to detach.
+     */
+    setAccelerator(accelerator: GraphAccelerator | null): void;
     /**
      * The current snapshot, by reference: nothing is copied.
      * @returns the immutable graph-format snapshot
@@ -665,6 +685,22 @@ export interface AccelerationControllerLike {
     readonly policy: AccelerationPolicy;
     /** The node count at or above which accelerated work uses the accelerator. */
     readonly minNodes: number;
+    /**
+     * Changes what the consumer asks of the hardware.
+     * @param policy - The new policy.
+     */
+    setPolicy(policy: AccelerationPolicy): void;
+    /**
+     * Attaches an accelerator the caller built, or detaches the current one with `null`.
+     * @param accelerator - The accelerator, or null to detach.
+     */
+    setAccelerator(accelerator: GraphAccelerator | null): void;
+    /**
+     * Watches every transition.
+     * @param listener - Called with the new status.
+     * @returns A function that stops the subscription.
+     */
+    onChange(listener: (status: AccelerationStatus) => void): () => void;
     /** Releases the hardware. */
     dispose(): void;
 }