fix: preserve scene material document state

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Fixes
+
+- Preserve custom scene materials, collections, and installed plugins across save, clone, import, and export.
+
 ## 0.6.0 (2026-04-21)
 
 ### Features

apps/editor/components/scene-loader.tsx

@@ -14,6 +14,11 @@ import Image from 'next/image'
 import Link from 'next/link'
 import { useRouter } from 'next/navigation'
 import { useCallback, useEffect, useRef, useState } from 'react'
+import {
+  isRemoteSceneEcho,
+  sceneGraphSignature,
+  type PersistedSceneGraph,
+} from '../lib/scene-sync'
 import { BuildTab } from './build-tab'
 import { CommunityViewerToolbarLeft, CommunityViewerToolbarRight } from './viewer-toolbar'
 
@@ -70,33 +75,19 @@ interface SceneLoaderProps {
   meta: SceneMeta
 }
 
-type SceneGraphWithCollections = SceneGraph & {
-  collections?: Record<string, unknown>
-}
-
 interface LiveSceneEvent {
   eventId: number
   sceneId: string
   version: number
   kind: string
   createdAt: string
-  graph: SceneGraphWithCollections
-}
-
-function sceneGraphSignature(graph: SceneGraphWithCollections): string {
-  return JSON.stringify({
-    nodes: graph.nodes,
-    rootNodeIds: graph.rootNodeIds,
-    collections: graph.collections,
-    installedPlugins: graph.installedPlugins,
-  })
+  graph: PersistedSceneGraph
 }
 
 export function SceneLoader({ initialScene, meta }: SceneLoaderProps) {
   const router = useRouter()
   const versionRef = useRef(meta.version)
   const lastRemoteGraphJsonRef = useRef<string | null>(null)
-  const suppressRemoteSaveUntilRef = useRef(0)
   const [conflict, setConflict] = useState(false)
   const [saveError, setSaveError] = useState<string | null>(null)
 
@@ -105,13 +96,10 @@ export function SceneLoader({ initialScene, meta }: SceneLoaderProps) {
   const handleSave = useCallback(
     async (graph: SceneGraph, options?: { keepalive?: boolean }) => {
       const graphJson = sceneGraphSignature(graph)
-      const isRecentRemoteApply = Date.now() < suppressRemoteSaveUntilRef.current
-      if (lastRemoteGraphJsonRef.current === graphJson) {
+      if (isRemoteSceneEcho(lastRemoteGraphJsonRef.current, graphJson)) {
         lastRemoteGraphJsonRef.current = null
-        suppressRemoteSaveUntilRef.current = 0
         return
       }
-      if (isRecentRemoteApply) return
 
       try {
         const response = await fetch(`/api/scenes/${meta.id}`, {
@@ -163,7 +151,6 @@ export function SceneLoader({ initialScene, meta }: SceneLoaderProps) {
 
       versionRef.current = payload.version
       lastRemoteGraphJsonRef.current = sceneGraphSignature(payload.graph)
-      suppressRemoteSaveUntilRef.current = Date.now() + 2500
       applySceneGraphToEditor(payload.graph)
       setConflict(false)
       setSaveError(null)

apps/editor/lib/graph-schema.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test'
+import { apiGraphSchema } from './graph-schema'
+
+const material = {
+  id: 'mat_accent',
+  name: 'Accent',
+  material: {
+    texture: { url: 'https://cdn.example.com/accent.png' },
+  },
+}
+
+describe('apiGraphSchema', () => {
+  test('preserves validated scene materials', () => {
+    const graph = apiGraphSchema.parse({
+      nodes: {},
+      rootNodeIds: [],
+      materials: { mat_accent: material },
+    })
+
+    expect(graph.materials?.mat_accent).toMatchObject(material)
+  })
+
+  for (const url of ['file:///private/key', 'javascript:alert(1)']) {
+    test(`rejects unsafe material texture URL: ${url}`, () => {
+      const result = apiGraphSchema.safeParse({
+        nodes: {},
+        rootNodeIds: [],
+        materials: {
+          mat_accent: {
+            ...material,
+            material: { texture: { url } },
+          },
+        },
+      })
+
+      expect(result.success).toBe(false)
+    })
+  }
+})

apps/editor/lib/graph-schema.ts

@@ -1,4 +1,4 @@
-import { AnyNode } from '@pascal-app/core/schema'
+import { AnyNode, SceneMaterial } from '@pascal-app/core/schema'
 import { z } from 'zod'
 
 /**
@@ -17,6 +17,7 @@ export const apiGraphSchema = z
     nodes: z.record(z.string(), z.unknown()),
     rootNodeIds: z.array(z.string()),
     collections: z.unknown().optional(),
+    materials: z.record(z.string(), SceneMaterial).optional(),
     installedPlugins: z.array(z.string().min(1)).optional(),
   })
   .superRefine((value, ctx) => {

apps/editor/lib/scene-sync.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  isRemoteSceneEcho,
+  sceneGraphSignature,
+  type PersistedSceneGraph,
+} from './scene-sync'
+
+function makeGraph(materialName = 'Accent'): PersistedSceneGraph {
+  return {
+    nodes: {},
+    rootNodeIds: [],
+    materials: {
+      mat_accent: {
+        id: 'mat_accent',
+        name: materialName,
+        material: { preset: 'custom', properties: { color: '#123456' } },
+      },
+    },
+  }
+}
+
+describe('isRemoteSceneEcho', () => {
+  test('recognizes only the exact remote graph', () => {
+    const remote = makeGraph()
+
+    expect(isRemoteSceneEcho(sceneGraphSignature(remote), sceneGraphSignature(remote))).toBe(true)
+  })
+
+  test('does not suppress a local material change', () => {
+    const remote = makeGraph()
+    const local = makeGraph('Updated accent')
+
+    expect(isRemoteSceneEcho(sceneGraphSignature(remote), sceneGraphSignature(local))).toBe(false)
+  })
+})

apps/editor/lib/scene-sync.ts

@@ -0,0 +1,22 @@
+import type { SceneGraph } from '@pascal-app/editor'
+
+export type PersistedSceneGraph = SceneGraph & {
+  collections?: Record<string, unknown>
+}
+
+export function sceneGraphSignature(graph: PersistedSceneGraph): string {
+  return JSON.stringify({
+    nodes: graph.nodes,
+    rootNodeIds: graph.rootNodeIds,
+    collections: graph.collections,
+    materials: graph.materials,
+    installedPlugins: graph.installedPlugins,
+  })
+}
+
+export function isRemoteSceneEcho(
+  lastRemoteGraphJson: string | null,
+  graphJson: string,
+): boolean {
+  return lastRemoteGraphJson === graphJson
+}

packages/core/src/utils/clone-scene-graph.test.ts

@@ -46,6 +46,13 @@ function makeSceneGraph(): SceneGraph {
         nodeIds: ['scan_1', 'guide_1'] as AnyNodeId[],
       },
     },
+    materials: {
+      mat_accent: {
+        id: 'mat_accent',
+        name: 'Accent',
+        material: { preset: 'custom', properties: { color: '#123456' } },
+      },
+    },
     installedPlugins: ['pascal:trees'],
   }
 }
@@ -59,6 +66,7 @@ describe('forkSceneGraph', () => {
     expect(nodes.some((node) => node.type === 'guide')).toBe(false)
     expect(nodes.some((node) => node.type === 'wall')).toBe(true)
     expect(forked.collections).toEqual({})
+    expect(forked.materials).toEqual(makeSceneGraph().materials)
     expect(forked.installedPlugins).toEqual(['pascal:trees'])
   })
 
@@ -73,8 +81,18 @@ describe('forkSceneGraph', () => {
     expect(
       Object.values(forked.collections ?? {}).flatMap((collection) => collection.nodeIds),
     ).toHaveLength(2)
+    expect(forked.materials).toEqual(makeSceneGraph().materials)
     expect(forked.installedPlugins).toEqual(['pascal:trees'])
   })
+
+  test('clones materials without sharing the source registry', () => {
+    const source = makeSceneGraph()
+    const cloned = cloneSceneGraph(source)
+
+    expect(cloned.materials).toEqual(source.materials)
+    expect(cloned.materials).not.toBe(source.materials)
+    expect(cloned.materials?.mat_accent).not.toBe(source.materials?.mat_accent)
+  })
 })
 
 describe('construction-dimension clone references', () => {

packages/core/src/utils/clone-scene-graph.ts

@@ -6,11 +6,13 @@ import {
 import type { AnyNode, AnyNodeId } from '../schema'
 import { generateId } from '../schema/base'
 import type { Collection, CollectionId } from '../schema/collections'
+import type { SceneMaterial, SceneMaterialId } from '../schema/scene-material'
 
 export type SceneGraph = {
   nodes: Record<AnyNodeId, AnyNode>
   rootNodeIds: AnyNodeId[]
   collections?: Record<CollectionId, Collection>
+  materials?: Record<SceneMaterialId, SceneMaterial>
   installedPlugins?: string[]
 }
 
@@ -32,7 +34,7 @@ function extractIdPrefix(id: string): string {
  * - Multi-scene in-memory scenarios
  */
 export function cloneSceneGraph(sceneGraph: SceneGraph): SceneGraph {
-  const { nodes, rootNodeIds, collections, installedPlugins } = sceneGraph
+  const { nodes, rootNodeIds, collections, materials, installedPlugins } = sceneGraph
 
   // Build ID mapping: old ID -> new ID
   const idMap = new Map<string, string>()
@@ -164,6 +166,7 @@ export function cloneSceneGraph(sceneGraph: SceneGraph): SceneGraph {
     nodes: clonedNodes,
     rootNodeIds: clonedRootNodeIds,
     ...(clonedCollections && { collections: clonedCollections }),
+    ...(materials && { materials: structuredClone(materials) }),
     ...(installedPlugins && { installedPlugins: [...installedPlugins] }),
   }
 }
@@ -304,7 +307,7 @@ export function forkSceneGraph(
     return cloneSceneGraph(sceneGraph)
   }
 
-  const { nodes, rootNodeIds, collections, installedPlugins } = sceneGraph
+  const { nodes, rootNodeIds, collections, materials, installedPlugins } = sceneGraph
 
   // First, identify scan and guide node IDs to exclude (user-uploaded imagery)
   const excludedNodeIds = new Set<string>()
@@ -366,6 +369,7 @@ export function forkSceneGraph(
     nodes: filteredNodes,
     rootNodeIds: filteredRootNodeIds,
     ...(filteredCollections && { collections: filteredCollections }),
+    ...(materials && { materials }),
     ...(installedPlugins && { installedPlugins }),
   })
 }

packages/mcp/src/bridge/scene-bridge.test.ts

@@ -432,6 +432,36 @@ describe('SceneBridge', () => {
       expect(Object.keys(bridge.getNodes()).length).toBe(Object.keys(snap.nodes).length)
     })
 
+    test('round-trips document state', () => {
+      const snapshot = {
+        ...bridge.exportJSON(),
+        collections: {
+          collection_kitchen: {
+            id: 'collection_kitchen',
+            name: 'Kitchen',
+            nodeIds: [],
+          },
+        },
+        materials: {
+          mat_accent: {
+            id: 'mat_accent',
+            name: 'Accent',
+            material: { preset: 'custom', properties: { color: '#123456' } },
+          },
+        },
+        installedPlugins: ['pascal:trees'],
+      }
+
+      bridge.setScene({}, [])
+      bridge.loadJSON(snapshot)
+
+      expect(bridge.exportJSON()).toMatchObject({
+        collections: snapshot.collections,
+        materials: snapshot.materials,
+        installedPlugins: snapshot.installedPlugins,
+      })
+    })
+
     test('loadJSON preserves explicit plugin installs', () => {
       const snap = bridge.exportJSON()
       bridge.loadJSON({ ...snap, installedPlugins: ['pascal:trees'] })

packages/mcp/src/bridge/scene-bridge.ts

@@ -20,6 +20,8 @@ export type ActiveSceneMeta = Pick<
   'id' | 'name' | 'projectId' | 'ownerId' | 'thumbnailUrl' | 'version'
 >
 
+type SetSceneExtra = Parameters<ReturnType<typeof useScene.getState>['setScene']>[2]
+
 /**
  * Headless bridge to the `@pascal-app/core` Zustand store.
  *
@@ -59,8 +61,12 @@ export class SceneBridge {
   }
 
   /** Replace entire scene (undoable via Zundo). */
-  setScene(nodes: Record<AnyNodeId, AnyNode>, rootNodeIds: AnyNodeId[]): void {
-    useScene.getState().setScene(nodes, rootNodeIds)
+  setScene(
+    nodes: Record<AnyNodeId, AnyNode>,
+    rootNodeIds: AnyNodeId[],
+    extra?: SetSceneExtra,
+  ): void {
+    useScene.getState().setScene(nodes, rootNodeIds, extra)
   }
 
   /** Full snapshot for export, including collections. */
@@ -72,6 +78,7 @@ export class SceneBridge {
         nodes: state.nodes,
         rootNodeIds: state.rootNodeIds,
         collections: state.collections ?? {},
+        materials: state.materials,
         ...(state.hasExplicitPluginInstallState || state.installedPlugins.length > 0
           ? { installedPlugins: state.installedPlugins }
           : {}),
@@ -119,13 +126,23 @@ export class SceneBridge {
       }
     }
 
-    this.setScene(nodes as Record<AnyNodeId, AnyNode>, rootNodeIds as AnyNodeId[])
-    if (Array.isArray(obj.installedPlugins)) {
-      useScene.getState().setInstalledPlugins(
-        obj.installedPlugins.filter((id): id is string => typeof id === 'string'),
-        { explicit: true },
-      )
-    }
+    const collections =
+      obj.collections && typeof obj.collections === 'object' && !Array.isArray(obj.collections)
+        ? (obj.collections as NonNullable<SetSceneExtra>['collections'])
+        : undefined
+    const materials =
+      obj.materials && typeof obj.materials === 'object' && !Array.isArray(obj.materials)
+        ? (obj.materials as NonNullable<SetSceneExtra>['materials'])
+        : undefined
+    const installedPlugins = Array.isArray(obj.installedPlugins)
+      ? obj.installedPlugins.filter((id): id is string => typeof id === 'string')
+      : undefined
+
+    this.setScene(nodes as Record<AnyNodeId, AnyNode>, rootNodeIds as AnyNodeId[], {
+      ...(collections && { collections }),
+      ...(materials && { materials }),
+      ...(installedPlugins && { installedPlugins, hasExplicitPluginInstallState: true }),
+    })
   }
 
   /** Read a single node, or `null` if not present. */