@graphty/graphty-element 2.3.1 → 2.4.0

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

@@ -0,0 +1,37 @@
+import { z } from "zod/v4";
+import { type OptionsSchema } from "../config";
+import { SimpleLayoutEngine } from "./LayoutEngine";
+declare const RadialLayoutConfig: z.ZodObject<{
+    root: z.ZodDefault<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    scale: z.ZodDefault<z.ZodNumber>;
+    center: z.ZodDefault<z.ZodUnion<[z.ZodArray<z.ZodNumber>, z.ZodNull]>>;
+    scalingFactor: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+type RadialLayoutConfigType = z.infer<typeof RadialLayoutConfig>;
+type RadialLayoutOpts = Partial<RadialLayoutConfigType>;
+/**
+ * Radial layout engine that places nodes on rings by hop distance from a root node
+ */
+export declare class RadialLayout extends SimpleLayoutEngine {
+    static type: string;
+    static maxDimensions: number;
+    static zodOptionsSchema: OptionsSchema;
+    scalingFactor: number;
+    config: RadialLayoutConfigType;
+    /**
+     * Create a radial layout engine
+     * @param opts - Configuration options including the root node
+     */
+    constructor(opts: RadialLayoutOpts);
+    /**
+     * Get dimension-specific options for radial layout
+     * @param dimension - The desired dimension (2 or 3)
+     * @returns Empty object for 2D, null for 3D (unsupported)
+     */
+    static getOptionsForDimension(dimension: 2 | 3): object | null;
+    /**
+     * Compute node positions on rings around the root
+     */
+    doLayout(): void;
+}
+export {};

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

@@ -323,6 +323,18 @@ export declare class SimulationLayoutEngine extends LayoutEngine {
      * @returns A promise that resolves when the batch has landed, or rejects with its failure.
      */
     stepAsync(iterations: number): Promise<void>;
+    /**
+     * Whether the manager has stopped stepping this layout -- a consumer's pause, or any other
+     * stop. A paused layout's work span closes once its in-flight batches land, because nothing
+     * is being submitted after them.
+     * @returns True while the layout is not being stepped.
+     */
+    get paused(): boolean;
+    /**
+     * Tells the bridge whether the manager is stepping it.
+     * @param value - True when the manager has stopped stepping this layout.
+     */
+    set paused(value: boolean);
     /**
      * Starts the settle count again, on a simulation that has one.
      *

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

@@ -112,6 +112,12 @@ export declare class DataManager implements Manager {
     private loadEndpoints;
     /** The tally the load in progress is counting into, or null outside a load. */
     private loadTally;
+    /**
+     * Bumped by every REPLACING load as it is asked for, and by `supersedeLoads`. A load that
+     * sees it move has been overtaken, and stops with `E_SUPERSEDED` rather than touching the
+     * graph: see `addDataFromSource`.
+     */
+    private replaceGeneration;
     /**
      * Creates an instance of DataManager
      * @param eventManager - Event manager for emitting data events
@@ -273,6 +279,22 @@ export declare class DataManager implements Manager {
      * @param idPath - JMESPath expression to extract node ID from data
      */
     addNode(node: AdHocData, idPath?: string): void;
+    /**
+     * The id `addNodes` reads off a node record.
+     * @param node - the record
+     * @param idPath - JMESPath expression to extract the id; the configured node id path when unset
+     * @returns the node's id
+     */
+    nodeIdOf(node: Record<string | number, unknown>, idPath?: string): NodeIdType;
+    /**
+     * Refuse a replacing node set the renderer cannot hold, before the replace removes anything.
+     *
+     * The node half of what {@link setEdges} decides first: the new set is counted against an
+     * emptied graph, so a refused replace keeps the nodes the graph had.
+     * @param count - how many distinct nodes the graph would hold afterwards
+     * @throws A `GraphtyError` with `E_TOO_LARGE` when `count` is past the ceiling
+     */
+    refuseNodeSetAboveCeiling(count: number): void;
     /**
      * Adds multiple nodes to the graph
      * @param nodes - Array of node data objects
@@ -472,12 +494,57 @@ export declare class DataManager implements Manager {
      *     while the source has still declared nothing
      */
     private applyDeclaredDirection;
+    /**
+     * Reserve a load's place in line, at the moment the caller asked for it.
+     *
+     * A caller that reads a file or sniffs a URL before it loads calls this FIRST, so a load that
+     * was asked for later still wins however long the earlier one spends reading. A replacing load
+     * supersedes every load reserved before it.
+     * @param replace - Whether the load will replace the graph
+     * @returns The generation to hand to `addDataFromSource` and `throwIfSuperseded`
+     */
+    beginLoad(replace: boolean): number;
+    /**
+     * Abandon every load in flight: each rejects with `E_SUPERSEDED` and adds nothing more.
+     * The element's `clearData` calls this, so a load finishing after the graph was closed does
+     * not bring its data back.
+     */
+    supersedeLoads(): void;
+    /**
+     * Throw `E_SUPERSEDED` when a load reserved at `generation` has been overtaken.
+     * @param generation - What `beginLoad` returned for the load
+     * @param type - The load's format, for the message
+     */
+    throwIfSuperseded(generation: number, type: string): void;
     /**
      * Loads data from a registered data source
+     *
+     * A REPLACING load reads the whole source into memory before it touches the store, and only
+     * once the source has finished without an error does it clear the graph and add what it read.
+     * A malformed or empty file therefore leaves the graph it would have replaced exactly as it
+     * was. An additive load streams each chunk straight in, as it always has.
+     *
+     * A load that reads no node records and no edge records at all fails with `E_EMPTY_LOAD`
+     * rather than completing with zero counts. A file of edges alone is not empty: its endpoints
+     * become nodes.
+     *
+     * The load that STARTED last wins. Once a replacing load has started, every load started
+     * before it -- replacing or additive -- is superseded: it adds nothing more and rejects with
+     * `E_SUPERSEDED`, whichever order the sources finish in. A superseded load emits no
+     * `data-loading-error`, because nothing went wrong with its source.
      * @param type - Data source type identifier
      * @param opts - Options to pass to the data source
-     */
-    addDataFromSource(type: string, opts?: object): Promise<void>;
+     * @param load - Which load this is, for every event it emits, and whether it replaces the graph
+     * @param load.loadId - The id every event about this load carries
+     * @param load.replace - Swap the graph for what the source holds, once it has all parsed
+     * @param load.generation - The place `beginLoad` reserved for this load when the caller's call
+     *     was made; left unset, the load takes its place now
+     */
+    addDataFromSource(type: string, opts?: object, load?: {
+        loadId?: number;
+        replace?: boolean;
+        generation?: number;
+    }): Promise<void>;
     /**
      * Freeze one load's counters into the report a consumer reads, and keep it for `lastImport`.
      * @param format - the data source that read the file

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

@@ -65,8 +65,9 @@ export declare class EventManager implements Manager {
      * @param chunksLoaded - Number of data chunks loaded
      * @param dataSourceType - Type of data source used
      * @param report - What the load did, including which endpoint spelling resolved
+     * @param loadId - Which load this is, when it is one
      */
-    emitGraphDataLoaded(graph: Graph | GraphContext, chunksLoaded: number, dataSourceType: string, report: ImportReport): void;
+    emitGraphDataLoaded(graph: Graph | GraphContext, chunksLoaded: number, dataSourceType: string, report: ImportReport, loadId?: number): void;
     /**
      * Emits the removal event naming every node and edge one removal call took away.
      * @param nodes - the nodes that were removed
@@ -122,8 +123,9 @@ export declare class EventManager implements Manager {
      * @param nodeRecordsLoaded - How many node RECORDS the source has handed over so far
      * @param edgeRecordsLoaded - How many edge RECORDS the source has handed over so far
      * @param chunksProcessed - Number of data chunks processed
+     * @param loadId - Which load this is, when it is one
      */
-    emitDataLoadingProgress(format: string, bytesProcessed: number, totalBytes: number | undefined, nodeRecordsLoaded: number, edgeRecordsLoaded: number, chunksProcessed: number): void;
+    emitDataLoadingProgress(format: string, bytesProcessed: number, totalBytes: number | undefined, nodeRecordsLoaded: number, edgeRecordsLoaded: number, chunksProcessed: number, loadId?: number): void;
     /**
      * Emits a data loading error event when an error occurs during import
      * @param error - Error object
@@ -134,12 +136,14 @@ export declare class EventManager implements Manager {
      * @param details.nodeId - Node ID related to error
      * @param details.edgeId - Edge ID related to error
      * @param details.canContinue - Whether loading can continue after this error
+     * @param details.loadId - Which load this is, when it is one
      */
     emitDataLoadingError(error: Error, context: DataLoadingErrorEvent["context"], format: string | undefined, details: {
         line?: number;
         nodeId?: unknown;
         edgeId?: string;
         canContinue: boolean;
+        loadId?: number;
     }): void;
     /**
      * Emits a summary of all data loading errors after import completes
@@ -149,8 +153,9 @@ export declare class EventManager implements Manager {
      * @param detailedReport - Detailed error report
      * @param primaryCategory - Primary error category
      * @param suggestion - Suggested fix for the errors
+     * @param loadId - Which load this is, when it is one
      */
-    emitDataLoadingErrorSummary(format: string, totalErrors: number, message: string, detailedReport: string, primaryCategory?: string, suggestion?: string): void;
+    emitDataLoadingErrorSummary(format: string, totalErrors: number, message: string, detailedReport: string, primaryCategory?: string, suggestion?: string, loadId?: number): void;
     /**
      * Emits a data loading complete event when import finishes
      * @param format - Data format that was loaded
@@ -161,8 +166,9 @@ export declare class EventManager implements Manager {
      * @param warnings - Number of warnings encountered
      * @param success - Whether loading was successful
      * @param report - What the load did, including which endpoint spelling resolved
+     * @param loadId - Which load this is, when it is one
      */
-    emitDataLoadingComplete(format: string, nodesLoaded: number, edgesLoaded: number, duration: number, errors: number, warnings: number, success: boolean, report: ImportReport): void;
+    emitDataLoadingComplete(format: string, nodesLoaded: number, edgesLoaded: number, duration: number, errors: number, warnings: number, success: boolean, report: ImportReport, loadId?: number): void;
     /**
      * Emits a selection changed event when node selection changes
      * @param previousNode - Previously selected node (or null)

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

@@ -69,7 +69,8 @@ export interface GraphContext {
      */
     isRunning(): boolean;
     /**
-     * Set the running state
+     * Play or pause the layout on a consumer's behalf. A pause holds until `setRunning(true)`;
+     * the element's own restarts write `getLayoutManager().running`, which the pause refuses.
      */
     setRunning(running: boolean): void;
     /**

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

@@ -42,6 +42,13 @@ export declare class LayoutManager implements Manager {
     private styles;
     layoutEngine?: LayoutEngine;
     private _running;
+    /**
+     * Set while a CONSUMER has paused the layout, through {@link LayoutManager.setPaused}. Nothing
+     * inside the element clears it: a load, a freeze, an accelerator attaching, a new layout or a
+     * drag may rebuild or place nodes, but their `running = true` is refused until the consumer
+     * resumes.
+     */
+    private _paused;
     /**
      * Set when a layout was built over a graph with nothing in it, and the pre-steps it is
      * configured with have therefore not been spent. See
@@ -68,8 +75,19 @@ export declare class LayoutManager implements Manager {
      * 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.
+     *
+     * While the consumer has paused the layout (see {@link LayoutManager.setPaused}) a `true` is
+     * ignored, so the element's own restarts cannot undo the pause.
      */
     set running(value: boolean);
+    /**
+     * Pause or resume the layout on a consumer's behalf.
+     *
+     * A pause holds until the consumer resumes it: internal restarts are refused while it is set.
+     * Resuming runs the layout, and reheats a simulation that had settled.
+     * @param paused - True to pause, false to resume.
+     */
+    setPaused(paused: boolean): void;
     private graphContext;
     /**
      * The graph's acceleration controller, once a context has arrived. A manager built without a
@@ -134,7 +152,7 @@ export declare class LayoutManager implements Manager {
     /**
      * Internal method for setting layout - bypasses queue
      * Used by operations that are already queued to prevent nested queueing
-     * @param type - Layout type identifier
+     * @param layout - A registered engine name, or a catalogue layout id
      * @param opts - Layout-specific options
      */
     private _setLayoutInternal;
@@ -246,10 +264,18 @@ export declare class LayoutManager implements Manager {
      */
     getNodePosition(node: Node): [number, number, number] | undefined;
     /**
-     * Check if layout has settled
-     * @returns True if layout has settled, false otherwise
+     * Whether the layout engine has converged: the positions are final.
+     *
+     * A layout that was stopped part-way is NOT settled; it is {@link LayoutManager.isPaused}. A
+     * reader that only needs "positions are not moving right now" asks `!running || isSettled`.
+     * @returns True when the engine has converged, or when there is no engine.
      */
     get isSettled(): boolean;
+    /**
+     * Whether the layout was stopped before it converged, so its positions are not final.
+     * @returns True when the layout is not running and has not settled.
+     */
+    get isPaused(): boolean;
     /**
      * Get nodes from layout engine
      * @returns Iterable of nodes managed by the layout engine
@@ -295,6 +321,7 @@ export declare class LayoutManager implements Manager {
         layoutType: string | undefined;
         isRunning: boolean;
         isSettled: boolean;
+        isPaused: boolean;
         nodeCount: number;
         edgeCount: number;
     };

package/dist/src/meshes/MeshCache.d.ts

@@ -26,6 +26,24 @@ export declare class MeshCache {
      * Clear all cached meshes and reset statistics
      */
     clear(): void;
+    /**
+     * Dispose and forget every cached mesh that nothing is drawn from any more.
+     *
+     * Every source mesh is handed out only as instances, so one with no instances is a look no
+     * element has: a size a layer used to paint, a halo nobody is selected for. Without this the
+     * cache holds one mesh per look ever drawn, which grows with every edit to a size or a shape
+     * until the next dataset boundary. A name that is asked for again is simply built again.
+     */
+    prune(): void;
+    /**
+     * Dispose a source mesh and the material it was built with.
+     *
+     * Every creator handed to get() builds a fresh material for its mesh, so the material dies
+     * with it; `mesh.dispose()` alone would leave it in `scene.materials` for good. Textures are
+     * kept: node gradient textures are shared across materials per scene.
+     * @param mesh - The cached source mesh
+     */
+    private static disposeSource;
     /**
      * Get the number of cached meshes
      * @returns Count of cached meshes

package/dist/src/meshes/NodeEffects.d.ts

@@ -83,13 +83,16 @@ export declare class NodeEffects {
      * must not pay for it, so the only call site is the `effect.glow` branch of
      * {@link NodeEffects.applyGlowEffect}; the removal branch deliberately does NOT create one.
      *
+     * DISPOSED AGAIN WHEN NOTHING GLOWS, by {@link NodeEffects.syncGlowStrengths}. The inclusion
+     * list alone never says so: `node.glow` is a mesh channel, so a node that stops glowing moves
+     * to another source mesh and the old glowing source stays listed with no instances. The next
+     * glow recreates the layer through this method.
+     *
      * `excludeByDefault: true` is a safety catch, not a tuning knob. Babylon's inclusion list
      * means "only these" when it is non-empty and "no opinion" -- i.e. EVERY mesh in the scene --
-     * when it is empty (ThinGlowLayer.hasMesh). An empty list is not reachable today, because the
-     * layer is only created at the moment a mesh is added to it and membership is keyed by the
-     * shared source mesh (see resolveRenderedMesh), but "the whole graph blooms" is a bad enough
-     * failure to be worth one option: with this set, `_internalShouldRender` returns false while
-     * the list is empty, so an emptied layer renders nothing at all.
+     * when it is empty (ThinGlowLayer.hasMesh). With this set, `_internalShouldRender` returns
+     * false while the list is empty, so an emptied layer renders nothing rather than blooming
+     * the whole graph.
      * @param scene - The Babylon.js scene
      * @returns The glow layer for the scene
      */
@@ -142,6 +145,10 @@ export declare class NodeEffects {
      * back to 0.1) leaves a mesh with no instances behind; counted, it would hold the layer at 100
      * and round the live glow away in the 8-bit map. It keeps its entry, because a node that goes
      * back to that strength reuses the cached mesh. A disposed mesh is dropped.
+     *
+     * When no glowing source mesh draws a node any more, the layer is disposed: it is a
+     * full-screen post-process that would otherwise render nothing every frame for the life of
+     * the scene. Every node mesh is an instance, so a source with no instances draws nothing.
      * @param glowLayer - The scene's glow layer
      * @param scene - The Babylon.js scene
      */
@@ -155,8 +162,8 @@ export declare class NodeEffects {
      * with one outline configuration -- and resolving to it here would take the outline away from
      * every sibling still on screen. That is the same reasoning `Node.dispose` records for glow,
      * and it has the same consequence: for an instanced node this removes nothing, the source is
-     * freed when `MeshCache` is cleared, and the layer's leftover uniqueId is inert because
-     * Babylon's uniqueIds are monotonic per scene and never reused.
+     * freed when `MeshCache` prunes or clears it, and the layer's leftover uniqueId is inert
+     * because Babylon's uniqueIds are monotonic per scene and never reused.
      * @param mesh - The mesh to remove from highlighting
      */
     static removeFromHighlight(mesh: AbstractMesh): void;
@@ -178,10 +185,8 @@ export declare class NodeEffects {
      * The colour map is keyed by mesh uniqueId, so it MUST die with the layer: leaving it behind
      * would let a later mesh that happens to reuse a uniqueId inherit a dead style's glow colour.
      *
-     * Sibling of {@link NodeEffects.disposeHighlightLayer} and, like it, currently called from
-     * nowhere in this package -- the scene outlives every dataset, so the layers are reused rather
-     * than rebuilt. It exists so that whoever tears a scene down has one call for each layer this
-     * class can create, instead of discovering the glow layer only by leaking it.
+     * Called by {@link NodeEffects.syncGlowStrengths} once no node glows; the next glow
+     * recreates the layer lazily.
      * @param scene - The Babylon.js scene
      */
     static disposeGlowLayer(scene: Scene): void;

package/dist/src/meshes/NodeMesh.d.ts

@@ -120,8 +120,8 @@ export declare class NodeMesh {
      *      provenance is invisible here, but unbounded allocation is not.
      *
      * The cache is a WeakMap keyed by scene, so the entries die with the scene and never leak
-     * across scenes or across tests. `MeshCache.clear()` disposes meshes only -- not materials and
-     * not textures -- so a cached texture stays valid across a 2D/3D switch.
+     * across scenes or across tests. `MeshCache` disposes a source mesh's material but never its
+     * textures, so a cached texture stays valid across a 2D/3D switch.
      * @param gradient - The normalised gradient to paint
      * @param scene - Babylon.js scene that will own the texture
      * @returns The shared texture, or undefined if one cannot or should not be allocated

package/dist/src/meshes/RichTextParser.d.ts

@@ -35,3 +35,29 @@ export declare class RichTextParser {
         totalHeight: number;
     };
 }
+/**
+ * Measures one line of segments from the font's own metrics.
+ *
+ * The line's ink height is the tallest ascent plus the deepest descent over its segments, each
+ * the larger of the font box (`fontBoundingBoxAscent` / `fontBoundingBoxDescent`) and the actual
+ * glyph box, plus the outline on both sides. The line box is that height times `lineHeight`, and
+ * the extra leading is split evenly above and below, as CSS does. The label's panel height and
+ * the renderer's line advance both come from here, so they cannot disagree.
+ * @param ctx - Canvas rendering context for measurement
+ * @param lineSegments - The segments of one line
+ * @param options - Layout options
+ * @param options.lineHeight - Line height multiplier
+ * @param options.textOutline - Whether text outline is enabled
+ * @param options.textOutlineWidth - Width of text outline
+ * @returns The line's advance width, its line box height, and the distance from the top of the
+ * line box to the alphabetic baseline
+ */
+export declare function measureLine(ctx: CanvasRenderingContext2D, lineSegments: TextSegment[], options: {
+    lineHeight: number;
+    textOutline: boolean;
+    textOutlineWidth: number;
+}): {
+    width: number;
+    lineBox: number;
+    baseline: number;
+};

package/dist/src/meshes/RichTextRenderer.d.ts

@@ -43,7 +43,6 @@ export declare class RichTextRenderer {
         width: number;
         height: number;
     }): void;
-    private measureLine;
     private calculateLineStartX;
     private drawLine;
     private drawTextWithShadow;

package/dist/src/session/cost/estimate.d.ts

@@ -27,7 +27,7 @@
  * Nothing here reaches Babylon.js, Lit or the DOM: an estimate is arithmetic over plain data,
  * published from the Node-safe `./session` entry point.
  */
-import type { AlgorithmDescriptor, AlgorithmKey, CostClass, Scope } from "../../catalog/types";
+import { type AlgorithmDescriptor, type AlgorithmKey, type CostClass, type Scope } from "../../catalog/types";
 import { GraphtyError } from "../../errors/GraphtyError";
 import type { GraphStatistics } from "../types";
 /**

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

@@ -29,8 +29,8 @@ export interface LayoutRecommendation {
      * The arrangement, exactly as `catalog.layouts()` publishes it.
      *
      * `layout.id` is the public arrangement name -- `"force"`, `"circular"` -- and `layout.engine`
-     * is the registered engine name `setLayout` takes. A consumer needs the second in order to
-     * act: `element.setLayout(recommendation.layout.engine)`.
+     * is the registered engine that runs it by default. `setLayout` takes either, so a consumer
+     * acts on the id: `element.setLayout(recommendation.layout.id)`.
      */
     readonly layout: LayoutDescriptor;
     /** Why this arrangement suits this graph, in a sentence a consumer can show a reader. */
@@ -80,7 +80,7 @@ export interface LayoutRecommendationOptions {
  * });
  *
  * if (advice !== undefined) {
- *     await element.setLayout(advice.layout.engine);
+ *     await element.setLayout(advice.layout.id);
  * }
  * ```
  */

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

@@ -18,7 +18,7 @@
  * structural view of `OperationQueueManager` narrow enough that the session never imports the
  * renderer's manager to talk to it.
  */
-import type { AlgorithmDescriptor, LayerId, RunId, Scope } from "../../catalog/types";
+import { type AlgorithmDescriptor, type LayerId, type RunId, type Scope } from "../../catalog/types";
 import type { AutoApplyPolicy } from "../styles/autoApply";
 import { type RunExecutor, type RunQueueContext } from "./Run";
 import { type Caveats, type EngineVersions, type ResolvedScope, type RunChange, type RunsApi } from "./types";

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

@@ -493,6 +493,12 @@ export interface StylesSources {
      * @param change - What changed, and how much was painted.
      */
     readonly onChange?: (change: StyleChange) => void;
+    /**
+     * Aborted when the session holding the stack is disposed. Every edit still pending is
+     * cancelled with it, so a caller awaiting one gets an `AbortError` rather than waiting for
+     * ever, and an edit issued afterwards is cancelled before it starts.
+     */
+    readonly disposed?: AbortSignal;
 }
 /**
  * What a highlight paints when its caller names no style.

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

@@ -26,9 +26,17 @@
  * does today. {@link channelRole} is where that split is written down, and
  * {@link meshChannelsFor} is the list a repaint pushes.
  *
- * A KEY IS OPAQUE AND SESSION-LOCAL. It is the order a style was first seen in, so it is stable
- * for the life of the session and meaningless outside it. Nothing may persist one, compare two
- * from different sessions, or read anything back out of the number.
+ * A KEY IS OPAQUE AND SESSION-LOCAL. It names one style for the life of the session and is
+ * meaningless outside it. Nothing may persist one, compare two from different sessions, or read
+ * anything back out of the number.
+ *
+ * A KEY IS RELEASED WHEN NOTHING IS DRAWN FROM IT, AND NEVER HANDED OUT AGAIN. The repaint counts
+ * the elements drawn from each key ({@link StyleInterner.retain}, {@link StyleInterner.release}),
+ * and a style no element holds is forgotten, so what the interner keeps follows the looks on
+ * screen rather than every edit ever made. The number is not recycled: a renderer names a cached
+ * source mesh after it, and a recycled key would hand one look's mesh to another. The storage
+ * behind a key IS recycled, which is what keeps a session that edits a size a thousand times
+ * the size of the picture it draws.
  *
  * Nothing here reaches Babylon.js, Lit or the DOM.
  */
@@ -76,7 +84,7 @@ export declare function meshChannelsFor(target: "node" | "edge"): readonly Chann
  * into the interner.
  */
 export interface StyleInterner<T> {
-    /** How many distinct styles have been minted. Keys run from 0 to this less one. */
+    /** How many distinct styles are held: minted and not yet released. */
     readonly size: number;
     /** Start a new sequence, discarding anything pushed and not ended. */
     begin(): void;
@@ -105,9 +113,22 @@ export interface StyleInterner<T> {
     /**
      * Finish the sequence and answer with the key the style it describes is known by.
      * @param mint - Builds the style object, called ONLY when the sequence is new.
-     * @returns The key: the order the style was first seen in.
+     * @returns The key, which no other style is ever given in this interner.
      */
     end(mint: () => T): number;
+    /**
+     * Say that one more element is drawn from a key.
+     * @param key - The key, as {@link end} answered with.
+     */
+    retain(key: number): void;
+    /**
+     * Say that one element fewer is drawn from a key, and forget its style when none is left.
+     *
+     * A style that has been minted and never retained is held until something retains and then
+     * releases it: minting is a lookup, and a lookup must not take a style away.
+     * @param key - The key, as {@link end} answered with.
+     */
+    release(key: number): void;
     /**
      * The style one key stands for.
      * @param key - The key, as {@link end} answered with.

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

@@ -168,7 +168,8 @@ export interface ElementPaint {
      *
      * This is the number a structural hash exists to keep small: it must follow the distinct
      * SHAPES and SIZES in the picture, never the element count, and a colour encoding must not
-     * move it.
+     * move it. A mesh no element is drawn from any more is not counted: its key is released and
+     * never handed out again.
      * @param target - Nodes or edges.
      * @returns The count, which is at least one.
      */

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

@@ -15,7 +15,7 @@
 import type { DerivedGraph, GraphSnapshot, NodeId } from "@graphty/graph-format";
 import type { z } from "zod/v4";
 import type { AccelerationCapabilities, AccelerationPolicy, AccelerationStatus, GraphAccelerator } from "../acceleration";
-import type { AlgorithmKey, AttributeDescriptor, CatalogApi, EdgeId, RunId, Scope } from "../catalog/types";
+import type { AlgorithmKey, AttributeDescriptor, CatalogApi, DeprecatedCatalogMethod, EdgeId, RunId, Scope } from "../catalog/types";
 import type { DataConfig } from "../config/DataConfig";
 import type { ElementPositions } from "../data/positions";
 import type { ImportReport } from "../data/report";
@@ -347,12 +347,12 @@ export interface SessionDataApi {
  * been run. A consumer wanting only the metrics that CAN run filters on `available`; both lists
  * come off one call rather than two that could disagree.
  *
- * 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: 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.
+ * The rest of {@link CatalogApi} -- the methods named in `DeprecatedCatalogMethod` -- is absent
+ * rather than stubbed, and deprecated on `CatalogApi` itself. A consumer discovers that gap by
+ * autocomplete finding nothing, not by a call that throws. This type is derived from that list,
+ * so implementing one of them means deleting its name there and nothing here.
  */
-export type SessionCatalogApi = Pick<CatalogApi, "algorithms" | "cameras" | "formats" | "layouts" | "logSinks" | "metrics" | "palettes" | "scales">;
+export type SessionCatalogApi = Omit<CatalogApi, DeprecatedCatalogMethod>;
 /** The configuration a session carries. */
 export interface SessionConfig {
     /** The data configuration: id paths, weight paths, position scale, direction, id coercion. */

package/dist/webgpu.js

@@ -1,7 +1,7 @@
 import { EXACT_MAX_NODES as n, createAccelerator as p, verifyDevice as u } from "@graphty/webgpu-graph-algorithms";
 import { probeBrowserWebGpu as l, requestGpuContext as d } from "@graphty/webgpu-graph-algorithms/browser";
-import { r as h } from "./chunks/registry-CSba5QGJ.js";
-import { G as s } from "./chunks/GraphtyError-BwcnblTH.js";
+import { r as h } from "./chunks/registry-jB46Gmeb.js";
+import { G as s } from "./chunks/GraphtyError-B93WRH3e.js";
 const a = "webgpu-graph-algorithms", w = /* @__PURE__ */ new Set(["kind", "ctx", "options", "dispose", "verify"]);
 function b(o, e) {
   for (const [r, t] of Object.entries(o))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/graphty-element",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "A Web Component library for 3D/2D graph visualization built with Lit and Babylon.js",
   "type": "module",
   "customElements": "./dist/custom-elements.json",
@@ -134,7 +134,7 @@
     "vitepress": "^1.6.3",
     "vitest": "^3.2.4",
     "@graphty/remote-logger": "^1.3.7",
-    "@graphty/webgpu-graph-algorithms": "^0.6.5"
+    "@graphty/webgpu-graph-algorithms": "^0.6.6"
   },
   "peerDependencies": {
     "@ai-sdk/anthropic": "^2.0.50",
@@ -146,7 +146,7 @@
     "ai": "^5.0.104",
     "encrypt-storage": "^2.14.7",
     "lit": "^3.0.0",
-    "@graphty/webgpu-graph-algorithms": "^0.6.5"
+    "@graphty/webgpu-graph-algorithms": "^0.6.6"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/anthropic": {
@@ -184,9 +184,9 @@
     "papaparse": "^5.5.3",
     "toposort": "^2.0.2",
     "zod": "^3.25.28",
-    "@graphty/algorithms": "^2.0.3",
-    "@graphty/graph-format": "^1.0.5",
-    "@graphty/layout": "^1.9.1"
+    "@graphty/layout": "^1.10.0",
+    "@graphty/algorithms": "^2.0.4",
+    "@graphty/graph-format": "^1.0.5"
   },
   "overrides": {
     "storybook": "$storybook"