@pascal-app/core 0.8.0 → 0.9.1

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { MaterialSchema as MaterialSchemaType } from '../material';
 export declare const RoofType: z.ZodEnum<{
     flat: "flat";
     hip: "hip";
@@ -9,6 +10,20 @@ export declare const RoofType: z.ZodEnum<{
     mansard: "mansard";
 }>;
 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>;
@@ -60,6 +75,105 @@ 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<{
@@ -74,11 +188,91 @@ export declare const RoofSegmentNode: z.ZodObject<{
     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":"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"}

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.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,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,CAoDzB"}
+{"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"}

package/dist/schema/nodes/roof.js

@@ -58,21 +58,9 @@ export function getEffectiveRoofSurfaceMaterial(node, role) {
             };
         }
     }
-    if (role === 'edge') {
-        if (node.wallMaterial !== undefined || typeof node.wallMaterialPreset === 'string') {
-            return {
-                material: node.wallMaterial,
-                materialPreset: typeof node.wallMaterialPreset === 'string' ? node.wallMaterialPreset : undefined,
-            };
-        }
-    }
-    if (role === 'wall') {
-        if (node.edgeMaterial !== undefined || typeof node.edgeMaterialPreset === 'string') {
-            return {
-                material: node.edgeMaterial,
-                materialPreset: typeof node.edgeMaterialPreset === 'string' ? node.edgeMaterialPreset : undefined,
-            };
-        }
-    }
+    // No cross-role fallback: an unset role resolves only to the legacy
+    // catch-all (which covers all three roles for back-compat) and otherwise
+    // to the caller's theme default. Painting one surface must never bleed
+    // onto the others.
     return getLegacyRoofSurfaceMaterial(node);
 }

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

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+/**
+ * Parametric shelf — a configurable furniture unit with one or more
+ * horizontal boards that host other items.
+ *
+ * Four styles share the same dimensional schema:
+ *
+ *   - `wall-shelf` — open boards held by end brackets. `rows > 1` stacks
+ *     evenly-spaced boards. Brackets style: `minimal | industrial | hidden`.
+ *     The v1 archetype.
+ *   - `bookshelf` — full-height cabinet: side panels + multiple shelf
+ *     boards. `columns > 1` adds vertical dividers between sections.
+ *     `withBack` toggles a back panel. `withSides` toggles the side
+ *     panels (`false` = open silhouette held by cross-brace posts).
+ *   - `open-rack` — industrial wire-rack style: four corner posts, no
+ *     side panels, slim boards. `withBack` adds an X-brace.
+ *   - `cubby` — grid of pigeonhole cubicles: `rows × columns` cells
+ *     formed by full back + sides + inner dividers. Each cubicle hosts
+ *     items on its own bottom surface.
+ *
+ * `height` is the distance from floor to the underside of the topmost
+ * board (legacy v1 semantic, preserved so v1 scenes load with identical
+ * top-board placement). For `rows > 1`, boards are evenly spaced from
+ * `height / rows` up to `height`. For `cubby`, the height divides into
+ * `rows` equal-height cubicles.
+ *
+ * Items host on each row's top surface via `capabilities.surfaces.custom`.
+ */
+export declare const ShelfNode: z.ZodObject<{
+    object: z.ZodDefault<z.ZodLiteral<"node">>;
+    name: z.ZodOptional<z.ZodString>;
+    parentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    visible: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    camera: z.ZodOptional<z.ZodObject<{
+        position: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        target: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        mode: z.ZodDefault<z.ZodEnum<{
+            perspective: "perspective";
+            orthographic: "orthographic";
+        }>>;
+        fov: z.ZodOptional<z.ZodNumber>;
+        zoom: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    metadata: z.ZodDefault<z.ZodOptional<z.ZodJSONSchema>>;
+    id: z.ZodDefault<z.ZodTemplateLiteral<`shelf_${string}`>>;
+    type: z.ZodDefault<z.ZodLiteral<"shelf">>;
+    children: z.ZodDefault<z.ZodArray<z.ZodDefault<z.ZodTemplateLiteral<`item_${string}`>>>>;
+    position: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    rotation: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    width: z.ZodDefault<z.ZodNumber>;
+    depth: z.ZodDefault<z.ZodNumber>;
+    thickness: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+    style: z.ZodDefault<z.ZodEnum<{
+        "wall-shelf": "wall-shelf";
+        bookshelf: "bookshelf";
+        "open-rack": "open-rack";
+        cubby: "cubby";
+    }>>;
+    rows: z.ZodDefault<z.ZodNumber>;
+    columns: z.ZodDefault<z.ZodNumber>;
+    withBack: z.ZodDefault<z.ZodBoolean>;
+    withSides: z.ZodDefault<z.ZodBoolean>;
+    withBottom: z.ZodDefault<z.ZodBoolean>;
+    bracketStyle: z.ZodDefault<z.ZodEnum<{
+        minimal: "minimal";
+        industrial: "industrial";
+        hidden: "hidden";
+    }>>;
+    material: 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>>;
+    materialPreset: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ShelfNode = z.infer<typeof ShelfNode>;
+//# sourceMappingURL=shelf.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shelf.d.ts","sourceRoot":"","sources":["../../../src/schema/nodes/shelf.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAKvB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwDpB,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA"}