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

package/dist/lib/terrain-codec.js

@@ -0,0 +1,167 @@
+/**
+ * The wire format for a `TerrainField`.
+ *
+ * The scene graph is persisted as JSON (`projects_models.scene_graph`, a jsonb
+ * column), so an `Int16Array` cannot be stored directly — `JSON.stringify` turns
+ * a typed array into an object with numeric string keys, which round-trips
+ * lossily and costs ~7 bytes per sample. This module is the one place the field
+ * crosses that boundary.
+ *
+ * Base64 of little-endian `Int16` was chosen over the alternatives:
+ *
+ * - **A plain number array** costs 4-6× the bytes and, worse, re-parses into a
+ *   `number[]` that every consumer would then have to copy into an `Int16Array`.
+ * - **`Array.from(heights)`** has the same problem and silently drops the
+ *   quantization invariant: nothing stops a hand-edited scene from putting
+ *   `2.5` in the array, and then `isFlatOver`'s integer equality is meaningless.
+ * - **Compression** (RLE, deflate) is deliberately *not* here. Imported DEMs are
+ *   noisy and compress worst, so a compressed format would fail only on the
+ *   messiest scenes — the ones most likely to be real. Chunking (`diffToPatches`)
+ *   is the size mitigation, not compression.
+ *
+ * Byte order is written explicitly via `DataView` rather than relying on
+ * `Int16Array`'s platform order. Every realistic platform is little-endian, but
+ * the wire format must not depend on that being true of the machine that saved
+ * the scene.
+ */
+import { MAX_TERRAIN_SIDE } from '../schema/terrain';
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+function encodeBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i] ?? 0;
+        const b1 = bytes[i + 1] ?? 0;
+        const b2 = bytes[i + 2] ?? 0;
+        const remaining = bytes.length - i;
+        out += BASE64_ALPHABET[b0 >> 2];
+        out += BASE64_ALPHABET[((b0 & 0x03) << 4) | (b1 >> 4)];
+        out += remaining > 1 ? BASE64_ALPHABET[((b1 & 0x0f) << 2) | (b2 >> 6)] : '=';
+        out += remaining > 2 ? BASE64_ALPHABET[b2 & 0x3f] : '=';
+    }
+    return out;
+}
+function decodeBase64(text) {
+    // Reverse lookup is built per call rather than at module scope: decode runs
+    // once per scene load, and a 64-entry loop is cheaper than the indirection
+    // of a module-level Map for a hot path that isn't hot.
+    const lookup = new Int8Array(128).fill(-1);
+    for (let i = 0; i < BASE64_ALPHABET.length; i++) {
+        lookup[BASE64_ALPHABET.charCodeAt(i)] = i;
+    }
+    let clean = '';
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code === 61 /* = */)
+            break;
+        if (code > 127 || lookup[code] === -1)
+            return null;
+        clean += text[i];
+    }
+    if (clean.length % 4 === 1)
+        return null;
+    const byteLength = Math.floor((clean.length * 3) / 4);
+    const bytes = new Uint8Array(byteLength);
+    let out = 0;
+    for (let i = 0; i < clean.length; i += 4) {
+        const c0 = lookup[clean.charCodeAt(i)] ?? 0;
+        const c1 = lookup[clean.charCodeAt(i + 1)] ?? 0;
+        const c2 = i + 2 < clean.length ? (lookup[clean.charCodeAt(i + 2)] ?? 0) : 0;
+        const c3 = i + 3 < clean.length ? (lookup[clean.charCodeAt(i + 3)] ?? 0) : 0;
+        if (out < byteLength)
+            bytes[out++] = (c0 << 2) | (c1 >> 4);
+        if (out < byteLength)
+            bytes[out++] = ((c1 & 0x0f) << 4) | (c2 >> 2);
+        if (out < byteLength)
+            bytes[out++] = ((c2 & 0x03) << 6) | c3;
+    }
+    return bytes;
+}
+export function encodeTerrainField(field) {
+    const bytes = new Uint8Array(field.heights.length * 2);
+    const view = new DataView(bytes.buffer);
+    for (let i = 0; i < field.heights.length; i++) {
+        view.setInt16(i * 2, field.heights[i] ?? 0, true);
+    }
+    return {
+        type: 'heightfield',
+        origin: [field.origin[0], field.origin[1]],
+        spacing: field.spacing,
+        cols: field.cols,
+        rows: field.rows,
+        step: field.step,
+        heights: encodeBase64(bytes),
+    };
+}
+/**
+ * Rebuild a field from persisted data, or `null` if the data is unusable.
+ *
+ * Returns `null` rather than throwing, and rather than repairing: a scene whose
+ * terrain fails to decode must still load (with flat ground) instead of taking
+ * the whole project down, and silently substituting a *different* terrain would
+ * be worse than showing none. The caller treats `null` as "this site has no
+ * terrain".
+ *
+ * Metadata and payload length are strict. Repairing a truncated payload or
+ * inventing missing metadata would silently substitute a different surface.
+ */
+export function decodeTerrainField(data) {
+    if (!data || typeof data !== 'object')
+        return null;
+    const d = data;
+    if (d.type !== 'heightfield')
+        return null;
+    if (!Number.isInteger(d.cols) || !Number.isInteger(d.rows))
+        return null;
+    const cols = d.cols;
+    const rows = d.rows;
+    if (cols < 1 || rows < 1)
+        return null;
+    if (cols > MAX_TERRAIN_SIDE || rows > MAX_TERRAIN_SIDE)
+        return null;
+    if (typeof d.heights !== 'string')
+        return null;
+    if (!Number.isFinite(d.spacing) || d.spacing <= 0)
+        return null;
+    if (!Number.isFinite(d.step) || d.step <= 0)
+        return null;
+    if (!Array.isArray(d.origin) ||
+        d.origin.length !== 2 ||
+        !Number.isFinite(d.origin[0]) ||
+        !Number.isFinite(d.origin[1])) {
+        return null;
+    }
+    const bytes = decodeBase64(d.heights);
+    if (!bytes)
+        return null;
+    if (encodeBase64(bytes) !== d.heights)
+        return null;
+    if (bytes.byteLength !== cols * rows * 2)
+        return null;
+    const heights = new Int16Array(cols * rows);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    for (let i = 0; i < heights.length; i++) {
+        heights[i] = view.getInt16(i * 2, true);
+    }
+    return {
+        origin: [d.origin[0], d.origin[1]],
+        spacing: d.spacing,
+        cols,
+        rows,
+        step: d.step,
+        heights,
+    };
+}
+/**
+ * True when every sample is at the datum — the test for "this field is not worth
+ * persisting".
+ *
+ * Called before writing to the node so an untouched site keeps `terrain:
+ * undefined` instead of carrying ~11 KB of base64 zeroes in every saved scene.
+ */
+export function isDatumField(field) {
+    for (let i = 0; i < field.heights.length; i++) {
+        if (field.heights[i] !== 0)
+            return false;
+    }
+    return true;
+}

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"}