Merge pull request #404 from pascalorg/feat/paint-slots-phase-1

Paint slots: phase 1 + paint unification
2026-06-15 10:59:49 -04:00
parent cf24b62c44 2ac9f6762d
commit e0179c480a
24 changed files with 1146 additions and 264 deletions
@@ -72,6 +72,12 @@ export {
  segmentsIntersect,
 } from './lib/polygon-relations'
 export { getRenderableSlabPolygon } from './lib/slab-polygon'
+export {
+  deriveSlotId,
+  isSlotMaterialName,
+  SLOT_MATERIAL_PREFIX,
+  slotLabelFromId,
+} from './lib/slots'
 export {
  type AutoCeilingPlanningContext,
  type AutoCeilingSyncPlan,
@@ -92,12 +98,18 @@ export {
  getLibraryMaterialIdFromRef,
  getMaterialPresetByRef,
  getMaterialsForCategory,
+  getSceneMaterialIdFromRef,
  LIBRARY_MATERIAL_REF_PREFIX,
  MATERIAL_CATALOG,
  MATERIAL_CATEGORIES,
  type MaterialCatalogItem,
  type MaterialCategory,
+  type MaterialRef,
+  type ParsedMaterialRef,
+  parseMaterialRef,
+  SCENE_MATERIAL_REF_PREFIX,
  toLibraryMaterialRef,
+  toSceneMaterialRef,
 } from './material-library'
 export type {
  FloorPlacedFootprint,
@@ -0,0 +1,27 @@
+export const SLOT_MATERIAL_PREFIX = 'slot_'
+
+/** A glTF material name marks a paintable slot when it starts with `slot_` (case-insensitive). */
+export function isSlotMaterialName(name: string): boolean {
+  return name.toLowerCase().startsWith(SLOT_MATERIAL_PREFIX)
+}
+
+/**
+ * Derive the stable slot id from a glTF material name:
+ * strip the `slot_` prefix (case-insensitive), drop Blender numeric dedupe
+ * suffixes like `.001`, lowercase the remainder. Returns null when the name
+ * is not a slot material. Used by BOTH the upload scan (later) and the
+ * renderer so DB metadata and runtime meshes can never drift.
+ */
+export function deriveSlotId(materialName: string): string | null {
+  if (!isSlotMaterialName(materialName)) return null
+  let rest = materialName.slice(SLOT_MATERIAL_PREFIX.length)
+  rest = rest.replace(/\.\d+$/, '')
+  return rest.toLowerCase()
+}
+
+/** slot id -> display label: underscores to spaces, sentence case. e.g. 'bed_frame' -> 'Bed frame'. */
+export function slotLabelFromId(slotId: string): string {
+  const spaced = slotId.replace(/_/g, ' ').trim()
+  if (!spaced) return spaced
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1)
+}
@@ -2423,17 +2423,39 @@ export function getCatalogMaterialById(id?: string): MaterialCatalogItem | undef
 }

 export const LIBRARY_MATERIAL_REF_PREFIX = 'library:'
+export const SCENE_MATERIAL_REF_PREFIX = 'scene:'

 export function toLibraryMaterialRef(id: string) {
  return `${LIBRARY_MATERIAL_REF_PREFIX}${id}`
 }

+export function toSceneMaterialRef(id: string) {
+  return `${SCENE_MATERIAL_REF_PREFIX}${id}`
+}
+
 export function getLibraryMaterialIdFromRef(materialRef?: string | null) {
  if (!materialRef) return null
  if (!materialRef.startsWith(LIBRARY_MATERIAL_REF_PREFIX)) return null
  return materialRef.slice(LIBRARY_MATERIAL_REF_PREFIX.length)
 }

+export function getSceneMaterialIdFromRef(materialRef?: string | null): string | null {
+  if (!materialRef || !materialRef.startsWith(SCENE_MATERIAL_REF_PREFIX)) return null
+  return materialRef.slice(SCENE_MATERIAL_REF_PREFIX.length)
+}
+
+export type MaterialRef = string
+
+export type ParsedMaterialRef = { kind: 'library'; id: string } | { kind: 'scene'; id: string }
+
+export function parseMaterialRef(ref?: string | null): ParsedMaterialRef | null {
+  const lib = getLibraryMaterialIdFromRef(ref)
+  if (lib) return { kind: 'library', id: lib }
+  const scene = getSceneMaterialIdFromRef(ref)
+  if (scene) return { kind: 'scene', id: scene }
+  return null
+}
+
 export function getMaterialPresetByRef(materialRef?: string | null): MaterialPresetPayload | null {
  const materialId = getLibraryMaterialIdFromRef(materialRef)
  if (!materialId) return null
@@ -1126,6 +1126,14 @@ export type PaintCapability = {
   * `role`. Returned partial is merged into the node by the editor.
   */
  buildPatch: (args: PaintPatchArgs) => Partial<AnyNode>
+  /**
+   * Optional: fully own the click-commit instead of the default
+   * `updateNode(node.id, buildPatch(...))`. Kinds whose commit has a side
+   * effect (items create a scene material for one-off colours, then store a
+   * `scene:<id>` ref) implement this; kinds that just patch the node omit it.
+   * Must perform its mutations as a single undo step.
+   */
+  commit?: (args: PaintPatchArgs) => void
  /**
   * Apply a preview to the kind's registered mesh subtree at
   * `role`. The kind builds whatever preview material(s) it needs
@@ -1169,6 +1177,8 @@ export type PaintResolveArgs = {
  localPosition?: readonly [number, number, number]
  /** Optional: name of the three.js object that received the hit. Stair uses this. */
  hitObjectName?: string
+  /** Optional: the three.js object that received the pointer hit. Items read userData.slotId off it. */
+  hitObject?: Object3D
 }

 export type PaintPatchArgs = {
@@ -158,6 +158,7 @@ export {
 } from './nodes/wall'
 export { WindowNode, WindowType } from './nodes/window'
 export { ZoneNode } from './nodes/zone'
+export { generateSceneMaterialId, SceneMaterial, type SceneMaterialId } from './scene-material'
 export type { AnyNodeId, AnyNodeType } from './types'
 // Union types
 export { AnyNode } from './types'
@@ -146,6 +146,11 @@ export const ItemNode = BaseNode.extend({
  // Denormalized references to collections this node belongs to
  collectionIds: z.array(z.custom<CollectionId>()).optional(),

+  // Per-slot material overrides. Key = slot id (see deriveSlotId), value = a
+  // MaterialRef string ('library:<id>' or 'scene:<id>'). Absent = authored /
+  // registry default. A dangling ref renders the default (never blocks).
+  slots: z.record(z.string(), z.string()).optional(),
+
  asset: assetSchema,
 }).describe(dedent`Item node - used to represent a item in the building
  - position: position in level coordinate system (or parent coordinate system if attached)
@@ -0,0 +1,13 @@
+import { z } from 'zod'
+import { generateId } from './base'
+import { MaterialSchema } from './material'
+
+export type SceneMaterialId = `mat_${string}`
+export const generateSceneMaterialId = (): SceneMaterialId => generateId('mat')
+
+export const SceneMaterial = z.object({
+  id: z.string(),
+  name: z.string(),
+  material: MaterialSchema,
+})
+export type SceneMaterial = z.infer<typeof SceneMaterial>
@@ -20,6 +20,7 @@ import { ShelfNode as ShelfNodeSchema } from '../schema/nodes/shelf'
 import { SiteNode } from '../schema/nodes/site'
 import { StairNode as StairNodeSchema } from '../schema/nodes/stair'
 import { StairSegmentNode as StairSegmentNodeSchema } from '../schema/nodes/stair-segment'
+import type { SceneMaterial, SceneMaterialId } from '../schema/scene-material'
 import type { AnyNode, AnyNodeId } from '../schema/types'
 import * as nodeActions from './actions/node-actions'
 import { resetSceneHistoryPauseDepth } from './history-control'
@@ -694,6 +695,7 @@ export type SceneState = {

  // 4. Relational metadata — not nodes
  collections: Record<CollectionId, Collection>
+  materials: Record<SceneMaterialId, SceneMaterial>

  // 5. Read-only lock — when true all create/update/delete operations are no-ops
  readOnly: boolean
@@ -703,7 +705,14 @@ export type SceneState = {
  loadScene: () => void
  clearScene: () => void
  unloadScene: () => void
-  setScene: (nodes: Record<AnyNodeId, AnyNode>, rootNodeIds: AnyNodeId[]) => void
+  setScene: (
+    nodes: Record<AnyNodeId, AnyNode>,
+    rootNodeIds: AnyNodeId[],
+    extra?: {
+      collections?: Record<CollectionId, Collection>
+      materials?: Record<SceneMaterialId, SceneMaterial>
+    },
+  ) => void

  markDirty: (id: AnyNodeId) => void
  clearDirty: (id: AnyNodeId) => void
@@ -728,12 +737,19 @@ export type SceneState = {
  updateCollection: (id: CollectionId, data: Partial<Omit<Collection, 'id'>>) => void
  addToCollection: (id: CollectionId, nodeId: AnyNodeId) => void
  removeFromCollection: (id: CollectionId, nodeId: AnyNodeId) => void
+
+  // Scene material actions
+  addSceneMaterial: (material: SceneMaterial) => void
+  updateSceneMaterial: (id: SceneMaterialId, data: Partial<Omit<SceneMaterial, 'id'>>) => void
+  removeSceneMaterial: (id: SceneMaterialId) => void
 }

 // type PartializedStoreState = Pick<SceneState, 'rootNodeIds' | 'nodes'>;

 type UseSceneStore = UseBoundStore<StoreApi<SceneState>> & {
-  temporal: StoreApi<TemporalState<Pick<SceneState, 'nodes' | 'rootNodeIds' | 'collections'>>>
+  temporal: StoreApi<
+    TemporalState<Pick<SceneState, 'nodes' | 'rootNodeIds' | 'collections' | 'materials'>>
+  >
 }

 const useScene: UseSceneStore = create<SceneState>()(
@@ -750,6 +766,7 @@ const useScene: UseSceneStore = create<SceneState>()(

      // 4. Collections
      collections: {} as Record<CollectionId, Collection>,
+      materials: {} as Record<SceneMaterialId, SceneMaterial>,

      // 5. Read-only lock
      readOnly: false,
@@ -761,6 +778,7 @@ const useScene: UseSceneStore = create<SceneState>()(
          rootNodeIds: [],
          dirtyNodes: new Set<AnyNodeId>(),
          collections: {},
+          materials: {},
        })
      },

@@ -769,7 +787,7 @@ const useScene: UseSceneStore = create<SceneState>()(
        get().loadScene() // Default scene
      },

-      setScene: (nodes, rootNodeIds) => {
+      setScene: (nodes, rootNodeIds, extra) => {
        // Apply backward compatibility migrations
        const patchedNodes = migrateNodes(nodes)

@@ -792,7 +810,8 @@ const useScene: UseSceneStore = create<SceneState>()(
          nodes: cleanedNodes,
          rootNodeIds,
          dirtyNodes: new Set<AnyNodeId>(),
-          collections: {},
+          collections: extra?.collections ?? {},
+          materials: extra?.materials ?? {},
        })

        const normalizedRootNodeIds = normalizeRootNodeIds(cleanedNodes, rootNodeIds)
@@ -809,7 +828,8 @@ const useScene: UseSceneStore = create<SceneState>()(
          nodes: cleanedNodes,
          rootNodeIds: normalizedRootNodeIds,
          dirtyNodes: new Set<AnyNodeId>(),
-          collections: {},
+          collections: extra?.collections ?? {},
+          materials: extra?.materials ?? {},
        })
        // Mark all nodes as dirty to trigger re-validation
        Object.values(cleanedNodes).forEach((node) => {
@@ -969,11 +989,38 @@ const useScene: UseSceneStore = create<SceneState>()(
          return { collections: nextCollections, nodes: nextNodes }
        })
      },
+
+      // --- SCENE MATERIALS ---
+
+      addSceneMaterial: (material) => {
+        if (get().readOnly) return
+        set((state) => ({
+          materials: { ...state.materials, [material.id]: material },
+        }))
+      },
+
+      updateSceneMaterial: (id, data) => {
+        if (get().readOnly) return
+        set((state) => {
+          const material = state.materials[id]
+          if (!material) return state
+          return { materials: { ...state.materials, [id]: { ...material, ...data } } }
+        })
+      },
+
+      removeSceneMaterial: (id) => {
+        if (get().readOnly) return
+        set((state) => {
+          const materials = { ...state.materials }
+          delete materials[id]
+          return { materials }
+        })
+      },
    }),
    {
      partialize: (state) => {
-        const { nodes, rootNodeIds, collections } = state
-        return { nodes, rootNodeIds, collections }
+        const { nodes, rootNodeIds, collections, materials } = state
+        return { nodes, rootNodeIds, collections, materials }
      },
      limit: 50, // Limit to last 50 actions
    },
@@ -906,6 +906,7 @@ export const SelectionManager = () => {
          normal: event.normal,
          localPosition: event.localPosition as readonly [number, number, number] | undefined,
          hitObjectName: event.nativeEvent.object?.name,
+          hitObject: getEventObject(event),
        })
        const compatible = role !== null && paintEnabled
        return {
@@ -915,15 +916,22 @@ export const SelectionManager = () => {
          apply:
            compatible && role
              ? () => {
-                  useScene.getState().updateNode(
-                    node.id as AnyNodeId,
-                    paintCap.buildPatch({
-                      node,
-                      role,
-                      material: paintSpec.material,
-                      materialPreset: paintSpec.materialPreset,
-                    }) as Partial<AnyNode>,
-                  )
+                  const args = {
+                    node,
+                    role,
+                    material: paintSpec.material,
+                    materialPreset: paintSpec.materialPreset,
+                  }
+                  if (paintCap.commit) {
+                    paintCap.commit(args)
+                  } else {
+                    useScene
+                      .getState()
+                      .updateNode(
+                        node.id as AnyNodeId,
+                        paintCap.buildPatch(args) as Partial<AnyNode>,
+                      )
+                  }
                }
              : null,
          preview:
@@ -1086,7 +1094,7 @@ export const SelectionManager = () => {
        }
      }

-      const disabledNodeTypes = ['item', 'window', 'door', 'zone']
+      const disabledNodeTypes = ['window', 'door', 'zone']
      if (disabledNodeTypes.includes(node.type)) {
        return {
          key: `${node.type}:${node.id}:unsupported`,
@@ -1549,6 +1557,7 @@ export const SelectionManager = () => {
              normal: event.normal,
              localPosition: event.localPosition as readonly [number, number, number] | undefined,
              hitObjectName: event.nativeEvent.object?.name,
+              hitObject: getEventObject(event),
            })
            if (role) {
              setSelectedMaterialTargetForNode(nodeToSelect, role as MaterialTargetRole)
@@ -1930,7 +1939,8 @@ const SelectionStateSync = () => {
    const selectedNode = useScene.getState().nodes[singleSelectedId as AnyNodeId]
    if (
      !selectedNode ||
-      (selectedNode.type !== 'wall' &&
+      (!nodeRegistry.get(selectedNode.type)?.capabilities?.paint &&
+        selectedNode.type !== 'wall' &&
        selectedNode.type !== 'fence' &&
        selectedNode.type !== 'slab' &&
        selectedNode.type !== 'ceiling' &&
@@ -11,6 +11,8 @@ import {
 import useEditor from './../../../store/use-editor'
 import { Button } from '../primitives/button'
 import { MaterialPicker } from './material-picker'
+import { PanelSection } from './panel-section'
+import { SceneMaterialList } from './scene-material-list'

 /**
 * Material picker for paint mode. Embedders render this wherever paint controls
@@ -27,6 +29,7 @@ export function MaterialPaintPanel() {
  const setPaintEraser = useEditor((state) => state.setPaintEraser)
  const selectedIds = useViewer((state) => state.selection.selectedIds)
  const nodes = useScene((state) => state.nodes)
+  const materialCount = useScene((state) => Object.keys(state.materials).length)
  const selectedId = selectedIds.length === 1 ? (selectedIds[0] ?? null) : null
  const selectedNode = selectedId ? nodes[selectedId as AnyNodeId] : null
  const canResetSelection =
@@ -78,6 +81,11 @@ export function MaterialPaintPanel() {
        selectedMaterialPreset={activePaintMaterial?.materialPreset}
        value={activePaintMaterial?.material}
      />
+      {materialCount > 0 ? (
+        <PanelSection title="Scene materials">
+          <SceneMaterialList />
+        </PanelSection>
+      ) : null}
    </div>
  )
 }
@@ -10,6 +10,7 @@ import {
  toLibraryMaterialRef,
 } from '@pascal-app/core'
 import { useEffect, useRef, useState } from 'react'
+import { CURATED_COLORS } from '../../../lib/colors'
 import useEditor from '../../../store/use-editor'

 type MaterialPickerProps = {
@@ -55,7 +56,8 @@ export function MaterialPicker({
      return
    }

-    const catalogId = getLibraryMaterialIdFromRef(selectedMaterialPreset) ?? value?.id ?? undefined
+    const catalogId =
+      getLibraryMaterialIdFromRef(selectedMaterialPreset) ?? value?.id ?? undefined
    const selectedCatalogEntry = getCatalogMaterialById(catalogId)
    if (selectedCatalogEntry?.category) {
      setSelectedCategory(selectedCatalogEntry.category)
@@ -64,6 +66,9 @@ export function MaterialPicker({

  const selectedCatalogId =
    selectedMaterialPreset ?? (value?.id ? toLibraryMaterialRef(value.id) : undefined)
+  const selectedCatalogMaterialId = getLibraryMaterialIdFromRef(selectedCatalogId) ?? undefined
+  const selectedCatalogEntry = getCatalogMaterialById(selectedCatalogMaterialId)
+  const selectedColor = value?.properties?.color.toLowerCase()

  const handleCatalogSelect = (materialId: string) => {
    if (disabled) return
@@ -72,6 +77,23 @@ export function MaterialPicker({
    onSelectMaterialPreset?.(toLibraryMaterialRef(materialId))
  }

+  const handleColorSelect = (hex: string) => {
+    if (disabled) return
+    setShowCustom(false)
+    setPaintPanelOpen(false)
+    onChange?.({
+      preset: 'custom',
+      properties: {
+        color: hex,
+        roughness: 0.6,
+        metalness: 0,
+        opacity: 1,
+        transparent: false,
+        side: 'front',
+      },
+    })
+  }
+
  useEffect(() => {
    const container = categoryScrollRef.current
    if (!container) return
@@ -97,10 +119,13 @@ export function MaterialPicker({
    if (disabled) return
    setShowCustom(true)
    setPaintPanelOpen(true)
+    const forkColor = selectedMaterialPreset
+      ? (selectedCatalogEntry?.previewColor ?? '#ffffff')
+      : '#ffffff'
    onChange?.({
      preset: 'custom',
      properties: {
-        color: value?.properties?.color || '#ffffff',
+        color: value?.properties?.color || forkColor,
        roughness: value?.properties?.roughness ?? 0.5,
        metalness: value?.properties?.metalness ?? 0,
        opacity: value?.properties?.opacity ?? 1,
@@ -114,6 +139,33 @@ export function MaterialPicker({
    <div className={`min-w-0 space-y-3 ${disabled ? 'pointer-events-none opacity-50' : ''}`}>
      {(catalogItems.length > 0 || onChange) && (
        <div className="min-w-0 space-y-1">
+          {onChange ? (
+            <div className="space-y-1.5">
+              <div className="font-medium text-[11px] text-muted-foreground uppercase tracking-[0.12em]">
+                Colors
+              </div>
+              <div className="flex flex-wrap gap-1.5">
+                {CURATED_COLORS.map((color) => {
+                  const isSelected = selectedColor === color.hex.toLowerCase()
+                  return (
+                    <button
+                      aria-label={color.name}
+                      className={`h-7 w-7 rounded-md border transition-all ${
+                        isSelected
+                          ? 'border-blue-500 ring-2 ring-blue-500/30'
+                          : 'border-gray-300 hover:border-gray-400'
+                      }`}
+                      key={color.hex}
+                      onClick={() => handleColorSelect(color.hex)}
+                      style={{ backgroundColor: color.hex }}
+                      title={color.name}
+                      type="button"
+                    />
+                  )
+                })}
+              </div>
+            </div>
+          ) : null}
          <div
            className="w-full max-w-full overflow-x-auto overflow-y-hidden"
            ref={categoryScrollRef}
@@ -149,45 +201,48 @@ export function MaterialPicker({
            style={{ gridTemplateColumns: 'repeat(auto-fill, minmax(72px, 1fr))' }}
          >
            {catalogItems.map((item) => (
-                <button
-                  className={`relative aspect-square w-full overflow-hidden rounded-lg border transition-all ${
-                    selectedCatalogId === toLibraryMaterialRef(item.id)
-                      ? 'border-blue-500 ring-2 ring-blue-500/30'
-                      : 'border-gray-300 hover:border-gray-400'
-                  }`}
-                  key={item.id}
-                  onClick={() => handleCatalogSelect(item.id)}
-                  title={item.label}
-                  type="button"
-                >
-                  <div className="pointer-events-none absolute inset-0 rounded-[inherit] ring-1 ring-white/12 ring-inset" />
-                  {item.previewThumbnailUrl ? (
-                    <img
-                      alt={item.label}
-                      className="h-full w-full object-cover"
-                      src={item.previewThumbnailUrl}
-                    />
-                  ) : item.previewColor ? (
-                    <div className="h-full w-full" style={{ backgroundColor: item.previewColor }} />
-                  ) : (
-                    <div className="h-full w-full bg-gray-100" />
-                  )}
-                </button>
-              ))}
-              {selectedCategory === 'other' && onChange ? (
-                <button
-                  className={`flex aspect-square w-full items-center justify-center rounded-lg border font-medium text-[10px] transition-all ${
-                    showCustom
-                      ? 'border-blue-500 ring-2 ring-blue-500/30'
-                      : 'border-gray-300 hover:border-gray-400'
-                  }`}
-                  onClick={handleCustomOpen}
-                  title="Custom"
-                  type="button"
-                >
-                  Custom
-                </button>
-              ) : null}
+              <button
+                className={`relative aspect-square w-full overflow-hidden rounded-lg border transition-all ${
+                  selectedCatalogId === toLibraryMaterialRef(item.id)
+                    ? 'border-blue-500 ring-2 ring-blue-500/30'
+                    : 'border-gray-300 hover:border-gray-400'
+                }`}
+                key={item.id}
+                onClick={() => handleCatalogSelect(item.id)}
+                title={item.label}
+                type="button"
+              >
+                <div className="pointer-events-none absolute inset-0 rounded-[inherit] ring-1 ring-white/12 ring-inset" />
+                {item.previewThumbnailUrl ? (
+                  <img
+                    alt={item.label}
+                    className="h-full w-full object-cover"
+                    src={item.previewThumbnailUrl}
+                  />
+                ) : item.previewColor ? (
+                  <div
+                    className="h-full w-full"
+                    style={{ backgroundColor: item.previewColor }}
+                  />
+                ) : (
+                  <div className="h-full w-full bg-gray-100" />
+                )}
+              </button>
+            ))}
+            {selectedCategory === 'other' && onChange ? (
+              <button
+                className={`flex aspect-square w-full items-center justify-center rounded-lg border font-medium text-[10px] transition-all ${
+                  showCustom
+                    ? 'border-blue-500 ring-2 ring-blue-500/30'
+                    : 'border-gray-300 hover:border-gray-400'
+                }`}
+                onClick={handleCustomOpen}
+                title="Custom"
+                type="button"
+              >
+                Custom
+              </button>
+            ) : null}
          </div>
        </div>
      )}
@@ -0,0 +1,140 @@
+'use client'
+
+import type { MaterialProperties, MaterialSchema } from '@pascal-app/core'
+import { Input } from '../primitives/input'
+
+const DEFAULT_MATERIAL_PROPERTIES: MaterialProperties = {
+  color: '#ffffff',
+  roughness: 0.5,
+  metalness: 0,
+  opacity: 1,
+  transparent: false,
+  side: 'front',
+}
+
+export function MaterialPropertiesEditor({
+  value,
+  onChange,
+}: {
+  value: MaterialSchema
+  onChange: (next: MaterialSchema) => void
+}) {
+  const currentProps = value.properties ?? DEFAULT_MATERIAL_PROPERTIES
+
+  const updateMaterial = (
+    updates: Partial<MaterialProperties>,
+    nextTransparent = currentProps.transparent,
+  ) => {
+    onChange({
+      ...value,
+      preset: value.preset ?? 'custom',
+      properties: {
+        ...currentProps,
+        ...updates,
+        transparent: nextTransparent,
+      },
+    })
+  }
+
+  return (
+    <div className="space-y-3">
+      <div className="space-y-2">
+        <label className="block font-medium text-muted-foreground text-xs uppercase tracking-[0.12em]">
+          Color
+        </label>
+        <div className="flex items-center gap-2">
+          <input
+            className="h-10 w-14 cursor-pointer rounded-md border border-input bg-transparent"
+            onChange={(e) => updateMaterial({ color: e.target.value })}
+            type="color"
+            value={currentProps.color}
+          />
+          <Input
+            onChange={(e) => updateMaterial({ color: e.target.value })}
+            value={currentProps.color}
+          />
+        </div>
+      </div>
+
+      <div className="space-y-2">
+        <div className="flex items-center justify-between">
+          <label className="font-medium text-muted-foreground text-xs uppercase tracking-[0.12em]">
+            Roughness
+          </label>
+          <span className="font-mono text-muted-foreground text-xs">
+            {currentProps.roughness.toFixed(2)}
+          </span>
+        </div>
+        <input
+          className="h-2 w-full cursor-pointer appearance-none rounded-full bg-accent"
+          max={1}
+          min={0}
+          onChange={(e) => updateMaterial({ roughness: Number.parseFloat(e.target.value) })}
+          step={0.01}
+          type="range"
+          value={currentProps.roughness}
+        />
+      </div>
+
+      <div className="space-y-2">
+        <div className="flex items-center justify-between">
+          <label className="font-medium text-muted-foreground text-xs uppercase tracking-[0.12em]">
+            Metalness
+          </label>
+          <span className="font-mono text-muted-foreground text-xs">
+            {currentProps.metalness.toFixed(2)}
+          </span>
+        </div>
+        <input
+          className="h-2 w-full cursor-pointer appearance-none rounded-full bg-accent"
+          max={1}
+          min={0}
+          onChange={(e) => updateMaterial({ metalness: Number.parseFloat(e.target.value) })}
+          step={0.01}
+          type="range"
+          value={currentProps.metalness}
+        />
+      </div>
+
+      <div className="space-y-2">
+        <div className="flex items-center justify-between">
+          <label className="font-medium text-muted-foreground text-xs uppercase tracking-[0.12em]">
+            Opacity
+          </label>
+          <span className="font-mono text-muted-foreground text-xs">
+            {currentProps.opacity.toFixed(2)}
+          </span>
+        </div>
+        <input
+          className="h-2 w-full cursor-pointer appearance-none rounded-full bg-accent"
+          max={1}
+          min={0}
+          onChange={(e) => {
+            const opacity = Number.parseFloat(e.target.value)
+            updateMaterial({ opacity }, opacity < 1 || currentProps.transparent)
+          }}
+          step={0.01}
+          type="range"
+          value={currentProps.opacity}
+        />
+      </div>
+
+      <div className="space-y-2">
+        <label className="block font-medium text-muted-foreground text-xs uppercase tracking-[0.12em]">
+          Side
+        </label>
+        <select
+          className="h-9 w-full rounded-md border border-input bg-transparent px-3 text-sm shadow-xs outline-none transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 dark:bg-input/30"
+          onChange={(e) =>
+            updateMaterial({ side: e.target.value as 'front' | 'back' | 'double' })
+          }
+          value={currentProps.side}
+        >
+          <option value="front">Front</option>
+          <option value="back">Back</option>
+          <option value="double">Double</option>
+        </select>
+      </div>
+    </div>
+  )
+}
@@ -0,0 +1,218 @@
+'use client'
+
+import {
+  generateSceneMaterialId,
+  type MaterialSchema,
+  type SceneMaterial,
+  type SceneMaterialId,
+  toSceneMaterialRef,
+  useScene,
+} from '@pascal-app/core'
+import { Copy, Paintbrush, Pencil, Trash2 } from 'lucide-react'
+import { useEffect, useMemo, useState } from 'react'
+import useEditor from '../../../store/use-editor'
+import { Button } from '../primitives/button'
+import { Input } from '../primitives/input'
+import { MaterialPropertiesEditor } from './material-properties-editor'
+
+type SlotRecord = Record<string, string | undefined>
+
+function getSlotRecord(node: unknown): SlotRecord | null {
+  if (!node || typeof node !== 'object' || !('slots' in node)) return null
+  const slots = (node as { slots?: unknown }).slots
+  if (!slots || typeof slots !== 'object' || Array.isArray(slots)) return null
+  return slots as SlotRecord
+}
+
+export function SceneMaterialList() {
+  const materials = useScene((state) => state.materials)
+  const nodes = useScene((state) => state.nodes)
+  const addSceneMaterial = useScene((state) => state.addSceneMaterial)
+  const updateSceneMaterial = useScene((state) => state.updateSceneMaterial)
+  const removeSceneMaterial = useScene((state) => state.removeSceneMaterial)
+  const activePaintTarget = useEditor((state) => state.activePaintTarget)
+  const setActivePaintMaterial = useEditor((state) => state.setActivePaintMaterial)
+
+  const materialEntries = useMemo(
+    () => Object.entries(materials) as [SceneMaterialId, SceneMaterial][],
+    [materials],
+  )
+
+  const usageCounts = useMemo(() => {
+    const counts = new Map<SceneMaterialId, number>()
+    const refToId = new Map<string, SceneMaterialId>()
+
+    for (const [id] of materialEntries) {
+      counts.set(id, 0)
+      refToId.set(toSceneMaterialRef(id), id)
+    }
+
+    for (const node of Object.values(nodes)) {
+      const slots = getSlotRecord(node)
+      if (!slots) continue
+
+      for (const value of Object.values(slots)) {
+        if (typeof value !== 'string') continue
+        const materialId = refToId.get(value)
+        if (!materialId) continue
+        counts.set(materialId, (counts.get(materialId) ?? 0) + 1)
+      }
+    }
+
+    return counts
+  }, [materialEntries, nodes])
+
+  return (
+    <div className="space-y-2">
+      {materialEntries.map(([id, sceneMaterial]) => (
+        <SceneMaterialRow
+          addSceneMaterial={addSceneMaterial}
+          activePaintTarget={activePaintTarget}
+          id={id}
+          key={id}
+          removeSceneMaterial={removeSceneMaterial}
+          sceneMaterial={sceneMaterial}
+          setActivePaintMaterial={setActivePaintMaterial}
+          updateSceneMaterial={updateSceneMaterial}
+          usageCount={usageCounts.get(id) ?? 0}
+        />
+      ))}
+    </div>
+  )
+}
+
+function SceneMaterialRow({
+  id,
+  sceneMaterial,
+  usageCount,
+  activePaintTarget,
+  addSceneMaterial,
+  updateSceneMaterial,
+  removeSceneMaterial,
+  setActivePaintMaterial,
+}: {
+  id: SceneMaterialId
+  sceneMaterial: SceneMaterial
+  usageCount: number
+  activePaintTarget: ReturnType<typeof useEditor.getState>['activePaintTarget']
+  addSceneMaterial: ReturnType<typeof useScene.getState>['addSceneMaterial']
+  updateSceneMaterial: ReturnType<typeof useScene.getState>['updateSceneMaterial']
+  removeSceneMaterial: ReturnType<typeof useScene.getState>['removeSceneMaterial']
+  setActivePaintMaterial: ReturnType<typeof useEditor.getState>['setActivePaintMaterial']
+}) {
+  const [isEditingMaterial, setIsEditingMaterial] = useState(false)
+  const [draftName, setDraftName] = useState(sceneMaterial.name)
+  const swatchColor = sceneMaterial.material.properties?.color ?? '#ffffff'
+
+  useEffect(() => {
+    setDraftName(sceneMaterial.name)
+  }, [sceneMaterial.name])
+
+  const commitName = () => {
+    const nextName = draftName.trim()
+    if (!nextName) {
+      setDraftName(sceneMaterial.name)
+      return
+    }
+    if (nextName !== sceneMaterial.name) {
+      updateSceneMaterial(id, { name: nextName })
+    }
+  }
+
+  const duplicateMaterial = () => {
+    addSceneMaterial({
+      id: generateSceneMaterialId(),
+      name: `${sceneMaterial.name} copy`,
+      material: structuredClone(sceneMaterial.material) as MaterialSchema,
+    })
+  }
+
+  return (
+    <div className="rounded-md border border-border/60 bg-background/40 p-2">
+      <div className="flex items-center gap-2">
+        <span
+          className="h-8 w-8 shrink-0 rounded-md border border-border/70"
+          style={{ backgroundColor: swatchColor }}
+        />
+        <Input
+          className="h-8 px-2 text-sm"
+          onBlur={commitName}
+          onChange={(e) => setDraftName(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') {
+              e.currentTarget.blur()
+            }
+            if (e.key === 'Escape') {
+              setDraftName(sceneMaterial.name)
+              e.currentTarget.blur()
+            }
+          }}
+          value={draftName}
+        />
+      </div>
+
+      <div className="mt-2 flex items-center justify-between gap-2">
+        <span className="text-muted-foreground text-xs">
+          Used by {usageCount} {usageCount === 1 ? 'part' : 'parts'}
+        </span>
+        <div className="flex items-center gap-1">
+          <Button
+            aria-label="Paint with"
+            onClick={() =>
+              setActivePaintMaterial({
+                material: sceneMaterial.material,
+                sourceTarget: activePaintTarget,
+              })
+            }
+            size="icon-sm"
+            title="Paint with"
+            type="button"
+            variant="outline"
+          >
+            <Paintbrush />
+          </Button>
+          <Button
+            aria-label="Edit"
+            aria-pressed={isEditingMaterial}
+            onClick={() => setIsEditingMaterial((value) => !value)}
+            size="icon-sm"
+            title="Edit"
+            type="button"
+            variant={isEditingMaterial ? 'default' : 'outline'}
+          >
+            <Pencil />
+          </Button>
+          <Button
+            aria-label="Duplicate"
+            onClick={duplicateMaterial}
+            size="icon-sm"
+            title="Duplicate"
+            type="button"
+            variant="outline"
+          >
+            <Copy />
+          </Button>
+          <Button
+            aria-label="Delete"
+            onClick={() => removeSceneMaterial(id)}
+            size="icon-sm"
+            title="Delete"
+            type="button"
+            variant="outline"
+          >
+            <Trash2 />
+          </Button>
+        </div>
+      </div>
+
+      {isEditingMaterial ? (
+        <div className="mt-3 border-border/60 border-t pt-3">
+          <MaterialPropertiesEditor
+            onChange={(material) => updateSceneMaterial(id, { material })}
+            value={sceneMaterial.material}
+          />
+        </div>
+      ) : null}
+    </div>
+  )
+}
@@ -1,24 +1,10 @@
 'use client'

 import useEditor from '../../../store/use-editor'
+import { MaterialPropertiesEditor } from '../controls/material-properties-editor'
 import { PanelSection } from '../controls/panel-section'
-import { Input } from '../primitives/input'
 import { PanelWrapper } from './panel-wrapper'

-function buildDefaultCustomMaterial() {
-  return {
-    preset: 'custom' as const,
-    properties: {
-      color: '#ffffff',
-      roughness: 0.5,
-      metalness: 0,
-      opacity: 1,
-      transparent: false,
-      side: 'front' as const,
-    },
-  }
-}
-
 export function PaintPanel() {
  const activePaintMaterial = useEditor((state) => state.activePaintMaterial)
  const activePaintTarget = useEditor((state) => state.activePaintTarget)
@@ -32,131 +18,18 @@ export function PaintPanel() {

  if (!customMaterial) return null

-  const currentProps = customMaterial.properties ?? buildDefaultCustomMaterial().properties
-
-  const updateCustomMaterial = (
-    updates: Partial<typeof currentProps>,
-    nextTransparent = currentProps.transparent,
-  ) => {
-    setActivePaintMaterial({
-      material: {
-        preset: 'custom',
-        properties: {
-          ...currentProps,
-          ...updates,
-          transparent: nextTransparent,
-        },
-      },
-      sourceTarget: activePaintMaterial?.sourceTarget ?? activePaintTarget,
-    })
-  }
-
  return (
    <PanelWrapper onClose={() => setPaintPanelOpen(false)} title="Material" width={320}>
-      <PanelSection title="Custom Material">
-        <div className="space-y-3">
-          <div className="space-y-2">
-            <label className="block font-medium text-muted-foreground text-xs uppercase tracking-[0.12em]">
-              Color
-            </label>
-            <div className="flex items-center gap-2">
-              <input
-                className="h-10 w-14 cursor-pointer rounded-md border border-input bg-transparent"
-                onChange={(e) => updateCustomMaterial({ color: e.target.value })}
-                type="color"
-                value={currentProps.color}
-              />
-              <Input
-                onChange={(e) => updateCustomMaterial({ color: e.target.value })}
-                value={currentProps.color}
-              />
-            </div>
-          </div>
-
-          <div className="space-y-2">
-            <div className="flex items-center justify-between">
-              <label className="font-medium text-muted-foreground text-xs uppercase tracking-[0.12em]">
-                Roughness
-              </label>
-              <span className="font-mono text-muted-foreground text-xs">
-                {currentProps.roughness.toFixed(2)}
-              </span>
-            </div>
-            <input
-              className="h-2 w-full cursor-pointer appearance-none rounded-full bg-accent"
-              max={1}
-              min={0}
-              onChange={(e) =>
-                updateCustomMaterial({ roughness: Number.parseFloat(e.target.value) })
-              }
-              step={0.01}
-              type="range"
-              value={currentProps.roughness}
-            />
-          </div>
-
-          <div className="space-y-2">
-            <div className="flex items-center justify-between">
-              <label className="font-medium text-muted-foreground text-xs uppercase tracking-[0.12em]">
-                Metalness
-              </label>
-              <span className="font-mono text-muted-foreground text-xs">
-                {currentProps.metalness.toFixed(2)}
-              </span>
-            </div>
-            <input
-              className="h-2 w-full cursor-pointer appearance-none rounded-full bg-accent"
-              max={1}
-              min={0}
-              onChange={(e) =>
-                updateCustomMaterial({ metalness: Number.parseFloat(e.target.value) })
-              }
-              step={0.01}
-              type="range"
-              value={currentProps.metalness}
-            />
-          </div>
-
-          <div className="space-y-2">
-            <div className="flex items-center justify-between">
-              <label className="font-medium text-muted-foreground text-xs uppercase tracking-[0.12em]">
-                Opacity
-              </label>
-              <span className="font-mono text-muted-foreground text-xs">
-                {currentProps.opacity.toFixed(2)}
-              </span>
-            </div>
-            <input
-              className="h-2 w-full cursor-pointer appearance-none rounded-full bg-accent"
-              max={1}
-              min={0}
-              onChange={(e) => {
-                const opacity = Number.parseFloat(e.target.value)
-                updateCustomMaterial({ opacity }, opacity < 1 || currentProps.transparent)
-              }}
-              step={0.01}
-              type="range"
-              value={currentProps.opacity}
-            />
-          </div>
-
-          <div className="space-y-2">
-            <label className="block font-medium text-muted-foreground text-xs uppercase tracking-[0.12em]">
-              Side
-            </label>
-            <select
-              className="h-9 w-full rounded-md border border-input bg-transparent px-3 text-sm shadow-xs outline-none transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 dark:bg-input/30"
-              onChange={(e) =>
-                updateCustomMaterial({ side: e.target.value as 'front' | 'back' | 'double' })
-              }
-              value={currentProps.side}
-            >
-              <option value="front">Front</option>
-              <option value="back">Back</option>
-              <option value="double">Double</option>
-            </select>
-          </div>
-        </div>
+      <PanelSection title="Custom material">
+        <MaterialPropertiesEditor
+          onChange={(material) =>
+            setActivePaintMaterial({
+              material,
+              sourceTarget: activePaintMaterial?.sourceTarget ?? activePaintTarget,
+            })
+          }
+          value={customMaterial}
+        />
      </PanelSection>
    </PanelWrapper>
  )
@@ -61,6 +61,12 @@ export function useAutoSave({
  useEffect(() => {
    let lastNodesSnapshot = JSON.stringify(useScene.getState().nodes)
    let lastNodeCount = Object.keys(useScene.getState().nodes).length
+    // Collections + scene materials are document-level state that persists with
+    // the graph but lives outside `nodes`. Track them by reference (zustand
+    // hands out a new object on every mutation) so a material edit or a
+    // collection change still triggers a save.
+    let lastCollectionsRef = useScene.getState().collections
+    let lastMaterialsRef = useScene.getState().materials

    async function executeSave() {
      if (isLoadingSceneRef.current || isVersionPreviewModeRef.current) {
@@ -69,8 +75,8 @@ export function useAutoSave({
        return
      }

-      const { nodes, rootNodeIds } = useScene.getState()
-      const sceneGraph = { nodes, rootNodeIds } as SceneGraph
+      const { nodes, rootNodeIds, collections, materials } = useScene.getState()
+      const sceneGraph = { nodes, rootNodeIds, collections, materials } as SceneGraph

      // Guard: refuse to autosave if the scene went from populated to nearly empty.
      // This catches accidental full deletions before they're persisted.
@@ -118,19 +124,29 @@ export function useAutoSave({
    const unsubscribe = useScene.subscribe((state) => {
      if (isLoadingSceneRef.current) {
        lastNodesSnapshot = JSON.stringify(state.nodes)
+        lastCollectionsRef = state.collections
+        lastMaterialsRef = state.materials
        return
      }

      if (isVersionPreviewModeRef.current) {
        setSaveStatus('paused')
        lastNodesSnapshot = JSON.stringify(state.nodes)
+        lastCollectionsRef = state.collections
+        lastMaterialsRef = state.materials
        return
      }

      const currentNodesSnapshot = JSON.stringify(state.nodes)
-      if (currentNodesSnapshot === lastNodesSnapshot) return
+      const changed =
+        currentNodesSnapshot !== lastNodesSnapshot ||
+        state.collections !== lastCollectionsRef ||
+        state.materials !== lastMaterialsRef
+      if (!changed) return

      lastNodesSnapshot = currentNodesSnapshot
+      lastCollectionsRef = state.collections
+      lastMaterialsRef = state.materials
      hasDirtyChangesRef.current = true
      onDirtyRef.current?.()
      setSaveStatus('pending')
@@ -156,8 +172,8 @@ export function useAutoSave({
    function flushOnExit() {
      if (!hasDirtyChangesRef.current) return
      hasDirtyChangesRef.current = false
-      const { nodes, rootNodeIds } = useScene.getState()
-      const sceneGraph = { nodes, rootNodeIds } as SceneGraph
+      const { nodes, rootNodeIds, collections, materials } = useScene.getState()
+      const sceneGraph = { nodes, rootNodeIds, collections, materials } as SceneGraph
      if (onSaveRef.current) {
        onSaveRef.current(sceneGraph, { keepalive: true }).catch(() => {})
      } else {
@@ -0,0 +1,16 @@
+export const CURATED_COLORS = [
+  { name: 'Warm white', hex: '#f5f1e8' },
+  { name: 'Soft linen', hex: '#e9ddcf' },
+  { name: 'Stone', hex: '#c8c2b8' },
+  { name: 'Clay beige', hex: '#b9a58f' },
+  { name: 'Greige', hex: '#9d9488' },
+  { name: 'Charcoal', hex: '#3c3c3a' },
+  { name: 'Mushroom', hex: '#a38f7b' },
+  { name: 'Terracotta', hex: '#b7654b' },
+  { name: 'Muted ochre', hex: '#c29b52' },
+  { name: 'Sage', hex: '#8d9b82' },
+  { name: 'Olive gray', hex: '#68715f' },
+  { name: 'Dusty blue', hex: '#7d91a3' },
+  { name: 'Slate teal', hex: '#4f7372' },
+  { name: 'Aubergine', hex: '#594354' },
+] as const
@@ -30,24 +30,26 @@ import {
  type WallSurfaceSide,
 } from '@pascal-app/core'

-export type PaintableMaterialTarget = Extract<
-  MaterialTarget,
-  | 'wall'
-  | 'roof'
-  | 'stair'
-  | 'fence'
-  | 'column'
-  | 'slab'
-  | 'ceiling'
-  | 'shelf'
-  | 'chimney'
-  | 'dormer'
-  | 'box-vent'
-  | 'ridge-vent'
-  | 'turbine-vent'
-  | 'cupola'
-  | 'eyebrow-vent'
->
+export type PaintableMaterialTarget =
+  | Extract<
+      MaterialTarget,
+      | 'wall'
+      | 'roof'
+      | 'stair'
+      | 'fence'
+      | 'column'
+      | 'slab'
+      | 'ceiling'
+      | 'shelf'
+      | 'chimney'
+      | 'dormer'
+      | 'box-vent'
+      | 'ridge-vent'
+      | 'turbine-vent'
+      | 'cupola'
+      | 'eyebrow-vent'
+    >
+  | 'item'

 export type SingleSurfaceMaterialRole = 'surface'

@@ -179,6 +181,7 @@ export function buildResetSurfaceMaterialUpdates(
      if (
        key === 'material' ||
        key === 'materialPreset' ||
+        key === 'slots' ||
        key.endsWith('Material') ||
        key.endsWith('MaterialPreset')
      ) {
@@ -276,6 +279,7 @@ export function resolveActivePaintMaterialFromSelection(params: {
      | ChimneyMaterialRole
      | DormerSurfaceMaterialRole
      | SingleSurfaceMaterialRole
+      | string
  } | null
 }): ActivePaintMaterial | null {
  const { nodes, selectedId, selectedMaterialTarget } = params
@@ -444,6 +448,10 @@ export function resolvePaintTargetFromSelection(params: {
    return 'shelf'
  }

+  if (selectedNode.type === 'item') {
+    return 'item'
+  }
+
  if (selectedNode.type === 'chimney') {
    return 'chimney'
  }
@@ -11,6 +11,10 @@ import useEditor, {
 export type SceneGraph = {
  nodes: Record<string, unknown>
  rootNodeIds: string[]
+  // Document-level scene state that travels with the graph. Optional so older
+  // payloads (and callers that only build nodes) stay valid.
+  collections?: Record<string, unknown>
+  materials?: Record<string, unknown>
 }

 type PersistedSelectionPath = {
@@ -374,8 +378,11 @@ function hasUsableSceneGraph(sceneGraph?: SceneGraph | null): sceneGraph is Scen

 export function applySceneGraphToEditor(sceneGraph?: SceneGraph | null) {
  if (hasUsableSceneGraph(sceneGraph)) {
-    const { nodes, rootNodeIds } = sceneGraph
-    useScene.getState().setScene(nodes as any, rootNodeIds as any)
+    const { nodes, rootNodeIds, collections, materials } = sceneGraph
+    useScene.getState().setScene(nodes as any, rootNodeIds as any, {
+      collections: collections as any,
+      materials: materials as any,
+    })
  } else {
    useScene.getState().clearScene()
  }
@@ -168,6 +168,7 @@ export type MaterialTargetRole =
  | ChimneyMaterialRole
  | DormerSurfaceMaterialRole
  | SingleSurfaceMaterialRole
+  | string

 export type SelectedMaterialTarget = {
  nodeId: AnyNodeId
@@ -7,6 +7,7 @@ import {
 } from '@pascal-app/core'
 import { buildItemFloorplan } from './floorplan'
 import { itemFloorplanMoveTarget } from './floorplan-move'
+import { itemPaint } from './paint'
 import { itemParametrics } from './parametrics'
 import { ItemNode } from './schema'

@@ -199,6 +200,7 @@ export const itemDefinition: NodeDefinition<typeof ItemNode> = {
    selectable: { hitVolume: 'bbox' },
    duplicable: true,
    deletable: true,
+    paint: itemPaint,
    // Items participate in compositions — e.g. "table-with-plants",
    // "shelf-with-books-on-top" — so they're presettable in their own
    // right (and as descendants of presettable parents). The GLB-kind
@@ -0,0 +1,249 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  generateSceneMaterialId,
+  type ItemNode,
+  type MaterialSchema,
+  type PaintCapability,
+  parseMaterialRef,
+  type SceneMaterial,
+  type SceneMaterialId,
+  toSceneMaterialRef,
+  useScene,
+} from '@pascal-app/core'
+import { createMaterial, createMaterialFromPresetRef, useViewer } from '@pascal-app/viewer'
+import type { Material, Mesh } from 'three'
+
+type SlotTag = string | null | (string | null)[]
+
+type SlotUserData = {
+  slotId?: SlotTag
+}
+
+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 getSlotTag(mesh: Mesh): SlotTag | undefined {
+  return (mesh.userData as SlotUserData).slotId
+}
+
+function slotTagContainsRole(tag: SlotTag | undefined, role: string): boolean {
+  if (Array.isArray(tag)) return tag.includes(role)
+  return tag === role
+}
+
+function resolveItemSlotId(args: {
+  materialIndex: number | null
+  hitObject?: { userData?: SlotUserData }
+}): string | null {
+  const tag = args.hitObject?.userData?.slotId
+  const slotId = Array.isArray(tag)
+    ? (tag[args.materialIndex ?? 0] ?? null)
+    : typeof tag === 'string'
+      ? tag
+      : null
+  return slotId
+}
+
+function buildItemSlotsPatch(
+  node: ItemNode,
+  role: string,
+  material: MaterialSchema | undefined,
+  materialPreset: string | undefined,
+): Partial<ItemNode> {
+  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: ItemNode['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 || currentNode.type !== 'item') 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 commitItemPaint(
+  node: ItemNode,
+  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 ItemNode | 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 applyItemPreview(
+  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 tag = getSlotTag(mesh)
+    if (!slotTagContainsRole(tag, role)) return
+
+    if (Array.isArray(tag)) {
+      const current = mesh.material as Material | Material[]
+      if (Array.isArray(current)) {
+        const previousArray = [...current]
+        const nextArray = [...current]
+        let changed = false
+        for (let index = 0; index < tag.length; index += 1) {
+          if (tag[index] !== role || !nextArray[index]) continue
+          nextArray[index] = previewMaterial
+          changed = true
+        }
+        if (!changed) return
+        mesh.material = nextArray
+        restores.push(() => {
+          mesh.material = previousArray
+        })
+        return
+      }
+      if (tag[0] !== 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 itemPaint: PaintCapability = {
+  resolveRole: ({ materialIndex, hitObject }) =>
+    resolveItemSlotId({ materialIndex, hitObject: hitObject as { userData?: SlotUserData } }),
+  buildPatch: ({ node, role, material, materialPreset }) =>
+    buildItemSlotsPatch(node as ItemNode, role, material, materialPreset) as Partial<AnyNode>,
+  commit: ({ node, role, material, materialPreset }) =>
+    commitItemPaint(node as ItemNode, role, material, materialPreset),
+  applyPreview: ({ role, root, material, materialPreset }) =>
+    applyItemPreview(role, root, material, materialPreset),
+  getEffectiveMaterial: ({ node, role }) => {
+    const ref = (node as ItemNode).slots?.[role]
+    const parsed = parseMaterialRef(ref)
+    if (!parsed) return null
+    if (parsed.kind === 'library') {
+      return { material: undefined, materialPreset: ref }
+    }
+    const sceneMaterial = useScene.getState().materials[parsed.id as SceneMaterialId]
+    if (!sceneMaterial) return null
+    return { material: sceneMaterial.material, materialPreset: undefined }
+  },
+}
@@ -3,9 +3,11 @@
 import {
  type AnimationEffect,
  type AnyNodeId,
+  deriveSlotId,
  getScaledDimensions,
  type Interactive,
  type ItemNode,
+  isSlotMaterialName,
  type LightEffect,
  useInteractive,
  useLiveNodeOverrides,
@@ -22,6 +24,7 @@ import {
  NodeRenderer,
  type RenderShading,
  resolveCdnUrl,
+  resolveMaterialRef,
  useItemLightPool,
  useNodeEvents,
  useViewer,
@@ -30,7 +33,7 @@ import { useAnimations } from '@react-three/drei'
 import { Clone } from '@react-three/drei/core/Clone'
 import { useGLTF } from '@react-three/drei/core/Gltf'
 import { useFrame } from '@react-three/fiber'
-import { Suspense, useEffect, useMemo, useRef } from 'react'
+import { Suspense, useEffect, useLayoutEffect, useMemo, useRef } from 'react'
 import type { AnimationAction, Group, Material, Mesh } from 'three'
 import { MathUtils } from 'three'
 import { positionLocal, smoothstep, time } from 'three/tsl'
@@ -44,16 +47,117 @@ type MutableMaterial = Material & {
  wireframe?: boolean
 }

-const getMaterialForOriginal = (
-  original: Material,
-  shading: RenderShading,
-  textures: boolean,
-  colorPreset: ColorPreset,
-): Material => {
-  if (original.name.toLowerCase() === 'glass') {
-    return glassMaterial
+type CapturedSingleItemMaterialData = {
+  captured: true
+  authoredMaterials: Material
+  slotIds: string | null
+}
+
+type CapturedMultiItemMaterialData = {
+  captured: true
+  authoredMaterials: Material[]
+  slotIds: (string | null)[]
+}
+
+type CapturedItemMaterialData = CapturedSingleItemMaterialData | CapturedMultiItemMaterialData
+
+type ItemMeshUserData = Mesh['userData'] & {
+  pascalItemMaterialCapture?: CapturedItemMaterialData
+  slotId?: string | null | (string | null)[]
+}
+
+type SceneMaterials = ReturnType<typeof useScene.getState>['materials']
+
+const getAuthoredSlotId = (material: Material): string | null =>
+  isSlotMaterialName(material.name) ? deriveSlotId(material.name) : null
+
+const captureItemMeshMaterials = (mesh: Mesh): CapturedItemMaterialData => {
+  const userData = mesh.userData as ItemMeshUserData
+  const captured = userData.pascalItemMaterialCapture
+  if (captured?.captured) {
+    userData.slotId = captured.slotIds
+    return captured
  }
+
+  if (Array.isArray(mesh.material)) {
+    const authoredMaterials = mesh.material.slice()
+    const slotIds = authoredMaterials.map(getAuthoredSlotId)
+    const next: CapturedItemMaterialData = {
+      captured: true,
+      authoredMaterials,
+      slotIds,
+    }
+    userData.pascalItemMaterialCapture = next
+    userData.slotId = slotIds
+    return next
+  }
+
+  const slotId = getAuthoredSlotId(mesh.material)
+  const next: CapturedItemMaterialData = {
+    captured: true,
+    authoredMaterials: mesh.material,
+    slotIds: slotId,
+  }
+  userData.pascalItemMaterialCapture = next
+  userData.slotId = slotId
+  return next
+}
+
+const hasCapturedSlot = (captured: CapturedItemMaterialData): boolean =>
+  Array.isArray(captured.slotIds)
+    ? captured.slotIds.some((slotId) => slotId != null)
+    : captured.slotIds != null
+
+const isCapturedMaterialArray = (
+  captured: CapturedItemMaterialData,
+): captured is CapturedMultiItemMaterialData => Array.isArray(captured.authoredMaterials)
+
+const isGlassMaterial = (material: Material): boolean =>
+  material === glassMaterial || material.name.toLowerCase() === 'glass'
+
+const clampGeometryGroups = (mesh: Mesh, matCount: number): void => {
+  if (mesh.geometry.groups.length === 0) return
+
+  const needsClamp = mesh.geometry.groups.some(
+    (group) => group.materialIndex !== undefined && group.materialIndex >= matCount,
+  )
+  if (!needsClamp) return
+
+  mesh.geometry = mesh.geometry.clone()
+  for (const group of mesh.geometry.groups) {
+    if (group.materialIndex !== undefined && group.materialIndex >= matCount) {
+      group.materialIndex = 0
+    }
+  }
+}
+
+const resolveItemMaterial = (
+  authoredMaterial: Material,
+  slotId: string | null,
+  {
+    colorPreset,
+    isAuthored,
+    nodeSlots,
+    sceneMaterials,
+    shading,
+    textures,
+  }: {
+    colorPreset: ColorPreset
+    isAuthored: boolean
+    nodeSlots: ItemNode['slots']
+    sceneMaterials: SceneMaterials
+    shading: RenderShading
+    textures: boolean
+  },
+): Material => {
  if (!textures) return createSurfaceRoleMaterial('furnishing', colorPreset)
+  if (authoredMaterial.name.toLowerCase() === 'glass') return glassMaterial
+  if (slotId != null) {
+    const override = resolveMaterialRef(nodeSlots?.[slotId], sceneMaterials, shading)
+    if (override) return override
+    return authoredMaterial
+  }
+  if (isAuthored) return authoredMaterial
  return baseMaterial(shading)
 }

@@ -182,6 +286,7 @@ const ModelRenderer = ({ node }: { node: ItemNode }) => {
  const shading = useViewer((s) => s.shading)
  const textures = useViewer((s) => s.textures)
  const colorPreset = useViewer((s) => s.colorPreset)
+  const sceneMaterials = useScene((s) => s.materials)
  // Freeze the interactive definition at mount — asset schemas don't change at runtime
  const interactiveRef = useRef(node.asset.interactive)

@@ -203,44 +308,59 @@ const ModelRenderer = ({ node }: { node: ItemNode }) => {
    return () => useInteractive.getState().removeItem(node.id)
  }, [node.id])

-  useMemo(() => {
-    scene.traverse((child) => {
-      if ((child as Mesh).isMesh) {
-        const mesh = child as Mesh
-        if (mesh.name === 'cutout') {
-          child.visible = false
-          return
-        }
+  useLayoutEffect(() => {
+    const root = ref.current
+    if (!root) return

-        let hasGlass = false
+    const meshEntries: { mesh: Mesh; captured: CapturedItemMaterialData }[] = []
+    let isAuthored = false

-        // Handle both single material and material array cases
-        if (Array.isArray(mesh.material)) {
-          mesh.material = mesh.material.map((mat) =>
-            getMaterialForOriginal(mat, shading, textures, colorPreset),
-          )
-          hasGlass = mesh.material.some((mat) => mat.name === 'glass')
+    root.traverse((child) => {
+      if (!(child as Mesh).isMesh) return

-          // Fix geometry groups that reference materialIndex beyond the material
-          // array length — this causes three-mesh-bvh to crash with
-          // "Cannot read properties of undefined (reading 'side')"
-          const matCount = mesh.material.length
-          if (mesh.geometry.groups.length > 0) {
-            for (const group of mesh.geometry.groups) {
-              if (group.materialIndex !== undefined && group.materialIndex >= matCount) {
-                group.materialIndex = 0
-              }
-            }
-          }
-        } else {
-          mesh.material = getMaterialForOriginal(mesh.material, shading, textures, colorPreset)
-          hasGlass = mesh.material.name === 'glass'
-        }
-        mesh.castShadow = !hasGlass
-        mesh.receiveShadow = !hasGlass
+      const mesh = child as Mesh
+      if (mesh.name === 'cutout') {
+        child.visible = false
      }
+
+      const captured = captureItemMeshMaterials(mesh)
+      if (hasCapturedSlot(captured)) isAuthored = true
+      if (mesh.name !== 'cutout') meshEntries.push({ mesh, captured })
    })
-  }, [scene, shading, textures, colorPreset])
+
+    const materialOptions = {
+      colorPreset,
+      isAuthored,
+      nodeSlots: node.slots,
+      sceneMaterials,
+      shading,
+      textures,
+    }
+
+    for (const { mesh, captured } of meshEntries) {
+      let hasGlass = false
+
+      if (isCapturedMaterialArray(captured)) {
+        const nextMaterials = captured.authoredMaterials.map((authoredMaterial, index) =>
+          resolveItemMaterial(authoredMaterial, captured.slotIds[index] ?? null, materialOptions),
+        )
+        mesh.material = nextMaterials
+        hasGlass = nextMaterials.some(isGlassMaterial)
+        clampGeometryGroups(mesh, nextMaterials.length)
+      } else {
+        const nextMaterial = resolveItemMaterial(
+          captured.authoredMaterials,
+          captured.slotIds,
+          materialOptions,
+        )
+        mesh.material = nextMaterial
+        hasGlass = isGlassMaterial(nextMaterial)
+      }
+
+      mesh.castShadow = !hasGlass
+      mesh.receiveShadow = !hasGlass
+    }
+  }, [ref, scene, shading, textures, colorPreset, node.slots, sceneMaterials])

  const interactive = interactiveRef.current
  const animEffect =
@@ -68,6 +68,7 @@ export {
  MONO_PALETTE,
  PRESET_PALETTES,
  type RenderShading,
+  resolveMaterialRef,
  resolveSurfaceColor,
  WHITE_PALETTE,
 } from './lib/materials'
@@ -4,7 +4,10 @@ import {
  type MaterialPresetPayload,
  type MaterialProperties,
  type MaterialSchema,
+  parseMaterialRef,
  resolveMaterial,
+  type SceneMaterial,
+  type SceneMaterialId,
  type SurfaceRole,
 } from '@pascal-app/core'
 import * as THREE from 'three'
@@ -486,6 +489,24 @@ export function createMaterial(
  return threeMaterial
 }

+/**
+ * Resolve a MaterialRef ('library:<id>' | 'scene:<id>') to a three.js material.
+ * Returns null for an unknown / dangling ref so callers fall back to the
+ * slot's default (authored material, then themed default). Never throws.
+ */
+export function resolveMaterialRef(
+  ref: string | undefined,
+  sceneMaterials: Record<SceneMaterialId, SceneMaterial> | undefined,
+  shading: RenderShading = 'rendered',
+): THREE.Material | null {
+  const parsed = parseMaterialRef(ref)
+  if (!parsed) return null
+  if (parsed.kind === 'library') return createMaterialFromPresetRef(ref, shading)
+  const sceneMaterial = sceneMaterials?.[parsed.id as SceneMaterialId]
+  if (!sceneMaterial) return null
+  return createMaterial(sceneMaterial.material, shading)
+}
+
 export function createDefaultMaterial(
  color = '#ffffff',
  roughness = 0.9,