@pascal-app/editor 0.7.0 → 0.9.1

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

@@ -1,29 +1,32 @@
-import type { AssetInput } from '@pascal-app/core'
+import type { AssetInput, ItemNode } from '@pascal-app/core'
 import {
+  type AlignmentAnchor,
+  type AnyNode,
   type AnyNodeId,
   type CeilingEvent,
+  collectAlignmentAnchors,
   emitter,
   type GridEvent,
   getScaledDimensions,
   type ItemEvent,
+  movingFootprintAnchors,
   resolveLevelId,
+  type ShelfEvent,
   sceneRegistry,
-  spatialGridManager,
   useLiveTransforms,
   useScene,
   useSpatialQuery,
   type WallEvent,
   type WallNode,
 } from '@pascal-app/core'
+import { useAlignmentGuides } from '@pascal-app/editor'
 import { useViewer } from '@pascal-app/viewer'
 import { Html } from '@react-three/drei'
-import { useFrame } from '@react-three/fiber'
-import { useEffect, useMemo, useRef, useState } from 'react'
+import { useFrame, useThree } from '@react-three/fiber'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import {
   Box3,
-  BufferGeometry,
   Euler,
-  Float32BufferAttribute,
   type Group,
   type LineSegments,
   Matrix4,
@@ -31,19 +34,29 @@ import {
   type Object3D,
   PlaneGeometry,
   Quaternion,
+  Ray,
   Vector3,
 } from 'three'
 import { distance, smoothstep, uv, vec2 } from 'three/tsl'
 import { LineBasicNodeMaterial, MeshBasicNodeMaterial } from 'three/webgpu'
 import { EDITOR_LAYER } from '../../../lib/constants'
 import { sfxEmitter } from '../../../lib/sfx-bus'
+import { resolveAlignmentForActiveBuilding } from '../../../lib/world-grid-snap'
 import useEditor from '../../../store/use-editor'
+import { getFloorStackPreviewPosition } from '../shared/floor-stack-preview'
+import {
+  createLineGeometry,
+  getBoxEdgePoints,
+  type PreviewBounds,
+  updateLineGeometry,
+} from '../shared/placement-box-geometry'
 import { getGridAlignedDimensions, snapToGrid, snapUpToGridStep } from './placement-math'
 import {
   ceilingStrategy,
   checkCanPlace,
   floorStrategy,
   itemSurfaceStrategy,
+  shelfSurfaceStrategy,
   wallStrategy,
 } from './placement-strategies'
 import type { PlacementState, TransitionResult } from './placement-types'
@@ -51,6 +64,10 @@ import type { DraftNodeHandle } from './use-draft-node'
 
 const DEFAULT_DIMENSIONS: [number, number, number] = [1, 1, 1]
 
+/** Figma-style alignment-snap threshold (meters), matching the 2D
+ *  floor-plan overlay and the 3D registry move tool. */
+const ALIGNMENT_THRESHOLD_M = 0.08
+
 function formatMeasurement(value: number, unit: 'metric' | 'imperial') {
   if (unit === 'imperial') {
     const feet = value * 3.280_84
@@ -62,13 +79,6 @@ function formatMeasurement(value: number, unit: 'metric' | 'imperial') {
   return `${Number.parseFloat(value.toFixed(2))}m`
 }
 
-type PreviewBounds = {
-  min: [number, number, number]
-  max: [number, number, number]
-  dimensions: [number, number, number]
-  center: [number, number, number]
-}
-
 /**
  * Expand `bounds` outward so each axis is rounded up to the active grid step.
  * The wireframe stays centered on the original bounds centre on each axis we
@@ -117,85 +127,12 @@ function expandBoundsToGrid(
   }
 }
 
-function getPreviewBoundsFromObject(object: Object3D | null): PreviewBounds | null {
-  if (!object) return null
-
-  object.updateWorldMatrix(true, true)
-
-  const inverseRootMatrix = new Matrix4().copy(object.matrixWorld).invert()
-  const localMatrix = new Matrix4()
-  const localBounds = new Box3()
-  const scratchBounds = new Box3()
-  const hasBounds = { current: false }
-  const registeredNodeObjects = new Set(sceneRegistry.nodes.values())
-
-  const expandBounds = (child: Object3D) => {
-    if (child !== object && registeredNodeObjects.has(child)) {
-      return
-    }
-
-    const mesh = child as Object3D & {
-      isMesh?: boolean
-      name?: string
-      geometry?: {
-        boundingBox: Box3 | null
-        computeBoundingBox?: () => void
-      }
-    }
-
-    if (mesh.isMesh && mesh.name !== 'cutout' && mesh.geometry) {
-      if (!mesh.geometry.boundingBox && mesh.geometry.computeBoundingBox) {
-        mesh.geometry.computeBoundingBox()
-      }
-
-      if (mesh.geometry.boundingBox) {
-        localMatrix.copy(inverseRootMatrix).multiply(mesh.matrixWorld)
-        scratchBounds.copy(mesh.geometry.boundingBox).applyMatrix4(localMatrix)
-        if (Number.isFinite(scratchBounds.min.x) && Number.isFinite(scratchBounds.max.x)) {
-          if (!hasBounds.current) {
-            localBounds.copy(scratchBounds)
-            hasBounds.current = true
-          } else {
-            localBounds.union(scratchBounds)
-          }
-        }
-      }
-    }
-
-    for (const grandchild of child.children) {
-      expandBounds(grandchild)
-    }
-  }
-
-  for (const child of object.children) {
-    expandBounds(child)
-  }
-
-  if (!hasBounds.current) return null
-
-  const size = new Vector3()
-  const center = new Vector3()
-  localBounds.getSize(size)
-  localBounds.getCenter(center)
-
-  if (size.x <= 0 || size.y <= 0 || size.z <= 0) {
-    return null
-  }
-
-  return {
-    min: [localBounds.min.x, localBounds.min.y, localBounds.min.z],
-    max: [localBounds.max.x, localBounds.max.y, localBounds.max.z],
-    dimensions: [size.x, size.y, size.z],
-    center: [center.x, center.y, center.z],
-  }
-}
-
 function getFallbackPreviewBounds(
   item: import('@pascal-app/core').ItemNode | null,
-  asset: AssetInput,
-  attachTo: AssetInput['attachTo'],
+  asset: AssetInput | null | undefined,
+  attachTo: AssetInput['attachTo'] | null | undefined,
 ): PreviewBounds {
-  const dims = item ? getScaledDimensions(item) : (asset.dimensions ?? DEFAULT_DIMENSIONS)
+  const dims = item ? getScaledDimensions(item) : (asset?.dimensions ?? DEFAULT_DIMENSIONS)
   return {
     min: [-dims[0] / 2, 0, attachTo === 'wall-side' ? -dims[2] : -dims[2] / 2],
     max: [dims[0] / 2, dims[1], attachTo === 'wall-side' ? 0 : dims[2] / 2],
@@ -204,112 +141,20 @@ function getFallbackPreviewBounds(
   }
 }
 
-function createLineGeometry(points: number[] = [0, 0, 0, 0, 0, 0]): BufferGeometry {
-  const geometry = new BufferGeometry()
-  geometry.setAttribute('position', new Float32BufferAttribute(points, 3))
-  return geometry
-}
-
-function getBoxEdgePoints(bounds: PreviewBounds): number[] {
-  const [width, height, depth] = bounds.dimensions
-  const [centerX, centerY, centerZ] = bounds.center
-  const minX = centerX - width / 2
-  const maxX = centerX + width / 2
-  const minY = centerY - height / 2
-  const maxY = centerY + height / 2
-  const minZ = centerZ - depth / 2
-  const maxZ = centerZ + depth / 2
-
-  return [
-    minX,
-    minY,
-    minZ,
-    maxX,
-    minY,
-    minZ,
-    maxX,
-    minY,
-    minZ,
-    maxX,
-    minY,
-    maxZ,
-    maxX,
-    minY,
-    maxZ,
-    minX,
-    minY,
-    maxZ,
-    minX,
-    minY,
-    maxZ,
-    minX,
-    minY,
-    minZ,
-
-    minX,
-    maxY,
-    minZ,
-    maxX,
-    maxY,
-    minZ,
-    maxX,
-    maxY,
-    minZ,
-    maxX,
-    maxY,
-    maxZ,
-    maxX,
-    maxY,
-    maxZ,
-    minX,
-    maxY,
-    maxZ,
-    minX,
-    maxY,
-    maxZ,
-    minX,
-    maxY,
-    minZ,
-
-    minX,
-    minY,
-    minZ,
-    minX,
-    maxY,
-    minZ,
-    maxX,
-    minY,
-    minZ,
-    maxX,
-    maxY,
-    minZ,
-    maxX,
-    minY,
-    maxZ,
-    maxX,
-    maxY,
-    maxZ,
-    minX,
-    minY,
-    maxZ,
-    minX,
-    maxY,
-    maxZ,
-  ]
-}
+function getGridAlignedPreviewNode(item: ItemNode): ItemNode {
+  const scaled = getScaledDimensions(item)
+  const aligned = getGridAlignedDimensions(scaled, item.asset.attachTo)
+  if (scaled[0] === aligned[0] && scaled[1] === aligned[1] && scaled[2] === aligned[2]) {
+    return item
+  }
 
-function updateLineGeometry(ref: React.RefObject<LineSegments>, points: number[]) {
-  const geometry = ref.current?.geometry
-  if (!geometry) return
+  const scaleAxis = (axis: 0 | 1 | 2) =>
+    scaled[axis] === 0 ? item.scale[axis] : item.scale[axis] * (aligned[axis] / scaled[axis])
 
-  const attribute = geometry.getAttribute('position') as Float32BufferAttribute | undefined
-  if (!attribute || attribute.array.length !== points.length) {
-    geometry.setAttribute('position', new Float32BufferAttribute(points, 3))
-  } else {
-    attribute.set(points)
-    attribute.needsUpdate = true
+  return {
+    ...item,
+    scale: [scaleAxis(0), scaleAxis(1), scaleAxis(2)] as [number, number, number],
   }
-  geometry.computeBoundingSphere()
 }
 
 // Shared materials for placement cursor - we just change colors, not swap materials
@@ -350,6 +195,8 @@ export interface PlacementCoordinatorConfig {
   initialState?: PlacementState
   /** Scale to use when lazily creating a draft (e.g. for wall/ceiling duplicates). Defaults to [1,1,1]. */
   defaultScale?: [number, number, number]
+  /** Move-mode sessions for floor items keep the grabbed item offset from the first floor-plane hit. */
+  preserveFloorDragOffset?: boolean
 }
 
 export function usePlacementCoordinator(config: PlacementCoordinatorConfig): React.ReactNode {
@@ -361,14 +208,44 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
   const basePlaneRef = useRef<Mesh>(null!)
   const gridPosition = useRef(new Vector3(0, 0, 0))
   const lastRawPos = useRef(new Vector3(0, 0, 0))
+  const lastWallDirtyAtRef = useRef(new Map<string, number>())
   const placementState = useRef<PlacementState>(
-    config.initialState ?? { surface: 'floor', wallId: null, ceilingId: null, surfaceItemId: null },
+    config.initialState ?? {
+      surface: 'floor',
+      wallId: null,
+      ceilingId: null,
+      surfaceItemId: null,
+      shelfId: null,
+    },
   )
   const shiftFreeRef = useRef(false)
   const previewBoundsSignatureRef = useRef<string | null>(null)
-  const meshPreviewAppliedRef = useRef(false)
+  // Goes true the first time a 3D pointer event drives this coordinator.
+  // The per-frame mesh-position lerp below is only useful for that path;
+  // when the move is being driven externally (2D `FloorplanRegistryMoveOverlay`
+  // writing scene.position directly), the lerp fights React's render and
+  // pulls the rendered item back toward its pre-move position. Gating
+  // the lerp on this flag keeps 3D placement smooth without hijacking
+  // 2D drags that share the same draft.
+  const has3DPointerDrivenMoveRef = useRef(false)
+  // The draft mesh's raycast is disabled while placing so the cursor ray
+  // passes through it to the surface beneath (grid / item / shelf). Without
+  // this, the ray hits the moving draft first and the surface strategy keeps
+  // re-deriving the host point from the draft's own (just-moved) geometry —
+  // on a multi-row shelf this oscillates the chosen row, jittering the item.
+  // Mirrors MoveRegistryNodeTool. Reconciled per-frame (the draft mesh can be
+  // recreated mid-session) and restored on unmount.
+  const raycastDisabledMeshRef = useRef<Object3D | null>(null)
+  const restoreRaycastsRef = useRef<Array<() => void>>([])
+  const raycastDisabledChildrenRef = useRef(new WeakSet<Object3D>())
   const [dimensionBounds, setDimensionBounds] = useState<PreviewBounds | null>(null)
 
+  // Live camera ref — the shelf-stickiness test reconstructs the cursor world
+  // ray (camera → grid hit) to check it still points at the shelf volume.
+  const camera = useThree((s) => s.camera)
+  const cameraRef = useRef(camera)
+  cameraRef.current = camera
+
   // Store config callbacks in refs to avoid re-running effect when they change
   const configRef = useRef(config)
   configRef.current = config
@@ -377,7 +254,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
   const { asset, draftNode } = config
   const unit = useViewer((state) => state.unit)
   const gridSnapStep = useEditor((s) => s.gridSnapStep)
-  const updatePreviewGeometry = (bounds: PreviewBounds) => {
+  const updatePreviewGeometry = useCallback((bounds: PreviewBounds) => {
     const [width, height, depth] = bounds.dimensions
     const [centerX, centerY, centerZ] = bounds.center
     const signature = `${width.toFixed(4)}:${height.toFixed(4)}:${depth.toFixed(4)}:${centerX.toFixed(4)}:${centerY.toFixed(4)}:${centerZ.toFixed(4)}`
@@ -394,9 +271,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     const oldBasePlaneGeometry = basePlaneRef.current.geometry
     basePlaneRef.current.geometry = nextBasePlaneGeometry
     oldBasePlaneGeometry.dispose()
-  }
+  }, [])
 
-  const updateDimensionGuides = (bounds: PreviewBounds) => {
+  const updateDimensionGuides = useCallback((bounds: PreviewBounds) => {
     setDimensionBounds((current) => {
       if (
         current &&
@@ -498,25 +375,53 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     applyPoints(measurementWidthRef, widthPoints)
     applyPoints(measurementDepthRef, depthPoints)
     applyPoints(measurementHeightRef, heightPoints)
-  }
+  }, [])
+
+  const getFloorVisualPosition = useCallback(
+    (
+      position: [number, number, number],
+      nodeUpdate?: Partial<ItemNode>,
+    ): [number, number, number] => {
+      const draft = draftNode.current
+      if (!(draft && !asset?.attachTo)) return position
+      const previewNode = getGridAlignedPreviewNode({ ...draft, ...nodeUpdate } as ItemNode)
+      return getFloorStackPreviewPosition({
+        node: previewNode,
+        position,
+        rotation: previewNode.rotation,
+      })
+    },
+    [asset?.attachTo, draftNode],
+  )
 
   useEffect(() => {
     if (!asset) return
     useScene.temporal.getState().pause()
-    meshPreviewAppliedRef.current = false
 
     const validators = { canPlaceOnFloor, canPlaceOnWall, canPlaceOnCeiling }
 
+    // Lazily-gathered alignment candidates — the corner anchors of every
+    // OTHER floor-placed node, excluding the draft. Computed on the first
+    // floor move (once the draft id exists) and reused for the rest of the
+    // drag; the scene graph is stable during placement. Coords are
+    // building-local, matching the draft's grid position and the guide
+    // layer's frame.
+    let alignmentCandidates: AlignmentAnchor[] | null = null
+    let floorDragAnchor: [number, number] | null = null
+
     // Reset placement state
     placementState.current = configRef.current.initialState ?? {
       surface: 'floor',
       wallId: null,
       ceilingId: null,
       surfaceItemId: null,
+      shelfId: null,
     }
     if (!asset.attachTo && placementState.current.surface === 'floor') {
       gridPosition.current.y = 0
-      cursorGroupRef.current.position.y = 0
+      if (cursorGroupRef.current) {
+        cursorGroupRef.current.position.y = 0
+      }
     }
 
     // ---- Helpers ----
@@ -527,7 +432,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       draftItem: draftNode.current,
       gridPosition: gridPosition.current,
       state: { ...placementState.current },
-      currentCursorRotationY: cursorGroupRef.current.rotation.y,
+      currentCursorRotationY:
+        cursorGroupRef.current?.rotation.y ?? draftNode.current?.rotation[1] ?? 0,
     })
 
     const getActiveValidators = () =>
@@ -557,12 +463,21 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     }
 
     const applyTransition = (result: TransitionResult) => {
+      // 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()
       Object.assign(placementState.current, result.stateUpdate)
       gridPosition.current.set(...result.gridPosition)
 
       const c = worldToBuildingLocal(...result.cursorPosition)
-      cursorGroupRef.current.position.set(c.x, c.y, c.z)
-      cursorGroupRef.current.rotation.y = result.cursorRotationY
+      if (cursorGroupRef.current) {
+        cursorGroupRef.current.position.set(c.x, c.y, c.z)
+        if (result.cursorRotation) {
+          cursorGroupRef.current.rotation.set(...result.cursorRotation)
+        } else {
+          cursorGroupRef.current.rotation.set(0, result.cursorRotationY, 0)
+        }
+      }
 
       const draft = draftNode.current
       if (draft) {
@@ -575,15 +490,22 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     const ensureDraft = (result: TransitionResult) => {
       gridPosition.current.set(...result.gridPosition)
       const c = worldToBuildingLocal(...result.cursorPosition)
-      cursorGroupRef.current.position.set(c.x, c.y, c.z)
-      cursorGroupRef.current.rotation.y = result.cursorRotationY
+      if (cursorGroupRef.current) {
+        cursorGroupRef.current.position.set(c.x, c.y, c.z)
+        if (result.cursorRotation) {
+          cursorGroupRef.current.rotation.set(...result.cursorRotation)
+        } else {
+          cursorGroupRef.current.rotation.set(0, result.cursorRotationY, 0)
+        }
+      }
 
-      draftNode.create(
-        gridPosition.current,
-        asset,
-        [0, result.cursorRotationY, 0],
-        configRef.current.defaultScale,
-      )
+      const initRotation: [number, number, number] = result.cursorRotation ?? [
+        0,
+        result.cursorRotationY,
+        0,
+      ]
+
+      draftNode.create(gridPosition.current, asset, initRotation, configRef.current.defaultScale)
 
       const draft = draftNode.current
       if (draft) {
@@ -592,6 +514,14 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         useScene.getState().updateNode(draft.id, result.nodeUpdate)
       }
 
+      const previewBounds = expandBoundsToGrid(
+        getFallbackPreviewBounds(draftNode.current, asset, asset.attachTo),
+        asset.attachTo,
+        gridSnapStep,
+      )
+      updatePreviewGeometry(previewBounds)
+      updateDimensionGuides(previewBounds)
+
       if (!revalidate()) {
         draftNode.destroy()
       }
@@ -599,6 +529,11 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     // ---- Init draft ----
     configRef.current.initDraft(gridPosition.current)
+    const preserveFloorDragOffset =
+      configRef.current.preserveFloorDragOffset === true &&
+      placementState.current.surface === 'floor' &&
+      !asset.attachTo
+    const relativeFloorStart = preserveFloorDragOffset ? gridPosition.current.clone() : null
 
     // Sync cursor to the draft mesh's world position and rotation
     if (draftNode.current) {
@@ -607,12 +542,22 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         const worldPos = new Vector3()
         mesh.getWorldPosition(worldPos)
         const localPos = worldToBuildingLocal(worldPos.x, worldPos.y, worldPos.z)
-        cursorGroupRef.current.position.copy(localPos)
-        // Extract world Y rotation (handles wall-parented items correctly)
-        const q = new Quaternion()
-        mesh.getWorldQuaternion(q)
-        cursorGroupRef.current.rotation.y = new Euler().setFromQuaternion(q, 'YXZ').y
-      } else {
+        if (cursorGroupRef.current) {
+          cursorGroupRef.current.position.copy(localPos)
+          if (draftNode.current.asset.attachTo) {
+            // Wall/ceiling items: extract world Y rotation (handles wall-parented items correctly)
+            const q = new Quaternion()
+            mesh.getWorldQuaternion(q)
+            cursorGroupRef.current.rotation.y = new Euler().setFromQuaternion(q, 'YXZ').y
+          } else {
+            // Floor items: the cursor group lives in building-local space, so use the
+            // node's local Y rotation — the same value onGridMove applies. The world
+            // quaternion would double-count any building rotation, leaving the initial
+            // box mis-rotated until the first cursor move.
+            cursorGroupRef.current.rotation.y = draftNode.current.rotation[1] ?? 0
+          }
+        }
+      } else if (cursorGroupRef.current) {
         cursorGroupRef.current.position.copy(gridPosition.current)
         cursorGroupRef.current.rotation.y = draftNode.current.rotation[1] ?? 0
       }
@@ -620,44 +565,190 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     revalidate()
 
+    // ---- Press-drag commit-on-release ----
+    // When the move was engaged by the press-drag move cross (vs. click-to-
+    // place), commit on pointer-up instead of waiting for a click. Each surface
+    // move handler records how to commit at the current cursor; the release
+    // replays it. Captured once at setup — a fresh coordinator mounts per move.
+    const dragMode = useEditor.getState().placementDragMode
+    let releaseCommit: (() => void) | null = null
+    // Eat the click the browser fires after pointer-up so the surface
+    // `:click` handlers don't commit a second time.
+    const swallowNextClick = () => {
+      const swallow = (e: Event) => {
+        e.stopPropagation()
+        e.preventDefault()
+      }
+      window.addEventListener('click', swallow, { capture: true, once: true })
+      setTimeout(() => window.removeEventListener('click', swallow, { capture: true }), 300)
+    }
+    const onReleaseCommit = () => {
+      if (!releaseCommit) return
+      const commit = releaseCommit
+      releaseCommit = null
+      swallowNextClick()
+      commit()
+    }
+
     // ---- 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 onGridMove = (event: GridEvent) => {
+      releaseCommit = () => onGridClick(event)
       // Lazy draft creation: if no draft yet (e.g. level wasn't ready during init), create now
       if (draftNode.current === null && asset.attachTo === undefined) {
         configRef.current.initDraft(gridPosition.current)
       }
 
-      lastRawPos.current.set(event.localPosition[0], event.localPosition[1], event.localPosition[2])
-      const result = floorStrategy.move(getContext(), event)
+      has3DPointerDrivenMoveRef.current = true
+
+      // Shelf stickiness: while hosting on a shelf, ignore floor events while
+      // the cursor ray still points at the shelf volume (the ray merely slipped
+      // 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.
+      if (placementState.current.surface === 'shelf-surface') {
+        if (cursorRayIntersectsActiveShelf(event.position)) return
+        detachItemSurfaceToFloor(event as unknown as ItemEvent)
+      }
+
+      const floorEvent =
+        relativeFloorStart !== null
+          ? (() => {
+              const rawX = event.localPosition[0]
+              const rawZ = event.localPosition[2]
+              const anchor = floorDragAnchor ?? [rawX, rawZ]
+              floorDragAnchor = anchor
+              return {
+                ...event,
+                localPosition: [
+                  relativeFloorStart.x + (rawX - anchor[0]),
+                  event.localPosition[1],
+                  relativeFloorStart.z + (rawZ - anchor[1]),
+                ] as [number, number, number],
+              }
+            })()
+          : event
+
+      lastRawPos.current.set(
+        floorEvent.localPosition[0],
+        floorEvent.localPosition[1],
+        floorEvent.localPosition[2],
+      )
+      if (!cursorGroupRef.current) return
+      const result = floorStrategy.move(getContext(), floorEvent)
       if (!result) return
 
+      // Figma-style alignment snap layered on top of the floor strategy's
+      // grid snap: when the draft's edge lines up (on X or Z) with another
+      // item's edge, snap and publish a guide. The guide connects to the
+      // nearest real corner of the candidate (resolver tie-break), so the dot
+      // always sits on an actual point. The delta is applied to BOTH the grid
+      // and cursor positions below. Alt bypasses.
+      const draft = draftNode.current
+      let alignX = 0
+      let alignZ = 0
+      const bypassAlign = floorEvent.nativeEvent?.altKey === true
+      if (!bypassAlign && draft) {
+        alignmentCandidates ??= collectAlignmentAnchors(
+          useScene.getState().nodes,
+          draft.id,
+          useViewer.getState().selection.levelId,
+        )
+        const ar = resolveAlignmentForActiveBuilding({
+          moving: movingFootprintAnchors(
+            draft as unknown as AnyNode,
+            result.gridPosition[0],
+            result.gridPosition[2],
+            cursorGroupRef.current.rotation.y,
+          ),
+          candidates: alignmentCandidates,
+          threshold: ALIGNMENT_THRESHOLD_M,
+        })
+        if (ar.snap) {
+          alignX = ar.snap.dx
+          alignZ = ar.snap.dz
+        }
+        useAlignmentGuides.getState().set(ar.guides)
+      } else {
+        useAlignmentGuides.getState().clear()
+      }
+
+      const gridPos: [number, number, number] = [
+        result.gridPosition[0] + alignX,
+        result.gridPosition[1],
+        result.gridPosition[2] + alignZ,
+      ]
+
       // Play snap sound when grid position changes
       if (
         previousGridPos &&
-        (result.gridPosition[0] !== previousGridPos[0] ||
-          result.gridPosition[2] !== previousGridPos[2])
+        (gridPos[0] !== previousGridPos[0] || gridPos[2] !== previousGridPos[2])
       ) {
         sfxEmitter.emit('sfx:grid-snap')
       }
 
-      previousGridPos = [...result.gridPosition]
-      gridPosition.current.set(...result.gridPosition)
-      cursorGroupRef.current.position.set(
-        result.cursorPosition[0],
-        result.cursorPosition[1],
-        result.cursorPosition[2],
-      )
+      previousGridPos = [...gridPos]
+      gridPosition.current.set(...gridPos)
+      const cursorPosition = getFloorVisualPosition(gridPos)
+      cursorGroupRef.current.position.set(cursorPosition[0], cursorPosition[1], cursorPosition[2])
+      // Floor items only rotate on Y; keep the preview box (and the live
+      // transform the 2D floorplan mirrors) aligned with the draft's
+      // rotation. Without this the box stays at its seed rotation until a
+      // manual R/T, so a moved already-rotated item shows an axis-aligned box.
+      cursorGroupRef.current.rotation.y = result.cursorRotationY
 
-      const draft = draftNode.current
-      if (draft) draft.position = result.gridPosition
+      if (draft) draft.position = gridPos
 
       // Publish live transform for 2D floorplan
       if (draft) {
         useLiveTransforms.getState().set(draft.id, {
-          position: result.gridPosition,
+          position: gridPos,
           rotation: cursorGroupRef.current.rotation.y,
         })
       }
@@ -666,11 +757,18 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     }
 
     const onGridClick = (event: GridEvent) => {
+      // Drop alignment guides on click — the move commits (guides done) or
+      // placement re-arms (the next move republishes them).
+      useAlignmentGuides.getState().clear()
       const result = floorStrategy.click(getContext(), event, getActiveValidators())
       if (!result) return
 
       // Preserve cursor rotation for the next draft
-      const currentRotation: [number, number, number] = [0, cursorGroupRef.current.rotation.y, 0]
+      const currentRotation: [number, number, number] = [
+        0,
+        cursorGroupRef.current?.rotation.y ?? draftNode.current?.rotation[1] ?? 0,
+        0,
+      ]
 
       // Clear live transform before commit
       if (draftNode.current) {
@@ -680,6 +778,13 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       draftNode.commit(result.nodeUpdate)
       if (configRef.current.onCommitted()) {
         draftNode.create(gridPosition.current, asset, currentRotation)
+        const previewBounds = expandBoundsToGrid(
+          getFallbackPreviewBounds(draftNode.current, asset, asset.attachTo),
+          asset.attachTo,
+          gridSnapStep,
+        )
+        updatePreviewGeometry(previewBounds)
+        updateDimensionGuides(previewBounds)
         revalidate()
       }
     }
@@ -687,6 +792,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     // ---- Wall Handlers ----
 
     const onWallEnter = (event: WallEvent) => {
+      has3DPointerDrivenMoveRef.current = true
       const nodes = useScene.getState().nodes
       const result = wallStrategy.enter(
         getContext(),
@@ -712,6 +818,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     }
 
     const onWallMove = (event: WallEvent) => {
+      releaseCommit = () => onWallClick(event)
+      has3DPointerDrivenMoveRef.current = true
+      if (!cursorGroupRef.current) return
       const ctx = getContext()
 
       if (ctx.state.surface !== 'wall') {
@@ -800,7 +909,13 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         }
         // Mark parent wall dirty so it rebuilds geometry — only when position changed
         if (result.dirtyNodeId && posChanged) {
-          useScene.getState().dirtyNodes.add(result.dirtyNodeId)
+          const now = globalThis.performance?.now?.() ?? Date.now()
+          const last = lastWallDirtyAtRef.current.get(result.dirtyNodeId) ?? 0
+          // Wall rebuilds can trigger expensive CSG; throttle live previews to avoid FPS collapse.
+          if (now - last > 120) {
+            lastWallDirtyAtRef.current.set(result.dirtyNodeId, now)
+            useScene.getState().dirtyNodes.add(result.dirtyNodeId)
+          }
         }
 
         // Publish live transform for 2D floorplan
@@ -884,9 +999,20 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       const wz = Math.round(buildingLocalPoint.z * 2) / 2
       const floorPos: [number, number, number] = [wx, 0, wz]
 
-      Object.assign(placementState.current, { surface: 'floor', surfaceItemId: null })
+      Object.assign(placementState.current, {
+        surface: 'floor',
+        surfaceItemId: null,
+        shelfId: null,
+      })
       gridPosition.current.set(wx, 0, wz)
-      cursorGroupRef.current.position.set(wx, 0, wz)
+      const levelId = useViewer.getState().selection.levelId as AnyNodeId | null
+      const floorVisualPosition = getFloorVisualPosition(
+        floorPos,
+        levelId ? { parentId: levelId } : undefined,
+      )
+      if (cursorGroupRef.current) {
+        cursorGroupRef.current.position.set(...floorVisualPosition)
+      }
 
       const draft = draftNode.current
       if (draft) {
@@ -902,6 +1028,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     const onItemEnter = (event: ItemEvent) => {
       if (event.node.id === draftNode.current?.id) return
+      has3DPointerDrivenMoveRef.current = true
       const result = itemSurfaceStrategy.enter(getContext(), event)
       if (!result) return
 
@@ -918,6 +1045,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     const onItemMove = (event: ItemEvent) => {
       if (event.node.id === draftNode.current?.id) return
+      releaseCommit = () => onItemClick(event)
+      has3DPointerDrivenMoveRef.current = true
+      if (!cursorGroupRef.current) return
       const ctx = getContext()
 
       if (ctx.state.surface !== 'item-surface') {
@@ -1001,7 +1131,102 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     }
 
     const onItemClick = (event: ItemEvent) => {
-      if (event.node.id === draftNode.current?.id) 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*
+      // the host's mesh, so the host's `${kind}:click` never fires.
+      // If we're currently hosting on a shelf-surface, treat the
+      // 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()
+        if (ctx.state.surface === 'shelf-surface' && ctx.state.shelfId) {
+          const shelfNode = useScene.getState().nodes[ctx.state.shelfId as AnyNodeId]
+          if (shelfNode && shelfNode.type === 'shelf') {
+            const synthetic = { ...event, node: shelfNode } as unknown as ItemEvent
+            const result = shelfSurfaceStrategy.click(ctx, synthetic as never)
+            if (result) {
+              event.stopPropagation()
+              if (draftNode.current) {
+                useLiveTransforms.getState().clear(draftNode.current.id)
+              }
+              draftNode.commit(result.nodeUpdate)
+              if (configRef.current.onCommitted()) {
+                const enterResult = shelfSurfaceStrategy.enter(ctx, synthetic as never)
+                if (enterResult) {
+                  applyTransition(enterResult)
+                } else {
+                  revalidate()
+                }
+              }
+              return
+            }
+          }
+        }
+        // Same self-click forwarding for item-surface hosts (tables,
+        // counters) — the draft mesh sits on top of the host mesh, so
+        // 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') {
+            const synthetic = { ...event, node: hostNode } as ItemEvent
+            const result = itemSurfaceStrategy.click(ctx, synthetic)
+            if (result) {
+              event.stopPropagation()
+              if (draftNode.current) {
+                useLiveTransforms.getState().clear(draftNode.current.id)
+              }
+              draftNode.commit(result.nodeUpdate)
+              if (configRef.current.onCommitted()) {
+                const enterResult = itemSurfaceStrategy.enter(ctx, synthetic)
+                if (enterResult) {
+                  applyTransition(enterResult)
+                } else {
+                  revalidate()
+                }
+              }
+              return
+            }
+          }
+        }
+        // Ceiling-hosted draft: when placing a ceiling-attached item the
+        // draft hangs below the ceiling and intercepts the click ray
+        // before the ceiling-grid mesh does — so `ceiling:click` never
+        // fires and the user's commit click is dropped. Forward the
+        // self-click to `ceilingStrategy.click` so placement commits the
+        // same way it would from a click on the ceiling itself.
+        if (ctx.state.surface === 'ceiling' && ctx.state.ceilingId) {
+          const ceilingNode = useScene.getState().nodes[ctx.state.ceilingId as AnyNodeId]
+          if (ceilingNode && ceilingNode.type === 'ceiling') {
+            const synthetic = { ...event, node: ceilingNode } as unknown as CeilingEvent
+            const result = ceilingStrategy.click(ctx, synthetic, getActiveValidators())
+            if (result) {
+              event.stopPropagation()
+              if (draftNode.current) {
+                useLiveTransforms.getState().clear(draftNode.current.id)
+              }
+              draftNode.commit(result.nodeUpdate)
+              if (configRef.current.onCommitted()) {
+                const nodes = useScene.getState().nodes
+                const enterResult = ceilingStrategy.enter(
+                  getContext(),
+                  synthetic,
+                  resolveLevelId,
+                  nodes,
+                )
+                if (enterResult) {
+                  applyTransition(enterResult)
+                } else {
+                  revalidate()
+                }
+              }
+              return
+            }
+          }
+        }
+        return
+      }
+
       const result = itemSurfaceStrategy.click(getContext(), event)
       if (!result) return
 
@@ -1026,6 +1251,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     // ---- Ceiling Handlers ----
 
     const onCeilingEnter = (event: CeilingEvent) => {
+      has3DPointerDrivenMoveRef.current = true
       const nodes = useScene.getState().nodes
       const result = ceilingStrategy.enter(getContext(), event, resolveLevelId, nodes)
       if (!result) return
@@ -1045,6 +1271,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     }
 
     const onCeilingMove = (event: CeilingEvent) => {
+      releaseCommit = () => onCeilingClick(event)
+      has3DPointerDrivenMoveRef.current = true
+      if (!cursorGroupRef.current) return
       if (!draftNode.current && placementState.current.surface === 'ceiling') {
         const nodes = useScene.getState().nodes
         const setup = ceilingStrategy.enter(getContext(), event, resolveLevelId, nodes)
@@ -1083,9 +1312,15 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         const mesh = sceneRegistry.nodes.get(draft.id)
         if (mesh) mesh.position.copy(gridPosition.current)
 
-        // Publish live transform for 2D floorplan
+        // Publish live transform for 2D floorplan. The item override in
+        // `floorplan-registry-layer` treats `live.position` as building-local
+        // plan coords (parentId forced to null so the resolver renders it
+        // directly), so publish the building-local cursor — not the
+        // world-space `result.cursorPosition`, which otherwise lands the 2D
+        // visual off the cursor whenever the building isn't at the origin
+        // with zero rotation.
         useLiveTransforms.getState().set(draft.id, {
-          position: result.cursorPosition,
+          position: [cc.x, cc.y, cc.z],
           rotation: cursorGroupRef.current.rotation.y,
         })
       }
@@ -1143,9 +1378,112 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       }
     }
 
+    // ---- Shelf Handlers ----
+    //
+    // Items can host on shelves the same way they host on tables and
+    // counters (item-surface). The shelf's `surfaces.custom` exposes one
+    // candidate Y per row; `shelfSurfaceStrategy` picks the closest one
+    // to the cursor's local-Y so the user can target a specific row.
+
+    const onShelfEnter = (event: ShelfEvent) => {
+      has3DPointerDrivenMoveRef.current = true
+      const result = shelfSurfaceStrategy.enter(getContext(), event)
+      if (!result) return
+
+      event.stopPropagation()
+      applyTransition(result)
+
+      if (!draftNode.current) {
+        ensureDraft(result)
+      } else if (result.nodeUpdate.parentId) {
+        useScene.getState().updateNode(draftNode.current.id, result.nodeUpdate)
+      }
+    }
+
+    const onShelfMove = (event: ShelfEvent) => {
+      releaseCommit = () => onShelfClick(event)
+      has3DPointerDrivenMoveRef.current = true
+      // 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()
+      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
+        // in to start hosting.
+        const enterResult = shelfSurfaceStrategy.enter(ctx, event)
+        if (!enterResult) return
+        event.stopPropagation()
+        applyTransition(enterResult)
+        if (!draftNode.current) {
+          ensureDraft(enterResult)
+        } else if (enterResult.nodeUpdate.parentId) {
+          useScene.getState().updateNode(draftNode.current.id, enterResult.nodeUpdate)
+        }
+        return
+      }
+      const result = shelfSurfaceStrategy.move(ctx, event)
+      if (!result) return
+
+      event.stopPropagation()
+
+      gridPosition.current.set(...result.gridPosition)
+      const ic = worldToBuildingLocal(...result.cursorPosition)
+      cursorGroupRef.current.position.set(ic.x, ic.y, ic.z)
+      cursorGroupRef.current.rotation.y = result.cursorRotationY
+
+      const draft = draftNode.current
+      if (draft) {
+        draft.position = result.gridPosition
+        const mesh = sceneRegistry.nodes.get(draft.id)
+        if (mesh) mesh.position.set(...result.gridPosition)
+        useLiveTransforms.getState().set(draft.id, {
+          position: result.cursorPosition,
+          rotation: result.cursorRotationY,
+        })
+      }
+
+      revalidate()
+    }
+
+    const onShelfLeave = (event: ShelfEvent) => {
+      if (placementState.current.surface !== 'shelf-surface') return
+      if (event.node.id !== placementState.current.shelfId) return
+      // Intentionally do NOT detach to the floor here. `shelf:leave` fires
+      // constantly while hosting because the cursor ray slips off the shelf's
+      // thin boards and through its gaps — detaching on each of those would
+      // thrash the item between the shelf row and the floor. The grid handler
+      // owns the real shelf→floor transition (see `isOverActiveShelfFootprint`
+      // in `onGridMove`): it detaches only once the cursor is clearly off the
+      // shelf footprint, which is the genuine "left the shelf" signal.
+      event.stopPropagation()
+    }
+
+    const onShelfClick = (event: ShelfEvent) => {
+      const result = shelfSurfaceStrategy.click(getContext(), event)
+      if (!result) return
+
+      event.stopPropagation()
+      if (draftNode.current) {
+        useLiveTransforms.getState().clear(draftNode.current.id)
+      }
+      draftNode.commit(result.nodeUpdate)
+
+      if (configRef.current.onCommitted()) {
+        const enterResult = shelfSurfaceStrategy.enter(getContext(), event)
+        if (enterResult) {
+          applyTransition(enterResult)
+        } else {
+          revalidate()
+        }
+      }
+    }
+
     // ---- Keyboard rotation ----
 
-    const ROTATION_STEP = Math.PI / 2
+    // 45° increments — matches the R-key rotation step for already-placed
+    // items (use-keyboard.ts) so the ghost/duplicate rotates the same way.
+    const ROTATION_STEP = Math.PI / 4
     const onKeyDown = (event: KeyboardEvent) => {
       if (event.key === 'Shift') {
         shiftFreeRef.current = true
@@ -1175,7 +1513,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         draft.rotation = [currentRotation[0], newRotationY, currentRotation[2]]
 
         // Ref + cursor mesh + item mesh — no store update during drag
-        cursorGroupRef.current.rotation.y = newRotationY
+        if (cursorGroupRef.current) {
+          cursorGroupRef.current.rotation.y = newRotationY
+        }
         const mesh = sceneRegistry.nodes.get(draft.id)
         if (mesh) mesh.rotation.y = newRotationY
 
@@ -1189,11 +1529,22 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
           const z = snapToGrid(lastRawPos.current.z, swapDims ? dimX : dimZ)
           gridPosition.current.set(x, gridPosition.current.y, z)
           draft.position = [x, gridPosition.current.y, z]
-          cursorGroupRef.current.position.x = x
-          cursorGroupRef.current.position.z = z
+          if (cursorGroupRef.current) {
+            if (surface === 'floor') {
+              cursorGroupRef.current.position.set(
+                ...getFloorVisualPosition([x, gridPosition.current.y, z]),
+              )
+            } else {
+              cursorGroupRef.current.position.x = x
+              cursorGroupRef.current.position.z = z
+            }
+          }
           if (mesh) {
             mesh.position.x = x
             mesh.position.z = z
+            if (surface === 'floor') {
+              mesh.position.y = getFloorVisualPosition([x, gridPosition.current.y, z])[1]
+            }
           }
         } else if (surface === 'item-surface' && placementState.current.surfaceItemId) {
           const surfaceMesh = sceneRegistry.nodes.get(placementState.current.surfaceItemId)
@@ -1213,7 +1564,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
               worldSnapped.y,
               worldSnapped.z,
             )
-            cursorGroupRef.current.position.set(localSnapped.x, localSnapped.y, localSnapped.z)
+            if (cursorGroupRef.current) {
+              cursorGroupRef.current.position.set(localSnapped.x, localSnapped.y, localSnapped.z)
+            }
             if (mesh) mesh.position.set(x, y, z)
           }
         }
@@ -1221,13 +1574,19 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         // Update live transform for 2D floorplan with post-snap position
         const currentLive = useLiveTransforms.getState().get(draft.id)
         if (currentLive) {
+          const livePosition: [number, number, number] =
+            surface === 'floor'
+              ? [draft.position[0], draft.position[1], draft.position[2]]
+              : cursorGroupRef.current
+                ? [
+                    cursorGroupRef.current.position.x,
+                    cursorGroupRef.current.position.y,
+                    cursorGroupRef.current.position.z,
+                  ]
+                : [draft.position[0], draft.position[1], draft.position[2]]
           useLiveTransforms.getState().set(draft.id, {
             ...currentLive,
-            position: [
-              cursorGroupRef.current.position.x,
-              cursorGroupRef.current.position.y,
-              cursorGroupRef.current.position.z,
-            ] as [number, number, number],
+            position: livePosition,
             rotation: newRotationY,
           })
         }
@@ -1248,6 +1607,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     // ---- tool:cancel (Escape / programmatic) ----
     const onCancel = () => {
+      useAlignmentGuides.getState().clear()
       if (configRef.current.onCancel) {
         configRef.current.onCancel()
       }
@@ -1264,21 +1624,17 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     window.addEventListener('contextmenu', onContextMenu)
 
     // ---- Bounding box geometry ----
+    // Always derive the wireframe from `asset.dimensions × scale` rather than
+    // the rendered mesh bounds. Asset dimensions describe the item's footprint
+    // (e.g. only the trunk for a palm tree), while the mesh bbox would include
+    // foliage or other visual overhang the snap logic intentionally ignores.
 
     const draft = draftNode.current
-    const fallbackBounds = expandBoundsToGrid(
+    const previewBounds = expandBoundsToGrid(
       getFallbackPreviewBounds(draft, asset, asset.attachTo),
       asset.attachTo,
       gridSnapStep,
     )
-    const previewBounds = draft
-      ? expandBoundsToGrid(
-          getPreviewBoundsFromObject(sceneRegistry.nodes.get(draft.id) ?? null) ??
-            getFallbackPreviewBounds(draft, asset, asset.attachTo),
-          asset.attachTo,
-          gridSnapStep,
-        )
-      : fallbackBounds
     updatePreviewGeometry(previewBounds)
     updateDimensionGuides(previewBounds)
 
@@ -1321,11 +1677,17 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     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)
+    if (dragMode) window.addEventListener('pointerup', onReleaseCommit)
 
     return () => {
       tearingDown = true
-      meshPreviewAppliedRef.current = false
+      if (dragMode) window.removeEventListener('pointerup', onReleaseCommit)
       unsubDraftWatch()
+      useAlignmentGuides.getState().clear()
       // Clear live transform for any remaining draft
       if (draftNode.current) {
         useLiveTransforms.getState().clear(draftNode.current.id)
@@ -1346,32 +1708,40 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       emitter.off('ceiling:move', onCeilingMove)
       emitter.off('ceiling:click', onCeilingClick)
       emitter.off('ceiling:leave', onCeilingLeave)
+      emitter.off('shelf:enter', onShelfEnter)
+      emitter.off('shelf:move', onShelfMove)
+      emitter.off('shelf:click', onShelfClick)
+      emitter.off('shelf:leave', onShelfLeave)
       emitter.off('tool:cancel', onCancel)
       window.removeEventListener('keydown', onKeyDown)
       window.removeEventListener('keyup', onKeyUp)
       window.removeEventListener('contextmenu', onContextMenu)
     }
-  }, [asset, canPlaceOnFloor, canPlaceOnWall, canPlaceOnCeiling, draftNode])
+  }, [
+    asset,
+    canPlaceOnFloor,
+    canPlaceOnWall,
+    canPlaceOnCeiling,
+    draftNode,
+    getFloorVisualPosition,
+    gridSnapStep,
+    updateDimensionGuides,
+    updatePreviewGeometry,
+  ])
 
   // Refresh wireframe when the grid step changes mid-placement so the green/red
   // box snaps to the new cell size right away.
   useEffect(() => {
     if (!asset) return
     const draft = draftNode.current
-    const fallbackBounds = expandBoundsToGrid(
+    const previewBounds = expandBoundsToGrid(
       getFallbackPreviewBounds(draft, asset, asset.attachTo),
       asset.attachTo,
       gridSnapStep,
     )
-    const meshBounds = draft
-      ? getPreviewBoundsFromObject(sceneRegistry.nodes.get(draft.id) ?? null)
-      : null
-    const previewBounds = meshBounds
-      ? expandBoundsToGrid(meshBounds, asset.attachTo, gridSnapStep)
-      : fallbackBounds
     updatePreviewGeometry(previewBounds)
     updateDimensionGuides(previewBounds)
-  }, [gridSnapStep, asset, draftNode])
+  }, [gridSnapStep, asset, draftNode, updateDimensionGuides, updatePreviewGeometry])
   // Wall/ceiling items are managed by their own surface entry events (ensureDraft / reparent).
   const viewerLevelId = useViewer((s) => s.selection.levelId)
   useEffect(() => {
@@ -1383,24 +1753,59 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     useScene.getState().updateNode(draft.id as AnyNodeId, { parentId: viewerLevelId })
   }, [viewerLevelId, draftNode, asset])
 
-  useFrame((_, delta) => {
-    if (!asset) return
-    if (!draftNode.current) return
-    const mesh = sceneRegistry.nodes.get(draftNode.current.id)
+  // Disable raycasting on the live draft mesh (and restore it when the draft
+  // changes or goes away) so the cursor ray passes through the item being
+  // moved and lands on the surface beneath it.
+  const reconcileDraftRaycast = useCallback((mesh: Object3D | null) => {
+    if (raycastDisabledMeshRef.current !== mesh) {
+      // New draft root (or cleared): restore the prior mesh and reset tracking.
+      for (const restore of restoreRaycastsRef.current) restore()
+      restoreRaycastsRef.current = []
+      raycastDisabledChildrenRef.current = new WeakSet()
+      raycastDisabledMeshRef.current = mesh
+    }
     if (!mesh) return
-    if (!meshPreviewAppliedRef.current) {
-      const previewBounds = getPreviewBoundsFromObject(mesh)
-      if (previewBounds) {
-        const expandedBounds = expandBoundsToGrid(
-          previewBounds,
-          asset.attachTo,
-          useEditor.getState().gridSnapStep,
-        )
-        updatePreviewGeometry(expandedBounds)
-        updateDimensionGuides(expandedBounds)
-        meshPreviewAppliedRef.current = true
-      }
+    // Disable any descendant not handled yet. Item drafts are GLB models whose
+    // child meshes mount asynchronously (Suspense), so a one-shot traverse
+    // misses them — those late children keep intercepting the ray and corrupt
+    // the shelf-row hit the moment the item moves onto a row. Re-walking each
+    // frame is cheap: the WeakSet makes it idempotent, so only new children pay.
+    mesh.traverse((child) => {
+      if (raycastDisabledChildrenRef.current.has(child)) return
+      raycastDisabledChildrenRef.current.add(child)
+      const original = child.raycast
+      child.raycast = () => {}
+      restoreRaycastsRef.current.push(() => {
+        child.raycast = original
+      })
+    })
+  }, [])
+
+  // Restore the draft mesh's raycast when the coordinator unmounts (tool change).
+  useEffect(() => () => reconcileDraftRaycast(null), [reconcileDraftRaycast])
+
+  useFrame((_, delta) => {
+    if (!asset) {
+      reconcileDraftRaycast(null)
+      return
+    }
+    if (!draftNode.current) {
+      reconcileDraftRaycast(null)
+      return
     }
+    const mesh = sceneRegistry.nodes.get(draftNode.current.id) ?? null
+    reconcileDraftRaycast(mesh)
+    // mitt listeners outlive the cursor group's mount; bail if it's gone
+    // (mount/teardown race, #323). Placed after reconcileDraftRaycast so the
+    // draft's raycast is still restored during that window.
+    if (!cursorGroupRef.current) return
+    // The mesh-position lerp below only makes sense once this coordinator
+    // owns the move via a 3D pointer event. Skip until then so that
+    // external drivers (e.g. the 2D `FloorplanRegistryMoveOverlay`
+    // writing scene.position directly) aren't fought by useFrame pulling
+    // the mesh back to its pre-move location.
+    if (!has3DPointerDrivenMoveRef.current) return
+    if (!mesh) return
 
     // Hide wall/ceiling-attached items when between surfaces (only cursor visible)
     if (asset.attachTo && placementState.current.surface === 'floor') {
@@ -1419,18 +1824,13 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
       // Adjust Y for slab elevation (floor items on top of slabs)
       if (!asset.attachTo) {
-        const nodes = useScene.getState().nodes
-        const levelId = resolveLevelId(draftNode.current, nodes)
-        const slabElevation = spatialGridManager.getSlabElevationForItem(
-          levelId,
-          [gridPosition.current.x, gridPosition.current.y, gridPosition.current.z],
-          getGridAlignedDimensions(
-            getScaledDimensions(draftNode.current),
-            draftNode.current.asset.attachTo,
-          ),
-          draftNode.current.rotation,
-        )
-        mesh.position.y = slabElevation
+        const visualPosition = getFloorVisualPosition([
+          gridPosition.current.x,
+          gridPosition.current.y,
+          gridPosition.current.z,
+        ])
+        mesh.position.y = visualPosition[1]
+        cursorGroupRef.current.position.y = visualPosition[1]
       }
     }
   })
@@ -1443,7 +1843,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
   const dims = getGridAlignedDimensions(rawDims, initialAttachTo, gridSnapStep)
   const wallSideZOffset = initialAttachTo === 'wall-side' ? -dims[2] / 2 : 0
   const initialDimensionBounds = expandBoundsToGrid(
-    getFallbackPreviewBounds(initialDraft, config.asset!, initialAttachTo),
+    getFallbackPreviewBounds(initialDraft, config.asset, initialAttachTo),
     initialAttachTo,
     gridSnapStep,
   )
@@ -1456,6 +1856,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       initialDimensionBounds.dimensions[0],
       initialDimensionBounds.dimensions[1],
       initialDimensionBounds.dimensions[2],
+      initialDimensionBounds,
     ],
   )
   const basePlaneGeometry = useMemo(() => {
@@ -1490,22 +1891,22 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
   const measurementContent = (
     <>
       <lineSegments
-        layers={EDITOR_LAYER}
         geometry={initialWidthGuideGeometry}
+        layers={EDITOR_LAYER}
         material={measurementMaterial}
         ref={measurementWidthRef}
         renderOrder={998}
       />
       <lineSegments
-        layers={EDITOR_LAYER}
         geometry={initialDepthGuideGeometry}
+        layers={EDITOR_LAYER}
         material={measurementMaterial}
         ref={measurementDepthRef}
         renderOrder={998}
       />
       <lineSegments
-        layers={EDITOR_LAYER}
         geometry={initialHeightGuideGeometry}
+        layers={EDITOR_LAYER}
         material={measurementMaterial}
         ref={measurementHeightRef}
         renderOrder={998}