murow 0.0.70 → 0.0.71

package/dist/core/navmesh/navmesh.js

@@ -1,799 +0,0 @@
-/* ---------------------------------- */
-/* Utils                              */
-/* ---------------------------------- */
-const dirs = [
-    { x: 1, y: 0 },
-    { x: -1, y: 0 },
-    { x: 0, y: 1 },
-    { x: 0, y: -1 },
-];
-/**
- * Converts world coordinates to grid cell coordinates (floor).
- */
-const toCell = (v) => ({
-    x: Math.floor(v.x),
-    y: Math.floor(v.y),
-});
-/**
- * Converts grid cell coordinates to world coordinates (cell center).
- */
-const fromCell = (v) => ({
-    x: v.x + 0.5,
-    y: v.y + 0.5
-});
-/**
- * Generates unique sequential IDs for obstacles.
- */
-const genId = (() => {
-    let i = 1;
-    return () => i++;
-})();
-/**
- * Encodes grid coordinates as a single integer for use as Map/Set keys.
- * Uses 32-bit safe packing: lower 16 bits = x, upper 16 bits = y.
- * Supports coordinates in range [-32768, 32767].
- */
-const encodeCell = (x, y) => (x & 0xffff) | ((y & 0xffff) << 16);
-/**
- * Decodes an encoded cell back to {x, y}.
- * Properly handles sign extension for negative coordinates.
- */
-const decodeCell = (n) => ({
-    x: (n << 16) >> 16,
-    y: n >> 16,
-});
-/* ---------------------------------- */
-/* Binary Heap (Priority Queue)      */
-/* ---------------------------------- */
-/**
- * Min-heap priority queue for A*.
- * Supports O(log n) insert and extract-min operations.
- */
-class BinaryHeap {
-    constructor(scoreFn) {
-        this.scoreFn = scoreFn;
-        this.heap = [];
-    }
-    push(item) {
-        this.heap.push(item);
-        this.bubbleUp(this.heap.length - 1);
-    }
-    pop() {
-        const result = this.heap[0];
-        const end = this.heap.pop();
-        if (this.heap.length > 0 && end !== undefined) {
-            this.heap[0] = end;
-            this.sinkDown(0);
-        }
-        return result;
-    }
-    get size() {
-        return this.heap.length;
-    }
-    bubbleUp(n) {
-        const element = this.heap[n];
-        const score = this.scoreFn(element);
-        while (n > 0) {
-            const parentN = ((n + 1) >> 1) - 1;
-            const parent = this.heap[parentN];
-            if (score >= this.scoreFn(parent))
-                break;
-            this.heap[parentN] = element;
-            this.heap[n] = parent;
-            n = parentN;
-        }
-    }
-    sinkDown(n) {
-        const length = this.heap.length;
-        const element = this.heap[n];
-        const elemScore = this.scoreFn(element);
-        while (true) {
-            const child2N = (n + 1) << 1;
-            const child1N = child2N - 1;
-            let swap = null;
-            let child1Score;
-            if (child1N < length) {
-                const child1 = this.heap[child1N];
-                child1Score = this.scoreFn(child1);
-                if (child1Score < elemScore) {
-                    swap = child1N;
-                }
-            }
-            if (child2N < length) {
-                const child2 = this.heap[child2N];
-                const child2Score = this.scoreFn(child2);
-                if (child2Score < (swap === null ? elemScore : child1Score)) {
-                    swap = child2N;
-                }
-            }
-            if (swap === null)
-                break;
-            this.heap[n] = this.heap[swap];
-            this.heap[swap] = element;
-            n = swap;
-        }
-    }
-}
-/* ---------------------------------- */
-/* Spatial Hash                       */
-/* ---------------------------------- */
-/**
- * Spatial hash for fast obstacle queries.
- * Divides space into fixed-size cells and indexes obstacles by cell.
- * Provides O(1) average case lookup instead of O(n) linear scan.
- *
- * Cell size = 1 matches grid pathfinding unit cells.
- */
-class SpatialHash {
-    constructor(cellSize = 1) {
-        this.grid = new Map();
-        this.obstacleCells = new Map();
-        this.cellSize = cellSize;
-    }
-    /**
-     * Returns hash key for a world position.
-     */
-    hash(x, y) {
-        const cx = Math.floor(x / this.cellSize);
-        const cy = Math.floor(y / this.cellSize);
-        return encodeCell(cx, cy);
-    }
-    /**
-     * Adds an obstacle to the spatial hash.
-     */
-    add(id, obstacle) {
-        const cells = this.getCellsForObstacle(obstacle);
-        for (const cell of cells) {
-            if (!this.grid.has(cell)) {
-                this.grid.set(cell, new Set());
-            }
-            this.grid.get(cell).add(id);
-        }
-        this.obstacleCells.set(id, cells);
-    }
-    /**
-     * Removes an obstacle from the spatial hash.
-     */
-    remove(id) {
-        const cells = this.obstacleCells.get(id);
-        if (!cells)
-            return;
-        for (const cell of cells) {
-            const bucket = this.grid.get(cell);
-            if (bucket) {
-                bucket.delete(id);
-                if (bucket.size === 0) {
-                    this.grid.delete(cell);
-                }
-            }
-        }
-        this.obstacleCells.delete(id);
-    }
-    /**
-     * Returns obstacle IDs that might contain the given point.
-     */
-    query(pos) {
-        const cell = this.hash(pos.x, pos.y);
-        return this.grid.get(cell) || new Set();
-    }
-    /**
-     * Clears the entire spatial hash.
-     */
-    clear() {
-        this.grid.clear();
-        this.obstacleCells.clear();
-    }
-    /**
-     * Determines which cells an obstacle overlaps.
-     */
-    getCellsForObstacle(o) {
-        const cells = new Set();
-        if (o.type === 'circle') {
-            const r = o.radius;
-            const minX = Math.floor((o.pos.x - r) / this.cellSize);
-            const maxX = Math.floor((o.pos.x + r) / this.cellSize);
-            const minY = Math.floor((o.pos.y - r) / this.cellSize);
-            const maxY = Math.floor((o.pos.y + r) / this.cellSize);
-            for (let x = minX; x <= maxX; x++) {
-                for (let y = minY; y <= maxY; y++) {
-                    cells.add(encodeCell(x, y));
-                }
-            }
-        }
-        else if (o.type === 'rect') {
-            const cx = o.pos.x + o.size.x / 2;
-            const cy = o.pos.y + o.size.y / 2;
-            const hw = o.size.x / 2;
-            const hh = o.size.y / 2;
-            const diagonal = Math.sqrt(hw * hw + hh * hh);
-            const minX = Math.floor((cx - diagonal) / this.cellSize);
-            const maxX = Math.floor((cx + diagonal) / this.cellSize);
-            const minY = Math.floor((cy - diagonal) / this.cellSize);
-            const maxY = Math.floor((cy + diagonal) / this.cellSize);
-            for (let x = minX; x <= maxX; x++) {
-                for (let y = minY; y <= maxY; y++) {
-                    cells.add(encodeCell(x, y));
-                }
-            }
-        }
-        else if (o.type === 'polygon') {
-            const bounds = getPolygonBounds(o);
-            const minX = Math.floor(bounds.minX / this.cellSize);
-            const maxX = Math.floor(bounds.maxX / this.cellSize);
-            const minY = Math.floor(bounds.minY / this.cellSize);
-            const maxY = Math.floor(bounds.maxY / this.cellSize);
-            for (let x = minX; x <= maxX; x++) {
-                for (let y = minY; y <= maxY; y++) {
-                    cells.add(encodeCell(x, y));
-                }
-            }
-        }
-        return cells;
-    }
-}
-/* ---------------------------------- */
-/* Geometry helpers                   */
-/* ---------------------------------- */
-/**
- * Tests if a point is inside a circle obstacle.
- */
-function pointInCircle(p, c) {
-    const dx = p.x - c.pos.x;
-    const dy = p.y - c.pos.y;
-    return dx * dx + dy * dy <= c.radius * c.radius;
-}
-/**
- * Tests if a point is inside a rectangle obstacle.
- * Handles rotation around the rectangle's center.
- */
-function pointInRect(p, r) {
-    const cx = r.pos.x + r.size.x / 2;
-    const cy = r.pos.y + r.size.y / 2;
-    if (r.rotation) {
-        const cos = Math.cos(-r.rotation);
-        const sin = Math.sin(-r.rotation);
-        const dx = p.x - cx;
-        const dy = p.y - cy;
-        const localX = dx * cos - dy * sin;
-        const localY = dx * sin + dy * cos;
-        return Math.abs(localX) <= r.size.x / 2 &&
-            Math.abs(localY) <= r.size.y / 2;
-    }
-    return (p.x >= r.pos.x &&
-        p.y >= r.pos.y &&
-        p.x <= r.pos.x + r.size.x &&
-        p.y <= r.pos.y + r.size.y);
-}
-/**
- * Tests if a point is inside a polygon obstacle using ray casting.
- * REQUIRES: polygon.points are defined relative to local origin (0,0).
- * Uses numerically stable intersection test.
- */
-function pointInPolygon(p, poly) {
-    let inside = false;
-    const pts = poly.points;
-    const cos = poly.rotation ? Math.cos(poly.rotation) : 1;
-    const sin = poly.rotation ? Math.sin(poly.rotation) : 0;
-    for (let i = 0, j = pts.length - 1; i < pts.length; j = i++) {
-        let xi = pts[i].x;
-        let yi = pts[i].y;
-        let xj = pts[j].x;
-        let yj = pts[j].y;
-        if (poly.rotation) {
-            const tempXi = xi * cos - yi * sin;
-            const tempYi = xi * sin + yi * cos;
-            const tempXj = xj * cos - yj * sin;
-            const tempYj = xj * sin + yj * cos;
-            xi = tempXi;
-            yi = tempYi;
-            xj = tempXj;
-            yj = tempYj;
-        }
-        xi += poly.pos.x;
-        yi += poly.pos.y;
-        xj += poly.pos.x;
-        yj += poly.pos.y;
-        // Stable ray casting test
-        const intersect = (yi > p.y) !== (yj > p.y) &&
-            p.x < ((xj - xi) * (p.y - yi)) / (yj - yi) + xi;
-        if (intersect)
-            inside = !inside;
-    }
-    return inside;
-}
-/**
- * Computes axis-aligned bounding box for a transformed polygon.
- */
-function getPolygonBounds(poly) {
-    let minX = Infinity, minY = Infinity;
-    let maxX = -Infinity, maxY = -Infinity;
-    const cos = poly.rotation ? Math.cos(poly.rotation) : 1;
-    const sin = poly.rotation ? Math.sin(poly.rotation) : 0;
-    for (const p of poly.points) {
-        let x = p.x;
-        let y = p.y;
-        if (poly.rotation) {
-            const tx = x * cos - y * sin;
-            const ty = x * sin + y * cos;
-            x = tx;
-            y = ty;
-        }
-        x += poly.pos.x;
-        y += poly.pos.y;
-        minX = Math.min(minX, x);
-        minY = Math.min(minY, y);
-        maxX = Math.max(maxX, x);
-        maxY = Math.max(maxY, y);
-    }
-    return { minX, minY, maxX, maxY };
-}
-/* ---------------------------------- */
-/* Obstacles                          */
-/* ---------------------------------- */
-/**
- * Manages obstacles with spatial hashing for fast queries.
- * Version tracking prevents unnecessary rebuilds.
- */
-class Obstacles {
-    constructor() {
-        this.items = new Map();
-        this.spatial = new SpatialHash(1); // Match grid cell size
-        this._cachedItems = [];
-        this.dirty = true;
-        this.version = 0;
-    }
-    add(obstacle) {
-        const id = genId();
-        const newObstacle = { ...obstacle, id };
-        this.items.set(id, newObstacle);
-        this.spatial.add(id, newObstacle);
-        this.dirty = true;
-        this.version++;
-        return id;
-    }
-    move(id, pos) {
-        const o = this.items.get(id);
-        if (!o)
-            return;
-        // Remove from old position in spatial hash
-        this.spatial.remove(id);
-        // Create updated obstacle
-        const updated = {
-            ...o,
-            pos: { ...pos },
-        };
-        this.items.set(id, updated);
-        this.spatial.add(id, updated);
-        this.dirty = true;
-        this.version++;
-    }
-    remove(id) {
-        this.spatial.remove(id);
-        this.items.delete(id);
-        this.dirty = true;
-        this.version++;
-    }
-    /**
-     * Fast spatial query using hash grid.
-     * O(1) average case instead of O(n) linear scan.
-     */
-    at(pos) {
-        const candidates = this.spatial.query(pos);
-        for (const id of candidates) {
-            const o = this.items.get(id);
-            if (!o || o.solid === false)
-                continue;
-            if (o.type === 'circle' && pointInCircle(pos, o))
-                return o;
-            if (o.type === 'rect' && pointInRect(pos, o))
-                return o;
-            if (o.type === 'polygon' && pointInPolygon(pos, o))
-                return o;
-        }
-    }
-    get values() {
-        if (!this.dirty)
-            return this._cachedItems;
-        this._cachedItems = [...this.items.values()];
-        this.dirty = false;
-        return this._cachedItems;
-    }
-}
-/* ---------------------------------- */
-/* Grid Nav                           */
-/* ---------------------------------- */
-/**
- * Grid navigation with simple full rebuild.
- * Fast enough for most games (< 1000 obstacles).
- *
- * Performance: O(n * area) where n = obstacle count.
- * Typical rebuild time: < 1ms for 100 obstacles on 100x100 grid.
- */
-class GridNav {
-    constructor(obstacles) {
-        this.obstacles = obstacles;
-        this.blocked = new Set();
-    }
-    /**
-     * Rebuilds the entire blocked cell set.
-     * Simple and correct - no incremental complexity.
-     */
-    rebuild() {
-        this.blocked.clear();
-        for (const o of this.obstacles.values) {
-            if (o.solid === false)
-                continue;
-            if (o.type === 'circle') {
-                const r = Math.ceil(o.radius);
-                const cx = Math.floor(o.pos.x);
-                const cy = Math.floor(o.pos.y);
-                for (let dx = -r; dx <= r; dx++) {
-                    for (let dy = -r; dy <= r; dy++) {
-                        const cellX = cx + dx;
-                        const cellY = cy + dy;
-                        const cellCenter = { x: cellX + 0.5, y: cellY + 0.5 };
-                        if (pointInCircle(cellCenter, o)) {
-                            this.blocked.add(encodeCell(cellX, cellY));
-                        }
-                    }
-                }
-            }
-            else if (o.type === 'rect') {
-                const cx = o.pos.x + o.size.x / 2;
-                const cy = o.pos.y + o.size.y / 2;
-                const hw = o.size.x / 2;
-                const hh = o.size.y / 2;
-                const diagonal = Math.sqrt(hw * hw + hh * hh);
-                const minX = Math.floor(cx - diagonal);
-                const maxX = Math.ceil(cx + diagonal);
-                const minY = Math.floor(cy - diagonal);
-                const maxY = Math.ceil(cy + diagonal);
-                for (let x = minX; x <= maxX; x++) {
-                    for (let y = minY; y <= maxY; y++) {
-                        const cellCenter = { x: x + 0.5, y: y + 0.5 };
-                        if (pointInRect(cellCenter, o)) {
-                            this.blocked.add(encodeCell(x, y));
-                        }
-                    }
-                }
-            }
-            else if (o.type === 'polygon') {
-                const bounds = getPolygonBounds(o);
-                const minX = Math.floor(bounds.minX);
-                const maxX = Math.ceil(bounds.maxX);
-                const minY = Math.floor(bounds.minY);
-                const maxY = Math.ceil(bounds.maxY);
-                for (let x = minX; x <= maxX; x++) {
-                    for (let y = minY; y <= maxY; y++) {
-                        const cellCenter = { x: x + 0.5, y: y + 0.5 };
-                        if (pointInPolygon(cellCenter, o)) {
-                            this.blocked.add(encodeCell(x, y));
-                        }
-                    }
-                }
-            }
-        }
-    }
-    findPath(from, to) {
-        return aStar(toCell(from), toCell(to), (x, y) => !this.blocked.has(encodeCell(x, y))).map(fromCell);
-    }
-}
-/* ---------------------------------- */
-/* Graph Nav                          */
-/* ---------------------------------- */
-/**
- * Line-of-sight navigation with grid fallback.
- * Not a true navmesh - use GridNav for production.
- */
-class GraphNav {
-    constructor(obstacles) {
-        this.obstacles = obstacles;
-    }
-    rebuild() { }
-    findPath(from, to) {
-        // Uniform sampling along path for LOS check
-        const steps = Math.ceil(Math.hypot(to.x - from.x, to.y - from.y) * 2);
-        let blocked = false;
-        for (let i = 1; i <= steps; i++) {
-            const t = i / steps;
-            const p = {
-                x: from.x + (to.x - from.x) * t,
-                y: from.y + (to.y - from.y) * t,
-            };
-            if (this.obstacles.at(p)) {
-                blocked = true;
-                break;
-            }
-        }
-        if (!blocked) {
-            return [from, to];
-        }
-        // Fallback to grid A*
-        const cellPath = aStar(toCell(from), toCell(to), (x, y) => {
-            const p = { x: x + 0.5, y: y + 0.5 };
-            return !this.obstacles.at(p);
-        });
-        return cellPath.map(fromCell);
-    }
-}
-/**
- * Navigation mesh with spatial hashing and smart rebuild.
- *
- * Features:
- * - Spatial hash: O(1) obstacle queries
- * - 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, 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.
-     * For polygons: ensure points are defined relative to (0,0).
-     */
-    addObstacle(obstacle) {
-        return this.obstacles.add(obstacle);
-    }
-    /**
-     * Moves an existing obstacle to a new position.
-     */
-    moveObstacle(id, pos) {
-        this.obstacles.move(id, pos);
-    }
-    /**
-     * Removes an obstacle by ID.
-     */
-    removeObstacle(id) {
-        this.obstacles.remove(id);
-    }
-    /**
-     * Returns all current obstacles.
-     */
-    getObstacles() {
-        return this.obstacles.values;
-    }
-    /**
-     * 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'
-            ? this.grid.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.
-     * Version checking eliminates unnecessary work.
-     */
-    rebuild() {
-        if (this.lastVersion === this.obstacles.version)
-            return;
-        this.grid?.rebuild();
-        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*                                 */
-/* ---------------------------------- */
-/**
- * A* pathfinding with binary heap and proper open set tracking.
- *
- * Optimizations:
- * - Binary heap: O(log n) operations
- * - Open set tracking: prevents duplicate nodes
- * - Integer cell encoding: eliminates string allocation
- * - Closed set: avoids reprocessing
- *
- * Performance: Handles 10k+ node searches efficiently.
- * Time: O(b^d * log n) where b = branching, d = depth, n = nodes.
- */
-function aStar(start, goal, walkable) {
-    const cameFrom = new Map();
-    const g = new Map();
-    const closed = new Set();
-    const openSet = new Set();
-    const key = (p) => encodeCell(p.x, p.y);
-    const h = (a, b) => Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
-    const open = new BinaryHeap((nodeKey) => {
-        const pos = decodeCell(nodeKey);
-        return g.get(nodeKey) + h(pos, goal);
-    });
-    const startKey = key(start);
-    g.set(startKey, 0);
-    open.push(startKey);
-    openSet.add(startKey);
-    while (open.size > 0) {
-        const currentKey = open.pop();
-        openSet.delete(currentKey);
-        const current = decodeCell(currentKey);
-        if (current.x === goal.x && current.y === goal.y) {
-            return reconstruct(cameFrom, current);
-        }
-        closed.add(currentKey);
-        for (const d of dirs) {
-            const n = { x: current.x + d.x, y: current.y + d.y };
-            if (!walkable(n.x, n.y))
-                continue;
-            const nk = key(n);
-            if (closed.has(nk))
-                continue;
-            const ng = g.get(currentKey) + 1;
-            if (ng < (g.get(nk) ?? Infinity)) {
-                g.set(nk, ng);
-                cameFrom.set(nk, currentKey);
-                if (!openSet.has(nk)) {
-                    open.push(nk);
-                    openSet.add(nk);
-                }
-            }
-        }
-    }
-    return [];
-}
-/**
- * Reconstructs path from A* came-from map.
- */
-function reconstruct(cameFrom, current) {
-    const path = [current];
-    let k = encodeCell(current.x, current.y);
-    while (cameFrom.has(k)) {
-        k = cameFrom.get(k);
-        path.push(decodeCell(k));
-    }
-    return path.reverse();
-}