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

Paint slots: phase 1 + paint unification

packages/core/src/index.ts

@@ -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,

packages/core/src/lib/slots.ts

@@ -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)
+}

packages/core/src/material-library.ts

@@ -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

packages/core/src/registry/types.ts

@@ -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 = {

packages/core/src/schema/index.ts

@@ -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'

packages/core/src/schema/nodes/item.ts

@@ -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)

packages/core/src/schema/scene-material.ts

@@ -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>

packages/core/src/store/use-scene.ts

@@ -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
     },

packages/editor/src/components/editor/selection-manager.tsx

@@ -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,16 +916,23 @@ export const SelectionManager = () => {
           apply:
             compatible && role
               ? () => {
-                  useScene.getState().updateNode(
-                    node.id as AnyNodeId,
-                    paintCap.buildPatch({
+                  const args = {
                     node,
                     role,
                     material: paintSpec.material,
                     materialPreset: paintSpec.materialPreset,
-                    }) as Partial<AnyNode>,
+                  }
+                  if (paintCap.commit) {
+                    paintCap.commit(args)
+                  } else {
+                    useScene
+                      .getState()
+                      .updateNode(
+                        node.id as AnyNodeId,
+                        paintCap.buildPatch(args) as Partial<AnyNode>,
                       )
                   }
+                }
               : null,
           preview:
             compatible && role
@@ -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' &&

packages/editor/src/components/ui/controls/material-paint-panel.tsx

@@ -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>
   )
 }

packages/editor/src/components/ui/controls/material-picker.tsx

@@ -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}
@@ -168,7 +220,10 @@ export function MaterialPicker({
                     src={item.previewThumbnailUrl}
                   />
                 ) : item.previewColor ? (
-                    <div className="h-full w-full" style={{ backgroundColor: item.previewColor }} />
+                  <div
+                    className="h-full w-full"
+                    style={{ backgroundColor: item.previewColor }}
+                  />
                 ) : (
                   <div className="h-full w-full bg-gray-100" />
                 )}

packages/editor/src/components/ui/controls/material-properties-editor.tsx

@@ -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>
+  )
+}

packages/editor/src/components/ui/controls/scene-material-list.tsx

@@ -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>
+  )
+}

packages/editor/src/components/ui/panels/paint-panel.tsx

@@ -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,
-  ) => {
+  return (
+    <PanelWrapper onClose={() => setPaintPanelOpen(false)} title="Material" width={320}>
+      <PanelSection title="Custom material">
+        <MaterialPropertiesEditor
+          onChange={(material) =>
             setActivePaintMaterial({
-      material: {
-        preset: 'custom',
-        properties: {
-          ...currentProps,
-          ...updates,
-          transparent: nextTransparent,
-        },
-      },
+              material,
               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}
+          value={customMaterial}
         />
-              <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>
     </PanelWrapper>
   )

packages/editor/src/hooks/use-auto-save.ts

@@ -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 {

packages/editor/src/lib/colors.ts

@@ -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

packages/editor/src/lib/material-paint.ts

@@ -30,7 +30,8 @@ import {
   type WallSurfaceSide,
 } from '@pascal-app/core'
 
-export type PaintableMaterialTarget = Extract<
+export type PaintableMaterialTarget =
+  | Extract<
       MaterialTarget,
       | 'wall'
       | 'roof'
@@ -47,7 +48,8 @@ export type PaintableMaterialTarget = Extract<
       | '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'
   }

packages/editor/src/lib/scene.ts

@@ -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()
   }

packages/editor/src/store/use-editor.tsx

@@ -168,6 +168,7 @@ export type MaterialTargetRole =
   | ChimneyMaterialRole
   | DormerSurfaceMaterialRole
   | SingleSurfaceMaterialRole
+  | string
 
 export type SelectedMaterialTarget = {
   nodeId: AnyNodeId

packages/nodes/src/item/definition.ts

@@ -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

packages/nodes/src/item/paint.ts

@@ -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 }
+  },
+}

packages/nodes/src/item/renderer.tsx

@@ -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) {
+  useLayoutEffect(() => {
+    const root = ref.current
+    if (!root) return
+
+    const meshEntries: { mesh: Mesh; captured: CapturedItemMaterialData }[] = []
+    let isAuthored = false
+
+    root.traverse((child) => {
+      if (!(child as Mesh).isMesh) return
+
       const mesh = child as Mesh
       if (mesh.name === 'cutout') {
         child.visible = false
-          return
       }
 
+      const captured = captureItemMeshMaterials(mesh)
+      if (hasCapturedSlot(captured)) isAuthored = true
+      if (mesh.name !== 'cutout') meshEntries.push({ mesh, captured })
+    })
+
+    const materialOptions = {
+      colorPreset,
+      isAuthored,
+      nodeSlots: node.slots,
+      sceneMaterials,
+      shading,
+      textures,
+    }
+
+    for (const { mesh, captured } of meshEntries) {
       let hasGlass = 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),
+      if (isCapturedMaterialArray(captured)) {
+        const nextMaterials = captured.authoredMaterials.map((authoredMaterial, index) =>
+          resolveItemMaterial(authoredMaterial, captured.slotIds[index] ?? null, materialOptions),
         )
-          hasGlass = mesh.material.some((mat) => mat.name === 'glass')
-
-          // 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
-              }
-            }
-          }
+        mesh.material = nextMaterials
+        hasGlass = nextMaterials.some(isGlassMaterial)
+        clampGeometryGroups(mesh, nextMaterials.length)
       } else {
-          mesh.material = getMaterialForOriginal(mesh.material, shading, textures, colorPreset)
-          hasGlass = mesh.material.name === 'glass'
+        const nextMaterial = resolveItemMaterial(
+          captured.authoredMaterials,
+          captured.slotIds,
+          materialOptions,
+        )
+        mesh.material = nextMaterial
+        hasGlass = isGlassMaterial(nextMaterial)
       }
+
       mesh.castShadow = !hasGlass
       mesh.receiveShadow = !hasGlass
     }
-    })
-  }, [scene, shading, textures, colorPreset])
+  }, [ref, scene, shading, textures, colorPreset, node.slots, sceneMaterials])
 
   const interactive = interactiveRef.current
   const animEffect =

packages/viewer/src/index.ts

@@ -68,6 +68,7 @@ export {
   MONO_PALETTE,
   PRESET_PALETTES,
   type RenderShading,
+  resolveMaterialRef,
   resolveSurfaceColor,
   WHITE_PALETTE,
 } from './lib/materials'

packages/viewer/src/lib/materials.ts

@@ -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,