murow 0.0.42 → 0.0.53

package/dist/core/fixed-ticker/fixed-ticker.d.ts

@@ -25,7 +25,7 @@ export declare class FixedTicker {
      * @description
      * Interval in milliseconds per tick
      */
-    private intervalMs;
+    intervalMs: number;
     /**
      * @description
      * Maximum amount of ticks to run per frame, to avoid
@@ -83,6 +83,14 @@ export declare class FixedTicker {
      * @returns {number} Accumulated time in seconds
      */
     get accumulatedTime(): number;
+    /**
+     * @description
+     * Returns the interpolation factor between 0 and 1 for smooth rendering between ticks.
+     * Clamped to prevent extrapolation when ticks are skipped.
+     *
+     * @returns {number} Alpha value between 0 and 1
+     */
+    get alpha(): number;
 }
 interface FixedTickerProps {
     /**

package/dist/core/fixed-ticker/fixed-ticker.js

@@ -88,4 +88,14 @@ export class FixedTicker {
     get accumulatedTime() {
         return this.accumulator / 1000; // Convert to seconds
     }
+    /**
+     * @description
+     * Returns the interpolation factor between 0 and 1 for smooth rendering between ticks.
+     * Clamped to prevent extrapolation when ticks are skipped.
+     *
+     * @returns {number} Alpha value between 0 and 1
+     */
+    get alpha() {
+        return Math.min(this.accumulatedTime / (1 / this.rate), 1.0);
+    }
 }

package/dist/core/navmesh/navmesh-worker-pool.d.ts

@@ -0,0 +1,53 @@
+/**
+ * NavMesh Worker Pool - Manages multiple workers for parallel pathfinding
+ */
+import { ObstacleInput } from './navmesh';
+interface Vec2 {
+    x: number;
+    y: number;
+}
+export declare class NavMeshWorkerPool {
+    private poolSize;
+    private workerPath;
+    private navType;
+    private obstacles;
+    private workers;
+    private nextWorkerIndex;
+    private requestId;
+    private pendingRequests;
+    private initialized;
+    constructor(poolSize: number, workerPath: string, navType?: 'grid' | 'graph', obstacles?: ObstacleInput[]);
+    /**
+     * Initialize all workers in the pool
+     */
+    init(): Promise<void>;
+    /**
+     * Find a path using the next available worker (round-robin)
+     */
+    findPath(from: Vec2, to: Vec2): Promise<Vec2[]>;
+    /**
+     * Add an obstacle to all workers
+     */
+    addObstacle(obstacle: ObstacleInput): Promise<number>;
+    /**
+     * Remove an obstacle from all workers
+     */
+    removeObstacle(obstacleId: number): Promise<void>;
+    /**
+     * Move an obstacle in all workers
+     */
+    moveObstacle(obstacleId: number, pos: Vec2): Promise<void>;
+    /**
+     * Terminate all workers
+     */
+    terminate(): void;
+    /**
+     * Get the number of pending requests
+     */
+    get pendingCount(): number;
+    /**
+     * Get the pool size
+     */
+    get size(): number;
+}
+export {};

package/dist/core/navmesh/navmesh-worker-pool.js

@@ -0,0 +1,180 @@
+/**
+ * NavMesh Worker Pool - Manages multiple workers for parallel pathfinding
+ */
+export class NavMeshWorkerPool {
+    constructor(poolSize, workerPath, navType = 'grid', obstacles = []) {
+        this.poolSize = poolSize;
+        this.workerPath = workerPath;
+        this.navType = navType;
+        this.obstacles = obstacles;
+        this.workers = [];
+        this.nextWorkerIndex = 0;
+        this.requestId = 0;
+        this.pendingRequests = new Map();
+        this.initialized = false;
+    }
+    /**
+     * Initialize all workers in the pool
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        const initPromises = [];
+        for (let i = 0; i < this.poolSize; i++) {
+            const worker = new Worker(this.workerPath, { type: 'module' });
+            // Set up message handler
+            worker.onmessage = (e) => {
+                const msg = e.data;
+                if (msg.type === 'PATH_RESULT') {
+                    const request = this.pendingRequests.get(msg.id);
+                    if (request) {
+                        request.resolve(msg.path);
+                        this.pendingRequests.delete(msg.id);
+                    }
+                }
+                else if (msg.type === 'ERROR') {
+                    // Reject all pending requests for this worker
+                    for (const [id, request] of this.pendingRequests.entries()) {
+                        request.reject(new Error(msg.error));
+                        this.pendingRequests.delete(id);
+                    }
+                }
+            };
+            worker.onerror = (error) => {
+                console.error('Worker error:', error);
+                // Reject all pending requests for this worker
+                for (const [id, request] of this.pendingRequests.entries()) {
+                    request.reject(new Error('Worker error'));
+                    this.pendingRequests.delete(id);
+                }
+            };
+            this.workers.push(worker);
+            // Initialize worker
+            const readyPromise = new Promise((resolve) => {
+                const onReady = (e) => {
+                    if (e.data.type === 'READY') {
+                        worker.removeEventListener('message', onReady);
+                        resolve();
+                    }
+                };
+                worker.addEventListener('message', onReady);
+            });
+            worker.postMessage({
+                type: 'INIT',
+                navType: this.navType,
+                obstacles: this.obstacles,
+            });
+            initPromises.push(readyPromise);
+        }
+        await Promise.all(initPromises);
+        this.initialized = true;
+    }
+    /**
+     * Find a path using the next available worker (round-robin)
+     */
+    async findPath(from, to) {
+        if (!this.initialized) {
+            throw new Error('Worker pool not initialized. Call init() first.');
+        }
+        const id = this.requestId++;
+        const worker = this.workers[this.nextWorkerIndex];
+        this.nextWorkerIndex = (this.nextWorkerIndex + 1) % this.workers.length;
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, { id, from, to, resolve, reject });
+            worker.postMessage({
+                type: 'FIND_PATH',
+                id,
+                from,
+                to,
+            });
+        });
+    }
+    /**
+     * Add an obstacle to all workers
+     */
+    async addObstacle(obstacle) {
+        if (!this.initialized) {
+            throw new Error('Worker pool not initialized. Call init() first.');
+        }
+        // Add to all workers
+        const promises = this.workers.map((worker) => {
+            return new Promise((resolve) => {
+                const onAdded = (e) => {
+                    if (e.data.type === 'OBSTACLE_ADDED') {
+                        worker.removeEventListener('message', onAdded);
+                        resolve(e.data.obstacleId);
+                    }
+                };
+                worker.addEventListener('message', onAdded);
+                worker.postMessage({ type: 'ADD_OBSTACLE', obstacle });
+            });
+        });
+        const ids = await Promise.all(promises);
+        return ids[0]; // All workers should return the same ID
+    }
+    /**
+     * Remove an obstacle from all workers
+     */
+    async removeObstacle(obstacleId) {
+        if (!this.initialized) {
+            throw new Error('Worker pool not initialized. Call init() first.');
+        }
+        const promises = this.workers.map((worker) => {
+            return new Promise((resolve) => {
+                const onRemoved = (e) => {
+                    if (e.data.type === 'OBSTACLE_REMOVED') {
+                        worker.removeEventListener('message', onRemoved);
+                        resolve();
+                    }
+                };
+                worker.addEventListener('message', onRemoved);
+                worker.postMessage({ type: 'REMOVE_OBSTACLE', obstacleId });
+            });
+        });
+        await Promise.all(promises);
+    }
+    /**
+     * Move an obstacle in all workers
+     */
+    async moveObstacle(obstacleId, pos) {
+        if (!this.initialized) {
+            throw new Error('Worker pool not initialized. Call init() first.');
+        }
+        const promises = this.workers.map((worker) => {
+            return new Promise((resolve) => {
+                const onMoved = (e) => {
+                    if (e.data.type === 'OBSTACLE_MOVED') {
+                        worker.removeEventListener('message', onMoved);
+                        resolve();
+                    }
+                };
+                worker.addEventListener('message', onMoved);
+                worker.postMessage({ type: 'MOVE_OBSTACLE', obstacleId, pos });
+            });
+        });
+        await Promise.all(promises);
+    }
+    /**
+     * Terminate all workers
+     */
+    terminate() {
+        for (const worker of this.workers) {
+            worker.terminate();
+        }
+        this.workers = [];
+        this.pendingRequests.clear();
+        this.initialized = false;
+    }
+    /**
+     * Get the number of pending requests
+     */
+    get pendingCount() {
+        return this.pendingRequests.size;
+    }
+    /**
+     * Get the pool size
+     */
+    get size() {
+        return this.workers.length;
+    }
+}

package/dist/core/navmesh/navmesh.d.ts

@@ -1,5 +1,41 @@
 type ObstacleId = number;
 export type Obstacle = CircleObstacle | RectObstacle | PolygonObstacle;
+/**
+ * NavMesh configuration options
+ */
+export interface NavMeshOptions<TWorkers extends boolean | 'auto' = false> {
+    /**
+     * Enable Web Workers for pathfinding
+     *
+     * - `false` (default): Synchronous pathfinding on main thread
+     * - `true`: Always use worker pool (4 workers)
+     * - `'auto'`: Automatically use workers when beneficial (>= 20 pending paths)
+     *
+     * @default false
+     *
+     * @remarks
+     * Workers provide 3-4.5x speedup for parallel pathfinding (20+ concurrent requests).
+     * For single/sequential pathfinding, sync is faster due to message passing overhead (~0.5ms).
+     *
+     * Use 'auto' for games where pathfinding load varies (e.g., RTS with unit groups).
+     */
+    workers?: TWorkers;
+    /**
+     * Number of workers to spawn (only used when workers = true)
+     * @default 4
+     */
+    workerPoolSize?: number;
+    /**
+     * Path to worker script (required if workers = true and running in browser)
+     * For Node.js/Bun, this is handled automatically
+     * @example './navmesh.worker.js'
+     */
+    workerPath?: string;
+}
+/**
+ * Helper type to determine return type based on worker configuration
+ */
+type PathResult<TWorkers extends boolean | 'auto' | undefined> = TWorkers extends false | undefined ? Vec2[] : TWorkers extends true ? Promise<Vec2[]> : Vec2[] | Promise<Vec2[]>;
 export type ObstacleInput = Omit<CircleObstacle, 'id'> | Omit<RectObstacle, 'id'> | Omit<PolygonObstacle, 'id'>;
 interface Vec2 {
     x: number;
@@ -62,25 +98,54 @@ type NavType = 'grid' | 'graph';
  * - Version tracking: zero unnecessary rebuilds
  * - Binary heap A*: handles 10k+ node searches
  * - Simple full rebuild: correct and fast enough
+ * - Optional Web Workers: 3-4.5x speedup for parallel pathfinding
  *
  * Performance characteristics:
  * - Obstacle query: O(1) average via spatial hash
  * - Grid rebuild: O(n * area), < 1ms for typical games
  * - Pathfinding: O(b^d * log n) with binary heap
+ * - Worker overhead: ~0.5ms per request (use for 20+ concurrent paths)
  *
  * Production ready for:
  * - Grid-based games
  * - RTS with < 1000 dynamic obstacles
  * - Turn-based games
  * - Moderate map sizes (< 1M cells)
+ *
+ * @example
+ * ```ts
+ * // Simple usage (synchronous) - typed as Vec2[]
+ * const navmesh = new NavMesh('grid');
+ * const path = navmesh.findPath({ from: {x:0, y:0}, to: {x:10, y:10} });
+ *
+ * // With workers (automatic) - typed as Vec2[] | Promise<Vec2[]>
+ * const navmesh = new NavMesh('grid', { workers: 'auto' });
+ * const path = await navmesh.findPath({ from: {x:0, y:0}, to: {x:10, y:10} });
+ *
+ * // With workers (always) - typed as Promise<Vec2[]>
+ * const navmesh = new NavMesh('grid', { workers: true });
+ * const path = await navmesh.findPath({ from: {x:0, y:0}, to: {x:10, y:10} });
+ * ```
  */
-export declare class NavMesh {
+export declare class NavMesh<TWorkers extends boolean | 'auto' = false> {
     private type;
     private grid?;
     private graph?;
     private lastVersion;
     obstacles: Obstacles;
-    constructor(type: NavType);
+    private options;
+    private workerPool?;
+    private pendingPaths;
+    private readonly AUTO_WORKER_THRESHOLD;
+    constructor(type: NavType, options?: NavMeshOptions<TWorkers>);
+    /**
+     * Lazy initialize worker pool
+     */
+    private initWorkerPool;
+    /**
+     * Check if we should use workers for this request
+     */
+    private shouldUseWorkers;
     /**
      * Adds an obstacle and returns its unique ID.
      * For polygons: ensure points are defined relative to (0,0).
@@ -102,15 +167,61 @@ export declare class NavMesh {
      * Finds a path from start to goal.
      * Automatically rebuilds navigation data if obstacles changed.
      * Returns empty array if no path exists.
+     *
+     * @remarks
+     * - If workers are disabled (false): Returns Vec2[] synchronously
+     * - If workers are enabled (true): Returns Promise<Vec2[]>
+     * - If workers are 'auto': Returns Vec2[] | Promise<Vec2[]> based on load
+     *
+     * @example
+     * ```ts
+     * // Synchronous (no workers) - typed as Vec2[]
+     * const navmesh = new NavMesh('grid');
+     * const path = navmesh.findPath({ from, to });
+     *
+     * // Asynchronous (with workers) - typed as Promise<Vec2[]>
+     * const navmesh = new NavMesh('grid', { workers: true });
+     * const path = await navmesh.findPath({ from, to });
+     *
+     * // Auto mode - typed as Vec2[] | Promise<Vec2[]>
+     * const navmesh = new NavMesh('grid', { workers: 'auto' });
+     * const result = navmesh.findPath({ from, to });
+     * const path = result instanceof Promise ? await result : result;
+     * ```
      */
     findPath({ from, to }: {
         from: Vec2;
         to: Vec2;
-    }): Vec2[];
+    }): PathResult<TWorkers>;
+    /**
+     * Async pathfinding using worker pool
+     */
+    private findPathAsync;
     /**
      * Smart rebuild - only rebuilds if obstacles changed.
      * Version checking eliminates unnecessary work.
      */
     rebuild(): void;
+    /**
+     * Cleanup resources (terminate worker pool if active)
+     * Call this when you're done with the NavMesh instance.
+     *
+     * @example
+     * ```ts
+     * const navmesh = new NavMesh('grid', { workers: true });
+     * // ... use navmesh ...
+     * navmesh.dispose(); // Cleanup workers
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Get current worker status for debugging/monitoring
+     */
+    getWorkerStatus(): {
+        workersEnabled: TWorkers;
+        workerPoolActive: boolean;
+        pendingPaths: number;
+        usingWorkersNow: boolean;
+    };
 }
 export {};

package/dist/core/navmesh/navmesh.js

@@ -524,27 +524,85 @@ class GraphNav {
  * - Version tracking: zero unnecessary rebuilds
  * - Binary heap A*: handles 10k+ node searches
  * - Simple full rebuild: correct and fast enough
+ * - Optional Web Workers: 3-4.5x speedup for parallel pathfinding
  *
  * Performance characteristics:
  * - Obstacle query: O(1) average via spatial hash
  * - Grid rebuild: O(n * area), < 1ms for typical games
  * - Pathfinding: O(b^d * log n) with binary heap
+ * - Worker overhead: ~0.5ms per request (use for 20+ concurrent paths)
  *
  * Production ready for:
  * - Grid-based games
  * - RTS with < 1000 dynamic obstacles
  * - Turn-based games
  * - Moderate map sizes (< 1M cells)
+ *
+ * @example
+ * ```ts
+ * // Simple usage (synchronous) - typed as Vec2[]
+ * const navmesh = new NavMesh('grid');
+ * const path = navmesh.findPath({ from: {x:0, y:0}, to: {x:10, y:10} });
+ *
+ * // With workers (automatic) - typed as Vec2[] | Promise<Vec2[]>
+ * const navmesh = new NavMesh('grid', { workers: 'auto' });
+ * const path = await navmesh.findPath({ from: {x:0, y:0}, to: {x:10, y:10} });
+ *
+ * // With workers (always) - typed as Promise<Vec2[]>
+ * const navmesh = new NavMesh('grid', { workers: true });
+ * const path = await navmesh.findPath({ from: {x:0, y:0}, to: {x:10, y:10} });
+ * ```
  */
 export class NavMesh {
-    constructor(type) {
+    constructor(type, options) {
         this.type = type;
         this.lastVersion = -1;
+        this.pendingPaths = 0;
+        this.AUTO_WORKER_THRESHOLD = 20; // Use workers when >= 20 pending paths
         this.obstacles = new Obstacles();
+        // Set defaults - cast to any to avoid complex type gymnastics
+        this.options = {
+            workers: (options?.workers ?? false),
+            workerPoolSize: options?.workerPoolSize ?? 4,
+            workerPath: options?.workerPath ?? './navmesh.worker.js',
+        };
+        // Initialize sync navigation
         if (type === 'grid')
             this.grid = new GridNav(this.obstacles);
         if (type === 'graph')
             this.graph = new GraphNav(this.obstacles);
+        // Initialize worker pool if workers = true
+        if (this.options.workers === true) {
+            this.initWorkerPool();
+        }
+    }
+    /**
+     * Lazy initialize worker pool
+     */
+    async initWorkerPool() {
+        if (this.workerPool)
+            return;
+        try {
+            // Dynamic import to avoid bundling worker pool if not needed
+            const { NavMeshWorkerPool } = await import('./navmesh-worker-pool');
+            this.workerPool = new NavMeshWorkerPool(this.options.workerPoolSize, this.options.workerPath, this.type, this.obstacles.values);
+            await this.workerPool.init();
+        }
+        catch (error) {
+            console.warn('Failed to initialize worker pool, falling back to sync:', error);
+            this.options.workers = false; // Disable workers on failure
+        }
+    }
+    /**
+     * Check if we should use workers for this request
+     */
+    shouldUseWorkers() {
+        if (this.options.workers === false)
+            return false;
+        if (this.options.workers === true)
+            return true;
+        // Auto mode: use workers if we have many pending paths
+        return this.pendingPaths >= this.AUTO_WORKER_THRESHOLD;
     }
     /**
      * Adds an obstacle and returns its unique ID.
@@ -575,12 +633,59 @@ export class NavMesh {
      * Finds a path from start to goal.
      * Automatically rebuilds navigation data if obstacles changed.
      * Returns empty array if no path exists.
+     *
+     * @remarks
+     * - If workers are disabled (false): Returns Vec2[] synchronously
+     * - If workers are enabled (true): Returns Promise<Vec2[]>
+     * - If workers are 'auto': Returns Vec2[] | Promise<Vec2[]> based on load
+     *
+     * @example
+     * ```ts
+     * // Synchronous (no workers) - typed as Vec2[]
+     * const navmesh = new NavMesh('grid');
+     * const path = navmesh.findPath({ from, to });
+     *
+     * // Asynchronous (with workers) - typed as Promise<Vec2[]>
+     * const navmesh = new NavMesh('grid', { workers: true });
+     * const path = await navmesh.findPath({ from, to });
+     *
+     * // Auto mode - typed as Vec2[] | Promise<Vec2[]>
+     * const navmesh = new NavMesh('grid', { workers: 'auto' });
+     * const result = navmesh.findPath({ from, to });
+     * const path = result instanceof Promise ? await result : result;
+     * ```
      */
     findPath({ from, to }) {
+        // Check if we should use workers
+        if (this.shouldUseWorkers() && this.workerPool) {
+            // Async path (with workers)
+            this.pendingPaths++;
+            return this.findPathAsync(from, to).finally(() => {
+                this.pendingPaths--;
+            });
+        }
+        // Sync path (no workers)
         this.rebuild();
-        return this.type === 'grid'
+        return (this.type === 'grid'
             ? this.grid.findPath(from, to)
-            : this.graph.findPath(from, to);
+            : this.graph.findPath(from, to));
+    }
+    /**
+     * Async pathfinding using worker pool
+     */
+    async findPathAsync(from, to) {
+        // Lazy init for 'auto' mode
+        if (this.options.workers === 'auto' && !this.workerPool) {
+            await this.initWorkerPool();
+        }
+        if (!this.workerPool) {
+            // Fallback to sync if workers failed to init
+            this.rebuild();
+            return this.type === 'grid'
+                ? this.grid.findPath(from, to)
+                : this.graph.findPath(from, to);
+        }
+        return this.workerPool.findPath(from, to);
     }
     /**
      * Smart rebuild - only rebuilds if obstacles changed.
@@ -593,6 +698,34 @@ export class NavMesh {
         this.graph?.rebuild();
         this.lastVersion = this.obstacles.version;
     }
+    /**
+     * Cleanup resources (terminate worker pool if active)
+     * Call this when you're done with the NavMesh instance.
+     *
+     * @example
+     * ```ts
+     * const navmesh = new NavMesh('grid', { workers: true });
+     * // ... use navmesh ...
+     * navmesh.dispose(); // Cleanup workers
+     * ```
+     */
+    dispose() {
+        if (this.workerPool) {
+            this.workerPool.terminate();
+            this.workerPool = undefined;
+        }
+    }
+    /**
+     * Get current worker status for debugging/monitoring
+     */
+    getWorkerStatus() {
+        return {
+            workersEnabled: this.options.workers,
+            workerPoolActive: !!this.workerPool,
+            pendingPaths: this.pendingPaths,
+            usingWorkersNow: this.shouldUseWorkers(),
+        };
+    }
 }
 /* ---------------------------------- */
 /* A*                                 */

package/dist/core/navmesh/navmesh.worker.d.ts

@@ -0,0 +1,11 @@
+/**
+ * NavMesh Worker - Offloads pathfinding to background thread
+ *
+ * Message Protocol:
+ * - INIT: Initialize NavMesh with obstacles
+ * - FIND_PATH: Request pathfinding (from, to)
+ * - ADD_OBSTACLE: Add obstacle dynamically
+ * - REMOVE_OBSTACLE: Remove obstacle dynamically
+ * - MOVE_OBSTACLE: Move obstacle
+ */
+export {};