@pascal-app/nodes 0.1.1

package/dist/item/definition.js

@@ -0,0 +1,309 @@
+import { getScaledDimensions, } from '@pascal-app/core';
+import { buildItemFloorplan } from './floorplan';
+import { itemFloorplanMoveTarget } from './floorplan-move';
+import { itemPaint } from './paint';
+import { itemParametrics } from './parametrics';
+import { ItemNode } from './schema';
+// 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];
+            },
+        },
+    };
+}
+/**
+ * Item — Phase 5 batch kind. Catalog-backed, GLB-rendered, multi-host.
+ *
+ * Demonstrates the **custom `def.renderer` escape hatch** (see
+ * plans/editor-node-registry.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 const itemDefinition = {
+    kind: 'item',
+    snapProfile: 'item',
+    facingIndicator: true,
+    schemaVersion: 1,
+    schema: ItemNode,
+    category: 'furnish',
+    surfaceRole: 'furnishing',
+    // Defaults shape is cast: the schema requires a fully-typed `asset`
+    // field, but in practice items are always created from the catalog
+    // (the asset is supplied at placement time). `createNode` re-parses
+    // through the schema, so any missing zod defaults fill at runtime.
+    defaults: () => ({
+        object: 'node',
+        parentId: null,
+        visible: true,
+        metadata: {},
+        children: [],
+        position: [0, 0, 0],
+        rotation: [0, 0, 0],
+        scale: [1, 1, 1],
+        asset: {
+            id: 'placeholder',
+            category: 'misc',
+            name: 'Item',
+            thumbnail: '',
+            src: 'asset:placeholder',
+            dimensions: [1, 1, 1],
+            source: 'library',
+        },
+    }),
+    capabilities: {
+        selectable: { hitVolume: 'bbox' },
+        duplicable: true,
+        deletable: true,
+        paint: itemPaint,
+        // Items participate in compositions — e.g. "table-with-plants",
+        // "shelf-with-books-on-top" — so they're presettable in their own
+        // right (and as descendants of presettable parents). The GLB-kind
+        // catalog still exists alongside; preset-flavoured items become
+        // siblings of GLB items inside the unified `items` table.
+        //
+        // Items can be hosted on walls (assets with `attachTo: 'wall'`)
+        // via `wallId` + `wallT`, or on a roof-segment wall face via
+        // `roofSegmentId`. When a composition that includes a wall-hosted
+        // item is saved as a preset (a sconce, a hanging shelf, etc.), the
+        // host app strips these via `getHostRefFields(def)` so the
+        // descendant re-attaches against the new host geometry at
+        // placement time.
+        hostRefFields: ['wallId', 'wallT', 'roofSegmentId', 'roofFace'],
+        // Floor items get lifted by slabs underneath via the generic
+        // `<FloorElevationSystem>`. Wall- / ceiling-attached items live in
+        // their parent's local frame and skip the lift via `applies`.
+        floorPlaced: {
+            footprint: (node) => {
+                const item = node;
+                return { dimensions: getScaledDimensions(item), rotation: item.rotation };
+            },
+            applies: (node) => !node.asset.attachTo,
+            collides: true,
+        },
+        // Recessed ceiling fixtures cut a hole in their host ceiling. The viewer's
+        // CeilingSystem queries this capability on each child of a ceiling so it
+        // never needs to branch on `node.type`.
+        ceilingCut: {
+            buildCeilingHole(rawNode) {
+                const node = rawNode;
+                if (!node.asset.recessed || node.asset.attachTo !== 'ceiling')
+                    return null;
+                // Inset slightly so the fixture's trim (widest part, sitting in the
+                // ceiling plane) overlaps the solid ceiling around the opening and hides
+                // the cut edge. Same constant the old ceiling-system used.
+                const INSET = 0.82;
+                const [width, , depth] = getScaledDimensions(node);
+                const halfW = (width / 2) * INSET;
+                const halfD = (depth / 2) * INSET;
+                const cx = node.position[0];
+                const cz = node.position[2];
+                const yaw = node.rotation?.[1] ?? 0;
+                const cos = Math.cos(yaw);
+                const sin = Math.sin(yaw);
+                // Rotate the (inset) footprint corners about Y and translate to the
+                // item's plan position. Y-rotation of (dx, dz): (dx·cos + dz·sin, −dx·sin + dz·cos).
+                return [
+                    [-halfW, -halfD],
+                    [halfW, -halfD],
+                    [halfW, halfD],
+                    [-halfW, halfD],
+                ].map(([dx, dz]) => [cx + dx * cos + dz * sin, cz - dx * sin + dz * cos]);
+            },
+        },
+    },
+    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()];
+    },
+    renderer: {
+        kind: 'parametric',
+        module: () => import('./renderer'),
+    },
+    system: {
+        module: () => import('./system'),
+        // Same priority as the legacy ItemSystem.
+        priority: 2,
+    },
+    // 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'),
+    // 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'),
+    },
+    // Stage C: floor-plan polygon. ctx.resolve walks the parent chain
+    // (wall / nested item / level) to compute the world-space transform.
+    floorplan: buildItemFloorplan,
+    // 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,
+    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' },
+    ],
+    presentation: {
+        label: 'Item',
+        description: 'A catalog-backed item (furniture, fixtures, decorations).',
+        icon: { kind: 'url', src: '/icons/item.webp' },
+        paletteSection: 'furnish',
+        paletteOrder: 10,
+    },
+    mcp: {
+        description: 'A catalog-backed item with asset reference, transforms, and optional attachTo for wall/ceiling mounting.',
+    },
+};

package/dist/item/floorplan-move.d.ts

@@ -0,0 +1,3 @@
+import { type FloorplanMoveTarget, type ItemNode } from '@pascal-app/core';
+export declare const itemFloorplanMoveTarget: FloorplanMoveTarget<ItemNode>;
+//# sourceMappingURL=floorplan-move.d.ts.map

package/dist/item/floorplan-move.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"floorplan-move.d.ts","sourceRoot":"","sources":["../../src/item/floorplan-move.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,mBAAmB,EAIxB,KAAK,QAAQ,EAKd,MAAM,kBAAkB,CAAA;AAkJzB,eAAO,MAAM,uBAAuB,EAAE,mBAAmB,CAAC,QAAQ,CA+BjE,CAAA"}

package/dist/item/floorplan-move.js

@@ -0,0 +1,307 @@
+import { collectAlignmentAnchors, getRoofWallFaceFrame, getScaledDimensions, movingFootprintAnchors, roofFacePointToSegment, useScene, } from '@pascal-app/core';
+import { applyFloorplanAlignment, isGridSnapActive, isMagneticSnapActive, useEditor, } from '@pascal-app/editor';
+import { createFloorplanCursorResolver } from '../shared/floorplan-cursor';
+import { findClosestWallInPlan, snapLocalXToNeighbors } from '../shared/wall-attach-target';
+function rotateVec(x, z, rotationY) {
+    const c = Math.cos(rotationY);
+    const s = Math.sin(rotationY);
+    return [x * c + z * s, -x * s + z * c];
+}
+function resolveItemPlanTransform(item, nodes, cache = new Map()) {
+    const cached = cache.get(item.id);
+    if (cached)
+        return cached;
+    const localRotation = item.rotation[1] ?? 0;
+    let result = {
+        point: [item.position[0], item.position[2]],
+        rotation: localRotation,
+    };
+    const parent = item.parentId ? nodes[item.parentId] : null;
+    if (parent?.type === 'wall') {
+        const wallRotation = -Math.atan2(parent.end[1] - parent.start[1], parent.end[0] - parent.start[0]);
+        const wallLocalZ = item.asset.attachTo === 'wall-side'
+            ? ((parent.thickness ?? 0.1) / 2) * (item.side === 'front' ? 1 : -1)
+            : item.position[2];
+        const [offsetX, offsetZ] = rotateVec(item.position[0], wallLocalZ, wallRotation);
+        result = {
+            point: [parent.start[0] + offsetX, parent.start[1] + offsetZ],
+            rotation: wallRotation + localRotation,
+        };
+    }
+    else if (parent?.type === 'shelf') {
+        const shelf = parent;
+        const [offsetX, offsetZ] = rotateVec(item.position[0], item.position[2], shelf.rotation[1] ?? 0);
+        result = {
+            point: [shelf.position[0] + offsetX, shelf.position[2] + offsetZ],
+            rotation: (shelf.rotation[1] ?? 0) + localRotation,
+        };
+    }
+    else if (parent?.type === 'item') {
+        const parentTransform = resolveItemPlanTransform(parent, nodes, cache);
+        const [offsetX, offsetZ] = rotateVec(item.position[0], item.position[2], parentTransform.rotation);
+        result = {
+            point: [parentTransform.point[0] + offsetX, parentTransform.point[1] + offsetZ],
+            rotation: parentTransform.rotation + localRotation,
+        };
+    }
+    else if (parent?.type === 'roof-segment') {
+        // Roof-hosted wall item: FACE-LOCAL position mapped through the face
+        // frame, then composed through the segment's and roof's yaw +
+        // position into level-local plan coords — without this the drag seed
+        // jumps off the roof at move start.
+        const segment = parent;
+        const roof = segment.parentId
+            ? nodes[segment.parentId]
+            : undefined;
+        if (roof?.type === 'roof' && item.roofFace) {
+            const frame = getRoofWallFaceFrame(segment, item.roofFace);
+            const segLocal = roofFacePointToSegment(segment, item.roofFace, item.position);
+            const [sx, sz] = rotateVec(segLocal[0], segLocal[2], segment.rotation ?? 0);
+            const [rx, rz] = rotateVec(sx + segment.position[0], sz + segment.position[2], roof.rotation ?? 0);
+            result = {
+                point: [rx + roof.position[0], rz + roof.position[2]],
+                rotation: (roof.rotation ?? 0) + (segment.rotation ?? 0) + frame.yaw + localRotation,
+            };
+        }
+    }
+    cache.set(item.id, result);
+    return result;
+}
+function resolveItemPlanPoint(item, nodes, cache = new Map()) {
+    return resolveItemPlanTransform(item, nodes, cache).point;
+}
+function createPlanarMovePointResolver(originalPlanPoint, node) {
+    const resolveCursor = createFloorplanCursorResolver({
+        original: originalPlanPoint,
+        metadata: node.metadata,
+    });
+    return (planPoint) => {
+        // Grid snap is mode-driven (matching 3D): quantize only when grid mode is
+        // active; in lines/off mode the cursor passes through unsnapped.
+        const step = isGridSnapActive() ? useEditor.getState().gridSnapStep : 0;
+        const snap = (value) => (step <= 0 ? value : Math.round(value / step) * step);
+        return resolveCursor(planPoint, { snap });
+    };
+}
+export const itemFloorplanMoveTarget = ({ node, nodes }) => {
+    const attachTo = node.asset.attachTo;
+    const startLevelId = (() => {
+        // Walk to the owning level depending on the item's current parent:
+        //   - wall / ceiling parent → parent.parentId is the level
+        //   - level parent (floor items) → parent.id IS the level
+        //   - item / shelf parent → walk up until we hit a level
+        // Without the `parent.type === 'level'` short-circuit, floor items
+        // (whose immediate parent is the level itself) get `level.parentId`,
+        // which is the *building* — `findContainingSurface` would then
+        // iterate the building's children (levels, not slabs) and the
+        // fallback `parentId: startLevelId` would reparent the item to the
+        // building. The item drops out of the level→children DFS the floor
+        // plan walks and disappears mid-drag.
+        const nodes = useScene.getState().nodes;
+        let current = nodes[node.parentId];
+        while (current) {
+            if (current.type === 'level')
+                return current.id;
+            if (!current.parentId)
+                return null;
+            current = nodes[current.parentId];
+        }
+        return null;
+    })();
+    if (attachTo === 'wall' || attachTo === 'wall-side') {
+        return buildWallItemSession(node, startLevelId);
+    }
+    if (attachTo === 'ceiling') {
+        return buildSurfaceItemSession(node, startLevelId, 'ceiling');
+    }
+    return buildFloorItemSession(node, startLevelId, nodes);
+};
+function buildWallItemSession(node, startLevelId) {
+    // Wall items use the same local-X snap pipeline as doors / windows.
+    // local-Y carries over from the source item's position (2D can't
+    // express vertical movement).
+    const startLocalY = node.position[1];
+    const resolveCursor = createFloorplanCursorResolver({
+        original: resolveItemPlanPoint(node, useScene.getState().nodes),
+        metadata: node.metadata,
+    });
+    return {
+        affectedIds: [node.id],
+        apply({ planPoint }) {
+            const nodes = useScene.getState().nodes;
+            const resolvedPlanPoint = resolveCursor(planPoint);
+            const hit = findClosestWallInPlan(resolvedPlanPoint, nodes, startLevelId);
+            if (!hit)
+                return;
+            const [width] = getScaledDimensions(node);
+            // Figma-style along-wall alignment (edge-to-edge with other openings /
+            // wall items / wall ends), winning over the grid snap; falls back to grid
+            // when nothing aligns. Both are mode-driven (matching 3D): alignment only in
+            // lines/magnetic mode, grid quantization only in grid mode.
+            const neighborX = isMagneticSnapActive()
+                ? snapLocalXToNeighbors({
+                    wall: hit.wall,
+                    localX: hit.localX,
+                    width,
+                    selfId: node.id,
+                    nodes,
+                })
+                : null;
+            const step = isGridSnapActive() ? useEditor.getState().gridSnapStep : 0;
+            const snappedLocalX = neighborX ?? (step <= 0 ? hit.localX : Math.round(hit.localX / step) * step);
+            const halfW = width / 2;
+            const clampedX = Math.max(halfW, Math.min(hit.wallLength - halfW, snappedLocalX));
+            useScene.getState().updateNodes([
+                {
+                    id: node.id,
+                    data: {
+                        position: [clampedX, startLocalY, 0],
+                        rotation: [0, hit.itemRotation, 0],
+                        side: hit.side,
+                        parentId: hit.wall.id,
+                        // Re-anchoring to a wall ends any roof-segment hosting; the
+                        // overlay's snapshot restores it if the move is reverted.
+                        roofSegmentId: undefined,
+                        roofFace: undefined,
+                    },
+                },
+            ]);
+        },
+        canCommit() {
+            const live = useScene.getState().nodes[node.id];
+            return !!live && live.type === 'item' && !!live.parentId;
+        },
+    };
+}
+/**
+ * Floor items live as level children — the slab is *not* a parent (slabs
+ * have no `children` field; only ceilings and the level itself do).
+ * Reparenting a floor item to a slab corrupts the parent-children
+ * bookkeeping and the item drops out of the level→children DFS the
+ * floor-plan layer walks → the polygon stops rendering mid-drag.
+ *
+ * For the 2D move we just translate `position` in level-local coords and
+ * leave the parent as the level (matching the 3D `detachItemSurfaceToFloor`
+ * in `use-placement-coordinator.tsx`). Snap to the 0.5m grid unless the
+ * user holds Shift.
+ */
+function buildFloorItemSession(node, startLevelId, nodes) {
+    const rotationY = node.rotation[1] ?? 0;
+    const resolvePlanPoint = createPlanarMovePointResolver(resolveItemPlanPoint(node, nodes), node);
+    // Alignment candidates gathered once — scene is stable during the drag.
+    const candidates = collectAlignmentAnchors(nodes, node.id);
+    return {
+        affectedIds: [node.id],
+        apply({ planPoint }) {
+            const gridSnapped = resolvePlanPoint(planPoint);
+            // Figma-style alignment layered on the grid snap, mode-driven (matching 3D):
+            // guides are DISPLAYED in every snapping mode; the magnetic pull onto them
+            // is applied only in "lines" mode (`applySnap`).
+            const { point: snapped } = applyFloorplanAlignment(gridSnapped, movingFootprintAnchors(node, gridSnapped[0], gridSnapped[1], rotationY), candidates, { applySnap: isMagneticSnapActive() });
+            const sourceY = node.position[1];
+            const nextPosition = [snapped[0], sourceY, snapped[1]];
+            useScene.getState().updateNodes([
+                {
+                    id: node.id,
+                    data: {
+                        position: nextPosition,
+                        // Keep parent as the level we resolved at session-start. If
+                        // somehow it's null (e.g. orphaned item), fall back to the
+                        // existing parent so we don't write `null` and detach.
+                        parentId: startLevelId ?? node.parentId,
+                    },
+                },
+            ]);
+        },
+        canCommit() {
+            const live = useScene.getState().nodes[node.id];
+            return !!live && live.type === 'item';
+        },
+    };
+}
+/**
+ * Ceiling items reparent to whichever ceiling polygon contains the
+ * pointer. Ceilings carry a `children` field on their schema so the
+ * parent-children bookkeeping in `updateNodes` works correctly when the
+ * item moves between ceilings. If the cursor drifts off every ceiling,
+ * the original parent is preserved (no detach back to the level — there
+ * is no canonical "free-floating ceiling item").
+ */
+function buildSurfaceItemSession(node, startLevelId, targetKind) {
+    const resolvePlanPoint = createPlanarMovePointResolver(resolveItemPlanPoint(node, useScene.getState().nodes), node);
+    return {
+        affectedIds: [node.id],
+        apply({ planPoint }) {
+            const nodes = useScene.getState().nodes;
+            const snapped = resolvePlanPoint(planPoint);
+            const surface = findContainingSurface(snapped, nodes, startLevelId, targetKind);
+            const sourceY = node.position[1];
+            const nextPosition = [snapped[0], sourceY, snapped[1]];
+            useScene.getState().updateNodes([
+                {
+                    id: node.id,
+                    data: {
+                        position: nextPosition,
+                        parentId: surface ? surface.id : node.parentId,
+                    },
+                },
+            ]);
+        },
+        canCommit() {
+            const live = useScene.getState().nodes[node.id];
+            return !!live && live.type === 'item';
+        },
+    };
+}
+/**
+ * Walk every ceiling under the level and return the first one whose
+ * polygon contains the pointer. Holes are honoured — a point inside a
+ * hole counts as not inside the surface. Slabs are intentionally NOT a
+ * valid target: floor items are parented to the level, not the slab,
+ * because slabs don't carry a `children` field on their schema.
+ */
+function findContainingSurface(point, nodes, parentLevelId, targetKind) {
+    if (!parentLevelId)
+        return null;
+    const level = nodes[parentLevelId];
+    const childIds = level?.children;
+    if (!Array.isArray(childIds))
+        return null;
+    for (const childId of childIds) {
+        const node = nodes[childId];
+        if (!node || node.type !== targetKind)
+            continue;
+        const surface = node;
+        const polygon = surface.polygon;
+        if (!polygon || polygon.length < 3)
+            continue;
+        if (!pointInRing(point, polygon))
+            continue;
+        const holes = surface.holes ?? [];
+        let inHole = false;
+        for (const hole of holes) {
+            if (hole.length >= 3 && pointInRing(point, hole)) {
+                inHole = true;
+                break;
+            }
+        }
+        if (!inHole)
+            return surface;
+    }
+    return null;
+}
+/** Standard ray-cast point-in-polygon. Treats edges as inside. */
+function pointInRing(point, ring) {
+    let inside = false;
+    const [px, py] = point;
+    for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+        const ax = ring[i][0];
+        const ay = ring[i][1];
+        const bx = ring[j][0];
+        const by = ring[j][1];
+        const intersects = ay > py !== by > py && px < ((bx - ax) * (py - ay)) / (by - ay) + ax;
+        if (intersects)
+            inside = !inside;
+    }
+    return inside;
+}

package/dist/item/floorplan.d.ts

@@ -0,0 +1,3 @@
+import { type FloorplanGeometry, type GeometryContext, type ItemNode } from '@pascal-app/core';
+export declare function buildItemFloorplan(node: ItemNode, ctx: GeometryContext): FloorplanGeometry | null;
+//# sourceMappingURL=floorplan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"floorplan.d.ts","sourceRoot":"","sources":["../../src/item/floorplan.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EAEtB,KAAK,eAAe,EAGpB,KAAK,QAAQ,EAId,MAAM,kBAAkB,CAAA;AA+IzB,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,eAAe,GAAG,iBAAiB,GAAG,IAAI,CAmGjG"}