@pascal-app/nodes 1.0.6 → 1.1.0

package/dist/procedural-item/definition.render.js

@@ -0,0 +1,84 @@
+import { getEffectiveNode, proceduralItemSlots } from '@pascal-app/core';
+import { evaluateRecipe, ProceduralItemNode, proceduralCeilingHole, proceduralFootprint, shelfRecipe, } from '@pascal-app/core/procedural-items';
+import { proceduralMechanism } from '../shared/item-interactions.js';
+import { bakeProceduralAnimationClips, isProceduralMotionPlaying } from './animation.js';
+export const proceduralItemRenderDefinition = {
+    kind: 'procedural-item',
+    schemaVersion: 1,
+    schema: ProceduralItemNode,
+    category: 'furnish',
+    surfaceRole: 'furnishing',
+    defaults: () => ({
+        object: 'node',
+        parentId: null,
+        visible: true,
+        metadata: {},
+        recipe: shelfRecipe,
+        parameters: {},
+        slots: {},
+        children: [],
+        attachments: {},
+        position: [0, 0, 0],
+        rotation: [0, 0, 0],
+    }),
+    capabilities: {
+        reveal: { phase: 'furnishing', style: 'drop', height: 0.3 },
+        revealOnEdit: ['recipe'],
+        batchable: {
+            scope: 'level',
+            // Part lights clone their emissive slot per node, and a playing motion
+            // moves meshes under the static copy.
+            excluded: (n) => n.recipe.parts.some((part) => part.light) ||
+                isProceduralMotionPlaying(n.id),
+        },
+        selectable: { hitVolume: 'bbox' },
+        mechanism: proceduralMechanism,
+        dragBounds: (n) => {
+            const node = n;
+            const e = evaluateRecipe(node.recipe, node.parameters);
+            return {
+                size: e.dimensions,
+                center: e.min.map((v, i) => (v + e.max[i]) / 2),
+            };
+        },
+        hostable: {
+            parents: ['level', 'wall', 'ceiling', 'procedural-item', 'item', 'shelf'],
+            align: 'face',
+        },
+        hostRefFields: ['wallId', 'side', 'supportSlabId'],
+        ceilingCut: {
+            buildCeilingHole: (n) => {
+                const node = getEffectiveNode(n);
+                return node.visible === false ? null : proceduralCeilingHole(node);
+            },
+        },
+        floorPlaced: {
+            footprint: (n) => proceduralFootprint(n),
+            applies: (n) => !n.recipe.mounting,
+            collides: true,
+        },
+        movable: { axes: ['x', 'z'], gridSnap: true },
+        rotatable: { axes: ['y'], snapAngles: [0, Math.PI / 4, Math.PI / 2, Math.PI] },
+        duplicable: { subtree: 'with-children' },
+        deletable: true,
+        slots: (n) => proceduralItemSlots(n),
+        surfaces: {
+            custom: (n) => evaluateRecipe(n.recipe, n.parameters).surfaces.map((s) => ({
+                id: s.id,
+                position: s.position,
+                normal: s.normal,
+                rotation: s.rotation,
+                size: s.size,
+            })),
+        },
+    },
+    relations: { hosts: ['item', 'procedural-item'], cascadeDelete: 'descendants' },
+    renderer: { kind: 'parametric', module: () => import('./renderer.js') },
+    exportAnimation: ({ node, object }) => bakeProceduralAnimationClips(node, object),
+    presentation: {
+        label: 'Procedural item',
+        description: 'Experimental editable recipe',
+        icon: { kind: 'iconify', name: 'lucide:boxes' },
+    },
+    mcp: { description: 'Experimental procedural item with a validated recipe.' },
+};

package/dist/procedural-item/renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/procedural-item/renderer.tsx"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,kBAAkB,EAGxB,MAAM,mCAAmC,CAAA;AA0C1C,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,+BA4VhF"}
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/procedural-item/renderer.tsx"],"names":[],"mappings":"AAWA,OAAO,EAIL,KAAK,kBAAkB,EAGxB,MAAM,mCAAmC,CAAA;AAyC1C,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,+BAqVhF"}

package/dist/procedural-item/renderer.edit.d.ts

@@ -0,0 +1,5 @@
+import type { ProceduralItemNode } from '@pascal-app/core/procedural-items';
+export default function EditorProceduralRenderer({ node }: {
+    node: ProceduralItemNode;
+}): import("react").JSX.Element;
+//# sourceMappingURL=renderer.edit.d.ts.map

package/dist/procedural-item/renderer.edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.edit.d.ts","sourceRoot":"","sources":["../../src/procedural-item/renderer.edit.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAA;AAK3E,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,+BAuCtF"}

package/dist/procedural-item/renderer.edit.js

@@ -0,0 +1,49 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLiveNodeOverrides, useScene } from '@pascal-app/core';
+import { usePlacementPreview } from '@pascal-app/editor';
+import { useEffect } from 'react';
+import ProceduralRenderer from './renderer.js';
+export default function EditorProceduralRenderer({ node }) {
+    const overrides = useLiveNodeOverrides((s) => s.overrides.get(node.id));
+    const effective = { ...node, ...overrides };
+    const cutKey = effective.recipe.cuts
+        ? JSON.stringify([
+            node.parentId,
+            effective.position,
+            effective.rotation,
+            effective.parameters,
+            effective.visible,
+            effective.recipe.cuts,
+            effective.recipe.surfaces,
+            effective.recipe.mounting?.reference,
+        ])
+        : '';
+    useEffect(() => {
+        const parentId = node.parentId;
+        if (!(cutKey && parentId))
+            return;
+        const recut = (id = parentId) => {
+            if (id && useScene.getState().nodes[id])
+                useScene.getState().markDirty(id);
+        };
+        // A move preview of this design re-cuts its ceiling, and the ceiling it previews on, on
+        // every step.
+        const unsubscribe = usePlacementPreview.subscribe((state, previous) => {
+            if (state.node?.id !== node.id && previous.node?.id !== node.id)
+                return;
+            recut();
+            for (const id of new Set([state.node?.parentId, previous.node?.parentId]))
+                if (id !== parentId && useScene.getState().nodes[id]?.type === 'ceiling')
+                    recut(id);
+        });
+        return () => {
+            unsubscribe();
+            recut();
+            const preview = usePlacementPreview.getState().node;
+            if (preview?.id === node.id && preview.parentId !== parentId)
+                recut(preview.parentId);
+        };
+    }, [cutKey, node.parentId, node.id]);
+    return _jsx(ProceduralRenderer, { node: node });
+}

package/dist/procedural-item/renderer.js

@@ -1,8 +1,7 @@
 'use client';
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useInteractive, useLiveNodeOverrides, useLiveTransforms, useRegistry, useScene, } from '@pascal-app/core';
+import { emitter, useInteractive, useLiveNodeOverrides, useLiveTransforms, useRegistry, useScene, } from '@pascal-app/core';
 import { motionAxis, motionRestOffset, ProceduralMotionController, proceduralLocalPose, } from '@pascal-app/core/procedural-items';
-import { usePlacementPreview } from '@pascal-app/editor';
 import { cloneWithProceduralEmission, createSurfaceRoleMaterial, materialCastsShadow, NodeRenderer, proceduralSlotMeshes, resolveMaterialRef, resolveSlotDefaultMaterial, setProceduralEmission, useItemLightPool, useLibraryMaterialsVersion, useNodeEvents, useViewer, } from '@pascal-app/viewer';
 import { useFrame, useThree } from '@react-three/fiber';
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
@@ -38,6 +37,8 @@ export default function ProceduralRenderer({ node }) {
     const splitRef = useRef(null);
     const controller = useRef(null);
     const lastCommand = useRef(0);
+    // The commanded run whose end is still to be announced (a door or drawer landing).
+    const settling = useRef(null);
     const awake = useRef(false);
     const invalidate = useThree((state) => state.invalidate);
     const overrides = useLiveNodeOverrides((s) => s.overrides.get(node.id));
@@ -101,24 +102,8 @@ export default function ProceduralRenderer({ node }) {
                 useScene.getState().markDirty(id);
         };
         recut();
-        // A move preview of this design re-cuts its ceiling, and the ceiling it previews on, on
-        // every step.
-        const unsubscribe = usePlacementPreview.subscribe((state, previous) => {
-            if (state.node?.id !== node.id && previous.node?.id !== node.id)
-                return;
-            recut();
-            for (const id of new Set([state.node?.parentId, previous.node?.parentId]))
-                if (id !== parentId && useScene.getState().nodes[id]?.type === 'ceiling')
-                    recut(id);
-        });
-        return () => {
-            unsubscribe();
-            recut();
-            const preview = usePlacementPreview.getState().node;
-            if (preview?.id === node.id && preview.parentId !== parentId)
-                recut(preview.parentId);
-        };
-    }, [cutKey, node.parentId, node.id]);
+        return () => recut();
+    }, [cutKey, node.parentId]);
     useLayoutEffect(() => {
         // Continuous joints start running, as in the baked viewer; flat spins keep #930's default.
         const running = new Set((node.recipe.joints ?? [])
@@ -147,7 +132,7 @@ export default function ProceduralRenderer({ node }) {
             awake.current = true;
             invalidate();
         }
-    }, [built, node.id, invalidate]);
+    }, [built, node.id, invalidate, node.recipe.joints]);
     useEffect(() => useInteractive.subscribe((state, previous) => {
         if (state.procedural[node.id] === previous.procedural[node.id])
             return;
@@ -161,10 +146,15 @@ export default function ProceduralRenderer({ node }) {
         if (state?.motionCommand && state.motionCommand.sequence > lastCommand.current) {
             controller.current?.command(state.motionCommand);
             lastCommand.current = state.motionCommand.sequence;
+            settling.current = state.motionCommand.sequence;
         }
         const frame = controller.current?.tick(delta);
         if (!frame)
             return;
+        if (settling.current !== null && frame.settled) {
+            emitter.emit('procedural:motion-settled', { nodeId: node.id, sequence: settling.current });
+            settling.current = null;
+        }
         for (const motion of built.evaluation.motions) {
             const group = ref.current.getObjectByName(`${node.id}__motion__${motion.id}`);
             if (!group)
@@ -238,7 +228,7 @@ export default function ProceduralRenderer({ node }) {
             for (const key of keys)
                 useItemLightPool.getState().unregister(key);
         };
-    }, [built, node.id, effective.visible, effective.metadata?.isNew]);
+    }, [built, node.id, effective.visible, effective.metadata?.isNew, effective.metadata]);
     const materialKey = JSON.stringify([effective.recipe.slots, effective.slots, libraryVersion]);
     const materials = useMemo(() => {
         const [slots, overrides] = JSON.parse(materialKey);

package/dist/render.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from '@pascal-app/core';
+/** Load exactly one built-in plugin: render for viewers, builtinPlugin for editors. */
+export declare const renderPlugin: Plugin;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAI9C,uFAAuF;AACvF,eAAO,MAAM,YAAY,EAAE,MAA+D,CAAA"}

package/dist/render.js

@@ -0,0 +1,4 @@
+import { renderDefinitions } from './builtin-definitions.js';
+import { builtinPluginMetadata } from './builtin-plugin-metadata.js';
+/** Load exactly one built-in plugin: render for viewers, builtinPlugin for editors. */
+export const renderPlugin = { ...builtinPluginMetadata, nodes: renderDefinitions };

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

@@ -1,16 +1,96 @@
-import { type NodeDefinition } from '@pascal-app/core';
-import { RidgeVentNode } from './schema.js';
-/**
- * Ridge vent — a ventilation strip running along the ridge of a roof
- * segment. Parented to a `roof-segment`; position is segment-local.
- *
- * Three-checkbox model — same shape as box-vent: custom `def.renderer`
- * (parent segment transform lookup + live-transform follow), pure
- * geometry builder shared with the placement preview + future tests,
- * no animation or per-frame system.
- *
- * The placement tool snaps to the nearest ridge/break line wherever the
- * cursor lands on a segment.
- */
-export declare const ridgeVentDefinition: NodeDefinition<typeof RidgeVentNode>;
+export declare const ridgeVentDefinition: 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<`rvent_${string}`>>;
+    type: import("zod").ZodDefault<import("zod").ZodLiteral<"ridge-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>>;
+    materialPreset: import("zod").ZodOptional<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>;
+    length: import("zod").ZodDefault<import("zod").ZodNumber>;
+    width: import("zod").ZodDefault<import("zod").ZodNumber>;
+    height: import("zod").ZodDefault<import("zod").ZodNumber>;
+    style: import("zod").ZodDefault<import("zod").ZodEnum<{
+        metal: "metal";
+        shingled: "shingled";
+        standard: "standard";
+    }>>;
+    endCaps: import("zod").ZodDefault<import("zod").ZodBoolean>;
+}, import("zod/v4/core").$strip>>;
 //# sourceMappingURL=definition.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/ridge-vent/definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAGpB,MAAM,kBAAkB,CAAA;AAIzB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAwIxC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EAAE,cAAc,CAAC,OAAO,aAAa,CA6DpE,CAAA"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/ridge-vent/definition.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAG/B,CAAA"}

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

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

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

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

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

@@ -0,0 +1,148 @@
+import { surfacePaintCapability } from '../shared/surface-paint.js';
+import { buildRidgeVentFloorplan } from './floorplan.js';
+import { ridgeVentParametrics } from './parametrics.js';
+// Edge-to-arrow-center offset, matching the box-vent / chimney cadence.
+const SIDE_HANDLE_OFFSET = 0.25;
+const HEIGHT_HANDLE_OFFSET = 0.15;
+// Snug to the vent corner — keeps the rotate icon close to the item.
+const ROTATE_CORNER_OFFSET = 0.1;
+// Ridge vents are long but thin — minimums let users shrink without
+// collapsing the geometry past the point where the cross-section
+// degenerates. Default length is 2.0, default width 0.3, default
+// height 0.08, so these are well below the defaults.
+const MIN_LENGTH = 0.2;
+const MIN_WIDTH = 0.1;
+const MIN_HEIGHT = 0.02;
+// Mid-Y of the vent body in vent-mesh-local frame. The base sits at the
+// ridge line (Y=0) and the cap peaks at Y=height — so side / rotate
+// chevrons place at half-height to read as "beside the body".
+function getBodyMidY(n) {
+    return Math.max(MIN_HEIGHT, n.height) / 2;
+}
+// Length arrow on ±X (the ridge direction). Asymmetric: drag one end
+// outward and the opposite end stays world-fixed by recentering
+// `position` along the vent's own +X arm in segment frame (yaw-aware
+// math, matches box-vent / chimney). The ridge vent typically straddles
+// a portion of the ridge, so dragging one end is the natural extend /
+// shorten gesture.
+function ridgeVentLengthHandle(side) {
+    const sign = side === 'right' ? 1 : -1;
+    return {
+        kind: 'linear-resize',
+        axis: 'x',
+        anchor: side === 'right' ? 'min' : 'max',
+        min: MIN_LENGTH,
+        currentValue: (n) => n.length,
+        apply: (initial, newLength) => {
+            const rotY = initial.rotation ?? 0;
+            const armX = Math.cos(rotY);
+            const armZ = -Math.sin(rotY);
+            const anchorX = initial.position[0] - sign * (initial.length / 2) * armX;
+            const anchorZ = initial.position[2] - sign * (initial.length / 2) * armZ;
+            const newCenterX = anchorX + sign * (newLength / 2) * armX;
+            const newCenterZ = anchorZ + sign * (newLength / 2) * armZ;
+            return {
+                length: newLength,
+                position: [newCenterX, initial.position[1], newCenterZ],
+            };
+        },
+        placement: {
+            position: (n) => [sign * (n.length / 2 + SIDE_HANDLE_OFFSET), getBodyMidY(n), 0],
+            rotationY: () => (side === 'right' ? 0 : Math.PI),
+        },
+    };
+}
+// Width arrow on +Z (across the ridge). Symmetric — the vent geometry
+// straddles the ridge line (Z=0) so growing the width pushes both edges
+// outward by the same amount. A single chevron on +Z reads as "this is
+// the width dimension"; keeping it symmetric also stays inside the same
+// handle-count budget the chimney / dormer / box-vent already document.
+function ridgeVentWidthHandle() {
+    return {
+        kind: 'linear-resize',
+        axis: 'z',
+        anchor: 'center',
+        min: MIN_WIDTH,
+        currentValue: (n) => n.width,
+        apply: (_n, newValue) => ({ width: newValue }),
+        placement: {
+            position: (n) => [0, getBodyMidY(n), n.width / 2 + SIDE_HANDLE_OFFSET],
+        },
+    };
+}
+// Height arrow above the cap peak. anchor='min' so the base stays
+// pinned to the ridge line (Y=0) and the peak follows the cursor. Plain
+// chevron — at default 0.08 m a dashed tracker leader would be visual
+// noise rather than a dimension cue.
+function ridgeVentHeightHandle() {
+    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.
+// Negate the cursor delta to match three.js Y-rotation handedness. The
+// registered group already centres on the vent and applies its yaw,
+// so the default rotation pivot is correct.
+function ridgeVentRotateHandle() {
+    return {
+        kind: 'arc-resize',
+        axis: 'angular',
+        shape: 'rotate',
+        apply: (initial, delta) => ({ rotation: (initial.rotation ?? 0) - delta }),
+        placement: {
+            position: (n) => [
+                n.length / 2 + ROTATE_CORNER_OFFSET,
+                getBodyMidY(n),
+                n.width / 2 + ROTATE_CORNER_OFFSET,
+            ],
+            // Two-headed icon's natural bias is along +X; aim along the
+            // +X+Z corner bisector so it sits visually flush with the
+            // rotate gesture's swing direction.
+            rotationY: () => -Math.PI / 4,
+        },
+        // Guide ring centred on the vent, sized to pass through the corner icon
+        // so the icon rides the ring — matches solar-panel / skylight.
+        decoration: {
+            kind: 'ring',
+            radius: (n) => Math.hypot(n.length / 2 + ROTATE_CORNER_OFFSET, n.width / 2 + ROTATE_CORNER_OFFSET),
+            y: (n) => getBodyMidY(n),
+        },
+    };
+}
+// `portal: 'grandparent'` on every handle — see box-vent's note. The vent
+// rides the roof→segment→node frame chain, so the handle rig must too, or
+// the handles (and rotate arc) render offset from the vent.
+const ridgeVentHandles = [
+    ridgeVentLengthHandle('right'),
+    ridgeVentLengthHandle('left'),
+    ridgeVentWidthHandle(),
+    ridgeVentHeightHandle(),
+    ridgeVentRotateHandle(),
+].map((h) => ({ ...h, portal: 'grandparent' }));
+export const ridgeVentEditContribution = {
+    snapProfile: 'item',
+    capabilities: {
+        // Single painted surface — registry-driven paint dispatch (see chimney).
+        paint: surfacePaintCapability,
+    },
+    parametrics: ridgeVentParametrics,
+    handles: ridgeVentHandles,
+    floorplan: buildRidgeVentFloorplan,
+    preview: () => import('./preview.js'),
+    tool: () => import('./tool.js'),
+    affordanceTools: {
+        move: () => import('./move-tool.js'),
+    },
+    toolHints: [
+        { key: 'Left click', label: 'Place ridge vent on roof' },
+        { key: 'Esc', label: 'Cancel' },
+    ],
+};