@pascal-app/editor 1.0.3 → 1.0.5

package/src/lib/glb-export.test.ts

@@ -2,15 +2,21 @@ import { afterEach, describe, expect, test } from 'bun:test'
 import {
   type AnyNode,
   type AnyNodeDefinition,
+  BaseNode,
   DoorNode,
   type GeometryContext,
+  LevelNode,
   loadPlugin,
+  type NodeDefinition,
   nodeRegistry,
+  nodeType,
+  objectId,
   registerNode,
   SiteNode,
   sceneRegistry,
   useScene,
 } from '@pascal-app/core'
+import { evaluateRecipe, ProceduralItemNode, parseRecipe } from '@pascal-app/core/procedural-items'
 import {
   buildDoorPreviewMesh,
   markViewerPresentationTextureBorrowed,
@@ -19,9 +25,14 @@ import {
 } from '@pascal-app/viewer'
 import * as THREE from 'three'
 import type { GLTFWriter } from 'three/examples/jsm/exporters/GLTFExporter.js'
+import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter.js'
 import { OBJExporter } from 'three/examples/jsm/exporters/OBJExporter.js'
 import { STLExporter } from 'three/examples/jsm/exporters/STLExporter.js'
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
 import { MeshStandardNodeMaterial } from 'three/webgpu'
+import cabinetJson from '../../../core/src/procedural-items/__fixtures__/cabinet_two_doors_drawer.json'
+import ceilingFanJson from '../../../core/src/procedural-items/__fixtures__/ceiling_fan.json'
+import pendantJson from '../../../core/src/procedural-items/__fixtures__/pendant_lamp.json'
 import {
   prepareSceneForExport,
   prepareSceneForExportAsync,
@@ -84,6 +95,249 @@ function sceneWithVisibleAndHiddenBoxes(): {
 }
 
 describe('prepareSceneForExport', () => {
+  test.each([true, false])(
+    'omits registered draft geometry absent from the saved document (onlyVisible=%s)',
+    (onlyVisible) => {
+      const { root, nodes } = sceneWithVisibleAndHiddenBoxes()
+      const draft = sceneRegistry.nodes.get('item_hidden')!
+      draft.name = 'Unplaced preview'
+      nodes.item_hidden!.visible = true
+      delete nodes.item_hidden
+
+      const result = prepareSceneForExport(root, nodes, { onlyVisible })
+      expect(result.scene.getObjectByName('Unplaced preview')).toBeUndefined()
+      expect(result.scene.children).toHaveLength(1)
+      expect(root.getObjectByName('Unplaced preview')).toBe(draft)
+    },
+  )
+
+  test('skips a refused subtree and reports its warning while exporting other objects', () => {
+    const root = new THREE.Group()
+    const refused = new THREE.Group()
+    refused.name = 'Oversized stair'
+    refused.userData.pascalExportRefusal = 'Detailed stair geometry exceeds the computation budget.'
+    refused.add(meshWithNodeMaterial(nodeMaterial()))
+    const accepted = meshWithNodeMaterial(nodeMaterial())
+    accepted.name = 'Retained object'
+    root.add(refused, accepted)
+    const result = prepareSceneForExport(root, {})
+    expect(result.scene.getObjectByName(refused.name)).toBeUndefined()
+    expect(result.scene.getObjectByName(accepted.name)).toBeDefined()
+    expect(
+      result.warnings.some(
+        (warning) => warning.includes(refused.name) && warning.includes('computation budget'),
+      ),
+    ).toBe(true)
+    expect(root.children).toContain(refused)
+    result.dispose()
+  })
+
+  test('exports procedural bulb emission on detached materials regardless of live state', async () => {
+    const definitionModule = '../../../nodes/src/procedural-item/definition'
+    const { proceduralItemDefinition } = await import(definitionModule)
+    registerNode(proceduralItemDefinition as AnyNodeDefinition)
+    const node = ProceduralItemNode.parse({
+      id: 'procedural-item_pendant_export',
+      recipe: parseRecipe(pendantJson),
+    })
+    const root = new THREE.Group()
+    const group = new THREE.Group()
+    const source = new THREE.MeshStandardMaterial({ color: '#3377aa' })
+    source.emissiveIntensity = 0
+    const mesh = new THREE.Mesh(new THREE.BoxGeometry(0.1, 0.1, 0.1), source)
+    mesh.userData.slotId = 'bulb'
+    group.add(mesh)
+    root.add(group)
+    sceneRegistry.nodes.set(node.id, group)
+
+    const result = prepareSceneForExport(root, { [node.id]: node as AnyNode })
+    const bakedMesh = result.scene.getObjectByName(node.id)?.children[0] as THREE.Mesh
+    const material = bakedMesh.material as THREE.MeshStandardMaterial
+    const light = evaluateRecipe(node.recipe).lights[0]!
+    expect(material).not.toBe(source)
+    expect(material.emissive.getHexString()).toBe(new THREE.Color(light.color).getHexString())
+    expect(material.emissiveIntensity).toBe(1)
+    expect(source.emissiveIntensity).toBe(0)
+    expect(result.scene.getObjectByProperty('type', 'PointLight')).toBeUndefined()
+    result.dispose()
+  })
+  test('exports procedural door, drawer, and fan clips from rest-pose motion groups', async () => {
+    const definitionModule = '../../../nodes/src/procedural-item/definition'
+    const { proceduralItemDefinition } = await import(definitionModule)
+    registerNode(proceduralItemDefinition as AnyNodeDefinition)
+    const root = new THREE.Group()
+    const nodes: Record<string, AnyNode> = {}
+    for (const [id, source] of [
+      ['procedural-item_cabinet:odd', cabinetJson],
+      ['procedural-item_fan:odd', ceilingFanJson],
+    ] as const) {
+      const node = ProceduralItemNode.parse({ id, recipe: parseRecipe(source) })
+      nodes[id] = node as AnyNode
+      const evaluation = evaluateRecipe(node.recipe)
+      const object = new THREE.Group()
+      const groups = new Map<string, THREE.Group>()
+      for (const motion of evaluation.motions) {
+        const group = new THREE.Group()
+        group.name = `${id}__motion__${motion.id}`
+        group.position.set(...motion.pivot)
+        group.userData.proceduralMotion = {
+          nodeId: id,
+          partId: motion.partId,
+          groupId: motion.id,
+          kind: motion.kind,
+        }
+        groups.set(motion.id, group)
+        object.add(group)
+      }
+      for (const shape of evaluation.shapes) {
+        const mesh = new THREE.Mesh(
+          new THREE.BoxGeometry(0.02, 0.02, 0.02),
+          new THREE.MeshStandardMaterial(),
+        )
+        mesh.userData.slotId = shape.slot
+        ;(shape.motionGroup ? groups.get(shape.motionGroup)! : object).add(mesh)
+      }
+      for (const group of groups.values()) group.rotation.y = 0.4
+      groups.get('drawer')?.position.set(0, 0, 0.25)
+      root.add(object)
+      sceneRegistry.nodes.set(id, object)
+    }
+
+    const { scene, animations } = prepareSceneForExport(root, nodes, { animations: 'keep' })
+    expect(animations.map((clip) => clip.name).sort()).toEqual([
+      'procedural-item_cabinet:odd:doors: open',
+      'procedural-item_cabinet:odd:drawer: open',
+      'procedural-item_fan:odd:rotor: loop',
+    ])
+    const doors = animations.find((clip) => clip.name.endsWith('doors: open'))!
+    expect(doors.tracks).toHaveLength(2)
+    expect(doors.duration).toBeCloseTo(0.65)
+    expect(doors.userData.loop).toBe(false)
+    const drawer = animations.find((clip) => clip.name.endsWith('drawer: open'))!
+    expect(drawer.tracks[0]).toBeInstanceOf(THREE.VectorKeyframeTrack)
+    for (const clip of [doors, drawer])
+      for (const track of clip.tracks) {
+        expect(track.times.length).toBeGreaterThanOrEqual(33)
+        expect(track.times[0]).toBe(0)
+        expect(track.times.at(-1)).toBeCloseTo(clip.duration)
+        for (let index = 1; index < track.times.length; index++)
+          expect(track.times[index]).toBeGreaterThan(track.times[index - 1]!)
+      }
+    expect(drawer.tracks[0]!.times.some((time) => Math.abs(time - 0.3) < 1e-6)).toBe(true)
+    expect(doors.tracks[0]!.times.some((time) => Math.abs(time - 0.55) < 1e-6)).toBe(true)
+    const drawerTrack = drawer.tracks[0]!
+    expect(Array.from(drawerTrack.values.slice(0, 3))).toEqual(
+      Array.from(drawerTrack.values.slice(3, 6)),
+    )
+    const doorTrack = doors.tracks[0]!
+    const last = doorTrack.values.length
+    expect(Array.from(doorTrack.values.slice(last - 8, last - 4))).toEqual(
+      Array.from(doorTrack.values.slice(last - 4)),
+    )
+    const fan = animations.find((clip) => clip.name.endsWith('rotor: loop'))!
+    expect(fan.tracks[0]!.times).toHaveLength(5)
+    expect(fan.userData.loop).toBe(true)
+    for (const clip of animations)
+      for (const track of clip.tracks) {
+        const target = scene.getObjectByProperty(
+          'uuid',
+          track.name.slice(0, track.name.lastIndexOf('.')),
+        )
+        expect(target).toBeDefined()
+        expect(target!.quaternion.angleTo(new THREE.Quaternion())).toBeCloseTo(0)
+        const marker = target!.userData.proceduralMotion
+        expect(marker.clip).toBe(clip.name)
+        expect(marker.groupId).toBeDefined()
+        if (clip !== fan) expect(marker.activeWindow).toBeDefined()
+        expect(target!.name).toContain('__motion__')
+      }
+    expect(scene.getObjectByName('procedural-item_cabinet:odd')?.userData).toMatchObject({
+      openable: true,
+      clips: [doors.name, drawer.name],
+    })
+    expect(scene.getObjectByName('procedural-item_fan:odd')?.userData).toMatchObject({
+      clips: [fan.name],
+    })
+    expect(scene.getObjectByName('procedural-item_fan:odd')?.userData.openable).toBeUndefined()
+    expect(
+      scene.getObjectByName('procedural-item_cabinet:odd__motion__doors')?.userData.proceduralMotion
+        .activeWindow,
+    ).toEqual([0, 0.63])
+    expect(
+      scene.getObjectByName('procedural-item_cabinet:odd__motion__drawer')?.userData
+        .proceduralMotion.activeWindow[0],
+    ).toBeCloseTo(0.3)
+    const exportedSlots: string[] = []
+    scene.traverse((object) => {
+      if (object.userData.slotId) exportedSlots.push(object.userData.slotId)
+    })
+    expect(exportedSlots).toContain('paint')
+    const originalFileReader = globalThis.FileReader
+    class ExportFileReader {
+      result: ArrayBuffer | null = null
+      onloadend: (() => void) | null = null
+      readAsArrayBuffer(blob: Blob) {
+        void blob.arrayBuffer().then((buffer) => {
+          this.result = buffer
+          this.onloadend?.()
+        })
+      }
+    }
+    globalThis.FileReader = ExportFileReader as unknown as typeof FileReader
+    let binary: ArrayBuffer
+    try {
+      binary = (await new GLTFExporter().parseAsync(scene, {
+        animations,
+        binary: true,
+      })) as ArrayBuffer
+    } finally {
+      globalThis.FileReader = originalFileReader
+    }
+    const loaded = await new GLTFLoader().parseAsync(binary, '')
+    expect(loaded.animations.map((clip) => clip.name).sort()).toEqual(
+      animations.map((clip) => clip.name).sort(),
+    )
+    for (const clip of loaded.animations) {
+      for (const track of clip.tracks) {
+        const target = loaded.scene.getObjectByName(
+          track.name.slice(0, track.name.lastIndexOf('.')),
+        )
+        expect(target?.userData.proceduralMotion.clip).toBe(clip.name)
+        expect(target?.userData.proceduralMotion.groupId).toBeDefined()
+      }
+    }
+    const loadedById = new Map<string, THREE.Object3D>()
+    loaded.scene.traverse((object) => {
+      if (typeof object.userData.pascalId === 'string')
+        loadedById.set(object.userData.pascalId, object)
+    })
+    expect(loadedById.get('procedural-item_cabinet:odd')?.userData).toMatchObject({
+      kind: 'procedural-item',
+      clips: [doors.name, drawer.name],
+    })
+    expect(loadedById.get('procedural-item_fan:odd')?.userData).toMatchObject({
+      kind: 'procedural-item',
+      clips: [fan.name],
+    })
+    const loadedSlots: string[] = []
+    loaded.scene.traverse((object) => {
+      if (object.userData.slotId) loadedSlots.push(object.userData.slotId)
+    })
+    expect(loadedSlots).toContain('paint')
+    expect(
+      scene.getObjectByName('procedural-item_cabinet:odd__motion__drawer')?.position.toArray(),
+    ).toEqual([0, 0, 0])
+
+    const withoutClips = prepareSceneForExport(root, nodes, { animations: 'none' })
+    expect(withoutClips.animations).toEqual([])
+    for (const motion of ['doors', 'doors~1', 'drawer', 'rotor']) {
+      const id = motion === 'rotor' ? 'procedural-item_fan:odd' : 'procedural-item_cabinet:odd'
+      const target = withoutClips.scene.getObjectByName(`${id}__motion__${motion}`)!
+      expect(target.quaternion.angleTo(new THREE.Quaternion())).toBeCloseTo(0)
+      if (motion === 'drawer') expect(target.position.toArray()).toEqual([0, 0, 0])
+      expect(target.userData.proceduralMotion.clip).toBeUndefined()
+    }
+  })
   test('converts NodeMaterials to classic glTF-standard materials', () => {
     const root = new THREE.Group()
     root.name = 'scene-renderer'
@@ -203,134 +457,133 @@ describe('prepareSceneForExport', () => {
     }
   })
 
-  test.each([
-    'sync',
-    'portable-sync',
-    'portable-async',
-  ] as const)('bakes Site bounds and same-kind sibling reservations through %s hooks', async (mode) => {
-    const restoreRegistry = nodeRegistry._snapshot()
-    try {
-      const kind = 'test:site-context-bake'
-      const nodeId = 'site_context_bake'
-      const site = SiteNode.parse({
-        polygon: {
-          type: 'polygon',
-          points: [
-            [0, 0],
-            [12, 0],
-            [12, 8],
-            [0, 8],
-          ],
-        },
-        children: [nodeId, 'declared_sibling', 'linked_sibling', 'other_kind'],
-      })
-      const otherSite = SiteNode.parse({
-        polygon: {
-          type: 'polygon',
-          points: [
-            [0, 0],
-            [30, 0],
-            [30, 4],
-            [0, 4],
-          ],
-        },
-        children: ['other_site_sibling'],
-      })
-      const buildGeometry = (context: GeometryContext) => {
-        const points = (context.parent as SiteNode | null)?.polygon?.points ?? [[0, 0]]
-        const xs = points.map(([x]) => x)
-        const zs = points.map(([, z]) => z)
-        const reservedWidth = context.siblings.reduce(
-          (width, sibling) => width + Number(sibling.metadata?.reservedWidth ?? 0),
-          0,
-        )
-        return new THREE.Mesh(
-          new THREE.BoxGeometry(
-            Math.max(...xs) - Math.min(...xs) - reservedWidth,
-            1,
-            Math.max(...zs) - Math.min(...zs),
-          ),
-          new THREE.MeshStandardMaterial(),
-        )
-      }
-      registerNode({
-        kind,
-        schemaVersion: 1,
-        schema: DoorNode,
-        category: 'furnish',
-        defaults: () => ({}) as never,
-        capabilities: {},
-        bake: 'replace',
-        ...(mode === 'portable-async'
-          ? { bakeGeometryAsync: async (_node, context) => buildGeometry(context) }
-          : { bakeGeometry: (_node, context) => buildGeometry(context) }),
-      } as AnyNodeDefinition)
-      const nodes = {
-        [site.id]: site,
-        [otherSite.id]: otherSite,
-        [nodeId]: {
-          id: nodeId,
-          type: kind,
-          parentId: null,
-          visible: true,
-          metadata: { reservedWidth: 100 },
-        },
-        declared_sibling: {
-          id: 'declared_sibling',
-          type: kind,
-          parentId: null,
-          metadata: { reservedWidth: 2 },
-        },
-        pointer_sibling: {
-          id: 'pointer_sibling',
-          type: kind,
-          parentId: site.id,
-          metadata: { reservedWidth: 3 },
-        },
-        linked_sibling: {
-          id: 'linked_sibling',
-          type: kind,
-          parentId: site.id,
-          metadata: { reservedWidth: 1 },
-        },
-        other_kind: {
-          id: 'other_kind',
-          type: 'test:other-kind',
-          parentId: site.id,
-          metadata: { reservedWidth: 100 },
-        },
-        other_site_sibling: {
-          id: 'other_site_sibling',
-          type: kind,
-          parentId: otherSite.id,
-          metadata: { reservedWidth: 4 },
-        },
-      } as unknown as Record<string, AnyNode>
-      const root = new THREE.Group()
-      const source = new THREE.Group()
-      root.add(source)
-      sceneRegistry.nodes.set(nodeId, source)
-      const prepare = mode === 'sync' ? prepareSceneForExport : prepareSceneForExportAsync
-      const exportedSize = async () => {
-        const prepared = await prepare(root, nodes)
-        try {
-          const exported = prepared.scene.getObjectByName(nodeId)!
-          return new THREE.Box3().setFromObject(exported).getSize(new THREE.Vector3()).toArray()
-        } finally {
-          prepared.dispose()
+  test.each(['sync', 'portable-sync', 'portable-async'] as const)(
+    'bakes Site bounds and same-kind sibling reservations through %s hooks',
+    async (mode) => {
+      const restoreRegistry = nodeRegistry._snapshot()
+      try {
+        const kind = 'test:site-context-bake'
+        const nodeId = 'site_context_bake'
+        const site = SiteNode.parse({
+          polygon: {
+            type: 'polygon',
+            points: [
+              [0, 0],
+              [12, 0],
+              [12, 8],
+              [0, 8],
+            ],
+          },
+          children: [nodeId, 'declared_sibling', 'linked_sibling', 'other_kind'],
+        })
+        const otherSite = SiteNode.parse({
+          polygon: {
+            type: 'polygon',
+            points: [
+              [0, 0],
+              [30, 0],
+              [30, 4],
+              [0, 4],
+            ],
+          },
+          children: ['other_site_sibling'],
+        })
+        const buildGeometry = (context: GeometryContext) => {
+          const points = (context.parent as SiteNode | null)?.polygon?.points ?? [[0, 0]]
+          const xs = points.map(([x]) => x)
+          const zs = points.map(([, z]) => z)
+          const reservedWidth = context.siblings.reduce(
+            (width, sibling) => width + Number(sibling.metadata?.reservedWidth ?? 0),
+            0,
+          )
+          return new THREE.Mesh(
+            new THREE.BoxGeometry(
+              Math.max(...xs) - Math.min(...xs) - reservedWidth,
+              1,
+              Math.max(...zs) - Math.min(...zs),
+            ),
+            new THREE.MeshStandardMaterial(),
+          )
+        }
+        registerNode({
+          kind,
+          schemaVersion: 1,
+          schema: DoorNode,
+          category: 'furnish',
+          defaults: () => ({}) as never,
+          capabilities: {},
+          bake: 'replace',
+          ...(mode === 'portable-async'
+            ? { bakeGeometryAsync: async (_node, context) => buildGeometry(context) }
+            : { bakeGeometry: (_node, context) => buildGeometry(context) }),
+        } as AnyNodeDefinition)
+        const nodes = {
+          [site.id]: site,
+          [otherSite.id]: otherSite,
+          [nodeId]: {
+            id: nodeId,
+            type: kind,
+            parentId: null,
+            visible: true,
+            metadata: { reservedWidth: 100 },
+          },
+          declared_sibling: {
+            id: 'declared_sibling',
+            type: kind,
+            parentId: null,
+            metadata: { reservedWidth: 2 },
+          },
+          pointer_sibling: {
+            id: 'pointer_sibling',
+            type: kind,
+            parentId: site.id,
+            metadata: { reservedWidth: 3 },
+          },
+          linked_sibling: {
+            id: 'linked_sibling',
+            type: kind,
+            parentId: site.id,
+            metadata: { reservedWidth: 1 },
+          },
+          other_kind: {
+            id: 'other_kind',
+            type: 'test:other-kind',
+            parentId: site.id,
+            metadata: { reservedWidth: 100 },
+          },
+          other_site_sibling: {
+            id: 'other_site_sibling',
+            type: kind,
+            parentId: otherSite.id,
+            metadata: { reservedWidth: 4 },
+          },
+        } as unknown as Record<string, AnyNode>
+        const root = new THREE.Group()
+        const source = new THREE.Group()
+        root.add(source)
+        sceneRegistry.nodes.set(nodeId, source)
+        const prepare = mode === 'sync' ? prepareSceneForExport : prepareSceneForExportAsync
+        const exportedSize = async () => {
+          const prepared = await prepare(root, nodes)
+          try {
+            const exported = prepared.scene.getObjectByName(nodeId)!
+            return new THREE.Box3().setFromObject(exported).getSize(new THREE.Vector3()).toArray()
+          } finally {
+            prepared.dispose()
+          }
         }
-      }
 
-      expect(await exportedSize()).toEqual([6, 1, 8])
-      nodes[nodeId]!.parentId = otherSite.id
-      expect(await exportedSize()).toEqual([26, 1, 4])
-      nodes[nodeId]!.parentId = null
-      site.children = site.children.filter((id) => id !== nodeId)
-      expect(await exportedSize()).toEqual([0, 1, 0])
-    } finally {
-      restoreRegistry()
-    }
-  })
+        expect(await exportedSize()).toEqual([6, 1, 8])
+        nodes[nodeId]!.parentId = otherSite.id
+        expect(await exportedSize()).toEqual([26, 1, 4])
+        nodes[nodeId]!.parentId = null
+        site.children = site.children.filter((id) => id !== nodeId)
+        expect(await exportedSize()).toEqual([0, 1, 0])
+      } finally {
+        restoreRegistry()
+      }
+    },
+  )
 
   test('selective exports omit a procedural kind without changing the live scene or later exports', () => {
     const restoreRegistry = nodeRegistry._snapshot()
@@ -998,6 +1251,54 @@ describe('prepareSceneForExport', () => {
     })
   })
 
+  test("lists any kind's registry loop clip in extras.clips, without claiming it opens", () => {
+    // A plugin mechanism (an articulated asset's joints) bakes one looping clip;
+    // the baked viewer can only play clips its identity node lists.
+    const root = new THREE.Group()
+    const nodeGroup = new THREE.Group()
+    const joint = new THREE.Group()
+    joint.add(meshWithNodeMaterial(nodeMaterial()))
+    nodeGroup.add(joint)
+    root.add(nodeGroup)
+
+    const kind = `test:articulated-${crypto.randomUUID()}`
+    const nodeId = 'plugin_articulated'
+    registerNode({
+      kind,
+      schemaVersion: 1,
+      category: 'furnish',
+      defaults: () => ({}),
+      capabilities: {},
+      exportAnimation: ({ node, object }: { node: AnyNode; object: THREE.Object3D }) => {
+        const target = object.children[0]!
+        const clip = new THREE.AnimationClip(`${node.id}: loop`, 2, [
+          new THREE.QuaternionKeyframeTrack(
+            `${target.uuid}.quaternion`,
+            [0, 2],
+            [0, 0, 0, 1, 0, 0, 0, 1],
+          ),
+        ])
+        clip.userData = { loop: true }
+        return clip
+      },
+    } as never)
+    sceneRegistry.nodes.set(nodeId, nodeGroup)
+
+    const { scene, animations } = prepareSceneForExport(root, {
+      [nodeId]: {
+        object: 'node',
+        id: nodeId,
+        type: kind,
+        name: 'Articulated',
+      } as unknown as AnyNode,
+    })
+
+    expect(animations.map((clip) => clip.name)).toEqual(['plugin_articulated: loop'])
+    const exported = scene.getObjectByProperty('name', nodeId)
+    expect(exported?.userData.clips).toEqual(['plugin_articulated: loop'])
+    expect(exported?.userData.openable).toBeUndefined()
+  })
+
   test('bakes a sliding door into a sampled position clip', () => {
     // Operation doors build their moving parts in a named group posed by
     // `poseDoorMovingParts`; the exporter samples it into keyframes. The active
@@ -1951,3 +2252,212 @@ describe('portable clips', () => {
     expect(legacy.animations).toEqual([])
   })
 })
+
+// Plugin API v1: a synthetic installed plugin through the real export path.
+describe('plugin bake policies through export', () => {
+  const pluginId = 'fixture:bake-export'
+  const levelId = 'level_plugin_bake'
+  const overlayId = 'fxoverlay_export'
+  const meadowId = 'fxmeadow_export'
+  const rockId = 'fxrock_export'
+
+  const namedBox = (name: string) =>
+    Object.assign(new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshStandardMaterial()), {
+      name,
+    })
+
+  async function withBakePlugin(
+    installedPlugins: string[],
+    run: (args: {
+      root: THREE.Group
+      live: Record<string, THREE.Group>
+      nodes: Record<string, AnyNode>
+      calls: string[]
+    }) => Promise<void>,
+  ) {
+    const restoreRegistry = nodeRegistry._snapshot()
+    const previousScene = useScene.getState()
+    const calls: string[] = []
+    const Fixture = (prefix: 'fxoverlay' | 'fxmeadow' | 'fxrock') =>
+      BaseNode.extend({ id: objectId(prefix), type: nodeType(`fixture:${prefix.slice(2)}`) })
+    const Overlay = Fixture('fxoverlay')
+    const Meadow = Fixture('fxmeadow')
+    const Rock = Fixture('fxrock')
+    const base = { object: 'node', parentId: null, visible: true, metadata: {} } as const
+    const overlay: NodeDefinition<typeof Overlay> = {
+      kind: 'fixture:overlay',
+      schemaVersion: 1,
+      schema: Overlay,
+      category: 'site',
+      defaults: () => base,
+      capabilities: {},
+      bake: 'strip',
+    }
+    const meadow: NodeDefinition<typeof Meadow> = {
+      kind: 'fixture:meadow',
+      schemaVersion: 1,
+      schema: Meadow,
+      category: 'site',
+      defaults: () => base,
+      capabilities: {},
+      bake: 'replace',
+      bakeGeometry: () => {
+        calls.push('bakeGeometry')
+        return new THREE.Group().add(namedBox('meadow-bake'))
+      },
+      bakeGeometryAsync: async () => {
+        calls.push('bakeGeometryAsync')
+        await Promise.resolve()
+        return new THREE.Group().add(namedBox('meadow-bake-async'))
+      },
+      bakeReplaceRenderer: { module: async () => ({ default: () => null }) },
+    }
+    const rock: NodeDefinition<typeof Rock> = {
+      kind: 'fixture:rock',
+      schemaVersion: 1,
+      schema: Rock,
+      category: 'site',
+      defaults: () => base,
+      capabilities: {},
+    }
+    // API v1 boundary casts: typed definitions do not widen to AnyNodeDefinition
+    // and plugin nodes are outside the AnyNode union.
+    const asPluginNode = <S extends AnyNodeDefinition['schema']>(def: NodeDefinition<S>) =>
+      def as unknown as AnyNodeDefinition
+    const asSceneNode = (node: { id: string; type: string }) => node as unknown as AnyNode
+    try {
+      await loadPlugin({
+        id: pluginId,
+        apiVersion: 1,
+        nodes: [asPluginNode(overlay), asPluginNode(meadow), asPluginNode(rock)],
+      })
+      useScene.setState({ installedPlugins, hasExplicitPluginInstallState: true })
+
+      const root = new THREE.Group()
+      const level = new THREE.Group()
+      root.add(level)
+      sceneRegistry.nodes.set(levelId, level)
+      const live: Record<string, THREE.Group> = {}
+      const pluginNodes = [
+        Overlay.parse({ id: overlayId, parentId: levelId }),
+        Meadow.parse({ id: meadowId, parentId: levelId }),
+        Rock.parse({ id: rockId, parentId: levelId }),
+      ].map(asSceneNode)
+      const nodes: Record<string, AnyNode> = {
+        [levelId]: asSceneNode(
+          LevelNode.parse({ id: levelId, children: pluginNodes.map((node) => node.id) }),
+        ),
+      }
+      for (const node of pluginNodes) {
+        const group = new THREE.Group().add(namedBox(`${node.id}-live`))
+        level.add(group)
+        sceneRegistry.nodes.set(node.id, group)
+        live[node.id] = group
+        nodes[node.id] = node
+      }
+      await run({ root, live, nodes, calls })
+    } finally {
+      restoreRegistry()
+      useScene.setState(previousScene)
+    }
+  }
+
+  function expectLiveTreeUntouched(live: Record<string, THREE.Group>) {
+    for (const [id, group] of Object.entries(live)) {
+      expect(group.parent).not.toBeNull()
+      expect(group.getObjectByName(`${id}-live`)).toBeDefined()
+    }
+  }
+
+  test.each([
+    ['sync', 'meadow-bake', ['bakeGeometry']],
+    ['async', 'meadow-bake-async', ['bakeGeometryAsync']],
+  ] as const)(
+    '%s export strips, replaces and keeps static plugin kinds without touching the live tree',
+    async (mode, bakedName, expectedCalls) => {
+      await withBakePlugin([pluginId], async ({ root, live, nodes, calls }) => {
+        const prepared =
+          mode === 'sync'
+            ? prepareSceneForExport(root, nodes)
+            : await prepareSceneForExportAsync(root, nodes)
+        try {
+          const scene = prepared.scene
+          expect(scene.getObjectByName(overlayId)).toBeUndefined()
+          expect(scene.getObjectByName(`${overlayId}-live`)).toBeUndefined()
+
+          const meadow = scene.getObjectByName(meadowId)
+          expect(meadow?.getObjectByName(bakedName)).toBeDefined()
+          expect(meadow?.getObjectByName(`${meadowId}-live`)).toBeUndefined()
+
+          expect(scene.getObjectByName(rockId)?.getObjectByName(`${rockId}-live`)).toBeDefined()
+          expect(calls).toEqual([...expectedCalls])
+          expectLiveTreeUntouched(live)
+        } finally {
+          prepared.dispose()
+        }
+      })
+    },
+  )
+
+  test('an uninstalled plugin contributes nothing to the export', async () => {
+    await withBakePlugin([], async ({ root, live, nodes, calls }) => {
+      const prepared = prepareSceneForExport(root, nodes)
+      try {
+        for (const id of [overlayId, meadowId, rockId]) {
+          expect(prepared.scene.getObjectByName(id)).toBeUndefined()
+        }
+        expect(calls).toEqual([])
+        expectLiveTreeUntouched(live)
+      } finally {
+        prepared.dispose()
+      }
+    })
+  })
+})
+
+test('prepared exports preserve surface identities and IFC subpart roles on registered meshes', () => {
+  const root = new THREE.Group()
+  root.name = 'scene-renderer'
+  const owner = { ...BaseNode.parse({ id: 'item_surface_owner' }), type: 'item' } as AnyNode
+  const child = {
+    ...BaseNode.parse({ id: 'item_surface_child', parentId: owner.id }),
+    type: 'item',
+  } as AnyNode
+  const mesh = meshWithNodeMaterial(nodeMaterial())
+  mesh.userData = {
+    surfaceNodeIds: [child.id],
+    pascalIfcRole: 'railing',
+    pascalIfcParts: [{ start: 0, count: 3, role: 'handrail' }],
+  }
+  root.add(mesh)
+  sceneRegistry.nodes.set(owner.id, mesh)
+  const { scene } = prepareSceneForExport(root, { [owner.id]: owner, [child.id]: child })
+  const exported = scene.getObjectByName(owner.id)!
+  expect(exported.userData.pascalId).toBe(owner.id)
+  expect(exported.userData.surfaceNodeIds).toEqual([child.id])
+  expect(exported.userData.pascalIfcRole).toBe('railing')
+  expect(exported.userData.pascalIfcParts).toEqual([{ start: 0, count: 3, role: 'handrail' }])
+})
+
+test('exports a plugin LOD once without invoking its argument-requiring constructor', () => {
+  class PluginLOD extends THREE.LOD {
+    constructor(model: THREE.Mesh) {
+      super()
+      if (!model) throw new Error('Model is required')
+      this.addLevel(model, 0)
+      this.addLevel(model.clone(), 10)
+    }
+  }
+  const mesh = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial())
+  const lod = new PluginLOD(mesh)
+  const root = new THREE.Group()
+  root.add(lod)
+  const { scene } = prepareSceneForExport(root, {})
+  const meshes: THREE.Mesh[] = []
+  scene.traverse((object) => {
+    if (object instanceof THREE.Mesh) meshes.push(object)
+  })
+  expect(meshes).toHaveLength(2)
+  expect(meshes[0]!.geometry).not.toBe(mesh.geometry)
+  expect(lod.levels).toHaveLength(2)
+})