feat(paint-slots): paintable slots on the procedural shelf (phase 5)

Proves the unified (nodeId, slotId) slot contract on a procedural generator,
beyond items and walls. A shelf now exposes three paintable slots — shelves /
frame / back — painted through the same PaintCapability dispatch and the same
node.slots: Record<slotId, MaterialRef> shape items use.

Foundation (shared, reusable by future procedural kinds):
- core: SlotDeclaration type + capabilities.slots(node) registry declaration;
  GeometryContext gains `materials` so a pure builder can resolve scene:<id>
  slot refs without importing useScene.
- viewer GeometrySystem: threads the scene material library into every builder
  ctx, and re-dirties (bypassing the geometryKey skip) any geometry node that
  references a scene material when that material changes — so editing a custom
  colour propagates to every shelf using it, matching items.

Shelf:
- schema: slots: Record<string, MaterialRef> (mirrors ItemNode).
- geometry: per-slot material resolution (slot override -> legacy whole-shelf
  -> declared default colour); every mesh stamped with userData.slotId;
  DEFAULT_SHELF_MATERIAL retired (declared default gives identical off-white).
- paint.ts: PaintCapability (resolveRole from userData.slotId, scene-material
  commit for one-off colours, preview restricted to __fromGeometry meshes so
  hosted items aren't ghosted, getEffectiveMaterial incl. legacy fallback).
- definition: paint + slots capabilities; slots folded into geometryKey.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

packages/nodes/src/shelf/definition.ts

@@ -4,8 +4,10 @@ import { buildShelfFloorplan } from './floorplan'
 import { shelfResizeAffordance, shelfRotateAffordance } from './floorplan-affordances'
 import { shelfFloorplanMoveTarget } from './floorplan-move'
 import { buildShelfGeometry, shelfRowSurfaceYs } from './geometry'
+import { shelfPaint } from './paint'
 import { shelfParametrics } from './parametrics'
 import { ShelfNode } from './schema'
+import { shelfSlots } from './slots'
 
 const SIDE_HANDLE_OFFSET = 0.18
 const HEIGHT_HANDLE_OFFSET = 0.22
@@ -155,8 +157,8 @@ export const shelfDefinition: NodeDefinition<typeof ShelfNode> = {
     withBottom: true,
     bracketStyle: 'minimal',
     // material / materialPreset left undefined — geometry falls back to
-    // `DEFAULT_SHELF_MATERIAL` (off-white), and paint mode writes the
-    // chosen catalog material into these fields.
+    // the per-slot off-white default, and slot paint mode writes chosen
+    // catalog materials into `slots`.
   }),
 
   capabilities: {
@@ -183,6 +185,8 @@ export const shelfDefinition: NodeDefinition<typeof ShelfNode> = {
     selectable: { hitVolume: 'bbox' },
     duplicable: true,
     deletable: true,
+    paint: shelfPaint,
+    slots: (n) => shelfSlots(n as ShelfNode),
     // Slab elevation lift via the generic `<FloorElevationSystem>` — a
     // shelf sitting over a raised slab visually rests on top of it.
     floorPlaced: {
@@ -233,6 +237,7 @@ export const shelfDefinition: NodeDefinition<typeof ShelfNode> = {
       s.bracketStyle,
       s.material,
       s.materialPreset,
+      JSON.stringify(s.slots ?? null),
     ])
   },
   floorplan: buildShelfFloorplan,

packages/nodes/src/shelf/floorplan-move.ts

@@ -109,7 +109,7 @@ export const shelfFloorplanMoveTarget: FloorplanMoveTarget<ShelfNode> = ({ node,
     },
     canCommit() {
       const live = useScene.getState().nodes[shelfId] as ShelfNode | undefined
-      if (!live || live.type !== 'shelf') return false
+      if (live?.type !== 'shelf') return false
       return !(lastPosition[0] === originalPosition[0] && lastPosition[2] === originalPosition[2])
     },
   }

packages/nodes/src/shelf/geometry.ts

@@ -1,14 +1,15 @@
-import { getMaterialPresetByRef } from '@pascal-app/core'
+import { type GeometryContext, getMaterialPresetByRef } from '@pascal-app/core'
 import {
   applyMaterialPresetToMaterials,
   createDefaultMaterial,
   createMaterial,
-  DEFAULT_SHELF_MATERIAL,
   type RenderShading,
+  resolveMaterialRef,
 } from '@pascal-app/viewer'
-import { BoxGeometry, FrontSide, Group, type Material, Mesh } from 'three'
+import { BoxGeometry, Group, type Material, Mesh } from 'three'
 import { sanitizeShelfDimensions } from './dimensions'
 import type { ShelfNode } from './schema'
+import { SHELF_SLOT_DEFAULT_COLOR, type ShelfSlotId } from './slots'
 
 /**
  * Pure shelf geometry builder. Takes a `ShelfNode` and returns a `Group`
@@ -23,75 +24,72 @@ import type { ShelfNode } from './schema'
  * index arrays directly, and lets AI-generated nodes follow the same
  * shape with no editor-specific knowledge.
  *
- * Materials: the kind exposes a single paintable surface via
- * `node.material` / `node.materialPreset` — same shape walls / slabs /
- * stairs use. When neither is set, every mesh shares the
- * `DEFAULT_SHELF_MATERIAL` (off-white). When the user paints, the
- * library preset's properties land on a cloned material here. The cache
- * key includes the preset / material signature so paint changes
- * invalidate without stomping unrelated shelves.
+ * Materials: the kind exposes per-slot paintable surfaces through
+ * `node.slots`, while `node.material` / `node.materialPreset` remain as
+ * legacy whole-shelf fallbacks. Every generated mesh is tagged with the
+ * slot it belongs to so paint mode can target shelves, frame, or back.
  *
  * Style dispatch lives at the top of the function; each style helper
  * mutates the same `group`.
  */
-type ShelfMaterial = Material & {
-  depthWrite: boolean
+type ShelfSlotMaterials = Record<ShelfSlotId, Material>
+
+function getShelfSlotMaterial(
+  node: ShelfNode,
+  slotId: ShelfSlotId,
+  materials: GeometryContext['materials'],
+  shading: RenderShading,
+): Material {
+  const ref = node.slots?.[slotId]
+  if (ref) {
+    const resolved = resolveMaterialRef(ref, materials, shading)
+    if (resolved) return resolved
+  }
+  // Legacy whole-shelf paint applies to every slot when set (no per-slot override).
+  if (node.materialPreset) {
+    const preset = getMaterialPresetByRef(node.materialPreset)
+    if (preset) {
+      const base = createDefaultMaterial('#ffffff', 0.5, shading)
+      applyMaterialPresetToMaterials(base, preset)
+      return base
+    }
+  }
+  if (node.material) return createMaterial(node.material, shading)
+  return createDefaultMaterial(SHELF_SLOT_DEFAULT_COLOR, 0.9, shading)
 }
 
-const shelfMaterialCache = new Map<string, Material>()
-
-function getShelfMaterial(node: ShelfNode, shading: RenderShading): Material {
-  const cacheKey = JSON.stringify({
-    shading,
-    material: node.material ?? null,
-    materialPreset: node.materialPreset ?? null,
-  })
-  const cached = shelfMaterialCache.get(cacheKey)
-  if (cached) return cached
-
-  const preset = getMaterialPresetByRef(node.materialPreset)
-  const material = preset
-    ? createDefaultMaterial('#ffffff', 0.5, shading)
-    : node.material
-      ? createMaterial(node.material, shading).clone()
-      : DEFAULT_SHELF_MATERIAL(shading).clone()
-
-  if (preset) {
-    applyMaterialPresetToMaterials(material, preset)
-  }
-
-  const shelfMaterial = material as ShelfMaterial
-  shelfMaterial.side = FrontSide
-  shelfMaterial.depthWrite = true
-  shelfMaterial.needsUpdate = true
-
-  shelfMaterialCache.set(cacheKey, material)
-  return material
+function stampShelfSlot(mesh: Mesh, slotId: ShelfSlotId): Mesh {
+  mesh.userData.slotId = slotId
+  return mesh
 }
 
 export function buildShelfGeometry(
   rawNode: ShelfNode,
-  _ctx?: unknown,
+  ctx?: GeometryContext,
   shading: RenderShading = 'rendered',
 ): Group {
   const node = sanitizeShelfDimensions(rawNode)
   const group = new Group()
   group.name = 'shelf-geometry'
 
-  const material = getShelfMaterial(node, shading)
+  const materials: ShelfSlotMaterials = {
+    shelves: getShelfSlotMaterial(node, 'shelves', ctx?.materials, shading),
+    frame: getShelfSlotMaterial(node, 'frame', ctx?.materials, shading),
+    back: getShelfSlotMaterial(node, 'back', ctx?.materials, shading),
+  }
 
   switch (node.style) {
     case 'wall-shelf':
-      buildWallShelf(group, node, material)
+      buildWallShelf(group, node, materials)
       break
     case 'bookshelf':
-      buildBookshelf(group, node, material)
+      buildBookshelf(group, node, materials)
       break
     case 'open-rack':
-      buildOpenRack(group, node, material)
+      buildOpenRack(group, node, materials)
       break
     case 'cubby':
-      buildCubby(group, node, material)
+      buildCubby(group, node, materials)
       break
   }
 
@@ -112,9 +110,12 @@ export function buildShelfGeometry(
  * evenly-spaced boards from `height/rows` up to `height`. Brackets
  * span from floor to the topmost board.
  */
-function buildWallShelf(group: Group, node: ShelfNode, material: Material) {
+function buildWallShelf(group: Group, node: ShelfNode, materials: ShelfSlotMaterials) {
   for (const y of boardCenterYs(node)) {
-    const board = new Mesh(new BoxGeometry(node.width, node.thickness, node.depth), material)
+    const board = stampShelfSlot(
+      new Mesh(new BoxGeometry(node.width, node.thickness, node.depth), materials.shelves),
+      'shelves',
+    )
     board.name = `shelf-board-${boardRowIndex(node, y)}`
     board.position.set(0, y, 0)
     group.add(board)
@@ -131,7 +132,10 @@ function buildWallShelf(group: Group, node: ShelfNode, material: Material) {
   const bracketDepth = node.bracketStyle === 'industrial' ? node.depth * 0.95 : node.depth * 0.7
 
   for (const sign of [-1, 1] as const) {
-    const bracket = new Mesh(new BoxGeometry(bracketWidth, bracketHeight, bracketDepth), material)
+    const bracket = stampShelfSlot(
+      new Mesh(new BoxGeometry(bracketWidth, bracketHeight, bracketDepth), materials.frame),
+      'frame',
+    )
     bracket.name = `shelf-bracket-${sign === -1 ? 'left' : 'right'}`
     bracket.position.set(sign * (node.width / 2 - inset), bracketHeight / 2, 0)
     group.add(bracket)
@@ -144,20 +148,26 @@ function buildWallShelf(group: Group, node: ShelfNode, material: Material) {
  * `withSides === false`, side panels become slim corner posts (a rack
  * silhouette).
  */
-function buildBookshelf(group: Group, node: ShelfNode, material: Material) {
+function buildBookshelf(group: Group, node: ShelfNode, materials: ShelfSlotMaterials) {
   const unitHeight = node.height + node.thickness
   const innerWidth = node.withSides ? node.width - 2 * node.thickness : node.width
 
   // Top + bottom + intermediate boards
   for (const y of boardCenterYs(node)) {
-    const board = new Mesh(new BoxGeometry(innerWidth, node.thickness, node.depth), material)
+    const board = stampShelfSlot(
+      new Mesh(new BoxGeometry(innerWidth, node.thickness, node.depth), materials.shelves),
+      'shelves',
+    )
     board.name = `shelf-board-${boardRowIndex(node, y)}`
     board.position.set(0, y, 0)
     group.add(board)
   }
 
   if (node.withBottom) {
-    const bottom = new Mesh(new BoxGeometry(innerWidth, node.thickness, node.depth), material)
+    const bottom = stampShelfSlot(
+      new Mesh(new BoxGeometry(innerWidth, node.thickness, node.depth), materials.shelves),
+      'shelves',
+    )
     bottom.name = 'shelf-board-bottom'
     bottom.position.set(0, node.thickness / 2, 0)
     group.add(bottom)
@@ -166,17 +176,23 @@ function buildBookshelf(group: Group, node: ShelfNode, material: Material) {
   // Side panels (or corner posts) — span the full unit height.
   if (node.withSides) {
     for (const sign of [-1, 1] as const) {
-      const side = new Mesh(new BoxGeometry(node.thickness, unitHeight, node.depth), material)
+      const side = stampShelfSlot(
+        new Mesh(new BoxGeometry(node.thickness, unitHeight, node.depth), materials.frame),
+        'frame',
+      )
       side.name = `shelf-side-${sign === -1 ? 'left' : 'right'}`
       side.position.set(sign * (node.width / 2 - node.thickness / 2), unitHeight / 2, 0)
       group.add(side)
     }
   } else {
-    addCornerPosts(group, node, material, unitHeight, 'rack')
+    addCornerPosts(group, node, materials.frame, unitHeight, 'rack')
   }
 
   if (node.withBack) {
-    const back = new Mesh(new BoxGeometry(innerWidth, unitHeight, node.thickness), material)
+    const back = stampShelfSlot(
+      new Mesh(new BoxGeometry(innerWidth, unitHeight, node.thickness), materials.back),
+      'back',
+    )
     back.name = 'shelf-back'
     back.position.set(0, unitHeight / 2, -(node.depth / 2 - node.thickness / 2))
     group.add(back)
@@ -187,7 +203,10 @@ function buildBookshelf(group: Group, node: ShelfNode, material: Material) {
     const colStep = innerWidth / node.columns
     for (let c = 1; c < node.columns; c++) {
       const x = -innerWidth / 2 + c * colStep
-      const divider = new Mesh(new BoxGeometry(node.thickness, unitHeight, node.depth), material)
+      const divider = stampShelfSlot(
+        new Mesh(new BoxGeometry(node.thickness, unitHeight, node.depth), materials.frame),
+        'frame',
+      )
       divider.name = `shelf-divider-col-${c}`
       divider.position.set(x, unitHeight / 2, 0)
       group.add(divider)
@@ -200,26 +219,32 @@ function buildBookshelf(group: Group, node: ShelfNode, material: Material) {
  * X-brace on the back face for stability. `withSides` / `bracketStyle`
  * are ignored (the rack defines its own posts).
  */
-function buildOpenRack(group: Group, node: ShelfNode, material: Material) {
+function buildOpenRack(group: Group, node: ShelfNode, materials: ShelfSlotMaterials) {
   const unitHeight = node.height + node.thickness
   const innerWidth = node.width
   const boardThickness = Math.max(0.02, node.thickness * 0.8)
 
   for (const y of boardCenterYs(node)) {
-    const board = new Mesh(new BoxGeometry(innerWidth, boardThickness, node.depth), material)
+    const board = stampShelfSlot(
+      new Mesh(new BoxGeometry(innerWidth, boardThickness, node.depth), materials.shelves),
+      'shelves',
+    )
     board.name = `shelf-board-${boardRowIndex(node, y)}`
     board.position.set(0, y, 0)
     group.add(board)
   }
 
-  addCornerPosts(group, node, material, unitHeight, 'rack')
+  addCornerPosts(group, node, materials.frame, unitHeight, 'rack')
 
   if (node.withBack) {
     const braceThickness = Math.max(0.015, node.thickness * 0.6)
     for (const y of [boardThickness, unitHeight - boardThickness] as const) {
-      const brace = new Mesh(
-        new BoxGeometry(node.width - braceThickness * 2, braceThickness, braceThickness),
-        material,
+      const brace = stampShelfSlot(
+        new Mesh(
+          new BoxGeometry(node.width - braceThickness * 2, braceThickness, braceThickness),
+          materials.frame,
+        ),
+        'frame',
       )
       brace.name = `shelf-brace-h-${y < unitHeight / 2 ? 'bottom' : 'top'}`
       brace.position.set(0, y, -(node.depth / 2 - braceThickness / 2))
@@ -233,32 +258,44 @@ function buildOpenRack(group: Group, node: ShelfNode, material: Material) {
  * boards + vertical dividers. `withBack` / `withSides` are forced on
  * because the cubby shape requires them.
  */
-function buildCubby(group: Group, node: ShelfNode, material: Material) {
+function buildCubby(group: Group, node: ShelfNode, materials: ShelfSlotMaterials) {
   const unitHeight = node.height + node.thickness
   const innerWidth = node.width - 2 * node.thickness
 
   for (const y of boardCenterYs(node)) {
-    const board = new Mesh(new BoxGeometry(innerWidth, node.thickness, node.depth), material)
+    const board = stampShelfSlot(
+      new Mesh(new BoxGeometry(innerWidth, node.thickness, node.depth), materials.shelves),
+      'shelves',
+    )
     board.name = `shelf-board-${boardRowIndex(node, y)}`
     board.position.set(0, y, 0)
     group.add(board)
   }
 
   if (node.withBottom) {
-    const bottom = new Mesh(new BoxGeometry(innerWidth, node.thickness, node.depth), material)
+    const bottom = stampShelfSlot(
+      new Mesh(new BoxGeometry(innerWidth, node.thickness, node.depth), materials.shelves),
+      'shelves',
+    )
     bottom.name = 'shelf-board-bottom'
     bottom.position.set(0, node.thickness / 2, 0)
     group.add(bottom)
   }
 
   for (const sign of [-1, 1] as const) {
-    const side = new Mesh(new BoxGeometry(node.thickness, unitHeight, node.depth), material)
+    const side = stampShelfSlot(
+      new Mesh(new BoxGeometry(node.thickness, unitHeight, node.depth), materials.frame),
+      'frame',
+    )
     side.name = `shelf-side-${sign === -1 ? 'left' : 'right'}`
     side.position.set(sign * (node.width / 2 - node.thickness / 2), unitHeight / 2, 0)
     group.add(side)
   }
 
-  const back = new Mesh(new BoxGeometry(innerWidth, unitHeight, node.thickness), material)
+  const back = stampShelfSlot(
+    new Mesh(new BoxGeometry(innerWidth, unitHeight, node.thickness), materials.back),
+    'back',
+  )
   back.name = 'shelf-back'
   back.position.set(0, unitHeight / 2, -(node.depth / 2 - node.thickness / 2))
   group.add(back)
@@ -273,9 +310,9 @@ function buildCubby(group: Group, node: ShelfNode, material: Material) {
       if (dividerHeight <= 0) continue
       for (let c = 1; c < node.columns; c++) {
         const x = -innerWidth / 2 + c * colStep
-        const divider = new Mesh(
-          new BoxGeometry(node.thickness, dividerHeight, node.depth),
-          material,
+        const divider = stampShelfSlot(
+          new Mesh(new BoxGeometry(node.thickness, dividerHeight, node.depth), materials.frame),
+          'frame',
         )
         divider.name = `shelf-divider-${r}-${c}`
         divider.position.set(x, cellBottomY + dividerHeight / 2, 0)
@@ -324,7 +361,10 @@ function addCornerPosts(
   const inset = postThickness / 2
   for (const xSign of [-1, 1] as const) {
     for (const zSign of [-1, 1] as const) {
-      const post = new Mesh(new BoxGeometry(postThickness, unitHeight, postThickness), material)
+      const post = stampShelfSlot(
+        new Mesh(new BoxGeometry(postThickness, unitHeight, postThickness), material),
+        'frame',
+      )
       post.name = `shelf-post-${xSign === -1 ? 'l' : 'r'}${zSign === -1 ? 'b' : 'f'}`
       post.position.set(
         xSign * (node.width / 2 - inset),

packages/nodes/src/shelf/paint.ts

@@ -0,0 +1,218 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  generateSceneMaterialId,
+  type MaterialSchema,
+  type PaintCapability,
+  parseMaterialRef,
+  type SceneMaterial,
+  type SceneMaterialId,
+  type ShelfNode,
+  toSceneMaterialRef,
+  useScene,
+} from '@pascal-app/core'
+import { createMaterial, createMaterialFromPresetRef, useViewer } from '@pascal-app/viewer'
+import type { Material, Mesh } from 'three'
+
+type ShelfSlotUserData = {
+  slotId?: string | null
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (typeof a !== typeof b) return false
+  if (a === null || b === null) return false
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false
+    for (let index = 0; index < a.length; index += 1) {
+      if (!deepEqual(a[index], b[index])) return false
+    }
+    return true
+  }
+  if (typeof a === 'object') {
+    const aRecord = a as Record<string, unknown>
+    const bRecord = b as Record<string, unknown>
+    const aKeys = Object.keys(aRecord)
+    const bKeys = Object.keys(bRecord)
+    if (aKeys.length !== bKeys.length) return false
+    for (const key of aKeys) {
+      if (!Object.hasOwn(bRecord, key)) return false
+      if (!deepEqual(aRecord[key], bRecord[key])) return false
+    }
+    return true
+  }
+  return false
+}
+
+function resolveShelfSlotId(args: { hitObject?: { userData?: ShelfSlotUserData } }): string | null {
+  const slotId = args.hitObject?.userData?.slotId
+  return typeof slotId === 'string' ? slotId : null
+}
+
+function buildShelfSlotsPatch(
+  node: ShelfNode,
+  role: string,
+  material: MaterialSchema | undefined,
+  materialPreset: string | undefined,
+): Partial<ShelfNode> {
+  const slots = { ...(node.slots ?? {}) }
+  if (material === undefined && materialPreset === undefined) {
+    delete slots[role]
+    return { slots }
+  }
+  if (materialPreset) {
+    slots[role] = materialPreset
+    return { slots }
+  }
+  return { slots }
+}
+
+function findMatchingSceneMaterial(
+  materials: Record<SceneMaterialId, SceneMaterial>,
+  material: MaterialSchema,
+): SceneMaterial | null {
+  for (const sceneMaterial of Object.values(materials)) {
+    if (deepEqual(sceneMaterial.material, material)) return sceneMaterial
+  }
+  return null
+}
+
+function commitNewSceneMaterialAndSlots(
+  nodeId: AnyNodeId,
+  nextSlots: ShelfNode['slots'],
+  sceneMaterial: SceneMaterial,
+): void {
+  // Creating the scene material and setting the slot ref are one logical
+  // edit, so apply both in a single `set` — zundo records one history entry,
+  // and one undo removes both the ref and its (now orphaned) material.
+  useScene.setState((state) => {
+    if (state.readOnly) return state
+    const currentNode = state.nodes[nodeId]
+    if (currentNode?.type !== 'shelf') return state
+    return {
+      materials: { ...state.materials, [sceneMaterial.id as SceneMaterialId]: sceneMaterial },
+      nodes: {
+        ...state.nodes,
+        [nodeId]: { ...currentNode, slots: nextSlots } as AnyNode,
+      },
+    }
+  })
+  useScene.getState().markDirty(nodeId)
+}
+
+function commitShelfPaint(
+  node: ShelfNode,
+  role: string,
+  material: MaterialSchema | undefined,
+  materialPreset: string | undefined,
+): void {
+  const nodeId = node.id as AnyNodeId
+  const state = useScene.getState()
+  const currentNode = (state.nodes[nodeId] as ShelfNode | undefined) ?? node
+  let ref: string | undefined
+  let newSceneMaterial: SceneMaterial | null = null
+
+  if (material === undefined && materialPreset === undefined) {
+    ref = undefined
+  } else if (materialPreset) {
+    ref = materialPreset
+  } else if (material) {
+    const existing = findMatchingSceneMaterial(state.materials, material)
+    if (existing) {
+      ref = toSceneMaterialRef(existing.id)
+    } else {
+      const id = generateSceneMaterialId()
+      newSceneMaterial = {
+        id,
+        name: `Material ${Object.keys(state.materials).length + 1}`,
+        material,
+      }
+      ref = toSceneMaterialRef(id)
+    }
+  } else {
+    return
+  }
+
+  const nextSlots = { ...(currentNode.slots ?? {}) }
+  if (ref) nextSlots[role] = ref
+  else delete nextSlots[role]
+
+  if (newSceneMaterial) {
+    commitNewSceneMaterialAndSlots(nodeId, nextSlots, newSceneMaterial)
+    return
+  }
+
+  state.updateNode(nodeId, { slots: nextSlots } as Partial<AnyNode>)
+}
+
+function buildPreviewMaterial(
+  material: MaterialSchema | undefined,
+  materialPreset: string | undefined,
+): Material | null {
+  const shading = useViewer.getState().shading
+  if (materialPreset) return createMaterialFromPresetRef(materialPreset, shading)
+  if (material) return createMaterial(material, shading)
+  return null
+}
+
+function applyShelfPreview(
+  role: string,
+  root: import('three').Object3D,
+  material: MaterialSchema | undefined,
+  materialPreset: string | undefined,
+): (() => void) | null {
+  const previewMaterial = buildPreviewMaterial(material, materialPreset)
+  if (!previewMaterial) return () => {}
+
+  const restores: Array<() => void> = []
+  root.traverse((object) => {
+    const mesh = object as Mesh
+    if (!mesh.isMesh) return
+    const userData = mesh.userData as ShelfSlotUserData & { __fromGeometry?: boolean }
+    // Only the shelf's own builder meshes — never hosted item children, whose
+    // GLB meshes can carry a colliding `userData.slotId` (slot_frame, etc.).
+    if (userData.__fromGeometry !== true) return
+    if (userData.slotId !== role) return
+
+    const previous = mesh.material
+    mesh.material = previewMaterial
+    restores.push(() => {
+      mesh.material = previous
+    })
+  })
+
+  if (restores.length === 0) return null
+  return () => {
+    for (let index = restores.length - 1; index >= 0; index -= 1) {
+      restores[index]?.()
+    }
+  }
+}
+
+export const shelfPaint: PaintCapability = {
+  resolveRole: ({ hitObject }) =>
+    resolveShelfSlotId({ hitObject: hitObject as { userData?: ShelfSlotUserData } }),
+  buildPatch: ({ node, role, material, materialPreset }) =>
+    buildShelfSlotsPatch(node as ShelfNode, role, material, materialPreset) as Partial<AnyNode>,
+  commit: ({ node, role, material, materialPreset }) =>
+    commitShelfPaint(node as ShelfNode, role, material, materialPreset),
+  applyPreview: ({ role, root, material, materialPreset }) =>
+    applyShelfPreview(role, root, material, materialPreset),
+  getEffectiveMaterial: ({ node, role }) => {
+    const shelf = node as ShelfNode
+    const parsed = parseMaterialRef(shelf.slots?.[role])
+    if (parsed) {
+      if (parsed.kind === 'library') {
+        return { material: undefined, materialPreset: shelf.slots?.[role] }
+      }
+      const sceneMaterial = useScene.getState().materials[parsed.id as SceneMaterialId]
+      if (sceneMaterial) return { material: sceneMaterial.material, materialPreset: undefined }
+    }
+    // No (or dangling) slot ref — surface the legacy whole-shelf paint the
+    // geometry builder still falls back to, so the picker matches what renders.
+    if (shelf.materialPreset || shelf.material) {
+      return { material: shelf.material, materialPreset: shelf.materialPreset }
+    }
+    return null
+  },
+}

packages/nodes/src/shelf/preview.tsx

@@ -13,11 +13,9 @@ import type { ShelfNode } from './schema'
  * then walks the result, **clones** each mesh's material, and mutates
  * the clone for a translucent ghost.
  *
- * Cloning is non-negotiable: `getShelfMaterial` caches the default
- * material instance in a module-scoped map keyed on
- * `material` / `materialPreset`, so every unpainted shelf in the scene
- * shares the same material. Mutating `mat.transparent = true` here
- * would leak into every committed shelf and render them all see-through.
+ * Cloning is non-negotiable: shelf geometry may receive materials from
+ * shared viewer caches, so mutating `mat.transparent = true` here would
+ * leak into committed shelves using the same material.
  *
  * Building the full geometry tree per-frame would be wasteful, so we
  * memoize the group + dispose the per-mesh material clones on unmount.
@@ -44,9 +42,9 @@ const ShelfPreview = ({ node }: { node: ShelfNode }) => {
       ;(obj as unknown as { raycast: () => void }).raycast = () => {}
 
       // `Mesh.material` is typed as `Material | Material[]` upstream;
-      // every shelf board carries a material from
-      // `getShelfMaterial`. Access through a structural cast keeps the
-      // assignment well-typed without depending on the Mesh union.
+      // every shelf board carries a material from the geometry builder.
+      // Access through a structural cast keeps the assignment well-typed
+      // without depending on the Mesh union.
       const mesh = obj as {
         material?: Material | Material[]
       }
@@ -70,8 +68,8 @@ const ShelfPreview = ({ node }: { node: ShelfNode }) => {
 
     return () => {
       // Dispose only the clones we made — never the shared cached
-      // material returned by `getShelfMaterial`, which other shelves in
-      // the scene still reference. Geometry is left alone for the same
+      // material returned by the builder, which other shelves in the
+      // scene may still reference. Geometry is left alone for the same
       // reason; the builder may move to a cached strategy in future.
       for (const c of cloned) c.dispose()
       built.traverse((obj) => {

packages/nodes/src/shelf/slots.ts

@@ -0,0 +1,35 @@
+import type { SlotDeclaration } from '@pascal-app/core'
+import type { ShelfNode } from './schema'
+
+export type ShelfSlotId = 'shelves' | 'frame' | 'back'
+
+// Visual parity with the retired DEFAULT_SHELF_MATERIAL (off-white).
+export const SHELF_SLOT_DEFAULT_COLOR = '#ffffff'
+
+/** Map a builder mesh name to its slot id (null = not a paintable shelf part). */
+export function shelfSlotIdForMeshName(name: string): ShelfSlotId | null {
+  if (name.startsWith('shelf-board')) return 'shelves'
+  if (name === 'shelf-back') return 'back'
+  if (
+    name.startsWith('shelf-side') ||
+    name.startsWith('shelf-post') ||
+    name.startsWith('shelf-divider') ||
+    name.startsWith('shelf-bracket') ||
+    name.startsWith('shelf-brace')
+  ) {
+    return 'frame'
+  }
+  return null
+}
+
+/** Which slots a given shelf actually exposes (depends on style/flags). */
+export function shelfSlots(node: ShelfNode): SlotDeclaration[] {
+  const slots: SlotDeclaration[] = [
+    { slotId: 'shelves', label: 'Shelves', default: SHELF_SLOT_DEFAULT_COLOR },
+  ]
+  const hasFrame = !(node.style === 'wall-shelf' && node.bracketStyle === 'hidden')
+  if (hasFrame) slots.push({ slotId: 'frame', label: 'Frame', default: SHELF_SLOT_DEFAULT_COLOR })
+  const hasBack = node.style === 'cubby' || (node.style === 'bookshelf' && node.withBack)
+  if (hasBack) slots.push({ slotId: 'back', label: 'Back', default: SHELF_SLOT_DEFAULT_COLOR })
+  return slots
+}