@flighthq/scene3d-resources 0.2.1-next.840.857425c

package/src/resolveScene3DResources.test.ts

@@ -0,0 +1,335 @@
+import type * as ImageModule from '@flighthq/image';
+import { createUnlitMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild } from '@flighthq/node';
+import { createMesh, createScene3D } from '@flighthq/scene3d';
+import { connectSignal } from '@flighthq/signals';
+import { createTexture } from '@flighthq/texture';
+import type { ImageResource, ImageResourceReference, Scene3DResourceResolver, Texture } from '@flighthq/types';
+import { ImageResourceFailureKind, ResourceResolutionState, ImageResourceReferenceKind } from '@flighthq/types';
+import type { Mock } from 'vitest';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import type * as ResolveScene3DResourcesModule from './resolveScene3DResources';
+import type * as ResolveScene3DResourcesAndWaitModule from './resolveScene3DResourcesAndWait';
+import type * as Scene3DResourceResolverModule from './sceneResourceResolver';
+import type * as Scene3DResourceSignalsModule from './sceneResourceSignals';
+
+const fakeImage = { height: 2, width: 2 } as unknown as ImageResource;
+type LoadImageResourceFromBytes = typeof ImageModule.loadImageResourceFromBytes;
+
+let createBuiltInScene3DResourceResolver: typeof Scene3DResourceResolverModule.createBuiltInScene3DResourceResolver;
+let disposeScene3DResourceResolver: typeof Scene3DResourceResolverModule.disposeScene3DResourceResolver;
+let enableScene3DResourceSignals: typeof Scene3DResourceSignalsModule.enableScene3DResourceSignals;
+let loadFromBytes: Mock<LoadImageResourceFromBytes>;
+let resolveOneScene3DResourceTexture: typeof ResolveScene3DResourcesModule.resolveOneScene3DResourceTexture;
+let resolveScene3DResources: typeof ResolveScene3DResourcesModule.resolveScene3DResources;
+let waitForScene3DResourceResolver: typeof ResolveScene3DResourcesAndWaitModule.waitForScene3DResourceResolver;
+
+function embeddedRef(mimeType: string | null = 'image/png'): ImageResourceReference {
+  return {
+    bytes: new Uint8Array([9, 9]),
+    failure: null,
+    kind: ImageResourceReferenceKind.Embedded,
+    mimeType,
+    state: ResourceResolutionState.Unresolved,
+  };
+}
+
+function externalRef(uri = 'leaf.png'): ImageResourceReference {
+  return {
+    basePath: null,
+    failure: null,
+    kind: ImageResourceReferenceKind.External,
+    mimeType: null,
+    state: ResourceResolutionState.Unresolved,
+    uri,
+  };
+}
+
+function pendingTexture(): Texture {
+  return createTexture({ resource: embeddedRef() });
+}
+
+function meshScene3D(...textures: Texture[]) {
+  const scene = createScene3D();
+  for (const texture of textures) {
+    addNodeChild(scene.root, createMesh(createBoxMeshGeometry(), [createUnlitMaterial({ baseColorMap: texture })]));
+  }
+  return scene;
+}
+
+async function settle(resolver: Scene3DResourceResolver): Promise<void> {
+  await waitForScene3DResourceResolver(resolver);
+}
+
+beforeAll(async () => {
+  vi.resetModules();
+  loadFromBytes = vi.fn<LoadImageResourceFromBytes>();
+  vi.doMock('@flighthq/image', () => ({
+    loadImageResourceFromBytes: loadFromBytes,
+    loadImageResourceFromUrl: vi.fn(),
+  }));
+  ({ resolveOneScene3DResourceTexture, resolveScene3DResources } = await import('./resolveScene3DResources'));
+  ({ waitForScene3DResourceResolver } = await import('./resolveScene3DResourcesAndWait'));
+  ({ createBuiltInScene3DResourceResolver, disposeScene3DResourceResolver } = await import('./sceneResourceResolver'));
+  ({ enableScene3DResourceSignals } = await import('./sceneResourceSignals'));
+});
+
+afterAll(() => {
+  vi.doUnmock('@flighthq/image');
+  vi.resetModules();
+});
+
+afterEach(() => {
+  loadFromBytes.mockReset();
+});
+
+describe('resolveOneScene3DResourceTexture', () => {
+  it('decodes embedded bytes through @flighthq/image', async () => {
+    loadFromBytes.mockResolvedValue(fakeImage);
+    const resolver = createBuiltInScene3DResourceResolver();
+    const ref = embeddedRef('image/jpeg');
+    const signal = new AbortController().signal;
+    const result = await resolveOneScene3DResourceTexture(resolver, ref, signal);
+    expect(loadFromBytes).toHaveBeenCalledWith((ref as { bytes: Uint8Array }).bytes, 'image/jpeg', signal);
+    expect(result).toBe(fakeImage);
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('passes undefined for a null embedded mimeType', async () => {
+    loadFromBytes.mockResolvedValue(fakeImage);
+    const resolver = createBuiltInScene3DResourceResolver();
+    await resolveOneScene3DResourceTexture(resolver, embeddedRef(null), new AbortController().signal);
+    expect(loadFromBytes).toHaveBeenCalledWith(expect.anything(), undefined, expect.anything());
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('routes external refs through the resolver fetch seam', async () => {
+    const fetch = vi.fn(async () => fakeImage);
+    const resolver = createBuiltInScene3DResourceResolver({ fetch });
+    const ref = externalRef();
+    const signal = new AbortController().signal;
+    const result = await resolveOneScene3DResourceTexture(resolver, ref, signal);
+    expect(fetch).toHaveBeenCalledWith(ref, signal);
+    expect(result).toBe(fakeImage);
+    disposeScene3DResourceResolver(resolver);
+  });
+});
+
+describe('resolveScene3DResources', () => {
+  it('resolves every pending texture, binding the image and advancing state', async () => {
+    loadFromBytes.mockResolvedValue(fakeImage);
+    const a = pendingTexture();
+    const b = pendingTexture();
+    const scene = meshScene3D(a, b);
+    const resolver = createBuiltInScene3DResourceResolver();
+
+    resolveScene3DResources(scene.root, resolver);
+    await settle(resolver);
+
+    expect(a.image).toBe(fakeImage);
+    expect(b.image).toBe(fakeImage);
+    expect(a.resource?.state).toBe(ResourceResolutionState.Resolved);
+    expect(a.resource?.failure).toBeNull();
+    expect(b.resource?.state).toBe(ResourceResolutionState.Resolved);
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('fetches and decodes one shared resource once, then binds every subscribed texture', async () => {
+    loadFromBytes.mockResolvedValue(fakeImage);
+    const ref = embeddedRef();
+    const a = createTexture({ resource: ref });
+    const b = createTexture({ resource: ref });
+    const scene = meshScene3D(a, b);
+    const resolver = createBuiltInScene3DResourceResolver();
+
+    resolveScene3DResources(scene.root, resolver);
+    await settle(resolver);
+
+    expect(loadFromBytes).toHaveBeenCalledTimes(1);
+    expect(a.image).toBe(fakeImage);
+    expect(b.image).toBe(fakeImage);
+    expect(ref.state).toBe(ResourceResolutionState.Resolved);
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('keeps a shared load alive until its final subscriber leaves the working set', async () => {
+    let loadSignal: AbortSignal | undefined;
+    loadFromBytes.mockImplementation(
+      (_bytes, _mime, signal) =>
+        new Promise<ImageResource>((_resolve, reject) => {
+          loadSignal = signal;
+          signal?.addEventListener('abort', () => reject(signal.reason));
+        }),
+    );
+    const ref = embeddedRef();
+    const a = createTexture({ resource: ref });
+    const b = createTexture({ resource: ref });
+    const scene = meshScene3D(a, b);
+    const resolver = createBuiltInScene3DResourceResolver();
+
+    resolveScene3DResources(scene.root, resolver);
+    await vi.waitFor(() => expect(loadSignal).toBeDefined());
+    resolveScene3DResources(scene.root, resolver, { select: (texture) => texture === b });
+    expect(loadSignal?.aborted).toBe(false);
+    expect(ref.state).toBe(ResourceResolutionState.Loading);
+
+    resolveScene3DResources(scene.root, resolver, { select: () => false });
+    expect(loadSignal?.aborted).toBe(true);
+    expect(ref.state).toBe(ResourceResolutionState.Unresolved);
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('binds a later subscriber from the resolved resource cache without decoding again', async () => {
+    loadFromBytes.mockResolvedValue(fakeImage);
+    const ref = embeddedRef();
+    const a = createTexture({ resource: ref });
+    const b = createTexture({ resource: ref });
+    const scene = meshScene3D(a, b);
+    const resolver = createBuiltInScene3DResourceResolver();
+
+    resolveScene3DResources(scene.root, resolver, { select: (texture) => texture === a });
+    await settle(resolver);
+    expect(a.image).toBe(fakeImage);
+    expect(b.image).toBeNull();
+
+    resolveScene3DResources(scene.root, resolver, { select: (texture) => texture === b });
+    expect(b.image).toBe(fakeImage);
+    expect(loadFromBytes).toHaveBeenCalledTimes(1);
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('limits the working set to textures the select predicate accepts', async () => {
+    loadFromBytes.mockResolvedValue(fakeImage);
+    const wanted = pendingTexture();
+    const skipped = pendingTexture();
+    const scene = meshScene3D(wanted, skipped);
+    const resolver = createBuiltInScene3DResourceResolver();
+
+    resolveScene3DResources(scene.root, resolver, { select: (texture) => texture === wanted });
+    await settle(resolver);
+
+    expect(wanted.resource?.state).toBe(ResourceResolutionState.Resolved);
+    expect(skipped.resource?.state).toBe(ResourceResolutionState.Unresolved);
+    expect(skipped.image).toBeNull();
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('fails a texture whose external fetch returns null', async () => {
+    const texture = createTexture({ resource: externalRef() });
+    const scene = meshScene3D(texture);
+    const resolver = createBuiltInScene3DResourceResolver({ fetch: async () => null });
+
+    resolveScene3DResources(scene.root, resolver);
+    await settle(resolver);
+
+    expect(texture.image).toBeNull();
+    expect(texture.resource?.state).toBe(ResourceResolutionState.Failed);
+    expect(texture.resource?.failure).toEqual({
+      kind: ImageResourceFailureKind.Unavailable,
+      message: 'Image resource resolution returned no image',
+      name: null,
+    });
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('fails a texture whose decode throws', async () => {
+    loadFromBytes.mockRejectedValue(new Error('bad image'));
+    const texture = pendingTexture();
+    const scene = meshScene3D(texture);
+    const resolver = createBuiltInScene3DResourceResolver();
+
+    resolveScene3DResources(scene.root, resolver);
+    await settle(resolver);
+
+    expect(texture.resource?.state).toBe(ResourceResolutionState.Failed);
+    expect(texture.resource?.failure).toEqual({
+      kind: ImageResourceFailureKind.Error,
+      message: 'bad image',
+      name: 'Error',
+    });
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('cancels and reverts a load dropped from the working set, then re-requests on re-entry', async () => {
+    const loadSignals: AbortSignal[] = [];
+    // A load that hangs until its signal aborts, so we can drop it mid-flight.
+    loadFromBytes.mockImplementation(
+      (_bytes, _mime, signal) =>
+        new Promise<ImageResource>((_resolve, reject) => {
+          if (signal !== undefined) loadSignals.push(signal);
+          signal?.addEventListener('abort', () => reject(signal.reason));
+        }),
+    );
+    const texture = pendingTexture();
+    const scene = meshScene3D(texture);
+    const resolver = createBuiltInScene3DResourceResolver();
+
+    resolveScene3DResources(scene.root, resolver, { select: () => true });
+    expect(texture.resource?.state).toBe(ResourceResolutionState.Loading);
+    await vi.waitFor(() => expect(loadSignals).toHaveLength(1));
+
+    // Drop it: not in the working set this pass → abort + revert.
+    resolveScene3DResources(scene.root, resolver, { select: () => false });
+    expect(texture.resource?.state).toBe(ResourceResolutionState.Unresolved);
+    expect(texture.image).toBeNull();
+    expect(loadSignals[0].aborted).toBe(true);
+
+    // Re-entry re-requests from scratch.
+    resolveScene3DResources(scene.root, resolver, { select: () => true });
+    expect(texture.resource?.state).toBe(ResourceResolutionState.Loading);
+    await vi.waitFor(() => expect(loadSignals).toHaveLength(2));
+
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('does not re-request a texture already in flight', async () => {
+    loadFromBytes.mockImplementation(() => new Promise<ImageResource>(() => {}));
+    const texture = pendingTexture();
+    const scene = meshScene3D(texture);
+    const resolver = createBuiltInScene3DResourceResolver();
+
+    resolveScene3DResources(scene.root, resolver);
+    await vi.waitFor(() => expect(loadFromBytes).toHaveBeenCalledTimes(1));
+    resolveScene3DResources(scene.root, resolver);
+    expect(loadFromBytes).toHaveBeenCalledTimes(1);
+
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('emits onResourceResolved when signals are enabled', async () => {
+    loadFromBytes.mockResolvedValue(fakeImage);
+    const texture = pendingTexture();
+    const scene = meshScene3D(texture);
+    const resolver = createBuiltInScene3DResourceResolver();
+    const signals = enableScene3DResourceSignals(resolver);
+    const resolved: Texture[] = [];
+    const failed: Texture[] = [];
+    connectSignal(signals.onResourceResolved, (event) => resolved.push(event.texture));
+    connectSignal(signals.onResourceFailed, (event) => failed.push(event.texture));
+
+    resolveScene3DResources(scene.root, resolver);
+    await settle(resolver);
+
+    expect(resolved).toEqual([texture]);
+    expect(failed).toEqual([]);
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('emits onResourceFailed when a decode throws', async () => {
+    loadFromBytes.mockRejectedValue(new Error('bad image'));
+    const texture = pendingTexture();
+    const scene = meshScene3D(texture);
+    const resolver = createBuiltInScene3DResourceResolver();
+    const signals = enableScene3DResourceSignals(resolver);
+    const failed: Texture[] = [];
+    connectSignal(signals.onResourceFailed, (event) => failed.push(event.texture));
+
+    resolveScene3DResources(scene.root, resolver);
+    await settle(resolver);
+
+    expect(failed).toEqual([texture]);
+    disposeScene3DResourceResolver(resolver);
+  });
+});

package/src/resolveScene3DResourcesAndWait.test.ts

@@ -0,0 +1,119 @@
+import { createUnlitMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild } from '@flighthq/node';
+import { createMesh, createScene3D } from '@flighthq/scene3d';
+import { connectSignal, createSignal } from '@flighthq/signals';
+import { createTexture } from '@flighthq/texture';
+import type { ImageResource, ImageResourceReference, Scene3DResourceLoadProgress } from '@flighthq/types';
+import { ResourceResolutionState, ImageResourceReferenceKind } from '@flighthq/types';
+import { describe, expect, it, vi } from 'vitest';
+
+import { loadScene3DResources, waitForScene3DResourceResolver } from './resolveScene3DResourcesAndWait';
+import { createBuiltInScene3DResourceResolver, disposeScene3DResourceResolver } from './sceneResourceResolver';
+
+const fakeImage = { height: 1, width: 1 } as unknown as ImageResource;
+
+function externalRef(): ImageResourceReference {
+  return {
+    basePath: null,
+    failure: null,
+    kind: ImageResourceReferenceKind.External,
+    mimeType: null,
+    state: ResourceResolutionState.Unresolved,
+    uri: 'leaf.png',
+  };
+}
+
+describe('loadScene3DResources', () => {
+  it('awaits every started load so the scene is fully resolved on return', async () => {
+    const fetch = vi.fn(async () => fakeImage);
+    const a = createTexture({ resource: externalRef() });
+    const b = createTexture({ resource: externalRef() });
+    const scene = createScene3D();
+    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);
+
+    expect(a.image).toBe(fakeImage);
+    expect(b.image).toBe(fakeImage);
+    expect(a.resource?.state).toBe(ResourceResolutionState.Resolved);
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('resolves immediately when there is nothing pending', async () => {
+    const scene = createScene3D();
+    const resolver = createBuiltInScene3DResourceResolver({ fetch: async () => fakeImage });
+    await expect(loadScene3DResources(scene.root, resolver)).resolves.toBeUndefined();
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('reports operation-scoped progress as unique references settle', async () => {
+    const a = createTexture({ resource: externalRef() });
+    const b = createTexture({ resource: externalRef() });
+    const scene = createScene3D();
+    addNodeChild(scene.root, createMesh(createBoxMeshGeometry(), [createUnlitMaterial({ baseColorMap: a })]));
+    addNodeChild(scene.root, createMesh(createBoxMeshGeometry(), [createUnlitMaterial({ baseColorMap: b })]));
+    const resolver = createBuiltInScene3DResourceResolver({ fetch: async () => fakeImage });
+    const events: Scene3DResourceLoadProgress[] = [];
+    const progress = createSignal<(event: Readonly<Scene3DResourceLoadProgress>) => void>();
+    connectSignal(progress, (event) => events.push({ ...event }));
+
+    await loadScene3DResources(scene.root, resolver, { progress });
+
+    expect(events[0]).toEqual({ loaded: 0, total: 2 });
+    expect(events.at(-1)).toEqual({ loaded: 2, total: 2 });
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('counts failed references as terminal without hiding their failure state', async () => {
+    const texture = createTexture({ resource: externalRef() });
+    const scene = createScene3D();
+    addNodeChild(scene.root, createMesh(createBoxMeshGeometry(), [createUnlitMaterial({ baseColorMap: texture })]));
+    const resolver = createBuiltInScene3DResourceResolver({ fetch: async () => null });
+    const events: Scene3DResourceLoadProgress[] = [];
+    const progress = createSignal<(event: Readonly<Scene3DResourceLoadProgress>) => void>();
+    connectSignal(progress, (event) => events.push({ ...event }));
+
+    await loadScene3DResources(scene.root, resolver, { progress });
+
+    expect(texture.image).toBeNull();
+    expect(texture.resource?.state).toBe(ResourceResolutionState.Failed);
+    expect(events).toEqual([
+      { loaded: 0, total: 1 },
+      { loaded: 1, total: 1 },
+    ]);
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('waits and reports only the references selected for this operation', async () => {
+    const selected = createTexture({ resource: externalRef() });
+    const deferred = createTexture({ resource: externalRef() });
+    const scene = createScene3D();
+    addNodeChild(scene.root, createMesh(createBoxMeshGeometry(), [createUnlitMaterial({ baseColorMap: selected })]));
+    addNodeChild(scene.root, createMesh(createBoxMeshGeometry(), [createUnlitMaterial({ baseColorMap: deferred })]));
+    const fetch = vi.fn(async () => fakeImage);
+    const resolver = createBuiltInScene3DResourceResolver({ fetch });
+    const events: Scene3DResourceLoadProgress[] = [];
+    const progress = createSignal<(event: Readonly<Scene3DResourceLoadProgress>) => void>();
+    connectSignal(progress, (event) => events.push({ ...event }));
+
+    await loadScene3DResources(scene.root, resolver, { progress, select: (texture) => texture === selected });
+
+    expect(selected.image).toBe(fakeImage);
+    expect(deferred.image).toBeNull();
+    expect(deferred.resource?.state).toBe(ResourceResolutionState.Unresolved);
+    expect(fetch).toHaveBeenCalledOnce();
+    expect(events.at(-1)).toEqual({ loaded: 1, total: 1 });
+    disposeScene3DResourceResolver(resolver);
+  });
+});
+
+describe('waitForScene3DResourceResolver', () => {
+  it('resolves immediately when the resolver has no pending requests', async () => {
+    const resolver = createBuiltInScene3DResourceResolver();
+    await expect(waitForScene3DResourceResolver(resolver)).resolves.toBeUndefined();
+    disposeScene3DResourceResolver(resolver);
+  });
+});

package/src/revealScene3DResourcesOnResolve.test.ts

@@ -0,0 +1,164 @@
+import { createStandardPbrMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild } from '@flighthq/node';
+import { createMesh, createScene3D } from '@flighthq/scene3d';
+import { emitSignal } from '@flighthq/signals';
+import { createTexture } from '@flighthq/texture';
+import { createTweenManager, hasTweensOf, updateTweens } from '@flighthq/tween';
+import type { Scene3D } from '@flighthq/types';
+import type {
+  EmbeddedImageResourceReference,
+  ImageResource,
+  Node3D,
+  Scene3DResourceEvent,
+  Texture,
+} from '@flighthq/types';
+import { ResourceResolutionState } from '@flighthq/types';
+
+import { revealScene3DResourcesOnResolve } from './revealScene3DResourcesOnResolve';
+import { createBuiltInScene3DResourceResolver } from './sceneResourceResolver';
+import { enableScene3DResourceSignals } from './sceneResourceSignals';
+
+function pendingRef(): EmbeddedImageResourceReference {
+  return {
+    bytes: new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+    failure: null,
+    kind: 'Embedded',
+    mimeType: 'image/png',
+    state: ResourceResolutionState.Unresolved,
+  };
+}
+
+function sceneWithPendingTexture(): { mesh: Node3D; scene: Scene3D; texture: Texture } {
+  const texture = createTexture({ resource: pendingRef() });
+  const material = createStandardPbrMaterial({ baseColorMap: texture });
+  const mesh = createMesh(createBoxMeshGeometry(), [material]);
+  const scene = createScene3D();
+  addNodeChild(scene.root, mesh);
+  return { mesh, scene, texture };
+}
+
+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());
+    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 });
+    expect(mesh.alpha).toBeCloseTo(0.2);
+  });
+
+  it('fades the owning object to full opacity as its texture resolves', () => {
+    const { mesh, scene, texture } = sceneWithPendingTexture();
+    const resolver = createBuiltInScene3DResourceResolver();
+    const manager = createTweenManager();
+    revealScene3DResourcesOnResolve(resolver, scene.root, manager, { fadeSeconds: 0.5 });
+    expect(mesh.alpha).toBe(0);
+
+    const signals = enableScene3DResourceSignals(resolver);
+    const event: Scene3DResourceEvent = { ref: texture.resource!, texture };
+    emitSignal(signals.onResourceResolved, event);
+    expect(hasTweensOf(manager, mesh)).toBe(true);
+
+    updateTweens(manager, 0.5);
+    expect(mesh.alpha).toBeCloseTo(1);
+  });
+
+  it('waits for every required texture across a material before revealing its owner', () => {
+    const baseColorMap = createTexture({ resource: pendingRef() });
+    const normalMap = createTexture({ resource: pendingRef() });
+    const material = createStandardPbrMaterial({ baseColorMap, normalMap });
+    const mesh = createMesh(createBoxMeshGeometry(), [material]);
+    const scene = createScene3D();
+    addNodeChild(scene.root, mesh);
+    const resolver = createBuiltInScene3DResourceResolver();
+    const manager = createTweenManager();
+    revealScene3DResourcesOnResolve(resolver, scene.root, manager, { fadeSeconds: 0.5 });
+
+    const signals = enableScene3DResourceSignals(resolver);
+    emitSignal(signals.onResourceResolved, { ref: baseColorMap.resource!, texture: baseColorMap });
+    expect(hasTweensOf(manager, mesh)).toBe(false);
+
+    emitSignal(signals.onResourceResolved, { ref: normalMap.resource!, texture: normalMap });
+    expect(hasTweensOf(manager, mesh)).toBe(true);
+  });
+
+  it('treats failure as settled and reveals the fallback only after the remaining resources settle', () => {
+    const baseColorMap = createTexture({ resource: pendingRef() });
+    const normalMap = createTexture({ resource: pendingRef() });
+    const material = createStandardPbrMaterial({ baseColorMap, normalMap });
+    const mesh = createMesh(createBoxMeshGeometry(), [material]);
+    const scene = createScene3D();
+    addNodeChild(scene.root, mesh);
+    const resolver = createBuiltInScene3DResourceResolver();
+    const manager = createTweenManager();
+    revealScene3DResourcesOnResolve(resolver, scene.root, manager, { fadeSeconds: 0.5 });
+
+    const signals = enableScene3DResourceSignals(resolver);
+    emitSignal(signals.onResourceFailed, { ref: normalMap.resource!, texture: normalMap });
+    expect(hasTweensOf(manager, mesh)).toBe(false);
+
+    emitSignal(signals.onResourceResolved, { ref: baseColorMap.resource!, 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({
+      image: { height: 1, width: 1 } as ImageResource,
+      resource: pendingRef(),
+    });
+    const failedRef = pendingRef();
+    failedRef.state = ResourceResolutionState.Failed;
+    const failed = createTexture({ resource: failedRef });
+    const material = createStandardPbrMaterial({ baseColorMap: bound, normalMap: failed });
+    const mesh = createMesh(createBoxMeshGeometry(), [material]);
+    const scene = createScene3D();
+    addNodeChild(scene.root, mesh);
+
+    revealScene3DResourcesOnResolve(createBuiltInScene3DResourceResolver(), scene.root, createTweenManager());
+    expect(mesh.alpha).toBe(1);
+  });
+
+  it('reveals every owner of one shared texture when that texture settles', () => {
+    const texture = createTexture({ resource: pendingRef() });
+    const a = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial({ baseColorMap: texture })]);
+    const b = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial({ baseColorMap: texture })]);
+    const scene = createScene3D();
+    addNodeChild(scene.root, a);
+    addNodeChild(scene.root, b);
+    const resolver = createBuiltInScene3DResourceResolver();
+    const manager = createTweenManager();
+    revealScene3DResourcesOnResolve(resolver, scene.root, manager);
+
+    emitSignal(enableScene3DResourceSignals(resolver).onResourceResolved, { ref: texture.resource!, texture });
+    expect(hasTweensOf(manager, a)).toBe(true);
+    expect(hasTweensOf(manager, b)).toBe(true);
+  });
+
+  it('ignores a resolve event for a texture it is not tracking', () => {
+    const { scene } = sceneWithPendingTexture();
+    const resolver = createBuiltInScene3DResourceResolver();
+    const manager = createTweenManager();
+    revealScene3DResourcesOnResolve(resolver, scene.root, manager, { fadeSeconds: 0.5 });
+
+    const stray = createTexture({ resource: pendingRef() });
+    emitSignal(enableScene3DResourceSignals(resolver).onResourceResolved, { ref: stray.resource!, texture: stray });
+    expect(hasTweensOf(manager, stray as unknown as object)).toBe(false);
+  });
+
+  it('disconnects the listener when the returned disposer runs', () => {
+    const { mesh, scene, texture } = sceneWithPendingTexture();
+    const resolver = createBuiltInScene3DResourceResolver();
+    const manager = createTweenManager();
+    const dispose = revealScene3DResourcesOnResolve(resolver, scene.root, manager, { fadeSeconds: 0.5 });
+    dispose();
+
+    emitSignal(enableScene3DResourceSignals(resolver).onResourceResolved, { ref: texture.resource!, texture });
+    expect(hasTweensOf(manager, mesh)).toBe(false);
+  });
+});