# src/wasm-mesher (JS side of the WASM mesher)

This directory is the JS-side counterpart of the Rust crate at
`/wasm-mesher/`. It contains everything that runs in the browser/Node:
the worker, the JS↔Rust bridge, the wasm-pack runtime artefacts, and
the WASM-only unit tests.

The Rust source itself stays at the repo root (`/wasm-mesher/`); only
its compiled output is mirrored here.

## Layout

```
src/wasm-mesher/
├── runtime-build/   ← wasm-pack output (--target web)
│   ├── wasm_mesher.js          ← JS shim generated by wasm-bindgen
│   ├── wasm_mesher_bg.wasm     ← compiled WASM module
│   └── *.d.ts                  ← typings
├── bridge/          ← thin JS layer between Rust output and the renderer
│   ├── convertChunk.ts         ← legacy slow path: prismarine-chunk → typed arrays
│   └── render-from-wasm.ts     ← geometry → Three.js + section split + heightmap
├── worker/          ← runs inside the dedicated mesher Web Worker
│   ├── mesherWasm.ts           ← worker entry; routes by version (1.16/17/18+)
│   ├── mesherWasmConversionCache.ts
│   └── mesherWasmRequestTracker.ts
├── tests/           ← WASM-only vitest tests (run by `pnpm unit-test`)
│   ├── heightmapParity.test.ts
│   ├── splitColumnWasmOutput.test.ts
│   └── mesherWasmConversionCache.test.ts
└── README.md        ← you are here
```

Other related directories:

- **`/wasm-mesher/`** (repo root) — the Rust crate (`src/*.rs`,
  `Cargo.toml`, `build.sh`) and standalone TS test harnesses
  (`tests/test-chunk.ts`, `tests/test-section-boundary.ts`).
  See `wasm-mesher/README.md` for the public Rust API.
- **`src/mesher-shared/`** — modules used by **both** this WASM path and
  the legacy JS mesher (`models`, `world`, `shared`, `worldConstants`,
  `computeHeightmap`, …).
- **`src/mesher-legacy/`** — the original JS mesher, kept until the WASM
  path proves itself in production. Will be removed in a follow-up PR.

## Building

The worker bundle is built by `scripts/buildMesherWorker.mjs`:

```bash
pnpm build:mesher          # esbuild → dist/mesherWasm.js (web-client contract)
pnpm watch:mesher          # incremental rebuild on change
```

The output filename `dist/mesherWasm.js` is **load-bearing** — the
web-client imports the worker by that path. `entryNames: '[name]'` in
the build config keeps the output flat regardless of source-tree depth.

The WASM module itself (`runtime-build/wasm_mesher_bg.wasm`) is rebuilt
by:

```bash
pnpm build:wasm            # → runs wasm-mesher/build.sh web (release)
```

This requires `wasm-pack` on PATH; see `wasm-mesher/README.md` for setup.

## Testing

```bash
pnpm unit-test --run       # all vitest tests, including this dir's tests/
pnpm test:wasm             # snapshot + boundary + heightmap (cjs harnesses)
pnpm test:wasm:boundary    # boundary + heightmap only
```

The vitest tests in `tests/` exercise the worker logic against real WASM:

- `heightmapParity.test.ts` — JS `computeHeightmap` vs Rust output.
- `splitColumnWasmOutput.test.ts` — column-split correctness.
- `mesherWasmConversionCache.test.ts` — cache eviction and column reuse.

## Notes

- `bridge/convertChunk.ts` is the **slow path** (prismarine-chunk → typed
  arrays in JS). For 1.18+ chunks the worker prefers the fast path:
  `parseChunkDump118FullColumnAll` (a single Rust call) consumed via
  `worker/mesherWasm.ts`. See `docs/issues/issue-15-wasm/history.md` for
  the rationale and benchmarks.
- Routing of raw `map_chunk` packets (1.16 / 1.17 / 1.18+) lives in
  `worker/mesherWasm.ts`; per-version Rust parsers are in
  `wasm-mesher/src/parser_*.rs`.