@flighthq/scene3d-resources 0.3.0-next.906.07cea63 → 0.3.0

package/src/revealScene3DResourcesOnResolve.test.ts

@@ -8,25 +8,37 @@ import { createTweenManager, hasTweensOf, updateTweens } from '@flighthq/tween/c
 import type { Scene3D } from '@flighthq/types/contract';
 import type {
   EmbeddedImageResourceReference,
-  ImageResource,
+  Image,
   Node3D,
   Scene3DResourceEvent,
   Texture,
 } from '@flighthq/types/contract';
-import { ResourceResolutionState } from '@flighthq/types/contract';
+import { ImageTextureSourceKind, ResourceResolutionState } from '@flighthq/types/contract';
 
 import { revealScene3DResourcesOnResolve } from './revealScene3DResourcesOnResolve';
 import { createBuiltInScene3DResourceResolver } from './sceneResourceResolver';
 import { enableScene3DResourceSignals } from './sceneResourceSignals';
 
+const testResources: EmbeddedImageResourceReference[] = [];
+
 function pendingRef(): EmbeddedImageResourceReference {
-  return {
+  const ref: EmbeddedImageResourceReference = {
     bytes: new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
     failure: null,
     kind: 'Embedded',
     mimeType: 'image/png',
     state: ResourceResolutionState.Unresolved,
   };
+  testResources.push(ref);
+  return ref;
+}
+
+function resourceOf(texture: Texture): EmbeddedImageResourceReference {
+  return testResources.find((ref) => ref.textures?.includes(texture) === true)!;
+}
+
+function configureResources(scene: Scene3D): void {
+  scene.resources = testResources.slice();
 }
 
 function sceneWithPendingTexture(): { mesh: Node3D; scene: Scene3D; texture: Texture } {
@@ -34,6 +46,7 @@ function sceneWithPendingTexture(): { mesh: Node3D; scene: Scene3D; texture: Tex
   const material = createStandardPbrMaterial({ baseColorMap: texture });
   const mesh = createMesh(createBoxMeshGeometry(), [material]);
   const scene = createScene3D();
+  configureResources(scene);
   addNodeChild(scene.root, mesh);
   return { mesh, scene, texture };
 }
@@ -42,14 +55,14 @@ describe('revealScene3DResourcesOnResolve', () => {
   it('hides every object carrying a pending texture to the start opacity up front', () => {
     const { mesh, scene } = sceneWithPendingTexture();
     const resolver = createBuiltInScene3DResourceResolver();
-    revealScene3DResourcesOnResolve(resolver, scene.root, createTweenManager());
+    revealScene3DResourcesOnResolve(resolver, scene, createTweenManager());
     expect(mesh.alpha).toBe(0);
   });
 
   it('honors a custom from opacity', () => {
     const { mesh, scene } = sceneWithPendingTexture();
     const resolver = createBuiltInScene3DResourceResolver();
-    revealScene3DResourcesOnResolve(resolver, scene.root, createTweenManager(), { from: 0.2 });
+    revealScene3DResourcesOnResolve(resolver, scene, createTweenManager(), { from: 0.2 });
     expect(mesh.alpha).toBeCloseTo(0.2);
   });
 
@@ -57,11 +70,11 @@ describe('revealScene3DResourcesOnResolve', () => {
     const { mesh, scene, texture } = sceneWithPendingTexture();
     const resolver = createBuiltInScene3DResourceResolver();
     const manager = createTweenManager();
-    revealScene3DResourcesOnResolve(resolver, scene.root, manager, { fadeSeconds: 0.5 });
+    revealScene3DResourcesOnResolve(resolver, scene, manager, { fadeSeconds: 0.5 });
     expect(mesh.alpha).toBe(0);
 
     const signals = enableScene3DResourceSignals(resolver);
-    const event: Scene3DResourceEvent = { ref: texture.resource!, texture };
+    const event: Scene3DResourceEvent = { ref: resourceOf(texture), texture };
     emitSignal(signals.onResourceResolved, event);
     expect(hasTweensOf(manager, mesh)).toBe(true);
 
@@ -75,16 +88,17 @@ describe('revealScene3DResourcesOnResolve', () => {
     const material = createStandardPbrMaterial({ baseColorMap, normalMap });
     const mesh = createMesh(createBoxMeshGeometry(), [material]);
     const scene = createScene3D();
+    configureResources(scene);
     addNodeChild(scene.root, mesh);
     const resolver = createBuiltInScene3DResourceResolver();
     const manager = createTweenManager();
-    revealScene3DResourcesOnResolve(resolver, scene.root, manager, { fadeSeconds: 0.5 });
+    revealScene3DResourcesOnResolve(resolver, scene, manager, { fadeSeconds: 0.5 });
 
     const signals = enableScene3DResourceSignals(resolver);
-    emitSignal(signals.onResourceResolved, { ref: baseColorMap.resource!, texture: baseColorMap });
+    emitSignal(signals.onResourceResolved, { ref: resourceOf(baseColorMap), texture: baseColorMap });
     expect(hasTweensOf(manager, mesh)).toBe(false);
 
-    emitSignal(signals.onResourceResolved, { ref: normalMap.resource!, texture: normalMap });
+    emitSignal(signals.onResourceResolved, { ref: resourceOf(normalMap), texture: normalMap });
     expect(hasTweensOf(manager, mesh)).toBe(true);
   });
 
@@ -94,23 +108,25 @@ describe('revealScene3DResourcesOnResolve', () => {
     const material = createStandardPbrMaterial({ baseColorMap, normalMap });
     const mesh = createMesh(createBoxMeshGeometry(), [material]);
     const scene = createScene3D();
+    configureResources(scene);
     addNodeChild(scene.root, mesh);
     const resolver = createBuiltInScene3DResourceResolver();
     const manager = createTweenManager();
-    revealScene3DResourcesOnResolve(resolver, scene.root, manager, { fadeSeconds: 0.5 });
+    revealScene3DResourcesOnResolve(resolver, scene, manager, { fadeSeconds: 0.5 });
 
     const signals = enableScene3DResourceSignals(resolver);
-    emitSignal(signals.onResourceFailed, { ref: normalMap.resource!, texture: normalMap });
+    emitSignal(signals.onResourceFailed, { ref: resourceOf(normalMap), texture: normalMap });
     expect(hasTweensOf(manager, mesh)).toBe(false);
 
-    emitSignal(signals.onResourceResolved, { ref: baseColorMap.resource!, texture: baseColorMap });
+    emitSignal(signals.onResourceResolved, { ref: resourceOf(baseColorMap), texture: baseColorMap });
     expect(hasTweensOf(manager, mesh)).toBe(true);
   });
 
   it('does not hide an owner whose resource was already bound or had already failed', () => {
     const bound = createTexture({
       resource: pendingRef(),
-      storage: { dimension: '2d', image: { height: 1, width: 1 } as ImageResource },
+      dimension: '2d',
+      source: { height: 1, kind: ImageTextureSourceKind, width: 1 } as Image,
     });
     const failedRef = pendingRef();
     failedRef.state = ResourceResolutionState.Failed;
@@ -118,9 +134,10 @@ describe('revealScene3DResourcesOnResolve', () => {
     const material = createStandardPbrMaterial({ baseColorMap: bound, normalMap: failed });
     const mesh = createMesh(createBoxMeshGeometry(), [material]);
     const scene = createScene3D();
+    configureResources(scene);
     addNodeChild(scene.root, mesh);
 
-    revealScene3DResourcesOnResolve(createBuiltInScene3DResourceResolver(), scene.root, createTweenManager());
+    revealScene3DResourcesOnResolve(createBuiltInScene3DResourceResolver(), scene, createTweenManager());
     expect(mesh.alpha).toBe(1);
   });
 
@@ -129,13 +146,14 @@ describe('revealScene3DResourcesOnResolve', () => {
     const a = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial({ baseColorMap: texture })]);
     const b = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial({ baseColorMap: texture })]);
     const scene = createScene3D();
+    configureResources(scene);
     addNodeChild(scene.root, a);
     addNodeChild(scene.root, b);
     const resolver = createBuiltInScene3DResourceResolver();
     const manager = createTweenManager();
-    revealScene3DResourcesOnResolve(resolver, scene.root, manager);
+    revealScene3DResourcesOnResolve(resolver, scene, manager);
 
-    emitSignal(enableScene3DResourceSignals(resolver).onResourceResolved, { ref: texture.resource!, texture });
+    emitSignal(enableScene3DResourceSignals(resolver).onResourceResolved, { ref: resourceOf(texture), texture });
     expect(hasTweensOf(manager, a)).toBe(true);
     expect(hasTweensOf(manager, b)).toBe(true);
   });
@@ -144,10 +162,10 @@ describe('revealScene3DResourcesOnResolve', () => {
     const { scene } = sceneWithPendingTexture();
     const resolver = createBuiltInScene3DResourceResolver();
     const manager = createTweenManager();
-    revealScene3DResourcesOnResolve(resolver, scene.root, manager, { fadeSeconds: 0.5 });
+    revealScene3DResourcesOnResolve(resolver, scene, manager, { fadeSeconds: 0.5 });
 
     const stray = createTexture({ resource: pendingRef() });
-    emitSignal(enableScene3DResourceSignals(resolver).onResourceResolved, { ref: stray.resource!, texture: stray });
+    emitSignal(enableScene3DResourceSignals(resolver).onResourceResolved, { ref: resourceOf(stray), texture: stray });
     expect(hasTweensOf(manager, stray as unknown as object)).toBe(false);
   });
 
@@ -155,10 +173,10 @@ describe('revealScene3DResourcesOnResolve', () => {
     const { mesh, scene, texture } = sceneWithPendingTexture();
     const resolver = createBuiltInScene3DResourceResolver();
     const manager = createTweenManager();
-    const dispose = revealScene3DResourcesOnResolve(resolver, scene.root, manager, { fadeSeconds: 0.5 });
+    const dispose = revealScene3DResourcesOnResolve(resolver, scene, manager, { fadeSeconds: 0.5 });
     dispose();
 
-    emitSignal(enableScene3DResourceSignals(resolver).onResourceResolved, { ref: texture.resource!, texture });
+    emitSignal(enableScene3DResourceSignals(resolver).onResourceResolved, { ref: resourceOf(texture), texture });
     expect(hasTweensOf(manager, mesh)).toBe(false);
   });
 });

package/src/sceneMaterialTextureRegistry.test.ts

@@ -1,13 +1,29 @@
-import { createStandardPbrMaterial, createUnlitMaterial } from '@flighthq/materials/contract';
+import {
+  createAnisotropyPbrExtension,
+  createExtendedPbrMaterial,
+  createStandardPbrMaterial,
+  createStandardPbrMaterialProperties,
+  createUnlitMaterial,
+} from '@flighthq/materials/contract';
 import { createTexture } from '@flighthq/texture/contract';
 import type { Material, Texture } from '@flighthq/types/contract';
-import { EntityRuntimeKey, StandardPbrMaterialKind, UnlitMaterialKind } from '@flighthq/types/contract';
+import {
+  AnisotropyPbrExtensionKind,
+  EntityRuntimeKey,
+  ExtendedPbrMaterialKind,
+  StandardPbrMaterialKind,
+  UnlitMaterialKind,
+} from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
 import {
   createScene3DMaterialTextureRegistry,
   getScene3DMaterialTextures,
-  registerBuiltInScene3DMaterialTextures,
+  hasScene3DMaterialTextureLister,
+  registerStandardPbrScene3DMaterialTextures,
+  registerUnlitScene3DMaterialTextures,
+  registerExtendedPbrScene3DMaterialTextures,
+  registerScene3DPbrExtensionTextures,
   registerScene3DMaterialTextures,
 } from './sceneMaterialTextureRegistry';
 
@@ -15,6 +31,7 @@ describe('createScene3DMaterialTextureRegistry', () => {
   it('creates an empty registry', () => {
     const registry = createScene3DMaterialTextureRegistry();
     expect(EntityRuntimeKey in registry).toBe(true);
+    expect(registry.extensionListers.size).toBe(0);
     expect(registry.listers.size).toBe(0);
   });
 });
@@ -29,7 +46,9 @@ describe('getScene3DMaterialTextures', () => {
 
   it('accumulates across calls without clearing out', () => {
     const registry = createScene3DMaterialTextureRegistry();
-    registerBuiltInScene3DMaterialTextures(registry);
+    registerStandardPbrScene3DMaterialTextures(registry);
+    registerUnlitScene3DMaterialTextures(registry);
+    registerExtendedPbrScene3DMaterialTextures(registry);
     const a = createTexture();
     const b = createTexture();
     const out: Texture[] = [];
@@ -39,34 +58,37 @@ describe('getScene3DMaterialTextures', () => {
   });
 });
 
-describe('registerBuiltInScene3DMaterialTextures', () => {
-  it('registers the standard-pbr and unlit listers', () => {
-    const registry = createScene3DMaterialTextureRegistry();
-    registerBuiltInScene3DMaterialTextures(registry);
-    expect(registry.listers.has(StandardPbrMaterialKind)).toBe(true);
-    expect(registry.listers.has(UnlitMaterialKind)).toBe(true);
-  });
-
-  it('lists every non-null standard-pbr texture slot and skips null ones', () => {
+describe('hasScene3DMaterialTextureLister', () => {
+  it('separates an unregistered kind from a material that genuinely has no maps', () => {
+    // getScene3DMaterialTextures appends nothing in both cases, so this is the only way to tell them
+    // apart — which is what explainScene3DResourceCoverage reports through.
     const registry = createScene3DMaterialTextureRegistry();
-    registerBuiltInScene3DMaterialTextures(registry);
-    const baseColorMap = createTexture();
-    const normalMap = createTexture();
-    const material = createStandardPbrMaterial({ baseColorMap, normalMap });
-    const out: Texture[] = [];
-    getScene3DMaterialTextures(registry, material, out);
-    expect(out).toContain(baseColorMap);
-    expect(out).toContain(normalMap);
-    expect(out).toHaveLength(2);
+    registerUnlitScene3DMaterialTextures(registry);
+    expect(hasScene3DMaterialTextureLister(registry, UnlitMaterialKind)).toBe(true);
+    expect(hasScene3DMaterialTextureLister(registry, StandardPbrMaterialKind)).toBe(false);
   });
+});
 
-  it('lists the unlit base-color slot', () => {
+describe('registerExtendedPbrScene3DMaterialTextures', () => {
+  it('lists standard maps and dispatches extensions through the nested kind registry', () => {
     const registry = createScene3DMaterialTextureRegistry();
-    registerBuiltInScene3DMaterialTextures(registry);
+    registerExtendedPbrScene3DMaterialTextures(registry);
     const baseColorMap = createTexture();
+    const anisotropyMap = createTexture();
+    registerScene3DPbrExtensionTextures(registry, AnisotropyPbrExtensionKind, (extension, out) => {
+      const anisotropy = extension as ReturnType<typeof createAnisotropyPbrExtension>;
+      if (anisotropy.anisotropyMap !== null) out.push(anisotropy.anisotropyMap);
+    });
     const out: Texture[] = [];
-    getScene3DMaterialTextures(registry, createUnlitMaterial({ baseColorMap }), out);
-    expect(out).toEqual([baseColorMap]);
+    getScene3DMaterialTextures(
+      registry,
+      createExtendedPbrMaterial({
+        extensions: [createAnisotropyPbrExtension({ anisotropyMap })],
+        standard: createStandardPbrMaterialProperties({ baseColorMap }),
+      }),
+      out,
+    );
+    expect(out).toEqual([baseColorMap, anisotropyMap]);
   });
 });
 
@@ -93,3 +115,73 @@ describe('registerScene3DMaterialTextures', () => {
     expect(out).toEqual([second]);
   });
 });
+
+describe('registerScene3DPbrExtensionTextures', () => {
+  it('is last-write-wins for vendor extension listers', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    const first = createTexture();
+    const second = createTexture();
+    registerScene3DPbrExtensionTextures(registry, AnisotropyPbrExtensionKind, (_extension, out) => out.push(first));
+    registerScene3DPbrExtensionTextures(registry, AnisotropyPbrExtensionKind, (_extension, out) => out.push(second));
+    const out: Texture[] = [];
+    registry.extensionListers.get(AnisotropyPbrExtensionKind)?.(createAnisotropyPbrExtension(), out);
+    expect(out).toEqual([second]);
+  });
+});
+
+describe('registerStandardPbrScene3DMaterialTextures', () => {
+  it('composes with the sibling doors to cover the three surface families', () => {
+    // What createBuiltInScene3DResourceResolver now spells out in its own body, rather than hiding it
+    // behind one registrar whose name did not say which families it covered.
+    const registry = createScene3DMaterialTextureRegistry();
+    registerStandardPbrScene3DMaterialTextures(registry);
+    registerUnlitScene3DMaterialTextures(registry);
+    registerExtendedPbrScene3DMaterialTextures(registry);
+    expect(registry.listers.has(ExtendedPbrMaterialKind)).toBe(true);
+    expect(registry.listers.has(StandardPbrMaterialKind)).toBe(true);
+    expect(registry.listers.has(UnlitMaterialKind)).toBe(true);
+  });
+
+  it('lists every non-null standard-pbr texture slot and skips null ones', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    registerStandardPbrScene3DMaterialTextures(registry);
+    registerUnlitScene3DMaterialTextures(registry);
+    registerExtendedPbrScene3DMaterialTextures(registry);
+    const baseColorMap = createTexture();
+    const normalMap = createTexture();
+    const material = createStandardPbrMaterial({ baseColorMap, normalMap });
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, material, out);
+    expect(out).toContain(baseColorMap);
+    expect(out).toContain(normalMap);
+    expect(out).toHaveLength(2);
+  });
+
+  it('lists the unlit base-color slot', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    registerStandardPbrScene3DMaterialTextures(registry);
+    registerUnlitScene3DMaterialTextures(registry);
+    registerExtendedPbrScene3DMaterialTextures(registry);
+    const baseColorMap = createTexture();
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, createUnlitMaterial({ baseColorMap }), out);
+    expect(out).toEqual([baseColorMap]);
+  });
+});
+
+describe('registerUnlitScene3DMaterialTextures', () => {
+  it('registers only the Unlit lister, leaving other kinds unlisted', () => {
+    // The point of splitting the built-in bag apart: each door registers exactly the family it names,
+    // so a registry holds what the caller asked for and nothing else.
+    const registry = createScene3DMaterialTextureRegistry();
+    registerUnlitScene3DMaterialTextures(registry);
+    const baseColorMap = createTexture();
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, createUnlitMaterial({ baseColorMap }), out);
+    expect(out).toEqual([baseColorMap]);
+
+    out.length = 0;
+    getScene3DMaterialTextures(registry, createStandardPbrMaterial({ baseColorMap }), out);
+    expect(out).toEqual([]);
+  });
+});

package/src/sceneResourceRecovery.test.ts

@@ -2,8 +2,8 @@ import { createUnlitMaterial } from '@flighthq/materials/contract';
 import { createBoxMeshGeometry } from '@flighthq/mesh/contract';
 import { addNodeChild } from '@flighthq/node/contract';
 import { createMesh, createScene3D } from '@flighthq/scene3d/contract';
-import { createTexture } from '@flighthq/texture/contract';
-import type { ImageResource, ImageResourceReference } from '@flighthq/types/contract';
+import { createTexture, getTextureSource } from '@flighthq/texture/contract';
+import type { Image, ImageResourceReference } from '@flighthq/types/contract';
 import {
   ImageResourceFailureKind,
   ImageResourceReferenceKind,
@@ -11,16 +11,11 @@ import {
 } from '@flighthq/types/contract';
 import { describe, expect, it, vi } from 'vitest';
 
-import { loadScene3DResources } from './resolveScene3DResourcesAndWait';
-import { waitForScene3DResourceResolver } from './resolveScene3DResourcesAndWait';
-import {
-  explainImageResourceReferenceResolution,
-  resetFailedImageResourceReference,
-  retryFailedScene3DResources,
-} from './sceneResourceRecovery';
+import { loadScene3DResources, waitForScene3DResourceResolver } from './loadScene3DResources';
+import { retryFailedScene3DResources } from './sceneResourceRecovery';
 import { createBuiltInScene3DResourceResolver, disposeScene3DResourceResolver } from './sceneResourceResolver';
 
-const fakeImage = { height: 1, width: 1 } as ImageResource;
+const fakeImage = { height: 1, width: 1 } as Image;
 
 function externalRef(state: ResourceResolutionState = ResourceResolutionState.Unresolved): ImageResourceReference {
   return {
@@ -33,58 +28,28 @@ function externalRef(state: ResourceResolutionState = ResourceResolutionState.Un
   };
 }
 
-describe('explainImageResourceReferenceResolution', () => {
-  it('returns detached plain data with retry eligibility and the preserved cause', () => {
-    const ref = externalRef(ResourceResolutionState.Failed);
-    ref.failure = { kind: ImageResourceFailureKind.Error, message: 'decode failed', name: 'CodecError' };
-    const explanation = explainImageResourceReferenceResolution(ref);
-    expect(explanation).toEqual({
-      failure: { kind: ImageResourceFailureKind.Error, message: 'decode failed', name: 'CodecError' },
-      kind: ImageResourceReferenceKind.External,
-      retryable: true,
-      state: ResourceResolutionState.Failed,
-    });
-    expect(explanation.failure).not.toBe(ref.failure);
-  });
-});
-
-describe('resetFailedImageResourceReference', () => {
-  it('clears a failed cause and returns the reference to Unresolved', () => {
-    const ref = externalRef(ResourceResolutionState.Failed);
-    ref.failure = { kind: ImageResourceFailureKind.Unavailable, message: 'missing', name: null };
-    expect(resetFailedImageResourceReference(ref)).toBe(true);
-    expect(ref.state).toBe(ResourceResolutionState.Unresolved);
-    expect(ref.failure).toBeNull();
-  });
-
-  it('does not invalidate a non-failed reference', () => {
-    const ref = externalRef(ResourceResolutionState.Resolved);
-    expect(resetFailedImageResourceReference(ref)).toBe(false);
-    expect(ref.state).toBe(ResourceResolutionState.Resolved);
-  });
-});
-
 describe('retryFailedScene3DResources', () => {
   it('resets one shared failed identity and re-requests it for every subscriber', async () => {
-    const fetch = vi.fn<() => Promise<ImageResource | null>>().mockResolvedValueOnce(null).mockResolvedValue(fakeImage);
+    const fetch = vi.fn<() => Promise<Image | null>>().mockResolvedValueOnce(null).mockResolvedValue(fakeImage);
     const ref = externalRef();
     const a = createTexture({ resource: ref });
     const b = createTexture({ resource: ref });
     const scene = createScene3D();
+    scene.resources.push(ref);
     addNodeChild(scene.root, createMesh(createBoxMeshGeometry(), [createUnlitMaterial({ baseColorMap: a })]));
     addNodeChild(scene.root, createMesh(createBoxMeshGeometry(), [createUnlitMaterial({ baseColorMap: b })]));
     const resolver = createBuiltInScene3DResourceResolver({ fetch });
 
-    await loadScene3DResources(scene.root, resolver);
+    await loadScene3DResources(scene, resolver);
     expect(ref.state).toBe(ResourceResolutionState.Failed);
     expect(ref.failure?.kind).toBe(ImageResourceFailureKind.Unavailable);
 
-    expect(retryFailedScene3DResources(scene.root, resolver)).toBe(1);
+    expect(retryFailedScene3DResources(scene, resolver)).toBe(1);
     await waitForScene3DResourceResolver(resolver);
     expect(fetch).toHaveBeenCalledTimes(2);
     expect(ref.failure).toBeNull();
-    expect(a.storage.image).toBe(fakeImage);
-    expect(b.storage.image).toBe(fakeImage);
+    expect(getTextureSource(a)).toBe(fakeImage);
+    expect(getTextureSource(b)).toBe(fakeImage);
     disposeScene3DResourceResolver(resolver);
   });
 
@@ -93,9 +58,10 @@ describe('retryFailedScene3DResources', () => {
     ref.failure = { kind: ImageResourceFailureKind.Unavailable, message: 'missing', name: null };
     const texture = createTexture({ resource: ref });
     const scene = createScene3D();
+    scene.resources.push(ref);
     addNodeChild(scene.root, createMesh(createBoxMeshGeometry(), [createUnlitMaterial({ baseColorMap: texture })]));
     const resolver = createBuiltInScene3DResourceResolver();
-    expect(retryFailedScene3DResources(scene.root, resolver, { select: () => false })).toBe(0);
+    expect(retryFailedScene3DResources(scene, resolver, { select: () => false })).toBe(0);
     expect(ref.state).toBe(ResourceResolutionState.Failed);
     disposeScene3DResourceResolver(resolver);
   });

package/src/sceneResourceResolver.test.ts

@@ -7,7 +7,11 @@ import {
   UnlitMaterialKind,
 } from '@flighthq/types/contract';
 import { Scene3DResourceResolverRuntimeKey } from '@flighthq/types/contract';
-import type { Scene3DResourceInFlight, Scene3DResourceResolverWithRuntime } from '@flighthq/types/contract';
+import type {
+  ImageResourceReference,
+  Scene3DResourceInFlight,
+  Scene3DResourceResolverWithRuntime,
+} from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
 import { createScene3DMaterialTextureRegistry } from './sceneMaterialTextureRegistry';
@@ -56,22 +60,21 @@ describe('disposeScene3DResourceResolver', () => {
   it('aborts every in-flight controller and clears the map', () => {
     const resolver = createScene3DResourceResolver();
     const controller = new AbortController();
-    const texture = createTexture({
-      resource: {
-        bytes: new Uint8Array(0),
-        failure: null,
-        kind: ImageResourceReferenceKind.Embedded,
-        mimeType: null,
-        state: ResourceResolutionState.Loading,
-      },
-    });
+    const ref = {
+      bytes: new Uint8Array(0),
+      failure: null,
+      kind: ImageResourceReferenceKind.Embedded,
+      mimeType: null,
+      state: ResourceResolutionState.Loading,
+    } as ImageResourceReference;
+    const texture = createTexture({ resource: ref });
     const entry: Scene3DResourceInFlight = {
       controller,
       promise: Promise.resolve(),
       subscribers: new Set([texture]),
     };
     const runtime = (resolver as Scene3DResourceResolverWithRuntime)[Scene3DResourceResolverRuntimeKey];
-    runtime.inFlight.set(texture.resource!, entry);
+    runtime.inFlight.set(ref, entry);
 
     disposeScene3DResourceResolver(resolver);
     expect(controller.signal.aborted).toBe(true);

package/src/sceneResourceResolverTreeShaking.test.ts

@@ -39,7 +39,7 @@ describe('scene resource resolver tree shaking', () => {
 
   it('includes failure logging only through the separately imported guard', async () => {
     const output = await bundleScene3DResourceResolverExport('enableScene3DResourceFailureGuards');
-    expect(output).toContain('image resource resolution failed');
+    expect(output).toContain('Scene3D resource acquisition failed');
   });
 });
 

package/src/shadedScene3DMaterialTextures.test.ts

@@ -0,0 +1,52 @@
+import { createShadedMaterial } from '@flighthq/shading/contract';
+import { createTexture } from '@flighthq/texture/contract';
+import type { Texture } from '@flighthq/types/contract';
+
+import { createScene3DMaterialTextureRegistry, getScene3DMaterialTextures } from './sceneMaterialTextureRegistry';
+import { registerShadedScene3DMaterialTextures } from './shadedScene3DMaterialTextures';
+
+describe('registerShadedScene3DMaterialTextures', () => {
+  it('lists the diffuse, normal and specular maps', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    registerShadedScene3DMaterialTextures(registry);
+    const diffuse = createTexture();
+    const normal = createTexture();
+    const specular = createTexture();
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(
+      registry,
+      createShadedMaterial({ diffuseMap: diffuse, normalMap: normal, specularMap: specular }),
+      out,
+    );
+    expect(out).toEqual([diffuse, normal, specular]);
+  });
+
+  it('skips the empty slots of a map-less material', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    registerShadedScene3DMaterialTextures(registry);
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, createShadedMaterial(), out);
+    expect(out).toEqual([]);
+  });
+
+  it('appends without clearing, so one mesh accumulates across its materials', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    registerShadedScene3DMaterialTextures(registry);
+    const first = createTexture();
+    const second = createTexture();
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, createShadedMaterial({ diffuseMap: first }), out);
+    getScene3DMaterialTextures(registry, createShadedMaterial({ specularMap: second }), out);
+    expect(out).toEqual([first, second]);
+  });
+
+  it('appends nothing for a ShadedMaterial while unregistered', () => {
+    // The registry cannot distinguish this from a material with no maps, which is why callers ask
+    // hasScene3DMaterialTextureLister instead and why getScene3DResourceTextures widens rather than
+    // trusting an empty answer.
+    const registry = createScene3DMaterialTextureRegistry();
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, createShadedMaterial({ diffuseMap: createTexture() }), out);
+    expect(out).toEqual([]);
+  });
+});

package/src/sheenPbrScene3DMaterialTextures.test.ts

@@ -0,0 +1,29 @@
+import { createExtendedPbrMaterial, createSheenPbrExtension } from '@flighthq/materials/contract';
+import { createTexture } from '@flighthq/texture/contract';
+import type { Texture } from '@flighthq/types/contract';
+
+import {
+  createScene3DMaterialTextureRegistry,
+  getScene3DMaterialTextures,
+  registerExtendedPbrScene3DMaterialTextures,
+} from './sceneMaterialTextureRegistry';
+import { registerSheenPbrScene3DMaterialTextures } from './sheenPbrScene3DMaterialTextures';
+
+describe('registerSheenPbrScene3DMaterialTextures', () => {
+  it('lists the sheen color and roughness maps', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    registerExtendedPbrScene3DMaterialTextures(registry);
+    registerSheenPbrScene3DMaterialTextures(registry);
+    const color = createTexture();
+    const roughness = createTexture();
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(
+      registry,
+      createExtendedPbrMaterial({
+        extensions: [createSheenPbrExtension({ sheenColorMap: color, sheenRoughnessMap: roughness })],
+      }),
+      out,
+    );
+    expect(out).toEqual([color, roughness]);
+  });
+});

package/src/specularPbrScene3DMaterialTextures.test.ts

@@ -0,0 +1,29 @@
+import { createExtendedPbrMaterial, createSpecularPbrExtension } from '@flighthq/materials/contract';
+import { createTexture } from '@flighthq/texture/contract';
+import type { Texture } from '@flighthq/types/contract';
+
+import {
+  createScene3DMaterialTextureRegistry,
+  getScene3DMaterialTextures,
+  registerExtendedPbrScene3DMaterialTextures,
+} from './sceneMaterialTextureRegistry';
+import { registerSpecularPbrScene3DMaterialTextures } from './specularPbrScene3DMaterialTextures';
+
+describe('registerSpecularPbrScene3DMaterialTextures', () => {
+  it('lists the specular factor and color maps', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    registerExtendedPbrScene3DMaterialTextures(registry);
+    registerSpecularPbrScene3DMaterialTextures(registry);
+    const factor = createTexture();
+    const color = createTexture();
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(
+      registry,
+      createExtendedPbrMaterial({
+        extensions: [createSpecularPbrExtension({ specularColorMap: color, specularMap: factor })],
+      }),
+      out,
+    );
+    expect(out).toEqual([factor, color]);
+  });
+});

package/src/threeDsLoad.test.ts

@@ -39,8 +39,8 @@ beforeAll(async () => {
 });
 
 afterAll(() => {
-  vi.doUnmock('@flighthq/net');
-  vi.doUnmock('@flighthq/scene3d-formats');
+  vi.doUnmock('@flighthq/net/contract');
+  vi.doUnmock('@flighthq/scene3d-formats/contract');
   vi.resetModules();
 });