@jgengine/core 0.10.0 → 0.12.0

package/dist/world/terraform.js

@@ -1,4 +1,5 @@
-import { FLAT_FIELD, withNormal } from "./terrain.js";
+import { fractalNoise, FLAT_FIELD, withNormal } from "./terrain.js";
+/** Smooth/linear/hard brush weight for a sample `distance` from the brush center. */
 export function brushWeight(distance, radius, falloff) {
     if (radius <= 0)
         return distance <= 0 ? 1 : 0;
@@ -15,6 +16,13 @@ export function brushWeight(distance, radius, falloff) {
 function clampIndex(value, max) {
     return value < 0 ? 0 : value > max ? max : value;
 }
+function clampRange(value, min, max) {
+    if (min !== undefined && value < min)
+        return min;
+    if (max !== undefined && value > max)
+        return max;
+    return value;
+}
 export function createEditableTerrain(config) {
     const base = config.base ?? FLAT_FIELD;
     const bounds = config.bounds;
@@ -27,12 +35,22 @@ export function createEditableTerrain(config) {
     const vertsZ = rows + 1;
     const offsets = new Float32Array(vertsX * vertsZ);
     const surfaces = new Array(cols * rows).fill(null);
+    const cellCount = cols * rows;
+    let layers = [];
+    // Lazily allocated: null until the first blend, so single-layer terrains carry no weight buffer.
+    let weights = null;
     function gridX(x) {
         return ((x - bounds.minX) / spanX) * cols;
     }
     function gridZ(z) {
         return ((z - bounds.minZ) / spanZ) * rows;
     }
+    function vertexWorldX(gx) {
+        return bounds.minX + (gx / cols) * spanX;
+    }
+    function vertexWorldZ(gz) {
+        return bounds.minZ + (gz / rows) * spanZ;
+    }
     function heightOffsetAt(x, z) {
         const fx = gridX(x);
         const fz = gridZ(z);
@@ -52,10 +70,55 @@ export function createEditableTerrain(config) {
     }
     const sampleHeight = (x, z) => base.sampleHeight(x, z) + heightOffsetAt(x, z);
     const sampleNormal = withNormal(sampleHeight);
-    function editHeight(edit) {
+    function totalHeightAtVertex(gx, gz) {
+        const wx = vertexWorldX(gx);
+        const wz = vertexWorldZ(gz);
+        return base.sampleHeight(wx, wz) + offsets[gz * vertsX + gx];
+    }
+    function neighborAverageHeight(gx, gz) {
+        let sum = 0;
+        let count = 0;
+        for (const [dx, dz] of [
+            [-1, 0],
+            [1, 0],
+            [0, -1],
+            [0, 1],
+        ]) {
+            const nx = gx + dx;
+            const nz = gz + dz;
+            if (nx < 0 || nx >= vertsX || nz < 0 || nz >= vertsZ)
+                continue;
+            sum += totalHeightAtVertex(nx, nz);
+            count += 1;
+        }
+        return count === 0 ? totalHeightAtVertex(gx, gz) : sum / count;
+    }
+    function writeOffset(index, next, limit, wx, wz, record) {
+        let value = next;
+        if (limit !== undefined) {
+            value = clampRange(base.sampleHeight(wx, wz) + value, limit.min, limit.max) - base.sampleHeight(wx, wz);
+        }
+        const before = offsets[index];
+        if (value === before)
+            return false;
+        offsets[index] = value;
+        record?.(index, before, value);
+        return true;
+    }
+    function editHeight(edit, record) {
         const falloff = edit.falloff ?? "smooth";
+        const shape = edit.shape ?? "circle";
         const strength = edit.strength ?? 1;
-        const target = edit.mode === "flatten" ? edit.target ?? sampleHeight(edit.center[0], edit.center[1]) : 0;
+        const limit = edit.heightLimit;
+        const flattenTarget = edit.mode === "flatten" ? edit.target ?? sampleHeight(edit.center[0], edit.center[1]) : 0;
+        const noiseConfig = {
+            seed: edit.seed ?? 1337,
+            frequency: edit.frequency ?? 0.15,
+            octaves: 3,
+            lacunarity: 2,
+            persistence: 0.5,
+            ridged: false,
+        };
         const rCells = Math.ceil(edit.radius / cellSize) + 1;
         const cx = gridX(edit.center[0]);
         const cz = gridZ(edit.center[1]);
@@ -68,32 +131,105 @@ export function createEditableTerrain(config) {
                 const gx = Math.round(cx) + ix;
                 if (gx < 0 || gx >= vertsX)
                     continue;
-                const wx = bounds.minX + (gx / cols) * spanX;
-                const wz = bounds.minZ + (gz / rows) * spanZ;
-                const dist = Math.hypot(wx - edit.center[0], wz - edit.center[1]);
+                const wx = vertexWorldX(gx);
+                const wz = vertexWorldZ(gz);
+                const dx = wx - edit.center[0];
+                const dz = wz - edit.center[1];
+                const dist = shape === "square" ? Math.max(Math.abs(dx), Math.abs(dz)) : Math.hypot(dx, dz);
                 const weight = brushWeight(dist, edit.radius, falloff);
                 if (weight <= 0)
                     continue;
                 const index = gz * vertsX + gx;
+                const current = offsets[index];
+                let next = current;
                 if (edit.mode === "raise")
-                    offsets[index] += strength * weight;
+                    next = current + strength * weight;
                 else if (edit.mode === "lower")
-                    offsets[index] -= strength * weight;
+                    next = current - strength * weight;
+                else if (edit.mode === "noise")
+                    next = current + fractalNoise(wx, wz, noiseConfig) * strength * weight;
+                else if (edit.mode === "smooth") {
+                    const target = neighborAverageHeight(gx, gz);
+                    const currentTotal = base.sampleHeight(wx, wz) + current;
+                    next = current + (target - currentTotal) * weight * strength;
+                }
                 else {
-                    const current = base.sampleHeight(wx, wz) + offsets[index];
-                    offsets[index] += (target - current) * weight * strength;
+                    const currentTotal = base.sampleHeight(wx, wz) + current;
+                    next = current + (flattenTarget - currentTotal) * weight * strength;
                 }
-                changed += 1;
+                if (writeOffset(index, next, limit, wx, wz, record))
+                    changed += 1;
             }
         }
         return changed;
     }
-    function paintSurface(edit) {
-        const surface = edit.surface ?? null;
+    function editRamp(edit, record) {
+        const to = edit.to;
+        if (to === undefined)
+            return 0;
+        const falloff = edit.falloff ?? "smooth";
+        const strength = edit.strength ?? 1;
+        const limit = edit.heightLimit;
+        const [ax, az] = edit.center;
+        const [bx, bz] = to;
+        const hFrom = edit.target ?? sampleHeight(ax, az);
+        const hTo = edit.targetTo ?? sampleHeight(bx, bz);
+        const segX = bx - ax;
+        const segZ = bz - az;
+        const segLenSq = segX * segX + segZ * segZ || 1;
+        const minGx = clampIndex(Math.floor(gridX(Math.min(ax, bx) - edit.radius)), vertsX - 1);
+        const maxGx = clampIndex(Math.ceil(gridX(Math.max(ax, bx) + edit.radius)), vertsX - 1);
+        const minGz = clampIndex(Math.floor(gridZ(Math.min(az, bz) - edit.radius)), vertsZ - 1);
+        const maxGz = clampIndex(Math.ceil(gridZ(Math.max(az, bz) + edit.radius)), vertsZ - 1);
+        let changed = 0;
+        for (let gz = minGz; gz <= maxGz; gz += 1) {
+            for (let gx = minGx; gx <= maxGx; gx += 1) {
+                const wx = vertexWorldX(gx);
+                const wz = vertexWorldZ(gz);
+                let t = ((wx - ax) * segX + (wz - az) * segZ) / segLenSq;
+                t = t < 0 ? 0 : t > 1 ? 1 : t;
+                const px = ax + segX * t;
+                const pz = az + segZ * t;
+                const weight = brushWeight(Math.hypot(wx - px, wz - pz), edit.radius, falloff);
+                if (weight <= 0)
+                    continue;
+                const index = gz * vertsX + gx;
+                const current = offsets[index];
+                const target = hFrom + (hTo - hFrom) * t;
+                const currentTotal = base.sampleHeight(wx, wz) + current;
+                const next = current + (target - currentTotal) * weight * strength;
+                if (writeOffset(index, next, limit, wx, wz, record))
+                    changed += 1;
+            }
+        }
+        return changed;
+    }
+    function cellWorldX(gx) {
+        return bounds.minX + ((gx + 0.5) / cols) * spanX;
+    }
+    function cellWorldZ(gz) {
+        return bounds.minZ + ((gz + 0.5) / rows) * spanZ;
+    }
+    function writeSurface(index, surface, record) {
+        const before = surfaces[index] ?? null;
+        if (before === surface)
+            return false;
+        surfaces[index] = surface;
+        record?.(index, before, surface);
+        return true;
+    }
+    /**
+     * Visits every cell in a brush footprint on the CELL grid, yielding each cell's flat `index`, its
+     * {@link brushWeight} `weight`, world center (`wx`,`wz`), and raw `dist` from the brush center.
+     * Shared by the cell-grid brushes ({@link paintSurface}, {@link blendPaint}); each applies its own
+     * inclusion test on the yielded values (paint uses `dist <= radius`, blend uses `weight > 0`).
+     */
+    function forEachBrushCell(edit, visit) {
+        const falloff = edit.falloff ?? "smooth";
+        const shape = edit.shape ?? "circle";
         const rCells = Math.ceil(edit.radius / cellSize) + 1;
         const cx = gridX(edit.center[0]);
         const cz = gridZ(edit.center[1]);
-        let painted = 0;
         for (let iz = -rCells; iz <= rCells; iz += 1) {
             const gz = Math.floor(cz) + iz;
             if (gz < 0 || gz >= rows)
@@ -102,36 +238,276 @@ export function createEditableTerrain(config) {
                 const gx = Math.floor(cx) + ix;
                 if (gx < 0 || gx >= cols)
                     continue;
-                const wx = bounds.minX + ((gx + 0.5) / cols) * spanX;
-                const wz = bounds.minZ + ((gz + 0.5) / rows) * spanZ;
-                if (Math.hypot(wx - edit.center[0], wz - edit.center[1]) > edit.radius)
-                    continue;
-                surfaces[gz * cols + gx] = surface;
+                const wx = cellWorldX(gx);
+                const wz = cellWorldZ(gz);
+                const dx = wx - edit.center[0];
+                const dz = wz - edit.center[1];
+                const dist = shape === "square" ? Math.max(Math.abs(dx), Math.abs(dz)) : Math.hypot(dx, dz);
+                visit(gz * cols + gx, brushWeight(dist, edit.radius, falloff), wx, wz, dist);
+            }
+        }
+    }
+    function paintSurface(edit, record) {
+        const surface = edit.surface ?? null;
+        let painted = 0;
+        // Binary inclusion by raw distance (includes dist == radius), independent of falloff shaping.
+        forEachBrushCell(edit, (index, _weight, _wx, _wz, dist) => {
+            if (dist > edit.radius)
+                return;
+            if (writeSurface(index, surface, record))
                 painted += 1;
+        });
+        return painted;
+    }
+    function localNormal(wx, wz) {
+        const eps = Math.max(cellSize, 0.5);
+        const hx = sampleHeight(wx + eps, wz) - sampleHeight(wx - eps, wz);
+        const hz = sampleHeight(wx, wz + eps) - sampleHeight(wx, wz - eps);
+        const nx = -hx;
+        const nz = -hz;
+        const ny = 2 * eps;
+        const length = Math.hypot(nx, ny, nz) || 1;
+        return [nx / length, ny / length, nz / length];
+    }
+    function autoPaint(rule, record) {
+        let painted = 0;
+        for (let gz = 0; gz < rows; gz += 1) {
+            for (let gx = 0; gx < cols; gx += 1) {
+                const wx = cellWorldX(gx);
+                const wz = cellWorldZ(gz);
+                const height = sampleHeight(wx, wz);
+                if (rule.minHeight !== undefined && height < rule.minHeight)
+                    continue;
+                if (rule.maxHeight !== undefined && height > rule.maxHeight)
+                    continue;
+                if (rule.minSlope !== undefined || rule.maxSlope !== undefined) {
+                    const [nx, ny, nz] = localNormal(wx, wz);
+                    const slope = Math.hypot(nx, nz) / Math.max(ny, 1e-9);
+                    if (rule.minSlope !== undefined && slope < rule.minSlope)
+                        continue;
+                    if (rule.maxSlope !== undefined && slope > rule.maxSlope)
+                        continue;
+                }
+                if (writeSurface(gz * cols + gx, rule.surface, record))
+                    painted += 1;
             }
         }
         return painted;
     }
-    function surfaceAt(x, z) {
+    function fillSurface(surface, record) {
+        let painted = 0;
+        for (let index = 0; index < surfaces.length; index += 1) {
+            if (writeSurface(index, surface, record))
+                painted += 1;
+        }
+        return painted;
+    }
+    function cellIndexAt(x, z) {
         const gx = Math.floor(gridX(x));
         const gz = Math.floor(gridZ(z));
         if (gx < 0 || gx >= cols || gz < 0 || gz >= rows)
+            return -1;
+        return gz * cols + gx;
+    }
+    function dominantLayerAt(cell) {
+        if (weights === null || layers.length === 0)
+            return -1;
+        const base = cell * layers.length;
+        let best = -1;
+        let bestWeight = 0;
+        for (let l = 0; l < layers.length; l += 1) {
+            const w = weights[base + l];
+            if (w > bestWeight) {
+                bestWeight = w;
+                best = l;
+            }
+        }
+        return best;
+    }
+    function surfaceAt(x, z) {
+        const cell = cellIndexAt(x, z);
+        if (cell < 0)
             return null;
-        return surfaces[gz * cols + gx] ?? null;
+        const dominant = dominantLayerAt(cell);
+        if (dominant >= 0)
+            return layers[dominant].surface;
+        return surfaces[cell] ?? null;
+    }
+    function weightsAt(x, z) {
+        const cell = cellIndexAt(x, z);
+        if (cell < 0 || weights === null || layers.length === 0)
+            return [];
+        const base = cell * layers.length;
+        return Array.from({ length: layers.length }, (_, l) => weights[base + l]);
+    }
+    /** Materializes the weight buffer, seeding each cell to weight 1 on its current dominant surface. */
+    function ensureWeights() {
+        if (weights !== null)
+            return weights;
+        const buffer = new Float32Array(cellCount * Math.max(1, layers.length));
+        if (layers.length > 0) {
+            for (let cell = 0; cell < cellCount; cell += 1) {
+                const surface = surfaces[cell];
+                const layer = surface === null ? -1 : layers.findIndex((entry) => entry.surface === surface);
+                if (layer >= 0)
+                    buffer[cell * layers.length + layer] = 1;
+            }
+        }
+        weights = buffer;
+        return buffer;
+    }
+    function blendCell(cell, target, amount, record) {
+        const buffer = ensureWeights();
+        const L = layers.length;
+        const base = cell * L;
+        const prevTarget = buffer[base + target];
+        const nextTarget = prevTarget + (1 - prevTarget) * amount;
+        if (nextTarget === prevTarget)
+            return false;
+        let othersSum = 0;
+        for (let l = 0; l < L; l += 1)
+            if (l !== target)
+                othersSum += buffer[base + l];
+        const remainder = 1 - nextTarget;
+        for (let l = 0; l < L; l += 1) {
+            const prev = buffer[base + l];
+            const next = l === target ? nextTarget : othersSum > 0 ? (prev / othersSum) * remainder : 0;
+            if (next !== prev) {
+                buffer[base + l] = next;
+                record?.(base + l, prev, next);
+            }
+        }
+        return true;
+    }
+    function blendPaint(edit, record) {
+        const surface = edit.surface;
+        if (surface === undefined || layers.length === 0)
+            return 0;
+        const target = layers.findIndex((entry) => entry.surface === surface);
+        if (target < 0)
+            return 0;
+        const strength = edit.strength ?? 1;
+        let painted = 0;
+        forEachBrushCell(edit, (index, weight) => {
+            if (weight <= 0)
+                return;
+            if (blendCell(index, target, weight * strength, record))
+                painted += 1;
+        });
+        return painted;
+    }
+    function runHeightEdit(edit, record) {
+        if (edit.mode === "ramp")
+            return editRamp(edit, record);
+        return editHeight(edit, record);
+    }
+    function surfaceDeltaFrom(run) {
+        const indices = [];
+        const before = [];
+        const after = [];
+        run((index, prev, next) => {
+            indices.push(index);
+            before.push(prev);
+            after.push(next);
+        });
+        return { indices, before, after };
     }
     const field = {
+        cols,
+        rows,
+        cellSize,
         sampleHeight,
         sampleNormal,
         ...(base.bounds === undefined ? {} : { bounds: base.bounds }),
         ...(base.waterLevel === undefined ? {} : { waterLevel: base.waterLevel }),
         apply(edit) {
-            return edit.mode === "paint" ? paintSurface(edit) : editHeight(edit);
+            return edit.mode === "paint" ? paintSurface(edit, null) : runHeightEdit(edit, null);
+        },
+        applyRecording(edit, record) {
+            return runHeightEdit(edit, record);
+        },
+        editDelta(edit) {
+            const indices = [];
+            const before = [];
+            const after = [];
+            runHeightEdit(edit, (index, prev, next) => {
+                indices.push(index);
+                before.push(prev);
+                after.push(next);
+            });
+            return { indices, before, after };
+        },
+        applyDelta(delta) {
+            for (let i = 0; i < delta.indices.length; i += 1)
+                offsets[delta.indices[i]] = delta.after[i];
+        },
+        revertDelta(delta) {
+            for (let i = 0; i < delta.indices.length; i += 1)
+                offsets[delta.indices[i]] = delta.before[i];
+        },
+        paintRecording(edit, record) {
+            return paintSurface(edit, record);
+        },
+        paintDelta(edit) {
+            return surfaceDeltaFrom((record) => paintSurface(edit, record));
+        },
+        fillSurfaceDelta(surface) {
+            return surfaceDeltaFrom((record) => fillSurface(surface, record));
+        },
+        autoPaintDelta(rule) {
+            return surfaceDeltaFrom((record) => autoPaint(rule, record));
+        },
+        applySurfaceDelta(delta) {
+            for (let i = 0; i < delta.indices.length; i += 1)
+                surfaces[delta.indices[i]] = delta.after[i] ?? null;
+        },
+        revertSurfaceDelta(delta) {
+            for (let i = 0; i < delta.indices.length; i += 1)
+                surfaces[delta.indices[i]] = delta.before[i] ?? null;
         },
+        get layers() {
+            return layers;
+        },
+        setLayers(next) {
+            layers = next.map((layer) => ({ ...layer }));
+            // Layer count changed shape: drop the weight buffer, blends re-seed from surfaces on demand.
+            weights = null;
+        },
+        blendRecording(edit, record) {
+            return blendPaint(edit, record);
+        },
+        blendPaintDelta(edit) {
+            const indices = [];
+            const before = [];
+            const after = [];
+            blendPaint(edit, (index, prev, next) => {
+                indices.push(index);
+                before.push(prev);
+                after.push(next);
+            });
+            return { layerCount: layers.length, indices, before, after };
+        },
+        applyWeightDelta(delta) {
+            if (delta.layerCount !== layers.length)
+                return;
+            const buffer = ensureWeights();
+            for (let i = 0; i < delta.indices.length; i += 1)
+                buffer[delta.indices[i]] = delta.after[i];
+        },
+        revertWeightDelta(delta) {
+            if (delta.layerCount !== layers.length)
+                return;
+            const buffer = ensureWeights();
+            for (let i = 0; i < delta.indices.length; i += 1)
+                buffer[delta.indices[i]] = delta.before[i];
+        },
+        weightsAt,
         heightOffsetAt,
         surfaceAt,
         reset() {
             offsets.fill(0);
             surfaces.fill(null);
+            weights = null;
         },
         snapshot() {
             return {
@@ -141,6 +517,8 @@ export function createEditableTerrain(config) {
                 rows,
                 offsets: Array.from(offsets),
                 surfaces: surfaces.slice(),
+                ...(layers.length === 0 ? {} : { layers: layers.map((layer) => ({ ...layer })) }),
+                ...(weights === null ? {} : { weights: Array.from(weights) }),
             };
         },
         restore(snapshot) {
@@ -150,10 +528,237 @@ export function createEditableTerrain(config) {
             const surfaceCount = Math.min(surfaces.length, snapshot.surfaces.length);
             for (let index = 0; index < surfaceCount; index += 1)
                 surfaces[index] = snapshot.surfaces[index] ?? null;
+            layers = (snapshot.layers ?? []).map((layer) => ({ ...layer }));
+            if (snapshot.weights === undefined || layers.length === 0) {
+                weights = null;
+            }
+            else {
+                const buffer = new Float32Array(cellCount * layers.length);
+                const copy = Math.min(buffer.length, snapshot.weights.length);
+                for (let index = 0; index < copy; index += 1)
+                    buffer[index] = snapshot.weights[index];
+                weights = buffer;
+            }
         },
     };
     return field;
 }
+/**
+ * The shared first/latest Map accumulator behind every `begin*Stroke`. Records each key's first
+ * `before` and latest `after` across many stamps, then assembles the net changed entries (skipping
+ * keys whose latest equals their first). Each stroke supplies its own recording call via `recordStamp`
+ * and wraps {@link StrokeChanges} into its concrete delta shape.
+ */
+function createStroke(recordStamp) {
+    const first = new Map();
+    const latest = new Map();
+    return {
+        stamp(edit) {
+            return recordStamp(edit, (index, before, after) => {
+                if (!first.has(index))
+                    first.set(index, before);
+                latest.set(index, after);
+            });
+        },
+        changes() {
+            const indices = [];
+            const before = [];
+            const after = [];
+            for (const [index, next] of latest) {
+                // Every latest key was set in `first` on the same callback, so this is always present.
+                const prev = first.get(index);
+                if (next === prev)
+                    continue;
+                indices.push(index);
+                before.push(prev);
+                after.push(next);
+            }
+            return { indices, before, after };
+        },
+        isEmpty() {
+            return latest.size === 0;
+        },
+    };
+}
+/** Opens a stroke recorder over `terrain`; stamp edits into it, then read one net delta. */
+export function beginTerraformStroke(terrain) {
+    const stroke = createStroke((edit, record) => terrain.applyRecording(edit, record));
+    return {
+        stamp: stroke.stamp,
+        delta: () => stroke.changes(),
+        isEmpty: stroke.isEmpty,
+    };
+}
+/** Opens a paint-stroke recorder over `terrain`; stamp paint edits into it, then read one net delta. */
+export function beginSurfaceStroke(terrain) {
+    const stroke = createStroke((edit, record) => terrain.paintRecording(edit, record));
+    return {
+        stamp: stroke.stamp,
+        delta: () => stroke.changes(),
+        isEmpty: stroke.isEmpty,
+    };
+}
+/** Returns a new snapshot with a surface delta's `after` ids applied (copy-on-write). */
+export function applySurfaceDeltaToSnapshot(snapshot, delta) {
+    const surfaces = snapshot.surfaces.slice();
+    for (let i = 0; i < delta.indices.length; i += 1)
+        surfaces[delta.indices[i]] = delta.after[i] ?? null;
+    return { ...snapshot, surfaces };
+}
+/** Returns a new snapshot with a surface delta's `before` ids restored (copy-on-write undo). */
+export function revertSurfaceDeltaFromSnapshot(snapshot, delta) {
+    const surfaces = snapshot.surfaces.slice();
+    for (let i = 0; i < delta.indices.length; i += 1)
+        surfaces[delta.indices[i]] = delta.before[i] ?? null;
+    return { ...snapshot, surfaces };
+}
+/** The distinct non-null surface ids painted in a snapshot, in first-seen order. */
+function distinctSurfaces(snapshot) {
+    const seen = new Set();
+    const out = [];
+    for (const surface of snapshot.surfaces) {
+        if (surface !== null && !seen.has(surface)) {
+            seen.add(surface);
+            out.push(surface);
+        }
+    }
+    return out;
+}
+/**
+ * Upgrades a pre-2.0 snapshot in place-safe (copy-on-write) form: derives a {@link TerrainMaterialLayer}
+ * stack from the distinct painted surfaces (first-seen order, default params) when none exists.
+ * Leaves the lazy `weights` buffer absent — a single-layer terrain stays compact until blended.
+ * Idempotent: a snapshot that already carries `layers` is returned unchanged.
+ */
+export function migrateTerrainSnapshot(snapshot) {
+    if (snapshot.layers !== undefined)
+        return snapshot;
+    const layers = distinctSurfaces(snapshot).map((surface) => ({
+        id: surface,
+        surface,
+        roughness: 0.9,
+        tiling: 8,
+    }));
+    return { ...snapshot, layers };
+}
+/** Materializes a snapshot's blend weights, seeding weight 1 on each cell's dominant surface. */
+function materializeSnapshotWeights(snapshot) {
+    const layers = snapshot.layers ?? [];
+    const cells = snapshot.cols * snapshot.rows;
+    const buffer = new Array(cells * Math.max(1, layers.length)).fill(0);
+    if (snapshot.weights !== undefined) {
+        const copy = Math.min(buffer.length, snapshot.weights.length);
+        for (let i = 0; i < copy; i += 1)
+            buffer[i] = snapshot.weights[i];
+        return buffer;
+    }
+    if (layers.length > 0) {
+        for (let cell = 0; cell < cells; cell += 1) {
+            const surface = snapshot.surfaces[cell] ?? null;
+            const layer = surface === null ? -1 : layers.findIndex((entry) => entry.surface === surface);
+            if (layer >= 0)
+                buffer[cell * layers.length + layer] = 1;
+        }
+    }
+    return buffer;
+}
+/**
+ * Returns a new snapshot with a weight delta's `after` values applied (materializing weights first).
+ * @internal — undo/redo plumbing behind the `blendTerrain` command.
+ */
+export function applyWeightDeltaToSnapshot(snapshot, delta) {
+    if (delta.layerCount !== (snapshot.layers?.length ?? 0))
+        return snapshot;
+    const weights = materializeSnapshotWeights(snapshot);
+    for (let i = 0; i < delta.indices.length; i += 1)
+        weights[delta.indices[i]] = delta.after[i];
+    return { ...snapshot, weights };
+}
+/**
+ * Returns a new snapshot with a weight delta's `before` values restored (copy-on-write undo).
+ * @internal — undo/redo plumbing behind the `blendTerrain` command.
+ */
+export function revertWeightDeltaFromSnapshot(snapshot, delta) {
+    if (delta.layerCount !== (snapshot.layers?.length ?? 0))
+        return snapshot;
+    const weights = materializeSnapshotWeights(snapshot);
+    for (let i = 0; i < delta.indices.length; i += 1)
+        weights[delta.indices[i]] = delta.before[i];
+    return { ...snapshot, weights };
+}
+/**
+ * Opens a blend-stroke recorder over `terrain`; stamp blend edits into it, then read one net delta.
+ * @internal — the stroke recorder behind the blend brush and the `blendTerrain` command.
+ */
+export function beginBlendStroke(terrain) {
+    const stroke = createStroke((edit, record) => terrain.blendRecording(edit, record));
+    return {
+        stamp: stroke.stamp,
+        // layerCount is read at delta() time, guarding replay after the layer stack changed shape.
+        delta: () => ({ layerCount: terrain.layers.length, ...stroke.changes() }),
+        isEmpty: stroke.isEmpty,
+    };
+}
+/**
+ * The world-space {@link Aabb} spanning the vertices a stroke's `indices` touched (indices into the
+ * `(cols+1)×(rows+1)` offset grid), expanded by `margin` meters. Drives partial preview-mesh
+ * rebuilds — only the dirty submesh re-samples instead of the whole heightfield. Null if empty.
+ * @internal — the editor's preview-mesh rebuild uses this; not a game-facing primitive.
+ */
+export function dirtyBoundsFromIndices(snapshot, indices, margin = 0) {
+    if (indices.length === 0)
+        return null;
+    const vertsX = snapshot.cols + 1;
+    const spanX = Math.max(snapshot.bounds.maxX - snapshot.bounds.minX, snapshot.cellSize);
+    const spanZ = Math.max(snapshot.bounds.maxZ - snapshot.bounds.minZ, snapshot.cellSize);
+    let minX = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxZ = -Infinity;
+    for (const index of indices) {
+        const gx = index % vertsX;
+        const gz = Math.floor(index / vertsX);
+        const wx = snapshot.bounds.minX + (gx / snapshot.cols) * spanX;
+        const wz = snapshot.bounds.minZ + (gz / snapshot.rows) * spanZ;
+        if (wx < minX)
+            minX = wx;
+        if (wx > maxX)
+            maxX = wx;
+        if (wz < minZ)
+            minZ = wz;
+        if (wz > maxZ)
+            maxZ = wz;
+    }
+    return { minX: minX - margin, minZ: minZ - margin, maxX: maxX + margin, maxZ: maxZ + margin };
+}
+/** A fresh, unedited terrain snapshot sized to `bounds`/`cellSize` — the seed for a new sculpt document. */
+export function createTerrainSnapshot(config) {
+    return createEditableTerrain(config).snapshot();
+}
+/** Rebuilds a live {@link EditableTerrain} from a snapshot, layered over `base` ground. */
+export function editableTerrainFromSnapshot(snapshot, base) {
+    const terrain = createEditableTerrain({
+        bounds: snapshot.bounds,
+        cellSize: snapshot.cellSize,
+        ...(base === undefined ? {} : { base }),
+    });
+    terrain.restore(snapshot);
+    return terrain;
+}
+/** Returns a new snapshot with a delta's `after` offsets applied (copy-on-write — inputs untouched). */
+export function applyDeltaToSnapshot(snapshot, delta) {
+    const offsets = snapshot.offsets.slice();
+    for (let i = 0; i < delta.indices.length; i += 1)
+        offsets[delta.indices[i]] = delta.after[i];
+    return { ...snapshot, offsets };
+}
+/** Returns a new snapshot with a delta's `before` offsets restored (copy-on-write undo). */
+export function revertDeltaFromSnapshot(snapshot, delta) {
+    const offsets = snapshot.offsets.slice();
+    for (let i = 0; i < delta.indices.length; i += 1)
+        offsets[delta.indices[i]] = delta.before[i];
+    return { ...snapshot, offsets };
+}
 export function createTerraformBrush(terrain, config = {}) {
     let radius = config.radius ?? 3;
     let strength = config.strength ?? 0.5;