@pascal-app/core 0.9.2 → 1.0.0-beta.1

package/dist/lib/terrain-field.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The terrain heightfield: one regular grid of quantized heights, and the
+ * only place terrain geometry is read from.
+ *
+ * Two invariants carry the whole design:
+ *
+ * 1. **Quantized to `Int16` multiples of `step`.** Heights are integers, so
+ *    "is this ground flat?" is exact integer equality rather than an epsilon
+ *    comparison. That is what lets the support election treat terrain as one
+ *    discrete candidate (see `slab-support.ts`) instead of a float soup that
+ *    never ties. `step` is metres per unit; at 0.01 the Int16 range covers
+ *    ±327 m of relief, far past any building site.
+ * 2. **Every read goes through `heightAt`.** Consumers never index `heights`
+ *    directly. One authority means the mesh, the raycast, the placement
+ *    predicate, and the tests cannot disagree about where the ground is.
+ *
+ * Pure data — no Three.js, per the core layer rule. The mesh built from this
+ * lives in `@pascal-app/nodes`.
+ */
+/**
+ * A regular grid of heights over the XZ plane.
+ *
+ * `origin` is the world XZ of sample [0,0]; sample [c,r] sits at
+ * `(origin[0] + c * spacing, origin[1] + r * spacing)`. Row-major, so index
+ * `r * cols + c`.
+ *
+ * Sized `2ⁿ+1` per side by convention (33, 65, 129, …) so a future LOD halving
+ * lands on existing samples and shares edge vertices with its neighbour rather
+ * than interpolating a seam.
+ */
+export type TerrainField = {
+    /** World XZ of sample [0,0]. */
+    readonly origin: readonly [number, number];
+    /** Metres between adjacent samples. */
+    readonly spacing: number;
+    readonly cols: number;
+    readonly rows: number;
+    /** Metres per `heights` unit — the quantization ladder. */
+    readonly step: number;
+    /** Row-major quantized heights, length `cols * rows`. */
+    readonly heights: Int16Array;
+};
+/** A rectangular sub-block of samples — the unit of every terrain write. */
+export type HeightPatch = {
+    readonly col0: number;
+    readonly row0: number;
+    readonly cols: number;
+    readonly rows: number;
+    /** Row-major quantized heights, length `cols * rows`. */
+    readonly heights: Int16Array;
+};
+export declare const DEFAULT_TERRAIN_STEP = 0.01;
+export declare const DEFAULT_TERRAIN_SPACING = 0.5;
+export declare function createTerrainField(options?: {
+    origin?: readonly [number, number];
+    spacing?: number;
+    cols?: number;
+    rows?: number;
+    step?: number;
+}): TerrainField;
+/** Quantize a metre height onto the field's ladder, clamped to Int16. */
+export declare function quantize(field: TerrainField, metres: number): number;
+/** Sample [c,r] in metres. Out-of-range indices clamp to the edge, so a
+ * consumer reading just past the boundary gets the border height rather than
+ * a hole — the same clamp-don't-ask rule the vertical model uses. */
+export declare function heightAtSample(field: TerrainField, col: number, row: number): number;
+/**
+ * The ground height in metres at a world XZ, on the rendered triangle plane.
+ *
+ * This is the single read authority named in the plan. Each cell uses the same
+ * `(c+1,r)`–`(c,r+1)` diagonal as `nodes/src/site/terrain-geometry.ts`, so
+ * placement, picking, collision, draping, and pixels all answer the same height.
+ */
+export declare function heightAt(field: TerrainField, x: number, z: number): number;
+/**
+ * Compatibility name for callers that explicitly describe a rendered surface.
+ * There is intentionally no second interpolation model: `heightAt` is the
+ * rendered triangle plane.
+ */
+export declare function surfaceHeightAt(field: TerrainField, x: number, z: number): number;
+/**
+ * Surface normal at a world XZ, from analytic central differences.
+ *
+ * Central differences rather than per-triangle face normals: the field is the
+ * authority, so the normal is a property of the *field* and stays continuous
+ * across triangle boundaries. Returns a unit vector, +Y up.
+ */
+export declare function normalAt(field: TerrainField, x: number, z: number): [number, number, number];
+/** Slope in radians from horizontal at a world XZ. 0 = flat, π/2 = vertical. */
+export declare function slopeAt(field: TerrainField, x: number, z: number): number;
+/**
+ * True when every sample under the world-XZ rect is at the identical quantized
+ * height — the placement predicate for kinds that need level ground.
+ *
+ * Exact integer equality, which is only meaningful because heights are
+ * quantized (invariant 1). A float field would need a tolerance here, and that
+ * tolerance would then have to agree with the support election's own epsilon —
+ * two tunables that could drift apart. Instead there is one ladder and no
+ * tolerance.
+ */
+export declare function isFlatOver(field: TerrainField, minX: number, minZ: number, maxX: number, maxZ: number): boolean;
+/**
+ * The one write API. Every terrain mutation — brush stroke, DEM import, scan
+ * conversion, preset, MCP tool — lands here.
+ *
+ * Returns a new field with a new `heights` buffer, so a stroke's before/after
+ * pair can be diffed for undo and for `diffToPatches`. Patch samples outside
+ * the field are ignored rather than throwing: an imported DEM is allowed to
+ * overhang the site, and clipping is the sane response.
+ */
+export declare function applyHeightPatch(field: TerrainField, patch: HeightPatch): TerrainField;
+/** The world-XZ sample range a rect covers, clamped to the field. Shared by
+ * the brushes so every tool agrees which samples a footprint touches. */
+export declare function sampleRangeOver(field: TerrainField, minX: number, minZ: number, maxX: number, maxZ: number): {
+    col0: number;
+    row0: number;
+    col1: number;
+    row1: number;
+} | null;
+/**
+ * The only brush in the first slice: set every sample under a world-XZ rect to
+ * one absolute height.
+ *
+ * Absolute-height flatten before raise/lower is deliberate. A raise/lower brush
+ * answers "make this taller", which the user cannot aim; flatten-to-height
+ * answers "put the ground at 2.5 m here", which is the actual task when siting
+ * a building — and it is the one brush whose result is predictable enough to
+ * test. Returns null when the rect misses the field entirely.
+ */
+export declare function flattenPatch(field: TerrainField, rect: {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}, metres: number): HeightPatch | null;
+/**
+ * Split the difference between two fields into patches that each stay under
+ * `maxBytes` when serialized.
+ *
+ * This exists because scene operations are capped at
+ * `MAX_SCENE_OPERATION_BYTES` (64 KiB) and each mutation carries both `from`
+ * and `to` — so a whole-field write is over budget the moment the grid gets
+ * interesting. Rows are the split unit: a patch is always whole rows, which
+ * keeps reassembly trivial and means a single-row edit costs one row.
+ *
+ * Returns the minimal dirty row span, so a small brush stroke on a large field
+ * produces a small patch rather than a full-field rewrite.
+ */
+export declare function diffToPatches(before: TerrainField, after: TerrainField, maxBytes: number): HeightPatch[];
+//# sourceMappingURL=terrain-field.d.ts.map

package/dist/lib/terrain-field.d.ts.map

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

package/dist/lib/terrain-field.js

@@ -0,0 +1,248 @@
+/**
+ * The terrain heightfield: one regular grid of quantized heights, and the
+ * only place terrain geometry is read from.
+ *
+ * Two invariants carry the whole design:
+ *
+ * 1. **Quantized to `Int16` multiples of `step`.** Heights are integers, so
+ *    "is this ground flat?" is exact integer equality rather than an epsilon
+ *    comparison. That is what lets the support election treat terrain as one
+ *    discrete candidate (see `slab-support.ts`) instead of a float soup that
+ *    never ties. `step` is metres per unit; at 0.01 the Int16 range covers
+ *    ±327 m of relief, far past any building site.
+ * 2. **Every read goes through `heightAt`.** Consumers never index `heights`
+ *    directly. One authority means the mesh, the raycast, the placement
+ *    predicate, and the tests cannot disagree about where the ground is.
+ *
+ * Pure data — no Three.js, per the core layer rule. The mesh built from this
+ * lives in `@pascal-app/nodes`.
+ */
+export const DEFAULT_TERRAIN_STEP = 0.01;
+export const DEFAULT_TERRAIN_SPACING = 0.5;
+export function createTerrainField(options) {
+    const cols = options?.cols ?? 65;
+    const rows = options?.rows ?? 65;
+    return {
+        origin: options?.origin ?? [0, 0],
+        spacing: options?.spacing ?? DEFAULT_TERRAIN_SPACING,
+        cols,
+        rows,
+        step: options?.step ?? DEFAULT_TERRAIN_STEP,
+        heights: new Int16Array(cols * rows),
+    };
+}
+/** Quantize a metre height onto the field's ladder, clamped to Int16. */
+export function quantize(field, metres) {
+    if (!Number.isFinite(metres))
+        return 0;
+    const raw = Math.round(metres / field.step);
+    return Math.max(-32768, Math.min(32767, raw));
+}
+/** Sample [c,r] in metres. Out-of-range indices clamp to the edge, so a
+ * consumer reading just past the boundary gets the border height rather than
+ * a hole — the same clamp-don't-ask rule the vertical model uses. */
+export function heightAtSample(field, col, row) {
+    const c = Math.max(0, Math.min(field.cols - 1, Math.trunc(col)));
+    const r = Math.max(0, Math.min(field.rows - 1, Math.trunc(row)));
+    return (field.heights[r * field.cols + c] ?? 0) * field.step;
+}
+/**
+ * The ground height in metres at a world XZ, on the rendered triangle plane.
+ *
+ * This is the single read authority named in the plan. Each cell uses the same
+ * `(c+1,r)`–`(c,r+1)` diagonal as `nodes/src/site/terrain-geometry.ts`, so
+ * placement, picking, collision, draping, and pixels all answer the same height.
+ */
+export function heightAt(field, x, z) {
+    if (field.cols < 2 || field.rows < 2)
+        return heightAtSample(field, 0, 0);
+    const u = Math.min(field.cols - 1, Math.max(0, (x - field.origin[0]) / field.spacing));
+    const v = Math.min(field.rows - 1, Math.max(0, (z - field.origin[1]) / field.spacing));
+    const col = Math.min(field.cols - 2, Math.floor(u));
+    const row = Math.min(field.rows - 2, Math.floor(v));
+    const tc = u - col;
+    const tr = v - row;
+    const h00 = heightAtSample(field, col, row);
+    const h10 = heightAtSample(field, col + 1, row);
+    const h01 = heightAtSample(field, col, row + 1);
+    const h11 = heightAtSample(field, col + 1, row + 1);
+    if (tc + tr <= 1)
+        return h00 + (h10 - h00) * tc + (h01 - h00) * tr;
+    return h11 + (h01 - h11) * (1 - tc) + (h10 - h11) * (1 - tr);
+}
+/**
+ * Compatibility name for callers that explicitly describe a rendered surface.
+ * There is intentionally no second interpolation model: `heightAt` is the
+ * rendered triangle plane.
+ */
+export function surfaceHeightAt(field, x, z) {
+    return heightAt(field, x, z);
+}
+/**
+ * Surface normal at a world XZ, from analytic central differences.
+ *
+ * Central differences rather than per-triangle face normals: the field is the
+ * authority, so the normal is a property of the *field* and stays continuous
+ * across triangle boundaries. Returns a unit vector, +Y up.
+ */
+export function normalAt(field, x, z) {
+    const d = field.spacing;
+    const dhdx = (heightAt(field, x + d, z) - heightAt(field, x - d, z)) / (2 * d);
+    const dhdz = (heightAt(field, x, z + d) - heightAt(field, x, z - d)) / (2 * d);
+    // Gradient (dh/dx, dh/dz) → normal (-dh/dx, 1, -dh/dz), normalized.
+    const len = Math.hypot(dhdx, 1, dhdz);
+    return [-dhdx / len, 1 / len, -dhdz / len];
+}
+/** Slope in radians from horizontal at a world XZ. 0 = flat, π/2 = vertical. */
+export function slopeAt(field, x, z) {
+    const d = field.spacing;
+    const dhdx = (heightAt(field, x + d, z) - heightAt(field, x - d, z)) / (2 * d);
+    const dhdz = (heightAt(field, x, z + d) - heightAt(field, x, z - d)) / (2 * d);
+    return Math.atan(Math.hypot(dhdx, dhdz));
+}
+/**
+ * True when every sample under the world-XZ rect is at the identical quantized
+ * height — the placement predicate for kinds that need level ground.
+ *
+ * Exact integer equality, which is only meaningful because heights are
+ * quantized (invariant 1). A float field would need a tolerance here, and that
+ * tolerance would then have to agree with the support election's own epsilon —
+ * two tunables that could drift apart. Instead there is one ladder and no
+ * tolerance.
+ */
+export function isFlatOver(field, minX, minZ, maxX, maxZ) {
+    const c0 = Math.max(0, Math.floor((minX - field.origin[0]) / field.spacing));
+    const r0 = Math.max(0, Math.floor((minZ - field.origin[1]) / field.spacing));
+    const c1 = Math.min(field.cols - 1, Math.ceil((maxX - field.origin[0]) / field.spacing));
+    const r1 = Math.min(field.rows - 1, Math.ceil((maxZ - field.origin[1]) / field.spacing));
+    if (c1 < c0 || r1 < r0)
+        return true;
+    const first = field.heights[r0 * field.cols + c0] ?? 0;
+    for (let r = r0; r <= r1; r++) {
+        const rowBase = r * field.cols;
+        for (let c = c0; c <= c1; c++) {
+            if ((field.heights[rowBase + c] ?? 0) !== first)
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * The one write API. Every terrain mutation — brush stroke, DEM import, scan
+ * conversion, preset, MCP tool — lands here.
+ *
+ * Returns a new field with a new `heights` buffer, so a stroke's before/after
+ * pair can be diffed for undo and for `diffToPatches`. Patch samples outside
+ * the field are ignored rather than throwing: an imported DEM is allowed to
+ * overhang the site, and clipping is the sane response.
+ */
+export function applyHeightPatch(field, patch) {
+    const heights = new Int16Array(field.heights);
+    for (let pr = 0; pr < patch.rows; pr++) {
+        const row = patch.row0 + pr;
+        if (row < 0 || row >= field.rows)
+            continue;
+        const destBase = row * field.cols;
+        const srcBase = pr * patch.cols;
+        for (let pc = 0; pc < patch.cols; pc++) {
+            const col = patch.col0 + pc;
+            if (col < 0 || col >= field.cols)
+                continue;
+            heights[destBase + col] = patch.heights[srcBase + pc] ?? 0;
+        }
+    }
+    return { ...field, heights };
+}
+/** The world-XZ sample range a rect covers, clamped to the field. Shared by
+ * the brushes so every tool agrees which samples a footprint touches. */
+export function sampleRangeOver(field, minX, minZ, maxX, maxZ) {
+    const col0 = Math.max(0, Math.floor((minX - field.origin[0]) / field.spacing));
+    const row0 = Math.max(0, Math.floor((minZ - field.origin[1]) / field.spacing));
+    const col1 = Math.min(field.cols - 1, Math.ceil((maxX - field.origin[0]) / field.spacing));
+    const row1 = Math.min(field.rows - 1, Math.ceil((maxZ - field.origin[1]) / field.spacing));
+    if (col1 < col0 || row1 < row0)
+        return null;
+    return { col0, row0, col1, row1 };
+}
+/**
+ * The only brush in the first slice: set every sample under a world-XZ rect to
+ * one absolute height.
+ *
+ * Absolute-height flatten before raise/lower is deliberate. A raise/lower brush
+ * answers "make this taller", which the user cannot aim; flatten-to-height
+ * answers "put the ground at 2.5 m here", which is the actual task when siting
+ * a building — and it is the one brush whose result is predictable enough to
+ * test. Returns null when the rect misses the field entirely.
+ */
+export function flattenPatch(field, rect, metres) {
+    const range = sampleRangeOver(field, rect.minX, rect.minZ, rect.maxX, rect.maxZ);
+    if (!range)
+        return null;
+    const cols = range.col1 - range.col0 + 1;
+    const rows = range.row1 - range.row0 + 1;
+    const value = quantize(field, metres);
+    const heights = new Int16Array(cols * rows);
+    heights.fill(value);
+    return { col0: range.col0, row0: range.row0, cols, rows, heights };
+}
+/**
+ * Split the difference between two fields into patches that each stay under
+ * `maxBytes` when serialized.
+ *
+ * This exists because scene operations are capped at
+ * `MAX_SCENE_OPERATION_BYTES` (64 KiB) and each mutation carries both `from`
+ * and `to` — so a whole-field write is over budget the moment the grid gets
+ * interesting. Rows are the split unit: a patch is always whole rows, which
+ * keeps reassembly trivial and means a single-row edit costs one row.
+ *
+ * Returns the minimal dirty row span, so a small brush stroke on a large field
+ * produces a small patch rather than a full-field rewrite.
+ */
+export function diffToPatches(before, after, maxBytes) {
+    if (before.cols !== after.cols || before.rows !== after.rows) {
+        // Shape changed — the whole field is dirty; chunk it wholesale.
+        return chunkRows(after, 0, after.rows - 1, maxBytes);
+    }
+    const patches = [];
+    let runStart = -1;
+    for (let r = 0; r < after.rows; r++) {
+        const base = r * after.cols;
+        let dirty = false;
+        for (let c = 0; c < after.cols; c++) {
+            if (before.heights[base + c] !== after.heights[base + c]) {
+                dirty = true;
+                break;
+            }
+        }
+        if (dirty && runStart < 0)
+            runStart = r;
+        if (!dirty && runStart >= 0) {
+            patches.push(...chunkRows(after, runStart, r - 1, maxBytes));
+            runStart = -1;
+        }
+    }
+    if (runStart >= 0)
+        patches.push(...chunkRows(after, runStart, after.rows - 1, maxBytes));
+    return patches;
+}
+/** Slice a whole-row span into patches that each fit `maxBytes`. */
+function chunkRows(field, firstRow, lastRow, maxBytes) {
+    // 2 bytes per Int16 sample, and the transport carries `from` + `to`, so a
+    // row costs twice its raw size. Halving the budget up front keeps the caller
+    // from having to know that.
+    const bytesPerRow = field.cols * 2 * 2;
+    const rowsPerChunk = Math.max(1, Math.floor(maxBytes / Math.max(1, bytesPerRow)));
+    const patches = [];
+    for (let start = firstRow; start <= lastRow; start += rowsPerChunk) {
+        const end = Math.min(lastRow, start + rowsPerChunk - 1);
+        const rows = end - start + 1;
+        patches.push({
+            col0: 0,
+            row0: start,
+            cols: field.cols,
+            rows,
+            heights: field.heights.slice(start * field.cols, (end + 1) * field.cols),
+        });
+    }
+    return patches;
+}

package/dist/lib/terrain-raycast.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Ray → terrain intersection.
+ *
+ * This is the function that replaces `t = -oy / dy` (the flat-ground plane
+ * solve) everywhere the editor asks "where on the ground is the pointer?".
+ * It lives in `core` with no Three.js so the 2D view, the tools, the placement
+ * coordinator, and the tests all call the same code — the failure mode this
+ * avoids is each surface having its own idea of where the ground is, which on
+ * flat ground is invisible and on a slope is a perspective-skewed offset that
+ * only some tools correct for.
+ *
+ * Method: march the ray in `spacing`-sized steps, watching the sign of
+ * `rayY - terrainY`, then bisect the bracketing interval. Marching (rather than
+ * per-triangle intersection over the whole grid) is what keeps this O(path
+ * length) instead of O(samples) — a 129² field is 32 768 triangles, and testing
+ * all of them per pointer-move is not affordable at 50 FPS.
+ *
+ * The bisection is exact to `spacing / 2^ITERATIONS`; at 0.5 m spacing and 20
+ * iterations that is under half a micrometre, i.e. far below the quantization
+ * ladder, so the returned point is on the same rendered triangle plane
+ * `heightAt` reports.
+ */
+import { type TerrainField } from './terrain-field';
+export type TerrainHit = {
+    /** Distance along the (unnormalized) direction vector. */
+    readonly t: number;
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+};
+/**
+ * First intersection of a ray with the terrain surface, or `null` if it misses.
+ *
+ * `direction` need not be normalized; `t` is in units of `direction`'s length,
+ * matching `Ray.at(t)` semantics so a viewer-side caller can pass a three.js ray
+ * through unchanged.
+ *
+ * The march tracks the *sign change* of `rayY - surfaceY` rather than assuming
+ * the ray starts above the ground, so a ray fired from inside a hill or from a
+ * basement finds the surface it exits through. A ray whose origin is already
+ * exactly on the surface returns `t = 0`.
+ */
+export declare function raycastTerrain(field: TerrainField, origin: readonly [number, number, number], direction: readonly [number, number, number]): TerrainHit | null;
+//# sourceMappingURL=terrain-raycast.d.ts.map

package/dist/lib/terrain-raycast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-raycast.d.ts","sourceRoot":"","sources":["../../src/lib/terrain-raycast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE7D,MAAM,MAAM,UAAU,GAAG;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAiHD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACzC,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC3C,UAAU,GAAG,IAAI,CAuDnB"}

package/dist/lib/terrain-raycast.js

@@ -0,0 +1,188 @@
+/**
+ * Ray → terrain intersection.
+ *
+ * This is the function that replaces `t = -oy / dy` (the flat-ground plane
+ * solve) everywhere the editor asks "where on the ground is the pointer?".
+ * It lives in `core` with no Three.js so the 2D view, the tools, the placement
+ * coordinator, and the tests all call the same code — the failure mode this
+ * avoids is each surface having its own idea of where the ground is, which on
+ * flat ground is invisible and on a slope is a perspective-skewed offset that
+ * only some tools correct for.
+ *
+ * Method: march the ray in `spacing`-sized steps, watching the sign of
+ * `rayY - terrainY`, then bisect the bracketing interval. Marching (rather than
+ * per-triangle intersection over the whole grid) is what keeps this O(path
+ * length) instead of O(samples) — a 129² field is 32 768 triangles, and testing
+ * all of them per pointer-move is not affordable at 50 FPS.
+ *
+ * The bisection is exact to `spacing / 2^ITERATIONS`; at 0.5 m spacing and 20
+ * iterations that is under half a micrometre, i.e. far below the quantization
+ * ladder, so the returned point is on the same rendered triangle plane
+ * `heightAt` reports.
+ */
+import { heightAt } from './terrain-field';
+/** Bisection depth. 20 halvings of one cell is sub-micrometre at any sane spacing. */
+const REFINE_ITERATIONS = 20;
+/**
+ * How far to march before giving up, in multiples of `spacing`.
+ *
+ * A ray aimed just above a distant ridge can travel a long way before it dips
+ * below the surface, but an unbounded march is a hang risk if a caller passes a
+ * near-horizontal ray. The bound is generous relative to any site: at 0.5 m
+ * spacing this is 4 km of travel.
+ */
+const MAX_STEPS = 8192;
+/**
+ * World-XZ bounds of the field, in metres. The march is clipped to this so a ray
+ * pointing away from the site terminates immediately instead of stepping
+ * MAX_STEPS times through empty space.
+ */
+function fieldBounds(field) {
+    return {
+        minX: field.origin[0],
+        minZ: field.origin[1],
+        maxX: field.origin[0] + (field.cols - 1) * field.spacing,
+        maxZ: field.origin[1] + (field.rows - 1) * field.spacing,
+    };
+}
+/**
+ * Min/max height in metres, cached per `heights` buffer.
+ *
+ * The vertical extent is what bounds the march for rays that never leave the
+ * field in XZ — a straight-down pointer ray, which is the single most common
+ * case, has `dx = dz = 0` and therefore an infinite XZ exit. Without a Y bound
+ * such a ray relies on `MAX_STEPS` to terminate, and an *upward* one burns all
+ * 8192 steps before returning null.
+ *
+ * The scan is O(samples), so it is cached on the buffer rather than repeated per
+ * ray. `applyHeightPatch` allocates a new `Int16Array` for every mutation, which
+ * makes the buffer identity a correct version key: a patched field misses the
+ * cache and rescans exactly once, and a stale entry is unreachable. `WeakMap`
+ * keeps it from retaining fields past their use.
+ */
+const heightRangeCache = new WeakMap();
+function heightRange(field) {
+    const cached = heightRangeCache.get(field.heights);
+    if (cached)
+        return cached;
+    let min = 0;
+    let max = 0;
+    if (field.heights.length > 0) {
+        min = field.heights[0] ?? 0;
+        max = min;
+        for (let i = 1; i < field.heights.length; i++) {
+            const h = field.heights[i] ?? 0;
+            if (h < min)
+                min = h;
+            if (h > max)
+                max = h;
+        }
+    }
+    const range = { minY: min * field.step, maxY: max * field.step };
+    heightRangeCache.set(field.heights, range);
+    return range;
+}
+/**
+ * Slab-method clip of the ray against the field's bounding box, returning the
+ * `[tEnter, tExit]` interval to march. Null when the ray misses the box.
+ *
+ * All three axes are clipped, not just XZ. The Y slab is what bounds a
+ * straight-down ray — `dx = dz = 0` makes both XZ slabs "parallel and inside",
+ * so an XZ-only clip returns an infinite exit and the march has to fall back on
+ * `MAX_STEPS`. The Y slab is padded because the surface is bilinear between
+ * samples and a tangent ray must not be clipped exactly at the extremum.
+ */
+function clipToField(field, origin, direction) {
+    const bounds = fieldBounds(field);
+    const { minY, maxY } = heightRange(field);
+    const pad = field.spacing;
+    let tEnter = 0;
+    let tExit = Number.POSITIVE_INFINITY;
+    const axes = [
+        [origin[0], direction[0], bounds.minX, bounds.maxX],
+        [origin[1], direction[1], minY - pad, maxY + pad],
+        [origin[2], direction[2], bounds.minZ, bounds.maxZ],
+    ];
+    for (const [o, d, lo, hi] of axes) {
+        if (Math.abs(d) < 1e-12) {
+            // Parallel to this slab: either always inside or never.
+            if (o < lo || o > hi)
+                return null;
+            continue;
+        }
+        const t1 = (lo - o) / d;
+        const t2 = (hi - o) / d;
+        tEnter = Math.max(tEnter, Math.min(t1, t2));
+        tExit = Math.min(tExit, Math.max(t1, t2));
+        if (tEnter > tExit)
+            return null;
+    }
+    return { tEnter, tExit };
+}
+/**
+ * First intersection of a ray with the terrain surface, or `null` if it misses.
+ *
+ * `direction` need not be normalized; `t` is in units of `direction`'s length,
+ * matching `Ray.at(t)` semantics so a viewer-side caller can pass a three.js ray
+ * through unchanged.
+ *
+ * The march tracks the *sign change* of `rayY - surfaceY` rather than assuming
+ * the ray starts above the ground, so a ray fired from inside a hill or from a
+ * basement finds the surface it exits through. A ray whose origin is already
+ * exactly on the surface returns `t = 0`.
+ */
+export function raycastTerrain(field, origin, direction) {
+    const dirLength = Math.hypot(direction[0], direction[1], direction[2]);
+    if (dirLength < 1e-12)
+        return null;
+    const clip = clipToField(field, origin, direction);
+    if (!clip)
+        return null;
+    const { tEnter, tExit } = clip;
+    // Step in world-space multiples of one cell, converted into t units. Half a
+    // cell, not a full one, so a ray crossing a single-cell spike cannot step over
+    // its peak and report the ground beyond it.
+    const stepT = field.spacing / 2 / dirLength;
+    const at = (t) => ({
+        x: origin[0] + direction[0] * t,
+        y: origin[1] + direction[1] * t,
+        z: origin[2] + direction[2] * t,
+    });
+    const surfaceGap = (t) => {
+        const p = at(t);
+        return p.y - heightAt(field, p.x, p.z);
+    };
+    const hitAt = (t) => {
+        const p = at(t);
+        return { t, x: p.x, y: heightAt(field, p.x, p.z), z: p.z };
+    };
+    let prevT = tEnter;
+    let prevGap = surfaceGap(tEnter);
+    // Entering exactly on the surface counts as a hit — a pointer ray grazing the
+    // ground plane must not fall through to the caller's flat-plane fallback.
+    if (prevGap === 0)
+        return hitAt(tEnter);
+    const startedAbove = prevGap > 0;
+    for (let step = 1; step <= MAX_STEPS; step++) {
+        const t = Math.min(tExit, tEnter + step * stepT);
+        const gap = surfaceGap(t);
+        // A crossing in either direction is a surface hit.
+        if (gap === 0 || gap > 0 !== startedAbove) {
+            let lo = prevT;
+            let hi = t;
+            for (let i = 0; i < REFINE_ITERATIONS; i++) {
+                const mid = (lo + hi) / 2;
+                if (surfaceGap(mid) > 0 === startedAbove)
+                    lo = mid;
+                else
+                    hi = mid;
+            }
+            return hitAt(hi);
+        }
+        prevT = t;
+        prevGap = gap;
+        if (t >= tExit)
+            break;
+    }
+    return null;
+}