@pascal-app/core 1.0.3 → 1.0.4

package/dist/systems/stair/stair-opening-system.js

@@ -1,12 +1,16 @@
 'use client';
 import { useEffect } from 'react';
+import { structureChangeBatch } from '../../commands/structure/shared.js';
 import { pauseSceneHistory, resumeSceneHistory } from '../../store/history-control.js';
-import { queueSceneNormalization } from '../../store/scene-hydration.js';
+import { isHydrationNormalization, queueSceneNormalization } from '../../store/scene-hydration.js';
 import useLiveNodeOverrides from '../../store/use-live-node-overrides.js';
 import useLiveTransforms from '../../store/use-live-transforms.js';
 import useScene from '../../store/use-scene.js';
+import { ensureSceneOpenings } from '../../utils/ensure-scene-openings.js';
+import { planOwnedFloorOpenings } from '../owned-floor-openings.js';
+import { reconcileOwnedFloorOpeningChanges } from '../reconcile-owned-floor-openings.js';
 import { createSurfaceOpeningPreviewController, getNodesWithLiveStairOpeningInputs, hasLiveStairOpeningInputs, } from './stair-opening-preview.js';
-import { syncAutoStairOpenings } from './stair-opening-sync.js';
+import { changedStairOpeningOwners, syncAutoStairOpenings } from './stair-opening-sync.js';
 import { syncStairRises } from './stair-rise.js';
 function isOpeningRelevantNode(node) {
     return (node?.type === 'building' ||
@@ -54,6 +58,25 @@ export function initializeStairOpeningSync() {
             syncingPreviewOpenings = false;
         });
     };
+    const applyOpeningChanges = (skipExistingSurfaces = false, ownerIds) => {
+        const changes = planOwnedFloorOpenings(useScene.getState().nodes, {
+            skipExistingSurfaces,
+            ownerIds,
+        });
+        if (!changes.length)
+            return;
+        syncingAutoOpenings = true;
+        pauseSceneHistory(useScene);
+        try {
+            const before = useScene.getState().nodes;
+            useScene.getState().applyNodeChanges(structureChangeBatch(changes));
+            reconcileOwnedFloorOpeningChanges(before, changes);
+        }
+        finally {
+            resumeSceneHistory(useScene);
+            syncingAutoOpenings = false;
+        }
+    };
     const clearPreviewUpdates = () => {
         if (previewController.previewSurfaceIds.size === 0)
             return;
@@ -76,17 +99,24 @@ export function initializeStairOpeningSync() {
         }
         applyPreviewUpdates(syncAutoStairOpenings(getNodesWithLiveStairOpeningInputs(nodes, liveTransforms, liveOverrides, previewSurfaceIds)));
     };
-    const runAutoSync = () => {
+    const runAutoSync = (preserveSlabs, before) => {
+        if (preserveSlabs) {
+            applyUpdates(ensureSceneOpenings(useScene.getState().nodes).updates);
+            applyOpeningChanges(true);
+            return;
+        }
         // Rise first: straight stairs converge their flight heights to the
         // resolved rise (level height or deck elevation), and the opening pass
         // reads those segment heights — so it must run against the post-rise
         // nodes.
         applyUpdates(syncStairRises(useScene.getState().nodes));
-        applyUpdates(syncAutoStairOpenings(useScene.getState().nodes));
+        applyOpeningChanges(false, changedStairOpeningOwners(before, useScene.getState().nodes));
     };
     let disposed = false;
     let syncGeneration = 0;
-    const scheduleAutoSync = () => {
+    let pendingBefore;
+    const scheduleAutoSync = (preserveSlabs = false, before = useScene.getState().nodes) => {
+        pendingBefore ??= before;
         const generation = ++syncGeneration;
         // One microtask later so every other scene-store listener for the
         // triggering transition (and, at mount, the editor's spatial-grid
@@ -97,17 +127,19 @@ export function initializeStairOpeningSync() {
         queueSceneNormalization(() => {
             if (disposed || generation !== syncGeneration)
                 return;
-            runAutoSync();
+            const previous = pendingBefore;
+            pendingBefore = undefined;
+            runAutoSync(preserveSlabs, previous);
             refreshLivePreview();
         });
     };
-    scheduleAutoSync();
+    scheduleAutoSync(true);
     const unsubscribeScene = useScene.subscribe((state, prevState) => {
         if (syncingAutoOpenings)
             return;
         if (!hasOpeningRelevantNodeChange(state.nodes, prevState.nodes))
             return;
-        scheduleAutoSync();
+        scheduleAutoSync(isHydrationNormalization() || state.hydrationId !== prevState.hydrationId, prevState.nodes);
     });
     const unsubscribeLiveTransforms = useLiveTransforms.subscribe(() => {
         refreshLivePreview();

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

@@ -0,0 +1,276 @@
+import type { AnyNode, StairNode as Stair } from '../../schema/index.js';
+export type StairLayoutPreset = 'straight' | 'l' | 'u';
+export type StairPresetOptions = {
+    layout: StairLayoutPreset;
+    turn?: 'left' | 'right';
+    width?: number;
+    landingDepth?: number;
+    turningStrategy?: 'landing' | 'winder';
+    innerGap?: number;
+    walkingLineOffset?: number;
+    division?: 'equal-going' | 'equal-angle';
+};
+/** Proposes a replacement chain, retaining flight/landing identities and finishes by role. */
+export declare function planStairPreset(original: Stair, nodes: Record<string, AnyNode>, options: StairPresetOptions): {
+    stair: {
+        object: "node";
+        parentId: string | null;
+        visible: boolean;
+        metadata: Record<string, unknown>;
+        id: `stair_${string}`;
+        type: "stair";
+        position: [number, number, number];
+        rotation: number;
+        stairType: "straight" | "spiral" | "curved";
+        fromLevelId: string | null;
+        toLevelId: string | null;
+        slabOpeningMode: "none" | "destination";
+        openingOffset: number;
+        width: number;
+        stepCount: number;
+        thickness: number;
+        fillToFloor: boolean;
+        innerRadius: number;
+        sweepAngle: number;
+        topLandingMode: "none" | "integrated";
+        topLandingDepth: number;
+        showCenterColumn: boolean;
+        showStepSupports: boolean;
+        railingMode: "left" | "right" | "none" | "both";
+        railingHeight: number;
+        children: `sseg_${string}`[];
+        name?: string | undefined;
+        camera?: {
+            position: [number, number, number];
+            target: [number, number, number];
+            mode: "perspective" | "orthographic";
+            fov?: number | undefined;
+            zoom?: number | undefined;
+        } | undefined;
+        provenance?: {
+            refs: {
+                id: string;
+                ns?: string | undefined;
+                role?: "primary" | "piece" | "absorbed" | "alias" | "derived" | undefined;
+            }[];
+            lineage?: {
+                op: "import" | "split" | "merge" | "duplicate" | "convert" | "promote" | "make-independent" | "attach";
+                fromIds: string[];
+            } | undefined;
+        } | undefined;
+        material?: {
+            id?: string | undefined;
+            preset?: "custom" | "white" | "brick" | "concrete" | "wood" | "glass" | "metal" | "plaster" | "tile" | "marble" | undefined;
+            properties?: {
+                color: string;
+                roughness: number;
+                metalness: number;
+                opacity: number;
+                transparent: boolean;
+                side: "front" | "back" | "double";
+            } | undefined;
+            texture?: {
+                url: string;
+                repeat?: [number, number] | undefined;
+                scale?: number | undefined;
+            } | undefined;
+        } | undefined;
+        materialPreset?: string | undefined;
+        railingMaterial?: {
+            id?: string | undefined;
+            preset?: "custom" | "white" | "brick" | "concrete" | "wood" | "glass" | "metal" | "plaster" | "tile" | "marble" | undefined;
+            properties?: {
+                color: string;
+                roughness: number;
+                metalness: number;
+                opacity: number;
+                transparent: boolean;
+                side: "front" | "back" | "double";
+            } | undefined;
+            texture?: {
+                url: string;
+                repeat?: [number, number] | undefined;
+                scale?: number | undefined;
+            } | undefined;
+        } | undefined;
+        railingMaterialPreset?: string | undefined;
+        treadMaterial?: {
+            id?: string | undefined;
+            preset?: "custom" | "white" | "brick" | "concrete" | "wood" | "glass" | "metal" | "plaster" | "tile" | "marble" | undefined;
+            properties?: {
+                color: string;
+                roughness: number;
+                metalness: number;
+                opacity: number;
+                transparent: boolean;
+                side: "front" | "back" | "double";
+            } | undefined;
+            texture?: {
+                url: string;
+                repeat?: [number, number] | undefined;
+                scale?: number | undefined;
+            } | undefined;
+        } | undefined;
+        treadMaterialPreset?: string | undefined;
+        sideMaterial?: {
+            id?: string | undefined;
+            preset?: "custom" | "white" | "brick" | "concrete" | "wood" | "glass" | "metal" | "plaster" | "tile" | "marble" | undefined;
+            properties?: {
+                color: string;
+                roughness: number;
+                metalness: number;
+                opacity: number;
+                transparent: boolean;
+                side: "front" | "back" | "double";
+            } | undefined;
+            texture?: {
+                url: string;
+                repeat?: [number, number] | undefined;
+                scale?: number | undefined;
+            } | undefined;
+        } | undefined;
+        sideMaterialPreset?: string | undefined;
+        slots?: Record<string, string> | undefined;
+        supportSlabId?: string | undefined;
+        deckSlabId?: string | undefined;
+        totalRise?: number | undefined;
+        designTargets?: {
+            maxRiserHeight: number;
+            minimumGoing: number;
+            targetGoing: number;
+            minimumHeadroom: number;
+        } | undefined;
+        uniformRisers?: boolean | undefined;
+        construction?: {
+            mode: "solid" | "open" | "waist" | "side-stringers" | "center-stringer";
+            waistThickness: number;
+            treadThickness: number;
+            riserThickness: number;
+            nosing: number;
+            finishThickness: number;
+            closedRisers: boolean;
+            stringerWidth: number;
+            stringerDepth: number;
+        } | undefined;
+        railingStyle?: "glass" | "metal" | "balusters" | "cable" | "boards" | "post-and-rail" | undefined;
+        railingPath?: "continuous" | "original" | undefined;
+        handrail?: {
+            mode: "left" | "right" | "none" | "both";
+            height: number;
+            diameter: number;
+            offset: number;
+            bottom?: {
+                extension: number;
+                return: "wall" | "floor" | "none" | "post";
+                returnLength: number;
+            } | undefined;
+            top?: {
+                extension: number;
+                return: "wall" | "floor" | "none" | "post";
+                returnLength: number;
+            } | undefined;
+        } | undefined;
+        railingTopPost?: boolean | undefined;
+        railingTopReach?: number | undefined;
+        railingPostThrough?: boolean | undefined;
+    };
+    segments: {
+        object: "node";
+        parentId: string | null;
+        visible: boolean;
+        metadata: Record<string, unknown>;
+        id: `sseg_${string}`;
+        type: "stair-segment";
+        position: [number, number, number];
+        rotation: number;
+        segmentType: "stair" | "landing";
+        width: number;
+        length: number;
+        height: number;
+        stepCount: number;
+        attachmentSide: "left" | "right" | "front";
+        fillToFloor: boolean;
+        thickness: number;
+        name?: string | undefined;
+        camera?: {
+            position: [number, number, number];
+            target: [number, number, number];
+            mode: "perspective" | "orthographic";
+            fov?: number | undefined;
+            zoom?: number | undefined;
+        } | undefined;
+        provenance?: {
+            refs: {
+                id: string;
+                ns?: string | undefined;
+                role?: "primary" | "piece" | "absorbed" | "alias" | "derived" | undefined;
+            }[];
+            lineage?: {
+                op: "import" | "split" | "merge" | "duplicate" | "convert" | "promote" | "make-independent" | "attach";
+                fromIds: string[];
+            } | undefined;
+        } | undefined;
+        material?: {
+            id?: string | undefined;
+            preset?: "custom" | "white" | "brick" | "concrete" | "wood" | "glass" | "metal" | "plaster" | "tile" | "marble" | undefined;
+            properties?: {
+                color: string;
+                roughness: number;
+                metalness: number;
+                opacity: number;
+                transparent: boolean;
+                side: "front" | "back" | "double";
+            } | undefined;
+            texture?: {
+                url: string;
+                repeat?: [number, number] | undefined;
+                scale?: number | undefined;
+            } | undefined;
+        } | undefined;
+        materialPreset?: string | undefined;
+        slots?: Record<string, string> | undefined;
+        construction?: {
+            mode: "solid" | "open" | "waist" | "side-stringers" | "center-stringer";
+            waistThickness: number;
+            treadThickness: number;
+            riserThickness: number;
+            nosing: number;
+            finishThickness: number;
+            closedRisers: boolean;
+            stringerWidth: number;
+            stringerDepth: number;
+        } | undefined;
+        winder?: {
+            turn: "left" | "right";
+            innerGap: number;
+            walkingLineOffset: number;
+            division: "equal-going" | "equal-angle";
+        } | undefined;
+    }[];
+    removeIds: `sseg_${string}`[];
+    footprint: {
+        width: number;
+        length: number;
+    };
+};
+/** Footprints in the stair's local axes; no scene writes and no automatic replacement. */
+export declare function proposeStairLayouts(stair: Stair, nodes: Record<string, AnyNode>, available?: {
+    width: number;
+    length: number;
+}): ({
+    layout: "straight" | "u" | "l";
+    turn: "left" | "right";
+    footprint: {
+        width: number;
+        length: number;
+    };
+    fits: boolean | null;
+    error: null;
+} | {
+    layout: "straight" | "u" | "l";
+    turn: "left" | "right";
+    footprint: null;
+    fits: boolean;
+    error: string;
+})[];
+//# sourceMappingURL=stair-presets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stair-presets.d.ts","sourceRoot":"","sources":["../../../src/systems/stair/stair-presets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA+B,SAAS,IAAI,KAAK,EAAE,MAAM,cAAc,CAAA;AAO5F,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,GAAG,GAAG,GAAG,CAAA;AACtD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,iBAAiB,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,EAAE,aAAa,GAAG,aAAa,CAAA;CACzC,CAAA;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,KAAK,EACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkH5B;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,SAAS,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;KA8B9C"}

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

@@ -0,0 +1,151 @@
+import { StairNode } from '../../schema/nodes/stair.js';
+import { StairSegmentNode } from '../../schema/nodes/stair-segment.js';
+import { stairFootprintAABB } from './stair-footprint.js';
+import { resolveStairTotalRise } from './stair-rise-query.js';
+import { planStairSizing } from './stair-sizing.js';
+/** Proposes a replacement chain, retaining flight/landing identities and finishes by role. */
+export function planStairPreset(original, nodes, options) {
+    const width = options.width ?? original.width;
+    const landingDepth = options.landingDepth ?? width;
+    if (!(Number.isFinite(width) && width > 0))
+        throw new RangeError('Width must be positive');
+    if (!(Number.isFinite(landingDepth) && landingDepth >= width))
+        throw new RangeError('A turning landing must be at least as deep as the stair is wide');
+    const old = original.children
+        .map((id) => nodes[id])
+        .filter((node) => node?.type === 'stair-segment');
+    const flights = old.filter((node) => node.segmentType === 'stair' && !node.winder);
+    const landings = old.filter((node) => node.segmentType === 'landing');
+    const turn = options.turn ?? 'left';
+    let rise = resolveStairTotalRise(original, nodes);
+    for (let iteration = 0; iteration < 16; iteration++) {
+        const sizing = planStairSizing(rise, { targets: original.designTargets });
+        const count = Math.max(options.layout === 'straight' ? 2 : 4, sizing.stepCount);
+        const winding = options.turningStrategy === 'winder' && options.layout !== 'straight';
+        const quarterCount = options.layout === 'u' ? 2 : 1;
+        const walkingLineOffset = options.walkingLineOffset ?? width / 2;
+        const innerGap = options.innerGap ?? 0;
+        if (!(walkingLineOffset > 0 && walkingLineOffset <= width && innerGap >= 0))
+            throw new RangeError('The walking line must lie within the winder width and gap must be nonnegative');
+        const winderCount = Math.max(1, Math.round((2 * (innerGap + walkingLineOffset)) / sizing.going));
+        if (winding && quarterCount * winderCount > count - 2)
+            throw new RangeError('The selected winder gap needs more risers than this stair permits');
+        const counts = options.layout === 'straight'
+            ? [count]
+            : [
+                Math.ceil((count - (winding ? quarterCount * winderCount : 0)) / 2),
+                Math.floor((count - (winding ? quarterCount * winderCount : 0)) / 2),
+            ];
+        let flightIndex = 0;
+        let landingIndex = 0;
+        const make = (segmentType, attachmentSide) => {
+            const prior = segmentType === 'stair' ? flights[flightIndex] : landings[landingIndex];
+            const stepCount = segmentType === 'stair' ? counts[flightIndex++] : 0;
+            if (segmentType === 'landing')
+                landingIndex++;
+            return StairSegmentNode.parse({
+                ...prior,
+                winder: undefined,
+                parentId: original.id,
+                segmentType,
+                visible: true,
+                position: [0, 0, 0],
+                rotation: 0,
+                attachmentSide,
+                width,
+                length: segmentType === 'stair' ? stepCount * sizing.going : landingDepth,
+                height: segmentType === 'stair' ? (rise * stepCount) / count : 0,
+                stepCount,
+                fillToFloor: prior?.fillToFloor ?? original.fillToFloor,
+                thickness: prior?.thickness ?? original.thickness,
+            });
+        };
+        const segments = [make('stair', 'front')];
+        if (options.layout !== 'straight') {
+            if (winding) {
+                for (let quarter = 0; quarter < quarterCount; quarter++) {
+                    const prior = old.filter((flight) => flight.winder)[quarter];
+                    segments.push(StairSegmentNode.parse({
+                        ...prior,
+                        id: prior?.id,
+                        parentId: original.id,
+                        width,
+                        visible: true,
+                        length: 2 * (innerGap + walkingLineOffset),
+                        height: (rise * winderCount) / count,
+                        stepCount: winderCount,
+                        attachmentSide: 'front',
+                        winder: {
+                            turn,
+                            innerGap,
+                            walkingLineOffset,
+                            division: options.division ?? 'equal-going',
+                        },
+                        fillToFloor: prior?.fillToFloor ?? original.fillToFloor,
+                        thickness: prior?.thickness ?? original.thickness,
+                    }));
+                }
+            }
+            else {
+                segments.push(make('landing', 'front'));
+                if (options.layout === 'u')
+                    segments.push(make('landing', turn));
+            }
+            segments.push(make('stair', winding ? 'front' : turn));
+        }
+        const stair = StairNode.parse({
+            ...original,
+            stairType: 'straight',
+            width,
+            stepCount: count,
+            uniformRisers: true,
+            children: segments.map((segment) => segment.id),
+        });
+        const proposed = { ...nodes, [stair.id]: stair };
+        for (const segment of segments)
+            proposed[segment.id] = segment;
+        const nextRise = resolveStairTotalRise(stair, proposed);
+        if (Math.abs(nextRise - rise) < 1e-6) {
+            const box = stairFootprintAABB({ ...stair, position: [0, 0, 0], rotation: 0 }, proposed);
+            return {
+                stair,
+                segments,
+                removeIds: old.filter((node) => !stair.children.includes(node.id)).map((node) => node.id),
+                footprint: { width: box.maxX - box.minX, length: box.maxZ - box.minZ },
+            };
+        }
+        rise = nextRise;
+    }
+    throw new RangeError('Stair support and arrival do not converge for this layout');
+}
+/** Footprints in the stair's local axes; no scene writes and no automatic replacement. */
+export function proposeStairLayouts(stair, nodes, available) {
+    if (available && (!(available.width > 0) || !(available.length > 0)))
+        throw new RangeError('Available footprint must be positive');
+    return [
+        { layout: 'straight', turn: 'left' },
+        { layout: 'l', turn: 'left' },
+        { layout: 'l', turn: 'right' },
+        { layout: 'u', turn: 'left' },
+        { layout: 'u', turn: 'right' },
+    ].map(({ layout, turn }) => {
+        try {
+            const plan = planStairPreset(stair, nodes, { layout, turn });
+            return {
+                layout,
+                turn,
+                footprint: plan.footprint,
+                fits: available
+                    ? plan.footprint.width <= available.width + 1e-8 &&
+                        plan.footprint.length <= available.length + 1e-8
+                    : null,
+                error: null,
+            };
+        }
+        catch (error) {
+            if (!(error instanceof RangeError))
+                throw error;
+            return { layout, turn, footprint: null, fits: false, error: error.message };
+        }
+    });
+}

package/dist/systems/stair/stair-rail-budget.d.ts

@@ -0,0 +1,6 @@
+import type { StairNode, StairSegmentNode } from '../../schema/index.js';
+/** Coarse work units bound path length, sampling and vertical repetition without
+ * knowing any guard's sections or joinery. Builders own their member profiles. */
+export declare function stairRailComplexity(stair: StairNode, segments: readonly StairSegmentNode[]): number;
+export declare function stairRailPathVertexBound(stair: StairNode, segments: readonly StairSegmentNode[]): number;
+//# sourceMappingURL=stair-rail-budget.d.ts.map

package/dist/systems/stair/stair-rail-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stair-rail-budget.d.ts","sourceRoot":"","sources":["../../../src/systems/stair/stair-rail-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAG/D;kFACkF;AAClF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,gBAAgB,EAAE,UA6B1F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,gBAAgB,EAAE,UAS/F"}

package/dist/systems/stair/stair-rail-budget.js

@@ -0,0 +1,36 @@
+import { resolveStairArcDimensions } from './stair-layout.js';
+/** Coarse work units bound path length, sampling and vertical repetition without
+ * knowing any guard's sections or joinery. Builders own their member profiles. */
+export function stairRailComplexity(stair, segments) {
+    const guards = stair.railingMode === 'none' ? 0 : stair.railingMode === 'both' ? 2 : 1;
+    const hands = !stair.handrail || stair.handrail.mode === 'none' ? 0 : stair.handrail.mode === 'both' ? 2 : 1;
+    if (!guards && !hands)
+        return 0;
+    const arc = resolveStairArcDimensions(stair, 0);
+    const length = stair.stairType !== 'straight'
+        ? (Math.abs(arc.sweepAngle) + Math.abs(arc.landingSweep)) * arc.outerRadius
+        : (segments.length ? segments : [{ width: stair.width, length: 3 }]).reduce((sum, segment) => sum +
+            ('winder' in segment && segment.winder
+                ? Math.PI * (segment.winder.innerGap + segment.width)
+                : segment.length + segment.width), 0);
+    const vertices = stairRailPathVertexBound(stair, segments);
+    const guardWork = guards *
+        (vertices + Math.ceil((length + (stair.railingTopReach ?? 0)) * 10)) *
+        Math.max(1, Math.ceil(stair.railingHeight));
+    const handWork = hands *
+        (vertices +
+            Math.ceil(length) +
+            Math.ceil(stair.handrail?.bottom?.extension ?? 0) +
+            Math.ceil(stair.handrail?.top?.extension ?? 0));
+    return guardWork + handWork;
+}
+export function stairRailPathVertexBound(stair, segments) {
+    const arc = resolveStairArcDimensions(stair, 0);
+    return stair.stairType !== 'straight'
+        ? Math.ceil((Math.abs(arc.sweepAngle) + Math.abs(arc.landingSweep)) / (Math.PI / 36)) + 2
+        : segments.reduce((sum, segment) => sum + (segment.winder ? segment.stepCount + 2 : 0), 0) +
+            8 * Math.max(1, segments.length) +
+            16 *
+                segments.length *
+                segments.filter((segment) => segment.segmentType === 'landing').length;
+}

package/dist/systems/stair/stair-rail-path.d.ts

@@ -0,0 +1,22 @@
+import type { AnyNode, StairNode } from '../../schema/index.js';
+export type StairRailPath = {
+    side: 'left' | 'right';
+    nodeIds: string[];
+    /** In the parent stair's local frame, before its position and rotation. */
+    points: [number, number, number][];
+};
+/** Exposed boundaries leave the flight entry and arrival portals open. */
+export declare function resolveStairRailPaths(stair: StairNode, nodes: Record<string, AnyNode>, mode?: "left" | "right" | "none" | "both", inset?: number): StairRailPath[];
+/**
+ * A predicate for "this horizontal point, in the stair's local frame, lies on
+ * the walkable surface" — the region a guard rail stands at the edge of. A rail
+ * guard uses it to tell which side of its path is the walking volume (so a flat
+ * glass pane can be held off that side) without re-deriving the footprint. For
+ * an arc stair the walkable surface is the annulus between the inner and outer
+ * walking radii; for a straight run or a winder it is the flight/landing
+ * footprint, with the same winder test the inset handrail uses.
+ */
+export declare function resolveStairWalkInside(stair: StairNode, nodes: Record<string, AnyNode>): (x: number, z: number) => boolean;
+/** End details are geometric returns; wall/post targets are not hosted connections. */
+export declare function resolveStairHandrailPaths(stair: StairNode, nodes: Record<string, AnyNode>): StairRailPath[];
+//# sourceMappingURL=stair-rail-path.d.ts.map

package/dist/systems/stair/stair-rail-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stair-rail-path.d.ts","sourceRoot":"","sources":["../../../src/systems/stair/stair-rail-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAoB,MAAM,cAAc,CAAA;AASxE,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACtB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,2EAA2E;IAC3E,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;CACnC,CAAA;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,qCAAoB,EACxB,KAAK,SAAI,GACR,aAAa,EAAE,CAyTjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAiCnC;AAmFD,uFAAuF;AACvF,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,aAAa,EAAE,CAkKjB"}