@playcanvas/splat-transform 2.0.3 → 2.0.4

package/dist/lib/gpu/gpu-dilation.d.ts

@@ -0,0 +1,87 @@
+import { GraphicsDevice } from 'playcanvas';
+import type { SparseVoxelGrid } from '../voxel/sparse-voxel-grid';
+/**
+ * Separable 3D dilation on the GPU using a row-aligned dense bit grid
+ * (1 bit per voxel, packed into u32 words; each row of bits along X starts
+ * on a word boundary so per-word access is trivial). Each pass owns its
+ * own `Compute` instance because their uniform buffers must not collide
+ * within a single submit.
+ */
+declare class GpuDilation {
+    private device;
+    private dilateXShader;
+    private dilateYZShader;
+    private clearShader;
+    private extractShader;
+    private compactShader;
+    private dilateXBindGroupFormat;
+    private dilateYZBindGroupFormat;
+    private clearBindGroupFormat;
+    private extractBindGroupFormat;
+    private compactBindGroupFormat;
+    private slots;
+    private srcTypesBuffer;
+    private srcKeysBuffer;
+    private srcLoBuffer;
+    private srcHiBuffer;
+    private srcTypesCapacity;
+    private srcMasksCapacity;
+    private srcMeta;
+    /** Number of double-buffered dispatch slots. */
+    static readonly NUM_SLOTS = 2;
+    constructor(device: GraphicsDevice);
+    private ensureSlotBuffers;
+    /**
+     * Dispatch a compute clear of `dst` to zero for the first `numWords` words.
+     * Uses the command encoder so it's correctly ordered with subsequent
+     * dilation passes (unlike `queue.writeBuffer`, which is queued separately
+     * and would race against the dispatches).
+     * @param slot - Per-chunk slot whose `clearCompute` pipeline is dispatched.
+     * @param dst - Destination buffer to zero.
+     * @param numWords - Number of leading u32 words to clear.
+     */
+    private dispatchClear;
+    /**
+     * Upload a `SparseVoxelGrid` to GPU storage buffers used by the extract
+     * shader. Reuses the existing buffers if they're large enough; otherwise
+     * destroys and reallocates. Designed to be called once per
+     * `gpuDilate3` call (the same `src` is read across all chunks).
+     * @param src - Source sparse grid to upload.
+     */
+    uploadSrc(src: SparseVoxelGrid): void;
+    /** Free uploaded `src` buffers. Caller can call after `gpuDilate3` finishes. */
+    releaseSrc(): void;
+    private ensureSlotOutputBuffers;
+    /**
+     * Sparse-path submit. Reads from the previously-uploaded `src` (via
+     * `uploadSrc`), runs extract → dilate → compact as GPU passes, and returns
+     * Promises for the per-block `typesOut` (packed 2-bit) and `masksOut`
+     * (lo/hi pairs). Caller integrates these into `dst` directly.
+     * @param slotIdx - Round-robin slot index (`0..NUM_SLOTS-1`).
+     * @param minBx - Outer chunk origin block X (in `src`'s block coords).
+     * @param minBy - Outer chunk origin block Y.
+     * @param minBz - Outer chunk origin block Z.
+     * @param outerBx - Outer chunk size in blocks along X.
+     * @param outerBy - Outer chunk size in blocks along Y.
+     * @param outerBz - Outer chunk size in blocks along Z.
+     * @param haloBx - Halo size in blocks along X (one side).
+     * @param haloBy - Halo size in blocks along Y (one side).
+     * @param haloBz - Halo size in blocks along Z (one side).
+     * @param innerBx - Inner (output) region size in blocks along X.
+     * @param innerBy - Inner region size in blocks along Y.
+     * @param innerBz - Inner region size in blocks along Z.
+     * @param halfExtentXZ - Dilation half-extent in voxels along X and Z.
+     * @param halfExtentY - Dilation half-extent in voxels along Y.
+     * @returns Promises for the inner region's packed types and `[lo, hi]` masks.
+     */
+    submitChunkSparse(slotIdx: number, minBx: number, minBy: number, minBz: number, outerBx: number, outerBy: number, outerBz: number, haloBx: number, haloBy: number, haloBz: number, innerBx: number, innerBy: number, innerBz: number, halfExtentXZ: number, halfExtentY: number): {
+        types: Promise<Uint32Array>;
+        masks: Promise<Uint32Array>;
+    };
+    private dispatchExtract;
+    private dispatchCompact;
+    private dispatchX;
+    private dispatchYZ;
+    destroy(): void;
+}
+export { GpuDilation };

package/dist/lib/gpu/gpu-voxelization.d.ts

@@ -49,9 +49,10 @@ declare class GpuVoxelization {
     private gaussianBuffer;
     private slots;
     private totalGaussians;
-    private zeroBuffer;
     /** Floats per Gaussian in the interleaved buffer (16 for alignment) */
     private static readonly FLOATS_PER_GAUSSIAN;
+    /** Gaussian rows per CPU staging chunk when uploading to the shared GPU buffer. */
+    private static readonly UPLOAD_CHUNK_GAUSSIANS;
     /** Maximum blocks per batch (16^3 = 4096 for 4x4x4 voxel blocks in a 16-block batch) */
     static readonly MAX_BLOCKS_PER_BATCH = 4096;
     /** Number of u32 fields per BatchInfo struct */

package/dist/lib/gpu/index.d.ts

@@ -1,3 +1,4 @@
 export { GpuClustering } from './gpu-clustering';
+export { GpuDilation } from './gpu-dilation';
 export { GpuVoxelization } from './gpu-voxelization';
 export type { BatchSpec, MultiBatchResult } from './gpu-voxelization';

package/dist/lib/index.d.cts

@@ -17,5 +17,5 @@ export { writeSog, writePly, writeCompressedPly, writeCsv, writeHtml, writeLod,
 export type { WriteVoxelOptions, VoxelMetadata } from './writers';
 export { carve, fillExterior, fillFloor, filterCluster, filterFloaters, findClusterVoxelFlood, voxelizeToBuffer } from './voxel';
 export type { NavSeed, NavSimplifyResult } from './voxel';
-export type { Options, Param, DeviceCreator } from './types';
+export type { CollisionMeshShape, Options, Param, DeviceCreator } from './types';
 export { version, revision } from './version';

package/dist/lib/index.d.ts

@@ -17,5 +17,5 @@ export { writeSog, writePly, writeCompressedPly, writeCsv, writeHtml, writeLod,
 export type { WriteVoxelOptions, VoxelMetadata } from './writers';
 export { carve, fillExterior, fillFloor, filterCluster, filterFloaters, findClusterVoxelFlood, voxelizeToBuffer } from './voxel';
 export type { NavSeed, NavSimplifyResult } from './voxel';
-export type { Options, Param, DeviceCreator } from './types';
+export type { CollisionMeshShape, Options, Param, DeviceCreator } from './types';
 export { version, revision } from './version';

package/dist/lib/io/write/memory-file-system.d.ts

@@ -17,6 +17,6 @@ import { type FileSystem, type Writer } from './file-system';
 declare class MemoryFileSystem implements FileSystem {
     results: Map<string, Uint8Array>;
     createWriter(filename: string): Writer;
-    mkdir(path: string): Promise<void>;
+    mkdir(_path: string): Promise<void>;
 }
 export { MemoryFileSystem };

package/dist/lib/mesh/index.d.ts

@@ -1,3 +1,4 @@
 export { marchingCubes } from './marching-cubes';
-export type { Mesh, MarchingCubesMesh } from './marching-cubes';
+export type { Mesh, MarchingCubesMesh, MarchingCubesOptions } from './marching-cubes';
 export { coplanarMerge } from './coplanar-merge';
+export { voxelFaces } from './voxel-faces';

package/dist/lib/mesh/marching-cubes.d.ts

@@ -1,5 +1,5 @@
 import type { Bounds } from '../data-table';
-import { BlockMaskBuffer } from '../voxel/block-mask-buffer';
+import { SparseVoxelGrid } from '../voxel/sparse-voxel-grid';
 /**
  * A simple triangle mesh with positions and indices.
  */
@@ -14,17 +14,30 @@ interface Mesh {
  */
 type MarchingCubesMesh = Mesh;
 /**
- * Extract a triangle mesh from a BlockMaskBuffer using marching cubes.
+ * Options for marching cubes extraction.
+ */
+interface MarchingCubesOptions {
+    /**
+     * Pre-merge exact full-face cells on flat axis-aligned regions before
+     * creating the mesh. Ambiguous and bevel cases still use normal marching
+     * cubes, so coplanarMerge can apply the final lossless optimization.
+     */
+    mergeFlatFaces?: boolean;
+}
+/**
+ * Extract a triangle mesh from a SparseVoxelGrid using marching cubes.
  *
  * Each voxel is treated as a cell in the marching cubes grid. Corner values
  * are binary (0 = empty, 1 = occupied) with a 0.5 threshold. Vertices are
- * placed at edge midpoints, producing a mesh that follows voxel boundaries.
+ * placed at edge midpoints, producing the binary-field isosurface between
+ * occupied and empty samples.
  *
- * @param buffer - Voxel block data after filtering
+ * @param grid - Voxel grid (after filtering / nav phases)
  * @param gridBounds - Grid bounds aligned to block boundaries
  * @param voxelResolution - Size of each voxel in world units
+ * @param options - Optional extraction settings
  * @returns Mesh with positions and indices
  */
-declare function marchingCubes(buffer: BlockMaskBuffer, gridBounds: Bounds, voxelResolution: number): MarchingCubesMesh;
+declare function marchingCubes(grid: SparseVoxelGrid, gridBounds: Bounds, voxelResolution: number, options?: MarchingCubesOptions): MarchingCubesMesh;
 export { marchingCubes };
-export type { Mesh, MarchingCubesMesh };
+export type { Mesh, MarchingCubesMesh, MarchingCubesOptions };

package/dist/lib/mesh/voxel-faces.d.ts

@@ -0,0 +1,18 @@
+import type { Bounds } from '../data-table';
+import type { Mesh } from './marching-cubes';
+import { SparseVoxelGrid } from '../voxel/sparse-voxel-grid';
+/**
+ * Extract a watertight voxel-boundary mesh from a SparseVoxelGrid.
+ *
+ * Exposed voxel faces are first greedily merged into axis-aligned rectangles.
+ * Rectangle boundaries are then split at every collinear rectangle corner
+ * before triangulation, so adjacent rectangles share matching edges instead
+ * of producing T-junctions.
+ *
+ * @param grid - Voxel grid after filtering / nav phases.
+ * @param gridBounds - Grid bounds aligned to block boundaries.
+ * @param voxelResolution - Size of each voxel in world units.
+ * @returns Mesh with positions and indices.
+ */
+declare const voxelFaces: (grid: SparseVoxelGrid, gridBounds: Bounds, voxelResolution: number) => Mesh;
+export { voxelFaces };

package/dist/lib/spatial/gaussian-bvh.d.ts

@@ -86,6 +86,24 @@ declare class GaussianBVH {
      * @returns Array of Gaussian indices that overlap the box
      */
     queryOverlappingRaw(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number[];
+    /**
+     * Query overlapping Gaussian indices directly into a caller-provided buffer.
+     *
+     * Returns the total number of matches even if the target buffer is too
+     * small; in that case only the prefix that fits is written and the caller
+     * can grow the buffer then retry.
+     *
+     * @param minX - Minimum X of query box
+     * @param minY - Minimum Y of query box
+     * @param minZ - Minimum Z of query box
+     * @param maxX - Maximum X of query box
+     * @param maxY - Maximum Y of query box
+     * @param maxZ - Maximum Z of query box
+     * @param result - Buffer to append matching Gaussian indices into.
+     * @param offset - Starting element offset in `result`.
+     * @returns Number of matching Gaussian indices.
+     */
+    queryOverlappingRawInto(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, result: Uint32Array, offset: number): number;
     /**
      * Recursive query helper.
      *
@@ -99,6 +117,22 @@ declare class GaussianBVH {
      * @param result - Array to append matching indices to
      */
     private queryNode;
+    /**
+     * Recursive typed-buffer query helper.
+     *
+     * @param node - Current BVH node to query
+     * @param minX - Query box minimum X
+     * @param minY - Query box minimum Y
+     * @param minZ - Query box minimum Z
+     * @param maxX - Query box maximum X
+     * @param maxY - Query box maximum Y
+     * @param maxZ - Query box maximum Z
+     * @param result - Buffer to append matching indices into
+     * @param offset - Starting element offset in `result`
+     * @param count - Number of matches already found for this query
+     * @returns Updated match count
+     */
+    private queryNodeInto;
     /**
      * Get the total number of Gaussians in the BVH.
      *

package/dist/lib/types.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Collision mesh shape generated alongside voxel output.
+ *
+ * - `smooth` - marching cubes with lossless coplanar merge.
+ * - `faces` - direct watertight voxel-boundary faces.
+ */
+type CollisionMeshShape = 'smooth' | 'faces';
 /**
  * Options for read/write operations.
  */
@@ -35,8 +42,8 @@ type Options = {
         y: number;
         z: number;
     };
-    /** When `true`, a collision mesh (.collision.glb) is generated alongside the voxel output, using marching cubes followed by lossless coplanar merge. */
-    collisionMesh?: boolean;
+    /** When set, a collision mesh (.collision.glb) is generated alongside the voxel output. `true` is equivalent to `smooth`. */
+    collisionMesh?: boolean | CollisionMeshShape;
 };
 /**
  * Parameter passed to MJS generator scripts.
@@ -55,4 +62,4 @@ type Param = {
  * @returns Promise resolving to a GraphicsDevice instance.
  */
 type DeviceCreator = () => Promise<import('playcanvas').GraphicsDevice>;
-export type { Options, Param, DeviceCreator };
+export type { CollisionMeshShape, Options, Param, DeviceCreator };

package/dist/lib/utils/math.d.ts

@@ -92,7 +92,8 @@ declare class Transform {
     static IDENTITY: Readonly<Transform>;
     /**
      * PLY coordinate convention: 180-degree rotation around Z.
-     * Used by PLY, splat, KSplat, SPZ, and legacy SOG formats.
+     * Used by formats that store Gaussian data in PLY-style coordinates:
+     * PLY, splat, KSplat, SPZ, and SOG.
      */
     static PLY: Readonly<Transform>;
 }

package/dist/lib/voxel/block-cleanup.d.ts

@@ -9,8 +9,11 @@ import { BlockMaskBuffer } from './block-mask-buffer';
  *
  * Blocks that become empty or solid as a consequence are handled automatically.
  *
- * @param buffer - BlockMaskBuffer with voxelization results
- * @returns New BlockMaskBuffer with filtered/filled data
+ * @param buffer - BlockMaskBuffer with voxelization results (linear-keyed).
+ * @param nbx - Grid block dimension X (used to decode block indices).
+ * @param nby - Grid block dimension Y (used to decode block indices).
+ * @param nbz - Grid block dimension Z (used for neighbor bounds checks).
+ * @returns New BlockMaskBuffer with filtered/filled data.
  */
-declare function filterAndFillBlocks(buffer: BlockMaskBuffer): BlockMaskBuffer;
+declare function filterAndFillBlocks(buffer: BlockMaskBuffer, nbx: number, nby: number, nbz: number): BlockMaskBuffer;
 export { filterAndFillBlocks };

package/dist/lib/voxel/block-mask-buffer.d.ts

@@ -1,24 +1,23 @@
 /**
  * Append-only buffer for streaming voxelization results.
- * Stores block masks using Morton codes for efficient octree construction.
+ * Stores (linear blockIdx, voxel mask) pairs for non-empty 4x4x4 blocks.
  *
- * Backed by typed arrays that grow geometrically. Morton codes use
- * Float64Array (51 bits of precision needed; exceeds Smi range), and
- * voxel masks use Uint32Array. This raises the per-buffer capacity well
- * above V8's regular-array backing-store limit so very large grids can
- * round-trip without throwing `RangeError: Invalid array length`.
+ * Block keys are linear block indices `bx + by*nbx + bz*nbx*nby` in the
+ * producer's grid coordinate system. Producers and consumers must agree
+ * on the grid dimensions; the buffer itself is dimension-agnostic.
  *
- * Buffers start at length 0 and the first `addBlock` allocates
- * `INITIAL_CAPACITY` entries; subsequent grows double. A freshly cleared
- * instance therefore retains no allocations until it is reused.
+ * Backed by typed arrays that grow geometrically. Keys use Float64Array so
+ * the per-buffer capacity exceeds V8's regular-array backing-store limit
+ * (large grids exceed Smi range and would throw `RangeError: Invalid array
+ * length` with a regular array).
  */
 declare class BlockMaskBuffer {
-    /** Morton codes for solid blocks (mask is implicitly all 1s) */
-    private _solidMorton;
+    /** Linear block indices for solid blocks (mask is implicitly all 1s) */
+    private _solidIdx;
     private _solidCount;
     private _solidCap;
-    /** Morton codes for mixed blocks */
-    private _mixedMorton;
+    /** Linear block indices for mixed blocks */
+    private _mixedIdx;
     private _mixedCount;
     private _mixedCap;
     /** Interleaved voxel masks for mixed blocks: [lo0, hi0, lo1, hi1, ...] */
@@ -27,25 +26,25 @@ declare class BlockMaskBuffer {
      * Add a non-empty block to the buffer.
      * Automatically classifies as solid or mixed based on mask values.
      *
-     * @param morton - Morton code encoding block position
+     * @param blockIdx - Linear block index (`bx + by*nbx + bz*nbx*nby`)
      * @param lo - Lower 32 bits of voxel mask
      * @param hi - Upper 32 bits of voxel mask
      */
-    addBlock(morton: number, lo: number, hi: number): void;
+    addBlock(blockIdx: number, lo: number, hi: number): void;
     /**
      * Get all mixed blocks as views into the underlying buffers.
-     * Index `i` of `morton` corresponds to mask pair `(masks[i*2], masks[i*2+1])`.
+     * Index `i` of `blockIdx` corresponds to mask pair `(masks[i*2], masks[i*2+1])`.
      *
-     * @returns Object with morton codes and interleaved masks
+     * @returns Object with linear block indices and interleaved masks
      */
     getMixedBlocks(): {
-        morton: Float64Array;
+        blockIdx: Float64Array;
         masks: Uint32Array;
     };
     /**
      * Get all solid blocks as a view into the underlying buffer.
      *
-     * @returns Array of Morton codes
+     * @returns Array of linear block indices
      */
     getSolidBlocks(): Float64Array;
     /**

package/dist/lib/voxel/block-mask-map.d.ts

@@ -51,6 +51,11 @@ declare class BlockMaskMap {
     removeAt(slot: number): void;
     delete(key: number): void;
     clear(): void;
+    /**
+     * Release all backing storage. The map should not be used again except by
+     * replacing it with a new instance.
+     */
+    releaseStorage(): void;
     forEach(fn: (key: number, lo: number, hi: number) => void): void;
     clone(): BlockMaskMap;
     private _grow;

package/dist/lib/voxel/carve.d.ts

@@ -1,5 +1,6 @@
-import { BlockMaskBuffer } from './block-mask-buffer';
 import type { NavSeed, NavSimplifyResult } from './fill-exterior';
 import type { Bounds } from '../data-table';
-declare const carve: (buffer: BlockMaskBuffer, gridBounds: Bounds, voxelResolution: number, capsuleHeight: number, capsuleRadius: number, seed: NavSeed) => NavSimplifyResult;
+import type { GpuDilation } from '../gpu';
+import { SparseVoxelGrid } from './sparse-voxel-grid';
+declare const carve: (gridA: SparseVoxelGrid, gridBounds: Bounds, voxelResolution: number, capsuleHeight: number, capsuleRadius: number, seed: NavSeed, gpu: GpuDilation) => Promise<NavSimplifyResult>;
 export { carve };

package/dist/lib/voxel/dilation.d.ts

@@ -1,22 +1,19 @@
 import { SparseVoxelGrid } from './sparse-voxel-grid';
+import { GpuDilation } from '../gpu';
 /**
- * 3D dilation by separable 1D passes (X then Z then Y).
+ * GPU separable 3D dilation. Chunks the grid into block-aligned inner regions plus
+ * a halo on each side, runs three GPU passes per chunk, and OR's the
+ * dilated inner region into a fresh destination `SparseVoxelGrid`.
  *
- * Allocates one fresh working grid (`a`) and uses one more (`b`) for the
- * intermediate. When `consumeSrc` is true the caller relinquishes `src`
- * — it gets cleared and reused as the second working grid, saving one
- * full SparseVoxelGrid allocation per call. After the function returns
- * with `consumeSrc=true`, `src` references an empty grid and must not
- * be read by the caller.
+ * The exact requested half-extents are passed to the dilation shaders. The
+ * sparse extraction halo is rounded up to the next 4-voxel block boundary so
+ * chunk extract/compact math remains block-aligned without over-dilating.
  *
- * @param src - Input grid. Read-only when `consumeSrc=false`; consumed
- * (cleared and used as scratch) when `consumeSrc=true`.
+ * @param gpu - Reusable GPU dilation context (compiled shader + buffers).
+ * @param src - Input sparse grid (read-only across the call).
  * @param halfExtentXZ - Dilation half-extent in voxels along X and Z.
  * @param halfExtentY - Dilation half-extent in voxels along Y.
- * @param consumeSrc - If true, the function may reuse `src`'s memory as
- * a working buffer. Saves ~one full grid's worth of allocation. The
- * caller must not read `src` after the call.
- * @returns Newly allocated dilated grid.
+ * @returns Newly allocated dilated sparse grid.
  */
-declare function sparseDilate3(src: SparseVoxelGrid, halfExtentXZ: number, halfExtentY: number, consumeSrc?: boolean): SparseVoxelGrid;
-export { sparseDilate3 };
+declare function gpuDilate3(gpu: GpuDilation, src: SparseVoxelGrid, halfExtentXZ: number, halfExtentY: number): Promise<SparseVoxelGrid>;
+export { gpuDilate3 };

package/dist/lib/voxel/fill-exterior.d.ts

@@ -1,14 +1,15 @@
-import { BlockMaskBuffer } from './block-mask-buffer';
 import type { Bounds } from '../data-table';
+import type { GpuDilation } from '../gpu';
+import { SparseVoxelGrid } from './sparse-voxel-grid';
 type NavSeed = {
     x: number;
     y: number;
     z: number;
 };
 type NavSimplifyResult = {
-    buffer: BlockMaskBuffer;
+    grid: SparseVoxelGrid;
     gridBounds: Bounds;
 };
-declare const fillExterior: (buffer: BlockMaskBuffer, gridBounds: Bounds, voxelResolution: number, dilation: number, seed: NavSeed) => NavSimplifyResult;
+declare const fillExterior: (gridOriginal: SparseVoxelGrid, gridBounds: Bounds, voxelResolution: number, dilation: number, seed: NavSeed, gpu: GpuDilation) => Promise<NavSimplifyResult>;
 export { fillExterior };
 export type { NavSeed, NavSimplifyResult };

package/dist/lib/voxel/fill-floor.d.ts

@@ -1,6 +1,7 @@
-import { BlockMaskBuffer } from './block-mask-buffer';
 import type { NavSimplifyResult } from './fill-exterior';
 import type { Bounds } from '../data-table';
+import type { GpuDilation } from '../gpu';
+import { SparseVoxelGrid } from './sparse-voxel-grid';
 /**
  * Floor-fill via XZ dilate -> per-column upward walk -> XZ dilate -> OR.
  *
@@ -9,12 +10,12 @@ import type { Bounds } from '../data-table';
  * 3D boundary BFS, and the dilations operate only in X and Z.
  *
  * Steps with `r = ceil(dilation / voxelResolution)`:
- *   1. `S_xz = sparseDilate3(S, r, 0)` closes any XZ holes in horizontal
+ *   1. `S_xz = gpuDilate3(S, r, 0)` closes any XZ holes in horizontal
  *      surfaces smaller than `2 * r`.
  *   2. For every (lx, lz), walk `y = 0` upward through `S_xz`. Mark each
  *      visited empty voxel into `foundEmpty`. Stop on the first solid voxel
  *      of `S_xz` or at the grid top.
- *   3. `dilatedFound = sparseDilate3(foundEmpty, r, 0)` spreads the found
+ *   3. `dilatedFound = gpuDilate3(foundEmpty, r, 0)` spreads the found
  *      under-surface volume back out in XZ to cover the kernel halo.
  *   4. `output = S | dilatedFound` adds the dilated under-surface region as
  *      solid on top of the original solids.
@@ -27,11 +28,14 @@ import type { Bounds } from '../data-table';
  * "fill the under-side of every column up to the first solid", matching the
  * original (pre-dilation) `fillFloor` behavior.
  *
- * @param buffer - Voxelized scene data.
+ * @param grid - Voxel grid (linear-keyed) — mutated as the under-surface
+ * region is OR'd into it. The same grid instance is returned in
+ * `NavSimplifyResult.grid`.
  * @param gridBounds - Axis-aligned bounds of the voxel grid.
  * @param voxelResolution - Size of each voxel in world units.
  * @param dilation - XZ dilation radius in world units. 0 disables dilation.
- * @returns Modified buffer with under-surface regions filled.
+ * @param gpu - Reusable GPU dilation context. Required when dilation > 0.
+ * @returns Modified grid with under-surface regions filled.
  */
-declare const fillFloor: (buffer: BlockMaskBuffer, gridBounds: Bounds, voxelResolution: number, dilation?: number) => NavSimplifyResult;
+declare const fillFloor: (grid: SparseVoxelGrid, gridBounds: Bounds, voxelResolution: number, dilation?: number, gpu?: GpuDilation | null) => Promise<NavSimplifyResult>;
 export { fillFloor };

package/dist/lib/voxel/flood-fill.d.ts

@@ -20,11 +20,14 @@ import { SparseVoxelGrid } from './sparse-voxel-grid';
  * @param nx - Grid dimension X in voxels.
  * @param ny - Grid dimension Y in voxels.
  * @param nz - Grid dimension Z in voxels.
+ * @param onBlockFilled - Optional progress callback receiving the running
+ * count of whole-block fills. Throttled internally so callers can wire it
+ * directly to a progress bar without worrying about per-block overhead.
  * @returns Sparse voxel grid marking all reachable voxels.
  */
 declare function twoLevelBFS(blocked: SparseVoxelGrid, blockSeeds: number[], voxelSeeds: {
     ix: number;
     iy: number;
     iz: number;
-}[], nx: number, ny: number, nz: number): SparseVoxelGrid;
+}[], nx: number, ny: number, nz: number, onBlockFilled?: (count: number) => void): SparseVoxelGrid;
 export { twoLevelBFS };

package/dist/lib/voxel/grid-ops.d.ts

@@ -18,8 +18,9 @@ declare function computeEmptyGrid(visited: SparseVoxelGrid, blocked: SparseVoxel
  * @param consumeA - If true, `a` is mutated in place and returned. The
  * caller must not subsequently read `a` as an independent value
  * (the returned grid IS `a`).
+ * @param onProgress - Optional progress callback over `b.types` words.
  * @returns Grid containing the union of both inputs. Equal to `a` when
  * `consumeA=true`, otherwise a freshly cloned grid.
  */
-declare function sparseOrGrids(a: SparseVoxelGrid, b: SparseVoxelGrid, consumeA?: boolean): SparseVoxelGrid;
+declare function sparseOrGrids(a: SparseVoxelGrid, b: SparseVoxelGrid, consumeA?: boolean, onProgress?: (done: number, total: number) => void): SparseVoxelGrid;
 export { computeEmptyGrid, sparseOrGrids };

package/dist/lib/voxel/morton.d.ts

@@ -8,13 +8,6 @@
  * @returns Morton code with interleaved bits: ...z2y2x2 z1y1x1 z0y0x0
  */
 declare function xyzToMorton(x: number, y: number, z: number): number;
-/**
- * Decode Morton code to block coordinates.
- *
- * @param m - Morton code
- * @returns Tuple of [x, y, z] block coordinates
- */
-declare function mortonToXYZ(m: number): [number, number, number];
 /**
  * Count the number of set bits in a 32-bit integer.
  *
@@ -38,13 +31,4 @@ declare function isSolid(lo: number, hi: number): boolean;
  * @returns True if all 64 voxels are empty
  */
 declare function isEmpty(lo: number, hi: number): boolean;
-/**
- * Get the offset to a child node given a parent's child mask and octant.
- * Uses popcount to count how many children come before this octant.
- *
- * @param mask - 8-bit child mask from parent node
- * @param octant - Octant index (0-7)
- * @returns Offset from base child pointer
- */
-declare function getChildOffset(mask: number, octant: number): number;
-export { xyzToMorton, mortonToXYZ, popcount, isSolid, isEmpty, getChildOffset };
+export { xyzToMorton, popcount, isSolid, isEmpty };

package/dist/lib/voxel/sparse-voxel-grid.d.ts

@@ -68,16 +68,62 @@ declare class SparseVoxelGrid {
     setVoxel(ix: number, iy: number, iz: number): void;
     orBlock(blockIdx: number, lo: number, hi: number): void;
     clear(): void;
+    /**
+     * Release the large backing arrays once a grid has been consumed.
+     */
+    releaseStorage(): void;
     clone(): SparseVoxelGrid;
-    static fromBuffer(acc: BlockMaskBuffer, nx: number, ny: number, nz: number): SparseVoxelGrid;
-    toBuffer(cropMinBx: number, cropMinBy: number, cropMinBz: number, cropMaxBx: number, cropMaxBy: number, cropMaxBz: number, defaultSolid?: boolean): BlockMaskBuffer;
-    toBufferInverted(cropMinBx: number, cropMinBy: number, cropMinBz: number, cropMaxBx: number, cropMaxBy: number, cropMaxBz: number): BlockMaskBuffer;
+    static fromBuffer(acc: BlockMaskBuffer, nx: number, ny: number, nz: number, onProgress?: (done: number, total: number) => void): SparseVoxelGrid;
+    toBuffer(cropMinBx: number, cropMinBy: number, cropMinBz: number, cropMaxBx: number, cropMaxBy: number, cropMaxBz: number, onProgress?: (done: number, total: number) => void): BlockMaskBuffer;
+    /**
+     * Crop this grid to a block-aligned sub-region. Returns a fresh grid of
+     * size `(cropMaxBx-cropMinBx)*4 x (cropMaxBy-cropMinBy)*4 x (cropMaxBz-cropMinBz)*4`
+     * containing the same data with origin shifted to (cropMinBx, cropMinBy, cropMinBz).
+     *
+     * Iterates only non-empty blocks of the source via word-level skipping.
+     *
+     * @param cropMinBx - Min block X (inclusive).
+     * @param cropMinBy - Min block Y (inclusive).
+     * @param cropMinBz - Min block Z (inclusive).
+     * @param cropMaxBx - Max block X (exclusive).
+     * @param cropMaxBy - Max block Y (exclusive).
+     * @param cropMaxBz - Max block Z (exclusive).
+     * @param onProgress - Optional progress callback over source `types` words.
+     * @returns Newly allocated cropped grid.
+     */
+    cropTo(cropMinBx: number, cropMinBy: number, cropMinBz: number, cropMaxBx: number, cropMaxBy: number, cropMaxBz: number, onProgress?: (done: number, total: number) => void): SparseVoxelGrid;
+    /**
+     * Crop this grid to a sub-region with inverted occupancy: source EMPTY
+     * becomes destination SOLID, source SOLID becomes destination EMPTY,
+     * source MIXED becomes destination MIXED with bitwise-inverted mask.
+     *
+     * The destination grid has dimensions matching the crop window. Used by
+     * carve to flip the navigable region (1=navigable) into the runtime's
+     * occupancy convention (1=blocked).
+     *
+     * Note: cropping the EMPTY-becomes-SOLID region is exact within the crop
+     * window only. Since the source grid's EMPTY blocks become SOLID in the
+     * output, the output's `types` for empty blocks must be set rather than
+     * left at their default. We therefore initialize the entire output to
+     * SOLID (word fill) and then patch any non-EMPTY source blocks.
+     *
+     * @param cropMinBx - Min block X (inclusive).
+     * @param cropMinBy - Min block Y (inclusive).
+     * @param cropMinBz - Min block Z (inclusive).
+     * @param cropMaxBx - Max block X (exclusive).
+     * @param cropMaxBy - Max block Y (exclusive).
+     * @param cropMaxBz - Max block Z (exclusive).
+     * @param onProgress - Optional progress callback over source `types` words.
+     * @returns Newly allocated cropped + inverted grid.
+     */
+    cropToInverted(cropMinBx: number, cropMinBy: number, cropMinBz: number, cropMaxBx: number, cropMaxBy: number, cropMaxBz: number, onProgress?: (done: number, total: number) => void): SparseVoxelGrid;
     /**
      * Get the bounding box of occupied blocks.
      *
+     * @param onProgress - Optional progress callback over `types` words.
      * @returns Block coordinate bounds, or null if no blocks are occupied.
      */
-    getOccupiedBlockBounds(): {
+    getOccupiedBlockBounds(onProgress?: (done: number, total: number) => void): {
         minBx: number;
         minBy: number;
         minBz: number;
@@ -91,9 +137,10 @@ declare class SparseVoxelGrid {
      * voxel). Useful when the runtime treats out-of-grid as solid, so fully
      * solid blocks beyond the navigable region can be cropped away.
      *
+     * @param onProgress - Optional progress callback over `types` words.
      * @returns Block coordinate bounds, or null if every block is solid.
      */
-    getNavigableBlockBounds(): {
+    getNavigableBlockBounds(onProgress?: (done: number, total: number) => void): {
         minBx: number;
         minBy: number;
         minBz: number;