@yggy-tech/graphraum 0.28.0 → 0.34.0

package/README.md

@@ -65,7 +65,7 @@ Publishing is automated with semantic-release after CI succeeds on `main`. Commi
 
 ## Documentation
 
-The [documentation](https://domudev.github.io/graphraum/), [API reference](https://domudev.github.io/graphraum/api-reference/), [visual language](https://domudev.github.io/graphraum/visual-language/), and executable [browser benchmark](https://domudev.github.io/graphraum/benchmark/) are published on GitHub Pages. Run them locally with:
+The [documentation](https://domudev.github.io/graphraum/), [API reference](https://domudev.github.io/graphraum/reference/api/), and the live [playground](https://domudev.github.io/graphraum/playground/) with the Prove benchmark are published on GitHub Pages. Run them locally with:
 
 ```sh
 bun install --cwd docs

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import Graph from "graphology";
 type GraphraumColor = number | string;
 type GraphraumMode = "2d" | "3d";
 type GraphraumNodeState = "dimmed" | "focused" | "hovered" | "selected";
+/** Application-owned edge state applied with `setEdgeState`. Edge selection uses `setEdgeSelection`. */
+type GraphraumEdgeState = "dimmed";
 type GraphraumNodeShape = "circle" | "diamond" | "hexagon" | "pill" | "rounded" | "square" | "triangle";
 interface GraphraumPosition {
   x: number;
@@ -18,6 +20,11 @@ interface GraphraumNodeGeometry {
   id: string;
   position: GraphraumPosition;
   color?: GraphraumColor;
+  /**
+   * Opt-in soft halo in 0..1 (default 0, none). Glowing nodes add one batched draw call;
+   * see the visual-language docs for the radius and opacity mapping.
+   */
+  glow?: number;
   height?: number;
   shape?: GraphraumNodeShape;
   size?: number;
@@ -28,6 +35,7 @@ interface GraphraumNodeGeometry {
 type GraphraumNode<NodeAttributes = undefined> = GraphraumNodeGeometry & GraphraumAttributes<NodeAttributes>;
 interface GraphraumNodeUpdate {
   color?: GraphraumColor | undefined;
+  glow?: number | undefined;
   height?: number | undefined;
   id: string;
   position?: GraphraumPosition;
@@ -72,6 +80,11 @@ interface GraphraumDataPatch<NodeAttributes = undefined, EdgeAttributes = undefi
 }
 interface GraphraumNodeVisual {
   color?: GraphraumColor;
+  /**
+   * Opt-in soft halo in 0..1 (default 0, none). Glowing nodes add one batched draw call;
+   * see the visual-language docs for the radius and opacity mapping.
+   */
+  glow?: number;
   height?: number;
   shape?: GraphraumNodeShape;
   size?: number;
@@ -194,6 +207,10 @@ type GraphraumBackground = GraphraumColor | GraphraumPatternBackground | "transp
 type GraphraumThemeName = "dark" | "light";
 interface GraphraumTheme {
   background: GraphraumBackground;
+  /** Color of edges dimmed with `setEdgeState("dimmed", ids)`. Selected edges stay selected. */
+  dimmedEdge: GraphraumColor;
+  /** Opacity cap (0..1) for dimmed edges; an edge that is already fainter keeps its own opacity. */
+  dimmedEdgeOpacity: number;
   dimmedNode: GraphraumColor;
   edge: GraphraumColor;
   edgeOpacity: number;
@@ -227,8 +244,27 @@ interface GraphraumOptions<NodeAttributes = undefined, EdgeAttributes = undefine
   viewportOverscan?: number;
   visuals?: GraphraumVisualMapper<NodeAttributes, EdgeAttributes>;
 }
+/** Options for `Graphraum.setAutoOrbit`. */
+interface GraphraumAutoOrbitOptions {
+  /** Orbit speed in radians per second. Must be above 0 and at most 2. Defaults to 0.07 (about 90 seconds per turn). */
+  speed?: number;
+  /** Idle time in milliseconds after a pointer, wheel or key interaction before the orbit resumes. Defaults to 3000. */
+  resumeAfterMs?: number;
+}
+/** Options for `Graphraum.flyTo`. */
+interface GraphraumFlyToOptions {
+  /** Nodes to frame, as `fitView({ nodeIds })` frames them. Unknown IDs are ignored. */
+  nodeIds: readonly string[];
+  /** Flight time in milliseconds. 0 jumps. Defaults to 1200. */
+  durationMs?: number;
+  /** Multiplies the fitted 3D camera distance or 2D visible height; above 1 leaves air around the nodes. Defaults to 1. */
+  distanceScale?: number;
+}
+/** `off`: not enabled. `active`: orbiting with a running frame loop. `paused`: enabled but stopped by interaction, a hidden tab or an off-screen canvas. */
+type GraphraumAutoOrbitStatus = "active" | "off" | "paused";
 interface GraphraumDiagnostics {
   aggregatedNodeClusters: number;
+  autoOrbit: GraphraumAutoOrbitStatus;
   cpuFrameMilliseconds: number;
   gpuFrameMilliseconds: number | null;
   gpuDrawCalls: number;
@@ -236,6 +272,7 @@ interface GraphraumDiagnostics {
   gpuTextures: number;
   lodLevel: "density" | "detail" | "overview";
   pickingStrategy: "raycaster-3d" | "spatial-grid-2d";
+  dimmedEdges: number;
   selectedEdges: number;
   selectedNodes: number;
   totalEdges: number;
@@ -244,6 +281,8 @@ interface GraphraumDiagnostics {
   visibleEdgeMarkers: number;
   visibleEdgeSegments: number;
   visibleEdges: number;
+  /** Glow halo instances in the final frame (at most 256; 0 in the density LOD tier). */
+  visibleGlowNodes: number;
   visibleNodes: number;
   visibleNodeCandidates: number;
 }
@@ -262,6 +301,11 @@ interface EndpointOutline {
 interface TrimEdgeEndpointsInput {
   attach?: EndpointAttach;
   clearance?: number;
+  /**
+   * `3d` trims along the 3D segment so ends meet camera-facing outlines; exact for circles,
+   * approximate for other shapes. Default `2d`.
+   */
+  mode?: GraphraumMode;
   source: GraphraumPosition;
   sourceOutline: EndpointOutline;
   target: GraphraumPosition;
@@ -270,8 +314,16 @@ interface TrimEdgeEndpointsInput {
 /**
  * Walk from the node center toward the far point and stop on the outline,
  * then pull back by `clearance` so the stroke is not stabbed.
+ *
+ * In `2d` the outline lies in the xy plane, so only the xy part of the chord counts. In `3d` the
+ * billboard faces the camera, so the edge stops one outline radius from the center along the 3D
+ * segment. The radius is measured along the chord's world xy heading (or +x when the chord is
+ * parallel to z), not along its on-screen heading. For circles the radius is the same in every
+ * direction, so the projected end lies on the outline or inside it (where the node covers the
+ * edge) from every view. Other shapes are approximate in 3D: an elongated or angular node can end
+ * inside its outline or short of it, depending on the camera.
  */
-declare function attachPointOnOutline(center: GraphraumPosition, far: GraphraumPosition, outline: EndpointOutline, clearance?: number): GraphraumPosition;
+declare function attachPointOnOutline(center: GraphraumPosition, far: GraphraumPosition, outline: EndpointOutline, clearance?: number, mode?: GraphraumMode): GraphraumPosition;
 /** Trim both ends of a center-to-center chord (or curve endpoints) to node boundaries. */
 declare function trimEdgeEndpoints(input: TrimEdgeEndpointsInput): {
   source: GraphraumPosition;
@@ -294,6 +346,12 @@ interface ForceLayoutRequest {
    */
   linkDistances?: Float32Array;
   nodeCount: number;
+  /**
+   * Optional cluster index per node (`nodeCount` values). `createForceSimulation()` seeds nodes
+   * around cluster centres and pulls each node towards its cluster centroid
+   * (`settings.clusterStrength`). A copy is stored; the array is never mutated.
+   */
+  clusters?: Uint32Array;
   settings?: ForceSettings;
   /**
    * Optional spring strength per edge (`edges.length / 2` values).
@@ -303,19 +361,29 @@ interface ForceLayoutRequest {
 }
 interface ForceSettings {
   centerAttraction: number;
+  /**
+   * Pull of every node towards its cluster centroid, scaled by the step alpha.
+   * `0` disables the pull. Ignored without `clusters`.
+   * Omitted → `DEFAULT_FORCE_SETTINGS.clusterStrength`.
+   */
+  clusterStrength?: number;
   damping: number;
   linkDistance: number;
   repulsion: number;
   springStrength: number;
 }
-declare const DEFAULT_FORCE_SETTINGS: ForceSettings;
+declare const DEFAULT_FORCE_SETTINGS: Required<ForceSettings>;
 declare function forceIterationCount(nodeCount: number): number;
 declare function createForceSimulation(request: ForceLayoutRequest): {
   readonly nodeCount: number;
   readonly edges: Uint32Array<ArrayBuffer>;
   readonly positions: Float32Array<ArrayBuffer>;
-  /** Add nodes while preserving every existing position and velocity. */
-  addNodes(count: number, initial?: Float32Array): number;
+  /**
+   * Add nodes while preserving every existing position and velocity. A simulation created with
+   * `clusters` requires one cluster index per added node (a new id starts a new cluster); a
+   * simulation created without clusters rejects them.
+   */
+  addNodes(count: number, initial?: Float32Array, addedClusters?: Uint32Array): number;
   /** Append endpoint indices for new edges; existing edge indices remain stable. */
   addEdges(nextEdges: Uint32Array): void;
   step(alpha: number): void;
@@ -420,12 +488,16 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   private nodeMesh;
   private nodePickMesh;
   private edgeMesh;
+  private readonly glowLayer;
+  private hasGlowNodes;
   private nodeCapacity;
   private edgeCapacity;
   private markerCapacity;
   private edgeInstanceCapacity;
   private selectedNodeIds;
   private selectedEdgeIds;
+  private dimmedEdgeIds;
+  private edgeIndexCache;
   private hoveredNodeIds;
   private focusedNodeIds;
   private dimmedNodeIds;
@@ -446,6 +518,12 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   private edgeSegmentCapacity;
   private mode;
   private frameRequest;
+  private autoOrbit;
+  private flight;
+  private readonly flightDirection;
+  /** True only during the orbit's own `controls.update(dt)`; see `handleViewChange`. */
+  private orbitUpdating;
+  private destroyed;
   private cpuFrameMilliseconds;
   private gpuFrameMilliseconds;
   private gpuTimer;
@@ -469,8 +547,28 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   /** Patches GPU edge instances for moved endpoints when the visible edge set is unchanged. */
   private patchVisibleEdgeEndpoints;
   setSelection(nodeIds: Iterable<string>): void;
-  /** Highlights edges without changing node selection or source graph data. */
+  /**
+   * Highlights edges without changing node selection or source graph data. Unknown IDs are ignored.
+   * Only the instance colors of edges whose selection changed are rewritten and uploaded.
+   */
   setEdgeSelection(edgeIds: Iterable<string>): void;
+  /**
+   * Applies an application-owned edge state without changing source graph data. `dimmed` uses
+   * `theme.dimmedEdge` / `theme.dimmedEdgeOpacity`; selected edges stay selected. Unknown IDs are ignored.
+   */
+  setEdgeState(state: GraphraumEdgeState, edgeIds: Iterable<string>): void;
+  private knownEdgeIds;
+  /**
+   * Visible slots, LOD tier, and geometry only change through materialize or endpoint patches,
+   * which keep `visibleEdgeLayouts` current, so a state change repaints in place. If a layout no
+   * longer fits the drawn instances, that invariant broke: fall back to a full materialize.
+   */
+  private repaintEdgeStates;
+  private edgeStateStyling;
+  /** Edge ID to compiled index, rebuilt only when the edge list is replaced. */
+  private edgeIndicesById;
+  /** Drops edge states whose edges left the graph. */
+  private pruneEdgeStates;
   /** Applies an application-owned visual state without changing source graph data. */
   setNodeState(state: GraphraumNodeState, nodeIds: Iterable<string>): void;
   /** One-hop neighbor node ids via incident edges (undirected adjacency). */
@@ -481,6 +579,14 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   render(): void;
   setMode(mode: GraphraumMode): void;
   getMode(): GraphraumMode;
+  /**
+   * Slowly orbits the 3D camera around its target until called with `false`. The orbit pauses while
+   * the camera controls handle a drag, pinch or wheel step and resumes after `resumeAfterMs` of idle;
+   * it also stops while the document is hidden or the canvas is off screen. While it is active a
+   * frame loop renders every frame (no viewport rematerialization), so check `prefers-reduced-motion`
+   * before enabling it. Throws in 2D mode; `setMode("2d")` turns it off. Does nothing after `destroy()`.
+   */
+  setAutoOrbit(options: GraphraumAutoOrbitOptions | false): void;
   getNodePresentation(nodeId: string): CompiledGraphraumPresentation | null;
   /** Returns canvas-relative screen coordinates for a node, or null when the node does not exist. */
   getNodeScreenPosition(nodeId: string): GraphraumScreenPosition | null;
@@ -514,13 +620,70 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
    * the node pick mesh then the edge instance mesh.
    */
   pickHit(clientX: number, clientY: number): GraphraumPickHit | null;
-  fitView(): void;
+  /** Frames every node, or only `nodeIds`; unknown ids are ignored and no match frames all nodes. Cancels a running `flyTo`. */
+  fitView(options?: {
+    nodeIds?: readonly string[];
+  }): void;
+  /**
+   * Animates the camera to frame `nodeIds` as `fitView({ nodeIds })` would, with an ease-in-out
+   * over `durationMs`. In 3D the camera and the orbit target move together and keep the current
+   * view direction, so a running auto-orbit carries on around the new target, at the fitted
+   * distance times `distanceScale`. In 2D it pans and zooms. Resolves `true` on arrival and
+   * `false` when cancelled by canvas pointer, wheel or key input, another `flyTo`, `fitView`,
+   * `setData`, `setMode`, a 2D resize or `destroy()`. Unknown IDs are ignored; when none match,
+   * or after `destroy()`, it resolves `false` without moving. With `prefers-reduced-motion:
+   * reduce` or a zero duration it jumps. Throws for an invalid duration or distance scale.
+   */
+  flyTo(options: GraphraumFlyToOptions): Promise<boolean>;
+  /** Nodes whose id is in `nodeIds`, in graph order; every node when `nodeIds` is omitted. */
+  private nodesWithIds;
+  /** The closest front-view camera that frames `nodes` (issue #124); applies the container aspect. */
+  private perspectiveFit;
+  /**
+   * A 3D flight keeps the view direction it reads from the camera every frame, so an orbit step
+   * between frames turns the flight with it. The destination distance is the front-view fit
+   * distance; near and far span both ends while flying, and the far plane at arrival still holds
+   * the whole graph so the rest of it stays visible around the framed nodes.
+   */
+  private planPerspectiveFlight;
+  /**
+   * A 2D flight switches to the destination frustum up front with a zoom that keeps the current
+   * view, then pans and eases the zoom back to 1, so it lands exactly on the fitted frustum.
+   */
+  private planOrthographicFlight;
+  /** Largest distance from `center` to any node's far edge. */
+  private graphRadiusAround;
+  /** Steps a running flight to the frame time; settles and resolves it at the end. */
+  private advanceFlight;
+  private readonly cancelFlight;
   setTheme(theme: Partial<GraphraumTheme> | GraphraumThemeName): void;
   setBackground(background: GraphraumBackground): void;
   resize(): void;
   destroy(): void;
   private readonly requestRender;
+  /** Renders a pending frame now instead of on the next animation frame. */
+  private flushRender;
+  private renderFrame;
+  private stopAutoOrbit;
+  /**
+   * One orbit frame. `autoRotate` is on only for this `update(dt)` call: OrbitControls also calls
+   * `update()` without a delta from wheel and key handlers and `fitView`, which would otherwise add
+   * a fixed per-call rotation. A moved camera emits `change` (a render request only, see
+   * `handleViewChange`); flushing that request renders this frame instead of the next one. During
+   * a `flyTo` the orbit still turns the camera but leaves the pending frame to the flight, which
+   * steps from the turned direction before it renders. A
+   * throwing update, render or view listener turns the orbit off rather than leaving it enabled
+   * without a loop.
+   */
+  private readonly stepAutoOrbit;
   private readGpuTimers;
+  /**
+   * Orbit frames skip materialization. In 3D the packed instances do not depend on camera
+   * orientation: there is no viewport culling, density LOD and edge tiers follow counts only,
+   * and the one orientation-dependent value (`worldUnitsPerPixel`, for edge hit slop) is used
+   * only by 2D picking. 3D picking raycasts the instances and screen positions are projected per
+   * call, so an orbit frame needs only a render, whose view listeners still run every frame.
+   */
   private readonly handleViewChange;
   private createCamera;
   private createControls;
@@ -528,6 +691,10 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   private pickEdge;
   private worldUnitsPerPixel;
   private applySelectionColors;
+  /** Rebuilds the opt-in halo pass; graphs without glow release it and skip the visible scan. */
+  private syncGlow;
+  private readonly glowAt;
+  private readonly describeGlowNode;
   private getNodeStateIds;
   private setNodeStateIds;
   private getNodeColor;
@@ -593,6 +760,8 @@ declare function selectRichNodeIds(input: {
 /** Dark canvas: Ink Black, Turf Green, Porcelain. */
 declare const graphraumThemeDark: Readonly<{
   background: string;
+  dimmedEdge: string;
+  dimmedEdgeOpacity: number;
   dimmedNode: string;
   edge: string;
   edgeOpacity: number;
@@ -608,6 +777,8 @@ declare const graphraumThemeDark: Readonly<{
 /** Light canvas: Porcelain field with Turf marks and Ink selection. */
 declare const graphraumThemeLight: Readonly<{
   background: string;
+  dimmedEdge: string;
+  dimmedEdgeOpacity: number;
   dimmedNode: string;
   edge: string;
   edgeOpacity: number;
@@ -623,6 +794,8 @@ declare const graphraumThemeLight: Readonly<{
 declare const graphraumThemes: Readonly<{
   dark: Readonly<{
     background: string;
+    dimmedEdge: string;
+    dimmedEdgeOpacity: number;
     dimmedNode: string;
     edge: string;
     edgeOpacity: number;
@@ -637,6 +810,8 @@ declare const graphraumThemes: Readonly<{
   }>;
   light: Readonly<{
     background: string;
+    dimmedEdge: string;
+    dimmedEdgeOpacity: number;
     dimmedNode: string;
     edge: string;
     edgeOpacity: number;
@@ -653,6 +828,8 @@ declare const graphraumThemes: Readonly<{
 /** Alias of {@link graphraumThemeDark} for backward compatibility. */
 declare const graphraumTheme: Readonly<{
   background: string;
+  dimmedEdge: string;
+  dimmedEdgeOpacity: number;
   dimmedNode: string;
   edge: string;
   edgeOpacity: number;
@@ -674,4 +851,4 @@ declare function isTransparentGraphraumBackground(background: GraphraumBackgroun
 /** Defines typed, serializable graph visuals without coupling application data to the render loop. */
 declare function defineVisuals<NodeAttributes = undefined, EdgeAttributes = undefined>(visuals: GraphraumVisualMapper<NodeAttributes, EdgeAttributes>): GraphraumVisualMapper<NodeAttributes, EdgeAttributes>;
 //#endregion
-export { type CompiledGraphraumPresentation, DEFAULT_ENDPOINT_ATTACH, DEFAULT_ENDPOINT_CLEARANCE, DEFAULT_FORCE_SETTINGS, type EndpointAttach, type EndpointOutline, type ForceLayoutRequest, type ForceSettings, type GraphologyEdgeAttributes, type GraphologyNodeAttributes, type GraphologyRenderer, Graphraum, type GraphraumBackground, type GraphraumColor, type GraphraumData, type GraphraumDataPatch, type GraphraumDiagnostics, type GraphraumEdge, type GraphraumEdgeEncoding, type GraphraumEdgeMarker, type GraphraumEdgeMarkerEnd, type GraphraumEdgePath, type GraphraumEdgeStyle, type GraphraumEdgeVisual, type GraphraumLabelCandidate, type GraphraumLayoutPositions, type GraphraumMode, type GraphraumNode, type GraphraumNodeEncoding, type GraphraumNodeGeometry, type GraphraumNodeShape, type GraphraumNodeState, type GraphraumNodeUpdate, type GraphraumNodeVisual, type GraphraumOptions, GraphraumOverlay, type GraphraumOverlayNode, type GraphraumOverlayOptions, type GraphraumPatternBackground, type GraphraumPickHit, type GraphraumPosition, type GraphraumPresentation, type GraphraumPresentationAction, type GraphraumPresentationProperty, type GraphraumPropertyValue, type GraphraumScreenPosition, type GraphraumTheme, type GraphraumThemeName, type GraphraumVisualMapper, type LabelBudgetCandidate, type RichNodePolicy, type SelectBudgetedLabelIdsInput, type SelectFocusLabelIdsInput, attachPointOnOutline, bindGraphology, boundOverlayIds, computeClusteredForcePositions, computeForcePositions, createForceSimulation, defineVisuals, forceIterationCount, graphraumEdgePaths, graphraumNodeShapes, graphraumTheme, graphraumThemeDark, graphraumThemeLight, graphraumThemes, isTransparentGraphraumBackground, normalizeGraphraumBackground, orderFocusNodeIds, resolveGraphraumTheme, selectBudgetedLabelIds, selectFocusLabelIds, selectRichNodeIds, trimEdgeEndpoints };
+export { type CompiledGraphraumPresentation, DEFAULT_ENDPOINT_ATTACH, DEFAULT_ENDPOINT_CLEARANCE, DEFAULT_FORCE_SETTINGS, type EndpointAttach, type EndpointOutline, type ForceLayoutRequest, type ForceSettings, type GraphologyEdgeAttributes, type GraphologyNodeAttributes, type GraphologyRenderer, Graphraum, type GraphraumAutoOrbitOptions, type GraphraumAutoOrbitStatus, type GraphraumBackground, type GraphraumColor, type GraphraumData, type GraphraumDataPatch, type GraphraumDiagnostics, type GraphraumEdge, type GraphraumEdgeEncoding, type GraphraumEdgeMarker, type GraphraumEdgeMarkerEnd, type GraphraumEdgePath, type GraphraumEdgeState, type GraphraumEdgeStyle, type GraphraumEdgeVisual, type GraphraumFlyToOptions, type GraphraumLabelCandidate, type GraphraumLayoutPositions, type GraphraumMode, type GraphraumNode, type GraphraumNodeEncoding, type GraphraumNodeGeometry, type GraphraumNodeShape, type GraphraumNodeState, type GraphraumNodeUpdate, type GraphraumNodeVisual, type GraphraumOptions, GraphraumOverlay, type GraphraumOverlayNode, type GraphraumOverlayOptions, type GraphraumPatternBackground, type GraphraumPickHit, type GraphraumPosition, type GraphraumPresentation, type GraphraumPresentationAction, type GraphraumPresentationProperty, type GraphraumPropertyValue, type GraphraumScreenPosition, type GraphraumTheme, type GraphraumThemeName, type GraphraumVisualMapper, type LabelBudgetCandidate, type RichNodePolicy, type SelectBudgetedLabelIdsInput, type SelectFocusLabelIdsInput, attachPointOnOutline, bindGraphology, boundOverlayIds, computeClusteredForcePositions, computeForcePositions, createForceSimulation, defineVisuals, forceIterationCount, graphraumEdgePaths, graphraumNodeShapes, graphraumTheme, graphraumThemeDark, graphraumThemeLight, graphraumThemes, isTransparentGraphraumBackground, normalizeGraphraumBackground, orderFocusNodeIds, resolveGraphraumTheme, selectBudgetedLabelIds, selectFocusLabelIds, selectRichNodeIds, trimEdgeEndpoints };