Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

28.0 KB
Raw Blame
/** Correct-by-construction architecture scaffolds in Kiln's +X/+Y/+Z frame. */
import * as THREE from 'three';
import { buildWallPanels } from './wall-panels';
import { assertDimension, assertRepetitionCount } from './geometry-budget';
import { checkedTrs } from './assembly-transform';

import {
  KILN_SEMANTIC_ROLES,
  semanticRole,
  stampSemanticMetadataV1,
  type SemanticLocalFrameV1,
  type SemanticRelationshipV1,
} from './contracts';

export type RidgeAxis = 'x' | 'z';
export type RoofSide = 'positive' | 'negative';

export interface GableRoofOptions {
  /** Exact footprint extent along world/local X, in meters. */
  spanX: number;
  /** Exact footprint extent along world/local Z, in meters. */
  spanZ: number;
  /** Ridge rise above the wall bearing line. Supply rise or pitchDegrees. */
  rise?: number;
  /** Pitch from horizontal. Supply pitchDegrees or rise. */
  pitchDegrees?: number;
  overhang?: number;
  ridgeAxis?: RidgeAxis;
  thickness?: number;
  parent?: THREE.Object3D;
}

export interface RoofFaceDimensions {
  alongRidge: number;
  downhill: number;
  thickness: number;
}

/**
 * A face-owned rigid frame. Local +X is ridge tangent, +Y is outward normal,
 * and +Z is downhill. World properties are getters, so parent transforms made
 * after construction cannot stale them.
 */
export interface RoofFaceFrame {
  side: RoofSide;
  ridgeAxis: RidgeAxis;
  roofRoot: THREE.Object3D;
  localToRoof: THREE.Matrix4;
  readonly localToWorld: THREE.Matrix4;
  readonly ridgeTangent: THREE.Vector3;
  readonly downhillDirection: THREE.Vector3;
  readonly outwardNormal: THREE.Vector3;
  readonly ridgeStart: THREE.Vector3;
  readonly ridgeEnd: THREE.Vector3;
  readonly eaveStart: THREE.Vector3;
  readonly eaveEnd: THREE.Vector3;
  dimensions: RoofFaceDimensions;
}

export interface GableRoofResult {
  root: THREE.Object3D;
  slopes: [THREE.Object3D, THREE.Object3D];
  faces: [RoofFaceFrame, RoofFaceFrame];
  rise: number;
  pitchDegrees: number;
}

export interface RoofPlanesOptions {
  /** Footprint extent along Z. */
  width: number;
  /** Footprint extent along X. */
  depth: number;
  /** Rise from the outer eave (Y=0) to the ridge. */
  height: number;
  overhang?: number;
  ridgeAxis?: RidgeAxis;
  thickness?: number;
  parent?: THREE.Object3D;
}

export interface GableOpening {
  id?: string;
  offset?: number;
  bottom?: number;
  width: number;
  height: number;
}

export interface GableEndPanelOptions {
  span: number;
  rise: number;
  thickness?: number;
  ridgeAxis?: RidgeAxis;
  side?: RoofSide;
  openings?: readonly GableOpening[];
  parent?: THREE.Object3D;
}

export interface GableEndPanelResult {
  root: THREE.Object3D;
  geometry: THREE.BufferGeometry;
  openings: THREE.Object3D[];
}

export type ShellWall = 'front' | 'back' | 'left' | 'right';

export interface GableShellOpening {
  id?: string;
  wall: ShellWall;
  kind?: 'door' | 'window';
  offset?: number;
  width?: number;
  height?: number;
  sill?: number;
  depth?: number;
}

export interface GableShellMaterials {
  wall: THREE.Material;
  roof: THREE.Material;
  floor?: THREE.Material;
  gable?: THREE.Material;
}

export interface GableShellOptions extends GableRoofOptions {
  wallHeight?: number;
  wallThickness?: number;
  floorThickness?: number;
  closedEnds?: boolean;
  enterable?: boolean;
  openings?: readonly GableShellOpening[];
  gableOpenings?: Partial<Record<RoofSide, readonly GableOpening[]>>;
}

export interface GableShellResult {
  root: THREE.Object3D;
  walls: Record<ShellWall, THREE.Object3D>;
  floor: THREE.Object3D;
  roof: GableRoofResult;
  gables: [THREE.Object3D, THREE.Object3D] | [];
  openings: THREE.Object3D[];
}

export type RoofSurfaceLayoutKind = 'panels' | 'shingles' | 'seams' | 'corrugations';

export interface RoofSurfaceLayoutOptions {
  face: RoofFaceFrame;
  kind: RoofSurfaceLayoutKind;
  parent?: THREE.Object3D;
  panelWidth?: number;
  rowHeight?: number;
  spacing?: number;
  thickness?: number;
}

export interface RoofSurfaceLayoutResult {
  root: THREE.Object3D;
  items: THREE.Object3D[];
  /** Explicit box geometry cost; not an instancing or draw-call estimate. */
  cost: { meshes: number; triangles: number };
}

const DEG = Math.PI / 180;
const EPSILON = 1e-7;

function positive(value: number, name: string): number {
  if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${name} must be finite and > 0`);
  return value;
}

function nonNegative(value: number, name: string): number {
  if (!Number.isFinite(value) || value < 0) throw new RangeError(`${name} must be finite and >= 0`);
  return value;
}

function roleMetadata(
  roles: readonly string[],
  relationships: readonly SemanticRelationshipV1[] = [],
  frames: readonly SemanticLocalFrameV1[] = [],
) {
  return { roles, relationships, frames, sockets: [] };
}

function relationship(kind: string, target: string): SemanticRelationshipV1 {
  return { kind, target, targetType: 'role' };
}

function setTransform(object: THREE.Object3D, matrix: THREE.Matrix4): void {
  matrix.decompose(object.position, object.quaternion, object.scale);
}

function resolvePitch(
  halfRun: number,
  rise: number | undefined,
  pitchDegrees: number | undefined,
): { rise: number; pitchDegrees: number } {
  positive(halfRun, 'roof half-run');
  if (rise === undefined && pitchDegrees === undefined) pitchDegrees = 30;
  if (pitchDegrees !== undefined) {
    if (!Number.isFinite(pitchDegrees) || pitchDegrees <= 0 || pitchDegrees >= 89) {
      throw new RangeError('pitchDegrees must be finite, > 0, and < 89');
    }
  }
  if (rise !== undefined) positive(rise, 'rise');
  const resolvedPitch = pitchDegrees ?? Math.atan2(rise!, halfRun) / DEG;
  const resolvedRise = rise ?? Math.tan(resolvedPitch * DEG) * halfRun;
  const expected = Math.tan(resolvedPitch * DEG) * halfRun;
  if (Math.abs(resolvedRise - expected) > Math.max(EPSILON, expected * 1e-6)) {
    throw new RangeError('rise and pitchDegrees disagree for the requested footprint');
  }
  return { rise: resolvedRise, pitchDegrees: resolvedPitch };
}

interface ResolvedRoofProfile {
  spanX: number;
  spanZ: number;
  ridgeAxis: RidgeAxis;
  overhang: number;
  thickness: number;
  rise: number;
  pitchDegrees: number;
  ridgeY: number;
  eaveY: number;
}

function resolveRoofProfile(options: GableRoofOptions): ResolvedRoofProfile {
  const spanX = positive(options.spanX, 'spanX');
  const spanZ = positive(options.spanZ, 'spanZ');
  const ridgeAxis = options.ridgeAxis ?? 'x';
  const overhang = nonNegative(options.overhang ?? 0.3, 'overhang');
  const thickness = positive(options.thickness ?? 0.08, 'thickness');
  const halfRun = (ridgeAxis === 'x' ? spanZ : spanX) / 2;
  const pitch = resolvePitch(halfRun, options.rise, options.pitchDegrees);
  return {
    spanX,
    spanZ,
    ridgeAxis,
    overhang,
    thickness,
    ...pitch,
    ridgeY: pitch.rise,
    eaveY: -Math.tan(pitch.pitchDegrees * DEG) * overhang,
  };
}

function buildFace(
  roofRoot: THREE.Object3D,
  profile: ResolvedRoofProfile,
  sideSign: 1 | -1,
): RoofFaceFrame {
  const side: RoofSide = sideSign > 0 ? 'positive' : 'negative';
  const halfFoot = (profile.ridgeAxis === 'x' ? profile.spanZ : profile.spanX) / 2;
  const horizontalRun = halfFoot + profile.overhang;
  const verticalRun = profile.ridgeY - profile.eaveY;
  const downhillLength = Math.hypot(horizontalRun, verticalRun);
  const alongRidge =
    (profile.ridgeAxis === 'x' ? profile.spanX : profile.spanZ) + profile.overhang * 2;
  const downhill =
    profile.ridgeAxis === 'x'
      ? new THREE.Vector3(0, -verticalRun, sideSign * horizontalRun).normalize()
      : new THREE.Vector3(sideSign * horizontalRun, -verticalRun, 0).normalize();
  const tangent =
    profile.ridgeAxis === 'x'
      ? new THREE.Vector3(sideSign, 0, 0)
      : new THREE.Vector3(0, 0, -sideSign);
  const normal = downhill.clone().cross(tangent).normalize();
  const localToRoof = new THREE.Matrix4().makeBasis(tangent, normal, downhill);
  localToRoof.setPosition(0, profile.ridgeY, 0);

  const world = (): THREE.Matrix4 => {
    roofRoot.updateWorldMatrix(true, false);
    return roofRoot.matrixWorld.clone().multiply(localToRoof);
  };
  const direction = (axis: THREE.Vector3): THREE.Vector3 =>
    axis.clone().transformDirection(world());
  const point = (x: number, z: number): THREE.Vector3 =>
    new THREE.Vector3(x, 0, z).applyMatrix4(world());

  return {
    side,
    ridgeAxis: profile.ridgeAxis,
    roofRoot,
    localToRoof,
    get localToWorld() {
      return world();
    },
    get ridgeTangent() {
      return direction(new THREE.Vector3(1, 0, 0));
    },
    get downhillDirection() {
      return direction(new THREE.Vector3(0, 0, 1));
    },
    get outwardNormal() {
      return direction(new THREE.Vector3(0, 1, 0));
    },
    get ridgeStart() {
      return point(-alongRidge / 2, 0);
    },
    get ridgeEnd() {
      return point(alongRidge / 2, 0);
    },
    get eaveStart() {
      return point(-alongRidge / 2, downhillLength);
    },
    get eaveEnd() {
      return point(alongRidge / 2, downhillLength);
    },
    dimensions: { alongRidge, downhill: downhillLength, thickness: profile.thickness },
  };
}

function buildRoof(
  name: string,
  material: THREE.Material,
  profile: ResolvedRoofProfile,
  parent?: THREE.Object3D,
): GableRoofResult {
  const root = new THREE.Object3D();
  root.name = name;
  if (parent) parent.add(root);
  stampSemanticMetadataV1(
    root,
    roleMetadata(
      [semanticRole(KILN_SEMANTIC_ROLES.roof, 'assembly')],
      [relationship('separable-from', 'architecture.shell.gable')],
    ),
  );

  const faces = [buildFace(root, profile, 1), buildFace(root, profile, -1)] as const;
  const buildSlope = (face: RoofFaceFrame): THREE.Object3D => {
    const geometry = new THREE.BoxGeometry(
      face.dimensions.alongRidge,
      profile.thickness,
      face.dimensions.downhill,
    );
    const mesh = new THREE.Mesh(geometry, material);
    mesh.name = `Mesh_${name}_${face.side}`;
    const center = new THREE.Matrix4().makeTranslation(
      0,
      -profile.thickness / 2,
      face.dimensions.downhill / 2,
    );
    setTransform(mesh, face.localToRoof.clone().multiply(center));
    const coveredWall =
      profile.ridgeAxis === 'x'
        ? face.side === 'positive'
          ? 'wall.right'
          : 'wall.left'
        : face.side === 'positive'
          ? 'wall.front'
          : 'wall.back';
    stampSemanticMetadataV1(
      mesh,
      roleMetadata(
        [semanticRole(KILN_SEMANTIC_ROLES.roof, 'slope', face.side)],
        [
          relationship(
            'adjacent-to',
            semanticRole(
              KILN_SEMANTIC_ROLES.roof,
              'slope',
              face.side === 'positive' ? 'negative' : 'positive',
            ),
          ),
          relationship('coverage-of', coveredWall),
          relationship('separable-from', 'architecture.shell.gable'),
        ],
        [
          { id: 'surface', translation: [0, profile.thickness / 2, 0], rotation: [0, 0, 0, 1] },
          {
            id: 'ridge',
            translation: [0, profile.thickness / 2, -face.dimensions.downhill / 2],
            rotation: [0, 0, 0, 1],
          },
          {
            id: 'eave',
            translation: [0, profile.thickness / 2, face.dimensions.downhill / 2],
            rotation: [0, 0, 0, 1],
          },
        ],
      ),
    );
    root.add(mesh);
    return mesh;
  };
  const slopes: [THREE.Object3D, THREE.Object3D] = [buildSlope(faces[0]), buildSlope(faces[1])];
  return {
    root,
    slopes,
    faces: [faces[0], faces[1]],
    rise: profile.rise,
    pitchDegrees: profile.pitchDegrees,
  };
}

/** Explicit-axis, wall-bearing gable roof. */
export function createGableRoof(
  name: string,
  material: THREE.Material,
  options: GableRoofOptions,
): GableRoofResult {
  return buildRoof(name, material, resolveRoofProfile(options), options.parent);
}

/** Outer-eave datum roof: width spans Z, depth spans X, outer top eave at Y=0. */
export function createRoofPlanes(
  name: string,
  material: THREE.Material,
  options: RoofPlanesOptions,
): GableRoofResult {
  const ridgeAxis = options.ridgeAxis ?? 'x';
  const overhang = nonNegative(options.overhang ?? 0.3, 'overhang');
  const halfFoot =
    (ridgeAxis === 'x' ? positive(options.width, 'width') : positive(options.depth, 'depth')) / 2;
  const totalRun = halfFoot + overhang;
  const height = positive(options.height, 'height');
  const pitchDegrees = Math.atan2(height, totalRun) / DEG;
  const profile = resolveRoofProfile({
    spanX: options.depth,
    spanZ: options.width,
    ridgeAxis,
    overhang,
    thickness: options.thickness,
    rise: Math.tan(pitchDegrees * DEG) * halfFoot,
  });
  // This constructor uses the outer-eave datum; createGableRoof uses wall bearing.
  profile.ridgeY = height;
  profile.eaveY = 0;
  profile.pitchDegrees = pitchDegrees;
  return buildRoof(name, material, profile, options.parent);
}

function openingFitsTriangle(
  opening: Required<Omit<GableOpening, 'id'>>,
  span: number,
  rise: number,
): boolean {
  const half = span / 2;
  const left = opening.offset - opening.width / 2;
  const right = opening.offset + opening.width / 2;
  const top = opening.bottom + opening.height;
  const maxAt = (u: number) => rise * (1 - Math.abs(u) / half);
  return (
    left > -half && right < half && opening.bottom >= 0 && top < Math.min(maxAt(left), maxAt(right))
  );
}

/** Exact extruded triangular gable panel with optional rectangular holes. */
export function createGableEndPanel(
  name: string,
  material: THREE.Material,
  options: GableEndPanelOptions,
): GableEndPanelResult {
  const span = positive(options.span, 'span');
  const rise = positive(options.rise, 'rise');
  const thickness = positive(options.thickness ?? 0.15, 'thickness');
  const ridgeAxis = options.ridgeAxis ?? 'x';
  const side = options.side ?? 'positive';
  const half = span / 2;
  const shape = new THREE.Shape();
  shape.moveTo(-half, 0);
  shape.lineTo(half, 0);
  shape.lineTo(0, rise);
  shape.closePath();

  const normalized = (options.openings ?? []).map((opening) => ({
    id: opening.id,
    offset: opening.offset ?? 0,
    bottom: opening.bottom ?? 0.25,
    width: positive(opening.width, 'opening.width'),
    height: positive(opening.height, 'opening.height'),
  }));
  for (const opening of normalized) {
    if (!openingFitsTriangle(opening, span, rise))
      throw new RangeError('gable opening must fit strictly inside the triangular boundary');
    const left = opening.offset - opening.width / 2;
    const right = opening.offset + opening.width / 2;
    const bottom = opening.bottom;
    const top = bottom + opening.height;
    const hole = new THREE.Path();
    hole.moveTo(left, bottom);
    hole.lineTo(left, top);
    hole.lineTo(right, top);
    hole.lineTo(right, bottom);
    hole.closePath();
    shape.holes.push(hole);
  }

  const geometry = new THREE.ExtrudeGeometry(shape, {
    depth: thickness,
    bevelEnabled: false,
    steps: 1,
  });
  geometry.translate(0, 0, -thickness / 2);
  if (ridgeAxis === 'x') geometry.rotateY(-Math.PI / 2);
  geometry.computeVertexNormals();
  const root = new THREE.Mesh(geometry, material);
  root.name = `Mesh_${name}`;
  stampSemanticMetadataV1(
    root,
    roleMetadata(
      [`roof.gable.${side}`],
      [
        relationship('adjacent-to', 'roof.slope.positive'),
        relationship('adjacent-to', 'roof.slope.negative'),
        relationship(
          'coverage-of',
          ridgeAxis === 'x'
            ? side === 'positive'
              ? 'wall.front'
              : 'wall.back'
            : side === 'positive'
              ? 'wall.right'
              : 'wall.left',
        ),
        relationship('separable-from', 'architecture.shell.gable'),
      ],
      [
        { id: 'base', translation: [0, 0, 0], rotation: [0, 0, 0, 1] },
        {
          id: 'apex',
          translation: ridgeAxis === 'x' ? [0, rise, 0] : [0, rise, 0],
          rotation: [0, 0, 0, 1],
        },
      ],
    ),
  );
  const markers = normalized.map((opening, index) => {
    const marker = new THREE.Object3D();
    marker.name = `Opening_${name}_${opening.id ?? index + 1}`;
    marker.position.set(
      ridgeAxis === 'z' ? opening.offset : 0,
      opening.bottom + opening.height / 2,
      ridgeAxis === 'x' ? opening.offset : 0,
    );
    marker.scale.set(
      ridgeAxis === 'x' ? thickness : opening.width,
      opening.height,
      ridgeAxis === 'x' ? opening.width : thickness,
    );
    stampSemanticMetadataV1(
      marker,
      roleMetadata(
        [`opening.gable.${side}.${opening.id ?? index + 1}`],
        [relationship('cutout-of', `roof.gable.${side}`)],
      ),
    );
    root.add(marker);
    return marker;
  });
  if (options.parent) options.parent.add(root);
  return { root, geometry, openings: markers };
}

function wallRunAxis(wall: ShellWall): RidgeAxis {
  return wall === 'front' || wall === 'back' ? 'z' : 'x';
}

function wallNeighbors(wall: ShellWall): [ShellWall, ShellWall] {
  return wall === 'front' || wall === 'back' ? ['left', 'right'] : ['front', 'back'];
}

function createShellWall(
  name: string,
  wall: ShellWall,
  material: THREE.Material,
  length: number,
  height: number,
  thickness: number,
  openings: readonly GableShellOpening[],
): { root: THREE.Object3D; openings: THREE.Object3D[] } {
  const axis = wallRunAxis(wall);
  const root = new THREE.Object3D();
  root.name = `${name}_Wall_${wall}`;
  const neighbors = wallNeighbors(wall);
  stampSemanticMetadataV1(
    root,
    roleMetadata(
      [`wall.${wall}`],
      [
        relationship('adjacent-to', `wall.${neighbors[0]}`),
        relationship('adjacent-to', `wall.${neighbors[1]}`),
        relationship('adjacent-to', 'floor'),
      ],
    ),
  );

  const built = buildWallPanels(length, height, thickness, openings);

  const panel = (suffix: string, lo: number, hi: number, y0: number, y1: number): void => {
    if (hi <= lo || y1 <= y0) return;
    const geometry =
      axis === 'x'
        ? new THREE.BoxGeometry(hi - lo, y1 - y0, thickness)
        : new THREE.BoxGeometry(thickness, y1 - y0, hi - lo);
    const mesh = new THREE.Mesh(geometry, material);
    mesh.name = `Mesh_${name}_${wall}_${suffix}`;
    mesh.position.set(
      axis === 'x' ? (lo + hi) / 2 : 0,
      (y0 + y1) / 2,
      axis === 'z' ? (lo + hi) / 2 : 0,
    );
    root.add(mesh);
  };
  const markers: THREE.Object3D[] = [];
  const singleNames: Record<string, string> = {
    '': 'solid',
    _L: 'left',
    _R: 'right',
    _Lintel: 'lintel',
    _Sill: 'sill',
  };
  for (const segment of built.panels) {
    panel(
      singleNames[segment.suffix] ?? segment.suffix.slice(1),
      segment.left,
      segment.right,
      segment.bottom,
      segment.top,
    );
  }
  for (const opening of built.openings) {
    const marker = new THREE.Object3D();
    marker.name = `Opening_${wall}_${opening.id}`;
    marker.position.set(
      axis === 'x' ? opening.offset : 0,
      opening.sill + opening.height / 2,
      axis === 'z' ? opening.offset : 0,
    );
    marker.scale.set(
      axis === 'x' ? opening.width : opening.depth,
      opening.height,
      axis === 'z' ? opening.width : opening.depth,
    );
    stampSemanticMetadataV1(
      marker,
      roleMetadata(
        [`opening.${wall}.${opening.kind}`],
        [
          relationship('cutout-of', `wall.${wall}`),
          relationship(
            opening.kind === 'door' ? 'portal-through' : 'aperture-through',
            `wall.${wall}`,
          ),
        ],
        [{ id: 'clearance', translation: [0, 0, 0], rotation: [0, 0, 0, 1] }],
      ),
    );
    root.add(marker);
    markers.push(marker);
  }
  return { root, openings: markers };
}

/** Closed-by-default room, floor, two roof slopes, and two exact gable ends. */
export function createGableShell(
  name: string,
  materials: GableShellMaterials,
  options: GableShellOptions,
): GableShellResult {
  const spanX = positive(options.spanX, 'spanX');
  const spanZ = positive(options.spanZ, 'spanZ');
  const wallHeight = positive(options.wallHeight ?? 2.8, 'wallHeight');
  const wallThickness = positive(options.wallThickness ?? 0.15, 'wallThickness');
  const floorThickness = positive(options.floorThickness ?? 0.1, 'floorThickness');
  const ridgeAxis = options.ridgeAxis ?? 'x';
  const closedEnds = options.closedEnds ?? true;
  const enterable = options.enterable ?? true;
  const shellOpenings =
    options.openings ?? (enterable ? [{ wall: 'front' as const, kind: 'door' as const }] : []);
  const root = new THREE.Object3D();
  root.name = name;
  stampSemanticMetadataV1(
    root,
    roleMetadata(
      ['architecture.shell.gable'],
      [relationship('contains', 'floor'), relationship('contains', 'roof.assembly')],
    ),
  );

  const wallSpecs: Record<ShellWall, { length: number; position: [number, number, number] }> = {
    front: { length: spanZ, position: [spanX / 2, 0, 0] },
    back: { length: spanZ, position: [-spanX / 2, 0, 0] },
    left: { length: spanX, position: [0, 0, -spanZ / 2] },
    right: { length: spanX, position: [0, 0, spanZ / 2] },
  };
  const walls = {} as Record<ShellWall, THREE.Object3D>;
  const openingMarkers: THREE.Object3D[] = [];
  for (const wall of ['front', 'back', 'left', 'right'] as const) {
    const built = createShellWall(
      name,
      wall,
      materials.wall,
      wallSpecs[wall].length,
      wallHeight,
      wallThickness,
      shellOpenings.filter((opening) => opening.wall === wall),
    );
    built.root.position.set(...wallSpecs[wall].position);
    root.add(built.root);
    walls[wall] = built.root;
    openingMarkers.push(...built.openings);
  }
  const floor = new THREE.Mesh(
    new THREE.BoxGeometry(spanX, floorThickness, spanZ),
    materials.floor ?? materials.wall,
  );
  floor.name = `Mesh_${name}_Floor`;
  floor.position.y = -floorThickness / 2;
  stampSemanticMetadataV1(
    floor,
    roleMetadata(
      ['floor'],
      ['front', 'back', 'left', 'right'].map((wall) => relationship('adjacent-to', `wall.${wall}`)),
    ),
  );
  root.add(floor);

  const roof = createGableRoof('Roof', materials.roof, {
    ...options,
    spanX,
    spanZ,
    ridgeAxis,
    parent: root,
  });
  roof.root.position.y = wallHeight;
  let gables: [THREE.Object3D, THREE.Object3D] | [] = [];
  if (closedEnds) {
    const gableMaterial = materials.gable ?? materials.wall;
    const span = ridgeAxis === 'x' ? spanZ : spanX;
    const ridgeSpan = ridgeAxis === 'x' ? spanX : spanZ;
    const positiveEnd = createGableEndPanel(`${name}_Gable_positive`, gableMaterial, {
      span,
      rise: roof.rise,
      thickness: wallThickness,
      ridgeAxis,
      side: 'positive',
      openings: options.gableOpenings?.positive,
      parent: roof.root,
    });
    const negativeEnd = createGableEndPanel(`${name}_Gable_negative`, gableMaterial, {
      span,
      rise: roof.rise,
      thickness: wallThickness,
      ridgeAxis,
      side: 'negative',
      openings: options.gableOpenings?.negative,
      parent: roof.root,
    });
    const coordinate = ridgeSpan / 2;
    positiveEnd.root.position.set(
      ridgeAxis === 'x' ? coordinate : 0,
      0,
      ridgeAxis === 'z' ? coordinate : 0,
    );
    negativeEnd.root.position.set(
      ridgeAxis === 'x' ? -coordinate : 0,
      0,
      ridgeAxis === 'z' ? -coordinate : 0,
    );
    gables = [positiveEnd.root, negativeEnd.root];
    openingMarkers.push(...positiveEnd.openings, ...negativeEnd.openings);
  }
  if (options.parent) options.parent.add(root);
  return { root, walls, floor, roof, gables, openings: openingMarkers };
}

/** Matrix-driven roof-local panels, shingles, seams, or corrugations. */
export function createRoofSurfaceLayout(
  name: string,
  material: THREE.Material,
  options: RoofSurfaceLayoutOptions,
): RoofSurfaceLayoutResult {
  if (!['panels', 'shingles', 'seams', 'corrugations'].includes(options.kind))
    throw new RangeError('createRoofSurfaceLayout: unknown kind.');
  const thickness = options.thickness ?? 0.025;
  const along = options.face.dimensions.alongRidge;
  const downhill = options.face.dimensions.downhill;
  for (const [key, value] of Object.entries({ thickness, alongRidge: along, downhill }))
    assertDimension(`createRoofSurfaceLayout ${key}`, value);
  const parent = options.parent ?? options.face.roofRoot;
  parent.updateWorldMatrix(true, false);
  if (!Number.isFinite(parent.matrixWorld.determinant()) || parent.matrixWorld.determinant() === 0)
    throw new Error('createRoofSurfaceLayout: parent transform is singular or nonfinite.');
  const faceToRoot = parent.matrixWorld.clone().invert().multiply(options.face.localToWorld);
  // A separate parent can introduce shear that cannot survive editable TRS/export.
  // The face's own roof root cancels inherited affine transforms losslessly.
  checkedTrs(faceToRoot, 'createRoofSurfaceLayout (use face.roofRoot for inherited shear)');
  const specs: Array<{ width: number; length: number; x: number; z: number }> = [];

  if (options.kind === 'panels') {
    const panelWidth = positive(options.panelWidth ?? 0.9, 'panelWidth');
    const count = Math.max(1, Math.ceil(along / panelWidth));
    assertRepetitionCount('createRoofSurfaceLayout panels', count);
    const width = along / count;
    for (let i = 0; i < count; i++)
      specs.push({
        width: width * 0.98,
        length: downhill,
        x: -along / 2 + width * (i + 0.5),
        z: downhill / 2,
      });
  } else if (options.kind === 'shingles') {
    const rowHeight = positive(options.rowHeight ?? 0.32, 'rowHeight');
    const tileWidth = positive(options.panelWidth ?? 0.42, 'panelWidth');
    const rows = Math.max(1, Math.ceil(downhill / rowHeight));
    const evenColumns = Math.ceil(along / tileWidth);
    const oddColumns = Math.ceil(along / tileWidth + 0.5);
    assertRepetitionCount(
      'createRoofSurfaceLayout shingles',
      Math.ceil(rows / 2) * evenColumns + Math.floor(rows / 2) * oddColumns,
    );
    for (let row = 0; row < rows; row++) {
      const zMin = row * rowHeight;
      const length = Math.min(rowHeight * 1.08, downhill - zMin);
      const columns = row % 2 === 0 ? evenColumns : oddColumns;
      const offset = row % 2 === 0 ? 0 : -tileWidth / 2;
      for (let column = 0; column < columns; column++) {
        const start = offset + column * tileWidth;
        const left = Math.max(0, start);
        const right = Math.min(along, start + tileWidth);
        if (right <= left) continue;
        specs.push({
          width: (right - left) * 0.96,
          length,
          x: -along / 2 + (left + right) / 2,
          z: zMin + length / 2,
        });
      }
    }
  } else {
    const spacing = positive(options.spacing ?? (options.kind === 'seams' ? 0.6 : 0.18), 'spacing');
    const width = options.kind === 'seams' ? 0.025 : 0.018;
    // A face narrower than one strip needs one clipped strip, not overlapping duplicates.
    const count = along <= width ? 1 : Math.max(2, Math.floor(along / spacing) + 1);
    assertRepetitionCount('createRoofSurfaceLayout strips', count);
    for (let i = 0; i < count; i++) {
      const center = count === 1 ? 0 : -along / 2 + (along * i) / (count - 1);
      const left = Math.max(-along / 2, center - width / 2);
      const right = Math.min(along / 2, center + width / 2);
      specs.push({ width: right - left, length: downhill, x: (left + right) / 2, z: downhill / 2 });
    }
  }
  for (const spec of specs) {
    assertDimension('createRoofSurfaceLayout generated width', spec.width);
    assertDimension('createRoofSurfaceLayout generated length', spec.length);
  }
  const root = new THREE.Object3D();
  root.name = name;
  stampSemanticMetadataV1(
    root,
    roleMetadata(
      [`roof.surface.${options.kind}`],
      [relationship('coverage-of', `roof.slope.${options.face.side}`)],
    ),
  );
  const items = specs.map((spec, index) => {
    const mesh = new THREE.Mesh(
      new THREE.BoxGeometry(spec.width, thickness, spec.length),
      material,
    );
    mesh.name = `Mesh_${name}_${index + 1}`;
    const local = new THREE.Matrix4().makeTranslation(spec.x, thickness / 2 + 0.002, spec.z);
    setTransform(mesh, faceToRoot.clone().multiply(local));
    root.add(mesh);
    return mesh;
  });
  // No caller hierarchy mutation occurs until every validation and construction succeeds.
  parent.add(root);
  return { root, items, cost: { meshes: items.length, triangles: items.length * 12 } };
}