@pascal-app/core 1.0.4 → 1.0.5

package/dist/services/roof-move.js

@@ -0,0 +1,316 @@
+import { applySceneChanges } from '../agent-operations/apply-changes.js';
+import { getLevelDisplayName } from '../lib/level-name.js';
+import { getActiveRoofHeight, parseNode, } from '../schema/index.js';
+import { resolveRoofElevation, roofWallTop } from '../systems/roof/roof-elevation.js';
+import { segmentBearing } from './roof-bearing.js';
+import { coveredStoreyId, planRoofLevel, servesAsRoofLevel } from './roof-level.js';
+import { getLevelBelow, getLevelElevations } from './storey.js';
+const segmentsOf = (nodes, roof) => roof.children
+    .map((id) => nodes[id])
+    .filter((child) => child?.type === 'roof-segment');
+/**
+ * Where a roof's segments bear, from the floor of the level holding it (m): the lowest of them;
+ * null with none.
+ */
+function roofBearing(nodes, roof) {
+    const heights = segmentsOf(nodes, roof).map((segment) => roof.position[1] + segment.position[1]);
+    return heights.length ? Math.min(...heights) : null;
+}
+/** How far from a storey's wall tops a roof bears and still stands on them; a porch's beam is lower. */
+const ON_WALLS = 0.15;
+/** Whether a roof's footprint bears on the tops of `levelId`'s walls under it: the height it keeps over a storey. */
+function bearsOn(nodes, roof, levelId) {
+    const bearing = roofBearing(nodes, roof);
+    const top = roofWallTop(roof, nodes, levelId);
+    return bearing !== null && top !== null && Math.abs(bearing - top) <= ON_WALLS;
+}
+/**
+ * A roof held by the storey whose walls carry it (written there before the rule, or by a tool that
+ * ignored it): it hides that storey's plan in solo and exploded views; the seat and
+ * `planRoofsOffStorey` move it. Some segment bears on the storey's walls (`segmentBearing`: walls
+ * along its edges, open air past them) and the roof follows walls, or a segment's base or eave
+ * stands at the eave those walls need (knee walls on the plate, or the segment's own walls rising to
+ * it). A lower wing's roof on the storey above is not one (its inner edge has rooms past it), nor a
+ * porch or portico on posts (no wall along its outer edges), nor a roof on another roof.
+ */
+export function isRoofOnStoreyWalls(nodes, roofId) {
+    const roof = nodes[roofId];
+    const level = roof?.type === 'roof' ? nodes[roof.parentId ?? ''] : undefined;
+    if (roof?.type !== 'roof' ||
+        level?.type !== 'level' ||
+        servesAsRoofLevel(nodes, level) ||
+        roof.support?.kind === 'roof')
+        return false;
+    return segmentsOf(nodes, roof).some((segment) => {
+        const { need } = segmentBearing(nodes, segment.id, level.id);
+        if (need === null)
+            return false;
+        if (roof.support?.kind === 'walls')
+            return true;
+        const base = roof.position[1] + segment.position[1];
+        return [base, base + segment.wallHeight].some((y) => Math.abs(y - need) <= ON_WALLS);
+    });
+}
+/**
+ * `roofs`, held by `storeyId` on its walls, moved to the level the rule gives them, each container
+ * dropped by the storey's offset so it stands where it stood. A roof that follows walls keeps
+ * following where the follow there reads the storey's walls, at the height it gives; elsewhere (over
+ * a support level or a level still to be built) it keeps its height instead.
+ */
+function planRoofMove(nodes, storeyId, roofs) {
+    const segmentRise = (segment) => (segment.wallHeight ?? 0) + getActiveRoofHeight(segment);
+    const rise = Math.max(0, ...roofs.flatMap((roof) => segmentsOf(nodes, roof)).map(segmentRise));
+    const planned = planRoofLevel(nodes, storeyId, rise);
+    const made = planned.kind === 'roof' ? planned.create : null;
+    const declares = planned.kind === 'roof' ? planned.update : [];
+    const ids = roofs.map((roof) => roof.id);
+    const move = (roof, y, support) => {
+        const [x, , z] = roof.position;
+        const data = { parentId: planned.levelId, position: [x, y, z] };
+        if (support)
+            data.support = support;
+        return { id: roof.id, data: data };
+    };
+    const kept = roofs.map((roof) => roof.position[1] + planned.storeyOffset);
+    // A level made for them lists its roofs from the start (updates land before creates, in the
+    // store too).
+    const placed = applySceneChanges(nodes, {
+        create: made ? [{ node: { ...made, children: ids } }] : [],
+        update: [...declares, ...roofs.map((roof, index) => move(roof, kept[index]))],
+    });
+    // The follow reads the walls of the level holding a roof and of the one directly under it: over
+    // a support level or a level still to be built it would not see the storey's.
+    const followSeesStorey = getLevelBelow(planned.levelId, placed)?.id === storeyId;
+    const moves = roofs.map((roof, index) => roof.support?.kind !== 'walls'
+        ? move(roof, kept[index])
+        : followSeesStorey
+            ? move(roof, resolveRoofElevation(placed[roof.id], placed))
+            : move(roof, kept[index], { kind: 'level' }));
+    // A roof level made for them is as tall as they rise over its floor, the eaves' lift over the
+    // storey included, as create_roof makes one.
+    const level = made && {
+        ...made,
+        children: ids,
+        height: Math.max(0.2, ...roofs.flatMap((roof, index) => segmentsOf(nodes, roof).map((segment) => moves[index].data.position[1] +
+            segment.position[1] +
+            segmentRise(segment)))),
+    };
+    return {
+        plan: planned.kind === 'roof' && level ? { ...planned, create: level } : planned,
+        changes: {
+            create: level ? [{ node: level, parentId: level.parentId ?? undefined }] : [],
+            update: [...declares, ...moves],
+        },
+    };
+}
+/**
+ * The repair for roofs written onto the storey whose walls carry them (`isRoofOnStoreyWalls`):
+ * each goes to the level the rule gives it, standing where it stood (`planRoofMove`). Null when the
+ * storey holds no such roof. Pure: one set of changes, so one undo step.
+ */
+export function planRoofsOffStorey(nodes, storeyId) {
+    const storey = nodes[storeyId];
+    if (storey?.type !== 'level')
+        return null;
+    const roofs = storey.children
+        .map((id) => nodes[id])
+        .filter((child) => child?.type === 'roof' && isRoofOnStoreyWalls(nodes, child.id));
+    return roofs.length ? planRoofMove(nodes, storeyId, roofs) : null;
+}
+/**
+ * Whether a roof stands over the storey under the level holding it: on the roof level over it
+ * (`coveredStoreyId`), or on the storey above bearing on its walls and not on its own level's (a
+ * lower wing's roof, where the rule puts it).
+ */
+function standsOver(nodes, roof, storeyId) {
+    const level = nodes[roof.parentId ?? ''];
+    if (level?.type !== 'level' || coveredStoreyId(nodes, roof) !== storeyId)
+        return false;
+    return (servesAsRoofLevel(nodes, level) ||
+        (bearsOn(nodes, roof, storeyId) && !bearsOn(nodes, roof, level.id)));
+}
+/** The levels between a storey and a level above it in their building's stack, bottom up. */
+function levelsBetween(elevations, storeyId, levelId) {
+    const lower = elevations.get(storeyId);
+    const upper = elevations.get(levelId);
+    if (!lower || !upper)
+        return '';
+    return [...elevations]
+        .filter(([, entry]) => entry.buildingId === upper.buildingId &&
+        entry.ordinal > lower.ordinal &&
+        entry.ordinal < upper.ordinal)
+        .sort(([, a], [, b]) => a.ordinal - b.ordinal)
+        .map(([id]) => id)
+        .join();
+}
+/**
+ * A roof on a level above the storey it covers (`coveredStoreyId`), at a height of its own
+ * (`support` level, as the agents' and the auto roof's are, measured from that storey's floor),
+ * keeps its height over that floor when its level rises or drops over the storey (the storey, or a
+ * support level or a level still to be built between them, made taller or shorter), as it did when
+ * it lived on the storey. The updates that keep it there from `before` to `after`; a roof moved in
+ * between, or whose level stands over another storey or other levels now, is left where it is.
+ */
+export function roofsKeptOverStorey(before, after) {
+    const was = getLevelElevations(before);
+    const now = getLevelElevations(after);
+    const rise = (elevations, levelId, storeyId) => (elevations.get(levelId)?.baseY ?? 0) - (elevations.get(storeyId)?.baseY ?? 0);
+    const updates = [];
+    for (const roof of Object.values(after)) {
+        if (roof.type !== 'roof' || roof.support?.kind !== 'level' || !roof.parentId)
+            continue;
+        const prior = before[roof.id];
+        if (prior?.type !== 'roof' ||
+            prior.parentId !== roof.parentId ||
+            prior.position[1] !== roof.position[1])
+            continue;
+        const storeyId = coveredStoreyId(after, roof);
+        if (!storeyId || storeyId === roof.parentId || coveredStoreyId(before, prior) !== storeyId)
+            continue;
+        // A level put in, taken out or reordered between them: the roof moves with its level (#1039).
+        const between = levelsBetween(now, storeyId, roof.parentId);
+        if (between !== levelsBetween(was, storeyId, roof.parentId))
+            continue;
+        const drift = rise(now, roof.parentId, storeyId) - rise(was, roof.parentId, storeyId);
+        if (Math.abs(drift) < 1e-6 || !standsOver(before, prior, storeyId))
+            continue;
+        // Over levels between, only a roof on the storey's walls stays on them: one a new level lifted
+        // off them stays on top of that level.
+        if (between && !bearsOn(before, prior, storeyId))
+            continue;
+        const [x, y, z] = roof.position;
+        updates.push({ id: roof.id, data: { position: [x, y - drift, z] } });
+    }
+    return updates;
+}
+const r3 = (value) => Math.round(value * 1000) / 1000;
+/** Whether two node values are the same, key order aside (a graph of fresh objects matches the store's). */
+function same(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    return [...keys].every((key) => same(a[key], b[key]));
+}
+const PLACEMENT = ['parentId', 'position', 'rotation', 'support', 'children'];
+/** Whether a write made a roof, or moved, turned or reshaped it: its placement or a segment differs. */
+function touched(before, after, roof) {
+    const prior = before[roof.id];
+    if (prior?.type !== 'roof')
+        return true;
+    return (PLACEMENT.some((key) => !same(prior[key], roof[key])) ||
+        roof.children.some((id) => !same(before[id], after[id])));
+}
+/**
+ * The seat over the scene a write produced, `after` as the store leaves it (creates parsed and
+ * attached, reparents and cascades applied), for writers that hold the result. A roof the write
+ * made, moved, turned or reshaped that stands on its storey's walls (`isRoofOnStoreyWalls`) goes to
+ * the level the rule gives it, as the repair moves it; one already on the same storey's walls before
+ * stays (an edit does not migrate a legacy roof; `verify_scene` reports it). Storey by storey, each
+ * move planned on the scene with the earlier ones applied, so one write makes one roof level per
+ * building. Null when no roof needs it.
+ */
+export function planRoofSeats(before, after) {
+    const byStorey = new Map();
+    for (const node of Object.values(after)) {
+        if (node.type !== 'roof' || !node.parentId)
+            continue;
+        if (!(touched(before, after, node) && isRoofOnStoreyWalls(after, node.id)))
+            continue;
+        const prior = before[node.id];
+        if (prior?.type === 'roof' &&
+            prior.parentId === node.parentId &&
+            isRoofOnStoreyWalls(before, node.id))
+            continue;
+        byStorey.set(node.parentId, [...(byStorey.get(node.parentId) ?? []), node]);
+    }
+    if (!byStorey.size)
+        return null;
+    let scene = after;
+    const create = [];
+    const update = [];
+    const notes = [];
+    for (const [storeyId, roofs] of byStorey) {
+        const { plan, changes } = planRoofMove(scene, storeyId, roofs.map((roof) => scene[roof.id]));
+        scene = applySceneChanges(scene, changes);
+        create.push(...changes.create);
+        update.push(...changes.update);
+        const storey = scene[storeyId];
+        const target = scene[plan.levelId];
+        const how = plan.kind !== 'roof'
+            ? ''
+            : plan.create
+                ? ', a new Roof level'
+                : plan.update.length
+                    ? ', declared the roof level'
+                    : '';
+        for (const { id } of roofs)
+            notes.push(`roof ${id} stands on ${getLevelDisplayName(storey)}'s walls, so it is on ${getLevelDisplayName(target)} (${plan.levelId}${how}) at y ${r3(scene[id].position[1])}: a roof lives on the level above the walls that carry it.`);
+    }
+    // A level an earlier move made lists what later moves put on it.
+    for (const entry of create)
+        entry.node = {
+            ...entry.node,
+            children: scene[entry.node.id].children,
+        };
+    return { changes: { create, update }, notes };
+}
+/**
+ * A write's changes with the roofs it puts on their walls' storey seated by the rule
+ * (`planRoofSeats` over the scene they produce), and a note per roof. The seat is written into the
+ * changes themselves, so the writer's one store call lands it: a created roof's entry takes its new
+ * parent and height (its other fields kept) and leaves a created parent's `children`; an existing
+ * roof's move and a level's declaration are updates; a new roof level is created right after its
+ * building when the write creates the building, else first, listing its roofs, so a store creating
+ * in order and one applying updates first both land it.
+ */
+export function seatRoofs(nodes, changes) {
+    const parsed = (changes.create ?? []).map(({ node, parentId }) => {
+        const result = parseNode(node);
+        return { node: result.success ? result.data : node, parentId };
+    });
+    const seat = planRoofSeats(nodes, applySceneChanges(nodes, {
+        create: parsed,
+        update: [...(changes.update ?? [])],
+        delete: [...(changes.delete ?? [])],
+    }));
+    if (!seat)
+        return { changes, notes: [] };
+    const written = new Map(seat.changes.update.map(({ id, data }) => [id, data]));
+    const leaving = (childId, parentId) => {
+        const to = written.get(childId)?.parentId;
+        return to !== undefined && to !== parentId;
+    };
+    const create = (changes.create ?? []).map((entry) => {
+        const data = written.get(entry.node.id);
+        const node = { ...entry.node, ...data };
+        const children = Array.isArray(node.children) ? node.children : null;
+        const kept = children?.filter((id) => !leaving(id, entry.node.id));
+        return {
+            ...entry,
+            node: (kept && kept.length !== children?.length
+                ? { ...node, children: kept }
+                : node),
+            ...(data?.parentId ? { parentId: data.parentId } : {}),
+        };
+    });
+    for (const entry of seat.changes.create) {
+        const building = create.findIndex(({ node }) => node.id === entry.node.parentId);
+        create.splice(building + 1, 0, entry);
+    }
+    const created = new Set(create.map(({ node }) => node.id));
+    return {
+        changes: {
+            ...changes,
+            create,
+            update: [
+                ...(changes.update ?? []),
+                ...seat.changes.update.filter(({ id }) => !created.has(id)),
+            ],
+        },
+        notes: seat.notes,
+    };
+}

package/dist/services/stair-surface-snap.d.ts

@@ -0,0 +1,14 @@
+import type { StairNode } from '../schema/nodes/stair.js';
+import type { AnyNode } from '../schema/types.js';
+export type StairSurfaceSnap = {
+    position: [number, number, number];
+    rotation: number;
+    totalRise: number;
+    stepCount: number;
+    length: number;
+    surfaceId: string;
+};
+/** Align a straight flight's high end to a nearby registered surface edge. */
+export declare function resolveStairSurfaceSnap(stair: StairNode, nodes: Readonly<Record<string, AnyNode>>, candidatePosition: [number, number, number], currentLength: number, baseElevation?: number, installedPlugins?: readonly string[]): StairSurfaceSnap | null;
+export declare function getBoundarySurfaces(nodes: Readonly<Record<string, AnyNode>>, parentId: string | null | undefined, installedPlugins?: readonly string[]): AnyNode[];
+//# sourceMappingURL=stair-surface-snap.d.ts.map

package/dist/services/stair-surface-snap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stair-surface-snap.d.ts","sourceRoot":"","sources":["../../src/services/stair-surface-snap.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAK9C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC3C,aAAa,EAAE,MAAM,EACrB,aAAa,SAAuB,EACpC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GACnC,gBAAgB,GAAG,IAAI,CA8EzB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GACnC,OAAO,EAAE,CAQX"}

package/dist/services/stair-surface-snap.js

@@ -0,0 +1,116 @@
+import { floorConstructionLift } from '../lib/floor-construction-lift.js';
+import { isNodeKindEnabled, nodeRegistry } from '../registry/registry.js';
+const SNAP_DISTANCE = 0.75;
+/** Align a straight flight's high end to a nearby registered surface edge. */
+export function resolveStairSurfaceSnap(stair, nodes, candidatePosition, currentLength, baseElevation = candidatePosition[1], installedPlugins) {
+    if (stair.stairType !== 'straight' || stair.autoSurfaceSnap === false)
+        return null;
+    const parentFrame = surfaceFrame(stair.parentId, nodes);
+    const candidate = toFrame([candidatePosition[0], candidatePosition[2]], parentFrame);
+    const rotation = stair.rotation + parentFrame.rotation;
+    const highEnd = [
+        candidate[0] + Math.sin(rotation) * currentLength,
+        candidate[1] + Math.cos(rotation) * currentLength,
+    ];
+    let closest = null;
+    for (const raw of Object.values(nodes)) {
+        if (surfaceFrame(raw.parentId, nodes).levelId !== parentFrame.levelId ||
+            raw.visible === false ||
+            !isNodeKindEnabled(raw.type, installedPlugins))
+            continue;
+        const top = nodeRegistry.get(raw.type)?.capabilities?.surfaces?.top;
+        if (!top?.boundary)
+            continue;
+        const surface = raw;
+        const targetFrame = surfaceFrame(raw.parentId, nodes);
+        const outline = top.boundary(raw, 0).map((point) => toFrame(point, targetFrame));
+        if (outline.length < 3)
+            continue;
+        const area = outline.reduce((sum, p, index) => {
+            const next = outline[(index + 1) % outline.length];
+            return sum + p[0] * next[1] - next[0] * p[1];
+        }, 0);
+        for (let index = 0; index < outline.length; index++) {
+            const a = outline[index], b = outline[(index + 1) % outline.length];
+            const dx = b[0] - a[0], dz = b[1] - a[1];
+            const size = Math.hypot(dx, dz);
+            if (size < 1e-4)
+                continue;
+            const project = (point) => Math.max(0, Math.min(1, ((point[0] - a[0]) * dx + (point[1] - a[1]) * dz) / (size * size)));
+            const lowT = project(candidate), highT = project(highEnd);
+            const lowEdge = [a[0] + dx * lowT, a[1] + dz * lowT];
+            const highEdge = [a[0] + dx * highT, a[1] + dz * highT];
+            const lowDistance = Math.hypot(candidate[0] - lowEdge[0], candidate[1] - lowEdge[1]);
+            const highDistance = Math.hypot(highEnd[0] - highEdge[0], highEnd[1] - highEdge[1]);
+            const t = highDistance < lowDistance ? highT : lowT;
+            const edge = [a[0] + dx * t, a[1] + dz * t];
+            const direction = area >= 0 ? 1 : -1;
+            const nx = (-dz / size) * direction, nz = (dx / size) * direction;
+            const outside = -((candidate[0] - edge[0]) * nx + (candidate[1] - edge[1]) * nz);
+            if (outside < -SNAP_DISTANCE)
+                continue;
+            const distance = Math.min(lowDistance, highDistance);
+            const catchDistance = stair.destinationSurfaceId === surface.id ? 1.25 : SNAP_DISTANCE;
+            if (distance > catchDistance || (closest && distance >= closest.distance))
+                continue;
+            const height = typeof top.height === 'function'
+                ? top.height(raw, { nodes, point: fromFrame(edge, targetFrame) })
+                : top.height;
+            const topElevation = targetFrame.y + (surface.position?.[1] ?? 0) + height + floorConstructionLift(nodes, raw);
+            const rise = topElevation - (baseElevation + parentFrame.y);
+            if (!Number.isFinite(rise) || rise <= 0.01)
+                continue;
+            const stepCount = Math.max(1, Math.round(rise / 0.16));
+            const minRun = stepCount * 0.28;
+            const length = Math.max(minRun, outside, 0.4);
+            const localPoint = fromFrame([edge[0] - nx * length, edge[1] - nz * length], parentFrame);
+            closest = {
+                distance,
+                snap: {
+                    position: [localPoint[0], candidatePosition[1], localPoint[1]],
+                    rotation: Math.atan2(nx, nz) - parentFrame.rotation,
+                    totalRise: rise,
+                    stepCount,
+                    length,
+                    surfaceId: surface.id,
+                },
+            };
+        }
+    }
+    return closest?.snap ?? null;
+}
+export function getBoundarySurfaces(nodes, parentId, installedPlugins) {
+    return Object.values(nodes).filter((node) => node.parentId === parentId &&
+        node.visible !== false &&
+        isNodeKindEnabled(node.type, installedPlugins) &&
+        Boolean(nodeRegistry.get(node.type)?.capabilities?.surfaces?.top?.boundary));
+}
+function surfaceFrame(parentId, nodes) {
+    const frame = { x: 0, y: 0, z: 0, rotation: 0, levelId: parentId };
+    const visited = new Set();
+    while (frame.levelId && !visited.has(frame.levelId)) {
+        visited.add(frame.levelId);
+        const parent = nodes[frame.levelId];
+        if (!parent || parent.type === 'level')
+            break;
+        const pose = parent;
+        const angle = typeof pose.rotation === 'number' ? pose.rotation : (pose.rotation?.[1] ?? 0);
+        const c = Math.cos(angle), s = Math.sin(angle);
+        const [x, y, z] = pose.position ?? [0, 0, 0];
+        const nextX = x + frame.x * c + frame.z * s;
+        frame.z = z - frame.x * s + frame.z * c;
+        frame.x = nextX;
+        frame.y += y;
+        frame.rotation += angle;
+        frame.levelId = parent.parentId;
+    }
+    return frame;
+}
+function toFrame([x, z], frame) {
+    const c = Math.cos(frame.rotation), s = Math.sin(frame.rotation);
+    return [frame.x + x * c + z * s, frame.z - x * s + z * c];
+}
+function fromFrame([x, z], frame) {
+    const c = Math.cos(frame.rotation), s = Math.sin(frame.rotation);
+    return [(x - frame.x) * c - (z - frame.z) * s, (x - frame.x) * s + (z - frame.z) * c];
+}

package/dist/services/storey-datum.d.ts

@@ -0,0 +1,12 @@
+import type { AnyNode } from '../schema/index.js';
+export type StoreyDatum = {
+    /** World/site Y of the level plane, excluding standing slabs and sampled terrain. */
+    floorElevation: number;
+    /** The same level plane in its building's coordinates. */
+    floorElevationBuildingLocal: number;
+    /** Stored floor-to-floor height, with the existing legacy fallback. */
+    floorToFloorHeight: number;
+};
+/** The existing resolved storey plane, not the walking surface elected from its slabs. */
+export declare function getStoreyDatum(nodes: Readonly<Record<string, AnyNode>>, levelId: string): StoreyDatum | null;
+//# sourceMappingURL=storey-datum.d.ts.map

package/dist/services/storey-datum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storey-datum.d.ts","sourceRoot":"","sources":["../../src/services/storey-datum.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,WAAW,CAAA;AAGnD,MAAM,MAAM,WAAW,GAAG;IACxB,qFAAqF;IACrF,cAAc,EAAE,MAAM,CAAA;IACtB,0DAA0D;IAC1D,2BAA2B,EAAE,MAAM,CAAA;IACnC,uEAAuE;IACvE,kBAAkB,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAC5B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,EAAE,MAAM,GACd,WAAW,GAAG,IAAI,CAYpB"}

package/dist/services/storey-datum.js

@@ -0,0 +1,18 @@
+import { SITE_DATUM_Y } from '../lib/terrain-support-query.js';
+import { getLevelElevations, getStoredLevelHeight } from './storey.js';
+/** The existing resolved storey plane, not the walking surface elected from its slabs. */
+export function getStoreyDatum(nodes, levelId) {
+    const level = nodes[levelId];
+    if (level?.type !== 'level')
+        return null;
+    const elevation = getLevelElevations(nodes).get(levelId);
+    if (!elevation)
+        return null;
+    const building = elevation.buildingId ? nodes[elevation.buildingId] : undefined;
+    const buildingY = building?.type === 'building' ? (building.position?.[1] ?? 0) : 0;
+    return {
+        floorElevation: SITE_DATUM_Y + buildingY + elevation.baseY,
+        floorElevationBuildingLocal: elevation.baseY,
+        floorToFloorHeight: getStoredLevelHeight(level),
+    };
+}

package/dist/services/storey.d.ts

@@ -1,4 +1,4 @@
-import type { LevelNode, WallNode } from '../schema/index.js';
+import type { LevelNode, SlabNode, WallNode } from '../schema/index.js';
 import type { AnyNode, AnyNodeId } from '../schema/types.js';
 /**
  * Gap kept between a ceiling's stored height and its clamp bound (storey
@@ -6,6 +6,8 @@ import type { AnyNode, AnyNodeId } from '../schema/types.js';
  * coincides with the solid above it.
  */
 export declare const CEILING_CLAMP_MARGIN = 0.01;
+/** Metres added per level ordinal in Exploded view, also used to frame agent captures. */
+export declare const EXPLODED_GAP = 5;
 /**
  * Stored storey height in meters (floor-to-floor). Falls back to
  * {@link DEFAULT_LEVEL_HEIGHT} for unmigrated legacy levels whose `height`
@@ -22,6 +24,46 @@ export type LevelElevation = {
 };
 export declare function getLevelElevations(nodes: Record<AnyNodeId, AnyNode>): Map<string, LevelElevation>;
 export declare function getAuthoredLevelElevations(nodes: Readonly<Record<string, AnyNode>>): Map<string, LevelElevation>;
+/**
+ * How far under the ground a floor has to sit to be below grade. A ground floor a few centimetres
+ * under the lawn (a basement deeper than it is tall pushes the stack down) stays a ground floor.
+ */
+export declare const BELOW_GRADE_TOLERANCE = 0.3;
+/**
+ * The world Y of `levelId`'s own plane, the one its slabs' `elevation`s are measured from: the
+ * stacked base and the building's height on the site. A floor slab's top is this plus its
+ * elevation. `null` for an id that is no level.
+ */
+export declare function levelPlaneWorldY(nodes: Record<AnyNodeId, AnyNode>, levelId: string): number | null;
+/**
+ * `levelId`'s world floor: the stacked base, the building's height on the site and the top of
+ * the highest slab it stands on. `null` for an id that is no level. A level with floors at
+ * several heights (a split level) has no single floor: this is the highest, and what asks where
+ * the ground stands over a floor asks per slab ({@link levelPlaneWorldY} plus the slab's
+ * elevation).
+ */
+export declare function levelFloorWorldY(nodes: Record<AnyNodeId, AnyNode>, levelId: string): number | null;
+/**
+ * The world Y of the top of the lowest floor slab `levelId` stands on: the floor a pit under the
+ * level has to go down to, the sunken room of a split level included ({@link levelFloorWorldY} is
+ * the highest). The same as `levelFloorWorldY` for a level with one floor, or none. `null` for an
+ * id that is no level.
+ */
+export declare function levelLowestFloorWorldY(nodes: Record<AnyNodeId, AnyNode>, levelId: string): number | null;
+/**
+ * The world Y of the underside of `levelId`'s lowest floor plate, never above the walls' base: the
+ * plane the foundation under the level tops out at, and the one the pit under the hole keeps its
+ * own floor clear of. `null` for an id that is no level.
+ */
+export declare function levelPlateUndersideWorldY(nodes: Record<AnyNodeId, AnyNode>, levelId: string): number | null;
+/**
+ * Whether `levelId` lies wholly below the flat site's grade (Y 0): its standing floor, the highest
+ * of its floor slabs, is under it by more than {@link BELOW_GRADE_TOLERANCE}. The level as a
+ * whole, which is what deriving a building's ground level asks. Sculpted terrain is not consulted,
+ * and neither is a lower floor of a split level: ask `levelGradeStanding`, which judges each floor
+ * against the datum or the terrain. `false` for an id that is no level.
+ */
+export declare function isLevelBelowGrade(nodes: Record<AnyNodeId, AnyNode>, levelId: string): boolean;
 export declare function getLevelFloorToFloorHeight(levelId: string, nodes: Record<AnyNodeId, AnyNode>): number;
 /**
  * The id of the level directly above `levelId` in its own stack (same
@@ -72,14 +114,18 @@ export declare function getCoveringSlabUndersideAt(levelId: string, nodes: Recor
  * edge's orientation (one wall clamped, its neighbor didn't). Boundary
  * contact counts as covered on every side of the slab.
  *
- * This is THE plane for a plane-bound wall (`height` absent). Explicit-height
- * walls ignore the value (`resolveWallTop` returns their stored height), so
- * passing it wherever a raw storey height feeds `resolveWallTop` /
- * `resolveWallEffectiveHeight` is always safe. Falls back to
+ * Use {@link getWallTop} to resolve a wall's top with its elected base and
+ * raw authored storey height, independently of this plane. Falls back to
  * {@link DEFAULT_LEVEL_HEIGHT} when `levelId` doesn't resolve to a level.
  */
 export declare function getWallPlaneTop(wall: Pick<WallNode, 'start' | 'end'> & Partial<Pick<WallNode, 'thickness' | 'curveOffset'>>, levelId: string, nodes: Record<AnyNodeId, AnyNode>): number;
+export declare function getWallTop(wall: WallNode, levelId: string, nodes: Record<AnyNodeId, AnyNode>, electedBase: number): number;
 export declare function getWallCoveringSlabUnderside(wall: Pick<WallNode, 'start' | 'end'> & Partial<Pick<WallNode, 'thickness' | 'curveOffset'>>, levelId: string, nodes: Record<AnyNodeId, AnyNode>): number | null;
+export declare function getWallCoveringSlabs(wall: Pick<WallNode, 'start' | 'end'> & Partial<Pick<WallNode, 'thickness' | 'curveOffset'>>, levelId: string, nodes: Record<AnyNodeId, AnyNode>): Array<{
+    slab: SlabNode;
+    underside: number;
+    top: number;
+}>;
 export declare function getWallPlaneTops(walls: readonly WallNode[], levelId: string, nodes: Record<AnyNodeId, AnyNode>): Map<string, number>;
 /**
  * Upper bound for a ceiling's stored height over `polygon` on `levelId`:

package/dist/services/storey.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storey.d.ts","sourceRoot":"","sources":["../../src/services/storey.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storey.d.ts","sourceRoot":"","sources":["../../src/services/storey.ts"],"names":[],"mappings":"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"}