@graphty/graphty-element 2.3.0 → 2.4.0

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.
@@ -362,3 +363,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/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/camera/builtins.d.ts

@@ -14,7 +14,9 @@
  * times the longest side: every one of those is what the element computed before, so no picture
  * moves. They disagree with each other -- the orbit controller's own framing pads 5 percent and
  * the 2D controller's pads 10 percent -- and this file does not average them, because averaging
- * them would change what a saved screenshot looks like. A plugin picks its own.
+ * them would change what a saved screenshot looks like. A plugin picks its own. The one
+ * exception is the isometric `beta`: it was 0.615, the elevation above the horizon, in a field
+ * measured down from the pole, and no picture depended on it because nothing applied it.
  *
  * THESE ARE NOT REGISTERED. A built-in id is reserved and `registerCameraView` refuses one, so
  * the table below is looked up first and the registry second, which is what keeps a registration
@@ -27,3 +29,14 @@ import type { CameraState, CameraViewInput } from "./types";
  * @returns The function, or undefined when the element ships no view by that name.
  */
 export declare function builtInCameraView(id: string): ((input: CameraViewInput) => CameraState) | undefined;
+/**
+ * Turn an orbit state given as angles into the position the element's cameras are placed from.
+ *
+ * `alpha`, `beta` and `radius` follow Babylon's ArcRotate convention: the viewer stands at
+ * target + radius * (cos(alpha) sin(beta), cos(beta), sin(alpha) sin(beta)). A state that already
+ * carries a position or a pivot rotation, or lacks an angle or a distance (`radius`, or
+ * `cameraDistance`), is returned unchanged.
+ * @param state - The state a caller or a camera view asked for.
+ * @returns The same state, with `position` (and `cameraDistance` from `radius`) filled in.
+ */
+export declare function orbitAnglesToPosition(state: CameraState): CameraState;

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

@@ -60,8 +60,15 @@ export interface CameraState {
         y: number;
         z: number;
     };
+    /**
+     * Orbit angles in Babylon's ArcRotate convention: `alpha` turns around the +y axis starting
+     * from +x, `beta` is measured down from +y (0 looks straight down, PI/2 is level). With
+     * `radius` they place the viewer at target + radius * (cos(alpha) sin(beta), cos(beta),
+     * sin(alpha) sin(beta)). Ignored when the state also gives `position` or `pivotRotation`.
+     */
     alpha?: number;
     beta?: number;
+    /** Distance from `target` for an orbit state given as `alpha` and `beta`. */
     radius?: number;
     fov?: number;
     zoom?: number;

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

@@ -14,6 +14,13 @@ interface InputHandler {
     update(): void;
 }
 export type CameraKey = "orbit" | "2d" | "xr";
+/**
+ * The camera each drawing view mode is drawn through. The immersive modes have none here: their
+ * camera belongs to the XR session.
+ * @param viewMode - The view mode.
+ * @returns The camera key, or undefined for a mode with no camera of its own.
+ */
+export declare function cameraForViewMode(viewMode: string): CameraKey | undefined;
 /**
  * Manages multiple camera controllers and their input handlers.
  * Provides functionality to register, activate, and switch between different camera types.
@@ -63,6 +70,12 @@ export declare class CameraManager {
      * @returns The active controller or null if no camera is active
      */
     getActiveController(): CameraController | null;
+    /**
+     * Gets a registered camera controller, whether or not it is the active one.
+     * @param key - The identifier the controller was registered under
+     * @returns The controller, or undefined when nothing is registered under the key
+     */
+    getController(key: CameraKey): CameraController | undefined;
     /**
      * Temporarily disable the active input handler (e.g., during node dragging)
      */

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

@@ -54,6 +54,15 @@ export declare class OrbitCameraController {
      * @param delta - Distance delta to adjust camera by
      */
     zoom(delta: number): void;
+    /**
+     * The distance rule every programmatic writer of `cameraDistance` follows: floored at
+     * `minZoomDistance`, never capped. The ceiling is a zoom-out limit for a reader, not a
+     * framing limit -- a saved state for a large graph can sit beyond it, and `zoom` accepts that
+     * -- while a distance under the floor would make the next zoom IN jump the camera outwards.
+     * @param distance - The distance asked for.
+     * @returns The distance to use.
+     */
+    clampDistance(distance: number): number;
     /**
      * Update camera position relative to the pivot.
      * Parents camera to pivot and positions at negative Z distance.

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/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.
@@ -271,6 +290,16 @@ export type Selector = {
     match: "ids";
     nodes?: readonly NodeId[];
     edges?: readonly EdgeId[];
+}
+/**
+ * The top `n` elements by one run field (`results.<run>.<field>`), cut only between tie
+ * groups: a group of equal values is painted whole, and only when all of it fits inside `n`.
+ * See `TopRanking` for the policy.
+ */
+ | {
+    match: "top";
+    path: Path;
+    n: number;
 } | {
     match: "everything";
 };
@@ -436,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. */
@@ -514,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[];
@@ -523,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/GraphStyle.d.ts

@@ -99,7 +99,11 @@ export declare const GraphStyle: z.ZodObject<{
         /** How solid the halo is, in `[0, 1]`. Low enough to read as a highlight rather than a node. */
         opacity: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
-    startingCameraDistance: z.ZodDefault<z.ZodNumber>;
+    /**
+     * How far the camera starts from the graph, in scene units. Set, it places the camera and
+     * turns off the element's automatic zoom-to-fit; unset, the graph is framed to fit.
+     */
+    startingCameraDistance: z.ZodOptional<z.ZodNumber>;
     layout: z.ZodOptional<z.ZodString>;
     layoutOptions: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
     /**

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

@@ -22,7 +22,7 @@ declare const StyleTemplateV1: z.ZodObject<{
             scale: z.ZodDefault<z.ZodNumber>;
             opacity: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>;
-        startingCameraDistance: z.ZodDefault<z.ZodNumber>;
+        startingCameraDistance: z.ZodOptional<z.ZodNumber>;
         layout: z.ZodOptional<z.ZodString>;
         layoutOptions: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
         viewMode: z.ZodDefault<z.ZodEnum<{
@@ -958,7 +958,7 @@ export declare const StyleTemplate: z.ZodDiscriminatedUnion<[z.ZodObject<{
             scale: z.ZodDefault<z.ZodNumber>;
             opacity: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>;
-        startingCameraDistance: z.ZodDefault<z.ZodNumber>;
+        startingCameraDistance: z.ZodOptional<z.ZodNumber>;
         layout: z.ZodOptional<z.ZodString>;
         layoutOptions: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
         viewMode: z.ZodDefault<z.ZodEnum<{

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/GEXFDataSource.d.ts

@@ -3,6 +3,14 @@ type GEXFDataSourceConfig = BaseDataSourceConfig;
 /**
  * Data source for loading graph data from GEXF (Graph Exchange XML Format) files.
  * Supports node and edge attributes, attribute types, and dynamic graphs.
+ *
+ * Dynamic graphs keep their time data on each record rather than acting on it:
+ * - a node's or edge's `start` / `end` / `timestamp` (see {@link readInterval}) go onto its data
+ *   under those names, and its `<spells>` go onto `spells` as a list of the same intervals;
+ * - an attribute with time-sliced `attvalue`s becomes a list of `{ value, start, end }` slices
+ *   instead of a single value. An attribute with no timed `attvalue` keeps its plain value.
+ *
+ * Dynamic `viz:*` elements (timed positions, colours or sizes) are not read.
  */
 export declare class GEXFDataSource extends DataSource {
     static readonly type = "gexf";
@@ -60,6 +68,21 @@ export declare class GEXFDataSource extends DataSource {
      * @returns the edge records, and how many edges stated each direction
      */
     private parseEdges;
+    /**
+     * Copy a node's or edge's lifetime, spells and attribute values onto its record.
+     *
+     * Every `attvalue` for one attribute is kept: if any of them is timed, the attribute becomes
+     * the list of all its slices, `{ value, start, end }`, in file order; otherwise it keeps its
+     * plain value, so a static file reads exactly as it always has.
+     * @param obj - the parsed `<node>` or `<edge>`
+     * @param obj.attvalues - its `<attvalues>` element, if any
+     * @param obj.attvalues.attvalue - the `<attvalue>` children
+     * @param obj.spells - its `<spells>` element, if any
+     * @param obj.spells.spell - the `<spell>` children
+     * @param record - the record being built, written in place
+     * @param attributes - the attribute definitions for this element class
+     */
+    private readTimeData;
     private parseValue;
 }
 export {};

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

@@ -185,6 +185,20 @@ export type GraphtyErrorCode =
  * import plan or the data.
  */
  | "E_ID_MISSING"
+/**
+ * A load read its source to the end and found nothing in it: no node records and no edge
+ * records. It is reported as a failure rather than as a success with zero counts, and a
+ * load asked to `replace` keeps the graph it would have replaced. `details` carry the
+ * format. The caller checks the file, or the format it was read as.
+ */
+ | "E_EMPTY_LOAD"
+/**
+ * A load was overtaken: a REPLACING load was called after it, or `clearData` ran, so its data
+ * would have replaced or mixed into the newer dataset. It stops without touching the graph.
+ * `details` carry the format. Not a fault in the source; the caller ignores it, or loads
+ * again.
+ */
+ | "E_SUPERSEDED"
 /**
  * The graph exceeds a hard structural limit of an index or of the accelerator, and no scope
  * or sample makes the work runnable. `details` carry the size and the limit. Distinct from