@flighthq/spatial 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './spatialIndex';
+export * from './uniformGrid';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './spatialIndex';
+export * from './uniformGrid';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}

package/dist/spatialIndex.d.ts

@@ -0,0 +1,11 @@
+import type { SpatialAabb, SpatialIndex, SpatialIndexBackend, SpatialObjectId, SpatialPair } from '@flighthq/types';
+export declare function clearSpatialIndex(index: Readonly<SpatialIndex>): void;
+export declare function createSpatialIndex(backend?: SpatialIndexBackend): SpatialIndex;
+export declare function insertSpatialObject(index: Readonly<SpatialIndex>, id: SpatialObjectId, bounds: Readonly<SpatialAabb>): void;
+export declare function querySpatialPairs(index: Readonly<SpatialIndex>, out: SpatialPair[]): void;
+export declare function querySpatialPoint(index: Readonly<SpatialIndex>, x: number, y: number, out: SpatialObjectId[]): void;
+export declare function querySpatialRay(index: Readonly<SpatialIndex>, x: number, y: number, dx: number, dy: number, out: SpatialObjectId[]): void;
+export declare function querySpatialRegion(index: Readonly<SpatialIndex>, region: Readonly<SpatialAabb>, out: SpatialObjectId[]): void;
+export declare function removeSpatialObject(index: Readonly<SpatialIndex>, id: SpatialObjectId): void;
+export declare function updateSpatialObject(index: Readonly<SpatialIndex>, id: SpatialObjectId, bounds: Readonly<SpatialAabb>): void;
+//# sourceMappingURL=spatialIndex.d.ts.map

package/dist/spatialIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatialIndex.d.ts","sourceRoot":"","sources":["../src/spatialIndex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKpH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,IAAI,CAErE;AAMD,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAM9E;AAID,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAC5B,IAAI,CAEN;AAKD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,IAAI,CAEzF;AAGD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,EAAE,GAAG,IAAI,CAEnH;AAID,wBAAgB,eAAe,CAC7B,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,eAAe,EAAE,GACrB,IAAI,CAEN;AAGD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC7B,GAAG,EAAE,eAAe,EAAE,GACrB,IAAI,CAEN;AAGD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,eAAe,GAAG,IAAI,CAE5F;AAGD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAC5B,IAAI,CAEN"}

package/dist/spatialIndex.js

@@ -0,0 +1,52 @@
+import { createUniformGridSpatialBackend } from './uniformGrid';
+// Empties the index of all objects while keeping it (and its backend) reusable.
+export function clearSpatialIndex(index) {
+    index.runtime.backend.clearSpatialIndex();
+}
+// Creates a 2D broadphase index. With no backend it defaults to a uniform grid sized for
+// medium-scale scenes; pass an explicit backend (a differently-sized grid, or a future quadtree /
+// sweep-and-prune) to select the structure for the workload. Constructing the default grid happens
+// here, on call — importing the package has no side effect.
+export function createSpatialIndex(backend) {
+    return {
+        runtime: {
+            backend: backend ?? createUniformGridSpatialBackend(DEFAULT_SPATIAL_CELL_SIZE),
+        },
+    };
+}
+// Adds an object to the index under `id` with its current bounds. The bounds are copied; the caller
+// may reuse its own value afterward.
+export function insertSpatialObject(index, id, bounds) {
+    index.runtime.backend.insertSpatialObject(id, bounds);
+}
+// Fills `out` (cleared first) with every deduplicated candidate pair — each unordered pair at most
+// once, never an object with itself. A pair is a broadphase candidate: the two objects are close
+// enough to be worth a narrow-phase test, which the caller (or @flighthq/collision) performs.
+export function querySpatialPairs(index, out) {
+    index.runtime.backend.querySpatialPairs(out);
+}
+// Fills `out` (cleared first) with the ids whose bounds contain the point (`x`,`y`).
+export function querySpatialPoint(index, x, y, out) {
+    index.runtime.backend.querySpatialPoint(x, y, out);
+}
+// Fills `out` (cleared first) with the ids whose bounds the ray from (`x`,`y`) along (`dx`,`dy`)
+// intersects. The direction need not be normalized; the ray is treated as extending forward only.
+export function querySpatialRay(index, x, y, dx, dy, out) {
+    index.runtime.backend.querySpatialRay(x, y, dx, dy, out);
+}
+// Fills `out` (cleared first) with the ids whose bounds overlap `region`.
+export function querySpatialRegion(index, region, out) {
+    index.runtime.backend.querySpatialRegion(region, out);
+}
+// Removes an object from the index. A no-op if the id is not present.
+export function removeSpatialObject(index, id) {
+    index.runtime.backend.removeSpatialObject(id);
+}
+// Moves an already-inserted object to new bounds. Inserting a not-yet-present id behaves as insert.
+export function updateSpatialObject(index, id, bounds) {
+    index.runtime.backend.updateSpatialObject(id, bounds);
+}
+// The default uniform-grid cell size when createSpatialIndex is called without an explicit backend —
+// a middle-of-the-road choice; a workload with a known typical object size should pass its own grid.
+const DEFAULT_SPATIAL_CELL_SIZE = 128;
+//# sourceMappingURL=spatialIndex.js.map

package/dist/spatialIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatialIndex.js","sourceRoot":"","sources":["../src/spatialIndex.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,+BAA+B,EAAE,MAAM,eAAe,CAAC;AAEhE,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,KAA6B;IAC7D,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC;AAC5C,CAAC;AAED,yFAAyF;AACzF,kGAAkG;AAClG,mGAAmG;AACnG,4DAA4D;AAC5D,MAAM,UAAU,kBAAkB,CAAC,OAA6B;IAC9D,OAAO;QACL,OAAO,EAAE;YACP,OAAO,EAAE,OAAO,IAAI,+BAA+B,CAAC,yBAAyB,CAAC;SAC/E;KACF,CAAC;AACJ,CAAC;AAED,oGAAoG;AACpG,qCAAqC;AACrC,MAAM,UAAU,mBAAmB,CACjC,KAA6B,EAC7B,EAAmB,EACnB,MAA6B;IAE7B,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC;AAED,mGAAmG;AACnG,iGAAiG;AACjG,8FAA8F;AAC9F,MAAM,UAAU,iBAAiB,CAAC,KAA6B,EAAE,GAAkB;IACjF,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,iBAAiB,CAAC,KAA6B,EAAE,CAAS,EAAE,CAAS,EAAE,GAAsB;IAC3G,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;AACrD,CAAC;AAED,iGAAiG;AACjG,kGAAkG;AAClG,MAAM,UAAU,eAAe,CAC7B,KAA6B,EAC7B,CAAS,EACT,CAAS,EACT,EAAU,EACV,EAAU,EACV,GAAsB;IAEtB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,kBAAkB,CAChC,KAA6B,EAC7B,MAA6B,EAC7B,GAAsB;IAEtB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACxD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,mBAAmB,CAAC,KAA6B,EAAE,EAAmB;IACpF,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,mBAAmB,CACjC,KAA6B,EAC7B,EAAmB,EACnB,MAA6B;IAE7B,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC;AAED,qGAAqG;AACrG,qGAAqG;AACrG,MAAM,yBAAyB,GAAG,GAAG,CAAC"}

package/dist/uniformGrid.d.ts

@@ -0,0 +1,3 @@
+import type { SpatialIndexBackend } from '@flighthq/types';
+export declare function createUniformGridSpatialBackend(cellSize: number): SpatialIndexBackend;
+//# sourceMappingURL=uniformGrid.d.ts.map

package/dist/uniformGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniformGrid.d.ts","sourceRoot":"","sources":["../src/uniformGrid.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA8B,mBAAmB,EAAgC,MAAM,iBAAiB,CAAC;AASrH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CA0CrF"}

package/dist/uniformGrid.js

@@ -0,0 +1,350 @@
+import { containsRectanglePointXY, intersectsRectangle } from '@flighthq/geometry';
+// Builds a uniform-grid (spatial-hash) backend: an object's AABB is mapped to the rectangular block
+// of fixed-size cells it covers, and each cell holds the ids overlapping it. Co-located objects share
+// a cell, so candidate pairs and region/point/ray hits are found by looking only at the relevant
+// cells instead of scanning every object. `cellSize` is the world-space side length of one cell; a
+// good value is roughly the size of a typical object (too small over-spans large objects across many
+// cells, too large lumps unrelated objects together). No import-time side effect — the caller
+// constructs a grid explicitly, and createSpatialIndex uses this as its default index.
+export function createUniformGridSpatialBackend(cellSize) {
+    const grid = {
+        cellSize,
+        cells: new Map(),
+        bounds: new Map(),
+        minCellX: 0,
+        minCellY: 0,
+        maxCellX: 0,
+        maxCellY: 0,
+        empty: true,
+        seen: new Set(),
+    };
+    return {
+        insertSpatialObject(id, bounds) {
+            _insertIntoGrid(grid, id, bounds);
+        },
+        updateSpatialObject(id, bounds) {
+            _removeFromGrid(grid, id);
+            _insertIntoGrid(grid, id, bounds);
+        },
+        removeSpatialObject(id) {
+            _removeFromGrid(grid, id);
+        },
+        clearSpatialIndex() {
+            grid.cells.clear();
+            grid.bounds.clear();
+            grid.seen.clear();
+            grid.empty = true;
+        },
+        querySpatialPairs(out) {
+            _queryGridPairs(grid, out);
+        },
+        querySpatialRegion(region, out) {
+            _queryGridRegion(grid, region, out);
+        },
+        querySpatialPoint(x, y, out) {
+            _queryGridPoint(grid, x, y, out);
+        },
+        querySpatialRay(x, y, dx, dy, out) {
+            _queryGridRay(grid, x, y, dx, dy, out);
+        },
+    };
+}
+// Maps a world coordinate to its cell index along one axis. Uses floor so negative coordinates map
+// to consistently decreasing cell indices (world 0 is the boundary between cell -1 and cell 0).
+function _cellIndex(coord, cellSize) {
+    return Math.floor(coord / cellSize);
+}
+// The map key for a cell. A string of the two signed integer coordinates — negatives and large
+// magnitudes are represented exactly, unlike a numeric pairing that could overflow or collide.
+function _cellKey(cx, cy) {
+    return `${cx},${cy}`;
+}
+// Fills a scratch RectangleLike (x/y/width/height) from a SpatialAabb (min/max corners) so the
+// geometry rectangle-overlap and point-containment helpers can be reused instead of re-deriving the
+// AABB math here. Assumes a normalized AABB (max >= min); a flipped AABB yields a negative extent,
+// which the geometry helpers still normalize internally.
+function _fillRectFromAabb(out, aabb) {
+    out.x = aabb.minX;
+    out.y = aabb.minY;
+    out.width = aabb.maxX - aabb.minX;
+    out.height = aabb.maxY - aabb.minY;
+}
+// Adds an object to every cell its AABB covers, storing a private copy of the bounds and expanding
+// the occupied cell range. The caller may safely mutate or reuse the passed bounds afterward.
+function _insertIntoGrid(grid, id, bounds) {
+    const cs = grid.cellSize;
+    const cx0 = _cellIndex(bounds.minX, cs);
+    const cx1 = _cellIndex(bounds.maxX, cs);
+    const cy0 = _cellIndex(bounds.minY, cs);
+    const cy1 = _cellIndex(bounds.maxY, cs);
+    grid.bounds.set(id, { minX: bounds.minX, minY: bounds.minY, maxX: bounds.maxX, maxY: bounds.maxY });
+    for (let cy = cy0; cy <= cy1; cy++) {
+        for (let cx = cx0; cx <= cx1; cx++) {
+            const key = _cellKey(cx, cy);
+            let cell = grid.cells.get(key);
+            if (cell === undefined) {
+                cell = { cx, cy, ids: new Set() };
+                grid.cells.set(key, cell);
+            }
+            cell.ids.add(id);
+        }
+    }
+    if (grid.empty) {
+        grid.minCellX = cx0;
+        grid.maxCellX = cx1;
+        grid.minCellY = cy0;
+        grid.maxCellY = cy1;
+        grid.empty = false;
+    }
+    else {
+        if (cx0 < grid.minCellX)
+            grid.minCellX = cx0;
+        if (cx1 > grid.maxCellX)
+            grid.maxCellX = cx1;
+        if (cy0 < grid.minCellY)
+            grid.minCellY = cy0;
+        if (cy1 > grid.maxCellY)
+            grid.maxCellY = cy1;
+    }
+}
+// Reports whether an AABB contains the point (`x`,`y`), reusing the geometry rectangle helper.
+function _isSpatialAabbContainsPoint(aabb, x, y) {
+    _fillRectFromAabb(_scratchRectA, aabb);
+    return containsRectanglePointXY(_scratchRectA, x, y);
+}
+// Reports whether two AABBs overlap, reusing the geometry rectangle-overlap helper (edge-touching
+// counts as disjoint, matching intersectsRectangle).
+function _isSpatialAabbOverlapping(a, b) {
+    _fillRectFromAabb(_scratchRectA, a);
+    _fillRectFromAabb(_scratchRectB, b);
+    return intersectsRectangle(_scratchRectA, _scratchRectB);
+}
+// Slab test for a ray (origin `ox`,`oy`, direction `dx`,`dy`, `t >= 0`) against an axis-aligned box.
+// Returns the entry parameter `t` (0 when the origin is already inside), or -1 when the ray misses
+// the box or the box lies entirely behind the origin. Direction need not be normalized.
+function _rayBoxEntryT(ox, oy, dx, dy, minX, minY, maxX, maxY) {
+    let tmin = -Infinity;
+    let tmax = Infinity;
+    if (dx !== 0) {
+        const inv = 1 / dx;
+        let t1 = (minX - ox) * inv;
+        let t2 = (maxX - ox) * inv;
+        if (t1 > t2) {
+            const t = t1;
+            t1 = t2;
+            t2 = t;
+        }
+        if (t1 > tmin)
+            tmin = t1;
+        if (t2 < tmax)
+            tmax = t2;
+    }
+    else if (ox < minX || ox > maxX) {
+        return -1;
+    }
+    if (dy !== 0) {
+        const inv = 1 / dy;
+        let t1 = (minY - oy) * inv;
+        let t2 = (maxY - oy) * inv;
+        if (t1 > t2) {
+            const t = t1;
+            t1 = t2;
+            t2 = t;
+        }
+        if (t1 > tmin)
+            tmin = t1;
+        if (t2 < tmax)
+            tmax = t2;
+    }
+    else if (oy < minY || oy > maxY) {
+        return -1;
+    }
+    if (tmax < tmin || tmax < 0)
+        return -1;
+    return tmin > 0 ? tmin : 0;
+}
+// Removes an object from every cell its stored AABB covered and drops now-empty cells. The occupied
+// cell range is intentionally not shrunk (only reset when the grid fully empties). A no-op for an
+// unknown id.
+function _removeFromGrid(grid, id) {
+    const bounds = grid.bounds.get(id);
+    if (bounds === undefined)
+        return;
+    const cs = grid.cellSize;
+    const cx0 = _cellIndex(bounds.minX, cs);
+    const cx1 = _cellIndex(bounds.maxX, cs);
+    const cy0 = _cellIndex(bounds.minY, cs);
+    const cy1 = _cellIndex(bounds.maxY, cs);
+    for (let cy = cy0; cy <= cy1; cy++) {
+        for (let cx = cx0; cx <= cx1; cx++) {
+            const key = _cellKey(cx, cy);
+            const cell = grid.cells.get(key);
+            if (cell === undefined)
+                continue;
+            cell.ids.delete(id);
+            if (cell.ids.size === 0)
+                grid.cells.delete(key);
+        }
+    }
+    grid.bounds.delete(id);
+    if (grid.bounds.size === 0)
+        grid.empty = true;
+}
+// Enumerates candidate pairs. Within each cell every co-occupant pair is a candidate, but a pair may
+// share several cells; to emit it exactly once, a pair is emitted only from its canonical cell — the
+// top-left (min x, min y) cell of the two objects' overlapping cell ranges, which both objects are
+// guaranteed to occupy. Ids are ordered a < b so the unordered pair is canonical. A pair is never
+// (a,a). The pair is a broadphase candidate (shared cell locality); the caller confirms real overlap.
+function _queryGridPairs(grid, out) {
+    out.length = 0;
+    const cs = grid.cellSize;
+    for (const cell of grid.cells.values()) {
+        const ids = cell.ids;
+        if (ids.size < 2)
+            continue;
+        const list = [...ids];
+        for (let i = 0; i < list.length; i++) {
+            for (let j = i + 1; j < list.length; j++) {
+                let a = list[i];
+                let b = list[j];
+                if (a > b) {
+                    const t = a;
+                    a = b;
+                    b = t;
+                }
+                const ab = grid.bounds.get(a);
+                const bb = grid.bounds.get(b);
+                if (ab === undefined || bb === undefined)
+                    continue;
+                const canonicalX = Math.max(_cellIndex(ab.minX, cs), _cellIndex(bb.minX, cs));
+                const canonicalY = Math.max(_cellIndex(ab.minY, cs), _cellIndex(bb.minY, cs));
+                if (cell.cx === canonicalX && cell.cy === canonicalY)
+                    out.push({ a, b });
+            }
+        }
+    }
+}
+// Gathers the ids in the cell containing the point, then confirms each against its real bounds. A
+// single cell holds each id at most once, so no dedup pass is needed.
+function _queryGridPoint(grid, x, y, out) {
+    out.length = 0;
+    const cs = grid.cellSize;
+    const cell = grid.cells.get(_cellKey(_cellIndex(x, cs), _cellIndex(y, cs)));
+    if (cell === undefined)
+        return;
+    for (const id of cell.ids) {
+        const bounds = grid.bounds.get(id);
+        if (bounds !== undefined && _isSpatialAabbContainsPoint(bounds, x, y))
+            out.push(id);
+    }
+}
+// Walks the cells the ray crosses (bounded to the occupied cell range) via an amanatides-woo DDA,
+// gathering deduplicated ids, then confirms each against a real ray-vs-AABB slab test — so a cell
+// co-occupant the ray does not actually strike is dropped. A zero-length direction degenerates to a
+// point query at the origin. An empty grid returns nothing.
+function _queryGridRay(grid, ox, oy, dx, dy, out) {
+    out.length = 0;
+    if (grid.empty)
+        return;
+    const cs = grid.cellSize;
+    const seen = grid.seen;
+    seen.clear();
+    if (dx === 0 && dy === 0) {
+        _queryGridPoint(grid, ox, oy, out);
+        return;
+    }
+    const boxMinX = grid.minCellX * cs;
+    const boxMinY = grid.minCellY * cs;
+    const boxMaxX = (grid.maxCellX + 1) * cs;
+    const boxMaxY = (grid.maxCellY + 1) * cs;
+    const tEnter = _rayBoxEntryT(ox, oy, dx, dy, boxMinX, boxMinY, boxMaxX, boxMaxY);
+    if (tEnter < 0)
+        return;
+    const startX = ox + tEnter * dx;
+    const startY = oy + tEnter * dy;
+    let cx = _cellIndex(startX, cs);
+    let cy = _cellIndex(startY, cs);
+    if (cx < grid.minCellX)
+        cx = grid.minCellX;
+    else if (cx > grid.maxCellX)
+        cx = grid.maxCellX;
+    if (cy < grid.minCellY)
+        cy = grid.minCellY;
+    else if (cy > grid.maxCellY)
+        cy = grid.maxCellY;
+    const stepX = dx > 0 ? 1 : dx < 0 ? -1 : 0;
+    const stepY = dy > 0 ? 1 : dy < 0 ? -1 : 0;
+    let tMaxX = Infinity;
+    let tDeltaX = Infinity;
+    if (stepX !== 0) {
+        const boundary = stepX > 0 ? (cx + 1) * cs : cx * cs;
+        tMaxX = (boundary - ox) / dx;
+        tDeltaX = cs / Math.abs(dx);
+    }
+    let tMaxY = Infinity;
+    let tDeltaY = Infinity;
+    if (stepY !== 0) {
+        const boundary = stepY > 0 ? (cy + 1) * cs : cy * cs;
+        tMaxY = (boundary - oy) / dy;
+        tDeltaY = cs / Math.abs(dy);
+    }
+    const maxSteps = grid.maxCellX - grid.minCellX + (grid.maxCellY - grid.minCellY) + 3;
+    for (let step = 0; step <= maxSteps; step++) {
+        if (cx < grid.minCellX || cx > grid.maxCellX || cy < grid.minCellY || cy > grid.maxCellY)
+            break;
+        const cell = grid.cells.get(_cellKey(cx, cy));
+        if (cell !== undefined) {
+            for (const id of cell.ids)
+                seen.add(id);
+        }
+        if (tMaxX < tMaxY) {
+            cx += stepX;
+            tMaxX += tDeltaX;
+        }
+        else {
+            cy += stepY;
+            tMaxY += tDeltaY;
+        }
+    }
+    for (const id of seen) {
+        const bounds = grid.bounds.get(id);
+        if (bounds !== undefined &&
+            _rayBoxEntryT(ox, oy, dx, dy, bounds.minX, bounds.minY, bounds.maxX, bounds.maxY) >= 0) {
+            out.push(id);
+        }
+    }
+}
+// Gathers the ids in every cell the region covers (deduplicated via the reused scratch set), then
+// confirms each against the region's real bounds — so a false cell-mate whose bounds miss the region
+// is dropped.
+function _queryGridRegion(grid, region, out) {
+    out.length = 0;
+    const cs = grid.cellSize;
+    const seen = grid.seen;
+    seen.clear();
+    const cx0 = _cellIndex(region.minX, cs);
+    const cx1 = _cellIndex(region.maxX, cs);
+    const cy0 = _cellIndex(region.minY, cs);
+    const cy1 = _cellIndex(region.maxY, cs);
+    for (let cy = cy0; cy <= cy1; cy++) {
+        for (let cx = cx0; cx <= cx1; cx++) {
+            const cell = grid.cells.get(_cellKey(cx, cy));
+            if (cell === undefined)
+                continue;
+            for (const id of cell.ids) {
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                const bounds = grid.bounds.get(id);
+                if (bounds !== undefined && _isSpatialAabbOverlapping(bounds, region))
+                    out.push(id);
+            }
+        }
+    }
+}
+// Reused scratch rectangles for the geometry overlap/containment helpers. Only ever read+written
+// within a single non-nested helper call, so sharing them across the module allocates nothing per
+// query without aliasing hazard.
+const _scratchRectA = { x: 0, y: 0, width: 0, height: 0 };
+const _scratchRectB = { x: 0, y: 0, width: 0, height: 0 };
+//# sourceMappingURL=uniformGrid.js.map

package/dist/uniformGrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniformGrid.js","sourceRoot":"","sources":["../src/uniformGrid.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/spatial",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/geometry": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "2D broadphase spatial index over object AABBs — candidate-pair, region, point, and ray queries behind a swappable index seam (uniform-grid default), feeding @flighthq/collision narrow-phase",
+  "sideEffects": false
+}

package/src/spatialIndex.test.ts

@@ -0,0 +1,184 @@
+import type { SpatialIndex, SpatialObjectId, SpatialPair } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import {
+  clearSpatialIndex,
+  createSpatialIndex,
+  insertSpatialObject,
+  querySpatialPairs,
+  querySpatialPoint,
+  querySpatialRay,
+  querySpatialRegion,
+  removeSpatialObject,
+  updateSpatialObject,
+} from './spatialIndex';
+import { createUniformGridSpatialBackend } from './uniformGrid';
+
+function makeIndex(cellSize = 10): SpatialIndex {
+  return createSpatialIndex(createUniformGridSpatialBackend(cellSize));
+}
+
+// Sorts pairs into canonical "a-b" strings so a result can be compared as a set regardless of order.
+function pairKeys(pairs: readonly SpatialPair[]): string[] {
+  return pairs.map((p) => `${Math.min(p.a, p.b)}-${Math.max(p.a, p.b)}`).sort();
+}
+
+describe('clearSpatialIndex', () => {
+  it('empties every query after clearing', () => {
+    const index = makeIndex();
+    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 4, maxY: 4 });
+    insertSpatialObject(index, 2, { minX: 2, minY: 2, maxX: 6, maxY: 6 });
+
+    clearSpatialIndex(index);
+
+    const pairs: SpatialPair[] = [];
+    querySpatialPairs(index, pairs);
+    expect(pairs).toHaveLength(0);
+
+    const region: SpatialObjectId[] = [];
+    querySpatialRegion(index, { minX: 0, minY: 0, maxX: 10, maxY: 10 }, region);
+    expect(region).toHaveLength(0);
+
+    const point: SpatialObjectId[] = [];
+    querySpatialPoint(index, 3, 3, point);
+    expect(point).toHaveLength(0);
+  });
+});
+
+describe('createSpatialIndex', () => {
+  it('defaults to a working uniform grid when given no backend', () => {
+    const index = createSpatialIndex();
+    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 4, maxY: 4 });
+    insertSpatialObject(index, 2, { minX: 1, minY: 1, maxX: 5, maxY: 5 });
+
+    const pairs: SpatialPair[] = [];
+    querySpatialPairs(index, pairs);
+    expect(pairKeys(pairs)).toEqual(['1-2']);
+  });
+
+  it('uses an explicitly supplied backend', () => {
+    const index = createSpatialIndex(createUniformGridSpatialBackend(64));
+    insertSpatialObject(index, 7, { minX: 0, minY: 0, maxX: 4, maxY: 4 });
+
+    const point: SpatialObjectId[] = [];
+    querySpatialPoint(index, 2, 2, point);
+    expect(point).toEqual([7]);
+  });
+});
+
+describe('insertSpatialObject', () => {
+  it('yields exactly the one overlapping pair from two overlapping objects and one far object', () => {
+    const index = makeIndex();
+    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 4, maxY: 4 });
+    insertSpatialObject(index, 2, { minX: 2, minY: 2, maxX: 6, maxY: 6 });
+    insertSpatialObject(index, 3, { minX: 100, minY: 100, maxX: 104, maxY: 104 });
+
+    const pairs: SpatialPair[] = [];
+    querySpatialPairs(index, pairs);
+
+    expect(pairs).toHaveLength(1);
+    expect(pairKeys(pairs)).toEqual(['1-2']);
+    for (const pair of pairs) expect(pair.a).not.toBe(pair.b);
+  });
+});
+
+describe('querySpatialPairs', () => {
+  it('reuses and clears the out array across calls', () => {
+    const index = makeIndex();
+    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 4, maxY: 4 });
+    insertSpatialObject(index, 2, { minX: 2, minY: 2, maxX: 6, maxY: 6 });
+
+    const out: SpatialPair[] = [];
+    querySpatialPairs(index, out);
+    expect(out).toHaveLength(1);
+
+    removeSpatialObject(index, 2);
+    querySpatialPairs(index, out);
+    expect(out).toHaveLength(0);
+  });
+});
+
+describe('querySpatialPoint', () => {
+  it('returns an object at an interior point and nothing at an empty point', () => {
+    const index = makeIndex();
+    insertSpatialObject(index, 1, { minX: 1, minY: 1, maxX: 3, maxY: 3 });
+    insertSpatialObject(index, 2, { minX: 8, minY: 8, maxX: 9, maxY: 9 });
+
+    const inside: SpatialObjectId[] = [];
+    querySpatialPoint(index, 2, 2, inside);
+    expect(inside).toEqual([1]);
+
+    const outside: SpatialObjectId[] = [];
+    querySpatialPoint(index, 6, 6, outside);
+    expect(outside).toHaveLength(0);
+  });
+});
+
+describe('querySpatialRay', () => {
+  it('returns an object the ray crosses and nothing for a ray that misses', () => {
+    const index = makeIndex();
+    insertSpatialObject(index, 1, { minX: 20, minY: 20, maxX: 24, maxY: 24 });
+
+    const hit: SpatialObjectId[] = [];
+    querySpatialRay(index, 0, 22, 1, 0, hit);
+    expect(hit).toEqual([1]);
+
+    const miss: SpatialObjectId[] = [];
+    querySpatialRay(index, 0, 0, 1, 0, miss);
+    expect(miss).toHaveLength(0);
+  });
+});
+
+describe('querySpatialRegion', () => {
+  it('includes overlapping bounds and excludes a cell-mate whose bounds miss the region', () => {
+    const index = makeIndex();
+    // Both objects share grid cell (0,0), but only object 1 actually overlaps the query region.
+    insertSpatialObject(index, 1, { minX: 1, minY: 1, maxX: 3, maxY: 3 });
+    insertSpatialObject(index, 2, { minX: 8, minY: 8, maxX: 9, maxY: 9 });
+
+    const out: SpatialObjectId[] = [];
+    querySpatialRegion(index, { minX: 0, minY: 0, maxX: 4, maxY: 4 }, out);
+
+    expect(out).toEqual([1]);
+  });
+});
+
+describe('removeSpatialObject', () => {
+  it('drops the object from pair, region, and point queries', () => {
+    const index = makeIndex();
+    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 4, maxY: 4 });
+    insertSpatialObject(index, 2, { minX: 2, minY: 2, maxX: 6, maxY: 6 });
+
+    removeSpatialObject(index, 2);
+
+    const pairs: SpatialPair[] = [];
+    querySpatialPairs(index, pairs);
+    expect(pairs).toHaveLength(0);
+
+    const region: SpatialObjectId[] = [];
+    querySpatialRegion(index, { minX: 0, minY: 0, maxX: 6, maxY: 6 }, region);
+    expect(region).toEqual([1]);
+
+    const point: SpatialObjectId[] = [];
+    querySpatialPoint(index, 5, 5, point);
+    expect(point).toHaveLength(0);
+  });
+});
+
+describe('updateSpatialObject', () => {
+  it('removes a pair once the moved object leaves the shared region', () => {
+    const index = makeIndex();
+    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 4, maxY: 4 });
+    insertSpatialObject(index, 2, { minX: 2, minY: 2, maxX: 6, maxY: 6 });
+
+    const before: SpatialPair[] = [];
+    querySpatialPairs(index, before);
+    expect(before).toHaveLength(1);
+
+    updateSpatialObject(index, 2, { minX: 200, minY: 200, maxX: 204, maxY: 204 });
+
+    const after: SpatialPair[] = [];
+    querySpatialPairs(index, after);
+    expect(after).toHaveLength(0);
+  });
+});

package/src/uniformGrid.test.ts

@@ -0,0 +1,97 @@
+import type { SpatialAabb, SpatialObjectId, SpatialPair } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createUniformGridSpatialBackend } from './uniformGrid';
+
+// A plain AABB-overlap confirmation used to turn broadphase candidate pairs into confirmed pairs (the
+// narrow-phase stand-in): exactly the check the caller would apply downstream.
+function boundsOverlap(a: Readonly<SpatialAabb>, b: Readonly<SpatialAabb>): boolean {
+  return a.minX < b.maxX && a.maxX > b.minX && a.minY < b.maxY && a.maxY > b.minY;
+}
+
+function pairKeys(pairs: readonly SpatialPair[]): string[] {
+  return pairs.map((p) => `${Math.min(p.a, p.b)}-${Math.max(p.a, p.b)}`).sort();
+}
+
+describe('createUniformGridSpatialBackend', () => {
+  it('emits a pair spanning several shared cells exactly once', () => {
+    const grid = createUniformGridSpatialBackend(10);
+    // Both objects cover the same 3x3 block of cells (0..2, 0..2), so they co-occupy nine cells.
+    grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 25, maxY: 25 });
+    grid.insertSpatialObject(2, { minX: 5, minY: 5, maxX: 29, maxY: 29 });
+
+    const pairs: SpatialPair[] = [];
+    grid.querySpatialPairs(pairs);
+
+    expect(pairs).toHaveLength(1);
+    expect(pairKeys(pairs)).toEqual(['1-2']);
+  });
+
+  it('never pairs an object with itself', () => {
+    const grid = createUniformGridSpatialBackend(10);
+    grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 4, maxY: 4 });
+
+    const pairs: SpatialPair[] = [];
+    grid.querySpatialPairs(pairs);
+    expect(pairs).toHaveLength(0);
+  });
+
+  it('returns nothing from every query on an empty grid', () => {
+    const grid = createUniformGridSpatialBackend(10);
+
+    const pairs: SpatialPair[] = [];
+    grid.querySpatialPairs(pairs);
+    expect(pairs).toHaveLength(0);
+
+    const region: SpatialObjectId[] = [];
+    grid.querySpatialRegion({ minX: -50, minY: -50, maxX: 50, maxY: 50 }, region);
+    expect(region).toHaveLength(0);
+
+    const point: SpatialObjectId[] = [];
+    grid.querySpatialPoint(0, 0, point);
+    expect(point).toHaveLength(0);
+
+    const ray: SpatialObjectId[] = [];
+    grid.querySpatialRay(0, 0, 1, 1, ray);
+    expect(ray).toHaveLength(0);
+  });
+
+  it('indexes objects at negative coordinates', () => {
+    const grid = createUniformGridSpatialBackend(10);
+    grid.insertSpatialObject(1, { minX: -8, minY: -8, maxX: -4, maxY: -4 });
+    grid.insertSpatialObject(2, { minX: -6, minY: -6, maxX: -2, maxY: -2 });
+
+    const pairs: SpatialPair[] = [];
+    grid.querySpatialPairs(pairs);
+    expect(pairKeys(pairs)).toEqual(['1-2']);
+
+    const point: SpatialObjectId[] = [];
+    grid.querySpatialPoint(-5, -5, point);
+    expect(point.sort()).toEqual([1, 2]);
+  });
+
+  it('gives the same confirmed pairs across different cell sizes', () => {
+    const objects: { id: SpatialObjectId; bounds: SpatialAabb }[] = [
+      { id: 1, bounds: { minX: 0, minY: 0, maxX: 10, maxY: 10 } },
+      { id: 2, bounds: { minX: 5, minY: 5, maxX: 15, maxY: 15 } },
+      { id: 3, bounds: { minX: 12, minY: 12, maxX: 20, maxY: 20 } },
+      { id: 4, bounds: { minX: 100, minY: 100, maxX: 110, maxY: 110 } },
+    ];
+    const boundsOf = new Map(objects.map((o) => [o.id, o.bounds]));
+
+    function confirmedPairs(cellSize: number): string[] {
+      const grid = createUniformGridSpatialBackend(cellSize);
+      for (const o of objects) grid.insertSpatialObject(o.id, o.bounds);
+      const candidates: SpatialPair[] = [];
+      grid.querySpatialPairs(candidates);
+      const confirmed = candidates.filter((p) => boundsOverlap(boundsOf.get(p.a)!, boundsOf.get(p.b)!));
+      return pairKeys(confirmed);
+    }
+
+    const fine = confirmedPairs(10);
+    const coarse = confirmedPairs(64);
+
+    expect(fine).toEqual(['1-2', '2-3']);
+    expect(coarse).toEqual(fine);
+  });
+});