@buley/hexgrid-3d 3.1.0 → 3.2.1

package/dist/webgpu/WebGPUContext.js

@@ -0,0 +1,60 @@
+/**
+ * WebGPU Context Manager
+ * Handles the creation and management of the WebGPU Device and Adapter.
+ */
+export class WebGPUContext {
+    constructor() {
+        this.adapter = null;
+        this.device = null;
+        this.isSupported = false;
+    }
+    static getInstance() {
+        if (!WebGPUContext.instance) {
+            WebGPUContext.instance = new WebGPUContext();
+        }
+        return WebGPUContext.instance;
+    }
+    /**
+     * Initialize WebGPU context.
+     */
+    async initialize() {
+        if (typeof navigator === 'undefined' || !navigator.gpu) {
+            console.warn('WebGPU is not supported in this environment.');
+            this.isSupported = false;
+            return false;
+        }
+        try {
+            this.adapter = await navigator.gpu.requestAdapter({
+                powerPreference: 'high-performance'
+            });
+            if (!this.adapter) {
+                console.warn('No WebGPU adapter found.');
+                this.isSupported = false;
+                return false;
+            }
+            this.device = await this.adapter.requestDevice();
+            this.device.lost.then((info) => {
+                console.error(`WebGPU device lost: ${info.message}`);
+                this.device = null;
+                this.isSupported = false;
+            });
+            this.isSupported = true;
+            console.log('WebGPU initialized successfully.');
+            return true;
+        }
+        catch (e) {
+            console.error('Failed to initialize WebGPU:', e);
+            this.isSupported = false;
+            return false;
+        }
+    }
+    getDevice() {
+        return this.device;
+    }
+    getAdapter() {
+        return this.adapter;
+    }
+    isAvailable() {
+        return this.isSupported && this.device !== null;
+    }
+}

package/dist/webnn/WebNNContext.d.ts

@@ -0,0 +1,38 @@
+/**
+ * WebNN Context Manager
+ * Handles the creation and management of the WebNN MLContext.
+ * Prioritizes NPU -> GPU -> CPU.
+ */
+export type WebNNDeviceType = 'cpu' | 'gpu' | 'npu';
+export declare class WebNNContext {
+    private static instance;
+    private context;
+    private deviceType;
+    private isSupported;
+    private constructor();
+    static getInstance(): WebNNContext;
+    /**
+     * Initialize WebNN context with preferred device type.
+     */
+    initialize(preference?: WebNNDeviceType): Promise<boolean>;
+    getContext(): MLContext | null;
+    getDeviceType(): WebNNDeviceType;
+    isAvailable(): boolean;
+}
+declare global {
+    interface Navigator {
+        ml: {
+            createContext(options?: {
+                deviceType?: string;
+            }): Promise<MLContext>;
+        };
+    }
+    interface MLContext {
+        compute(graph: MLGraph, inputs: Record<string, ArrayBufferView>, outputs: Record<string, ArrayBufferView>): Promise<MLComputeResult>;
+    }
+    interface MLGraph {
+    }
+    interface MLComputeResult {
+    }
+}
+//# sourceMappingURL=WebNNContext.d.ts.map

package/dist/webnn/WebNNContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebNNContext.d.ts","sourceRoot":"","sources":["../../src/webnn/WebNNContext.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAEpD,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAe;IACtC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,WAAW,CAAkB;IAErC,OAAO;IAEP,MAAM,CAAC,WAAW,IAAI,YAAY;IAOlC;;OAEG;IACG,UAAU,CAAC,UAAU,GAAE,eAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;IAuCvE,UAAU,IAAI,SAAS,GAAG,IAAI;IAI9B,aAAa,IAAI,eAAe;IAIhC,WAAW,IAAI,OAAO;CAGvB;AAGD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,SAAS;QACjB,EAAE,EAAE;YACF,aAAa,CAAC,OAAO,CAAC,EAAE;gBAAE,UAAU,CAAC,EAAE,MAAM,CAAA;aAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;SACtE,CAAC;KACH;IAED,UAAU,SAAS;QAEjB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;KACtI;IAED,UAAU,OAAO;KAEhB;IAED,UAAU,eAAe;KAExB;CACF"}

package/dist/webnn/WebNNContext.js

@@ -0,0 +1,66 @@
+/**
+ * WebNN Context Manager
+ * Handles the creation and management of the WebNN MLContext.
+ * Prioritizes NPU -> GPU -> CPU.
+ */
+export class WebNNContext {
+    constructor() {
+        this.context = null;
+        this.deviceType = 'cpu';
+        this.isSupported = false;
+    }
+    static getInstance() {
+        if (!WebNNContext.instance) {
+            WebNNContext.instance = new WebNNContext();
+        }
+        return WebNNContext.instance;
+    }
+    /**
+     * Initialize WebNN context with preferred device type.
+     */
+    async initialize(preference = 'npu') {
+        if (typeof navigator === 'undefined' || !navigator.ml) {
+            console.warn('WebNN is not supported in this environment.');
+            this.isSupported = false;
+            return false;
+        }
+        try {
+            // Try preferred device first
+            this.context = await navigator.ml.createContext({ deviceType: preference });
+            this.deviceType = preference;
+            this.isSupported = true;
+            console.log(`WebNN initialized successfully on ${preference}`);
+            return true;
+        }
+        catch (e) {
+            console.warn(`Failed to initialize WebNN on ${preference}, trying fallback chain...`, e);
+            // Fallback chain: NPU -> GPU -> CPU
+            const chain = ['npu', 'gpu', 'cpu'];
+            const startIndex = chain.indexOf(preference) + 1;
+            for (let i = startIndex; i < chain.length; i++) {
+                const fallback = chain[i];
+                try {
+                    this.context = await navigator.ml.createContext({ deviceType: fallback });
+                    this.deviceType = fallback;
+                    this.isSupported = true;
+                    console.log(`WebNN initialized successfully on fallback ${fallback}`);
+                    return true;
+                }
+                catch (err) {
+                    console.warn(`Failed to initialize WebNN on fallback ${fallback}`, err);
+                }
+            }
+        }
+        this.isSupported = false;
+        return false;
+    }
+    getContext() {
+        return this.context;
+    }
+    getDeviceType() {
+        return this.deviceType;
+    }
+    isAvailable() {
+        return this.isSupported && this.context !== null;
+    }
+}

package/dist/workers/hexgrid-math.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure mathematical functions for hexgrid calculations.
+ * These functions have NO side effects, NO logging, and NO mutable state access.
+ * They are deterministic and testable in isolation.
+ */
+/**
+ * Calculate the bounding box of a set of 2D/3D positions.
+ * @pure - No side effects, deterministic
+ * @param positions Array of [x, y, z] coordinates
+ * @returns Object with min/max bounds and dimensions
+ */
+export declare function getGridBounds(positions: [number, number, number][]): {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    width: number;
+    height: number;
+};
+/**
+ * Calculate Euclidean distance between two 3D points with optional spherical wrapping.
+ * @pure - No side effects, deterministic
+ * @param a First point [x, y, z]
+ * @param b Second point [x, y, z]
+ * @param bounds Grid bounds for spherical calculation
+ * @param isSpherical Whether to apply spherical wrapping (toroidal distance)
+ * @returns Euclidean distance
+ */
+export declare function distanceBetween(a: [number, number, number], b: [number, number, number], bounds: {
+    width: number;
+    height: number;
+}, isSpherical: boolean): number;
+/**
+ * Calculate UV texture coordinates for a tile based on its grid position.
+ * @pure - No side effects, deterministic
+ * @param gridCol Column index (0-based)
+ * @param gridRow Row index (0-based)
+ * @param tilesX Total number of columns in texture grid
+ * @param tilesY Total number of rows in texture grid
+ * @returns [minU, minV, maxU, maxV] in range [0, 1]
+ *
+ * Note: V=1.0 represents the top of the texture.
+ * Row 0 maps to top, so maxV=1 and minV=1-1/tilesY.
+ */
+export declare function calculateUvBoundsFromGridPosition(gridCol: number, gridRow: number, tilesX: number, tilesY: number): [number, number, number, number];
+/**
+ * Calculate contiguity score between indices (internal connectivity).
+ * Higher score means more indices in the set are neighbors with each other.
+ * @pure - No side effects, deterministic
+ * @param indices Set of position indices to measure
+ * @param positions Array of all positions
+ * @param hexRadius Radius for neighbor detection
+ * @param getNeighbors Function to get neighbors for an index (dependency injection)
+ * @returns Sum of neighbor connections within the set
+ */
+export declare function calculateContiguity(indices: number[], positions: [number, number, number][], hexRadius: number, getNeighbors: (index: number) => number[]): number;
+/**
+ * Calculate contiguity score for a photo's indices.
+ * @pure - No side effects, deterministic
+ * @param indices Indices belonging to a photo
+ * @param positions Array of all positions
+ * @param hexRadius Radius for neighbor detection
+ * @param getNeighbors Function to get neighbors for an index
+ * @returns Total contiguity score
+ */
+export declare function calculatePhotoContiguity(indices: number[], positions: [number, number, number][], hexRadius: number, getNeighbors: (index: number) => number[]): number;
+/**
+ * Calculate contiguity after a hypothetical swap of two indices.
+ * @pure - No side effects, deterministic
+ * @param indices Current indices
+ * @param positions Array of all positions
+ * @param hexRadius Radius for neighbor detection
+ * @param fromIndex Index to swap from
+ * @param toIndex Index to swap to
+ * @param getNeighbors Function to get neighbors for an index
+ * @returns Contiguity score after swap
+ */
+export declare function calculateSwappedContiguity(indices: number[], positions: [number, number, number][], hexRadius: number, fromIndex: number, toIndex: number, getNeighbors: (index: number) => number[]): number;
+//# sourceMappingURL=hexgrid-math.d.ts.map

package/dist/workers/hexgrid-math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hexgrid-math.d.ts","sourceRoot":"","sources":["../../src/workers/hexgrid-math.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;;;;;;;EAmBlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC3B,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC3B,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACzC,WAAW,EAAE,OAAO,GACnB,MAAM,CAeR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAalC;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,GACxC,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,GACxC,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,GACxC,MAAM,CAgBR"}

package/dist/workers/hexgrid-math.js

@@ -0,0 +1,136 @@
+/**
+ * Pure mathematical functions for hexgrid calculations.
+ * These functions have NO side effects, NO logging, and NO mutable state access.
+ * They are deterministic and testable in isolation.
+ */
+/**
+ * Calculate the bounding box of a set of 2D/3D positions.
+ * @pure - No side effects, deterministic
+ * @param positions Array of [x, y, z] coordinates
+ * @returns Object with min/max bounds and dimensions
+ */
+export function getGridBounds(positions) {
+    if (!positions || positions.length === 0) {
+        return { minX: 0, maxX: 0, minY: 0, maxY: 0, width: 0, height: 0 };
+    }
+    let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+    for (const p of positions) {
+        if (!p)
+            continue;
+        minX = Math.min(minX, p[0]);
+        maxX = Math.max(maxX, p[0]);
+        minY = Math.min(minY, p[1]);
+        maxY = Math.max(maxY, p[1]);
+    }
+    return { minX, maxX, minY, maxY, width: maxX - minX, height: maxY - minY };
+}
+/**
+ * Calculate Euclidean distance between two 3D points with optional spherical wrapping.
+ * @pure - No side effects, deterministic
+ * @param a First point [x, y, z]
+ * @param b Second point [x, y, z]
+ * @param bounds Grid bounds for spherical calculation
+ * @param isSpherical Whether to apply spherical wrapping (toroidal distance)
+ * @returns Euclidean distance
+ */
+export function distanceBetween(a, b, bounds, isSpherical) {
+    let dx = b[0] - a[0];
+    let dy = b[1] - a[1];
+    if (isSpherical && bounds.width > 0 && bounds.height > 0) {
+        // Apply toroidal wrapping: shortest distance considering wraparound
+        if (Math.abs(dx) > bounds.width / 2) {
+            dx = dx > 0 ? dx - bounds.width : dx + bounds.width;
+        }
+        if (Math.abs(dy) > bounds.height / 2) {
+            dy = dy > 0 ? dy - bounds.height : dy + bounds.height;
+        }
+    }
+    return Math.sqrt(dx * dx + dy * dy);
+}
+/**
+ * Calculate UV texture coordinates for a tile based on its grid position.
+ * @pure - No side effects, deterministic
+ * @param gridCol Column index (0-based)
+ * @param gridRow Row index (0-based)
+ * @param tilesX Total number of columns in texture grid
+ * @param tilesY Total number of rows in texture grid
+ * @returns [minU, minV, maxU, maxV] in range [0, 1]
+ *
+ * Note: V=1.0 represents the top of the texture.
+ * Row 0 maps to top, so maxV=1 and minV=1-1/tilesY.
+ */
+export function calculateUvBoundsFromGridPosition(gridCol, gridRow, tilesX, tilesY) {
+    // Guard against invalid grid dimensions
+    if (tilesX <= 0 || tilesY <= 0) {
+        return [0, 0, 1, 1];
+    }
+    const minU = gridCol / tilesX;
+    const maxU = (gridCol + 1) / tilesX;
+    // V=1 is top, so row 0 maps to top (maxV=1, minV=1-1/tilesY)
+    const minV = 1 - (gridRow + 1) / tilesY;
+    const maxV = 1 - gridRow / tilesY;
+    return [minU, minV, maxU, maxV];
+}
+/**
+ * Calculate contiguity score between indices (internal connectivity).
+ * Higher score means more indices in the set are neighbors with each other.
+ * @pure - No side effects, deterministic
+ * @param indices Set of position indices to measure
+ * @param positions Array of all positions
+ * @param hexRadius Radius for neighbor detection
+ * @param getNeighbors Function to get neighbors for an index (dependency injection)
+ * @returns Sum of neighbor connections within the set
+ */
+export function calculateContiguity(indices, positions, hexRadius, getNeighbors) {
+    if (!indices || indices.length === 0)
+        return 0;
+    if (!positions || positions.length === 0)
+        return 0;
+    if (hexRadius <= 0)
+        return 0;
+    const set = new Set(indices);
+    let total = 0;
+    for (const idx of indices) {
+        const neighbors = getNeighbors(idx);
+        for (const n of neighbors) {
+            if (set.has(n))
+                total++;
+        }
+    }
+    return total;
+}
+/**
+ * Calculate contiguity score for a photo's indices.
+ * @pure - No side effects, deterministic
+ * @param indices Indices belonging to a photo
+ * @param positions Array of all positions
+ * @param hexRadius Radius for neighbor detection
+ * @param getNeighbors Function to get neighbors for an index
+ * @returns Total contiguity score
+ */
+export function calculatePhotoContiguity(indices, positions, hexRadius, getNeighbors) {
+    return calculateContiguity(indices, positions, hexRadius, getNeighbors);
+}
+/**
+ * Calculate contiguity after a hypothetical swap of two indices.
+ * @pure - No side effects, deterministic
+ * @param indices Current indices
+ * @param positions Array of all positions
+ * @param hexRadius Radius for neighbor detection
+ * @param fromIndex Index to swap from
+ * @param toIndex Index to swap to
+ * @param getNeighbors Function to get neighbors for an index
+ * @returns Contiguity score after swap
+ */
+export function calculateSwappedContiguity(indices, positions, hexRadius, fromIndex, toIndex, getNeighbors) {
+    if (!indices || indices.length === 0)
+        return 0;
+    const tempIndices = [...indices];
+    const fromPos = tempIndices.indexOf(fromIndex);
+    const toPos = tempIndices.indexOf(toIndex);
+    if (fromPos !== -1)
+        tempIndices[fromPos] = toIndex;
+    if (toPos !== -1)
+        tempIndices[toPos] = fromIndex;
+    return calculatePhotoContiguity(tempIndices, positions, hexRadius, getNeighbors);
+}

package/dist/workers/hexgrid-worker.worker.d.ts

@@ -0,0 +1,35 @@
+export interface Photo {
+    id: string;
+    title?: string;
+    alt?: string;
+    imageUrl?: string;
+    velocity?: number;
+}
+export interface Infection {
+    photo: Photo;
+    gridPosition: [number, number];
+    infectionTime: number;
+    generation: number;
+    uvBounds: [number, number, number, number];
+    scale: number;
+    growthRate?: number;
+    tilesX?: number;
+    tilesY?: number;
+}
+export interface InfectionSystemState {
+    infections: Map<number, Infection>;
+    availableIndices: number[];
+    lastEvolutionTime: number;
+    generation: number;
+    tileCenters?: Array<{
+        photoId: string;
+        clusterIndex: number;
+        centers: Array<{
+            x: number;
+            y: number;
+            col: number;
+            row: number;
+        }>;
+    }>;
+}
+//# sourceMappingURL=hexgrid-worker.worker.d.ts.map

package/dist/workers/hexgrid-worker.worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hexgrid-worker.worker.d.ts","sourceRoot":"","sources":["../../src/workers/hexgrid-worker.worker.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACnC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,KAAK,CAAC;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACpE,CAAC,CAAC;CACJ"}