@kortexya/nodus 0.1.1 → 0.1.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kortexya/nodus",
-  "version": "0.1.1",
-  "description": "Nodus \u2014 a high-performance graph visualization engine (WebGL/WebGPU/Canvas/SVG).",
+  "version": "0.1.3",
+  "description": "Nodus — a high-performance graph visualization engine (WebGL/WebGPU/Canvas/SVG).",
   "homepage": "https://kortexya.com",
   "author": "Kortexya <david.loiret@kortexya.com>",
   "license": "UNLICENSED",

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/Geo.d.ts

@@ -41,6 +41,15 @@ export declare class Geo extends Module {
             longitude: number;
         };
     }) => Promise<any[]>;
+    /**
+     * Set geographic coordinates on a list of nodes. `coords[i]` is
+     * `{ latitude, longitude }` for `nodes.get(i)`. The values are written to each
+     * node's data at the configured latitude/longitude paths, then projected into
+     * the internal geo.lat/geo.lng arrays (and re-rendered if geo mode is on).
+     * Backs the public `node.setGeoCoordinates()` / `nodeList.setGeoCoordinates()`
+     * and the in-map node-drag handler.
+     */
+    setNodeGeoCoordinates(nodes: any, coords: any[]): Promise<any>;
     onMounted(): void;
     private _onDataChange;
     private _refreshOrAddNodes;

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;