@pascal-app/nodes 1.0.7 → 1.1.0

package/dist/item/definition.d.ts

@@ -1,32 +1,281 @@
-import { type NodeDefinition } from '@pascal-app/core';
-import { ItemNode } from './schema.js';
-/**
- * Item — Phase 5 batch kind. Catalog-backed, GLB-rendered, multi-host.
- *
- * Demonstrates the **custom `def.renderer` escape hatch** ("Opting out of a
- * generic path" in wiki/architecture/node-definitions.md): items use `useGLTF` from drei to
- * load CDN assets, plus a non-trivial interactive-widget layer inside
- * the rendered scene. Not expressible as a pure `def.geometry`. The
- * registry mounts the custom React renderer as-is.
- *
- * Capabilities:
- *  - **No `movable`**: item's move is bespoke `MoveItemContent` —
- *    handles attachTo transitions mid-drag (floor ↔ wall ↔ ceiling),
- *    asset.attachTo lookups, scale-preserving Y math for surface
- *    placement. The smooth generic mover can't express that. Legacy
- *    mover keeps running via capability-driven dispatch.
- *  - `selectable`, `duplicable`, `deletable` standard.
- *
- * Stages:
- *  - A: registered.
- *  - B: N/A — def.renderer escape hatch (GLB / useGLTF).
- *  - C: `def.floorplan` resolves parent chain via `ctx.resolve`,
- *    returns a rotated rectangle (width × depth). Mirrors the legacy
- *    `getItemFloorplanTransform` math. Legacy `floorplanItemEntries`
- *    short-circuits when item is registered.
- *
- * `toolHints`: matches the legacy ItemHelper UI (mouse / R / T / Shift /
- * Esc) — registry-driven placement panel.
- */
-export declare const itemDefinition: NodeDefinition<typeof ItemNode>;
+export declare const itemDefinition: 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<`item_${string}`>>;
+    type: import("zod").ZodDefault<import("zod").ZodLiteral<"item">>;
+    position: import("zod").ZodDefault<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+    rotation: import("zod").ZodDefault<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+    scale: import("zod").ZodDefault<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+    side: import("zod").ZodOptional<import("zod").ZodEnum<{
+        back: "back";
+        front: "front";
+    }>>;
+    children: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+    wallId: import("zod").ZodOptional<import("zod").ZodString>;
+    wallT: import("zod").ZodOptional<import("zod").ZodNumber>;
+    roofSegmentId: import("zod").ZodOptional<import("zod").ZodString>;
+    roofFace: import("zod").ZodOptional<import("zod").ZodEnum<{
+        back: "back";
+        front: "front";
+        left: "left";
+        right: "right";
+    }>>;
+    blockFaceId: import("zod").ZodOptional<import("zod").ZodString>;
+    supportSlabId: import("zod").ZodOptional<import("zod").ZodString>;
+    collectionIds: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodCustom<`collection_${string}`, `collection_${string}`>>>;
+    slots: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+    source: import("zod").ZodOptional<import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"script">;
+        meta: import("zod").ZodOptional<import("zod").ZodObject<{
+            description: import("zod").ZodOptional<import("zod").ZodString>;
+            category: import("zod").ZodOptional<import("zod").ZodString>;
+            tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+            parent: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>;
+        language: import("zod").ZodDefault<import("zod").ZodEnum<{
+            bpy: "bpy";
+            three: "three";
+        }>>;
+        script: import("zod").ZodString;
+        params: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodBoolean, import("zod").ZodString]>>>;
+        artifact: import("zod").ZodString;
+        manifest: import("zod").ZodObject<{
+            bounds: import("zod").ZodObject<{
+                min: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+                max: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+            }, import("zod/v4/core").$strip>;
+            params: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+                id: import("zod").ZodString;
+                label: import("zod").ZodOptional<import("zod").ZodString>;
+                kind: import("zod").ZodEnum<{
+                    boolean: "boolean";
+                    number: "number";
+                    string: "string";
+                }>;
+                default: import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodBoolean, import("zod").ZodString]>;
+                min: import("zod").ZodOptional<import("zod").ZodNumber>;
+                max: import("zod").ZodOptional<import("zod").ZodNumber>;
+                step: import("zod").ZodOptional<import("zod").ZodNumber>;
+                unit: import("zod").ZodOptional<import("zod").ZodString>;
+                options: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+            }, import("zod/v4/core").$strip>>>;
+            parts: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+                id: import("zod").ZodString;
+                label: import("zod").ZodOptional<import("zod").ZodString>;
+                type: import("zod").ZodOptional<import("zod").ZodString>;
+                bounds: import("zod").ZodOptional<import("zod").ZodObject<{
+                    min: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+                    max: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+                }, import("zod/v4/core").$strip>>;
+            }, import("zod/v4/core").$strip>>>;
+            surfaces: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+                part: import("zod").ZodOptional<import("zod").ZodString>;
+                y: import("zod").ZodNumber;
+                polygon: import("zod").ZodArray<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+            }, import("zod/v4/core").$strip>>>;
+            slots: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+                id: import("zod").ZodString;
+                label: import("zod").ZodOptional<import("zod").ZodString>;
+                color: import("zod").ZodOptional<import("zod").ZodString>;
+                roughness: import("zod").ZodOptional<import("zod").ZodNumber>;
+                metalness: import("zod").ZodOptional<import("zod").ZodNumber>;
+                transparent: import("zod").ZodOptional<import("zod").ZodBoolean>;
+                emissive: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            }, import("zod/v4/core").$strip>>>;
+            anchors: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+                id: import("zod").ZodString;
+                position: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+                normal: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+            }, import("zod/v4/core").$strip>>>;
+            lights: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+                id: import("zod").ZodString;
+                position: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+                color: import("zod").ZodString;
+                intensity: import("zod").ZodNumber;
+                distance: import("zod").ZodOptional<import("zod").ZodNumber>;
+                spot: import("zod").ZodOptional<import("zod").ZodObject<{
+                    direction: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+                    angle: import("zod").ZodNumber;
+                    softness: import("zod").ZodNumber;
+                }, import("zod/v4/core").$strip>>;
+                shadows: import("zod").ZodOptional<import("zod").ZodBoolean>;
+                glow: import("zod").ZodOptional<import("zod").ZodObject<{
+                    size: import("zod").ZodNumber;
+                    strength: import("zod").ZodDefault<import("zod").ZodNumber>;
+                }, import("zod/v4/core").$strip>>;
+            }, import("zod/v4/core").$strip>>>;
+            undersides: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+                part: import("zod").ZodOptional<import("zod").ZodString>;
+                polygon: import("zod").ZodArray<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+                plane: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+            }, import("zod/v4/core").$strip>>>;
+            animations: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+                name: import("zod").ZodString;
+                duration: import("zod").ZodNumber;
+            }, import("zod/v4/core").$strip>>>;
+            cutters: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+                host: import("zod").ZodEnum<{
+                    ceiling: "ceiling";
+                    mounted: "mounted";
+                    slab: "slab";
+                    wall: "wall";
+                }>;
+                polygon: import("zod").ZodArray<import("zod").ZodArray<import("zod").ZodNumber>>;
+                minY: import("zod").ZodNumber;
+                maxY: import("zod").ZodNumber;
+            }, import("zod/v4/core").$strip>>>;
+            cutout: import("zod").ZodDefault<import("zod").ZodBoolean>;
+            collider: import("zod").ZodDefault<import("zod").ZodBoolean>;
+            shape: import("zod").ZodOptional<import("zod").ZodObject<{
+                tolerance: import("zod").ZodNumber;
+                bands: import("zod").ZodArray<import("zod").ZodObject<{
+                    y0: import("zod").ZodNumber;
+                    y1: import("zod").ZodNumber;
+                    polygons: import("zod").ZodArray<import("zod").ZodObject<{
+                        outer: import("zod").ZodArray<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+                        holes: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodArray<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber], null>>>>;
+                    }, import("zod/v4/core").$strip>>;
+                }, import("zod/v4/core").$strip>>;
+            }, import("zod/v4/core").$strip>>;
+            triangles: import("zod").ZodNumber;
+            coverage: import("zod").ZodOptional<import("zod").ZodNumber>;
+            uncovered: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+                min: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber], null>;
+                max: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber], null>;
+            }, import("zod/v4/core").$strip>>>;
+        }, import("zod/v4/core").$strip>;
+        images: import("zod").ZodOptional<import("zod").ZodObject<{
+            artifact: import("zod").ZodString;
+            thumbnail: import("zod").ZodString;
+            floorPlan: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>>;
+    asset: import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        category: import("zod").ZodString;
+        name: import("zod").ZodString;
+        thumbnail: import("zod").ZodString;
+        floorPlanUrl: import("zod").ZodOptional<import("zod").ZodString>;
+        source: import("zod").ZodDefault<import("zod").ZodEnum<{
+            community: "community";
+            library: "library";
+            mine: "mine";
+        }>>;
+        isDraft: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        src: import("zod").ZodString;
+        dimensions: import("zod").ZodDefault<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+        attachTo: import("zod").ZodOptional<import("zod").ZodEnum<{
+            ceiling: "ceiling";
+            wall: "wall";
+            "wall-side": "wall-side";
+        }>>;
+        recessed: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        functionTags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        offset: import("zod").ZodDefault<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+        rotation: import("zod").ZodDefault<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+        scale: import("zod").ZodDefault<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+        surface: import("zod").ZodOptional<import("zod").ZodObject<{
+            height: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strip>>;
+        interactive: import("zod").ZodOptional<import("zod").ZodObject<{
+            controls: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                kind: import("zod").ZodLiteral<"toggle">;
+                label: import("zod").ZodOptional<import("zod").ZodString>;
+                default: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                kind: import("zod").ZodLiteral<"slider">;
+                label: import("zod").ZodString;
+                min: import("zod").ZodNumber;
+                max: import("zod").ZodNumber;
+                step: import("zod").ZodDefault<import("zod").ZodNumber>;
+                unit: import("zod").ZodOptional<import("zod").ZodString>;
+                displayMode: import("zod").ZodDefault<import("zod").ZodEnum<{
+                    dial: "dial";
+                    slider: "slider";
+                    stepper: "stepper";
+                }>>;
+                default: import("zod").ZodOptional<import("zod").ZodNumber>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                kind: import("zod").ZodLiteral<"temperature">;
+                label: import("zod").ZodDefault<import("zod").ZodString>;
+                min: import("zod").ZodDefault<import("zod").ZodNumber>;
+                max: import("zod").ZodDefault<import("zod").ZodNumber>;
+                unit: import("zod").ZodDefault<import("zod").ZodEnum<{
+                    C: "C";
+                    F: "F";
+                }>>;
+                default: import("zod").ZodOptional<import("zod").ZodNumber>;
+            }, import("zod/v4/core").$strip>], "kind">>>;
+            effects: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                kind: import("zod").ZodLiteral<"animation">;
+                mode: import("zod").ZodOptional<import("zod").ZodEnum<{
+                    ambient: "ambient";
+                    "open-close": "open-close";
+                }>>;
+                control: import("zod").ZodOptional<import("zod").ZodNumber>;
+                clips: import("zod").ZodObject<{
+                    on: import("zod").ZodOptional<import("zod").ZodString>;
+                    off: import("zod").ZodOptional<import("zod").ZodString>;
+                    loop: import("zod").ZodOptional<import("zod").ZodString>;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                kind: import("zod").ZodLiteral<"light">;
+                color: import("zod").ZodDefault<import("zod").ZodString>;
+                intensityRange: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber], null>;
+                distance: import("zod").ZodOptional<import("zod").ZodNumber>;
+                offset: import("zod").ZodDefault<import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>>;
+                spot: import("zod").ZodOptional<import("zod").ZodObject<{
+                    direction: import("zod").ZodTuple<[import("zod").ZodNumber, import("zod").ZodNumber, import("zod").ZodNumber], null>;
+                    angle: import("zod").ZodNumber;
+                    softness: import("zod").ZodNumber;
+                }, import("zod/v4/core").$strip>>;
+                shadows: import("zod").ZodOptional<import("zod").ZodBoolean>;
+                glow: import("zod").ZodOptional<import("zod").ZodObject<{
+                    size: import("zod").ZodNumber;
+                    strength: import("zod").ZodDefault<import("zod").ZodNumber>;
+                }, import("zod/v4/core").$strip>>;
+            }, import("zod/v4/core").$strip>], "kind">>>;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>;
+}, import("zod/v4/core").$strip>>;
 //# sourceMappingURL=definition.d.ts.map

package/dist/item/definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/item/definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,cAAc,EAGpB,MAAM,kBAAkB,CAAA;AAWzB,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AA+HnC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,cAAc,EAAE,cAAc,CAAC,OAAO,QAAQ,CAuN1D,CAAA"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/item/definition.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAAoE,CAAA"}

package/dist/item/definition.edit.d.ts

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

package/dist/item/definition.edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.edit.d.ts","sourceRoot":"","sources":["../../src/item/definition.edit.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAQvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAkIxC,eAAO,MAAM,oBAAoB,EAAE,oBAAoB,CAAC,OAAO,QAAQ,CAiFtE,CAAA"}

package/dist/item/definition.edit.js

@@ -0,0 +1,206 @@
+import { getEffectiveCutterNode, getScaledDimensions, resolveCutterHost, toggleMechanism, } from '@pascal-app/core';
+import { itemHasLights, itemMechanism, toggleItemLights } from '../shared/item-interactions.js';
+import { restingFloorplanAffectedIds } from '../shared/resting-surface-plan.js';
+import { buildItemContextualDimensions, buildItemFloorplan } from './floorplan.js';
+import { itemFloorplanMoveTarget } from './floorplan-move.js';
+import { itemPaint } from './paint.js';
+import { itemParametrics } from './parametrics.js';
+import { itemPlacementNotice } from './placement-notice.js';
+// The two floor gizmos flank the item at mid-height so they never overlap,
+// even on small items: move sits past the left edge, rotate past the right
+// edge, both floated the same distance in front of the item. Mirrors the
+// wall-item layout below (WALL_SIDE_OFFSET / WALL_GIZMO_LIFT). The guide ring
+// traces a circle slightly outside the footprint's bounding circle.
+const GIZMO_SIDE_OFFSET = 0.3;
+const GIZMO_FRONT_OFFSET = 0.3;
+const ROTATE_RING_OFFSET = 0.06;
+// Whole-item rotation handle — the two-headed curved arrow. `arc-resize`
+// does the angular drag math (raycasts a horizontal plane at the gizmo's
+// Y, measures cursor bearing around the item's local origin, returns the
+// delta). Rotation snaps to 15° increments by default; holding Shift
+// bypasses that snap (handled generically in node-arrow-handles for any
+// `shape: 'rotate'`), matching the R/T rotate step for placed items. Item
+// rotation is stored as `[x, y, z]`; only the Y component turns.
+function itemRotateHandle() {
+    return {
+        kind: 'arc-resize',
+        axis: 'angular',
+        shape: 'rotate',
+        // Negate the cursor delta to match three.js Y-rotation handedness
+        // (positive Ry takes +X → −Z, while atan2(z, x) increases +X → +Z).
+        apply: (initial, delta) => {
+            const [rx, ry, rz] = initial.rotation ?? [0, 0, 0];
+            return { rotation: [rx, ry - delta, rz] };
+        },
+        placement: {
+            // Past the item's right edge at mid-height, floated in front. The
+            // registered item mesh carries position + rotation only (scale lives on
+            // an inner mesh), so the scaled footprint maps straight to world.
+            position: (n) => {
+                const [w, h, d] = getScaledDimensions(n);
+                return [w / 2 + GIZMO_SIDE_OFFSET, h / 2, d / 2 + GIZMO_FRONT_OFFSET];
+            },
+            // Fixed −45° tilt leans the curve toward the item's front face.
+            rotationY: () => -Math.PI / 4,
+        },
+        decoration: {
+            kind: 'ring',
+            radius: (n) => {
+                const [w, , d] = getScaledDimensions(n);
+                return Math.hypot(w / 2, d / 2) + ROTATE_RING_OFFSET;
+            },
+            y: (n) => getScaledDimensions(n)[1] / 2,
+        },
+    };
+}
+// The 4-way move cross, just past the item's left edge. Press-drag hands the
+// item to its placement coordinator (showing the bounding box, dimension labels
+// and grid-snap ticker) and commits on release — press-drag-release motion with
+// the full placement feedback.
+function itemMoveHandle() {
+    return {
+        kind: 'tap-action',
+        shape: 'move-cross',
+        cursor: 'move',
+        onActivate: (node, _scene, editor) => editor.engageMoveDrag(node),
+        placement: {
+            // Past the item's left edge at mid-height, mirroring the rotate grip on
+            // the right so the two never overlap on small items.
+            position: (n) => {
+                const [w, h, d] = getScaledDimensions(n);
+                return [-(w / 2 + GIZMO_SIDE_OFFSET), h / 2, d / 2 + GIZMO_FRONT_OFFSET];
+            },
+        },
+    };
+}
+// ---- Wall-mounted items (attachTo 'wall' / 'wall-side') ----
+// These live in the wall's local frame: position is [along-wall, up, depth]
+// and the item faces along the wall normal (its local +Z). Both gizmos use
+// `portal: 'grandparent'` so they render in the wall frame like door / window
+// handles, and sit a little off the wall surface (+Z) so they're grabbable.
+// How far off the wall surface (along the normal) the wall gizmos float, and
+// how far to either side of the item they sit.
+const WALL_GIZMO_LIFT = 0.12;
+const WALL_SIDE_OFFSET = 0.3;
+// Spin the item flat against the wall — rotation about its local +Z (the wall
+// normal), written to rotation[2]. Sits just past the item's right edge.
+function itemWallRotateHandle() {
+    return {
+        kind: 'arc-resize',
+        axis: 'angular',
+        shape: 'rotate',
+        rotationPlane: 'node-normal',
+        portal: 'grandparent',
+        apply: (initial, delta) => {
+            const [rx, ry, rz] = initial.rotation ?? [0, 0, 0];
+            return { rotation: [rx, ry, rz + delta] };
+        },
+        placement: {
+            position: (n) => {
+                const [w] = getScaledDimensions(n);
+                return [w / 2 + WALL_SIDE_OFFSET, 0, WALL_GIZMO_LIFT];
+            },
+        },
+    };
+}
+// Move cross past the item's left edge on the wall face. Tap to hand the item
+// to its placement coordinator (`engageMove`) — same feedback as the floating
+// move button, and the coordinator handles the wall ↔ floor ↔ ceiling
+// transitions the generic translate drag couldn't. `plane: 'node-normal'`
+// stands the cross up against the wall face.
+function itemWallMoveHandle() {
+    return {
+        kind: 'tap-action',
+        shape: 'move-cross',
+        plane: 'node-normal',
+        portal: 'grandparent',
+        cursor: 'move',
+        onActivate: (node, _scene, editor) => editor.engageMoveDrag(node),
+        placement: {
+            position: (n) => {
+                const [w] = getScaledDimensions(n);
+                return [-(w / 2 + WALL_SIDE_OFFSET), 0, WALL_GIZMO_LIFT];
+            },
+        },
+    };
+}
+export const itemEditContribution = {
+    snapProfile: 'item',
+    facingIndicator: true,
+    extensions: {
+        'pascal:editor/floorplan': {
+            contextualDimensions: buildItemContextualDimensions,
+            actionMenu: { actions: () => import('../shared/item-interaction-actions.js') },
+        },
+    },
+    capabilities: {
+        paint: itemPaint,
+    },
+    parametrics: itemParametrics,
+    // In-world rotate + move gizmos for selected items.
+    //  - Floor items: world-Y rotate + free floor-plane move cross.
+    //  - Wall items: wall-normal rotate (spin flat against the wall) + a move
+    //    cross constrained to the wall face. Both ride the wall frame.
+    //  - Ceiling items: no gizmos yet (move via the move tool).
+    handles: (node) => {
+        const attachTo = node.asset.attachTo;
+        if (attachTo === 'wall' || attachTo === 'wall-side') {
+            return [itemWallRotateHandle(), itemWallMoveHandle()];
+        }
+        if (attachTo)
+            return [];
+        return [itemRotateHandle(), itemMoveHandle()];
+    },
+    preview: () => import('./renderer.js').then(({ ItemPreview }) => ({ default: ItemPreview })),
+    // Catalog placement tool — mounted when `useEditor.tool === 'item'`.
+    // Wraps the same placement coordinator the move-tool uses (surface
+    // strategies for floor / wall / ceiling / item-surface). Replaces
+    // the legacy `editor/src/components/tools/item/item-tool.tsx`.
+    tool: () => import('./tool.js'),
+    // Stage D — 3D move-tool (registry-driven). Adopts the moving node
+    // and runs the placement coordinator with surface strategies for
+    // floor / wall / ceiling / item-surface, including attachTo
+    // *transitions* (drop a wall item on a ceiling and have it switch).
+    // Replaces the legacy `MoveItemContent` in editor's dispatcher; the
+    // `getRegistryAffordanceTool('item', 'move')` lookup picks this up.
+    affordanceTools: {
+        move: () => import('./move-tool.js'),
+    },
+    // Stage C: floor-plan polygon. ctx.resolve walks the parent chain
+    // (wall / nested item / level) to compute the world-space transform.
+    floorplan: buildItemFloorplan,
+    floorplanAffectedIds: (args) => {
+        const ids = [...restingFloorplanAffectedIds(args)];
+        for (const node of [args.node, getEffectiveCutterNode(args.node)]) {
+            if (node.type !== 'item')
+                continue;
+            for (const cutter of node.source?.manifest.cutters ?? []) {
+                const host = resolveCutterHost(node, cutter.host === 'mounted' ? 'cutout' : `cut:${cutter.host}`, args.nodes);
+                if (host)
+                    ids.push(host.id);
+            }
+        }
+        return ids;
+    },
+    // 2D move-on-floorplan handler. Branches on `asset.attachTo`:
+    // wall items snap to walls (like door / window), ceiling items
+    // snap to ceiling polygons, floor items snap to slabs. attachTo
+    // *transitions* (drop a wall item on a ceiling) remain canonical
+    // in the 3D path; 2D only re-anchors within the same family.
+    floorplanMoveTarget: itemFloorplanMoveTarget,
+    placementNotice: itemPlacementNotice,
+    keyboardActions: {
+        e: {
+            appliesTo: (node) => itemMechanism.has(node) || itemHasLights(node),
+            // Same as the action bar: mechanisms when the item has them, otherwise its light.
+            run: (node) => itemMechanism.has(node) ? toggleMechanism(itemMechanism, node) : toggleItemLights(node),
+        },
+    },
+    toolHints: [
+        { key: 'Left click', label: 'Place item' },
+        { key: 'R / T', label: 'Rotate' },
+        { key: 'Shift', label: 'Cycle snapping mode' },
+        { key: 'Alt', label: 'Force place' },
+        { key: 'Esc', label: 'Cancel' },
+    ],
+};