@pascal-app/core 1.0.5 → 1.0.7

package/dist/spatial/usage-field/fixtures.js

@@ -0,0 +1,160 @@
+import { isFloorUnderlay } from '../../agent-operations/furniture-kind.js';
+import { CODE_PROFILES, codeProfileOf, } from '../../building/code-profile.js';
+import { catalogueKey } from './catalogue.js';
+import { m, nameOf, quote, unique } from './labels.js';
+import { obstaclesInBand, rayHit } from './obstacles.js';
+import { roomAt } from './pieces.js';
+const TOILET = /toilet|water ?closet|(?:^|[^a-z])wc(?![a-z])/i;
+const BASIN = /basin|lavatory|vanity|bathroom[- ]sink|wash ?hand/i;
+const BASIN_WORD = /basin|lavatory|vanity|sink|wash ?hand/i;
+const SHOWER = /shower/i;
+/** The feet band: what a person's legs and a fixture's rim meet (m above the floor). */
+const BAND = { from: 0.05, to: 0.9 };
+const RAY_MAX_M = 1.5;
+/** Where along a fixture's depth, from its back, the sides are read. */
+const SIDE_SAMPLES = [0.25, 0.5, 0.75, 1];
+/** A lavatory this wide has more than one basin: its centre line is not a basin's. */
+const SINGLE_BASIN_MAX_M = 1.0;
+const kindOf = (item) => {
+    const text = `${item.name ?? ''} ${item.asset.name ?? ''} ${item.asset.id ?? ''} ${item.asset.category ?? ''}`;
+    const key = catalogueKey(item.asset.src ?? '');
+    if (key === 'system/toilet' || (TOILET.test(text) && !BASIN_WORD.test(text)))
+        return 'toilet';
+    if (key === 'system/shower-square' || SHOWER.test(text))
+        return 'shower';
+    if (key === 'system/bathroom-sink' || (BASIN.test(text) && !/kitchen/i.test(text)))
+        return 'lavatory';
+    return null;
+};
+const inchesText = (metres) => `${Math.round(metres / 0.0254)} in`;
+/**
+ * Bathroom fixture clearances: a toilet's centre to the nearest obstruction on each side and its clear
+ * space in front, a lavatory's front (and, for a single basin, its side), a shower's clear space at its
+ * best open side. Read on the exact outlines of the feet band. The fixture's front is its +Z, checked
+ * against the wall behind it (a fixture whose back is free and whose +Z meets a wall is read the other
+ * way round); a shower has no opening side in the model, so the best of its four sides is read, which is
+ * as good as the opening can be.
+ *
+ * These are a code's numbers. With no `site.metadata.codeProfile` the scene has no jurisdiction, and a
+ * finding is information that names the US IRC it used; with `irc-2021` set it is a warning. A profile
+ * with no row for it (the Australian NCC, France hold none of the bathroom figures) reports nothing.
+ * Approximate fixture outlines remain labeled as such without downgrading a clearance defect.
+ */
+export function fixtureClearanceIssues(nodes, shapes) {
+    const profile = codeProfileOf(nodes);
+    const applied = profile ?? CODE_PROFILES['irc-2021'];
+    if (Object.keys(applied.thresholds).length === 0)
+        return [];
+    const out = [];
+    for (const level of shapes.levels) {
+        const prisms = level.prisms.filter((prism) => !(nodes[prism.nodeId]?.type === 'item' && isFloorUnderlay(nodes[prism.nodeId])));
+        for (const item of Object.values(nodes)) {
+            if (item.type !== 'item' || item.visible === false || item.parentId !== level.levelId)
+                continue;
+            const kind = kindOf(item);
+            if (!kind)
+                continue;
+            const own = prisms.filter((p) => p.nodeId === item.id);
+            if (!own.length)
+                continue;
+            const approximate = own.some((p) => p.shape === 'approx');
+            // the feet band stands on the fixture's own floor: a floor plate set off its storey's base is the fixture's floor
+            const floorY = Math.min(...own.map((p) => p.z0));
+            const band = { z0: floorY + BAND.from, z1: floorY + BAND.to };
+            const yaw = item.rotation?.[1] ?? 0;
+            const f = [Math.sin(yaw), Math.cos(yaw)];
+            const r = [Math.cos(yaw), -Math.sin(yaw)];
+            const points = own.flatMap((p) => p.outer);
+            const project = (u) => points.map((p) => p[0] * u[0] + p[1] * u[1]);
+            const [r0, r1] = [Math.min(...project(r)), Math.max(...project(r))];
+            const [f0, f1] = [Math.min(...project(f)), Math.max(...project(f))];
+            const at = (ur, uf) => [r[0] * ur + f[0] * uf, r[1] * ur + f[1] * uf];
+            const obstacles = obstaclesInBand(prisms, band, undefined, (p) => {
+                if (p.nodeId === item.id || p.kind === 'treatment')
+                    return true;
+                const owner = nodes[p.nodeId];
+                return owner?.type === 'item' && owner.parentId === item.id;
+            });
+            const middle = (r0 + r1) / 2;
+            const depth = f1 - f0;
+            const behind = rayHit(at(middle, f0 - 0.001), [-f[0], -f[1]], obstacles, 0.4);
+            const ahead = rayHit(at(middle, f1 + 0.001), f, obstacles, 0.4);
+            const turned = behind > ahead + 0.05 && ahead < 0.15;
+            const front = turned ? [-f[0], -f[1]] : f;
+            const edge = turned ? f0 - 0.001 : f1 + 0.001;
+            const measures = [];
+            if (kind === 'shower') {
+                let best = 0;
+                for (const [dir, e, u0, u1, across] of [
+                    [f, f1 + 0.001, r0, r1, true],
+                    [[-f[0], -f[1]], f0 - 0.001, r0, r1, true],
+                    [r, r1 + 0.001, f0, f1, false],
+                    [[-r[0], -r[1]], r0 - 0.001, f0, f1, false],
+                ]) {
+                    const clear = Math.min(...[0.25, 0.5, 0.75].map((s) => {
+                        const u = u0 + (u1 - u0) * s;
+                        return rayHit(across ? at(u, e) : at(e, u), dir, obstacles, RAY_MAX_M);
+                    }));
+                    best = Math.max(best, clear);
+                }
+                measures.push({
+                    id: 'showerFrontClear',
+                    label: 'in front of its best open side',
+                    value: best,
+                });
+            }
+            else {
+                const front0 = [-0.25, -0.125, 0, 0.125, 0.25].map((o) => rayHit(at(middle + o, edge), front, obstacles, RAY_MAX_M));
+                measures.push({
+                    id: kind === 'toilet' ? 'toiletFrontClear' : 'lavatoryFrontClear',
+                    label: 'in front',
+                    value: Math.min(...front0),
+                });
+                if (kind === 'toilet' || r1 - r0 <= SINGLE_BASIN_MAX_M) {
+                    let side = Number.POSITIVE_INFINITY;
+                    // not along the back edge: a ray grazing the wall behind the fixture is not a side obstruction
+                    for (const sign of [-1, 1])
+                        for (const share of SIDE_SAMPLES)
+                            side = Math.min(side, (r1 - r0) / 2 +
+                                rayHit(at(sign > 0 ? r1 + 0.001 : r0 - 0.001, f0 + depth * share), [r[0] * sign, r[1] * sign], obstacles, 0.6));
+                    measures.push({
+                        id: kind === 'toilet' ? 'toiletSideClear' : 'lavatorySideClear',
+                        label: 'from its centre to the nearest obstruction at the side',
+                        value: side,
+                    });
+                }
+            }
+            const room = roomAt(nodes, level.levelId, at(middle, (f0 + f1) / 2));
+            const name = nameOf(nodes, item.id);
+            for (const { id, label, value } of measures) {
+                const row = applied.thresholds[id];
+                if (!row || !(value < row.value - 0.005))
+                    continue;
+                const secondary = row.source === 'secondary source';
+                const best = id === 'showerFrontClear';
+                out.push({
+                    type: 'usage_fixture_clearance',
+                    message: `${quote(name)}${room ? ` in ${quote(room.name)}` : ''} has ${m(value)} m ${label}${best ? ', the best of its four sides (the model has no opening side)' : ''}; ${applied.label} (${row.section}${secondary ? ', secondary source' : ''}) asks ${m(row.value)} m (${inchesText(row.value)})${profile ? '' : ', and this project names no code'}.`,
+                    severity: profile ? 'warning' : 'info',
+                    nodeIds: unique([room?.id, item.id]),
+                    valueM: Math.round(value * 1000) / 1000,
+                    thresholdM: row.value,
+                    place: {
+                        room: room?.name ?? '',
+                        roomId: room?.id ?? level.levelId,
+                        at: at(middle, (f0 + f1) / 2),
+                    },
+                    obstacles: [],
+                    approximate,
+                    code: {
+                        profile: applied.id,
+                        cite: row.cite,
+                        source: row.source,
+                        byDefault: profile === null,
+                    },
+                });
+            }
+        }
+    }
+    return out;
+}

package/dist/spatial/usage-field/flag.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Usage checks (passages, turning circles, pockets, wall objects, measured flow) are off until a
+ * host turns them on. Core reads no environment: the app and the servers set this once at start,
+ * from `PASCAL_SDF_CHECKS`.
+ */
+export declare function setSdfChecks(on: boolean): void;
+export declare const sdfChecksOn: () => boolean;
+/** What `PASCAL_SDF_CHECKS` (or its `NEXT_PUBLIC_` mirror) says: `1` or `true` turns the checks on, anything else, or nothing, leaves them off. */
+export declare const sdfChecksFromEnv: (value: string | undefined) => boolean;
+//# sourceMappingURL=flag.d.ts.map

package/dist/spatial/usage-field/flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flag.d.ts","sourceRoot":"","sources":["../../../src/spatial/usage-field/flag.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAE9C;AAED,eAAO,MAAM,WAAW,QAAO,OAAkB,CAAA;AAEjD,mJAAmJ;AACnJ,eAAO,MAAM,gBAAgB,UAAW,MAAM,GAAG,SAAS,KAAG,OACX,CAAA"}

package/dist/spatial/usage-field/flag.js

@@ -0,0 +1,12 @@
+let enabled = false;
+/**
+ * Usage checks (passages, turning circles, pockets, wall objects, measured flow) are off until a
+ * host turns them on. Core reads no environment: the app and the servers set this once at start,
+ * from `PASCAL_SDF_CHECKS`.
+ */
+export function setSdfChecks(on) {
+    enabled = on;
+}
+export const sdfChecksOn = () => enabled;
+/** What `PASCAL_SDF_CHECKS` (or its `NEXT_PUBLIC_` mirror) says: `1` or `true` turns the checks on, anything else, or nothing, leaves them off. */
+export const sdfChecksFromEnv = (value) => value === '1' || value?.toLowerCase() === 'true';

package/dist/spatial/usage-field/floors.d.ts

@@ -0,0 +1,13 @@
+import type { FloorRegion, Skipped } from './types.js';
+import type { Nodes } from './walls.js';
+/**
+ * The floor a person stands on, level by level: each slab's walking surface less the floor openings
+ * and lift shafts cut through it, at the height the circulation graph reads (`floorsOf`), so the
+ * usage checks and the circulation report stand on the same floor. A slab draped over terrain is one
+ * flat height here and is marked approximate; a recessed slab (a pool) is not a floor.
+ */
+export declare function levelFloors(nodes: Nodes): {
+    floors: Map<string, FloorRegion[]>;
+    skipped: Skipped[];
+};
+//# sourceMappingURL=floors.d.ts.map

package/dist/spatial/usage-field/floors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"floors.d.ts","sourceRoot":"","sources":["../../../src/spatial/usage-field/floors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG;IACzC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAA;IAClC,OAAO,EAAE,OAAO,EAAE,CAAA;CACnB,CA2BA"}

package/dist/spatial/usage-field/floors.js

@@ -0,0 +1,36 @@
+import { floorsOf } from '../../agent-operations/circulation-spaces.js';
+import { difference } from '../../lib/polygon-boolean.js';
+/**
+ * The floor a person stands on, level by level: each slab's walking surface less the floor openings
+ * and lift shafts cut through it, at the height the circulation graph reads (`floorsOf`), so the
+ * usage checks and the circulation report stand on the same floor. A slab draped over terrain is one
+ * flat height here and is marked approximate; a recessed slab (a pool) is not a floor.
+ */
+export function levelFloors(nodes) {
+    const floors = new Map();
+    const skipped = [];
+    for (const floor of floorsOf(nodes).floors) {
+        const cuts = [...floor.voids, ...floor.shafts].map((ring) => ({ outer: ring, holes: [] }));
+        const regions = [];
+        for (const slab of floor.slabs) {
+            const source = nodes[slab.id];
+            if (source?.type === 'slab' && source.recessed) {
+                skipped.push({ nodeId: slab.id, why: 'a recessed slab is not a floor to stand on' });
+                continue;
+            }
+            const pieces = difference({ outer: slab.polygon, holes: slab.holes }, cuts);
+            for (const [index, piece] of pieces.entries())
+                regions.push({
+                    id: `${slab.id}#floor${pieces.length > 1 ? `.${index}` : ''}`,
+                    nodeId: slab.id,
+                    outer: piece.outer,
+                    holes: piece.holes,
+                    y: slab.elevation,
+                    outdoor: slab.outdoor,
+                    shape: 'exact',
+                });
+        }
+        floors.set(floor.id, regions);
+    }
+    return { floors, skipped };
+}

package/dist/spatial/usage-field/index.d.ts

@@ -0,0 +1,7 @@
+export { catalogueKey } from './catalogue.js';
+export { type UsageIssue, usageIssues } from './findings.js';
+export { sdfChecksFromEnv, sdfChecksOn, setSdfChecks } from './flag.js';
+export { measureUsage, type UsageMeasure } from './measure.js';
+export { usageShapes } from './shapes.js';
+export type { FloorRegion, LevelShapes, Prism, PrismKind, Skipped, UsageShapes } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/spatial/usage-field/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spatial/usage-field/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,KAAK,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACzD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AACpE,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAA;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AACtC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA"}

package/dist/spatial/usage-field/index.js

@@ -0,0 +1,5 @@
+export { catalogueKey } from './catalogue.js';
+export { usageIssues } from './findings.js';
+export { sdfChecksFromEnv, sdfChecksOn, setSdfChecks } from './flag.js';
+export { measureUsage } from './measure.js';
+export { usageShapes } from './shapes.js';

package/dist/spatial/usage-field/items.d.ts

@@ -0,0 +1,38 @@
+import type { AnyNode, ItemNode } from '../../schema/index.js';
+import { getLevelElevations } from '../../services/storey.js';
+import { type SupportCache } from './support.js';
+import type { Prism, Skipped } from './types.js';
+import type { Nodes } from './walls.js';
+/** A stored shape no looser than this is read as the build's own outline. */
+export declare const EXACT_SHAPE_TOLERANCE_M = 0.02;
+export type ItemShapes = {
+    itemId: string;
+    levelId: string | null;
+    prisms: Prism[];
+};
+export type ItemContext = {
+    nodes: Nodes;
+    byId: Map<string, AnyNode>;
+    elevations: ReturnType<typeof getLevelElevations>;
+    supportCache: SupportCache;
+};
+export declare const itemContext: (nodes: Nodes) => ItemContext;
+/** One item as prisms in absolute building metres; or `unshaped` with what it is hosted by, or `skipped` with why. */
+export declare function itemShapesOf(item: ItemNode, { nodes, byId, elevations, supportCache }: ItemContext): {
+    shapes: ItemShapes;
+} | {
+    unshaped: string;
+} | {
+    skipped: Skipped;
+};
+/**
+ * Every item as prisms in absolute building metres, filed under its level. An item stands on the
+ * floor under it, on the item that hosts it, or on a wall; one hosted by a ceiling, a roof or a block
+ * is counted in `unshaped`. Its outline is its script's stored shape when it has one, else a box.
+ */
+export declare function itemBodies(nodes: Nodes): {
+    items: ItemShapes[];
+    skipped: Skipped[];
+    unshaped: Record<string, number>;
+};
+//# sourceMappingURL=items.d.ts.map

package/dist/spatial/usage-field/items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"items.d.ts","sourceRoot":"","sources":["../../../src/spatial/usage-field/items.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAiB,QAAQ,EAAY,MAAM,cAAc,CAAA;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAQ1D,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,WAAW,CAAA;AACnE,OAAO,KAAK,EAAE,KAAK,EAAQ,OAAO,EAAE,MAAM,SAAS,CAAA;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAKpC,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,OAAO,CAAA;AAG3C,MAAM,MAAM,UAAU,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,CAAA;AAuLpF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,KAAK,CAAA;IACZ,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC1B,UAAU,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAA;IACjD,YAAY,EAAE,YAAY,CAAA;CAC3B,CAAA;AAED,eAAO,MAAM,WAAW,UAAW,KAAK,KAAG,WAKzC,CAAA;AAEF,sHAAsH;AACtH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,QAAQ,EACd,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,EAAE,WAAW,GACrD;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CA8DtE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG;IACxC,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,OAAO,EAAE,OAAO,EAAE,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC,CAaA"}

package/dist/spatial/usage-field/items.js

@@ -0,0 +1,261 @@
+import { itemLevelPose } from '../../agent-operations/item-space.js';
+import { resolveLevelId } from '../../lib/node-ancestry.js';
+import { wallSupportForNodes } from '../../lib/opening-floor-datum.js';
+import { getScaledDimensions } from '../../schema/nodes/item.js';
+import { getLevelElevations } from '../../services/storey.js';
+import { getWallCurveFrameAt, getWallCurveLength, isCurvedWall, } from '../../systems/wall/wall-curve.js';
+import { getWallBodyCenterOffset, getWallLocalFaceZ } from '../../systems/wall/wall-frame.js';
+import { catalogueShape } from './catalogue.js';
+import { floorUnder, isHidden } from './support.js';
+/** A stored shape no looser than this is read as the build's own outline. */
+export const EXACT_SHAPE_TOLERANCE_M = 0.02;
+const ROTATION_EPSILON = 1e-9;
+const rectangle = (x0, z0, x1, z1) => [
+    [x0, z0],
+    [x1, z0],
+    [x1, z1],
+    [x0, z1],
+];
+function boxBand(min, max) {
+    return {
+        y0: min[1],
+        y1: max[1],
+        polygons: [{ outer: rectangle(min[0], min[2], max[0], max[2]) }],
+    };
+}
+/**
+ * What an item occupies in its own frame. A script compiled with usage checks on carries the
+ * outline it traced from its meshes; one compiled before has only its parts' and its bounds, which
+ * are drawn as boxes and marked approximate; a library model has the outline baked from its GLB, and
+ * one without is its box.
+ */
+function localShape(item) {
+    const manifest = item.source?.manifest;
+    if (manifest?.shape) {
+        const coarse = manifest.shape.tolerance > EXACT_SHAPE_TOLERANCE_M;
+        return {
+            bands: manifest.shape.bands,
+            frame: 'artifact',
+            shape: coarse ? 'approx' : 'exact',
+            ...(coarse ? { why: 'a script outline simplified to fit its manifest' } : {}),
+        };
+    }
+    if (manifest) {
+        const parts = manifest.parts.filter((part) => part.bounds);
+        if (parts.length >= 2)
+            return {
+                bands: parts.map((part) => boxBand(part.bounds.min, part.bounds.max)),
+                frame: 'artifact',
+                shape: 'approx',
+                why: 'a script compiled without a usage outline: its parts as boxes',
+            };
+        return {
+            bands: [boxBand(manifest.bounds.min, manifest.bounds.max)],
+            frame: 'artifact',
+            shape: 'approx',
+            why: 'a script compiled without a usage outline: its bounds box',
+        };
+    }
+    const baked = catalogueShape(item.asset.src);
+    if (baked) {
+        const coarse = baked.tolerance > EXACT_SHAPE_TOLERANCE_M;
+        return {
+            bands: baked.bands,
+            frame: 'artifact',
+            shape: coarse ? 'approx' : 'exact',
+            ...(coarse ? { why: 'a library model outlined to within a few centimetres' } : {}),
+        };
+    }
+    const [w, h, d] = item.asset.dimensions;
+    return {
+        bands: [boxBand([-w / 2, 0, -d / 2], [w / 2, h, d / 2])],
+        frame: 'node',
+        shape: 'approx',
+        why: 'a catalogue model: its box',
+    };
+}
+const turn = (x, z, angle) => [
+    x * Math.cos(angle) + z * Math.sin(angle),
+    -x * Math.sin(angle) + z * Math.cos(angle),
+];
+const flat = (rotation) => Math.abs(rotation[0] ?? 0) < ROTATION_EPSILON && Math.abs(rotation[2] ?? 0) < ROTATION_EPSILON;
+const orientation = (ring) => {
+    let a = 0;
+    for (let i = 0, j = ring.length - 1; i < ring.length; j = i++)
+        a += ring[j][0] * ring[i][1] - ring[i][0] * ring[j][1];
+    return a;
+};
+/** One local band as a prism in building metres, through the corrective, node and host transforms. */
+function bandPrisms(item, local, place, id) {
+    const assetScale = item.asset.scale ?? [1, 1, 1];
+    const offset = item.asset.offset;
+    const corrective = local.frame === 'artifact';
+    const scale = item.scale;
+    const asset = corrective ? item.asset.rotation[1] : 0;
+    const out = [];
+    for (const [index, band] of local.bands.entries()) {
+        const heightAt = (y) => place.origin[2] + (corrective ? assetScale[1] * y + offset[1] : y) * scale[1];
+        const [z0, z1] = [heightAt(band.y0), heightAt(band.y1)].sort((a, b) => a - b);
+        for (const [k, polygon] of band.polygons.entries()) {
+            const ring = (points) => {
+                const moved = points.map(([x, z]) => {
+                    let px = x;
+                    let pz = z;
+                    if (corrective) {
+                        ;
+                        [px, pz] = turn(x * assetScale[0], z * assetScale[2], asset);
+                        px += offset[0];
+                        pz += offset[2];
+                    }
+                    ;
+                    [px, pz] = turn(px * scale[0], pz * scale[2], place.yaw);
+                    return place.plan(px + place.origin[0], pz + place.origin[1]);
+                });
+                // A mirrored item (a negative scale) reverses the winding; keep each ring's as it was.
+                return orientation(moved) * orientation(points) < 0 ? moved.reverse() : moved;
+            };
+            out.push({
+                id: `${id}.${index}.${k}`,
+                nodeId: item.id,
+                kind: 'item',
+                z0,
+                z1,
+                outer: ring(polygon.outer),
+                holes: (polygon.holes ?? []).map(ring),
+                shape: local.shape === 'exact' && !place.approx ? 'exact' : 'approx',
+                ...(local.why || place.approx ? { why: local.why ?? place.approx } : {}),
+                ...(place.host ? { host: place.host } : {}),
+            });
+        }
+    }
+    return out;
+}
+/** The box a tilted or oddly scaled item fills, as one approximate prism. */
+function tiltedPrism(item, place, id) {
+    const [sx, sy, sz] = item.scale;
+    const [w, h, d] = item.asset.dimensions;
+    const half = rectangle((-w / 2) * sx, (-d / 2) * sz, (w / 2) * sx, (d / 2) * sz);
+    const moved = half.map(([x, z]) => {
+        const [px, pz] = turn(x, z, place.yaw);
+        return place.plan(px + place.origin[0], pz + place.origin[1]);
+    });
+    return [
+        {
+            id,
+            nodeId: item.id,
+            kind: 'item',
+            z0: place.origin[2],
+            z1: place.origin[2] + h * sy,
+            outer: moved,
+            holes: [],
+            shape: 'approx',
+            why: 'an item turned about a horizontal axis: its box',
+            ...(place.host ? { host: place.host } : {}),
+        },
+    ];
+}
+/** Where a wall's local frame (x along the wall, z across, toward its left) lands in plan. */
+function wallPlan(wall) {
+    const length = getWallCurveLength(wall);
+    return (x, z) => {
+        const frame = getWallCurveFrameAt(wall, length > 1e-9 ? Math.min(1, Math.max(0, x / length)) : 0);
+        return [frame.point.x + frame.normal.x * z, frame.point.y + frame.normal.y * z];
+    };
+}
+export const itemContext = (nodes) => ({
+    nodes,
+    byId: new Map(Object.entries(nodes)),
+    elevations: getLevelElevations(nodes),
+    supportCache: new Map(),
+});
+/** One item as prisms in absolute building metres; or `unshaped` with what it is hosted by, or `skipped` with why. */
+export function itemShapesOf(item, { nodes, byId, elevations, supportCache }) {
+    try {
+        if (item.asset.attachTo === 'ceiling')
+            return { unshaped: 'ceiling item' };
+        if (item.roofSegmentId || item.blockFaceId)
+            return { unshaped: 'item on a roof or a block' };
+        const levelId = resolveLevelId(item, nodes);
+        const baseY = elevations.get(levelId)?.baseY ?? 0;
+        const parent = item.parentId ? nodes[item.parentId] : undefined;
+        const local = localShape(item);
+        let place;
+        if (parent?.type === 'wall') {
+            if (item.asset.attachTo !== 'wall' && item.asset.attachTo !== 'wall-side')
+                return { unshaped: 'item on a wall that is not wall-mounted' };
+            const wall = parent;
+            const across = item.asset.attachTo === 'wall-side'
+                ? getWallLocalFaceZ(wall, item.side === 'front' ? 'a' : 'b')
+                : item.position[2] + getWallBodyCenterOffset(wall);
+            const base = baseY + wallSupportForNodes(wall, nodes).elevation;
+            place = {
+                origin: [item.position[0], across, base + item.position[1]],
+                yaw: item.rotation[1],
+                plan: wallPlan(wall),
+                host: { wallId: wall.id, face: across >= 0 ? 'a' : 'b' },
+                ...(isCurvedWall(wall) ? { approx: 'an item on a curved wall' } : {}),
+            };
+        }
+        else {
+            const pose = itemLevelPose(item, byId);
+            if (!pose)
+                return { unshaped: 'item hosted where its pose cannot be read' };
+            const [x, y, z] = pose.position;
+            const root = rootOf(item, nodes);
+            const floor = root.parentId === levelId || !root.parentId
+                ? floorUnder(root, {
+                    position: [root.position[0], 0, root.position[2]],
+                    dimensions: getScaledDimensions(root),
+                    rotation: root.rotation,
+                }, nodes, levelId, supportCache)
+                : 0;
+            place = {
+                origin: [x, z, baseY + floor + y],
+                // `yawDeg` is the sum of the hosts' `rotation[1]`, which is in radians
+                yaw: pose.yawDeg,
+                plan: (px, pz) => [px, pz],
+            };
+        }
+        const id = `${item.id}#shape`;
+        const tilted = !flat(item.rotation) || !flat(item.asset.rotation);
+        const degenerate = [...item.scale, ...(item.asset.scale ?? [1, 1, 1])].some((v) => v === 0);
+        const prisms = tilted || degenerate ? tiltedPrism(item, place, id) : bandPrisms(item, local, place, id);
+        return { shapes: { itemId: item.id, levelId, prisms } };
+    }
+    catch (error) {
+        return {
+            skipped: { nodeId: item.id, why: error instanceof Error ? error.message : String(error) },
+        };
+    }
+}
+/**
+ * Every item as prisms in absolute building metres, filed under its level. An item stands on the
+ * floor under it, on the item that hosts it, or on a wall; one hosted by a ceiling, a roof or a block
+ * is counted in `unshaped`. Its outline is its script's stored shape when it has one, else a box.
+ */
+export function itemBodies(nodes) {
+    const items = [];
+    const skipped = [];
+    const unshaped = {};
+    const context = itemContext(nodes);
+    for (const node of Object.values(nodes)) {
+        if (node.type !== 'item' || isHidden(node, nodes))
+            continue;
+        const shaped = itemShapesOf(node, context);
+        if ('shapes' in shaped)
+            items.push(shaped.shapes);
+        else if ('skipped' in shaped)
+            skipped.push(shaped.skipped);
+        else
+            unshaped[shaped.unshaped] = (unshaped[shaped.unshaped] ?? 0) + 1;
+    }
+    return { items, skipped, unshaped };
+}
+function rootOf(item, nodes) {
+    let root = item;
+    for (let parent = root.parentId ? nodes[root.parentId] : undefined; parent?.type === 'item';) {
+        root = parent;
+        parent = root.parentId ? nodes[root.parentId] : undefined;
+    }
+    return root;
+}

package/dist/spatial/usage-field/labels.d.ts

@@ -0,0 +1,8 @@
+import type { Nodes } from './walls.js';
+/** A node's name as a finding says it: its own, its asset's, or its kind and the tail of its id. */
+export declare function nameOf(nodes: Nodes, id: string): string;
+export declare const m: (v: number) => string;
+export declare const cm: (v: number) => string;
+export declare const quote: (name: string) => string;
+export declare const unique: (ids: (string | undefined)[]) => string[];
+//# sourceMappingURL=labels.d.ts.map

package/dist/spatial/usage-field/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../../../src/spatial/usage-field/labels.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,oGAAoG;AACpG,wBAAgB,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED,eAAO,MAAM,CAAC,MAAO,MAAM,WAAiB,CAAA;AAC5C,eAAO,MAAM,EAAE,MAAO,MAAM,WAAgC,CAAA;AAC5D,eAAO,MAAM,KAAK,SAAU,MAAM,WAAgB,CAAA;AAClD,eAAO,MAAM,MAAM,QAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,aAEjD,CAAA"}

package/dist/spatial/usage-field/labels.js

@@ -0,0 +1,14 @@
+/** A node's name as a finding says it: its own, its asset's, or its kind and the tail of its id. */
+export function nameOf(nodes, id) {
+    const node = nodes[id];
+    if (!node)
+        return id;
+    const tail = id.slice(id.indexOf('_') + 1).slice(0, 4);
+    return String(node.name ?? node.asset?.name ?? `${node.type[0].toUpperCase()}${node.type.slice(1)} ${tail}`);
+}
+export const m = (v) => v.toFixed(2);
+export const cm = (v) => `${Math.round(v * 100)} cm`;
+export const quote = (name) => `“${name}”`;
+export const unique = (ids) => [
+    ...new Set(ids.filter((id) => !!id)),
+];

package/dist/spatial/usage-field/level-field.d.ts

@@ -0,0 +1,47 @@
+import { BucketIndex, type Grid } from './field.js';
+import { type Aabb, type Band, type Obstacle } from './obstacles.js';
+import type { FloorRegion, Prism, Ring, UsageShapes } from './types.js';
+/** A body in the height range a person's trunk and legs fill, and in the range a wheelchair's feet and wheels do. */
+export declare const BODY_BAND: {
+    readonly from: 0.03;
+    readonly to: 2;
+};
+export declare const FEET_BAND: {
+    readonly from: 0.03;
+    readonly to: 0.7;
+};
+export type FloorGroup = {
+    levelId: string;
+    /** Absolute height of the finished floor. */
+    y: number;
+    regions: FloorRegion[];
+    domain: Aabb;
+};
+/** Regions of one level at one finished height share a field; a step or a porch deck is a group of its own. */
+export declare function floorGroups(shapes: UsageShapes): FloorGroup[];
+export declare function inRing(px: number, pz: number, ring: Ring): boolean;
+export declare const inRegion: (px: number, pz: number, region: Pick<FloorRegion, 'outer' | 'holes'>) => boolean;
+/** The cells whose centre lies in any of the rings (holes excluded), as a 0/1 mask. */
+export declare function maskOf(g: Grid, regions: Pick<FloorRegion, 'outer' | 'holes'>[]): Uint8Array;
+export type LevelField = {
+    group: FloorGroup;
+    band: Band;
+    grid: Grid;
+    /** Signed distance to the nearest obstacle in the band, at every cell centre. */
+    F: Float32Array;
+    A: Int32Array;
+    /** 1 where a person can stand on the floor, whatever is on it. */
+    floor: Uint8Array;
+    /** 1 where the floor is free: on it, and clear of every obstacle. */
+    free: Uint8Array;
+    obstacles: Obstacle[];
+    index: BucketIndex;
+};
+/** What a body of a band bumps into above one floor group: every prism of the building meeting it, stairs included. */
+export declare function buildField(shapes: UsageShapes, group: FloorGroup, range: {
+    from: number;
+    to: number;
+}, cell: number, skip?: (prism: Prism) => boolean, extra?: Prism[]): LevelField;
+/** The cell under a plan point, or -1 off the field. */
+export declare const fieldCell: (field: LevelField, x: number, z: number) => number;
+//# sourceMappingURL=level-field.d.ts.map

package/dist/spatial/usage-field/level-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"level-field.d.ts","sourceRoot":"","sources":["../../../src/spatial/usage-field/level-field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAkC,KAAK,IAAI,EAAY,MAAM,SAAS,CAAA;AAC1F,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAmB,MAAM,aAAa,CAAA;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAEpE,qHAAqH;AACrH,eAAO,MAAM,SAAS;aAAK,IAAI,EAAE,IAAI;aAAE,EAAE,EAAE,CAAG;CAAW,CAAA;AACzD,eAAO,MAAM,SAAS;aAAK,IAAI,EAAE,IAAI;aAAE,EAAE,EAAE,GAAG;CAAW,CAAA;AAEzD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,6CAA6C;IAC7C,CAAC,EAAE,MAAM,CAAA;IACT,OAAO,EAAE,WAAW,EAAE,CAAA;IACtB,MAAM,EAAE,IAAI,CAAA;CACb,CAAA;AAED,+GAA+G;AAC/G,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,EAAE,CA6B7D;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CASlE;AAED,eAAO,MAAM,QAAQ,OAAQ,MAAM,MAAM,MAAM,UAAU,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC,YACT,CAAA;AAEpF,uFAAuF;AACvF,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC,EAAE,GAAG,UAAU,CAsB3F;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,UAAU,CAAA;IACjB,IAAI,EAAE,IAAI,CAAA;IACV,IAAI,EAAE,IAAI,CAAA;IACV,iFAAiF;IACjF,CAAC,EAAE,YAAY,CAAA;IACf,CAAC,EAAE,UAAU,CAAA;IACb,kEAAkE;IAClE,KAAK,EAAE,UAAU,CAAA;IACjB,qEAAqE;IACrE,IAAI,EAAE,UAAU,CAAA;IAChB,SAAS,EAAE,QAAQ,EAAE,CAAA;IACrB,KAAK,EAAE,WAAW,CAAA;CACnB,CAAA;AAED,uHAAuH;AACvH,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EACnC,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,EAChC,KAAK,GAAE,KAAK,EAAO,GAClB,UAAU,CAwBZ;AAED,wDAAwD;AACxD,eAAO,MAAM,SAAS,UAAW,UAAU,KAAK,MAAM,KAAK,MAAM,WAA6B,CAAA"}