@graphty/graphty-element 2.3.1 → 2.4.1

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

@@ -16,6 +16,7 @@
  * The file is free of Babylon.js, Lit and DOM references so it can be re-exported from the
  * Node-safe entry points.
  */
+import type { AlgorithmAccelerator } from "@graphty/algorithms";
 import type { AccelerationErrorCode } from "../errors";
 /**
  * Where hardware acceleration stands, in one word.
@@ -220,6 +221,13 @@ export type AcceleratorFactory = (options?: AcceleratorFactoryOptions) => Promis
  * renders. It is plain, frozen, serialisable data: no GPU objects, no promises, no classes.
  */
 export interface AccelerationStatus {
+    /**
+     * The policy in force: what the consumer asked for, however they asked -- the `acceleration`
+     * attribute, the property, or `session.acceleration`. A change of policy publishes a new
+     * status even when the state does not move.
+     * @since 2.3.0
+     */
+    readonly policy: AccelerationPolicy;
     /** The one-word state. */
     readonly state: AccelerationState;
     /** The attached accelerator's backend, when one is attached. */
@@ -362,3 +370,80 @@ export declare const ACCELERATION_MIN_NODES_KEY = "acceleration.minNodes";
  * which is not part of the published documentation site.
  */
 export declare const ACCELERATION_MIN_NODES_DEFAULT = 0;
+/**
+ * Where and when the per-capability floors below were measured, as the plan's reason quotes it.
+ */
+export declare const ACCELERATION_MIN_NODES_MEASUREMENT = "RTX 4070 SUPER, headless Chromium, 2026-09-25";
+/**
+ * The node count below which the element declines the accelerator for one capability, when the
+ * consumer has not set {@link ACCELERATION_MIN_NODES_KEY} themselves.
+ *
+ * {@link ACCELERATION_MIN_NODES_DEFAULT} is 0 because it was measured for the forceatlas2
+ * LAYOUT, whose accelerated frame was never slower than the CPU's at any size. A traversal is a
+ * different shape of work: the whole walk is one call, and on the device that call has a floor
+ * of several submit round trips whatever the size, so below some node count the CPU walk is done
+ * before the device has started. One number cannot serve both, which is why the layout default
+ * stays 0 and each algorithm capability the adapters route carries its own floor here.
+ *
+ * MEASURED, not guessed. `tmp/traversal-threshold/kernel-cpu-vs-gpu.ts` (the harness, kept
+ * out of the tree) mounted `<graphty-element acceleration="required">` in headless Chromium on
+ * the dev box (RTX 4070 SUPER through ANGLE's Vulkan backend, 2026-09-25, load average
+ * 18 to 23), took the accelerator the element built, built seeded undirected graphs with ten
+ * edges per node and integer weights 1..10 in the page, and timed the two dispatchers
+ * `Algorithm.accelerated()` uses -- `accelerated(null)` for the CPU port and
+ * `accelerated(narrowAlgorithms(accelerator))` for the device -- directly on the snapshot, so no
+ * renderer frame is in the loop. Medians of nine warm calls after one cold call, in ms:
+ *
+ * | nodes / edges | BFS cpu | BFS gpu | sssp cpu | sssp gpu | pageRank cpu | pageRank gpu | components cpu | components gpu |
+ * | ------------- | ------: | ------: | -------: | -------: | -----------: | -----------: | -------------: | -------------: |
+ * | 1k / 10k      |     0.1 |     7.8 |      0.3 |      7.3 |          0.7 |          3.0 |            0.2 |            3.9 |
+ * | 5k / 50k      |     0.6 |     8.8 |      1.6 |      7.9 |          5.3 |          2.9 |            1.2 |            5.3 |
+ * | 10k / 100k    |     1.0 |     7.5 |      2.8 |      7.2 |          4.6 |          2.9 |            2.3 |            7.4 |
+ * | 20k / 200k    |     1.7 |     9.1 |      3.8 |     13.5 |         16.2 |          3.0 |            4.8 |            7.5 |
+ * | 50k / 500k    |     5.7 |    13.0 |     25.8 |     27.6 |         50.3 |          4.3 |           11.6 |            7.8 |
+ * | 100k / 1M     |     9.8 |    17.3 |     30.4 |     49.2 |         67.4 |          5.6 |           16.2 |            8.6 |
+ * | 200k / 2M     |    17.6 |    23.2 |     73.0 |     79.6 |        148.3 |         10.5 |           29.9 |           11.5 |
+ * | 500k / 5M     |    88.3 |    33.6 |    343.8 |    150.3 |        523.0 |         36.1 |           99.7 |           20.9 |
+ * | 1M / 10M      |   250.9 |    24.2 |   1031.1 |    274.9 |       1762.4 |         17.5 |          215.7 |           43.2 |
+ *
+ * The two traversals were then measured twice more around their crossover, because the device's
+ * time at one size moves with what else the box is doing (the first sweep's 200k row was taken
+ * at a load average of 22.6, the repeats at about 18):
+ *
+ * | nodes / edges | BFS cpu | BFS gpu | sssp cpu | sssp gpu |
+ * | ------------- | ------: | ------: | -------: | -------: |
+ * | 100k / 1M     |     7.4 |     9.5 |     26.9 |     20.9 |
+ * | 200k / 2M     |    15.6 |    10.1 |     66.3 |     37.8 |
+ * | 200k / 2M     |    17.8 |    11.0 |     70.6 |     42.5 |
+ * | 300k / 3M     |    35.2 |    13.3 |    129.2 |     77.1 |
+ * | 300k / 3M     |    34.4 |    18.9 |    129.8 |     65.2 |
+ * | 400k / 4M     |    63.3 |    30.7 |    226.6 |    128.2 |
+ * | 500k / 5M     |    93.1 |    32.5 |    361.9 |    200.0 |
+ *
+ * So: BFS loses at 100k in both runs and splits at 200k (one loss, two wins); Dijkstra splits at
+ * both 100k and 200k; from 300k up the device wins every run of both by two to ten times.
+ * PageRank wins from 5k and connected components from 50k, in the one run each was measured.
+ *
+ * A floor is the smallest measured size at which the device's median was at or below the CPU
+ * port's IN EVERY RUN, so a size that won under one load and lost under another is below it. A
+ * capability that is not listed has no floor and follows {@link ACCELERATION_MIN_NODES_DEFAULT}.
+ *
+ * Two things the table does not cover. It is one card and one browser: a slower CPU or a
+ * slower device moves the crossover, and a consumer who has measured their own machine sets
+ * `acceleration.minNodes`, which replaces every floor here with their number. And it is the
+ * kernel's time, not the run's: through the element a run also publishes its result rows,
+ * which costs the same on either path and is why the element-level numbers in the issue read
+ * higher on both sides.
+ *
+ * Under `acceleration="required"` the floors do not apply: `"required"` is what a benchmark
+ * runs under, and a benchmark of the small end of the curve has to reach the device.
+ */
+/**
+ * The capabilities a floor can name: the seam's algorithm members, by their exact names.
+ *
+ * Typed against the seam rather than as a string so that a member renamed on one side and not
+ * the other is a compile error here, not a floor that silently stops applying and sends that
+ * capability back to the GPU at every size.
+ */
+export type FlooredCapability = Exclude<keyof AlgorithmAccelerator, "kind" | "release">;
+export declare const ACCELERATION_MIN_NODES_BY_CAPABILITY: Readonly<Partial<Record<FlooredCapability, number>>>;

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

@@ -50,8 +50,21 @@ export interface AlgorithmStatics {
      *
      * Absent, the element estimates from the `costClass` the descriptor declares, which is what
      * every algorithm this package ships does.
+     *
+     * Prefer {@link costUnits}: seconds written on one machine are wrong on every other, and no
+     * calibration can scale them, so an estimate from this hook always reports "modelled".
      */
     cost?: (n: number, m: number) => number;
+    /**
+     * A cost model in WORK UNITS over a graph of n nodes and m edges, for the whole run.
+     *
+     * The units are those of the descriptor's `costClass`: elements for `instant` and
+     * `iterative` (count every iteration), source-edge pairs for `heavy`, operations for
+     * `cubic`. The element divides them by the rate it measured for that class on this device,
+     * so the estimate follows the machine and reports "calibrated" once the device is probed,
+     * exactly as a built-in's does. Wins over {@link cost} when both are declared.
+     */
+    costUnits?: (n: number, m: number) => number;
     /**
      * The plugin's own version, recorded on every run this algorithm produces.
      *

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

@@ -0,0 +1,26 @@
+import type { FieldDescriptor, NodeId } from "../catalog/types";
+import { MetricAlgorithm } from "./metrics/MetricAlgorithm";
+import type { MetricMeasurement, MetricRunContext } from "./metrics/types";
+/**
+ * K-core decomposition: how deep in the graph's densely connected core each node sits.
+ *
+ * A node's core number is the largest k for which it belongs to a k-core -- the largest part of
+ * the graph in which every node has at least k neighbours. Every node has one, so every node is
+ * measured.
+ */
+export declare class KCoreAlgorithm extends MetricAlgorithm {
+    static namespace: string;
+    static type: string;
+    /**
+     * The fields a k-core result publishes.
+     * @returns The uniform node-metric fields.
+     */
+    protected resultFields(): readonly FieldDescriptor[];
+    /**
+     * Give every node its core number.
+     * @param context - Where progress goes and where cancellation arrives.
+     * @param nodeIds - The nodes to measure.
+     * @returns One core number per node.
+     */
+    protected measure(context: MetricRunContext, nodeIds: readonly NodeId[]): Promise<MetricMeasurement>;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * @file Link prediction: the pairs of unconnected nodes most likely to be joined next.
+ *
+ * The answer is a list of scored pairs, not a value on each node or edge -- a predicted link is
+ * an edge that does not exist yet, so there is no element to hang it on. The result is shaped as
+ * a pair list, which is why a run of it suggests no style: painting it would mean inventing the
+ * thing it painted.
+ */
+import { adamicAdarPrediction, commonNeighborsPrediction } from "@graphty/algorithms";
+import { type OptionsSchema as ZodOptionsSchema } from "../config";
+import { type AlgorithmOutput, type AlgorithmRunContext, DeclaredAlgorithm } from "./results";
+import type { OptionsSchema } from "./types/OptionSchema";
+/** The two scoring methods, by the name the `method` option takes. */
+declare const METHODS: {
+    readonly "adamic-adar": typeof adamicAdarPrediction;
+    readonly "common-neighbors": typeof commonNeighborsPrediction;
+};
+/** Options for link prediction. */
+interface LinkPredictionOptions extends Record<string, unknown> {
+    /** Which score ranks the pairs. */
+    method: keyof typeof METHODS;
+    /** How many of the best-scoring pairs to keep. */
+    topK: number;
+}
+/**
+ * Link prediction: scores every pair of nodes that is not already joined by how many neighbours
+ * the two share, and keeps the best.
+ */
+export declare class LinkPredictionAlgorithm extends DeclaredAlgorithm<LinkPredictionOptions> {
+    static namespace: string;
+    static type: string;
+    static zodOptionsSchema: ZodOptionsSchema;
+    static optionsSchema: OptionsSchema;
+    /**
+     * Score every unconnected pair of nodes and keep the best.
+     * @param context - What the element gave the run.
+     * @returns The scored pairs, best first, or null when the graph has no nodes.
+     */
+    compute(context: AlgorithmRunContext): Promise<AlgorithmOutput | null>;
+}
+export {};

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

@@ -1,3 +1,4 @@
+import { Vector3 } from "@babylonjs/core";
 /**
  * Shared input utility functions for camera controllers.
  * Used by both 3D (OrbitInputController) and XR (XRInputHandler).
@@ -11,3 +12,69 @@
  * @returns Adjusted value with deadzone and curve applied
  */
 export declare function applyDeadzone(value: number, threshold?: number): number;
+/** Thumbstick deflection, per axis, that XR input ignores. */
+export declare const XR_THUMBSTICK_DEADZONE = 0.15;
+/**
+ * Whether a tracked hand is pinching, with hysteresis: a hand that is already pinching lets go at
+ * a looser distance than an open hand needs to start.
+ * @param distance - Thumb tip to index tip, in metres
+ * @param wasPinching - Whether the hand was pinching last frame
+ * @returns Whether the hand is pinching now
+ */
+export declare function isPinching(distance: number, wasPinching: boolean): boolean;
+/**
+ * How firmly a tracked hand is pinching: 1 with the finger tips touching, falling to 0 at the
+ * pinch start distance.
+ * @param distance - Thumb tip to index tip, in metres
+ * @returns Pinch strength in [0, 1]
+ */
+export declare function pinchStrength(distance: number): number;
+/** What one frame of thumbstick input does to the XR pivot. Zero (or a zoom of 1) means leave it alone. */
+interface ThumbstickDeltas {
+    /** Radians, for `PivotController.rotate`. */
+    yaw: number;
+    /** Radians, for `PivotController.rotate`. */
+    pitch: number;
+    /** Factor, for `PivotController.zoom`. */
+    zoom: number;
+    /** Distance, for `PivotController.panViewRelative`. */
+    pan: number;
+}
+/**
+ * Map one frame of thumbstick input to pivot movement. Left stick X yaws and Y pitches (forward
+ * moves the graph up, as mouse and touch do); right stick Y zooms (forward zooms in) and X pans.
+ * @param left - Left stick axes, each in [-1, 1]
+ * @param left.x - Left stick X
+ * @param left.y - Left stick Y
+ * @param right - Right stick axes, each in [-1, 1]
+ * @param right.x - Right stick X
+ * @param right.y - Right stick Y
+ * @returns The movement to apply this frame
+ */
+export declare function thumbstickDeltas(left: {
+    x: number;
+    y: number;
+}, right: {
+    x: number;
+    y: number;
+}): ThumbstickDeltas;
+/** What one frame of a two-hand gesture does to the XR pivot. */
+interface TwoHandGestureDelta {
+    /** Factor, for `PivotController.zoom`, clamped to [0.9, 1.1]. Hands moving apart zoom out. */
+    zoom: number;
+    /** Unit axis for `PivotController.rotateAroundAxis`, or null when the hands did not turn. */
+    axis: Vector3 | null;
+    /** Radians, for `PivotController.rotateAroundAxis`. */
+    angle: number;
+}
+/**
+ * Map the change in the line between two pinching hands, from one frame to the next, to pivot
+ * movement: the change in its length zooms, and the change in its direction rotates.
+ * @param previousDistance - Distance between the hands last frame
+ * @param previousDirection - Unit vector from left hand to right hand last frame
+ * @param distance - Distance between the hands this frame
+ * @param direction - Unit vector from left hand to right hand this frame
+ * @returns The movement to apply this frame
+ */
+export declare function twoHandGestureDelta(previousDistance: number, previousDirection: Vector3, distance: number, direction: Vector3): TwoHandGestureDelta;
+export {};

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

@@ -32,14 +32,6 @@ export declare class XRInputHandler {
     private previousDirection;
     private wasPinching;
     private handTrackingFeature;
-    private readonly DEADZONE;
-    private readonly YAW_SPEED;
-    private readonly PITCH_SPEED;
-    private readonly PAN_SPEED;
-    private readonly ZOOM_SPEED;
-    private readonly GESTURE_ZOOM_SENSITIVITY;
-    private readonly _PINCH_START;
-    private readonly _PINCH_END;
     private lastControllerRemovedTime;
     private readonly INPUT_SWITCH_DELAY_MS;
     private isDraggingNode;

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

@@ -20,10 +20,10 @@
  *   `JSON.stringify`, a `postMessage` to a worker and a write to a saved document, and a
  *   closure survives none of those. A cost estimate that needs code belongs to
  *   `session.estimate()`, which runs where the code is.
- * - **The table only lists what ships.** Four members of `KNOWN_ALGORITHMS` -- `all-paths`,
- *   `clustering-coefficient`, `k-core` and `link-prediction` -- are not registered by this
- *   package and therefore have no descriptor here. A catalogue that advertised them would be
- *   lying about what the element can run.
+ * - **The table only lists what ships.** Two members of `KNOWN_ALGORITHMS` -- `all-paths` and
+ *   `clustering-coefficient`, listed in `DEPRECATED_ALGORITHMS` -- are not implemented and
+ *   therefore have no descriptor here. A catalogue that advertised them would be lying about
+ *   what the element can run.
  *
  * Two conventions worth stating once:
  *
@@ -70,7 +70,7 @@ export interface BuiltInAlgorithmDescriptor extends AlgorithmDescriptor {
 /**
  * Every algorithm this package registers, as a plain-JSON descriptor.
  *
- * Twenty-one descriptors for twenty-three registered algorithms: the two single-source
+ * Twenty-three descriptors for twenty-five registered algorithms: the two single-source
  * shortest-path engines are one key with a `method` parameter, and the two component algorithms
  * are one key with a `strength` parameter. Each descriptor's `legacyKeys` names the 1.10 keys it
  * replaces and the parameters that reproduce them.

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

@@ -9,8 +9,8 @@ export type { LabelAnimation, LabelBadge, LabelGradientDirection, LabelGradientT
 export { LABEL_STYLE_FIELDS } from "./label-style";
 export type { OptionsFromZodOptions, OptionsSource, OptionUiMeta } from "./optionsFromZod";
 export { optionsFromZod } from "./optionsFromZod";
-export type { AlgorithmDescriptor, AlgorithmKey, AttributeDescriptor, AttributeType, Binding, CameraDescriptor, CameraId, CatalogApi, Channel, ChannelValue, CostClass, DrawingMode, EdgeId, EdgeLinePattern, Encoding, FieldDescriptor, FormatDescriptor, FormatId, FunctionDescriptor, GraphtyErrorCode, KnownAlgorithm, LabelStyle, LayerId, LayerKind, LayerSource, LayerSpec, LayoutDescriptor, LayoutId, LogSinkDescriptor, LogSinkId, MetricAvailability, NodeId, OptionBound, OptionChoice, OptionDescriptor, OptionType, PaletteDescriptor, PaletteId, Path, Query, QueryValidation, ResultShape, Rgba, RunId, ScaleDescriptor, Scope, ScopeId, Selector, StaticStyle, StyleDocument, ThemeDescriptor, } from "./types";
-export { ATTRIBUTE_TYPES, COST_CLASSES, isAttributeType, isCostClass, isOptionBound, isOptionType, isResultShape, KNOWN_ALGORITHMS, KNOWN_CAMERA_IDS, KNOWN_FORMAT_IDS, KNOWN_LAYOUT_IDS, KNOWN_LOG_SINK_IDS, KNOWN_PALETTE_IDS, OPTION_BOUND_SOURCES, OPTION_TYPES, RESULT_SHAPES, } from "./types";
+export type { AlgorithmDescriptor, AlgorithmKey, AttributeDescriptor, AttributeType, Binding, CameraDescriptor, CameraId, CatalogApi, Channel, ChannelValue, CostClass, DeprecatedAlgorithm, DeprecatedCatalogMethod, DrawingMode, EdgeId, EdgeLinePattern, Encoding, FieldDescriptor, FormatDescriptor, FormatId, FunctionDescriptor, GraphtyErrorCode, KnownAlgorithm, LabelStyle, LayerId, LayerKind, LayerSource, LayerSpec, LayoutDescriptor, LayoutId, LogSinkDescriptor, LogSinkId, MetricAvailability, NodeId, OptionBound, OptionChoice, OptionDescriptor, OptionType, PaletteDescriptor, PaletteId, Path, Query, QueryValidation, ResultShape, Rgba, RunId, ScaleDescriptor, Scope, ScopeId, Selector, StaticStyle, StyleDocument, ThemeDescriptor, } from "./types";
+export { ATTRIBUTE_TYPES, COST_CLASSES, DEPRECATED_ALGORITHMS, isAttributeType, isCostClass, isOptionBound, isOptionType, isResultShape, KNOWN_ALGORITHMS, KNOWN_CAMERA_IDS, KNOWN_FORMAT_IDS, KNOWN_LAYOUT_IDS, KNOWN_LOG_SINK_IDS, KNOWN_PALETTE_IDS, OPTION_BOUND_SOURCES, OPTION_TYPES, RESULT_SHAPES, } from "./types";
 /**
  * What the element does NOT serve on the styling surface, said out loud.
  *

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 seventeen engines whose registered
+ * and never which library draws it. The element registers nineteen 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
@@ -14,10 +14,11 @@
  * descriptor a consumer reads carries the default engine and that engine's options; the rest of
  * the list is there for a consumer that wants to choose.
  *
- * Two names in the built-in layout list have no engine behind them yet, and two engines describe
- * an arrangement that list has no name for. Both are recorded here -- {@link UNSERVED_LAYOUT_IDS}
- * and the `spiral` and `planar` entries -- rather than left for a consumer to discover by asking
- * for a layout that never answers, or by never learning a capability exists.
+ * A name in the built-in layout list with no engine behind it would be recorded in
+ * {@link UNSERVED_LAYOUT_IDS} (none is, today), and two engines describe an arrangement that list
+ * has no name for, which the `spiral` and `planar` entries record -- rather than left for a
+ * consumer to discover by asking for a layout that never answers, or by never learning a
+ * capability exists.
  *
  * `sizeRating` is the largest graph the default engine is recommended for, read from its cost: a
  * placement that visits each node once rates "any", an iterative all-pairs force rates 2000.
@@ -78,7 +79,7 @@ export declare const LAYOUT_DESCRIPTORS: readonly LayoutDescriptor[];
 /**
  * The built-in layout names no registered engine draws yet. Listed rather than omitted, because
  * a name that is in the type and missing from the catalogue is otherwise discovered by asking
- * for it and getting an error.
+ * for it and getting an error. Empty today: every built-in name has an engine.
  */
 export declare const UNSERVED_LAYOUT_IDS: readonly UnservedLayout[];
 /**

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

@@ -33,6 +33,12 @@
  * {@link PluginRegistry.clearForTesting} exists so a suite can leave the registry as it found
  * it, and is named so nobody can mistake it for part of the contract.
  *
+ * ONE STORE PER PAGE, NOT PER COPY. A page can evaluate graphty-element twice -- the self-contained
+ * bundle beside an `./extend` import, two installs of the package, a dev server loading one module
+ * under two URLs -- and the element deliberately survives that. Every registry therefore keeps its
+ * state on `globalThis` under a `Symbol.for` key ({@link sharedStore}), so a registration made
+ * through any copy reaches the element any other copy defined.
+ *
  * NOTHING HERE IMPORTS A CLASS, a reader, an engine or a renderer. A registry holds whatever it
  * was handed at run time, which is what keeps `./catalog` and `./extend` resolvable in Node.
  */
@@ -110,6 +116,62 @@ export interface PluginRegistrySpec<TEntry, TDescriptor> {
      */
     builtInIds(): readonly string[];
 }
+/**
+ * The one instance of a piece of registry state on this page, whichever copy of graphty-element
+ * asks for it.
+ *
+ * Keyed on `Symbol.for`, which is shared by every realm-local module graph, so two copies of this
+ * module find the same value. The `v1` names the shape of what is stored, and that includes the
+ * shape of every entry and descriptor inside it, not only the container: any change to an entry
+ * or a descriptor that an older copy on the same page cannot read must bump the version, so the
+ * two copies keep separate stores rather than misreading each other's.
+ * @param kind - Which piece of state.
+ * @param create - Builds it the first time any copy asks.
+ * @returns The page's instance.
+ */
+export declare function sharedStore<T>(kind: string, create: () => T): T;
+/**
+ * A map from name to implementation (a class, a factory) that this copy of graphty-element reads
+ * first and every other copy on the page reads after its own.
+ *
+ * THIS COPY'S OWN ENTRIES WIN, because they include its built-ins: a second copy's box shape is
+ * built with the second copy's Babylon.js, and its degree algorithm extends the second copy's base
+ * class, so handing those to this copy's element would mix two renderers in one scene. What a copy
+ * does not have itself -- a plugin registered through another copy -- comes from the page's
+ * shared map.
+ */
+export declare class SharedImplementationMap<V> {
+    #private;
+    /**
+     * Join the page's shared map for this extension point, creating it if this copy is first.
+     * @param kind - Which extension point, which names the page's shared map.
+     */
+    constructor(kind: string);
+    /**
+     * File an implementation for this copy and for every other copy on the page.
+     * @param name - The name it is filed under.
+     * @param value - The implementation.
+     */
+    set(name: string, value: V): void;
+    /**
+     * This copy's implementation, or else the one another copy filed.
+     * @param name - The name.
+     * @returns The implementation, or undefined when no copy filed one.
+     */
+    get(name: string): V | undefined;
+    /**
+     * Whether THIS copy filed the name, which is what a built-in duplicate check asks: another
+     * copy registering its own built-ins is not a collision.
+     * @param name - The name.
+     * @returns True when this copy filed it.
+     */
+    hasOwn(name: string): boolean;
+    /**
+     * Every name any copy filed.
+     * @returns The names, this copy's first.
+     */
+    keys(): IterableIterator<string>;
+}
 /**
  * Build a registry for one extension point.
  * @param spec - How this kind of extension is read.

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

@@ -61,6 +61,13 @@ export interface RegisteredAlgorithm {
      * plugin still supplies real arithmetic for the estimator to use.
      */
     readonly cost?: (n: number, m: number) => number;
+    /**
+     * A cost model in work units of the descriptor's cost class, read from `static costUnits`.
+     *
+     * The estimator divides it by this device's rate for that class, so calibration scales it.
+     * Wins over {@link cost} when both are present.
+     */
+    readonly costUnits?: (n: number, m: number) => number;
     /**
      * The plugin's own version, read from `static version`.
      *

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

@@ -53,10 +53,29 @@ export type Query = string;
 /**
  * The built-in algorithms. The list is also available at runtime so a consumer can enumerate
  * the built-in set without a catalogue instance.
+ *
+ * Two of these names are deprecated: `all-paths` and `clustering-coefficient` are reserved but
+ * not implemented, and starting either fails with `E_UNSUPPORTED`. See
+ * {@link DEPRECATED_ALGORITHMS}.
  */
 export declare const KNOWN_ALGORITHMS: readonly ["degree", "betweenness", "closeness", "pagerank", "eigenvector", "katz", "hits", "louvain", "leiden", "label-propagation", "components", "shortest-path", "all-pairs-distance", "all-paths", "max-flow", "min-cut", "k-core", "clustering-coefficient", "girvan-newman", "bfs", "dfs", "kruskal", "prim", "bipartite-matching", "link-prediction"];
-/** One of the built-in algorithms. */
+/**
+ * One of the built-in algorithms. `all-paths` and `clustering-coefficient` are deprecated and do
+ * not run; see {@link DEPRECATED_ALGORITHMS}.
+ */
 export type KnownAlgorithm = (typeof KNOWN_ALGORITHMS)[number];
+/**
+ * The built-in algorithm names the element reserves but does not run.
+ *
+ * Nothing implements these two yet. The names stay in {@link KNOWN_ALGORITHMS}, so no plugin can
+ * claim them and no code that names them stops compiling, but starting one fails with
+ * `E_UNSUPPORTED` rather than `E_UNKNOWN_ALGORITHM`. Each is removed at the next major release
+ * unless it is implemented first: `all-paths` is tracked by issue #329 and
+ * `clustering-coefficient` by issue #330.
+ */
+export declare const DEPRECATED_ALGORITHMS: readonly ["all-paths", "clustering-coefficient"];
+/** A built-in algorithm name the element reserves but does not run, and will remove. */
+export type DeprecatedAlgorithm = (typeof DEPRECATED_ALGORITHMS)[number];
 /**
  * An algorithm key. The built-in names keep autocomplete alive; the string arm accepts a
  * plugin's name.
@@ -446,13 +465,23 @@ export interface ScaleDescriptor {
     domainKind: "numeric" | "categorical" | "boolean";
     options: readonly OptionDescriptor[];
 }
-/** One named style document, offered as a whole look. */
+/**
+ * One named style document, offered as a whole look.
+ *
+ * Nothing produces one yet: it is returned only by the deprecated `CatalogApi.themes()`, and goes
+ * with it at the next major release unless that is implemented first (issue #331).
+ */
 export interface ThemeDescriptor {
     name: string;
     plainName: string;
     document: StyleDocument;
 }
-/** One function the expression grammar accepts. */
+/**
+ * One function the expression grammar accepts.
+ *
+ * Nothing produces one yet: it is returned only by the deprecated `CatalogApi.functions()`, and
+ * goes with it at the next major release unless that is implemented first (issue #332).
+ */
 export interface FunctionDescriptor {
     name: string;
     /** The smallest and largest argument count accepted. */
@@ -524,7 +553,12 @@ export type Scope = "visible" | "graph" | "selection" | "largest-component" | {
 } | {
     nodes: readonly NodeId[];
 };
-/** The catalogue: everything the element can offer, as data. */
+/**
+ * The catalogue: everything the element can offer, as data.
+ *
+ * `session.catalog` implements every method here except the six named in
+ * {@link DeprecatedCatalogMethod}, which nothing implements yet.
+ */
 export interface CatalogApi {
     algorithms(): readonly AlgorithmDescriptor[];
     layouts(): readonly LayoutDescriptor[];
@@ -533,24 +567,61 @@ export interface CatalogApi {
     cameras(): readonly CameraDescriptor[];
     logSinks(): readonly LogSinkDescriptor[];
     scales(): readonly ScaleDescriptor[];
+    /**
+     * @deprecated Not implemented. Removed at the next major release unless it is implemented
+     * first (issue #331).
+     */
     themes(): readonly ThemeDescriptor[];
+    /**
+     * @deprecated Not implemented. Removed at the next major release unless it is implemented
+     * first (issue #332).
+     */
     functions(): readonly FunctionDescriptor[];
+    /**
+     * @deprecated Not implemented. Removed at the next major release unless it is implemented
+     * first (issue #333).
+     */
     timeAttributes(): readonly AttributeDescriptor[];
     metrics(): readonly MetricAvailability[];
-    /** The metrics that can run on this graph. A runtime query, not a static list. */
+    /**
+     * The metrics that can run on this graph. A runtime query, not a static list.
+     * @deprecated Not implemented; `metrics()` carries `available` and `reason` for the same
+     * question. Removed at the next major release unless it is implemented first (issue #334).
+     */
     applicable(): readonly MetricAvailability[];
+    /**
+     * @deprecated Not implemented. Removed at the next major release unless it is implemented
+     * first (issue #335).
+     */
     validate(query: Query, o?: {
         kind?: "selector" | "filter" | "formula";
     }): QueryValidation;
-    /** The options for one algorithm or layout, with data-dependent bounds resolved. */
+    /**
+     * The options for one algorithm or layout, with data-dependent bounds resolved.
+     * @deprecated Not implemented; `algorithms()` and `layouts()` carry the static option
+     * descriptors. Removed at the next major release unless it is implemented first (issue #336).
+     */
     optionsFor(key: AlgorithmKey | LayoutId, scope?: Scope): Promise<readonly OptionDescriptor[]>;
 }
+/**
+ * The {@link CatalogApi} methods nothing implements yet, which `session.catalog` leaves out.
+ *
+ * Implementing one means deleting its name here: `SessionCatalogApi` is derived from this list,
+ * so the two cannot drift apart.
+ */
+export type DeprecatedCatalogMethod = "themes" | "functions" | "timeAttributes" | "applicable" | "validate" | "optionsFor";
 /**
  * Tell whether a value is one of the option types.
  * @param value - The value to test.
  * @returns True when the value is a member of OPTION_TYPES.
  */
 export declare function isOptionType(value: unknown): value is OptionType;
+/**
+ * Tell whether an algorithm key names a built-in the element reserves but does not run.
+ * @param key - The algorithm key.
+ * @returns True when the key is a member of DEPRECATED_ALGORITHMS.
+ */
+export declare function isDeprecatedAlgorithm(key: string): key is DeprecatedAlgorithm;
 /**
  * Tell whether a value is one of the cost classes.
  * @param value - The value to test.

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

@@ -1,4 +1,39 @@
 import { z } from "zod/v4";
+/**
+ * Every arrow the edge renderer can draw at the head or tail of an edge, in schema order.
+ * Read `EdgeArrowTypes.options` for the list, e.g. to build a picker.
+ */
+export declare const EdgeArrowTypes: z.ZodEnum<{
+    none: "none";
+    dot: "dot";
+    normal: "normal";
+    inverted: "inverted";
+    "sphere-dot": "sphere-dot";
+    "open-dot": "open-dot";
+    tee: "tee";
+    "open-normal": "open-normal";
+    diamond: "diamond";
+    "open-diamond": "open-diamond";
+    crow: "crow";
+    box: "box";
+    "half-open": "half-open";
+    vee: "vee";
+}>;
+/**
+ * Every line pattern the edge renderer can draw, in schema order.
+ * Read `EdgeLineTypes.options` for the list, e.g. to build a picker.
+ */
+export declare const EdgeLineTypes: z.ZodEnum<{
+    solid: "solid";
+    dot: "dot";
+    diamond: "diamond";
+    box: "box";
+    star: "star";
+    dash: "dash";
+    "dash-dot": "dash-dot";
+    sinewave: "sinewave";
+    zigzag: "zigzag";
+}>;
 /**
  * Everything a style layer can say about how one edge is drawn.
  *

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

@@ -1,7 +1,7 @@
 export type { AdHocData, ImageData } from "./common";
 export { colorToHex } from "./common";
 export type { EdgeStyleConfig } from "./EdgeStyle";
-export { defaultEdgeStyle, EdgeStyle } from "./EdgeStyle";
+export { defaultEdgeStyle, EdgeArrowTypes, EdgeLineTypes, EdgeStyle } from "./EdgeStyle";
 export type { FetchEdgesFn, FetchNodesFn, GraphBehaviorConfig } from "./GraphBehavior";
 export type { NodeIdType } from "./GraphBehavior";
 export { GraphBehaviorOpts } from "./GraphBehavior";

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

@@ -1,5 +1,5 @@
 import * as z4 from "zod/v4/core";
-import type { RegisterOptions } from "../catalog/pluginRegistry";
+import { type RegisterOptions } from "../catalog/pluginRegistry";
 import type { FormatDescriptor } from "../catalog/types";
 import { AdHocData } from "../config";
 import { ErrorAggregator } from "./ErrorAggregator.js";