@yggy-tech/graphraum 0.0.0-stage → 0.34.0

package/dist/index.d.ts

@@ -0,0 +1,854 @@
+import Graph from "graphology";
+//#region src/types.d.ts
+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;
+  y: number;
+  z?: number;
+}
+type GraphraumAttributes<Attributes> = [Attributes] extends [undefined] ? {
+  attributes?: never;
+} : {
+  attributes: Attributes;
+};
+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;
+  strokeColor?: GraphraumColor;
+  strokeWidth?: number;
+  width?: number;
+}
+type GraphraumNode<NodeAttributes = undefined> = GraphraumNodeGeometry & GraphraumAttributes<NodeAttributes>;
+interface GraphraumNodeUpdate {
+  color?: GraphraumColor | undefined;
+  glow?: number | undefined;
+  height?: number | undefined;
+  id: string;
+  position?: GraphraumPosition;
+  shape?: GraphraumNodeShape | undefined;
+  size?: number | undefined;
+  strokeColor?: GraphraumColor | undefined;
+  strokeWidth?: number | undefined;
+  width?: number | undefined;
+}
+/** A transferable XYZ position batch in the same order as `nodeIds`. */
+interface GraphraumLayoutPositions {
+  nodeIds: readonly string[];
+  positions: Float32Array;
+}
+type GraphraumEdgeStyle = "solid" | "dashed" | "dotted";
+type GraphraumEdgeMarker = "none" | "triangle";
+type GraphraumEdgeMarkerEnd = "target" | "source" | "both";
+type GraphraumEdgePath = "straight" | "quadratic" | "cubic";
+type GraphraumEdge<EdgeAttributes = undefined> = {
+  color?: GraphraumColor;
+  width?: number;
+  opacity?: number;
+  style?: GraphraumEdgeStyle;
+  marker?: GraphraumEdgeMarker;
+  markerSize?: number;
+  markerEnd?: GraphraumEdgeMarkerEnd;
+  path?: GraphraumEdgePath;
+  controlPoints?: readonly GraphraumPosition[];
+  id: string;
+  source: string;
+  target: string;
+} & GraphraumAttributes<EdgeAttributes>;
+interface GraphraumData<NodeAttributes = undefined, EdgeAttributes = undefined> {
+  nodes: readonly GraphraumNode<NodeAttributes>[];
+  edges: readonly GraphraumEdge<EdgeAttributes>[];
+}
+interface GraphraumDataPatch<NodeAttributes = undefined, EdgeAttributes = undefined> {
+  addedNodes?: readonly GraphraumNode<NodeAttributes>[];
+  addedEdges?: readonly GraphraumEdge<EdgeAttributes>[];
+  removedNodeIds?: readonly string[];
+  removedEdgeIds?: readonly string[];
+}
+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;
+  strokeColor?: GraphraumColor;
+  strokeWidth?: number;
+  width?: number;
+}
+interface GraphraumEdgeVisual {
+  color?: GraphraumColor;
+  width?: number;
+  opacity?: number;
+  style?: GraphraumEdgeStyle;
+  marker?: GraphraumEdgeMarker;
+  markerSize?: number;
+  markerEnd?: GraphraumEdgeMarkerEnd;
+  path?: GraphraumEdgePath;
+  controlPoints?: readonly GraphraumPosition[];
+}
+type GraphraumPropertyValue = boolean | null | number | string;
+interface GraphraumPresentationProperty {
+  id: string;
+  label: string;
+  value: GraphraumPropertyValue;
+}
+interface GraphraumPresentationAction {
+  disabled?: boolean;
+  id: string;
+  label: string;
+}
+interface GraphraumPresentation {
+  actions?: readonly GraphraumPresentationAction[];
+  properties?: readonly GraphraumPresentationProperty[];
+  subtitle?: string;
+  title: string;
+}
+interface CompiledGraphraumPresentation extends GraphraumPresentation {
+  actions: readonly Readonly<GraphraumPresentationAction>[];
+  properties: readonly Readonly<GraphraumPresentationProperty>[];
+}
+interface GraphraumScreenPosition {
+  visible: boolean;
+  x: number;
+  y: number;
+}
+interface GraphraumOverlayNode {
+  id: string;
+  presentation: CompiledGraphraumPresentation | null;
+}
+interface GraphraumLabelCandidate {
+  id: string;
+  importance: number;
+  visible: boolean;
+}
+interface GraphraumOverlayOptions {
+  /**
+   * Label refresh policy. `manual` only shows ids from `setLabels()`. `auto` budgets by
+   * importance on view change. `focus` budgets selected ∪ hovered ∪ 1-hop neighbors first.
+   * When omitted, `autoLabels: true` maps to `auto` for compatibility; otherwise `manual`.
+   */
+  labelPolicy?: "manual" | "auto" | "focus";
+  /**
+   * When `labelPolicy` is `focus`, controls whether leftover budget is filled by importance.
+   * Default `importance`. Use `none` for selected/hover/neighbor labels only.
+   */
+  focusLabelFill?: "importance" | "none";
+  /**
+   * @deprecated Prefer `labelPolicy: "auto"`. When `labelPolicy` is omitted, `true` enables `auto`.
+   */
+  autoLabels?: boolean;
+  /**
+   * When set with `renderToolbar`, keeps the toolbar pinned to the selected or hovered node.
+   * Default `false` — host calls `setToolbar` manually.
+   */
+  autoToolbar?: false | "selected" | "hovered";
+  overlayClassName?: string;
+  maxLabels?: number;
+  /**
+   * Hard cap for host HTML focus cards. Default 24. Manual `setRichNodes` throws when exceeded;
+   * `autoRichNodes` slices to the cap.
+   */
+  maxRichNodes?: number;
+  labelClassName?: string;
+  toolbarClassName?: string;
+  richNodeClassName?: string;
+  /**
+   * When set with `renderRichNode`, keeps focus cards on selected and/or hovered nodes.
+   * Default `false` — host calls `setRichNodes`.
+   */
+  autoRichNodes?: false | "selected" | "hovered" | "focus";
+  renderLabel?: (node: GraphraumOverlayNode) => HTMLElement | null;
+  renderToolbar?: (node: GraphraumOverlayNode) => HTMLElement | null;
+  /** Host HTML for a strictly bounded focused subset. Not the dense node path. */
+  renderRichNode?: (node: GraphraumOverlayNode) => HTMLElement | null;
+}
+interface GraphraumNodeEncoding {
+  presentation?: GraphraumPresentation;
+  visual?: GraphraumNodeVisual;
+}
+interface GraphraumEdgeEncoding {
+  presentation?: GraphraumPresentation;
+  visual?: GraphraumEdgeVisual;
+}
+interface GraphraumVisualMapper<NodeAttributes = undefined, EdgeAttributes = undefined> {
+  edge?: (edge: Readonly<GraphraumEdge<EdgeAttributes>>) => GraphraumEdgeEncoding | undefined;
+  node?: (node: Readonly<GraphraumNode<NodeAttributes>>) => GraphraumNodeEncoding | undefined;
+}
+/**
+ * Canvas backdrop.
+ * - CSS color string paints a solid WebGL clear
+ * - `null` / `"transparent"` leaves the canvas clear so a host CSS color, gradient, or pattern shows through
+ * - `{ type: "pattern", source }` uses an image/canvas/bitmap as `scene.background`
+ */
+type GraphraumPatternBackground = {
+  type: "pattern";
+  source: CanvasImageSource;
+  /** Horizontal and vertical tile count. Default `[1, 1]` stretches to fill. */
+  repeat?: readonly [number, number];
+};
+type GraphraumBackground = GraphraumColor | GraphraumPatternBackground | "transparent" | null;
+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;
+  edgeWidth: number;
+  /** How edge ends meet nodes. Default `boundary`. */
+  endpointAttach: "boundary" | "center";
+  focusedNode: GraphraumColor;
+  hoveredNode: GraphraumColor;
+  node: GraphraumColor;
+  nodeStroke: GraphraumColor;
+  selectedEdge: GraphraumColor;
+  selectedNode: GraphraumColor;
+}
+/** Discriminated pick result. Nodes win over edges when both intersect the pointer. */
+type GraphraumPickHit = {
+  kind: "edge";
+  id: string;
+} | {
+  kind: "node";
+  id: string;
+};
+interface GraphraumOptions<NodeAttributes = undefined, EdgeAttributes = undefined> {
+  antialias?: boolean;
+  maxVisibleEdges?: number;
+  maxVisibleNodes?: number;
+  maxPixelRatio?: number;
+  mode?: GraphraumMode;
+  /** Named preset (`"dark"` / `"light"`) or a partial override merged onto dark. */
+  theme?: Partial<GraphraumTheme> | GraphraumThemeName;
+  viewportCulling?: boolean;
+  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;
+  gpuGeometries: number;
+  gpuTextures: number;
+  lodLevel: "density" | "detail" | "overview";
+  pickingStrategy: "raycaster-3d" | "spatial-grid-2d";
+  dimmedEdges: number;
+  selectedEdges: number;
+  selectedNodes: number;
+  totalEdges: number;
+  totalNodes: number;
+  visibleEdgeCandidates: number;
+  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;
+}
+//#endregion
+//#region src/edge-endpoint-attach.d.ts
+type EndpointAttach = "boundary" | "center";
+declare const DEFAULT_ENDPOINT_ATTACH: EndpointAttach;
+declare const DEFAULT_ENDPOINT_CLEARANCE = 0.75;
+interface EndpointOutline {
+  height?: number;
+  shape?: GraphraumNodeShape;
+  size?: number;
+  strokeWidth?: number;
+  width?: number;
+}
+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;
+  targetOutline: EndpointOutline;
+}
+/**
+ * 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, 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;
+  target: GraphraumPosition;
+};
+//#endregion
+//#region src/edge-styles.d.ts
+declare const graphraumEdgePaths: readonly ["straight", "quadratic", "cubic"];
+//#endregion
+//#region src/force-layout.d.ts
+/** Input for graphraum's dimension-aware force layout helpers. */
+interface ForceLayoutRequest {
+  dimensions: 2 | 3;
+  edges: Uint32Array;
+  /** When omitted, `forceIterationCount(nodeCount)` is used. */
+  iterations?: number;
+  /**
+   * Optional rest length per edge (`edges.length / 2` values).
+   * Omitted → `settings.linkDistance` for every edge.
+   */
+  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).
+   * Omitted → `settings.springStrength` for every edge.
+   */
+  springStrengths?: Float32Array;
+}
+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: 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. 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;
+};
+declare function computeForcePositions(request: ForceLayoutRequest): Float32Array<ArrayBuffer>;
+declare function computeClusteredForcePositions(request: ForceLayoutRequest & {
+  clusters: Uint32Array;
+}): Float32Array<ArrayBuffer>;
+//#endregion
+//#region src/graphology.d.ts
+type GraphologyNodeAttributes = Record<string, unknown> & {
+  color?: GraphraumColor;
+  shape?: GraphraumNodeShape;
+  size?: number;
+  x?: number;
+  y?: number;
+  z?: number;
+};
+type GraphologyEdgeAttributes = Record<string, unknown> & {
+  color?: GraphraumColor;
+};
+interface GraphologyRenderer<NodeAttributes, EdgeAttributes> {
+  setData(data: GraphraumData<NodeAttributes, EdgeAttributes>): void;
+}
+/** Projects a mutable Graphology graph into Graphraum and keeps the binding alive until disposed. */
+declare function bindGraphology<NodeAttributes extends GraphologyNodeAttributes, EdgeAttributes extends GraphologyEdgeAttributes>(renderer: GraphologyRenderer<NodeAttributes, EdgeAttributes>, graph: Graph<NodeAttributes, EdgeAttributes>): () => void;
+//#endregion
+//#region src/overlay.d.ts
+/** A bounded DOM layer for labels, a focused-node toolbar, and optional rich HTML cards. */
+declare class GraphraumOverlay<NodeAttributes = undefined, EdgeAttributes = undefined> {
+  private readonly graph;
+  private readonly container;
+  private readonly options;
+  private readonly root;
+  private readonly labels;
+  private readonly richNodes;
+  private toolbar;
+  private toolbarNodeId;
+  private readonly stopObservingView;
+  private readonly stopObservingFocus;
+  private readonly previousContainerPosition;
+  private readonly labelPolicy;
+  private readonly focusLabelFill;
+  private readonly autoToolbar;
+  private readonly autoRichNodes;
+  private readonly maxLabels;
+  private readonly maxRichNodes;
+  constructor(graph: Graphraum<NodeAttributes, EdgeAttributes>, container: HTMLElement, options: GraphraumOverlayOptions);
+  /**
+   * Replaces the labeled node set. When `labelPolicy` is `auto` or `focus`, the next view/focus
+   * change overwrites this list from the policy.
+   */
+  setLabels(nodeIds: Iterable<string>): void;
+  /**
+   * Replaces the rich HTML node set. When `autoRichNodes` is set, the next focus change
+   * overwrites this list from the policy.
+   */
+  setRichNodes(nodeIds: Iterable<string>): void;
+  setToolbar(nodeId: string | null): void;
+  destroy(): void;
+  private update;
+  private syncRichNodesFromFocus;
+  private syncToolbar;
+  private syncLabels;
+  private syncRichNodes;
+  private updatePositions;
+  private createEntry;
+  private updateEntry;
+  private applyClassName;
+}
+//#endregion
+//#region src/graphraum.d.ts
+/** A small, explicit WebGL graph renderer: one instanced node mesh and one batched edge geometry. */
+declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined> {
+  private readonly container;
+  private readonly renderer;
+  private readonly scene;
+  private readonly raycaster;
+  private readonly pointer;
+  private readonly pickCenter;
+  private readonly pickRight;
+  private readonly pickUp;
+  private theme;
+  private backgroundTexture;
+  private readonly resizeObserver;
+  private readonly maxVisibleEdges;
+  private readonly maxVisibleNodes;
+  private readonly viewportCulling;
+  private readonly viewportOverscan;
+  private readonly visuals;
+  private camera;
+  private controls;
+  private data;
+  private nodeIds;
+  private nodeIndices;
+  private edgeNodeIndices;
+  private canonicalEdgePositions;
+  private incidentEdgeIndices;
+  private nodePresentations;
+  private edgePresentations;
+  private spatialGrid2d;
+  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;
+  private visibleNodeSlots;
+  private visibleEdgeSlots;
+  private visibleEdgeLayouts;
+  private lastEdgeLodTier;
+  private visibleNodeIndices;
+  private pickableEdgeSegments;
+  private visibleEdgeSegmentEdgeIndices;
+  private visibleNodeCount;
+  private visibleNodeCandidateCount;
+  private densityLodActive;
+  private visibleEdgeSegmentCount;
+  private visibleEdgeCount;
+  private visibleEdgeMarkerCount;
+  private visibleEdgeCandidateCount;
+  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;
+  private readonly viewListeners;
+  private readonly focusListeners;
+  private lastHoveredNodeId;
+  constructor(container: HTMLElement, options?: GraphraumOptions<NodeAttributes, EdgeAttributes>);
+  setData(data: GraphraumData<NodeAttributes, EdgeAttributes>): void;
+  /** Merge a topology patch without fitting or resetting the current camera. */
+  applyDataPatch(patch: GraphraumDataPatch<NodeAttributes, EdgeAttributes>): void;
+  private canAppendDataPatch;
+  private canMutateDataInPlace;
+  private mutateDataInPlace;
+  private appendDataPatch;
+  private replaceData;
+  updateNodes(updates: readonly GraphraumNodeUpdate[]): void;
+  /** Applies a transferable XYZ layout batch. Call repeatedly as a worker produces progressive positions. */
+  applyLayout(layout: GraphraumLayoutPositions): void;
+  private getGraphObjects;
+  private applyPreparedNodeUpdates;
+  /** 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. 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). */
+  getNeighborIds(nodeId: string): string[];
+  getSelectedNodeIds(): readonly string[];
+  getHoveredNodeIds(): readonly string[];
+  /** Schedules one render on the next animation frame. Repeated calls in one frame are coalesced. */
+  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;
+  /**
+   * Candidates for a budgeted DOM label layer. Importance is incident edge degree, with a boost
+   * for selected nodes so selection stays labeled. Visibility comes from screen projection.
+   */
+  getLabelCandidates(): GraphraumLabelCandidate[];
+  /** Converts client coordinates to graph world coordinates on the z=0 plane. */
+  screenToWorld(clientX: number, clientY: number): {
+    x: number;
+    y: number;
+    z: number;
+  } | null;
+  /** Creates a bounded DOM layer for labels, a toolbar, and optional rich HTML focus cards. */
+  createOverlay(options?: GraphraumOverlayOptions): GraphraumOverlay<NodeAttributes, EdgeAttributes>;
+  /** Subscribes to camera and viewport changes. Returns an unsubscribe function. */
+  onViewChange(listener: () => void): () => boolean;
+  /** Subscribes to selection and hover changes that affect overlay focus chrome. */
+  onFocusChange(listener: () => void): () => boolean;
+  private notifyFocusChange;
+  private handlePointerMove;
+  private handlePointerLeave;
+  getEdgePresentation(edgeId: string): CompiledGraphraumPresentation | null;
+  getDiagnostics(): GraphraumDiagnostics;
+  /** Picks a node under the pointer. Prefer `pickHit` when edges must be selectable too. */
+  pick(clientX: number, clientY: number): string | null;
+  /**
+   * Picks the top-most graph element under the pointer. Nodes win over edges when both hit.
+   * 2D uses the spatial grid for nodes and world-space segment distance for edges; 3D uses
+   * the node pick mesh then the edge instance mesh.
+   */
+  pickHit(clientX: number, clientY: number): GraphraumPickHit | null;
+  /** 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;
+  private pickNode;
+  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;
+  private getViewportBounds2d;
+  private isNodeVisible2d;
+  private disposeBackgroundTexture;
+  private createBackgroundTexture;
+  private applyBackground;
+  private materializeViewport;
+  private materializeNodes;
+  private disposeGraphObjects;
+}
+//#endregion
+//#region src/label-budget.d.ts
+interface LabelBudgetCandidate {
+  id: string;
+  importance: number;
+  visible: boolean;
+}
+interface SelectBudgetedLabelIdsInput {
+  candidates: readonly LabelBudgetCandidate[];
+  maxLabels: number;
+}
+/** Picks visible label ids by importance within a hard DOM budget. */
+declare function selectBudgetedLabelIds({ candidates, maxLabels }: SelectBudgetedLabelIdsInput): string[];
+interface SelectFocusLabelIdsInput {
+  /** Prefer these ids first (selected, then hovered, then neighbors) — order within each tier is free. */
+  focusIds: readonly string[];
+  candidates: readonly LabelBudgetCandidate[];
+  maxLabels: number;
+  /**
+   * When `"importance"` (default), leftover budget is filled by visible importance.
+   * When `"none"`, only focus ids are labeled.
+   */
+  fill?: "importance" | "none";
+}
+/**
+ * Labels for a sparse focus set: keep focus ids that are visible, then optionally fill
+ * remaining budget from other visible candidates by importance. Focus order is preserved.
+ */
+declare function selectFocusLabelIds({ focusIds, candidates, maxLabels, fill }: SelectFocusLabelIdsInput): string[];
+/** Builds an ordered focus id list: selected, then hovered, then unique neighbors. */
+declare function orderFocusNodeIds(input: {
+  selectedIds: readonly string[];
+  hoveredIds: readonly string[];
+  neighborIds: readonly string[];
+}): string[];
+//#endregion
+//#region src/node-shapes.d.ts
+declare const graphraumNodeShapes: readonly ["circle", "square", "diamond", "hexagon", "triangle", "pill", "rounded"];
+//#endregion
+//#region src/overlay-budget.d.ts
+type RichNodePolicy = "selected" | "hovered" | "focus";
+declare function boundOverlayIds(ids: Iterable<string>, max: number, kind: string): string[];
+declare function selectRichNodeIds(input: {
+  hoveredIds: readonly string[];
+  maxRichNodes: number;
+  policy: RichNodePolicy;
+  selectedIds: readonly string[];
+}): string[];
+//#endregion
+//#region src/theme.d.ts
+/** Dark canvas: Ink Black, Turf Green, Porcelain. */
+declare const graphraumThemeDark: Readonly<{
+  background: string;
+  dimmedEdge: string;
+  dimmedEdgeOpacity: number;
+  dimmedNode: string;
+  edge: string;
+  edgeOpacity: number;
+  edgeWidth: number;
+  endpointAttach: "boundary";
+  focusedNode: string;
+  hoveredNode: string;
+  node: string;
+  nodeStroke: string;
+  selectedEdge: string;
+  selectedNode: string;
+}>;
+/** 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;
+  edgeWidth: number;
+  endpointAttach: "boundary";
+  focusedNode: string;
+  hoveredNode: string;
+  node: string;
+  nodeStroke: string;
+  selectedEdge: string;
+  selectedNode: string;
+}>;
+declare const graphraumThemes: Readonly<{
+  dark: Readonly<{
+    background: string;
+    dimmedEdge: string;
+    dimmedEdgeOpacity: number;
+    dimmedNode: string;
+    edge: string;
+    edgeOpacity: number;
+    edgeWidth: number;
+    endpointAttach: "boundary";
+    focusedNode: string;
+    hoveredNode: string;
+    node: string;
+    nodeStroke: string;
+    selectedEdge: string;
+    selectedNode: string;
+  }>;
+  light: Readonly<{
+    background: string;
+    dimmedEdge: string;
+    dimmedEdgeOpacity: number;
+    dimmedNode: string;
+    edge: string;
+    edgeOpacity: number;
+    edgeWidth: number;
+    endpointAttach: "boundary";
+    focusedNode: string;
+    hoveredNode: string;
+    node: string;
+    nodeStroke: string;
+    selectedEdge: string;
+    selectedNode: string;
+  }>;
+}>;
+/** Alias of {@link graphraumThemeDark} for backward compatibility. */
+declare const graphraumTheme: Readonly<{
+  background: string;
+  dimmedEdge: string;
+  dimmedEdgeOpacity: number;
+  dimmedNode: string;
+  edge: string;
+  edgeOpacity: number;
+  edgeWidth: number;
+  endpointAttach: "boundary";
+  focusedNode: string;
+  hoveredNode: string;
+  node: string;
+  nodeStroke: string;
+  selectedEdge: string;
+  selectedNode: string;
+}>;
+declare function resolveGraphraumTheme(input?: Partial<GraphraumTheme> | GraphraumThemeName, base?: GraphraumTheme): GraphraumTheme;
+/** Collapse `"transparent"` onto `null` so callers have one transparent sentinel. */
+declare function normalizeGraphraumBackground(background: GraphraumBackground): Exclude<GraphraumBackground, "transparent">;
+declare function isTransparentGraphraumBackground(background: GraphraumBackground): boolean;
+//#endregion
+//#region src/visuals.d.ts
+/** 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 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 };