@pascal-app/core 0.8.0 → 0.9.2

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

@@ -0,0 +1,101 @@
+import type { RoofSegmentNode } from './roof-segment';
+/**
+ * Wall-face math for roof segments — the vertical surfaces a wall-mounted
+ * opening (door / window) can attach to. A segment's generated volume has
+ * four vertical faces; on gable-family roofs the end faces extend past the
+ * eave line into the gable (rect + triangle/pentagon, coplanar with the
+ * base wall). These helpers describe each face as a 2D frame
+ * (`u` along the face, `v` height above the segment base) plus the
+ * placeable profile polygon, so placement tools, renderers, and CSG cut
+ * builders all share one definition of "the wall under the roof".
+ *
+ * The numbers MUST mirror the outer wall volume built by
+ * `getRoofSegmentBrushes` in the viewer's roof system
+ * (`getVol(wallThickness / 2, 0, 0, …)`): the volume is the segment
+ * footprint extended outward by `wallThickness / 2`, which drops the eave
+ * line by `(wallThickness / 2) · tanθ` and raises the ridge by the same
+ * amount so the apex stays at `wallHeight + activeRh`.
+ */
+export type RoofWallFaceId = 'front' | 'back' | 'right' | 'left';
+export type RoofSegmentWallFace = {
+    id: RoofWallFaceId;
+    /** Outward normal in segment-local space. */
+    normal: [number, number, number];
+    /**
+     * Yaw (radians, rotation-y) mapping opening-local +Z to the outward
+     * normal and opening-local +X to the face's +U direction — the same
+     * frame a wall-hosted door/window uses relative to its wall mesh.
+     */
+    yaw: number;
+    /** Face length along U. */
+    length: number;
+    /**
+     * Placeable region, CCW polygon in face coords. `u ∈ [0, length]`,
+     * `v` is height above the segment base (segment-local Y).
+     */
+    profile: [number, number][];
+};
+type SegmentWallInputs = Pick<RoofSegmentNode, 'roofType' | 'width' | 'depth' | 'wallHeight' | 'wallThickness' | 'pitch'> & Partial<Pick<RoofSegmentNode, 'gambrelLowerWidthRatio' | 'gambrelLowerHeightRatio' | 'mansardSteepWidthRatio' | 'mansardSteepHeightRatio' | 'dutchHipWidthRatio' | 'dutchHipHeightRatio' | 'dutchWaistLengthRatio'>>;
+export declare function getRoofSegmentWallFace(node: SegmentWallInputs, id: RoofWallFaceId): RoofSegmentWallFace;
+export declare function getRoofSegmentWallFaces(node: SegmentWallInputs): RoofSegmentWallFace[];
+/**
+ * Segment-local point → face coords. `dist` is the signed offset off the
+ * outer wall plane along the face normal (0 = on the plane, positive =
+ * outside the volume).
+ */
+export declare function segmentPointToRoofWallFace(node: SegmentWallInputs, id: RoofWallFaceId, point: [number, number, number]): {
+    u: number;
+    v: number;
+    dist: number;
+};
+/**
+ * The face's render frame in segment-local space: a group placed at
+ * `origin` and yawed by `yaw` maps face coords to segment space —
+ * frame X = U (along the face), frame Y = V (height), frame Z = the
+ * outward normal, with z = 0 on the WALL MID-PLANE. The mid-plane of
+ * the generated wall volume lands exactly on the nominal footprint
+ * (`±width/2` / `±depth/2`), so hosted children use the same position
+ * conventions as wall children (openings at z = 0, wall-side items
+ * pushed +thickness/2 at render time). Renderers derive this from the
+ * live-override-merged segment, which is what makes hosted children
+ * track segment edits live instead of jumping on commit.
+ */
+export declare function getRoofWallFaceFrame(node: SegmentWallInputs, id: RoofWallFaceId): {
+    origin: [number, number, number];
+    yaw: number;
+};
+/** Face-frame point ([u, v, z-from-mid-plane]) → segment-local point. */
+export declare function roofFacePointToSegment(node: SegmentWallInputs, id: RoofWallFaceId, point: [number, number, number]): [number, number, number];
+/**
+ * Max width of a rect growing from an anchored vertical edge (`anchorU`)
+ * in direction `growSign` (±1 along U) while staying inside the face
+ * profile at the fixed vertical center `vCenter`. Resize-handle limit:
+ * the anchored-edge model matches the handles' apply math (opposite
+ * edge stays put, center re-derives).
+ */
+export declare function getMaxRoofRectWidthFromAnchor(face: RoofSegmentWallFace, anchorU: number, growSign: number, vCenter: number, height: number): number;
+/**
+ * Max height of a rect growing from an anchored horizontal edge
+ * (`anchorV`) in direction `growSign` (+1 = bottom anchored, grows up)
+ * while staying inside the face profile at the fixed horizontal center
+ * `uCenter`.
+ */
+export declare function getMaxRoofRectHeightFromAnchor(face: RoofSegmentWallFace, uCenter: number, width: number, anchorV: number, growSign: number): number;
+/**
+ * Clamp a rect center so the rect fits inside the face profile.
+ *
+ * - `lockV: true` (doors): `v` is fixed; only `u` slides. Returns null
+ *   when no `u` keeps the rect inside at that height.
+ * - otherwise (windows): the center is projected into the eroded convex
+ *   region (cyclic projection — profiles are convex by construction).
+ *
+ * Returns null when the rect cannot fit anywhere on the face.
+ */
+export declare function clampRectToRoofWallFace(face: RoofSegmentWallFace, u: number, v: number, width: number, height: number, opts?: {
+    lockV?: boolean;
+}): {
+    u: number;
+    v: number;
+} | null;
+export {};
+//# sourceMappingURL=roof-segment-walls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"roof-segment-walls.d.ts","sourceRoot":"","sources":["../../../src/schema/nodes/roof-segment-walls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAGrD;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAA;AAEhE,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,cAAc,CAAA;IAClB,6CAA6C;IAC7C,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAA;IACX,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;CAC5B,CAAA;AAED,KAAK,iBAAiB,GAAG,IAAI,CAC3B,eAAe,EACf,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,eAAe,GAAG,OAAO,CAC1E,GACC,OAAO,CACL,IAAI,CACF,eAAe,EACb,wBAAwB,GACxB,yBAAyB,GACzB,wBAAwB,GACxB,yBAAyB,GACzB,oBAAoB,GACpB,qBAAqB,GACrB,uBAAuB,CAC1B,CACF,CAAA;AAqJH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,iBAAiB,EACvB,EAAE,EAAE,cAAc,GACjB,mBAAmB,CAUrB;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,EAAE,CAStF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,iBAAiB,EACvB,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC9B;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAaxC;AA+CD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,iBAAiB,EACvB,EAAE,EAAE,cAAc,GACjB;IAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAYnD;AAED,yEAAyE;AACzE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,iBAAiB,EACvB,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC9B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAO1B;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,MAAM,CAWR;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,MAAM,CASR;AAID;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,mBAAmB,EACzB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACzB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAwCjC"}

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

@@ -0,0 +1,330 @@
+import { getDutchRoofMetrics, getSegmentSlopeFrame } from './roof-segment';
+function getWallVolumeFrame(node) {
+    const { activeRh, tanTheta } = getSegmentSlopeFrame(node);
+    const wallThickness = node.wallThickness ?? 0.1;
+    const autoDrop = (wallThickness / 2) * tanTheta;
+    const wV = Math.max(0.01, node.width + wallThickness);
+    const dV = Math.max(0.01, node.depth + wallThickness);
+    const eaveY = Math.max(0.01, node.wallHeight - autoDrop);
+    let rh = activeRh;
+    if (activeRh > 0) {
+        rh = activeRh + autoDrop;
+        if (node.roofType === 'shed')
+            rh = activeRh + 2 * autoDrop;
+    }
+    return {
+        wV,
+        dV,
+        eaveY,
+        peakY: eaveY + Math.max(0.001, rh),
+        tanTheta,
+        hasSlope: activeRh > 0,
+    };
+}
+const FACE_NORMALS = {
+    front: [0, 0, 1],
+    back: [0, 0, -1],
+    right: [1, 0, 0],
+    left: [-1, 0, 0],
+};
+const FACE_YAWS = {
+    front: 0,
+    back: Math.PI,
+    right: Math.PI / 2,
+    left: -Math.PI / 2,
+};
+function rectProfile(length, top) {
+    return [
+        [0, 0],
+        [length, 0],
+        [length, top],
+        [0, top],
+    ];
+}
+function buildFaceProfile(node, frame, id) {
+    const { wV, dV, eaveY, peakY, tanTheta, hasSlope } = frame;
+    const isEnd = id === 'right' || id === 'left';
+    const length = isEnd ? dV : wV;
+    if (!hasSlope)
+        return rectProfile(length, eaveY);
+    switch (node.roofType) {
+        case 'gable': {
+            if (!isEnd)
+                return rectProfile(length, eaveY);
+            return [
+                [0, 0],
+                [length, 0],
+                [length, eaveY],
+                [length / 2, peakY],
+                [0, eaveY],
+            ];
+        }
+        case 'gambrel': {
+            if (!isEnd)
+                return rectProfile(length, eaveY);
+            // Kink ring sits at z = ±mz on the nominal footprint (see
+            // getModuleFaces); both end faces are symmetric about u = length/2.
+            const ratio = node.gambrelLowerWidthRatio ?? 0.5;
+            const mz = Math.min((node.depth / 2) * ratio, length / 2);
+            const kinkY = eaveY + (length / 2 - mz) * tanTheta;
+            return [
+                [0, 0],
+                [length, 0],
+                [length, eaveY],
+                [length / 2 + mz, kinkY],
+                [length / 2, peakY],
+                [length / 2 - mz, kinkY],
+                [0, eaveY],
+            ];
+        }
+        case 'shed': {
+            // Slope falls toward +Z: 'back' is the full-height wall, the end
+            // faces are right trapezoids rising toward the back edge.
+            if (id === 'front')
+                return rectProfile(length, eaveY);
+            if (id === 'back')
+                return rectProfile(length, peakY);
+            if (id === 'right') {
+                return [
+                    [0, 0],
+                    [length, 0],
+                    [length, peakY],
+                    [0, eaveY],
+                ];
+            }
+            return [
+                [0, 0],
+                [length, 0],
+                [length, eaveY],
+                [0, peakY],
+            ];
+        }
+        case 'dutch': {
+            const metrics = getDutchRoofMetrics(node);
+            const isDutchGableFace = (metrics.axis === 'x' && isEnd) ||
+                (metrics.axis === 'z' && (id === 'front' || id === 'back'));
+            if (!isDutchGableFace)
+                return rectProfile(length, eaveY);
+            const shoulderInset = metrics.axis === 'x' ? metrics.shoulderInsetAlongDepth : metrics.shoulderInsetAlongWidth;
+            if (!(shoulderInset > 0.001))
+                return rectProfile(length, eaveY);
+            const shoulderLo = Math.max(0, shoulderInset);
+            const shoulderHi = Math.min(length, length - shoulderInset);
+            if (!(shoulderHi - shoulderLo > 0.02))
+                return rectProfile(length, eaveY);
+            return [
+                [0, 0],
+                [length, 0],
+                [length, eaveY],
+                [shoulderHi, eaveY],
+                [length / 2, peakY],
+                [shoulderLo, eaveY],
+                [0, eaveY],
+            ];
+        }
+        default:
+            return rectProfile(length, eaveY);
+    }
+}
+export function getRoofSegmentWallFace(node, id) {
+    const frame = getWallVolumeFrame(node);
+    const isEnd = id === 'right' || id === 'left';
+    return {
+        id,
+        normal: FACE_NORMALS[id],
+        yaw: FACE_YAWS[id],
+        length: isEnd ? frame.dV : frame.wV,
+        profile: buildFaceProfile(node, frame, id),
+    };
+}
+export function getRoofSegmentWallFaces(node) {
+    const frame = getWallVolumeFrame(node);
+    return ['front', 'back', 'right', 'left'].map((id) => ({
+        id,
+        normal: FACE_NORMALS[id],
+        yaw: FACE_YAWS[id],
+        length: id === 'right' || id === 'left' ? frame.dV : frame.wV,
+        profile: buildFaceProfile(node, frame, id),
+    }));
+}
+/**
+ * Segment-local point → face coords. `dist` is the signed offset off the
+ * outer wall plane along the face normal (0 = on the plane, positive =
+ * outside the volume).
+ */
+export function segmentPointToRoofWallFace(node, id, point) {
+    const { wV, dV } = getWallVolumeFrame(node);
+    const [x, y, z] = point;
+    switch (id) {
+        case 'front':
+            return { u: x + wV / 2, v: y, dist: z - dV / 2 };
+        case 'back':
+            return { u: wV / 2 - x, v: y, dist: -z - dV / 2 };
+        case 'right':
+            return { u: dV / 2 - z, v: y, dist: x - wV / 2 };
+        case 'left':
+            return { u: z + dV / 2, v: y, dist: -x - wV / 2 };
+    }
+}
+/**
+ * Inward half-plane constraints of the raw profile polygon (CCW →
+ * interior is to the left of each edge): a point p is inside when
+ * `nu·p.u + nv·p.v ≥ c` for every constraint.
+ */
+function getProfileConstraints(face) {
+    const constraints = [];
+    const pts = face.profile;
+    for (let i = 0; i < pts.length; i++) {
+        const a = pts[i];
+        const b = pts[(i + 1) % pts.length];
+        const du = b[0] - a[0];
+        const dv = b[1] - a[1];
+        const len = Math.hypot(du, dv);
+        if (len < 1e-9)
+            continue;
+        const nu = -dv / len;
+        const nv = du / len;
+        constraints.push({ nu, nv, c: nu * a[0] + nv * a[1] });
+    }
+    return constraints;
+}
+/**
+ * Half-plane constraints for the CENTER of a `width × height` rect that
+ * must fit inside the face profile — the raw constraints eroded by the
+ * rect's half-extents projected on each edge normal.
+ */
+function getRectCenterConstraints(face, width, height) {
+    return getProfileConstraints(face).map(({ nu, nv, c }) => ({
+        nu,
+        nv,
+        c: c + (Math.abs(nu) * width) / 2 + (Math.abs(nv) * height) / 2,
+    }));
+}
+/**
+ * The face's render frame in segment-local space: a group placed at
+ * `origin` and yawed by `yaw` maps face coords to segment space —
+ * frame X = U (along the face), frame Y = V (height), frame Z = the
+ * outward normal, with z = 0 on the WALL MID-PLANE. The mid-plane of
+ * the generated wall volume lands exactly on the nominal footprint
+ * (`±width/2` / `±depth/2`), so hosted children use the same position
+ * conventions as wall children (openings at z = 0, wall-side items
+ * pushed +thickness/2 at render time). Renderers derive this from the
+ * live-override-merged segment, which is what makes hosted children
+ * track segment edits live instead of jumping on commit.
+ */
+export function getRoofWallFaceFrame(node, id) {
+    const { wV, dV } = getWallVolumeFrame(node);
+    switch (id) {
+        case 'front':
+            return { origin: [-wV / 2, 0, node.depth / 2], yaw: FACE_YAWS.front };
+        case 'back':
+            return { origin: [wV / 2, 0, -node.depth / 2], yaw: FACE_YAWS.back };
+        case 'right':
+            return { origin: [node.width / 2, 0, dV / 2], yaw: FACE_YAWS.right };
+        case 'left':
+            return { origin: [-node.width / 2, 0, -dV / 2], yaw: FACE_YAWS.left };
+    }
+}
+/** Face-frame point ([u, v, z-from-mid-plane]) → segment-local point. */
+export function roofFacePointToSegment(node, id, point) {
+    const { origin, yaw } = getRoofWallFaceFrame(node, id);
+    const cos = Math.cos(yaw);
+    const sin = Math.sin(yaw);
+    const [u, v, z] = point;
+    // rotation-y: +x → (cos, 0, -sin), +z → (sin, 0, cos)
+    return [origin[0] + u * cos + z * sin, origin[1] + v, origin[2] - u * sin + z * cos];
+}
+/**
+ * Max width of a rect growing from an anchored vertical edge (`anchorU`)
+ * in direction `growSign` (±1 along U) while staying inside the face
+ * profile at the fixed vertical center `vCenter`. Resize-handle limit:
+ * the anchored-edge model matches the handles' apply math (opposite
+ * edge stays put, center re-derives).
+ */
+export function getMaxRoofRectWidthFromAnchor(face, anchorU, growSign, vCenter, height) {
+    let max = Number.POSITIVE_INFINITY;
+    for (const { nu, nv, c } of getProfileConstraints(face)) {
+        // Center at anchorU + growSign·w/2, eroded by |nu|·w/2 + |nv|·h/2:
+        // base + k·w ≥ 0 with k ≤ 0 only when growth approaches the edge.
+        const k = (nu * growSign - Math.abs(nu)) / 2;
+        if (k >= -1e-9)
+            continue;
+        const base = nu * anchorU + nv * vCenter - c - (Math.abs(nv) * height) / 2;
+        max = Math.min(max, Math.max(0, base / -k));
+    }
+    return max;
+}
+/**
+ * Max height of a rect growing from an anchored horizontal edge
+ * (`anchorV`) in direction `growSign` (+1 = bottom anchored, grows up)
+ * while staying inside the face profile at the fixed horizontal center
+ * `uCenter`.
+ */
+export function getMaxRoofRectHeightFromAnchor(face, uCenter, width, anchorV, growSign) {
+    let max = Number.POSITIVE_INFINITY;
+    for (const { nu, nv, c } of getProfileConstraints(face)) {
+        const k = (nv * growSign - Math.abs(nv)) / 2;
+        if (k >= -1e-9)
+            continue;
+        const base = nu * uCenter + nv * anchorV - c - (Math.abs(nu) * width) / 2;
+        max = Math.min(max, Math.max(0, base / -k));
+    }
+    return max;
+}
+const CLAMP_EPSILON = 1e-4;
+/**
+ * Clamp a rect center so the rect fits inside the face profile.
+ *
+ * - `lockV: true` (doors): `v` is fixed; only `u` slides. Returns null
+ *   when no `u` keeps the rect inside at that height.
+ * - otherwise (windows): the center is projected into the eroded convex
+ *   region (cyclic projection — profiles are convex by construction).
+ *
+ * Returns null when the rect cannot fit anywhere on the face.
+ */
+export function clampRectToRoofWallFace(face, u, v, width, height, opts) {
+    const constraints = getRectCenterConstraints(face, width, height);
+    if (constraints.length < 3)
+        return null;
+    if (opts?.lockV) {
+        let lo = Number.NEGATIVE_INFINITY;
+        let hi = Number.POSITIVE_INFINITY;
+        for (const { nu, nv, c } of constraints) {
+            const rhs = c - nv * v;
+            if (Math.abs(nu) < 1e-9) {
+                if (rhs > CLAMP_EPSILON)
+                    return null;
+                continue;
+            }
+            if (nu > 0)
+                lo = Math.max(lo, rhs / nu);
+            else
+                hi = Math.min(hi, rhs / nu);
+        }
+        if (lo > hi + CLAMP_EPSILON)
+            return null;
+        return { u: Math.min(Math.max(u, lo), hi), v };
+    }
+    let pu = u;
+    let pv = v;
+    for (let iter = 0; iter < 32; iter++) {
+        let worst = null;
+        let worstViolation = CLAMP_EPSILON;
+        for (const constraint of constraints) {
+            const violation = constraint.c - (constraint.nu * pu + constraint.nv * pv);
+            if (violation > worstViolation) {
+                worstViolation = violation;
+                worst = constraint;
+            }
+        }
+        if (!worst)
+            return { u: pu, v: pv };
+        pu += worst.nu * worstViolation;
+        pv += worst.nv * worstViolation;
+    }
+    for (const { nu, nv, c } of constraints) {
+        if (nu * pu + nv * pv < c - 1e-3)
+            return null;
+    }
+    return { u: pu, v: pv };
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=roof-segment-walls.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"roof-segment-walls.test.d.ts","sourceRoot":"","sources":["../../../src/schema/nodes/roof-segment-walls.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,92 @@
+import { describe, expect, test } from 'bun:test';
+import { RoofSegmentNode } from './roof-segment';
+import { getRoofSegmentWallFace, getRoofSegmentWallFaces, getRoofWallFaceFrame, roofFacePointToSegment, segmentPointToRoofWallFace, } from './roof-segment-walls';
+function segment(overrides = {}) {
+    return RoofSegmentNode.parse({
+        id: 'rseg_test',
+        type: 'roof-segment',
+        roofType: 'gable',
+        width: 8,
+        depth: 6,
+        wallHeight: 2.6,
+        wallThickness: 0.1,
+        pitch: 40,
+        ...overrides,
+    });
+}
+describe('roof wall face frames', () => {
+    test('frame z = 0 lands on the nominal footprint (wall mid-plane)', () => {
+        const seg = segment();
+        // front face, u at the face middle, v = 1, mid-plane.
+        const point = roofFacePointToSegment(seg, 'front', [(8 + 0.1) / 2, 1, 0]);
+        expect(point[0]).toBeCloseTo(0);
+        expect(point[1]).toBeCloseTo(1);
+        expect(point[2]).toBeCloseTo(3); // depth / 2 — the footprint plane
+    });
+    test('frame +z is the outward normal on every face', () => {
+        const seg = segment();
+        for (const [faceId, axis, sign] of [
+            ['front', 2, 1],
+            ['back', 2, -1],
+            ['right', 0, 1],
+            ['left', 0, -1],
+        ]) {
+            const onPlane = roofFacePointToSegment(seg, faceId, [1, 1, 0]);
+            const pushed = roofFacePointToSegment(seg, faceId, [1, 1, 0.5]);
+            expect(pushed[axis] - onPlane[axis]).toBeCloseTo(0.5 * sign);
+            // The other horizontal axis is unaffected by the push.
+            const other = axis === 2 ? 0 : 2;
+            expect(pushed[other] - onPlane[other]).toBeCloseTo(0);
+        }
+    });
+    test('face frame agrees with the hit resolver coordinates', () => {
+        const seg = segment();
+        // A point on the outer surface (z = +thickness/2 off the mid-plane)
+        // must read back with the same u/v and dist ≈ 0 off the outer plane.
+        const segLocal = roofFacePointToSegment(seg, 'right', [2.5, 1.25, 0.05]);
+        const { u, v, dist } = segmentPointToRoofWallFace(seg, 'right', segLocal);
+        expect(u).toBeCloseTo(2.5);
+        expect(v).toBeCloseTo(1.25);
+        expect(dist).toBeCloseTo(0);
+    });
+    test('resizing the segment moves the frame, not the stored coords', () => {
+        // The core live-tracking property: the same face-local point maps to
+        // the new plane after a depth change — children follow by re-render.
+        const before = roofFacePointToSegment(segment(), 'front', [2, 1, 0]);
+        const after = roofFacePointToSegment(segment({ depth: 8 }), 'front', [2, 1, 0]);
+        expect(before[2]).toBeCloseTo(3);
+        expect(after[2]).toBeCloseTo(4);
+        expect(after[1]).toBeCloseTo(before[1]);
+    });
+    test('frame yaw matches the face descriptor yaw', () => {
+        const seg = segment();
+        for (const faceId of ['front', 'back', 'right', 'left']) {
+            expect(getRoofWallFaceFrame(seg, faceId).yaw).toBe(getRoofSegmentWallFace(seg, faceId).yaw);
+        }
+    });
+    test('dutch width-axis roofs expose hostable gable-end wall profiles on the short ends', () => {
+        const faces = getRoofSegmentWallFaces(segment({
+            roofType: 'dutch',
+            width: 8,
+            depth: 6,
+            dutchHipWidthRatio: 0.25,
+            dutchWaistLengthRatio: 1,
+        }));
+        const left = faces.find((face) => face.id === 'left');
+        const right = faces.find((face) => face.id === 'right');
+        expect(left?.profile.length).toBeGreaterThan(5);
+        expect(right?.profile.length).toBeGreaterThan(5);
+        expect(left?.profile[3]?.[1]).toBeCloseTo(left?.profile[2]?.[1] ?? 0);
+    });
+    test('dutch long-side faces stay rectangular while only the gable ends rise above the eave', () => {
+        const faces = getRoofSegmentWallFaces(segment({
+            roofType: 'dutch',
+            width: 8,
+            depth: 6,
+        }));
+        const front = faces.find((face) => face.id === 'front');
+        const back = faces.find((face) => face.id === 'back');
+        expect(front?.profile).toHaveLength(4);
+        expect(back?.profile).toHaveLength(4);
+    });
+});