@graphty/graphty-element 2.0.1 → 2.2.1

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

@@ -0,0 +1,97 @@
+import { type Camera, type Scene } from "@babylonjs/core";
+import type { Node } from "../Node";
+import type { GraphContext } from "./GraphContext";
+/**
+ * Hides node labels that would be drawn on top of each other, when the graph's behaviour
+ * configuration asks for it (`labels.declutter`, off by default).
+ *
+ * Every node label is its own billboarded plane, so two labelled nodes that land near each other
+ * on screen draw their words over one another. The pass projects each drawn label's WORDS -- not
+ * its padded plane -- to a screen rectangle, orders the labels by priority -- a selected node
+ * first, then the node with more edges, then the node id so the answer is stable -- and keeps a
+ * label only if its rectangle meets no label already kept. Kept rectangles are bucketed in a
+ * screen grid, so each label is tested against its neighbours rather than against every label.
+ *
+ * THE PASS RUNS ONLY WHEN SOMETHING THAT DECIDES PLACEMENT CHANGED: the camera's view or
+ * projection, the viewport size, a label added, rebuilt or removed, a node moved, shown, hidden
+ * or (de)selected, an edge added or removed, or the setting itself. A still scene costs one cheap
+ * walk over the labelled nodes per frame and no projection at all.
+ *
+ * A label that loses is hidden with `isVisible`, never with `setEnabled` and never through a
+ * style. `setEnabled` is the visibility mask's switch (`Node.applyRenderState`), and a style is
+ * the reader's answer to what a node looks like; this is a placement decision, so it has its own
+ * switch. Turning the setting off shows every label again.
+ *
+ * ONE PER SCENE, created by the first node that draws a label, and kept on `scene.metadata`
+ * the way `NodeEffects` keeps the glow layer.
+ */
+export declare class LabelDeclutter {
+    private readonly scene;
+    private readonly context;
+    /** How many full passes have run. Read by tests to prove a still scene is not re-measured. */
+    passes: number;
+    private readonly observer;
+    private readonly entries;
+    /** Reused every pass: the candidates in priority order. */
+    private readonly order;
+    /** Reused every pass: kept labels by grid cell. Emptied, not rebuilt. */
+    private readonly grid;
+    private columns;
+    private rows;
+    private dirty;
+    private wasOn;
+    private camera;
+    private readonly view;
+    private readonly projection;
+    private width;
+    private height;
+    private edgeVersion;
+    private degrees;
+    private readonly transform;
+    private readonly toPixels;
+    private readonly worldToPixels;
+    private readonly viewport;
+    private readonly right;
+    private readonly up;
+    private readonly centre;
+    private readonly corner;
+    private readonly centreOnScreen;
+    private readonly cornerOnScreen;
+    private constructor();
+    /**
+     * Make sure the scene has a declutter pass, and add a node that is drawing a label to it.
+     * @param scene - The scene the labels are drawn in.
+     * @param context - The graph: its configuration says whether to declutter, its edges give
+     *     the degree order.
+     * @param node - The node drawing a label.
+     */
+    static track(scene: Scene, context: GraphContext, node: Node): void;
+    /** Stop running before frames. */
+    dispose(): void;
+    /** Before every frame: decide whether placement could have changed, and if so, place. */
+    run(): void;
+    /**
+     * One full pass: decide which labels are drawn.
+     * @param camera - The camera the frame is drawn from.
+     */
+    place(camera: Camera): void;
+    /**
+     * Whether anything that decides placement differs from what the last pass saw.
+     * @param camera - The camera the frame is drawn from.
+     * @returns True when the labels have to be placed again.
+     */
+    private changed;
+    /**
+     * Record what this pass sees of one node, and drop it if its label is gone.
+     * @param entry - The node.
+     * @returns Its label plane, or null when it has none.
+     */
+    private observe;
+    private remember;
+    private isClear;
+    private keep;
+    /** The setting was turned off: every label is drawn again. */
+    private showAll;
+    /** How many edges each node has, counted again only when an edge is added or removed. */
+    private refreshDegrees;
+}

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

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

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

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

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

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

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

@@ -114,14 +114,38 @@ export declare class NodeEffects {
      * material. Unfreezing to set `emissiveColor` would make every glowing style pay a material
      * re-bind per frame and would change the node's lit appearance as a side effect.
      *
-     * KNOWN LIMIT, stated rather than hidden: `intensity` is a property of the LAYER, not of a
-     * mesh, so with two glowing styles on screen the last one applied sets the strength for both.
-     * Colour is per style (see {@link NodeEffects.resolveRenderedMesh}). Per-style strength needs
-     * one layer per strength, which costs a full-screen pass each and was not worth it here.
+     * STRENGTH IS PER SOURCE MESH, like colour, through {@link NodeEffects.syncGlowStrengths}.
+     * It used to be written to `glowLayer.intensity`, which belongs to the one layer the scene
+     * shares, so the last glowing style applied set the strength of every glowing node.
      * @param mesh - The mesh to apply the effect to
      * @param effect - The effect configuration from the node style
      */
     static applyGlowEffect(mesh: AbstractMesh, effect: NodeStyleConfig["effect"] | undefined): void;
+    /**
+     * The glow strength each glowing source mesh asked for, kept on scene.metadata beside the
+     * glow colours.
+     * @param scene - The Babylon.js scene
+     * @returns The per-source-mesh strengths
+     */
+    private static glowStrengths;
+    /**
+     * Draw every glowing source mesh at its own strength, with one layer.
+     *
+     * Babylon multiplies a per-mesh `setEffectIntensity` into the glow colour as the glow map is
+     * drawn, and the layer's `intensity` scales the blurred result. The glow map is an 8-bit
+     * texture, so a per-mesh factor above 1 clamps and a strength of 3 would read the same as 1.
+     * So the layer carries the LARGEST strength on screen and each mesh carries its share of it,
+     * which is never above 1.
+     *
+     * Only source meshes that still draw a node count toward the largest strength. MeshCache
+     * never evicts a source mesh, so a strength that is no longer used (a slider dragged from 100
+     * 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.
+     * @param glowLayer - The scene's glow layer
+     * @param scene - The Babylon.js scene
+     */
+    private static syncGlowStrengths;
     /**
      * Remove a mesh from the highlight layer.
      *
@@ -149,7 +173,7 @@ export declare class NodeEffects {
      */
     static disposeHighlightLayer(scene: Scene): void;
     /**
-     * Dispose the glow layer for a scene, and forget the per-style colours with it.
+     * Dispose the glow layer for a scene, and forget the per-style colours and strengths with it.
      *
      * 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.

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

@@ -42,6 +42,8 @@ export declare class RichTextLabel {
     private parsedContent;
     private actualDimensions;
     private contentArea;
+    /** The size of the words alone, in the same units as `actualDimensions`. */
+    private textSize;
     private totalBorderWidth;
     private pointerInfo;
     private _progressValue;
@@ -112,6 +114,21 @@ export declare class RichTextLabel {
      * @returns The Babylon.js mesh or null if not created
      */
     get labelMesh(): Mesh | null;
+    /**
+     * Where the words sit on the label's plane, without its margins, padding, borders or pointer.
+     *
+     * Each edge is a fraction of the plane: `left`/`right` across it from its left edge, and
+     * `top`/`bottom` down it from its top edge, so a label whose words fill it reads
+     * `{ left: 0, right: 1, top: 0, bottom: 1 }`. Two labels whose planes overlap only in their
+     * padding do not draw over each other's words; this is what tells them apart.
+     * @returns The words' rectangle as fractions of the plane.
+     */
+    get textBounds(): {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    };
     /**
      * Gets the label's unique identifier
      * @returns The label ID

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

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

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

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

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

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

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

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

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

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

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

@@ -21,8 +21,6 @@
  *   compile error rather than a silent no-op.
  * - `edge.curvature` is a switch, not an amount. The edge renderer offsets its control points by
  *   a fixed fraction of the edge length, so "curve this edge" is the only thing it can be told.
- * - `node.glowStrength` is drawn, but Babylon keeps a glow's intensity on the LAYER rather than
- *   on a mesh, so two glowing styles on screen share whichever strength was applied last.
  * - `node.outline` is a colour and no width, for the same reason in the same shape: the stroke
  *   is drawn by a highlight LAYER whose blur size belongs to the layer, so every outline on
  *   screen is one width. This is the sentence the element's natural-language layer reads out

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

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

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

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

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

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