@pascal-app/editor 0.8.0 → 0.9.1

package/src/components/tools/fence/fence-drafting.ts

@@ -8,11 +8,12 @@ import {
 } from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
 import { sfxEmitter } from '../../../lib/sfx-bus'
+import useEditor from '../../../store/use-editor'
 import {
   findWallSnapTarget,
+  getSegmentGridStep,
   getWallAngleSnapStep,
-  getWallGridStep,
-  isWallLongEnough,
+  isSegmentLongEnough,
   snapPointTo45Degrees,
   snapPointToGrid,
   type WallPlanPoint,
@@ -20,6 +21,9 @@ import {
 
 export type FencePlanPoint = WallPlanPoint
 
+const FENCE_CORNER_SNAP_RADIUS = 0.28
+const FENCE_SPAN_SNAP_RADIUS = 0.16
+
 type SegmentNode = {
   start: FencePlanPoint
   end: FencePlanPoint
@@ -57,46 +61,68 @@ function findFenceSnapTarget(
   fences: FenceNode[],
   ignoreFenceIds: string[] = [],
 ): FencePlanPoint | null {
-  const radiusSquared = 0.35 ** 2
+  const cornerRadiusSquared = FENCE_CORNER_SNAP_RADIUS ** 2
+  const spanRadiusSquared = FENCE_SPAN_SNAP_RADIUS ** 2
   const ignoredFenceIds = new Set(ignoreFenceIds)
-  let bestTarget: FencePlanPoint | null = null
-  let bestDistanceSquared = Number.POSITIVE_INFINITY
+  let bestCornerTarget: FencePlanPoint | null = null
+  let bestCornerDistanceSquared = Number.POSITIVE_INFINITY
+  let bestSpanTarget: FencePlanPoint | null = null
+  let bestSpanDistanceSquared = Number.POSITIVE_INFINITY
 
   for (const fence of fences) {
     if (ignoredFenceIds.has(fence.id)) {
       continue
     }
 
-    const candidates: Array<FencePlanPoint | null> = [fence.start, fence.end]
+    for (const candidate of [fence.start, fence.end]) {
+      const candidateDistanceSquared = distanceSquared(point, candidate)
+      if (
+        candidateDistanceSquared > cornerRadiusSquared ||
+        candidateDistanceSquared >= bestCornerDistanceSquared
+      ) {
+        continue
+      }
+
+      bestCornerTarget = candidate
+      bestCornerDistanceSquared = candidateDistanceSquared
+    }
+
     if (isCurvedWall(fence)) {
       const sampleCount = Math.max(8, Math.ceil(getWallCurveLength(fence) / 0.3))
-      for (let index = 0; index <= sampleCount; index += 1) {
+      for (let index = 1; index < sampleCount; index += 1) {
         const frame = getWallCurveFrameAt(fence, index / sampleCount)
-        candidates.push([frame.point.x, frame.point.y])
+        const candidate: FencePlanPoint = [frame.point.x, frame.point.y]
+        const candidateDistanceSquared = distanceSquared(point, candidate)
+        if (
+          candidateDistanceSquared > spanRadiusSquared ||
+          candidateDistanceSquared >= bestSpanDistanceSquared
+        ) {
+          continue
+        }
+
+        bestSpanTarget = candidate
+        bestSpanDistanceSquared = candidateDistanceSquared
       }
     } else {
-      candidates.push(projectPointOntoSegment(point, fence))
-    }
-
-    for (const candidate of candidates) {
+      const candidate = projectPointOntoSegment(point, fence)
       if (!candidate) {
         continue
       }
 
       const candidateDistanceSquared = distanceSquared(point, candidate)
       if (
-        candidateDistanceSquared > radiusSquared ||
-        candidateDistanceSquared >= bestDistanceSquared
+        candidateDistanceSquared > spanRadiusSquared ||
+        candidateDistanceSquared >= bestSpanDistanceSquared
       ) {
         continue
       }
 
-      bestTarget = candidate
-      bestDistanceSquared = candidateDistanceSquared
+      bestSpanTarget = candidate
+      bestSpanDistanceSquared = candidateDistanceSquared
     }
   }
 
-  return bestTarget
+  return bestCornerTarget ?? bestSpanTarget
 }
 
 export function snapFenceDraftPoint(args: {
@@ -106,14 +132,25 @@ export function snapFenceDraftPoint(args: {
   start?: FencePlanPoint
   angleSnap?: boolean
   ignoreFenceIds?: string[]
+  /** Override the grid step (e.g. `WALL_FINE_GRID_STEP` for precision mode). */
+  step?: number
+  /**
+   * Optional grid-snap function. When provided, replaces the default
+   * local-axis snap — lets the 2D floor-plan keep snapping to the
+   * world XZ grid even when the building is rotated. Wall / fence
+   * endpoint snap precedence is preserved.
+   */
+  gridSnap?: (point: FencePlanPoint) => FencePlanPoint
 }): FencePlanPoint {
-  const { point, walls, fences, start, angleSnap = false, ignoreFenceIds } = args
-  const gridStep = getWallGridStep()
+  const { point, walls, fences, start, angleSnap = false, ignoreFenceIds, step, gridSnap } = args
+  const gridStep = step ?? getSegmentGridStep()
   const angleStep = getWallAngleSnapStep(gridStep)
   const basePoint =
     start && angleSnap
-      ? snapPointTo45Degrees(start, point, gridStep, angleStep)
-      : snapPointToGrid(point, gridStep)
+      ? snapPointTo45Degrees(start, point, gridStep, angleStep, gridSnap)
+      : gridSnap
+        ? gridSnap(point)
+        : snapPointToGrid(point, gridStep)
   const fenceSnapTarget = findFenceSnapTarget(basePoint, fences, ignoreFenceIds)
 
   return fenceSnapTarget ?? findWallSnapTarget(basePoint, walls) ?? basePoint
@@ -126,12 +163,17 @@ export function createFenceOnCurrentLevel(
   const currentLevelId = useViewer.getState().selection.levelId
   const { createNode, nodes } = useScene.getState()
 
-  if (!(currentLevelId && isWallLongEnough(start, end))) {
+  if (!(currentLevelId && isSegmentLongEnough(start, end))) {
     return null
   }
 
   const fenceCount = Object.values(nodes).filter((node) => node.type === 'fence').length
+  // Build parameters seeded by a placed preset (height, style, post
+  // spacing, …) merge in first; `name`/`start`/`end` always win. The
+  // schema parse validates and drops anything unexpected.
+  const defaults = useEditor.getState().toolDefaults.fence ?? {}
   const fence = FenceNode.parse({
+    ...defaults,
     name: `Fence ${fenceCount + 1}`,
     start,
     end,

package/src/components/tools/item/move-tool.tsx

@@ -1,112 +1,48 @@
-import type {
-  BuildingNode,
-  CeilingNode,
-  ColumnNode,
-  DoorNode,
-  FenceNode,
-  ItemNode,
-  RoofNode,
-  RoofSegmentNode,
-  SlabNode,
-  SpawnNode,
-  StairNode,
-  StairSegmentNode,
-  WallNode,
-  WindowNode,
-} from '@pascal-app/core'
-import { Vector3 } from 'three'
-import { sfxEmitter } from '../../../lib/sfx-bus'
+import type { AnyNodeId, ElevatorNode, SpawnNode } from '@pascal-app/core'
+import { nodeRegistry } from '@pascal-app/core'
+import { Suspense } from 'react'
 import useEditor from '../../../store/use-editor'
-import { MoveBuildingContent } from '../building/move-building-tool'
-import { MoveCeilingTool } from '../ceiling/move-ceiling-tool'
-import { MoveColumnTool } from '../column/move-column-tool'
-import { MoveDoorTool } from '../door/move-door-tool'
-import { MoveFenceTool } from '../fence/move-fence-tool'
-import { MoveRoofTool } from '../roof/move-roof-tool'
-import { MoveSlabTool } from '../slab/move-slab-tool'
-import { MoveSpawnTool } from '../spawn/move-spawn-tool'
-import { MoveWallTool } from '../wall/move-wall-tool'
-import { MoveWindowTool } from '../window/move-window-tool'
-import type { PlacementState } from './placement-types'
-import { useDraftNode } from './use-draft-node'
-import { usePlacementCoordinator } from './use-placement-coordinator'
+import { MoveElevatorTool } from '../elevator/move-elevator-tool'
+import { MoveRegistryNodeTool } from '../registry/move-registry-node-tool'
+import { getRegistryAffordanceTool } from '../shared/affordance-dispatch'
 
-function getInitialState(node: {
-  asset: { attachTo?: string }
-  parentId: string | null
-}): PlacementState {
-  const attachTo = node.asset.attachTo
-  if (attachTo === 'wall' || attachTo === 'wall-side') {
-    return { surface: 'wall', wallId: node.parentId, ceilingId: null, surfaceItemId: null }
-  }
-  if (attachTo === 'ceiling') {
-    return { surface: 'ceiling', wallId: null, ceilingId: node.parentId, surfaceItemId: null }
-  }
-  return { surface: 'floor', wallId: null, ceilingId: null, surfaceItemId: null }
-}
-
-function MoveItemContent({ movingNode }: { movingNode: ItemNode }) {
-  const draftNode = useDraftNode()
-
-  const meta =
-    typeof movingNode.metadata === 'object' && movingNode.metadata !== null
-      ? (movingNode.metadata as Record<string, unknown>)
-      : {}
-  const isNew = !!meta.isNew
+/**
+ * MoveTool dispatcher. Routes to (in order):
+ *
+ *   1. `MoveRegistryNodeTool` — generic translate-on-XZ for kinds that
+ *      declare `capabilities.movable` (shelf, spawn, item-with-floor-attach,
+ *      …).
+ *   2. `def.affordanceTools.move` — kind-owned move component, lazy-loaded
+ *      via `getRegistryAffordanceTool`. Covers both generic movers
+ *      (slab / ceiling / wall / fence / column / item / door / window) and
+ *      the bespoke roof / roof-segment / stair / stair-segment / building
+ *      movers ported into `@pascal-app/nodes`.
+ *   3. `elevator` is the lone remaining legacy arm — its bespoke cab/shaft
+ *      mover hasn't been ported to a kind-owned affordance yet.
+ */
+export const MoveTool: React.FC<{
+  onNodeMoved?: (nodeId: AnyNodeId) => void
+  onSpawnMoved?: (nodeId: SpawnNode['id']) => void
+}> = ({ onNodeMoved }) => {
+  const movingNode = useEditor((state) => state.movingNode)
 
-  const cursor = usePlacementCoordinator({
-    asset: movingNode.asset,
-    draftNode,
-    // Duplicates start fresh in floor mode; wall/ceiling draft is created lazily by ensureDraft
-    initialState: isNew
-      ? { surface: 'floor', wallId: null, ceilingId: null, surfaceItemId: null }
-      : getInitialState(movingNode),
-    // Preserve the original item's scale so Y-position calculations use the correct height
-    defaultScale: isNew ? movingNode.scale : undefined,
-    initDraft: (gridPosition) => {
-      if (isNew) {
-        // Duplicate: use the same create() path as ItemTool so ghost rendering works correctly.
-        // Floor items get a draft immediately; wall/ceiling items are created lazily on surface entry.
-        gridPosition.copy(new Vector3(...movingNode.position))
-        if (!movingNode.asset.attachTo) {
-          draftNode.create(gridPosition, movingNode.asset, movingNode.rotation, movingNode.scale)
-        }
-      } else {
-        draftNode.adopt(movingNode)
-        gridPosition.copy(new Vector3(...movingNode.position))
-      }
-    },
-    onCommitted: () => {
-      sfxEmitter.emit('sfx:item-place')
-      useEditor.getState().setMovingNode(null)
-      return false
-    },
-    onCancel: () => {
-      draftNode.destroy()
-      useEditor.getState().setMovingNode(null)
-    },
-  })
+  if (!movingNode) return null
 
-  return <>{cursor}</>
-}
+  const def = nodeRegistry.get(movingNode.type)
+  if (def?.capabilities?.movable) {
+    return <MoveRegistryNodeTool node={movingNode} />
+  }
 
-export const MoveTool: React.FC = () => {
-  const movingNode = useEditor((state) => state.movingNode)
+  const RegistryMove = getRegistryAffordanceTool(movingNode.type, 'move')
+  if (RegistryMove) {
+    return (
+      <Suspense fallback={null}>
+        <RegistryMove node={movingNode} />
+      </Suspense>
+    )
+  }
 
-  if (!movingNode) return null
-  if (movingNode.type === 'building')
-    return <MoveBuildingContent node={movingNode as BuildingNode} />
-  if (movingNode.type === 'door') return <MoveDoorTool node={movingNode as DoorNode} />
-  if (movingNode.type === 'window') return <MoveWindowTool node={movingNode as WindowNode} />
-  if (movingNode.type === 'ceiling') return <MoveCeilingTool node={movingNode as CeilingNode} />
-  if (movingNode.type === 'column') return <MoveColumnTool node={movingNode as ColumnNode} />
-  if (movingNode.type === 'slab') return <MoveSlabTool node={movingNode as SlabNode} />
-  if (movingNode.type === 'wall') return <MoveWallTool node={movingNode as WallNode} />
-  if (movingNode.type === 'fence') return <MoveFenceTool node={movingNode as FenceNode} />
-  if (movingNode.type === 'roof' || movingNode.type === 'roof-segment')
-    return <MoveRoofTool node={movingNode as RoofNode | RoofSegmentNode} />
-  if (movingNode.type === 'spawn') return <MoveSpawnTool node={movingNode as SpawnNode} />
-  if (movingNode.type === 'stair' || movingNode.type === 'stair-segment')
-    return <MoveRoofTool node={movingNode as StairNode | StairSegmentNode} />
-  return <MoveItemContent movingNode={movingNode as ItemNode} />
+  if (movingNode.type === 'elevator')
+    return <MoveElevatorTool node={movingNode as ElevatorNode} onCommitted={onNodeMoved} />
+  return null
 }

package/src/components/tools/item/placement-math.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from 'bun:test'
+import { stripTransient } from './placement-math'
+
+describe('stripTransient', () => {
+  test('removes placement-only metadata flags before commit', () => {
+    expect(stripTransient({ isNew: true, isTransient: true, label: 'copy' })).toEqual({
+      label: 'copy',
+    })
+  })
+})

package/src/components/tools/item/placement-math.ts

@@ -1,4 +1,5 @@
 import { type AssetInput, isObject } from '@pascal-app/core'
+import { Euler, Matrix3, type Matrix4, Quaternion, Vector3 } from 'three'
 import useEditor from '../../../store/use-editor'
 
 function getGridSnapStep(): number {
@@ -110,11 +111,36 @@ export function isValidWallSideFace(normal: [number, number, number] | undefined
   return Math.abs(normal[2]) > 0.7
 }
 
-/**
- * Strip the `isTransient` flag from node metadata before committing.
- */
+/** Strip placement-only metadata flags before committing a draft. */
 export function stripTransient(meta: any): any {
   if (!isObject(meta)) return meta
-  const { isTransient, ...rest } = meta as Record<string, any>
-  return rest
+  const nextMeta = { ...(meta as Record<string, any>) }
+  delete nextMeta.isNew
+  delete nextMeta.isTransient
+  return nextMeta
+}
+
+const _up = new Vector3(0, 1, 0)
+const _normal = new Vector3()
+const _quat = new Quaternion()
+const _euler = new Euler()
+
+/**
+ * Compute euler rotation that tilts an item so its local +Y aligns with a
+ * roof surface normal. The normal is in the hit mesh's local space and is
+ * transformed to world space via the mesh's matrixWorld.
+ */
+export function calculateRoofRotation(
+  normal: [number, number, number] | undefined,
+  objectMatrixWorld: Matrix4,
+): [number, number, number] {
+  if (!normal) return [0, 0, 0]
+
+  _normal.set(normal[0], normal[1], normal[2])
+  _normal.applyNormalMatrix(new Matrix3().getNormalMatrix(objectMatrixWorld)).normalize()
+
+  _quat.setFromUnitVectors(_up, _normal)
+  _euler.setFromQuaternion(_quat, 'XYZ')
+
+  return [_euler.x, _euler.y, _euler.z]
 }

package/src/components/tools/item/placement-strategies.ts

@@ -6,16 +6,20 @@ import type {
   GridEvent,
   ItemEvent,
   ItemNode,
+  ShelfEvent,
+  ShelfNode,
   WallEvent,
   WallNode,
 } from '@pascal-app/core'
 import {
   getScaledDimensions,
   isLowProfileItemSurface,
+  nodeRegistry,
   sceneRegistry,
   useScene,
 } from '@pascal-app/core'
 import { Euler, Matrix3, Quaternion, Vector3 } from 'three'
+import { snapWorldXZForActiveBuilding } from '../../../lib/world-grid-snap'
 import {
   calculateCursorRotation,
   calculateItemRotation,
@@ -96,16 +100,22 @@ export const floorStrategy = {
     const [dimX, , dimZ] = dims
     const rotY = ctx.draftItem?.rotation?.[1] ?? 0
     const swapDims = Math.abs(Math.sin(rotY)) > 0.9
-    // event.localPosition is building-local; the coordinator cursor group is inside the
-    // building-local ToolManager group, so local coords are correct for both data and visuals.
-    const x = snapToGrid(event.localPosition[0], swapDims ? dimZ : dimX)
-    const z = snapToGrid(event.localPosition[2], swapDims ? dimX : dimZ)
+    // Snap on the world XZ grid (the grid the editor renders) so the
+    // item edges land on the visible grid even when the active building
+    // is rotated; then project the world point back into building-local
+    // for storage. Without this, a rotated building drags placement off
+    // the world grid.
+    const snappedWorldX = snapToGrid(event.position[0], swapDims ? dimZ : dimX)
+    const snappedWorldZ = snapToGrid(event.position[2], swapDims ? dimX : dimZ)
+    const { local } = snapWorldXZForActiveBuilding(snappedWorldX, snappedWorldZ, 0)
+    const [x, z] = local
+    const y = ctx.gridPosition.y
 
     return {
-      gridPosition: [x, 0, z],
-      cursorPosition: [x, event.localPosition[1], z],
-      cursorRotationY: 0,
-      nodeUpdate: { position: [x, 0, z] },
+      gridPosition: [x, y, z],
+      cursorPosition: [x, y, z],
+      cursorRotationY: rotY,
+      nodeUpdate: { position: [x, y, z] },
       stopPropagation: false,
       dirtyNodeId: null,
     }
@@ -123,7 +133,11 @@ export const floorStrategy = {
     if (ctx.state.surface !== 'floor') return null
     if (!(ctx.levelId && ctx.draftItem)) return null
 
-    const pos: [number, number, number] = [ctx.gridPosition.x, 0, ctx.gridPosition.z]
+    const pos: [number, number, number] = [
+      ctx.gridPosition.x,
+      ctx.gridPosition.y,
+      ctx.gridPosition.z,
+    ]
     const valid = validators.canPlaceOnFloor(
       ctx.levelId,
       pos,
@@ -362,16 +376,19 @@ export const ceilingStrategy = {
     // use the ceiling hit's local position rather than world position.
     const x = snapToGrid(event.localPosition[0], swapDims ? dimZ : dimX)
     const z = snapToGrid(event.localPosition[2], swapDims ? dimX : dimZ)
-    const worldSnapped = event.object.localToWorld(new Vector3(x, -itemHeight, z))
+    // Recessed fixtures seat flush with the ceiling plane (body rising into the
+    // void above); everything else hangs its full height below the ceiling.
+    const seatY = ctx.asset.recessed ? 0 : -itemHeight
+    const worldSnapped = event.object.localToWorld(new Vector3(x, seatY, z))
 
     return {
       stateUpdate: { surface: 'ceiling', ceilingId: event.node.id },
       nodeUpdate: {
-        position: [x, -itemHeight, z],
+        position: [x, seatY, z],
         parentId: event.node.id,
       },
       cursorRotationY: 0,
-      gridPosition: [x, -itemHeight, z],
+      gridPosition: [x, seatY, z],
       cursorPosition: [worldSnapped.x, worldSnapped.y, worldSnapped.z],
       stopPropagation: true,
     }
@@ -393,10 +410,13 @@ export const ceilingStrategy = {
 
     const x = snapToGrid(event.localPosition[0], swapDims ? dimZ : dimX)
     const z = snapToGrid(event.localPosition[2], swapDims ? dimX : dimZ)
-    const worldSnapped = event.object.localToWorld(new Vector3(x, -itemHeight, z))
+    // Recessed fixtures seat flush with the ceiling plane (body rising into the
+    // void above); everything else hangs its full height below the ceiling.
+    const seatY = ctx.draftItem.asset.recessed ? 0 : -itemHeight
+    const worldSnapped = event.object.localToWorld(new Vector3(x, seatY, z))
 
     return {
-      gridPosition: [x, -itemHeight, z],
+      gridPosition: [x, seatY, z],
       cursorPosition: [worldSnapped.x, worldSnapped.y, worldSnapped.z],
       cursorRotationY: 0,
       nodeUpdate: null,
@@ -587,6 +607,156 @@ export const itemSurfaceStrategy = {
   },
 }
 
+// ============================================================================
+// SHELF SURFACE STRATEGY
+// ============================================================================
+
+/**
+ * Resolve the row Y closest to the cursor's local Y. Reads candidate row
+ * positions from the kind's `capabilities.surfaces.custom` — the shelf
+ * declaration emits one `SurfacePoint` per board's top surface. The
+ * strategy stays kind-agnostic at this level: any future "multi-board"
+ * kind that declares `surfaces.custom` with upward normals gets the
+ * same hit behaviour for free.
+ */
+function getShelfRowSurfaceY(shelfNode: ShelfNode, localY: number): number | null {
+  const def = nodeRegistry.get('shelf')
+  const custom = def?.capabilities?.surfaces?.custom
+  if (!custom) return null
+  const candidates = custom(shelfNode as AnyNode)
+  if (candidates.length === 0) return null
+  let best = candidates[0]
+  let bestDist = Math.abs(best!.position[1] - localY)
+  for (let i = 1; i < candidates.length; i++) {
+    const c = candidates[i]
+    if (!c) continue
+    const dist = Math.abs(c.position[1] - localY)
+    if (dist < bestDist) {
+      best = c
+      bestDist = dist
+    }
+  }
+  return best?.position[1] ?? null
+}
+
+export const shelfSurfaceStrategy = {
+  /**
+   * Handle shelf:enter — transition the draft onto the closest shelf
+   * row. Mirrors `itemSurfaceStrategy.enter` but reads candidate
+   * surface heights from the shelf kind's `surfaces.custom` (one Y per
+   * board) instead of `asset.surface.height`. Picks the row whose
+   * surface Y is nearest the cursor's local Y so the user can target a
+   * specific row by hovering near it.
+   */
+  enter(ctx: PlacementContext, event: ShelfEvent): TransitionResult | null {
+    if (ctx.asset.attachTo) return null
+    const shelfNode = event.node as ShelfNode
+
+    if (ctx.state.surface === 'shelf-surface' && ctx.state.shelfId === shelfNode.id) {
+      return null
+    }
+    if (!isUpwardShelfSurfaceHit(event)) return null
+
+    // Size check: draft footprint must fit on the shelf board (width × depth).
+    const ourDims = ctx.draftItem
+      ? getScaledDimensions(ctx.draftItem)
+      : (ctx.asset.dimensions ?? DEFAULT_DIMENSIONS)
+    if (ourDims[0] > shelfNode.width || ourDims[2] > shelfNode.depth) return null
+
+    const shelfMesh = sceneRegistry.nodes.get(shelfNode.id)
+    if (!shelfMesh) return null
+
+    const worldPos = new Vector3(event.position[0], event.position[1], event.position[2])
+    const localPos = shelfMesh.worldToLocal(worldPos)
+    const rowY = getShelfRowSurfaceY(shelfNode, localPos.y)
+    if (rowY === null) return null
+
+    const x = snapToGrid(localPos.x, ourDims[0])
+    const z = snapToGrid(localPos.z, ourDims[2])
+
+    const worldSnapped = shelfMesh.localToWorld(new Vector3(x, rowY, z))
+
+    const surfaceQuat = new Quaternion()
+    shelfMesh.getWorldQuaternion(surfaceQuat)
+    const surfaceWorldY = new Euler().setFromQuaternion(surfaceQuat, 'YXZ').y
+    const localRotationY = ctx.currentCursorRotationY - surfaceWorldY
+    const draftRotation = ctx.draftItem?.rotation ?? [0, 0, 0]
+
+    return {
+      stateUpdate: { surface: 'shelf-surface', shelfId: shelfNode.id },
+      nodeUpdate: {
+        position: [x, rowY, z],
+        parentId: shelfNode.id,
+        rotation: [draftRotation[0], localRotationY, draftRotation[2]],
+      },
+      cursorRotationY: ctx.currentCursorRotationY,
+      gridPosition: [x, rowY, z],
+      cursorPosition: [worldSnapped.x, worldSnapped.y, worldSnapped.z],
+      stopPropagation: true,
+    }
+  },
+
+  /**
+   * Handle shelf:move — re-derive the closest row each tick so the user
+   * can slide between rows without leaving the shelf.
+   */
+  move(ctx: PlacementContext, event: ShelfEvent): PlacementResult | null {
+    if (ctx.state.surface !== 'shelf-surface') return null
+    if (!(ctx.state.shelfId && ctx.draftItem)) return null
+    if (event.node.id !== ctx.state.shelfId) return null
+
+    const shelfNode = event.node as ShelfNode
+    const shelfMesh = sceneRegistry.nodes.get(shelfNode.id)
+    if (!shelfMesh) return null
+
+    const ourDims = getScaledDimensions(ctx.draftItem)
+    const worldPos = new Vector3(event.position[0], event.position[1], event.position[2])
+    const localPos = shelfMesh.worldToLocal(worldPos)
+    const rowY = getShelfRowSurfaceY(shelfNode, localPos.y)
+    if (rowY === null) return null
+
+    const x = snapToGrid(localPos.x, ourDims[0])
+    const z = snapToGrid(localPos.z, ourDims[2])
+    const worldSnapped = shelfMesh.localToWorld(new Vector3(x, rowY, z))
+
+    return {
+      gridPosition: [x, rowY, z],
+      cursorPosition: [worldSnapped.x, worldSnapped.y, worldSnapped.z],
+      cursorRotationY: ctx.currentCursorRotationY,
+      nodeUpdate: { position: [x, rowY, z] },
+      stopPropagation: true,
+      dirtyNodeId: null,
+    }
+  },
+
+  /**
+   * Handle shelf:click — commit placement on the active row.
+   */
+  click(ctx: PlacementContext, event: ShelfEvent): CommitResult | null {
+    if (ctx.state.surface !== 'shelf-surface') return null
+    if (!(ctx.draftItem && ctx.state.shelfId)) return null
+    if (event.node.id !== ctx.state.shelfId) return null
+
+    return {
+      nodeUpdate: {
+        position: [ctx.gridPosition.x, ctx.gridPosition.y, ctx.gridPosition.z],
+        parentId: ctx.state.shelfId,
+        metadata: stripTransient(ctx.draftItem.metadata),
+      },
+      stopPropagation: true,
+      dirtyNodeId: null,
+    }
+  },
+}
+
+/** Same upward-normal heuristic as `isUpwardItemSurfaceHit`, but typed
+ *  for `ShelfEvent`. Re-uses the matrix-driven world normal calculation
+ *  via a tiny `ItemEvent`-shaped adapter — the function only reads
+ *  `event.normal` + `event.object`. */
+function isUpwardShelfSurfaceHit(event: ShelfEvent): boolean {
+  return isUpwardItemSurfaceHit(event as unknown as ItemEvent)
+}
+
 // ============================================================================
 // VALIDATION
 // ============================================================================
@@ -603,6 +773,11 @@ export function checkCanPlace(ctx: PlacementContext, validators: SpatialValidato
     return ctx.state.surfaceItemId !== null
   }
 
+  // Shelf surface: same — size check already happened on enter
+  if (ctx.state.surface === 'shelf-surface') {
+    return ctx.state.shelfId !== null
+  }
+
   const attachTo = ctx.draftItem.asset.attachTo
 
   const alignedDims = getGridAlignedDimensions(getScaledDimensions(ctx.draftItem), attachTo)
@@ -635,7 +810,7 @@ export function checkCanPlace(ctx: PlacementContext, validators: SpatialValidato
   // Floor (no attachTo)
   return validators.canPlaceOnFloor(
     ctx.levelId,
-    [ctx.gridPosition.x, 0, ctx.gridPosition.z],
+    [ctx.gridPosition.x, ctx.gridPosition.y, ctx.gridPosition.z],
     alignedDims,
     ctx.draftItem.rotation,
     [ctx.draftItem.id],