@graphty/graphty-element 2.3.0 → 2.3.1

package/dist/graphty.js

@@ -1,14 +1,14 @@
-import { A as e, a as E, b as r, D as O, E as o, d as S, G as R, e as _, I as t, L, N as C, O as A, R as N, S as n, f as I, g as T, h as g, U as i, i as l } from "./chunks/index-CD0_RJv-.js";
-import { a as p, S as G, b as f } from "./chunks/paletteRegistry-DnWHQsAD.js";
-import { D as y, E as D } from "./chunks/DataSource-bt0DhBjG.js";
-import { k as P, l as U, g as c, h as m, A as u, C as x, i as B } from "./chunks/Algorithm-RQ629NLb.js";
-import { e as H, E as b, N as Y, a as F, P as W, R as k, S as K, d as v, b as w, c as Q } from "./chunks/NodeStyle-DKj7HjMJ.js";
-import { A as j, a as q, G as z, i as J, b as Z } from "./chunks/GraphtyError-BwcnblTH.js";
-import { B as aa, a as sa, b as ea, C as Ea, G as ra, c as Oa, I as oa, O as Sa, d as Ra, e as _a, f as ta, P as La, g as Ca, h as Aa, R as Na, T as na, i as Ia, V as Ta, Y as ga } from "./chunks/sequential-Zym81qm7.js";
-import { a as la, G as da, V as pa, i as Ga } from "./chunks/GraphStyle-D0PXnZKu.js";
-import { c as ha } from "./chunks/common-DWNKjpH_.js";
+import { A as e, a as E, b as r, D as O, E as o, d as S, G as R, e as _, I as L, L as t, N as C, O as A, R as N, S as n, f as I, g as T, h as g, U as i, i as p } from "./chunks/index-C0mIoumR.js";
+import { L as l, S as G, a as f } from "./chunks/paletteRegistry-x7WOEKZY.js";
+import { D, E as M } from "./chunks/DataSource-OeN3NeyD.js";
+import { I as P, J as U, p as c, q as m, A as u, C as x, x as B } from "./chunks/optionsFromZod-17lkrAJs.js";
+import { e as H, E as b, N as Y, a as F, P as W, R as K, S as k, d as q, b as v, c as w } from "./chunks/NodeStyle-DKj7HjMJ.js";
+import { A as Q, a as X, G as j, i as z, b as Z } from "./chunks/GraphtyError-BwcnblTH.js";
+import { B as aa, a as sa, b as ea, C as Ea, G as ra, c as Oa, I as oa, O as Sa, d as Ra, e as _a, f as La, P as ta, g as Ca, h as Aa, R as Na, T as na, i as Ia, V as Ta, Y as ga } from "./chunks/sequential-Zym81qm7.js";
+import { a as pa, G as da, V as la, i as Ga } from "./chunks/GraphStyle-Cwr55SAE.js";
+import { c as ya } from "./chunks/common-DWNKjpH_.js";
 export {
-  j as ACCELERATION_ERROR_CODES,
+  Q as ACCELERATION_ERROR_CODES,
   P as ACCELERATION_MIN_NODES_DEFAULT,
   U as ACCELERATION_MIN_NODES_KEY,
   c as ACCELERATION_POLICIES,
@@ -22,41 +22,41 @@ export {
   r as BUILTIN_PRESETS,
   Ea as CARBON_COLORS,
   x as CPU_PRECISION,
-  la as DEFAULT_VIEW_MODE,
+  pa as DEFAULT_VIEW_MODE,
   O as DataManager,
-  y as DataSource,
+  D as DataSource,
   H as EDGE_CONSTANTS,
   o as Edge,
   b as EdgeStyle,
-  D as ErrorAggregator,
+  M as ErrorAggregator,
   S as EventManager,
-  q as GRAPHTY_ERROR_CODES,
+  X as GRAPHTY_ERROR_CODES,
   ra as GREENS_COLORS,
   Oa as GREEN_SUCCESS,
   R as Graph,
   da as GraphBackground,
   _ as Graphty,
-  z as GraphtyError,
+  j as GraphtyError,
   oa as INFERNO_COLORS,
-  t as InputManager,
-  p as LayoutEngine,
-  L as LayoutManager,
+  L as InputManager,
+  l as LayoutEngine,
+  t as LayoutManager,
   C as Node,
   Y as NodeShapes,
   F as NodeStyle,
   Sa as OKABE_ITO_COLORS,
   Ra as ORANGES_COLORS,
   _a as ORANGE_WARNING,
-  ta as OTHER_GROUP_COLOR,
+  La as OTHER_GROUP_COLOR,
   A as OperationQueueManager,
-  La as PASTEL_COLORS,
+  ta as PASTEL_COLORS,
   Ca as PLASMA_COLORS,
   Aa as PURPLE_GREEN_COLORS,
   W as PolyhedronType,
   Na as RED_BLUE_COLORS,
   N as RenderManager,
-  k as RichTextStyle,
-  K as SHAPE_CONSTANTS,
+  K as RichTextStyle,
+  k as SHAPE_CONSTANTS,
   n as ScreenshotError,
   I as ScreenshotErrorCode,
   T as SelectionManager,
@@ -66,16 +66,16 @@ export {
   na as TOL_MUTED_COLORS,
   Ia as TOL_VIBRANT_COLORS,
   i as UpdateManager,
-  pa as VIEW_MODE_VALUES,
+  la as VIEW_MODE_VALUES,
   Ta as VIRIDIS_COLORS,
   ga as YLORBR_COLORS,
-  ha as colorToHex,
-  v as defaultEdgeStyle,
-  w as defaultNodeStyle,
-  Q as defaultRichTextLabelStyle,
-  l as defaultXRConfig,
+  ya as colorToHex,
+  q as defaultEdgeStyle,
+  v as defaultNodeStyle,
+  w as defaultRichTextLabelStyle,
+  p as defaultXRConfig,
   B as isAccelerationPolicy,
-  J as isGraphtyError,
+  z as isGraphtyError,
   Z as isGraphtyErrorCode,
   Ga as isViewMode
 };

package/dist/schema.js

@@ -1,7 +1,7 @@
 import { R as N, e as x } from "./chunks/types-B7bX5c0K.js";
 import { M as A, h as y, i as M } from "./chunks/interpolation-DY-PNpqX.js";
 import { B as D, a as U, b as B, C as P, G as H, c as V, I as $, O as w, d as F, e as W, f as Y, P as j, g as k, h as q, R as K, T as v, i as z, V as J, Y as Q } from "./chunks/sequential-Zym81qm7.js";
-import { D as Z, a as tt, G as nt, b as at, V as st, i as et } from "./chunks/GraphStyle-D0PXnZKu.js";
+import { D as Z, a as tt, G as nt, b as at, V as st, i as et } from "./chunks/GraphStyle-Cwr55SAE.js";
 import { E as rt, N as ct, a as it, R as Ot, d as St, b as Rt, c as lt } from "./chunks/NodeStyle-DKj7HjMJ.js";
 import { c as ft } from "./chunks/common-DWNKjpH_.js";
 function l(t) {

package/dist/session.d.ts

@@ -78,7 +78,7 @@ export type { LayoutRecommendation, LayoutRecommendationOptions } from "./src/se
 export { recommendLayout } from "./src/session";
 export type { BatchResult, BatchStep, Caveats, EngineVersions, Precision, Progress, QueueEntry, QueuePolicy, ResolvedScope, Run, RunChange, RunDirection, RunExecutionContext, RunExecutor, RunOptions, RunOutcome, RunPhase, RunProgressReport, RunQueue, RunRecord, RunRemoval, RunsApi, RunScopeRecord, RunSpec, RunStatus, RunStyle, StaleNote, StartOptions, WeightMeaning, } from "./src/session/runs";
 export { isRunId, isRunStatus, isTerminalRunStatus, QUEUE_POLICIES, RUN_ID_PATTERN, RUN_PHASES, RUN_STATUSES, TERMINAL_RUN_STATUSES, } from "./src/session/runs";
-export type { Histogram, HistogramBin, HistogramBinning, HistogramOptions, Normalization, NumericColumnView, RankingEntry, ReadingOptions, ResultsApi, ResultSummary, RunRef, RunResult, SummaryEntry, SummaryGroup, } from "./src/session/results";
+export type { Histogram, HistogramBin, HistogramBinning, HistogramOptions, Normalization, NumericColumnView, RankingEntry, ReadingOptions, ResultsApi, ResultSummary, RunRef, RunResult, SummaryEntry, SummaryGroup, TopRanking, } from "./src/session/results";
 export { defaultReading, RESULT_FIELD_NAMES, RESULT_ROOT, RESULT_SHAPE_CONTRACTS, resultPath } from "./src/session/results";
 export type { SavedScope, ScopeApi, ScopeCount, ScopeCountOptions } from "./src/session/scope";
 export { DEFAULT_SCOPE_SAMPLE } from "./src/session/scope";

package/dist/session.js

@@ -1,10 +1,9 @@
 import { R, e as _ } from "./chunks/types-B7bX5c0K.js";
-import { A as c, a as C, G as p, i as m, b as g } from "./chunks/GraphtyError-BwcnblTH.js";
-import { g as O, h as U, i as I } from "./chunks/Algorithm-RQ629NLb.js";
-import { D as h } from "./chunks/GraphSession-iNyKm7Ds.js";
-import { a as N, b as y, c as D, d as v, Q as w, R as G, e as b, f as x, S as F, T as M, g as z, i as k, h as H, j as Y, k as j } from "./chunks/GraphSession-iNyKm7Ds.js";
-import { R as Q, t as X, u as B, v as J, w as K, x as V } from "./chunks/paletteRegistry-DnWHQsAD.js";
-import { L as s } from "./chunks/scales-DyuwlJKI.js";
+import { A as c, a as C, G as p, i as m, b as L } from "./chunks/GraphtyError-BwcnblTH.js";
+import { p as O, q as U, R as I, t as P, u as y, w as N, x as D, y as w, z as v } from "./chunks/optionsFromZod-17lkrAJs.js";
+import { D as h } from "./chunks/GraphSession-Bef1AYw9.js";
+import { a as b, b as x, c as F, d as z, Q as M, R as k, e as H, f as Y, S as j, T as q, g as Q, i as X, h as B, j as J, k as K } from "./chunks/GraphSession-Bef1AYw9.js";
+import { L as s } from "./chunks/scales-BRwl51k8.js";
 const u = [
   {
     id: "fixed",
@@ -53,34 +52,34 @@ export {
   c as ACCELERATION_ERROR_CODES,
   O as ACCELERATION_POLICIES,
   U as ACCELERATION_POLICY_DEFAULT,
-  N as DEFAULT_COST_GATE_LIMITS,
-  y as DEFAULT_EXACT_COMPUTATION_CAP_SECONDS,
+  b as DEFAULT_COST_GATE_LIMITS,
+  x as DEFAULT_EXACT_COMPUTATION_CAP_SECONDS,
   h as DEFAULT_LIMITS,
-  D as DEFAULT_SCOPE_SAMPLE,
-  v as DEFAULT_SELECTION_CAP,
+  F as DEFAULT_SCOPE_SAMPLE,
+  z as DEFAULT_SELECTION_CAP,
   C as GRAPHTY_ERROR_CODES,
   p as GraphtyError,
-  w as QUEUE_POLICIES,
-  Q as RESULT_FIELD_NAMES,
-  X as RESULT_ROOT,
+  M as QUEUE_POLICIES,
+  I as RESULT_FIELD_NAMES,
+  P as RESULT_ROOT,
   R as RESULT_SHAPES,
-  B as RESULT_SHAPE_CONTRACTS,
-  G as RUN_ID_PATTERN,
-  b as RUN_PHASES,
-  x as RUN_STATUSES,
-  F as SET_OPS,
-  M as TERMINAL_RUN_STATUSES,
-  z as createGraphSession,
-  J as defaultReading,
-  I as isAccelerationPolicy,
-  k as isAlgorithmRunCommand,
+  y as RESULT_SHAPE_CONTRACTS,
+  k as RUN_ID_PATTERN,
+  H as RUN_PHASES,
+  Y as RUN_STATUSES,
+  j as SET_OPS,
+  q as TERMINAL_RUN_STATUSES,
+  Q as createGraphSession,
+  N as defaultReading,
+  D as isAccelerationPolicy,
+  X as isAlgorithmRunCommand,
   m as isGraphtyError,
-  g as isGraphtyErrorCode,
+  L as isGraphtyErrorCode,
   _ as isResultShape,
-  H as isRunId,
-  Y as isRunStatus,
-  j as isTerminalRunStatus,
-  K as quotePath,
+  B as isRunId,
+  J as isRunStatus,
+  K as isTerminalRunStatus,
+  w as quotePath,
   T as recommendLayout,
-  V as resultPath
+  v as resultPath
 };

package/dist/src/Graph.d.ts

@@ -558,9 +558,17 @@ export declare class Graph implements GraphContext {
         [key: string]: unknown;
     }[], options?: QueueableOptions): Promise<void>;
     /**
-     * Set the active camera mode (e.g., "arcRotate", "universal").
-     * @param mode - Camera mode key to activate
+     * Activate the camera that belongs to the current view mode: `"2d"` in 2D, `"orbit"` in 3D.
+     *
+     * A camera belongs to one view mode, and switching between them is `setViewMode`'s job: it
+     * also rebuilds the meshes and the layout for the new mode. A camera from the other mode is
+     * refused rather than activated, because activating it would leave the scene drawing through
+     * one mode's camera while recording the other, and `setViewMode` would then take the scene
+     * for already being where it was asked to go.
+     * @param mode - Camera key to activate
      * @param options - Queue options for operation ordering
+     * @throws A `GraphtyError` with `E_BAD_COMMAND` when the camera does not belong to the view
+     * mode the graph is in (or is going to, once queued view-mode changes run).
      */
     setCameraMode(mode: CameraKey, options?: QueueableOptions): Promise<void>;
     /**
@@ -900,6 +908,27 @@ export declare class Graph implements GraphContext {
      * the session begins when a consumer calls `setViewMode` from a click.
      */
     private applyOpeningViewMode;
+    /**
+     * Frame the graph on the element's own initiative -- after a data load, a new layout, or the
+     * first settlement -- unless the configuration placed the camera itself with
+     * `startingCameraDistance`. An explicit `zoomToFit()` is not affected.
+     */
+    private autoFrame;
+    /**
+     * Set how far the camera stands from the graph, and stop the element framing the graph on its
+     * own. Undefined hands framing back to zoom-to-fit.
+     *
+     * The 3D orbit camera is moved to the distance (floored at its minimum zoom distance). The 2D
+     * camera's half-width becomes the half-extent the 3D camera's field of view covers at that
+     * distance, so switching view mode keeps a comparable framing.
+     * @param distance - The distance, in scene units, or undefined for automatic framing.
+     * @throws A `GraphtyError` with `E_OPTION_RANGE` when the distance is not a finite number.
+     */
+    setStartingCameraDistance(distance: number | undefined): void;
+    /**
+     * Place both cameras from the configured `startingCameraDistance`, when there is one.
+     */
+    private applyStartingCameraDistance;
     /**
      * Set the view mode.
      * This controls the camera type, input handling, and rendering approach.
@@ -1340,8 +1369,9 @@ export declare class Graph implements GraphContext {
      * Required because cameraDistance is not a scene node property
      * @param orbitController - Orbit camera controller instance
      * @param orbitController.cameraDistance - Current camera distance from pivot
+     * @param orbitController.clampDistance - The controller's distance rule (the zoom floor)
      * @param orbitController.updateCameraPosition - Function to update camera position
-     * @param targetDistance - Target camera distance to animate to
+     * @param requestedDistance - Camera distance to animate to, before the zoom floor applies
      * @param frameCount - Number of frames for the animation
      * @param fps - Frames per second for the animation
      * @param easing - Optional easing function name

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/src/graphty-element.d.ts

@@ -575,12 +575,13 @@ export declare class Graphty extends LitElement {
      */
     set background(value: GraphBackgroundConfig | undefined);
     /**
-     * How far the camera starts from the graph.
+     * How far the camera starts from the graph, in scene units.
      * @remarks
-     * It is carried in the element's configuration document. NOTHING READS IT YET -- no camera
-     * is placed from it today, and that was true before this property existed; the property
-     * makes the setting reachable again rather than newly effective. A graph that has settled is
-     * framed by `zoomToFit()`.
+     * Set, it places the 3D camera at this distance from the orbit centre (never closer than the
+     * minimum zoom distance) and gives the 2D camera the same view height, and the element stops
+     * framing the graph on its own after a data load or a layout change. `zoomToFit()` still
+     * frames it when called. Unset (the default), every load is framed to fit. Setting it on a
+     * running graph moves the camera.
      * @since 2.0.0
      * @example
      * ```typescript
@@ -1690,10 +1691,14 @@ export declare class Graphty extends LitElement {
      */
     getMeshCache(): import("./meshes/MeshCache").MeshCache;
     /**
-     * Set the camera mode.
+     * Activate the camera of the current view mode: `"orbit"` in 3D, `"2d"` in 2D.
+     * @remarks
+     * A camera from the other view mode is refused; change view mode with `viewMode` or
+     * `setViewMode`, which switches the camera with it.
      * @param mode - Camera mode key
      * @param options - Queue options
      * @returns Promise that resolves when camera mode is set
+     * @throws A `GraphtyError` with `E_BAD_COMMAND` when the camera belongs to another view mode
      * @since 1.5.0
      */
     setCameraMode(mode: import("./cameras/CameraManager").CameraKey, options?: import("./utils/queue-migration").QueueableOptions): Promise<void>;

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/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/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/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

@@ -211,6 +211,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.