@pascal-app/viewer 0.7.0 → 0.9.1

package/dist/systems/roof/roof-system.js

@@ -1,9 +1,16 @@
+import { getEffectiveNode, getSegmentSlopeFrame, hasSegmentMaterialOverride, nodeRegistry, sceneRegistry, useLiveNodeOverrides, useScene, } from '@pascal-app/core';
 import { useFrame } from '@react-three/fiber';
-import { sceneRegistry, useScene, } from '@pascal-app/core';
 import * as THREE from 'three';
 import { mergeVertices } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
 import { ADDITION, Brush, Evaluator, SUBTRACTION } from 'three-bvh-csg';
 import { computeBoundsTree } from 'three-mesh-bvh';
+function csgGeometry(brush) {
+    return brush.geometry;
+}
+function csgMaterials(brush) {
+    const mat = brush.material;
+    return Array.isArray(mat) ? mat : [mat];
+}
 const csgEvaluator = new Evaluator();
 csgEvaluator.useGroups = true;
 csgEvaluator.consolidateGroups = false; // shared dummyMats across brushes causes consolidation to misalign groupIndices vs groupOrder indices → crash
@@ -24,8 +31,22 @@ const _quaternion = new THREE.Quaternion();
 const _scale = new THREE.Vector3(1, 1, 1);
 const _yAxis = new THREE.Vector3(0, 1, 0);
 const _uvFaceNormal = new THREE.Vector3();
+const _uvWorldDown = new THREE.Vector3(0, -1, 0);
+const _uvDownSlope = new THREE.Vector3();
+const _uvAcrossSlope = new THREE.Vector3();
+const _tmpVec3A = new THREE.Vector3();
+const _tmpVec3B = new THREE.Vector3();
+const _surfaceRay = new THREE.Ray();
+const _surfaceOrigin = new THREE.Vector3();
+const _surfaceDir = new THREE.Vector3(0, -1, 0);
+const _surfaceHits = [];
+const _surfaceV0 = new THREE.Vector3();
+const _surfaceV1 = new THREE.Vector3();
+const _surfaceV2 = new THREE.Vector3();
+const _surfaceFaceNormal = new THREE.Vector3();
 // Pending merged-roof updates carried across frames (for throttling)
 const pendingRoofUpdates = new Set();
+const warnedMergedRoofNaNIds = new Set();
 const MAX_ROOFS_PER_FRAME = 1;
 const MAX_SEGMENTS_PER_FRAME = 3;
 // ============================================================================
@@ -35,10 +56,16 @@ export const RoofSystem = () => {
     const dirtyNodes = useScene((state) => state.dirtyNodes);
     const clearDirty = useScene((state) => state.clearDirty);
     const rootNodeIds = useScene((state) => state.rootNodeIds);
+    // Subscribe so an override-only update (no scene write) still re-runs
+    // the component, letting the useFrame loop pick up the latest dirtyNodes
+    // set from the render pass that received the override-publishing
+    // `markDirty` call. Mirrors WallSystem / DoorSystem.
+    useLiveNodeOverrides((s) => s.overrides);
     useFrame(() => {
         // Clear stale pending updates when the scene is unloaded
         if (rootNodeIds.length === 0) {
             pendingRoofUpdates.clear();
+            warnedMergedRoofNaNIds.clear();
             return;
         }
         if (dirtyNodes.size === 0 && pendingRoofUpdates.size === 0)
@@ -50,14 +77,37 @@ export const RoofSystem = () => {
             const node = nodes[id];
             if (!node)
                 return;
+            // Roof accessories (chimney, skylight, solar-panel, dormer,
+            // ridge-vent, box-vent — anything declaring
+            // `capabilities.roofAccessory` on its NodeDefinition) cascade
+            // their dirty mark to the host segment's parent roof so the
+            // merged shell re-CSGs with the new cut. Without this, moving /
+            // resizing an accessory leaves the merged roof showing the
+            // previous cut shape (stale CSG) once the user exits segment
+            // edit mode. Registry-driven so the viewer stays kind-agnostic.
+            const def = nodeRegistry.get(node.type);
+            if (def?.capabilities?.roofAccessory) {
+                const segId = node.roofSegmentId;
+                const seg = segId ? nodes[segId] : undefined;
+                if (seg?.parentId) {
+                    pendingRoofUpdates.add(seg.parentId);
+                }
+                clearDirty(id);
+                return;
+            }
             if (node.type === 'roof-segment') {
                 const mesh = sceneRegistry.nodes.get(id);
+                // Merge any live override (width / depth / wallHeight / pitch /
+                // rotation) so the mesh rebuild reflects the in-flight handle drag
+                // without zustand churn. When no override is set this returns the
+                // scene node unchanged. Same pattern as DoorSystem / WallSystem.
+                const effectiveSegment = getEffectiveNode(node);
                 if (mesh) {
                     // Only compute expensive individual CSG when the segment is actually rendered
                     // (its parent group is visible = the roof is selected for editing)
                     const isVisible = mesh.parent?.visible !== false;
                     if (isVisible && segmentsProcessed < MAX_SEGMENTS_PER_FRAME) {
-                        updateRoofSegmentGeometry(node, mesh);
+                        updateRoofSegmentGeometry(effectiveSegment, mesh);
                         segmentsProcessed++;
                     }
                     else if (isVisible) {
@@ -71,12 +121,16 @@ export const RoofSystem = () => {
                         if (mesh.geometry.type === 'BoxGeometry') {
                             mesh.geometry.dispose();
                             const placeholder = new THREE.BufferGeometry();
-                            placeholder.setAttribute('position', new THREE.Float32BufferAttribute([], 3));
+                            // Three zero-vertices (one degenerate, invisible triangle), not an
+                            // empty attribute: an empty position (count 0) leaves WebGPU vertex
+                            // buffer slot 0 unbound if the mesh is ever drawn, and computeBoundsTree
+                            // needs a real position buffer to index.
+                            placeholder.setAttribute('position', new THREE.Float32BufferAttribute(new Float32Array(9), 3));
                             computeGeometryBoundsTree(placeholder);
                             mesh.geometry = placeholder;
                         }
-                        mesh.position.set(node.position[0], node.position[1], node.position[2]);
-                        mesh.rotation.y = node.rotation;
+                        mesh.position.set(effectiveSegment.position[0], effectiveSegment.position[1], effectiveSegment.position[2]);
+                        mesh.rotation.y = effectiveSegment.rotation;
                     }
                     clearDirty(id);
                 }
@@ -84,8 +138,8 @@ export const RoofSystem = () => {
                     clearDirty(id);
                 }
                 // Queue the parent roof for a merged geometry update
-                if (node.parentId) {
-                    pendingRoofUpdates.add(node.parentId);
+                if (effectiveSegment.parentId) {
+                    pendingRoofUpdates.add(effectiveSegment.parentId);
                 }
             }
             else if (node.type === 'roof') {
@@ -104,13 +158,15 @@ export const RoofSystem = () => {
                 continue;
             }
             const group = sceneRegistry.nodes.get(id);
-            if (group) {
-                const mergedMesh = group.getObjectByName('merged-roof');
-                if (mergedMesh?.visible !== false) {
-                    // Only rebuild when visible — RoofEditSystem re-triggers via markDirty on edit mode exit
-                    updateMergedRoofGeometry(node, group, nodes);
-                    roofsProcessed++;
-                }
+            if (!group)
+                continue;
+            const mergedMesh = group.getObjectByName('merged-roof');
+            if (!mergedMesh)
+                continue;
+            if (mergedMesh.visible !== false) {
+                // Only rebuild when visible — RoofEditSystem re-triggers via markDirty on edit mode exit
+                updateMergedRoofGeometry(node, group, nodes);
+                roofsProcessed++;
             }
             pendingRoofUpdates.delete(id);
         }
@@ -132,9 +188,21 @@ function updateMergedRoofGeometry(roofNode, group, nodes) {
     const mergedMesh = group.getObjectByName('merged-roof');
     if (!mergedMesh)
         return;
+    // Segments that carry their own material / preset (catch-all or any of
+    // the role-specific fields) are rendered as their own per-segment mesh
+    // in `RoofRenderer` so the painted material is preserved. Exclude them
+    // from the merged shell — otherwise the merged mesh would draw on top
+    // with the roof's default material.
+    //
+    // Merge each child through `getEffectiveNode` so an in-flight handle
+    // drag (live override on width / depth / wallHeight / pitch / rotation)
+    // is reflected in the merged shell during the drag, not only on commit.
     const children = (roofNode.children ?? [])
-        .map((id) => nodes[id])
-        .filter(Boolean);
+        .map((id) => {
+        const scn = nodes[id];
+        return scn ? getEffectiveNode(scn) : undefined;
+    })
+        .filter((n) => n !== undefined && !hasSegmentMaterialOverride(n));
     if (children.length === 0) {
         mergedMesh.geometry.dispose();
         // Keep a valid position attribute so Drei's BVH can index safely.
@@ -149,9 +217,76 @@ function updateMergedRoofGeometry(roofNode, group, nodes) {
         const brushes = getRoofSegmentBrushes(child);
         if (!brushes)
             continue;
+        // Per-child cuts in SEGMENT-LOCAL space: subtract every accessory
+        // that contributes a cut (declares
+        // `capabilities.roofAccessory.buildCut`) from shin / deck / wall
+        // before we accumulate. Mirrors roof-system v1 — the cut is built
+        // in segment-local, then carved out before the segment transform
+        // stacks on. Registry-driven so the viewer never names a kind.
+        let workingShin = brushes.shinSlab;
+        let workingDeck = brushes.deckSlab;
+        let workingWall = brushes.wallBrush;
+        for (const childElemId of child.children ?? []) {
+            const childElem = nodes[childElemId];
+            if (!childElem)
+                continue;
+            const meta = typeof childElem.metadata === 'object' && childElem.metadata !== null
+                ? childElem.metadata
+                : undefined;
+            if (meta?.isTransient)
+                continue;
+            const childDef = nodeRegistry.get(childElem.type);
+            const buildCut = childDef?.capabilities?.roofAccessory?.buildCut;
+            if (!buildCut)
+                continue;
+            const cutGeo = buildCut(childElem, child);
+            if (!cutGeo)
+                continue;
+            // Wrap the kind-emitted geometry in a Brush. Kinds return raw
+            // shapes; the viewer welds (mandatory after rotations leave
+            // duplicated verts), attaches a single material group, and
+            // builds the bounds tree — keeping kind code free of
+            // three-bvh-csg / three-mesh-bvh imports.
+            const welded = mergeVertices(cutGeo, 1e-4);
+            cutGeo.dispose();
+            const idxCount = welded.getIndex()?.count ?? 0;
+            if (idxCount === 0) {
+                welded.dispose();
+                continue;
+            }
+            welded.clearGroups();
+            welded.addGroup(0, idxCount, 0);
+            welded.computeVertexNormals();
+            computeGeometryBoundsTree(welded);
+            const cut = new Brush(welded, dummyMats[0]);
+            cut.updateMatrixWorld();
+            try {
+                const nextShin = csgEvaluator.evaluate(workingShin, cut, SUBTRACTION);
+                workingShin.geometry.dispose();
+                prepareBrushForCSG(nextShin);
+                workingShin = nextShin;
+                const nextDeck = csgEvaluator.evaluate(workingDeck, cut, SUBTRACTION);
+                workingDeck.geometry.dispose();
+                prepareBrushForCSG(nextDeck);
+                workingDeck = nextDeck;
+                const nextWall = csgEvaluator.evaluate(workingWall, cut, SUBTRACTION);
+                workingWall.geometry.dispose();
+                prepareBrushForCSG(nextWall);
+                workingWall = nextWall;
+            }
+            catch (e) {
+                console.error(`[${childElem.type}] cut CSG failed:`, e);
+            }
+            finally {
+                cut.geometry.dispose();
+            }
+        }
+        brushes.shinSlab = workingShin;
+        brushes.deckSlab = workingDeck;
+        brushes.wallBrush = workingWall;
         _matrix.compose(_position.set(child.position[0], child.position[1], child.position[2]), _quaternion.setFromAxisAngle(_yAxis, child.rotation), _scale);
         const applyTransform = (brush) => {
-            brush.geometry.applyMatrix4(_matrix);
+            csgGeometry(brush).applyMatrix4(_matrix);
             brush.updateMatrixWorld();
         };
         applyTransform(brushes.shinSlab);
@@ -206,10 +341,24 @@ function updateMergedRoofGeometry(roofNode, group, nodes) {
             const finalWallTrimmed = csgEvaluator.evaluate(totalWall, totalInner, SUBTRACTION);
             const shinDeck = csgEvaluator.evaluate(finalShinTrimmed, finalDeckTrimmed, ADDITION);
             const combined = csgEvaluator.evaluate(shinDeck, finalWallTrimmed, ADDITION);
-            const resultGeo = combined.geometry;
-            const resultMaterials = Array.isArray(combined.material)
-                ? combined.material
-                : [combined.material];
+            const resultGeo = csgGeometry(combined);
+            if (geometryHasNaNPositions(resultGeo)) {
+                if (!warnedMergedRoofNaNIds.has(roofNode.id)) {
+                    console.warn('[RoofSystem] Skipping merged roof geometry with NaN positions', roofNode.id);
+                    warnedMergedRoofNaNIds.add(roofNode.id);
+                }
+                resultGeo.dispose();
+                finalShinTrimmed.geometry.dispose();
+                finalDeckTrimmed.geometry.dispose();
+                finalWallTrimmed.geometry.dispose();
+                shinDeck.geometry.dispose();
+                totalShinSlab.geometry.dispose();
+                totalDeckSlab.geometry.dispose();
+                totalWall.geometry.dispose();
+                totalInner.geometry.dispose();
+                return;
+            }
+            const resultMaterials = csgMaterials(combined);
             const matToIndex = new Map([
                 [dummyMats[0], 0],
                 [dummyMats[1], 1],
@@ -219,8 +368,8 @@ function updateMergedRoofGeometry(roofNode, group, nodes) {
             for (const g of resultGeo.groups) {
                 g.materialIndex = mapRoofGroupMaterialIndex(g.materialIndex, resultMaterials, matToIndex);
             }
-            ensureUv2Attribute(resultGeo);
             resultGeo.computeVertexNormals();
+            ensureUv2Attribute(resultGeo);
             mergedMesh.geometry.dispose();
             mergedMesh.geometry = resultGeo;
             finalShinTrimmed.geometry.dispose();
@@ -237,19 +386,54 @@ function updateMergedRoofGeometry(roofNode, group, nodes) {
         totalInner.geometry.dispose();
     }
 }
-const dummyMats = [
+function geometryHasNaNPositions(geometry) {
+    const position = geometry.getAttribute('position');
+    if (!position)
+        return false;
+    for (let i = 0; i < position.array.length; i++) {
+        if (Number.isNaN(position.array[i]))
+            return true;
+    }
+    return false;
+}
+/**
+ * Four dummy materials used as identity placeholders during CSG. Shared
+ * across every input brush so three-bvh-csg can preserve reference
+ * equality on the result and `mapRoofGroupMaterialIndex` can map result
+ * groups back to slots 0..3. Exposed so kinds that compose additional
+ * CSG ops on top of `getRoofSegmentBrushes` (e.g. dormer) use the same
+ * identity refs.
+ */
+export const roofCsgDummyMats = [
     new THREE.MeshBasicMaterial(),
     new THREE.MeshBasicMaterial(),
     new THREE.MeshBasicMaterial(),
     new THREE.MeshBasicMaterial(),
 ];
-const ROOF_MATERIAL_SLOT_COUNT = 4;
-function mapRoofGroupMaterialIndex(groupMaterialIndex, csgMaterials, matToIndex) {
+// Internal alias kept so the surrounding file's many call sites don't churn.
+const dummyMats = roofCsgDummyMats;
+export const ROOF_MATERIAL_SLOT_COUNT = 4;
+export function mapRoofGroupMaterialIndex(groupMaterialIndex, csgMaterials, matToIndex) {
     if (groupMaterialIndex === undefined)
         return 0;
+    // Primary path — reference-equality lookup. Fast and exact when
+    // three-bvh-csg preserves the original `dummyMats` references on
+    // the result brush.
     const sourceMaterial = csgMaterials[groupMaterialIndex];
     const mappedIndex = sourceMaterial ? matToIndex.get(sourceMaterial) : undefined;
-    return mappedIndex ?? 0;
+    if (mappedIndex !== undefined)
+        return mappedIndex;
+    // Robust fallback — every input brush was constructed with the same
+    // 4-slot `dummyMats` array, so after N union/subtraction passes the
+    // result's material array is `[dummyMats[0..3], dummyMats[0..3], ...]`
+    // and the group's materialIndex is `slot + (brushOffset * 4)`. The
+    // slot we care about is therefore `materialIndex % 4`. Without this
+    // fallback, any CSG pass that returns a fresh `Material` object (or
+    // clones the dummyMats refs) makes every group collapse to slot 0
+    // (Wall) — which is the "shape is there but the wrong colour"
+    // symptom roofs show after deselect / refresh.
+    return (((groupMaterialIndex % ROOF_MATERIAL_SLOT_COUNT) + ROOF_MATERIAL_SLOT_COUNT) %
+        ROOF_MATERIAL_SLOT_COUNT);
 }
 function normalizeRoofMaterialIndex(materialIndex) {
     if (materialIndex === undefined || !Number.isFinite(materialIndex))
@@ -267,38 +451,20 @@ const RAKE_FACE_ALIGNMENT_EPSILON = 0.35;
  * Ports the prototype's CSG approach using three-bvh-csg.
  */
 export function getRoofSegmentBrushes(node) {
-    const { roofType, width, depth, wallHeight, roofHeight, wallThickness, deckThickness, overhang, shingleThickness, } = node;
-    const activeRh = roofType === 'flat' ? 0 : roofHeight;
-    let run = Math.min(width, depth) / 2;
-    let rise = activeRh;
-    if (roofType === 'shed') {
-        run = depth;
-    }
-    if (roofType === 'gable') {
-        run = depth / 2;
-    }
-    if (roofType === 'gambrel') {
-        run = depth / 4;
-        rise = activeRh * 0.6;
-    }
-    if (roofType === 'mansard') {
-        run = Math.min(width, depth) * 0.15;
-        rise = activeRh * 0.7;
-    }
-    if (roofType === 'dutch') {
-        run = Math.min(width, depth) * 0.25;
-        rise = activeRh * 0.5;
-    }
-    const tanTheta = run > 0 ? rise / run : 0;
-    const cosTheta = Math.cos(Math.atan2(rise, run)) || 1;
-    const sinTheta = Math.sin(Math.atan2(rise, run)) || 0;
+    const { roofType, width, depth, wallHeight, wallThickness, deckThickness, overhang, shingleThickness, } = node;
+    const { activeRh, tanTheta, cosTheta, sinTheta } = getSegmentSlopeFrame(node);
+    const shapeRatios = {
+        gambrelLowerWidthRatio: node.gambrelLowerWidthRatio,
+        mansardSteepWidthRatio: node.mansardSteepWidthRatio,
+        dutchHipWidthRatio: node.dutchHipWidthRatio,
+    };
     const verticalRt = activeRh > 0 ? deckThickness / cosTheta : deckThickness;
     const baseI = Math.min(width, depth) * 0.25;
     const getVol = (wExt, vOffset, baseY, matIndex, isVoid) => {
         const wV = Math.max(0.01, width + 2 * wExt);
         const dV = Math.max(0.01, depth + 2 * wExt);
         const autoDrop = wExt * tanTheta;
-        const whV = wallHeight - autoDrop + vOffset;
+        const whV = Math.max(0.01, wallHeight - autoDrop + vOffset);
         let rhV = activeRh;
         if (activeRh > 0) {
             rhV = activeRh + autoDrop;
@@ -310,7 +476,7 @@ export function getRoofSegmentBrushes(node) {
         if (isVoid) {
             structuralI += deckThickness;
         }
-        const faces = getModuleFaces(roofType, wV, dV, whV, rhV, safeBaseY, { dutchI: structuralI }, width, depth, tanTheta);
+        const faces = getModuleFaces(roofType, wV, dV, whV, rhV, safeBaseY, { dutchI: structuralI }, width, depth, tanTheta, shapeRatios);
         return createGeometryFromFaces(faces, matIndex);
     };
     const wallGeo = getVol(wallThickness / 2, 0, 0, 0, false);
@@ -384,8 +550,8 @@ export function getRoofSegmentBrushes(node) {
     };
     const insetsBot = getInsets(shinBotWh, botBaseY, true, shinBotW, shinBotD);
     const insetsTop = getInsets(shinTopWh, topBaseY, false, shinTopW, shinTopD);
-    const botFaces = getModuleFaces(roofType, shinBotW, shinBotD, shinBotWh, shinBotRh, botBaseY, insetsBot, width, depth, tanTheta);
-    const topFaces = getModuleFaces(roofType, shinTopW, shinTopD, shinTopWh, shinTopRh, topBaseY, insetsTop, width, depth, tanTheta);
+    const botFaces = getModuleFaces(roofType, shinBotW, shinBotD, shinBotWh, shinBotRh, botBaseY, insetsBot, width, depth, tanTheta, shapeRatios);
+    const topFaces = getModuleFaces(roofType, shinTopW, shinTopD, shinTopWh, shinTopRh, topBaseY, insetsTop, width, depth, tanTheta, shapeRatios);
     const shinBotGeo = createGeometryFromFaces(botFaces, 1);
     const shinTopGeo = createGeometryFromFaces(topFaces, (normal) => normal.y > SHINGLE_SURFACE_EPSILON ? 3 : 1);
     if (transZ !== 0) {
@@ -477,10 +643,8 @@ export function generateRoofSegmentGeometry(node) {
         const hollowWall = csgEvaluator.evaluate(wallBrush, innerBrush, SUBTRACTION);
         const shinDeck = csgEvaluator.evaluate(shinSlab, deckSlab, ADDITION);
         const combined = csgEvaluator.evaluate(shinDeck, hollowWall, ADDITION);
-        resultGeo = combined.geometry;
-        const resultMaterials = Array.isArray(combined.material)
-            ? combined.material
-            : [combined.material];
+        resultGeo = csgGeometry(combined);
+        const resultMaterials = csgMaterials(combined);
         const matToIndex = new Map([
             [dummyMats[0], 0],
             [dummyMats[1], 1],
@@ -496,17 +660,17 @@ export function generateRoofSegmentGeometry(node) {
     }
     catch (e) {
         console.error('Roof CSG failed:', e);
-        resultGeo = wallBrush.geometry.clone();
+        resultGeo = csgGeometry(wallBrush).clone();
     }
     deckSlab.geometry.dispose();
     shinSlab.geometry.dispose();
     wallBrush.geometry.dispose();
     innerBrush.geometry.dispose();
-    ensureUv2Attribute(resultGeo);
     resultGeo.computeVertexNormals();
+    ensureUv2Attribute(resultGeo);
     return resultGeo;
 }
-function remapRoofShellFaces(geometry, node) {
+export function remapRoofShellFaces(geometry, node) {
     const position = geometry.getAttribute('position');
     const index = geometry.getIndex();
     if (!(position && index) || index.count === 0 || geometry.groups.length === 0)
@@ -597,8 +761,12 @@ function getRakeAxis(node) {
 /**
  * Generates faces for a roof module volume.
  * Supports: hip, gable, shed, gambrel, dutch, mansard, flat.
+ *
+ * `shapeRatios` controls the kink positions on multi-slope roofs. The
+ * height ratios are already baked into `tanTheta` (via the slope frame)
+ * so they don't need to be threaded again.
  */
-function getModuleFaces(type, w, d, wh, rh, baseY, insets, baseW, baseD, tanTheta) {
+function getModuleFaces(type, w, d, wh, rh, baseY, insets, baseW, baseD, tanTheta, shapeRatios) {
     const v = (x, y, z) => new THREE.Vector3(x, y, z);
     const { iF = 0, iB = 0, iL = 0, iR = 0 } = insets;
     const b1 = v(-w / 2 + iL, baseY, d / 2 - iF);
@@ -643,7 +811,7 @@ function getModuleFaces(type, w, d, wh, rh, baseY, insets, baseW, baseD, tanThet
         faces.push([e1, e2, t2, t1], [e2, e3, t2], [e3, e4, t1, t2], [e4, e1, t1]);
     }
     else if (type === 'gambrel') {
-        const mz = (baseD / 2) * 0.5;
+        const mz = (baseD / 2) * shapeRatios.gambrelLowerWidthRatio;
         const dist = d / 2 - mz;
         const mh = wh + dist * (tanTheta || 0);
         const m1 = v(-w / 2, mh, mz);
@@ -655,7 +823,7 @@ function getModuleFaces(type, w, d, wh, rh, baseY, insets, baseW, baseD, tanThet
         faces.push([e4, e1, m1, r1, m4], [e2, e3, m3, r2, m2], [e1, e2, m2, m1], [m1, m2, r2, r1], [e3, e4, m4, m3], [m3, m4, r1, r2]);
     }
     else if (type === 'mansard') {
-        const i = Math.min(baseW, baseD) * 0.15;
+        const i = Math.min(baseW, baseD) * shapeRatios.mansardSteepWidthRatio;
         const mh = wh + i * (tanTheta || 0);
         const m1 = v(-w / 2 + i, mh, d / 2 - i);
         const m2 = v(w / 2 - i, mh, d / 2 - i);
@@ -682,7 +850,9 @@ function getModuleFaces(type, w, d, wh, rh, baseY, insets, baseW, baseD, tanThet
         }
     }
     else if (type === 'dutch') {
-        const i = insets.dutchI !== undefined ? insets.dutchI : Math.min(baseW, baseD) * 0.25;
+        const i = insets.dutchI !== undefined
+            ? insets.dutchI
+            : Math.min(baseW, baseD) * shapeRatios.dutchHipWidthRatio;
         const mh = wh + i * (tanTheta || 0);
         if (w >= d) {
             const m1 = v(-w / 2 + i, mh, d / 2 - i);
@@ -725,6 +895,25 @@ function createGeometryFromFaces(faces, matRule = null) {
         const vA = new THREE.Vector3().subVectors(p1, p0);
         const vB = new THREE.Vector3().subVectors(p2, p0);
         const normal = new THREE.Vector3().crossVectors(vA, vB).normalize();
+        let slopeAlignedDown = null;
+        let slopeAlignedAcross = null;
+        let slopeAlignedVOrigin = 0;
+        if (normal.y > SHINGLE_SURFACE_EPSILON) {
+            _uvDownSlope.copy(_uvWorldDown).projectOnPlane(normal);
+            if (_uvDownSlope.lengthSq() > 1e-8) {
+                _uvDownSlope.normalize();
+                _uvAcrossSlope.crossVectors(_uvDownSlope, normal).normalize();
+                let highestPoint = face[0];
+                for (const candidate of face) {
+                    if (candidate.y > highestPoint.y) {
+                        highestPoint = candidate;
+                    }
+                }
+                slopeAlignedDown = _uvDownSlope.clone();
+                slopeAlignedAcross = _uvAcrossSlope.clone();
+                slopeAlignedVOrigin = highestPoint.dot(slopeAlignedDown);
+            }
+        }
         let assignedMatIndex = 0;
         if (typeof matRule === 'function') {
             assignedMatIndex = matRule(normal);
@@ -747,9 +936,16 @@ function createGeometryFromFaces(faces, matRule = null) {
             normals.push(normal.x, normal.y, normal.z);
             normals.push(normal.x, normal.y, normal.z);
             normals.push(normal.x, normal.y, normal.z);
-            pushRoofUv(uvs, p0, normal);
-            pushRoofUv(uvs, fi, normal);
-            pushRoofUv(uvs, fi1, normal);
+            if (slopeAlignedDown && slopeAlignedAcross) {
+                uvs.push(p0.dot(slopeAlignedAcross), slopeAlignedVOrigin - p0.dot(slopeAlignedDown));
+                uvs.push(fi.dot(slopeAlignedAcross), slopeAlignedVOrigin - fi.dot(slopeAlignedDown));
+                uvs.push(fi1.dot(slopeAlignedAcross), slopeAlignedVOrigin - fi1.dot(slopeAlignedDown));
+            }
+            else {
+                pushRoofUv(uvs, p0, normal);
+                pushRoofUv(uvs, fi, normal);
+                pushRoofUv(uvs, fi1, normal);
+            }
             indices.push(vertexCount, vertexCount + 1, vertexCount + 2);
             faceVertexCount += 3;
             vertexCount += 3;
@@ -783,11 +979,20 @@ function pushRoofUv(uvs, point, normal) {
         uvs.push(point.x, point.z);
         return;
     }
+    if (_uvFaceNormal.y > SHINGLE_SURFACE_EPSILON) {
+        _uvDownSlope.copy(_uvWorldDown).projectOnPlane(_uvFaceNormal);
+        if (_uvDownSlope.lengthSq() > 1e-8) {
+            _uvDownSlope.normalize();
+            _uvAcrossSlope.crossVectors(_uvDownSlope, _uvFaceNormal).normalize();
+            uvs.push(point.dot(_uvAcrossSlope), point.dot(_uvDownSlope));
+            return;
+        }
+    }
     if (absX >= absZ) {
-        uvs.push(point.z, point.y);
+        uvs.push(_uvFaceNormal.x >= 0 ? point.z : -point.z, -point.y);
         return;
     }
-    uvs.push(point.x, point.y);
+    uvs.push(_uvFaceNormal.z >= 0 ? point.x : -point.x, -point.y);
 }
 function ensureUv2Attribute(geometry) {
     const uv = geometry.getAttribute('uv');
@@ -795,3 +1000,138 @@ function ensureUv2Attribute(geometry) {
         return;
     geometry.setAttribute('uv2', new THREE.Float32BufferAttribute(Array.from(uv.array), 2));
 }
+/**
+ * Returns the outer roof surface frame (point + normal) at a given segment-local XZ.
+ * This is used for skylight placement + cut direction so cutouts remain perpendicular
+ * to the true roof surface even on multi-slope roofs (gambrel/mansard/dutch).
+ */
+export function getRoofOuterSurfaceFrameAtPoint(segment, lx, lz) {
+    const { roofType, width, depth, wallHeight, wallThickness, deckThickness, overhang, shingleThickness, } = segment;
+    const { activeRh, tanTheta, cosTheta, sinTheta } = getSegmentSlopeFrame(segment);
+    if (roofType === 'flat' || activeRh === 0) {
+        return {
+            point: new THREE.Vector3(lx, wallHeight + deckThickness + shingleThickness, lz),
+            normal: new THREE.Vector3(0, 1, 0),
+        };
+    }
+    const verticalRt = deckThickness / cosTheta;
+    const horizontalOverhang = overhang * cosTheta;
+    const deckExt = wallThickness / 2 + horizontalOverhang;
+    const stSin = shingleThickness * sinTheta;
+    const stCos = shingleThickness * cosTheta;
+    const shinBotW = Math.max(0.01, width + 2 * deckExt);
+    const shinBotD = Math.max(0.01, depth + 2 * deckExt);
+    const deckDrop = deckExt * tanTheta;
+    const shinBotWh = wallHeight - deckDrop + verticalRt;
+    let shinBotRh = activeRh;
+    if (activeRh > 0) {
+        shinBotRh = activeRh + deckDrop;
+        if (roofType === 'shed')
+            shinBotRh = activeRh + 2 * deckDrop;
+    }
+    let shinTopW = shinBotW;
+    let shinTopD = shinBotD;
+    let transZ = 0;
+    if (['hip', 'mansard', 'dutch'].includes(roofType)) {
+        shinTopW += 2 * stSin;
+        shinTopD += 2 * stSin;
+    }
+    else {
+        shinTopW += 2 * stSin;
+        shinTopD += 2 * stSin;
+        transZ = stSin;
+    }
+    const shinTopWh = shinBotWh + stCos;
+    const shinTopRh = shinBotRh + stCos;
+    const topBaseY = 0;
+    const baseI = Math.min(width, depth) * 0.25;
+    const getInsets = (_wh, _baseY, isVoid, _wV, _dV) => {
+        const inset = Math.max(0.01, baseI);
+        let iF = 0;
+        let iB = 0;
+        let iL = 0;
+        let iR = 0;
+        if (roofType === 'hip') {
+            iF = inset;
+            iB = inset;
+            iL = inset;
+            iR = inset;
+        }
+        else if (roofType === 'gable' || roofType === 'gambrel') {
+            iL = inset;
+            iR = inset;
+        }
+        else if (roofType === 'mansard' || roofType === 'dutch') {
+            iF = inset;
+            iB = inset;
+            iL = inset;
+            iR = inset;
+        }
+        else if (roofType === 'shed') {
+            iF = inset;
+        }
+        let structuralI = baseI;
+        if (isVoid) {
+            structuralI += shingleThickness;
+        }
+        return { iF, iB, iL, iR, dutchI: structuralI };
+    };
+    const insetsTop = getInsets(shinTopWh, topBaseY, false, shinTopW, shinTopD);
+    const shapeRatios = {
+        gambrelLowerWidthRatio: segment.gambrelLowerWidthRatio,
+        mansardSteepWidthRatio: segment.mansardSteepWidthRatio,
+        dutchHipWidthRatio: segment.dutchHipWidthRatio,
+    };
+    const topFaces = getModuleFaces(roofType, shinTopW, shinTopD, shinTopWh, shinTopRh, topBaseY, insetsTop, width, depth, tanTheta, shapeRatios);
+    const topGeo = createGeometryFromFaces(topFaces, (normal) => normal.y > SHINGLE_SURFACE_EPSILON ? 3 : 1);
+    if (transZ !== 0)
+        topGeo.translate(0, 0, transZ);
+    topGeo.computeBoundingBox();
+    const topY = wallHeight + activeRh + deckThickness + shingleThickness + 10;
+    _surfaceOrigin.set(lx, topY, lz);
+    _surfaceRay.set(_surfaceOrigin, _surfaceDir);
+    _surfaceHits.length = 0;
+    const pos = topGeo.getAttribute('position');
+    const index = topGeo.getIndex();
+    if (!pos || !index) {
+        topGeo.dispose();
+        return {
+            point: new THREE.Vector3(lx, wallHeight, lz),
+            normal: new THREE.Vector3(0, 1, 0),
+        };
+    }
+    let bestT = Number.POSITIVE_INFINITY;
+    let bestPoint = null;
+    let bestNormal = null;
+    for (let i = 0; i < index.count; i += 3) {
+        const a = index.getX(i);
+        const b = index.getX(i + 1);
+        const c = index.getX(i + 2);
+        _surfaceV0.fromBufferAttribute(pos, a);
+        _surfaceV1.fromBufferAttribute(pos, b);
+        _surfaceV2.fromBufferAttribute(pos, c);
+        const hit = _surfaceRay.intersectTriangle(_surfaceV0, _surfaceV1, _surfaceV2, false, _tmpVec3A);
+        if (!hit)
+            continue;
+        const t = hit.distanceTo(_surfaceOrigin);
+        if (t < bestT) {
+            bestT = t;
+            bestPoint = hit.clone();
+            _surfaceFaceNormal
+                .subVectors(_surfaceV1, _surfaceV0)
+                .cross(_tmpVec3B.subVectors(_surfaceV2, _surfaceV0))
+                .normalize();
+            bestNormal = _surfaceFaceNormal.clone();
+        }
+    }
+    topGeo.dispose();
+    if (!bestPoint || !bestNormal) {
+        return {
+            point: new THREE.Vector3(lx, wallHeight, lz),
+            normal: new THREE.Vector3(0, 1, 0),
+        };
+    }
+    if (bestNormal.y < 0)
+        bestNormal.multiplyScalar(-1);
+    return { point: bestPoint, normal: bestNormal };
+}