@pascal-app/core 0.8.0 → 0.9.2

package/dist/systems/fence/fence-spline.js

@@ -0,0 +1,196 @@
+/**
+ * Pure 2D spline sampling for fences whose centerline is defined by a `path`
+ * of control points (the "flying path" curved fence).
+ *
+ * Each control point carries an OUT-handle offset vector. When the user has
+ * not adjusted it, the handle defaults to a distance-aware Catmull-Rom-style
+ * tangent: direction comes from neighbouring points, while length is capped by
+ * the shorter adjacent span. When the user drags a tangent handle (stored in
+ * `tangents[i]`), that point's handle becomes the stored vector and the IN
+ * handle is its mirror, so the curve stays smooth (C1) through the point but
+ * bends to taste. Each span is then a cubic Bézier between consecutive points
+ * using their handles.
+ *
+ * Lives in `@pascal-app/core` and imports NO Three.js — the same `CurveFrame`
+ * shape that `wall-curve.ts` returns (point / tangent / normal) is produced
+ * here so the spline branch is a drop-in for the arc branch in every consumer.
+ */
+const EPSILON = 1e-6;
+const DEFAULT_SEGMENTS_PER_SPAN = 32;
+const TWO_POINT_CURVE_SAGITTA_RATIO = 0.18;
+const TWO_POINT_CURVE_MIN_SAGITTA = 0.18;
+const TWO_POINT_CURVE_MAX_SAGITTA = 1.2;
+export function isSplineFence(fence) {
+    return Array.isArray(fence.path) && fence.path.length >= 2;
+}
+function toPoints(path) {
+    return path.map(([x, y]) => ({ x, y }));
+}
+function distance(a, b) {
+    return Math.hypot(b.x - a.x, b.y - a.y);
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+/**
+ * OUT-handle offset vector for control point `index` — the stored tangent if
+ * the user has adjusted it, otherwise the automatic distance-aware tangent
+ * (endpoints duplicate the neighbour so the ends stay tangent to their single
+ * span). The IN handle is the negation of this.
+ *
+ * Exported so the editing UI can draw the tangent line / handle dots at the
+ * right place even before the user has dragged them.
+ */
+export function getFenceControlHandle(path, tangents, index) {
+    const stored = tangents?.[index];
+    if (stored) {
+        return { x: stored[0], y: stored[1] };
+    }
+    const prev = path[index - 1] ?? path[index];
+    const next = path[index + 1] ?? path[index];
+    const prevDistance = distance({ x: path[index][0], y: path[index][1] }, {
+        x: prev[0],
+        y: prev[1],
+    });
+    const nextDistance = distance({ x: path[index][0], y: path[index][1] }, {
+        x: next[0],
+        y: next[1],
+    });
+    const handleLength = Math.min(prevDistance || nextDistance, nextDistance || prevDistance) / 3;
+    const vx = next[0] - prev[0];
+    const vy = next[1] - prev[1];
+    const len = Math.hypot(vx, vy);
+    if (len < EPSILON || handleLength < EPSILON) {
+        return { x: 0, y: 0 };
+    }
+    return {
+        x: (vx / len) * handleLength,
+        y: (vy / len) * handleLength,
+    };
+}
+export function getTwoPointFenceCurveTangents(path) {
+    if (path.length !== 2)
+        return undefined;
+    const start = path[0];
+    const end = path[1];
+    const dx = end[0] - start[0];
+    const dy = end[1] - start[1];
+    const chordLength = Math.hypot(dx, dy);
+    if (chordLength < EPSILON)
+        return undefined;
+    const tangentX = dx / 3;
+    const tangentY = dy / 3;
+    const normalX = -dy / chordLength;
+    const normalY = dx / chordLength;
+    const sagitta = clamp(chordLength * TWO_POINT_CURVE_SAGITTA_RATIO, TWO_POINT_CURVE_MIN_SAGITTA, TWO_POINT_CURVE_MAX_SAGITTA);
+    const bendX = normalX * sagitta * (4 / 3);
+    const bendY = normalY * sagitta * (4 / 3);
+    return [
+        [tangentX + bendX, tangentY + bendY],
+        [tangentX - bendX, tangentY - bendY],
+    ];
+}
+function cubicBezier(p0, p1, p2, p3, u) {
+    const mu = 1 - u;
+    const a = mu * mu * mu;
+    const b = 3 * mu * mu * u;
+    const c = 3 * mu * u * u;
+    const d = u * u * u;
+    return {
+        x: a * p0.x + b * p1.x + c * p2.x + d * p3.x,
+        y: a * p0.y + b * p1.y + c * p2.y + d * p3.y,
+    };
+}
+function hasAnyTangent(tangents) {
+    return Array.isArray(tangents) && tangents.some((t) => t != null);
+}
+/**
+ * Sample the spline centerline into a polyline. Control points are honored as
+ * on-curve anchors; `segmentsPerSpan` controls smoothness between them.
+ * Returns `(segmentsPerSpan * spanCount) + 1` points, first == path[0],
+ * last == path[-1].
+ */
+export function sampleFenceSpline(path, tangents, segmentsPerSpan = DEFAULT_SEGMENTS_PER_SPAN) {
+    const pts = toPoints(path);
+    if (pts.length === 0)
+        return [];
+    if (pts.length === 1)
+        return [pts[0]];
+    // Two points with no adjusted tangents is a straight segment.
+    if (pts.length === 2 && !hasAnyTangent(tangents))
+        return [pts[0], pts[1]];
+    const steps = Math.max(1, Math.floor(segmentsPerSpan));
+    const result = [pts[0]];
+    for (let i = 0; i < pts.length - 1; i += 1) {
+        const p1 = pts[i];
+        const p2 = pts[i + 1];
+        const outHandle = getFenceControlHandle(path, tangents, i);
+        const nextHandle = getFenceControlHandle(path, tangents, i + 1);
+        // Bézier controls: leave p1 along its OUT handle, arrive at p2 along its
+        // IN handle (= negated OUT handle).
+        const c1 = { x: p1.x + outHandle.x, y: p1.y + outHandle.y };
+        const c2 = { x: p2.x - nextHandle.x, y: p2.y - nextHandle.y };
+        for (let s = 1; s <= steps; s += 1) {
+            result.push(cubicBezier(p1, c1, c2, p2, s / steps));
+        }
+    }
+    return result;
+}
+function frameFromPolyline(points, t) {
+    if (points.length === 0) {
+        return {
+            point: { x: 0, y: 0 },
+            tangent: { x: 1, y: 0 },
+            normal: { x: 0, y: 1 },
+        };
+    }
+    if (points.length === 1) {
+        return {
+            point: points[0],
+            tangent: { x: 1, y: 0 },
+            normal: { x: 0, y: 1 },
+        };
+    }
+    const clamped = clamp01(t);
+    const lastIndex = points.length - 1;
+    const scaled = clamped * lastIndex;
+    const lower = Math.min(lastIndex - 1, Math.floor(scaled));
+    const upper = lower + 1;
+    const localU = scaled - lower;
+    const a = points[lower];
+    const b = points[upper];
+    const point = {
+        x: a.x + (b.x - a.x) * localU,
+        y: a.y + (b.y - a.y) * localU,
+    };
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const len = Math.hypot(dx, dy);
+    const tangent = len < EPSILON ? { x: 1, y: 0 } : { x: dx / len, y: dy / len };
+    return {
+        point,
+        tangent,
+        normal: { x: -tangent.y, y: tangent.x },
+    };
+}
+/**
+ * Frame (point + tangent + normal) at parameter `t` in [0, 1] along the spline
+ * centerline. Same return shape as `getWallCurveFrameAt` so it is a drop-in for
+ * the arc branch. `t` is uniform over the sampled polyline (arc length is not
+ * reparameterised — adequate for marching posts / rails and far cheaper).
+ */
+export function getFenceSplineFrameAt(path, t, tangents, segmentsPerSpan = DEFAULT_SEGMENTS_PER_SPAN) {
+    return frameFromPolyline(sampleFenceSpline(path, tangents, segmentsPerSpan), t);
+}
+/** Total polyline length of the sampled spline centerline. */
+export function getFenceSplineLength(path, tangents, segmentsPerSpan = DEFAULT_SEGMENTS_PER_SPAN) {
+    const points = sampleFenceSpline(path, tangents, segmentsPerSpan);
+    let total = 0;
+    for (let i = 1; i < points.length; i += 1) {
+        total += distance(points[i - 1], points[i]);
+    }
+    return total;
+}

package/dist/systems/fence/fence-spline.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fence-spline.test.d.ts.map

package/dist/systems/fence/fence-spline.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fence-spline.test.d.ts","sourceRoot":"","sources":["../../../src/systems/fence/fence-spline.test.ts"],"names":[],"mappings":""}

package/dist/systems/fence/fence-spline.test.js

@@ -0,0 +1,136 @@
+import { describe, expect, test } from 'bun:test';
+import { getFenceControlHandle, getFenceSplineFrameAt, getFenceSplineLength, getTwoPointFenceCurveTangents, isSplineFence, sampleFenceSpline, } from './fence-spline';
+describe('isSplineFence', () => {
+    test('false without a path or with < 2 points', () => {
+        expect(isSplineFence({ path: undefined })).toBe(false);
+        expect(isSplineFence({ path: [[0, 0]] })).toBe(false);
+    });
+    test('true with >= 2 points', () => {
+        expect(isSplineFence({
+            path: [
+                [0, 0],
+                [1, 0],
+            ],
+        })).toBe(true);
+    });
+});
+describe('sampleFenceSpline', () => {
+    test('honors the control points as on-curve anchors', () => {
+        const path = [
+            [0, 0],
+            [2, 2],
+            [4, 0],
+        ];
+        const sampled = sampleFenceSpline(path, undefined, 8);
+        // First and last sample equal the path endpoints exactly.
+        expect(sampled[0]).toEqual({ x: 0, y: 0 });
+        expect(sampled[sampled.length - 1]).toEqual({ x: 4, y: 0 });
+        // The interior control point is interpolated: some sample lands on (2, 2).
+        const hitsMiddle = sampled.some((p) => Math.hypot(p.x - 2, p.y - 2) < 1e-6);
+        expect(hitsMiddle).toBe(true);
+    });
+    test('two-point path with no tangents is a straight segment', () => {
+        expect(sampleFenceSpline([
+            [0, 0],
+            [3, 0],
+        ], undefined, 8)).toEqual([
+            { x: 0, y: 0 },
+            { x: 3, y: 0 },
+        ]);
+    });
+    test('a stored tangent bends an otherwise straight two-point span', () => {
+        const path = [
+            [0, 0],
+            [4, 0],
+        ];
+        // Pull the first point's handle up — the span should bow off the X axis.
+        const sampled = sampleFenceSpline(path, [[0, 2], null], 12);
+        expect(sampled[0]).toEqual({ x: 0, y: 0 });
+        expect(sampled[sampled.length - 1]).toEqual({ x: 4, y: 0 });
+        const maxY = Math.max(...sampled.map((p) => Math.abs(p.y)));
+        expect(maxY).toBeGreaterThan(0.1);
+    });
+    test('generated two-point curve tangents create a gentle arc', () => {
+        const path = [
+            [0, 0],
+            [4, 0],
+        ];
+        const sampled = sampleFenceSpline(path, getTwoPointFenceCurveTangents(path), 16);
+        expect(sampled[0]).toEqual({ x: 0, y: 0 });
+        expect(sampled[sampled.length - 1]).toEqual({ x: 4, y: 0 });
+        const maxY = Math.max(...sampled.map((p) => p.y));
+        expect(maxY).toBeGreaterThan(0.4);
+    });
+    test('produces a smooth (no-cusp) curve on uneven spacing', () => {
+        const path = [
+            [0, 0],
+            [1, 0.2],
+            [5, 0.3],
+            [6, 0],
+        ];
+        const sampled = sampleFenceSpline(path, undefined, 16);
+        let maxTurn = 0;
+        for (let i = 2; i < sampled.length; i += 1) {
+            const a = sampled[i - 2];
+            const b = sampled[i - 1];
+            const c = sampled[i];
+            const t1 = Math.atan2(b.y - a.y, b.x - a.x);
+            const t2 = Math.atan2(c.y - b.y, c.x - b.x);
+            let d = Math.abs(t2 - t1);
+            if (d > Math.PI)
+                d = 2 * Math.PI - d;
+            maxTurn = Math.max(maxTurn, d);
+        }
+        expect(maxTurn).toBeLessThan(Math.PI / 2);
+    });
+});
+describe('getFenceControlHandle', () => {
+    test('returns the stored tangent when present', () => {
+        expect(getFenceControlHandle([
+            [0, 0],
+            [4, 0],
+        ], [[1, 2], null], 0)).toEqual({ x: 1, y: 2 });
+    });
+    test('falls back to the automatic distance-aware tangent', () => {
+        const path = [
+            [0, 0],
+            [3, 0],
+            [6, 0],
+        ];
+        expect(getFenceControlHandle(path, undefined, 1)).toEqual({ x: 1, y: 0 });
+    });
+});
+describe('getFenceSplineFrameAt', () => {
+    const path = [
+        [0, 0],
+        [2, 0],
+        [4, 0],
+    ];
+    test('t=0 / t=1 land on the endpoints', () => {
+        expect(getFenceSplineFrameAt(path, 0).point).toEqual({ x: 0, y: 0 });
+        expect(getFenceSplineFrameAt(path, 1).point).toEqual({ x: 4, y: 0 });
+    });
+    test('returns a unit tangent and perpendicular normal', () => {
+        const frame = getFenceSplineFrameAt(path, 0.5);
+        expect(Math.hypot(frame.tangent.x, frame.tangent.y)).toBeCloseTo(1, 5);
+        const dot = frame.tangent.x * frame.normal.x + frame.tangent.y * frame.normal.y;
+        expect(dot).toBeCloseTo(0, 5);
+    });
+});
+describe('getFenceSplineLength', () => {
+    test('roughly matches the straight distance for a straight path', () => {
+        expect(getFenceSplineLength([
+            [0, 0],
+            [3, 4],
+        ], undefined, 8)).toBeCloseTo(5, 5);
+    });
+    test('a curved path is longer than its endpoint chord', () => {
+        const path = [
+            [0, 0],
+            [2, 2],
+            [4, 0],
+        ];
+        const chord = Math.hypot(4, 0);
+        expect(getFenceSplineLength(path, undefined, 16)).toBeGreaterThan(chord);
+    });
+});

package/dist/systems/stair/stair-footprint.d.ts

@@ -0,0 +1,44 @@
+import type { AnyNode, StairNode, StairSegmentNode } from '../../schema';
+/**
+ * Stair footprint geometry shared by the slab-opening sync and the
+ * alignment-anchor adapters. A stair has no single box footprint: straight
+ * stairs are a cumulative chain of `stair-segment` children, curved / spiral
+ * stairs are an annular sector stored entirely on the parent. Both reduce to
+ * an XZ bounding box here so callers that only need "where does the stair sit
+ * in plan" (alignment guides) don't have to re-walk the geometry.
+ *
+ * All math is in the building-local XZ frame, matching `node.position`.
+ */
+export type StairFootprintAABB = {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+};
+type SegmentTransform = {
+    position: [number, number, number];
+    rotation: number;
+};
+/**
+ * XZ rotation in the stair geometry convention (equivalent to rotating by
+ * `-angle` in standard math): positive `angle` turns local +Z toward +X. Every
+ * stair helper — slab openings, floor-plan emitter, this footprint — shares it,
+ * so anchors line up with the rendered stair.
+ */
+export declare function rotateXZ(x: number, z: number, angle: number): [number, number];
+/**
+ * Cumulative per-segment transforms for a straight (segment-chained) stair.
+ * Each flight attaches to the previous segment's end; `attachmentSide` rotates
+ * the chain ±90° (left / right) or continues straight (front). Positions are in
+ * the stair's local frame (before the stair's own `position` / `rotation`).
+ */
+export declare function computeSegmentTransforms(segments: StairSegmentNode[]): SegmentTransform[];
+/**
+ * XZ bounding box of a stair's plan footprint, or null when it can't be
+ * determined (a straight stair whose segment children aren't in `nodes`).
+ * Straight stairs need the children to walk the flight chain; curved / spiral
+ * stairs are derived from the parent alone, so `nodes` is optional for them.
+ */
+export declare function stairFootprintAABB(stair: StairNode, nodes?: Readonly<Record<string, AnyNode>>): StairFootprintAABB | null;
+export {};
+//# sourceMappingURL=stair-footprint.d.ts.map

package/dist/systems/stair/stair-footprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stair-footprint.d.ts","sourceRoot":"","sources":["../../../src/systems/stair/stair-footprint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAa,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAEnF;;;;;;;;;GASG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3F,KAAK,gBAAgB,GAAG;IACtB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAI9E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAkDzF;AAwHD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,kBAAkB,GAAG,IAAI,CAK3B"}

package/dist/systems/stair/stair-footprint.js

@@ -0,0 +1,178 @@
+/**
+ * XZ rotation in the stair geometry convention (equivalent to rotating by
+ * `-angle` in standard math): positive `angle` turns local +Z toward +X. Every
+ * stair helper — slab openings, floor-plan emitter, this footprint — shares it,
+ * so anchors line up with the rendered stair.
+ */
+export function rotateXZ(x, z, angle) {
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    return [x * cos + z * sin, -x * sin + z * cos];
+}
+/**
+ * Cumulative per-segment transforms for a straight (segment-chained) stair.
+ * Each flight attaches to the previous segment's end; `attachmentSide` rotates
+ * the chain ±90° (left / right) or continues straight (front). Positions are in
+ * the stair's local frame (before the stair's own `position` / `rotation`).
+ */
+export function computeSegmentTransforms(segments) {
+    const transforms = [];
+    let currentX = 0;
+    let currentY = 0;
+    let currentZ = 0;
+    let currentRot = 0;
+    for (let index = 0; index < segments.length; index++) {
+        const segment = segments[index];
+        if (!segment)
+            continue;
+        if (index === 0) {
+            transforms.push({ position: [currentX, currentY, currentZ], rotation: currentRot });
+            continue;
+        }
+        const previous = segments[index - 1];
+        if (!previous)
+            continue;
+        let attachX = 0;
+        let attachZ = 0;
+        let rotationDelta = 0;
+        switch (segment.attachmentSide) {
+            case 'front':
+                attachX = 0;
+                attachZ = previous.length;
+                break;
+            case 'left':
+                attachX = previous.width / 2;
+                attachZ = previous.length / 2;
+                rotationDelta = Math.PI / 2;
+                break;
+            case 'right':
+                attachX = -previous.width / 2;
+                attachZ = previous.length / 2;
+                rotationDelta = -Math.PI / 2;
+                break;
+        }
+        const [deltaX, deltaZ] = rotateXZ(attachX, attachZ, currentRot);
+        currentX += deltaX;
+        currentY += previous.height;
+        currentZ += deltaZ;
+        currentRot += rotationDelta;
+        transforms.push({ position: [currentX, currentY, currentZ], rotation: currentRot });
+    }
+    return transforms;
+}
+function emptyBox() {
+    return {
+        minX: Number.POSITIVE_INFINITY,
+        minZ: Number.POSITIVE_INFINITY,
+        maxX: Number.NEGATIVE_INFINITY,
+        maxZ: Number.NEGATIVE_INFINITY,
+    };
+}
+/** Grow `box` to include the world-plan point produced by rotating the
+ *  stair-local point by the stair's rotation and offsetting by its position. */
+function extendByLocal(box, stair, localX, localZ) {
+    const [wx, wz] = rotateXZ(localX, localZ, stair.rotation ?? 0);
+    const x = stair.position[0] + wx;
+    const z = stair.position[2] + wz;
+    if (x < box.minX)
+        box.minX = x;
+    if (x > box.maxX)
+        box.maxX = x;
+    if (z < box.minZ)
+        box.minZ = z;
+    if (z > box.maxZ)
+        box.maxZ = z;
+}
+function finiteBox(box) {
+    return Number.isFinite(box.minX) && Number.isFinite(box.minZ) ? box : null;
+}
+/** Bounding box of a straight stair's segment chain, walking the children. */
+function straightStairAABB(stair, nodes) {
+    const segments = (stair.children ?? [])
+        .map((childId) => nodes[childId])
+        .filter((segment) => segment?.type === 'stair-segment' && segment.visible !== false);
+    if (segments.length === 0)
+        return null;
+    const transforms = computeSegmentTransforms(segments);
+    const box = emptyBox();
+    segments.forEach((segment, index) => {
+        const transform = transforms[index];
+        if (!transform)
+            return;
+        const halfWidth = segment.width / 2;
+        // Segment-local footprint: X across the flight, Z along the run from the
+        // attachment edge (0) to the far edge (length).
+        for (const [cornerX, cornerZ] of [
+            [-halfWidth, 0],
+            [halfWidth, 0],
+            [halfWidth, segment.length],
+            [-halfWidth, segment.length],
+        ]) {
+            const [offsetX, offsetZ] = rotateXZ(cornerX, cornerZ, transform.rotation);
+            extendByLocal(box, stair, transform.position[0] + offsetX, transform.position[2] + offsetZ);
+        }
+    });
+    return finiteBox(box);
+}
+const ARC_SAMPLES = 48;
+function getSpiralLandingSweep(stair, sweepAngle) {
+    if ((stair.topLandingMode ?? 'none') !== 'integrated')
+        return 0;
+    const innerRadius = Math.max(0.05, stair.innerRadius ?? 0.9);
+    const width = Math.max(stair.width ?? 1, 0.4);
+    const landingDepth = Math.max(0.3, stair.topLandingDepth ?? Math.max(width * 0.9, 0.8));
+    return (Math.min(Math.PI * 0.75, landingDepth / Math.max(innerRadius + width / 2, 0.1)) *
+        Math.sign(sweepAngle || 1));
+}
+/** Bounding box of a curved / spiral stair's annular sector (plus the
+ *  integrated spiral top landing when present). */
+function arcStairAABB(stair) {
+    const isSpiral = stair.stairType === 'spiral';
+    const minInnerRadius = isSpiral ? 0.05 : 0.2;
+    const innerRadius = Math.max(minInnerRadius, stair.innerRadius ?? (isSpiral ? 0.2 : 0.9));
+    const width = Math.max(stair.width ?? 1, 0.4);
+    const outerRadius = innerRadius + width;
+    const rawSweep = stair.sweepAngle ?? (isSpiral ? Math.PI * 2 : Math.PI / 2);
+    let sweep = rawSweep;
+    // A full revolution would make the arc degenerate; clamp just under 2π the
+    // same way the floor-plan emitter does so the sampled box stays correct.
+    if (Math.abs(sweep) >= Math.PI * 2)
+        sweep = Math.sign(sweep || 1) * (Math.PI * 2 - 0.001);
+    const half = sweep / 2;
+    const box = emptyBox();
+    // Sample both rims across the sweep — the extremes can fall on either the
+    // arc ends or an axis crossing in between, so we need the full sweep.
+    for (let step = 0; step <= ARC_SAMPLES; step += 1) {
+        const angle = -half + (sweep * step) / ARC_SAMPLES;
+        const cos = Math.cos(angle);
+        const sin = Math.sin(angle);
+        extendByLocal(box, stair, cos * innerRadius, sin * innerRadius);
+        extendByLocal(box, stair, cos * outerRadius, sin * outerRadius);
+    }
+    // Integrated spiral top landing renders as an angular extension of the
+    // annular stair body, not as a rectangular box outside the outer rim.
+    if (isSpiral && stair.topLandingMode === 'integrated') {
+        const landingSweep = getSpiralLandingSweep(stair, rawSweep);
+        const landingSteps = Math.max(1, Math.ceil(Math.abs(landingSweep) / (Math.PI / 24)));
+        for (let step = 0; step <= landingSteps; step += 1) {
+            const angle = rawSweep / 2 + (landingSweep * step) / landingSteps;
+            const cos = Math.cos(angle);
+            const sin = Math.sin(angle);
+            extendByLocal(box, stair, cos * innerRadius, sin * innerRadius);
+            extendByLocal(box, stair, cos * outerRadius, sin * outerRadius);
+        }
+    }
+    return finiteBox(box);
+}
+/**
+ * XZ bounding box of a stair's plan footprint, or null when it can't be
+ * determined (a straight stair whose segment children aren't in `nodes`).
+ * Straight stairs need the children to walk the flight chain; curved / spiral
+ * stairs are derived from the parent alone, so `nodes` is optional for them.
+ */
+export function stairFootprintAABB(stair, nodes) {
+    if ((stair.stairType ?? 'straight') === 'straight') {
+        return nodes ? straightStairAABB(stair, nodes) : null;
+    }
+    return arcStairAABB(stair);
+}