@loradb/lora-graph-canvas 0.10.0

package/dist/types.d.ts

@@ -0,0 +1,375 @@
+import { CSSProperties } from 'react';
+/** Graph node. `id` is required; the rest are optional. The engine writes
+ *  back `x/y/z` (and `vx/vy/vz`) every tick, and the host can pin a node
+ *  by setting `fx/fy/fz`. */
+export interface NodeObject {
+    id: string | number;
+    x?: number;
+    y?: number;
+    z?: number;
+    vx?: number;
+    vy?: number;
+    vz?: number;
+    fx?: number;
+    fy?: number;
+    fz?: number;
+    label?: string;
+    color?: string;
+    group?: string | number;
+    val?: number;
+    [key: string]: unknown;
+}
+/** Graph link. `source` and `target` are required. */
+export interface LinkObject {
+    id?: string | number;
+    source: string | number | NodeObject;
+    target: string | number | NodeObject;
+    label?: string;
+    color?: string;
+    width?: number;
+    curvature?: number;
+    [key: string]: unknown;
+}
+export interface GraphData<N extends NodeObject = NodeObject, L extends LinkObject = LinkObject> {
+    nodes: N[];
+    links: L[];
+}
+export type GraphMode = "2d" | "3d";
+/** Built-in tool identifiers. */
+export type ToolId = "select" | "pan" | "add-node" | "add-link" | "delete" | "duplicate" | "select-all" | "fit" | "zoom-in" | "zoom-out" | "pause" | "resume" | "screenshot" | "export-json" | "import-json" | "toggle-mode";
+/** Accepts a literal value, a property accessor string, or a function. */
+export type Accessor<T, In> = T | string | ((obj: In) => T);
+export type DagMode = "td" | "bu" | "lr" | "rl" | "radialout" | "radialin" | null;
+/** CSS-variable theme. Each key maps to one of the `--lgc-*` variables.
+ *  Only set what you want to override. */
+export interface LoraGraphTheme {
+    background?: string;
+    foreground?: string;
+    border?: string;
+    accent?: string;
+    toolbarBackground?: string;
+    toolbarForeground?: string;
+    toolbarBorder?: string;
+    toolActiveBackground?: string;
+    toolHoverBackground?: string;
+    tooltipBackground?: string;
+    tooltipForeground?: string;
+    menuBackground?: string;
+    menuForeground?: string;
+    menuHoverBackground?: string;
+    fontFamily?: string;
+    fontSize?: string;
+}
+export interface ToolbarConfig {
+    include?: ToolId[];
+    exclude?: ToolId[];
+    position?: "top" | "top-right" | "top-left" | "bottom";
+}
+export interface LoraGraphCanvasProps<N extends NodeObject = NodeObject, L extends LinkObject = LinkObject> {
+    data?: GraphData<N, L>;
+    defaultData?: GraphData<N, L>;
+    onDataChange?: (next: GraphData<N, L>) => void;
+    mode?: GraphMode;
+    defaultMode?: GraphMode;
+    onModeChange?: (mode: GraphMode) => void;
+    width?: number;
+    height?: number;
+    className?: string;
+    style?: CSSProperties;
+    backgroundColor?: string;
+    theme?: Partial<LoraGraphTheme>;
+    nodeId?: string;
+    linkSource?: string;
+    linkTarget?: string;
+    nodeColor?: Accessor<string, N>;
+    nodeLabel?: Accessor<string | HTMLElement, N>;
+    nodeVal?: Accessor<number, N>;
+    nodeAutoColorBy?: Accessor<string | null, N>;
+    nodeRelSize?: number;
+    nodeVisibility?: Accessor<boolean, N>;
+    nodeOpacity?: number;
+    nodeResolution?: number;
+    linkColor?: Accessor<string, L>;
+    linkLabel?: Accessor<string | HTMLElement, L>;
+    linkWidth?: Accessor<number, L>;
+    linkCurvature?: Accessor<number, L>;
+    linkLineDash?: Accessor<number[] | null, L>;
+    linkAutoColorBy?: Accessor<string | null, L>;
+    linkVisibility?: Accessor<boolean, L>;
+    linkOpacity?: number;
+    linkResolution?: number;
+    linkCurveRotation?: Accessor<number, L>;
+    linkDirectionalArrowLength?: Accessor<number, L>;
+    linkDirectionalArrowColor?: Accessor<string, L>;
+    linkDirectionalArrowRelPos?: Accessor<number, L>;
+    linkDirectionalArrowResolution?: number;
+    linkDirectionalParticles?: Accessor<number, L>;
+    linkDirectionalParticleSpeed?: Accessor<number, L>;
+    linkDirectionalParticleWidth?: Accessor<number, L>;
+    linkDirectionalParticleOffset?: Accessor<number, L>;
+    linkDirectionalParticleColor?: Accessor<string, L>;
+    linkDirectionalParticleResolution?: number;
+    cooldownTicks?: number;
+    cooldownTime?: number;
+    warmupTicks?: number;
+    d3AlphaDecay?: number;
+    d3VelocityDecay?: number;
+    d3AlphaMin?: number;
+    d3AlphaTarget?: number;
+    dagMode?: DagMode;
+    dagLevelDistance?: number;
+    dagNodeFilter?: (node: N) => boolean;
+    onDagError?: (loopNodeIds: Array<string | number>) => void;
+    /** 3D-only: drop layout to 1, 2, or 3 dimensions (flattens z when 2). */
+    numDimensions?: 1 | 2 | 3;
+    /** 3D-only: switch the layout engine. ngraph is ~3× faster for >10k nodes. */
+    forceEngine?: "d3" | "ngraph";
+    /** 3D-only: ngraph physics tuning, passed straight through. */
+    ngraphPhysics?: object;
+    /** 3D-only: throttle the raycaster used for hover / click hit
+     *  testing. Defaults to 0 (every frame). Bump to 50-200ms on
+     *  huge graphs to skip raycasts on most frames — the perf tier
+     *  picks a sensible value automatically. */
+    pointerRaycasterThrottleMs?: number;
+    /** Add a node-collision force so circles don't overlap. `true` uses
+     *  `nodeRelSize` as the radius; pass a number to override. */
+    collideNodes?: boolean | number;
+    tools?: boolean | ToolId[] | ToolbarConfig;
+    showContextMenu?: boolean;
+    showLegend?: boolean;
+    selection?: "none" | "single" | "multi";
+    /** Allow ⌘C / ⌘X / ⌘V (and the matching ref methods). */
+    enableClipboard?: boolean;
+    /** Render the floating tooltip (the cursor-anchored label resolved
+     *  from `nodeLabel` / `linkLabel`) on hover. Defaults to `false` —
+     *  the hover state still drives neighbour highlighting and on-canvas
+     *  labels, just without the mouse-attached pill. */
+    enableTooltip?: boolean;
+    /** Play an animated "zoom in to the bounds" intro on first mount.
+     *  The camera starts pulled back proportional to node count (so a
+     *  sparse 10-node graph reveals from ~×3 out and a 10k stress graph
+     *  from ~×6 out) and tweens into the fitted view. Defaults to
+     *  `true`. Pass `false` to suppress the intro and snap to the
+     *  kapsule's own initial fit instead. */
+    introZoom?: boolean;
+    enableNodeDrag?: boolean;
+    enableZoom?: boolean;
+    enablePan?: boolean;
+    enablePointerInteraction?: boolean;
+    enableNavigationControls?: boolean;
+    linkHoverPrecision?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    showPointerCursor?: Accessor<boolean, N | L>;
+    showNavInfo?: boolean;
+    autoPauseRedraw?: boolean;
+    /** When true (default false), clicking a node animates the camera
+     *  toward it; clicking the same node again restores the prior view. */
+    focusOnClick?: boolean;
+    /** When true (default false), hovering a node highlights it and its
+     *  neighbours via the accent color. Requires cross-linked neighbour
+     *  refs in the node data, or set `autoIndexNeighbors`. */
+    highlightNeighborsOnHover?: boolean;
+    /** Auto-build `node._neighbors` and `node._links` arrays after every
+     *  data change so `highlightNeighborsOnHover` has something to walk. */
+    autoIndexNeighbors?: boolean;
+    /** Background helper: draw a faint grid behind the canvas. Useful in
+     *  a playground. 2D only. */
+    showGrid?: boolean | {
+        spacing?: number;
+        color?: string;
+    };
+    /** Render each node's label directly on the 2D canvas (under the
+     *  node). When this is on, the default node colour is automatically
+     *  faded so the label text reads clearly on top of overlapping
+     *  nodes. 2D only — in 3D, use `nodeLabel` for the hover tooltip. */
+    showLabels?: boolean;
+    /** When `true` (default), releasing a dragged node pins it at its
+     *  new position by writing `fx`/`fy`/`fz`. Dragging a node that's
+     *  part of the current selection moves all selected nodes together
+     *  and pins them as a group on release. Set to `false` to keep the
+     *  default simulation-pull behaviour. */
+    fixOnDrop?: boolean;
+    /** Auto-tune renderer / simulation settings based on graph size so
+     *  the canvas stays responsive into the 50k-100k-node range.
+     *
+     *  - `"auto"` (default): pick a tier from the live node + link count.
+     *  - `"off"`: never inject perf defaults — only the host's props
+     *    drive the kapsule.
+     *  - `"default" | "large" | "xlarge" | "huge"`: force a specific
+     *    tier regardless of size (useful for benchmarking).
+     *
+     *  Each tier overrides things like `cooldownTicks`, `d3AlphaDecay`,
+     *  3D `nodeResolution`/`linkResolution`, and the 3D layout engine.
+     *  Any prop the host sets explicitly always wins. */
+    performanceProfile?: "auto" | "off" | "default" | "large" | "xlarge" | "huge";
+    /** Switch the simulation into a beeswarm layout: nodes spread along
+     *  one axis driven by a value accessor, with a weak orthogonal pull
+     *  and collision so they don't overlap. Pass `true` for an
+     *  id-hashed spread, or an object to control the value source and
+     *  axis. Disables the default `center` + `charge` forces while
+     *  active. */
+    beeswarm?: boolean | {
+        /** Target axis (default `"x"`). */
+        axis?: "x" | "y";
+        /** Position along the chosen axis — `(node) => number` or a
+         *  property key whose value is numeric. Defaults to a stable
+         *  hash of the node id. */
+        value?: string | ((n: N) => number);
+        /** Strength of the orthogonal pull-to-zero force. Default 0.2. */
+        strength?: number;
+    };
+    onNodeClick?: (node: N, event: MouseEvent) => void;
+    onNodeRightClick?: (node: N, event: MouseEvent) => void;
+    onNodeHover?: (node: N | null, previousNode: N | null) => void;
+    onNodeDoubleClick?: (node: N, event: MouseEvent) => void;
+    onNodeDrag?: (node: N, translate: {
+        x: number;
+        y: number;
+        z?: number;
+    }) => void;
+    onNodeDragEnd?: (node: N, translate: {
+        x: number;
+        y: number;
+        z?: number;
+    }) => void;
+    onLinkClick?: (link: L, event: MouseEvent) => void;
+    onLinkRightClick?: (link: L, event: MouseEvent) => void;
+    onLinkHover?: (link: L | null, previousLink: L | null) => void;
+    onBackgroundClick?: (event: MouseEvent) => void;
+    onBackgroundRightClick?: (event: MouseEvent) => void;
+    onSelectionChange?: (selectedIds: Array<string | number>) => void;
+    onEngineTick?: () => void;
+    onEngineStop?: () => void;
+    onZoom?: (transform: {
+        k: number;
+        x: number;
+        y: number;
+    }) => void;
+    onZoomEnd?: (transform: {
+        k: number;
+        x: number;
+        y: number;
+    }) => void;
+    onRenderFramePre?: (ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    onRenderFramePost?: (ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    /** Fires when the user copies nodes (⌘C) — receives the snapshot. */
+    onCopy?: (nodes: N[]) => void;
+    /** Fires when the user cuts nodes (⌘X) — receives the snapshot
+     *  *before* the originals are removed from the graph. */
+    onCut?: (nodes: N[]) => void;
+    /** Fires after a paste places new nodes in the graph. */
+    onPaste?: (nodes: N[]) => void;
+    nodeCanvasObject?: (n: N, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    nodeCanvasObjectMode?: "replace" | "before" | "after" | ((n: N) => "replace" | "before" | "after" | undefined);
+    nodePointerAreaPaint?: (n: N, color: string, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    linkCanvasObject?: (l: L, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    linkCanvasObjectMode?: "replace" | "before" | "after" | ((l: L) => "replace" | "before" | "after" | undefined);
+    linkPointerAreaPaint?: (l: L, color: string, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    nodeThreeObject?: (n: N) => unknown;
+    nodeThreeObjectExtend?: Accessor<boolean, N>;
+    linkThreeObject?: (l: L) => unknown;
+    linkThreeObjectExtend?: Accessor<boolean, L>;
+    linkMaterial?: Accessor<unknown, L>;
+    nodePositionUpdate?: ((obj: unknown, coords: {
+        x: number;
+        y: number;
+        z: number;
+    }, node: N) => void | boolean | null) | null;
+    linkPositionUpdate?: ((obj: unknown, coords: {
+        start: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        end: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }, link: L) => void | boolean | null) | null;
+    /** 3D init-only — passed once on engine construction. */
+    controlType?: "trackball" | "orbit" | "fly";
+    rendererConfig?: Record<string, unknown>;
+    extraRenderers?: unknown[];
+}
+export interface LoraGraphCanvasHandle<N extends NodeObject = NodeObject, L extends LinkObject = LinkObject> {
+    getData(): GraphData<N, L>;
+    setData(next: GraphData<N, L>): void;
+    addNode(node?: Partial<N> & {
+        id?: string | number;
+    }, opts?: {
+        at?: {
+            x: number;
+            y: number;
+            z?: number;
+        };
+    }): N;
+    addNodes(nodes: Array<Partial<N> & {
+        id?: string | number;
+    }>): N[];
+    updateNode(id: string | number, patch: Partial<N>): void;
+    removeNode(id: string | number): void;
+    removeNodes(ids: Array<string | number>): void;
+    addLink(link: {
+        source: string | number;
+        target: string | number;
+        id?: string | number;
+    } & Partial<L>): L;
+    addLinks(links: Array<{
+        source: string | number;
+        target: string | number;
+    } & Partial<L>>): L[];
+    removeLink(predicate: (l: L) => boolean): void;
+    clear(): void;
+    getSelection(): Array<string | number>;
+    setSelection(ids: Array<string | number>): void;
+    selectAll(): void;
+    clearSelection(): void;
+    getMode(): GraphMode;
+    setMode(mode: GraphMode): void;
+    fit(durationMs?: number, padding?: number): void;
+    centerAt(x: number, y: number, z?: number, durationMs?: number): void;
+    zoom(scale: number, durationMs?: number): void;
+    zoomIn(step?: number): void;
+    zoomOut(step?: number): void;
+    copy(): N[];
+    cut(): N[];
+    paste(opts?: {
+        at?: {
+            x: number;
+            y: number;
+            z?: number;
+        };
+    }): N[];
+    duplicate(): N[];
+    /** Create a fresh node and link each currently selected node to it.
+     *  No-op when the selection is empty. Returns the new node, or null
+     *  if nothing was created. */
+    addConnectedNode(opts?: {
+        at?: {
+            x: number;
+            y: number;
+            z?: number;
+        };
+        label?: string;
+    }): N | null;
+    togglePin(id: string | number): void;
+    exportJSON(): string;
+    importJSON(json: string): void;
+    downloadJSON(filename?: string): void;
+    pause(): void;
+    resume(): void;
+    reheat(): void;
+    /** Get / set / clear a d3-force by name. Pass `null` to remove. */
+    d3Force(name: string): unknown;
+    d3Force(name: string, fn: unknown | null): void;
+    /** Emit a one-off particle along a link (visual ping for events). */
+    emitParticle(link: L): void;
+    /** Halt any in-flight camera animation (e.g. a focus tween) and
+     *  freeze the camera at its current state. */
+    stopAnimation(): void;
+    screenshot(): Promise<Blob | null>;
+    engine2D(): unknown | null;
+    engine3D(): unknown | null;
+}

package/dist/utils/accessor.d.ts

@@ -0,0 +1,36 @@
+/** Resolve an accessor against an object. Mirrors the kapsule's
+ *  `accessor-fn` semantics: a function is invoked; a string is used as
+ *  a property name; anything else (including undefined) is returned as
+ *  is. */
+export declare function readAccessor<T, In>(accessor: T | string | ((obj: In) => T) | undefined, obj: In): T | undefined;
+/** Resolve a node's display caption. Precedence:
+ *    1. Host accessor (`nodeLabel`) when it returns a non-empty value.
+ *       Strings pass through; HTMLElements yield their textContent;
+ *       other primitives (e.g. numeric `nodeLabel="id"`) are stringified.
+ *    2. The node's own `label` field, if it's a non-empty string.
+ *    3. The node id, stringified.
+ *  Returns "" when nothing resolves — callers should treat that as
+ *  "skip drawing". */
+export declare function resolveNodeLabelText<N extends {
+    id?: string | number;
+    label?: unknown;
+}>(accessor: string | HTMLElement | ((n: N) => string | HTMLElement) | undefined, node: N): string;
+/** Resolve a link's display caption. Same precedence as
+ *  `resolveNodeLabelText`, with the id-based fallback rendering as
+ *  `source → target` using the resolved endpoint ids. Returns "" when
+ *  no caption can be formed. */
+export declare function resolveLinkLabelText<L extends {
+    label?: unknown;
+    source: unknown;
+    target: unknown;
+}>(accessor: string | HTMLElement | ((l: L) => string | HTMLElement) | undefined, link: L): string;
+/** Adjust a CSS color string toward the given alpha. Best-effort —
+ *  passes through unrecognised inputs untouched. Used by the
+ *  neighbour-highlight code to dim non-hovered neighbours. */
+export declare function adjustAlpha(color: string, alpha: number): string;
+/** Shared sentinel for the "no hover-highlight" state. Reusing one
+ *  instance lets React's useState bail out when transitioning empty →
+ *  empty (e.g. mouseleave → mouseleave), avoiding a no-op re-render plus
+ *  downstream engineProps re-memo and kapsule re-bind. Treated as
+ *  read-only — all consumers only call `.has()` on it. */
+export declare const EMPTY_ID_SET: Set<string | number>;

package/dist/utils/download.d.ts

@@ -0,0 +1,4 @@
+/** Trigger a browser download for a given Blob. */
+export declare function downloadBlob(blob: Blob, filename: string): void;
+/** Snapshot the supplied canvas to a PNG and trigger a download. */
+export declare function downloadScreenshot(canvas: HTMLCanvasElement | null | undefined): void;

package/dist/utils/geometry.d.ts

@@ -0,0 +1,8 @@
+export interface Point2 {
+    x: number;
+    y: number;
+}
+export declare function distance2(a: Point2, b: Point2): number;
+/** Default snap distances for "drag node onto node → link" gesture. */
+export declare const SNAP_IN = 15;
+export declare const SNAP_OUT = 40;

package/dist/utils/grid.d.ts

@@ -0,0 +1,9 @@
+export interface GridOptions {
+    spacing?: number;
+    color?: string;
+}
+/** Draws a faint, infinite grid behind the graph. Hooked up via the
+ *  engine's `onRenderFramePre` callback so the grid stays under the
+ *  nodes / links. The grid adapts to the current zoom level: at high
+ *  zoom we draw a tighter sub-grid, at low zoom a coarser one. */
+export declare function drawBackgroundGrid(ctx: CanvasRenderingContext2D, globalScale: number, opts?: GridOptions): void;

package/dist/utils/ids.d.ts

@@ -0,0 +1,3 @@
+export declare function createId(prefix?: string): string;
+/** Reset all counters. Intended only for tests so they observe stable IDs. */
+export declare function __resetIdCounters(): void;

package/dist/utils/perfTier.d.ts

@@ -0,0 +1,29 @@
+import { GraphMode, LinkObject, LoraGraphCanvasProps, NodeObject } from '../types';
+/** Performance tier — picked from the live node + link count and used
+ *  to inject sensible defaults on top of the user's props. Higher
+ *  tiers trade visual quality for frame rate so the renderer stays
+ *  responsive on large graphs. */
+export type PerfTier = "default" | "large" | "xlarge" | "huge";
+export interface PickPerfTierInput {
+    nodeCount: number;
+    linkCount: number;
+}
+/** Map graph size to a tier. Links count for half a node since they're
+ *  cheaper than nodes to render (one canvas line vs a circle + label),
+ *  but they still drive force ticks. Thresholds were picked empirically
+ *  to keep 60fps on a 2019 MacBook Pro:
+ *    – default  : < 2k         (no tuning, full quality)
+ *    – large    : 2k …  10k    (mild tweaks, still pretty)
+ *    – xlarge   : 10k … 50k    (aggressive: ngraph layout in 3D, no
+ *                                particles, faster cooldown)
+ *    – huge     : 50k+         (all bets off — 100k target)
+ */
+export declare function pickPerfTier({ nodeCount, linkCount, }: PickPerfTierInput): PerfTier;
+/** Tier-specific prop defaults. Returned as a plain object so it can
+ *  be spread *before* the user's props in the engine prop bag — the
+ *  host's explicit values always win, so this only fills holes.
+ *
+ *  We deliberately only set the props that move the needle on the
+ *  bottleneck for that tier (drawing or simulation), and only when the
+ *  user hasn't already opted in to a more conservative value. */
+export declare function perfTierDefaults<N extends NodeObject = NodeObject, L extends LinkObject = LinkObject>(tier: PerfTier, mode: GraphMode): Partial<LoraGraphCanvasProps<N, L>>;

package/dist/utils/spriteLabel.d.ts

@@ -0,0 +1,61 @@
+import { Sprite, Texture } from 'three';
+export interface SpriteLabelOpts {
+    text: string;
+    /** Font size used when rasterising into the canvas texture. Larger
+     *  values → sharper text when the camera is close. Defaults to 32. */
+    fontSize?: number;
+    fontFamily?: string;
+    color?: string;
+    /** CSS color string for the background pill. Pass an empty string
+     *  for no background. Defaults to a semi-opaque dark pill. */
+    backgroundColor?: string;
+    /** Optional foreground for the alternate "selected" rasterisation.
+     *  When supplied alongside `selectedBackgroundColor`, a second
+     *  texture is baked at construction and stored on
+     *  `sprite.userData.selectedTexture`. Swap `material.map` between
+     *  that and `sprite.userData.normalTexture` to toggle styling
+     *  without re-rasterising on each selection change. */
+    selectedColor?: string;
+    /** Optional pill background for the alternate "selected"
+     *  rasterisation. See `selectedColor`. */
+    selectedBackgroundColor?: string;
+    /** Padding in canvas pixels around the rasterised text. */
+    padding?: number;
+    /** World-space height of the resulting sprite. Width derives from
+     *  the rasterised aspect ratio. Defaults to 4. Ignored when
+     *  `pixelHeight` is set. */
+    worldHeight?: number;
+    /** When provided, the sprite auto-scales each frame so its on-screen
+     *  height stays at roughly this many CSS pixels regardless of camera
+     *  distance — the constant-screen-size behaviour 2D labels get for
+     *  free via `fontSize / globalScale`. Overrides `worldHeight`.
+     *  Requires a PerspectiveCamera (the kapsule's default). */
+    pixelHeight?: number;
+}
+/** Extra fields stashed on `sprite.userData` for labels built with
+ *  alternate "selected" styling. Consumers can flip
+ *  `material.map = userData.selectedTexture` to switch styles without
+ *  rebuilding the sprite. */
+export interface SpriteLabelUserData {
+    normalTexture?: Texture;
+    selectedTexture?: Texture;
+}
+/** Release every GPU resource (both textures + the material) owned by
+ *  a label sprite. Call when removing the sprite from the scene for
+ *  good — without this the CanvasTextures stay resident in GPU memory
+ *  forever, which on a heavily-edited 10k+-node graph accumulates
+ *  into hundreds of MB of orphaned textures. */
+export declare function disposeLabelSprite(sprite: Sprite): void;
+/** Build a billboarded text sprite for use as a 3D label.
+ *
+ *  Rasterises the text once into a `CanvasTexture` and wraps it in
+ *  a `Sprite`. The sprite always faces the camera (that's the
+ *  `Sprite` semantic) and respects depth so it occludes nodes
+ *  behind it correctly while remaining flat.
+ *
+ *  Allocates a fresh canvas + texture + material per call. Hosts
+ *  rendering 10k+ labels should dispose them when the corresponding
+ *  node / link is removed — we don't keep a global cache because the
+ *  text content varies per item, and pooling by text+style alone
+ *  would let stale sprites pin GPU memory after data updates. */
+export declare function createTextSprite(opts: SpriteLabelOpts): Sprite;

package/dist/utils/themeStyle.d.ts

@@ -0,0 +1,5 @@
+import { CSSProperties } from 'react';
+import { LoraGraphTheme } from '../types';
+/** Translate a partial `LoraGraphTheme` into a style object that sets
+ *  the matching CSS custom properties on the host element. */
+export declare function themeToStyle(theme?: Partial<LoraGraphTheme>): CSSProperties;

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@loradb/lora-graph-canvas",
+  "version": "0.10.0",
+  "description": "React graph canvas for LoraDB. Unified 2D/3D force-directed component with a built-in tool palette for adding, connecting, selecting, and removing nodes.",
+  "license": "BUSL-1.1",
+  "author": "LoraDB, Inc.",
+  "homepage": "https://github.com/lora-db/lora/tree/main/packages/lora-graph-canvas#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lora-db/lora.git",
+    "directory": "packages/lora-graph-canvas"
+  },
+  "bugs": {
+    "url": "https://github.com/lora-db/lora/issues"
+  },
+  "keywords": [
+    "lora",
+    "loradb",
+    "graph",
+    "canvas",
+    "react",
+    "force-directed",
+    "2d",
+    "3d",
+    "three"
+  ],
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./styles.css": "./dist/style.css"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src test",
+    "format": "prettier --write src test",
+    "format:check": "prettier --check src test",
+    "storybook": "storybook dev -p 6007",
+    "build:storybook": "storybook build -o storybook-static"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "three": ">=0.150.0"
+  },
+  "dependencies": {
+    "d3-array": "^3.2.0",
+    "d3-drag": "^3.0.0",
+    "d3-force-3d": "^3.0.0",
+    "d3-scale": "^4.0.0",
+    "d3-scale-chromatic": "^3.0.0",
+    "d3-selection": "^3.0.0",
+    "d3-zoom": "^3.0.0",
+    "three-forcegraph": "^1.43.0",
+    "three-render-objects": "^1.41.0"
+  },
+  "devDependencies": {
+    "@storybook/addon-essentials": "^8.3.0",
+    "@storybook/addon-interactions": "^8.3.0",
+    "@storybook/addon-links": "^8.3.0",
+    "@storybook/blocks": "^8.3.0",
+    "@storybook/react": "^8.3.0",
+    "@storybook/react-vite": "^8.3.0",
+    "@storybook/test": "^8.3.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.0.0",
+    "@testing-library/user-event": "^14.5.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@types/three": "^0.182.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "jsdom": "^25.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "storybook": "^8.3.0",
+    "three": "^0.182.0",
+    "typescript": "^5.6.0",
+    "vite": "^5.4.0",
+    "vite-plugin-dts": "^4.2.0",
+    "vitest": "^2.1.0"
+  }
+}