@pascal-app/core 1.0.3 → 1.0.5

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

@@ -0,0 +1,173 @@
+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';
+export const isScriptedNode = (node) => Boolean(node?.source) &&
+    (node.type === 'item' ||
+        node.type === 'window' ||
+        node.type === 'door' ||
+        node.type === 'column');
+/**
+ * Merges reuse metadata into a source's, dropping `meta` when nothing is left:
+ * the scene carries no empty object.
+ */
+export function withSourceMeta(source, next, parent) {
+    const { meta: previous, ...rest } = source;
+    const meta = GeometrySourceMeta.parse({
+        ...previous,
+        ...Object.fromEntries(Object.entries(GeometrySourceMeta.parse(next)).filter(([, value]) => value !== undefined)),
+        ...(parent ? { parent } : {}),
+    });
+    return (Object.keys(meta).length > 0 ? { ...rest, meta } : rest);
+}
+/** The `source` a compile produces, the same on every kind. */
+export const scriptSource = (compiled, meta = {}, previous) => withSourceMeta({
+    kind: 'script',
+    meta: previous?.meta,
+    language: compiled.language,
+    script: compiled.script,
+    params: compiled.params,
+    artifact: compiled.sha256,
+    // Worker structured clones retain optional undefined fields; durable scene writes are JSON.
+    manifest: JSON.parse(JSON.stringify(compiled.manifest)),
+}, meta, 
+// A params-only rebuild runs the same script: its lineage stays where it was.
+previous && previous.script !== compiled.script ? previous.script : undefined);
+/**
+ * What a scripted object is, for reuse, whatever its kind: the name from the
+ * node, an item's category from its asset, the rest from `source.meta`.
+ */
+export function scriptedObjectMeta(node) {
+    const { description, category, tags, parent } = node.source.meta ?? {};
+    return {
+        name: node.name,
+        description,
+        category: node.type === 'item' ? node.asset.category : category,
+        tags,
+        parent,
+    };
+}
+/**
+ * A scripted node's thumbnail and floor-plan image as `artifact://` URLs, or
+ * null until an editor has taken them of the GLB the node shows now.
+ */
+export function scriptImages(node) {
+    if (!isScriptedNode(node))
+        return null;
+    const { images, artifact } = node.source;
+    if (images?.artifact !== artifact)
+        return null;
+    return { thumbnail: artifactUrl(images.thumbnail), floorPlan: artifactUrl(images.floorPlan) };
+}
+const matchSlot = (slot) => matchPascalMaterial({ ...slot, name: `${slot.id} ${slot.label ?? ''}` });
+/**
+ * Paint and automatic matching write the same overrides. A rebuild keeps every
+ * pick, but a slot still holding what the previous build matched is matched
+ * again, so a script edit to that finish shows.
+ */
+export function matchScriptSlotsToLibrary(manifest, overrides = {}, previous) {
+    const slots = { ...overrides };
+    for (const slot of manifest.slots) {
+        if (Object.hasOwn(overrides, slot.id)) {
+            const before = previous?.slots.find((candidate) => candidate.id === slot.id);
+            if (!before || overrides[slot.id] !== matchSlot(before))
+                continue;
+            delete slots[slot.id];
+        }
+        const ref = matchSlot(slot);
+        if (ref)
+            slots[slot.id] = ref;
+    }
+    return slots;
+}
+/** Width, height and depth of what the script built. */
+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.
+ */
+export function scriptedOrigin(node) {
+    if (node.type !== 'window' && node.type !== 'door')
+        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
+ * `open` reversed), a `loop` clip that runs throughout, and a play toggle per
+ * other clip, labelled with its name. Light offsets are in the node's frame,
+ * `origin` being where the script's origin sits in it (`scriptedOrigin`).
+ */
+export function scriptInteractive(manifest, origin = [0, 0, 0]) {
+    const controls = [];
+    const effects = [];
+    if (manifest.lights.length > 0) {
+        controls.push({ kind: 'toggle', label: 'Lights', default: true });
+        for (const light of manifest.lights) {
+            effects.push({
+                kind: 'light',
+                color: light.color,
+                intensityRange: [0, light.intensity],
+                distance: light.distance,
+                offset: [
+                    light.position[0] + origin[0],
+                    light.position[1] + origin[1],
+                    light.position[2] + origin[2],
+                ],
+            });
+        }
+    }
+    const clip = (name) => manifest.animations.some((animation) => animation.name === name);
+    if (clip('open')) {
+        effects.push({
+            kind: 'animation',
+            mode: 'open-close',
+            control: controls.length,
+            clips: { on: 'open', off: clip('close') ? 'close' : undefined },
+        });
+        controls.push({ kind: 'toggle', label: 'Open', default: false });
+    }
+    if (clip('loop'))
+        effects.push({ kind: 'animation', mode: 'ambient', clips: { loop: 'loop' } });
+    // Every other clip gets its own play toggle, labelled with its name.
+    for (const { name } of manifest.animations) {
+        if (name === 'open' || name === 'close' || name === 'loop')
+            continue;
+        effects.push({
+            kind: 'animation',
+            mode: 'ambient',
+            control: controls.length,
+            clips: { on: name },
+        });
+        controls.push({ kind: 'toggle', label: name, default: false });
+    }
+    return effects.length > 0 ? { controls, effects } : undefined;
+}

package/dist/lib/geometry-surfaces.d.ts

@@ -0,0 +1,61 @@
+import type { GeometryArtifactManifest } from '../schema/geometry-source.js';
+type Surface = GeometryArtifactManifest['surfaces'][number];
+type Manifest = Pick<GeometryArtifactManifest, 'surfaces' | 'parts'>;
+/**
+ * Where something dropped at local (x, z) comes to rest on an authored
+ * object: its main surface when the point is over it (a bench anywhere on a
+ * porch lands on the landing, not on the beam), otherwise the highest
+ * non-roof surface under the point. `maxY` caps the search. Null when
+ * nothing is under the point.
+ */
+export declare function geometrySurfaceAt(manifest: Manifest & Pick<GeometryArtifactManifest, 'bounds'>, x: number, z: number, maxY?: number): Surface | null;
+/**
+ * The one height an authored object offers as "where things rest" (the
+ * item's `asset.surface`): its highest main surface, so a porch rests things
+ * on its landing and a table on its top. Null when it has none.
+ */
+export declare function geometryRestingHeight(manifest: Manifest & Pick<GeometryArtifactManifest, 'bounds'>): number | null;
+/**
+ * Where a ceiling item hangs from an authored object above local (x, z): the
+ * lowest underside over the point (a beam before the vault plane above it),
+ * with its height there — sloped undersides included. Null when none is over it.
+ */
+export declare function geometryUndersideAt(manifest: Pick<GeometryArtifactManifest, 'undersides'>, x: number, z: number): {
+    part?: string;
+    y: number;
+    normal: [number, number, number];
+} | null;
+/**
+ * The rotation that seats a flush fixture (a recessed can) on a sloped
+ * underside: its +Y goes into the surface, against the downward `normal`,
+ * then it keeps its own turn `yaw`. Euler XYZ, as items store rotation.
+ */
+export declare function flushMountRotation(normal: readonly [number, number, number], yaw: number): [number, number, number];
+/**
+ * Whether a ceiling fixture sits flush on a surface (tilting with a slope)
+ * rather than hanging plumb: flagged `recessed`, or shallow enough that it
+ * can only be a can or a surface light (catalog data often lacks the flag).
+ */
+export declare function mountsFlush(asset: {
+    recessed?: boolean;
+    dimensions?: readonly number[];
+}): boolean;
+/** The closest point to (x, z) inside a convex outline (itself when inside). */
+export declare function nearestPointIn(polygon: readonly [number, number][], x: number, z: number): [number, number];
+/**
+ * Where a child item of an authored object sits after the object is rebuilt:
+ * a resting item back on the surface under it (moved onto the main surface
+ * when that shrank away from it), a hanging one from the underside above it.
+ * Positions are in the object's frame; `scale` is the object's. Null when
+ * nothing applies (wall-mounted children, objects without surfaces).
+ */
+export declare function resettledPosition(manifest: Pick<GeometryArtifactManifest, 'surfaces' | 'undersides' | 'parts' | 'bounds'>, child: {
+    position: readonly [number, number, number];
+    asset: {
+        attachTo?: string;
+        recessed?: boolean;
+        dimensions?: readonly number[];
+    };
+}, scale: readonly [number, number, number]): [number, number, number] | null;
+export {};
+//# sourceMappingURL=geometry-surfaces.d.ts.map

package/dist/lib/geometry-surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry-surfaces.d.ts","sourceRoot":"","sources":["../../src/lib/geometry-surfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AAEzE,KAAK,OAAO,GAAG,wBAAwB,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAC3D,KAAK,QAAQ,GAAG,IAAI,CAAC,wBAAwB,EAAE,UAAU,GAAG,OAAO,CAAC,CAAA;AAyCpE;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC,wBAAwB,EAAE,QAAQ,CAAC,EAC7D,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,SAA2B,GAC9B,OAAO,GAAG,IAAI,CAMhB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC,wBAAwB,EAAE,QAAQ,CAAC,GAC5D,MAAM,GAAG,IAAI,CAEf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,IAAI,CAAC,wBAAwB,EAAE,YAAY,CAAC,EACtD,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CASvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACzC,GAAG,EAAE,MAAM,GACV,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAoB1B;AAKD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC/B,GAAG,OAAO,CAEV;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EACpC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBlB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,IAAI,CAAC,wBAAwB,EAAE,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,CAAC,EACxF,KAAK,EAAE;IACL,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAA;CACjF,EACD,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GACvC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAiBjC"}

package/dist/lib/geometry-surfaces.js

@@ -0,0 +1,156 @@
+/** Part types whose tops shelter rather than hold: nothing is placed on a porch roof. */
+const SHELTER_TYPES = new Set(['roof', 'canopy', 'awning', 'ceiling']);
+function receives(manifest, surface) {
+    if (!surface.part)
+        return true;
+    const type = manifest.parts.find((part) => part.id === surface.part)?.type;
+    return !(type && SHELTER_TYPES.has(type));
+}
+function contains(polygon, x, z) {
+    let inside = false;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+        const [xi, zi] = polygon[i];
+        const [xj, zj] = polygon[j];
+        if (zi > z !== zj > z && x < ((xj - xi) * (z - zi)) / (zj - zi) + xi)
+            inside = !inside;
+    }
+    return inside;
+}
+function area(polygon) {
+    let sum = 0;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+        sum += (polygon[j][0] + polygon[i][0]) * (polygon[j][1] - polygon[i][1]);
+    }
+    return Math.abs(sum) / 2;
+}
+/** Non-roof surfaces covering at least half the object's footprint: its landing, its top. */
+function mainSurfaces(manifest) {
+    const { min, max } = manifest.bounds;
+    const footprint = (max[0] - min[0]) * (max[2] - min[2]);
+    return manifest.surfaces.filter((surface) => receives(manifest, surface) && area(surface.polygon) >= footprint / 2);
+}
+const highest = (surfaces) => surfaces.reduce((best, s) => (!best || s.y > best.y ? s : best), null);
+/**
+ * Where something dropped at local (x, z) comes to rest on an authored
+ * object: its main surface when the point is over it (a bench anywhere on a
+ * porch lands on the landing, not on the beam), otherwise the highest
+ * non-roof surface under the point. `maxY` caps the search. Null when
+ * nothing is under the point.
+ */
+export function geometrySurfaceAt(manifest, x, z, maxY = Number.POSITIVE_INFINITY) {
+    const under = (surface) => surface.y <= maxY && contains(surface.polygon, x, z);
+    return (highest(mainSurfaces(manifest).filter(under)) ??
+        highest(manifest.surfaces.filter((s) => receives(manifest, s) && under(s))));
+}
+/**
+ * The one height an authored object offers as "where things rest" (the
+ * item's `asset.surface`): its highest main surface, so a porch rests things
+ * on its landing and a table on its top. Null when it has none.
+ */
+export function geometryRestingHeight(manifest) {
+    return highest(mainSurfaces(manifest))?.y ?? null;
+}
+/**
+ * Where a ceiling item hangs from an authored object above local (x, z): the
+ * lowest underside over the point (a beam before the vault plane above it),
+ * with its height there — sloped undersides included. Null when none is over it.
+ */
+export function geometryUndersideAt(manifest, x, z) {
+    let best = null;
+    for (const underside of manifest.undersides) {
+        const [a, b, c, d] = underside.plane;
+        if (b === 0 || !contains(underside.polygon, x, z))
+            continue;
+        const y = -(a * x + c * z + d) / b;
+        if (!best || y < best.y)
+            best = { part: underside.part, y, normal: [a, b, c] };
+    }
+    return best;
+}
+/**
+ * The rotation that seats a flush fixture (a recessed can) on a sloped
+ * underside: its +Y goes into the surface, against the downward `normal`,
+ * then it keeps its own turn `yaw`. Euler XYZ, as items store rotation.
+ */
+export function flushMountRotation(normal, yaw) {
+    // Quaternion turning +Y onto -normal (the direction into the surface).
+    const [vx, vy, vz] = [-normal[0], -normal[1], -normal[2]];
+    let [qx, qy, qz, qw] = [vz, 0, -vx, 1 + vy];
+    const length = Math.hypot(qx, qy, qz, qw) || 1;
+    [qx, qy, qz, qw] = [qx / length, qy / length, qz / length, qw / length];
+    // Then the fixture's own yaw about its local +Y.
+    const [sy, cy] = [Math.sin(yaw / 2), Math.cos(yaw / 2)];
+    const [x, y, z, w] = [qx * cy - qz * sy, qw * sy + qy * cy, qz * cy + qx * sy, qw * cy - qy * sy];
+    const m11 = 1 - 2 * (y * y + z * z);
+    const m12 = 2 * (x * y - w * z);
+    const m13 = 2 * (x * z + w * y);
+    const m22 = 1 - 2 * (x * x + z * z);
+    const m23 = 2 * (y * z - w * x);
+    const m32 = 2 * (y * z + w * x);
+    const m33 = 1 - 2 * (x * x + y * y);
+    const ry = Math.asin(Math.max(-1, Math.min(1, m13)));
+    return Math.abs(m13) < 0.9999999
+        ? [Math.atan2(-m23, m33), ry, Math.atan2(-m12, m11)]
+        : [Math.atan2(m32, m22), ry, 0];
+}
+/** At or under this height a ceiling fixture mounts flush (a can, a surface light) rather than hangs. */
+const FLUSH_MOUNT_MAX_HEIGHT = 0.15;
+/**
+ * Whether a ceiling fixture sits flush on a surface (tilting with a slope)
+ * rather than hanging plumb: flagged `recessed`, or shallow enough that it
+ * can only be a can or a surface light (catalog data often lacks the flag).
+ */
+export function mountsFlush(asset) {
+    return Boolean(asset.recessed) || (asset.dimensions?.[1] ?? 1) <= FLUSH_MOUNT_MAX_HEIGHT;
+}
+/** The closest point to (x, z) inside a convex outline (itself when inside). */
+export function nearestPointIn(polygon, x, z) {
+    if (contains(polygon, x, z))
+        return [x, z];
+    let best = [x, z];
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+        const [ax, az] = polygon[j];
+        const [bx, bz] = polygon[i];
+        const dx = bx - ax;
+        const dz = bz - az;
+        const t = Math.max(0, Math.min(1, ((x - ax) * dx + (z - az) * dz) / (dx * dx + dz * dz || 1)));
+        const px = ax + t * dx;
+        const pz = az + t * dz;
+        const distance = Math.hypot(px - x, pz - z);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = [px, pz];
+        }
+    }
+    return best;
+}
+/**
+ * Where a child item of an authored object sits after the object is rebuilt:
+ * a resting item back on the surface under it (moved onto the main surface
+ * when that shrank away from it), a hanging one from the underside above it.
+ * Positions are in the object's frame; `scale` is the object's. Null when
+ * nothing applies (wall-mounted children, objects without surfaces).
+ */
+export function resettledPosition(manifest, child, scale) {
+    const [sx, sy, sz] = scale;
+    const x = child.position[0] / sx;
+    const z = child.position[2] / sz;
+    if (child.asset.attachTo === 'ceiling') {
+        const underside = geometryUndersideAt(manifest, x, z);
+        if (!underside)
+            return null;
+        const drop = mountsFlush(child.asset) ? 0.02 : (child.asset.dimensions?.[1] ?? 0);
+        return [child.position[0], underside.y * sy - drop, child.position[2]];
+    }
+    if (child.asset.attachTo)
+        return null;
+    const surface = geometrySurfaceAt(manifest, x, z);
+    if (surface)
+        return [child.position[0], surface.y * sy, child.position[2]];
+    const main = mainSurfaces(manifest).sort((a, b) => b.y - a.y)[0];
+    if (!main)
+        return null;
+    const [nx, nz] = nearestPointIn(main.polygon, x, z);
+    return [nx * sx, main.y * sy, nz * sz];
+}

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"}

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;
+}