@pascal-app/core 1.0.4 → 1.0.6

package/dist/lib/foundation-standard.js

@@ -0,0 +1,30 @@
+const INCH = 0.0254;
+/**
+ * The standard numbers of a residential foundation, in metres, stated once: the generic foundation
+ * the viewer draws under every building (`genericFoundation`), Bones' pour and the sections
+ * plugin's drawings all read them. They are the common US residential values (IRC chapters 4 and
+ * 5), not a jurisdiction's: core holds no frost data, so what depends on one (the frost line, the
+ * wall convention) stays with the jurisdiction profile in Bones.
+ */
+export const FOUNDATION_STANDARD = {
+    /** Continuous footing under an exterior wall: 16 in wide, the usual pour for light framing (IRC R403.1). */
+    footingWidth: 16 * INCH,
+    /** 6 in is the minimum (IRC Table R403.1(1)); 8 in is the near-universal pour. */
+    footingThickness: 8 * INCH,
+    /**
+     * How far the footing's bottom sits under the lowest grade where nothing says better: 12 in, the
+     * shallowest Bones allows (IRC R403.1.4.1 asks for the frost line, which core does not know). A
+     * generic depth, drawn as one.
+     */
+    footingBelowGrade: 12 * INCH,
+    /** The foundation wall (the stem) from the footing up to the floor: 8 in (IRC R404.1). */
+    stemThickness: 8 * INCH,
+    /** A crawl space vent, 8 × 16 in screened for 50 sq in net (IRC R408.1), within 3 ft of each corner, set 2 ft in (R408.2). */
+    ventWidth: 16 * INCH,
+    ventHeight: 8 * INCH,
+    ventNetAreaSqIn: 50,
+    ventCornerInset: 24 * INCH,
+    /** The crawl space access through the stem: 16 × 24 in (IRC R408.4). */
+    crawlAccessWidth: 24 * INCH,
+    crawlAccessHeight: 16 * INCH,
+};

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

@@ -0,0 +1,36 @@
+import { type AnyNode, type AnyNodeId, WallNode } from '../schema/index.js';
+import type { Assembly } from '../schema/assembly.js';
+import { type FoundationConstruction, type FoundationReading } from './foundation-construction.js';
+/**
+ * Whether a wall against the ground on `levelId` is a foundation wall: the level is below grade everywhere, or the
+ * building's ground line puts it under the ground floor (a basement the terrain leaves part of out
+ * of the ground). A floor a hillside only half buries, with nothing named under the line, is a floor.
+ */
+export declare function levelHoldsFoundationWalls(nodes: Record<AnyNodeId, AnyNode>, levelId: string): boolean;
+/** What the agent is told of the rule: the foundation wall of this building's construction, and what is not one. */
+export declare function foundationWallRule(reading: FoundationReading): string;
+/** The construction a foundation wall is born with. */
+export declare function foundationWallConstruction(construction: FoundationConstruction): {
+    assembly: Assembly;
+    thickness: number;
+};
+/**
+ * The `candidates` (walls among `levelWalls`, the level's walls with them in) that hold the earth
+ * back: the level holds foundation walls and no closed circuit of walls encloses them. A partition
+ * inside the outline is not one, nor is a ring of walls inside it (a courtyard walled on every
+ * side: a room open to the sky, as the structure kernel reads it, facing air, not earth). A wall
+ * outside the outline (a well against it) is. A wall with no closed circuit around it yet (the
+ * first walls of a basement, an open run) counts as the outline in the making, so a basement drawn
+ * wall by wall is foundation all the way round. The outline is the one `genericFoundation` draws
+ * under.
+ */
+export declare function wallsAgainstGround(nodes: Record<AnyNodeId, AnyNode>, levelId: string, levelWalls: WallNode[], candidates: WallNode[]): WallNode[];
+/**
+ * The walls just drawn on `levelId` (`inserted`, among `levelWalls` with them in) as the level's
+ * default builds them: the walls against the ground take the foundation construction of the
+ * building's region (CMU or cast concrete), a
+ * partition keeps the ordinary wall. A caller who gave a thickness or an assembly (`given`) keeps
+ * it; existing walls are never rewritten.
+ */
+export declare function withFoundationConstruction(nodes: Record<AnyNodeId, AnyNode>, levelId: string, levelWalls: WallNode[], inserted: WallNode[], given: Partial<WallNode>): WallNode[];
+//# sourceMappingURL=foundation-wall.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-wall.d.ts","sourceRoot":"","sources":["../../src/lib/foundation-wall.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAkB,QAAQ,EAAE,MAAM,WAAW,CAAA;AAClF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAGlD,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EAEvB,MAAM,2BAA2B,CAAA;AAIlC;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,MAAM,GACd,OAAO,CAQT;AAED,oHAAoH;AACpH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAErE;AAED,uDAAuD;AACvD,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,sBAAsB,GAAG;IAChF,QAAQ,EAAE,QAAQ,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;CAClB,CAMA;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,QAAQ,EAAE,EACtB,UAAU,EAAE,QAAQ,EAAE,GACrB,QAAQ,EAAE,CAIZ;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,QAAQ,EAAE,EACtB,QAAQ,EAAE,QAAQ,EAAE,EACpB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,GACvB,QAAQ,EAAE,CAYZ"}

package/dist/lib/foundation-wall.js

@@ -0,0 +1,66 @@
+import { WallNode } from '../schema/index.js';
+import { assemblyThickness } from '../systems/wall/wall-assembly.js';
+import { enclosedWallIds } from './exterior-wall-loops.js';
+import { foundationReadingOfLevel, } from './foundation-construction.js';
+import { levelGradeStanding } from './grade-standing.js';
+import { levelUnderNamedGround } from './ground-level.js';
+/**
+ * Whether a wall against the ground on `levelId` is a foundation wall: the level is below grade everywhere, or the
+ * building's ground line puts it under the ground floor (a basement the terrain leaves part of out
+ * of the ground). A floor a hillside only half buries, with nothing named under the line, is a floor.
+ */
+export function levelHoldsFoundationWalls(nodes, levelId) {
+    const level = nodes[levelId];
+    if (level?.type !== 'level')
+        return false;
+    const standing = levelGradeStanding(nodes, levelId);
+    if (standing === 'below-grade')
+        return true;
+    return (standing === 'partly-below-grade' && levelUnderNamedGround(nodes, level) === true);
+}
+/** What the agent is told of the rule: the foundation wall of this building's construction, and what is not one. */
+export function foundationWallRule(reading) {
+    return `a wall against the ground on a level below grade is a foundation wall (${reading.construction.description}); a partition is an ordinary wall; the construction follows the region and style (${reading.basis})`;
+}
+/** The construction a foundation wall is born with. */
+export function foundationWallConstruction(construction) {
+    return {
+        assembly: structuredClone(construction.assembly),
+        // Micrometres: the stored thickness is a clean 0.241, not the float noise of 0.203 + 0.038.
+        thickness: Math.round(assemblyThickness(construction.assembly) * 1e6) / 1e6,
+    };
+}
+/**
+ * The `candidates` (walls among `levelWalls`, the level's walls with them in) that hold the earth
+ * back: the level holds foundation walls and no closed circuit of walls encloses them. A partition
+ * inside the outline is not one, nor is a ring of walls inside it (a courtyard walled on every
+ * side: a room open to the sky, as the structure kernel reads it, facing air, not earth). A wall
+ * outside the outline (a well against it) is. A wall with no closed circuit around it yet (the
+ * first walls of a basement, an open run) counts as the outline in the making, so a basement drawn
+ * wall by wall is foundation all the way round. The outline is the one `genericFoundation` draws
+ * under.
+ */
+export function wallsAgainstGround(nodes, levelId, levelWalls, candidates) {
+    if (!levelHoldsFoundationWalls(nodes, levelId))
+        return [];
+    const enclosed = enclosedWallIds(levelWalls.filter((wall) => wall.visible !== false));
+    return candidates.filter((wall) => !enclosed.has(wall.id));
+}
+/**
+ * The walls just drawn on `levelId` (`inserted`, among `levelWalls` with them in) as the level's
+ * default builds them: the walls against the ground take the foundation construction of the
+ * building's region (CMU or cast concrete), a
+ * partition keeps the ordinary wall. A caller who gave a thickness or an assembly (`given`) keeps
+ * it; existing walls are never rewritten.
+ */
+export function withFoundationConstruction(nodes, levelId, levelWalls, inserted, given) {
+    if (given.assembly !== undefined || given.thickness !== undefined)
+        return inserted;
+    const against = new Set(wallsAgainstGround(nodes, levelId, levelWalls, inserted).map((wall) => wall.id));
+    if (against.size === 0)
+        return inserted;
+    const { construction } = foundationReadingOfLevel(nodes, levelId);
+    return inserted.map((wall) => against.has(wall.id)
+        ? WallNode.parse({ ...wall, ...foundationWallConstruction(construction) })
+        : wall);
+}

package/dist/lib/generic-foundation.d.ts

@@ -0,0 +1,40 @@
+import type { AnyNode, AnyNodeId } from '../schema/index.js';
+type Nodes = Record<AnyNodeId, AnyNode>;
+/**
+ * One run of the foundation under the exterior walls: a prism along `from` to `to` (world plan,
+ * already carried past the wall's ends so the corners close), `width` wide, from `bottomY` up to
+ * `topY`. A `footing` is the concrete pour under the wall, a `stem` the foundation wall on it,
+ * built of `material`: the footing is always concrete, the stem is what the building's
+ * foundation construction is (block or cast concrete, by region).
+ */
+export type FoundationMember = {
+    kind: 'footing' | 'stem';
+    material: 'concrete' | 'cmu';
+    levelId: string;
+    from: [number, number];
+    to: [number, number];
+    width: number;
+    bottomY: number;
+    topY: number;
+};
+/**
+ * The foundation a building stands on where the scene stores none: a continuous footing and a
+ * foundation wall under the exterior walls of each building's lowest level with a closed outline,
+ * derived from those walls, never stored, so nothing in a saved scene changes. The numbers are
+ * {@link FOUNDATION_STANDARD}: a 16 × 8 in footing whose bottom sits 12 in under the lowest grade
+ * (a generic depth: core has no frost data), and a wall from the footing up to the underside of the
+ * lowest floor, of the building's foundation construction (`foundationReadingOf`): 8 in block by
+ * default, cast concrete in Europe.
+ *
+ * - A level below grade (all of it) has no second wall: its exterior walls are the foundation
+ *   walls, so only the footing is drawn, under the underside of its floor.
+ * - A wall that stores its own stem (`underpinning`) keeps it; the footing goes under that stem.
+ * - A slab that stores a solid foundation skirt (`foundation`) is the foundation under its level:
+ *   walls without a stored stem get nothing.
+ * - A node that declares `drawsFoundation` on the level (a framing plugin) draws it itself: the
+ *   generic one steps aside. The plugin may read `isCaptureSessionOn()` to give it back to a
+ *   picture, which shows the finished house.
+ */
+export declare function genericFoundation(nodes: Nodes): FoundationMember[];
+export {};
+//# sourceMappingURL=generic-foundation.d.ts.map

package/dist/lib/generic-foundation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-foundation.d.ts","sourceRoot":"","sources":["../../src/lib/generic-foundation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAA+C,MAAM,WAAW,CAAA;AAYhG,KAAK,KAAK,GAAG,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;IACxB,QAAQ,EAAE,UAAU,GAAG,KAAK,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtB,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAgBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,gBAAgB,EAAE,CAWlE"}

package/dist/lib/generic-foundation.js

@@ -0,0 +1,200 @@
+import { isCaptureSessionOn } from '../events/capture-sessions.js';
+import { nodeRegistry } from '../registry/index.js';
+import { getLevelElevations, levelPlateUndersideWorldY } from '../services/storey.js';
+import { getWallCenterlineSegments } from '../systems/wall/wall-curve.js';
+import { getWallThickness } from '../systems/wall/wall-footprint.js';
+import { getWallBodyCenterOffset } from '../systems/wall/wall-frame.js';
+import { exteriorWallLoops } from './exterior-wall-loops.js';
+import { foundationReadingOf } from './foundation-construction.js';
+import { FOUNDATION_STANDARD } from './foundation-standard.js';
+import { levelGradeStanding } from './grade-standing.js';
+import { groundHeightAt } from './site-ground-height.js';
+import { levelLocalToWorldXZ } from './terrain-support-query.js';
+const STEM_MATERIAL = {
+    cmu: 'cmu',
+    'cast-concrete': 'concrete',
+};
+/** The lowest grade is sampled at this many points along each wall, the generator's own count. */
+const GRADE_SAMPLES = 7;
+/** A stem shorter than this is the floor sitting on the footing: nothing to draw. */
+const MIN_STEM_HEIGHT = 1e-3;
+// Per scene and per capture session: a plugin's `drawsFoundation` may step aside from a picture
+// (the pictures show the finished house), a state no node holds.
+const memo = new WeakMap();
+/**
+ * The foundation a building stands on where the scene stores none: a continuous footing and a
+ * foundation wall under the exterior walls of each building's lowest level with a closed outline,
+ * derived from those walls, never stored, so nothing in a saved scene changes. The numbers are
+ * {@link FOUNDATION_STANDARD}: a 16 × 8 in footing whose bottom sits 12 in under the lowest grade
+ * (a generic depth: core has no frost data), and a wall from the footing up to the underside of the
+ * lowest floor, of the building's foundation construction (`foundationReadingOf`): 8 in block by
+ * default, cast concrete in Europe.
+ *
+ * - A level below grade (all of it) has no second wall: its exterior walls are the foundation
+ *   walls, so only the footing is drawn, under the underside of its floor.
+ * - A wall that stores its own stem (`underpinning`) keeps it; the footing goes under that stem.
+ * - A slab that stores a solid foundation skirt (`foundation`) is the foundation under its level:
+ *   walls without a stored stem get nothing.
+ * - A node that declares `drawsFoundation` on the level (a framing plugin) draws it itself: the
+ *   generic one steps aside. The plugin may read `isCaptureSessionOn()` to give it back to a
+ *   picture, which shows the finished house.
+ */
+export function genericFoundation(nodes) {
+    const capturing = isCaptureSessionOn();
+    const hit = memo.get(nodes);
+    if (hit && hit.capturing === capturing)
+        return hit.members;
+    const members = [];
+    for (const node of Object.values(nodes)) {
+        if (node.type === 'building' && node.visible !== false)
+            members.push(...buildingFoundation(nodes, node));
+    }
+    memo.set(nodes, { capturing, members });
+    return members;
+}
+function buildingFoundation(nodes, building) {
+    const enclosed = lowestEnclosedLevel(nodes, building);
+    if (!enclosed || levelDrawsFoundation(nodes, enclosed.level))
+        return [];
+    const { level, walls } = enclosed;
+    const site = siteOf(nodes, building);
+    const gradeAt = (x, z) => groundHeightAt(site, x, z);
+    const lowestGrade = Math.min(...walls.map((wall) => lowestGradeAlong(building, wall, gradeAt)));
+    const floors = floorsOf(nodes, level);
+    const wallBaseY = building.position[1] + (getLevelElevations(nodes).get(level.id)?.baseY ?? 0);
+    // The footing never pokes above the wall's base into the room, nor above the floor's underside.
+    const floorUnderside = levelPlateUndersideWorldY(nodes, level.id) ?? wallBaseY;
+    const { construction } = foundationReadingOf(nodes, building.id);
+    const stemMaterial = STEM_MATERIAL[construction.id];
+    const stemThickness = construction.stemThickness;
+    const buried = levelGradeStanding(nodes, level.id) === 'below-grade';
+    const solidSkirt = floors.some((floor) => floor.foundation?.type === 'solid');
+    const members = [];
+    for (const wall of walls) {
+        const stored = wall.underpinning;
+        if (!stored && solidSkirt)
+            continue;
+        const run = runOf(building, wall, stemThickness);
+        const wallWidth = Math.max(stemThickness, getWallThickness(wall));
+        const footingWidth = wallWidth + FOUNDATION_STANDARD.footingWidth - FOUNDATION_STANDARD.stemThickness;
+        const footingTop = stored
+            ? Math.min(wallBaseY - stored.rim - stored.stem, lowestGradeAlong(building, wall, gradeAt))
+            : footingTopUnder(floorUnderside, lowestGrade);
+        const footingBottom = footingTop - FOUNDATION_STANDARD.footingThickness;
+        for (const segment of run) {
+            members.push({
+                kind: 'footing',
+                material: 'concrete',
+                levelId: level.id,
+                ...segment,
+                width: footingWidth,
+                bottomY: footingBottom,
+                topY: footingTop,
+            });
+            if (stored || buried || floorUnderside - footingTop < MIN_STEM_HEIGHT)
+                continue;
+            members.push({
+                kind: 'stem',
+                material: stemMaterial,
+                levelId: level.id,
+                ...segment,
+                width: wallWidth,
+                bottomY: footingTop,
+                topY: floorUnderside,
+            });
+        }
+    }
+    return members;
+}
+/**
+ * The footing's top: the generic depth under the lowest grade, or the floor's underside where that
+ * is deeper (a level below grade sits its footing right under its floor).
+ */
+function footingTopUnder(floorUnderside, lowestGrade) {
+    const { footingBelowGrade, footingThickness } = FOUNDATION_STANDARD;
+    return Math.min(lowestGrade - footingBelowGrade + footingThickness, floorUnderside);
+}
+/**
+ * The building's lowest level whose walls close an outline, with those exterior walls. A level
+ * under the ground still being drawn (a basement's first wall, an open run) carries no foundation
+ * yet, and the one over it does; a level at grade whose walls close nothing stands on nothing
+ * drawn, whatever is over it.
+ */
+function lowestEnclosedLevel(nodes, building) {
+    const elevations = getLevelElevations(nodes);
+    const levels = Object.values(nodes)
+        .filter((node) => node.type === 'level' && elevations.get(node.id)?.buildingId === building.id)
+        .sort((a, b) => a.level - b.level);
+    for (const level of levels) {
+        if (!level.children.some((id) => nodes[id]?.type === 'wall'))
+            continue;
+        const walls = exteriorWalls(nodes, level);
+        if (walls.length > 0)
+            return { level, walls };
+        if (levelGradeStanding(nodes, level.id) === 'at-grade')
+            return null;
+    }
+    return null;
+}
+function levelDrawsFoundation(nodes, level) {
+    return level.children.some((id) => {
+        const child = nodes[id];
+        return child
+            ? nodeRegistry.get(child.type)?.capabilities?.drawsFoundation?.(child) === true
+            : false;
+    });
+}
+function exteriorWalls(nodes, level) {
+    const walls = level.children
+        .map((id) => nodes[id])
+        .filter((node) => node?.type === 'wall' && node.visible !== false);
+    const outside = new Set();
+    for (const loop of exteriorWallLoops(walls))
+        for (const face of loop)
+            outside.add(face.wallId);
+    return walls.filter((wall) => outside.has(wall.id));
+}
+function floorsOf(nodes, level) {
+    return level.children
+        .map((id) => nodes[id])
+        .filter((node) => node?.type === 'slab' && node.recessed !== true);
+}
+function siteOf(nodes, building) {
+    const parent = building.parentId ? nodes[building.parentId] : undefined;
+    return parent?.type === 'site'
+        ? parent
+        : (Object.values(nodes).find((node) => node.type === 'site') ?? null);
+}
+function lowestGradeAlong(building, wall, gradeAt) {
+    let lowest = Number.POSITIVE_INFINITY;
+    for (let k = 0; k < GRADE_SAMPLES; k++) {
+        const t = k / (GRADE_SAMPLES - 1);
+        const [x, z] = levelLocalToWorldXZ(building, wall.start[0] + (wall.end[0] - wall.start[0]) * t, wall.start[1] + (wall.end[1] - wall.start[1]) * t);
+        lowest = Math.min(lowest, gradeAt(x, z));
+    }
+    return lowest;
+}
+/**
+ * A wall's body centreline in the world as consecutive runs, each carried half its width past both
+ * ends so the runs of a corner (or a curve's pieces) overlap and close it.
+ */
+function runOf(building, wall, stemThickness) {
+    const offset = getWallBodyCenterOffset(wall);
+    const reach = Math.max(stemThickness, getWallThickness(wall)) / 2;
+    return getWallCenterlineSegments(wall).flatMap(([a, b]) => {
+        const dx = b.x - a.x;
+        const dz = b.y - a.y;
+        const length = Math.hypot(dx, dz);
+        if (length < 1e-9)
+            return [];
+        const [ux, uz] = [dx / length, dz / length];
+        // The wall's normal as the plan footprint takes it, so a justified wall sits where it is drawn.
+        const [nx, nz] = [-uz * offset, ux * offset];
+        return [
+            {
+                from: levelLocalToWorldXZ(building, a.x + nx - ux * reach, a.y + nz - uz * reach),
+                to: levelLocalToWorldXZ(building, b.x + nx + ux * reach, b.y + nz + uz * reach),
+            },
+        ];
+    });
+}

package/dist/lib/geometry-script-node.d.ts

@@ -20,15 +20,15 @@ export declare function withSourceMeta<S extends {
     meta?: GeometrySourceMeta;
 }>(source: S, next: object, parent?: string): S;
 /** The `source` a compile produces, the same on every kind. */
-export declare const scriptSource: (compiled: CompiledGeometryScript, meta?: object, previous?: ScriptedNode["source"]) => {
-    kind: "script";
+export declare const scriptSource: (compiled: CompiledGeometryScript, meta?: object, previous?: ScriptedNode['source']) => {
+    kind: 'script';
     meta: {
         description?: string | undefined;
         category?: string | undefined;
         tags?: string[] | undefined;
         parent?: string | undefined;
     } | undefined;
-    language: "three" | "bpy";
+    language: "bpy" | "three";
     script: string;
     params: Record<string, string | number | boolean>;
     artifact: string;
@@ -65,11 +65,40 @@ type Manifest = CompiledGeometryScript['manifest'];
 export declare function matchScriptSlotsToLibrary(manifest: Manifest, overrides?: Record<string, string>, previous?: Manifest): Record<string, string>;
 /** Width, height and depth of what the script built. */
 export declare function scriptedSize(manifest: CompiledGeometryScript['manifest']): [number, number, number];
+/**
+ * A compile whose bounds are not finite numbers cannot be sized or placed, and what is built from
+ * it would fail its schema with a raw validation array or carry a non-finite size: refused before
+ * anything is built, whichever scripted tool it came to. A mesh at a position that is not a number
+ * leaves NaN bounds (null once they crossed a JSON hop).
+ */
+export declare function requireMeasured(compiled: CompiledGeometryScript, subject: {
+    label?: string;
+    nodeId?: string;
+    tool: string;
+}): void;
 /**
  * Where the script's origin (the bottom centre of what it built) sits in the
  * node's own frame: a window or door is placed by its centre.
  */
 export declare function scriptedOrigin(node: ScriptedNode): [number, number, number];
+/**
+ * Where a ceiling item's origin sits in the ceiling's frame (y = 0 is the ceiling plane): a recessed
+ * fixture seats flush; a scripted object is origined at its top (the compiler's ceiling mount), so
+ * it hangs from its bounds' top; a catalog model is origined at its bottom and hangs its full height.
+ */
+export declare function ceilingSeatY(item: {
+    asset: {
+        recessed?: boolean;
+    };
+    source?: {
+        manifest: {
+            bounds: {
+                max: readonly number[];
+            };
+        };
+    };
+    scale?: readonly number[];
+}, height: number): number;
 /**
  * The item's controls from what the module emitted: a light switch for its
  * lights, an open/close toggle for an `open` clip (closing plays `close`, or

package/dist/lib/geometry-script-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geometry-script-node.d.ts","sourceRoot":"","sources":["../../src/lib/geometry-script-node.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAGxD,sGAAsG;AACtG,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC,GAAG;IAC3E,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAA;CACxC,CAAA;AAED,eAAO,MAAM,cAAc,GACzB,MAAM;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,KACnD,IAAI,IAAI,YAKiB,CAAA;AAE5B;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,kBAAkB,CAAA;CAAE,EACpE,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,CAAC,CAUH;AAED,+DAA+D;AAC/D,eAAO,MAAM,YAAY,GACvB,UAAU,sBAAsB,EAChC,OAAM,MAAW,EACjB,WAAW,YAAY,CAAC,QAAQ,CAAC;;;;;;;;;;;;;CAgBhC,CAAA;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY;;;;;;EASpD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GACnD;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKjD;AAED,KAAK,QAAQ,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAA;AAKlD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,EAClB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACtC,QAAQ,CAAC,EAAE,QAAQ,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYxB;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,sBAAsB,CAAC,UAAU,CAAC,GAC3C,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAG1B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAG3E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,sBAAsB,CAAC,UAAU,CAAC,EAC5C,MAAM,GAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAa,GAC3C,QAAQ,CAAC,OAAO,CAAC,CAAC,aAAa,CAAC,CA0ClC"}
+{"version":3,"file":"geometry-script-node.d.ts","sourceRoot":"","sources":["../../src/lib/geometry-script-node.ts"],"names":[],"mappings":"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"}

package/dist/lib/geometry-script-node.js

@@ -1,3 +1,4 @@
+import { refuse } from '../agent-tools/refusal.js';
 import { matchPascalMaterial } from '../procedural-items/library-colors.js';
 import { GeometrySourceMeta } from '../schema/geometry-metadata.js';
 import { artifactUrl } from './artifact-store.js';
@@ -84,6 +85,19 @@ export function scriptedSize(manifest) {
     const { min, max } = manifest.bounds;
     return [max[0] - min[0], max[1] - min[1], max[2] - min[2]];
 }
+/**
+ * A compile whose bounds are not finite numbers cannot be sized or placed, and what is built from
+ * it would fail its schema with a raw validation array or carry a non-finite size: refused before
+ * anything is built, whichever scripted tool it came to. A mesh at a position that is not a number
+ * leaves NaN bounds (null once they crossed a JSON hop).
+ */
+export function requireMeasured(compiled, subject) {
+    const { min, max } = compiled.manifest.bounds;
+    if ([...min, ...max].every(Number.isFinite))
+        return;
+    const label = subject.label ? `"${subject.label}"` : (subject.nodeId ?? 'The object');
+    refuse('unmeasurable_object', `${label} cannot be measured: its bounds are not finite numbers (min [${min.map(String).join(', ')}], max [${max.map(String).join(', ')}]) with params ${JSON.stringify(compiled.params)}. A mesh in the script has a position, rotation or scale that is not a number (a helper called one argument short passes the next value in its place). Fix the script and call ${subject.tool} again; nothing was ${subject.nodeId ? 'changed' : 'added'}.`, { label: subject.label ?? subject.nodeId });
+}
 /**
  * Where the script's origin (the bottom centre of what it built) sits in the
  * node's own frame: a window or door is placed by its centre.
@@ -93,6 +107,18 @@ export function scriptedOrigin(node) {
         return [0, 0, 0];
     return [0, -scriptedSize(node.source.manifest)[1] / 2, 0];
 }
+/**
+ * Where a ceiling item's origin sits in the ceiling's frame (y = 0 is the ceiling plane): a recessed
+ * fixture seats flush; a scripted object is origined at its top (the compiler's ceiling mount), so
+ * it hangs from its bounds' top; a catalog model is origined at its bottom and hangs its full height.
+ */
+export function ceilingSeatY(item, height) {
+    if (item.asset.recessed)
+        return 0;
+    if (item.source)
+        return -(item.source.manifest.bounds.max[1] ?? 0) * (item.scale?.[1] ?? 1);
+    return -height;
+}
 /**
  * The item's controls from what the module emitted: a light switch for its
  * lights, an open/close toggle for an `open` clip (closing plays `close`, or

package/dist/lib/grade-standing.d.ts

@@ -0,0 +1,38 @@
+import type { AnyNode, AnyNodeId, LevelNode } from '../schema/index.js';
+import { type TerrainField } from './terrain-field.js';
+/**
+ * Where a level stands against the ground as it actually lies: at grade, below it everywhere,
+ * or below it on part of its footprint — a hillside can bury half a floor whose other half
+ * walks out. `isLevelBelowGrade` alone only knows the flat datum, so a street raised 6 m over
+ * a garden level left every floor "at grade" and the ground never veiled.
+ */
+export type LevelGradeStanding = 'at-grade' | 'partly-below-grade' | 'below-grade';
+/**
+ * `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 declare function levelGradeStanding(nodes: Record<AnyNodeId, AnyNode>, levelId: string): LevelGradeStanding;
+/** Whether a floor at world Y `floorY` lies under a flat site's datum by more than the tolerance. */
+export declare function floorBuriedOnFlatSite(floorY: number): boolean;
+/** The site's terrain field for the site this level stands on, or null on a flat site. */
+export declare function terrainFieldOverLevel(nodes: Record<AnyNodeId, AnyNode>, level: LevelNode): TerrainField | 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 declare function footprintSamples(nodes: Record<AnyNodeId, AnyNode>, level: LevelNode, field: TerrainField): Array<[number, number]>;
+/**
+ * {@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 declare function footprintFloorSamples(nodes: Record<AnyNodeId, AnyNode>, level: LevelNode, field: TerrainField): Array<[number, number, number]>;
+//# sourceMappingURL=grade-standing.d.ts.map

package/dist/lib/grade-standing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grade-standing.d.ts","sourceRoot":"","sources":["../../src/lib/grade-standing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAgB,SAAS,EAAY,MAAM,WAAW,CAAA;AAUtF,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAI7D;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,oBAAoB,GAAG,aAAa,CAAA;AAKlF;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,MAAM,GACd,kBAAkB,CAuBpB;AAsBD,qGAAqG;AACrG,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE7D;AAcD,0FAA0F;AAC1F,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,SAAS,GACf,YAAY,GAAG,IAAI,CAOrB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,YAAY,GAClB,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAEzB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,YAAY,GAClB,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAcjC"}