feat(paint-slots): authored item materials + unified slot painting

Phase 1 + paint unification of the paint-slots plan.

- core: scene-material data layer (materials map mirroring collections,
  undo/partialize/setScene full-graph support), SceneMaterial schema,
  scene:/library: MaterialRef helpers + parseMaterialRef, slot id helpers
  (deriveSlotId/slotLabelFromId), slots map on ItemNode, hitObject on
  PaintResolveArgs, optional PaintCapability.commit.
- viewer: resolveMaterialRef (library:/scene: -> three material, null on
  dangling).
- nodes(item): renderer keeps authored GLB materials for slot-authored
  assets and applies per-slot overrides per-instance (never mutates the
  shared cached GLB); textures-off still collapses to furnishing role;
  non-authored items unchanged. Item paint capability + registration.
- editor: item joins the unified (nodeId, slotId) paint dispatch; item
  paint target + slot reset.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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