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

package/dist/lib/space-detection.js

@@ -1,9 +1,14 @@
+import { GROUND_SUPPORT_ID } from '../hooks/spatial-grid/support-host-id';
 import { CeilingNode, SlabNode, ZoneNode, } from '../schema';
+import { DEFAULT_LEVEL_HEIGHT } from '../services/level-height';
+import { CEILING_CLAMP_MARGIN, findLevelAboveId, getCeilingClampBound, getLevelElevations, getStoredLevelHeight, } from '../services/storey';
 import { getSceneHistoryPauseDepth, pauseSceneHistory, resumeSceneHistory, } from '../store/history-control';
+import { computeWallSlabSupport } from '../systems/slab/slab-support';
 import { getClampedWallCurveOffset, getWallCurveFrameAt, isCurvedWall, } from '../systems/wall/wall-curve';
+import { resolveWallTop } from '../systems/wall/wall-top';
 import { simplifyClosedPolygon } from './polygon-geometry';
+import { terrainSupportLift } from './terrain-support';
 const DEFAULT_AUTO_SLAB_ELEVATION = 0.05;
-const DEFAULT_AUTO_CEILING_HEIGHT = 2.5;
 const CEILING_HEIGHT_EPSILON = 1e-6;
 const ROOM_CURVE_TOLERANCE = 0.04;
 const MAX_CURVE_SUBDIVISION_DEPTH = 6;
@@ -19,6 +24,7 @@ const WALL_JUNCTION_TOLERANCE = 0.08;
 // deleted) and the node is demoted to manual so user data survives.
 const ORPHAN_MERGE_COVERAGE_THRESHOLD = 0.6;
 const COVERAGE_SAMPLE_STEPS = 12;
+const ROOM_VERTICAL_PLANE_EPSILON = 1e-3;
 function pointFromTuple(point) {
     return { x: point[0], y: point[1] };
 }
@@ -194,51 +200,56 @@ function wallBoundsRoom(wall, roomPolygon) {
     const matchingPoints = candidates.filter((point) => pointDistanceToPolygonBoundary(point, roomPolygon) <= WALL_ROOM_BOUNDARY_TOLERANCE);
     return matchingPoints.length >= 2;
 }
-function pointIsOnSlab(point, slab) {
-    if (slab.polygon.length < 3)
-        return false;
-    const slabPolygon = slab.polygon.map(pointFromTuple);
-    if (!pointInPolygon(point, slabPolygon))
-        return false;
-    for (const hole of slab.holes ?? []) {
-        if (hole.length >= 3 && pointInPolygon(point, hole.map(pointFromTuple))) {
-            return false;
-        }
-    }
-    return true;
+/**
+ * The clamp bound for a ceiling polygon under this planning context —
+ * the context's cross-level resolver when provided, else the plane-only
+ * `storeyHeight - CEILING_CLAMP_MARGIN` degradation.
+ */
+function resolveCeilingClampBound(polygon, context) {
+    if (context.ceilingClampBound)
+        return context.ceilingClampBound(polygon);
+    return (context.storeyHeight ?? DEFAULT_LEVEL_HEIGHT) - CEILING_CLAMP_MARGIN;
 }
-function slabSupportsRoom(roomPolygon, slab) {
-    if (slab.polygon.length < 3)
-        return false;
-    if (polygonSignature(slab.polygon.map(pointFromTuple)) === polygonSignature(roomPolygon)) {
-        return true;
-    }
-    return pointIsOnSlab(polygonCentroid(roomPolygon), slab);
+function consensusElevation(values) {
+    if (values.length === 0 || values.some((value) => !Number.isFinite(value)))
+        return undefined;
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    if (max - min > ROOM_VERTICAL_PLANE_EPSILON)
+        return undefined;
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
 }
-function resolveRoomSlabElevation(roomPolygon, slabs = []) {
-    let maxElevation = 0;
-    for (const slab of slabs) {
-        if (!slabSupportsRoom(roomPolygon, slab))
+function autoRoomVerticalPlacements(spaces, walls, supportSlabs, nodes, storeyHeight) {
+    const wallsById = new Map(walls.map((wall) => [wall.id, wall]));
+    const placements = new Map();
+    for (const space of spaces) {
+        const boundaryWalls = space.wallIds.flatMap((id) => {
+            const wall = wallsById.get(id);
+            return wall ? [wall] : [];
+        });
+        if (boundaryWalls.length !== space.wallIds.length)
             continue;
-        maxElevation = Math.max(maxElevation, slab.elevation ?? DEFAULT_AUTO_SLAB_ELEVATION);
-    }
-    return maxElevation;
-}
-function resolveRoomWallHeight(roomPolygon, walls = []) {
-    let maxHeight = 0;
-    for (const wall of walls) {
-        if (!wallBoundsRoom(wall, roomPolygon))
+        const wallBases = boundaryWalls.map((wall) => {
+            const offset = wall.supportOffset ?? 0;
+            if (wall.supportSlabId === GROUND_SUPPORT_ID) {
+                return ((terrainSupportLift(nodes, space.levelId, wall.start[0], wall.start[1]) ?? 0) + offset);
+            }
+            return (computeWallSlabSupport(wall, supportSlabs, walls, wall.supportSlabId ?? null).elevation +
+                offset);
+        });
+        const base = consensusElevation(wallBases);
+        if (base === undefined)
             continue;
-        const height = wall.height ?? DEFAULT_AUTO_CEILING_HEIGHT;
-        if (Number.isFinite(height)) {
-            maxHeight = Math.max(maxHeight, height);
-        }
+        const wallTops = boundaryWalls.map((wall, index) => resolveWallTop(wall, storeyHeight, wallBases[index] ?? base));
+        const top = consensusElevation(wallTops);
+        if (top === undefined)
+            continue;
+        placements.set(polygonSignature(space.polygon.map(pointFromTuple)), {
+            slabElevation: base + DEFAULT_AUTO_SLAB_ELEVATION,
+            ceilingHeight: top - CEILING_CLAMP_MARGIN,
+        });
     }
-    return maxHeight > 0 ? maxHeight : DEFAULT_AUTO_CEILING_HEIGHT;
-}
-function resolveAutoCeilingHeight(roomPolygon, context = {}) {
-    return (resolveRoomSlabElevation(roomPolygon, context.slabs) +
-        resolveRoomWallHeight(roomPolygon, context.walls));
+    return placements;
 }
 function getWallDirection(wall) {
     const dx = wall.end[0] - wall.start[0];
@@ -612,7 +623,12 @@ function wallGeometrySignature(wall) {
         wall.end[0].toFixed(4),
         wall.end[1].toFixed(4),
         (wall.thickness ?? 0.2).toFixed(4),
-        (wall.height ?? DEFAULT_AUTO_CEILING_HEIGHT).toFixed(4),
+        // Plane-bound (no stored height) is a distinct state, not a default
+        // value: it resolves to the storey plane, so it must not alias an
+        // explicit height of the same magnitude in the trigger signature.
+        wall.height == null ? 'plane' : wall.height.toFixed(4),
+        wall.supportSlabId ?? 'elected',
+        (wall.supportOffset ?? 0).toFixed(4),
         getClampedWallCurveOffset(wall).toFixed(4),
     ].join('|');
 }
@@ -627,13 +643,24 @@ function zoneGeometrySignature(zone) {
         zone.polygon.map(([x, z]) => `${x.toFixed(4)},${z.toFixed(4)}`).join(';'),
     ].join('|');
 }
-// Slabs and ceilings stay out of the trigger signature: including generated
-// surfaces caused delete/recreate feedback. Zones are included only so a newly
-// traced room footprint can adopt its enclosing walls without waiting for the
-// next remodel.
+// Slab/ceiling POLYGONS stay out of the trigger signature: including
+// generated footprints caused delete/recreate feedback. Zones are included
+// only so a newly traced room footprint can adopt its enclosing walls
+// without waiting for the next remodel. Slab ELEVATIONS and the level's
+// stored storey height ARE included — both feed the explicit-ceiling
+// re-clamp bound (the storey plane), and neither is rewritten by
+// the sync, so regeneration triggers when they change without feedback.
+// Stage 3-B adds the LEVEL-ABOVE's covering-slab undersides (elevation −
+// thickness, recessed pools excluded): a deck created, lowered, or
+// thickened above must re-run the sync below so ceilings re-clamp under
+// it. Same polygon exclusion applies — the level-above's own auto sync
+// rewrites its slab footprints, and hashing them here would re-trigger
+// this level on every remodel above.
 function levelStructureSnapshots(nodes) {
     const wallsByLevel = new Map();
     const zonesByLevel = new Map();
+    const slabElevationsByLevel = new Map();
+    const coveringUndersidesByLevel = new Map();
     for (const node of Object.values(nodes)) {
         if (!(node && typeof node === 'object' && 'parentId' in node && node.parentId))
             continue;
@@ -648,13 +675,33 @@ function levelStructureSnapshots(nodes) {
             zones.push(ZoneNode.parse(node));
             zonesByLevel.set(levelId, zones);
         }
+        else if (node.type === 'slab') {
+            const elevations = slabElevationsByLevel.get(levelId) ?? [];
+            elevations.push(`${node.id}:${(node.elevation ?? DEFAULT_AUTO_SLAB_ELEVATION).toFixed(4)}`);
+            slabElevationsByLevel.set(levelId, elevations);
+            if (node.recessed !== true) {
+                const undersides = coveringUndersidesByLevel.get(levelId) ?? [];
+                const elevation = node.elevation ?? 0.05;
+                const thickness = node.thickness ?? 0.05;
+                undersides.push(`${node.id}:${(elevation - thickness).toFixed(4)}`);
+                coveringUndersidesByLevel.set(levelId, undersides);
+            }
+        }
     }
+    const levelElevations = getLevelElevations(nodes);
     const snapshots = new Map();
     const levelIds = new Set([...wallsByLevel.keys(), ...zonesByLevel.keys()]);
     for (const levelId of levelIds) {
         const walls = wallsByLevel.get(levelId) ?? [];
         const zones = zonesByLevel.get(levelId) ?? [];
-        snapshots.set(levelId, `${levelWallSnapshot(walls)}##${zones.map(zoneGeometrySignature).sort().join('||')}`);
+        const level = nodes[levelId];
+        const storeyKey = level?.type === 'level' && typeof level.height === 'number' ? level.height.toFixed(4) : '';
+        const slabKey = (slabElevationsByLevel.get(levelId) ?? []).sort().join(';');
+        const aboveId = findLevelAboveId(levelId, levelElevations);
+        const aboveSlabKey = aboveId
+            ? (coveringUndersidesByLevel.get(aboveId) ?? []).sort().join(';')
+            : '';
+        snapshots.set(levelId, `${storeyKey}#${levelWallSnapshot(walls)}##${zones.map(zoneGeometrySignature).sort().join('||')}##${slabKey}##${aboveSlabKey}`);
     }
     return snapshots;
 }
@@ -712,7 +759,7 @@ export function resolveAutoZonePolygon(zone, resolve) {
     const room = extractRooms(walls).find((candidate) => sameStringSet([...new Set(candidate.boundaryFaces.map((boundary) => boundary.wallId))], zone.boundaryWallIds));
     return room ? room.polygon.map(pointToTuple) : zone.polygon;
 }
-export function planAutoSlabsForLevel(roomPolygons, existingSlabs) {
+export function planAutoSlabsForLevel(roomPolygons, existingSlabs, context = {}) {
     const manualSlabs = existingSlabs.filter((slab) => !slab.autoFromWalls);
     const manualSignatures = new Set(manualSlabs.map((slab) => polygonSignature(slab.polygon.map(pointFromTuple))));
     const manualPolygons = manualSlabs.map((slab) => slab.polygon.map(pointFromTuple));
@@ -758,7 +805,11 @@ export function planAutoSlabsForLevel(roomPolygons, existingSlabs) {
             return;
         matchedDetectedIdx.add(index);
         matchedSlabIds.add(existing.slab.id);
-        updatesById.set(existing.slab.id, room.poly.map(pointToTuple));
+        const polygon = room.poly.map(pointToTuple);
+        updatesById.set(existing.slab.id, {
+            polygon,
+            elevation: context.elevationForRoom?.(polygon),
+        });
     });
     const remainingDetected = detected
         .map((room, index) => ({ room, index }))
@@ -787,7 +838,11 @@ export function planAutoSlabsForLevel(roomPolygons, existingSlabs) {
             continue;
         matchedDetectedIdx.add(index);
         matchedSlabIds.add(bestMatch.entry.slab.id);
-        updatesById.set(bestMatch.entry.slab.id, room.poly.map(pointToTuple));
+        const polygon = room.poly.map(pointToTuple);
+        updatesById.set(bestMatch.entry.slab.id, {
+            polygon,
+            elevation: context.elevationForRoom?.(polygon),
+        });
     }
     const detectedRoomPolygons = detectedAll.map((room) => room.poly);
     const slabsToDelete = [];
@@ -809,10 +864,17 @@ export function planAutoSlabsForLevel(roomPolygons, existingSlabs) {
         ...existingAuto
             .filter((slab) => updatesById.has(slab.id))
             .flatMap((slab) => {
-            const polygon = updatesById.get(slab.id);
-            if (!polygon)
+            const update = updatesById.get(slab.id);
+            if (!update)
                 return [];
-            return sameTuplePolygon(slab.polygon, polygon) ? [] : [{ id: slab.id, data: { polygon } }];
+            const data = {};
+            if (!sameTuplePolygon(slab.polygon, update.polygon))
+                data.polygon = update.polygon;
+            if (update.elevation !== undefined &&
+                Math.abs(slab.elevation - update.elevation) > ROOM_VERTICAL_PLANE_EPSILON) {
+                data.elevation = update.elevation;
+            }
+            return Object.keys(data).length > 0 ? [{ id: slab.id, data }] : [];
         }),
         ...slabDemotions,
     ];
@@ -826,11 +888,15 @@ export function planAutoSlabsForLevel(roomPolygons, existingSlabs) {
             continue;
         const name = nextAutoRoomName(plannedSlabsForNaming, 'Slab');
         plannedSlabsForNaming.push({ name });
+        const polygon = room.poly.map(pointToTuple);
+        const elevation = context.elevationForRoom?.(polygon);
         slabsToCreate.push(SlabNode.parse({
             name,
-            polygon: room.poly.map(pointToTuple),
+            polygon,
             holes: [],
-            elevation: DEFAULT_AUTO_SLAB_ELEVATION,
+            elevation: elevation !== undefined && Number.isFinite(elevation)
+                ? elevation
+                : DEFAULT_AUTO_SLAB_ELEVATION,
             autoFromWalls: true,
         }));
     }
@@ -840,8 +906,8 @@ export function planAutoSlabsForLevel(roomPolygons, existingSlabs) {
         delete: slabsToDelete,
     };
 }
-function syncAutoSlabsForLevel(levelId, roomPolygons, existingSlabs, sceneStore) {
-    const plan = planAutoSlabsForLevel(roomPolygons, existingSlabs);
+function syncAutoSlabsForLevel(levelId, roomPolygons, existingSlabs, sceneStore, context = {}) {
+    const plan = planAutoSlabsForLevel(roomPolygons, existingSlabs, context);
     if (plan.delete.length > 0) {
         sceneStore.getState().deleteNodes(plan.delete);
     }
@@ -853,22 +919,6 @@ function syncAutoSlabsForLevel(levelId, roomPolygons, existingSlabs, sceneStore)
     }
     return plan;
 }
-export function projectAutoSlabsForPlan(existingSlabs, plan) {
-    const slabsById = new Map(existingSlabs.map((slab) => [slab.id, slab]));
-    for (const id of plan.delete) {
-        slabsById.delete(id);
-    }
-    for (const update of plan.update) {
-        const slab = slabsById.get(update.id);
-        if (!slab)
-            continue;
-        slabsById.set(update.id, SlabNode.parse({ ...slab, ...update.data }));
-    }
-    for (const slab of plan.create) {
-        slabsById.set(slab.id, slab);
-    }
-    return [...slabsById.values()];
-}
 export function planAutoCeilingsForLevel(roomPolygons, existingCeilings, context = {}) {
     const manualCeilings = existingCeilings.filter((ceiling) => !ceiling.autoFromWalls);
     const manualSignatures = new Set(manualCeilings.map((ceiling) => polygonSignature(ceiling.polygon.map(pointFromTuple))));
@@ -887,7 +937,6 @@ export function planAutoCeilingsForLevel(roomPolygons, existingCeilings, context
         centroid: polygonCentroid(room.poly),
         area: Math.abs(polygonArea(room.poly)),
         bbox: bboxOf(room.poly),
-        ceilingHeight: resolveAutoCeilingHeight(room.poly, context),
     }));
     const detected = detectedAll.filter(({ sig, poly }) => !manualSignatures.has(sig) && !matchesManualFootprint(poly, manualPolygons));
     const existingAuto = existingCeilings.filter((ceiling) => ceiling.autoFromWalls);
@@ -916,9 +965,10 @@ export function planAutoCeilingsForLevel(roomPolygons, existingCeilings, context
             return;
         matchedDetectedIdx.add(index);
         matchedCeilingIds.add(existing.ceiling.id);
+        const polygon = room.poly.map(pointToTuple);
         updatesById.set(existing.ceiling.id, {
-            polygon: room.poly.map(pointToTuple),
-            height: room.ceilingHeight,
+            polygon,
+            height: context.heightForRoom?.(polygon),
         });
     });
     const remainingDetected = detected
@@ -948,9 +998,10 @@ export function planAutoCeilingsForLevel(roomPolygons, existingCeilings, context
             continue;
         matchedDetectedIdx.add(index);
         matchedCeilingIds.add(bestMatch.entry.ceiling.id);
+        const polygon = room.poly.map(pointToTuple);
         updatesById.set(bestMatch.entry.ceiling.id, {
-            polygon: room.poly.map(pointToTuple),
-            height: room.ceilingHeight,
+            polygon,
+            height: context.heightForRoom?.(polygon),
         });
     }
     const detectedRoomPolygons = detectedAll.map((room) => room.poly);
@@ -967,6 +1018,24 @@ export function planAutoCeilingsForLevel(roomPolygons, existingCeilings, context
             ceilingDemotions.push({ id: ceiling.id, data: { autoFromWalls: false } });
         }
     }
+    // Stage 3-B reactive re-clamp (clamp-never-ask): a covering slab
+    // created, moved, or thickened on the level above can leave an EXISTING
+    // manual explicit-height ceiling poking into its solid. Clamp explicit
+    // heights down to the bound; never raise them — a user-lowered ceiling
+    // is intent, only an over-bound one is a conflict. Follows-mode
+    // ceilings (absent height) derive under the bound by construction and
+    // are skipped, so the clamp can never convert one to an explicit
+    // height.
+    const manualClamps = manualCeilings.flatMap((ceiling) => {
+        if (ceiling.height == null)
+            return [];
+        const bound = resolveCeilingClampBound(ceiling.polygon, context);
+        if (!Number.isFinite(bound))
+            return [];
+        return ceiling.height > bound + CEILING_HEIGHT_EPSILON
+            ? [{ id: ceiling.id, data: { height: bound } }]
+            : [];
+    });
     const ceilingsToUpdate = [
         ...existingAuto
             .filter((ceiling) => updatesById.has(ceiling.id))
@@ -975,16 +1044,17 @@ export function planAutoCeilingsForLevel(roomPolygons, existingCeilings, context
             if (!update)
                 return [];
             const data = {};
-            if (!sameTuplePolygon(ceiling.polygon, update.polygon)) {
+            if (!sameTuplePolygon(ceiling.polygon, update.polygon))
                 data.polygon = update.polygon;
-            }
-            if (Math.abs((ceiling.height ?? DEFAULT_AUTO_CEILING_HEIGHT) - update.height) >
-                CEILING_HEIGHT_EPSILON) {
+            if (update.height !== undefined &&
+                (ceiling.height === undefined ||
+                    Math.abs(ceiling.height - update.height) > ROOM_VERTICAL_PLANE_EPSILON)) {
                 data.height = update.height;
             }
-            return Object.keys(data).length === 0 ? [] : [{ id: ceiling.id, data }];
+            return Object.keys(data).length > 0 ? [{ id: ceiling.id, data }] : [];
         }),
         ...ceilingDemotions,
+        ...manualClamps,
     ];
     const plannedCeilingsForNaming = [...existingCeilings];
     const ceilingsToCreate = [];
@@ -996,11 +1066,13 @@ export function planAutoCeilingsForLevel(roomPolygons, existingCeilings, context
             continue;
         const name = nextAutoRoomName(plannedCeilingsForNaming, 'Ceiling');
         plannedCeilingsForNaming.push({ name });
+        const polygon = room.poly.map(pointToTuple);
+        const height = context.heightForRoom?.(polygon);
         ceilingsToCreate.push(CeilingNode.parse({
             name,
-            polygon: room.poly.map(pointToTuple),
+            polygon,
             holes: [],
-            height: room.ceilingHeight,
+            ...(height !== undefined && Number.isFinite(height) ? { height } : {}),
             autoFromWalls: true,
         }));
     }
@@ -1066,10 +1138,24 @@ function runSpaceDetection(levelIds, sceneStore, editorStore, nodes) {
                 },
             })));
         }
+        const levelNode = nodes[levelId];
+        const storeyHeight = levelNode?.type === 'level'
+            ? getStoredLevelHeight(levelNode)
+            : DEFAULT_LEVEL_HEIGHT;
         const parsedSlabs = slabs.map((slab) => SlabNode.parse(slab));
-        const slabPlan = syncAutoSlabsForLevel(levelId, roomPolygons, parsedSlabs, sceneStore);
-        const projectedSlabs = projectAutoSlabsForPlan(parsedSlabs, slabPlan);
-        syncAutoCeilingsForLevel(levelId, roomPolygons, ceilings.map((ceiling) => CeilingNode.parse(ceiling)), sceneStore, { walls, slabs: projectedSlabs });
+        const verticalPlacements = autoRoomVerticalPlacements(spaces, walls, 
+        // A derived floor cannot be evidence for its own next elevation: that
+        // would lift unpinned walls, then lift the floor again on every pass.
+        parsedSlabs.filter((slab) => !slab.autoFromWalls), nodes, storeyHeight);
+        const placementFor = (polygon) => verticalPlacements.get(polygonSignature(polygon.map(pointFromTuple)));
+        syncAutoSlabsForLevel(levelId, roomPolygons, parsedSlabs, sceneStore, {
+            elevationForRoom: (polygon) => placementFor(polygon)?.slabElevation,
+        });
+        syncAutoCeilingsForLevel(levelId, roomPolygons, ceilings.map((ceiling) => CeilingNode.parse(ceiling)), sceneStore, {
+            storeyHeight,
+            ceilingClampBound: (polygon) => getCeilingClampBound(levelId, nodes, polygon),
+            heightForRoom: (polygon) => placementFor(polygon)?.ceilingHeight,
+        });
         const zonePlan = planAutoZonesForLevel(spaces, zones.map((zone) => ZoneNode.parse(zone)));
         if (zonePlan.update.length > 0)
             updateNodes(zonePlan.update);

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

@@ -0,0 +1,163 @@
+/**
+ * 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 { type HeightPatch, type TerrainField } from './terrain-field';
+export type BrushShape = 'round' | 'square';
+/**
+ * `raise`/`lower` are one verb with an inverted sign at the call site, matching
+ * every surveyed tool's modifier-inverts convention. `flatten` is absolute:
+ * it converges on a target height, which is the operation that makes two
+ * disjoint building pads provably equal — the thing freehand push/pull cannot do.
+ */
+export type TerrainVerb = 'raise' | 'lower' | 'flatten' | 'smooth';
+export type BrushSettings = {
+    /** Brush radius in metres. */
+    radius: number;
+    /** 0–1. Scales how far one full stroke pass gets toward its goal. */
+    strength: number;
+    /**
+     * 0–1 softness. 0 is a hard-edged stamp; 1 puts the cosine bell across the
+     * whole radius. The inner `1 - falloff` fraction stays at full coverage.
+     */
+    falloff: number;
+    shape: BrushShape;
+};
+export declare const DEFAULT_BRUSH_SETTINGS: BrushSettings;
+/**
+ * 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 declare 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 declare 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 declare function minBrushRadius(field: Pick<TerrainField, 'spacing'>): number;
+export type TerrainStroke = {
+    readonly verb: TerrainVerb;
+    readonly settings: BrushSettings;
+    /** The field at pointer-down. Never mutated; every dab reads from it. */
+    readonly snapshot: TerrainField;
+    /** Absolute target height in metres. Only meaningful for `flatten`. */
+    readonly target: number;
+    /** Sample index → saturating coverage in 0–1. */
+    readonly mask: Map<number, number>;
+    /** Lazily computed diffused snapshot, for `smooth`. */
+    smoothed: Int16Array | null;
+    /** Last dab centre, for arc-length spacing. Null until the first dab. */
+    lastX: number | null;
+    lastZ: number | null;
+};
+export declare function beginStroke(options: {
+    field: TerrainField;
+    verb: TerrainVerb;
+    settings?: Partial<BrushSettings>;
+    /** Absolute height for `flatten`, in metres. Ignored by the other verbs. */
+    target?: number;
+}): TerrainStroke;
+/**
+ * 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 declare function sampleTarget(field: TerrainField, x: number, z: number): number;
+/**
+ * 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 declare function detachStrokeAnchor(stroke: TerrainStroke): void;
+/**
+ * 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 declare function advanceStroke(stroke: TerrainStroke, x: number, z: number): HeightPatch | null;
+/**
+ * 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 declare function weightAt(settings: BrushSettings, dx: number, dz: number): number;
+/**
+ * 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 declare function brushHeightAt(field: TerrainField, x: number, z: number): number;
+/** Peak coverage the stroke reached, for tests and for the HUD's "pass" readout. */
+export declare function maxCoverage(stroke: TerrainStroke): number;
+/**
+ * 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 declare function highestOver(field: TerrainField, minX: number, minZ: number, maxX: number, maxZ: number): number;
+//# sourceMappingURL=terrain-brush.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-brush.d.ts","sourceRoot":"","sources":["../../src/lib/terrain-brush.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EACL,KAAK,WAAW,EAIhB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAA;AAExB,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE3C;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAA;AAElE,MAAM,MAAM,aAAa,GAAG;IAC1B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,UAAU,CAAA;CAClB,CAAA;AAED,eAAO,MAAM,sBAAsB,EAAE,aAKpC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAE/C;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,GAAG,MAAM,CAE3E;AAaD,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,uDAAuD;IACvD,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAA;IAC3B,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,CAAA;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE;IACnC,KAAK,EAAE,YAAY,CAAA;IACnB,IAAI,EAAE,WAAW,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;IACjC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,aAAa,CAWhB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAG9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA8C7F;AAmID;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAehF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAIzD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,MAAM,CAeR"}