@kortexya/nodus 0.1.0 → 0.1.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kortexya/nodus",
-  "version": "0.1.0",
-  "description": "Nodus \u2014 a high-performance graph visualization engine (WebGL/WebGPU/Canvas/SVG).",
+  "version": "0.1.2",
+  "description": "Nodus — a high-performance graph visualization engine (WebGL/WebGPU/Canvas/SVG).",
   "homepage": "https://kortexya.com",
   "author": "Kortexya <david.loiret@kortexya.com>",
   "license": "UNLICENSED",
@@ -19,7 +19,10 @@
     "clean:dist": "rm -f nodus.src.bundle.js nodus_wasm-*.js nodus_render_wasm-*.js __vite-plugin-wasm-helper-*.js chunk-*.js && rm -rf assets types",
     "build:types": "tsc -p tsconfig.json --declaration --emitDeclarationOnly --noEmit false --outDir types",
     "prepublishOnly": "npm run build",
-    "release": "bash scripts/release.sh"
+    "release": "bash scripts/release.sh",
+    "docs:dev": "npm --prefix docs run dev",
+    "docs:build": "npm --prefix docs run build",
+    "docs:preview": "npm --prefix docs run preview"
   },
   "exports": {
     ".": {

package/types/hypergraph/render/BubbleSets.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Bubble Sets — member-tight, non-member-avoiding set boundaries.
+ *
+ * The naive way to draw a hyperedge is the convex hull of its member vertices
+ * (see `monotoneChain`). A convex hull encloses everything between its corners,
+ * so it routinely swallows vertices that are NOT members — drawing an overlap
+ * that doesn't exist. For a tool whose job is conveying which evidence is shared,
+ * that is a correctness bug, not a cosmetic one.
+ *
+ * Bubble Sets (Collins, Penn & Carpendale, "Bubble Sets: Revealing Set Relations
+ * with Isocontours over Existing Visualizations", IEEE TVCG 2009) fixes it with a
+ * scalar energy field: member vertices (and the virtual edges that connect them)
+ * deposit POSITIVE energy that attracts the contour; non-member vertices deposit
+ * NEGATIVE energy that repels it. The boundary is the isocontour at a threshold,
+ * traced with marching squares and smoothed. The result hugs the members, bridges
+ * them into one organic blob, and carves AROUND (or punches a hole through) any
+ * non-member caught in the middle.
+ *
+ * Everything here is in world coordinates and camera-independent, so the result
+ * is cached by the caller and only recomputed when vertex positions change.
+ */
+import type { Vec2 } from '../types';
+export interface BubbleSetOptions {
+    /** Characteristic length L (world units). Derived from member spacing when omitted. */
+    scale?: number;
+    memberR0Factor?: number;
+    memberR1Factor?: number;
+    edgeR1Factor?: number;
+    nmR0Factor?: number;
+    nmR1Factor?: number;
+    threshold?: number;
+    memberInfluence?: number;
+    edgeInfluence?: number;
+    nonMemberInfluence?: number;
+    smooth?: number;
+    maxGrid?: number;
+}
+/**
+ * Compute the boundary of a set as one or more closed world-space loops.
+ * Multiple loops happen when the set is genuinely disconnected, or when a
+ * non-member punches a hole — render them with the even-odd fill rule.
+ */
+export declare function computeBubbleSet(members: Vec2[], nonMembers: Vec2[], opts?: BubbleSetOptions): Vec2[][];
+/** Even-odd point-in-set test against a set of loops (matches the fill rule). */
+export declare function pointInLoops(x: number, y: number, loops: Vec2[][]): boolean;

package/types/hypergraph/render/Interaction.d.ts

@@ -15,6 +15,10 @@ export interface HitTestState {
     vertexRadius: number;
     /** 'primal' | 'dual' | 'both' — which set of polygons to hit-test. */
     view: 'primal' | 'dual' | 'both';
+    /** Bubble-set boundary loops per hyperedge — when present, the cursor is
+     *  tested against the SAME shape that's drawn (so hover matches the polygon
+     *  and never fires for a non-member region). Falls back to the convex hull. */
+    contours?: Map<HypergraphId, Vec2[][]>;
 }
 export interface HitResult {
     hyperedge: HypergraphId | null;

package/types/hypergraph/render/PolygonRenderer.d.ts

@@ -18,6 +18,11 @@ export interface PolygonRenderState {
     options: Required<Omit<HypergraphRenderOptions, 'palette'>> & {
         palette: HypergraphRenderOptions['palette'];
     };
+    /** Precomputed world-space boundary loops per hyperedge (Bubble Sets). When
+     *  present (flat primal view), polygons are drawn/​filled from these instead
+     *  of the convex hull — so the boundary excludes non-members. Multiple loops
+     *  per hyperedge are filled even-odd (holes around interior non-members). */
+    contours?: Map<HypergraphId, Vec2[][]>;
     /** Currently-hovered primal hyperedge id. */
     hoveredHyperedge?: HypergraphId | null;
     /** Hovered dual hyperedge (corresponds to a primal vertex). */

package/types/hypergraph/types.d.ts

@@ -145,6 +145,11 @@ export interface HypergraphRenderOptions {
      *  draws a small label badge at the vertex position. Used for
      *  Aït-Kaci coreference X-tags. */
     vertexTag?: (v: HypergraphVertex) => string | null | undefined;
+    /** Hyperedge boundary style for the flat primal view. `'bubble'` (default)
+     *  draws member-tight Bubble Sets that exclude non-member vertices; `'hull'`
+     *  draws the legacy convex hull (faster, but encloses non-members). 2.5D and
+     *  dual views always use the convex hull. */
+    boundary?: 'bubble' | 'hull';
 }
 export interface InteractionEvent {
     /** Hyperedge id under cursor, if any. */

package/types/internals/Hypergraph.d.ts

@@ -36,6 +36,10 @@ export declare class Hypergraph extends Module {
     /** Last applied render options. */
     renderOptions: PolygonRenderState['options'] | null;
     private _layers;
+    /** Cached Bubble-Set boundary loops, keyed by a positions+structure
+     *  signature so they recompute only when vertices actually move (not on
+     *  every camera pan/zoom frame). */
+    private _contourCache;
     hoveredHyperedge: HypergraphId | null;
     hoveredDualOf: HypergraphId | null;
     hoveredVertex: HypergraphId | null;
@@ -58,6 +62,15 @@ export declare class Hypergraph extends Module {
      *   3. undefined — caller skips this vertex.
      */
     private _resolvePosition;
+    /**
+     * Push apart any vertices the optimizer left (near-)coincident. When two
+     * vertices that belong to DIFFERENT hyperedges land on top of each other, no
+     * region boundary can contain one while excluding the other — so the polygon
+     * is forced to swallow a non-member. A light relaxation that only moves pairs
+     * closer than the minimum spacing (and leaves everything else untouched)
+     * removes that pathology while preserving the optimized layout.
+     */
+    private _separateVertices;
     /** Build a live positions map for the renderer — combines optimizer
      *  output with bound Nodus node positions. */
     private _livePositions;
@@ -85,6 +98,22 @@ export declare class Hypergraph extends Module {
     getDualPositions(): Map<HypergraphId, Vec2>;
     /** CCW convex-hull polygon for one hyperedge — uses live positions. */
     getHyperedgePolygon(heId: HypergraphId): Vec2[];
+    /** Member-tight Bubble-Set boundary loops for one hyperedge (the SHAPE the
+     *  renderer actually draws in the flat primal view). Multiple loops = a
+     *  disconnected set or a hole carved around an interior non-member; test
+     *  containment even-odd. Falls back to the convex hull when bubble boundaries
+     *  are disabled or unavailable. */
+    getHyperedgeContours(heId: HypergraphId): Vec2[][];
+    /**
+     * Compute (and cache) the Bubble-Set boundary loops for every hyperedge.
+     * Members of a hyperedge attract the contour; all OTHER vertices repel it,
+     * so the boundary hugs the members and routes around / holes out anything
+     * that isn't one of them — unlike the convex hull, which swallows them.
+     *
+     * Cached by a cheap positions+structure signature so a static graph computes
+     * this once and every subsequent camera frame reuses it.
+     */
+    private _ensureContours;
     render(opts?: HypergraphRenderOptions): RenderHandles;
     private _bindInteraction;
     private _unbindInteraction;
@@ -101,6 +130,10 @@ export declare class Hypergraph extends Module {
     }): void;
     clearSelection(): void;
     getHyperedgeAtPoint(world: Vec2): InteractionEvent;
+    /** ALL hyperedges whose drawn boundary contains `world` (≥2 ⇒ the cursor is
+     *  in a real overlap region). Uses the same Bubble-Set contours as the
+     *  renderer + hit-test, so it never reports a non-member region as overlap. */
+    getHyperedgesAtPoint(world: Vec2): HypergraphId[];
     refreshLayers(): void;
     removeLayers(): void;
     setActiveView(view: 'primal' | 'dual' | 'both'): void;

package/types/modules/HypergraphAPI.d.ts

@@ -31,6 +31,10 @@ export declare class HypergraphAPI extends APIModule {
     getVertexPositions(): Map<HypergraphId, Vec2>;
     getDualPositions(): Map<HypergraphId, Vec2>;
     getHyperedgePolygon(heId: HypergraphId): Vec2[];
+    /** Member-tight Bubble-Set boundary loops (the shape actually drawn). */
+    getHyperedgeContours(heId: HypergraphId): Vec2[][];
+    /** All hyperedges whose drawn boundary contains the world point (overlap). */
+    getHyperedgesAtPoint(world: Vec2): HypergraphId[];
     render(opts?: HypergraphRenderOptions): {
         primal?: any;
         dual?: any;

package/types/renderers/WasmGraphRenderer.d.ts

@@ -25,16 +25,24 @@ export declare class WasmGraphRenderer {
     private _raf;
     private _toLinear;
     private _styleVersion;
+    private _styleDirty;
+    private _frameScheduled;
     private _radii;
     private _fill;
     private _shape;
     private _stroke;
     private _sw;
+    private _swMinVis;
+    private _layer;
+    private _pulses;
     private _outline;
     private _haloCol;
     private _haloW;
+    private _outerCol;
+    private _outerW;
     private _imageTile;
     private _atlasKey;
+    private _pieColors;
     private _pieOffset;
     private _pieCount;
     private _pieSegs;
@@ -42,14 +50,45 @@ export declare class WasmGraphRenderer {
     private _edgeColor;
     private _edgeWidth;
     private _edgeCurv;
+    private _edgeArrows;
+    private _edgeDash;
+    private _edgeHaloCol;
+    private _edgeHaloW;
+    private _edgeOutlineCol;
+    private _edgeOutlineW;
+    private _edgeLabel;
+    private _edgeLabelFont;
+    private _edgeLabelCol;
+    private _edgeLabelSize;
+    private _edgeLabelSec;
+    private _edgeLabelSecFont;
+    private _edgeLabelSecCol;
     private _xs;
     private _ys;
     private _nodeIds;
     private _labels;
     private _lastCam;
-    private _fitted;
+    private _autoFrame;
+    private _selfMovingCamera;
+    private _lastFit;
     private _glyphs;
+    private _glyphKey;
+    private _textFonts;
+    private _labelCol;
+    private _labelMinVis;
+    private _labelMaxLine;
+    private _labelSize;
+    private _labelSecSize;
+    private _labelPos;
+    private _labelSecondary;
+    private _labelSecCol;
+    private _labelSecFont;
+    private _labelSecBg;
+    private _labelBgCol;
+    private _icons;
     private _fontPx;
+    private _targetAtlasPx;
+    private _quadScale;
     private _highlight;
     private _pieData;
     private _badgeNode;
@@ -60,13 +99,19 @@ export declare class WasmGraphRenderer {
     private _badgeStrokeCol;
     private _badgeStrokeW;
     private _badgeText;
+    private _badgeFont;
     private _badgeTextCol;
     private constructor();
+    /** Coalesce redraw requests into a single rAF-driven frame (no-op if one is already pending or the
+     * environment has no rAF). Keeps event-driven redraws cheap when many events fire in one tick. */
+    private _scheduleFrame;
     /** Create a renderer bound to `canvas`. `WasmRendererClass` is the lazy-loaded wgpu class. */
     static create(nodus: any, canvas: HTMLCanvasElement, WasmRendererClass: any, opts?: WasmGraphRendererOptions): Promise<WasmGraphRenderer>;
     /** Rasterise an ASCII glyph atlas (white, alpha=coverage) into a texture the TEXT shader samples,
      * recording each glyph's UV region. Monospace-ish layout in a fixed cell grid. */
     private _buildAtlas;
+    /** CELL/ATLAS_PX from `_buildAtlas` — scales a quad so the em renders at the requested font size. */
+    private static readonly _QUAD_SCALE;
     /** Load image URLs into a 16×16 tile grid atlas (64px tiles, 1024² sRGB) and upload it; redraw on
      * completion so node icons appear. attrEx.y (set in _buildNodeAttrs) selects each node's tile. */
     private _loadAtlas;
@@ -76,6 +121,11 @@ export declare class WasmGraphRenderer {
     private _buildText;
     private _dpr;
     private _sizeCanvas;
+    /** Keep the backing store (and wgpu surface) matched to the canvas's displayed CSS size × DPR.
+     * Called every frame — a no-op when the size is unchanged. Without it a responsive container or a
+     * canvas sized before layout (clientWidth 0 → 320 fallback at create) renders at a stale, smaller
+     * resolution that the browser upscales, which reads as a soft / non-crisp image. */
+    private _syncCanvasSize;
     /** getAttribute that returns null instead of throwing on an undefined attribute name. */
     private _safeAttr;
     /** A Nodus style value (false/null = off, colour string, or {color,...}) → LINEAR rgba, or null. */
@@ -98,8 +148,16 @@ export declare class WasmGraphRenderer {
      *   [20..24] outerStrokeCol   [24..28] outlineCol */
     private _buildNodeAttrs;
     /** Assemble the edge attr SoA the EDGE shader decodes — 2×u32 per edge: packed rgba8 colour, then
-     * (widthU16 | dash<<16 | arrows<<20 | widthScale<<22 | curvByte<<24). The edge feature surface. */
+     * (width14 | dash<<14 | headShape<<16 | tailShape<<19 | widthScale<<22 | curvByte<<24). headShape/
+     * tailShape are 3-bit extremity shapes (0 none,1 arrow,2 square,3 circle,4 open-arrow). Feature surface. */
     private _buildEdgeAttrs;
+    /** Halo edges: a wider, halo-coloured copy of each haloed edge, packed like _buildEdgeAttrs so it can
+     * be PREPENDED (drawn behind the real edges). No dash/arrows; width = edgeWidth + 2·haloWidth. */
+    private _buildEdgeHalos;
+    /** Active pulse rings this frame → instance arrays (a transparent disk with a coloured inner-stroke
+     * ring). Each enabled node spawns a ring every `iv` ms; a ring lives `du` ms, growing sr→er·radius
+     * while its colour lerps sc→ec (→ transparent). Empty when nothing pulses. */
+    private _buildPulseRings;
     /** Draw one frame from the live graph. */
     renderFrame(): void;
     /** Hit-test a canvas-relative screen point (CSS px) → node id, or null. CPU point-in-radius