@jgengine/core 0.11.0 → 0.13.0

package/dist/world/streets.d.ts

@@ -1,5 +1,5 @@
 import type { RoadEnvironmentDescriptor } from "./features.js";
-import { type RoadPoint } from "./roads.js";
+import { type DashExclusion, type RoadPoint } from "./roads.js";
 /**
  * Offset a centerline sideways by a signed distance along its local perpendicular — the
  * building block for lanes, curb lines, and sidewalk paths. Positive offsets fall on the
@@ -73,8 +73,110 @@ export interface ParkingSpot {
  * coordinates in the middle of the carriageway.
  */
 export declare function parkingSpots(road: RoadEnvironmentDescriptor, options?: ParkingSpotOptions): readonly ParkingSpot[];
+/**
+ * Signed planar distance from `(x, z)` to the nearest road *surface edge* across every segment of
+ * every road (#1051): negative inside the asphalt (magnitude = how far in from the closest edge, so
+ * `-width/2` on the centerline), `~0` right at the curb, and positive off the road (the gap to the
+ * nearest edge). Point-to-segment distance minus the road's half width, minimised over all segments —
+ * the "am I on the road, and by how much" seam driving grip, tyre audio, and off-road penalties.
+ *
+ * Allocation-free per call (only scalars — no arrays or objects) so a per-tick car sim can sample it
+ * on the hot path; degenerate roads (fewer than two path points) contribute nothing, and with no road
+ * surface at all it returns {@link Number.POSITIVE_INFINITY} (everywhere is off-road).
+ */
+export declare function distanceToRoadEdge(roads: readonly RoadEnvironmentDescriptor[], x: number, z: number): number;
+/** Grip levels and blend width for {@link roadSurfaceSampler}; each field is optional and defaulted. */
+export interface RoadSurfaceOptions {
+    /** Grip multiplier on the asphalt. Default 1. */
+    onRoad?: number;
+    /** Grip multiplier once fully off the road past the shoulder. Default 0.72. */
+    offRoad?: number;
+    /** Width (world units) of the blend band outside the curb from full to off-road grip. Default 3. */
+    shoulder?: number;
+}
+/**
+ * A `surfaceFriction`-compatible sampler (the `(x, z) => grip` hook a kinematic car reads each tick)
+ * that turns road geometry into grip (#1051): full `onRoad` grip on the asphalt, a monotonic linear ramp
+ * down across a `shoulder`-wide band at the curb, and flat `offRoad` grip beyond it — so a car that
+ * clips onto the grass loses bite progressively instead of snapping. Closes over {@link
+ * distanceToRoadEdge}, so the returned sampler is itself allocation-free per call.
+ */
+export declare function roadSurfaceSampler(roads: readonly RoadEnvironmentDescriptor[], options?: RoadSurfaceOptions): (x: number, z: number) => number;
 /**
  * A deterministic point on one of a road's sidewalks at a normalized position — `side` picks the
  * band, `fraction` (0..1) picks how far along. The canonical pedestrian spawn helper.
  */
 export declare function sidewalkPoint(road: RoadEnvironmentDescriptor, side: "left" | "right", fraction: number): RoadPoint | null;
+/**
+ * The two curb lines of a road — offset polylines running along the outer edge of the asphalt on
+ * each side. Mesh these with a thin darker ribbon to give the road a curb/edge strip instead of a
+ * hard asphalt-to-terrain seam. `inset` (default 0) nudges the line inward off the raw edge so the
+ * strip straddles the border.
+ */
+export declare function curbPaths(road: RoadEnvironmentDescriptor, inset?: number): readonly [readonly RoadPoint[], readonly RoadPoint[]];
+/** A single arm of a junction: the road width plus the outward direction the road leaves the center. */
+export interface RoadApproach {
+    /** Unit vector pointing from the junction center outward along the road arm. */
+    direction: readonly [number, number];
+    /** Drivable width of the road on this arm. */
+    width: number;
+}
+/** A welded road intersection: a patch center/radius plus the arms that feed it. */
+export interface RoadJunction {
+    /** World XZ center of the intersection. */
+    center: RoadPoint;
+    /** Radius of the covering patch (covers the crossing ribbons). */
+    radius: number;
+    /** Representative surface elevation (max of the participating roads). */
+    elevation: number;
+    /** Representative asphalt color (the widest participating road's color). */
+    color: string;
+    /** Outward arms leaving the junction — one per road direction that continues past the center. */
+    approaches: readonly RoadApproach[];
+}
+/** Options for {@link findRoadJunctions}. */
+export interface RoadJunctionOptions {
+    /** Roads weld only when their elevations differ by at most this much. Default 0.12. */
+    elevationBand?: number;
+    /** Crossing points closer than this merge into a single junction. Default 6. */
+    mergeDistance?: number;
+    /** Hard cap on junctions returned so detection stays bounded. Default 256. */
+    maxJunctions?: number;
+    /** Extra scale on the patch radius past the widest arm's half-width. Default 1.15. */
+    radiusScale?: number;
+}
+/**
+ * Detect welded intersections across a set of roads: wherever two road centerlines cross (or a road
+ * terminates on another) within the same elevation band, emit a {@link RoadJunction} whose patch
+ * covers the crossing ribbons. Nearby crossings merge into one junction. Deterministic and bounded —
+ * O(roads² · segments²) with a `maxJunctions` cap — so a scene builds its intersections once.
+ */
+export declare function findRoadJunctions(roads: readonly RoadEnvironmentDescriptor[], options?: RoadJunctionOptions): readonly RoadJunction[];
+/** Circular marking-exclusion zones for the junctions, sized to hide the center line under each patch. */
+export declare function junctionExclusions(junctions: readonly RoadJunction[], pad?: number): readonly DashExclusion[];
+/** Options for {@link junctionMarkings}. */
+export interface JunctionMarkingOptions {
+    /** Emit a stop-line bar across each approach. Default true. */
+    stopLines?: boolean;
+    /** Emit crosswalk bars at each approach. Default true. */
+    crosswalks?: boolean;
+    /** Number of zebra bars per crosswalk. Default 5. */
+    crosswalkBars?: number;
+    /** Clear gap outside the patch before markings start. Default 0.6. */
+    gap?: number;
+    /** Depth (along travel) of the crosswalk band. Default 2.4. */
+    crosswalkDepth?: number;
+}
+/** Thin marking polylines for a junction: stop-line bars and crosswalk bars, ready for {@link buildRoadRibbon}. */
+export interface JunctionMarkings {
+    /** One bar per approach, perpendicular to travel just outside the patch. */
+    stopLines: readonly (readonly RoadPoint[])[];
+    /** Continental (parallel-to-travel) zebra bars, `crosswalkBars` per approach. */
+    crosswalkBars: readonly (readonly RoadPoint[])[];
+}
+/**
+ * Data-driven junction entry markings: a stop-line bar across each approach and a band of crosswalk
+ * bars just outside the welded patch. Each returned polyline is a thin centerline meant to be meshed
+ * with {@link buildRoadRibbon} at a small width. Fully skippable per-feature via the options.
+ */
+export declare function junctionMarkings(junction: RoadJunction, options?: JunctionMarkingOptions): JunctionMarkings;

package/dist/world/streets.js

@@ -130,6 +130,61 @@ export function parkingSpots(road, options = {}) {
     }
     return spots;
 }
+/**
+ * Signed planar distance from `(x, z)` to the nearest road *surface edge* across every segment of
+ * every road (#1051): negative inside the asphalt (magnitude = how far in from the closest edge, so
+ * `-width/2` on the centerline), `~0` right at the curb, and positive off the road (the gap to the
+ * nearest edge). Point-to-segment distance minus the road's half width, minimised over all segments —
+ * the "am I on the road, and by how much" seam driving grip, tyre audio, and off-road penalties.
+ *
+ * Allocation-free per call (only scalars — no arrays or objects) so a per-tick car sim can sample it
+ * on the hot path; degenerate roads (fewer than two path points) contribute nothing, and with no road
+ * surface at all it returns {@link Number.POSITIVE_INFINITY} (everywhere is off-road).
+ */
+export function distanceToRoadEdge(roads, x, z) {
+    let best = Number.POSITIVE_INFINITY;
+    for (let r = 0; r < roads.length; r += 1) {
+        const road = roads[r];
+        const path = road.path;
+        if (path.length < 2)
+            continue;
+        const half = road.width / 2;
+        for (let i = 0; i < path.length - 1; i += 1) {
+            const a = path[i];
+            const b = path[i + 1];
+            const abx = b[0] - a[0];
+            const abz = b[1] - a[1];
+            const lengthSq = abx * abx + abz * abz;
+            const t = lengthSq === 0 ? 0 : Math.max(0, Math.min(1, ((x - a[0]) * abx + (z - a[1]) * abz) / lengthSq));
+            const px = a[0] + abx * t;
+            const pz = a[1] + abz * t;
+            const edge = Math.hypot(x - px, z - pz) - half;
+            if (edge < best)
+                best = edge;
+        }
+    }
+    return best;
+}
+/**
+ * A `surfaceFriction`-compatible sampler (the `(x, z) => grip` hook a kinematic car reads each tick)
+ * that turns road geometry into grip (#1051): full `onRoad` grip on the asphalt, a monotonic linear ramp
+ * down across a `shoulder`-wide band at the curb, and flat `offRoad` grip beyond it — so a car that
+ * clips onto the grass loses bite progressively instead of snapping. Closes over {@link
+ * distanceToRoadEdge}, so the returned sampler is itself allocation-free per call.
+ */
+export function roadSurfaceSampler(roads, options = {}) {
+    const onRoad = options.onRoad ?? 1;
+    const offRoad = options.offRoad ?? 0.72;
+    const shoulder = options.shoulder ?? 3;
+    return (x, z) => {
+        const edge = distanceToRoadEdge(roads, x, z);
+        if (edge <= 0)
+            return onRoad;
+        if (shoulder <= 0 || edge >= shoulder)
+            return offRoad;
+        return onRoad + (offRoad - onRoad) * (edge / shoulder);
+    };
+}
 /**
  * A deterministic point on one of a road's sidewalks at a normalized position — `side` picks the
  * band, `fraction` (0..1) picks how far along. The canonical pedestrian spawn helper.
@@ -142,3 +197,221 @@ export function sidewalkPoint(road, side, fraction) {
     const along = Math.max(0, Math.min(1, fraction)) * pathLength(path);
     return pointAlong(path, along).point;
 }
+/**
+ * The two curb lines of a road — offset polylines running along the outer edge of the asphalt on
+ * each side. Mesh these with a thin darker ribbon to give the road a curb/edge strip instead of a
+ * hard asphalt-to-terrain seam. `inset` (default 0) nudges the line inward off the raw edge so the
+ * strip straddles the border.
+ */
+export function curbPaths(road, inset = 0) {
+    const edge = road.width / 2 - inset;
+    return [offsetPath(road.path, edge), offsetPath(road.path, -edge)];
+}
+const EPS = 1e-6;
+/** Intersection point of segments a→b and c→d, or null when they don't cross (endpoints included). */
+function segmentIntersection(a, b, c, d) {
+    const r0 = b[0] - a[0];
+    const r1 = b[1] - a[1];
+    const s0 = d[0] - c[0];
+    const s1 = d[1] - c[1];
+    const denom = r0 * s1 - r1 * s0;
+    if (Math.abs(denom) < EPS)
+        return null; // parallel or degenerate
+    const t = ((c[0] - a[0]) * s1 - (c[1] - a[1]) * s0) / denom;
+    const u = ((c[0] - a[0]) * r1 - (c[1] - a[1]) * r0) / denom;
+    if (t < -EPS || t > 1 + EPS || u < -EPS || u > 1 + EPS)
+        return null;
+    return [a[0] + r0 * t, a[1] + r1 * t];
+}
+function unit(dx, dz) {
+    const len = Math.hypot(dx, dz) || 1;
+    return [dx / len, dz / len];
+}
+/**
+ * Add the arms a road contributes at junction point `p`: the road continues past `p` in each
+ * direction that still has centerline beyond it, so a mid-path crossing yields two opposing arms
+ * and a road that terminates at `p` (a T-junction) yields only the one inward arm.
+ */
+function armsAt(path, p, width, roadIndex) {
+    const arms = [];
+    // Nearest vertex "before" (toward path start) and "after" (toward path end) of p.
+    // Walk the path measuring where p falls; use the two adjacent tangents.
+    let hitSeg = -1;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const abx = b[0] - a[0];
+        const abz = b[1] - a[1];
+        const lengthSq = abx * abx + abz * abz;
+        const t = lengthSq === 0 ? 0 : ((p[0] - a[0]) * abx + (p[1] - a[1]) * abz) / lengthSq;
+        const px = a[0] + abx * Math.max(0, Math.min(1, t));
+        const pz = a[1] + abz * Math.max(0, Math.min(1, t));
+        if (Math.hypot(p[0] - px, p[1] - pz) < 1e-3) {
+            hitSeg = i;
+            break;
+        }
+    }
+    if (hitSeg < 0)
+        return arms;
+    const a = path[hitSeg];
+    const b = path[hitSeg + 1];
+    const forward = unit(b[0] - a[0], b[1] - a[1]);
+    const atStart = Math.hypot(p[0] - path[0][0], p[1] - path[0][1]) < 1e-3;
+    const atEnd = Math.hypot(p[0] - path[path.length - 1][0], p[1] - path[path.length - 1][1]) < 1e-3;
+    // Arm toward path end exists unless p sits exactly at the end.
+    if (!atEnd)
+        arms.push({ roadIndex, direction: forward, width });
+    // Arm toward path start exists unless p sits exactly at the start.
+    if (!atStart)
+        arms.push({ roadIndex, direction: [-forward[0], -forward[1]], width });
+    return arms;
+}
+function mergeArm(arms, arm) {
+    for (const existing of arms) {
+        if (existing.roadIndex === arm.roadIndex) {
+            const dot = existing.direction[0] * arm.direction[0] + existing.direction[1] * arm.direction[1];
+            if (dot > 0.985)
+                return; // same road, near-identical direction — already have this arm
+        }
+    }
+    arms.push(arm);
+}
+/**
+ * Detect welded intersections across a set of roads: wherever two road centerlines cross (or a road
+ * terminates on another) within the same elevation band, emit a {@link RoadJunction} whose patch
+ * covers the crossing ribbons. Nearby crossings merge into one junction. Deterministic and bounded —
+ * O(roads² · segments²) with a `maxJunctions` cap — so a scene builds its intersections once.
+ */
+export function findRoadJunctions(roads, options = {}) {
+    const elevationBand = options.elevationBand ?? 0.12;
+    const mergeDistance = options.mergeDistance ?? 6;
+    const maxJunctions = options.maxJunctions ?? 256;
+    const radiusScale = options.radiusScale ?? 1.15;
+    const mergeSq = mergeDistance * mergeDistance;
+    const candidates = [];
+    const emit = (p, ri, ci) => {
+        if (candidates.length >= maxJunctions && findNear(candidates, p, mergeSq) === null)
+            return;
+        const roadA = roads[ri];
+        const roadB = roads[ci];
+        const half = Math.max(roadA.width, roadB.width) / 2;
+        const radius = half * radiusScale;
+        const elevation = Math.max(roadA.elevation, roadB.elevation);
+        const wider = roadA.width >= roadB.width ? roadA : roadB;
+        const near = findNear(candidates, p, mergeSq);
+        const arms = [
+            ...armsAt(roadA.path, p, roadA.width, ri),
+            ...armsAt(roadB.path, p, roadB.width, ci),
+        ];
+        if (near === null) {
+            const merged = [];
+            for (const arm of arms)
+                mergeArm(merged, arm);
+            candidates.push({
+                x: p[0],
+                z: p[1],
+                radius,
+                elevation,
+                color: wider.color,
+                colorWidth: wider.width,
+                arms: merged,
+            });
+        }
+        else {
+            near.radius = Math.max(near.radius, radius);
+            near.elevation = Math.max(near.elevation, elevation);
+            if (wider.width > near.colorWidth) {
+                near.color = wider.color;
+                near.colorWidth = wider.width;
+            }
+            for (const arm of arms)
+                mergeArm(near.arms, arm);
+        }
+    };
+    for (let i = 0; i < roads.length; i += 1) {
+        const roadA = roads[i];
+        if (roadA.path.length < 2)
+            continue;
+        for (let j = i + 1; j < roads.length; j += 1) {
+            const roadB = roads[j];
+            if (roadB.path.length < 2)
+                continue;
+            if (Math.abs(roadA.elevation - roadB.elevation) > elevationBand)
+                continue;
+            for (let si = 0; si < roadA.path.length - 1; si += 1) {
+                for (let sj = 0; sj < roadB.path.length - 1; sj += 1) {
+                    const hit = segmentIntersection(roadA.path[si], roadA.path[si + 1], roadB.path[sj], roadB.path[sj + 1]);
+                    if (hit !== null)
+                        emit(hit, i, j);
+                }
+            }
+        }
+    }
+    return candidates.map((c) => ({
+        center: [c.x, c.z],
+        radius: c.radius,
+        elevation: c.elevation,
+        color: c.color,
+        approaches: c.arms.map((arm) => ({ direction: arm.direction, width: arm.width })),
+    }));
+}
+function findNear(candidates, p, mergeSq) {
+    for (const c of candidates) {
+        const dx = c.x - p[0];
+        const dz = c.z - p[1];
+        if (dx * dx + dz * dz <= mergeSq)
+            return c;
+    }
+    return null;
+}
+/** Circular marking-exclusion zones for the junctions, sized to hide the center line under each patch. */
+export function junctionExclusions(junctions, pad = 0.5) {
+    return junctions.map((j) => ({ center: j.center, radius: j.radius + pad }));
+}
+/**
+ * Data-driven junction entry markings: a stop-line bar across each approach and a band of crosswalk
+ * bars just outside the welded patch. Each returned polyline is a thin centerline meant to be meshed
+ * with {@link buildRoadRibbon} at a small width. Fully skippable per-feature via the options.
+ */
+export function junctionMarkings(junction, options = {}) {
+    const wantStop = options.stopLines ?? true;
+    const wantCross = options.crosswalks ?? true;
+    const barCount = Math.max(1, Math.floor(options.crosswalkBars ?? 5));
+    const gap = options.gap ?? 0.6;
+    const depth = options.crosswalkDepth ?? 2.4;
+    const [cx, cz] = junction.center;
+    const stopLines = [];
+    const crosswalkBars = [];
+    for (const approach of junction.approaches) {
+        const [dx, dz] = approach.direction;
+        // Across-the-road axis, perpendicular to travel.
+        const ax = -dz;
+        const az = dx;
+        const half = approach.width / 2;
+        const stopDist = junction.radius + gap;
+        if (wantStop) {
+            const px = cx + dx * stopDist;
+            const pz = cz + dz * stopDist;
+            stopLines.push([
+                [px + ax * half, pz + az * half],
+                [px - ax * half, pz - az * half],
+            ]);
+        }
+        if (wantCross) {
+            const near = stopDist + 0.4;
+            const barWidth = half * 2 * 0.16;
+            const usable = half * 2 - barWidth;
+            for (let b = 0; b < barCount; b += 1) {
+                const frac = barCount === 1 ? 0 : b / (barCount - 1) - 0.5;
+                const offset = frac * usable;
+                const bx = cx + ax * offset;
+                const bz = cz + az * offset;
+                crosswalkBars.push([
+                    [bx + dx * near, bz + dz * near],
+                    [bx + dx * (near + depth), bz + dz * (near + depth)],
+                ]);
+            }
+        }
+    }
+    return { stopLines, crosswalkBars };
+}

package/dist/world/terraform.js

@@ -218,13 +218,18 @@ export function createEditableTerrain(config) {
         record?.(index, before, surface);
         return true;
     }
-    function paintSurface(edit, record) {
-        const surface = edit.surface ?? null;
+    /**
+     * 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)
@@ -233,15 +238,25 @@ export function createEditableTerrain(config) {
                 const gx = Math.floor(cx) + ix;
                 if (gx < 0 || gx >= cols)
                     continue;
-                const dx = cellWorldX(gx) - edit.center[0];
-                const dz = cellWorldZ(gz) - edit.center[1];
+                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);
-                if (dist > edit.radius)
-                    continue;
-                if (writeSurface(gz * cols + gx, surface, record))
-                    painted += 1;
+                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) {
@@ -371,31 +386,14 @@ export function createEditableTerrain(config) {
         const target = layers.findIndex((entry) => entry.surface === surface);
         if (target < 0)
             return 0;
-        const falloff = edit.falloff ?? "smooth";
-        const shape = edit.shape ?? "circle";
         const strength = edit.strength ?? 1;
-        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)
-                continue;
-            for (let ix = -rCells; ix <= rCells; ix += 1) {
-                const gx = Math.floor(cx) + ix;
-                if (gx < 0 || gx >= cols)
-                    continue;
-                const dx = cellWorldX(gx) - edit.center[0];
-                const dz = cellWorldZ(gz) - 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;
-                if (blendCell(gz * cols + gx, target, weight * strength, record))
-                    painted += 1;
-            }
-        }
+        forEachBrushCell(edit, (index, weight) => {
+            if (weight <= 0)
+                return;
+            if (blendCell(index, target, weight * strength, record))
+                painted += 1;
+        });
         return painted;
     }
     function runHeightEdit(edit, record) {
@@ -545,23 +543,29 @@ export function createEditableTerrain(config) {
     };
     return field;
 }
-/** Opens a stroke recorder over `terrain`; stamp edits into it, then read one net delta. */
-export function beginTerraformStroke(terrain) {
+/**
+ * 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 terrain.applyRecording(edit, (index, before, after) => {
+            return recordStamp(edit, (index, before, after) => {
                 if (!first.has(index))
                     first.set(index, before);
                 latest.set(index, after);
             });
         },
-        delta() {
+        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;
@@ -576,35 +580,22 @@ export function beginTerraformStroke(terrain) {
         },
     };
 }
+/** 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 first = new Map();
-    const latest = new Map();
+    const stroke = createStroke((edit, record) => terrain.paintRecording(edit, record));
     return {
-        stamp(edit) {
-            return terrain.paintRecording(edit, (index, before, after) => {
-                if (!first.has(index))
-                    first.set(index, before);
-                latest.set(index, after);
-            });
-        },
-        delta() {
-            const indices = [];
-            const before = [];
-            const after = [];
-            for (const [index, next] of latest) {
-                const prev = first.get(index) ?? null;
-                if (next === prev)
-                    continue;
-                indices.push(index);
-                before.push(prev);
-                after.push(next);
-            }
-            return { indices, before, after };
-        },
-        isEmpty() {
-            return latest.size === 0;
-        },
+        stamp: stroke.stamp,
+        delta: () => stroke.changes(),
+        isEmpty: stroke.isEmpty,
     };
 }
 /** Returns a new snapshot with a surface delta's `after` ids applied (copy-on-write). */
@@ -700,33 +691,12 @@ export function revertWeightDeltaFromSnapshot(snapshot, delta) {
  * @internal — the stroke recorder behind the blend brush and the `blendTerrain` command.
  */
 export function beginBlendStroke(terrain) {
-    const first = new Map();
-    const latest = new Map();
+    const stroke = createStroke((edit, record) => terrain.blendRecording(edit, record));
     return {
-        stamp(edit) {
-            return terrain.blendRecording(edit, (index, before, after) => {
-                if (!first.has(index))
-                    first.set(index, before);
-                latest.set(index, after);
-            });
-        },
-        delta() {
-            const indices = [];
-            const before = [];
-            const after = [];
-            for (const [index, next] of latest) {
-                const prev = first.get(index);
-                if (next === prev)
-                    continue;
-                indices.push(index);
-                before.push(prev);
-                after.push(next);
-            }
-            return { layerCount: terrain.layers.length, indices, before, after };
-        },
-        isEmpty() {
-            return latest.size === 0;
-        },
+        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,
     };
 }
 /**