@pascal-app/editor 1.0.0-beta.4 → 1.0.0

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

@@ -6,14 +6,19 @@ import {
   type CeilingEvent,
   collectAlignmentAnchors,
   emitter,
+  findLevelAncestorId,
   type GridEvent,
   getScaledDimensions,
   type ItemEvent,
   movingFootprintAnchors,
+  type NodeEvent,
+  nodeRegistry,
   type RoofEvent,
+  resolveFrozenFloorPlacementPatch,
   resolveLevelId,
   type ShelfEvent,
   sceneRegistry,
+  useLiveNodeOverrides,
   useLiveTransforms,
   useScene,
   useSpatialQuery,
@@ -55,6 +60,7 @@ import useAlignmentGuides from '../../../store/use-alignment-guides'
 import useEditor, { isAlignmentGuideActive, isMagneticSnapActive } from '../../../store/use-editor'
 
 import useFacingPose from '../../../store/use-facing-pose'
+import usePlacementPreview from '../../../store/use-placement-preview'
 import { getFloorStackPreviewPosition } from '../shared/floor-stack-preview'
 import {
   createLineGeometry,
@@ -63,9 +69,17 @@ import {
   updateLineGeometry,
 } from '../shared/placement-box-geometry'
 import {
+  type PointerSupportSurface,
   resolvePointerSupportElevation,
   resolvePointerSupportSurface,
 } from '../shared/pointer-support-cap'
+import { shouldCreateFloorDraft } from './draft-creation'
+import { commitFaceHostClick, resolveFaceHostPreviewCommit } from './face-host-commit'
+import {
+  applyFaceHostPreviewPose,
+  resolveFaceHostSwitch,
+  shouldDetachFaceHostOnLeave,
+} from './face-host-preview'
 import {
   getDetachedAttachmentPreviewLift,
   getGridAlignedDimensions,
@@ -77,12 +91,14 @@ import {
 import {
   ceilingStrategy,
   checkCanPlace,
+  faceHostStrategy,
   floorStrategy,
   itemSurfaceStrategy,
   roofWallStrategy,
   shelfSurfaceStrategy,
   wallStrategy,
 } from './placement-strategies'
+import { resolveItemPlacementSurfaceNormal } from './placement-surface'
 import type { PlacementState, TransitionResult } from './placement-types'
 import type { DraftNodeHandle } from './use-draft-node'
 
@@ -178,6 +194,27 @@ function getGridAlignedPreviewNode(item: ItemNode): ItemNode {
   }
 }
 
+/**
+ * Building-local Y of the storey the floor-path ghost belongs to.
+ *
+ * The cursor group is mounted inside ToolManager's building-local group, which
+ * carries no per-floor elevation, while every floor-path position (grid
+ * position, `getFloorVisualPosition`) is LEVEL-local — so on an upper storey the
+ * wireframe and its dimension labels render a floor too low. The wall / ceiling
+ * / item-surface paths don't need this: they convert a world hit through
+ * `worldToBuildingLocal`, which already carries the storey.
+ *
+ * Read off the level mesh (same source as `LevelOffsetGroup`) rather than the
+ * stored elevation so the ghost also follows the exploded-view lerp.
+ */
+function getPlacementLevelY(draft: ItemNode | null | undefined): number {
+  const levelId =
+    (draft ? findLevelAncestorId(draft.id, useScene.getState().nodes) : null) ??
+    useViewer.getState().selection.levelId
+  const levelMesh = levelId ? sceneRegistry.nodes.get(levelId as AnyNodeId) : null
+  return levelMesh ? levelMesh.position.y : 0
+}
+
 // Shared materials for placement cursor - we just change colors, not swap materials
 // Note: EdgesGeometry doesn't work with dashed lines, so using solid lines
 const edgeMaterial = new LineBasicNodeMaterial({
@@ -280,6 +317,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
   // by the MAX overlapping slab and a deck above the aimed-at floor
   // captures the item (and the grid-plane feedback makes it blink).
   const pointerSupportCapRef = useRef<number | null>(null)
+  const pointerSupportSurfaceRef = useRef<PointerSupportSurface | null>(null)
+  const frozenSupportSlabIdRef = useRef<string | undefined>(undefined)
   const [dimensionBounds, setDimensionBounds] = useState<PreviewBounds | null>(null)
 
   // Live camera ref — the shelf-stickiness test reconstructs the cursor world
@@ -295,6 +334,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
   const { canPlaceOnFloor, canPlaceOnWall, canPlaceOnCeiling } = useSpatialQuery()
   const { asset, draftNode } = config
   const unit = useViewer((state) => state.unit)
+  const metricNotation = useViewer((state) => state.metricNotation)
   const gridSnapStep = useEditor((s) => s.gridSnapStep)
   const updatePreviewGeometry = useCallback((bounds: PreviewBounds) => {
     const [width, height, depth] = bounds.dimensions
@@ -426,17 +466,50 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     ): [number, number, number] => {
       const draft = draftNode.current
       if (!(draft && !asset?.attachTo)) return position
-      const previewNode = getGridAlignedPreviewNode({ ...draft, ...nodeUpdate } as ItemNode)
+      const previewNode = getGridAlignedPreviewNode({
+        ...draft,
+        ...nodeUpdate,
+        ...(pointerSupportSurfaceRef.current?.sourceNodeId
+          ? { supportSlabId: frozenSupportSlabIdRef.current }
+          : {}),
+      } as ItemNode)
       return getFloorStackPreviewPosition({
         node: previewNode,
         position,
         rotation: previewNode.rotation,
-        maxElevation: pointerSupportCapRef.current,
+        maxElevation: pointerSupportSurfaceRef.current?.sourceNodeId
+          ? null
+          : pointerSupportCapRef.current,
       })
     },
     [asset?.attachTo, draftNode],
   )
 
+  // 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
+    // Item models can mount descendants asynchronously. Re-walk the root so
+    // newly mounted meshes cannot intercept the next pointer event.
+    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
+      })
+    })
+  }, [])
+
   useEffect(() => {
     if (!asset) return
     useScene.temporal.getState().pause()
@@ -451,6 +524,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     // layer's frame.
     let alignmentCandidates: AlignmentAnchor[] | null = null
     let floorDragAnchor: [number, number] | null = null
+    let pendingFaceHostId: string | null = null
 
     // Reset placement state
     placementState.current = configRef.current.initialState ?? {
@@ -464,10 +538,12 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     // No pointer surface known yet — fall back to the uncapped election
     // (an adopted move draft keeps its persisted host until the first move).
     pointerSupportCapRef.current = null
+    pointerSupportSurfaceRef.current = null
+    frozenSupportSlabIdRef.current = undefined
     if (!asset.attachTo && placementState.current.surface === 'floor') {
       gridPosition.current.y = 0
       if (cursorGroupRef.current) {
-        cursorGroupRef.current.position.y = 0
+        cursorGroupRef.current.position.y = getPlacementLevelY(draftNode.current)
       }
     }
 
@@ -492,6 +568,13 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
           }
         : validators
 
+    const disableDraftRaycastNow = () => {
+      const draft = draftNode.current
+      if (!draft) return
+      const mesh = sceneRegistry.nodes.get(draft.id)
+      if (mesh) reconcileDraftRaycast(mesh)
+    }
+
     const finishCommittedPlacement = (
       committedId: string | null,
       wasAdopted: boolean,
@@ -516,6 +599,40 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       useEditor.getState().setMode('select')
     }
 
+    const commitDraft = (
+      nodeUpdate: Partial<ItemNode>,
+      options?: {
+        supportElevationCap?: number | null
+        preferredSupportSlabId?: string | null
+        pinSupport?: boolean
+      },
+    ) => {
+      const draftId = draftNode.current?.id ?? null
+      const wasAdopted = draftNode.isAdopted
+      const finalId = draftNode.commit(nodeUpdate, options)
+      if (draftId) {
+        useLiveTransforms.getState().clear(draftId)
+        useLiveNodeOverrides.getState().clearFields(draftId, faceHostClearFields(draftNode.current))
+      }
+      return { committedId: finalId ?? draftId, wasAdopted }
+    }
+
+    const faceHostClearFields = (draft: ItemNode | null | undefined): Array<keyof ItemNode> => {
+      if (!draft?.parentId) return ['position', 'rotation']
+      const host = useScene.getState().nodes[draft.parentId as AnyNodeId]
+      return host
+        ? [...(nodeRegistry.get(host.type)?.capabilities.faceHost?.clearItemFields ?? [])]
+        : ['position', 'rotation']
+    }
+
+    const currentFaceHostId = (draft: ItemNode | null | undefined): string | null => {
+      if (!draft?.parentId) return null
+      const host = useScene.getState().nodes[draft.parentId as AnyNodeId]
+      return host
+        ? (nodeRegistry.get(host.type)?.capabilities.faceHost?.currentFaceId(draft) ?? null)
+        : null
+    }
+
     const revalidate = (): boolean => {
       const placeable = altFreeRef.current || checkCanPlace(getContext(), validators)
       const color = placeable ? 0x22_c5_5e : 0xef_44_44 // green-500 : red-500
@@ -539,6 +656,21 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       return buildingMesh ? buildingMesh.localToWorld(new Vector3(x, y, z)) : new Vector3(x, y, z)
     }
 
+    const worldRotationToBuildingLocal = (
+      rotation: [number, number, number],
+    ): [number, number, number] => {
+      const worldQuaternion = new Quaternion().setFromEuler(new Euler(...rotation))
+      const buildingId = useViewer.getState().selection.buildingId
+      const buildingMesh = buildingId ? sceneRegistry.nodes.get(buildingId as AnyNodeId) : null
+      if (buildingMesh) {
+        const buildingWorldQuaternion = new Quaternion()
+        buildingMesh.getWorldQuaternion(buildingWorldQuaternion)
+        worldQuaternion.premultiply(buildingWorldQuaternion.invert())
+      }
+      const localRotation = new Euler().setFromQuaternion(worldQuaternion, 'XYZ')
+      return [localRotation.x, localRotation.y, localRotation.z]
+    }
+
     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).
@@ -554,7 +686,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (cursorGroupRef.current) {
         cursorGroupRef.current.position.set(c.x, c.y, c.z)
         if (result.cursorRotation) {
-          cursorGroupRef.current.rotation.set(...result.cursorRotation)
+          cursorGroupRef.current.rotation.set(
+            ...worldRotationToBuildingLocal(result.cursorRotation),
+          )
         } else {
           cursorGroupRef.current.rotation.set(0, result.cursorRotationY, 0)
         }
@@ -574,7 +708,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (cursorGroupRef.current) {
         cursorGroupRef.current.position.set(c.x, c.y, c.z)
         if (result.cursorRotation) {
-          cursorGroupRef.current.rotation.set(...result.cursorRotation)
+          cursorGroupRef.current.rotation.set(
+            ...worldRotationToBuildingLocal(result.cursorRotation),
+          )
         } else {
           cursorGroupRef.current.rotation.set(0, result.cursorRotationY, 0)
         }
@@ -599,6 +735,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         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)
+        disableDraftRaycastNow()
       }
 
       const previewBounds = expandBoundsToGrid(
@@ -774,7 +911,10 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
           }
         }
       } else if (cursorGroupRef.current) {
+        // No registered mesh yet (a just-created draft renders next tick), so
+        // fall back to the level-local grid position lifted onto its storey.
         cursorGroupRef.current.position.copy(gridPosition.current)
+        cursorGroupRef.current.position.y += getPlacementLevelY(draftNode.current)
         cursorGroupRef.current.rotation.y = draftNode.current.rotation[1] ?? 0
       }
     }
@@ -857,7 +997,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     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) {
+      if (
+        shouldCreateFloorDraft(draftNode.current, asset.attachTo, placementState.current.surface)
+      ) {
         configRef.current.initDraft(gridPosition.current)
       }
 
@@ -874,6 +1016,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       // a drag over a deck-above-a-floor hop between the two surfaces).
       const pointed = resolvePointerSupportSurface(cameraRef.current, event.position)
       pointerSupportCapRef.current = pointed?.elevation ?? null
+      pointerSupportSurfaceRef.current = pointed
       const surfaceEvent: GridEvent =
         pointed?.worldPoint && pointed.localPoint
           ? { ...event, position: pointed.worldPoint, localPosition: pointed.localPoint }
@@ -945,11 +1088,37 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         useAlignmentGuides.getState().clear()
       }
 
-      const gridPos: [number, number, number] = [
+      // `result.gridPosition[1]` is the LIVE `gridPosition.current.y` — seeded
+      // from the draft's authored Y by `initDraft` (so a block-face / raised
+      // construction-plane item keeps its height) and zeroed by
+      // `detachItemSurfaceToFloor` / `faceHostStrategy.leave` when the item
+      // comes back down. Freezing it at drag start instead left an item taken
+      // off a shelf floating at the shelf's height.
+      let gridPos: [number, number, number] = [
         result.gridPosition[0] + alignX,
         result.gridPosition[1],
         result.gridPosition[2] + alignZ,
       ]
+      frozenSupportSlabIdRef.current = undefined
+      if (draft && pointed?.sourceNodeId) {
+        const effectiveNode = {
+          ...draft,
+          position: gridPos,
+          parentId: useViewer.getState().selection.levelId ?? draft.parentId,
+        } as ItemNode
+        const frozenPatch = resolveFrozenFloorPlacementPatch(
+          effectiveNode,
+          useScene.getState().nodes,
+          {
+            position: gridPos,
+            rotation: effectiveNode.rotation,
+            elevation: pointed.elevation,
+            preferredSlabId: pointed.supportSlabId,
+          },
+        )
+        gridPos = frozenPatch.position
+        frozenSupportSlabIdRef.current = frozenPatch.supportSlabId
+      }
 
       // Play snap sound when grid position changes
       if (
@@ -965,7 +1134,11 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (!draft && asset.attachTo) {
         cursorPosition[1] += getDetachedAttachmentPreviewLift(asset.attachTo)
       }
-      cursorGroupRef.current.position.set(cursorPosition[0], cursorPosition[1], cursorPosition[2])
+      cursorGroupRef.current.position.set(
+        cursorPosition[0],
+        cursorPosition[1] + getPlacementLevelY(draft),
+        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
@@ -1001,20 +1174,15 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         0,
       ]
 
-      // Clear live transform before commit
-      if (draftNode.current) {
-        useLiveTransforms.getState().clear(draftNode.current.id)
-      }
-
-      const committedId = draftNode.current?.id ?? null
-      const wasAdopted = draftNode.isAdopted
       // Carry the pointer surface cap into the commit so the persisted
       // supportSlabId reproduces the capped election (elects the aimed-at
       // lower slab — or the ground — instead of a deck hanging above).
-      const finalId = draftNode.commit(result.nodeUpdate, {
+      const { committedId, wasAdopted } = commitDraft(result.nodeUpdate, {
         supportElevationCap: pointerSupportCapRef.current,
+        preferredSupportSlabId: pointerSupportSurfaceRef.current?.supportSlabId,
+        pinSupport: pointerSupportSurfaceRef.current?.sourceNodeId != null,
       })
-      finishCommittedPlacement(finalId ?? committedId, wasAdopted, () => {
+      finishCommittedPlacement(committedId, wasAdopted, () => {
         draftNode.create(
           gridPosition.current,
           asset,
@@ -1129,19 +1297,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         }
         const correctedX = wallDragAnchor.startX + (rawX - wallDragAnchor.rawX)
         const correctedY = wallDragAnchor.startY + (rawY - wallDragAnchor.rawY)
-        const wallMesh = sceneRegistry.nodes.get(event.node.id)
-        // Derive the world cursor from the corrected wall-local point so the
-        // visual cursor (world) and the stored position (wall-local) agree; if
-        // the wall mesh is somehow absent, keep the raw world hit unchanged.
-        const correctedWorld = wallMesh
-          ? wallMesh.localToWorld(new Vector3(correctedX, correctedY, event.localPosition[2]))
-          : null
         wallMoveEvent = {
           ...event,
           localPosition: [correctedX, correctedY, event.localPosition[2]],
-          position: correctedWorld
-            ? [correctedWorld.x, correctedWorld.y, correctedWorld.z]
-            : event.position,
         }
       }
       const result = wallStrategy.move(ctx, wallMoveEvent, getActiveValidators())
@@ -1203,22 +1361,11 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
         // Publish live transform for the 2D floorplan. The floorplan resolves a
         // wall item's footprint (and its wall-side depth offset) from this
-        // rotation as a PLAN-space yaw. `cursorRotationY` is the 3D world cursor
-        // yaw, which is π off from the plan rotation on a wall face — feeding it
-        // raw flips the footprint to the far side of the wall during placement.
-        // Publish the plan rotation (wall angle + the item's wall-local yaw) so
-        // the preview matches what the committed node resolves to.
-        let liveRotation = result.cursorRotationY
-        const liveWallId = placementState.current.wallId
-        const liveWall = liveWallId ? useScene.getState().nodes[liveWallId as AnyNodeId] : undefined
-        if (liveWall?.type === 'wall') {
-          const w = liveWall as WallNode
-          const wallPlanRotation = -Math.atan2(w.end[1] - w.start[1], w.end[0] - w.start[0])
-          liveRotation = wallPlanRotation + (draft.rotation[1] ?? 0)
-        }
+        // rotation as a PLAN-space yaw — which is exactly what the wall strategy
+        // composes `cursorRotationY` as (wall yaw + the item's wall-local yaw).
         useLiveTransforms.getState().set(draft.id, {
           position: result.cursorPosition,
-          rotation: liveRotation,
+          rotation: result.cursorRotationY,
         })
       }
     }
@@ -1228,18 +1375,12 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (!result) return
 
       event.stopPropagation()
-      // Clear live transform before commit
-      if (draftNode.current) {
-        useLiveTransforms.getState().clear(draftNode.current.id)
-      }
-      const committedId = draftNode.current?.id ?? null
-      const wasAdopted = draftNode.isAdopted
-      const finalId = draftNode.commit(result.nodeUpdate)
+      const { committedId, wasAdopted } = commitDraft(result.nodeUpdate)
       if (result.dirtyNodeId) {
         useScene.getState().dirtyNodes.add(result.dirtyNodeId)
       }
 
-      finishCommittedPlacement(finalId ?? committedId, wasAdopted, () => {
+      finishCommittedPlacement(committedId, wasAdopted, () => {
         const nodes = useScene.getState().nodes
         const enterResult = wallStrategy.enter(
           getContext(),
@@ -1388,14 +1529,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (!result) return
 
       event.stopPropagation()
-      if (draftNode.current) {
-        useLiveTransforms.getState().clear(draftNode.current.id)
-      }
-      const committedId = draftNode.current?.id ?? null
-      const wasAdopted = draftNode.isAdopted
-      const finalId = draftNode.commit(result.nodeUpdate)
+      const { committedId, wasAdopted } = commitDraft(result.nodeUpdate)
 
-      finishCommittedPlacement(finalId ?? committedId, wasAdopted, () => {
+      finishCommittedPlacement(committedId, wasAdopted, () => {
         const enterResult = roofWallStrategy.enter(getContext(), event, altFreeRef.current)
         if (enterResult) {
           applyTransition(enterResult)
@@ -1428,6 +1564,119 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       }
     }
 
+    // ---- Face Host Handlers ----
+
+    const enterFaceHost = (event: NodeEvent): boolean => {
+      const result = faceHostStrategy.enter(getContext(), event)
+      if (!result) return false
+      pendingFaceHostId = null
+      event.stopPropagation()
+      applyTransition(result)
+      if (!draftNode.current) {
+        ensureDraft(result)
+      } else if (result.nodeUpdate.parentId) {
+        useScene.getState().updateNode(draftNode.current.id, result.nodeUpdate)
+        disableDraftRaycastNow()
+      }
+      if (draftNode.current) useLiveTransforms.getState().clear(draftNode.current.id)
+      return true
+    }
+
+    const onFaceHostEnter = (event: NodeEvent) => {
+      has3DPointerDrivenMoveRef.current = true
+      enterFaceHost(event)
+    }
+
+    const onFaceHostMove = (event: NodeEvent) => {
+      has3DPointerDrivenMoveRef.current = true
+      if (!cursorGroupRef.current) return
+      const ctx = getContext()
+      if (ctx.state.surface !== 'block-face' || !draftNode.current) {
+        if (enterFaceHost(event)) releaseCommit = () => onFaceHostClick(event)
+        return
+      }
+      const result = faceHostStrategy.move(ctx, event)
+      if (!result) {
+        event.stopPropagation()
+        return
+      }
+
+      event.stopPropagation()
+      const draft = draftNode.current
+      const nextFaceId = result.hostFaceId
+      const faceSwitch = resolveFaceHostSwitch(
+        currentFaceHostId(draft),
+        nextFaceId,
+        pendingFaceHostId,
+      )
+      pendingFaceHostId = faceSwitch.pendingFaceId
+      if (!faceSwitch.accept) return
+      releaseCommit = () => onFaceHostClick(event)
+
+      const posChanged =
+        gridPosition.current.x !== result.gridPosition[0] ||
+        gridPosition.current.y !== result.gridPosition[1] ||
+        gridPosition.current.z !== result.gridPosition[2]
+      if (posChanged) sfxEmitter.emit('sfx:grid-snap')
+      gridPosition.current.set(...result.gridPosition)
+      const cursor = worldToBuildingLocal(...result.cursorPosition)
+      cursorGroupRef.current.position.copy(cursor)
+      if (result.cursorRotation) {
+        cursorGroupRef.current.rotation.set(...worldRotationToBuildingLocal(result.cursorRotation))
+      }
+
+      if (draft && result.nodeUpdate) {
+        Object.assign(draft, result.nodeUpdate)
+        const mesh = sceneRegistry.nodes.get(draft.id)
+        const rotation = result.nodeUpdate.rotation ?? draft.rotation
+        if (mesh) applyFaceHostPreviewPose(mesh, result.gridPosition, rotation)
+        useLiveNodeOverrides.getState().set(draft.id, {
+          position: result.gridPosition,
+          rotation,
+          ...result.nodeUpdate,
+        })
+      }
+      revalidate()
+    }
+
+    const onFaceHostClick = (event: NodeEvent) => {
+      const outcome = commitFaceHostClick({
+        commitDraft,
+        enterFaceHost,
+        event,
+        getContext,
+      })
+      if (!outcome) return
+      const { committedId, wasAdopted } = outcome
+      finishCommittedPlacement(committedId, wasAdopted, () => {
+        const enterResult = faceHostStrategy.enter(getContext(), event)
+        if (enterResult) applyTransition(enterResult)
+        else revalidate()
+      })
+    }
+
+    const onFaceHostLeave = (event: NodeEvent) => {
+      pendingFaceHostId = null
+      if (!shouldDetachFaceHostOnLeave(asset.attachTo)) {
+        event.stopPropagation()
+        return
+      }
+      const result = faceHostStrategy.leave(getContext())
+      if (!result) return
+      event.stopPropagation()
+      const draft = draftNode.current
+      if (draft) {
+        useLiveNodeOverrides.getState().clearFields(draft.id, faceHostClearFields(draft))
+      }
+      if (draftNode.isAdopted) {
+        applyTransition(result)
+        if (draft) useScene.getState().updateNode(draft.id, result.nodeUpdate)
+      } else {
+        draftNode.destroy()
+        Object.assign(placementState.current, result.stateUpdate)
+      }
+    }
+
     // ---- Item Surface Handlers ----
 
     const detachItemSurfaceToFloor = (event: ItemEvent) => {
@@ -1469,7 +1718,11 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         levelId ? { parentId: levelId } : undefined,
       )
       if (cursorGroupRef.current) {
-        cursorGroupRef.current.position.set(...floorVisualPosition)
+        cursorGroupRef.current.position.set(
+          floorVisualPosition[0],
+          floorVisualPosition[1] + getPlacementLevelY(draftNode.current),
+          floorVisualPosition[2],
+        )
       }
 
       const draft = draftNode.current
@@ -1633,6 +1886,15 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       // 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 === 'block-face') {
+          const result = resolveFaceHostPreviewCommit(ctx)
+          if (result) {
+            event.stopPropagation()
+            const { committedId, wasAdopted } = commitDraft(result.nodeUpdate)
+            finishCommittedPlacement(committedId, wasAdopted, revalidate)
+            return
+          }
+        }
         if (ctx.state.surface === 'shelf-surface' && ctx.state.shelfId) {
           const shelfNode = useScene.getState().nodes[ctx.state.shelfId as AnyNodeId]
           if (shelfNode && shelfNode.type === 'shelf') {
@@ -1640,13 +1902,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
             const result = shelfSurfaceStrategy.click(ctx, synthetic as never)
             if (result) {
               event.stopPropagation()
-              if (draftNode.current) {
-                useLiveTransforms.getState().clear(draftNode.current.id)
-              }
-              const committedId = draftNode.current?.id ?? null
-              const wasAdopted = draftNode.isAdopted
-              const finalId = draftNode.commit(result.nodeUpdate)
-              finishCommittedPlacement(finalId ?? committedId, wasAdopted, () => {
+              const { committedId, wasAdopted } = commitDraft(result.nodeUpdate)
+              finishCommittedPlacement(committedId, wasAdopted, () => {
                 const enterResult = shelfSurfaceStrategy.enter(ctx, synthetic as never)
                 if (enterResult) {
                   applyTransition(enterResult)
@@ -1668,13 +1925,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
             const result = itemSurfaceStrategy.click(ctx, synthetic)
             if (result) {
               event.stopPropagation()
-              if (draftNode.current) {
-                useLiveTransforms.getState().clear(draftNode.current.id)
-              }
-              const committedId = draftNode.current?.id ?? null
-              const wasAdopted = draftNode.isAdopted
-              const finalId = draftNode.commit(result.nodeUpdate)
-              finishCommittedPlacement(finalId ?? committedId, wasAdopted, () => {
+              const { committedId, wasAdopted } = commitDraft(result.nodeUpdate)
+              finishCommittedPlacement(committedId, wasAdopted, () => {
                 const enterResult = itemSurfaceStrategy.enter(ctx, synthetic)
                 if (enterResult) {
                   applyTransition(enterResult)
@@ -1699,13 +1951,8 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
             const result = ceilingStrategy.click(ctx, synthetic, getActiveValidators())
             if (result) {
               event.stopPropagation()
-              if (draftNode.current) {
-                useLiveTransforms.getState().clear(draftNode.current.id)
-              }
-              const committedId = draftNode.current?.id ?? null
-              const wasAdopted = draftNode.isAdopted
-              const finalId = draftNode.commit(result.nodeUpdate)
-              finishCommittedPlacement(finalId ?? committedId, wasAdopted, () => {
+              const { committedId, wasAdopted } = commitDraft(result.nodeUpdate)
+              finishCommittedPlacement(committedId, wasAdopted, () => {
                 const nodes = useScene.getState().nodes
                 const enterResult = ceilingStrategy.enter(
                   getContext(),
@@ -1730,15 +1977,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (!result) return
 
       event.stopPropagation()
-      // Clear live transform before commit
-      if (draftNode.current) {
-        useLiveTransforms.getState().clear(draftNode.current.id)
-      }
-      const committedId = draftNode.current?.id ?? null
-      const wasAdopted = draftNode.isAdopted
-      const finalId = draftNode.commit(result.nodeUpdate)
+      const { committedId, wasAdopted } = commitDraft(result.nodeUpdate)
 
-      finishCommittedPlacement(finalId ?? committedId, wasAdopted, () => {
+      finishCommittedPlacement(committedId, wasAdopted, () => {
         // Try to set up next draft on the same surface
         const enterResult = itemSurfaceStrategy.enter(getContext(), event)
         if (enterResult) {
@@ -1861,15 +2102,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (!result) return
 
       event.stopPropagation()
-      // Clear live transform before commit
-      if (draftNode.current) {
-        useLiveTransforms.getState().clear(draftNode.current.id)
-      }
-      const committedId = draftNode.current?.id ?? null
-      const wasAdopted = draftNode.isAdopted
-      const finalId = draftNode.commit(result.nodeUpdate)
+      const { committedId, wasAdopted } = commitDraft(result.nodeUpdate)
 
-      finishCommittedPlacement(finalId ?? committedId, wasAdopted, () => {
+      finishCommittedPlacement(committedId, wasAdopted, () => {
         const nodes = useScene.getState().nodes
         const enterResult = ceilingStrategy.enter(getContext(), event, resolveLevelId, nodes)
         if (enterResult) {
@@ -2002,14 +2237,9 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (!result) return
 
       event.stopPropagation()
-      if (draftNode.current) {
-        useLiveTransforms.getState().clear(draftNode.current.id)
-      }
-      const committedId = draftNode.current?.id ?? null
-      const wasAdopted = draftNode.isAdopted
-      const finalId = draftNode.commit(result.nodeUpdate)
+      const { committedId, wasAdopted } = commitDraft(result.nodeUpdate)
 
-      finishCommittedPlacement(finalId ?? committedId, wasAdopted, () => {
+      finishCommittedPlacement(committedId, wasAdopted, () => {
         const enterResult = shelfSurfaceStrategy.enter(getContext(), event)
         if (enterResult) {
           applyTransition(enterResult)
@@ -2038,7 +2268,11 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
       // Roof-wall drafts live flat in the host face frame (yaw 0) —
       // manual rotation would skew them off the wall plane.
-      if (placementState.current.surface === 'roof-wall') return
+      if (
+        placementState.current.surface === 'roof-wall' ||
+        placementState.current.surface === 'block-face'
+      )
+        return
 
       let rotationDir: 1 | -1 | 0 = 0
       if ((event.key === 'r' || event.key === 'R') && !event.metaKey && !event.ctrlKey)
@@ -2054,9 +2288,11 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         const newRotationY = steppedRotation(currentRotation[1] ?? 0, rotationDir)
         draft.rotation = [currentRotation[0], newRotationY, currentRotation[2]]
 
-        // Ref + cursor mesh + item mesh — no store update during drag
+        // 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
+        // table or shelf while still matching the draft exactly on the floor.
         if (cursorGroupRef.current) {
-          cursorGroupRef.current.rotation.y = newRotationY
+          cursorGroupRef.current.rotation.y += newRotationY - currentRotation[1]
         }
         const mesh = sceneRegistry.nodes.get(draft.id)
         if (mesh) mesh.rotation.y = newRotationY
@@ -2073,8 +2309,11 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
           draft.position = [x, gridPosition.current.y, z]
           if (cursorGroupRef.current) {
             if (surface === 'floor') {
+              const visual = getFloorVisualPosition([x, gridPosition.current.y, z])
               cursorGroupRef.current.position.set(
-                ...getFloorVisualPosition([x, gridPosition.current.y, z]),
+                visual[0],
+                visual[1] + getPlacementLevelY(draft),
+                visual[2],
               )
             } else {
               cursorGroupRef.current.position.x = x
@@ -2120,24 +2359,40 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
           }
         }
 
-        // Update live transform for 2D floorplan with post-snap position
+        // 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 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: livePosition,
-            rotation: newRotationY,
-          })
+        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: livePosition,
+          rotation: cursorGroupRef.current?.rotation.y ?? newRotationY,
+        })
+
+        const placementPreview = usePlacementPreview.getState()
+        if (placementPreview.node?.id === draft.id) {
+          const parentNode = draft.parentId
+            ? (useScene.getState().nodes[draft.parentId as AnyNodeId] ?? null)
+            : null
+          placementPreview.set(
+            {
+              ...draft,
+              position: [...draft.position],
+              rotation: [...draft.rotation],
+            },
+            parentNode,
+          )
         }
 
         revalidate()
@@ -2248,6 +2503,10 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     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)
@@ -2270,11 +2529,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (placementState.current.surface !== 'floor') return
       onGridClick(event as unknown as GridEvent)
     }
-    emitter.on('wall:click', commitFloorOnSurfaceClick as never)
-    emitter.on('item:click', commitFloorOnSurfaceClick as never)
-    emitter.on('ceiling:click', commitFloorOnSurfaceClick as never)
-    emitter.on('roof:click', commitFloorOnSurfaceClick as never)
-    emitter.on('shelf:click', commitFloorOnSurfaceClick as never)
+    emitter.on('node:click', commitFloorOnSurfaceClick as never)
     if (dragMode) window.addEventListener('pointerup', onReleaseCommit)
 
     return () => {
@@ -2282,9 +2537,10 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       if (dragMode) window.removeEventListener('pointerup', onReleaseCommit)
       unsubDraftWatch()
       useAlignmentGuides.getState().clear()
-      // Clear live transform for any remaining draft
+      // Clear every live preview channel before restoring or deleting the draft.
       if (draftNode.current) {
         useLiveTransforms.getState().clear(draftNode.current.id)
+        useLiveNodeOverrides.getState().clearFields(draftNode.current.id, ['rotation'])
       }
       draftNode.destroy()
       useScene.temporal.getState().resume()
@@ -2302,6 +2558,10 @@ 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('ceiling:enter', onCeilingEnter)
       emitter.off('ceiling:move', onCeilingMove)
       emitter.off('ceiling:click', onCeilingClick)
@@ -2310,11 +2570,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       emitter.off('shelf:move', onShelfMove)
       emitter.off('shelf:click', onShelfClick)
       emitter.off('shelf:leave', onShelfLeave)
-      emitter.off('wall:click', commitFloorOnSurfaceClick as never)
-      emitter.off('item:click', commitFloorOnSurfaceClick as never)
-      emitter.off('ceiling:click', commitFloorOnSurfaceClick as never)
-      emitter.off('roof:click', commitFloorOnSurfaceClick as never)
-      emitter.off('shelf:click', commitFloorOnSurfaceClick as never)
+      emitter.off('node:click', commitFloorOnSurfaceClick as never)
       emitter.off('tool:cancel', onCancel)
       window.removeEventListener('keydown', onKeyDown)
       window.removeEventListener('keyup', onKeyUp)
@@ -2332,6 +2588,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     gridSnapStep,
     updateDimensionGuides,
     updatePreviewGeometry,
+    reconcileDraftRaycast,
   ])
 
   // Refresh wireframe when the grid step changes mid-placement so the green/red
@@ -2363,39 +2620,17 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     const draftParent = draft.parentId
       ? useScene.getState().nodes[draft.parentId as AnyNodeId]
       : undefined
-    if (draftParent?.type === 'item' || draftParent?.type === 'shelf') return
+    if (
+      draftParent?.type === 'item' ||
+      draftParent?.type === 'shelf' ||
+      (draftParent &&
+        nodeRegistry.get(draftParent.type)?.capabilities.faceHost?.currentFaceId(draft))
+    )
+      return
     draft.parentId = viewerLevelId
     useScene.getState().updateNode(draft.id as AnyNodeId, { parentId: viewerLevelId })
   }, [viewerLevelId, draftNode, asset])
 
-  // 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
-    // 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])
 
@@ -2407,8 +2642,10 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
   // 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 facingForwardRef = useRef(new Vector3(0, 0, 1))
   const facingQuatRef = useRef(new Quaternion())
+  const ghostSurfaceQuatRef = useRef(new Quaternion())
   useFrame(() => {
     const ghost = cursorGroupRef.current
     if (!(asset && ghost)) {
@@ -2423,7 +2660,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     // the item's forward on the floor, and the triangle rides at the ghost's Y.
     let facingYaw = ghost.rotation.y
     let facingY = ghost.position.y
-    if (surf === 'wall' || surf === 'roof-wall') {
+    if (surf === 'wall' || surf === 'roof-wall' || surf === 'block-face') {
       // Wall/roof-segment faces: the cursor group's yaw is the symmetric
       // wireframe yaw (π off the real facing for a wall, and a different frame
       // for a roof face), so derive the item's TRUE outward facing from the
@@ -2431,21 +2668,31 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       // surface. This keeps BOTH the grid normal and the triangle correct for
       // wall and roof-segment hosts alike, rather than the old quaternion read
       // that pointed the wrong way.
-      const mesh = draftNode.current ? sceneRegistry.nodes.get(draftNode.current.id) : null
-      if (mesh) {
-        mesh.getWorldQuaternion(facingQuatRef.current)
-        const fwd = facingForwardRef.current.set(0, 0, 1).applyQuaternion(facingQuatRef.current)
-        fwd.y = 0
-        if (fwd.lengthSq() > 1e-6) facingYaw = Math.atan2(fwd.x, fwd.z)
-      }
+      const mesh =
+        surf === 'block-face' || !draftNode.current
+          ? null
+          : sceneRegistry.nodes.get(draftNode.current.id)
+      ghost.getWorldQuaternion(ghostSurfaceQuatRef.current)
+      const hostedQuaternion = mesh ? mesh.getWorldQuaternion(facingQuatRef.current) : null
+      resolveItemPlacementSurfaceNormal(
+        surf,
+        ghostSurfaceQuatRef.current,
+        hostedQuaternion,
+        n,
+        asset.attachTo,
+      )
+      const fwd = facingForwardRef.current.copy(n)
+      if (fwd.lengthSq() > 1e-6) facingYaw = Math.atan2(fwd.x, fwd.z)
       // The forward triangle is a floor aid; drop it to the building-local floor
-      // under the wall (the ghost Y is up on the wall).
-      facingY = 0
-      n.set(Math.sin(facingYaw), 0, Math.cos(facingYaw))
+      // under the hosted plane — the storey's floor, not world ground.
+      facingY = getPlacementLevelY(draftNode.current)
     } else {
-      n.set(0, 1, 0)
+      ghost.getWorldQuaternion(ghostSurfaceQuatRef.current)
+      resolveItemPlacementSurfaceNormal(surf, ghostSurfaceQuatRef.current, null, n)
     }
-    publishPlacementSurface(ghost.position, n)
+    // `publishPlacementSurface` is a WORLD-space contract (the grid reads it in
+    // world space), but the ghost lives in the building-local tool group.
+    publishPlacementSurface(ghost.getWorldPosition(surfaceWorldPointRef.current), n)
 
     if (shape.depth > 0) {
       useFacingPose.getState().set({
@@ -2513,8 +2760,16 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
           gridPosition.current.z,
         ])
         mesh.position.y = visualPosition[1]
-        cursorGroupRef.current.position.y = visualPosition[1]
-      }
+        cursorGroupRef.current.position.y =
+          visualPosition[1] + getPlacementLevelY(draftNode.current)
+      }
+    } else if (placementState.current.surface === 'block-face') {
+      const rotation = draftNode.current.rotation
+      applyFaceHostPreviewPose(
+        mesh,
+        [gridPosition.current.x, gridPosition.current.y, gridPosition.current.z],
+        rotation,
+      )
     }
   })
 
@@ -2558,9 +2813,21 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
     depth: currentDimensionBounds.dimensions[2],
     center: [currentDimensionBounds.center[0], currentDimensionBounds.center[2]],
   }
-  const widthLabel = formatLinearMeasurement(currentDimensionBounds.dimensions[0], unit)
-  const depthLabel = formatLinearMeasurement(currentDimensionBounds.dimensions[2], unit)
-  const heightLabel = formatLinearMeasurement(currentDimensionBounds.dimensions[1], unit)
+  const widthLabel = formatLinearMeasurement(
+    currentDimensionBounds.dimensions[0],
+    unit,
+    metricNotation,
+  )
+  const depthLabel = formatLinearMeasurement(
+    currentDimensionBounds.dimensions[2],
+    unit,
+    metricNotation,
+  )
+  const heightLabel = formatLinearMeasurement(
+    currentDimensionBounds.dimensions[1],
+    unit,
+    metricNotation,
+  )
   const widthLabelPosition: [number, number, number] = [
     currentDimensionBounds.center[0],
     0.04,