@kortexya/nodus 0.1.0

package/types/algorithms/force-gpu/kernels/index.d.ts

@@ -0,0 +1,176 @@
+import { type GpuTexture } from '../webgl/helpers';
+import { type AtlasSlot, type SimItem, type SimLayout } from '../ParticleSystem';
+export interface KernelHandle {
+    step: (...args: any[]) => void;
+    outputs: any;
+    destroy: () => void;
+}
+interface AabbInput {
+    items: {
+        N: number;
+        pointsSlot: AtlasSlot;
+    }[];
+    texture: {
+        points: () => GpuTexture;
+    };
+}
+interface AabbOutput {
+    items: {
+        spatialBoundariesSlot: AtlasSlot;
+    }[];
+    texture: {
+        spatialBoundaries: () => GpuTexture;
+    };
+}
+export declare function makeAabbKernel(gl: WebGL2RenderingContext, input: AabbInput): KernelHandle & {
+    outputs: AabbOutput;
+};
+interface MortonInput {
+    items: (SimItem & {
+        depth: number;
+        N: number;
+    })[];
+    texture: {
+        points: () => GpuTexture;
+        spatialBoundaries: () => GpuTexture;
+    };
+}
+interface MortonOutput {
+    items: {
+        N: number;
+        spatialKeysSlot: AtlasSlot;
+    }[];
+    texture: {
+        spatialKeys: () => GpuTexture;
+    };
+}
+export declare function makeMortonKernel(gl: WebGL2RenderingContext, input: MortonInput): KernelHandle & {
+    outputs: MortonOutput;
+};
+interface SortKeysInput {
+    items: {
+        N: number;
+        spatialKeysSlot: AtlasSlot;
+    }[];
+    texture: {
+        spatialKeys: () => GpuTexture;
+    };
+}
+interface SortOutput {
+    items: {
+        N: number;
+        spatialKeysSlot: AtlasSlot;
+    }[];
+    texture: {
+        spatialKeys: () => GpuTexture;
+    };
+}
+export declare function makeSortKeysKernel(gl: WebGL2RenderingContext, input: SortKeysInput): KernelHandle & {
+    outputs: SortOutput;
+};
+export declare function makeSortIntervalsKernel(gl: WebGL2RenderingContext, input: SortKeysInput): KernelHandle & {
+    outputs: SortOutput;
+};
+interface CellLookupInput {
+    items: (SimItem & {
+        depth: number;
+        order: number;
+        N: number;
+        spatialKeysSlot: AtlasSlot;
+        spatialBoundariesSlot: AtlasSlot;
+    })[];
+    texture: {
+        spatialKeys: () => GpuTexture;
+        spatialBoundaries: () => GpuTexture;
+        points?: () => GpuTexture;
+    };
+}
+interface CellLookupOutput {
+    items: (SimItem & {
+        depth: number;
+        order: number;
+        N: number;
+        spatialKeysSlot: AtlasSlot;
+        spatialBoundariesSlot: AtlasSlot;
+        gridCellsSlot: AtlasSlot;
+    })[];
+    texture: {
+        spatialKeys: () => GpuTexture;
+        spatialBoundaries: () => GpuTexture;
+        gridCells: () => GpuTexture;
+        points?: () => GpuTexture;
+    };
+}
+export declare function makeCellLookupKernel(gl: WebGL2RenderingContext, input: CellLookupInput): KernelHandle & {
+    outputs: CellLookupOutput;
+};
+interface BhTranslateInput extends CellLookupOutput {
+}
+interface BhTranslateItem {
+    order: number;
+    depth: number;
+    multipolesSlot: {
+        [level: number]: AtlasSlot;
+    };
+}
+interface BhTranslateOutput {
+    items: BhTranslateItem[];
+    texture: {
+        multipoles: (level: number, ch: number) => GpuTexture | undefined;
+    };
+}
+export declare function makeBhTranslateKernel(gl: WebGL2RenderingContext, input: BhTranslateInput & {
+    items: (BhTranslateInput['items'][number] & {
+        order: number;
+    })[];
+}): KernelHandle & {
+    outputs: BhTranslateOutput;
+};
+interface BhExpandInput extends BhTranslateOutput {
+    items: (BhTranslateItem & SimItem)[];
+}
+interface BhExpandOutput {
+    items: (BhTranslateItem & SimItem & {
+        localExpansionsSlot: {
+            [l: number]: AtlasSlot;
+        };
+    })[];
+    texture: {
+        localExpansions: (level: number, ch: number) => GpuTexture | undefined;
+    };
+}
+export declare function makeBhExpandKernel(gl: WebGL2RenderingContext, input: BhExpandInput): KernelHandle & {
+    outputs: BhExpandOutput;
+};
+export interface IntegrateOptions {
+    charge: number;
+    gravity: number;
+    inertia: number;
+    edgeStrength: number;
+    edgeLength: number;
+    elasticity: number;
+    margin: number;
+    maxDisplacement: number;
+}
+interface IntegrateInput {
+    items: any[];
+    texture: SimLayout['texture'] & {
+        spatialBoundaries: () => GpuTexture;
+        spatialKeys: () => GpuTexture;
+        gridCells: () => GpuTexture;
+        localExpansions: (level: number, ch: number) => GpuTexture | undefined;
+    };
+}
+interface IntegrateOutput {
+    items: {
+        N: number;
+        pointsSlot: AtlasSlot;
+    }[];
+    texture: {
+        points: () => GpuTexture;
+    };
+}
+export declare function makeIntegrateKernel(gl: WebGL2RenderingContext, input: IntegrateInput, opts: IntegrateOptions): KernelHandle & {
+    outputs: IntegrateOutput;
+};
+export {};

package/types/algorithms/force-gpu/kernels/utils.d.ts

@@ -0,0 +1,31 @@
+import { createFramebuffer, type GpuTexture } from '../webgl/helpers';
+export declare const aabbDepth: (n: number) => number;
+export declare const nextPow2: (n: number) => number;
+export declare const logCeil: (n: number) => number;
+export declare function splitPow2(n: number): [number, number];
+export declare const triCount: (n: number) => number;
+export declare const emptySlot: () => {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export declare function once<T>(start: () => Promise<T>): () => Promise<T>;
+export declare const bhDepth: (n: number) => number;
+export declare const batchSize: (n: number, lo?: number, hi?: number) => number;
+export declare const coolingAlpha: (e: number, t: number) => number;
+export declare function initSortPairs(arr: Uint32Array): Uint32Array;
+export declare function createKeyTexture(gl: WebGL2RenderingContext, [w, h]: [number, number]): GpuTexture;
+export declare function createIntervalTexture(gl: WebGL2RenderingContext, [w, h]: [number, number]): GpuTexture;
+export declare function createFramebuffer2(gl: WebGL2RenderingContext, ca0: GpuTexture, ca1: GpuTexture): {
+    handle: WebGLFramebuffer;
+    ca0: GpuTexture;
+    ca1: GpuTexture;
+};
+export interface AnimationLoop {
+    start: () => Promise<void>;
+    step: () => boolean | undefined;
+    stop: () => void;
+}
+export declare function createAnimationLoop(batch: number, step: (i: number) => boolean): AnimationLoop;
+export { createFramebuffer };

package/types/algorithms/force-gpu/shaders/aabb.d.ts

@@ -0,0 +1,2 @@
+import type { ShaderPair } from './types';
+export declare const aabbShader: ShaderPair;

package/types/algorithms/force-gpu/shaders/bhExpand.d.ts

@@ -0,0 +1,2 @@
+import type { ShaderPair } from './types';
+export declare const bhExpandShader: ShaderPair;

package/types/algorithms/force-gpu/shaders/bhTranslate.d.ts

@@ -0,0 +1,2 @@
+import type { ShaderPair } from './types';
+export declare const bhTranslateShader: ShaderPair;

package/types/algorithms/force-gpu/shaders/cellLookup.d.ts

@@ -0,0 +1,2 @@
+import type { ShaderPair } from './types';
+export declare const cellLookupShader: ShaderPair;

package/types/algorithms/force-gpu/shaders/index.d.ts

@@ -0,0 +1,9 @@
+export type { ShaderPair } from './types';
+export { integrateShader } from './integrate';
+export { bhExpandShader } from './bhExpand';
+export { bhTranslateShader } from './bhTranslate';
+export { cellLookupShader } from './cellLookup';
+export { sortKeysShader } from './sortKeys';
+export { sortIntervalsShader } from './sortIntervals';
+export { mortonShader } from './morton';
+export { aabbShader } from './aabb';

package/types/algorithms/force-gpu/shaders/integrate.d.ts

@@ -0,0 +1,2 @@
+import type { ShaderPair } from './types';
+export declare const integrateShader: ShaderPair;

package/types/algorithms/force-gpu/shaders/morton.d.ts

@@ -0,0 +1,2 @@
+import type { ShaderPair } from './types';
+export declare const mortonShader: ShaderPair;

package/types/algorithms/force-gpu/shaders/sortIntervals.d.ts

@@ -0,0 +1,2 @@
+import type { ShaderPair } from './types';
+export declare const sortIntervalsShader: ShaderPair;

package/types/algorithms/force-gpu/shaders/sortKeys.d.ts

@@ -0,0 +1,2 @@
+import type { ShaderPair } from './types';
+export declare const sortKeysShader: ShaderPair;

package/types/algorithms/force-gpu/shaders/types.d.ts

@@ -0,0 +1,10 @@
+export interface ShaderPair {
+    /** vertex shader source — `#version 300 es`, one instance per slot. */
+    vert: string;
+    /** fragment shader source — performs the per-pixel computation. */
+    frag: string;
+    /** descriptive name for debugging / pipeline registry. */
+    name: string;
+    /** number of color attachments the fragment shader writes. */
+    outputs: number;
+}

package/types/algorithms/force-gpu/webgl/helpers.d.ts

@@ -0,0 +1,24 @@
+export declare const QUAD_VERTICES: Float32Array<ArrayBuffer>;
+export declare function uniformSetterName(): {
+    readonly [type: number]: string;
+};
+export declare function compileShader(gl: WebGL2RenderingContext, type: GLenum, source: string): WebGLShader;
+export declare function createProgram(gl: WebGL2RenderingContext, vsSource: string, fsSource: string): WebGLProgram;
+export interface GpuTexture {
+    size: [number, number];
+    data: ArrayBufferView | null;
+    type: GLenum;
+    format: GLenum;
+    handle: WebGLTexture;
+}
+export interface CreateTextureOpts {
+    size: [number, number];
+    data: ArrayBufferView | null;
+    type: GLenum;
+    internalFormat?: GLenum;
+    format?: GLenum;
+}
+export declare function createFloatTexture(gl: WebGL2RenderingContext, opts: CreateTextureOpts): GpuTexture;
+export declare function createFramebuffer(gl: WebGL2RenderingContext, texture: WebGLTexture): WebGLFramebuffer;
+export declare function createBuffer(gl: WebGL2RenderingContext, data?: BufferSource): WebGLBuffer;
+export declare function makePingPong<A, B>(a: A, b: B): () => [A | B, A | B];

package/types/algorithms/force-gpu/webgl/index.d.ts

@@ -0,0 +1,4 @@
+export { QUAD_VERTICES, uniformSetterName, compileShader, createProgram, createFloatTexture, createFramebuffer, createBuffer, makePingPong, } from './helpers';
+export type { GpuTexture, CreateTextureOpts } from './helpers';
+export { introspectProgram, bindUniforms, } from './program';
+export type { UniformInfo, UniformTable } from './program';

package/types/algorithms/force-gpu/webgl/program.d.ts

@@ -0,0 +1,15 @@
+export interface UniformInfo {
+    size: number;
+    data: any;
+    type: GLenum;
+    location: WebGLUniformLocation;
+}
+export type UniformTable = {
+    [name: string]: UniformInfo;
+};
+export declare function introspectProgram(gl: WebGL2RenderingContext, program: WebGLProgram, defaults: {
+    [name: string]: any;
+}): UniformTable;
+export declare function bindUniforms(gl: WebGL2RenderingContext, table: UniformTable, overrides?: {
+    [name: string]: any;
+}): void;

package/types/algorithms/forceFactory.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Force layout factory.
+ *
+ * Wraps the force simulation (Barnes-Hut / GPU-accelerated) as a layout
+ * descriptor that can be registered with `modules.layouts`.
+ *
+ * The factory returns `(opts?) => Promise<any>` — calling it starts the
+ * layout and resolves when it converges or is stopped.
+ */
+/** Nodus instance (subset of the public API used here). */
+interface Nodus {
+    modules: {
+        layouts: {
+            register(descriptor: LayoutDescriptor): void;
+            start(name: string, opts: any): Promise<any>;
+        };
+        graph: any;
+        locate: any;
+        camera: any;
+    };
+    layouts: {
+        force: (opts?: any) => Promise<any>;
+    };
+    getNodes(ids?: any): any;
+}
+/** Layout descriptor registered with the layout system. */
+interface LayoutDescriptor {
+    name: string;
+    imports?: Record<string, any>;
+    configure(opts: any, modules: any): any;
+    context?(): any;
+    update(msg: any, context: any): any;
+    stop(context: any): void;
+    isRunning(context: any): boolean;
+    onSync(msg: any, modules?: any, running?: boolean): any;
+}
+/** Strip non-transferable (function) properties from an options object. */
+declare function ensureTransferable<T extends Record<string, any>>(opts: T): T;
+/**
+ * The layout descriptor that the layout system runs in a worker (or
+ * on the main thread when `useWebWorker` is false / GPU mode).
+ */
+declare const forceDescriptor: LayoutDescriptor;
+/**
+ * Handle the `incremental` option: run the layout on a subgraph and place
+ * it relative to the existing nodes.
+ */
+declare function incrementalLayout(opts: any, nodus: any, layoutFn: (o: any) => Promise<any>): Promise<any>;
+/**
+ * Create and register the force layout on an Nodus instance.
+ *
+ * @returns A function `(opts?) => Promise<any>` that starts the layout.
+ */
+export default function forceFactory(nodus: Nodus): (opts?: any) => Promise<any>;
+export { forceDescriptor, incrementalLayout, ensureTransferable };

package/types/algorithms/forceLinkFactory.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ForceLink layout factory.
+ *
+ * Wraps the ForceAtlas2-style force-directed layout as a layout descriptor.
+ * This layout uses a Barnes-Hut approximation for repulsion, adaptive
+ * speed control, and optional sibling alignment.
+ *
+ * Unlike the basic force layout, forceLink operates on a flat byte-array
+ * representation of the graph (`NodeMatrix` / `EdgeMatrix`) and runs its
+ * own convergence loop.
+ */
+interface Nodus {
+    modules: {
+        layouts: {
+            register(descriptor: LayoutDescriptor): void;
+            start(name: string, opts: any): Promise<any>;
+        };
+        graph: any;
+    };
+    layouts: {
+        forceLink: (opts?: any) => Promise<any>;
+    };
+}
+interface LayoutDescriptor {
+    name: string;
+    configure(opts: any, modules: any): any;
+    context(): any;
+    update(msg: any, context: any): any;
+    stop(context: any): void;
+    isRunning(context: any): boolean;
+    onSync(msg: any, modules: any): any;
+}
+declare const forceLinkDescriptor: LayoutDescriptor;
+/**
+ * Create and register the forceLink layout on an Nodus instance.
+ *
+ * @returns A function `(opts?) => Promise<any>` that starts the layout.
+ */
+export default function forceLinkFactory(nodus: Nodus): (opts?: any) => Promise<any>;
+export { forceLinkDescriptor };

package/types/algorithms/grid/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Grid layout algorithm.
+ *
+ * Arranges nodes in a regular grid pattern with configurable rows,
+ * columns, distances, and optional sorting.
+ */
+export interface GridOptions {
+    rows?: number;
+    cols?: number;
+    sortBy?: string;
+    sortFallbackValue?: any;
+    reverse?: boolean;
+    colDistance?: number;
+    rowDistance?: number;
+}
+export interface GridInput {
+    nodeCount: number;
+    nodeRadii: number[];
+    nodeData?: any[];
+    nodeDegrees?: number[];
+}
+export interface GridResult {
+    x: number[];
+    y: number[];
+}
+export declare function grid(input: GridInput, options?: GridOptions): GridResult;

package/types/algorithms/gridFactory.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Grid layout factory.
+ *
+ * Wraps the grid algorithm as a layout descriptor. The placement compute runs
+ * in Rust (wasm `layout_grid_factory`, byte-exact — grid-concentric-parity.mjs
+ * holds the frozen TS oracle); only configure() extraction and the user-data
+ * sort (V8 comparator semantics) stay TS. wasm is REQUIRED (Phase-5 rule).
+ */
+interface Nodus {
+    modules: {
+        layouts: {
+            register(descriptor: LayoutDescriptor): void;
+            start(name: string, opts: any): Promise<any>;
+        };
+    };
+}
+interface LayoutDescriptor {
+    name: string;
+    configure(opts: any, modules: any): any;
+    update(msg: any): any;
+    onSync(msg: any): any;
+}
+declare const gridDescriptor: LayoutDescriptor;
+/**
+ * Create and register the grid layout on an Nodus instance.
+ *
+ * @returns A function `(opts?) => Promise<any>` that starts the layout.
+ */
+export default function gridFactory(nodus: Nodus): (opts?: any) => Promise<any>;
+export { gridDescriptor };

package/types/algorithms/hierarchical/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Hierarchical (Sugiyama-style) layout algorithm.
+ *
+ * Phases:
+ *  1. Layer assignment (longest-path or user-specified)
+ *  2. Crossing reduction (median sweeps, dev's Et3)
+ *  3. X-coordinate assignment (Brandes-Köpf, dev's ut3 → see ./sugiyama.ts)
+ *  4. Component packing
+ */
+export interface HierarchicalOptions {
+    direction?: 'TB' | 'BT' | 'LR' | 'RL';
+    nodeDistance?: number;
+    levelDistance?: number;
+    componentDistance?: number;
+    gapWidth?: number;
+    roots?: number[];
+    sinks?: number[];
+    compactSiblings?: boolean;
+    siblingsDistance?: number;
+    decross?: boolean;
+    arrangeComponents?: 'fit' | 'grid' | 'singleLine';
+    gridDistance?: number;
+    layer?: string;
+}
+export interface HierarchicalInput {
+    nodeCount: number;
+    sources: number[];
+    targets: number[];
+    nodeRadii: number[];
+    nodeData?: any[];
+    layerField?: string;
+    /** Original node positions (pre-layout). The reference translates the laid-out graph so
+     *  its centroid lands on the ORIGINAL positions' centroid (Z4/Q3); omitted values count
+     *  as 0, so with no positions the layout is centroid-anchored at the origin. */
+    initialX?: ArrayLike<number>;
+    initialY?: ArrayLike<number>;
+    /** Per-node user layer constraints (the reference's data.layer — user `roots` are encoded
+     *  as layer 0 by the factory). undefined/NaN = unconstrained. Presence of ANY numeric
+     *  value switches the component's dag to the reference's synthetic user-layer BFS tree. */
+    nodeLayers?: Array<number | undefined>;
+}
+export interface HierarchicalResult {
+    x: number[];
+    y: number[];
+}
+export declare function referenceComponents(n: number, src: number[], tgt: number[]): number[][];
+export declare function referenceUserLayerTree(comp: number[], eSrc: number[], eTgt: number[], layerOf: (id: number) => number | undefined): {
+    src: number[];
+    tgt: number[];
+} | null;
+export declare function referenceDag(comp: number[], eSrc: number[], eTgt: number[]): {
+    order: number[];
+    childrenOf: Map<number, number[]>;
+};
+export declare function removeCycles(n: number, sources: number[], targets: number[], seedOrder?: number[]): {
+    sources: number[];
+    targets: number[];
+};
+export declare function longestPathLayering(n: number, out: number[][], inc: number[][], _roots: number[], // reference folds user roots into data layers (layer=0) in configure
+sinks: number[], userLayersIn?: ArrayLike<number | undefined>): number[];
+export declare function barycenterSweep(layers: number[][], out: number[][], inc: number[][], layer: number[], iterations: number): void;
+export declare function assignCoordinates(layers: number[][], nodeRadii: number[], nodeDistance: number, levelDistance: number, direction: 'TB' | 'BT' | 'LR' | 'RL', compactSiblings: boolean, siblingsDistance: number, out: number[][], inc: number[][], layer: number[]): {
+    x: number[];
+    y: number[];
+};
+interface PackUnit {
+    nodes: number[];
+    /** grid fake unit: pre-sized box (no bbox/centering pass) */
+    fake?: {
+        w: number;
+        h: number;
+    };
+    w: number;
+    h: number;
+    x: number | undefined;
+    y: number | undefined;
+}
+export declare function packComponents(units: PackUnit[], x: number[], y: number[], radii: number[], componentDistance: number, arrangeComponents: 'fit' | 'grid' | 'singleLine'): void;
+export declare function hierarchical(input: HierarchicalInput, options?: HierarchicalOptions): HierarchicalResult;
+export {};