@pascal-app/nodes 1.0.7 → 1.1.0

package/dist/block/definition.js

@@ -1,144 +1,5 @@
-import { blockSlots, createBoxBlockTopology, } from '@pascal-app/core';
-import { perNodeGeometryBatchable } from '../shared/node-batch/batchable.js';
-import { blockContextualHelp } from './contextual-help.js';
-import { blockFaceHost } from './face-host.js';
-import { buildBlockFloorplan } from './floorplan.js';
-import { buildBlockGeometry } from './geometry.js';
-import { blockPaint } from './paint.js';
-import { blockParametrics } from './parametrics.js';
-import { BlockNode } from './schema.js';
-import { blockSurfaceProvider } from './surface.js';
-/** Bottom within this of the floor (and top above it): the block stands on the floor. */
-const BLOCK_ON_FLOOR_MAX_BOTTOM = 0.1;
-const BLOCK_ON_FLOOR_MIN_TOP = 0.01;
-/**
- * Floor collision is for blocks standing on the floor. Soffits, vaults,
- * gutters and mantels hang above floor placements, and foundation pads sit
- * under the floor, so neither blocks furniture nor gets refused when moved.
- */
-function blockRestsOnFloor(node) {
-    const { size, center } = blockBounds(node);
-    const bottom = node.position[1] + center[1] - size[1] / 2;
-    const top = node.position[1] + center[1] + size[1] / 2;
-    return bottom <= BLOCK_ON_FLOOR_MAX_BOTTOM && top > BLOCK_ON_FLOOR_MIN_TOP;
-}
-export function blockBounds(node) {
-    const xs = node.topology.vertices.map((vertex) => vertex.position[0]);
-    const ys = node.topology.vertices.map((vertex) => vertex.position[1]);
-    const zs = node.topology.vertices.map((vertex) => vertex.position[2]);
-    if (xs.length === 0) {
-        return {
-            size: [0, 0, 0],
-            center: [0, 0, 0],
-        };
-    }
-    const minX = Math.min(...xs);
-    const maxX = Math.max(...xs);
-    const minY = Math.min(...ys);
-    const maxY = Math.max(...ys);
-    const minZ = Math.min(...zs);
-    const maxZ = Math.max(...zs);
-    return {
-        size: [maxX - minX, maxY - minY, maxZ - minZ],
-        center: [(minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2],
-    };
-}
-function footprintPosition(node, center) {
-    const cos = Math.cos(node.rotation);
-    const sin = Math.sin(node.rotation);
-    return [
-        node.position[0] + center[0] * cos + center[2] * sin,
-        node.position[1],
-        node.position[2] - center[0] * sin + center[2] * cos,
-    ];
-}
-export const blockDefinition = {
-    kind: 'block',
-    schemaVersion: 5,
-    schema: BlockNode,
-    category: 'structure',
-    surfaceRole: 'wall',
-    snapProfile: 'structural',
-    extensions: {
-        'pascal:editor/floorplan': {
-            tool: () => import('./tool.js'),
-            preferredView: '3d',
-        },
-        'pascal:editor/contextual-help': blockContextualHelp,
-    },
-    defaults: () => ({
-        object: 'node',
-        parentId: null,
-        visible: true,
-        metadata: {},
-        children: [],
-        position: [0, 0, 0],
-        rotation: 0,
-        topology: createBoxBlockTopology(),
-        slots: {},
-        slotNames: { body: 'Body' },
-    }),
-    capabilities: {
-        batchable: perNodeGeometryBatchable,
-        selectable: { hitVolume: 'bbox' },
-        surfaces: {
-            hosting: blockSurfaceProvider,
-            top: {
-                height: (rawNode) => {
-                    const node = rawNode;
-                    const { size, center } = blockBounds(node);
-                    return center[1] + size[1] / 2;
-                },
-            },
-            sides: { faces: 'all' },
-        },
-        movable: { axes: ['x', 'z'], gridSnap: true },
-        duplicable: { subtree: true },
-        deletable: true,
-        dragBounds: (rawNode) => blockBounds(rawNode),
-        floorPlaced: {
-            footprint: (rawNode) => {
-                const node = rawNode;
-                const { size, center } = blockBounds(node);
-                return {
-                    dimensions: size,
-                    position: footprintPosition(node, center),
-                    rotation: [0, node.rotation, 0],
-                };
-            },
-            collides: (rawNode) => blockRestsOnFloor(rawNode),
-        },
-        paint: blockPaint,
-        slots: (rawNode) => blockSlots(rawNode),
-        faceHost: blockFaceHost,
-    },
-    relations: {
-        hosts: ['item'],
-        cascadeDelete: 'descendants',
-    },
-    geometry: buildBlockGeometry,
-    geometryChildTypes: [],
-    geometryKey: (node) => JSON.stringify([node.topology, node.slots]),
-    floorplan: buildBlockFloorplan,
-    parametrics: blockParametrics,
-    affordanceTools: {
-        selection: () => import('./selection.js'),
-    },
-    preview: () => import('./preview.js'),
-    tool: () => import('./tool.js'),
-    toolHints: [
-        { key: 'Left click', label: 'Place block' },
-        { key: 'Esc', label: 'Cancel' },
-    ],
-    presentation: {
-        label: 'Block',
-        description: 'A topology-backed solid edited directly in the canvas.',
-        icon: { kind: 'url', src: '/icons/cube.webp' },
-        paletteSection: 'structure',
-        paletteOrder: 75,
-        actionMenu: false,
-    },
-    mcp: {
-        description: 'An editable block solid with persistent vertex, edge, and face topology. Positions are level-local meters.',
-    },
-};
+import { composeNodeDefinition } from '../definition-contributions.js';
+import { blockEditContribution } from './definition.edit.js';
+import { blockRenderDefinition } from './definition.render.js';
+export const blockDefinition = composeNodeDefinition(blockRenderDefinition, blockEditContribution);
+export { blockBounds } from './definition.render.js';

package/dist/block/definition.render.d.ts

@@ -0,0 +1,11 @@
+import { type BlockNode as BlockNodeType } from '@pascal-app/core';
+import type { NodeRenderDefinition } from '../definition-contributions.js';
+import { BlockNode } from './schema.js';
+export declare function blockBounds(node: BlockNodeType): {
+    size: [number, number, number];
+    center: [number, number, number];
+};
+export declare const blockRenderDefinition: NodeRenderDefinition<typeof BlockNode> & {
+    kind: 'block';
+};
+//# sourceMappingURL=definition.render.d.ts.map

package/dist/block/definition.render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.render.d.ts","sourceRoot":"","sources":["../../src/block/definition.render.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,IAAI,aAAa,EAGhC,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAIvE,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAoBpC,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa;UAMtB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;YACtB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;EAalD;AAYD,eAAO,MAAM,qBAAqB,EAAE,oBAAoB,CAAC,OAAO,SAAS,CAAC,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAsE3F,CAAA"}

package/dist/block/definition.render.js

@@ -0,0 +1,120 @@
+import { blockSlots, createBoxBlockTopology, } from '@pascal-app/core';
+import { perNodeGeometryBatchable } from '../shared/node-batch/batchable.js';
+import { blockFaceHost } from './face-host.js';
+import { buildBlockGeometry } from './geometry.js';
+import { BlockNode } from './schema.js';
+import { blockSurfaceProvider } from './surface.js';
+/** Bottom within this of the floor (and top above it): the block stands on the floor. */
+const BLOCK_ON_FLOOR_MAX_BOTTOM = 0.1;
+const BLOCK_ON_FLOOR_MIN_TOP = 0.01;
+/**
+ * Floor collision is for blocks standing on the floor. Soffits, vaults,
+ * gutters and mantels hang above floor placements, and foundation pads sit
+ * under the floor, so neither blocks furniture nor gets refused when moved.
+ */
+function blockRestsOnFloor(node) {
+    const { size, center } = blockBounds(node);
+    const bottom = node.position[1] + center[1] - size[1] / 2;
+    const top = node.position[1] + center[1] + size[1] / 2;
+    return bottom <= BLOCK_ON_FLOOR_MAX_BOTTOM && top > BLOCK_ON_FLOOR_MIN_TOP;
+}
+export function blockBounds(node) {
+    const xs = node.topology.vertices.map((vertex) => vertex.position[0]);
+    const ys = node.topology.vertices.map((vertex) => vertex.position[1]);
+    const zs = node.topology.vertices.map((vertex) => vertex.position[2]);
+    if (xs.length === 0) {
+        return {
+            size: [0, 0, 0],
+            center: [0, 0, 0],
+        };
+    }
+    const minX = Math.min(...xs);
+    const maxX = Math.max(...xs);
+    const minY = Math.min(...ys);
+    const maxY = Math.max(...ys);
+    const minZ = Math.min(...zs);
+    const maxZ = Math.max(...zs);
+    return {
+        size: [maxX - minX, maxY - minY, maxZ - minZ],
+        center: [(minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2],
+    };
+}
+function footprintPosition(node, center) {
+    const cos = Math.cos(node.rotation);
+    const sin = Math.sin(node.rotation);
+    return [
+        node.position[0] + center[0] * cos + center[2] * sin,
+        node.position[1],
+        node.position[2] - center[0] * sin + center[2] * cos,
+    ];
+}
+export const blockRenderDefinition = {
+    kind: 'block',
+    schemaVersion: 5,
+    schema: BlockNode,
+    category: 'structure',
+    surfaceRole: 'wall',
+    defaults: () => ({
+        object: 'node',
+        parentId: null,
+        visible: true,
+        metadata: {},
+        children: [],
+        position: [0, 0, 0],
+        rotation: 0,
+        topology: createBoxBlockTopology(),
+        slots: {},
+        slotNames: { body: 'Body' },
+    }),
+    capabilities: {
+        batchable: perNodeGeometryBatchable,
+        selectable: { hitVolume: 'bbox' },
+        surfaces: {
+            hosting: blockSurfaceProvider,
+            top: {
+                height: (rawNode) => {
+                    const node = rawNode;
+                    const { size, center } = blockBounds(node);
+                    return center[1] + size[1] / 2;
+                },
+            },
+            sides: { faces: 'all' },
+        },
+        movable: { axes: ['x', 'z'], gridSnap: true },
+        duplicable: { subtree: true },
+        deletable: true,
+        dragBounds: (rawNode) => blockBounds(rawNode),
+        floorPlaced: {
+            footprint: (rawNode) => {
+                const node = rawNode;
+                const { size, center } = blockBounds(node);
+                return {
+                    dimensions: size,
+                    position: footprintPosition(node, center),
+                    rotation: [0, node.rotation, 0],
+                };
+            },
+            collides: (rawNode) => blockRestsOnFloor(rawNode),
+        },
+        slots: (rawNode) => blockSlots(rawNode),
+        faceHost: blockFaceHost,
+    },
+    relations: {
+        hosts: ['item'],
+        cascadeDelete: 'descendants',
+    },
+    geometry: buildBlockGeometry,
+    geometryChildTypes: [],
+    geometryKey: (node) => JSON.stringify([node.topology, node.slots]),
+    presentation: {
+        label: 'Block',
+        description: 'A topology-backed solid edited directly in the canvas.',
+        icon: { kind: 'url', src: '/icons/cube.webp' },
+        paletteSection: 'structure',
+        paletteOrder: 75,
+        actionMenu: false,
+    },
+    mcp: {
+        description: 'An editable block solid with persistent vertex, edge, and face topology. Positions are level-local meters.',
+    },
+};

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

@@ -1,30 +1,104 @@
-import { type NodeDefinition } from '@pascal-app/core';
-import { BoxVentNode } from './schema.js';
-/**
- * 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>;
+export declare const boxVentDefinition: import("@pascal-app/core").NodeDefinition<import("zod").ZodObject<{
+    object: import("zod").ZodDefault<import("zod").ZodLiteral<"node">>;
+    name: import("zod").ZodOptional<import("zod").ZodString>;
+    parentId: import("zod").ZodDefault<import("zod").ZodNullable<import("zod").ZodString>>;
+    visible: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodBoolean>>;
+    camera: import("zod").ZodOptional<import("zod").ZodObject<{
+        position: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+        target: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+        mode: import("zod").ZodDefault<import("zod").ZodEnum<{
+            orthographic: "orthographic";
+            perspective: "perspective";
+        }>>;
+        fov: import("zod").ZodOptional<import("zod").ZodNumber>;
+        zoom: import("zod").ZodOptional<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strip>>;
+    metadata: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>;
+    provenance: import("zod").ZodOptional<import("zod").ZodObject<{
+        refs: import("zod").ZodArray<import("zod").ZodObject<{
+            ns: import("zod").ZodOptional<import("zod").ZodString>;
+            id: import("zod").ZodString;
+            role: import("zod").ZodOptional<import("zod").ZodEnum<{
+                absorbed: "absorbed";
+                alias: "alias";
+                derived: "derived";
+                piece: "piece";
+                primary: "primary";
+            }>>;
+        }, import("zod/v4/core").$strip>>;
+        lineage: import("zod").ZodOptional<import("zod").ZodObject<{
+            op: import("zod").ZodEnum<{
+                attach: "attach";
+                convert: "convert";
+                duplicate: "duplicate";
+                import: "import";
+                "make-independent": "make-independent";
+                merge: "merge";
+                promote: "promote";
+                split: "split";
+            }>;
+            fromIds: import("zod").ZodArray<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>>;
+    id: import("zod").ZodDefault<import("zod").ZodTemplateLiteral<`bvent_${string}`>>;
+    type: import("zod").ZodDefault<import("zod").ZodLiteral<"box-vent">>;
+    material: import("zod").ZodOptional<import("zod").ZodObject<{
+        id: import("zod").ZodOptional<import("zod").ZodString>;
+        preset: import("zod").ZodOptional<import("zod").ZodCatch<import("zod").ZodEnum<{
+            brick: "brick";
+            concrete: "concrete";
+            custom: "custom";
+            glass: "glass";
+            marble: "marble";
+            metal: "metal";
+            plaster: "plaster";
+            tile: "tile";
+            white: "white";
+            wood: "wood";
+        }>>>;
+        properties: import("zod").ZodOptional<import("zod").ZodObject<{
+            color: import("zod").ZodDefault<import("zod").ZodString>;
+            roughness: import("zod").ZodDefault<import("zod").ZodNumber>;
+            metalness: import("zod").ZodDefault<import("zod").ZodNumber>;
+            opacity: import("zod").ZodDefault<import("zod").ZodNumber>;
+            transparent: import("zod").ZodDefault<import("zod").ZodBoolean>;
+            side: import("zod").ZodDefault<import("zod").ZodEnum<{
+                back: "back";
+                double: "double";
+                front: "front";
+            }>>;
+        }, import("zod/v4/core").$strip>>;
+        texture: import("zod").ZodOptional<import("zod").ZodObject<{
+            url: import("zod").ZodString;
+            repeat: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+            scale: import("zod").ZodOptional<import("zod").ZodNumber>;
+            offset: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+            normalMap: import("zod").ZodOptional<import("zod").ZodString>;
+            normalScale: import("zod").ZodOptional<import("zod").ZodNumber>;
+            bumpMap: import("zod").ZodOptional<import("zod").ZodString>;
+            bumpScale: import("zod").ZodOptional<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>>;
+    slots: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+    materialPreset: import("zod").ZodDefault<import("zod").ZodString>;
+    roofSegmentId: import("zod").ZodOptional<import("zod").ZodString>;
+    position: import("zod").ZodDefault<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+    rotation: import("zod").ZodDefault<import("zod").ZodNumber>;
+    width: import("zod").ZodDefault<import("zod").ZodNumber>;
+    depth: import("zod").ZodDefault<import("zod").ZodNumber>;
+    height: import("zod").ZodDefault<import("zod").ZodNumber>;
+    hoodOverhang: import("zod").ZodDefault<import("zod").ZodNumber>;
+    topTaper: import("zod").ZodDefault<import("zod").ZodNumber>;
+    capHeight: import("zod").ZodDefault<import("zod").ZodNumber>;
+    capGap: import("zod").ZodDefault<import("zod").ZodNumber>;
+    domeCurvature: import("zod").ZodDefault<import("zod").ZodNumber>;
+    baseInset: import("zod").ZodDefault<import("zod").ZodNumber>;
+    baseHeight: import("zod").ZodDefault<import("zod").ZodNumber>;
+    cornerBevel: import("zod").ZodDefault<import("zod").ZodNumber>;
+    style: import("zod").ZodPreprocess<import("zod").ZodDefault<import("zod").ZodEnum<{
+        box: "box";
+        cap: "cap";
+        dome: "dome";
+    }>>, unknown>;
+}, import("zod/v4/core").$strip>>;
 //# sourceMappingURL=definition.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/box-vent/definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,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,CA0DhE,CAAA"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/box-vent/definition.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAG7B,CAAA"}

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

@@ -0,0 +1,4 @@
+import type { NodeEditContribution } from '../definition-contributions.js';
+import type { BoxVentNode } from './schema.js';
+export declare const boxVentEditContribution: NodeEditContribution<typeof BoxVentNode>;
+//# sourceMappingURL=definition.edit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"definition.edit.d.ts","sourceRoot":"","sources":["../../src/box-vent/definition.edit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAIvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAgJ3C,eAAO,MAAM,uBAAuB,EAAE,oBAAoB,CAAC,OAAO,WAAW,CAiB5E,CAAA"}

package/dist/box-vent/definition.edit.js

@@ -0,0 +1,151 @@
+import { buildBoxVentFloorplan } from './floorplan.js';
+import { boxVentPaint } from './paint.js';
+import { boxVentParametrics } from './parametrics.js';
+// 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' }));
+export const boxVentEditContribution = {
+    snapProfile: 'item',
+    capabilities: {
+        paint: boxVentPaint,
+    },
+    parametrics: boxVentParametrics,
+    handles: boxVentHandles,
+    floorplan: buildBoxVentFloorplan,
+    preview: () => import('./preview.js'),
+    tool: () => import('./tool.js'),
+    affordanceTools: {
+        move: () => import('./move-tool.js'),
+    },
+    toolHints: [
+        { key: 'Left click', label: 'Place box vent on roof' },
+        { key: 'Esc', label: 'Cancel' },
+    ],
+};