vortx-gl 1.0.36 → 1.0.38

package/README.md

@@ -419,6 +419,22 @@ Visual properties are applied in the following order of precedence:
 2. **Class Styles**: Properties defined in the stylesheet for the applied classes.
 3. **Engine Defaults**: Hardcoded fallback values.
 
+### 4. Focus (Dim Everything Else)
+Draw a subset normally and dim the rest. Dimmed elements stay interactive (hover, pick, select), and no element style is changed, so clearing restores the previous look.
+
+```typescript
+// Focus two nodes; edges between them are in focus too.
+engine.setFocus(["node-1", "node-2"]);
+
+// Or name the edges in focus explicitly.
+engine.setFocus(["node-1", "node-2"], ["edge-7"]);
+
+engine.getFocus();   // { nodeIds, edgeIds? } or null
+engine.clearFocus(); // same as setFocus(null) or setFocus([])
+```
+
+Unknown ids are ignored. The dim level is `style.focusDimOpacity` (default `0.15`), read from the config passed to the engine (GraphCanvas `config` prop), e.g. `{ style: { focusDimOpacity: 0.25 } }`.
+
 ---
 
 ## ⚡ Energy Flow Animation

package/dist/engine/config.d.ts

@@ -78,6 +78,11 @@ export declare const GraphConfig: {
          * selected node). Set false to suppress.
          */
         readonly showOffscreenSelectionIndicator: true;
+        /**
+         * Opacity (0–1) of every node and edge outside the current focus set
+         * (GraphEngine.setFocus). Unused while no focus is set.
+         */
+        readonly focusDimOpacity: 0.15;
     };
     readonly graphOptions: {
         /** Cytoscape: text-opacity 1 vs 0 on `.nodes`. */

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

@@ -10,6 +10,9 @@ export declare class GpuBufferManager {
     sizeBuffer: WebGLBuffer | null;
     targetPositionBuffer: WebGLBuffer | null;
     edgeIndexBuffer: WebGLBuffer | null;
+    focusDimBuffer: WebGLBuffer | null;
+    focusEdgeIndexBuffer: WebGLBuffer | null;
+    dimEdgeIndexBuffer: WebGLBuffer | null;
     pickingFramebuffer: WebGLFramebuffer | null;
     pickingTexture: WebGLTexture | null;
     uMatrixLoc: WebGLUniformLocation | null;
@@ -20,12 +23,28 @@ export declare class GpuBufferManager {
     uEdgeColorLoc: WebGLUniformLocation | null;
     uTransitionProgressLoc: WebGLUniformLocation | null;
     uEdgeTransitionProgressLoc: WebGLUniformLocation | null;
+    uFocusDimLoc: WebGLUniformLocation | null;
+    uBgColorLoc: WebGLUniformLocation | null;
     private gl;
     private canvas;
     constructor(gl: WebGL2RenderingContext, canvas: HTMLCanvasElement);
     init(): void;
     private initShaders;
     private initBuffers;
+    /**
+     * Upload the per-node focus dim flags (1 = dimmed, 0 = normal), one float per
+     * node, and enable a_dimmed. `null` disables the attribute, which makes every
+     * node read 0 (no dim) at zero per-frame cost. The array must cover every
+     * drawn node — the caller re-syncs whenever the node count changes.
+     */
+    syncFocusNodes(dimmed: Float32Array | null): void;
+    /** Upload the focused / out-of-focus halves of the edge index buffer. */
+    syncFocusEdges(focused: Uint32Array, dimmed: Uint32Array): void;
+    /**
+     * Draw `count` indices of one focus half with the edge program already in
+     * use and its uniforms set, then restore the edge VAO's own index buffer.
+     */
+    drawFocusEdges(which: "focused" | "dimmed", count: number): void;
     initPicking(): void;
     private createProgram;
     reallocateNodeBuffers(positions: Float32Array, colorData: Float32Array, idData: Float32Array, shapeData: Float32Array, sizeData?: Float32Array): void;

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

@@ -40,7 +40,23 @@ export declare class SharedOverlayState {
     /** Toggle for the off-canvas-edge dot+arrow that marks a selected node
      * outside the viewport. Mirrors GraphConfig.style.showOffscreenSelectionIndicator. */
     showOffscreenSelectionIndicator: boolean;
+    /**
+     * Focus (GraphEngine.setFocus): node indices drawn at full opacity. null
+     * means no focus, and every pass takes its unchanged fast path.
+     */
+    focusNodes: Set<number> | null;
+    /**
+     * Edge ids in focus. null while focusNodes is set means "derive from the
+     * endpoints": an edge is in focus when both of its nodes are.
+     */
+    focusEdges: Set<string> | null;
+    /** Opacity of out-of-focus elements. Mirrors GraphConfig.style.focusDimOpacity. */
+    focusDimOpacity: number;
     constructor(canvas: HTMLCanvasElement, ctx: CanvasRenderingContext2D);
+    /** True when a focus is set and node `i` is outside it. O(1). */
+    isNodeDimmed(i: number): boolean;
+    /** True when a focus is set and the edge (u→v, id) is outside it. O(1). */
+    isEdgeDimmed(u: number, v: number, id: string | undefined): boolean;
     /** 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. */

package/dist/engine/renderer.d.ts

@@ -54,6 +54,17 @@ export declare class GraphEngine {
     resolvedEdgeStyles: Map<string, ResolvedEdgeStyle>;
     resolvedEdgeSelectStyles: Map<string, ResolvedEdgeSelectStyle>;
     private _lastBackendData;
+    private _focusNodeIds;
+    private _focusEdgeIds;
+    /** Resolved focused node indices; null = no effective focus (fast path). */
+    private _focusNodeIdx;
+    private _focusDirty;
+    private _focusNodeCount;
+    private _focusIdMapRef;
+    private _focusEdgeIndicesRef;
+    private _focusDimData;
+    private _focusEdgeCount;
+    private _dimEdgeCount;
     constructor(canvas: HTMLCanvasElement, overlayCanvas: HTMLCanvasElement, configOverrides?: PartialGraphConfig);
     destroy(): void;
     attachMinimap(canvas: HTMLCanvasElement, intervalMs?: number): Minimap;
@@ -292,6 +303,39 @@ export declare class GraphEngine {
         period?: number;
     }): void;
     clearHighlight(): void;
+    /**
+     * Focus: draw the given nodes (and edges) normally and everything else
+     * dimmed to `GraphConfig.style.focusDimOpacity`. Dimmed elements stay fully
+     * interactive (hover, pick, select). Purely visual — no node or edge state
+     * is mutated, so clearFocus() restores exactly the previous look.
+     *
+     * @param nodeIds user ids, resolved like selectNodes(); unknown ids are
+     *   ignored. `null` or an empty list clears the focus.
+     * @param edgeIds edge ids in focus. When omitted, an edge is in focus when
+     *   both of its endpoints are.
+     *
+     * Ids are kept, not indices: after nodes/edges are added or removed the
+     * focus is re-resolved, and ids that no longer exist simply don't match.
+     */
+    setFocus(nodeIds: ReadonlyArray<string | number> | null, edgeIds?: ReadonlyArray<string>): void;
+    /** Remove the focus; every node and edge returns to its normal look. */
+    clearFocus(): void;
+    /**
+     * Current focus as passed to setFocus (canonical node ids, explicit edge
+     * ids or undefined), or null when no focus is set.
+     */
+    getFocus(): {
+        nodeIds: Array<string | number>;
+        edgeIds?: string[];
+    } | null;
+    /**
+     * Bring the resolved focus sets + GPU focus buffers in line with the
+     * current node/edge arrays. O(1) when nothing changed; otherwise
+     * O(focus + N + E), which only happens on setFocus or a node/edge set
+     * change — never per frame.
+     */
+    private _syncFocus;
+    private _isEdgeFocused;
     /** Pan/zoom the camera to frame just the given nodes (bbox + margin). */
     fitToNodes(ids: ReadonlyArray<string | number>): void;
     setTransitionState(t: number): void;

package/dist/engine/shaders/node.glsl.d.ts

@@ -1,2 +1,2 @@
-export declare const NODE_VS = "#version 300 es\nlayout(location = 0) in vec2 a_position;\nlayout(location = 1) in vec4 a_color;\nlayout(location = 2) in float a_id;\nlayout(location = 3) in vec2 a_targetPosition;\nlayout(location = 4) in float a_shape;\n// Per-node size multiplier. 1.0 = base size, 2.0 = 2x bigger, etc.\n// Sourced from (input.size || input.width || 50) / 50 at ingest.\nlayout(location = 5) in float a_size;\n\nuniform mat3 u_matrix;\nuniform float u_pointSize;\n// GPU's ALIASED_POINT_SIZE_RANGE upper bound, set once at init by the\n// renderer. Clamped here so a node with size > 1 never exceeds the GPU\n// limit and silently mismatches the overlay's idea of where the sprite\n// edge is. Overlay reads the same clamp via getMaxNodePointSize().\nuniform float u_pointSizeMax;\nuniform bool u_pickingMode;\nuniform float u_transitionProgress;\n\nout vec4 v_color;\nflat out uint v_id;\nflat out int v_shape;\n\nvoid main() {\n    // Interpolate between current and target position on GPU\n    vec2 pos = mix(a_position, a_targetPosition, u_transitionProgress);\n    vec3 position = u_matrix * vec3(pos, 1.0);\n    gl_Position = vec4(position.xy, 0, 1);\n    gl_PointSize = min(u_pointSize * a_size, u_pointSizeMax);\n\n    // Visible nodes are forced opaque so edges (drawn before) never leak\n    // through the node body. Hidden nodes (alpha < 0.001) still vanish via\n    // the discard branch in the fragment shader.\n    float alpha = a_color.a < 0.001 ? 0.0 : 1.0;\n    v_color = vec4(a_color.rgb, alpha);\n    v_id = uint(a_id);\n    v_shape = int(a_shape);\n}\n";
+export declare const NODE_VS = "#version 300 es\nlayout(location = 0) in vec2 a_position;\nlayout(location = 1) in vec4 a_color;\nlayout(location = 2) in float a_id;\nlayout(location = 3) in vec2 a_targetPosition;\nlayout(location = 4) in float a_shape;\n// Per-node size multiplier. 1.0 = base size, 2.0 = 2x bigger, etc.\n// Sourced from (input.size || input.width || 50) / 50 at ingest.\nlayout(location = 5) in float a_size;\n// Focus: 1.0 = out of focus (dimmed), 0.0 = normal. The array is only\n// enabled while a focus is set; disabled, WebGL feeds the default generic\n// attribute value (0,0,0,1), so its x component reads 0.0 = no dim.\nlayout(location = 6) in float a_dimmed;\n\nuniform mat3 u_matrix;\nuniform float u_pointSize;\n// GPU's ALIASED_POINT_SIZE_RANGE upper bound, set once at init by the\n// renderer. Clamped here so a node with size > 1 never exceeds the GPU\n// limit and silently mismatches the overlay's idea of where the sprite\n// edge is. Overlay reads the same clamp via getMaxNodePointSize().\nuniform float u_pointSizeMax;\nuniform bool u_pickingMode;\nuniform float u_transitionProgress;\n// Opacity of out-of-focus nodes (GraphConfig.style.focusDimOpacity) and the\n// canvas clear colour they blend toward.\nuniform float u_focusDim;\nuniform vec3 u_bgColor;\n\nout vec4 v_color;\nflat out uint v_id;\nflat out int v_shape;\n\nvoid main() {\n    // Interpolate between current and target position on GPU\n    vec2 pos = mix(a_position, a_targetPosition, u_transitionProgress);\n    vec3 position = u_matrix * vec3(pos, 1.0);\n    gl_Position = vec4(position.xy, 0, 1);\n    gl_PointSize = min(u_pointSize * a_size, u_pointSizeMax);\n\n    // Visible nodes are forced opaque so edges (drawn before) never leak\n    // through the node body. Hidden nodes (alpha < 0.001) still vanish via\n    // the discard branch in the fragment shader.\n    float alpha = a_color.a < 0.001 ? 0.0 : 1.0;\n    // A dimmed node is blended toward the background colour instead of being\n    // made translucent: same look as alpha = u_focusDim over the clear colour,\n    // but the sprite stays opaque, so edges still don't leak through it and\n    // the hidden-node alpha test above is untouched.\n    vec3 rgb = mix(a_color.rgb, mix(u_bgColor, a_color.rgb, u_focusDim), a_dimmed);\n    v_color = vec4(rgb, alpha);\n    v_id = uint(a_id);\n    v_shape = int(a_shape);\n}\n";
 export declare const NODE_FS = "#version 300 es\nprecision highp float;\n\nin vec4 v_color;\nflat in uint v_id;\nflat in int v_shape;\n\nuniform bool u_pickingMode;\nout vec4 outColor;\n\nvoid main() {\n    vec2 p = gl_PointCoord - vec2(0.5);\n\n    // Every shape fills the full pointSize sprite (extent 0.5 from center)\n    // so edges + overlay decorations, which assume node radius == pointSize/2,\n    // actually reach the visible node border.\n    if (v_shape == 0) { // Circle\n        if (length(p) > 0.5) discard;\n    } else if (v_shape == 1) { // Square\n        if (abs(p.x) > 0.5 || abs(p.y) > 0.5) discard;\n    } else if (v_shape == 2) { // Triangle\n        if (p.y > 0.5 || p.y < -0.5 || abs(p.x) > (0.5 - (p.y + 0.5) * 0.5)) discard;\n    } else if (v_shape == 3) { // Diamond\n        if (abs(p.x) + abs(p.y) > 0.5) discard;\n    } else if (v_shape == 4) { // Round Rectangle\n        // Inner half-extent 0.3 + corner radius 0.2 \u2192 still reaches 0.5 at the\n        // edges, and the corner radius (0.2\u00B7diameter = 0.4\u00B7radius) now MATCHES\n        // drawShapePath's roundRect([r*0.4]) so the GPU fill no longer pokes\n        // past the Canvas2D border/shadow at the corners.\n        float dist = length(max(abs(p) - 0.3, 0.0));\n        if (dist > 0.2) discard;\n    } else if (v_shape == 5) { // Cut Rectangle\n        if (abs(p.x) > 0.5 || abs(p.y) > 0.5 || abs(p.x) + abs(p.y) > 0.85) discard;\n    }\n\n    // Hidden nodes (alpha == 0): skip rendering AND picking.\n    if (v_color.a < 0.001) discard;\n\n    if (u_pickingMode) {\n        uint id = v_id + 1u;\n        float r = float((id >> 16) & 0xFFu) / 255.0;\n        float g = float((id >> 8) & 0xFFu) / 255.0;\n        float b = float(id & 0xFFu) / 255.0;\n        outColor = vec4(r, g, b, 1.0);\n    } else {\n        outColor = v_color;\n    }\n}\n";

package/dist/engine/types.d.ts

@@ -375,6 +375,12 @@ export interface Combo {
      * button is also hidden for managed combos.
      */
     managed?: boolean;
+    /**
+     * Plain hull, e.g. to show clusters: no HUD pill and no collapse/edit
+     * buttons, and the fill + border come from `color`. Collapse it from code
+     * only. Pair with `managed` to keep members from being edited by drag.
+     */
+    decorative?: boolean;
 }
 /**
  * An item in the radial (circular) context menu.
@@ -758,4 +764,14 @@ export interface OverlayRenderParams extends InteractionState {
     defaultLabelMaxZoom?: number;
     config: import('./config').ResolvedGraphConfig;
     spatialIndex?: import('./spatialIndex').SpatialIndex;
+    /**
+     * Focus (GraphEngine.setFocus): node indices drawn at full opacity; every
+     * other node is dimmed to config.style.focusDimOpacity. null/undefined = no focus.
+     */
+    focusNodes?: Set<number> | null;
+    /**
+     * Edge ids in focus. null/undefined while focusNodes is set = an edge is in
+     * focus when both of its endpoints are.
+     */
+    focusEdges?: Set<string> | null;
 }