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

package/dist/lib/terrain-brush.js

@@ -0,0 +1,359 @@
+/**
+ * The sculpt brush: pointer motion → `HeightPatch`.
+ *
+ * The obvious implementation — `h += strength * falloff` every tick — is wrong,
+ * and it is wrong in a way that is well documented by the people who ship it.
+ * Dwelling in one spot accumulates without bound, overlapping dabs double-apply,
+ * and a fast drag deposits less material than a slow one. That is exactly the
+ * "hash edges and jagged" result expert Sims builders complain about and route
+ * around. This module implements the model the mature tools converge on instead:
+ *
+ * 1. **Freeze a snapshot at pointer-down.** Every dab is evaluated against the
+ *    snapshot, never against the running result.
+ * 2. **Saturating coverage mask.** A dab raises coverage to `max(mask, falloff)`
+ *    rather than adding to it, and the height is always
+ *    `snapshot + delta * mask`. Re-crossing your own stroke therefore cannot
+ *    compound — the second pass recomputes the same value from the same
+ *    snapshot.
+ * 3. **Arc-length dab spacing.** `advanceStroke` walks from the previous dab to
+ *    the new pointer position in fixed metre steps, so stroke strength is a
+ *    function of distance travelled, not of mouse speed or frame rate.
+ * 4. **Cosine-bell falloff.** Of the standard sculpt kernels this is one of only
+ *    two that are C¹ at *both* centre and rim, which is what prevents a visible
+ *    ridge at the brush boundary.
+ *
+ * The consequence users feel: one stroke is one bounded, repeatable edit. Hold
+ * still and nothing runs away; press again to go further.
+ *
+ * The `TerrainStroke` returned by `beginStroke` is a mutable accumulator — the
+ * one mutable thing in this file, and deliberately so. It is owned by exactly
+ * one in-flight gesture and dies with it, which is cheaper and clearer than
+ * rebuilding a coverage map per pointer-move.
+ */
+import { heightAt, heightAtSample, quantize, } from './terrain-field';
+export const DEFAULT_BRUSH_SETTINGS = {
+    radius: 2,
+    strength: 0.6,
+    falloff: 0.6,
+    shape: 'round',
+};
+/**
+ * Metres a single raise/lower stroke moves the ground at full strength and full
+ * coverage. Bounding it per stroke is what makes the verb aimable: the user
+ * knows a pass is worth at most this much, and repeats for more.
+ */
+export const RAISE_METRES_PER_STROKE = 1;
+/**
+ * Smallest brush radius that still bites, as a multiple of the field's spacing.
+ *
+ * A dab only moves samples that fall *inside* its radius, so a brush narrower
+ * than the gap between samples can land entirely between four of them and change
+ * nothing: `advanceStroke` returns `null`, and the user drags with no mark, no
+ * cursor change, and no error. 1.5 rather than the ~0.71 where a round brush
+ * first catches a corner, because a brush that only bites when it happens to
+ * straddle a sample is worse than one that is honestly too small — at 1.5 the
+ * worst-case coverage is 0.97, so the dab lands wherever it is aimed.
+ *
+ * A *multiple* of spacing rather than a constant because spacing is not fixed:
+ * `fieldExtentForSite` stretches it once a lot exceeds what 257² samples cover
+ * at the default, so on a 300 m lot the old flat 0.5 m floor sat below half the
+ * sample gap and the brush silently stopped working at the bottom of its range.
+ */
+export const MIN_BRUSH_RADIUS_IN_SPACINGS = 1.5;
+/**
+ * Clamp a radius to what `field` can actually resolve.
+ *
+ * Lives here rather than in the editor's UI layer because it is a fact about the
+ * footprint math above, not a preference: every producer of a radius (slider,
+ * `[`/`]`, a future import preset) has to respect it or it produces a brush that
+ * does nothing.
+ */
+export function minBrushRadius(field) {
+    return field.spacing * MIN_BRUSH_RADIUS_IN_SPACINGS;
+}
+/** Dabs are placed every `radius * this` metres along the pointer path. */
+const DAB_SPACING_FRACTION = 0.25;
+/**
+ * Jacobi iterations used to precompute the smooth target. Each is applied with
+ * λ = 0.25 on a 4-neighbour stencil, the stability bound for the discrete
+ * diffusion — above it the filter oscillates instead of converging.
+ */
+const SMOOTH_ITERATIONS = 8;
+const SMOOTH_LAMBDA = 0.25;
+export function beginStroke(options) {
+    return {
+        verb: options.verb,
+        settings: { ...DEFAULT_BRUSH_SETTINGS, ...options.settings },
+        snapshot: options.field,
+        target: options.target ?? 0,
+        mask: new Map(),
+        smoothed: null,
+        lastX: null,
+        lastZ: null,
+    };
+}
+/**
+ * Sample the height a `flatten` stroke should aim at, from the field itself.
+ *
+ * Sampling before the stroke starts (right-click / first click, per the surveyed
+ * tools) is what makes "flatten this pad to match that corner" a two-step
+ * gesture instead of a numeric-entry chore.
+ */
+export function sampleTarget(field, x, z) {
+    return heightAt(field, x, z);
+}
+/**
+ * Forget where the last dab landed, without ending the stroke.
+ *
+ * Needed because dab spacing is a true *arc length*: `advanceStroke` interpolates
+ * from the previous centre, so any gap in the pointer stream is bridged with a
+ * line of dabs when it resumes. That is exactly right for a dropped frame, and
+ * exactly wrong when the caller deliberately skipped a stretch — a camera zoom
+ * mid-stroke moves the ground under a held brush, and bridging back to a centre
+ * from before the zoom paints a stripe across everything in between.
+ *
+ * A stroke resumed after this deposits its next dab at the pointer, like the
+ * first one. The mask is untouched, so the stroke stays saturating across the
+ * break and the whole gesture is still one undo step.
+ */
+export function detachStrokeAnchor(stroke) {
+    stroke.lastX = null;
+    stroke.lastZ = null;
+}
+/**
+ * Extend the stroke to the pointer's new position and return the patch to apply.
+ *
+ * Returns `null` when the motion is shorter than the dab spacing (nothing
+ * changed yet) or when the footprint misses the field entirely. The patch is
+ * absolute heights over the union of the dabs placed by *this* call, recomputed
+ * from the snapshot and the saturated mask — which is why applying patches in
+ * order converges rather than compounding.
+ */
+export function advanceStroke(stroke, x, z) {
+    const dabs = dabPositions(stroke, x, z);
+    if (dabs.length === 0)
+        return null;
+    const field = stroke.snapshot;
+    let minCol = field.cols;
+    let minRow = field.rows;
+    let maxCol = -1;
+    let maxRow = -1;
+    for (const [dx, dz] of dabs) {
+        const range = footprint(field, dx, dz, stroke.settings.radius);
+        if (!range)
+            continue;
+        if (range.col0 < minCol)
+            minCol = range.col0;
+        if (range.row0 < minRow)
+            minRow = range.row0;
+        if (range.col1 > maxCol)
+            maxCol = range.col1;
+        if (range.row1 > maxRow)
+            maxRow = range.row1;
+        for (let r = range.row0; r <= range.row1; r++) {
+            const sampleZ = field.origin[1] + r * field.spacing;
+            for (let c = range.col0; c <= range.col1; c++) {
+                const sampleX = field.origin[0] + c * field.spacing;
+                const coverage = weightAt(stroke.settings, sampleX - dx, sampleZ - dz);
+                if (coverage <= 0)
+                    continue;
+                const index = r * field.cols + c;
+                const previous = stroke.mask.get(index) ?? 0;
+                if (coverage > previous)
+                    stroke.mask.set(index, coverage);
+            }
+        }
+    }
+    if (maxCol < minCol || maxRow < minRow)
+        return null;
+    const cols = maxCol - minCol + 1;
+    const rows = maxRow - minRow + 1;
+    const heights = new Int16Array(cols * rows);
+    for (let r = 0; r < rows; r++) {
+        const fieldRow = minRow + r;
+        for (let c = 0; c < cols; c++) {
+            const fieldCol = minCol + c;
+            const index = fieldRow * field.cols + fieldCol;
+            heights[r * cols + c] = resolveSample(stroke, index, fieldCol, fieldRow);
+        }
+    }
+    return { col0: minCol, row0: minRow, cols, rows, heights };
+}
+/**
+ * The quantized height a sample should hold given the stroke's current mask.
+ *
+ * Every verb has the same shape — `snapshot + (goal - snapshot) * mask *
+ * strength` — which is what makes them all saturating. `raise`/`lower` express
+ * their goal as an offset from the snapshot, `flatten` as an absolute, and
+ * `smooth` as the diffused snapshot.
+ */
+function resolveSample(stroke, index, col, row) {
+    const field = stroke.snapshot;
+    const base = field.heights[index] ?? 0;
+    const coverage = stroke.mask.get(index) ?? 0;
+    if (coverage <= 0)
+        return base;
+    const amount = coverage * stroke.settings.strength;
+    const baseMetres = base * field.step;
+    switch (stroke.verb) {
+        case 'raise':
+            return quantize(field, baseMetres + RAISE_METRES_PER_STROKE * amount);
+        case 'lower':
+            return quantize(field, baseMetres - RAISE_METRES_PER_STROKE * amount);
+        case 'flatten':
+            return quantize(field, baseMetres + (stroke.target - baseMetres) * amount);
+        case 'smooth': {
+            const smoothed = smoothedSnapshot(stroke);
+            const goal = (smoothed[index] ?? base) * field.step;
+            return quantize(field, baseMetres + (goal - baseMetres) * amount);
+        }
+        default:
+            // `col`/`row` are carried for future verbs that need position (terrace).
+            void col;
+            void row;
+            return base;
+    }
+}
+/**
+ * The diffused snapshot every `smooth` dab lerps toward, computed once per
+ * stroke.
+ *
+ * Whole-field rather than stroke-local: a local blur would need its border
+ * samples pinned, and pinned borders are precisely where a smooth brush leaves
+ * the ridge it was supposed to remove. The cost is a few passes over an array
+ * that is 4 225 entries at the default 65² size.
+ */
+function smoothedSnapshot(stroke) {
+    if (stroke.smoothed)
+        return stroke.smoothed;
+    const field = stroke.snapshot;
+    let current = new Int16Array(field.heights);
+    let next = new Int16Array(current.length);
+    for (let iteration = 0; iteration < SMOOTH_ITERATIONS; iteration++) {
+        for (let r = 0; r < field.rows; r++) {
+            for (let c = 0; c < field.cols; c++) {
+                const index = r * field.cols + c;
+                const centre = current[index] ?? 0;
+                const laplacian = sampleClamped(current, field, c - 1, r) +
+                    sampleClamped(current, field, c + 1, r) +
+                    sampleClamped(current, field, c, r - 1) +
+                    sampleClamped(current, field, c, r + 1) -
+                    4 * centre;
+                next[index] = Math.round(centre + SMOOTH_LAMBDA * laplacian);
+            }
+        }
+        const swap = current;
+        current = next;
+        next = swap;
+    }
+    stroke.smoothed = current;
+    return current;
+}
+function sampleClamped(heights, field, col, row) {
+    const c = Math.max(0, Math.min(field.cols - 1, col));
+    const r = Math.max(0, Math.min(field.rows - 1, row));
+    return heights[r * field.cols + c] ?? 0;
+}
+/**
+ * Dab centres from the last one to `(x, z)`, spaced by arc length.
+ *
+ * The first dab of a stroke is placed exactly at the pointer, so a click with no
+ * drag still deposits one dab. After that, motion shorter than one spacing
+ * deposits nothing and the stroke keeps its old anchor — which is what makes the
+ * spacing a true arc length rather than a per-event budget.
+ */
+function dabPositions(stroke, x, z) {
+    if (stroke.lastX === null || stroke.lastZ === null) {
+        stroke.lastX = x;
+        stroke.lastZ = z;
+        return [[x, z]];
+    }
+    const spacing = Math.max(1e-3, stroke.settings.radius * DAB_SPACING_FRACTION);
+    const dx = x - stroke.lastX;
+    const dz = z - stroke.lastZ;
+    const distance = Math.hypot(dx, dz);
+    if (distance < spacing)
+        return [];
+    const steps = Math.floor(distance / spacing);
+    const dabs = [];
+    for (let step = 1; step <= steps; step++) {
+        const t = (step * spacing) / distance;
+        dabs.push([stroke.lastX + dx * t, stroke.lastZ + dz * t]);
+    }
+    const last = dabs[dabs.length - 1];
+    if (last) {
+        stroke.lastX = last[0];
+        stroke.lastZ = last[1];
+    }
+    return dabs;
+}
+/** Sample range a dab of `radius` at `(x, z)` touches, clamped to the field. */
+function footprint(field, x, z, radius) {
+    const col0 = Math.max(0, Math.ceil((x - radius - field.origin[0]) / field.spacing));
+    const row0 = Math.max(0, Math.ceil((z - radius - field.origin[1]) / field.spacing));
+    const col1 = Math.min(field.cols - 1, Math.floor((x + radius - field.origin[0]) / field.spacing));
+    const row1 = Math.min(field.rows - 1, Math.floor((z + radius - field.origin[1]) / field.spacing));
+    if (col1 < col0 || row1 < row0)
+        return null;
+    return { col0, row0, col1, row1 };
+}
+/**
+ * Coverage in 0–1 for a sample at offset `(dx, dz)` from a dab centre.
+ *
+ * Round uses Euclidean distance, square uses Chebyshev — the same radius means
+ * the square brush's inscribed circle matches the round one, so switching shape
+ * mid-session does not change the brush's apparent size.
+ */
+export function weightAt(settings, dx, dz) {
+    const radius = Math.max(1e-6, settings.radius);
+    const distance = settings.shape === 'square' ? Math.max(Math.abs(dx), Math.abs(dz)) : Math.hypot(dx, dz);
+    const normalized = distance / radius;
+    if (normalized >= 1)
+        return 0;
+    const falloff = Math.min(1, Math.max(0, settings.falloff));
+    if (falloff <= 0)
+        return 1;
+    const inner = 1 - falloff;
+    if (normalized <= inner)
+        return 1;
+    const t = (normalized - inner) / falloff;
+    // Cosine bell: 1 at t=0, 0 at t=1, zero derivative at both ends.
+    return 0.5 * (1 + Math.cos(Math.PI * t));
+}
+/**
+ * The world-XZ height under a brush, for the readout the sculpt HUD shows.
+ * Thin, but it keeps the tool from importing `heightAt` just to render a number.
+ */
+export function brushHeightAt(field, x, z) {
+    return heightAt(field, x, z);
+}
+/** Peak coverage the stroke reached, for tests and for the HUD's "pass" readout. */
+export function maxCoverage(stroke) {
+    let max = 0;
+    for (const value of stroke.mask.values())
+        if (value > max)
+            max = value;
+    return max;
+}
+/**
+ * Highest sample height in metres under a world-XZ rect — the seed a `flatten`
+ * pad uses when the user asks for "level with the high corner" rather than
+ * typing a number.
+ */
+export function highestOver(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 heightAtSample(field, col0, row0);
+    let highest = Number.NEGATIVE_INFINITY;
+    for (let r = row0; r <= row1; r++) {
+        for (let c = col0; c <= col1; c++) {
+            const value = (field.heights[r * field.cols + c] ?? 0) * field.step;
+            if (value > highest)
+                highest = value;
+        }
+    }
+    return highest;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * 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 { type TerrainData } from '../schema/terrain';
+import type { TerrainField } from './terrain-field';
+export declare function encodeTerrainField(field: TerrainField): TerrainData;
+/**
+ * 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 declare function decodeTerrainField(data: unknown): TerrainField | null;
+/**
+ * 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 declare function isDatumField(field: TerrainField): boolean;
+//# sourceMappingURL=terrain-codec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-codec.d.ts","sourceRoot":"","sources":["../../src/lib/terrain-codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAoDnD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAenE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAwCrE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAKzD"}

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;
+}