@pascal-app/editor 1.0.0 → 1.0.3

package/src/components/tools/item/use-placement-coordinator.tsx

@@ -4,6 +4,7 @@ import {
   type AnyNode,
   type AnyNodeId,
   type CeilingEvent,
+  canHostSurfaceChild,
   collectAlignmentAnchors,
   emitter,
   findLevelAncestorId,
@@ -17,6 +18,7 @@ import {
   resolveFrozenFloorPlacementPatch,
   resolveLevelId,
   type ShelfEvent,
+  type SurfaceRejectReason,
   sceneRegistry,
   useLiveNodeOverrides,
   useLiveTransforms,
@@ -30,16 +32,13 @@ import { Html } from '@react-three/drei'
 import { useFrame, useThree } from '@react-three/fiber'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import {
-  Box3,
   Euler,
   type Group,
   type LineSegments,
-  Matrix4,
   type Mesh,
   type Object3D,
   PlaneGeometry,
   Quaternion,
-  Ray,
   Vector3,
 } from 'three'
 import { distance, smoothstep, uv, vec2 } from 'three/tsl'
@@ -50,17 +49,30 @@ import {
 } from '../../../lib/active-placement-surface'
 import { EDITOR_LAYER } from '../../../lib/constants'
 import { formatLinearMeasurement } from '../../../lib/measurements'
+import { isFreshPlacementMetadata } from '../../../lib/placement-metadata'
+import { createMovementSfxTick } from '../../../lib/sfx/movement-tick'
 import { sfxEmitter } from '../../../lib/sfx-bus'
-
+import {
+  surfaceAttachmentId,
+  surfaceFramePose,
+  updateSurfaceNode,
+} from '../../../lib/surface-attachment'
 import {
   projectAlignmentGuidesWorldToActiveBuildingLocal,
   resolveAlignmentForActiveBuilding,
 } from '../../../lib/world-grid-snap'
 import useAlignmentGuides from '../../../store/use-alignment-guides'
-import useEditor, { isAlignmentGuideActive, isMagneticSnapActive } from '../../../store/use-editor'
-
+import useEditor, {
+  isAlignmentGuideActive,
+  isGridSnapActive,
+  isMagneticSnapActive,
+} from '../../../store/use-editor'
 import useFacingPose from '../../../store/use-facing-pose'
 import usePlacementPreview from '../../../store/use-placement-preview'
+import {
+  createItemSurfaceGridDispatch,
+  createItemSurfacePointerArbitration,
+} from '../registry/item-surface-move'
 import { getFloorStackPreviewPosition } from '../shared/floor-stack-preview'
 import {
   createLineGeometry,
@@ -70,9 +82,13 @@ import {
 } from '../shared/placement-box-geometry'
 import {
   type PointerSupportSurface,
-  resolvePointerSupportElevation,
   resolvePointerSupportSurface,
 } from '../shared/pointer-support-cap'
+import { createShelfStickiness } from '../shared/shelf-stickiness'
+import {
+  createSurfaceEventOwnership,
+  createSurfaceRejectionFeedback,
+} from '../shared/surface-rejection'
 import { shouldCreateFloorDraft } from './draft-creation'
 import { commitFaceHostClick, resolveFaceHostPreviewCommit } from './face-host-commit'
 import {
@@ -547,10 +563,15 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       }
     }
 
+    let lastSurfaceEvent: NodeEvent<AnyNode> | null = null
+    const feedback = createSurfaceRejectionFeedback()
+    feedback.clear()
+
     // ---- Helpers ----
 
     const getContext = () => ({
       asset,
+      onSurfaceReject: (reason: SurfaceRejectReason) => feedback.reject(reason),
       levelId: useViewer.getState().selection.levelId,
       draftItem: draftNode.current,
       gridPosition: gridPosition.current,
@@ -580,6 +601,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       wasAdopted: boolean,
       repeat: () => void,
     ) => {
+      if (!committedId) return
       if (configRef.current.onCommitted()) {
         repeat()
         return
@@ -609,12 +631,19 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     ) => {
       const draftId = draftNode.current?.id ?? null
       const wasAdopted = draftNode.isAdopted
-      const finalId = draftNode.commit(nodeUpdate, options)
-      if (draftId) {
+      const finalId = draftNode.commit(nodeUpdate, {
+        ...options,
+        onReject: (reason) => {
+          feedback.reject(reason)
+          edgeMaterial.color.setHex(0xef_44_44)
+          basePlaneMaterial.color.setHex(0xef_44_44)
+        },
+      })
+      if (finalId && draftId) {
         useLiveTransforms.getState().clear(draftId)
         useLiveNodeOverrides.getState().clearFields(draftId, faceHostClearFields(draftNode.current))
       }
-      return { committedId: finalId ?? draftId, wasAdopted }
+      return { committedId: finalId, wasAdopted }
     }
 
     const faceHostClearFields = (draft: ItemNode | null | undefined): Array<keyof ItemNode> => {
@@ -633,14 +662,74 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         : null
     }
 
+    const surfacePointer = createItemSurfacePointerArbitration()
+    const surfaceOwnership = createSurfaceEventOwnership()
     const revalidate = (): boolean => {
-      const placeable = altFreeRef.current || checkCanPlace(getContext(), validators)
+      const fits = checkCanPlace(getContext(), validators)
+      if (
+        !fits &&
+        lastSurfaceEvent &&
+        (feedback.reason === 'footprint-outside-surface' ||
+          feedback.reason === 'footprint-exceeds-host' ||
+          feedback.reason === 'no-surface') &&
+        (placementState.current.surface === 'item-surface' ||
+          placementState.current.surface === 'shelf-surface')
+      ) {
+        const hostId =
+          placementState.current.surface === 'shelf-surface'
+            ? placementState.current.shelfId
+            : placementState.current.surfaceItemId
+        const mesh = hostId ? sceneRegistry.nodes.get(hostId) : undefined
+        if (mesh) {
+          const position = mesh.localToWorld(gridPosition.current.clone()).toArray()
+          feedback.clear()
+          detachItemSurfaceToFloor({ ...lastSurfaceEvent, position } as ItemEvent)
+          return revalidate()
+        }
+      }
+      const placeable = !feedback.reason && (altFreeRef.current || fits)
       const color = placeable ? 0x22_c5_5e : 0xef_44_44 // green-500 : red-500
       edgeMaterial.color.setHex(color)
       basePlaneMaterial.color.setHex(color)
       return placeable
     }
 
+    const surfaceContext = (event: NodeEvent<AnyNode>, generic = false) => {
+      lastSurfaceEvent = event
+      return {
+        ...getContext(),
+        onSurfaceReject: (reason: SurfaceRejectReason) => {
+          // A rejected generic acquisition leaves the paired pointer's floor route in charge.
+          if (
+            generic &&
+            placementState.current.surfaceItemId !== event.node.id &&
+            reason !== 'surface-cutout' &&
+            reason !== 'surface-occupied'
+          ) {
+            return
+          }
+          surfaceOwnership.claim(event.node.id, event.nativeEvent.nativeEvent ?? event.nativeEvent)
+          event.stopPropagation()
+          if (
+            (reason === 'footprint-outside-surface' ||
+              reason === 'footprint-exceeds-host' ||
+              reason === 'no-surface') &&
+            (placementState.current.surface === 'item-surface' ||
+              placementState.current.surface === 'shelf-surface')
+          ) {
+            feedback.clear()
+            detachItemSurfaceToFloor(event as ItemEvent)
+            // A generic host exit yields positioning to this pointer's paired floor event.
+            if (!generic)
+              surfacePointer.hit(event.node.id, event.nativeEvent.nativeEvent ?? event.nativeEvent)
+            return
+          }
+          feedback.reject(reason, event.nativeEvent.nativeEvent ?? event.nativeEvent)
+          revalidate()
+        },
+      }
+    }
+
     // Tool visuals are rendered inside the building-local ToolManager group, so all cursor
     // positions must be in building-local space. Wall/ceiling/item-surface strategies return
     // world-space cursor positions (from their event.position); convert them here.
@@ -671,7 +760,23 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       return [localRotation.x, localRotation.y, localRotation.z]
     }
 
-    const applyTransition = (result: TransitionResult) => {
+    const { tick: tickMovementSfx } = createMovementSfxTick()
+    const tickSurfaceMovementSfx = (position: [number, number, number]) => {
+      const point = worldToBuildingLocal(...position)
+      tickMovementSfx({
+        coords: [point.x, point.z],
+        gridSnapActive: isGridSnapActive(),
+        gridStep: useEditor.getState().gridSnapStep,
+      })
+    }
+
+    const applyTransition = (result: TransitionResult, event?: NodeEvent<AnyNode>) => {
+      if (event) {
+        surfaceOwnership.claim(event.node.id, event.nativeEvent.nativeEvent ?? event.nativeEvent)
+        surfacePointer.hit(event.node.id, event.nativeEvent.nativeEvent ?? event.nativeEvent)
+        tickSurfaceMovementSfx(result.cursorPosition)
+      }
+      feedback.clear()
       // Alignment guides are floor-only; clear them when the cursor moves
       // onto a wall / ceiling / item surface (only those paths call this).
       useAlignmentGuides.getState().clear()
@@ -734,7 +839,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (draft) {
         Object.assign(draft, result.nodeUpdate)
         // One-time setup: put node in the right parent so it renders correctly
-        useScene.getState().updateNode(draft.id, result.nodeUpdate)
+        if (result.surfaceId !== undefined)
+          draftNode.updateSurface(result.nodeUpdate, result.surfaceId)
+        else updateSurfaceNode(draft.id, result.nodeUpdate)
         disableDraftRaycastNow()
       }
 
@@ -753,6 +860,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     // ---- Init draft ----
     configRef.current.initDraft(gridPosition.current)
+    if (draftNode.current && surfaceAttachmentId(draftNode.current))
+      gridPosition.current.set(...draftNode.current.position)
     const preserveDragOffset = configRef.current.preserveDragOffset === true
     // The host the item was grabbed from + its pre-drag host-local position.
     // Each surface's grab anchor preserves the grab offset only on THAT host,
@@ -939,6 +1048,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       setTimeout(() => window.removeEventListener('click', swallow, { capture: true }), 300)
     }
     const onReleaseCommit = () => {
+      gridDispatch.flush()
       if (!releaseCommit) return
       const commit = releaseCommit
       releaseCommit = null
@@ -948,53 +1058,10 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     // ---- Floor Handlers ----
 
-    let previousGridPos: [number, number, number] | null = null
-
-    // Scratch objects reused by the stickiness test (runs per grid:move).
-    const stickyRay = new Ray()
-    const stickyBox = new Box3()
-    const stickyMat = new Matrix4()
-    const stickyCamPos = new Vector3()
-
-    // True while the cursor ray still points at the active shelf's volume.
-    // Used to keep an item hosted on a shelf "sticky": from an angled camera
-    // the cursor ray slips off the shelf's thin boards / through its gaps and
-    // lands on the floor *behind* the shelf, which would otherwise thrash the
-    // placement between the shelf row and the floor on every micro-move. We
-    // reconstruct the world ray (camera → grid hit point) and test it against
-    // the shelf's bounding box — so a ray that passes *through* the shelf but
-    // lands behind it still counts as "on the shelf". Only a ray that misses
-    // the shelf box entirely means the user genuinely moved off it. A simple
-    // footprint test on the floor hit point can't distinguish those.
-    const cursorRayIntersectsActiveShelf = (gridWorldPoint: [number, number, number]): boolean => {
-      const shelfId = placementState.current.shelfId
-      if (!shelfId) return false
-      const shelfMesh = sceneRegistry.nodes.get(shelfId as AnyNodeId)
-      const shelfNode = useScene.getState().nodes[shelfId as AnyNodeId] as
-        | { width?: number; depth?: number; height?: number }
-        | undefined
-      if (!(shelfMesh && shelfNode?.width && shelfNode?.depth && shelfNode?.height)) return false
-
-      cameraRef.current.getWorldPosition(stickyCamPos)
-      stickyRay.origin.copy(stickyCamPos)
-      stickyRay.direction
-        .set(
-          gridWorldPoint[0] - stickyCamPos.x,
-          gridWorldPoint[1] - stickyCamPos.y,
-          gridWorldPoint[2] - stickyCamPos.z,
-        )
-        .normalize()
-
-      // Into shelf-local space, then test the shelf's local AABB (origin at the
-      // base: y ∈ [0, height]) with a small margin.
-      stickyRay.applyMatrix4(stickyMat.copy(shelfMesh.matrixWorld).invert())
-      const m = 0.08
-      stickyBox.min.set(-shelfNode.width / 2 - m, -m, -shelfNode.depth / 2 - m)
-      stickyBox.max.set(shelfNode.width / 2 + m, shelfNode.height + m, shelfNode.depth / 2 + m)
-      return stickyRay.intersectsBox(stickyBox)
-    }
+    const cursorRayIntersectsShelf = createShelfStickiness()
 
     const onGridMove = (event: GridEvent) => {
+      if (surfacePointer.blocksGrid(event.nativeEvent.nativeEvent ?? event.nativeEvent)) return
       releaseCommit = () => onGridClick(event)
       // Lazy draft creation: if no draft yet (e.g. level wasn't ready during init), create now
       if (
@@ -1014,7 +1081,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       // perspective-skewed along the ray whenever the plane sits on a
       // different storey than the pointed surface (the skew is what made
       // a drag over a deck-above-a-floor hop between the two surfaces).
-      const pointed = resolvePointerSupportSurface(cameraRef.current, event.position)
+      const pointed = resolvePointerSupportSurface(cameraRef.current, event.position, {
+        pointerRay: event.nativeEvent.ray,
+      })
       pointerSupportCapRef.current = pointed?.elevation ?? null
       pointerSupportSurfaceRef.current = pointed
       const surfaceEvent: GridEvent =
@@ -1027,13 +1096,34 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       // off a board / through a gap and hit the floor behind). Detach to the
       // floor only once the ray misses the shelf entirely — without this the
       // item oscillates between the shelf row and the floor on every micro-move.
+      const counterId =
+        placementState.current.surface === 'item-surface'
+          ? placementState.current.surfaceItemId
+          : null
+      if (counterId && useScene.getState().nodes[counterId as AnyNodeId]?.type === 'cabinet') {
+        if (
+          surfacePointer.blocksGrid(event.nativeEvent.nativeEvent ?? event.nativeEvent) ||
+          cursorRayIntersectsShelf(counterId, cameraRef.current, event.position)
+        )
+          return
+        detachItemSurfaceToFloor(surfaceEvent as unknown as ItemEvent)
+      }
       if (placementState.current.surface === 'shelf-surface') {
-        if (cursorRayIntersectsActiveShelf(event.position)) return
+        if (
+          cursorRayIntersectsShelf(
+            placementState.current.shelfId,
+            cameraRef.current,
+            event.position,
+          )
+        )
+          return
         // Land at the pointed surface's plan point — the raw grid hit is
         // still skewed by the plane riding at the shelf-surface height.
         detachItemSurfaceToFloor(surfaceEvent as unknown as ItemEvent)
       }
 
+      if (placementState.current.surface === 'floor')
+        feedback.grid(event.nativeEvent.nativeEvent ?? event.nativeEvent)
       const floorEvent = applyFloorGrabOffset(surfaceEvent)
 
       lastRawPos.current.set(
@@ -1120,15 +1210,11 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         frozenSupportSlabIdRef.current = frozenPatch.supportSlabId
       }
 
-      // Play snap sound when grid position changes
-      if (
-        previousGridPos &&
-        (gridPos[0] !== previousGridPos[0] || gridPos[2] !== previousGridPos[2])
-      ) {
-        sfxEmitter.emit('sfx:grid-snap')
-      }
-
-      previousGridPos = [...gridPos]
+      tickMovementSfx({
+        coords: [gridPos[0], gridPos[2]],
+        gridSnapActive: isGridSnapActive(),
+        gridStep: useEditor.getState().gridSnapStep,
+      })
       gridPosition.current.set(...gridPos)
       const cursorPosition = getFloorVisualPosition(gridPos)
       if (!draft && asset.attachTo) {
@@ -1161,6 +1247,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     }
 
     const onGridClick = (event: GridEvent) => {
+      gridDispatch.flush()
+      if (feedback.reason) return
       // Drop alignment guides on click — the move commits (guides done) or
       // placement re-arms (the next move republishes them).
       useAlignmentGuides.getState().clear()
@@ -1222,7 +1310,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         ensureDraft(result)
       } else if (result.nodeUpdate.parentId) {
         // Existing draft (move mode): reparent to new wall
-        useScene.getState().updateNode(draftNode.current.id, result.nodeUpdate)
+        updateSurfaceNode(draftNode.current.id, result.nodeUpdate)
         if (result.stateUpdate.wallId) {
           useScene.getState().dirtyNodes.add(result.stateUpdate.wallId as AnyNodeId)
         }
@@ -1249,7 +1337,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         event.stopPropagation()
         applyTransition(enterResult)
         if (draftNode.current && enterResult.nodeUpdate.parentId) {
-          useScene.getState().updateNode(draftNode.current.id, enterResult.nodeUpdate)
+          updateSurfaceNode(draftNode.current.id, enterResult.nodeUpdate)
           if (enterResult.stateUpdate.wallId) {
             useScene.getState().dirtyNodes.add(enterResult.stateUpdate.wallId as AnyNodeId)
           }
@@ -1446,7 +1534,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         ensureDraft(result)
       } else if (result.nodeUpdate.parentId) {
         // Existing draft (move mode): reparent to the segment
-        useScene.getState().updateNode(draftNode.current.id, result.nodeUpdate)
+        updateSurfaceNode(draftNode.current.id, result.nodeUpdate)
       }
       return true
     }
@@ -1575,7 +1663,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (!draftNode.current) {
         ensureDraft(result)
       } else if (result.nodeUpdate.parentId) {
-        useScene.getState().updateNode(draftNode.current.id, result.nodeUpdate)
+        updateSurfaceNode(draftNode.current.id, result.nodeUpdate)
         disableDraftRaycastNow()
       }
       if (draftNode.current) useLiveTransforms.getState().clear(draftNode.current.id)
@@ -1673,22 +1761,23 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         if (draft) useScene.getState().updateNode(draft.id, result.nodeUpdate)
       } else {
         draftNode.destroy()
+        gridPosition.current.set(...result.gridPosition)
         Object.assign(placementState.current, result.stateUpdate)
       }
     }
 
     // ---- Item Surface Handlers ----
 
-    const detachItemSurfaceToFloor = (event: ItemEvent) => {
+    const detachItemSurfaceToFloor = (event: NodeEvent<AnyNode>) => {
       hostSurfaceDragAnchor = null
+      surfacePointer.clear()
       // Landing back on the floor: refresh the pointer surface cap from
       // this event's world hit so the first floor position already targets
       // the aimed-at surface (not a deck above it).
-      pointerSupportCapRef.current = resolvePointerSupportElevation(cameraRef.current, [
-        event.position[0],
-        event.position[1],
-        event.position[2],
-      ])
+      pointerSupportCapRef.current =
+        resolvePointerSupportSurface(cameraRef.current, event.position, {
+          pointerRay: event.nativeEvent.ray,
+        })?.elevation ?? null
       // Coming back from a host: forget the floor grab too, so the item
       // centers under the cursor instead of restoring the pre-drag offset —
       // and landing on the floor is "anchoring elsewhere", so a later return
@@ -1753,7 +1842,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         // parent-must-be-a-level guard and the item + grid stopped following
         // slab elevations for the rest of the drag).
         if (levelId) draft.parentId = levelId
-        useScene.getState().updateNode(draft.id, {
+        updateSurfaceNode(draft.id, {
           parentId: useViewer.getState().selection.levelId as string,
           position: floorPos,
           rotation,
@@ -1763,29 +1852,42 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       revalidate()
     }
 
-    const onItemEnter = (event: ItemEvent) => {
+    const onItemEnter = (event: NodeEvent<AnyNode>, generic = false) => {
+      if (event.node.type === 'cabinet' && placementState.current.surfaceItemId === event.node.id) {
+        onItemMove(event)
+        return
+      }
+      if (event.node.type === 'cabinet') {
+        lastRawPos.current.set(...event.position)
+        surfacePointer.hit(event.node.id, event.nativeEvent.nativeEvent ?? event.nativeEvent)
+      }
       if (event.node.id === draftNode.current?.id) return
       has3DPointerDrivenMoveRef.current = true
-      const result = itemSurfaceStrategy.enter(getContext(), event)
+      const result = itemSurfaceStrategy.enter(surfaceContext(event, generic), event)
       if (!result) return
+      feedback.clear()
 
       event.stopPropagation()
-      applyTransition(result)
+      applyTransition(result, event)
 
       if (!draftNode.current) {
         ensureDraft(result)
       } else if (result.nodeUpdate.parentId) {
         // Existing draft (move mode): reparent to surface item
-        useScene.getState().updateNode(draftNode.current.id, result.nodeUpdate)
+        draftNode.updateSurface(result.nodeUpdate, result.surfaceId ?? null)
       }
     }
 
-    const onItemMove = (event: ItemEvent) => {
+    const onItemMove = (event: NodeEvent<AnyNode>, generic = false) => {
       if (event.node.id === draftNode.current?.id) return
       releaseCommit = () => onItemClick(event)
       has3DPointerDrivenMoveRef.current = true
       if (!cursorGroupRef.current) return
-      const ctx = getContext()
+      const ctx = surfaceContext(event, generic)
+      if (event.node.type === 'cabinet') {
+        lastRawPos.current.set(...event.position)
+        surfacePointer.hit(event.node.id, event.nativeEvent.nativeEvent ?? event.nativeEvent)
+      }
 
       if (ctx.state.surface !== 'item-surface') {
         // Try entering surface mode
@@ -1793,9 +1895,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         if (!enterResult) return
 
         event.stopPropagation()
-        applyTransition(enterResult)
+        applyTransition(enterResult, event)
         if (draftNode.current && enterResult.nodeUpdate.parentId) {
-          useScene.getState().updateNode(draftNode.current.id, enterResult.nodeUpdate)
+          draftNode.updateSurface(enterResult.nodeUpdate, enterResult.surfaceId ?? null)
         }
         return
       }
@@ -1806,20 +1908,22 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
           event,
         )
 
+        // An unclaimed generic mesh must let its owning ancestor receive the same hit.
+        if (generic && !enterResult) return
         event.stopPropagation()
         if (enterResult) {
-          applyTransition(enterResult)
+          applyTransition(enterResult, event)
           if (draftNode.current && enterResult.nodeUpdate.parentId) {
-            useScene.getState().updateNode(draftNode.current.id, enterResult.nodeUpdate)
+            draftNode.updateSurface(enterResult.nodeUpdate, enterResult.surfaceId ?? null)
           }
-        } else {
+        } else if (!feedback.reason) {
           detachItemSurfaceToFloor(event)
         }
         return
       }
 
       if (!draftNode.current) {
-        const enterResult = itemSurfaceStrategy.enter(getContext(), event)
+        const enterResult = itemSurfaceStrategy.enter(surfaceContext(event, generic), event)
         if (!enterResult) return
         event.stopPropagation()
         ensureDraft(enterResult)
@@ -1836,11 +1940,17 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         itemMoveEvent.position[1],
         itemMoveEvent.position[2],
       )
-      const result = itemSurfaceStrategy.move(ctx, itemMoveEvent)
-      if (!result) return
+      const result = itemSurfaceStrategy.move(ctx, itemMoveEvent, event)
+      if (!result) {
+        revalidate()
+        return
+      }
+      feedback.clear()
 
       event.stopPropagation()
 
+      surfacePointer.hit(event.node.id, event.nativeEvent.nativeEvent ?? event.nativeEvent)
+      tickSurfaceMovementSfx(result.cursorPosition)
       gridPosition.current.set(...result.gridPosition)
       const ic = worldToBuildingLocal(...result.cursorPosition)
       cursorGroupRef.current.position.set(ic.x, ic.y, ic.z)
@@ -1849,8 +1959,13 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       const draft = draftNode.current
       if (draft) {
         draft.position = result.gridPosition
+        if (event.node.type === 'procedural-item')
+          draftNode.updateSurface(result.nodeUpdate ?? {}, result.surfaceId ?? null)
         const mesh = sceneRegistry.nodes.get(draft.id)
-        if (mesh) mesh.position.set(...result.gridPosition)
+        if (mesh)
+          mesh.position.set(
+            ...surfaceFramePose(draft.parentId, surfaceAttachmentId(draft), draft, true).position,
+          )
 
         // Publish live transform for 2D floorplan
         useLiveTransforms.getState().set(draft.id, {
@@ -1862,7 +1977,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       revalidate()
     }
 
-    const onItemLeave = (event: ItemEvent) => {
+    const onItemLeave = (event: NodeEvent<AnyNode>) => {
+      if (event.node.type === 'cabinet') return
       if (event.node.id === draftNode.current?.id) return
       if (placementState.current.surface !== 'item-surface') return
 
@@ -1876,7 +1992,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       detachItemSurfaceToFloor(event)
     }
 
-    const onItemClick = (event: ItemEvent) => {
+    const onItemClick = (event: NodeEvent<AnyNode>) => {
+      gridDispatch.flush()
+      if (feedback.reason) return
       // Click on the draft item itself. R3F dispatches click events to
       // the closest intersected mesh only — when the draft is hovering
       // on a host (shelf / table / etc.) the draft's mesh is *above*
@@ -1885,7 +2003,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       // self-click as a commit on the active shelf so the user doesn't
       // have to aim around the cursor preview to drop the item.
       if (event.node.id === draftNode.current?.id) {
-        const ctx = getContext()
+        const ctx = surfaceContext(event)
         if (ctx.state.surface === 'block-face') {
           const result = resolveFaceHostPreviewCommit(ctx)
           if (result) {
@@ -1920,7 +2038,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         // the host's own click event is blocked by the cursor preview.
         if (ctx.state.surface === 'item-surface' && ctx.state.surfaceItemId) {
           const hostNode = useScene.getState().nodes[ctx.state.surfaceItemId as AnyNodeId]
-          if (hostNode && hostNode.type === 'item') {
+          if (hostNode) {
             const synthetic = { ...event, node: hostNode } as ItemEvent
             const result = itemSurfaceStrategy.click(ctx, synthetic)
             if (result) {
@@ -1955,7 +2073,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
               finishCommittedPlacement(committedId, wasAdopted, () => {
                 const nodes = useScene.getState().nodes
                 const enterResult = ceilingStrategy.enter(
-                  getContext(),
+                  surfaceContext(event),
                   synthetic,
                   resolveLevelId,
                   nodes,
@@ -1973,7 +2091,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         return
       }
 
-      const result = itemSurfaceStrategy.click(getContext(), event)
+      const result = itemSurfaceStrategy.click(surfaceContext(event), event)
       if (!result) return
 
       event.stopPropagation()
@@ -1981,7 +2099,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
       finishCommittedPlacement(committedId, wasAdopted, () => {
         // Try to set up next draft on the same surface
-        const enterResult = itemSurfaceStrategy.enter(getContext(), event)
+        const enterResult = itemSurfaceStrategy.enter(surfaceContext(event), event)
         if (enterResult) {
           applyTransition(enterResult)
         } else {
@@ -2005,7 +2123,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         ensureDraft(result)
       } else if (result.nodeUpdate.parentId) {
         // Existing draft (move mode): reparent to new ceiling
-        useScene.getState().updateNode(draftNode.current.id, result.nodeUpdate)
+        updateSurfaceNode(draftNode.current.id, result.nodeUpdate)
         if (result.stateUpdate.ceilingId) {
           useScene.getState().dirtyNodes.add(result.stateUpdate.ceilingId as AnyNodeId)
         }
@@ -2155,16 +2273,16 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     const onShelfEnter = (event: ShelfEvent) => {
       has3DPointerDrivenMoveRef.current = true
-      const result = shelfSurfaceStrategy.enter(getContext(), event)
+      const result = shelfSurfaceStrategy.enter(surfaceContext(event), event)
       if (!result) return
 
       event.stopPropagation()
-      applyTransition(result)
+      applyTransition(result, event)
 
       if (!draftNode.current) {
         ensureDraft(result)
       } else if (result.nodeUpdate.parentId) {
-        useScene.getState().updateNode(draftNode.current.id, result.nodeUpdate)
+        updateSurfaceNode(draftNode.current.id, result.nodeUpdate)
       }
     }
 
@@ -2174,7 +2292,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       // A shelf event can fire before the cursor group mounts or after
       // teardown, leaving the ref null; bail before dereferencing it below.
       if (!cursorGroupRef.current) return
-      const ctx = getContext()
+      const ctx = surfaceContext(event)
       if (ctx.state.surface !== 'shelf-surface') {
         // Cursor entered via a move event without an enter — try
         // transitioning in so the user doesn't need to mouse out + back
@@ -2182,11 +2300,11 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         const enterResult = shelfSurfaceStrategy.enter(ctx, event)
         if (!enterResult) return
         event.stopPropagation()
-        applyTransition(enterResult)
+        applyTransition(enterResult, event)
         if (!draftNode.current) {
           ensureDraft(enterResult)
         } else if (enterResult.nodeUpdate.parentId) {
-          useScene.getState().updateNode(draftNode.current.id, enterResult.nodeUpdate)
+          updateSurfaceNode(draftNode.current.id, enterResult.nodeUpdate)
         }
         return
       }
@@ -2198,8 +2316,11 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       const result = shelfSurfaceStrategy.move(ctx, shelfMoveEvent)
       if (!result) return
 
+      feedback.clear()
       event.stopPropagation()
 
+      surfacePointer.hit(event.node.id, event.nativeEvent.nativeEvent ?? event.nativeEvent)
+      tickSurfaceMovementSfx(result.cursorPosition)
       gridPosition.current.set(...result.gridPosition)
       const ic = worldToBuildingLocal(...result.cursorPosition)
       cursorGroupRef.current.position.set(ic.x, ic.y, ic.z)
@@ -2209,7 +2330,10 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (draft) {
         draft.position = result.gridPosition
         const mesh = sceneRegistry.nodes.get(draft.id)
-        if (mesh) mesh.position.set(...result.gridPosition)
+        if (mesh)
+          mesh.position.set(
+            ...surfaceFramePose(draft.parentId, surfaceAttachmentId(draft), draft, true).position,
+          )
         useLiveTransforms.getState().set(draft.id, {
           position: result.cursorPosition,
           rotation: result.cursorRotationY,
@@ -2233,14 +2357,16 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     }
 
     const onShelfClick = (event: ShelfEvent) => {
-      const result = shelfSurfaceStrategy.click(getContext(), event)
+      gridDispatch.flush()
+      if (feedback.reason) return
+      const result = shelfSurfaceStrategy.click(surfaceContext(event), event)
       if (!result) return
 
       event.stopPropagation()
       const { committedId, wasAdopted } = commitDraft(result.nodeUpdate)
 
       finishCommittedPlacement(committedId, wasAdopted, () => {
-        const enterResult = shelfSurfaceStrategy.enter(getContext(), event)
+        const enterResult = shelfSurfaceStrategy.enter(surfaceContext(event), event)
         if (enterResult) {
           applyTransition(enterResult)
         } else {
@@ -2286,7 +2412,49 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         const currentRotation = draft.rotation
         // Round to the nearest 45° then step, matching the placed-item R/T.
         const newRotationY = steppedRotation(currentRotation[1] ?? 0, rotationDir)
-        draft.rotation = [currentRotation[0], newRotationY, currentRotation[2]]
+        const nextRotation: [number, number, number] = [
+          currentRotation[0],
+          newRotationY,
+          currentRotation[2],
+        ]
+        const surface = placementState.current.surface
+        const surfaceMesh =
+          surface === 'item-surface' && placementState.current.surfaceItemId
+            ? sceneRegistry.nodes.get(placementState.current.surfaceItemId)
+            : undefined
+        let surfacePosition: [number, number, number] | undefined
+        if (surfaceMesh) {
+          const localPos = surfaceMesh.worldToLocal(lastRawPos.current.clone())
+          const [dimX, , dimZ] = getScaledDimensions(draft)
+          const swapDims = Math.abs(Math.sin(newRotationY)) > 0.9
+          surfacePosition = [
+            snapToGrid(localPos.x, swapDims ? dimZ : dimX),
+            gridPosition.current.y,
+            snapToGrid(localPos.z, swapDims ? dimX : dimZ),
+          ]
+        }
+        if (surfaceAttachmentId(draft)) {
+          let occupied = false
+          checkCanPlace(
+            {
+              ...getContext(),
+              draftItem: { ...draft, rotation: nextRotation },
+              gridPosition: surfacePosition
+                ? new Vector3(...surfacePosition)
+                : gridPosition.current,
+              onSurfaceReject: (reason) => {
+                occupied = reason === 'surface-occupied'
+              },
+            },
+            validators,
+          )
+          if (occupied) {
+            feedback.reject('surface-occupied')
+            revalidate()
+            return
+          }
+        }
+        draft.rotation = nextRotation
 
         // Rotate the building-local cursor by the same delta as the host-local
         // draft. This preserves the host's composed yaw for items resting on a
@@ -2298,7 +2466,6 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         if (mesh) mesh.rotation.y = newRotationY
 
         // Re-snap position immediately with updated rotation (dimX/dimZ may swap at 90°)
-        const surface = placementState.current.surface
         if (surface === 'floor' || surface === 'ceiling') {
           const dims = getScaledDimensions(draft)
           const [dimX, , dimZ] = dims
@@ -2328,15 +2495,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
             }
           }
         } else if (surface === 'item-surface' && placementState.current.surfaceItemId) {
-          const surfaceMesh = sceneRegistry.nodes.get(placementState.current.surfaceItemId)
-          if (surfaceMesh) {
-            const localPos = surfaceMesh.worldToLocal(lastRawPos.current.clone())
-            const dims = getScaledDimensions(draft)
-            const [dimX, , dimZ] = dims
-            const swapDims = Math.abs(Math.sin(newRotationY)) > 0.9
-            const x = snapToGrid(localPos.x, swapDims ? dimZ : dimX)
-            const z = snapToGrid(localPos.z, swapDims ? dimX : dimZ)
-            const y = gridPosition.current.y
+          if (surfaceMesh && surfacePosition) {
+            const [x, y, z] = surfacePosition
             gridPosition.current.set(x, y, z)
             draft.position = [x, y, z]
             const worldSnapped = surfaceMesh.localToWorld(new Vector3(x, y, z))
@@ -2362,7 +2522,21 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         // Keep both preview renderers on the rotated draft. The item renderer
         // consumes live node overrides, while the floor-plan renderer consumes
         // the live transform and placement-preview snapshot.
-        useLiveNodeOverrides.getState().set(draft.id, { rotation: draft.rotation })
+        const storedSurfacePose = surfaceFramePose(
+          draft.parentId,
+          surfaceAttachmentId(draft),
+          draft,
+          true,
+        )
+        if (surfaceAttachmentId(draft)) {
+          draftNode.updateSurface(
+            { position: draft.position, rotation: draft.rotation },
+            surfaceAttachmentId(draft),
+          )
+          mesh?.position.set(...storedSurfacePose.position)
+          mesh?.rotation.set(...storedSurfacePose.rotation)
+        }
+        useLiveNodeOverrides.getState().set(draft.id, { rotation: storedSurfacePose.rotation })
         const currentLive = useLiveTransforms.getState().get(draft.id)
         const livePosition: [number, number, number] =
           surface === 'floor'
@@ -2395,7 +2569,13 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
           )
         }
 
-        revalidate()
+        if (feedback.reason && lastSurfaceEvent) {
+          if (lastSurfaceEvent.node.type === 'shelf') onShelfMove(lastSurfaceEvent as ShelfEvent)
+          else onItemMove(lastSurfaceEvent as NodeEvent<AnyNode>)
+        } else {
+          feedback.clear()
+          revalidate()
+        }
       }
     }
 
@@ -2474,7 +2654,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     const unsubDraftWatch = useScene.subscribe((state) => {
       if (tearingDown) return
       const draft = draftNode.current
-      if (draft === null) return
+      if (draft === null || isFreshPlacementMetadata(draft.metadata)) return
       if (draft.id in state.nodes) return
 
       queueMicrotask(() => {
@@ -2489,32 +2669,73 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     // ---- Subscribe ----
 
-    emitter.on('grid:move', onGridMove)
+    const specializedKinds = new Set<string>()
+    const subscribeSpecialized = <E,>(key: string, handler: (event: E) => void) => {
+      specializedKinds.add(key.slice(0, key.lastIndexOf(':')))
+      emitter.on(key as never, handler as never)
+    }
+    const genericRoute = (phase: 'enter' | 'move' | 'click' | 'leave') => (event: NodeEvent) => {
+      if (specializedKinds.has(event.node.type)) return
+      if (
+        !surfaceOwnership.allows(event.node.id, event.nativeEvent.nativeEvent ?? event.nativeEvent)
+      )
+        return
+      if (nodeRegistry.get(event.node.type)?.capabilities.faceHost) {
+        const handlers = {
+          enter: onFaceHostEnter,
+          move: onFaceHostMove,
+          click: onFaceHostClick,
+          leave: onFaceHostLeave,
+        }
+        handlers[phase](event)
+        return
+      }
+      if (!canHostSurfaceChild(event.node, 'item', draftNode.current?.id)) return
+      if (phase === 'leave' && placementState.current.surfaceItemId !== event.node.id) return
+      if (phase === 'enter') onItemEnter(event, true)
+      else if (phase === 'move') onItemMove(event, true)
+      else if (phase === 'click') onItemClick(event)
+      else onItemLeave(event)
+    }
+    const onNodeEnter = genericRoute('enter')
+    const onNodeMove = genericRoute('move')
+    const onNodeClick = genericRoute('click')
+    const onNodeLeave = genericRoute('leave')
+    const gridDispatch = createItemSurfaceGridDispatch(onGridMove)
+    emitter.on('grid:move', gridDispatch.schedule)
     emitter.on('grid:click', onGridClick)
-    emitter.on('item:enter', onItemEnter)
-    emitter.on('item:move', onItemMove)
-    emitter.on('item:leave', onItemLeave)
-    emitter.on('item:click', onItemClick)
-    emitter.on('wall:enter', onWallEnter)
-    emitter.on('wall:move', onWallMove)
-    emitter.on('wall:click', onWallClick)
-    emitter.on('wall:leave', onWallLeave)
-    emitter.on('roof:enter', onRoofWallEnter)
-    emitter.on('roof:move', onRoofWallMove)
-    emitter.on('roof:click', onRoofWallClick)
-    emitter.on('roof:leave', onRoofWallLeave)
-    emitter.on('node:enter', onFaceHostEnter)
-    emitter.on('node:move', onFaceHostMove)
-    emitter.on('node:click', onFaceHostClick)
-    emitter.on('node:leave', onFaceHostLeave)
-    emitter.on('ceiling:enter', onCeilingEnter)
-    emitter.on('ceiling:move', onCeilingMove)
-    emitter.on('ceiling:click', onCeilingClick)
-    emitter.on('ceiling:leave', onCeilingLeave)
-    emitter.on('shelf:enter', onShelfEnter)
-    emitter.on('shelf:move', onShelfMove)
-    emitter.on('shelf:click', onShelfClick)
-    emitter.on('shelf:leave', onShelfLeave)
+    subscribeSpecialized('item:enter', onItemEnter)
+    subscribeSpecialized('item:move', onItemMove)
+    subscribeSpecialized('item:leave', onItemLeave)
+    subscribeSpecialized('item:click', onItemClick)
+    subscribeSpecialized('wall:enter', onWallEnter)
+    subscribeSpecialized('wall:move', onWallMove)
+    subscribeSpecialized('wall:click', onWallClick)
+    subscribeSpecialized('wall:leave', onWallLeave)
+    subscribeSpecialized('roof:enter', onRoofWallEnter)
+    subscribeSpecialized('roof:move', onRoofWallMove)
+    subscribeSpecialized('roof:click', onRoofWallClick)
+    subscribeSpecialized('roof:leave', onRoofWallLeave)
+    emitter.on('node:enter', onNodeEnter)
+    emitter.on('node:move', onNodeMove)
+    emitter.on('node:click', onNodeClick)
+    emitter.on('node:leave', onNodeLeave)
+    subscribeSpecialized('ceiling:enter', onCeilingEnter)
+    subscribeSpecialized('ceiling:move', onCeilingMove)
+    subscribeSpecialized('ceiling:click', onCeilingClick)
+    subscribeSpecialized('ceiling:leave', onCeilingLeave)
+    subscribeSpecialized('cabinet:enter', onItemEnter)
+    subscribeSpecialized('procedural-item:enter', onItemEnter)
+    subscribeSpecialized('cabinet:move', onItemMove)
+    subscribeSpecialized('procedural-item:move', onItemMove)
+    subscribeSpecialized('cabinet:click', onItemClick)
+    subscribeSpecialized('procedural-item:click', onItemClick)
+    subscribeSpecialized('cabinet:leave', onItemLeave)
+    subscribeSpecialized('procedural-item:leave', onItemLeave)
+    subscribeSpecialized('shelf:enter', onShelfEnter)
+    subscribeSpecialized('shelf:move', onShelfMove)
+    subscribeSpecialized('shelf:click', onShelfClick)
+    subscribeSpecialized('shelf:leave', onShelfLeave)
 
     // A floor placement commits at the tracked floor cursor (`gridPosition`),
     // which keeps following the floor even when the click ray lands on a wall
@@ -2534,6 +2755,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     return () => {
       tearingDown = true
+      feedback.clear()
       if (dragMode) window.removeEventListener('pointerup', onReleaseCommit)
       unsubDraftWatch()
       useAlignmentGuides.getState().clear()
@@ -2544,7 +2766,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       }
       draftNode.destroy()
       useScene.temporal.getState().resume()
-      emitter.off('grid:move', onGridMove)
+      gridDispatch.cancel()
+      emitter.off('grid:move', gridDispatch.schedule)
       emitter.off('grid:click', onGridClick)
       emitter.off('item:enter', onItemEnter)
       emitter.off('item:move', onItemMove)
@@ -2558,14 +2781,22 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       emitter.off('roof:move', onRoofWallMove)
       emitter.off('roof:click', onRoofWallClick)
       emitter.off('roof:leave', onRoofWallLeave)
-      emitter.off('node:enter', onFaceHostEnter)
-      emitter.off('node:move', onFaceHostMove)
-      emitter.off('node:click', onFaceHostClick)
-      emitter.off('node:leave', onFaceHostLeave)
+      emitter.off('node:enter', onNodeEnter)
+      emitter.off('node:move', onNodeMove)
+      emitter.off('node:click', onNodeClick)
+      emitter.off('node:leave', onNodeLeave)
       emitter.off('ceiling:enter', onCeilingEnter)
       emitter.off('ceiling:move', onCeilingMove)
       emitter.off('ceiling:click', onCeilingClick)
       emitter.off('ceiling:leave', onCeilingLeave)
+      emitter.off('cabinet:enter', onItemEnter)
+      emitter.off('procedural-item:enter' as never, onItemEnter)
+      emitter.off('cabinet:move', onItemMove)
+      emitter.off('procedural-item:move' as never, onItemMove)
+      emitter.off('cabinet:click', onItemClick)
+      emitter.off('procedural-item:click' as never, onItemClick)
+      emitter.off('cabinet:leave', onItemLeave)
+      emitter.off('procedural-item:leave' as never, onItemLeave)
       emitter.off('shelf:enter', onShelfEnter)
       emitter.off('shelf:move', onShelfMove)
       emitter.off('shelf:click', onShelfClick)
@@ -2623,6 +2854,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     if (
       draftParent?.type === 'item' ||
       draftParent?.type === 'shelf' ||
+      draftParent?.type === 'cabinet' ||
+      draftParent?.type === 'procedural-item' ||
+      (draftParent && canHostSurfaceChild(draftParent, draft.type, draft.id)) ||
       (draftParent &&
         nodeRegistry.get(draftParent.type)?.capabilities.faceHost?.currentFaceId(draft))
     )
@@ -2641,8 +2875,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
   // instead of drawing an inline triangle. Only this coordinator publishes — a
   // moving existing node has no draft here, so the grid reads that case straight
   // off the node's mesh. Cleared when idle.
-  const surfaceNormalRef = useRef(new Vector3(0, 1, 0))
   const surfaceWorldPointRef = useRef(new Vector3())
+  const surfaceNormalRef = useRef(new Vector3(0, 1, 0))
   const facingForwardRef = useRef(new Vector3(0, 0, 1))
   const facingQuatRef = useRef(new Quaternion())
   const ghostSurfaceQuatRef = useRef(new Quaternion())