@pascal-app/nodes 0.1.1

package/dist/box-vent/definition.d.ts

@@ -0,0 +1,30 @@
+import { type NodeDefinition } from '@pascal-app/core';
+import { BoxVentNode } from './schema';
+/**
+ * Box vent — a small louvered ventilation box that sits on a roof
+ * slope. Parented to a `roof-segment`; position is segment-local;
+ * rotation rotates the vent around the segment's vertical axis after
+ * the slope tilt is applied.
+ *
+ * Composition (three-checkbox model):
+ *  - **`renderer` (custom)** — the box-vent needs the parent segment's
+ *    position + rotation + slope geometry to position itself, and the
+ *    registry-era roof-segment renderer doesn't auto-nest children
+ *    (its mesh is filled by `RoofSystem`). The custom renderer reads
+ *    the segment from `useScene`, applies the transform stack, and
+ *    follows the segment's `useLiveTransforms` override during a
+ *    parent drag.
+ *  - **no `geometry`** — geometry is created inside the renderer via
+ *    the shared pure builder in `./geometry`. We could lift it to
+ *    `def.geometry` once roof-segment migrates to the parametric path
+ *    (Phase 5 Stage B); for now keeping it inside the renderer
+ *    matches the legacy mount semantics one-for-one.
+ *  - **no `system`** — no animations, no cross-kind cascades.
+ *
+ * The bespoke move flow (segment-hopping with hit-tests against every
+ * sibling roof-segment) ports later as `affordanceTools.move`. The
+ * placement `def.tool` listens to `roof:*` events and creates a new
+ * vent on click.
+ */
+export declare const boxVentDefinition: NodeDefinition<typeof BoxVentNode>;
+//# sourceMappingURL=definition.d.ts.map

package/dist/box-vent/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/box-vent/definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAA;AAIzB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AA4ItC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,OAAO,WAAW,CAwDhE,CAAA"}

package/dist/box-vent/definition.js

@@ -0,0 +1,210 @@
+import { BoxVentNode as BoxVentNodeSchema, } from '@pascal-app/core';
+import { surfacePaintCapability } from '../shared/surface-paint';
+import { buildBoxVentFloorplan } from './floorplan';
+import { boxVentParametrics } from './parametrics';
+import { BoxVentNode } from './schema';
+// Edge-to-arrow-center offset, matching the chimney / dormer cadence.
+const SIDE_HANDLE_OFFSET = 0.25;
+const HEIGHT_HANDLE_OFFSET = 0.2;
+// Snug to the vent corner — vents are small (default 0.4 m), so the big
+// chimney/dormer offset floated the rotate icon far off the item.
+const ROTATE_CORNER_OFFSET = 0.1;
+// Min sizes — vents are small (default 0.4 × 0.4 × 0.15), so the floor
+// is well below the default values to allow shrinking without locking.
+const MIN_DIM = 0.1;
+const MIN_HEIGHT = 0.05;
+// Mid-Y of the vent body in vent-mesh-local. The vent sits with its base
+// at y=0 on the slope, so mid is half the height. Side / depth / rotate
+// chevrons all place their handle at this Y to read as "this dimension
+// is the vent body".
+function getBodyMidY(n) {
+    return Math.max(0.001, n.height) / 2;
+}
+// Width arrow on the +X (right) or -X (left) side of the vent body.
+// Asymmetric resize — anchored edge stays world-fixed by recentering
+// `position` along the vent's own +X arm in segment frame (matches the
+// chimney / dormer width handle math). The slope tilt rotates around
+// the vent's base point, so segment-local XZ of the anchored edge stays
+// the same regardless of tilt; only the yaw matters for the projection.
+function boxVentWidthHandle(side) {
+    const sign = side === 'right' ? 1 : -1;
+    return {
+        kind: 'linear-resize',
+        axis: 'x',
+        anchor: side === 'right' ? 'min' : 'max',
+        min: MIN_DIM,
+        currentValue: (n) => n.width,
+        apply: (initial, newWidth) => {
+            const rotY = initial.rotation ?? 0;
+            const armX = Math.cos(rotY);
+            const armZ = -Math.sin(rotY);
+            const anchorX = initial.position[0] - sign * (initial.width / 2) * armX;
+            const anchorZ = initial.position[2] - sign * (initial.width / 2) * armZ;
+            const newCenterX = anchorX + sign * (newWidth / 2) * armX;
+            const newCenterZ = anchorZ + sign * (newWidth / 2) * armZ;
+            return {
+                width: newWidth,
+                position: [newCenterX, initial.position[1], newCenterZ],
+            };
+        },
+        placement: {
+            position: (n) => [sign * (n.width / 2 + SIDE_HANDLE_OFFSET), getBodyMidY(n), 0],
+            // Flip the left chevron so it points outward toward -X. The
+            // generic LinearArrow auto-orients for axis 'z'; +X / -X facing
+            // is up to the descriptor.
+            rotationY: () => (side === 'right' ? 0 : Math.PI),
+        },
+    };
+}
+// Depth arrow on the +Z side. Symmetric (anchor 'center') matches the
+// chimney / dormer handle count budget — splitting into asymmetric front /
+// back chevrons here would push the vent over the same TSL/MRT pipeline
+// threshold those nodes already document. Single symmetric chevron grows
+// the depth from the centre.
+function boxVentDepthHandle() {
+    return {
+        kind: 'linear-resize',
+        axis: 'z',
+        anchor: 'center',
+        min: MIN_DIM,
+        currentValue: (n) => n.depth,
+        apply: (_n, newValue) => ({ depth: newValue }),
+        placement: {
+            position: (n) => [0, getBodyMidY(n), n.depth / 2 + SIDE_HANDLE_OFFSET],
+        },
+    };
+}
+// Height arrow above the top of the vent. anchor='min' so the base stays
+// pinned to the slope at vent-local y=0 and the top edge follows the
+// pointer. Plain chevron (not tracker) — at default sizes (~0.15 m) a
+// dashed leader from base to top reads as visual noise rather than a
+// dimension cue.
+function boxVentHeightHandle() {
+    return {
+        kind: 'linear-resize',
+        axis: 'y',
+        anchor: 'min',
+        min: MIN_HEIGHT,
+        currentValue: (n) => n.height,
+        apply: (_n, newValue) => ({ height: Math.max(MIN_HEIGHT, newValue) }),
+        placement: {
+            position: (n) => [0, Math.max(n.height, MIN_HEIGHT) + HEIGHT_HANDLE_OFFSET, 0],
+        },
+    };
+}
+// Whole-vent rotation gizmo at the +X/+Z corner of the body footprint.
+// The registered group already centres on the vent and applies its
+// composed slope+yaw quaternion, so the default rotation pivot is
+// correct — no `rotationCenter` override needed.
+function boxVentRotateHandle() {
+    return {
+        kind: 'arc-resize',
+        axis: 'angular',
+        shape: 'rotate',
+        apply: (initial, delta) => ({ rotation: (initial.rotation ?? 0) - delta }),
+        placement: {
+            position: (n) => [
+                n.width / 2 + ROTATE_CORNER_OFFSET,
+                getBodyMidY(n),
+                n.depth / 2 + ROTATE_CORNER_OFFSET,
+            ],
+            // Aim the two-headed icon along the +X+Z corner bisector.
+            rotationY: () => -Math.PI / 4,
+        },
+        // Guide ring centred on the vent (drawn at the handle-frame origin),
+        // sized to pass through the corner icon so the icon rides the ring and
+        // the whole control reads as encircling the item — matches solar-panel.
+        decoration: {
+            kind: 'ring',
+            radius: (n) => Math.hypot(n.width / 2 + ROTATE_CORNER_OFFSET, n.depth / 2 + ROTATE_CORNER_OFFSET),
+            y: (n) => getBodyMidY(n),
+        },
+    };
+}
+// `portal: 'grandparent'` on every handle: the vent mesh is mounted under
+// the roof's `roof-elements` group (reproducing the segment transform), so
+// the handle rig must ride the roof→segment→node frame chain — same as
+// solar-panel / skylight. Without it the handles (and the rotate arc) mount
+// in the bare segment-mesh frame and render offset from the vent.
+const boxVentHandles = [
+    boxVentWidthHandle('right'),
+    boxVentWidthHandle('left'),
+    boxVentDepthHandle(),
+    boxVentHeightHandle(),
+    boxVentRotateHandle(),
+].map((h) => ({ ...h, portal: 'grandparent' }));
+/**
+ * Box vent — a small louvered ventilation box that sits on a roof
+ * slope. Parented to a `roof-segment`; position is segment-local;
+ * rotation rotates the vent around the segment's vertical axis after
+ * the slope tilt is applied.
+ *
+ * Composition (three-checkbox model):
+ *  - **`renderer` (custom)** — the box-vent needs the parent segment's
+ *    position + rotation + slope geometry to position itself, and the
+ *    registry-era roof-segment renderer doesn't auto-nest children
+ *    (its mesh is filled by `RoofSystem`). The custom renderer reads
+ *    the segment from `useScene`, applies the transform stack, and
+ *    follows the segment's `useLiveTransforms` override during a
+ *    parent drag.
+ *  - **no `geometry`** — geometry is created inside the renderer via
+ *    the shared pure builder in `./geometry`. We could lift it to
+ *    `def.geometry` once roof-segment migrates to the parametric path
+ *    (Phase 5 Stage B); for now keeping it inside the renderer
+ *    matches the legacy mount semantics one-for-one.
+ *  - **no `system`** — no animations, no cross-kind cascades.
+ *
+ * The bespoke move flow (segment-hopping with hit-tests against every
+ * sibling roof-segment) ports later as `affordanceTools.move`. The
+ * placement `def.tool` listens to `roof:*` events and creates a new
+ * vent on click.
+ */
+export const boxVentDefinition = {
+    kind: 'box-vent',
+    schemaVersion: 1,
+    schema: BoxVentNode,
+    category: 'structure',
+    surfaceRole: 'roof',
+    defaults: () => {
+        const stub = BoxVentNodeSchema.parse({ id: 'bvent_default', type: 'box-vent' });
+        const { id: _id, type: _type, ...rest } = stub;
+        return rest;
+    },
+    capabilities: {
+        selectable: { hitVolume: 'bbox' },
+        duplicable: true,
+        deletable: true,
+        // Single painted surface — registry-driven paint dispatch (see chimney).
+        paint: surfacePaintCapability,
+        // Mounts on a roof segment via `roofSegmentId`. Sits ON TOP of the
+        // slope — no `buildCut`, just the dirty cascade so the parent
+        // roof's merged shell rebuilds when the vent moves / resizes.
+        roofAccessory: {},
+    },
+    parametrics: boxVentParametrics,
+    handles: boxVentHandles,
+    floorplan: buildBoxVentFloorplan,
+    renderer: {
+        kind: 'parametric',
+        module: () => import('./renderer'),
+    },
+    preview: () => import('./preview'),
+    tool: () => import('./tool'),
+    affordanceTools: {
+        move: () => import('./move-tool'),
+    },
+    toolHints: [
+        { key: 'Left click', label: 'Place box vent on roof' },
+        { key: 'Esc', label: 'Cancel' },
+    ],
+    presentation: {
+        label: 'Box Vent',
+        description: 'Small louvered exhaust vent that sits on a roof slope.',
+        icon: { kind: 'url', src: '/icons/roof.webp' },
+        paletteSection: 'structure',
+        paletteOrder: 120,
+    },
+    mcp: {
+        description: 'A louvered box vent sitting on a roof segment. Style: standard / low-profile / dome. Width/depth/height/hoodOverhang parametric.',
+    },
+};

package/dist/box-vent/floorplan.d.ts

@@ -0,0 +1,15 @@
+import type { BoxVentNode, FloorplanGeometry, GeometryContext } from '@pascal-app/core';
+/**
+ * Floor-plan builder for a box vent — a small attic-exhaust vent on a roof
+ * slope. Seen from above it reads as its footprint per style: `box` is a
+ * cover with an inset riser, `cap` flares to a flange past the body, and
+ * `dome` is a flush ellipse.
+ *
+ * Coordinate frame mirrors the 3D transform stack
+ * (roof → roof-segment → vent), same as the chimney builder. `position`
+ * is segment-local (X = width, Z = depth; Y ignored — anchored to the
+ * slope). `rotation` is yaw. Rotations negated for the floor plan's y-down
+ * convention.
+ */
+export declare function buildBoxVentFloorplan(node: BoxVentNode, ctx: GeometryContext): FloorplanGeometry | null;
+//# sourceMappingURL=floorplan.d.ts.map

package/dist/box-vent/floorplan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"floorplan.d.ts","sourceRoot":"","sources":["../../src/box-vent/floorplan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EACX,iBAAiB,EAEjB,eAAe,EAGhB,MAAM,kBAAkB,CAAA;AAEzB;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,eAAe,GACnB,iBAAiB,GAAG,IAAI,CAqL1B"}

package/dist/box-vent/floorplan.js

@@ -0,0 +1,187 @@
+/**
+ * Floor-plan builder for a box vent — a small attic-exhaust vent on a roof
+ * slope. Seen from above it reads as its footprint per style: `box` is a
+ * cover with an inset riser, `cap` flares to a flange past the body, and
+ * `dome` is a flush ellipse.
+ *
+ * Coordinate frame mirrors the 3D transform stack
+ * (roof → roof-segment → vent), same as the chimney builder. `position`
+ * is segment-local (X = width, Z = depth; Y ignored — anchored to the
+ * slope). `rotation` is yaw. Rotations negated for the floor plan's y-down
+ * convention.
+ */
+export function buildBoxVentFloorplan(node, ctx) {
+    const segment = ctx.parent;
+    if (segment?.type !== 'roof-segment')
+        return null;
+    const roofId = segment.parentId;
+    const roof = roofId ? ctx.resolve(roofId) : undefined;
+    if (roof?.type !== 'roof')
+        return null;
+    const cosR = Math.cos(-roof.rotation);
+    const sinR = Math.sin(-roof.rotation);
+    const segCx = roof.position[0] + segment.position[0] * cosR - segment.position[2] * sinR;
+    const segCz = roof.position[2] + segment.position[0] * sinR + segment.position[2] * cosR;
+    const segRot = -(roof.rotation + segment.rotation);
+    const cosS = Math.cos(segRot);
+    const sinS = Math.sin(segRot);
+    const cx = segCx + node.position[0] * cosS - node.position[2] * sinS;
+    const cz = segCz + node.position[0] * sinS + node.position[2] * cosS;
+    const rot = -(roof.rotation + segment.rotation + node.rotation);
+    const cos = Math.cos(rot);
+    const sin = Math.sin(rot);
+    const toPlan = (lx, lz) => [
+        cx + lx * cos - lz * sin,
+        cz + lx * sin + lz * cos,
+    ];
+    const view = ctx.viewState;
+    const palette = view?.palette;
+    const isSelected = view?.selected ?? false;
+    const isHighlighted = view?.highlighted ?? false;
+    const isHovered = view?.hovered ?? false;
+    const showSelectedChrome = isSelected || isHighlighted;
+    // Painted-metal vent — cool grey, accent on select, light blue on hover.
+    const baseInk = '#475569';
+    const stroke = showSelectedChrome && palette
+        ? palette.selectedStroke
+        : isHovered && palette
+            ? palette.wallHoverStroke
+            : baseInk;
+    const fill = showSelectedChrome ? '#fed7aa' : '#dbe1e8';
+    const fillOpacity = showSelectedChrome ? 0.55 : 0.7;
+    const lineWidth = showSelectedChrome ? 0.03 : 0.02;
+    const hw = Math.max(node.width, 0.05) / 2;
+    const hd = Math.max(node.depth, 0.05) / 2;
+    const style = node.style ?? 'cap';
+    const rect = (halfX, halfZ) => [
+        toPlan(-halfX, -halfZ),
+        toPlan(halfX, -halfZ),
+        toPlan(halfX, halfZ),
+        toPlan(-halfX, halfZ),
+    ];
+    const ellipse = (halfX, halfZ) => {
+        const pts = [];
+        const N = 28;
+        for (let i = 0; i < N; i++) {
+            const a = (i / N) * Math.PI * 2;
+            pts.push(toPlan(halfX * Math.cos(a), halfZ * Math.sin(a)));
+        }
+        return pts;
+    };
+    const children = [];
+    if (style === 'dome') {
+        // Outer = the round flange plate (dome radius + flange overhang).
+        const ovh = Math.max(0, node.hoodOverhang ?? 0.04);
+        const outer = ellipse(hw + ovh, hd + ovh);
+        children.push({
+            kind: 'polygon',
+            points: outer,
+            fill: stroke,
+            fillOpacity: 0,
+            stroke: 'none',
+            strokeWidth: 0,
+            pointerEvents: 'all',
+        });
+        children.push({
+            kind: 'polygon',
+            points: outer,
+            fill,
+            fillOpacity,
+            stroke,
+            strokeWidth: lineWidth,
+            pointerEvents: 'none',
+        });
+        // Dome footprint inside the flange.
+        children.push({
+            kind: 'polygon',
+            points: ellipse(hw, hd),
+            fill: 'none',
+            stroke,
+            strokeWidth: lineWidth * 0.8,
+            strokeOpacity: 0.7,
+            pointerEvents: 'none',
+        });
+        // Inner ring suggests the dome bulge.
+        children.push({
+            kind: 'polygon',
+            points: ellipse(hw * 0.5, hd * 0.5),
+            fill: 'none',
+            stroke,
+            strokeWidth: lineWidth * 0.8,
+            strokeOpacity: 0.5,
+            pointerEvents: 'none',
+        });
+    }
+    else if (style === 'cap') {
+        // Flange flares past the body by `hoodOverhang` on all sides.
+        const ovh = Math.max(0, node.hoodOverhang ?? 0.04);
+        const outer = rect(hw + ovh, hd + ovh);
+        children.push({
+            kind: 'polygon',
+            points: outer,
+            fill: stroke,
+            fillOpacity: 0,
+            stroke: 'none',
+            strokeWidth: 0,
+            pointerEvents: 'all',
+        });
+        children.push({
+            kind: 'polygon',
+            points: outer,
+            fill,
+            fillOpacity,
+            stroke,
+            strokeWidth: lineWidth,
+            strokeLinejoin: 'miter',
+            pointerEvents: 'none',
+        });
+        // Body footprint inside the flange.
+        children.push({
+            kind: 'polygon',
+            points: rect(hw, hd),
+            fill: 'none',
+            stroke,
+            strokeWidth: lineWidth * 0.8,
+            strokeOpacity: 0.7,
+            strokeLinejoin: 'miter',
+            pointerEvents: 'none',
+        });
+    }
+    else {
+        // box: cover footprint + inset riser.
+        const outer = rect(hw, hd);
+        children.push({
+            kind: 'polygon',
+            points: outer,
+            fill: stroke,
+            fillOpacity: 0,
+            stroke: 'none',
+            strokeWidth: 0,
+            pointerEvents: 'all',
+        });
+        children.push({
+            kind: 'polygon',
+            points: outer,
+            fill,
+            fillOpacity,
+            stroke,
+            strokeWidth: lineWidth,
+            strokeLinejoin: 'miter',
+            pointerEvents: 'none',
+        });
+        const inset = Math.max(0, Math.min(node.baseInset ?? 0.06, Math.min(hw, hd) - 0.01));
+        if (inset > 0.001) {
+            children.push({
+                kind: 'polygon',
+                points: rect(hw - inset, hd - inset),
+                fill: 'none',
+                stroke,
+                strokeWidth: lineWidth * 0.8,
+                strokeOpacity: 0.7,
+                strokeLinejoin: 'miter',
+                pointerEvents: 'none',
+            });
+        }
+    }
+    return { kind: 'group', children };
+}

package/dist/box-vent/geometry.d.ts

@@ -0,0 +1,40 @@
+import { type BoxVentNode, type RoofType } from '@pascal-app/core';
+import * as THREE from 'three';
+/**
+ * Pure builder for the box-vent mesh. Models a real attic box vent:
+ *
+ *   ┌──────────────────────┐        ← rounded dome cap (closed)
+ *   │        ───           │
+ *   │  ◜─────────────◝    │
+ *  ─┘─────────────────────└─       ← flange flashing
+ *
+ * - **Body**: short rectangular walls + a sealed bottom.
+ * - **Dome cap**: smooth half-ellipsoid that fully closes the top — no
+ *   flat plateau (the old pyramid hood left one). Used for every style;
+ *   `style` just tunes how much of the total height is body vs cap.
+ * - **Skirt / flange**: the dome's base ring extends past the body by
+ *   `hoodOverhang`, doubling as the mounting flashing tab.
+ *
+ * Louvered slats were removed — real box vents read smooth from typical
+ * camera distances; the slat pile only made the ghost preview noisy and
+ * the texture wrap unpredictable.
+ *
+ * Pure: no React, no scene access, no store mutation. Safe to call from
+ * unit tests, the placement preview, and the move-tool ghost.
+ */
+export declare function buildBoxVentGeometry(node: BoxVentNode): THREE.BufferGeometry;
+/**
+ * Slope tilt for a box-vent at segment-local Z position. The vent's
+ * X axis stays parallel to the segment's ridge; the +Z (down-slope)
+ * side dips, the -Z (up-slope) side lifts. Flat segments return 0.
+ *
+ * Pure: lifted out so the renderer / move tool / preview share one
+ * source of truth.
+ */
+export declare function computeBoxVentSlopeTilt(segment: {
+    roofType: RoofType;
+    pitch: number;
+    width: number;
+    depth: number;
+} | undefined, localZ: number): number;
+//# sourceMappingURL=geometry.d.ts.map

package/dist/box-vent/geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.d.ts","sourceRoot":"","sources":["../../src/box-vent/geometry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAuB,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AACvF,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,KAAK,CAAC,cAAc,CAI5E;AA+kBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,EACxF,MAAM,EAAE,MAAM,GACb,MAAM,CAKR"}