@pascal-app/core 1.0.4 → 1.0.6

package/dist/lib/grade-standing.js

@@ -0,0 +1,137 @@
+import { BELOW_GRADE_TOLERANCE, getLevelElevations, isLevelBelowGrade, levelPlaneWorldY, } from '../services/storey.js';
+import { pointInPolygon } from '../systems/slab/slab-support.js';
+import { levelUnderNamedGround } from './ground-level.js';
+import { isSiteFlatwork } from './site-flatwork.js';
+import { heightAt } from './terrain-field.js';
+import { terrainFieldOf } from './terrain-source.js';
+import { levelLocalToWorldXZ, SITE_DATUM_Y } from './terrain-support-query.js';
+/** Sample lines per footprint side at most: enough to catch a slope crossing a floor plate. */
+const MAX_SAMPLE_LINES = 17;
+/**
+ * `levelId`'s standing against the ground. When its building names a ground level, the line is the
+ * word: a level under it is below grade, and one at or over it is not buried by the stack's own
+ * elevations (a basement added under a house, a floor the stack lifted). Where the sculpted terrain
+ * stands over a floor's slabs (sampled against the field, the ground over each slab's own floor
+ * where it stands more than {@link BELOW_GRADE_TOLERANCE} above it: a split level's sunken room is
+ * judged at its own height, not at the raised part's) it still decides how much of that floor is
+ * buried: a hillside buries half a floor whose other half walks out, and a floor under the line the
+ * terrain leaves out of the ground reads as partly below. Without a named ground level, or a field,
+ * the flat datum answers exactly as before. `'at-grade'` for an id that is no level.
+ */
+export function levelGradeStanding(nodes, levelId) {
+    const level = nodes[levelId];
+    if (level?.type !== 'level')
+        return 'at-grade';
+    const under = levelUnderNamedGround(nodes, level);
+    const flat = under === null
+        ? isLevelBelowGrade(nodes, levelId)
+            ? 'below-grade'
+            : 'at-grade'
+        : under
+            ? 'below-grade'
+            : 'at-grade';
+    const field = terrainFieldOverLevel(nodes, level);
+    if (!field)
+        return under === null ? flatFloorsStanding(nodes, level, flat) : flat;
+    const samples = footprintFloorSamples(nodes, level, field);
+    if (samples.length === 0)
+        return flat;
+    let buried = 0;
+    for (const [worldX, worldZ, floorY] of samples) {
+        if (heightAt(field, worldX, worldZ) - floorY > BELOW_GRADE_TOLERANCE)
+            buried += 1;
+    }
+    if (buried === 0)
+        return under ? 'partly-below-grade' : 'at-grade';
+    return buried === samples.length ? 'below-grade' : 'partly-below-grade';
+}
+/**
+ * A flat site with no ground line named: the datum is the ground under every floor, and each floor
+ * slab of the level is judged against it as the sampled path judges them against the field. A split
+ * level whose raised part sits at grade is partly below grade over its sunken room, not at grade
+ * on the strength of its highest floor. A level with no floor slab reads as `fallback` (its plane).
+ */
+function flatFloorsStanding(nodes, level, fallback) {
+    const plane = levelPlaneWorldY(nodes, level.id);
+    if (plane === null)
+        return fallback;
+    const slabs = floorSlabsOf(nodes, level);
+    if (slabs.length === 0)
+        return fallback;
+    const buried = slabs.filter((slab) => floorBuriedOnFlatSite(plane + slab.elevation)).length;
+    if (buried === 0)
+        return 'at-grade';
+    return buried === slabs.length ? 'below-grade' : 'partly-below-grade';
+}
+/** Whether a floor at world Y `floorY` lies under a flat site's datum by more than the tolerance. */
+export function floorBuriedOnFlatSite(floorY) {
+    return SITE_DATUM_Y - floorY > BELOW_GRADE_TOLERANCE;
+}
+/** The floor slabs of the house on a level: not a basin, not site flatwork, with a plan. */
+function floorSlabsOf(nodes, level) {
+    const slabs = [];
+    for (const childId of level.children) {
+        const slab = nodes[childId];
+        if (slab?.type !== 'slab' || slab.recessed === true || slab.polygon.length < 3)
+            continue;
+        if (isSiteFlatwork(slab))
+            continue;
+        slabs.push(slab);
+    }
+    return slabs;
+}
+/** The site's terrain field for the site this level stands on, or null on a flat site. */
+export function terrainFieldOverLevel(nodes, level) {
+    const buildingId = getLevelElevations(nodes).get(level.id)?.buildingId;
+    const building = buildingId ? nodes[buildingId] : undefined;
+    const site = (building?.parentId ? nodes[building.parentId] : undefined) ??
+        Object.values(nodes).find((node) => node.type === 'site');
+    return site?.type === 'site' ? terrainFieldOf(site) : null;
+}
+/**
+ * World XZ samples over the level's floor slabs: each slab's corners plus a grid across it no
+ * coarser than the terrain's own spacing, capped so a big plate stays cheap. Slabs are the
+ * footprint the grade ring already trusts (`belowGradeFootprints`).
+ */
+export function footprintSamples(nodes, level, field) {
+    return footprintFloorSamples(nodes, level, field).map(([x, z]) => [x, z]);
+}
+/**
+ * {@link footprintSamples} with the world Y of the top of the floor slab each sample lies on as a
+ * third coordinate: a level with floors at several heights (a split level) is buried by the ground
+ * over each of them, not over the highest alone.
+ */
+export function footprintFloorSamples(nodes, level, field) {
+    const buildingId = getLevelElevations(nodes).get(level.id)?.buildingId;
+    const building = buildingId ? nodes[buildingId] : undefined;
+    const placed = building?.type === 'building' ? building : null;
+    const plane = levelPlaneWorldY(nodes, level.id);
+    if (plane === null)
+        return [];
+    const samples = [];
+    for (const slab of floorSlabsOf(nodes, level)) {
+        for (const [x, z] of slabSamples(slab.polygon, field.spacing)) {
+            const [worldX, worldZ] = levelLocalToWorldXZ(placed, x, z);
+            samples.push([worldX, worldZ, plane + slab.elevation]);
+        }
+    }
+    return samples;
+}
+function slabSamples(polygon, spacing) {
+    const samples = [...polygon];
+    const xs = polygon.map(([x]) => x);
+    const zs = polygon.map(([, z]) => z);
+    const minX = Math.min(...xs);
+    const maxX = Math.max(...xs);
+    const minZ = Math.min(...zs);
+    const maxZ = Math.max(...zs);
+    const stepX = Math.max(spacing, (maxX - minX) / (MAX_SAMPLE_LINES - 1));
+    const stepZ = Math.max(spacing, (maxZ - minZ) / (MAX_SAMPLE_LINES - 1));
+    for (let x = minX + stepX / 2; x < maxX; x += stepX) {
+        for (let z = minZ + stepZ / 2; z < maxZ; z += stepZ) {
+            if (pointInPolygon(x, z, polygon))
+                samples.push([x, z]);
+        }
+    }
+    return samples;
+}

package/dist/lib/ground-level.d.ts

@@ -0,0 +1,20 @@
+import type { AnyNode, AnyNodeId, LevelNode } from '../schema/index.js';
+/** The level a building stands at grade on, and whether the building says so or it is read off. */
+export type GroundLevel = {
+    level: LevelNode;
+    explicit: boolean;
+};
+/**
+ * The ground line of `buildingId`'s stack: the level standing at grade, the levels with a lower
+ * floor index below it. The building names it (`groundLevelId`, written by "Set as ground floor");
+ * until it does, or when the level named is gone, it is the lowest level whose floor is not under
+ * the flat datum, the reading every scene had before the line existed. `null` for an id that is
+ * no building, or a building with every floor under the ground.
+ */
+export declare function groundLevelOf(nodes: Record<AnyNodeId, AnyNode>, buildingId: string): GroundLevel | null;
+/**
+ * Whether a building that names its ground level puts `level` under it: a lower floor index. `null`
+ * when the line is only read off the elevations (nothing named), so a caller falls back to them.
+ */
+export declare function levelUnderNamedGround(nodes: Record<AnyNodeId, AnyNode>, level: LevelNode): boolean | null;
+//# sourceMappingURL=ground-level.d.ts.map

package/dist/lib/ground-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-level.d.ts","sourceRoot":"","sources":["../../src/lib/ground-level.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAgB,SAAS,EAAE,MAAM,WAAW,CAAA;AAG5E,mGAAmG;AACnG,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAA;AAIjE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,UAAU,EAAE,MAAM,GACjB,WAAW,GAAG,IAAI,CAUpB;AAsBD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,SAAS,GACf,OAAO,GAAG,IAAI,CAMhB"}

package/dist/lib/ground-level.js

@@ -0,0 +1,49 @@
+import { getLevelElevations, isLevelBelowGrade } from '../services/storey.js';
+const groundMemo = new WeakMap();
+/**
+ * The ground line of `buildingId`'s stack: the level standing at grade, the levels with a lower
+ * floor index below it. The building names it (`groundLevelId`, written by "Set as ground floor");
+ * until it does, or when the level named is gone, it is the lowest level whose floor is not under
+ * the flat datum, the reading every scene had before the line existed. `null` for an id that is
+ * no building, or a building with every floor under the ground.
+ */
+export function groundLevelOf(nodes, buildingId) {
+    let byBuilding = groundMemo.get(nodes);
+    if (!byBuilding) {
+        byBuilding = new Map();
+        groundMemo.set(nodes, byBuilding);
+    }
+    if (byBuilding.has(buildingId))
+        return byBuilding.get(buildingId) ?? null;
+    const found = resolveGroundLevel(nodes, buildingId);
+    byBuilding.set(buildingId, found);
+    return found;
+}
+function resolveGroundLevel(nodes, buildingId) {
+    const building = nodes[buildingId];
+    if (building?.type !== 'building')
+        return null;
+    const elevations = getLevelElevations(nodes);
+    const levels = Object.values(nodes)
+        .filter((node) => node.type === 'level' && elevations.get(node.id)?.buildingId === buildingId)
+        .sort((a, b) => a.level - b.level);
+    const named = building.groundLevelId;
+    const explicit = named ? levels.find((level) => level.id === named) : undefined;
+    if (explicit)
+        return { level: explicit, explicit: true };
+    const derived = levels.find((level) => !isLevelBelowGrade(nodes, level.id));
+    return derived ? { level: derived, explicit: false } : null;
+}
+/**
+ * Whether a building that names its ground level puts `level` under it: a lower floor index. `null`
+ * when the line is only read off the elevations (nothing named), so a caller falls back to them.
+ */
+export function levelUnderNamedGround(nodes, level) {
+    const buildingId = getLevelElevations(nodes).get(level.id)?.buildingId;
+    if (!buildingId)
+        return null;
+    const ground = groundLevelOf(nodes, buildingId);
+    if (!ground?.explicit)
+        return null;
+    return level.level < ground.level.level;
+}

package/dist/lib/ground-over-part.d.ts

@@ -0,0 +1,13 @@
+import type { Point2D } from './polygon-union.js';
+import { type TerrainField } from './terrain-field.js';
+/**
+ * The part of `plate` (a floor plate in the world plan) over which the ground stands higher than
+ * `above` metres. The ground is the rendered terrain, the triangle plane `heightAt` reads (each cell
+ * split on its `(c+1,r)`–`(c,r+1)` diagonal), so the cut follows the slope exactly: every triangle
+ * of the field gives its piece where it stands over `above`, a run of cells wholly over it in a row
+ * is one rectangle, and the pieces are joined and cut to the plate. Past the field's edge the
+ * ground is the edge's height, as `heightAt` reads it. Rings only: an island of low ground inside
+ * the part is not cut out.
+ */
+export declare function groundOverPart(plate: readonly Point2D[], field: TerrainField, above: number): Point2D[][];
+//# sourceMappingURL=ground-over-part.d.ts.map

package/dist/lib/ground-over-part.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-over-part.d.ts","sourceRoot":"","sources":["../../src/lib/ground-over-part.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAwBnE;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,MAAM,GACZ,OAAO,EAAE,EAAE,CA0Db"}

package/dist/lib/ground-over-part.js

@@ -0,0 +1,94 @@
+import { area, intersection, union } from './polygon-boolean.js';
+import { heightAtSample } from './terrain-field.js';
+/** Pieces smaller than this (m²) are the clip's rounding, not ground. */
+const MIN_PIECE_AREA = 0.01;
+/** A plate over this many field cells is left whole rather than walked cell by cell. */
+const MAX_CELLS = 90_000;
+/** The part of a triangle where the height is positive, by clipping it against `f > 0` (f is linear on it). */
+function positivePart(triangle) {
+    const part = [];
+    for (let i = 0; i < 3; i += 1) {
+        const a = triangle[i];
+        const b = triangle[(i + 1) % 3];
+        if (a.f > 0)
+            part.push([a.x, a.z]);
+        if (a.f > 0 !== b.f > 0) {
+            const t = a.f / (a.f - b.f);
+            part.push([a.x + (b.x - a.x) * t, a.z + (b.z - a.z) * t]);
+        }
+    }
+    return part;
+}
+/**
+ * The part of `plate` (a floor plate in the world plan) over which the ground stands higher than
+ * `above` metres. The ground is the rendered terrain, the triangle plane `heightAt` reads (each cell
+ * split on its `(c+1,r)`–`(c,r+1)` diagonal), so the cut follows the slope exactly: every triangle
+ * of the field gives its piece where it stands over `above`, a run of cells wholly over it in a row
+ * is one rectangle, and the pieces are joined and cut to the plate. Past the field's edge the
+ * ground is the edge's height, as `heightAt` reads it. Rings only: an island of low ground inside
+ * the part is not cut out.
+ */
+export function groundOverPart(plate, field, above) {
+    if (plate.length < 3)
+        return [];
+    const [originX, originZ] = field.origin;
+    const { spacing } = field;
+    const xs = plate.map(([x]) => x);
+    const zs = plate.map(([, z]) => z);
+    const firstCol = Math.floor((Math.min(...xs) - originX) / spacing);
+    const lastCol = Math.floor((Math.max(...xs) - originX) / spacing);
+    const firstRow = Math.floor((Math.min(...zs) - originZ) / spacing);
+    const lastRow = Math.floor((Math.max(...zs) - originZ) / spacing);
+    if ((lastCol - firstCol + 1) * (lastRow - firstRow + 1) > MAX_CELLS)
+        return [[...plate]];
+    const pieces = [];
+    for (let row = firstRow; row <= lastRow; row += 1) {
+        const z0 = originZ + row * spacing;
+        const z1 = z0 + spacing;
+        let runStart = -1;
+        const closeRun = (col) => {
+            if (runStart < 0)
+                return;
+            const x0 = originX + runStart * spacing;
+            const x1 = originX + col * spacing;
+            pieces.push([
+                [x0, z0],
+                [x1, z0],
+                [x1, z1],
+                [x0, z1],
+            ]);
+            runStart = -1;
+        };
+        for (let col = firstCol; col <= lastCol; col += 1) {
+            const x0 = originX + col * spacing;
+            const x1 = x0 + spacing;
+            const c00 = { x: x0, z: z0, f: heightAtSample(field, col, row) - above };
+            const c10 = { x: x1, z: z0, f: heightAtSample(field, col + 1, row) - above };
+            const c01 = { x: x0, z: z1, f: heightAtSample(field, col, row + 1) - above };
+            const c11 = { x: x1, z: z1, f: heightAtSample(field, col + 1, row + 1) - above };
+            const over = [c00, c10, c01, c11].filter((corner) => corner.f > 0).length;
+            if (over === 4) {
+                if (runStart < 0)
+                    runStart = col;
+                continue;
+            }
+            closeRun(col);
+            if (over === 0)
+                continue;
+            for (const triangle of [
+                [c00, c10, c01],
+                [c11, c01, c10],
+            ]) {
+                const piece = positivePart(triangle);
+                if (piece.length >= 3)
+                    pieces.push(piece);
+            }
+        }
+        closeRun(lastCol + 1);
+    }
+    if (pieces.length === 0)
+        return [];
+    return intersection(union(pieces), [...plate])
+        .filter((polygon) => area([polygon]) >= MIN_PIECE_AREA)
+        .map((polygon) => polygon.outer);
+}

package/dist/lib/ground-seat.d.ts

@@ -0,0 +1,47 @@
+import type { AnyNode, AnyNodeId, LevelNode } from '../schema/index.js';
+import { type FoundationReading } from './foundation-construction.js';
+/** How far the ground floor's datum may stand from its seat and still count as seated on it. */
+export declare const GROUND_SEAT_TOLERANCE = 0.05;
+/**
+ * Where "Set as ground floor" and `set_ground_level` stand the ground floor over finished grade
+ * on the generic (block) foundation: the top of the foundation, where the wood framing starts, 8
+ * in (0.203 m) above the ground. IRC R317.1 keeps wood framing resting on a foundation wall at
+ * least 8 in from exposed ground. A building's region and style can choose another construction
+ * and its own seat (`GroundSeat.aboveGrade`, `FOUNDATION_CONSTRUCTIONS`).
+ */
+export declare const GROUND_FLOOR_ABOVE_GRADE: number;
+/**
+ * The grade a level's floor is seated against: the flat datum on a flat site, and on shaped
+ * terrain the ground's mean height over the level's floor slabs (the building's own origin when it
+ * has none yet).
+ */
+export declare function gradeUnderLevel(nodes: Record<AnyNodeId, AnyNode>, level: LevelNode): number;
+/** Where a building's ground level stands against grade. */
+export type GroundSeat = {
+    buildingId: string;
+    levelId: string;
+    /** The building names it; false when it is read off the elevations. */
+    explicit: boolean;
+    /** World Y of the ground level's floor datum (without its slab). */
+    floorElevation: number;
+    /** World Y of the grade under it. */
+    gradeElevation: number;
+    /** How far the floor datum stands over grade: negative when it is sunk. */
+    offset: number;
+    /** How far the building's foundation construction stands the ground floor over grade, metres. */
+    aboveGrade: number;
+    /** The construction, the region and style it was read from. */
+    foundation: FoundationReading;
+    /**
+     * The floor datum stands between grade and the foundation's top (`aboveGrade`, or the block's
+     * 8 in where that is higher), within {@link GROUND_SEAT_TOLERANCE}: what a scene seated before
+     * the 8 in rule, one seated by it and one seated by its own region's construction all satisfy,
+     * so a check has nothing to say about any of them.
+     */
+    seated: boolean;
+    /** The floor datum stands at `aboveGrade` over grade, within the tolerance. */
+    atFoundationTop: boolean;
+};
+/** `null` for an id that is no building, or a building with no level at or over the ground. */
+export declare function groundSeat(nodes: Record<AnyNodeId, AnyNode>, buildingId: string): GroundSeat | null;
+//# sourceMappingURL=ground-seat.d.ts.map

package/dist/lib/ground-seat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-seat.d.ts","sourceRoot":"","sources":["../../src/lib/ground-seat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAgB,SAAS,EAAE,MAAM,WAAW,CAAA;AAE5E,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,2BAA2B,CAAA;AAMlC,gGAAgG;AAChG,eAAO,MAAM,qBAAqB,OAAO,CAAA;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,QAA8C,CAAA;AAEnF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAa3F;AAED,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAAG;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAA;IACjB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAA;IACtB,qCAAqC;IACrC,cAAc,EAAE,MAAM,CAAA;IACtB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAA;IACd,iGAAiG;IACjG,UAAU,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,UAAU,EAAE,iBAAiB,CAAA;IAC7B;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAA;IACf,+EAA+E;IAC/E,eAAe,EAAE,OAAO,CAAA;CACzB,CAAA;AAED,+FAA+F;AAC/F,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,UAAU,EAAE,MAAM,GACjB,UAAU,GAAG,IAAI,CAsBnB"}

package/dist/lib/ground-seat.js

@@ -0,0 +1,61 @@
+import { getStoreyDatum } from '../services/storey-datum.js';
+import { FOUNDATION_CONSTRUCTIONS, foundationReadingOf, } from './foundation-construction.js';
+import { footprintSamples, terrainFieldOverLevel } from './grade-standing.js';
+import { groundLevelOf } from './ground-level.js';
+import { heightAt } from './terrain-field.js';
+import { levelLocalToWorldXZ, SITE_DATUM_Y } from './terrain-support-query.js';
+/** How far the ground floor's datum may stand from its seat and still count as seated on it. */
+export const GROUND_SEAT_TOLERANCE = 0.05;
+/**
+ * Where "Set as ground floor" and `set_ground_level` stand the ground floor over finished grade
+ * on the generic (block) foundation: the top of the foundation, where the wood framing starts, 8
+ * in (0.203 m) above the ground. IRC R317.1 keeps wood framing resting on a foundation wall at
+ * least 8 in from exposed ground. A building's region and style can choose another construction
+ * and its own seat (`GroundSeat.aboveGrade`, `FOUNDATION_CONSTRUCTIONS`).
+ */
+export const GROUND_FLOOR_ABOVE_GRADE = FOUNDATION_CONSTRUCTIONS.cmu.seatAboveGrade;
+/**
+ * The grade a level's floor is seated against: the flat datum on a flat site, and on shaped
+ * terrain the ground's mean height over the level's floor slabs (the building's own origin when it
+ * has none yet).
+ */
+export function gradeUnderLevel(nodes, level) {
+    const field = terrainFieldOverLevel(nodes, level);
+    if (!field)
+        return SITE_DATUM_Y;
+    const samples = footprintSamples(nodes, level, field);
+    if (samples.length === 0) {
+        const building = nodes[level.parentId];
+        const placed = building?.type === 'building' ? building : null;
+        const [x, z] = levelLocalToWorldXZ(placed, 0, 0);
+        return heightAt(field, x, z);
+    }
+    let sum = 0;
+    for (const [x, z] of samples)
+        sum += heightAt(field, x, z);
+    return sum / samples.length;
+}
+/** `null` for an id that is no building, or a building with no level at or over the ground. */
+export function groundSeat(nodes, buildingId) {
+    const ground = groundLevelOf(nodes, buildingId);
+    const datum = ground ? getStoreyDatum(nodes, ground.level.id) : null;
+    if (!(ground && datum))
+        return null;
+    const gradeElevation = gradeUnderLevel(nodes, ground.level);
+    const offset = datum.floorElevation - gradeElevation;
+    const foundation = foundationReadingOf(nodes, buildingId);
+    const aboveGrade = foundation.construction.seatAboveGrade;
+    return {
+        buildingId,
+        levelId: ground.level.id,
+        explicit: ground.explicit,
+        floorElevation: datum.floorElevation,
+        gradeElevation,
+        offset,
+        aboveGrade,
+        foundation,
+        seated: offset >= -GROUND_SEAT_TOLERANCE &&
+            offset <= Math.max(aboveGrade, GROUND_FLOOR_ABOVE_GRADE) + GROUND_SEAT_TOLERANCE,
+        atFoundationTop: Math.abs(offset - aboveGrade) <= GROUND_SEAT_TOLERANCE,
+    };
+}

package/dist/lib/ground-window.d.ts

@@ -0,0 +1,39 @@
+import type { AnyNode, AnyNodeId } from '../schema/index.js';
+/**
+ * The ground between an eye and the house: a hillside can hide a level that no floor-burial
+ * test flags — the owner's street-side plateau stands 6 m tall just past the walls, over a
+ * pad flattened to 0. These boxes and the march along the sight line are what the ground
+ * window (the veiled patch of ground in the way) is decided from, live and in a capture.
+ */
+export type GroundBox = {
+    min: [number, number, number];
+    max: [number, number, number];
+};
+/**
+ * The world box of one level: its floor slabs' extent (its walls' if it has no slab), from its
+ * lowest floor (the sunken room of a split level) to the height of its highest floor's ceiling.
+ */
+export declare function levelGroundBox(nodes: Record<AnyNodeId, AnyNode>, levelId: string): GroundBox | null;
+/**
+ * The world box of a building (every building, with no id): the union of its levels' boxes.
+ * The window's target when the whole building is shown.
+ */
+export declare function buildingGroundBox(nodes: Record<AnyNodeId, AnyNode>, buildingId?: string | null): GroundBox | null;
+/**
+ * The world box of what the editor's level display shows when `levelId` is the shown level: that
+ * level and the ones under it, in every building (the display decides from the level index alone
+ * and hides the ones above), the levels the author hid left out. Where the fog of the underground
+ * keeps the world clear. `null` for an id that is no level, or when nothing shown has a footprint.
+ */
+export declare function levelStackGroundBox(nodes: Record<AnyNodeId, AnyNode>, levelId: string): GroundBox | null;
+/**
+ * Whether sculpted ground stands between `eye` and `box`: any of the sight lines to a grid
+ * over the box's floor passes under the terrain before it reaches the floor — a grid, not
+ * just the corners, because ground sculpted over the middle of a partly buried floor hides
+ * the rooms under it from above while every corner stays visible. Pure height field
+ * arithmetic — the few throttled CPU rays the view bar's word and the window's on/off
+ * are decided by; the window's shape itself is per-fragment in the renderer. `false` on a
+ * flat site, and for an eye inside the box (a walkthrough sees out, not through a window).
+ */
+export declare function terrainBetweenEyeAndBox(nodes: Record<AnyNodeId, AnyNode>, eye: readonly [number, number, number], box: GroundBox): boolean;
+//# sourceMappingURL=ground-window.d.ts.map

package/dist/lib/ground-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-window.d.ts","sourceRoot":"","sources":["../../src/lib/ground-window.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAA2B,MAAM,WAAW,CAAA;AAO5E;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAA;AAExF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,MAAM,GACd,SAAS,GAAG,IAAI,CAQlB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,SAAS,GAAG,IAAI,CASlB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,MAAM,GACd,SAAS,GAAG,IAAI,CAUlB;AAOD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACtC,GAAG,EAAE,SAAS,GACb,OAAO,CAwBT"}

package/dist/lib/ground-window.js

@@ -0,0 +1,147 @@
+import { getLevelElevations, levelFloorWorldY, levelLowestFloorWorldY } from '../services/storey.js';
+import { isSiteFlatwork } from './site-flatwork.js';
+import { heightAt } from './terrain-field.js';
+import { terrainFieldOf } from './terrain-source.js';
+import { levelLocalToWorldXZ } from './terrain-support-query.js';
+/**
+ * The world box of one level: its floor slabs' extent (its walls' if it has no slab), from its
+ * lowest floor (the sunken room of a split level) to the height of its highest floor's ceiling.
+ */
+export function levelGroundBox(nodes, levelId) {
+    const level = nodes[levelId];
+    const floorY = levelFloorWorldY(nodes, levelId);
+    if (level?.type !== 'level' || floorY === null)
+        return null;
+    const height = getLevelElevations(nodes).get(levelId)?.height ?? 3;
+    const points = footprintPoints(nodes, level);
+    if (points.length === 0)
+        return null;
+    return boxOf(points, levelLowestFloorWorldY(nodes, levelId) ?? floorY, floorY + height);
+}
+/**
+ * The world box of a building (every building, with no id): the union of its levels' boxes.
+ * The window's target when the whole building is shown.
+ */
+export function buildingGroundBox(nodes, buildingId) {
+    let box = null;
+    for (const node of Object.values(nodes)) {
+        if (node.type !== 'level')
+            continue;
+        if (buildingId && getLevelElevations(nodes).get(node.id)?.buildingId !== buildingId)
+            continue;
+        const levelBox = levelGroundBox(nodes, node.id);
+        if (levelBox)
+            box = box ? unionBox(box, levelBox) : levelBox;
+    }
+    return box;
+}
+/**
+ * The world box of what the editor's level display shows when `levelId` is the shown level: that
+ * level and the ones under it, in every building (the display decides from the level index alone
+ * and hides the ones above), the levels the author hid left out. Where the fog of the underground
+ * keeps the world clear. `null` for an id that is no level, or when nothing shown has a footprint.
+ */
+export function levelStackGroundBox(nodes, levelId) {
+    const shown = nodes[levelId];
+    if (shown?.type !== 'level')
+        return null;
+    let box = null;
+    for (const node of Object.values(nodes)) {
+        if (node.type !== 'level' || node.level > shown.level || node.visible === false)
+            continue;
+        const levelBox = levelGroundBox(nodes, node.id);
+        if (levelBox)
+            box = box ? unionBox(box, levelBox) : levelBox;
+    }
+    return box;
+}
+/** How far past the sight line the ground must stand to count as in the way. */
+const SIGHT_CLEARANCE = 0.05;
+/** Sight-line marches at most this long, however far the eye is. */
+const MAX_MARCH_STEPS = 240;
+/**
+ * Whether sculpted ground stands between `eye` and `box`: any of the sight lines to a grid
+ * over the box's floor passes under the terrain before it reaches the floor — a grid, not
+ * just the corners, because ground sculpted over the middle of a partly buried floor hides
+ * the rooms under it from above while every corner stays visible. Pure height field
+ * arithmetic — the few throttled CPU rays the view bar's word and the window's on/off
+ * are decided by; the window's shape itself is per-fragment in the renderer. `false` on a
+ * flat site, and for an eye inside the box (a walkthrough sees out, not through a window).
+ */
+export function terrainBetweenEyeAndBox(nodes, eye, box) {
+    const site = Object.values(nodes).find((node) => node.type === 'site');
+    const field = site?.type === 'site' ? terrainFieldOf(site) : null;
+    if (!field)
+        return false;
+    if (eye[0] >= box.min[0] &&
+        eye[0] <= box.max[0] &&
+        eye[1] >= box.min[1] &&
+        eye[1] <= box.max[1] &&
+        eye[2] >= box.min[2] &&
+        eye[2] <= box.max[2])
+        return false;
+    const floorY = box.min[1];
+    for (const fx of [0, 0.25, 0.5, 0.75, 1])
+        for (const fz of [0, 0.25, 0.5, 0.75, 1]) {
+            const target = [
+                box.min[0] + (box.max[0] - box.min[0]) * fx,
+                floorY,
+                box.min[2] + (box.max[2] - box.min[2]) * fz,
+            ];
+            if (sightLineBuried(field, eye, target))
+                return true;
+        }
+    return false;
+}
+function sightLineBuried(field, eye, target) {
+    const dx = target[0] - eye[0];
+    const dz = target[2] - eye[2];
+    const planLength = Math.hypot(dx, dz);
+    // Straight down: the ground at the eye's own XZ is what the floor under it is seen through.
+    if (planLength < 1e-6)
+        return heightAt(field, eye[0], eye[2]) > target[1] + SIGHT_CLEARANCE;
+    const steps = Math.min(MAX_MARCH_STEPS, Math.max(2, Math.ceil(planLength / field.spacing)));
+    for (let step = 1; step < steps; step += 1) {
+        const t = step / steps;
+        const x = eye[0] + dx * t;
+        const z = eye[2] + dz * t;
+        // Samples over the footprint count too: from above, ground sculpted over part of a
+        // partly buried floor is exactly what stands between the eye and its rooms. A pad at
+        // the floor's own height never trips this — the sight line only reaches it at the
+        // target, where the clearance absorbs it.
+        const sightY = eye[1] + (target[1] - eye[1]) * t;
+        if (heightAt(field, x, z) > sightY + SIGHT_CLEARANCE)
+            return true;
+    }
+    return false;
+}
+function footprintPoints(nodes, level) {
+    const buildingId = getLevelElevations(nodes).get(level.id)?.buildingId;
+    const building = buildingId ? nodes[buildingId] : undefined;
+    const placed = building?.type === 'building' ? building : null;
+    const points = [];
+    for (const childId of level.children) {
+        const child = nodes[childId];
+        if (child?.type === 'slab' && child.recessed !== true && !isSiteFlatwork(child))
+            for (const [x, z] of child.polygon)
+                points.push(levelLocalToWorldXZ(placed, x, z));
+        else if (child?.type === 'wall')
+            for (const [x, z] of [child.start, child.end])
+                points.push(levelLocalToWorldXZ(placed, x, z));
+    }
+    return points;
+}
+function boxOf(points, minY, maxY) {
+    const xs = points.map(([x]) => x);
+    const zs = points.map(([, z]) => z);
+    return {
+        min: [Math.min(...xs), minY, Math.min(...zs)],
+        max: [Math.max(...xs), maxY, Math.max(...zs)],
+    };
+}
+function unionBox(a, b) {
+    return {
+        min: [Math.min(a.min[0], b.min[0]), Math.min(a.min[1], b.min[1]), Math.min(a.min[2], b.min[2])],
+        max: [Math.max(a.max[0], b.max[0]), Math.max(a.max[1], b.max[1]), Math.max(a.max[2], b.max[2])],
+    };
+}

package/dist/lib/opening-floor-datum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"opening-floor-datum.d.ts","sourceRoot":"","sources":["../../src/lib/opening-floor-datum.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAY,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAElF,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,8BAA8B,CAAA;AAsBrC,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC,eAAe,CAoCjB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,sBAAsB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAMnF;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,QAAQ,GAAG,UAAU,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,EACrE,OAAO,EAAE,eAAe,GACvB,MAAM,CAWR;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,QAAQ,GAAG,UAAU,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,EACrE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC,MAAM,CAER;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,QAAQ,GAAG,UAAU,EAAE,UAAU,GAAG,QAAQ,CAAC,EAC3D,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,kBAAmC,GACzC,OAAO,CAGT;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,QAAQ,GAAG,UAAU,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,EACrE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,kBAAmC,GACzC,MAAM,CAIR;AAUD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,QAAQ,GAAG,UAAU,EAC9B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,kBAAmC;;;;;;;EA6D3C;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,QAAQ,GAAG,UAAU,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC,GAAG;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,EACD,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;EAyBzC"}
+{"version":3,"file":"opening-floor-datum.d.ts","sourceRoot":"","sources":["../../src/lib/opening-floor-datum.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAY,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAElF,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,8BAA8B,CAAA;AAqBrC,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC,eAAe,CAoCjB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,sBAAsB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAMnF;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,QAAQ,GAAG,UAAU,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,EACrE,OAAO,EAAE,eAAe,GACvB,MAAM,CAWR;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,QAAQ,GAAG,UAAU,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,EACrE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC,MAAM,CAER;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,QAAQ,GAAG,UAAU,EAAE,UAAU,GAAG,QAAQ,CAAC,EAC3D,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,kBAAmC,GACzC,OAAO,CAGT;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,QAAQ,GAAG,UAAU,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,EACrE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,kBAAmC,GACzC,MAAM,CAIR;AAUD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,QAAQ,GAAG,UAAU,EAC9B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,kBAAmC;;;;;;;EA6D3C;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,QAAQ,GAAG,UAAU,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC,GAAG;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,EACD,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;EAyBzC"}