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

package/dist/hooks/spatial-grid/spatial-grid-manager.js

@@ -1,30 +1,22 @@
 import { getRenderableSlabPolygon } from '../../lib/slab-polygon';
+import { terrainSupportLift } from '../../lib/terrain-support';
 import { nodeRegistry } from '../../registry';
 import { getScaledDimensions, isLowProfileItemSurface } from '../../schema';
+import { getWallPlaneTop } from '../../services/storey';
+import useLiveNodeOverrides, { getEffectiveNode } from '../../store/use-live-node-overrides';
+import useLiveTransforms from '../../store/use-live-transforms';
 import useScene from '../../store/use-scene';
-import { getWallCurveFrameAt, isCurvedWall } from '../../systems/wall/wall-curve';
+import { computeWallSlabSupport, pointInPolygon, SUPPORT_ELEVATION_EPSILON, } from '../../systems/slab/slab-support';
 import { DEFAULT_WALL_THICKNESS } from '../../systems/wall/wall-footprint';
+import { resolveWallEffectiveHeight } from '../../systems/wall/wall-top';
 import { getFloorPlacedFootprints } from './floor-placed-elevation';
 import { SpatialGrid } from './spatial-grid';
+import { GROUND_SUPPORT_ID } from './support-host-id';
 import { WallSpatialGrid } from './wall-spatial-grid';
+export { computeWallSlabElevation, computeWallSlabSupport, pointInPolygon, SUPPORT_ELEVATION_EPSILON, wallOverlapsPolygon, } from '../../systems/slab/slab-support';
 // ============================================================================
 // GEOMETRY HELPERS
 // ============================================================================
-/**
- * Point-in-polygon test using ray casting algorithm.
- */
-export function pointInPolygon(px, pz, polygon) {
-    let inside = false;
-    const n = polygon.length;
-    for (let i = 0, j = n - 1; i < n; j = i++) {
-        const xi = polygon[i][0], zi = polygon[i][1];
-        const xj = polygon[j][0], zj = polygon[j][1];
-        if (zi > pz !== zj > pz && px < ((xj - xi) * (pz - zi)) / (zj - zi) + xi) {
-            inside = !inside;
-        }
-    }
-    return inside;
-}
 /**
  * Compute the 4 XZ footprint corners of an item given its position, dimensions, and Y rotation.
  */
@@ -203,400 +195,6 @@ export function itemOverlapsPolygon(position, dimensions, rotation, polygon, ins
     }
     return false;
 }
-function pointSegmentDistance(px, pz, ax, az, bx, bz) {
-    const dx = bx - ax;
-    const dz = bz - az;
-    const lengthSquared = dx * dx + dz * dz;
-    if (lengthSquared < 1e-18)
-        return Math.hypot(px - ax, pz - az);
-    const t = Math.max(0, Math.min(1, ((px - ax) * dx + (pz - az) * dz) / lengthSquared));
-    return Math.hypot(px - (ax + dx * t), pz - (az + dz * t));
-}
-// Ray-cast pointInPolygon is unreliable for points exactly on the polygon
-// boundary: the answer flips depending on which side of the polygon the edge
-// is on. Interval classification below therefore treats "within this distance
-// of the boundary" as inside explicitly, so walls sitting exactly on a slab
-// edge (the common case — auto-slab polygons derive from wall centerlines)
-// classify identically on every side of the slab.
-const ON_BOUNDARY_EPSILON = 1e-4;
-function pointOnPolygonBoundary(px, pz, polygon) {
-    const n = polygon.length;
-    for (let i = 0; i < n; i++) {
-        const [ax, az] = polygon[i];
-        const [bx, bz] = polygon[(i + 1) % n];
-        if (pointSegmentDistance(px, pz, ax, az, bx, bz) <= ON_BOUNDARY_EPSILON)
-            return true;
-    }
-    return false;
-}
-function mergeIntervals(intervals) {
-    if (intervals.length <= 1)
-        return intervals;
-    const sorted = [...intervals].sort((a, b) => a[0] - b[0]);
-    const merged = [[sorted[0][0], sorted[0][1]]];
-    for (let i = 1; i < sorted.length; i++) {
-        const [intervalStart, intervalEnd] = sorted[i];
-        const last = merged[merged.length - 1];
-        if (intervalStart <= last[1] + 1e-9) {
-            last[1] = Math.max(last[1], intervalEnd);
-        }
-        else {
-            merged.push([intervalStart, intervalEnd]);
-        }
-    }
-    return merged;
-}
-/** Total length of a merged (sorted, disjoint) interval list. */
-function intervalsLength(intervals) {
-    let total = 0;
-    for (const [intervalStart, intervalEnd] of intervals)
-        total += intervalEnd - intervalStart;
-    return total;
-}
-/** `base` minus `cut`. Both inputs may be unsorted; the result is merged. */
-function subtractIntervals(base, cut) {
-    if (base.length === 0 || cut.length === 0)
-        return mergeIntervals(base);
-    const cuts = mergeIntervals(cut);
-    const result = [];
-    for (const [baseStart, baseEnd] of mergeIntervals(base)) {
-        let cursor = baseStart;
-        for (const [cutStart, cutEnd] of cuts) {
-            if (cutEnd <= cursor)
-                continue;
-            if (cutStart >= baseEnd)
-                break;
-            if (cutStart > cursor)
-                result.push([cursor, cutStart]);
-            cursor = cutEnd;
-            if (cursor >= baseEnd)
-                break;
-        }
-        if (cursor < baseEnd)
-            result.push([cursor, baseEnd]);
-    }
-    return result;
-}
-/**
- * Sub-intervals of segment (ax,az)→(bx,bz) that lie inside the polygon (and,
- * when `includeBoundary`, on its boundary), as [t0, t1] fractions of the
- * segment. The segment is split at every crossing with a polygon edge and
- * each sub-interval is classified by its midpoint, so no test point ever
- * sits on a crossing.
- */
-function segmentInsideIntervals(ax, az, bx, bz, polygon, includeBoundary) {
-    const dx = bx - ax;
-    const dz = bz - az;
-    const length = Math.hypot(dx, dz);
-    if (length < 1e-9)
-        return [];
-    const ts = [0, 1];
-    const n = polygon.length;
-    for (let i = 0; i < n; i++) {
-        const [px, pz] = polygon[i];
-        const [qx, qz] = polygon[(i + 1) % n];
-        const ex = qx - px;
-        const ez = qz - pz;
-        const denom = dx * ez - dz * ex;
-        if (Math.abs(denom) < 1e-12)
-            continue; // parallel/collinear — nothing to split at
-        const t = ((px - ax) * ez - (pz - az) * ex) / denom;
-        const s = ((px - ax) * dz - (pz - az) * dx) / denom;
-        if (t > 0 && t < 1 && s >= -1e-9 && s <= 1 + 1e-9)
-            ts.push(t);
-    }
-    ts.sort((a, b) => a - b);
-    const inside = [];
-    for (let i = 1; i < ts.length; i++) {
-        const t0 = ts[i - 1];
-        const t1 = ts[i];
-        if (t1 - t0 < 1e-9)
-            continue;
-        const tm = (t0 + t1) / 2;
-        const mx = ax + dx * tm;
-        const mz = az + dz * tm;
-        const midpointInside = pointOnPolygonBoundary(mx, mz, polygon)
-            ? includeBoundary
-            : pointInPolygon(mx, mz, polygon);
-        if (midpointInside)
-            inside.push([t0, t1]);
-    }
-    return inside;
-}
-function polylineLength(points) {
-    let total = 0;
-    for (let i = 1; i < points.length; i++) {
-        total += Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
-    }
-    return total;
-}
-/**
- * Inside sub-intervals of a polyline against a polygon, in cumulative
- * arc-length units from the polyline start (merged, disjoint). Boundary
- * contact counts as inside for slab support (walls sit exactly on slab
- * edges — see ON_BOUNDARY_EPSILON above); hole callers pass
- * `includeBoundary: false` so a wall running along a stairwell hole's
- * rim keeps the rim's support.
- */
-function polylineInsideIntervals(points, polygon, includeBoundary = true) {
-    const intervals = [];
-    let offset = 0;
-    for (let i = 1; i < points.length; i++) {
-        const a = points[i - 1];
-        const b = points[i];
-        const segmentLength = Math.hypot(b.x - a.x, b.y - a.y);
-        if (segmentLength < 1e-9)
-            continue;
-        for (const [t0, t1] of segmentInsideIntervals(a.x, a.y, b.x, b.y, polygon, includeBoundary)) {
-            intervals.push([offset + t0 * segmentLength, offset + t1 * segmentLength]);
-        }
-        offset += segmentLength;
-    }
-    return mergeIntervals(intervals);
-}
-function polylineInsideLength(points, polygon) {
-    return intervalsLength(polylineInsideIntervals(points, polygon));
-}
-// Minimum length of wall that must lie on/inside a slab polygon before the
-// wall counts as overlapping it. Point contact (a perpendicular wall butting
-// into a room's edge) clips to ~zero length and never reaches this, so such
-// walls don't follow the slab's elevation.
-const WALL_SLAB_MIN_OVERLAP = 0.05;
-/**
- * Centerline of the wall plus its two face lines (centerline offset by
- * ±halfThickness). The face lines catch walls whose centerline sits on or
- * just outside the slab boundary but whose body reaches onto the slab —
- * e.g. slab polygons drawn to the room's interior faces.
- */
-function wallTestPolylines(start, end, curveOffset, halfThickness) {
-    const wallLike = { start, end, curveOffset };
-    if (curveOffset !== 0 && isCurvedWall(wallLike)) {
-        const count = 16;
-        const center = [];
-        const left = [];
-        const right = [];
-        for (let i = 0; i <= count; i++) {
-            const frame = getWallCurveFrameAt(wallLike, i / count);
-            center.push(frame.point);
-            left.push({
-                x: frame.point.x + frame.normal.x * halfThickness,
-                y: frame.point.y + frame.normal.y * halfThickness,
-            });
-            right.push({
-                x: frame.point.x - frame.normal.x * halfThickness,
-                y: frame.point.y - frame.normal.y * halfThickness,
-            });
-        }
-        return halfThickness > 0 ? [center, left, right] : [center];
-    }
-    const center = [
-        { x: start[0], y: start[1] },
-        { x: end[0], y: end[1] },
-    ];
-    const dx = end[0] - start[0];
-    const dz = end[1] - start[1];
-    const len = Math.hypot(dx, dz);
-    if (len < 1e-10 || halfThickness <= 0)
-        return [center];
-    const nx = (-dz / len) * halfThickness;
-    const nz = (dx / len) * halfThickness;
-    return [
-        center,
-        [
-            { x: start[0] + nx, y: start[1] + nz },
-            { x: end[0] + nx, y: end[1] + nz },
-        ],
-        [
-            { x: start[0] - nx, y: start[1] - nz },
-            { x: end[0] - nx, y: end[1] - nz },
-        ],
-    ];
-}
-/**
- * Test whether a wall overlaps a slab polygon along a segment of its length.
- *
- * The wall's centerline and both face lines are clipped against the polygon;
- * the wall overlaps when the longest clipped inside-or-on-boundary length
- * exceeds a threshold (5cm, halved for very short walls). Because interval
- * midpoints classify "on the boundary" as inside explicitly (never by
- * ray-cast tie-breaking), a wall sitting exactly on a slab edge resolves
- * identically on every side of the slab.
- *
- * A wall that only touches the polygon at a point — a perpendicular wall
- * butting into a room's edge, or a corner-to-corner touch — clips to ~zero
- * length and does NOT overlap.
- */
-export function wallOverlapsPolygon(startOrWall, endOrPolygon, polygonArg) {
-    // Two call shapes:
-    //   wallOverlapsPolygon(wallLike, polygon) — preferred; curve-aware
-    //   wallOverlapsPolygon(start, end, polygon) — legacy chord-only
-    let start;
-    let end;
-    let polygon;
-    let curveOffset = 0;
-    let thickness = DEFAULT_WALL_THICKNESS;
-    if (Array.isArray(startOrWall)) {
-        start = startOrWall;
-        end = endOrPolygon;
-        polygon = polygonArg;
-    }
-    else {
-        start = startOrWall.start;
-        end = startOrWall.end;
-        curveOffset = startOrWall.curveOffset ?? 0;
-        thickness = startOrWall.thickness ?? DEFAULT_WALL_THICKNESS;
-        polygon = endOrPolygon;
-    }
-    const halfThickness = Math.max(thickness / 2, 0);
-    const polylines = wallTestPolylines(start, end, curveOffset, halfThickness);
-    const centerLength = polylineLength(polylines[0]);
-    if (centerLength < 1e-9)
-        return false;
-    let overlap = 0;
-    for (const line of polylines) {
-        overlap = Math.max(overlap, polylineInsideLength(line, polygon));
-    }
-    const threshold = Math.max(1e-3, Math.min(WALL_SLAB_MIN_OVERLAP, centerLength * 0.5));
-    return overlap >= threshold;
-}
-// A slab elevation must support at least this fraction of the wall's
-// length before it can dictate the wall's base. Below majority, a raised
-// slab reaching one endpoint would hoist the whole wall off the floor
-// that actually carries it.
-const WALL_SLAB_SUPPORT_MAJORITY = 0.5;
-// Slabs whose elevations differ by less than this pool their support:
-// a wall shared between two rooms' slabs is covered roughly half by
-// each, and must still follow their common elevation.
-const WALL_SLAB_ELEVATION_POOL_EPSILON = 1e-4;
-export function computeWallSlabSupport(wallLike, slabs, levelWalls) {
-    const { start, end, curveOffset = 0, thickness = DEFAULT_WALL_THICKNESS } = wallLike;
-    const halfThickness = Math.max(thickness / 2, 0);
-    const polylines = wallTestPolylines(start, end, curveOffset, halfThickness);
-    const polylineLengths = polylines.map(polylineLength);
-    const wallLength = polylineLengths[0];
-    if (wallLength < 1e-9) {
-        return { elevation: 0, baseElevation: 0, baseSegments: [] };
-    }
-    const minSupport = Math.max(1e-3, Math.min(WALL_SLAB_MIN_OVERLAP, wallLength * 0.5));
-    const groups = [];
-    for (const slab of slabs) {
-        if (slab.polygon.length < 3)
-            continue;
-        const renderedPolygon = getRenderableSlabPolygon(slab, {
-            walls: levelWalls,
-            siblingSlabs: slabs.filter((other) => other.id !== slab.id),
-        });
-        let supported = 0;
-        const perPolyline = polylines.map((line) => {
-            let intervals = polylineInsideIntervals(line, renderedPolygon);
-            for (const hole of slab.holes || []) {
-                if (intervals.length === 0)
-                    break;
-                if (hole.length < 3)
-                    continue;
-                intervals = subtractIntervals(intervals, polylineInsideIntervals(line, hole, false));
-            }
-            supported = Math.max(supported, intervalsLength(intervals));
-            return intervals;
-        });
-        if (supported < minSupport)
-            continue;
-        const elevation = slab.elevation ?? 0.05;
-        let group = groups.find((candidate) => Math.abs(candidate.elevation - elevation) <= WALL_SLAB_ELEVATION_POOL_EPSILON);
-        if (!group) {
-            group = { elevation, perPolyline: polylines.map(() => []) };
-            groups.push(group);
-        }
-        for (let i = 0; i < perPolyline.length; i++) {
-            group.perPolyline[i].push(...perPolyline[i]);
-        }
-    }
-    const evaluatedGroups = groups.map((group) => {
-        let coverage = 0;
-        const mergedPerPolyline = group.perPolyline.map(mergeIntervals);
-        for (let i = 0; i < group.perPolyline.length; i++) {
-            const lineLength = polylineLengths[i];
-            if (lineLength < 1e-9)
-                continue;
-            coverage = Math.max(coverage, intervalsLength(mergedPerPolyline[i]) / lineLength);
-        }
-        return { ...group, coverage, mergedPerPolyline };
-    });
-    let majorityElevation = Number.NEGATIVE_INFINITY;
-    let bestElevation = Number.NEGATIVE_INFINITY;
-    let bestCoverage = -1;
-    for (const group of evaluatedGroups) {
-        if (group.coverage >= WALL_SLAB_SUPPORT_MAJORITY - 1e-6) {
-            majorityElevation = Math.max(majorityElevation, group.elevation);
-        }
-        if (group.coverage > bestCoverage + 1e-6 ||
-            (Math.abs(group.coverage - bestCoverage) <= 1e-6 && group.elevation > bestElevation)) {
-            bestCoverage = group.coverage;
-            bestElevation = group.elevation;
-        }
-    }
-    const elevation = majorityElevation !== Number.NEGATIVE_INFINITY
-        ? majorityElevation
-        : bestElevation === Number.NEGATIVE_INFINITY
-            ? 0
-            : bestElevation;
-    const normalizedIntervals = (group, polylineIndex) => {
-        const lineLength = polylineLengths[polylineIndex];
-        if (lineLength < 1e-9)
-            return [];
-        return group.mergedPerPolyline[polylineIndex].map(([intervalStart, intervalEnd]) => [intervalStart / lineLength, intervalEnd / lineLength]);
-    };
-    const normalizedByGroup = evaluatedGroups.map((group) => ({
-        elevation: group.elevation,
-        perPolyline: group.mergedPerPolyline.map((_, index) => normalizedIntervals(group, index)),
-    }));
-    const breakpoints = [0, 1];
-    for (const group of normalizedByGroup) {
-        for (const intervals of group.perPolyline) {
-            for (const [intervalStart, intervalEnd] of intervals) {
-                breakpoints.push(intervalStart, intervalEnd);
-            }
-        }
-    }
-    breakpoints.sort((left, right) => left - right);
-    const uniqueBreakpoints = breakpoints.filter((value, index) => index === 0 || value - breakpoints[index - 1] > 1e-7);
-    const highestAt = (polylineIndex, t) => {
-        let highest = Number.NEGATIVE_INFINITY;
-        for (const group of normalizedByGroup) {
-            if (group.perPolyline[polylineIndex]?.some(([intervalStart, intervalEnd]) => t >= intervalStart - 1e-7 && t <= intervalEnd + 1e-7)) {
-                highest = Math.max(highest, group.elevation);
-            }
-        }
-        return highest;
-    };
-    const baseSegments = [];
-    for (let index = 1; index < uniqueBreakpoints.length; index++) {
-        const start = uniqueBreakpoints[index - 1];
-        const end = uniqueBreakpoints[index];
-        if (end - start < 1e-7)
-            continue;
-        const midpoint = (start + end) / 2;
-        const leftElevation = polylines.length >= 3 ? highestAt(1, midpoint) : Number.NEGATIVE_INFINITY;
-        const rightElevation = polylines.length >= 3 ? highestAt(2, midpoint) : Number.NEGATIVE_INFINITY;
-        const faceElevations = [leftElevation, rightElevation].filter(Number.isFinite);
-        const segmentElevation = faceElevations.length > 0 ? Math.min(...faceElevations) : Math.max(highestAt(0, midpoint), 0);
-        const previous = baseSegments[baseSegments.length - 1];
-        if (previous &&
-            Math.abs(previous.elevation - segmentElevation) <= WALL_SLAB_ELEVATION_POOL_EPSILON) {
-            previous.end = end;
-        }
-        else {
-            baseSegments.push({ start, end, elevation: segmentElevation });
-        }
-    }
-    if (baseSegments.length === 0)
-        baseSegments.push({ start: 0, end: 1, elevation });
-    const baseElevation = Math.min(...baseSegments.map((segment) => segment.elevation));
-    return { elevation, baseElevation, baseSegments };
-}
-export function computeWallSlabElevation(wallLike, slabs, levelWalls) {
-    return computeWallSlabSupport(wallLike, slabs, levelWalls).elevation;
-}
 export class SpatialGridManager {
     floorGrids = new Map(); // levelId -> grid
     wallGrids = new Map(); // levelId -> wall grid
@@ -631,7 +229,14 @@ export class SpatialGridManager {
     }
     getWallHeight(wallId) {
         const wall = this.walls.get(wallId);
-        return wall?.height ?? 2.5; // Default wall height
+        if (!wall)
+            return 0;
+        if (wall.height != null)
+            return wall.height;
+        const nodes = useScene.getState().nodes;
+        const levelId = resolveNodeLevelId(wall, nodes);
+        const support = this.getSlabSupportForWall(levelId, wall.start, wall.end, wall.curveOffset ?? 0, wall.thickness, wall.supportSlabId ?? null, undefined, wall.supportOffset);
+        return resolveWallEffectiveHeight(wall, getWallPlaneTop(wall, levelId, nodes), support.elevation);
     }
     getCeilingGrid(ceilingId) {
         if (!this.ceilingGrids.has(ceilingId)) {
@@ -645,10 +250,122 @@ export class SpatialGridManager {
         }
         return this.slabsByLevel.get(levelId);
     }
+    /**
+     * Per-slab RENDERED polygon cache (`getRenderableSlabPolygon`). Item
+     * support queries run per frame and the projection scans the level's
+     * walls + sibling slabs, so the result is cached per slab id and
+     * dropped for the whole level whenever a slab or wall on that level
+     * flows through the manager's create/update/delete handlers.
+     */
+    renderedSlabPolygons = new Map();
+    invalidateRenderedSlabPolygons(levelId) {
+        const slabMap = this.slabsByLevel.get(levelId);
+        if (!slabMap)
+            return;
+        for (const slabId of slabMap.keys())
+            this.renderedSlabPolygons.delete(slabId);
+    }
+    /**
+     * True while a slab or wall on `levelId` has a live preview: group drags
+     * publish translated slab polygons and wall endpoints to
+     * `useLiveNodeOverrides`, and the slab move tool / room-preset stamp
+     * publish a translation DELTA to `useLiveTransforms` — either way the
+     * scene store commits only on release, so the committed cache and index
+     * would elect support against pre-drag footprints (items and walls
+     * visibly drop to ground mid-preview). Support queries then read
+     * live-effective records and skip the rendered-polygon cache.
+     */
+    levelHasLivePreview(levelId) {
+        const nodes = useScene.getState().nodes;
+        const structuralOnLevel = (id) => {
+            const node = nodes[id];
+            if (!node || (node.type !== 'slab' && node.type !== 'wall'))
+                return false;
+            return resolveNodeLevelId(node, nodes) === levelId;
+        };
+        const overrides = useLiveNodeOverrides.getState().overrides;
+        for (const id of overrides.keys()) {
+            if (structuralOnLevel(id))
+                return true;
+        }
+        const transforms = useLiveTransforms.getState().transforms;
+        for (const id of transforms.keys()) {
+            if (structuralOnLevel(id))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * The live-effective slab record: field overrides merged, then the
+     * `useLiveTransforms` DELTA (slab publishers — move tool, room-preset
+     * stamp — store a translation, not an absolute position) applied to the
+     * polygon, holes, and elevation. Mapping happens exactly ONCE at each
+     * public query's loop entry: `slabSupportsFootprint` /
+     * `getRenderedSlabPolygon` take the already-effective record and must
+     * never re-map, or the delta would apply twice.
+     */
+    effectiveSlabRecord(slab) {
+        let effective = getEffectiveNode(slab);
+        const live = useLiveTransforms.getState().get(slab.id);
+        if (live) {
+            const [dx, dy, dz] = live.position;
+            if (dx !== 0 || dy !== 0 || dz !== 0) {
+                effective = {
+                    ...effective,
+                    polygon: effective.polygon.map(([x, z]) => [x + dx, z + dz]),
+                    holes: (effective.holes || []).map((hole) => hole.map(([x, z]) => [x + dx, z + dz])),
+                    elevation: (effective.elevation ?? 0.05) + dy,
+                };
+            }
+        }
+        return effective;
+    }
+    getRenderedSlabPolygon(levelId, slab) {
+        const live = this.levelHasLivePreview(levelId);
+        if (!live) {
+            const cached = this.renderedSlabPolygons.get(slab.id);
+            if (cached)
+                return cached;
+        }
+        const siblingSlabs = [];
+        for (const other of this.getSlabMap(levelId).values()) {
+            if (other.id !== slab.id)
+                siblingSlabs.push(live ? this.effectiveSlabRecord(other) : other);
+        }
+        const walls = this.getLevelWallNodes(levelId);
+        const polygon = getRenderableSlabPolygon(slab, {
+            walls: live ? walls.map((wall) => getEffectiveNode(wall)) : walls,
+            siblingSlabs,
+        });
+        if (!live)
+            this.renderedSlabPolygons.set(slab.id, polygon);
+        return polygon;
+    }
+    /**
+     * Support test shared by election, candidate listing, and persisted-host
+     * validation: the footprint overlaps the slab's RENDERED polygon (what
+     * users see — matching the wall election in `computeWallSlabSupport`),
+     * with the center-point hole veto kept against the stored holes (holes
+     * are data, never render-offset).
+     */
+    slabSupportsFootprint(levelId, slab, position, dimensions, rotation) {
+        if (slab.polygon.length < 3)
+            return false;
+        const rendered = this.getRenderedSlabPolygon(levelId, slab);
+        if (!itemOverlapsPolygon(position, dimensions, rotation, rendered, 0.01))
+            return false;
+        const [cx, , cz] = position;
+        for (const hole of slab.holes || []) {
+            if (hole.length >= 3 && pointInPolygon(cx, cz, hole))
+                return false;
+        }
+        return true;
+    }
     // Called when nodes change
     handleNodeCreated(node, levelId) {
         if (node.type === 'slab') {
             this.getSlabMap(levelId).set(node.id, node);
+            this.invalidateRenderedSlabPolygons(levelId);
         }
         else if (node.type === 'ceiling') {
             this.ceilings.set(node.id, node);
@@ -656,6 +373,8 @@ export class SpatialGridManager {
         else if (node.type === 'wall') {
             const wall = node;
             this.walls.set(wall.id, wall);
+            // Rendered slab polygons adopt wall bands — a new wall can extend them.
+            this.invalidateRenderedSlabPolygons(levelId);
         }
         else if (node.type === 'item') {
             const item = node;
@@ -700,6 +419,7 @@ export class SpatialGridManager {
     handleNodeUpdated(node, levelId) {
         if (node.type === 'slab') {
             this.getSlabMap(levelId).set(node.id, node);
+            this.invalidateRenderedSlabPolygons(levelId);
         }
         else if (node.type === 'ceiling') {
             this.ceilings.set(node.id, node);
@@ -707,6 +427,7 @@ export class SpatialGridManager {
         else if (node.type === 'wall') {
             const wall = node;
             this.walls.set(wall.id, wall);
+            this.invalidateRenderedSlabPolygons(levelId);
         }
         else if (node.type === 'item') {
             const item = node;
@@ -756,6 +477,9 @@ export class SpatialGridManager {
     }
     handleNodeDeleted(nodeId, nodeType, levelId) {
         if (nodeType === 'slab') {
+            // Invalidate before removal so the deleted slab's own cache entry
+            // (still keyed in the level map here) is dropped with its siblings'.
+            this.invalidateRenderedSlabPolygons(levelId);
             this.getSlabMap(levelId).delete(nodeId);
         }
         else if (nodeType === 'ceiling') {
@@ -764,6 +488,7 @@ export class SpatialGridManager {
         }
         else if (nodeType === 'wall') {
             this.walls.delete(nodeId);
+            this.invalidateRenderedSlabPolygons(levelId);
             // Remove all items attached to this wall from the spatial grid
             const removedItemIds = this.getWallGrid(levelId).removeWall(nodeId);
             return removedItemIds; // Caller can use this to delete the items from scene
@@ -901,7 +626,8 @@ export class SpatialGridManager {
         if (!slabMap)
             return 0;
         let maxElevation = 0;
-        for (const slab of slabMap.values()) {
+        for (const stored of slabMap.values()) {
+            const slab = this.effectiveSlabRecord(stored);
             if (slab.polygon.length >= 3 && pointInPolygon(x, z, slab.polygon)) {
                 // Check if point is in any hole
                 let inHole = false;
@@ -924,37 +650,142 @@ export class SpatialGridManager {
     }
     /**
      * Get the slab elevation for an item using its full footprint (bounding box).
-     * Checks if any part of the item's rotated footprint overlaps with any slab polygon (excluding holes).
-     * Returns the highest overlapping slab elevation, or 0 if none.
+     * Thin wrapper over {@link getSlabSupportForItem} for callers (and tests)
+     * that only need the number.
      */
-    getSlabElevationForItem(levelId, position, dimensions, rotation) {
+    getSlabElevationForItem(levelId, position, dimensions, rotation, maxElevation) {
+        return this.getSlabSupportForItem(levelId, position, dimensions, rotation, maxElevation)
+            .elevation;
+    }
+    /**
+     * Elect the supporting slab for a footprint: the highest-elevation slab
+     * whose RENDERED polygon the footprint overlaps (center-point hole veto
+     * applies). Returns `{ elevation: 0, slabId: null }` when nothing
+     * overlaps.
+     *
+     * `maxElevation` is the pointer-decided cap: when set, only slabs whose
+     * walking surface sits at or below `maxElevation +
+     * SUPPORT_ELEVATION_EPSILON` may win — a deck hanging above the surface
+     * the cursor ray actually hit never captures the election.
+     */
+    getSlabSupportForItem(levelId, position, dimensions, rotation, maxElevation) {
         const slabMap = this.slabsByLevel.get(levelId);
         if (!slabMap)
-            return 0;
-        let maxElevation = Number.NEGATIVE_INFINITY;
-        for (const slab of slabMap.values()) {
-            if (slab.polygon.length >= 3 &&
-                itemOverlapsPolygon(position, dimensions, rotation, slab.polygon, 0.01)) {
-                // Check if item is entirely within a hole (if so, ignore this slab)
-                // We consider it entirely in a hole if the item center is in the hole
+            return { elevation: 0, slabId: null };
+        let winningElevation = Number.NEGATIVE_INFINITY;
+        let winnerId = null;
+        for (const stored of slabMap.values()) {
+            const slab = this.effectiveSlabRecord(stored);
+            const elevation = slab.elevation ?? 0.05;
+            if (maxElevation != null && elevation > maxElevation + SUPPORT_ELEVATION_EPSILON)
+                continue;
+            if (!this.slabSupportsFootprint(levelId, slab, position, dimensions, rotation))
+                continue;
+            if (elevation > winningElevation) {
+                winningElevation = elevation;
+                winnerId = slab.id;
+            }
+        }
+        return winnerId === null
+            ? { elevation: 0, slabId: null }
+            : { elevation: winningElevation, slabId: winnerId };
+    }
+    /**
+     * The walking surface the pointer actually points at: the nearest slab
+     * plane the ray crosses INSIDE that slab's rendered polygon (hole veto
+     * applies), or the level base (`elevation: 0, slabId: null`) when it
+     * crosses none. Ray origin/direction are level-local. Deliberately a
+     * point test, not a footprint test — it answers "which surface is under
+     * the cursor", which then caps the footprint election so a deck hanging
+     * above the aimed-at floor never lifts the placement. `point` is the
+     * ray's crossing of that surface's plane — the stable plan point
+     * callers should elect/preview at (see {@link PointedSupportSurface}).
+     */
+    getPointedSupportSurface(levelId, rayOrigin, rayDirection) {
+        const slabMap = this.slabsByLevel.get(levelId);
+        const [ox, oy, oz] = rayOrigin;
+        const [dx, dy, dz] = rayDirection;
+        if (Math.abs(dy) < 1e-9)
+            return { elevation: 0, slabId: null, point: null };
+        let best = null;
+        if (slabMap) {
+            for (const stored of slabMap.values()) {
+                const slab = this.effectiveSlabRecord(stored);
+                if (slab.polygon.length < 3)
+                    continue;
+                const elevation = slab.elevation ?? 0.05;
+                const t = (elevation - oy) / dy;
+                if (t <= 0)
+                    continue;
+                if (best && t >= best.t)
+                    continue;
+                const x = ox + dx * t;
+                const z = oz + dz * t;
+                const rendered = this.getRenderedSlabPolygon(levelId, slab);
+                if (rendered.length < 3 || !pointInPolygon(x, z, rendered))
+                    continue;
                 let inHole = false;
-                const [cx, , cz] = position;
-                const holes = slab.holes || [];
-                for (const hole of holes) {
-                    if (hole.length >= 3 && pointInPolygon(cx, cz, hole)) {
+                for (const hole of slab.holes || []) {
+                    if (hole.length >= 3 && pointInPolygon(x, z, hole)) {
                         inHole = true;
                         break;
                     }
                 }
-                if (!inHole) {
-                    const elevation = slab.elevation ?? 0.05;
-                    if (elevation > maxElevation) {
-                        maxElevation = elevation;
-                    }
-                }
+                if (inHole)
+                    continue;
+                best = { t, elevation, slabId: slab.id };
             }
         }
-        return maxElevation === Number.NEGATIVE_INFINITY ? 0 : maxElevation;
+        if (best) {
+            return {
+                elevation: best.elevation,
+                slabId: best.slabId,
+                point: [ox + dx * best.t, oz + dz * best.t],
+            };
+        }
+        const tBase = -oy / dy;
+        return {
+            elevation: 0,
+            slabId: null,
+            point: tBase > 0 ? [ox + dx * tBase, oz + dz * tBase] : null,
+        };
+    }
+    /**
+     * All slabs supporting a footprint, one entry per overlapping slab
+     * (highest elevation first; slab id breaks ties deterministically).
+     * Commit-side ambiguity check: persist a `supportSlabId` only when the
+     * candidates carry ≥ 2 distinct elevations.
+     */
+    getSupportCandidatesForFootprint(levelId, position, dimensions, rotation) {
+        const slabMap = this.slabsByLevel.get(levelId);
+        if (!slabMap)
+            return [];
+        const candidates = [];
+        for (const stored of slabMap.values()) {
+            const slab = this.effectiveSlabRecord(stored);
+            if (!this.slabSupportsFootprint(levelId, slab, position, dimensions, rotation))
+                continue;
+            candidates.push({ slabId: slab.id, elevation: slab.elevation ?? 0.05 });
+        }
+        candidates.sort((a, b) => b.elevation - a.elevation || (a.slabId < b.slabId ? -1 : a.slabId > b.slabId ? 1 : 0));
+        return candidates;
+    }
+    /**
+     * Elevation of a persisted support host for a footprint, or null when
+     * the slab no longer exists on the level or no longer overlaps the
+     * footprint (same overlap test as election). Deliberately read-only: a
+     * host reshaped away is NOT cleared — callers fall back to election and
+     * the stale reference resumes hosting if the slab's polygon returns.
+     * Slab deletion is the only writer (`deleteNodesAction` strips it).
+     */
+    getHostSlabElevationForFootprint(levelId, slabId, position, dimensions, rotation) {
+        const stored = this.slabsByLevel.get(levelId)?.get(slabId);
+        if (!stored)
+            return null;
+        const slab = this.effectiveSlabRecord(stored);
+        if (!this.slabSupportsFootprint(levelId, slab, position, dimensions, rotation))
+            return null;
+        return slab.elevation ?? 0.05;
     }
     /**
      * Get the slab elevation for a wall by checking if it overlaps with any slab polygon (excluding holes).
@@ -963,19 +794,43 @@ export class SpatialGridManager {
      * Accepts an optional `curveOffset` so curved walls evaluate overlap
      * against their actual centerline samples, not just the chord.
      */
-    getSlabElevationForWall(levelId, start, end, curveOffset = 0, thickness = DEFAULT_WALL_THICKNESS) {
-        return this.getSlabSupportForWall(levelId, start, end, curveOffset, thickness).elevation;
-    }
-    getSlabSupportForWall(levelId, start, end, curveOffset = 0, thickness = DEFAULT_WALL_THICKNESS) {
+    getSlabElevationForWall(levelId, start, end, curveOffset = 0, thickness = DEFAULT_WALL_THICKNESS, preferredSlabId) {
+        return this.getSlabSupportForWall(levelId, start, end, curveOffset, thickness, preferredSlabId)
+            .elevation;
+    }
+    getSlabSupportForWall(levelId, start, end, curveOffset = 0, thickness = DEFAULT_WALL_THICKNESS, preferredSlabId, maxElevation, supportOffset = 0) {
+        if (preferredSlabId === GROUND_SUPPORT_ID) {
+            const nodes = useScene.getState().nodes;
+            const elevation = (terrainSupportLift(nodes, levelId, start[0], start[1]) ?? 0) + supportOffset;
+            return {
+                elevation,
+                electedSlabId: null,
+                baseElevation: elevation,
+                baseSegments: [{ start: 0, end: 1, elevation }],
+            };
+        }
         const slabMap = this.slabsByLevel.get(levelId);
         if (!slabMap) {
+            const elevation = supportOffset;
             return {
-                elevation: 0,
-                baseElevation: 0,
-                baseSegments: [{ start: 0, end: 1, elevation: 0 }],
+                elevation,
+                electedSlabId: null,
+                baseElevation: elevation,
+                baseSegments: [{ start: 0, end: 1, elevation }],
             };
         }
-        return computeWallSlabSupport({ start, end, curveOffset, thickness }, [...slabMap.values()], this.getLevelWallNodes(levelId));
+        const support = computeWallSlabSupport({ start, end, curveOffset, thickness }, [...slabMap.values()].map((slab) => this.effectiveSlabRecord(slab)), this.getLevelWallNodes(levelId).map((wall) => getEffectiveNode(wall)), preferredSlabId, maxElevation);
+        if (supportOffset === 0)
+            return support;
+        return {
+            ...support,
+            elevation: support.elevation + supportOffset,
+            baseElevation: support.baseElevation + supportOffset,
+            baseSegments: support.baseSegments.map((segment) => ({
+                ...segment,
+                elevation: segment.elevation + supportOffset,
+            })),
+        };
     }
     /**
      * Walls on a level, resolved fresh from the scene store (the manager's
@@ -1070,6 +925,7 @@ export class SpatialGridManager {
         return { valid: conflicts.length === 0, conflictIds: conflicts };
     }
     clearLevel(levelId) {
+        this.invalidateRenderedSlabPolygons(levelId);
         this.floorGrids.delete(levelId);
         this.wallGrids.delete(levelId);
         this.slabsByLevel.delete(levelId);
@@ -1082,7 +938,26 @@ export class SpatialGridManager {
         this.ceilingGrids.clear();
         this.ceilings.clear();
         this.itemCeilingMap.clear();
+        this.renderedSlabPolygons.clear();
     }
 }
 // Singleton instance
 export const spatialGridManager = new SpatialGridManager();
+/** Level-local Y where the rendered wall mesh begins. */
+export function getWallBaseElevationForNodes(wall, nodes) {
+    const levelId = resolveNodeLevelId(wall, nodes);
+    return spatialGridManager.getSlabSupportForWall(levelId, wall.start, wall.end, wall.curveOffset ?? 0, wall.thickness, wall.supportSlabId ?? null, undefined, wall.supportOffset).elevation;
+}
+/**
+ * Effective (extruded) height of a wall resolved from a nodes record:
+ * {@link resolveWallEffectiveHeight} over the covering-clamped plane top
+ * (`getWallPlaneTop`) and the singleton manager's slab election — so the
+ * value always agrees with the rendered wall. One shared resolver for the
+ * editor overlays (measurement label, action menu, side handles) that used
+ * to copy this derivation locally.
+ */
+export function getWallEffectiveHeightForNodes(wall, nodes) {
+    const levelId = resolveNodeLevelId(wall, nodes);
+    const baseElevation = getWallBaseElevationForNodes(wall, nodes);
+    return resolveWallEffectiveHeight(wall, getWallPlaneTop(wall, levelId, nodes), baseElevation);
+}