@pascal-app/core 1.0.3 → 1.0.4

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

@@ -0,0 +1,255 @@
+import { StairDesignTargets } from '../../schema/nodes/stair.js';
+import { measureStairHeadroom } from './stair-clearance.js';
+import { resolveStairConstruction } from './stair-construction.js';
+import { measureStairDetail } from './stair-detail-budget.js';
+import { createDefaultStairSegment, createStairFlightFromStair, } from './stair-flight.js';
+import { resolveStairArcDimensions } from './stair-layout.js';
+import { resolveStairRailPaths } from './stair-rail-path.js';
+import { resolveStairTotalRise } from './stair-rise-query.js';
+import { resolveStairWinder } from './stair-winder.js';
+export const DEFAULT_STAIR_DESIGN_TARGETS = StairDesignTargets.parse({});
+export function planStairSizing(rise, options = {}) {
+    const targets = StairDesignTargets.parse(options.targets ?? {});
+    if (!(Number.isFinite(rise) && rise > 0))
+        throw new RangeError('Rise must be positive');
+    const ratio = rise / targets.maxRiserHeight;
+    const stepCount = options.stepCount ?? Math.max(2, Math.ceil(ratio - Number.EPSILON * ratio));
+    if (!Number.isSafeInteger(stepCount) || stepCount < 2)
+        throw new RangeError('Use at least two whole risers');
+    const length = options.runLength ?? stepCount * Math.max(targets.minimumGoing, targets.targetGoing);
+    if (!(Number.isFinite(length) && length > 0))
+        throw new RangeError('Run must be positive');
+    return { stepCount, length, riserHeight: rise / stepCount, going: length / stepCount };
+}
+export function createSizedStairFlight(rise, overrides = {}, targets) {
+    const sizing = planStairSizing(rise, {
+        stepCount: overrides.stepCount,
+        runLength: overrides.length,
+        targets,
+    });
+    return createDefaultStairSegment({
+        ...overrides,
+        height: rise,
+        length: sizing.length,
+        stepCount: sizing.stepCount,
+    });
+}
+/** Resolves support and arrival against each proposed run before returning a new flight. */
+export function planStairCreation(stair, nodes, dimensions = {}, baseElevation) {
+    const resolveRise = (candidate, prospective) => resolveStairTotalRise(candidate, prospective, baseElevation === undefined ? undefined : () => baseElevation);
+    let flight = createSizedStairFlight(resolveRise({ ...stair, children: [] }, nodes), dimensions, stair.designTargets);
+    for (let iteration = 0;; iteration++) {
+        const candidate = { ...stair, stepCount: flight.stepCount, children: [flight.id] };
+        const rise = resolveRise(candidate, {
+            ...nodes,
+            [candidate.id]: candidate,
+            [flight.id]: { ...flight, parentId: candidate.id },
+        });
+        if (Math.abs(rise - flight.height) < 1e-6)
+            return { stair: candidate, flight };
+        if (iteration === 15)
+            throw new RangeError('Stair support and arrival do not converge; choose an explicit rise or run');
+        flight = { ...createSizedStairFlight(rise, dimensions, stair.designTargets), id: flight.id };
+    }
+}
+export function measureStair(stair, nodes) {
+    const totalRise = resolveStairTotalRise(stair, nodes);
+    const targets = stair.designTargets ?? DEFAULT_STAIR_DESIGN_TARGETS;
+    const diagnostics = [];
+    const report = (code, nodeId, message, severity = 'warning') => diagnostics.push({ code, severity, nodeId, message });
+    if (!(totalRise > 0))
+        report('invalid-rise', stair.id, 'The destination must be above the stair base.', 'error');
+    const arc = resolveStairArcDimensions(stair, totalRise);
+    if (stair.stairType === 'spiral' &&
+        stair.topLandingMode === 'integrated' &&
+        stair.topLandingDepth > 2 * Math.PI * arc.walkingRadius)
+        report('landing-overlap', stair.id, 'Landing depth exceeds a full circle at the walking line; the visible landing is limited to one circle.');
+    const segments = stair.children
+        .map((id) => nodes[id])
+        .filter((node) => node?.type === 'stair-segment');
+    const segmentsById = new Map(segments.map((segment) => [segment.id, segment]));
+    const detail = measureStairDetail(stair, segments);
+    if (detail.error)
+        report('geometry-unresolved', stair.id, detail.error, 'error');
+    const flights = stair.stairType !== 'straight'
+        ? [
+            {
+                nodeId: stair.id,
+                count: arc.stepCount,
+                rise: totalRise,
+                length: Math.abs(arc.sweepAngle) * arc.walkingRadius,
+                width: arc.width,
+                innerGoing: Math.abs(arc.stepSweep) * arc.innerRadius,
+            },
+        ]
+        : (segments.length
+            ? segments.filter((segment) => segment.segmentType === 'stair')
+            : [createStairFlightFromStair(stair, nodes)]).map((segment) => {
+            let winder = null;
+            try {
+                winder = resolveStairWinder(segment);
+            }
+            catch (error) {
+                report('invalid-winder', segment.id, error instanceof Error ? error.message : String(error), 'error');
+            }
+            if (winder && winder.narrowEndGoing < 0.1)
+                report('narrow-winder-end', segment.id, 'The narrow end of a winder tread is below 0.10 m; check the intended stair use.');
+            return {
+                nodeId: segments.length ? segment.id : stair.id,
+                count: segment.stepCount,
+                rise: segment.height,
+                length: winder
+                    ? 2 * (segment.winder.innerGap + segment.winder.walkingLineOffset)
+                    : segment.length,
+                ...(winder ? { minimumGoing: winder.going } : {}),
+                width: segment.width,
+                innerGoing: winder?.narrowEndGoing ?? null,
+            };
+        });
+    const measurements = flights.map((flight) => {
+        const valid = Number.isInteger(flight.count) &&
+            flight.count > 0 &&
+            flight.length > 0 &&
+            flight.rise > 0 &&
+            flight.width > 0;
+        if (!valid)
+            report('invalid-flight', flight.nodeId, 'Flight dimensions and integer riser count must be positive.', 'error');
+        const riserHeight = valid ? flight.rise / flight.count : null;
+        const going = valid
+            ? 'minimumGoing' in flight
+                ? (flight.minimumGoing ?? flight.length / flight.count)
+                : flight.length / flight.count
+            : null;
+        if (riserHeight !== null && riserHeight > targets.maxRiserHeight + 1e-6)
+            report('riser-target', flight.nodeId, 'Riser height exceeds the design target.');
+        if (going !== null && going < targets.minimumGoing - 1e-6)
+            report('going-target', flight.nodeId, 'Going is below the design target.');
+        const comfort = riserHeight !== null && going !== null ? 2 * riserHeight + going : null;
+        if (comfort !== null && (comfort < 0.6 || comfort > 0.65))
+            report('comfort-target', flight.nodeId, 'Two risers plus going is outside the 0.60–0.65 m design range.');
+        return {
+            ...flight,
+            construction: resolveStairConstruction(segmentsById.get(flight.nodeId) ?? stair, stair),
+            riserHeight,
+            going,
+            comfort,
+            slope: valid ? Math.atan2(flight.rise, flight.length) : null,
+        };
+    });
+    const risers = measurements.flatMap((flight) => flight.riserHeight === null ? [] : [flight.riserHeight]);
+    const uniformity = risers.length ? Math.max(...risers) - Math.min(...risers) : 0;
+    if (uniformity > 1e-4)
+        report('nonuniform-risers', stair.id, 'Flight riser heights differ. Use uniform-riser repair only if this is a proposed design.');
+    for (const landing of segments.filter((segment) => stair.stairType === 'straight' && segment.segmentType === 'landing' && segment.height !== 0))
+        report('raised-landing', landing.id, 'A landing has a stored rise; inspect its transition before repair.');
+    const chainRise = segments.reduce((sum, segment) => sum + segment.height, 0);
+    if (stair.stairType === 'straight' && segments.length && Math.abs(chainRise - totalRise) > 1e-4)
+        report('arrival-mismatch', stair.id, 'The flight chain does not reach the declared destination.');
+    const headroom = measureStairHeadroom(stair, nodes);
+    if (headroom.status === 'unresolved')
+        report('headroom-unresolved', stair.id, 'Detailed headroom could not be evaluated: check riser counts and the surface query budget.');
+    else if (headroom.obstructions.length)
+        report('headroom-target', stair.id, 'Overhead surfaces leave less than the target headroom.');
+    return {
+        totalRise,
+        targets,
+        detail,
+        headroom,
+        railings: {
+            layout: segments.some((segment) => segment.winder) ||
+                stair.railingStyle === 'glass' ||
+                stair.railingStyle === 'metal'
+                ? 'continuous'
+                : (stair.railingPath ?? 'original'),
+            style: stair.railingStyle ?? 'balusters',
+            guardHeight: stair.railingHeight,
+            handrail: stair.handrail ?? null,
+            paths: detail.error
+                ? null
+                : segments.some((segment) => segment.winder) ||
+                    stair.railingPath === 'continuous' ||
+                    stair.railingStyle === 'glass' ||
+                    stair.railingStyle === 'metal'
+                    ? resolveStairRailPaths(stair, nodes).map((path) => ({
+                        side: path.side,
+                        nodeIds: path.nodeIds,
+                        length: path.points
+                            .slice(1)
+                            .reduce((sum, point, i) => sum +
+                            Math.hypot(point[0] - path.points[i][0], point[1] - path.points[i][1], point[2] - path.points[i][2]), 0),
+                    }))
+                    : null,
+        },
+        flights: measurements,
+        riserCount: flights.reduce((sum, flight) => sum + flight.count, 0),
+        uniformity,
+        diagnostics,
+    };
+}
+/** Explicit repair; existing measured flight proportions remain untouched until requested. */
+export function planStairSizingEdit(stair, nodes, fitRun = false) {
+    const rise = resolveStairTotalRise(stair, nodes);
+    const targets = stair.designTargets ?? DEFAULT_STAIR_DESIGN_TARGETS;
+    const updates = [];
+    if (stair.stairType !== 'straight') {
+        const sizing = planStairSizing(rise, { targets });
+        const arc = resolveStairArcDimensions(stair, rise);
+        updates.push({
+            id: stair.id,
+            data: {
+                stepCount: sizing.stepCount,
+                uniformRisers: true,
+                ...(fitRun
+                    ? { sweepAngle: (Math.sign(arc.sweepAngle || 1) * sizing.length) / arc.walkingRadius }
+                    : {}),
+            },
+        });
+        return updates;
+    }
+    const segments = stair.children
+        .map((id) => nodes[id])
+        .filter((node) => node?.type === 'stair-segment');
+    const flights = segments.filter((segment) => segment.segmentType === 'stair');
+    if (segments.length && !flights.length)
+        throw new RangeError('Add a flight before sizing a stair with only landings');
+    const flightRise = rise -
+        segments
+            .filter((segment) => segment.segmentType === 'landing')
+            .reduce((sum, segment) => sum + segment.height, 0);
+    const sizing = planStairSizing(flightRise, { targets });
+    if (!flights.length) {
+        if (fitRun)
+            throw new RangeError('Add a flight before fitting the run');
+        return [{ id: stair.id, data: { stepCount: sizing.stepCount, uniformRisers: true } }];
+    }
+    const count = Math.max(2 * flights.length, sizing.stepCount);
+    const available = count - 2 * flights.length;
+    const run = (flight) => flight.winder ? 2 * (flight.winder.innerGap + flight.winder.walkingLineOffset) : flight.length;
+    for (const flight of flights)
+        resolveStairWinder(flight);
+    const weight = flights.reduce((sum, flight) => sum + Math.max(0, run(flight)), 0);
+    const shares = flights.map((flight, index) => ({
+        index,
+        value: weight ? (available * Math.max(0, run(flight))) / weight : available / flights.length,
+    }));
+    const counts = shares.map((share) => 2 + Math.floor(share.value));
+    let remaining = count - counts.reduce((sum, value) => sum + value, 0);
+    for (const share of [...shares].sort((a, b) => (b.value % 1) - (a.value % 1))) {
+        if (remaining-- <= 0)
+            break;
+        counts[share.index] += 1;
+    }
+    updates.push({ id: stair.id, data: { uniformRisers: true, stepCount: count } });
+    for (const [index, flight] of flights.entries()) {
+        const stepCount = counts[index];
+        updates.push({
+            id: flight.id,
+            data: {
+                stepCount,
+                height: (flightRise * stepCount) / count,
+                ...(fitRun && !flight.winder ? { length: stepCount * sizing.going } : {}),
+            },
+        });
+    }
+    return updates;
+}

package/dist/systems/stair/stair-sweep-edit.d.ts

@@ -0,0 +1,7 @@
+import type { StairNode } from '../../schema/index.js';
+/** Keep the opposite arrival/entry edge fixed, and preserve winding at the zero-sweep limit. */
+export declare function planStairSweepEdit(stair: Pick<StairNode, 'sweepAngle' | 'rotation'>, delta: number, end: 'start' | 'end'): {
+    sweepAngle: number;
+    rotation: number;
+};
+//# sourceMappingURL=stair-sweep-edit.d.ts.map

package/dist/systems/stair/stair-sweep-edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stair-sweep-edit.d.ts","sourceRoot":"","sources":["../../../src/systems/stair/stair-sweep-edit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE7C,gGAAgG;AAChG,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,UAAU,CAAC,EACjD,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,OAAO,GAAG,KAAK;;;EAOrB"}

package/dist/systems/stair/stair-sweep-edit.js

@@ -0,0 +1,8 @@
+/** Keep the opposite arrival/entry edge fixed, and preserve winding at the zero-sweep limit. */
+export function planStairSweepEdit(stair, delta, end) {
+    const sign = Math.sign(stair.sweepAngle) || 1;
+    const target = stair.sweepAngle + (end === 'end' ? delta : -delta);
+    const sweepAngle = sign * Math.max(0.0001, sign * target);
+    const change = sweepAngle - stair.sweepAngle;
+    return { sweepAngle, rotation: stair.rotation + (end === 'end' ? -change / 2 : change / 2) };
+}

package/dist/systems/stair/stair-walking-line.d.ts

@@ -0,0 +1,5 @@
+import type { StairNode, StairSegmentNode } from '../../schema/index.js';
+export type StairWalkingPoint = [number, number, number];
+/** Ideal ascent line in stair-local coordinates; hidden segments break the displayed path. */
+export declare function resolveStairWalkingPaths(stair: StairNode, segments: readonly StairSegmentNode[], totalRise: number): StairWalkingPoint[][];
+//# sourceMappingURL=stair-walking-line.d.ts.map

package/dist/systems/stair/stair-walking-line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stair-walking-line.d.ts","sourceRoot":"","sources":["../../../src/systems/stair/stair-walking-line.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAK/D,MAAM,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAExD,8FAA8F;AAC9F,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,SAAS,EAAE,MAAM,GAChB,iBAAiB,EAAE,EAAE,CA4FvB"}

package/dist/systems/stair/stair-walking-line.js

@@ -0,0 +1,91 @@
+import { computeSegmentTransforms, rotateXZ } from './stair-footprint.js';
+import { resolveStairArcDimensions } from './stair-layout.js';
+import { resolveStairWinder } from './stair-winder.js';
+/** Ideal ascent line in stair-local coordinates; hidden segments break the displayed path. */
+export function resolveStairWalkingPaths(stair, segments, totalRise) {
+    if (stair.visible === false)
+        return [];
+    if (stair.stairType !== 'straight') {
+        const layout = resolveStairArcDimensions(stair, totalRise);
+        if (!Number.isFinite(layout.sweepAngle))
+            return [];
+        // A presentation budget coarsens exceptionally long arcs without truncating their sweep.
+        const samples = Math.max(2, Math.min(10_000, Math.ceil(Math.abs(layout.sweepAngle) / (Math.PI / 60))));
+        const points = Array.from({ length: samples + 1 }, (_, index) => {
+            const t = index / samples;
+            const angle = -layout.sweepAngle / 2 + t * layout.sweepAngle;
+            return [
+                Math.cos(angle) * layout.walkingRadius,
+                t * totalRise,
+                Math.sin(angle) * layout.walkingRadius,
+            ];
+        });
+        if (layout.landingSweep) {
+            const landingSamples = Math.max(2, Math.ceil(Math.abs(layout.landingSweep) / (Math.PI / 60)));
+            for (let index = 1; index <= landingSamples; index++) {
+                const angle = layout.sweepAngle / 2 + (layout.landingSweep * index) / landingSamples;
+                points.push([
+                    Math.cos(angle) * layout.walkingRadius,
+                    totalRise,
+                    Math.sin(angle) * layout.walkingRadius,
+                ]);
+            }
+        }
+        return [points];
+    }
+    const chain = segments.length
+        ? segments
+        : [
+            {
+                width: stair.width,
+                length: 3,
+                height: totalRise,
+                attachmentSide: 'front',
+                segmentType: 'stair',
+                visible: true,
+            },
+        ];
+    const transforms = computeSegmentTransforms(chain);
+    const paths = [];
+    let current = [];
+    const flush = () => {
+        if (current.length > 1)
+            paths.push(current);
+        current = [];
+    };
+    for (const [index, segment] of chain.entries()) {
+        if (segment.visible === false) {
+            flush();
+            continue;
+        }
+        const transform = transforms[index];
+        const point = (x, y, z) => {
+            const [dx, dz] = rotateXZ(x, z, transform.rotation);
+            return [transform.position[0] + dx, transform.position[1] + y, transform.position[2] + dz];
+        };
+        const winder = 'winder' in segment ? resolveStairWinder(segment) : null;
+        if (winder) {
+            const points = winder.walkingLine.map(([x, y, z]) => point(x, y, z));
+            const first = points[0];
+            if (current.length && Math.hypot(...first.map((v, i) => v - current.at(-1)[i])) > 1e-8)
+                flush();
+            current.push(...points);
+            continue;
+        }
+        const start = point(0, segment.segmentType === 'landing' ? segment.height : 0, 0);
+        if (!current.length ||
+            Math.hypot(...start.map((value, axis) => value - current.at(-1)[axis])) > 1e-8) {
+            flush();
+            current.push(start);
+        }
+        if (segment.segmentType === 'landing') {
+            current.push(point(0, segment.height, segment.length / 2));
+            const nextSide = chain[index + 1]?.attachmentSide ?? 'front';
+            current.push(point(nextSide === 'left' ? segment.width / 2 : nextSide === 'right' ? -segment.width / 2 : 0, segment.height, nextSide === 'front' ? segment.length : segment.length / 2));
+        }
+        else
+            current.push(point(0, segment.height, segment.length));
+    }
+    flush();
+    return paths;
+}

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

@@ -0,0 +1,36 @@
+import type { StairNode, StairSegmentNode } from '../../schema/index.js';
+export type StairWinderPoint = [number, number];
+export type StairWinderLayout = {
+    treads: {
+        polygon: StairWinderPoint[];
+        elevation: number;
+        startStation: number;
+        endStation: number;
+        startAngle: number;
+        endAngle: number;
+    }[];
+    footprint: StairWinderPoint[];
+    walkingLine: [number, number, number][];
+    innerBoundary: [number, number, number][];
+    outerBoundary: [number, number, number][];
+    exit: {
+        position: [number, number, number];
+        rotation: number;
+    };
+    going: number;
+    narrowEndGoing: number;
+};
+/** A square-ring quarter turn: tread rays meet square rims, including their corner. */
+export declare function resolveStairWinder(segment: Pick<StairSegmentNode, 'width' | 'height' | 'stepCount' | 'winder'>): StairWinderLayout | null;
+export type StairWinderConstructionPiece = {
+    role: 'tread' | 'body';
+    walkingTop: boolean;
+    index: number;
+    polygon: StairWinderPoint[];
+    bottom: number[];
+    top: number;
+};
+/** Polygon prisms share the exact walking footprint; structure stays below its finished top. */
+export declare function resolveWinderStairConstruction(segment: StairSegmentNode, absoluteHeight?: number, parent?: StairNode): StairWinderConstructionPiece[] | null;
+export declare function resolveStairWinderFootprint(segment: StairSegmentNode, parent?: StairNode): StairWinderPoint[] | null;
+//# sourceMappingURL=stair-winder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stair-winder.d.ts","sourceRoot":"","sources":["../../../src/systems/stair/stair-winder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/D,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAC/C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE;QACN,OAAO,EAAE,gBAAgB,EAAE,CAAA;QAC3B,SAAS,EAAE,MAAM,CAAA;QACjB,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,MAAM,CAAA;KACjB,EAAE,CAAA;IACH,SAAS,EAAE,gBAAgB,EAAE,CAAA;IAC7B,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;IACvC,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;IACzC,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;IACzC,IAAI,EAAE;QAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC,GAC3E,iBAAiB,GAAG,IAAI,CAqF1B;AAED,MAAM,MAAM,4BAA4B,GAAG;IACzC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAA;IACtB,UAAU,EAAE,OAAO,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,gGAAgG;AAChG,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,gBAAgB,EACzB,cAAc,SAAI,EAClB,MAAM,CAAC,EAAE,SAAS,GACjB,4BAA4B,EAAE,GAAG,IAAI,CA6HvC;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,SAAS,GACjB,gBAAgB,EAAE,GAAG,IAAI,CAW3B"}

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

@@ -0,0 +1,173 @@
+/** A square-ring quarter turn: tread rays meet square rims, including their corner. */
+export function resolveStairWinder(segment) {
+    if (!segment.winder)
+        return null;
+    const { innerGap: gap, walkingLineOffset: offset, turn, division } = segment.winder;
+    const { width, height, stepCount: count } = segment;
+    if (!(Number.isFinite(width) &&
+        width > 0 &&
+        Number.isFinite(height) &&
+        height > 0 &&
+        Number.isInteger(count) &&
+        count > 0 &&
+        count <= 10000))
+        throw new RangeError('Winders require positive dimensions and 1–10,000 whole risers.');
+    if (!(Number.isFinite(gap) && gap >= 0 && Number.isFinite(offset) && offset > 0 && offset <= width))
+        throw new RangeError('The winder walking line must lie within the flight width.');
+    const radius = gap + offset;
+    const outer = gap + width;
+    const sign = turn === 'left' ? -1 : 1;
+    // Pivot lies beside the entry. Travel starts along +Z and ends toward the turn.
+    const point = (r, angle) => {
+        const scale = r / Math.max(Math.cos(angle), Math.sin(angle));
+        return [sign * (gap + width / 2 - scale * Math.cos(angle)), scale * Math.sin(angle)];
+    };
+    const stationAngle = (station) => station <= radius ? Math.atan2(station, radius) : Math.atan2(radius, 2 * radius - station);
+    const angleStation = (angle) => angle <= Math.PI / 4 ? radius * Math.tan(angle) : 2 * radius - radius / Math.tan(angle);
+    const angles = Array.from({ length: count + 1 }, (_, index) => division === 'equal-angle'
+        ? ((index / count) * Math.PI) / 2
+        : stationAngle((index / count) * 2 * radius));
+    const rim = (r, start, end) => [
+        point(r, start),
+        ...(start < Math.PI / 4 && end > Math.PI / 4 ? [point(r, Math.PI / 4)] : []),
+        point(r, end),
+    ];
+    const treads = Array.from({ length: count }, (_, index) => {
+        const start = angles[index], end = angles[index + 1];
+        const polygon = [...rim(outer, start, end), ...rim(gap, start, end).reverse()];
+        return {
+            polygon,
+            elevation: ((index + 1) * height) / count,
+            startStation: angleStation(start),
+            endStation: angleStation(end),
+            startAngle: start,
+            endAngle: end,
+        };
+    });
+    const boundary = (r) => {
+        const samples = [...angles, Math.PI / 4].sort((a, b) => a - b);
+        let treadIndex = 0;
+        return samples
+            .filter((angle, index) => !index || Math.abs(angle - samples[index - 1]) > 1e-10)
+            .map((angle) => {
+            const [x, z] = point(r, angle);
+            while (treadIndex < count - 1 && angles[treadIndex + 1] < angle)
+                treadIndex++;
+            const index = treadIndex;
+            const startStation = angleStation(angles[index]), endStation = angleStation(angles[index + 1]);
+            const progress = (angleStation(angle) - startStation) / (endStation - startStation);
+            return [x, ((index + progress) * height) / count, z];
+        });
+    };
+    const walkingLine = boundary(radius);
+    return {
+        treads,
+        footprint: [...rim(outer, 0, Math.PI / 2), ...rim(gap, 0, Math.PI / 2).reverse()],
+        walkingLine,
+        innerBoundary: boundary(gap),
+        outerBoundary: boundary(outer),
+        exit: {
+            position: [sign * (gap + width / 2), height, gap + width / 2],
+            rotation: (sign * Math.PI) / 2,
+        },
+        going: Math.min(...treads.map((tread) => tread.endStation - tread.startStation)),
+        narrowEndGoing: (gap / radius) * Math.min(...treads.map((tread) => tread.endStation - tread.startStation)),
+    };
+}
+/** Polygon prisms share the exact walking footprint; structure stays below its finished top. */
+export function resolveWinderStairConstruction(segment, absoluteHeight = 0, parent) {
+    const layout = resolveStairWinder(segment);
+    if (!layout)
+        return null;
+    const c = segment.construction ?? parent?.construction;
+    const mode = c?.mode ?? (segment.fillToFloor ? 'solid' : 'waist');
+    const finish = c?.finishThickness ?? 0, treadThickness = c?.treadThickness ?? segment.thickness;
+    const gap = segment.winder.innerGap, width = segment.width, radius = gap + segment.winder.walkingLineOffset;
+    const sign = segment.winder.turn === 'left' ? -1 : 1, pivot = sign * (gap + width / 2);
+    const rise = segment.height / segment.stepCount, slope = segment.height / (2 * radius);
+    const waist = (c?.waistThickness ?? segment.thickness) * Math.sqrt(1 + slope * slope) + finish;
+    const parts = 1 +
+        Number(finish > 0) +
+        Number((mode === 'solid' || mode === 'waist') && (c?.nosing ?? 0) > 0) +
+        Number(mode !== 'solid' && mode !== 'waist' && c?.closedRisers) +
+        (mode === 'side-stringers' ? 2 : mode === 'center-stringer' ? 1 : 0);
+    if (segment.stepCount * parts * 2 > 10000)
+        throw new RangeError('Detailed winder construction exceeds the 10,000-surface computation budget. The authored values are preserved.');
+    const pieces = [];
+    const angle = ([x, z]) => Math.atan2(z, sign * (pivot - x));
+    const station = (a) => a <= Math.PI / 4 ? radius * Math.tan(a) : 2 * radius - radius / Math.tan(a);
+    const point = (r, a) => {
+        const scale = r / Math.max(Math.cos(a), Math.sin(a));
+        return [pivot - sign * scale * Math.cos(a), scale * Math.sin(a)];
+    };
+    const polygon = (inner, outer, start, end) => {
+        const rim = (r) => [
+            point(r, start),
+            ...(start < Math.PI / 4 && end > Math.PI / 4 ? [point(r, Math.PI / 4)] : []),
+            point(r, end),
+        ];
+        return [...rim(outer), ...rim(inner).reverse()];
+    };
+    const emit = (role, index, poly, top, bottom, walkingTop = false) => {
+        const n = poly.length / 2;
+        for (let i = 0; i < n - 1; i++) {
+            const ids = [i, i + 1, poly.length - 2 - i, poly.length - 1 - i];
+            const polygon = ids.map((j) => poly[j]);
+            const bottomValues = ids.map((j, k) => typeof bottom === 'number'
+                ? bottom
+                : bottom(poly[j][0] === pivot && poly[j][1] === 0
+                    ? poly[ids[k === 2 ? 1 : k === 3 ? 0 : k]]
+                    : poly[j]));
+            pieces.push({ role, index, polygon, top, bottom: bottomValues, walkingTop });
+        }
+    };
+    for (const [index, tread] of layout.treads.entries()) {
+        const start = tread.startAngle, end = tread.endAngle;
+        const top = tread.elevation - finish;
+        const nosing = c?.nosing ?? 0;
+        const approach = start - Math.atan2(nosing, radius);
+        const full = polygon(gap, gap + width, approach, end);
+        const walkingHeight = (p) => (index + (station(angle(p)) - tread.startStation) / (tread.endStation - tread.startStation)) *
+            rise;
+        const underside = (p) => Math.min(top - 1e-8, walkingHeight(p) - waist);
+        if (mode === 'solid' || mode === 'waist') {
+            emit('body', index, tread.polygon, top, mode === 'solid'
+                ? Math.min(-absoluteHeight, top - (c?.waistThickness ?? segment.thickness))
+                : underside, finish === 0);
+            if (nosing > 0)
+                emit('tread', index, polygon(gap, gap + width, approach, start), top, top - treadThickness);
+        }
+        else {
+            emit('tread', index, full, top, top - treadThickness, finish === 0);
+            if (c?.closedRisers)
+                emit('body', index, polygon(gap, gap + width, start, Math.min(end, start + Math.atan2(c.riserThickness, radius))), top, top - rise);
+        }
+        if (finish > 0)
+            emit('tread', index, full, tread.elevation, top, true);
+        if (mode === 'side-stringers' || mode === 'center-stringer') {
+            const band = c.stringerWidth;
+            const bands = mode === 'side-stringers'
+                ? [
+                    [gap, gap + band],
+                    [gap + width - band, gap + width],
+                ]
+                : [[radius - band / 2, radius + band / 2]];
+            for (const [inner, outer] of bands)
+                emit('body', index, polygon(inner, outer, start, end), top - treadThickness, (p) => Math.min(top - treadThickness - 1e-8, walkingHeight(p) - treadThickness - finish - c.stringerDepth));
+        }
+    }
+    return pieces;
+}
+export function resolveStairWinderFootprint(segment, parent) {
+    const layout = resolveStairWinder(segment);
+    if (!layout)
+        return null;
+    const polygon = layout.footprint.map((point) => [...point]);
+    const nose = (segment.construction ?? parent?.construction)?.nosing ?? 0;
+    if (nose) {
+        const radius = segment.winder.innerGap + segment.winder.walkingLineOffset;
+        polygon[0][1] = (-(segment.winder.innerGap + segment.width) * nose) / radius;
+        polygon[polygon.length - 1][1] = (-segment.winder.innerGap * nose) / radius;
+    }
+    return polygon;
+}