@pascal-app/editor 0.8.0 → 0.9.2

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

@@ -1,8 +1,26 @@
 import { type AssetInput, isObject } from '@pascal-app/core'
-import useEditor from '../../../store/use-editor'
+import { Euler, Matrix3, type Matrix4, Quaternion, Vector3 } from 'three'
+import { resolveSnapFlags } from '../../../lib/snapping-mode'
+import useEditor, { getActiveSnappingMode } from '../../../store/use-editor'
 
+// Sentinel returned when the active context's snapping mode disables grid snap.
+// The snap helpers below treat any `step <= 0` as "no grid snap" and pass the
+// raw value through. For items the default mode is now `lines` (grid off), so
+// item placement/move is free + line-snap unless the user opts into `grid`.
 function getGridSnapStep(): number {
-  return useEditor.getState().gridSnapStep
+  return resolveSnapFlags(getActiveSnappingMode()).grid ? useEditor.getState().gridSnapStep : 0
+}
+
+const ROTATION_QUANTUM = Math.PI / 4
+
+/**
+ * R/T rotation: round the current angle to the nearest 45° then step ONE
+ * increment in `direction` (+1 / -1), so the node always lands on a clean 45°
+ * multiple regardless of its starting angle (12° → 45°, 40° → 90°) rather than a
+ * blind ±45° from an arbitrary angle.
+ */
+export function steppedRotation(current: number, direction: 1 | -1): number {
+  return (Math.round(current / ROTATION_QUANTUM) + direction) * ROTATION_QUANTUM
 }
 
 function positiveModulo(value: number, divisor: number): number {
@@ -13,6 +31,7 @@ function positiveModulo(value: number, divisor: number): number {
  * Snaps a position to the active grid step, aligning item edges to grid lines.
  */
 export function snapToGrid(position: number, dimension: number, step = getGridSnapStep()): number {
+  if (step <= 0) return position
   const halfDim = dimension / 2
   const offset = positiveModulo(halfDim, step)
   return Math.round((position - offset) / step) * step + offset
@@ -22,6 +41,7 @@ export function snapToGrid(position: number, dimension: number, step = getGridSn
  * Snap a value to the active grid step (used for wall-local positions).
  */
 export function snapToHalf(value: number, step = getGridSnapStep()): number {
+  if (step <= 0) return value
   return Math.round(value / step) * step
 }
 
@@ -29,6 +49,7 @@ export function snapToHalf(value: number, step = getGridSnapStep()): number {
  * Round a value up to the next multiple of `step`, with a minimum of `step`.
  */
 export function snapUpToGridStep(value: number, step = getGridSnapStep()): number {
+  if (step <= 0) return value
   return Math.max(step, Math.ceil(value / step) * step)
 }
 
@@ -54,6 +75,12 @@ export function getGridAlignedDimensions(
   return [snapUpToGridStep(w, step), h, snapUpToGridStep(d, step)]
 }
 
+export function getDetachedAttachmentPreviewLift(
+  attachTo: AssetInput['attachTo'] | null | undefined,
+): number {
+  return attachTo ? 0.45 : 0
+}
+
 /**
  * Calculate cursor rotation in WORLD space from wall normal and orientation.
  */
@@ -110,11 +137,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,29 @@ import type {
   GridEvent,
   ItemEvent,
   ItemNode,
+  RoofEvent,
+  RoofNode,
+  RoofSegmentNode,
+  RoofWallFaceId,
+  ShelfEvent,
+  ShelfNode,
   WallEvent,
   WallNode,
 } from '@pascal-app/core'
 import {
+  canHostOnTop,
+  clampRectToRoofWallFace,
+  getRoofSegmentWallFace,
   getScaledDimensions,
   isLowProfileItemSurface,
+  nodeRegistry,
+  roofFacePointToSegment,
   sceneRegistry,
   useScene,
 } from '@pascal-app/core'
 import { Euler, Matrix3, Quaternion, Vector3 } from 'three'
+import { hasRoofFaceChildOverlap, resolveRoofWallHit } from '../../../lib/roof-wall-hit'
+import { snapWorldXZForActiveBuilding } from '../../../lib/world-grid-snap'
 import {
   calculateCursorRotation,
   calculateItemRotation,
@@ -52,6 +65,7 @@ function isUpwardItemSurfaceHit(event: ItemEvent): boolean {
 }
 
 function getSurfacePlacementHeight(surfaceItem: ItemNode, event: ItemEvent, localPos: Vector3) {
+  if (!canHostOnTop(surfaceItem)) return null
   if (isLowProfileItemSurface(surfaceItem)) return null
   if (!isUpwardItemSurfaceHit(event)) return null
 
@@ -96,16 +110,25 @@ 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.
+    // Snapping is governed by the active mode (snapToGrid returns raw in Off /
+    // non-grid modes); Alt is force-place only and never bypasses snapping here.
+    const [x, z] = snapWorldXZForActiveBuilding(
+      snapToGrid(event.position[0], swapDims ? dimZ : dimX),
+      snapToGrid(event.position[2], swapDims ? dimX : dimZ),
+      0,
+    ).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,
     }
@@ -122,8 +145,13 @@ export const floorStrategy = {
   ): CommitResult | null {
     if (ctx.state.surface !== 'floor') return null
     if (!(ctx.levelId && ctx.draftItem)) return null
+    if (ctx.draftItem.asset.attachTo) 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,
@@ -197,10 +225,13 @@ export const wallStrategy = {
     const adjustedY = validation.adjustedY ?? y
 
     return {
-      stateUpdate: { surface: 'wall', wallId: event.node.id },
+      stateUpdate: { surface: 'wall', wallId: event.node.id, roofSegmentId: null },
       nodeUpdate: {
         position: [x, adjustedY, z],
         parentId: event.node.id,
+        // The draft may arrive from a roof-segment wall face.
+        roofSegmentId: undefined,
+        roofFace: undefined,
         side,
         rotation: [0, itemRotation, 0],
       },
@@ -299,6 +330,8 @@ export const wallStrategy = {
       nodeUpdate: {
         position: [ctx.gridPosition.x, ctx.gridPosition.y, ctx.gridPosition.z],
         parentId: event.node.id,
+        roofSegmentId: undefined,
+        roofFace: undefined,
         side: ctx.draftItem.side,
         rotation: ctx.draftItem.rotation,
         metadata: stripTransient(ctx.draftItem.metadata),
@@ -328,6 +361,225 @@ export const wallStrategy = {
   },
 }
 
+// ============================================================================
+// ROOF WALL STRATEGY
+// ============================================================================
+
+type RoofWallTarget = {
+  segment: RoofSegmentNode
+  faceId: RoofWallFaceId
+  faceYaw: number
+  /** Stored node position: FACE-LOCAL, y = bottom edge. */
+  position: [number, number, number]
+  /** Face-coord center of the placed rect (for the overlap guard). */
+  centerU: number
+  centerV: number
+  width: number
+  height: number
+  cursorPosition: [number, number, number]
+  cursorRotationY: number
+}
+
+/**
+ * Resolve a roof pointer event to an item placement on a segment wall
+ * face. Items snap u / bottom-v to the 0.5m grid, then the rect is
+ * clamped inside the face profile (sliding under the gable slopes).
+ * Position frame matches wall hosting: y anchors the BOTTOM edge;
+ * `wall-side` items mount on the outer surface, `wall` items center in
+ * the wall thickness.
+ *
+ * `freePlace` mirrors the wall flow's Alt override (stubbed
+ * validators): the profile clamp is skipped, so the rect may overhang
+ * the face edges — placement follows the snapped cursor as-is.
+ */
+function resolveRoofWallTarget(
+  ctx: PlacementContext,
+  event: RoofEvent,
+  freePlace = false,
+): RoofWallTarget | null {
+  const attachTo = ctx.asset.attachTo
+  if (attachTo !== 'wall' && attachTo !== 'wall-side') return null
+
+  const hit = resolveRoofWallHit(event.node as RoofNode, event.position, event.normal, event.object)
+  if (!hit) return null
+
+  const rawDims = ctx.draftItem
+    ? getScaledDimensions(ctx.draftItem)
+    : (ctx.asset.dimensions ?? DEFAULT_DIMENSIONS)
+  const dims = getGridAlignedDimensions(rawDims, attachTo)
+  const [width, height] = dims
+
+  // Snap follows the active mode (snapToHalf returns raw in Off/non-grid);
+  // `freePlace` (Alt) is force-place — it only skips the face-fit validity gate.
+  const u = snapToHalf(hit.u)
+  const centerV = snapToHalf(hit.v) + height / 2
+  const fitted = freePlace ? null : clampRectToRoofWallFace(hit.face, u, centerV, width, height)
+  if (!fitted && !freePlace) return null
+  const finalU = fitted?.u ?? u
+  const finalV = fitted?.v ?? centerV
+
+  // FACE-LOCAL storage (z = 0 → wall mid-plane; ItemSystem pushes
+  // wall-side items to the outer surface, exactly like wall hosting).
+  // The renderer mounts the node inside the live face frame, so items
+  // track segment resizes without any re-anchoring.
+  const position: [number, number, number] = [finalU, finalV - height / 2, 0]
+
+  const segObj = sceneRegistry.nodes.get(hit.segment.id)
+  if (!segObj) return null
+  segObj.updateWorldMatrix(true, false)
+  const segLocal = roofFacePointToSegment(hit.segment, hit.face.id, position)
+  const worldPos = segObj.localToWorld(new Vector3(segLocal[0], segLocal[1], segLocal[2]))
+
+  const nodes = useScene.getState().nodes
+  const roof = hit.segment.parentId
+    ? (nodes[hit.segment.parentId as AnyNodeId] as RoofNode | undefined)
+    : undefined
+
+  return {
+    segment: hit.segment,
+    faceId: hit.face.id,
+    faceYaw: hit.face.yaw,
+    position,
+    centerU: finalU,
+    centerV: finalV,
+    width,
+    height,
+    cursorPosition: [worldPos.x, worldPos.y, worldPos.z],
+    cursorRotationY: (roof?.rotation ?? 0) + (hit.segment.rotation ?? 0) + hit.face.yaw,
+  }
+}
+
+/** Validation half of `checkCanPlace` for the roof-wall surface. */
+function canPlaceOnRoofWall(ctx: PlacementContext): boolean {
+  const segmentId = ctx.state.roofSegmentId
+  if (!(segmentId && ctx.draftItem)) return false
+  const segment = useScene.getState().nodes[segmentId as AnyNodeId] as RoofSegmentNode | undefined
+  if (segment?.type !== 'roof-segment') return false
+  const faceId = ctx.draftItem.roofFace
+  if (!faceId) return false
+  const face = getRoofSegmentWallFace(segment, faceId)
+
+  const dims = getGridAlignedDimensions(
+    getScaledDimensions(ctx.draftItem),
+    ctx.draftItem.asset.attachTo,
+  )
+  const [width, height] = dims
+  // gridPosition carries the stored FACE-LOCAL coords (u, bottom-v, z).
+  const u = ctx.gridPosition.x
+  const centerV = ctx.gridPosition.y + height / 2
+  const clamped = clampRectToRoofWallFace(face, u, centerV, width, height)
+  if (!clamped || Math.abs(clamped.u - u) > 1e-3 || Math.abs(clamped.v - centerV) > 1e-3) {
+    return false
+  }
+  return !hasRoofFaceChildOverlap(segment, faceId, u, centerV, width, height, ctx.draftItem.id)
+}
+
+export const roofWallStrategy = {
+  /**
+   * Handle roof:enter / first hover — transition onto a segment wall
+   * face. Returns null when the item doesn't wall-attach or the pointer
+   * isn't over a placeable face.
+   */
+  enter(ctx: PlacementContext, event: RoofEvent, freePlace = false): TransitionResult | null {
+    const target = resolveRoofWallTarget(ctx, event, freePlace)
+    if (!target) return null
+
+    return {
+      stateUpdate: { surface: 'roof-wall', roofSegmentId: target.segment.id, wallId: null },
+      nodeUpdate: {
+        position: target.position,
+        parentId: target.segment.id,
+        roofSegmentId: target.segment.id,
+        roofFace: target.faceId,
+        wallId: undefined,
+        side: 'front',
+        rotation: [0, 0, 0],
+      },
+      cursorRotationY: target.cursorRotationY,
+      gridPosition: target.position,
+      cursorPosition: target.cursorPosition,
+      stopPropagation: true,
+    }
+  },
+
+  /**
+   * Handle roof:move while on a segment wall face. Returns null when the
+   * pointer resolves to a DIFFERENT segment (the coordinator re-enters —
+   * segment transitions inside one roof never re-fire roof:enter) or to
+   * no placeable face.
+   */
+  move(ctx: PlacementContext, event: RoofEvent, freePlace = false): PlacementResult | null {
+    if (ctx.state.surface !== 'roof-wall') return null
+    if (!ctx.draftItem) return null
+
+    const target = resolveRoofWallTarget(ctx, event, freePlace)
+    if (!target) return null
+    if (target.segment.id !== ctx.state.roofSegmentId) return null
+
+    return {
+      gridPosition: target.position,
+      cursorPosition: target.cursorPosition,
+      cursorRotationY: target.cursorRotationY,
+      nodeUpdate: {
+        position: target.position,
+        side: 'front',
+        rotation: [0, 0, 0],
+        roofFace: target.faceId,
+      },
+      stopPropagation: true,
+      // Items don't cut the roof — no geometry rebuild needed.
+      dirtyNodeId: null,
+    }
+  },
+
+  /**
+   * Handle roof:click — commit placement on the segment wall face.
+   */
+  click(ctx: PlacementContext, _event: RoofEvent, freePlace = false): CommitResult | null {
+    if (ctx.state.surface !== 'roof-wall') return null
+    if (!(ctx.draftItem && ctx.state.roofSegmentId)) return null
+    // Alt mirrors the wall flow's stubbed validators: skip profile-fit
+    // and overlap checks entirely.
+    if (!freePlace && !canPlaceOnRoofWall(ctx)) return null
+
+    return {
+      nodeUpdate: {
+        position: [ctx.gridPosition.x, ctx.gridPosition.y, ctx.gridPosition.z],
+        parentId: ctx.state.roofSegmentId,
+        roofSegmentId: ctx.state.roofSegmentId,
+        roofFace: ctx.draftItem.roofFace,
+        wallId: undefined,
+        side: 'front',
+        rotation: [0, 0, 0],
+        metadata: stripTransient(ctx.draftItem.metadata),
+      },
+      stopPropagation: true,
+      dirtyNodeId: null,
+    }
+  },
+
+  /**
+   * Handle roof:leave — transition back to floor surface.
+   */
+  leave(ctx: PlacementContext): TransitionResult | null {
+    if (ctx.state.surface !== 'roof-wall') return null
+
+    return {
+      stateUpdate: { surface: 'floor', roofSegmentId: null },
+      nodeUpdate: {
+        position: [ctx.gridPosition.x, ctx.gridPosition.y, ctx.gridPosition.z],
+        parentId: ctx.levelId,
+        roofSegmentId: undefined,
+        roofFace: undefined,
+      },
+      cursorRotationY: 0,
+      gridPosition: [ctx.gridPosition.x, ctx.gridPosition.y, ctx.gridPosition.z],
+      cursorPosition: [ctx.gridPosition.x, ctx.gridPosition.y, ctx.gridPosition.z],
+      stopPropagation: true,
+    }
+  },
+}
+
 // ============================================================================
 // CEILING STRATEGY
 // ============================================================================
@@ -362,16 +614,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 +648,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 +845,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 +1011,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)
@@ -619,6 +1032,9 @@ export function checkCanPlace(ctx: PlacementContext, validators: SpatialValidato
   }
 
   if (attachTo === 'wall' || attachTo === 'wall-side') {
+    if (ctx.state.surface === 'roof-wall') {
+      return canPlaceOnRoofWall(ctx)
+    }
     if (ctx.state.surface !== 'wall' || !ctx.state.wallId) return false
     return validators.canPlaceOnWall(
       ctx.levelId,
@@ -635,7 +1051,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],