vortx-gl 1.0.4 → 1.0.27

package/dist/engine/core/context.d.ts

@@ -0,0 +1,20 @@
+import { EventEmitter } from '../events';
+import { InteractionState } from '../types';
+import { NodeStore } from './NodeStore';
+import { EdgeStore } from './EdgeStore';
+import { ComboStore } from './ComboStore';
+import { Camera } from './Camera';
+import { GpuBufferManager } from '../gpu/GpuBufferManager';
+export interface EngineContext {
+    gl: WebGL2RenderingContext;
+    canvas: HTMLCanvasElement;
+    emitter: EventEmitter;
+    requestRender: () => void;
+    nodes: NodeStore;
+    edges: EdgeStore;
+    combos: ComboStore;
+    camera: Camera;
+    gpu: GpuBufferManager;
+    state: InteractionState;
+    theme: "dark" | "light";
+}

package/dist/engine/events.d.ts

@@ -9,21 +9,8 @@ export type EventHandler<T = unknown> = (data: T) => void;
  */
 export declare class EventEmitter {
     private listeners;
-    /**
-     * Subscribe to an event.
-     * @param event The event unique key.
-     * @param handler Function to execute when the event fires.
-     * @returns An unsubscribe function for convenient cleanup.
-     */
     on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
-    /**
-     * Unsubscribe a specific handler from an event.
-     */
     off<T = unknown>(event: string, handler: EventHandler<T>): void;
-    /**
-     * @internal
-     * Fire an event to all current subscribers.
-     */
     emit<T = unknown>(event: string, data?: T): void;
     /**
      * Remove all handlers for a specific event, or all events if no name given.

package/dist/engine/gpu/GpuBufferManager.d.ts

@@ -0,0 +1,39 @@
+export declare class GpuBufferManager {
+    program: WebGLProgram | null;
+    edgeProgram: WebGLProgram | null;
+    vao: WebGLVertexArrayObject | null;
+    edgeVao: WebGLVertexArrayObject | null;
+    positionBuffer: WebGLBuffer | null;
+    colorBuffer: WebGLBuffer | null;
+    idBuffer: WebGLBuffer | null;
+    shapeBuffer: WebGLBuffer | null;
+    sizeBuffer: WebGLBuffer | null;
+    targetPositionBuffer: WebGLBuffer | null;
+    edgeIndexBuffer: WebGLBuffer | null;
+    pickingFramebuffer: WebGLFramebuffer | null;
+    pickingTexture: WebGLTexture | null;
+    uMatrixLoc: WebGLUniformLocation | null;
+    uPointSizeLoc: WebGLUniformLocation | null;
+    uPointSizeMaxLoc: WebGLUniformLocation | null;
+    uPickingModeLoc: WebGLUniformLocation | null;
+    uEdgeMatrixLoc: WebGLUniformLocation | null;
+    uEdgeColorLoc: WebGLUniformLocation | null;
+    uTransitionProgressLoc: WebGLUniformLocation | null;
+    uEdgeTransitionProgressLoc: WebGLUniformLocation | null;
+    private gl;
+    private canvas;
+    constructor(gl: WebGL2RenderingContext, canvas: HTMLCanvasElement);
+    init(): void;
+    private initShaders;
+    private initBuffers;
+    initPicking(): void;
+    private createProgram;
+    reallocateNodeBuffers(positions: Float32Array, colorData: Float32Array, idData: Float32Array, shapeData: Float32Array, sizeData?: Float32Array): void;
+    syncNode(idx: number, positions: Float32Array, colorData: Float32Array, idData: Float32Array, shapeData: Float32Array, sizeData?: Float32Array): void;
+    /** Push a single node's size multiplier to the GPU. Used by updateNode. */
+    syncSize(idx: number, sizeData: Float32Array): void;
+    syncEdges(indices: Uint32Array | null): void;
+    syncPositions(positions: Float32Array): void;
+    syncAllPositions(positions: Float32Array): void;
+    destroy(): void;
+}

package/dist/engine/interaction/GroupInteraction.d.ts

@@ -0,0 +1,40 @@
+import { vec2 } from 'gl-matrix';
+import { GraphEngine } from '../renderer';
+import { HUDAction } from '../overlay';
+/**
+ * GroupInteraction manages all combo/group related interactions.
+ *
+ * Behavior design:
+ * - Click on combo HUD: Toggle collapse/expand or enter Edit Mode.
+ * - Edit Mode: Highlights the group and selects all its members.
+ * - Drag nodes INTO a group hull: Add nodes to that group.
+ * - Drag nodes OUT of a group hull: Remove nodes from that group.
+ * - Click on combo hull: Drag the entire group.
+ */
+export declare class GroupInteraction {
+    private engine;
+    private canvas;
+    private _lastDropPickTime;
+    constructor(engine: GraphEngine, canvas: HTMLCanvasElement);
+    /**
+     * Handles HUD button actions (expand/collapse, edit).
+     * Returns true if handled — caller should return early.
+     */
+    handleHUDAction(hudAction: HUDAction): boolean;
+    /**
+     * Throttled drop-target highlight during node dragging.
+     * Shows orange feedback when dragging over a group.
+     */
+    handleDragOver(mouseX: number, mouseY: number): void;
+    /**
+     * Called on mouse/touch-up after dragging nodes.
+     * Membership is updated based on where the nodes were dropped.
+     */
+    handleDrop(mouseX: number, mouseY: number): void;
+    /**
+     * Moves the selected combo by the world-space delta from last mouse position.
+     */
+    handleGroupDrag(mouseX: number, mouseY: number, lastMouse: vec2): void;
+    /** Exits edit mode and clears selection. Call when clicking on empty space. */
+    exitEditMode(): void;
+}

package/dist/engine/interaction.d.ts

@@ -1,9 +1,11 @@
-import type { GraphEngine } from "./renderer";
+import { GraphEngine } from './renderer';
 export declare class InteractionManager {
     private lastMouse;
     private isPanning;
+    private isDraggingCombo;
     private engine;
     private canvas;
+    private groups;
     private lastTouchDistance;
     private lastTouchMidpoint;
     private isTouching;
@@ -11,9 +13,12 @@ export declare class InteractionManager {
     private touchStartPos;
     private longPressTimer;
     private isLongPress;
-    private isDraggingCombo;
+    private lastPickTime;
+    private _zoomSettleTimer;
+    private _disposers;
     constructor(engine: GraphEngine, canvas: HTMLCanvasElement);
     private setupListeners;
+    destroy(): void;
     private handleMouseDown;
     private handleMouseMove;
     private handleMouseUp;

package/dist/engine/overlay/ComboRenderer.d.ts

@@ -0,0 +1,25 @@
+import { mat3 } from 'gl-matrix';
+import { Combo } from '../types';
+import { SharedOverlayState } from './SharedOverlayState';
+export interface HUDAction {
+    comboId: string;
+    action: "expand" | "edit" | "delete";
+}
+/**
+ * Renders combo (group) hulls, their summary circles when collapsed, and
+ * the floating HUD strip used to expand/edit each one.
+ *
+ * Owns the `hudRects` map so HUD hit-testing can stay co-located with
+ * the drawing code that produced the rectangles.
+ */
+export declare class ComboRenderer {
+    private hudRects;
+    private state;
+    constructor(state: SharedOverlayState);
+    /** Hit-test the rendered HUD strip. Returns the action under the cursor, or null. */
+    pickHUDAction(mouseX: number, mouseY: number): HUDAction | null;
+    draw(combos: Map<string, Combo>, positions: Float32Array, nodeCount: number, viewMatrix: mat3, zoom: number, selectedComboId: string | null, dropTargetId: string | null, editingComboId: string | null, theme: string, dpr: number): void;
+    private drawCollapsedCombo;
+    private drawExpandedCombo;
+    private drawGroupHUD;
+}

package/dist/engine/overlay/EdgeRenderer.d.ts

@@ -0,0 +1,32 @@
+import { mat3 } from 'gl-matrix';
+import { NodeMetadata, EdgeMetadata, PhantomEdge } from '../types';
+import { SharedOverlayState } from './SharedOverlayState';
+/**
+ * Renders custom edges (when overriding the GPU edge buffer), edge labels,
+ * arrowheads, hover/selected highlights, and the drag-to-create phantom edge.
+ *
+ * Owns the small adjacency cache used by the hover pass so we don't rescan
+ * the full edge list every frame.
+ */
+export declare class EdgeRenderer {
+    private hoverNeighborCache;
+    private hoverCachedNodeId;
+    private hoverCachedEdgeCount;
+    private state;
+    constructor(state: SharedOverlayState);
+    drawHighlight(u: number, v: number, edgeId: string, positions: Float32Array, viewMatrix: mat3, dpr: number, nodeMetadata: Map<number, NodeMetadata>, edgeMetadata: Map<string, EdgeMetadata>, pointSize: number): void;
+    drawPhantom(phantom: PhantomEdge, positions: Float32Array, viewMatrix: mat3, dpr: number): void;
+    /**
+     * Draws every edge connected to `hoveredId` in the secondary highlight color.
+     * Adjacency list is cached and only rebuilt when the hovered node or edge
+     * topology changes — a major win on high-degree nodes.
+     */
+    drawHoverHighlight(hoveredId: number, indices: Uint32Array, count: number, theme: "dark" | "light", dpr: number, nodeMetadata: Map<number, NodeMetadata>, pointSize: number): void;
+    /**
+     * Draws edges that opt into custom styling (color, width, curvature, dash).
+     * Plain edges keep using the GPU pipeline.
+     */
+    drawCustomEdges(indices: Uint32Array, count: number, edgeMetadata: Map<string, EdgeMetadata>, edgeIndexToId: string[], theme: string, dpr: number, nodeMetadata: Map<number, NodeMetadata>, pointSize: number): void;
+    drawLabels(indices: Uint32Array, count: number, edgeMetadata: Map<string, EdgeMetadata>, edgeIndexToId: string[], theme: "dark" | "light", dpr: number, zoom: number, nodeMetadata: Map<number, NodeMetadata>, pointSize: number, defaultLabelMinZoom?: number, defaultLabelMaxZoom?: number): void;
+    drawArrows(indices: Uint32Array, count: number, edgeMetadata: Map<string, EdgeMetadata>, edgeIndexToId: string[], theme: string, dpr: number, zoom: number, nodeMetadata: Map<number, NodeMetadata>, pointSize: number): void;
+}

package/dist/engine/overlay/NodeRenderer.d.ts

@@ -0,0 +1,52 @@
+import { mat3 } from 'gl-matrix';
+import { NodeMetadata } from '../types';
+import { SharedOverlayState } from './SharedOverlayState';
+/**
+ * Draws everything that lives on a node: selection halos, shape borders,
+ * icons, labels, badges, and lock indicators.
+ */
+export declare class NodeRenderer {
+    private state;
+    constructor(state: SharedOverlayState);
+    /**
+     * Selection ring stroked just outside each selected node. Off-screen
+     * selections get a small directional ping.
+     */
+    drawHighlights(ids: Set<number>, count: number, positions: Float32Array, viewMatrix: mat3, pointSize: number, dpr: number, hiddenNodes: Set<number>, shapeData?: Float32Array, metadata?: Map<number, NodeMetadata>): void;
+    /**
+     * Re-fills each selected node with its `colorOnSelect` (when set). Must run
+     * AFTER `punchOutNodes` and BEFORE `drawLabels` so the icon stays on top.
+     */
+    drawSelectionFills(ids: Set<number>, count: number, metadata: Map<number, NodeMetadata>, pointSize: number, hiddenNodes: Set<number>, shapeData?: Float32Array): void;
+    /**
+     * Two offset shadow circles behind any node carrying the "nodeGroup" class,
+     * conveying that the node represents multiple collapsed entities.
+     */
+    drawGroupStackShadows(_count: number, metadata: Map<number, NodeMetadata>, pointSize: number, dpr: number, colorData: Float32Array): void;
+    /**
+     * Dark count badge top-right of every nodeGroup-classed node, showing
+     * `metadata.groupCount`. Skipped when groupCount is undefined or zero.
+     */
+    drawGroupBadges(_count: number, metadata: Map<number, NodeMetadata>, pointSize: number, dpr: number): void;
+    /**
+     * Dark expand-button (+) top-right of every nodeGroup-classed node.
+     */
+    drawExpandButtons(_count: number, metadata: Map<number, NodeMetadata>, pointSize: number, dpr: number): void;
+    /**
+     * Draws a thin shape outline + clipped icon/image for each visible node, then
+     * places its label according to alignment metadata. Caps total drawn nodes
+     * at `maxLabels` so very dense graphs don't tank the frame.
+     */
+    drawLabels(count: number, metadata: Map<number, NodeMetadata>, theme: "dark" | "light", dpr: number, pointSize: number, zoom: number, lockedNodes: Set<number>, shapeData?: Float32Array, defaultLabelMinZoom?: number, defaultLabelMaxZoom?: number, hoveredNodeId?: number | null, priorityNodeIds?: Set<number>, colorData?: Float32Array): void;
+    private drawLabelLoop;
+    /** Draws round badges at the four corners around a node circle. */
+    drawBadges(_count: number, metadata: Map<number, NodeMetadata>, dpr: number, pointSize: number, zoom: number): void;
+    /**
+     * Punches transparent holes where each node's circle sits, so that overlay
+     * elements drawn earlier (edge labels, arrows) are visually clipped behind
+     * the WebGL-rendered node beneath them.
+     */
+    punchOutNodes(_count: number, metadata: Map<number, NodeMetadata>, pointSize: number): void;
+    private drawNodeIcon;
+    private drawLockIcon;
+}

package/dist/engine/overlay/OverlayManager.d.ts

@@ -0,0 +1,38 @@
+import { OverlayRenderParams } from '../types';
+import { HUDAction } from './ComboRenderer';
+/**
+ * Top-level Canvas2D overlay coordinator.
+ *
+ * Responsibilities are kept narrow:
+ *  - own the shared scratch state + projection cache
+ *  - compute viewport bounds and pre-project visible nodes
+ *  - dispatch each render phase to a focused sub-renderer
+ *
+ * All actual drawing lives in ComboRenderer / NodeRenderer / EdgeRenderer
+ * and the small free-function modules in this directory.
+ */
+export declare class OverlayManager {
+    private state;
+    private combos;
+    private nodes;
+    private edges;
+    private invViewScratch;
+    private tlScratch;
+    private brScratch;
+    private vMinX;
+    private vMaxX;
+    private vMinY;
+    private vMaxY;
+    private wasProjecting;
+    constructor(canvas: HTMLCanvasElement, ctx: CanvasRenderingContext2D);
+    /** Fast clear for animation frames — skips all drawing work. */
+    clearOnly(): void;
+    /** Hit-test the combo HUD strip (delegates to ComboRenderer). */
+    pickHUDAction(mouseX: number, mouseY: number): HUDAction | null;
+    render(params: OverlayRenderParams): void;
+    /**
+     * Walks every node, marking culled ones with NaN in `projectedCache` and
+     * filling the rest with screen-space coords.
+     */
+    private projectVisibleNodes;
+}

package/dist/engine/overlay/SharedOverlayState.d.ts

@@ -0,0 +1,47 @@
+import { mat3, vec2, vec3 } from 'gl-matrix';
+/**
+ * Shared mutable state passed to every overlay sub-renderer.
+ *
+ * Owns the projection cache, scratch vectors, and `project()` helper so that
+ * sub-renderers can avoid re-allocating per frame and stay aligned on a single
+ * world→screen mapping.
+ */
+export declare class SharedOverlayState {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+    /** Screen-space (x,y) for every node, indexed by node id. NaN means culled. */
+    projectedCache: Float32Array<ArrayBuffer>;
+    /** Pre-built [0..count] index array, reused for label iteration. */
+    nodeIndices: Int32Array<ArrayBuffer>;
+    /**
+     * Subset of nodeIndices whose projected coords fall inside the canvas
+     * (plus a small margin). Built once per frame in OverlayManager.render
+     * after projection. Per-node overlay passes (punchOutNodes, drawLabels,
+     * drawBadges, drawGroupBadges, drawExpandButtons) iterate THIS instead
+     * of nodeIndices so they walk ~visible-count entries instead of N.
+     *
+     * On a 100K-node graph with ~500 nodes visible, this turns O(N)
+     * iterations per pass into O(visible) — typically 10–100× faster per
+     * Canvas2D pass during pan/zoom.
+     */
+    visibleNodeIndices: Int32Array<ArrayBuffer>;
+    /** Number of valid entries at the start of `visibleNodeIndices`. */
+    visibleNodeCount: number;
+    posScratch: vec3;
+    spScratch: vec2;
+    s1Scratch: vec2;
+    s2Scratch: vec2;
+    maxLabelsPerFrame: number;
+    smallGraphThreshold: number;
+    viewportCullMargin: number;
+    /** CSS pixels of inset between the icon and the node's outer border. */
+    nodeIconPaddingPx: number;
+    /** Toggle for the off-canvas-edge dot+arrow that marks a selected node
+     * outside the viewport. Mirrors GraphConfig.style.showOffscreenSelectionIndicator. */
+    showOffscreenSelectionIndicator: boolean;
+    constructor(canvas: HTMLCanvasElement, ctx: CanvasRenderingContext2D);
+    /** World→screen projection. Writes to `out` and returns it for chaining. */
+    project(x: number, y: number, viewMatrix: mat3, out: vec2): vec2;
+    /** Grow projection/index buffers if the node count exceeds current capacity. */
+    ensureCapacity(nodeCount: number): void;
+}

package/dist/engine/overlay/effects.d.ts

@@ -0,0 +1,15 @@
+import { vec2 } from 'gl-matrix';
+import { EdgeMetadata, FlowConfig } from '../types';
+/** Box-selection marquee rectangle. */
+export declare function drawMarquee(ctx: CanvasRenderingContext2D, start: vec2, end: vec2, dpr: number): void;
+/**
+ * Small "ping" + arrow at the screen edge pointing to an off-screen target.
+ * Used so users notice selected nodes/edges that have scrolled out of view.
+ */
+export declare function drawOffscreenIndicator(ctx: CanvasRenderingContext2D, canvas: HTMLCanvasElement, target1: vec2, target2: vec2, color: string, dpr: number): void;
+/**
+ * Animated particles travelling along edges. Reads endpoint positions from
+ * the projection cache (NaN endpoints are skipped). Particle count is capped
+ * via `step` so very dense graphs don't blow out path complexity.
+ */
+export declare function drawFlow(ctx: CanvasRenderingContext2D, projectedCache: Float32Array, indices: Uint32Array, count: number, zoom: number, dpr: number, theme: "dark" | "light", flow: FlowConfig, edgeMetadata: Map<string, EdgeMetadata>, selectedNodes: Set<number>): void;

package/dist/engine/overlay/index.d.ts

@@ -0,0 +1,2 @@
+export { OverlayManager } from './OverlayManager';
+export type { HUDAction } from './ComboRenderer';

package/dist/engine/overlay/shapes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shape index → Canvas2D path. Numeric ids match the GPU shader's switch:
+ *   0=circle, 1=square, 2=triangle, 3=diamond, 4=round-rect, 5=cut-rect.
+ *
+ * Caller is responsible for `beginPath()` before and `fill()`/`stroke()`/`clip()` after.
+ */
+export declare function drawShapePath(ctx: CanvasRenderingContext2D, x: number, y: number, r: number, shape: number): void;

package/dist/engine/overlay/text.d.ts

@@ -0,0 +1,15 @@
+import { NodeMetadata, EdgeMetadata } from '../types';
+/** Strip HTML tags so they aren't drawn literally onto the canvas. */
+export declare function stripHtml(text: string): string;
+/**
+ * Resolve the text actually rendered for a node/edge. Honors `labelHidden`
+ * and `labelSource` (which pulls a value from `meta.data`).
+ */
+export declare function resolveLabelText(meta: NodeMetadata | EdgeMetadata): string;
+/**
+ * Draws a metadata-driven text label with optional background, border, outline,
+ * uppercase/lowercase transform, and word-wrapping.
+ *
+ * `isMiddle` indicates an edge mid-label (different default styling than node labels).
+ */
+export declare function drawStyledText(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, meta: NodeMetadata | EdgeMetadata, theme: "dark" | "light", dpr: number, isMiddle?: boolean, bgOpacityOverride?: number, isHovered?: boolean, scale?: number): void;

package/dist/engine/picking.d.ts

@@ -1,7 +1,15 @@
-import { mat3 } from "gl-matrix";
-import type { Combo } from "./types";
+import { mat3 } from 'gl-matrix';
+import { Combo, EdgeMetadata } from './types';
 export declare class PickingEngine {
     private gl;
+    private _v1;
+    private _v2;
+    private _v3;
+    private _bSeg0;
+    private _bSeg1;
+    private _p1;
+    private _invViewScratch;
+    private _mouseNDC;
     constructor(gl: WebGL2RenderingContext);
     pickNode(params: {
         mouseX: number;
@@ -23,6 +31,8 @@ export declare class PickingEngine {
         viewMatrix: mat3;
         canvasW: number;
         canvasH: number;
+        edgeMetadata: Map<string, EdgeMetadata>;
+        edgeIndexToId: string[];
     }): string | null;
     pickCombo(params: {
         mouseX: number;
@@ -34,7 +44,8 @@ export declare class PickingEngine {
         zoom: number;
         canvasW: number;
         canvasH: number;
+        excludeIndices?: Set<number>;
     }): string | null;
     private distToSegment;
-    private project;
+    private projectTo;
 }

package/dist/engine/renderConstants.d.ts

@@ -0,0 +1,13 @@
+export declare const SELECTION_RING_COLOR: "#4A9EFF";
+export declare const SELECTION_RING_WIDTH_PX: 3;
+export declare const SELECTION_RING_RADIUS_FACTOR: 1.1;
+export declare const NODE_GROUP_BADGE_RADIUS_PX: 10;
+export declare const NODE_GROUP_BADGE_FILL: "#76ABE7";
+export declare const NODE_GROUP_BADGE_TEXT: "#ffffff";
+export declare const NODE_GROUP_BADGE_TEXT_PX: 10;
+export declare const NODE_GROUP_STACK_SHADOW_OFFSETS: readonly number[];
+export declare const NODE_GROUP_STACK_SHADOW_OPACITY: 0.2;
+export declare const NODE_EXPAND_BUTTON_RADIUS_PX: 10;
+export declare const NODE_EXPAND_BUTTON_FILL: "#1a1a1a";
+export declare const NODE_EXPAND_BUTTON_ICON: "#ffffff";
+export declare const NODE_EXPAND_BUTTON_ICON_PX: 12;