hypercube-compute 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,321 @@
+declare class TriadeMasterBuffer {
+    readonly buffer: ArrayBuffer;
+    private offset;
+    /**
+     * Alloue un unique bloc de mémoire vive (ArrayBuffer) pour l'ensemble du système.
+     * @param totalBytes Taille totale de la RAM allouée (par défaut 100 MB).
+     */
+    constructor(totalBytes?: number);
+    /**
+     * Alloue les octets nécessaires pour un Cube de 6 Faces en O(1) sans fragmentation.
+     * @param mapSize Résolution (ex: 400x400)
+     * @returns L'offset de départ dans l'ArrayBuffer
+     */
+    allocateCube(mapSize: number, numFaces?: number): number;
+    /** Retourne la quantité de RAM consommée */
+    getUsedMemoryInMB(): string;
+}
+
+/**
+ * Type alias to explicitly signal to AI that this array is a Flat Tensor (1D array simulating 2D/3D).
+ * @AI_RULE DO NOT iterate using functional array methods (map, forEach, reduce). DO NOT use `push` or `splice`.
+ */
+type FlatTensorView = Float32Array;
+/**
+ * Interface fondamentale (Le Contract) pour tout algorithme physique dans Triade Engine.
+ * Implémentée par les moteurs LBM, GameOfLife, SAT.
+ */
+interface ITriadeEngine {
+    /**
+     * @description Exécute un pas de simulation mathématique à l'intérieur d'un TriadeCube.
+     * @param faces Les 6 (ou N) "Views" (FlatTensorView) pointant vers la VRAM continue.
+     * @param mapSize La dimension N (N x N) de ce chunk spatial.
+     *
+     * @AI_RULE CRITICAL_PERFORMANCE: This method runs inside a hot loop (like 60 FPS).
+     * @AI_RULE ZERO_ALLOCATION: DO NOT instantiate any object (`new Object()`, `[]`, `{}`) inside this scope to avoid Garbage Collection.
+     * @AI_RULE MEMORY_ACCESS: Use 1D sequential iterations `for (let i = 0; i < length; i++)`. Read/Write values via `faces[index][i]`. Map 2D coords using `index = y * mapSize + x`.
+     * @AI_RULE ERROR_HANDLING: If generating errors, be highly verbose for self-correction. Example: `throw new Error("[Triade] Out of bounds: index ${i} exceeds size ${length}")`
+     */
+    compute(faces: FlatTensorView[], mapSize: number): void;
+    /**
+     * Identifiant explicite du moteur algorithmique.
+     * @AI_RULE This MUST match the semantic context of the Engine (e.g., 'Navier-Stokes-LBM-D2Q9', 'Game-Of-Life').
+     */
+    get name(): string;
+}
+
+declare class TriadeCubeV2 {
+    readonly mapSize: number;
+    readonly faces: Float32Array[];
+    readonly offset: number;
+    engine: ITriadeEngine | null;
+    /**
+     * @param mapSize La résolution (N x N)
+     * @param masterBuffer L'allocateur de RAM central de l'Orchestrateur
+     */
+    constructor(mapSize: number, masterBuffer: TriadeMasterBuffer, numFaces?: number);
+    /**
+     * Injecte le cerveau mathématique dans ce paquet mémoire.
+     */
+    setEngine(engine: ITriadeEngine): void;
+    /**
+     * Exécute le calcul de la Frame (O1, Wavefront, Automates)
+     */
+    compute(): void;
+    /** Helper pour vider une face spécifique */
+    clearFace(faceIndex: number): void;
+}
+
+/**
+ * Chef d'orchestre de la V2.
+ * Il possède la VRAM globale partagée et gère les instanciations de Cubes sans fragmentation RAM.
+ */
+declare class Triade {
+    private _masterBuffer;
+    cubes: Map<string, TriadeCubeV2>;
+    get masterBuffer(): TriadeMasterBuffer;
+    /**
+     * @param vRamAllocMegabytes Taille du ArrayBuffer en Mega-Octets (par defaut 50MB)
+     */
+    constructor(vRamAllocMegabytes?: number);
+    /**
+     * Forge un nouveau Cube (View Paging) depuis le Buffer Maître.
+     */
+    createCube(name: string, mapSize: number, engine: ITriadeEngine, numFaces?: number): TriadeCubeV2;
+    /**
+     * Accès sécurisé à un cube pour UI/Render logic.
+     */
+    getCube(id: string): TriadeCubeV2 | undefined;
+}
+
+/**
+ * TriadeGrid gère un assemblage N x M de TriadeCubes adjacents.
+ * Il assure la communication "Boundary Exchange" (Ghost Cells) entre les cubes
+ * à la fin de chaque étape de calcul pour unifier la simulation.
+ */
+declare class TriadeGrid {
+    cubes: (TriadeCubeV2 | null)[][];
+    readonly cols: number;
+    readonly rows: number;
+    readonly cubeSize: number;
+    isPeriodic: boolean;
+    constructor(cols: number, rows: number, cubeSize: number, masterBuffer: TriadeMasterBuffer, engineFactory: () => ITriadeEngine, numFaces?: number, isPeriodic?: boolean);
+    /**
+     * Calcule une étape complète de la grille.
+     * 1. Exécute "compute()" sur chaque cube
+     * 2. Synchronise les bords (Boundary Exchange) sur les faces demandées
+     */
+    compute(facesToSynchronize?: number | number[]): void;
+    /**
+     * Recopie les vecteurs périphériques (1 pixel de profondeur) vers les bords des voisins.
+     */
+    private synchronizeBoundaries;
+}
+
+declare class AerodynamicsEngine implements ITriadeEngine {
+    dragScore: number;
+    private initialized;
+    get name(): string;
+    compute(faces: Float32Array[], mapSize: number): void;
+}
+
+declare class EcosystemEngineO1 implements ITriadeEngine {
+    get name(): string;
+    compute(faces: Float32Array[], mapSize: number): void;
+}
+
+declare class GameOfLifeEngine implements ITriadeEngine {
+    get name(): string;
+    compute(faces: Float32Array[], mapSize: number): void;
+}
+
+declare class HeatmapEngine implements ITriadeEngine {
+    readonly name = "Heatmap (O1 Spatial Convolution)";
+    radius: number;
+    weight: number;
+    /**
+     * @param radius Rayon d'influence en cellules
+     * @param weight Coefficient multiplicateur à l'arrivée
+     */
+    constructor(radius?: number, weight?: number);
+    /**
+     * Exécute le Summed Area Table Algorithm (Face 5) suivi
+     * d'un Box Filter O(1) vers la Synthèse (Face 3).
+     */
+    compute(faces: Float32Array[], mapSize: number): void;
+}
+
+declare class CanvasAdapter {
+    /**
+     * Lit un Tenseur Plat (Face de Float32Array) et le peint sur un contexte Canvas Native.
+     * Cette interface sépare la logique de rendu (UI) du moteur mathématique (Triade).
+     */
+    static renderFaceToCanvas(faceData: Float32Array, mapSize: number, ctx: CanvasRenderingContext2D, options?: {
+        colorScheme: 'heat' | 'grayscale';
+        normalizeMax?: number;
+    }): void;
+}
+
+declare class WebGLAdapter {
+    private gl;
+    private texture;
+    private program;
+    readonly mapSize: number;
+    constructor(canvas: HTMLCanvasElement, mapSize: number);
+    /**
+     * Propulse la Face Mémoire Triade directement dans la VRAM GPU.
+     * C'est l'opération la plus rapide sur navigateur (O(1) Data Upload).
+     */
+    renderFaceToWebGL(faceData: Float32Array): void;
+    private createProgram;
+}
+
+interface OceanEngineParams {
+    tau_0: number;
+    smagorinsky: number;
+    cflLimit: number;
+    bioDiffusion: number;
+    bioGrowth: number;
+    vortexRadius: number;
+    vortexStrength: number;
+}
+declare class OceanEngine implements ITriadeEngine {
+    readonly name = "OceanEngine";
+    private readonly w;
+    private readonly cx;
+    private readonly cy;
+    private readonly opp;
+    private feq_cache;
+    private pulled_f;
+    params: OceanEngineParams;
+    stats: {
+        maxU: number;
+        avgTau: number;
+    };
+    interaction: {
+        mouseX: number;
+        mouseY: number;
+        active: boolean;
+    };
+    constructor();
+    /**
+     * Entry point: Orchestrates LBM and Bio steps
+     */
+    compute(faces: Float32Array[], size: number): void;
+    private stepLBM;
+    private stepBio;
+}
+
+interface Boat$1 {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    length: number;
+    angle: number;
+}
+declare class OceanSimulatorAddon {
+    readonly size: number;
+    private master;
+    private cube;
+    private engine;
+    boats: Boat$1[];
+    constructor(size?: number);
+    /**
+     * Engine parameters access
+     */
+    get params(): OceanEngineParams;
+    get stats(): {
+        maxU: number;
+        avgTau: number;
+    };
+    /**
+     * High-level Boat API
+     */
+    addBoat(x: number, y: number, length?: number): void;
+    /**
+     * Global Step: Fluid -> Bio -> Boats
+     */
+    step(): void;
+    /**
+     * Interaction bridge
+     */
+    setInteraction(x: number, y: number, active: boolean): void;
+    /**
+     * Helper to render everything to a canvas
+     */
+    render(ctx: CanvasRenderingContext2D, imageData: ImageData): void;
+    /** Access to raw buffers for custom rendering */
+    getRawFaces(): Float32Array<ArrayBufferLike>[];
+}
+
+declare class OceanWebGLRenderer {
+    private gl;
+    private program;
+    private indexCount;
+    private texRho;
+    private texUx;
+    private texUy;
+    private texObst;
+    private globalW;
+    private globalH;
+    private chunkSize;
+    constructor(canvas: HTMLCanvasElement, cols: number, rows: number, chunkSize: number);
+    private createTexture;
+    private bindTextureUniform;
+    private updateSubTexture;
+    render(grid: TriadeGrid): void;
+    private createProgram;
+}
+
+interface Boat {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    length: number;
+    angle: number;
+}
+declare class OceanWorld {
+    readonly cols: number;
+    readonly rows: number;
+    readonly chunkSize: number;
+    readonly globalSizeW: number;
+    readonly globalSizeH: number;
+    grid: TriadeGrid;
+    boats: Boat[];
+    keys: {
+        up: boolean;
+        down: boolean;
+        left: boolean;
+        right: boolean;
+    };
+    constructor(masterBuffer: TriadeMasterBuffer, cols?: number, rows?: number, chunkSize?: number);
+    reset(): void;
+    addBoat(globalX: number, globalY: number, length?: number): void;
+    step(): void;
+    setVortexParams(strength: number, radius: number): void;
+    /**
+     * Helper to render a specific chunk to an isolated Canvas Context
+     */
+    renderChunk(chunkX: number, chunkY: number, ctx: CanvasRenderingContext2D, imageData: ImageData): void;
+    setInteraction(globalX: number, globalY: number, active: boolean): void;
+}
+
+/**
+ * @AI_BOILERPLATE This is the standard template for creating a new O(1) physics/math engine.
+ * Rename the class and implement the specific logic inside compute().
+ */
+declare class BlankEngine implements ITriadeEngine {
+    get name(): string;
+    /**
+     * Called at every simulation tick.
+     * @param faces Array of Float32Array (VRAM Memory mapping of the TriadeCube)
+     *              Face[0] is typically the main Output buffer or State A
+     *              Face[1] is typically the Secondary buffer or State B (Wait/Swap)
+     * @param mapSize The N x N resolution of the chunk
+     */
+    compute(faces: FlatTensorView[], mapSize: number): void;
+}
+
+export { AerodynamicsEngine, BlankEngine, type Boat, CanvasAdapter, EcosystemEngineO1, type FlatTensorView, GameOfLifeEngine, HeatmapEngine, type ITriadeEngine, OceanEngine, type OceanEngineParams, OceanSimulatorAddon, OceanWebGLRenderer, OceanWorld, Triade, TriadeCubeV2, TriadeGrid, TriadeMasterBuffer, WebGLAdapter };