@yggy-tech/graphraum 0.0.0-stage → 0.28.0

package/dist/index.d.ts

@@ -0,0 +1,677 @@
+import Graph from "graphology";
+//#region src/types.d.ts
+type GraphraumColor = number | string;
+type GraphraumMode = "2d" | "3d";
+type GraphraumNodeState = "dimmed" | "focused" | "hovered" | "selected";
+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;
+  height?: number;
+  shape?: GraphraumNodeShape;
+  size?: number;
+  strokeColor?: GraphraumColor;
+  strokeWidth?: number;
+  width?: number;
+}
+type GraphraumNode<NodeAttributes = undefined> = GraphraumNodeGeometry & GraphraumAttributes<NodeAttributes>;
+interface GraphraumNodeUpdate {
+  color?: GraphraumColor | 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;
+  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;
+  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>;
+}
+interface GraphraumDiagnostics {
+  aggregatedNodeClusters: number;
+  cpuFrameMilliseconds: number;
+  gpuFrameMilliseconds: number | null;
+  gpuDrawCalls: number;
+  gpuGeometries: number;
+  gpuTextures: number;
+  lodLevel: "density" | "detail" | "overview";
+  pickingStrategy: "raycaster-3d" | "spatial-grid-2d";
+  selectedEdges: number;
+  selectedNodes: number;
+  totalEdges: number;
+  totalNodes: number;
+  visibleEdgeCandidates: number;
+  visibleEdgeMarkers: number;
+  visibleEdgeSegments: number;
+  visibleEdges: 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;
+  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.
+ */
+declare function attachPointOnOutline(center: GraphraumPosition, far: GraphraumPosition, outline: EndpointOutline, clearance?: number): 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;
+  settings?: ForceSettings;
+  /**
+   * Optional spring strength per edge (`edges.length / 2` values).
+   * Omitted → `settings.springStrength` for every edge.
+   */
+  springStrengths?: Float32Array;
+}
+interface ForceSettings {
+  centerAttraction: number;
+  damping: number;
+  linkDistance: number;
+  repulsion: number;
+  springStrength: number;
+}
+declare const DEFAULT_FORCE_SETTINGS: 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;
+  /** 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 nodeCapacity;
+  private edgeCapacity;
+  private markerCapacity;
+  private edgeInstanceCapacity;
+  private selectedNodeIds;
+  private selectedEdgeIds;
+  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 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. */
+  setEdgeSelection(edgeIds: Iterable<string>): void;
+  /** 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;
+  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;
+  fitView(): void;
+  setTheme(theme: Partial<GraphraumTheme> | GraphraumThemeName): void;
+  setBackground(background: GraphraumBackground): void;
+  resize(): void;
+  destroy(): void;
+  private readonly requestRender;
+  private readGpuTimers;
+  private readonly handleViewChange;
+  private createCamera;
+  private createControls;
+  private pickNode;
+  private pickEdge;
+  private worldUnitsPerPixel;
+  private applySelectionColors;
+  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;
+  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;
+  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;
+    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;
+    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;
+  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 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 };