@kortexya/nodus 0.1.0

package/types/hypergraph/osfkb/adapter.d.ts

@@ -0,0 +1,315 @@
+/**
+ * OSFKB → Nodus adapter.
+ *
+ * Maps an OSFKB `VisualizationGraph` (Rust DTO at
+ * `osfkb/crates/api/src/dto/visualization.rs`) into:
+ *   - an Nodus node-link graph for `nodus.setGraph({ nodes, edges })`
+ *   - a hypergraph for `nodus.hypergraph.setData({ vertices, hyperedges })`
+ *
+ * The two are linked by id: each polygon vertex's `nodeId` is the same
+ * id as its corresponding Nodus node, so dragging an Nodus node moves the
+ * polygon corner in lockstep (when `vertex.nodeId` is honored — see
+ * `src/internals/Hypergraph.ts`).
+ *
+ * Endpoint shapes covered: hypergraph (POST .../visualization/hypergraph)
+ * and lattice (POST .../visualization/lattice). Both return a top-level
+ * `graph: VisualizationGraphDto` (response shape differs only in the
+ * surrounding stats / components fields).
+ */
+import type { HypergraphData } from '../types';
+export interface OsfkbGraphNode {
+    id: string;
+    label: string;
+    node_type: string | {
+        Custom: string;
+    };
+    entity_id?: string;
+    size?: number;
+    color?: string;
+    level?: number;
+    properties?: Record<string, string>;
+}
+export interface OsfkbGraphEdge {
+    id: string;
+    source: string;
+    target: string;
+    label?: string;
+    edge_type: string | {
+        Custom: string;
+    };
+    weight?: number;
+    curvature?: number;
+    color?: string;
+    properties?: Record<string, string>;
+}
+export interface OsfkbHyperedge {
+    id: string;
+    label?: string;
+    nodes: string[];
+    ordered: boolean;
+    hyperedge_type: string | {
+        Custom: string;
+    };
+    source_term_id?: string;
+    color?: string;
+    properties?: Record<string, string>;
+}
+export interface OsfkbVisualizationGraph {
+    graph_id?: string;
+    metadata?: {
+        title?: string;
+        description?: string;
+        node_count?: number;
+        edge_count?: number;
+        hyperedge_count?: number;
+    };
+    nodes: OsfkbGraphNode[];
+    edges: OsfkbGraphEdge[];
+    hyperedges: OsfkbHyperedge[];
+    layout?: {
+        algorithm?: string;
+        direction?: string;
+    };
+}
+/** Either endpoint wraps `graph: VisualizationGraphDto`. */
+export interface OsfkbVisualizationResponse {
+    graph: OsfkbVisualizationGraph;
+    /** Present on /hypergraph responses — Aït-Kaci coreference groups. */
+    coreferences?: OsfkbCoreferenceGroup[];
+    /** Present on /derivation responses. */
+    iterations?: number;
+    fixpoint_reached?: boolean;
+    derived_count?: number;
+    rule_application_count?: number;
+}
+export interface OsfkbCoreferenceGroup {
+    target_term_id: string;
+    tag: string;
+    references: Array<{
+        term_id: string;
+        feature_name: string;
+    }>;
+}
+/** Nodus node descriptor — minimal shape `nodus.setGraph` accepts. */
+export interface NodusGraphNode {
+    id: string;
+    attributes: {
+        x: number;
+        y: number;
+        radius: number;
+        color: string;
+        text?: {
+            content?: string;
+        };
+    };
+    data?: any;
+}
+/** Nodus edge descriptor. */
+export interface NodusGraphEdge {
+    id: string;
+    source: string;
+    target: string;
+    attributes?: {
+        color?: string;
+        width?: number;
+    };
+    data?: any;
+}
+export interface OsfkbAdapterResult {
+    /** Nodus underlying node-link graph (term/sort/feature nodes + binary edges). */
+    nodusGraph: {
+        nodes: NodusGraphNode[];
+        edges: NodusGraphEdge[];
+    };
+    /** Hypergraph data for `nodus.hypergraph.setData(...)`. */
+    hypergraph: HypergraphData;
+    /** Convenience: id → original OSFKB node so caller can hydrate UI. */
+    nodeIndex: Map<string, OsfkbGraphNode>;
+    /** Convenience: id → original OSFKB hyperedge. */
+    hyperedgeIndex: Map<string, OsfkbHyperedge>;
+    /** Aït-Kaci coreference groups echoed through from the OSFKB
+     *  response (the same Ψ-term referenced from multiple feature
+     *  occurrences). Renderers paint these as identity edges with the
+     *  shared "X" tag. */
+    coreferences: OsfkbCoreferenceGroup[];
+    /** True if this is a derivation-lattice response (different
+     *  coloring conventions; rules vs. facts). */
+    isDerivation: boolean;
+}
+export interface AdaptOptions {
+    /** Initial radius for the ring layout placeholder. Default 600. */
+    initialRadius?: number;
+    /** Per-node radius. Default 6. */
+    nodeRadius?: number;
+    /** Color palette indexed by hyperedge_type. Falls back to default. */
+    hyperedgeColors?: Partial<Record<string, string>>;
+    /** Skip OSFKB Feature nodes (they make the underlying graph noisy
+     *  because each Ψ-term feature becomes its own dot). Default false. */
+    collapseFeatureNodes?: boolean;
+}
+/**
+ * Tenant-agnostic category extractor. Splits the node name on common
+ * separators and returns the first segment, falling back to `node_type`
+ * and finally to `(uncategorized)`. This is purely structural — it has
+ * no knowledge of any specific dataset's vocabulary. Tenants whose
+ * naming uses different conventions can supply a custom extractor at
+ * runtime via `viewer-config.json` (the example HTML invokes that
+ * override before passing nodes to the adapter; the adapter itself
+ * stays defaults-only).
+ *
+ * Exported so the example HTML can also call it for any side-channel
+ * nodes it constructs (search-result hydration, etc.).
+ */
+export declare function defaultExtractCategory(node: OsfkbGraphNode): string;
+/**
+ * Convert an OSFKB `VisualizationGraph` (or response wrapper) into the
+ * shapes Nodus needs.
+ */
+export declare function adaptOsfkbGraph(source: OsfkbVisualizationGraph | OsfkbVisualizationResponse, options?: AdaptOptions): OsfkbAdapterResult;
+export interface OsfkbClientOptions {
+    /** Base URL, no trailing slash. e.g. http://127.0.0.1:8080 */
+    baseUrl: string;
+    /** Required: tenant UUID for `X-Tenant-Id` header. */
+    tenantId: string;
+    /** Optional headers (namespace, user, ...). Merged with the auth header. */
+    headers?: Record<string, string>;
+}
+export declare function fetchOsfkbHypergraph(client: OsfkbClientOptions, body: {
+    root_term_id: string;
+    max_depth?: number;
+    include_hyperedges?: boolean;
+    include_relations?: boolean;
+    s_threshold?: number;
+}): Promise<OsfkbVisualizationResponse>;
+export declare function fetchOsfkbLattice(client: OsfkbClientOptions, body?: {
+    root_sort_id?: string;
+    max_depth?: number;
+    /** Page size; 0 = unlimited. Default 500 server-side. */
+    limit?: number;
+    /** Page offset. */
+    offset?: number;
+}): Promise<OsfkbVisualizationResponse>;
+/**
+ * Walk every page of the lattice endpoint and merge into a single
+ * response. Dedupes nodes by `id` and edges by `id` (server emits
+ * UUID-derived stable ids so accumulating pages reconstructs the
+ * same graph as a single unpaginated call).
+ *
+ * Optional `onPage(partial)` callback fires after each page is
+ * accumulated, with the cumulative response so far — letting the UI
+ * render incrementally without waiting for all pages to land.
+ */
+export declare function fetchOsfkbLatticeAll(client: OsfkbClientOptions, body?: {
+    root_sort_id?: string;
+    max_depth?: number;
+}, pageSize?: number, onProgress?: (loaded: number, total: number) => void, onPage?: (partial: OsfkbVisualizationResponse) => void | Promise<void>): Promise<OsfkbVisualizationResponse>;
+/**
+ * Fetch the forward-chain derivation lattice. Runs the homoiconic
+ * chainer with provenance enabled and returns a meta-hypergraph in the
+ * standard `VisualizationGraph` shape:
+ *   - Term nodes for each Ψ-term (assertion, rule, derivation)
+ *   - Rule nodes (NodeType::Rule, distinct color)
+ *   - Edge per (antecedent → derived) and (rule → derived)
+ *   - Hyperedge per rule application grouping rule + antecedents +
+ *     produced fact
+ */
+export declare function fetchOsfkbDerivation(client: OsfkbClientOptions, body?: {
+    max_iterations?: number;
+    include_aggregates?: boolean;
+    focus_term_ids?: string[];
+}): Promise<OsfkbVisualizationResponse>;
+/** Fetch residuation state diagram for visual overlay (witness state). */
+export declare function fetchOsfkbResiduation(client: OsfkbClientOptions, body?: any): Promise<any>;
+/** Fetch a single term to get its current witness state (Complete /
+ *  Residuated / NoWitnesses). Used by the demo's witness overlay. */
+export declare function fetchOsfkbTermState(client: OsfkbClientOptions, termId: string): Promise<{
+    state: 'complete' | 'residuated' | 'no_witnesses';
+    term: any;
+}>;
+/** Term-level unification (`⊔`) or anti-unification (`⊓`) — operates
+ *  on Ψ-terms directly (vs. the sort-only `/api/v1/sorts/{glb,lub}`).
+ *  Returns operand1 + operand2 + result as a polygon graph the
+ *  renderer can animate as a merge. */
+export declare function fetchOsfkbUnifyTerms(client: OsfkbClientOptions, body: {
+    term1_id: string;
+    term2_id: string;
+    op?: 'unify' | 'anti_unify';
+}): Promise<OsfkbVisualizationResponse>;
+/** Fetch the LIFE function definitions in the tenant's term store. */
+export declare function fetchOsfkbFunctions(client: OsfkbClientOptions, body?: {
+    name_prefix?: string;
+    limit?: number;
+}): Promise<OsfkbVisualizationResponse>;
+/** Diff two MVCC branches of the tenant's term store. */
+export declare function fetchOsfkbBranchDiff(client: OsfkbClientOptions, body: {
+    branch_a: string;
+    branch_b: string;
+    limit?: number;
+}): Promise<OsfkbVisualizationResponse>;
+/** Issue an OSFQL query and return the result Ψ-term set wrapped in
+ *  a visualization-friendly shape (`{graph: VisualizationGraph}`).
+ *  When the OSFQL endpoint returns a flat term list, this helper
+ *  fetches each one's hypergraph and concatenates the results. */
+export declare function fetchOsfkbOsfqlAsGraph(client: OsfkbClientOptions, query: string): Promise<OsfkbVisualizationResponse>;
+/** Fuzzy unification on two Ψ-terms — returns a membership grade
+ *  ∈ [0, 1]. Used by the demo to render the merge polygon with
+ *  opacity = grade. */
+export declare function fetchOsfkbFuzzyUnify(client: OsfkbClientOptions, body: {
+    term1_id: string;
+    term2_id: string;
+}): Promise<{
+    grade: number;
+    result_term_id?: string;
+    bindings?: any[];
+}>;
+/** Fetch the graded-poset projection of the sort hierarchy. */
+export declare function fetchOsfkbGradedPoset(client: OsfkbClientOptions, body?: {
+    include_lower_adjacencies?: boolean;
+    include_upper_adjacencies?: boolean;
+    /** Page size; 0 = unlimited. Default 500 server-side. */
+    limit?: number;
+    /** Page offset. */
+    offset?: number;
+}): Promise<OsfkbVisualizationResponse>;
+/**
+ * Walk every page of the graded-poset endpoint and merge into a
+ * single response. Dedupes nodes/edges by id (UUID-derived).
+ *
+ * Optional `onPage(partial)` callback fires after each page is
+ * accumulated — lets the UI render incrementally.
+ */
+export declare function fetchOsfkbGradedPosetAll(client: OsfkbClientOptions, body?: {
+    include_lower_adjacencies?: boolean;
+    include_upper_adjacencies?: boolean;
+}, pageSize?: number, onProgress?: (loaded: number, total: number) => void, onPage?: (partial: OsfkbVisualizationResponse) => void | Promise<void>): Promise<OsfkbVisualizationResponse>;
+/**
+ * Fetch an N-hop neighborhood around a focus sort. Designed for
+ * tenants with millions of sorts — instead of trying to load the
+ * entire lattice, the client picks a focus and asks for a bounded
+ * subgraph. Returns at most `max_nodes` (default 5000); when the
+ * BFS reaches more than that, the response sets `truncated: true`.
+ */
+export declare function fetchOsfkbSortNeighborhood(client: OsfkbClientOptions, body: {
+    sort_id: string;
+    hops?: number;
+    max_nodes?: number;
+    include_ancestors?: boolean;
+    include_descendants?: boolean;
+    include_siblings?: boolean;
+}): Promise<OsfkbVisualizationResponse & {
+    truncated?: boolean;
+    reachable_count?: number;
+    emitted_count?: number;
+}>;
+/** Subscribe to the forward-chain SSE stream and call onStep for each
+ *  derivation event. Returns an EventSource handle so the caller can
+ *  close() when done. */
+export declare function subscribeOsfkbDerivationStream(client: OsfkbClientOptions, onStep: (step: {
+    iteration: number;
+    rule_id: string;
+    derived_fact: string;
+    antecedents: string[];
+}) => void, onError?: (err: any) => void): EventSource;
+/** Fetch GLB / LUB of two sorts — used by the unify visual diff
+ *  to compute the join of two selected term sorts in the lattice. */
+export declare function fetchOsfkbGlbLub(client: OsfkbClientOptions, op: 'glb' | 'lub', sortIds: string[]): Promise<any>;

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

@@ -0,0 +1,40 @@
+/**
+ * Hit-testing helpers for hypergraph interaction.
+ *
+ * Given a screen-space mouse position, return the topmost hyperedge or
+ * vertex under the pointer. The renderer paints hyperedges in iteration
+ * order, so the *last* matching hyperedge is the visual top.
+ */
+import type { Hypergraph } from '../Hypergraph';
+import type { HypergraphId, Vec2 } from '../types';
+export interface HitTestState {
+    H: Hypergraph;
+    positions: Map<HypergraphId, Vec2>;
+    dualPositions?: Map<HypergraphId, Vec2>;
+    showVertices: boolean;
+    vertexRadius: number;
+    /** 'primal' | 'dual' | 'both' — which set of polygons to hit-test. */
+    view: 'primal' | 'dual' | 'both';
+}
+export interface HitResult {
+    hyperedge: HypergraphId | null;
+    /** When `view` is 'dual' or 'both', a hit may be a *dual hyperedge*
+     *  (which corresponds to a primal vertex). We expose it as `dualOf` so
+     *  callers can treat it as either a vertex hit or a dual-polygon hit. */
+    dualOf: HypergraphId | null;
+    vertex: HypergraphId | null;
+}
+/**
+ * Hit-test against polygons + vertex dots in z-order (last drawn wins).
+ *
+ * Returns the topmost hit. Caller decides whether to prioritize vertex
+ * or polygon — this function returns all three, with `vertex` set when
+ * the cursor is within `vertexRadius` of any vertex (vertices draw on
+ * top of polygons in our renderer).
+ */
+export declare function hitTest(state: HitTestState, worldX: number, worldY: number, zoom: number): HitResult;
+/**
+ * Convert screen position to world (graph) coordinates using Nodus's
+ * camera.
+ */
+export declare function screenToWorld(nodus: any, x: number, y: number): Vec2;

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

@@ -0,0 +1,50 @@
+/**
+ * Canvas overlay polygon renderer for hypergraphs.
+ *
+ * Draws each hyperedge as a filled convex polygon whose corners are the
+ * incident-vertex positions, sorted CCW around the centroid. Renderer-
+ * agnostic: this works above any Nodus host renderer (Canvas / WebGL /
+ * WebGPU) because Nodus's `Layers.render()` (`src/internals/Layers.ts`)
+ * applies the camera world-to-screen transform inside the layer's own
+ * canvas regardless of which renderer is drawing the underlying graph.
+ */
+import type { Hypergraph } from '../Hypergraph';
+import type { HypergraphId, HypergraphRenderOptions, Vec2 } from '../types';
+export interface PolygonRenderState {
+    H: Hypergraph;
+    positions: Map<HypergraphId, Vec2>;
+    /** Optional dual positions; when provided the dual layer can render. */
+    dualPositions?: Map<HypergraphId, Vec2>;
+    options: Required<Omit<HypergraphRenderOptions, 'palette'>> & {
+        palette: HypergraphRenderOptions['palette'];
+    };
+    /** Currently-hovered primal hyperedge id. */
+    hoveredHyperedge?: HypergraphId | null;
+    /** Hovered dual hyperedge (corresponds to a primal vertex). */
+    hoveredDualOf?: HypergraphId | null;
+    /** Currently-hovered vertex id. */
+    hoveredVertex?: HypergraphId | null;
+    /** Selection sets. */
+    selectedHyperedges?: Set<HypergraphId>;
+    selectedVertices?: Set<HypergraphId>;
+}
+export declare function applyDefaults(opts?: HypergraphRenderOptions): PolygonRenderState['options'];
+/**
+ * Oblique-projection 2.5D mapping. Treats every polygon as living on a
+ * horizontal slab at z = level × levelSpacing, then projects to screen
+ * space with a constant tilt so multiple slabs are visible without a
+ * full 3D camera. The optimizer remains 2D — only the renderer changes.
+ *
+ * The mapping is `(x, y, level) → (x + tilt_x · level, y − tilt_y ·
+ * level)` with `tilt_y = sin(angle) × levelSpacing` and a small
+ * x-offset proportional to level for parallax. This produces a
+ * topographic-map view that reads as "depth-1 sorts are nearer
+ * camera, depth-N sorts are further away".
+ */
+export declare function project25D(pos: Vec2, level: number, levelSpacing: number, tilt: number): Vec2;
+/**
+ * Build the canvas draw function. Calls `stateProvider()` on every
+ * frame so the draw fn always sees the latest positions (the optimizer
+ * replaces the position map by reference once it finishes).
+ */
+export declare function createPolygonDraw(nodus: any, stateProvider: () => PolygonRenderState): (ctx: CanvasRenderingContext2D) => void;

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

@@ -0,0 +1,7 @@
+/**
+ * SVG-layer polygon renderer for hypergraphs (parallel path to the
+ * Canvas renderer). Used when the host Nodus renderer is SVG, or when
+ * the user explicitly requests `layer: 'svg'` for export.
+ */
+import type { PolygonRenderState } from './PolygonRenderer';
+export declare function createSVGDraw(stateProvider: () => PolygonRenderState): (root: SVGElement) => void;

package/types/hypergraph/types.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Public types for the hypergraph subsystem.
+ * Implements the data model from Oliver et al., "Scalable Hypergraph
+ * Visualization" (TVCG 2023, arXiv:2308.05043).
+ */
+export type HypergraphId = string | number;
+export interface HypergraphVertex<VData = any> {
+    id: HypergraphId;
+    /** When set, binds this vertex to an existing Nodus node so positions track. */
+    nodeId?: any;
+    data?: VData;
+}
+export interface HypergraphHyperedge<EData = any> {
+    id: HypergraphId;
+    /** Vertex ids that this hyperedge is incident to. Cardinality = vertices.length. */
+    vertices: HypergraphId[];
+    data?: EData;
+}
+export interface HypergraphData<VData = any, EData = any> {
+    vertices: HypergraphVertex<VData>[];
+    hyperedges: HypergraphHyperedge<EData>[];
+}
+export type ForbiddenSubgraphKind = '3a2' | '2a3' | 'strangledV' | 'strangledE';
+export interface ForbiddenSubgraph {
+    kind: ForbiddenSubgraphKind;
+    vertices: HypergraphId[];
+    hyperedges: HypergraphId[];
+}
+export type AtomicOperationKind = 'vertexRemoval' | 'hyperedgeRemoval' | 'vertexMerger' | 'hyperedgeMerger';
+/** Record produced by the simplifier and consumed by the reverser. */
+export interface AtomicOperationRecord {
+    kind: AtomicOperationKind;
+    /** Vertex(es) operated on. For removal: [removed]. For merger: [retained, removed]. */
+    vertices: HypergraphId[];
+    /** Hyperedges operated on. Same convention as vertices. */
+    hyperedges: HypergraphId[];
+    /** Footprint at apply time: V_O ∪ V_v ∪ ... — used for local reversal. */
+    footprintVertices: HypergraphId[];
+    footprintHyperedges: HypergraphId[];
+    /** Snapshot needed to restore (e.g. for vertex merger: which hyperedges contained the removed vertex). */
+    snapshot?: any;
+}
+export interface SimplificationOptions {
+    /** Priority weights from paper Eq. (1). */
+    alpha?: number;
+    beta?: number;
+    gamma?: number;
+    /** Power t in adjacency factor Adj_t. Paper recommends t = 2. */
+    adjacencyT?: number;
+    maxScales?: number;
+    /** Termination criterion (paper §5.1):
+     *  - 'linear': stop once H is linear (every pair of hyperedges shares ≤1 vertex)
+     *  - 'noForbidden': stop once linear AND no forbidden sub-hypergraphs remain (default)
+     *  - 'targetVertices': stop when |V(H)| ≤ targetVertexCount
+     *  - 'targetHyperedges': stop when |E(H)| ≤ targetHyperedgeCount
+     *  - 'manual': run until queue exhausts or maxScales reached */
+    stopWhen?: 'linear' | 'noForbidden' | 'targetVertices' | 'targetHyperedges' | 'manual';
+    /** Lower-bound vertex count when stopWhen = 'targetVertices'. */
+    targetVertexCount?: number;
+    /** Lower-bound hyperedge count when stopWhen = 'targetHyperedges'. */
+    targetHyperedgeCount?: number;
+    forbiddenSubgraphs?: ForbiddenSubgraphKind[];
+    /** Recompute betweenness every K ops. 0 = compute once on H_0 only
+     *  (paper-faithful). Default 0. */
+    betweennessRefreshEvery?: number;
+}
+export interface LayoutWeights {
+    regularity: number;
+    area: number;
+    separation: number;
+    intersection: number;
+    coordination: number;
+}
+export interface LayoutOptions {
+    weights?: Partial<LayoutWeights>;
+    separationIters?: number;
+    regularityIters?: number;
+    solver?: 'lbfgs' | 'adam';
+    /** Whether to optimize the dual hypergraph simultaneously (paper-faithful). */
+    optimizeDual?: boolean;
+    /** Map from hyperedge cardinality to target polygon area. Default k → 80·k.
+     *  This option is dropped silently when running in a worker (functions
+     *  can't cross postMessage); pass `useWorker: false` to honor it. */
+    targetAreaPerCardinality?: (k: number) => number;
+    /** Buffer distance d_b in separation energy. Default 10. */
+    bufferDistance?: number;
+    /** Run the L-BFGS optimization in a Web Worker so the main thread
+     *  stays interactive. Default true. Falls back to inline execution
+     *  when Workers are unavailable or when a worker run errors out. */
+    useWorker?: boolean;
+    /** Throttle the worker → main progress stream — emit one event per N
+     *  L-BFGS iterations to avoid saturating postMessage. Default 25. */
+    progressEvery?: number;
+    onProgress?: (info: LayoutProgress) => void;
+}
+export interface LayoutProgress {
+    scale: number;
+    phase: 'separation' | 'regularity' | 'reversal';
+    iter: number;
+    energy: number;
+}
+export interface HypergraphRenderOptions {
+    fillOpacity?: number;
+    strokeOpacity?: number;
+    /** Either an array (cycled by index) or a function of the hyperedge. */
+    palette?: string[] | ((he: HypergraphHyperedge, index: number) => string);
+    showVertices?: boolean;
+    showIncidenceEdges?: boolean;
+    /** Layer position relative to Nodus's main render layer. */
+    position?: 'below' | 'above';
+    layer?: 'canvas' | 'svg';
+    view?: 'primal' | 'dual' | 'both' | '2.5d';
+    /** When `view === '2.5d'`, returns the lattice depth of a vertex
+     *  (root = 0, deeper = larger). Each polygon is rendered on a slab
+     *  whose z-elevation is `level * levelSpacing`, projected obliquely
+     *  to 2D screen space. Defaults to reading `vertex.data?.level`,
+     *  `vertex.data?.osfkb?.level`, or 0. */
+    levelOf?: (v: HypergraphVertex) => number;
+    /** World-space spacing between successive 2.5D levels. Default 200. */
+    levelSpacing?: number;
+    /** Oblique-projection tilt angle (radians). 0 = flat 2D, π/2 =
+     *  side-on. Default π/6 (30°) — a topographic-map look. Only used
+     *  when `view === '2.5d'`. */
+    obliqueTilt?: number;
+    /** Pixel-radius of the vertex dots when showVertices is true. */
+    vertexRadius?: number;
+    /** Multiplier on fill opacity for the hovered polygon. Default 2.2 (capped at 1). */
+    hoverFillOpacityScale?: number;
+    /** Stroke width (in CSS pixels) for the hovered polygon. Default 3. */
+    hoverStrokeWidth?: number;
+    /** Stroke color for selected polygons (CSS color). Default '#fbbf24'. */
+    selectionStrokeColor?: string;
+    /** Stroke width (CSS pixels) for selected polygons. Default 3. */
+    selectionStrokeWidth?: number;
+    /** Dash pattern for selected polygon outline. Default [6, 4]. */
+    selectionDash?: number[];
+    /** Whether mouse hover/click events are enabled. Default true. */
+    interactive?: boolean;
+    /** Optional per-hyperedge opacity multiplier (returns 0..1). When
+     *  provided, the polygon renderer scales `fillOpacity` by this
+     *  value — used by the provenance / certainty overlay so polygons
+     *  fade with their semiring tag. */
+    hyperedgeOpacity?: (he: HypergraphHyperedge) => number;
+    /** Per-vertex tag string. When provided + truthy, the renderer
+     *  draws a small label badge at the vertex position. Used for
+     *  Aït-Kaci coreference X-tags. */
+    vertexTag?: (v: HypergraphVertex) => string | null | undefined;
+}
+export interface InteractionEvent {
+    /** Hyperedge id under cursor, if any. */
+    hyperedge: HypergraphId | null;
+    /** Primal-vertex id when the dual polygon was hit (its dual is a hyperedge in H'). */
+    dualOf: HypergraphId | null;
+    /** Vertex id under cursor (vertex dots take priority over polygons). */
+    vertex: HypergraphId | null;
+    /** World-space cursor position. */
+    world: Vec2;
+    /** Original DOM mouse event, if available. */
+    domEvent?: MouseEvent;
+}
+export interface QualityMetrics {
+    overlapCount: number;
+    overlapArea: number;
+    avgRegularity: number;
+    forbiddenSubgraphCount: number;
+}
+export interface Vec2 {
+    x: number;
+    y: number;
+}

package/types/index.d.ts

@@ -0,0 +1,21 @@
+import './internals/wasmInit';
+export { Nodus } from './Nodus';
+export { WasmGraphRenderer } from './renderers/WasmGraphRenderer';
+export { WasmRendererAdapter } from './renderers/WasmRendererAdapter';
+/** WebGPU capability check (the Rust/wgpu renderer prefers WebGPU, falls back to WebGL2). */
+export declare const isWebGpuSupported: () => boolean;
+export { Node } from './core/Node';
+export { Edge } from './core/Edge';
+export { NodeList } from './core/NodeList';
+export { EdgeList } from './core/EdgeList';
+export { Transformation } from './core/Transformation';
+export { StyleRule, StyleClass } from './modules/StylesAPI';
+export { NonObjectPropertyWatcher, ObjectPropertyWatcher } from './modules/SchemaAPI';
+export { BoundingBox } from './geometry/BoundingBox';
+export * as hypergraph from './hypergraph/index';
+export type { HypergraphData, HypergraphVertex, HypergraphHyperedge, HypergraphId, HypergraphRenderOptions, InteractionEvent, SimplificationOptions, LayoutOptions, LayoutWeights, LayoutProgress, QualityMetrics, AtomicOperationKind, AtomicOperationRecord, ForbiddenSubgraph, ForbiddenSubgraphKind, } from './hypergraph/types';
+export * as geometry from './geometry/index';
+export * as parse from './modules/ParseAPI';
+export { radialFactory, forceFactory, forceLinkFactory, gridFactory, hierarchicalFactory, sequentialFactory, concentricFactory, } from './modules/LayoutsAPI';
+export { enableWasmBackend, configureBackends, useWasm, type Subsystem, type Backend } from './internals/wasmBackend';
+export { Nodus as default } from './Nodus';

package/types/internals/Algorithms.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Algorithms — graph algorithms: shortest path, cycle detection, MST, BFS, DFS, betweenness.
+ * Faithfully translated from /tmp/nodus_extracted/Algorithms.js
+ */
+import { Module } from './Module';
+export declare class Algorithms extends Module {
+    private _nodeList;
+    private _edgeList;
+    private _sourceList;
+    private _targetList;
+    private _excludedList;
+    private _virtualList;
+    onMounted(): void;
+    shortestPath(opts?: {
+        source?: any;
+        target?: any;
+        directed?: boolean;
+        edges?: any;
+        nodes?: any;
+        edgeCostFunction?: (edge: any) => number;
+        heuristicFunction?: (node: any, target: any) => number;
+    }): Promise<any>;
+    private _constructPath;
+    /**
+     * Whole-graph unit-cost shortest path via the Rust GraphCore A* (byte-exact with the TS A* —
+     * see shortest-path-exact-parity). Snapshots the live graph into a GraphCore (live element
+     * indexes used as ids, added in the live node/edge order so the adjacency — and thus the
+     * PrioritySet tie-break — matches), runs the Rust A*, then maps the gc indexes back to live
+     * indexes and builds the same { nodes, edges } NodeList/EdgeList result as _constructPath.
+     */
+    private _pathCore;
+    private _pathCoreKey;
+    /**
+     * The WHOLE-graph GraphCore, cached + rebuilt only when the node/edge Storage version changes
+     * (a structural mutation). Eliminates the O(V+E) per-call rebuild for repeated pathfinding on
+     * a static graph. Built from the live node/edge `_indexes` order so the adjacency (and the
+     * PrioritySet tie-break) is byte-exact. Safe because shortestPath's wasm guard only fires for
+     * the whole graph (no node/edge subgraph).
+     */
+    private _wholeGraphCore;
+    private _shortestPathWasm;
+    detectCycle(nodes: any, edges: any): any;
+    /** Directed cycle detection via the Rust GraphCore (byte-exact with detectCyclesDirected). */
+    private _detectCycleWasm;
+    getAllSimpleCycles(nodes: any, edges: any): any[];
+    /** All simple cycles via the Rust GraphCore (byte-exact with CyclesFinder, discovery order). */
+    private _allSimpleCyclesWasm;
+    minimumSpanningTree(nodes: any, edges: any, weightFn?: (edge: any) => number): any[];
+    bfs({ root, onNode, onEdge, directed }: {
+        root: any;
+        onNode: (n: any) => boolean | void;
+        onEdge?: (e: any) => boolean | void;
+        directed?: boolean;
+    }): void;
+    dfs({ root, onNode, onEdge, directed }: {
+        root: any;
+        onNode: (n: any) => boolean | void;
+        onEdge?: (e: any) => boolean | void;
+        directed?: boolean;
+    }): void;
+    betweenness({ nodes, edges, directed, normalized }: {
+        nodes: any;
+        edges: any;
+        directed: boolean;
+        normalized: boolean;
+    }): any;
+    fishEyeExpand(nodes: any, _edges: any, k: number, opts: any): any;
+}