@pascal-app/editor 1.0.3 → 1.0.5

package/src/lib/scene-clipboard.ts

@@ -1,31 +1,58 @@
 import {
   AnyNode,
   type AnyNodeId,
+  collectionIdsOf,
   generateId,
   generateSceneMaterialId,
+  getArtifactStore,
+  isDerivedNode,
+  isStoreyContent,
   type LevelNode,
   nodeRegistry,
+  type ParsedBuildJson,
   remapMeasurementReferences,
+  runAsSingleSceneHistoryStep,
   SceneMaterial,
   type SceneMaterialId,
   type StairNode,
+  scriptedSize,
+  seatRoofs,
+  storeyOf,
   useScene,
 } from '@pascal-app/core'
+import { clampDoorToWall, clampWindowToWall } from '@pascal-app/core/building'
 import { useViewer } from '@pascal-app/viewer'
+import { referencedSceneMaterialIds, remapSceneMaterialRefs } from './scene-material-refs'
 
 type ClipboardPayload = {
   copiedAt: number
   materials: SceneMaterial[]
   nodes: AnyNode[]
+  /** The project copied from, where the scripted nodes' artifacts live. */
+  projectId: string | null
   rootIds: AnyNodeId[]
 }
 
 export type PasteResult = {
   createdMaterialIds: SceneMaterialId[]
   pastedIds: AnyNodeId[]
+  /** Scripted nodes left out (with what they host): their artifacts could not come from the project they were copied from. */
+  refusedIds: AnyNodeId[]
+  /** Why they were left out, when any were. */
+  refusal: PasteRefusal | null
   skippedIds: AnyNodeId[]
 }
 
+/**
+ * `no-access`: the source project cannot be read any more (removed from it,
+ * deleted, made private, another account). `no-copies`: its geometry is
+ * readable but this script version cannot be copied. `failed`: the copy itself failed.
+ */
+export type PasteRefusal = 'no-access' | 'no-copies' | 'failed'
+
+type Refused = { ids: ReadonlySet<AnyNodeId>; reason: PasteRefusal | null }
+const NONE_REFUSED: Refused = { ids: new Set(), reason: null }
+
 const SYSTEM_CLIPBOARD_KIND = 'pascal.scene-nodes'
 const SYSTEM_CLIPBOARD_VERSION = 1
 
@@ -84,7 +111,7 @@ function collectSubtreeIds(
 ) {
   if (ids.has(rootId)) return
   const node = nodes[rootId]
-  if (!node) return
+  if (!node || isDerivedNode(node)) return
   ids.add(rootId)
 
   if ('children' in node && Array.isArray(node.children)) {
@@ -129,6 +156,7 @@ function isClipboardRoot(
 }
 
 function isCopyableRootType(node: AnyNode) {
+  if (isDerivedNode(node)) return false
   if (COPYABLE_ROOT_TYPES.has(node.type)) return true
   const definition = nodeRegistry.get(node.type)
   return !!definition && definition.capabilities?.duplicable !== false
@@ -195,10 +223,7 @@ function remapNodeReferences(
   rootIds: Set<AnyNodeId>,
   nodes: Record<AnyNodeId, AnyNode>,
 ) {
-  const clone = remapSceneMaterialReferences(
-    JSON.parse(JSON.stringify(node)),
-    materialIdMap,
-  ) as AnyNode
+  const clone = remapSceneMaterialRefs(JSON.parse(JSON.stringify(node)) as AnyNode, materialIdMap)
   ;(clone as Record<string, unknown>).id = idMap.get(oldId)
 
   if (rootIds.has(oldId)) {
@@ -217,6 +242,11 @@ function remapNodeReferences(
     clone.parentId = idMap.get(clone.parentId as AnyNodeId) ?? clone.parentId
   }
 
+  if (clone.type === 'zone' && node.parentId !== clone.parentId && clone.floor?.footprint) {
+    const { footprint: _footprint, ...floor } = clone.floor
+    clone.floor = floor
+  }
+
   if ('children' in clone && Array.isArray(clone.children)) {
     ;(clone as Record<string, unknown>).children = (clone.children as AnyNodeId[])
       .map((childId) => idMap.get(childId))
@@ -232,6 +262,13 @@ function remapNodeReferences(
     }
   }
 
+  // A corner window pasted with its partner joins the partner's copy; pasted alone, it is plain.
+  if (clone.type === 'window' && clone.corner) {
+    const partnerId = idMap.get(clone.corner.partnerId as AnyNodeId)
+    if (partnerId) clone.corner = { ...clone.corner, partnerId }
+    else delete clone.corner
+  }
+
   if (clone.type === 'stair') {
     const nextLevelId = getNextLevelId(targetLevel, nodes)
     ;(clone as StairNode).fromLevelId = targetLevel.id
@@ -253,43 +290,6 @@ function remapNodeReferences(
   return AnyNode.parse(clone)
 }
 
-function remapSceneMaterialReferences(
-  value: unknown,
-  materialIdMap: Map<SceneMaterialId, SceneMaterialId>,
-): unknown {
-  if (typeof value === 'string' && value.startsWith('scene:')) {
-    const oldId = value.slice('scene:'.length) as SceneMaterialId
-    const nextId = materialIdMap.get(oldId)
-    return nextId ? `scene:${nextId}` : value
-  }
-  if (Array.isArray(value)) {
-    return value.map((entry) => remapSceneMaterialReferences(entry, materialIdMap))
-  }
-  if (value && typeof value === 'object') {
-    return Object.fromEntries(
-      Object.entries(value).map(([key, entry]) => [
-        key,
-        remapSceneMaterialReferences(entry, materialIdMap),
-      ]),
-    )
-  }
-  return value
-}
-
-function collectReferencedSceneMaterialIds(value: unknown, ids: Set<SceneMaterialId>) {
-  if (typeof value === 'string' && value.startsWith('scene:')) {
-    ids.add(value.slice('scene:'.length) as SceneMaterialId)
-    return
-  }
-  if (Array.isArray(value)) {
-    for (const entry of value) collectReferencedSceneMaterialIds(entry, ids)
-    return
-  }
-  if (value && typeof value === 'object') {
-    for (const entry of Object.values(value)) collectReferencedSceneMaterialIds(entry, ids)
-  }
-}
-
 function buildClipboardPayload(ids: AnyNodeId[]): ClipboardPayload | null {
   const scene = useScene.getState()
   const selectedIdSet = new Set(ids)
@@ -321,8 +321,7 @@ function buildClipboardPayload(ids: AnyNodeId[]): ClipboardPayload | null {
     .map((id) => scene.nodes[id])
     .filter((node): node is AnyNode => !!node)
     .map((node) => JSON.parse(JSON.stringify(node)) as AnyNode)
-  const materialIds = new Set<SceneMaterialId>()
-  collectReferencedSceneMaterialIds(copiedNodes, materialIds)
+  const materialIds = referencedSceneMaterialIds(copiedNodes)
 
   return {
     copiedAt: Date.now(),
@@ -331,6 +330,7 @@ function buildClipboardPayload(ids: AnyNodeId[]): ClipboardPayload | null {
       .filter((material): material is SceneMaterial => !!material)
       .map((material) => JSON.parse(JSON.stringify(material)) as SceneMaterial),
     nodes: copiedNodes,
+    projectId: useViewer.getState().projectId,
     rootIds,
   }
 }
@@ -363,6 +363,7 @@ function parseClipboardPayload(text: string): ClipboardPayload | null {
       copiedAt?: unknown
       materials?: unknown
       nodes?: unknown
+      projectId?: unknown
       rootIds?: unknown
     }
     if (
@@ -390,6 +391,7 @@ function parseClipboardPayload(text: string): ClipboardPayload | null {
       copiedAt: candidate.copiedAt,
       materials: materials.filter((result) => result.success).map((result) => result.data),
       nodes: parsedNodes,
+      projectId: typeof candidate.projectId === 'string' ? candidate.projectId : null,
       rootIds,
     }
   } catch {
@@ -470,23 +472,154 @@ export function pasteEditorClipboardToLevel(targetLevelId?: AnyNodeId): PasteRes
 export async function pasteSystemEditorClipboardToLevel(
   targetLevelId?: AnyNodeId,
 ): Promise<PasteResult | null> {
-  if (!(await readEditorClipboardFromSystem())) return null
-  return pasteEditorClipboardToLevel(targetLevelId)
+  const projectId = useViewer.getState().projectId
+  const store = getArtifactStore()
+  if (!(await readEditorClipboardFromSystem()) || !clipboardPayload) return null
+  if (projectId !== useViewer.getState().projectId || store !== getArtifactStore()) return null
+  const payload = clipboardPayload
+  const targetLevel = getPasteTargetLevel(targetLevelId)
+  if (!targetLevel) return null
+  const refused =
+    payload.projectId && payload.projectId === projectId
+      ? NONE_REFUSED
+      : await copyArtifactsHere(payload)
+  // Navigation can replace the scene while the server copies its artifacts.
+  if (projectId !== useViewer.getState().projectId || store !== getArtifactStore()) return null
+  return applyClipboardPayloadToLevel(payload, targetLevel.id, refused)
+}
+
+/** The script and GLB a scripted node, a room's floor script or a wall's face scripts reference. */
+function artifactHashes(node: AnyNode): string[] {
+  const sources =
+    node.type === 'zone'
+      ? [node.floor?.script]
+      : node.type === 'wall'
+        ? [node.finishScripts?.a, node.finishScripts?.b]
+        : ['source' in node ? node.source : undefined]
+  return sources.flatMap((source) =>
+    typeof source === 'object' && source?.kind === 'script' ? [source.script, source.artifact] : [],
+  )
+}
+
+/**
+ * A paste from another project first brings the artifacts its scripted nodes
+ * reference into this one. Returns the nodes whose artifacts could not come,
+ * which the paste leaves out with everything they host, and why.
+ */
+async function copyArtifactsHere(
+  payload: Pick<ClipboardPayload, 'nodes' | 'projectId'>,
+): Promise<Refused> {
+  const store = getArtifactStore()
+  const hashes = [...new Set(payload.nodes.flatMap(artifactHashes))]
+  if (hashes.length === 0) return NONE_REFUSED
+
+  let failed = false
+  const missing = new Set(
+    store.copyFrom
+      ? payload.projectId
+        ? await store.copyFrom(payload.projectId, hashes).catch(() => {
+            failed = true
+            return hashes
+          })
+        : hashes
+      : hashes.filter((sha) => !store.url(sha)),
+  )
+  const ids = new Set<AnyNodeId>()
+  let geometryMissing = false
+  for (const node of payload.nodes) {
+    const [script, artifact] = artifactHashes(node)
+    if (!script || !artifact || !(missing.has(script) || missing.has(artifact))) continue
+    ids.add(node.id as AnyNodeId)
+    geometryMissing ||= missing.has(artifact)
+  }
+  if (ids.size === 0) return NONE_REFUSED
+  return { ids, reason: failed ? 'failed' : geometryMissing ? 'no-access' : 'no-copies' }
+}
+
+/**
+ * A build file loaded into another project first brings the artifacts its
+ * scripted nodes reference from the project it was saved in, as a paste does.
+ * Answers the build without the nodes whose artifacts could not come, nor
+ * anything they host.
+ */
+export async function bringBuildArtifacts(build: ParsedBuildJson): Promise<{
+  build: ParsedBuildJson
+  refusedIds: AnyNodeId[]
+  refusal: PasteRefusal | null
+}> {
+  const nodes = Object.values(build.nodes) as AnyNode[]
+  // A file's origin is untrusted, even when it names this project. Older files can
+  // still use artifacts already registered here, but cannot introduce missing ones.
+  const refused = await copyArtifactsHere({
+    nodes,
+    projectId: build.projectId ?? useViewer.getState().projectId,
+  })
+  if (refused.ids.size === 0) return { build, refusedIds: [], refusal: null }
+
+  const excluded = new Set<string>(refused.ids)
+  for (let grew = true; grew; ) {
+    grew = false
+    for (const node of nodes) {
+      if (node.parentId && excluded.has(node.parentId) && !excluded.has(node.id)) {
+        excluded.add(node.id)
+        grew = true
+      }
+    }
+  }
+  const kept: Record<string, unknown> = {}
+  for (const node of nodes) {
+    if (excluded.has(node.id)) continue
+    const children = (node as { children?: unknown }).children
+    kept[node.id] = Array.isArray(children)
+      ? { ...node, children: children.filter((id) => !excluded.has(id as string)) }
+      : node
+  }
+  const collections =
+    build.collections &&
+    Object.fromEntries(
+      Object.entries(build.collections).map(([id, collection]) => [
+        id,
+        { ...collection, nodeIds: collection.nodeIds.filter((nodeId) => !excluded.has(nodeId)) },
+      ]),
+    )
+  return {
+    build: {
+      ...build,
+      nodes: kept,
+      rootNodeIds: build.rootNodeIds.filter((id) => !excluded.has(id)),
+      ...(collections ? { collections } : {}),
+    },
+    refusedIds: [...refused.ids],
+    refusal: refused.reason,
+  }
 }
 
 function applyClipboardPayloadToLevel(
-  payload: ClipboardPayload,
+  copied: ClipboardPayload,
   targetLevelId?: AnyNodeId,
+  { ids: refused, reason: refusal }: Refused = NONE_REFUSED,
 ): PasteResult | null {
-  const targetLevel = getPasteTargetLevel(targetLevelId)
-  if (!targetLevel) return null
+  const aimedLevel = getPasteTargetLevel(targetLevelId)
+  if (!aimedLevel) return null
+  const payload = refused.size > 0 ? withoutRefusedSubtrees(copied, refused) : copied
 
   const scene = useScene.getState()
+  // A paste lands on one level. On a roof level, one carrying anything a storey holds (walls,
+  // rooms, items, cabinets, …) goes to the storey it covers, whole: the row in view was the roof's,
+  // the plan is the storey's, and a roof in it that bears there is seated back up.
+  const rootIdSet = new Set(payload.rootIds)
+  const targetLevel = payload.nodes.some(
+    (node) => rootIdSet.has(node.id as AnyNodeId) && isStoreyContent(node.type, node.metadata),
+  )
+    ? ((scene.nodes[storeyOf(scene.nodes, aimedLevel.id) as AnyNodeId] as LevelNode | undefined) ??
+      aimedLevel)
+    : aimedLevel
   const idMap = new Map<AnyNodeId, AnyNodeId>()
   const materialIdMap = new Map<SceneMaterialId, SceneMaterialId>()
   const materialsToCreate: SceneMaterial[] = []
 
   for (const node of payload.nodes) {
+    if (isDerivedNode(node)) continue
     idMap.set(node.id as AnyNodeId, generateId(extractIdPrefix(node.id)) as AnyNodeId)
   }
   for (const material of payload.materials) {
@@ -501,11 +634,14 @@ function applyClipboardPayloadToLevel(
     materialsToCreate.push({ ...material, id: nextId })
   }
 
-  const rootIdSet = new Set(payload.rootIds)
   const pastedNodes: AnyNode[] = []
   const skippedIds: AnyNodeId[] = []
 
   for (const node of payload.nodes) {
+    if (isDerivedNode(node)) {
+      skippedIds.push(node.id as AnyNodeId)
+      continue
+    }
     try {
       pastedNodes.push(
         remapNodeReferences(
@@ -524,33 +660,108 @@ function applyClipboardPayloadToLevel(
     }
   }
 
+  fitOpeningsToPastedWalls(pastedNodes, scene.nodes)
+
   if (pastedNodes.length === 0) {
-    return { createdMaterialIds: [], pastedIds: [], skippedIds }
+    return {
+      createdMaterialIds: [],
+      pastedIds: [],
+      refusedIds: [...refused],
+      refusal,
+      skippedIds,
+    }
   }
 
-  for (const material of materialsToCreate) {
-    scene.addSceneMaterial(material)
-  }
-  scene.createNodes(
-    pastedNodes.map((node) => ({
+  const sourceIds = new Map([...idMap].map(([source, copy]) => [copy, source]))
+  // A roof pasted onto the walls that carry it goes to the level above them, in the paste itself.
+  const { changes } = seatRoofs(scene.nodes, {
+    create: pastedNodes.map((node) => ({
       node,
       parentId: (node.parentId as AnyNodeId | null) ?? undefined,
+      // A copy is in its source's collections; an item brings them in its own `collectionIds`.
+      ...(node.type !== 'item' && {
+        collectionIds: collectionIdsOf(scene.collections, sourceIds.get(node.id as AnyNodeId)!),
+      }),
     })),
-  )
+  })
+  runAsSingleSceneHistoryStep(useScene, () => {
+    for (const material of materialsToCreate) scene.addSceneMaterial(material)
+    scene.applyNodeChanges(changes)
+  })
 
+  const nodes = useScene.getState().nodes
   const pastedNodeIds = new Set(pastedNodes.map((node) => node.id as AnyNodeId))
   const pastedRootIds = payload.rootIds
     .map((rootId) => idMap.get(rootId))
     .filter((id): id is AnyNodeId => !!id && pastedNodeIds.has(id))
+  const rootLevel = nodes[(nodes[pastedRootIds[0]!]?.parentId ?? '') as AnyNodeId]
 
   useViewer.getState().setSelection({
-    levelId: targetLevel.id,
+    levelId: rootLevel?.type === 'level' ? rootLevel.id : targetLevel.id,
     selectedIds: pastedRootIds,
   })
 
   return {
     createdMaterialIds: materialsToCreate.map((material) => material.id as SceneMaterialId),
     pastedIds: pastedRootIds,
+    refusedIds: [...refused],
+    refusal,
     skippedIds,
   }
 }
+
+/**
+ * A door or window pasted with its wall is held inside it the way the door and window tools place
+ * one: a wall pasted under a lower storey would otherwise leave a tall window poking above it.
+ */
+function fitOpeningsToPastedWalls(pasted: AnyNode[], sceneNodes: Record<AnyNodeId, AnyNode>) {
+  const byId = Object.fromEntries(pasted.map((node) => [node.id, node])) as Record<
+    AnyNodeId,
+    AnyNode
+  >
+  let nodes: Record<AnyNodeId, AnyNode> | undefined
+  pasted.forEach((node, index) => {
+    if (node.type !== 'door' && node.type !== 'window') return
+    const wall = node.parentId ? byId[node.parentId as AnyNodeId] : undefined
+    if (wall?.type !== 'wall') return
+    // A scripted opening is as tall as what its script built, as the wall cuts it.
+    const [width, height] = node.source
+      ? scriptedSize(node.source.manifest)
+      : [node.width, node.height]
+    nodes ??= { ...sceneNodes, ...byId }
+    const [x, y, z] = node.position
+    const { clampedY } =
+      node.type === 'door'
+        ? clampDoorToWall(wall, x, width, height)
+        : clampWindowToWall(wall, x, y, width, height, nodes)
+    if (clampedY !== y) pasted[index] = { ...node, position: [x, clampedY, z] }
+  })
+}
+
+function withoutRefusedSubtrees(
+  payload: ClipboardPayload,
+  refused: ReadonlySet<AnyNodeId>,
+): ClipboardPayload {
+  const children = new Map<string, AnyNodeId[]>()
+  for (const node of payload.nodes) {
+    if (!node.parentId) continue
+    const siblings = children.get(node.parentId) ?? []
+    siblings.push(node.id as AnyNodeId)
+    children.set(node.parentId, siblings)
+  }
+  const excluded = new Set(refused)
+  for (const id of excluded) {
+    for (const childId of children.get(id) ?? []) excluded.add(childId)
+  }
+  const nodes = payload.nodes.filter((node) => !excluded.has(node.id as AnyNodeId))
+  const kept = new Set(nodes.map((node) => node.id))
+  const materialIds = referencedSceneMaterialIds(nodes)
+  return {
+    ...payload,
+    materials: payload.materials.filter((material) =>
+      materialIds.has(material.id as SceneMaterialId),
+    ),
+    nodes,
+    rootIds: payload.rootIds.filter((id) => kept.has(id)),
+  }
+}

package/src/lib/scene-material-refs.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test'
+import type { AnyNode } from '@pascal-app/core'
+import {
+  referencedSceneMaterialIds,
+  remapSceneMaterialRefs,
+  sceneMaterialUsageCounts,
+} from './scene-material-refs'
+
+const ref = (id: string) => `scene:${id}`
+
+// One node per place a finish can live.
+const nodes = {
+  zone_room: {
+    id: 'zone_room',
+    type: 'zone',
+    floor: {
+      finish: ref('floor'),
+      regions: [{ id: 'r1', polygon: [], finish: ref('rug') }],
+    },
+    wallMaterial: ref('walls'),
+    wallOverrides: [{ wallId: 'wall_1', face: 'a', finish: ref('accent') }],
+    floorStepFinish: ref('step'),
+    floorStepOverrides: [{ key: 'door_1', finish: ref('doorstep') }],
+    floorEdgeFinish: ref('edge'),
+  },
+  wall_1: {
+    id: 'wall_1',
+    type: 'wall',
+    slots: { a: ref('walls') },
+    faceRegions: [{ id: 'w1', face: 'a', finish: ref('wainscot') }],
+  },
+  slab_base: {
+    id: 'slab_base',
+    type: 'slab',
+    plateRole: 'base',
+    slots: { edge: ref('band') },
+    foundation: { type: 'solid', material: ref('foundation') },
+  },
+  item_1: { id: 'item_1', type: 'item', slots: { seat: 'library:oak' } },
+} as unknown as Record<string, AnyNode>
+
+describe('scene material refs', () => {
+  test('counts every finish location, one per use', () => {
+    const counts = sceneMaterialUsageCounts(nodes)
+    expect(Object.fromEntries(counts)).toEqual({
+      floor: 1,
+      rug: 1,
+      walls: 2,
+      accent: 1,
+      step: 1,
+      doorstep: 1,
+      edge: 1,
+      wainscot: 1,
+      band: 1,
+      foundation: 1,
+    })
+  })
+
+  test('collects the materials a set of nodes carries, ignoring library refs', () => {
+    expect(
+      [...referencedSceneMaterialIds([nodes.zone_room, nodes.item_1])].map(String).sort(),
+    ).toEqual(['accent', 'doorstep', 'edge', 'floor', 'rug', 'step', 'walls'])
+  })
+
+  test('remaps refs wherever they are and keeps untouched nodes as they were', () => {
+    const map = new Map([
+      ['floor', 'floor2'],
+      ['foundation', 'stone'],
+      ['doorstep', 'tile'],
+    ])
+    const zone = remapSceneMaterialRefs(nodes.zone_room, map) as Record<string, any>
+    expect(zone.floor.finish).toBe(ref('floor2'))
+    expect(zone.floor.regions).toBe((nodes.zone_room as Record<string, any>).floor.regions)
+    expect(zone.floorStepOverrides).toEqual([{ key: 'door_1', finish: ref('tile') }])
+    const slab = remapSceneMaterialRefs(nodes.slab_base, map) as Record<string, any>
+    expect(slab.foundation).toEqual({ type: 'solid', material: ref('stone') })
+    expect(remapSceneMaterialRefs(nodes.item_1, map)).toBe(nodes.item_1)
+  })
+})

package/src/lib/scene-material-refs.ts

@@ -0,0 +1,79 @@
+import {
+  type AnyNode,
+  getSceneMaterialIdFromRef,
+  type SceneMaterialId,
+  toSceneMaterialRef,
+} from '@pascal-app/core'
+
+// Where a scene material (`scene:<id>`) is used. A node carries refs in more
+// places than its `slots`: a room's floor finish and floor regions, its wall
+// material and per-wall overrides, its floor step finishes (room-wide and per
+// doorway) and edge finish, a wall's face paint regions, a footprint's edge
+// band (`slots.edge`) and foundation.
+// Every string ref anywhere in a node counts, so a new finish location is
+// covered without touching this walker. The usage count, preset/room saving
+// and pasting all walk the same way, so they always agree.
+
+/** Calls `visit` with the material id of every `scene:` ref inside `value`, once per use. */
+export function forEachSceneMaterialRef(value: unknown, visit: (id: SceneMaterialId) => void) {
+  if (typeof value === 'string') {
+    const id = getSceneMaterialIdFromRef(value)
+    if (id) visit(id as SceneMaterialId)
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) forEachSceneMaterialRef(entry, visit)
+    return
+  }
+  if (value && typeof value === 'object')
+    for (const entry of Object.values(value)) forEachSceneMaterialRef(entry, visit)
+}
+
+/** The scene materials `value` references (a node, a list of nodes, …). */
+export function referencedSceneMaterialIds(value: unknown): Set<SceneMaterialId> {
+  const ids = new Set<SceneMaterialId>()
+  forEachSceneMaterialRef(value, (id) => ids.add(id))
+  return ids
+}
+
+/** How many parts use each scene material across `nodes` (one per finish or slot). */
+export function sceneMaterialUsageCounts(
+  nodes: Record<string, AnyNode>,
+): Map<SceneMaterialId, number> {
+  const counts = new Map<SceneMaterialId, number>()
+  for (const node of Object.values(nodes))
+    forEachSceneMaterialRef(node, (id) => counts.set(id, (counts.get(id) ?? 0) + 1))
+  return counts
+}
+
+/**
+ * `value` with every `scene:<old>` ref the map knows rewritten to `scene:<new>`.
+ * Unchanged branches keep their identity, so an untouched node comes back as-is.
+ */
+export function remapSceneMaterialRefs<T>(value: T, idMap: ReadonlyMap<string, string>): T {
+  if (typeof value === 'string') {
+    const id = getSceneMaterialIdFromRef(value)
+    const next = id ? idMap.get(id) : undefined
+    return (next && next !== id ? toSceneMaterialRef(next) : value) as T
+  }
+  if (Array.isArray(value)) {
+    let changed = false
+    const next = value.map((entry) => {
+      const mapped = remapSceneMaterialRefs(entry, idMap)
+      if (mapped !== entry) changed = true
+      return mapped
+    })
+    return (changed ? next : value) as T
+  }
+  if (value && typeof value === 'object') {
+    let changed = false
+    const next: Record<string, unknown> = {}
+    for (const [key, entry] of Object.entries(value)) {
+      const mapped = remapSceneMaterialRefs(entry, idMap)
+      if (mapped !== entry) changed = true
+      next[key] = mapped
+    }
+    return (changed ? next : value) as T
+  }
+  return value
+}