@graphty/graphty-element 2.3.0 → 2.4.0

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

@@ -114,6 +114,15 @@ export declare class StylePainter {
      * @returns True when a pass has painted something the renderer has not applied.
      */
     get hasPending(): boolean;
+    /**
+     * Whether a style pass is still on its way: asked for, and not yet announced.
+     *
+     * Different from {@link StylePainter.hasPending}, which is paint that has ARRIVED and not been
+     * drawn. This is paint that has not arrived yet, and what it will change -- a colour, a size,
+     * the box the camera frames -- is not known until it does.
+     * @returns True while the bound pass is painting or queued to paint.
+     */
+    get isPainting(): boolean;
     /**
      * Take the nodes waiting to be drawn.
      * @returns Their dense indices. The set is emptied.

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

@@ -419,6 +419,11 @@ export declare class UpdateManager implements Manager {
      * @returns True when this frame will re-frame the camera, given a box to frame.
      */
     private willZoomToFit;
+    /**
+     * Whether a style pass has been asked for and has not announced what it painted yet.
+     * @returns True while the session's style stack is painting.
+     */
+    private styleIsPainting;
     /**
      * Frame the camera on a box {@link UpdateManager.willZoomToFit} has already approved.
      * @param box - The box to frame, or undefined when there is nothing to frame.

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

@@ -13,4 +13,4 @@
 export { defaultReading } from "./reading";
 export { createResultsApi, type ResultsRunEntry } from "./ResultsApi";
 export { createRunResult, type ResultElementValues } from "./RunResult";
-export { checkShapeContract, type Histogram, type HistogramBin, type HistogramBinning, type HistogramOptions, type Normalization, type NumericColumnView, type RankingEntry, type ReadingOptions, RESULT_FIELD_NAMES, RESULT_PATH_RUN_PLACEHOLDER, RESULT_ROOT, RESULT_SHAPE_CONTRACTS, resultPath, type ResultsApi, type ResultSummary, type RunRef, type RunResult, type SummaryEntry, type SummaryGroup, } from "./types";
+export { checkShapeContract, type Histogram, type HistogramBin, type HistogramBinning, type HistogramOptions, type Normalization, type NumericColumnView, type RankingEntry, type ReadingOptions, RESULT_FIELD_NAMES, RESULT_PATH_RUN_PLACEHOLDER, RESULT_ROOT, RESULT_SHAPE_CONTRACTS, resultPath, type ResultsApi, type ResultSummary, type RunRef, type RunResult, type SummaryEntry, type SummaryGroup, type TopRanking, } from "./types";

package/dist/src/session/results/statistics.d.ts

@@ -25,7 +25,7 @@
  * published from the Node-safe `./session` entry point.
  */
 import type { NodeId } from "../../catalog/types";
-import type { Histogram, HistogramOptions, Normalization, NumericColumnView, RankingEntry } from "./types";
+import type { Histogram, HistogramOptions, Normalization, NumericColumnView, RankingEntry, TopRanking } from "./types";
 /**
  * How many bins a histogram is cut into when the caller does not say.
  *
@@ -182,6 +182,13 @@ export interface RankableEntry {
  * @returns The ranking, best first. Entries with no finite value are left out.
  */
 export declare function rankEntries(entries: readonly RankableEntry[]): readonly RankingEntry[];
+/**
+ * The top `n` of a ranking, cut only between tie groups. See {@link TopRanking} for the policy.
+ * @param ranking - The ranking, best first, with tied entries sharing a rank.
+ * @param n - The most entries the top may hold, a whole number.
+ * @returns The entries taken, and the group that did not fit when one did not.
+ */
+export declare function topOfRanking(ranking: readonly RankingEntry[], n: number): TopRanking;
 /** How one histogram is cut, including the one thing the caller never has to say. */
 interface HistogramRequest extends HistogramOptions {
     /**

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

@@ -479,6 +479,30 @@ export interface RankingEntry {
     /** The share of measured elements it ranks at or above, from 0 to 1. */
     readonly percentile: number;
 }
+/**
+ * The top of a ranking, cut only between tie groups.
+ *
+ * THE TIE POLICY: a group of elements that share a value is taken whole or not at all, and it is
+ * taken only when the whole group fits inside the limit. With ranks that share a place (1, 2, 2,
+ * 4), a group of size `s` at rank `r` is in exactly when `r + s - 1 <= n`. So the top never holds
+ * more than `n` elements and never splits a tie by an arbitrary order -- and it can hold FEWER
+ * than `n`, or none at all on a graph whose top value is shared by more than `n` elements.
+ * {@link TopRanking.leftOut} and {@link TopRanking.reason} say when that happened.
+ */
+export interface TopRanking {
+    /** The elements taken, best first: whole tie groups only, never more than the limit. */
+    readonly entries: readonly RankingEntry[];
+    /**
+     * The tie group that stopped the top short: the first group that did not fit, with its
+     * value and its size. Null when nothing was left out on account of a tie.
+     */
+    readonly leftOut: {
+        readonly value: number;
+        readonly count: number;
+    } | null;
+    /** Why fewer elements were taken than the limit allowed, in a sentence; null when none were left out. */
+    readonly reason: string | null;
+}
 /** One bar of a histogram. */
 export interface HistogramBin {
     /** The lowest value the bin holds, inclusive. */
@@ -646,6 +670,15 @@ export interface RunResult {
      * @returns The entries, best first.
      */
     ranking(field: string, limit?: number): readonly RankingEntry[];
+    /**
+     * The top `n` elements on one field, cut only between tie groups. See {@link TopRanking}
+     * for the tie policy. A `{ match: "top" }` style selector and a `{ top }` selection target
+     * both read this, so the two can never disagree about which elements are the top `n`.
+     * @param field - The field to rank on.
+     * @param n - The most elements the top may hold.
+     * @returns The elements taken, and the tie group left out when there was one.
+     */
+    top(field: string, n: number): TopRanking;
     /**
      * The distribution of one numeric field.
      * @param field - The field to bin.

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

@@ -104,7 +104,10 @@ export type SelectionTarget = ElementIdTarget | NeighborhoodTarget
  | {
     readonly scope: Scope;
 }
-/** The highest-ranked elements of a finished run. */
+/**
+ * The highest-ranked elements of a finished run. A tie group is taken whole and only when it
+ * fits inside `n`, so this can select fewer than `n` elements, or none. See `TopRanking` in the results types.
+ */
  | {
     readonly top: {
         readonly run: RunRef;

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

@@ -115,6 +115,19 @@ export interface SelectorSource {
      * @returns The indices, or undefined when the column cannot be enumerated.
      */
     readonly measured?: (path: Path, target: SelectorTarget) => ArrayLike<number> | undefined;
+    /**
+     * The lowest value in the top `n` of one run column, cut only between tie groups (see
+     * `RunResult.top`), or undefined when nothing is taken or the column is not a ranked run
+     * field for this kind of element. Absent, a `{match:"top"}` selector is refused.
+     *
+     * Asked once per element, so it must answer from something already computed: a session
+     * reads it off the run's result, which keeps the answer per field and `n`.
+     * @param path - The column path, `results.<run>.<field>`.
+     * @param target - Whether the asking layer paints nodes or edges.
+     * @param n - The most elements the top may hold.
+     * @returns The cut, or undefined.
+     */
+    readonly topCut?: (path: Path, target: SelectorTarget, n: number) => number | undefined;
 }
 /**
  * One target's half of a {@link SelectorSource}, resolved once so the predicate never chooses.
@@ -160,7 +173,7 @@ export type ElementPredicate = (index: number) => boolean;
 /** A selector, reduced to the test a repaint runs and the columns that test reads. */
 export interface CompiledSelector {
     /** Which selector kind this was compiled from. */
-    readonly match: "everything" | "expression" | "has" | "ids";
+    readonly match: "everything" | "expression" | "has" | "ids" | "top";
     /** Which kind of element it speaks about. */
     readonly target: SelectorTarget;
     /**
@@ -231,6 +244,18 @@ export declare function hasPredicate(columns: ElementColumns, path: Path): Eleme
  * @returns The test.
  */
 export declare function idsPredicate(columns: ElementColumns, ids: ReadonlySet<EdgeId | NodeId>): ElementPredicate;
+/**
+ * The predicate for `{match:"top"}`: the element's value is at or above the top's cut.
+ *
+ * The cut is asked for per element rather than settled here, because a run that finishes or
+ * re-runs after the layer was added publishes a new ranking, and a cut captured now would go on
+ * painting the old top.
+ * @param columns - Where to read values.
+ * @param path - The column path.
+ * @param cutOf - The lowest value in the top, or undefined when nothing is in it.
+ * @returns The test.
+ */
+export declare function topPredicate(columns: ElementColumns, path: Path, cutOf: () => number | undefined): ElementPredicate;
 /**
  * Parse and compile `{match:"expression"}`.
  *

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.
      */
@@ -211,6 +212,17 @@ export interface ElementPaint {
      * @returns A function that stops the notifications.
      */
     onPainted(listener: () => void): () => void;
+    /**
+     * Whether a pass has been asked for and has not finished yet.
+     *
+     * A pass YIELDS TO THE EVENT LOOP and waits behind the pass in front of it, so between the
+     * edit that asks for it and the announcement that ends it there are frames -- as many as the
+     * machine is slow. Nothing is in {@link ElementPaint.lastPainted} for those frames, and a
+     * renderer that asked only whether paint was waiting to be drawn would call the picture
+     * finished, and frame the camera on it, while a node's new size was still on its way.
+     * @returns True from the moment a pass is requested until it has announced what it painted.
+     */
+    painting(): boolean;
     /**
      * The layers the last pass could not paint, and why.
      * @returns The problems, emptied at the start of every pass.

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

@@ -68,6 +68,17 @@ export type Selector =
     readonly match: "ids";
     readonly nodes?: readonly NodeId[];
     readonly 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`.
+ * So a layer never paints more than `n` elements, and paints none on a graph whose highest
+ * value is shared by more than `n`. `RunResult.top` is the same cut with its reason.
+ */
+ | {
+    readonly match: "top";
+    readonly path: Path;
+    readonly n: number;
 };
 /**
  * Turn a selector into the predicate a repaint runs.
@@ -81,6 +92,7 @@ export type Selector =
  * @returns The compiled selector: its test, and the columns that test reads.
  * @throws A `GraphtyError` with code `E_BAD_SELECTOR` when the selector's shape or its
  *     expression is wrong, `E_SELECTOR_EMPTY` when a selector is empty, and `E_UNSUPPORTED`
- *     when an `ids` selector is offered to a session that cannot say which id sits at which row.
+ *     when an `ids` selector is offered to a session that cannot say which id sits at which row,
+ *     or a `top` selector to one that cannot rank a run's column.
  */
 export declare function compileSelector(selector: Selector, target: SelectorTarget, source: SelectorSource): CompiledSelector;

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

@@ -131,6 +131,15 @@ export interface SessionSelectorSource extends SelectorSource {
      * @returns The indices, ascending, or undefined when the column cannot be enumerated.
      */
     readonly measured: (path: Path, target: SelectorTarget) => ArrayLike<number> | undefined;
+    /**
+     * The lowest value in the top `n` of a run's column, from `RunResult.top`, which keeps it.
+     * @param path - The column path, `results.<run>.<field>`.
+     * @param target - Whether the asking layer paints nodes or edges.
+     * @param n - The most elements the top may hold.
+     * @returns The cut, or undefined when nothing is taken or the path names no numeric field of
+     *     this kind of element.
+     */
+    readonly topCut: (path: Path, target: SelectorTarget, n: number) => number | undefined;
 }
 /**
  * The id of the node at one end of an edge, for the attribute keys that name an endpoint.

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.0",
+  "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"