@splatwalk/core 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Eisaman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @splatwalk/core
+
+The SplatWalk WASM core as a single, versioned, binary-friendly package. It bundles:
+
+- `wasm_splatwalk.js` + `wasm_splatwalk_bg.wasm` — the wasm-bindgen glue and binary.
+- `wasm_splatwalk.d.ts` — hand-authored TypeScript declarations with the real
+  settings and result shapes (the generated wasm-bindgen `.d.ts` types every
+  argument and result as `any`).
+- `floor` subpath — a framework-agnostic FAST NAV floor module (`buildFastFloorMesh`,
+  `extractFloorFieldWithRecovery`, `trimStrayFloorCells`, the dense-floor seed/region
+  estimators, the recovery ladder, and the canonical `FAST_NAV_PRESET`). No Babylon
+  or bundler dependency.
+
+This package targets binary-only and non-Babylon integrators. The reference
+TypeScript bridge and Babylon UI live in the main SplatWalk repository.
+
+## Install
+
+```bash
+npm install @splatwalk/core
+```
+
+MIT-licensed and free forever, including for commercial and proprietary use.
+See [`LICENSING.md`](https://github.com/EricEisaman/splatwalk/blob/main/LICENSING.md).
+
+## Use the binary directly
+
+```ts
+import init, {
+  init_splatwalk,
+  build_walkable_ground_field,
+  build_room_floor_mesh,
+  mesh_to_glb,
+} from '@splatwalk/core';
+
+await init();          // always init before calling named exports
+init_splatwalk();
+
+const field = build_walkable_ground_field(splatBytes, settings);
+if (field.api_version !== 2) throw new Error('stale SplatWalk binary');
+
+// One-call room floor (binary-side equivalent of the FAST NAV floor path):
+const floor = build_room_floor_mesh(splatBytes, { ...settings, emit_glb: true });
+const glb = floor.glb ?? mesh_to_glb(floor.mesh.vertices, floor.mesh.indices);
+```
+
+`semver` and `capabilities` on every result let you tolerate additive change
+instead of hard-failing on a version bump; `api_version` stays the hard gate.
+
+## Use the framework-agnostic floor module
+
+```ts
+import {
+  FAST_NAV_PRESET,
+  extractFloorFieldWithRecovery,
+  resolveRecovery,
+} from '@splatwalk/core/floor';
+
+const result = await extractFloorFieldWithRecovery({
+  bytes: splatBytes,
+  // Inject the binary's field builder so the module stays engine-agnostic:
+  buildField: async (b, s) => build_walkable_ground_field(b, s),
+  baseSettings: { ...FAST_NAV_PRESET, rotation, flip_y, collision_seed },
+  seed: collision_seed,
+  recovery: resolveRecovery(),
+  log: (m) => console.log(m),
+});
+```
+
+See the [Integration Guide](https://github.com/EricEisaman/splatwalk/blob/main/docs/INTEGRATION.md)
+for a task-oriented walkthrough, and `docs/wasm-api.md` in the main repository for
+the full settings reference, the coordinate + winding contract, and the progress
+line protocol.

package/floor.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Framework-agnostic FAST NAV floor logic.
+ *
+ * This module contains the room-floor extraction math that does NOT depend on
+ * Babylon.js, the viewer, or any web-worker glue. It operates purely on the
+ * {@link WalkableGroundFieldResult} returned by the WASM core plus plain
+ * {@link MeshSettings}, so binary-only and non-Babylon integrators can reuse it
+ * without pulling in a 3D engine. The Babylon orchestration (the viewer, the nav
+ * worker, spawn handling) lives in {@link "@/navigation/fastNav"}, which
+ * re-exports everything here for backwards compatibility.
+ *
+ * The only imports are type-only, so nothing in this module ties a consumer to a
+ * specific runtime or bundler.
+ */
+import type { MeshSettings, WalkableGroundFieldResult } from './wasm_splatwalk';
+/** A single human-readable progress line, optionally tagged with `[INFO]`, `[WAIT]`, `[WARN]`, `[SUCCESS]`. */
+export type FastNavLogger = (message: string) => void;
+/**
+ * Canonical FAST NAV floor-field preset.
+ *
+ * These are the conservative reconstruction + 2.5D floor-field settings the
+ * reference FAST NAV path uses to extract a room floor. Binary-only integrators
+ * can pass this straight to `build_walkable_ground_field` / `build_room_floor_mesh`
+ * (merged with their own per-scene `rotation`, `flip_y`, `collision_seed`, and
+ * optional `region_min`/`region_max`) instead of reverse-engineering the values.
+ *
+ * It intentionally omits per-scene fields (`rotation`, `flip_y`, `collision_seed`,
+ * `region_*`) so callers supply those for their own splat orientation and seed.
+ *
+ * Keep this in sync with the Rust `fast_nav_preset_json()` in
+ * `wasm-splatwalk/src/lib.rs`, which the WASM core exports via `fast_nav_preset()`
+ * and bakes into `build_room_floor_mesh`.
+ */
+export declare const FAST_NAV_PRESET: Readonly<MeshSettings>;
+/**
+ * Default vertical tolerance (meters) within which a floor corner height is snapped
+ * to the dominant floor plane, so a flat floor triangulates as a single flat surface
+ * instead of a noisy set of stepped quads that Recast fragments into islands.
+ */
+export declare const DEFAULT_FLOOR_FLATTEN_TOLERANCE = 0.12;
+/** Default ceiling on total navmesh voxel columns when auto-sizing the cell size. */
+export declare const DEFAULT_MAX_NAV_CELLS = 1000000;
+/**
+ * Auto-size the Recast cell size (`cs`) for a floor/collider mesh of the given
+ * horizontal extent.
+ *
+ * Follows the standard Recast guideline that `cs` belongs in
+ * `[agentRadius / 3, agentRadius / 2]`, and within that window picks the FINEST
+ * cell size whose grid (`width/cs * depth/cs`) still fits under `maxCells`. This
+ * keeps coverage of a large scene complete (the grid is bounded by a cell budget
+ * instead of a fixed small `cs` that either truncates the area or explodes the
+ * voxel count) while never going finer/coarser than the agent radius warrants.
+ *
+ * `agentRadiusM` is the agent radius in metres; with the gaming-standard 0.5 m
+ * agent this yields `cs` in `[0.167, 0.25]`.
+ */
+export declare function autoNavCellSize(widthM: number, depthM: number, agentRadiusM: number, maxCells?: number): number;
+/** Why floor-field extraction failed (used to drive adaptive recovery). */
+export type FastNavFloorReason = 'no_component' | 'too_small' | 'empty_mesh';
+/** Diagnostic payload attached to a {@link FastNavFloorError}. */
+export interface FastNavFloorDiagnostics {
+    /** Largest usable floor area found, in square meters (if known). */
+    readonly area?: number;
+    /** Number of connected floor components considered. */
+    readonly components?: number;
+    /** Per-state cell counts from the walkable ground field. */
+    readonly stateCounts?: Record<string, number>;
+}
+/**
+ * Typed error thrown by {@link buildFastFloorMesh} when the floor field does not
+ * yield a usable room floor. The {@link reason} lets the recovery loop decide
+ * whether to escalate extraction parameters and retry.
+ */
+export declare class FastNavFloorError extends Error {
+    readonly reason: FastNavFloorReason;
+    readonly area?: number;
+    readonly components?: number;
+    readonly stateCounts?: Record<string, number>;
+    constructor(reason: FastNavFloorReason, message: string, diagnostics?: FastNavFloorDiagnostics);
+}
+/** A single attempt in the adaptive floor-field recovery ladder. */
+export interface FastNavRecoveryStep {
+    /** Human-readable label surfaced in the logs (e.g. `relaxed`, `coarse`). */
+    readonly label: string;
+    /** Partial {@link MeshSettings} merged over the base fast-field settings for this attempt. */
+    readonly settings: Partial<MeshSettings>;
+    /** Minimum accepted floor area (m^2) for this attempt to count as success. */
+    readonly minRoomFloorArea: number;
+    /** Optional per-step override for stray-floater trimming (see {@link trimStrayFloorCells}). */
+    readonly strayTrim?: StrayTrimOptions;
+}
+/** Configurable, ordered floor-field recovery ladder. */
+export interface FastNavRecoveryConfig {
+    /** Attempts tried in order; the first one that yields a usable floor wins. */
+    readonly steps: readonly FastNavRecoveryStep[];
+}
+/**
+ * Default, built-in recovery ladder. It first escalates extraction parameters
+ * (coarser cells, lower density threshold, higher variance tolerance, higher
+ * voxel target, lower confidence) and only relaxes the room-area gate on later
+ * steps as a last resort. Integrators can override any/all of this.
+ */
+export declare const DEFAULT_FAST_NAV_RECOVERY: FastNavRecoveryConfig;
+/**
+ * Resolve a (possibly partial/omitted) recovery config to a concrete one,
+ * falling back to {@link DEFAULT_FAST_NAV_RECOVERY} when no steps are supplied.
+ * This is what makes adaptive recovery on-by-default for every caller.
+ */
+export declare function resolveRecovery(partial?: Partial<FastNavRecoveryConfig>): FastNavRecoveryConfig;
+/**
+ * Tuning for {@link trimStrayFloorCells}. All optional; sensible defaults make it
+ * a no-op on clean scenes and only trim a small number of peripheral strays.
+ */
+export interface StrayTrimOptions {
+    /** Master switch. Defaults to `true` (built-in, on by default). */
+    readonly enabled?: boolean;
+    /**
+     * Max vertical distance (meters) a cell may sit from the median floor height to
+     * still count as real floor. Cells beyond this are treated as stray floaters.
+     * Defaults to `0.5`.
+     */
+    readonly heightTolerance?: number;
+    /**
+     * Safety cap: if trimming would drop more than this fraction of the floor, the
+     * spread is considered structural (e.g. a genuine multi-level floor) and nothing
+     * is trimmed. Defaults to `0.3` ("small numbers" of strays only).
+     */
+    readonly maxStrayFraction?: number;
+    /** Never trim the floor below this many cells. Defaults to `16`. */
+    readonly minKeepCells?: number;
+}
+/** Result of {@link trimStrayFloorCells}. */
+export interface StrayTrimResult {
+    /** The retained floor cell indices (the dense, contiguous core). */
+    readonly cells: number[];
+    /** Cells dropped because their height was a floater-like outlier. */
+    readonly droppedHeightOutliers: number;
+    /** Cells dropped because they were spatially-isolated peripheral specks. */
+    readonly droppedPeripheral: number;
+    /** Median floor height used as the reference plane. */
+    readonly medianHeight: number;
+    /** Whether any cells were dropped. */
+    readonly changed: boolean;
+}
+/**
+ * Ignore a small number of stray peripheral splats/cells in a detected floor.
+ *
+ * Large, floater-heavy scans leave scattered cells at outlier heights inside an
+ * otherwise-flat floor component; triangulating them creates vertical cliffs that
+ * Recast splits into tiny fragments. This helper drops height outliers (relative
+ * to the median floor plane) and any spatially-isolated specks, keeping the
+ * largest contiguous core. It is deliberately conservative: if the would-be
+ * removals exceed `maxStrayFraction`, the spread is treated as structural and the
+ * input is returned unchanged, so clean and legitimately multi-level floors are
+ * untouched.
+ */
+export declare function trimStrayFloorCells(field: WalkableGroundFieldResult, cells: number[], options?: StrayTrimOptions): StrayTrimResult;
+/** Tuning for {@link estimateDenseFloorSeed}. */
+export interface DenseSeedOptions {
+    /** Master switch. Defaults to `true` (built-in, on by default). */
+    readonly enabled?: boolean;
+    /** Height histogram bin size (meters) used to find the dense floor band. Defaults to `0.25`. */
+    readonly heightBin?: number;
+    /**
+     * Keep only cells at/above this density percentile when locating the dense
+     * floor (0..1). Higher = stricter, ignores more sparse strays. Defaults to `0.6`.
+     */
+    readonly densityPercentile?: number;
+    /**
+     * Minimum horizontal/vertical move (meters) from the current seed before a
+     * re-seed + field rebuild is worthwhile. Defaults to `2.0`.
+     */
+    readonly reseedThreshold?: number;
+}
+/**
+ * Estimate a collision seed located in the DENSE floor area of the scene, so the
+ * pipeline anchors on the real room floor instead of a sparse floater plane below
+ * it (the common failure on large, floater-heavy scans). Returns `fallbackSeed`
+ * when there isn't enough signal to be confident.
+ */
+export declare function estimateDenseFloorSeed(field: WalkableGroundFieldResult, fallbackSeed: number[], options?: DenseSeedOptions): number[];
+/**
+ * Estimate an adapted default region (oriented-space AABB) around the dense floor:
+ * generous in XZ (covers the whole floor band) but tightly clamped in Y to the
+ * floor plus walkable headroom. This excludes deep stray floaters below/above the
+ * real floor so floor detection is no longer dragged off the dense area. Returns
+ * `null` when there isn't enough signal.
+ */
+export declare function estimateDenseFloorRegion(field: WalkableGroundFieldResult, options?: DenseSeedOptions): {
+    min: number[];
+    max: number[];
+} | null;
+export interface FastFloorMesh {
+    positions: Float32Array;
+    indices: Uint32Array;
+    selectedCellCount: number;
+    acceptedCellCount: number;
+    obstacleCellCount: number;
+    rejectedCellCount: number;
+    selectedArea: number;
+    centroid: [number, number, number];
+    componentCount: number;
+    fallbackUsed: boolean;
+    seedDistance: number;
+    /** Number of enclosed void/low-confidence cells bridged back into the floor. */
+    bridgedCellCount: number;
+}
+/**
+ * Build a planar floor mesh from a walkable ground field by selecting the best
+ * connected floor component near the seed. Throws a typed {@link FastNavFloorError}
+ * when no usable floor of at least `minRoomFloorArea` square meters is found, so
+ * callers can escalate extraction parameters and retry. A small number of stray
+ * peripheral cells are ignored via {@link trimStrayFloorCells} (configurable).
+ */
+export declare function buildFastFloorMesh(field: WalkableGroundFieldResult, seed: number[] | null, minRoomFloorArea: number, log: FastNavLogger, _strayTrim?: StrayTrimOptions, floorFlattenTolerance?: number): FastFloorMesh;
+/** Builds a walkable ground field from splat bytes + settings (the WASM core call). */
+export type WalkableGroundFieldBuilder = (bytes: Uint8Array, settings: MeshSettings) => Promise<WalkableGroundFieldResult>;
+/** Arguments for {@link extractFloorFieldWithRecovery}. */
+export interface ExtractFloorFieldArgs {
+    /** Raw, already-decompressed splat bytes. */
+    readonly bytes: Uint8Array;
+    /**
+     * Field builder used for each attempt. Inject the WASM core's
+     * `build_walkable_ground_field` (via the bridge) so this module stays
+     * framework-agnostic and does not import the bridge/worker itself.
+     */
+    readonly buildField: WalkableGroundFieldBuilder;
+    /** Base fast-field {@link MeshSettings} that each recovery step is merged over. */
+    readonly baseSettings: MeshSettings;
+    /** Carve seed in oriented space; snapped to the detected floor plane per attempt. */
+    readonly seed: number[];
+    /** Resolved recovery ladder (use {@link resolveRecovery} to fill defaults). */
+    readonly recovery: FastNavRecoveryConfig;
+    /** Default stray-floater trimming for steps that don't specify their own. */
+    readonly strayTrim?: StrayTrimOptions;
+    /** Density-aware re-seeding to anchor on the dense floor (on by default). */
+    readonly denseSeed?: DenseSeedOptions;
+    /** Progress sink. */
+    readonly log: FastNavLogger;
+}
+/** Successful result of {@link extractFloorFieldWithRecovery}. */
+export interface ExtractFloorFieldResult {
+    readonly field: WalkableGroundFieldResult;
+    readonly floorMesh: FastFloorMesh;
+    /** Seed snapped to the floor plane of the winning attempt. */
+    readonly effectiveSeed: number[];
+    /** Label of the recovery step that produced the floor. */
+    readonly stepLabel: string;
+}
+/**
+ * Run floor-field extraction with the built-in adaptive recovery ladder: for each
+ * step, merge its settings over `baseSettings`, build the walkable ground field,
+ * snap the seed to the detected floor plane, then build the floor mesh with that
+ * step's `minRoomFloorArea`. On a {@link FastNavFloorError} (including an empty
+ * mesh) it logs and escalates to the next step. The first success wins; if every
+ * step fails it throws an aggregated {@link FastNavFloorError}.
+ */
+export declare function extractFloorFieldWithRecovery(args: ExtractFloorFieldArgs): Promise<ExtractFloorFieldResult>;