@pascal-app/editor 1.0.0-beta.5 → 1.0.1

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

@@ -1,9 +1,33 @@
 import { afterEach, describe, expect, test } from 'bun:test'
-import { type AnyNode, DoorNode, registerNode, sceneRegistry } from '@pascal-app/core'
-import { buildDoorPreviewMesh } from '@pascal-app/viewer'
+import {
+  type AnyNode,
+  type AnyNodeDefinition,
+  DoorNode,
+  type GeometryContext,
+  loadPlugin,
+  nodeRegistry,
+  registerNode,
+  SiteNode,
+  sceneRegistry,
+  useScene,
+} from '@pascal-app/core'
+import {
+  buildDoorPreviewMesh,
+  markViewerPresentationTextureBorrowed,
+  type ViewerPresentationContribution,
+  viewerPresentationRegistry,
+} from '@pascal-app/viewer'
 import * as THREE from 'three'
 import type { GLTFWriter } from 'three/examples/jsm/exporters/GLTFExporter.js'
-import { prepareSceneForExport, writeTextureReferenceExtras } from './glb-export'
+import { OBJExporter } from 'three/examples/jsm/exporters/OBJExporter.js'
+import { STLExporter } from 'three/examples/jsm/exporters/STLExporter.js'
+import { MeshStandardNodeMaterial } from 'three/webgpu'
+import {
+  prepareSceneForExport,
+  prepareSceneForExportAsync,
+  writeTextureReferenceExtras,
+} from './glb-export'
+import { createUsdzScene } from './portable-export'
 
 // The reference module reads the storage origin lazily on first use, so
 // setting the env here (before any validation call) pins it for the file.
@@ -14,25 +38,15 @@ afterEach(() => {
   sceneRegistry.clear()
 })
 
-function nodeMaterial(overrides: Record<string, unknown> = {}) {
-  // Duck-typed stand-in for the viewer's MeshStandard/LambertNodeMaterial:
-  // the exporter keys off `isNodeMaterial` and reads plain PBR props.
-  return {
-    isNodeMaterial: true,
-    name: 'painted',
-    color: new THREE.Color('#cc3300'),
+function nodeMaterial(overrides: Record<string, unknown> = {}): THREE.Material {
+  const material = new MeshStandardNodeMaterial({
+    color: '#cc3300',
     roughness: 0.3,
     metalness: 0.7,
-    transparent: false,
-    opacity: 1,
-    side: THREE.FrontSide,
-    alphaTest: 0,
-    depthWrite: true,
-    depthTest: true,
-    vertexColors: false,
-    toneMapped: true,
-    ...overrides,
-  } as unknown as THREE.Material
+  })
+  material.name = 'painted'
+  Object.assign(material, overrides)
+  return material
 }
 
 function meshWithNodeMaterial(material: THREE.Material): THREE.Mesh {
@@ -40,6 +54,35 @@ function meshWithNodeMaterial(material: THREE.Material): THREE.Mesh {
   return new THREE.Mesh(geometry, material)
 }
 
+function sceneWithVisibleAndHiddenBoxes(): {
+  root: THREE.Group
+  nodes: Record<string, AnyNode>
+} {
+  const root = new THREE.Group()
+  const nodes: Record<string, AnyNode> = {}
+
+  for (const [id, visible, x] of [
+    ['item_visible', true, 0],
+    ['item_hidden', false, 2],
+  ] as const) {
+    const group = new THREE.Group()
+    const mesh = meshWithNodeMaterial(nodeMaterial())
+    mesh.position.x = x
+    group.add(mesh)
+    root.add(group)
+    sceneRegistry.nodes.set(id, group)
+    nodes[id] = {
+      object: 'node',
+      id,
+      type: 'item',
+      parentId: null,
+      visible,
+    } as unknown as AnyNode
+  }
+
+  return { root, nodes }
+}
+
 describe('prepareSceneForExport', () => {
   test('converts NodeMaterials to classic glTF-standard materials', () => {
     const root = new THREE.Group()
@@ -57,6 +100,340 @@ describe('prepareSceneForExport', () => {
     expect(material.color.getHexString()).toBe('cc3300')
   })
 
+  test('clones userData that holds runtime resources and functions', () => {
+    const root = new THREE.Group()
+    root.name = 'scene-renderer'
+    const effectMaterial = new THREE.MeshStandardMaterial()
+    effectMaterial.addEventListener('dispose', () => {})
+    const pool = meshWithNodeMaterial(nodeMaterial())
+    pool.userData = { waterEffect: { material: effectMaterial, onFrame: () => {} } }
+    const overlay = meshWithNodeMaterial(nodeMaterial())
+    overlay.userData = { pascalExport: 'strip', mesh: pool }
+    root.add(pool, overlay)
+    expect(() => structuredClone(pool.userData)).toThrow()
+
+    const { scene } = prepareSceneForExport(root, {})
+
+    const meshes: THREE.Mesh[] = []
+    scene.traverse((object) => {
+      if ((object as THREE.Mesh).isMesh) meshes.push(object as THREE.Mesh)
+    })
+    expect(meshes).toHaveLength(1)
+    expect(meshes[0]?.userData.waterEffect).toBeUndefined()
+    expect(pool.userData.waterEffect.material).toBe(effectMaterial)
+  })
+
+  test('replaces only the cloned registered subtree with bake-only geometry', () => {
+    const restoreRegistry = nodeRegistry._snapshot()
+    try {
+      let receivedParentId: string | null | undefined
+      registerNode({
+        kind: 'test:bake-geometry',
+        schemaVersion: 1,
+        schema: DoorNode,
+        category: 'utility',
+        defaults: () => ({}) as never,
+        capabilities: {},
+        bake: 'replace',
+        bakeGeometry: (_node, context) => {
+          receivedParentId = context.parent?.id
+          const group = new THREE.Group()
+          const instances = new THREE.InstancedMesh(
+            new THREE.BoxGeometry(0.1, 1, 0.1),
+            new THREE.MeshStandardMaterial({ color: '#228833' }),
+            1,
+          )
+          instances.name = 'baked-instance'
+          instances.setMatrixAt(0, new THREE.Matrix4().makeTranslation(4, 0, 2))
+          group.add(instances)
+          return group
+        },
+      } as AnyNodeDefinition)
+
+      const root = new THREE.Group()
+      const liveGroup = new THREE.Group()
+      liveGroup.position.set(2, 0, 3)
+      const liveMesh = meshWithNodeMaterial(nodeMaterial())
+      liveMesh.name = 'live-procedural-candidate'
+      liveGroup.add(liveMesh)
+      const before = meshWithNodeMaterial(nodeMaterial())
+      before.name = 'before-bake-replacement'
+      const after = meshWithNodeMaterial(nodeMaterial())
+      after.name = 'after-bake-replacement'
+      root.add(before, liveGroup, after)
+
+      const siteId = 'site_bake'
+      const grassId = 'grass_bake'
+      sceneRegistry.nodes.set(grassId, liveGroup)
+      const nodes = {
+        [siteId]: {
+          object: 'node',
+          id: siteId,
+          type: 'site',
+          parentId: null,
+          children: [grassId],
+        } as unknown as AnyNode,
+        [grassId]: {
+          object: 'node',
+          id: grassId,
+          type: 'test:bake-geometry',
+          parentId: siteId,
+          visible: true,
+        } as unknown as AnyNode,
+      }
+
+      const { scene } = prepareSceneForExport(root, nodes)
+      const exported = scene.getObjectByName(grassId)
+      const baked = exported?.getObjectByName('baked-instance')
+
+      expect(receivedParentId).toBe(siteId)
+      expect(liveGroup.getObjectByName('live-procedural-candidate')).toBe(liveMesh)
+      expect(scene.getObjectByName('live-procedural-candidate')).toBeUndefined()
+      expect(exported?.position.toArray()).toEqual([2, 0, 3])
+      expect(scene.children.map((child) => child.name)).toEqual([
+        'before-bake-replacement',
+        grassId,
+        'after-bake-replacement',
+      ])
+      expect((baked as THREE.InstancedMesh | undefined)?.isInstancedMesh).toBe(true)
+      expect((baked as THREE.InstancedMesh | undefined)?.count).toBe(1)
+      expect(((baked as THREE.InstancedMesh).material as THREE.Material).isMaterial).toBe(true)
+    } finally {
+      restoreRegistry()
+    }
+  })
+
+  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()
+    }
+  })
+
+  test('selective exports omit a procedural kind without changing the live scene or later exports', () => {
+    const restoreRegistry = nodeRegistry._snapshot()
+    try {
+      const kind = 'test:optional-ground-cover'
+      registerNode({
+        kind,
+        schemaVersion: 1,
+        schema: DoorNode,
+        category: 'furnish',
+        defaults: () => ({}) as never,
+        capabilities: {},
+        bake: 'replace',
+        bakeGeometry: () =>
+          new THREE.Mesh(
+            new THREE.BoxGeometry(1, 1, 1),
+            new THREE.MeshStandardMaterial({ color: '#228833' }),
+          ),
+      } as AnyNodeDefinition)
+      const root = new THREE.Group()
+      const building = meshWithNodeMaterial(nodeMaterial())
+      const grass = new THREE.Group()
+      const water = meshWithNodeMaterial(nodeMaterial())
+      root.add(building, grass, water)
+      const nodes: Record<string, AnyNode> = {}
+      for (const [id, type, object] of [
+        ['building_export', 'building', building],
+        ['grass_export', kind, grass],
+        ['water_export', 'test:water', water],
+      ] as const) {
+        sceneRegistry.nodes.set(id, object)
+        nodes[id] = { id, type, visible: true } as unknown as AnyNode
+      }
+
+      const complete = prepareSceneForExport(root, nodes)
+      const selected = prepareSceneForExport(root, nodes, {
+        excludedNodeTypes: [kind],
+        onlyVisible: false,
+      })
+      const stl = new STLExporter()
+      expect(stl.parse(complete.scene, { binary: true }).getUint32(80, true)).toBe(36)
+      expect(stl.parse(selected.scene, { binary: true }).getUint32(80, true)).toBe(24)
+      const obj = new OBJExporter().parse(selected.scene)
+      expect(obj).not.toContain('grass_export')
+      expect(obj).toContain('building_export')
+      expect(obj).toContain('water_export')
+      expect(selected.scene.getObjectByName('grass_export')).toBeUndefined()
+      expect(root.children).toEqual([building, grass, water])
+      expect(grass.visible).toBe(true)
+      expect(nodes.grass_export?.visible).toBe(true)
+      const later = prepareSceneForExport(root, nodes)
+      expect(stl.parse(later.scene, { binary: true }).getUint32(80, true)).toBe(36)
+    } finally {
+      restoreRegistry()
+    }
+  })
+
+  test('excluding a parent skips descendant bake failures and animation tracks', () => {
+    const restoreRegistry = nodeRegistry._snapshot()
+    try {
+      registerNode({
+        kind: 'test:unavailable-bake',
+        schemaVersion: 1,
+        schema: DoorNode,
+        category: 'furnish',
+        defaults: () => ({}) as never,
+        capabilities: {},
+        bakeGeometry: () => {
+          throw new Error('Procedural content unavailable')
+        },
+      } as AnyNodeDefinition)
+      const root = new THREE.Group()
+      const excluded = new THREE.Group()
+      const procedural = new THREE.Group()
+      const door = new THREE.Group()
+      const leaf = meshWithNodeMaterial(nodeMaterial())
+      leaf.userData.pascalSwingLeaf = { axis: 'y', openRotationY: Math.PI / 2 }
+      door.add(leaf)
+      excluded.add(procedural, door)
+      root.add(excluded, meshWithNodeMaterial(nodeMaterial()))
+      const nodes: Record<string, AnyNode> = {}
+      for (const [id, type, object, parentId] of [
+        ['procedural_child', 'test:unavailable-bake', procedural, 'excluded_parent'],
+        ['door_child', 'door', door, 'excluded_parent'],
+        ['excluded_parent', 'test:optional-parent', excluded, null],
+      ] as const) {
+        sceneRegistry.nodes.set(id, object)
+        nodes[id] = { id, type, parentId, visible: true } as unknown as AnyNode
+      }
+
+      expect(() => prepareSceneForExport(root, nodes)).toThrow('Procedural content unavailable')
+      const selected = prepareSceneForExport(root, nodes, {
+        excludedNodeTypes: ['test:optional-parent'],
+      })
+      expect(new STLExporter().parse(selected.scene, { binary: true }).getUint32(80, true)).toBe(12)
+      expect(selected.animations).toEqual([])
+      expect(selected.scene.getObjectByName('door_child')).toBeUndefined()
+      expect(excluded.children).toEqual([procedural, door])
+    } finally {
+      restoreRegistry()
+    }
+  })
+
   test('shared NodeMaterial instances convert to a single shared material', () => {
     const root = new THREE.Group()
     const shared = nodeMaterial()
@@ -114,7 +491,11 @@ describe('prepareSceneForExport', () => {
     expect(placeholder.flipY).toBe(stamped.flipY)
     expect(placeholder.colorSpace).toBe(stamped.colorSpace)
     expect(placeholder.userData.pascalTextureRef).toEqual(stamped.userData.pascalTextureRef)
-    expect(material.normalMap).toBe(unstamped)
+    expect(material.normalMap).toBeInstanceOf(THREE.DataTexture)
+    expect(Array.from((material.normalMap as THREE.DataTexture).image.data as Uint8Array)).toEqual([
+      128, 128, 255, 255,
+    ])
+    expect(material.normalMap?.userData.pascalTextureRef).toBeUndefined()
     const sharedMaterial = (scene.children[1] as THREE.Mesh).material as THREE.MeshStandardMaterial
     expect(sharedMaterial.map).toBe(placeholder)
   })
@@ -173,6 +554,151 @@ describe('prepareSceneForExport', () => {
     expect(meshes).toHaveLength(1)
   })
 
+  test('excludes hidden scene nodes and descendants by default', () => {
+    const root = new THREE.Group()
+    const levelGroup = new THREE.Group()
+    const itemGroup = new THREE.Group()
+    itemGroup.add(meshWithNodeMaterial(nodeMaterial()))
+    levelGroup.add(itemGroup)
+    root.add(levelGroup)
+
+    const levelId = 'level_hidden'
+    const itemId = 'item_visible_child'
+    sceneRegistry.nodes.set(levelId, levelGroup)
+    sceneRegistry.nodes.set(itemId, itemGroup)
+    const nodes: Record<string, AnyNode> = {
+      [levelId]: {
+        object: 'node',
+        id: levelId,
+        type: 'level',
+        parentId: null,
+        visible: false,
+      } as unknown as AnyNode,
+      [itemId]: {
+        object: 'node',
+        id: itemId,
+        type: 'item',
+        parentId: levelId,
+        visible: true,
+      } as unknown as AnyNode,
+    }
+
+    const { scene, animations } = prepareSceneForExport(root, nodes)
+
+    expect(scene.getObjectByName(levelId)).toBeUndefined()
+    expect(scene.getObjectByName(itemId)).toBeUndefined()
+    expect(animations).toHaveLength(0)
+  })
+
+  test('inherits hidden Site visibility for detached declared children and their descendants', async () => {
+    const restoreRegistry = nodeRegistry._snapshot()
+    try {
+      const kind = 'test:detached-site-visibility'
+      const childId = 'detached_site_child'
+      const descendantId = 'detached_site_descendant'
+      const explicitId = 'explicit_site_child'
+      const unownedId = 'unowned_site_child'
+      const hiddenSite = SiteNode.parse({
+        visible: false,
+        children: [childId, explicitId],
+      })
+      const visibleSite = SiteNode.parse({ visible: true })
+      registerNode({
+        kind,
+        schemaVersion: 1,
+        schema: DoorNode,
+        category: 'furnish',
+        defaults: () => ({}) as never,
+        capabilities: {},
+        bakeGeometryAsync: async () =>
+          new THREE.Mesh(new THREE.BoxGeometry(2, 1, 3), new THREE.MeshStandardMaterial()),
+      } as AnyNodeDefinition)
+      const nodes = {
+        [hiddenSite.id]: hiddenSite,
+        [visibleSite.id]: visibleSite,
+        [childId]: { id: childId, type: kind, parentId: null, visible: true },
+        [descendantId]: { id: descendantId, type: kind, parentId: childId, visible: true },
+        [explicitId]: { id: explicitId, type: kind, parentId: visibleSite.id, visible: true },
+        [unownedId]: { id: unownedId, type: kind, parentId: null, visible: true },
+      } as unknown as Record<string, AnyNode>
+      const allIds = [childId, descendantId, explicitId, unownedId]
+      const root = new THREE.Group()
+      for (const id of [hiddenSite.id, visibleSite.id, ...allIds]) {
+        const object = new THREE.Group()
+        root.add(object)
+        sceneRegistry.nodes.set(id, object)
+      }
+      const exportedIds = async (onlyVisible?: boolean) => {
+        const prepared = await prepareSceneForExportAsync(root, nodes, { onlyVisible })
+        try {
+          return allIds.filter((id) => prepared.scene.getObjectByName(id) !== undefined)
+        } finally {
+          prepared.dispose()
+        }
+      }
+
+      expect(await exportedIds()).toEqual([explicitId, unownedId])
+      expect(await exportedIds(false)).toEqual(allIds)
+      nodes[hiddenSite.id] = { ...hiddenSite, visible: true }
+      expect(await exportedIds()).toEqual(allIds)
+      nodes[hiddenSite.id] = hiddenSite
+      expect(await exportedIds()).toEqual([explicitId, unownedId])
+    } finally {
+      restoreRegistry()
+    }
+  })
+
+  test('can include hidden scene nodes when visible-only export is disabled', () => {
+    const root = new THREE.Group()
+    const itemGroup = new THREE.Group()
+    itemGroup.add(meshWithNodeMaterial(nodeMaterial()))
+    root.add(itemGroup)
+
+    const itemId = 'item_hidden'
+    sceneRegistry.nodes.set(itemId, itemGroup)
+    const nodes: Record<string, AnyNode> = {
+      [itemId]: {
+        object: 'node',
+        id: itemId,
+        type: 'item',
+        parentId: null,
+        visible: false,
+      } as unknown as AnyNode,
+    }
+
+    const { scene } = prepareSceneForExport(root, nodes, { onlyVisible: false })
+
+    expect(scene.getObjectByName(itemId)?.userData).toMatchObject({
+      pascalId: itemId,
+      kind: 'item',
+    })
+  })
+
+  test('traditional binary STL excludes hidden nodes by default and can include them', () => {
+    const { root, nodes } = sceneWithVisibleAndHiddenBoxes()
+
+    const visibleScene = prepareSceneForExport(root, nodes).scene
+    const completeScene = prepareSceneForExport(root, nodes, { onlyVisible: false }).scene
+    const visibleStl = new STLExporter().parse(visibleScene, { binary: true })
+    const completeStl = new STLExporter().parse(completeScene, { binary: true })
+
+    expect(visibleStl.getUint32(80, true)).toBe(12)
+    expect(completeStl.getUint32(80, true)).toBe(24)
+  })
+
+  test('traditional OBJ excludes hidden nodes by default and can include them', () => {
+    const { root, nodes } = sceneWithVisibleAndHiddenBoxes()
+
+    const visibleScene = prepareSceneForExport(root, nodes).scene
+    const completeScene = prepareSceneForExport(root, nodes, { onlyVisible: false }).scene
+    const visibleObj = new OBJExporter().parse(visibleScene)
+    const completeObj = new OBJExporter().parse(completeScene)
+    const vertexCount = (obj: string) => obj.match(/^v /gm)?.length ?? 0
+
+    expect(vertexCount(visibleObj)).toBe(24)
+    expect(vertexCount(completeObj)).toBe(48)
+  })
+
   test('neutralises an invisible hitbox root but keeps its visible children', () => {
     // Door/window roots are selection hitboxes: a box geometry with an invisible
     // material (object stays visible). Left intact it would plug the wall opening.
@@ -553,4 +1079,832 @@ describe('prepareSceneForExport', () => {
       expect(panel!.quaternion.angleTo(new THREE.Quaternion())).toBeLessThan(1e-4)
     }
   })
+
+  describe('requireSynchronousBake', () => {
+    test('rejects a retained async-only kind instead of returning its proxy', () => {
+      const restoreRegistry = nodeRegistry._snapshot()
+      try {
+        const kind = 'test:async-only-synchronous-export'
+        const nodeId = 'async_only_synchronous_export'
+        registerNode({
+          kind,
+          schemaVersion: 1,
+          schema: DoorNode,
+          category: 'furnish',
+          defaults: () => ({}) as never,
+          capabilities: {},
+          bake: 'replace',
+          bakeGeometryAsync: async () =>
+            new THREE.Mesh(new THREE.BoxGeometry(4, 5, 6), new THREE.MeshStandardMaterial()),
+        } as AnyNodeDefinition)
+
+        const proxyGeometry = new THREE.BoxGeometry(0.25, 0.5, 0.75)
+        const proxyMaterial = new THREE.MeshStandardMaterial()
+        let sourceGeometryDisposals = 0
+        let sourceMaterialDisposals = 0
+        proxyGeometry.addEventListener('dispose', () => {
+          sourceGeometryDisposals += 1
+        })
+        proxyMaterial.addEventListener('dispose', () => {
+          sourceMaterialDisposals += 1
+        })
+        const proxy = new THREE.Mesh(proxyGeometry, proxyMaterial)
+        proxy.name = 'async-only-proxy'
+        const source = new THREE.Group()
+        source.add(proxy)
+        const root = new THREE.Group()
+        root.add(source)
+        sceneRegistry.nodes.set(nodeId, source)
+        const nodes = {
+          [nodeId]: { id: nodeId, type: kind, visible: true },
+        } as unknown as Record<string, AnyNode>
+
+        const compatible = prepareSceneForExport(root, nodes)
+        expect(compatible.scene.getObjectByName('async-only-proxy')).toBeDefined()
+        compatible.dispose()
+
+        let rejection: unknown
+        try {
+          prepareSceneForExport(root, nodes, { requireSynchronousBake: true })
+        } catch (error) {
+          rejection = error
+        }
+
+        expect(rejection).toBeInstanceOf(Error)
+        const message = rejection instanceof Error ? rejection.message : ''
+        expect(message).toContain(kind)
+        expect(message).toMatch(/\bGLB\b/)
+        expect(message).toMatch(/\bUSDZ\b/)
+        expect(message).toMatch(/exclud/i)
+        expect(sourceGeometryDisposals).toBe(0)
+        expect(sourceMaterialDisposals).toBe(0)
+        expect(root.children).toEqual([source])
+        expect(source.children).toEqual([proxy])
+      } finally {
+        restoreRegistry()
+      }
+    })
+
+    test('allows a valid model when every async-only kind is pruned', async () => {
+      const restoreRegistry = nodeRegistry._snapshot()
+      const { installedPlugins, hasExplicitPluginInstallState } = useScene.getState()
+      try {
+        const excludedKind = 'test:excluded-synchronous-export'
+        const hiddenKind = 'test:hidden-synchronous-export'
+        const descendantKind = 'test:descendant-synchronous-export'
+        const disabledKind = 'test:disabled-synchronous-export'
+        const disabledPluginId = 'test:disabled-synchronous-export-plugin'
+        const asyncOnlyDefinition = (kind: string): AnyNodeDefinition =>
+          ({
+            kind,
+            schemaVersion: 1,
+            schema: DoorNode,
+            category: 'furnish',
+            defaults: () => ({}) as never,
+            capabilities: {},
+            bake: 'replace',
+            bakeGeometryAsync: async () => {
+              throw new Error(`Pruned async-only builder ran for ${kind}`)
+            },
+          }) as AnyNodeDefinition
+
+        for (const kind of [excludedKind, hiddenKind, descendantKind]) {
+          registerNode(asyncOnlyDefinition(kind))
+        }
+        await loadPlugin({
+          id: disabledPluginId,
+          apiVersion: 1,
+          nodes: [asyncOnlyDefinition(disabledKind)],
+        })
+        useScene.getState().setInstalledPlugins([], { explicit: true })
+
+        const valid = new THREE.Mesh(
+          new THREE.BoxGeometry(2, 3, 4),
+          new THREE.MeshStandardMaterial(),
+        )
+        valid.name = 'valid-model'
+        const excluded = new THREE.Group()
+        const hidden = new THREE.Group()
+        const disabled = new THREE.Group()
+        const excludedParent = new THREE.Group()
+        const descendant = new THREE.Group()
+        excludedParent.add(descendant)
+        const root = new THREE.Group()
+        root.add(valid, excluded, hidden, disabled, excludedParent)
+
+        const excludedId = 'excluded_async_only'
+        const hiddenId = 'hidden_async_only'
+        const disabledId = 'disabled_async_only'
+        const excludedParentId = 'excluded_async_only_parent'
+        const descendantId = 'descendant_async_only'
+        sceneRegistry.nodes.set(excludedId, excluded)
+        sceneRegistry.nodes.set(hiddenId, hidden)
+        sceneRegistry.nodes.set(disabledId, disabled)
+        sceneRegistry.nodes.set(excludedParentId, excludedParent)
+        sceneRegistry.nodes.set(descendantId, descendant)
+        const nodes = {
+          [excludedId]: { id: excludedId, type: excludedKind, visible: true },
+          [hiddenId]: { id: hiddenId, type: hiddenKind, visible: false },
+          [disabledId]: { id: disabledId, type: disabledKind, visible: true },
+          [excludedParentId]: {
+            id: excludedParentId,
+            type: 'test:excluded-synchronous-export-parent',
+            visible: true,
+            children: [descendantId],
+          },
+          [descendantId]: {
+            id: descendantId,
+            type: descendantKind,
+            parentId: excludedParentId,
+            visible: true,
+          },
+        } as unknown as Record<string, AnyNode>
+
+        const prepared = prepareSceneForExport(root, nodes, {
+          excludedNodeTypes: [excludedKind, 'test:excluded-synchronous-export-parent'],
+          requireSynchronousBake: true,
+        })
+
+        const validModel = prepared.scene.getObjectByName('valid-model')
+        expect(validModel).toBeDefined()
+        const size = new THREE.Box3().setFromObject(validModel!).getSize(new THREE.Vector3())
+        expect(size.toArray()).toEqual([2, 3, 4])
+        for (const id of [excludedId, hiddenId, disabledId, excludedParentId, descendantId]) {
+          expect(prepared.scene.getObjectByName(id)).toBeUndefined()
+        }
+        prepared.dispose()
+      } finally {
+        useScene
+          .getState()
+          .setInstalledPlugins(installedPlugins, { explicit: hasExplicitPluginInstallState })
+        restoreRegistry()
+      }
+    })
+
+    test('uses synchronous geometry when a retained kind provides both hooks', () => {
+      const restoreRegistry = nodeRegistry._snapshot()
+      try {
+        const kind = 'test:dual-hook-synchronous-export'
+        const nodeId = 'dual_hook_synchronous_export'
+        registerNode({
+          kind,
+          schemaVersion: 1,
+          schema: DoorNode,
+          category: 'furnish',
+          defaults: () => ({}) as never,
+          capabilities: {},
+          bake: 'replace',
+          bakeGeometry: () =>
+            new THREE.Mesh(new THREE.BoxGeometry(2, 3, 4), new THREE.MeshStandardMaterial()),
+          bakeGeometryAsync: async () =>
+            new THREE.Mesh(new THREE.BoxGeometry(8, 8, 8), new THREE.MeshStandardMaterial()),
+        } as AnyNodeDefinition)
+
+        const source = new THREE.Group()
+        source.add(
+          new THREE.Mesh(new THREE.BoxGeometry(0.25, 0.5, 0.75), new THREE.MeshStandardMaterial()),
+        )
+        const root = new THREE.Group()
+        root.add(source)
+        sceneRegistry.nodes.set(nodeId, source)
+        const nodes = {
+          [nodeId]: { id: nodeId, type: kind, visible: true },
+        } as unknown as Record<string, AnyNode>
+
+        const prepared = prepareSceneForExport(root, nodes, {
+          requireSynchronousBake: true,
+        })
+
+        const exported = prepared.scene.getObjectByName(nodeId)
+        expect(exported).toBeDefined()
+        const size = new THREE.Box3().setFromObject(exported!).getSize(new THREE.Vector3())
+        expect(size.toArray()).toEqual([2, 3, 4])
+        expect(root.children).toEqual([source])
+        prepared.dispose()
+      } finally {
+        restoreRegistry()
+      }
+    })
+  })
+
+  test('awaits async bake geometry with full semantic context after selection', async () => {
+    const restoreRegistry = nodeRegistry._snapshot()
+    try {
+      const retainedKind = 'test:async-context-bake'
+      let asyncCalls = 0
+      let syncCalls = 0
+      registerNode({
+        kind: retainedKind,
+        schemaVersion: 1,
+        schema: DoorNode,
+        category: 'furnish',
+        defaults: () => ({}) as never,
+        capabilities: {},
+        bake: 'replace',
+        bakeGeometry: () => {
+          syncCalls += 1
+          throw new Error('sync builder must not run when async geometry is available')
+        },
+        bakeGeometryAsync: async (_node, context) => {
+          asyncCalls += 1
+          await Promise.resolve()
+          const obstacle = context.resolve<{ metadata?: { acceptanceWidth?: number } }>(
+            'door_obstacle_async_context',
+          )
+          return new THREE.Mesh(
+            new THREE.BoxGeometry(obstacle?.metadata?.acceptanceWidth ?? 0, 1, 1),
+            new THREE.MeshStandardMaterial(),
+          )
+        },
+      } as AnyNodeDefinition)
+      const root = new THREE.Group()
+      const source = new THREE.Group()
+      const obstacle = new THREE.Group()
+      root.add(source, obstacle)
+      sceneRegistry.nodes.set('async_context_node', source)
+      sceneRegistry.nodes.set('door_obstacle_async_context', obstacle)
+      const nodes = {
+        async_context_node: {
+          id: 'async_context_node',
+          type: retainedKind,
+          visible: true,
+        },
+        door_obstacle_async_context: {
+          id: 'door_obstacle_async_context',
+          type: 'test:excluded-obstacle',
+          visible: true,
+          metadata: { acceptanceWidth: 2 },
+        },
+      } as unknown as Record<string, AnyNode>
+
+      const prepared = await prepareSceneForExportAsync(root, nodes, {
+        excludedNodeTypes: ['test:excluded-obstacle'],
+      })
+      const baked = prepared.scene.children.find((child) => child instanceof THREE.Mesh)
+      expect(asyncCalls).toBe(1)
+      expect(syncCalls).toBe(0)
+      expect(baked).toBeInstanceOf(THREE.Mesh)
+      if (baked instanceof THREE.Mesh) {
+        baked.geometry.computeBoundingBox()
+        expect(baked.geometry.boundingBox?.getSize(new THREE.Vector3()).x).toBeCloseTo(2)
+      }
+      expect(prepared.animations).toEqual([])
+      expect(root.children).toEqual([source, obstacle])
+      prepared.dispose()
+    } finally {
+      restoreRegistry()
+    }
+  })
+
+  test('does not invoke async builders for excluded or invisible nodes', async () => {
+    const restoreRegistry = nodeRegistry._snapshot()
+    try {
+      let calls = 0
+      for (const kind of ['test:excluded-async-bake', 'test:hidden-async-bake']) {
+        registerNode({
+          kind,
+          schemaVersion: 1,
+          schema: DoorNode,
+          category: 'furnish',
+          defaults: () => ({}) as never,
+          capabilities: {},
+          bake: 'replace',
+          bakeGeometryAsync: async () => {
+            calls += 1
+            throw new Error('unselected async builder ran')
+          },
+        } as AnyNodeDefinition)
+      }
+      const root = new THREE.Group()
+      const excluded = new THREE.Group()
+      const hidden = new THREE.Group()
+      const retained = meshWithNodeMaterial(nodeMaterial())
+      root.add(excluded, hidden, retained)
+      sceneRegistry.nodes.set('excluded_async_node', excluded)
+      sceneRegistry.nodes.set('hidden_async_node', hidden)
+      const nodes = {
+        excluded_async_node: {
+          id: 'excluded_async_node',
+          type: 'test:excluded-async-bake',
+          visible: true,
+        },
+        hidden_async_node: {
+          id: 'hidden_async_node',
+          type: 'test:hidden-async-bake',
+          visible: false,
+        },
+      } as unknown as Record<string, AnyNode>
+
+      const prepared = await prepareSceneForExportAsync(root, nodes, {
+        excludedNodeTypes: ['test:excluded-async-bake'],
+        onlyVisible: true,
+      })
+      expect(calls).toBe(0)
+      expect(prepared.scene.children).toHaveLength(1)
+      prepared.dispose()
+    } finally {
+      restoreRegistry()
+    }
+  })
+
+  test('disposes only export-owned resources when a later async builder fails', async () => {
+    const restoreRegistry = nodeRegistry._snapshot()
+    try {
+      const ownedGeometry = new THREE.BoxGeometry()
+      const ownedMaterial = new THREE.MeshStandardMaterial()
+      const sourceGeometry = new THREE.BoxGeometry()
+      const sourceMaterial = new THREE.MeshStandardMaterial()
+      let ownedGeometryDisposals = 0
+      let ownedMaterialDisposals = 0
+      let sourceGeometryDisposals = 0
+      let sourceMaterialDisposals = 0
+      ownedGeometry.addEventListener('dispose', () => {
+        ownedGeometryDisposals += 1
+      })
+      ownedMaterial.addEventListener('dispose', () => {
+        ownedMaterialDisposals += 1
+      })
+      sourceGeometry.addEventListener('dispose', () => {
+        sourceGeometryDisposals += 1
+      })
+      sourceMaterial.addEventListener('dispose', () => {
+        sourceMaterialDisposals += 1
+      })
+      registerNode({
+        kind: 'test:first-owned-async-bake',
+        schemaVersion: 1,
+        schema: DoorNode,
+        category: 'furnish',
+        defaults: () => ({}) as never,
+        capabilities: {},
+        bake: 'replace',
+        bakeGeometryAsync: async () => new THREE.Mesh(ownedGeometry, ownedMaterial),
+      } as AnyNodeDefinition)
+      registerNode({
+        kind: 'test:later-failing-async-bake',
+        schemaVersion: 1,
+        schema: DoorNode,
+        category: 'furnish',
+        defaults: () => ({}) as never,
+        capabilities: {},
+        bake: 'replace',
+        bakeGeometryAsync: async () => {
+          throw new Error('acceptance injected async failure')
+        },
+      } as AnyNodeDefinition)
+      const root = new THREE.Group()
+      const first = new THREE.Group()
+      const failing = new THREE.Group()
+      const source = new THREE.Mesh(sourceGeometry, sourceMaterial)
+      root.add(first, failing, source)
+      sceneRegistry.nodes.set('first_owned_async_node', first)
+      sceneRegistry.nodes.set('later_failing_async_node', failing)
+      const nodes = {
+        first_owned_async_node: {
+          id: 'first_owned_async_node',
+          type: 'test:first-owned-async-bake',
+          visible: true,
+        },
+        later_failing_async_node: {
+          id: 'later_failing_async_node',
+          type: 'test:later-failing-async-bake',
+          visible: true,
+        },
+      } as unknown as Record<string, AnyNode>
+
+      await expect(prepareSceneForExportAsync(root, nodes)).rejects.toThrow(
+        'acceptance injected async failure',
+      )
+      expect(ownedGeometryDisposals).toBe(1)
+      expect(ownedMaterialDisposals).toBe(1)
+      expect(sourceGeometryDisposals).toBe(0)
+      expect(sourceMaterialDisposals).toBe(0)
+      expect(root.children).toEqual([first, failing, source])
+    } finally {
+      restoreRegistry()
+    }
+  })
+
+  test('includes a registered static presentation only when explicitly selected', async () => {
+    const priorPresentations = viewerPresentationRegistry.getSnapshot()
+    viewerPresentationRegistry.reset()
+    try {
+      const contribution: ViewerPresentationContribution = {
+        id: 'test:static-export-presentation',
+        component: async () => ({ default: () => null }),
+        staticExport: {
+          label: 'Acceptance surroundings',
+          build: async ({ nodes, onlyVisible, excludedNodeTypes }) => {
+            const semantic = nodes.semantic_context_node as
+              | { metadata?: { acceptanceDimensions?: [number, number, number] } }
+              | undefined
+            const dimensions = semantic?.metadata?.acceptanceDimensions ?? [0, 0, 0]
+            return new THREE.Mesh(
+              new THREE.BoxGeometry(
+                dimensions[0],
+                onlyVisible ? 0 : dimensions[1],
+                excludedNodeTypes.includes('test:excluded-context') ? dimensions[2] : 0,
+              ),
+              new THREE.MeshStandardMaterial({ color: '#4a6b3d' }),
+            )
+          },
+        },
+      }
+      viewerPresentationRegistry.register(contribution)
+      const root = new THREE.Group()
+      root.add(meshWithNodeMaterial(nodeMaterial()))
+      const nodes = {
+        semantic_context_node: {
+          id: 'semantic_context_node',
+          type: 'test:semantic-context',
+          visible: true,
+          metadata: { acceptanceDimensions: [3, 1, 2] },
+        },
+      } as unknown as Record<string, AnyNode>
+
+      const defaultArtifact = await prepareSceneForExportAsync(root, nodes, {
+        onlyVisible: false,
+      })
+      expect(
+        defaultArtifact.scene.getObjectByProperty('name', 'test:static-export-presentation'),
+      ).toBeUndefined()
+      defaultArtifact.dispose()
+
+      const selectedArtifact = await prepareSceneForExportAsync(root, nodes, {
+        excludedNodeTypes: ['test:excluded-context'],
+        includedPresentationIds: [contribution.id],
+        onlyVisible: false,
+      })
+      const presentation = selectedArtifact.scene.getObjectByProperty('name', contribution.id)
+      expect(presentation?.userData).toMatchObject({
+        label: 'Acceptance surroundings',
+        pascalPresentationId: contribution.id,
+      })
+      const bounds = new THREE.Box3().setFromObject(presentation!)
+      expect(bounds.getSize(new THREE.Vector3()).toArray()).toEqual([3, 1, 2])
+      selectedArtifact.dispose()
+    } finally {
+      viewerPresentationRegistry.reset()
+      for (const contribution of priorPresentations) {
+        viewerPresentationRegistry.register(contribution)
+      }
+    }
+  })
+
+  test('preserves marked borrowed presentation textures and disposes owned maps', async () => {
+    await withCanvasCapture(async (canvasPixels) => {
+      const priorPresentations = viewerPresentationRegistry.getSnapshot()
+      viewerPresentationRegistry.reset()
+      const borrowed = new THREE.DataTexture(new Uint8Array([20, 40, 60, 255]), 1, 1)
+      const owned = new THREE.DataTexture(new Uint8Array([80, 100, 120, 255]), 1, 1)
+      const borrowedOnFailure = new THREE.DataTexture(new Uint8Array([140, 160, 180, 255]), 1, 1)
+      const ownedOnFailure = new THREE.DataTexture(new Uint8Array([200, 220, 240, 255]), 1, 1)
+      markViewerPresentationTextureBorrowed(borrowed)
+      markViewerPresentationTextureBorrowed(borrowedOnFailure)
+      const disposals = {
+        borrowed: 0,
+        owned: 0,
+        borrowedOnFailure: 0,
+        ownedOnFailure: 0,
+      }
+      for (const [texture, key] of [
+        [borrowed, 'borrowed'],
+        [owned, 'owned'],
+        [borrowedOnFailure, 'borrowedOnFailure'],
+        [ownedOnFailure, 'ownedOnFailure'],
+      ] as const) {
+        texture.addEventListener('dispose', () => {
+          disposals[key] += 1
+        })
+      }
+      const textureContribution = (
+        id: string,
+        texture: THREE.Texture,
+      ): ViewerPresentationContribution => ({
+        id,
+        component: async () => ({ default: () => null }),
+        staticExport: {
+          label: id,
+          build: () =>
+            new THREE.Mesh(
+              new THREE.PlaneGeometry(1, 1),
+              new THREE.MeshStandardMaterial({ map: texture }),
+            ),
+        },
+      })
+      try {
+        viewerPresentationRegistry.register(
+          textureContribution('test:borrowed-presentation-texture', borrowed),
+        )
+        viewerPresentationRegistry.register(
+          textureContribution('test:owned-presentation-texture', owned),
+        )
+        const success = await prepareSceneForExportAsync(
+          new THREE.Group(),
+          {},
+          {
+            includedPresentationIds: [
+              'test:borrowed-presentation-texture',
+              'test:owned-presentation-texture',
+            ],
+          },
+        )
+        const generatedTextures: THREE.Texture[] = []
+        success.scene.traverse((object) => {
+          if (!(object as THREE.Mesh).isMesh) return
+          const mesh = object as THREE.Mesh
+          const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material]
+          for (const material of materials) {
+            const map = (material as THREE.MeshStandardMaterial).map
+            if (map) generatedTextures.push(map)
+          }
+        })
+        expect(generatedTextures).toHaveLength(2)
+        expect(
+          generatedTextures.every((texture) => (texture as THREE.CanvasTexture).isCanvasTexture),
+        ).toBe(true)
+        expect(generatedTextures.map(canvasPixels).sort()).toEqual(
+          [
+            [20, 40, 60, 255],
+            [80, 100, 120, 255],
+          ].sort(),
+        )
+        let generatedTextureDisposals = 0
+        for (const texture of generatedTextures) {
+          texture.addEventListener('dispose', () => {
+            generatedTextureDisposals += 1
+          })
+        }
+        success.dispose()
+        expect(generatedTextureDisposals).toBe(2)
+        expect(disposals).toMatchObject({ borrowed: 0, owned: 1 })
+        expect(Array.from(borrowed.image.data as Uint8Array)).toEqual([20, 40, 60, 255])
+
+        viewerPresentationRegistry.register(
+          textureContribution('test:borrowed-presentation-texture-failure', borrowedOnFailure),
+        )
+        viewerPresentationRegistry.register(
+          textureContribution('test:owned-presentation-texture-failure', ownedOnFailure),
+        )
+        viewerPresentationRegistry.register({
+          id: 'test:failing-presentation-after-textures',
+          component: async () => ({ default: () => null }),
+          staticExport: {
+            label: 'Injected failure after texture ownership',
+            build: () => {
+              throw new Error('acceptance presentation texture failure')
+            },
+          },
+        })
+        await expect(
+          prepareSceneForExportAsync(
+            new THREE.Group(),
+            {},
+            {
+              includedPresentationIds: [
+                'test:borrowed-presentation-texture-failure',
+                'test:owned-presentation-texture-failure',
+                'test:failing-presentation-after-textures',
+              ],
+            },
+          ),
+        ).rejects.toThrow('acceptance presentation texture failure')
+        expect(disposals).toEqual({
+          borrowed: 0,
+          owned: 1,
+          borrowedOnFailure: 0,
+          ownedOnFailure: 1,
+        })
+        expect(Array.from(borrowedOnFailure.image.data as Uint8Array)).toEqual([140, 160, 180, 255])
+      } finally {
+        viewerPresentationRegistry.reset()
+        for (const contribution of priorPresentations) {
+          viewerPresentationRegistry.register(contribution)
+        }
+      }
+    })
+  })
+})
+
+async function withCanvasCapture(
+  run: (pixels: (texture: THREE.Texture) => number[]) => Promise<void>,
+): Promise<void> {
+  const globals = globalThis as unknown as { document?: Document }
+  const previousDocument = globals.document
+  const pixelsByCanvas = new WeakMap<HTMLCanvasElement, Uint8ClampedArray>()
+  globals.document = {
+    createElement: (tagName: string) => {
+      if (tagName !== 'canvas') throw new Error(`Unexpected element request: ${tagName}`)
+      const canvas = {
+        width: 0,
+        height: 0,
+        getContext: () => ({
+          createImageData: (width: number, height: number) =>
+            ({
+              colorSpace: 'srgb',
+              data: new Uint8ClampedArray(width * height * 4),
+              height,
+              width,
+            }) as ImageData,
+          putImageData: (image: ImageData) => {
+            pixelsByCanvas.set(canvas, new Uint8ClampedArray(image.data))
+          },
+          fillRect: (_x: number, _y: number, width: number, height: number) => {
+            pixelsByCanvas.set(canvas, new Uint8ClampedArray(width * height * 4).fill(255))
+          },
+          drawImage: (image: HTMLCanvasElement) => {
+            const pixels = pixelsByCanvas.get(image)
+            if (!pixels) throw new Error('Source canvas has no captured pixels')
+            pixelsByCanvas.set(canvas, new Uint8ClampedArray(pixels))
+          },
+          getImageData: (_x: number, _y: number, width: number, height: number) =>
+            ({
+              colorSpace: 'srgb',
+              data: pixelsByCanvas.get(canvas) ?? new Uint8ClampedArray(width * height * 4),
+              height,
+              width,
+            }) as ImageData,
+        }),
+      } as unknown as HTMLCanvasElement
+      return canvas
+    },
+  } as unknown as Document
+
+  try {
+    await run((texture) => {
+      const pixels = pixelsByCanvas.get(texture.image as HTMLCanvasElement)
+      if (!pixels) throw new Error('Generated canvas texture has no captured pixels')
+      return Array.from(pixels)
+    })
+  } finally {
+    if (previousDocument) globals.document = previousDocument
+    else delete globals.document
+  }
+}
+
+describe('normal maps in async export preparation', () => {
+  test('decompresses a compressed normal map through the provided decompressor before baking its scale', async () => {
+    await withCanvasCapture(async () => {
+      const root = new THREE.Group()
+      const compressed = new THREE.CompressedTexture([], 2, 2)
+      compressed.name = 'NormalGL_3a132c5f'
+      const material = nodeMaterial({ normalMap: compressed }) as THREE.MeshStandardMaterial
+      material.normalScale.set(0.5, 0.5)
+      root.add(meshWithNodeMaterial(material))
+      let calls = 0
+
+      const prepared = await prepareSceneForExportAsync(
+        root,
+        {},
+        {
+          decompressTexture: async (texture) => {
+            calls += 1
+            expect(texture.name).toBe('NormalGL_3a132c5f')
+            return new THREE.DataTexture(
+              new Uint8Array(
+                [128, 128, 255, 255].concat(
+                  [128, 128, 255, 255],
+                  [128, 128, 255, 255],
+                  [128, 128, 255, 255],
+                ),
+              ),
+              2,
+              2,
+            )
+          },
+        },
+      )
+
+      const exported = (prepared.scene.children[0] as THREE.Mesh)
+        .material as THREE.MeshStandardMaterial
+      expect(calls).toBe(1)
+      expect((exported.normalMap as { isCanvasTexture?: boolean }).isCanvasTexture).toBe(true)
+      expect(exported.normalScale.toArray()).toEqual([1, 1])
+      expect(material.normalMap).toBe(compressed)
+      expect(material.normalScale.toArray()).toEqual([0.5, 0.5])
+    })
+  })
+
+  test('reference mode keeps a stamped normal-map placeholder and its scale for the packer', async () => {
+    await withCanvasCapture(async () => {
+      const root = new THREE.Group()
+      const stamped = new THREE.CompressedTexture([], 4, 4)
+      stamped.userData.pascalTextureRef = {
+        v: 1,
+        kind: 'library-material',
+        src: `${STORAGE_ORIGIN}/storage/v1/object/public/materials/user/material/oak_normal_512.ktx2`,
+        map: 'normal',
+        colorSpace: 'linear',
+      }
+      const material = nodeMaterial({ normalMap: stamped }) as THREE.MeshStandardMaterial
+      material.normalScale.set(1, -1)
+      root.add(meshWithNodeMaterial(material))
+
+      const prepared = await prepareSceneForExportAsync(
+        root,
+        {},
+        {
+          textures: 'reference',
+          purpose: 'viewer',
+          decompressTexture: async () => {
+            throw new Error('by-reference placeholders must not be decompressed')
+          },
+        },
+      )
+
+      const exported = (prepared.scene.children[0] as THREE.Mesh)
+        .material as THREE.MeshStandardMaterial
+      expect(exported.normalMap?.userData.pascalTextureRef).toEqual(
+        stamped.userData.pascalTextureRef,
+      )
+      expect(exported.normalScale.toArray()).toEqual([1, -1])
+    })
+  })
+})
+
+describe('portable glass', () => {
+  test('see-through untextured surfaces become transmission glass in portable exports only', async () => {
+    const root = new THREE.Group()
+    const glass = new MeshStandardNodeMaterial({
+      color: '#3d9ed4',
+      transparent: true,
+      opacity: 0.3,
+      roughness: 0.1,
+    })
+    const tintedPlastic = new MeshStandardNodeMaterial({
+      color: '#3d9ed4',
+      transparent: true,
+      opacity: 0.8,
+    })
+    root.add(meshWithNodeMaterial(glass), meshWithNodeMaterial(tintedPlastic))
+
+    const portable = await prepareSceneForExportAsync(root, {})
+    const [exportedGlass, exportedPlastic] = portable.scene.children.map(
+      (child) => (child as THREE.Mesh).material as THREE.MeshPhysicalMaterial,
+    )
+    expect(exportedGlass!.isMeshPhysicalMaterial).toBe(true)
+    expect(exportedGlass!.transmission).toBe(1)
+    expect(exportedGlass!.transparent).toBe(false)
+    expect(exportedGlass!.opacity).toBe(1)
+    expect(exportedGlass!.roughness).toBeCloseTo(0.1)
+    // 30% authored opacity keeps 30% of the (linear) tint.
+    const tint = new THREE.Color('#3d9ed4')
+    expect(exportedGlass!.color.r).toBeCloseTo(tint.r + (1 - tint.r) * 0.7, 4)
+    expect(exportedGlass!.color.b).toBeCloseTo(tint.b + (1 - tint.b) * 0.7, 4)
+    expect(exportedPlastic!.isMeshPhysicalMaterial).toBeUndefined()
+    expect(exportedPlastic!.transparent).toBe(true)
+
+    const viewer = prepareSceneForExport(root, {}, { purpose: 'viewer' })
+    const kept = (viewer.scene.children[0] as THREE.Mesh).material as THREE.MeshStandardMaterial
+    expect((kept as { isMeshPhysicalMaterial?: boolean }).isMeshPhysicalMaterial).toBeUndefined()
+    expect(kept.transparent).toBe(true)
+    expect(kept.opacity).toBeCloseTo(0.3)
+
+    // USDZ has no transmission: the same prep hands glass its opacity back.
+    const usdz = createUsdzScene(portable.scene)
+    const usdzGlass = (usdz.children[0] as THREE.Mesh).material as THREE.MeshPhysicalMaterial
+    expect(usdzGlass.transmission).toBe(0)
+    expect(usdzGlass.transparent).toBe(true)
+    expect(usdzGlass.opacity).toBeCloseTo(0.3)
+    expect(exportedGlass!.transmission).toBe(1)
+  })
+})
+
+describe('portable clips', () => {
+  function swingDoorScene() {
+    const root = new THREE.Group()
+    const doorGroup = new THREE.Group()
+    const leaf = new THREE.Group()
+    leaf.userData.pascalSwingLeaf = { axis: 'y', openRotationY: Math.PI / 2 }
+    leaf.add(meshWithNodeMaterial(nodeMaterial()))
+    doorGroup.add(leaf)
+    root.add(doorGroup)
+    const doorId = 'door_portable'
+    sceneRegistry.nodes.set(doorId, doorGroup)
+    const nodes: Record<string, AnyNode> = {
+      [doorId]: { object: 'node', id: doorId, type: 'door', name: 'Door' } as unknown as AnyNode,
+    }
+    return { root, nodes, doorId }
+  }
+
+  test('GLB downloads keep door clips when asked, USDZ passes none', async () => {
+    const { root, nodes, doorId } = swingDoorScene()
+
+    const glb = await prepareSceneForExportAsync(root, nodes, { animations: 'keep' })
+    expect(glb.animations).toHaveLength(1)
+    expect(glb.animations[0]!.name).toBe(`${doorId}: open`)
+    const track = glb.animations[0]!.tracks[0]!
+    const targetUuid = track.name.split('.')[0]
+    expect(glb.scene.getObjectByProperty('uuid', targetUuid)).toBeDefined()
+    expect(glb.scene.getObjectByProperty('name', doorId)?.userData.clips).toEqual([
+      `${doorId}: open`,
+    ])
+
+    const usdz = await prepareSceneForExportAsync(root, nodes, { animations: 'none' })
+    expect(usdz.animations).toEqual([])
+    expect(usdz.scene.getObjectByProperty('name', doorId)?.userData.clips).toBeUndefined()
+
+    const legacy = await prepareSceneForExportAsync(root, nodes)
+    expect(legacy.animations).toEqual([])
+  })
 })