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

package/dist/lib/terrain-raycast.js

@@ -0,0 +1,188 @@
+/**
+ * Ray → terrain intersection.
+ *
+ * This is the function that replaces `t = -oy / dy` (the flat-ground plane
+ * solve) everywhere the editor asks "where on the ground is the pointer?".
+ * It lives in `core` with no Three.js so the 2D view, the tools, the placement
+ * coordinator, and the tests all call the same code — the failure mode this
+ * avoids is each surface having its own idea of where the ground is, which on
+ * flat ground is invisible and on a slope is a perspective-skewed offset that
+ * only some tools correct for.
+ *
+ * Method: march the ray in `spacing`-sized steps, watching the sign of
+ * `rayY - terrainY`, then bisect the bracketing interval. Marching (rather than
+ * per-triangle intersection over the whole grid) is what keeps this O(path
+ * length) instead of O(samples) — a 129² field is 32 768 triangles, and testing
+ * all of them per pointer-move is not affordable at 50 FPS.
+ *
+ * The bisection is exact to `spacing / 2^ITERATIONS`; at 0.5 m spacing and 20
+ * iterations that is under half a micrometre, i.e. far below the quantization
+ * ladder, so the returned point is on the same rendered triangle plane
+ * `heightAt` reports.
+ */
+import { heightAt } from './terrain-field';
+/** Bisection depth. 20 halvings of one cell is sub-micrometre at any sane spacing. */
+const REFINE_ITERATIONS = 20;
+/**
+ * How far to march before giving up, in multiples of `spacing`.
+ *
+ * A ray aimed just above a distant ridge can travel a long way before it dips
+ * below the surface, but an unbounded march is a hang risk if a caller passes a
+ * near-horizontal ray. The bound is generous relative to any site: at 0.5 m
+ * spacing this is 4 km of travel.
+ */
+const MAX_STEPS = 8192;
+/**
+ * World-XZ bounds of the field, in metres. The march is clipped to this so a ray
+ * pointing away from the site terminates immediately instead of stepping
+ * MAX_STEPS times through empty space.
+ */
+function fieldBounds(field) {
+    return {
+        minX: field.origin[0],
+        minZ: field.origin[1],
+        maxX: field.origin[0] + (field.cols - 1) * field.spacing,
+        maxZ: field.origin[1] + (field.rows - 1) * field.spacing,
+    };
+}
+/**
+ * Min/max height in metres, cached per `heights` buffer.
+ *
+ * The vertical extent is what bounds the march for rays that never leave the
+ * field in XZ — a straight-down pointer ray, which is the single most common
+ * case, has `dx = dz = 0` and therefore an infinite XZ exit. Without a Y bound
+ * such a ray relies on `MAX_STEPS` to terminate, and an *upward* one burns all
+ * 8192 steps before returning null.
+ *
+ * The scan is O(samples), so it is cached on the buffer rather than repeated per
+ * ray. `applyHeightPatch` allocates a new `Int16Array` for every mutation, which
+ * makes the buffer identity a correct version key: a patched field misses the
+ * cache and rescans exactly once, and a stale entry is unreachable. `WeakMap`
+ * keeps it from retaining fields past their use.
+ */
+const heightRangeCache = new WeakMap();
+function heightRange(field) {
+    const cached = heightRangeCache.get(field.heights);
+    if (cached)
+        return cached;
+    let min = 0;
+    let max = 0;
+    if (field.heights.length > 0) {
+        min = field.heights[0] ?? 0;
+        max = min;
+        for (let i = 1; i < field.heights.length; i++) {
+            const h = field.heights[i] ?? 0;
+            if (h < min)
+                min = h;
+            if (h > max)
+                max = h;
+        }
+    }
+    const range = { minY: min * field.step, maxY: max * field.step };
+    heightRangeCache.set(field.heights, range);
+    return range;
+}
+/**
+ * Slab-method clip of the ray against the field's bounding box, returning the
+ * `[tEnter, tExit]` interval to march. Null when the ray misses the box.
+ *
+ * All three axes are clipped, not just XZ. The Y slab is what bounds a
+ * straight-down ray — `dx = dz = 0` makes both XZ slabs "parallel and inside",
+ * so an XZ-only clip returns an infinite exit and the march has to fall back on
+ * `MAX_STEPS`. The Y slab is padded because the surface is bilinear between
+ * samples and a tangent ray must not be clipped exactly at the extremum.
+ */
+function clipToField(field, origin, direction) {
+    const bounds = fieldBounds(field);
+    const { minY, maxY } = heightRange(field);
+    const pad = field.spacing;
+    let tEnter = 0;
+    let tExit = Number.POSITIVE_INFINITY;
+    const axes = [
+        [origin[0], direction[0], bounds.minX, bounds.maxX],
+        [origin[1], direction[1], minY - pad, maxY + pad],
+        [origin[2], direction[2], bounds.minZ, bounds.maxZ],
+    ];
+    for (const [o, d, lo, hi] of axes) {
+        if (Math.abs(d) < 1e-12) {
+            // Parallel to this slab: either always inside or never.
+            if (o < lo || o > hi)
+                return null;
+            continue;
+        }
+        const t1 = (lo - o) / d;
+        const t2 = (hi - o) / d;
+        tEnter = Math.max(tEnter, Math.min(t1, t2));
+        tExit = Math.min(tExit, Math.max(t1, t2));
+        if (tEnter > tExit)
+            return null;
+    }
+    return { tEnter, tExit };
+}
+/**
+ * First intersection of a ray with the terrain surface, or `null` if it misses.
+ *
+ * `direction` need not be normalized; `t` is in units of `direction`'s length,
+ * matching `Ray.at(t)` semantics so a viewer-side caller can pass a three.js ray
+ * through unchanged.
+ *
+ * The march tracks the *sign change* of `rayY - surfaceY` rather than assuming
+ * the ray starts above the ground, so a ray fired from inside a hill or from a
+ * basement finds the surface it exits through. A ray whose origin is already
+ * exactly on the surface returns `t = 0`.
+ */
+export function raycastTerrain(field, origin, direction) {
+    const dirLength = Math.hypot(direction[0], direction[1], direction[2]);
+    if (dirLength < 1e-12)
+        return null;
+    const clip = clipToField(field, origin, direction);
+    if (!clip)
+        return null;
+    const { tEnter, tExit } = clip;
+    // Step in world-space multiples of one cell, converted into t units. Half a
+    // cell, not a full one, so a ray crossing a single-cell spike cannot step over
+    // its peak and report the ground beyond it.
+    const stepT = field.spacing / 2 / dirLength;
+    const at = (t) => ({
+        x: origin[0] + direction[0] * t,
+        y: origin[1] + direction[1] * t,
+        z: origin[2] + direction[2] * t,
+    });
+    const surfaceGap = (t) => {
+        const p = at(t);
+        return p.y - heightAt(field, p.x, p.z);
+    };
+    const hitAt = (t) => {
+        const p = at(t);
+        return { t, x: p.x, y: heightAt(field, p.x, p.z), z: p.z };
+    };
+    let prevT = tEnter;
+    let prevGap = surfaceGap(tEnter);
+    // Entering exactly on the surface counts as a hit — a pointer ray grazing the
+    // ground plane must not fall through to the caller's flat-plane fallback.
+    if (prevGap === 0)
+        return hitAt(tEnter);
+    const startedAbove = prevGap > 0;
+    for (let step = 1; step <= MAX_STEPS; step++) {
+        const t = Math.min(tExit, tEnter + step * stepT);
+        const gap = surfaceGap(t);
+        // A crossing in either direction is a surface hit.
+        if (gap === 0 || gap > 0 !== startedAbove) {
+            let lo = prevT;
+            let hi = t;
+            for (let i = 0; i < REFINE_ITERATIONS; i++) {
+                const mid = (lo + hi) / 2;
+                if (surfaceGap(mid) > 0 === startedAbove)
+                    lo = mid;
+                else
+                    hi = mid;
+            }
+            return hitAt(hi);
+        }
+        prevT = t;
+        prevGap = gap;
+        if (t >= tExit)
+            break;
+    }
+    return null;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Scene → `TerrainField`, cached.
+ *
+ * Every consumer that needs the ground — the mesh builder, the raycast, the
+ * placement predicate, the collider, the 2D view — starts here. It exists to
+ * solve one problem: the scene stores terrain as base64 (`site.terrain`), and
+ * decoding that per frame, or per pointer-move, would be absurd.
+ *
+ * The cache is a `WeakMap` keyed on the **`TerrainData` object identity**, which
+ * is a correct version key because the scene store is immutable-by-convention:
+ * `updateNode` produces a new node object with a new `terrain` object, so a
+ * changed terrain necessarily misses the cache and a stale entry is unreachable.
+ * No invalidation call, no version counter, nothing to forget to bump.
+ *
+ * `commitTerrainField` closes the loop: it encodes a field *and* primes the cache
+ * with the field it just encoded. That is what makes a sculpt stroke free — after
+ * the commit, the next read is a cache hit, so a stroke never decodes base64 even
+ * once, let alone per dab.
+ */
+import type { SiteNode } from '../schema/nodes/site';
+import type { TerrainData } from '../schema/terrain';
+import { createTerrainField, type TerrainField } from './terrain-field';
+/**
+ * The terrain field for a site, or `null` when the site has no sculpted terrain.
+ *
+ * `null` means flat ground at the datum. It is deliberately not "a flat field":
+ * callers use `null` to take their existing flat-ground fast path, which keeps
+ * every scene that has never touched terrain — the overwhelming majority —
+ * running exactly the code it ran before terrain existed. That property is worth
+ * more than the uniformity of always having a field.
+ *
+ * An in-flight sculpt stroke wins over the persisted data. Resolving that *here*
+ * rather than per caller is what makes a stroke consistent: the mesh, the pointer
+ * raycast, the placement predicate, the collider, and the 2D view all see the
+ * same ground mid-drag without any of them knowing a stroke exists. The
+ * alternative — each consumer checking the live store — is how a drag ends up
+ * showing a hill the raycast cannot hit.
+ */
+export declare function terrainFieldOf(site: (Pick<SiteNode, 'terrain'> & {
+    id?: string;
+}) | null | undefined): TerrainField | null;
+/**
+ * The field a site *would* sculpt into: its existing terrain, or a fresh flat
+ * field sized to `options`.
+ *
+ * Separate from `terrainFieldOf` because the read path wants `null` for "no
+ * terrain" and the write path wants something to write into. Collapsing them
+ * would force every reader to allocate a field it does not need.
+ */
+export declare function terrainFieldForEdit(site: Pick<SiteNode, 'terrain'> | null | undefined, options?: Parameters<typeof createTerrainField>[0]): TerrainField;
+/**
+ * Encode a field for persistence and prime the read cache with it.
+ *
+ * Call this instead of `encodeTerrainField` whenever the result is going into the
+ * scene. The returned data is what to write to `site.terrain`; the cache priming
+ * means the very next `terrainFieldOf` on the updated node returns this exact
+ * field object without decoding.
+ */
+export declare function commitTerrainField(field: TerrainField): TerrainData;
+//# sourceMappingURL=terrain-source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-source.d.ts","sourceRoot":"","sources":["../../src/lib/terrain-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAUvE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GACrE,YAAY,GAAG,IAAI,CAkBrB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,EAClD,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,GACjD,YAAY,CAEd;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAInE"}

package/dist/lib/terrain-source.js

@@ -0,0 +1,90 @@
+/**
+ * Scene → `TerrainField`, cached.
+ *
+ * Every consumer that needs the ground — the mesh builder, the raycast, the
+ * placement predicate, the collider, the 2D view — starts here. It exists to
+ * solve one problem: the scene stores terrain as base64 (`site.terrain`), and
+ * decoding that per frame, or per pointer-move, would be absurd.
+ *
+ * The cache is a `WeakMap` keyed on the **`TerrainData` object identity**, which
+ * is a correct version key because the scene store is immutable-by-convention:
+ * `updateNode` produces a new node object with a new `terrain` object, so a
+ * changed terrain necessarily misses the cache and a stale entry is unreachable.
+ * No invalidation call, no version counter, nothing to forget to bump.
+ *
+ * `commitTerrainField` closes the loop: it encodes a field *and* primes the cache
+ * with the field it just encoded. That is what makes a sculpt stroke free — after
+ * the commit, the next read is a cache hit, so a stroke never decodes base64 even
+ * once, let alone per dab.
+ */
+import useLiveTerrain from '../store/use-live-terrain';
+import { decodeTerrainField, encodeTerrainField } from './terrain-codec';
+import { createTerrainField } from './terrain-field';
+const fieldCache = new WeakMap();
+/**
+ * Sites whose `terrain` failed to decode. Prevents re-attempting a doomed decode
+ * on every frame — the corrupt-scene path must be cheap, not just survivable.
+ */
+const failedDecodes = new WeakSet();
+/**
+ * The terrain field for a site, or `null` when the site has no sculpted terrain.
+ *
+ * `null` means flat ground at the datum. It is deliberately not "a flat field":
+ * callers use `null` to take their existing flat-ground fast path, which keeps
+ * every scene that has never touched terrain — the overwhelming majority —
+ * running exactly the code it ran before terrain existed. That property is worth
+ * more than the uniformity of always having a field.
+ *
+ * An in-flight sculpt stroke wins over the persisted data. Resolving that *here*
+ * rather than per caller is what makes a stroke consistent: the mesh, the pointer
+ * raycast, the placement predicate, the collider, and the 2D view all see the
+ * same ground mid-drag without any of them knowing a stroke exists. The
+ * alternative — each consumer checking the live store — is how a drag ends up
+ * showing a hill the raycast cannot hit.
+ */
+export function terrainFieldOf(site) {
+    if (site?.id) {
+        const live = useLiveTerrain.getState().fieldOf(site.id);
+        if (live)
+            return live;
+    }
+    const data = site?.terrain;
+    if (!data)
+        return null;
+    const cached = fieldCache.get(data);
+    if (cached)
+        return cached;
+    if (failedDecodes.has(data))
+        return null;
+    const field = decodeTerrainField(data);
+    if (!field) {
+        failedDecodes.add(data);
+        return null;
+    }
+    fieldCache.set(data, field);
+    return field;
+}
+/**
+ * The field a site *would* sculpt into: its existing terrain, or a fresh flat
+ * field sized to `options`.
+ *
+ * Separate from `terrainFieldOf` because the read path wants `null` for "no
+ * terrain" and the write path wants something to write into. Collapsing them
+ * would force every reader to allocate a field it does not need.
+ */
+export function terrainFieldForEdit(site, options) {
+    return terrainFieldOf(site) ?? createTerrainField(options);
+}
+/**
+ * Encode a field for persistence and prime the read cache with it.
+ *
+ * Call this instead of `encodeTerrainField` whenever the result is going into the
+ * scene. The returned data is what to write to `site.terrain`; the cache priming
+ * means the very next `terrainFieldOf` on the updated node returns this exact
+ * field object without decoding.
+ */
+export function commitTerrainField(field) {
+    const data = encodeTerrainField(field);
+    fieldCache.set(data, field);
+    return data;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Terrain as the level base — the third and last place flat ground was assumed.
+ *
+ * `getFloorPlacedElevation` returns a *lift* added to a node's level-local Y, and
+ * two of its `0`-returns mean "supported by the level base". This module is what
+ * those two branches call so that "the level base" can mean the sculpted ground
+ * instead of the plane `y = 0`. The other `0`-returns are `+0` no-ops for
+ * wall/ceiling-attached items, non-`level` parents, and broken graphs; substituting
+ * terrain there would lift sconces off walls, so they stay `0` forever.
+ *
+ * The whole file is pure — nodes in, metres out — which is what lets the stacking
+ * matrix be tested per kind without a canvas.
+ */
+import type { AnyNode } from '../schema';
+/**
+ * World Y of the site datum — the plane terrain heights are measured from.
+ *
+ * Terrain vertices are absolute world coordinates (the site group renders at the
+ * origin and `terrain-geometry` writes `origin + col * spacing` straight into the
+ * buffer), so the datum is a constant rather than a site property. It is named
+ * because the *comparison* against it is load-bearing, not the value: it is what
+ * separates "the ground" from every other horizontal surface in the scene.
+ */
+export declare const SITE_DATUM_Y = 0;
+/**
+ * How close a surface must sit to the datum to count as the ground.
+ *
+ * Loose enough to absorb float drift through a level's world matrix, tight enough
+ * that a ground slab (5 cm) still reads as a built surface rather than as terrain.
+ */
+export declare const SITE_DATUM_EPSILON = 0.0001;
+/** True when a world-space height is the site datum — i.e. the terrain's plane. */
+export declare function isSiteDatum(worldY: number): boolean;
+/**
+ * Whether the sculpted ground is what a node on `levelId` stands on — i.e.
+ * whether moving the terrain moves that node.
+ *
+ * Split out of `terrainSupportLift` so the invalidation rule that re-elevates
+ * nodes after a sculpt (`markTerrainSupportDependents`) tests grade-ness with
+ * the *same* predicate the resolver does. Two copies of this test would drift,
+ * and the failure is silent: a level the resolver drapes but the dirty rule
+ * skips leaves its contents frozen at the height the ground used to be.
+ *
+ * Deliberately independent of whether a field exists. A stroke that clears the
+ * terrain has to re-elevate exactly the nodes a stroke that creates it does, and
+ * asking about the field here would mark none of them on the way back down.
+ */
+export declare function isLevelAtSiteDatum(nodes: Record<string, AnyNode>, levelId: string): boolean;
+/**
+ * The lift, in level-local metres, that the sculpted ground provides to a node on
+ * `levelId` at level-local `x`/`z`. Null when terrain does not support this node —
+ * no sculpted ground, an unresolvable level, or a storey whose floor is not at
+ * grade.
+ *
+ * Null rather than 0 so callers keep their existing flat-ground path verbatim.
+ * That is what makes this change invisible to every scene that never touched
+ * terrain, which is nearly all of them.
+ */
+export declare function terrainSupportLift(nodes: Record<string, AnyNode>, levelId: string, x: number, z: number): number | null;
+//# sourceMappingURL=terrain-support.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-support.d.ts","sourceRoot":"","sources":["../../src/lib/terrain-support.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,WAAW,CAAA;AAOnD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,IAAI,CAAA;AAE7B;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAO,CAAA;AAEtC,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAqFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3F;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,EACf,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,MAAM,GAAG,IAAI,CAYf"}

package/dist/lib/terrain-support.js

@@ -0,0 +1,150 @@
+/**
+ * Terrain as the level base — the third and last place flat ground was assumed.
+ *
+ * `getFloorPlacedElevation` returns a *lift* added to a node's level-local Y, and
+ * two of its `0`-returns mean "supported by the level base". This module is what
+ * those two branches call so that "the level base" can mean the sculpted ground
+ * instead of the plane `y = 0`. The other `0`-returns are `+0` no-ops for
+ * wall/ceiling-attached items, non-`level` parents, and broken graphs; substituting
+ * terrain there would lift sconces off walls, so they stay `0` forever.
+ *
+ * The whole file is pure — nodes in, metres out — which is what lets the stacking
+ * matrix be tested per kind without a canvas.
+ */
+import { getLevelElevations } from '../services/storey';
+import { heightAt } from './terrain-field';
+import { terrainFieldOf } from './terrain-source';
+/**
+ * World Y of the site datum — the plane terrain heights are measured from.
+ *
+ * Terrain vertices are absolute world coordinates (the site group renders at the
+ * origin and `terrain-geometry` writes `origin + col * spacing` straight into the
+ * buffer), so the datum is a constant rather than a site property. It is named
+ * because the *comparison* against it is load-bearing, not the value: it is what
+ * separates "the ground" from every other horizontal surface in the scene.
+ */
+export const SITE_DATUM_Y = 0;
+/**
+ * How close a surface must sit to the datum to count as the ground.
+ *
+ * Loose enough to absorb float drift through a level's world matrix, tight enough
+ * that a ground slab (5 cm) still reads as a built surface rather than as terrain.
+ */
+export const SITE_DATUM_EPSILON = 1e-4;
+/** True when a world-space height is the site datum — i.e. the terrain's plane. */
+export function isSiteDatum(worldY) {
+    return Math.abs(worldY - SITE_DATUM_Y) < SITE_DATUM_EPSILON;
+}
+/**
+ * `getLevelElevations` memoized on the `nodes` record identity.
+ *
+ * Without this the stacking resolver is O(N) per node and therefore O(N²) per
+ * frame, since `FloorElevationSystem` calls it for every dirty floor-placed node.
+ * The scene store is immutable-by-convention, so the record identity is a correct
+ * version key — the same reasoning (and the same `WeakMap` shape) as
+ * `terrain-source`'s field cache and the spatial grid's `levelWallsCache`.
+ */
+const levelElevationCache = new WeakMap();
+function cachedLevelElevations(nodes) {
+    const cached = levelElevationCache.get(nodes);
+    if (cached)
+        return cached;
+    const elevations = getLevelElevations(nodes);
+    levelElevationCache.set(nodes, elevations);
+    return elevations;
+}
+function siteOf(nodes) {
+    for (const node of Object.values(nodes)) {
+        if (node?.type === 'site')
+            return node;
+    }
+    return null;
+}
+/**
+ * Level-local XZ → world XZ, through the building's transform.
+ *
+ * A level group carries only a Y offset (`LevelSystem` writes `position.y` and
+ * nothing else), so level-local XZ is building-local XZ; the building carries the
+ * site-space placement, and the site renders at the origin. Only the Y rotation
+ * matters — a building tipped in X or Z is not a thing the editor can produce.
+ */
+function levelLocalToWorldXZ(building, x, z) {
+    if (!building)
+        return [x, z];
+    const angle = building.rotation?.[1] ?? 0;
+    const [px, , pz] = building.position ?? [0, 0, 0];
+    if (angle === 0)
+        return [x + px, z + pz];
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    return [cos * x + sin * z + px, -sin * x + cos * z + pz];
+}
+/**
+ * Where a level sits relative to the datum, for the levels terrain can support.
+ *
+ * **Only the storey the level stack puts at the datum follows terrain.** An upper
+ * storey has a real floor, and draping it would sink its contents into the
+ * hillside under the building. The test is that storey's own base height against
+ * the datum — deliberately asked of `getLevelElevations`, the same function the
+ * renderer positions level groups with, so placement can never hold a second
+ * opinion about which storey is on the ground.
+ *
+ * Which storey that is follows from the stack, not from the ordinal: today the
+ * lowest ordinal anchors at 0, so a building with an ordinal `-1` level has *that*
+ * level at grade and its ground floor a storey up. When genuine below-grade
+ * stacking lands, this rule tracks it with no change here — an excavated basement
+ * will stop being at the datum, and stop being draped, on its own.
+ */
+function levelDatum(nodes, levelId) {
+    const elevation = cachedLevelElevations(nodes).get(levelId);
+    if (!elevation)
+        return null;
+    const building = elevation.buildingId
+        ? (nodes[elevation.buildingId] ?? null)
+        : null;
+    const datum = building?.position?.[1] ?? 0;
+    const baseWorldY = datum + elevation.baseY;
+    if (!isSiteDatum(baseWorldY))
+        return null;
+    return { building, baseWorldY };
+}
+/**
+ * Whether the sculpted ground is what a node on `levelId` stands on — i.e.
+ * whether moving the terrain moves that node.
+ *
+ * Split out of `terrainSupportLift` so the invalidation rule that re-elevates
+ * nodes after a sculpt (`markTerrainSupportDependents`) tests grade-ness with
+ * the *same* predicate the resolver does. Two copies of this test would drift,
+ * and the failure is silent: a level the resolver drapes but the dirty rule
+ * skips leaves its contents frozen at the height the ground used to be.
+ *
+ * Deliberately independent of whether a field exists. A stroke that clears the
+ * terrain has to re-elevate exactly the nodes a stroke that creates it does, and
+ * asking about the field here would mark none of them on the way back down.
+ */
+export function isLevelAtSiteDatum(nodes, levelId) {
+    return levelDatum(nodes, levelId) !== null;
+}
+/**
+ * The lift, in level-local metres, that the sculpted ground provides to a node on
+ * `levelId` at level-local `x`/`z`. Null when terrain does not support this node —
+ * no sculpted ground, an unresolvable level, or a storey whose floor is not at
+ * grade.
+ *
+ * Null rather than 0 so callers keep their existing flat-ground path verbatim.
+ * That is what makes this change invisible to every scene that never touched
+ * terrain, which is nearly all of them.
+ */
+export function terrainSupportLift(nodes, levelId, x, z) {
+    const site = siteOf(nodes);
+    const field = site ? terrainFieldOf(site) : null;
+    if (!field)
+        return null;
+    const datum = levelDatum(nodes, levelId);
+    if (!datum)
+        return null;
+    const [worldX, worldZ] = levelLocalToWorldXZ(datum.building, x, z);
+    // The lift is measured from the storey's own base, so a building sited on a
+    // datum other than 0 does not double-count it.
+    return heightAt(field, worldX, worldZ) - datum.baseWorldY;
+}

package/dist/lib/wall-distance.d.ts

@@ -0,0 +1,60 @@
+import type { WallNode } from '../schema/nodes/wall';
+import type { AnyNode, AnyNodeId } from '../schema/types';
+/**
+ * Pure plan-space wall-distance math shared by the 2D opening snap
+ * (`findClosestWallInPlan` in @pascal-app/nodes) and the editor's 2D
+ * Voronoi debug overlay. One source of truth means the overlay is a
+ * faithful picture of what the snap actually decides.
+ *
+ * A wall segment's Voronoi cell is exactly "the points whose nearest wall
+ * is this segment", so nearest-segment classification == the segment
+ * Voronoi diagram. Curved walls are excluded (the opening snap rejects
+ * them — mitering + arc + opening tears in 3D).
+ */
+/**
+ * Max cursor-to-wall plan distance (metres) for a 2D opening to snap onto a
+ * wall. Tight, because plan walls are thin and often close together — a large
+ * radius would let a far wall's region reach across a nearer one. Shared so the
+ * snap and the Voronoi debug overlay clip to the exact same range.
+ */
+export declare const WALL_SNAP_DISTANCE_M = 0.4;
+export type WallSegment = {
+    wall: WallNode;
+    /** [x, z] plan start. */
+    start: readonly [number, number];
+    /** [x, z] plan end. */
+    end: readonly [number, number];
+    /** Unit direction (start → end) in plan. */
+    dirX: number;
+    dirY: number;
+    /** Segment length in metres. */
+    length: number;
+};
+export type WallSegmentClosest = {
+    segment: WallSegment;
+    /** Distance from the query point to the closest point on the segment. */
+    distance: number;
+    /** Distance along the wall from `start`, clamped to [0, length]. */
+    along: number;
+    /** Signed perpendicular offset from the wall axis (+ on the front side). */
+    perp: number;
+};
+/**
+ * Collect the straight (non-curved) wall segments that are direct children
+ * of a level — the candidates an opening can snap onto.
+ */
+export declare function collectLevelWallSegments(nodes: Record<AnyNodeId, AnyNode>, levelId: AnyNodeId | null): WallSegment[];
+/** Closest point + signed offset of one query point against one segment. */
+export declare function closestOnSegment(segment: WallSegment, pointX: number, pointY: number): {
+    distance: number;
+    along: number;
+    perp: number;
+};
+/**
+ * The single nearest wall segment to a plan point — its Voronoi cell. Returns
+ * null when `segments` is empty or (when `maxDistance` is given) nothing is
+ * within range. Ties resolve to the first segment scanned; callers pass an
+ * already-curved-filtered list from `collectLevelWallSegments`.
+ */
+export declare function nearestWallSegment(segments: readonly WallSegment[], pointX: number, pointY: number, maxDistance?: number, excludeWallId?: AnyNodeId): WallSegmentClosest | null;
+//# sourceMappingURL=wall-distance.d.ts.map

package/dist/lib/wall-distance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wall-distance.d.ts","sourceRoot":"","sources":["../../src/lib/wall-distance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAGzD;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAA;AAEvC,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,QAAQ,CAAA;IACd,yBAAyB;IACzB,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,uBAAuB;IACvB,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,WAAW,CAAA;IACpB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,SAAS,GAAG,IAAI,GACxB,WAAW,EAAE,CA0Bf;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CASnD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,WAAW,EAAE,EAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,WAAW,SAA2B,EACtC,aAAa,CAAC,EAAE,SAAS,GACxB,kBAAkB,GAAG,IAAI,CAU3B"}