@pascal-app/core 0.7.0 → 0.9.1

package/dist/schema/nodes/roof-segment.d.ts

@@ -1,14 +1,29 @@
 import { z } from 'zod';
+import type { MaterialSchema as MaterialSchemaType } from '../material';
 export declare const RoofType: z.ZodEnum<{
+    flat: "flat";
     hip: "hip";
     gable: "gable";
     shed: "shed";
     gambrel: "gambrel";
     dutch: "dutch";
     mansard: "mansard";
-    flat: "flat";
 }>;
 export type RoofType = z.infer<typeof RoofType>;
+export declare const ROOF_SHAPE_DEFAULTS: {
+    /** Gambrel: lower (steep) face occupies this fraction of the horizontal half-depth. */
+    readonly gambrelLowerWidthRatio: 0.5;
+    /** Gambrel: lower (steep) face rises this fraction of the way to the peak. */
+    readonly gambrelLowerHeightRatio: 0.6;
+    /** Mansard: steep face occupies this fraction of `min(width, depth)`. */
+    readonly mansardSteepWidthRatio: 0.15;
+    /** Mansard: steep face rises this fraction of the way to the peak. */
+    readonly mansardSteepHeightRatio: 0.7;
+    /** Dutch: hip face occupies this fraction of `min(width, depth)`. */
+    readonly dutchHipWidthRatio: 0.25;
+    /** Dutch: hip face rises this fraction of the way to the peak. */
+    readonly dutchHipHeightRatio: 0.5;
+};
 export declare const RoofSegmentNode: z.ZodObject<{
     object: z.ZodDefault<z.ZodLiteral<"node">>;
     name: z.ZodOptional<z.ZodString>;
@@ -30,6 +45,7 @@ export declare const RoofSegmentNode: z.ZodObject<{
     material: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         preset: z.ZodOptional<z.ZodEnum<{
+            custom: "custom";
             white: "white";
             brick: "brick";
             concrete: "concrete";
@@ -39,7 +55,6 @@ export declare const RoofSegmentNode: z.ZodObject<{
             plaster: "plaster";
             tile: "tile";
             marble: "marble";
-            custom: "custom";
         }>>;
         properties: z.ZodOptional<z.ZodObject<{
             color: z.ZodDefault<z.ZodString>;
@@ -60,25 +75,204 @@ export declare const RoofSegmentNode: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     materialPreset: z.ZodOptional<z.ZodString>;
+    topMaterial: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        preset: z.ZodOptional<z.ZodEnum<{
+            custom: "custom";
+            white: "white";
+            brick: "brick";
+            concrete: "concrete";
+            wood: "wood";
+            glass: "glass";
+            metal: "metal";
+            plaster: "plaster";
+            tile: "tile";
+            marble: "marble";
+        }>>;
+        properties: z.ZodOptional<z.ZodObject<{
+            color: z.ZodDefault<z.ZodString>;
+            roughness: z.ZodDefault<z.ZodNumber>;
+            metalness: z.ZodDefault<z.ZodNumber>;
+            opacity: z.ZodDefault<z.ZodNumber>;
+            transparent: z.ZodDefault<z.ZodBoolean>;
+            side: z.ZodDefault<z.ZodEnum<{
+                front: "front";
+                back: "back";
+                double: "double";
+            }>>;
+        }, z.core.$strip>>;
+        texture: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            repeat: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            scale: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    topMaterialPreset: z.ZodOptional<z.ZodString>;
+    edgeMaterial: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        preset: z.ZodOptional<z.ZodEnum<{
+            custom: "custom";
+            white: "white";
+            brick: "brick";
+            concrete: "concrete";
+            wood: "wood";
+            glass: "glass";
+            metal: "metal";
+            plaster: "plaster";
+            tile: "tile";
+            marble: "marble";
+        }>>;
+        properties: z.ZodOptional<z.ZodObject<{
+            color: z.ZodDefault<z.ZodString>;
+            roughness: z.ZodDefault<z.ZodNumber>;
+            metalness: z.ZodDefault<z.ZodNumber>;
+            opacity: z.ZodDefault<z.ZodNumber>;
+            transparent: z.ZodDefault<z.ZodBoolean>;
+            side: z.ZodDefault<z.ZodEnum<{
+                front: "front";
+                back: "back";
+                double: "double";
+            }>>;
+        }, z.core.$strip>>;
+        texture: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            repeat: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            scale: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    edgeMaterialPreset: z.ZodOptional<z.ZodString>;
+    wallMaterial: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        preset: z.ZodOptional<z.ZodEnum<{
+            custom: "custom";
+            white: "white";
+            brick: "brick";
+            concrete: "concrete";
+            wood: "wood";
+            glass: "glass";
+            metal: "metal";
+            plaster: "plaster";
+            tile: "tile";
+            marble: "marble";
+        }>>;
+        properties: z.ZodOptional<z.ZodObject<{
+            color: z.ZodDefault<z.ZodString>;
+            roughness: z.ZodDefault<z.ZodNumber>;
+            metalness: z.ZodDefault<z.ZodNumber>;
+            opacity: z.ZodDefault<z.ZodNumber>;
+            transparent: z.ZodDefault<z.ZodBoolean>;
+            side: z.ZodDefault<z.ZodEnum<{
+                front: "front";
+                back: "back";
+                double: "double";
+            }>>;
+        }, z.core.$strip>>;
+        texture: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            repeat: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            scale: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    wallMaterialPreset: z.ZodOptional<z.ZodString>;
     position: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
     rotation: z.ZodDefault<z.ZodNumber>;
     roofType: z.ZodDefault<z.ZodEnum<{
+        flat: "flat";
         hip: "hip";
         gable: "gable";
         shed: "shed";
         gambrel: "gambrel";
         dutch: "dutch";
         mansard: "mansard";
-        flat: "flat";
     }>>;
     width: z.ZodDefault<z.ZodNumber>;
     depth: z.ZodDefault<z.ZodNumber>;
     wallHeight: z.ZodDefault<z.ZodNumber>;
-    roofHeight: z.ZodDefault<z.ZodNumber>;
+    pitch: z.ZodDefault<z.ZodNumber>;
     wallThickness: z.ZodDefault<z.ZodNumber>;
     deckThickness: z.ZodDefault<z.ZodNumber>;
     overhang: z.ZodDefault<z.ZodNumber>;
     shingleThickness: z.ZodDefault<z.ZodNumber>;
+    gambrelLowerWidthRatio: z.ZodDefault<z.ZodNumber>;
+    gambrelLowerHeightRatio: z.ZodDefault<z.ZodNumber>;
+    mansardSteepWidthRatio: z.ZodDefault<z.ZodNumber>;
+    mansardSteepHeightRatio: z.ZodDefault<z.ZodNumber>;
+    dutchHipWidthRatio: z.ZodDefault<z.ZodNumber>;
+    dutchHipHeightRatio: z.ZodDefault<z.ZodNumber>;
+    children: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type RoofSegmentNode = z.infer<typeof RoofSegmentNode>;
+/** Shape of the per-type ratios consumed by the slope helpers. */
+type ShapeRatios = {
+    gambrelLowerWidthRatio: number;
+    gambrelLowerHeightRatio: number;
+    mansardSteepWidthRatio: number;
+    mansardSteepHeightRatio: number;
+    dutchHipWidthRatio: number;
+    dutchHipHeightRatio: number;
+};
+type PitchInputs = {
+    roofType: RoofType;
+    width: number;
+    depth: number;
+} & Partial<ShapeRatios>;
+export type SegmentSlopeFrame = {
+    /** Horizontal half-span of the primary slope face (eave-to-ridge). */
+    run: number;
+    /** Vertical height of the primary slope face. */
+    rise: number;
+    /** tan(pitch). 0 for flat or zero-pitch segments. */
+    tanTheta: number;
+    /** cos(pitch). 1 for flat or zero-pitch segments. */
+    cosTheta: number;
+    /** sin(pitch). 0 for flat or zero-pitch segments. */
+    sinTheta: number;
+    /** Overall eave-to-peak height of the assembled roof. */
+    activeRh: number;
+};
+/**
+ * One stop for the slope math every roof-segment consumer needs. Builds
+ * `run`, `rise`, the trig triple, and the overall peak height from the
+ * segment's pitch + footprint + roofType. Before this helper existed,
+ * the table was duplicated in three places (the brush builder, the
+ * skylight surface-frame routine, and the segment-hit raycaster) and
+ * silently drifted when a new roof type was added.
+ */
+export declare function getSegmentSlopeFrame(node: Pick<RoofSegmentNode, 'roofType' | 'pitch' | 'width' | 'depth'> & Partial<ShapeRatios>): SegmentSlopeFrame;
+/**
+ * The eave-to-peak height of the assembled segment, derived from pitch +
+ * footprint + roofType. Replaces the legacy `roofHeight` field on the node.
+ */
+export declare function getActiveRoofHeight(node: Parameters<typeof getSegmentSlopeFrame>[0]): number;
+/** Segment-local surface height used by roof accessory placement and hit disambiguation. */
+export declare function getRoofSegmentSurfaceY(node: Pick<RoofSegmentNode, 'roofType' | 'width' | 'depth' | 'wallHeight'> & Parameters<typeof getSegmentSlopeFrame>[0], localX: number, localZ: number): number;
+/**
+ * Inverse of `getActiveRoofHeight` — recover the pitch a legacy
+ * `roofHeight` value would correspond to. Used by the scene migration.
+ * Ratio overrides are optional and default to the shape defaults.
+ */
+export declare function getPitchFromActiveRoofHeight(input: PitchInputs & {
+    roofHeight: number;
+}): number;
+export type RoofSegmentSurfaceMaterialRole = 'top' | 'edge' | 'wall';
+export type RoofSegmentSurfaceMaterialSpec = {
+    material?: MaterialSchemaType;
+    materialPreset?: string;
+};
+/**
+ * Resolve the segment-level material for one of the three surface roles.
+ * Falls back through: role-specific field → catch-all `material`. Pass the
+ * parent roof to `parentFallback` when you want the roof's role material
+ * to fill in for an unset segment slot — typical from the renderer.
+ */
+export declare function getEffectiveSegmentSurfaceMaterial(node: RoofSegmentNode, role: RoofSegmentSurfaceMaterialRole, parentFallback?: RoofSegmentSurfaceMaterialSpec): RoofSegmentSurfaceMaterialSpec;
+/**
+ * Returns true when the segment has any segment-level material override —
+ * either the legacy catch-all or any of the three role-specific fields.
+ * Used by `RoofRenderer` and `updateMergedRoofGeometry` to decide whether
+ * the segment should be drawn as its own mesh or folded into the merged
+ * shell.
+ */
+export declare function hasSegmentMaterialOverride(node: RoofSegmentNode): boolean;
+export {};
 //# sourceMappingURL=roof-segment.d.ts.map

package/dist/schema/nodes/roof-segment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roof-segment.d.ts","sourceRoot":"","sources":["../../../src/schema/nodes/roof-segment.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,QAAQ;;;;;;;;EAA0E,CAAA;AAE/F,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA;AAE/C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkC3B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA"}
+{"version":3,"file":"roof-segment.d.ts","sourceRoot":"","sources":["../../../src/schema/nodes/roof-segment.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,cAAc,IAAI,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAGvE,eAAO,MAAM,QAAQ;;;;;;;;EAA0E,CAAA;AAE/F,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA;AAI/C,eAAO,MAAM,mBAAmB;IAC9B,uFAAuF;;IAEvF,8EAA8E;;IAE9E,yEAAyE;;IAEzE,sEAAsE;;IAEtE,qEAAqE;;IAErE,kEAAkE;;CAE1D,CAAA;AAEV,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgG3B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAa7D,kEAAkE;AAClE,KAAK,WAAW,GAAG;IACjB,sBAAsB,EAAE,MAAM,CAAA;IAC9B,uBAAuB,EAAE,MAAM,CAAA;IAC/B,sBAAsB,EAAE,MAAM,CAAA;IAC9B,uBAAuB,EAAE,MAAM,CAAA;IAC/B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,mBAAmB,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED,KAAK,WAAW,GAAG;IACjB,QAAQ,EAAE,QAAQ,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;AAkDxB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAA;IACX,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAA;IAChB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,GAC3F,iBAAiB,CAiBnB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAE5F;AAED,4FAA4F;AAC5F,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,YAAY,CAAC,GACxE,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,EAC5C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,MAAM,CA4BR;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,WAAW,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAOhG;AAMD,MAAM,MAAM,8BAA8B,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;AACpE,MAAM,MAAM,8BAA8B,GAAG;IAC3C,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAWD;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,8BAA8B,EACpC,cAAc,CAAC,EAAE,8BAA8B,GAC9C,8BAA8B,CA+BhC;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAWzE"}

package/dist/schema/nodes/roof-segment.js

@@ -3,11 +3,40 @@ import { z } from 'zod';
 import { BaseNode, nodeType, objectId } from '../base';
 import { MaterialSchema } from '../material';
 export const RoofType = z.enum(['hip', 'gable', 'shed', 'gambrel', 'dutch', 'mansard', 'flat']);
+// Default shape ratios. Tuning these used to require editing the geometry
+// code in two places; they are now schema fields with these defaults.
+export const ROOF_SHAPE_DEFAULTS = {
+    /** Gambrel: lower (steep) face occupies this fraction of the horizontal half-depth. */
+    gambrelLowerWidthRatio: 0.5,
+    /** Gambrel: lower (steep) face rises this fraction of the way to the peak. */
+    gambrelLowerHeightRatio: 0.6,
+    /** Mansard: steep face occupies this fraction of `min(width, depth)`. */
+    mansardSteepWidthRatio: 0.15,
+    /** Mansard: steep face rises this fraction of the way to the peak. */
+    mansardSteepHeightRatio: 0.7,
+    /** Dutch: hip face occupies this fraction of `min(width, depth)`. */
+    dutchHipWidthRatio: 0.25,
+    /** Dutch: hip face rises this fraction of the way to the peak. */
+    dutchHipHeightRatio: 0.5,
+};
 export const RoofSegmentNode = BaseNode.extend({
     id: objectId('rseg'),
     type: nodeType('roof-segment'),
+    // Catch-all material — splatted across all 4 slots in the renderer
+    // when no role-specific override is set. Kept for back-compat with
+    // older scenes; new paint operations should prefer the role fields.
     material: MaterialSchema.optional(),
     materialPreset: z.string().optional(),
+    // Role-specific overrides mirror the parent roof's surface roles.
+    // When set they win over the segment's catch-all `material` and over
+    // the parent roof's role / catch-all materials. Resolution order:
+    //   segment role → segment catch-all → roof role → roof catch-all.
+    topMaterial: MaterialSchema.optional(),
+    topMaterialPreset: z.string().optional(),
+    edgeMaterial: MaterialSchema.optional(),
+    edgeMaterialPreset: z.string().optional(),
+    wallMaterial: MaterialSchema.optional(),
+    wallMaterialPreset: z.string().optional(),
     position: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
     // Rotation around Y axis in radians
     rotation: z.number().default(0),
@@ -16,14 +45,60 @@ export const RoofSegmentNode = BaseNode.extend({
     // Footprint dimensions
     width: z.number().default(8),
     depth: z.number().default(6),
-    // Vertical dimensions
+    // Wall height beneath the roof
     wallHeight: z.number().default(0.5),
-    roofHeight: z.number().default(2.5),
+    // Roof pitch in degrees — angle of the primary slope face.
+    // For gable/hip/shed this is the only slope; for gambrel/mansard/dutch
+    // it is the steep (lower) slope. The overall peak height is derived
+    // from pitch + footprint + roofType via getActiveRoofHeight().
+    pitch: z.number().min(0).max(85).default(40),
     // Structure thicknesses
     wallThickness: z.number().default(0.1),
     deckThickness: z.number().default(0.1),
     overhang: z.number().default(0.3),
     shingleThickness: z.number().default(0.05),
+    // Shape-specific ratios. Only the pair matching `roofType` is read; the
+    // rest are inert. Defined on every segment so the panel can flip
+    // roofType without losing the previous shape's tuning.
+    gambrelLowerWidthRatio: z
+        .number()
+        .min(0.1)
+        .max(0.9)
+        .default(ROOF_SHAPE_DEFAULTS.gambrelLowerWidthRatio),
+    gambrelLowerHeightRatio: z
+        .number()
+        .min(0.1)
+        .max(0.9)
+        .default(ROOF_SHAPE_DEFAULTS.gambrelLowerHeightRatio),
+    mansardSteepWidthRatio: z
+        .number()
+        .min(0.05)
+        .max(0.45)
+        .default(ROOF_SHAPE_DEFAULTS.mansardSteepWidthRatio),
+    mansardSteepHeightRatio: z
+        .number()
+        .min(0.1)
+        .max(0.9)
+        .default(ROOF_SHAPE_DEFAULTS.mansardSteepHeightRatio),
+    dutchHipWidthRatio: z
+        .number()
+        .min(0.05)
+        .max(0.45)
+        .default(ROOF_SHAPE_DEFAULTS.dutchHipWidthRatio),
+    dutchHipHeightRatio: z
+        .number()
+        .min(0.1)
+        .max(0.9)
+        .default(ROOF_SHAPE_DEFAULTS.dutchHipHeightRatio),
+    // Hosted accessories — chimney, dormer, skylight, box-vent,
+    // ridge-vent, solar-panel, gutter. Each accessory's `parentId` points back
+    // here; the segment renderer mounts them recursively via
+    // `<NodeRenderer>` so they inherit the segment's transform stack.
+    // Required for `createNode(child, segmentId)` to append the child
+    // to this array — see
+    // `wiki/architecture/node-definitions.md` ("Host kinds need a
+    // `children` field on the schema").
+    children: z.array(z.string()).default([]),
 }).describe(dedent `
   Roof segment node - an individual roof module within a roof group.
   Each segment generates a complete architectural volume (walls + roof).
@@ -31,8 +106,184 @@ export const RoofSegmentNode = BaseNode.extend({
   - roofType: hip, gable, shed, gambrel, dutch, mansard, flat
   - width/depth: footprint dimensions
   - wallHeight: height of walls below the roof
-  - roofHeight: height of the roof peak above the walls
+  - pitch: roof slope in degrees (angle of the primary slope face)
   - wallThickness/deckThickness: structural thicknesses
   - overhang: eave overhang distance
   - shingleThickness: outer shingle layer thickness
+  - gambrelLowerWidthRatio / gambrelLowerHeightRatio: kink position on gambrel roofs
+  - mansardSteepWidthRatio / mansardSteepHeightRatio: waist position on mansard roofs
+  - dutchHipWidthRatio / dutchHipHeightRatio: hip-to-gable split on dutch roofs
   `);
+function withRatioDefaults(input) {
+    return {
+        ...input,
+        gambrelLowerWidthRatio: input.gambrelLowerWidthRatio ?? ROOF_SHAPE_DEFAULTS.gambrelLowerWidthRatio,
+        gambrelLowerHeightRatio: input.gambrelLowerHeightRatio ?? ROOF_SHAPE_DEFAULTS.gambrelLowerHeightRatio,
+        mansardSteepWidthRatio: input.mansardSteepWidthRatio ?? ROOF_SHAPE_DEFAULTS.mansardSteepWidthRatio,
+        mansardSteepHeightRatio: input.mansardSteepHeightRatio ?? ROOF_SHAPE_DEFAULTS.mansardSteepHeightRatio,
+        dutchHipWidthRatio: input.dutchHipWidthRatio ?? ROOF_SHAPE_DEFAULTS.dutchHipWidthRatio,
+        dutchHipHeightRatio: input.dutchHipHeightRatio ?? ROOF_SHAPE_DEFAULTS.dutchHipHeightRatio,
+    };
+}
+function getPrimarySlopeRun(input) {
+    const min = Math.min(input.width, input.depth);
+    switch (input.roofType) {
+        case 'shed':
+            return input.depth;
+        case 'gable':
+            return input.depth / 2;
+        case 'gambrel':
+            return (input.depth / 2) * input.gambrelLowerWidthRatio;
+        case 'mansard':
+            return min * input.mansardSteepWidthRatio;
+        case 'dutch':
+            return min * input.dutchHipWidthRatio;
+        default:
+            return min / 2;
+    }
+}
+// Fraction of the overall peak height that is taken up by the primary slope.
+function getPrimarySlopeRiseFraction(input) {
+    switch (input.roofType) {
+        case 'gambrel':
+            return input.gambrelLowerHeightRatio;
+        case 'mansard':
+            return input.mansardSteepHeightRatio;
+        case 'dutch':
+            return input.dutchHipHeightRatio;
+        default:
+            return 1;
+    }
+}
+/**
+ * One stop for the slope math every roof-segment consumer needs. Builds
+ * `run`, `rise`, the trig triple, and the overall peak height from the
+ * segment's pitch + footprint + roofType. Before this helper existed,
+ * the table was duplicated in three places (the brush builder, the
+ * skylight surface-frame routine, and the segment-hit raycaster) and
+ * silently drifted when a new roof type was added.
+ */
+export function getSegmentSlopeFrame(node) {
+    const ratios = withRatioDefaults(node);
+    const run = getPrimarySlopeRun(ratios);
+    // `!(pitch > 0)` (not `pitch <= 0`) so a missing/NaN pitch — e.g. a segment
+    // from an older migration that only set `roofHeight`, or stale persisted data —
+    // resolves to a flat frame instead of computing `Math.tan(NaN)` → NaN geometry,
+    // which poisons the merged-roof CSG ("Coplanar clip not handled" + NaN positions).
+    if (node.roofType === 'flat' || !(node.pitch > 0)) {
+        return { run, rise: 0, tanTheta: 0, cosTheta: 1, sinTheta: 0, activeRh: 0 };
+    }
+    const pitchRad = (node.pitch * Math.PI) / 180;
+    const tanTheta = Math.tan(pitchRad);
+    const cosTheta = Math.cos(pitchRad) || 1;
+    const sinTheta = Math.sin(pitchRad);
+    const rise = run * tanTheta;
+    const activeRh = rise / getPrimarySlopeRiseFraction(ratios);
+    return { run, rise, tanTheta, cosTheta, sinTheta, activeRh };
+}
+/**
+ * The eave-to-peak height of the assembled segment, derived from pitch +
+ * footprint + roofType. Replaces the legacy `roofHeight` field on the node.
+ */
+export function getActiveRoofHeight(node) {
+    return getSegmentSlopeFrame(node).activeRh;
+}
+/** Segment-local surface height used by roof accessory placement and hit disambiguation. */
+export function getRoofSegmentSurfaceY(node, localX, localZ) {
+    const activeRh = getActiveRoofHeight(node);
+    const peakY = node.wallHeight + activeRh;
+    if (activeRh === 0)
+        return node.wallHeight;
+    if (node.roofType === 'gable' ||
+        node.roofType === 'gambrel' ||
+        node.roofType === 'mansard' ||
+        node.roofType === 'dutch') {
+        const t = node.depth > 0 ? Math.abs(localZ) / (node.depth / 2) : 0;
+        return peakY - t * activeRh;
+    }
+    if (node.roofType === 'shed') {
+        const t = (localZ + node.depth / 2) / (node.depth || 1);
+        return peakY - t * activeRh;
+    }
+    if (node.roofType === 'hip') {
+        const fx = node.width > 0 ? Math.abs(localX) / (node.width / 2) : 0;
+        const fz = node.depth > 0 ? Math.abs(localZ) / (node.depth / 2) : 0;
+        return peakY - Math.max(fx, fz) * activeRh;
+    }
+    const t = node.depth > 0 ? Math.abs(localZ) / (node.depth / 2) : 0;
+    return peakY - t * activeRh;
+}
+/**
+ * Inverse of `getActiveRoofHeight` — recover the pitch a legacy
+ * `roofHeight` value would correspond to. Used by the scene migration.
+ * Ratio overrides are optional and default to the shape defaults.
+ */
+export function getPitchFromActiveRoofHeight(input) {
+    if (input.roofType === 'flat' || input.roofHeight <= 0)
+        return 0;
+    const ratios = withRatioDefaults(input);
+    const run = getPrimarySlopeRun(ratios);
+    if (run <= 0)
+        return 0;
+    const rise = input.roofHeight * getPrimarySlopeRiseFraction(ratios);
+    return (Math.atan2(rise, run) * 180) / Math.PI;
+}
+function getLegacyRoofSegmentSurfaceMaterial(node) {
+    return {
+        material: node.material,
+        materialPreset: typeof node.materialPreset === 'string' ? node.materialPreset : undefined,
+    };
+}
+/**
+ * Resolve the segment-level material for one of the three surface roles.
+ * Falls back through: role-specific field → catch-all `material`. Pass the
+ * parent roof to `parentFallback` when you want the roof's role material
+ * to fill in for an unset segment slot — typical from the renderer.
+ */
+export function getEffectiveSegmentSurfaceMaterial(node, role, parentFallback) {
+    if (role === 'top') {
+        if (node.topMaterial !== undefined || typeof node.topMaterialPreset === 'string') {
+            return {
+                material: node.topMaterial,
+                materialPreset: typeof node.topMaterialPreset === 'string' ? node.topMaterialPreset : undefined,
+            };
+        }
+    }
+    else if (role === 'edge') {
+        if (node.edgeMaterial !== undefined || typeof node.edgeMaterialPreset === 'string') {
+            return {
+                material: node.edgeMaterial,
+                materialPreset: typeof node.edgeMaterialPreset === 'string' ? node.edgeMaterialPreset : undefined,
+            };
+        }
+    }
+    else if (role === 'wall') {
+        if (node.wallMaterial !== undefined || typeof node.wallMaterialPreset === 'string') {
+            return {
+                material: node.wallMaterial,
+                materialPreset: typeof node.wallMaterialPreset === 'string' ? node.wallMaterialPreset : undefined,
+            };
+        }
+    }
+    const legacy = getLegacyRoofSegmentSurfaceMaterial(node);
+    if (legacy.material !== undefined || legacy.materialPreset !== undefined)
+        return legacy;
+    return parentFallback ?? { material: undefined, materialPreset: undefined };
+}
+/**
+ * Returns true when the segment has any segment-level material override —
+ * either the legacy catch-all or any of the three role-specific fields.
+ * Used by `RoofRenderer` and `updateMergedRoofGeometry` to decide whether
+ * the segment should be drawn as its own mesh or folded into the merged
+ * shell.
+ */
+export function hasSegmentMaterialOverride(node) {
+    return (node.material !== undefined ||
+        typeof node.materialPreset === 'string' ||
+        node.topMaterial !== undefined ||
+        typeof node.topMaterialPreset === 'string' ||
+        node.edgeMaterial !== undefined ||
+        typeof node.edgeMaterialPreset === 'string' ||
+        node.wallMaterial !== undefined ||
+        typeof node.wallMaterialPreset === 'string');
+}

package/dist/schema/nodes/roof.d.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { type MaterialSchema } from '../material';
+import type { MaterialSchema as MaterialSchemaType } from '../material';
 export type RoofSurfaceMaterialRole = 'top' | 'edge' | 'wall';
 export type RoofSurfaceMaterialSpec = {
-    material?: MaterialSchema;
+    material?: MaterialSchemaType;
     materialPreset?: string;
 };
 export declare const RoofNode: z.ZodObject<{
@@ -26,6 +26,7 @@ export declare const RoofNode: z.ZodObject<{
     material: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         preset: z.ZodOptional<z.ZodEnum<{
+            custom: "custom";
             white: "white";
             brick: "brick";
             concrete: "concrete";
@@ -35,7 +36,6 @@ export declare const RoofNode: z.ZodObject<{
             plaster: "plaster";
             tile: "tile";
             marble: "marble";
-            custom: "custom";
         }>>;
         properties: z.ZodOptional<z.ZodObject<{
             color: z.ZodDefault<z.ZodString>;
@@ -59,6 +59,7 @@ export declare const RoofNode: z.ZodObject<{
     topMaterial: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         preset: z.ZodOptional<z.ZodEnum<{
+            custom: "custom";
             white: "white";
             brick: "brick";
             concrete: "concrete";
@@ -68,7 +69,6 @@ export declare const RoofNode: z.ZodObject<{
             plaster: "plaster";
             tile: "tile";
             marble: "marble";
-            custom: "custom";
         }>>;
         properties: z.ZodOptional<z.ZodObject<{
             color: z.ZodDefault<z.ZodString>;
@@ -92,6 +92,7 @@ export declare const RoofNode: z.ZodObject<{
     edgeMaterial: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         preset: z.ZodOptional<z.ZodEnum<{
+            custom: "custom";
             white: "white";
             brick: "brick";
             concrete: "concrete";
@@ -101,7 +102,6 @@ export declare const RoofNode: z.ZodObject<{
             plaster: "plaster";
             tile: "tile";
             marble: "marble";
-            custom: "custom";
         }>>;
         properties: z.ZodOptional<z.ZodObject<{
             color: z.ZodDefault<z.ZodString>;
@@ -125,6 +125,7 @@ export declare const RoofNode: z.ZodObject<{
     wallMaterial: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         preset: z.ZodOptional<z.ZodEnum<{
+            custom: "custom";
             white: "white";
             brick: "brick";
             concrete: "concrete";
@@ -134,7 +135,6 @@ export declare const RoofNode: z.ZodObject<{
             plaster: "plaster";
             tile: "tile";
             marble: "marble";
-            custom: "custom";
         }>>;
         properties: z.ZodOptional<z.ZodObject<{
             color: z.ZodDefault<z.ZodString>;

package/dist/schema/nodes/roof.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roof.d.ts","sourceRoot":"","sources":["../../../src/schema/nodes/roof.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,KAAK,cAAc,EAA0C,MAAM,aAAa,CAAA;AAGzF,MAAM,MAAM,uBAAuB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;AAC7D,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyBpB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA;AAS/C,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,uBAAuB,GAC5B,uBAAuB,CAmDzB"}
+{"version":3,"file":"roof.d.ts","sourceRoot":"","sources":["../../../src/schema/nodes/roof.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,cAAc,IAAI,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAIvE,MAAM,MAAM,uBAAuB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;AAC7D,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyBpB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA;AAS/C,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,uBAAuB,GAC5B,uBAAuB,CAoCzB"}