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

package/src/sceneDocumentSource.test.ts

@@ -0,0 +1,116 @@
+import { setNetBackend } from '@flighthq/net';
+import { connectSignal, createSignal, emitSignal } from '@flighthq/signals';
+import type { NetResponse, Scene3DDocument, Scene3DDocumentLoadProgress } from '@flighthq/types';
+import { ImageResourceReferenceKind, ResourceResolutionState } from '@flighthq/types';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  getScene3DDocumentBasePathFromUrl,
+  loadScene3DDocumentBytesFromUrl,
+  loadScene3DDocumentTextFromUrl,
+  setScene3DDocumentResourceBasePathFromUrl,
+} from './sceneDocumentSource';
+
+function okResponse(body: string | ArrayBuffer): NetResponse {
+  return { body, headers: {}, ok: true, status: 200, statusText: 'OK', url: 'u' };
+}
+
+function failResponse(): NetResponse {
+  return { body: null, headers: {}, ok: false, status: 404, statusText: 'Not Found', url: 'u' };
+}
+
+afterEach(() => {
+  setNetBackend(null);
+});
+
+describe('getScene3DDocumentBasePathFromUrl', () => {
+  it('returns the containing path without query or fragment data', () => {
+    expect(getScene3DDocumentBasePathFromUrl('models/ship.gltf?cache=1')).toBe('models');
+    expect(getScene3DDocumentBasePathFromUrl('ship.gltf')).toBeNull();
+  });
+});
+
+describe('loadScene3DDocumentBytesFromUrl', () => {
+  it('forwards cancellation and identifies byte-progress events by URL', async () => {
+    const controller = new AbortController();
+    const events: Scene3DDocumentLoadProgress[] = [];
+    const progress = createSignal<(event: Readonly<Scene3DDocumentLoadProgress>) => void>();
+    connectSignal(progress, (event) => events.push({ ...event }));
+    setNetBackend({
+      sendNetRequest: async (_request, options) => {
+        expect(options?.signal).toBe(controller.signal);
+        emitSignal(options!.progress!, { loaded: 2, phase: 'download', total: 3 });
+        return okResponse(new Uint8Array([1, 2, 3]).buffer);
+      },
+    });
+
+    const bytes = await loadScene3DDocumentBytesFromUrl('model.bin', { progress, signal: controller.signal });
+
+    expect(Array.from(bytes!)).toEqual([1, 2, 3]);
+    expect(events).toEqual([{ loaded: 2, phase: 'download', total: 3, url: 'model.bin' }]);
+  });
+
+  it('returns null on an expected transport failure', async () => {
+    setNetBackend({ sendNetRequest: async () => failResponse() });
+    await expect(loadScene3DDocumentBytesFromUrl('missing.bin')).resolves.toBeNull();
+  });
+});
+
+describe('loadScene3DDocumentTextFromUrl', () => {
+  it('fetches the URL as text and returns the string', async () => {
+    let requestedType: string | undefined;
+    setNetBackend({
+      sendNetRequest: async (request) => {
+        requestedType = request.responseType;
+        return okResponse('v 0 0 0');
+      },
+    });
+
+    await expect(loadScene3DDocumentTextFromUrl('model.obj')).resolves.toBe('v 0 0 0');
+    expect(requestedType).toBe('text');
+  });
+
+  it('returns null on an expected transport failure', async () => {
+    setNetBackend({ sendNetRequest: async () => failResponse() });
+    await expect(loadScene3DDocumentTextFromUrl('missing.obj')).resolves.toBeNull();
+  });
+});
+
+describe('setScene3DDocumentResourceBasePathFromUrl', () => {
+  it('sets only unresolved relative resources whose parser did not already supply a base path', () => {
+    const document = {
+      animations: [],
+      cameras: [],
+      lights: [],
+      materials: [],
+      meshes: [],
+      metadata: null,
+      nodes: [],
+      scenes: [],
+      skins: [],
+      resources: [
+        {
+          basePath: null,
+          failure: null,
+          kind: ImageResourceReferenceKind.External,
+          mimeType: null,
+          state: ResourceResolutionState.Unresolved,
+          uri: 'skin.png',
+        },
+        {
+          basePath: 'authored',
+          failure: null,
+          kind: ImageResourceReferenceKind.External,
+          mimeType: null,
+          state: ResourceResolutionState.Unresolved,
+          uri: 'fixed.png',
+        },
+      ],
+    } satisfies Scene3DDocument;
+
+    setScene3DDocumentResourceBasePathFromUrl(document, 'models/ship.obj');
+
+    expect(document.resources[0].basePath).toBe('models');
+    expect(document.resources[1].basePath).toBe('authored');
+  });
+});

package/src/sceneMaterialTextureRegistry.test.ts

@@ -0,0 +1,95 @@
+import { createStandardPbrMaterial, createUnlitMaterial } from '@flighthq/materials';
+import { createTexture } from '@flighthq/texture';
+import type { Material, Texture } from '@flighthq/types';
+import { EntityRuntimeKey, StandardPbrMaterialKind, UnlitMaterialKind } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import {
+  createScene3DMaterialTextureRegistry,
+  getScene3DMaterialTextures,
+  registerBuiltInScene3DMaterialTextures,
+  registerScene3DMaterialTextures,
+} from './sceneMaterialTextureRegistry';
+
+describe('createScene3DMaterialTextureRegistry', () => {
+  it('creates an empty registry', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    expect(EntityRuntimeKey in registry).toBe(true);
+    expect(registry.listers.size).toBe(0);
+  });
+});
+
+describe('getScene3DMaterialTextures', () => {
+  it('appends nothing for an unregistered kind', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, createUnlitMaterial(), out);
+    expect(out).toHaveLength(0);
+  });
+
+  it('accumulates across calls without clearing out', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    registerBuiltInScene3DMaterialTextures(registry);
+    const a = createTexture();
+    const b = createTexture();
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, createUnlitMaterial({ baseColorMap: a }), out);
+    getScene3DMaterialTextures(registry, createUnlitMaterial({ baseColorMap: b }), out);
+    expect(out).toEqual([a, b]);
+  });
+});
+
+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', () => {
+    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);
+  });
+
+  it('lists the unlit base-color slot', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    registerBuiltInScene3DMaterialTextures(registry);
+    const baseColorMap = createTexture();
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, createUnlitMaterial({ baseColorMap }), out);
+    expect(out).toEqual([baseColorMap]);
+  });
+});
+
+describe('registerScene3DMaterialTextures', () => {
+  it('binds a lister for a custom kind', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    const custom = createTexture();
+    registerScene3DMaterialTextures(registry, 'acme.Custom', (_material: Readonly<Material>, out: Texture[]) => {
+      out.push(custom);
+    });
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, { kind: 'acme.Custom' } as unknown as Material, out);
+    expect(out).toEqual([custom]);
+  });
+
+  it('is last-write-wins with no guard', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    const first = createTexture();
+    const second = createTexture();
+    registerScene3DMaterialTextures(registry, UnlitMaterialKind, (_m, out) => out.push(first));
+    registerScene3DMaterialTextures(registry, UnlitMaterialKind, (_m, out) => out.push(second));
+    const out: Texture[] = [];
+    getScene3DMaterialTextures(registry, createUnlitMaterial(), out);
+    expect(out).toEqual([second]);
+  });
+});

package/src/sceneResourceRecovery.test.ts

@@ -0,0 +1,98 @@
+import { createUnlitMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild } from '@flighthq/node';
+import { createMesh, createScene3D } from '@flighthq/scene3d';
+import { createTexture } from '@flighthq/texture';
+import type { ImageResource, ImageResourceReference } from '@flighthq/types';
+import { ImageResourceFailureKind, ImageResourceReferenceKind, ResourceResolutionState } from '@flighthq/types';
+import { describe, expect, it, vi } from 'vitest';
+
+import { loadScene3DResources } from './resolveScene3DResourcesAndWait';
+import { waitForScene3DResourceResolver } from './resolveScene3DResourcesAndWait';
+import {
+  explainImageResourceReferenceResolution,
+  resetFailedImageResourceReference,
+  retryFailedScene3DResources,
+} from './sceneResourceRecovery';
+import { createBuiltInScene3DResourceResolver, disposeScene3DResourceResolver } from './sceneResourceResolver';
+
+const fakeImage = { height: 1, width: 1 } as ImageResource;
+
+function externalRef(state: ResourceResolutionState = ResourceResolutionState.Unresolved): ImageResourceReference {
+  return {
+    basePath: null,
+    failure: null,
+    kind: ImageResourceReferenceKind.External,
+    mimeType: null,
+    state,
+    uri: 'leaf.png',
+  };
+}
+
+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 ref = externalRef();
+    const a = createTexture({ resource: ref });
+    const b = createTexture({ resource: ref });
+    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(ref.state).toBe(ResourceResolutionState.Failed);
+    expect(ref.failure?.kind).toBe(ImageResourceFailureKind.Unavailable);
+
+    expect(retryFailedScene3DResources(scene.root, resolver)).toBe(1);
+    await waitForScene3DResourceResolver(resolver);
+    expect(fetch).toHaveBeenCalledTimes(2);
+    expect(ref.failure).toBeNull();
+    expect(a.image).toBe(fakeImage);
+    expect(b.image).toBe(fakeImage);
+    disposeScene3DResourceResolver(resolver);
+  });
+
+  it('honors selection and leaves an excluded failure untouched', () => {
+    const ref = externalRef(ResourceResolutionState.Failed);
+    ref.failure = { kind: ImageResourceFailureKind.Unavailable, message: 'missing', name: null };
+    const texture = createTexture({ resource: ref });
+    const scene = createScene3D();
+    addNodeChild(scene.root, createMesh(createBoxMeshGeometry(), [createUnlitMaterial({ baseColorMap: texture })]));
+    const resolver = createBuiltInScene3DResourceResolver();
+    expect(retryFailedScene3DResources(scene.root, resolver, { select: () => false })).toBe(0);
+    expect(ref.state).toBe(ResourceResolutionState.Failed);
+    disposeScene3DResourceResolver(resolver);
+  });
+});

package/src/sceneResourceResolver.test.ts

@@ -0,0 +1,80 @@
+import { createTexture } from '@flighthq/texture';
+import {
+  ResourceResolutionState,
+  EntityRuntimeKey,
+  ImageResourceReferenceKind,
+  StandardPbrMaterialKind,
+  UnlitMaterialKind,
+} from '@flighthq/types';
+import { Scene3DResourceResolverRuntimeKey } from '@flighthq/types';
+import type { Scene3DResourceInFlight, Scene3DResourceResolverWithRuntime } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createScene3DMaterialTextureRegistry } from './sceneMaterialTextureRegistry';
+import {
+  createBuiltInScene3DResourceResolver,
+  createScene3DResourceResolver,
+  disposeScene3DResourceResolver,
+} from './sceneResourceResolver';
+
+describe('createBuiltInScene3DResourceResolver', () => {
+  it('assembles Standard PBR and Unlit discovery only through the explicit built-in constructor', () => {
+    const resolver = createBuiltInScene3DResourceResolver();
+    expect(resolver.registry.listers.has(StandardPbrMaterialKind)).toBe(true);
+    expect(resolver.registry.listers.has(UnlitMaterialKind)).toBe(true);
+    disposeScene3DResourceResolver(resolver);
+  });
+});
+
+describe('createScene3DResourceResolver', () => {
+  it('creates an Entity with an empty registry and private runtime machinery', () => {
+    const resolver = createScene3DResourceResolver();
+    const runtime = (resolver as Scene3DResourceResolverWithRuntime)[Scene3DResourceResolverRuntimeKey];
+    expect(EntityRuntimeKey in resolver).toBe(true);
+    expect(resolver.registry.listers.size).toBe(0);
+    expect(typeof resolver.fetch).toBe('function');
+    expect(runtime.inFlight.size).toBe(0);
+    expect(runtime.signals).toBeNull();
+    expect(runtime.loader).toBeDefined();
+    disposeScene3DResourceResolver(resolver);
+  });
+});
+
+describe('createScene3DResourceResolver options', () => {
+  it('uses a caller-supplied registry and fetch wholesale', () => {
+    const registry = createScene3DMaterialTextureRegistry();
+    const fetch = async () => null;
+    const resolver = createScene3DResourceResolver({ fetch, registry });
+    expect(resolver.registry).toBe(registry);
+    expect(resolver.registry.listers.has(UnlitMaterialKind)).toBe(false);
+    expect(resolver.fetch).toBe(fetch);
+    disposeScene3DResourceResolver(resolver);
+  });
+});
+
+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 entry: Scene3DResourceInFlight = {
+      controller,
+      promise: Promise.resolve(),
+      subscribers: new Set([texture]),
+    };
+    const runtime = (resolver as Scene3DResourceResolverWithRuntime)[Scene3DResourceResolverRuntimeKey];
+    runtime.inFlight.set(texture.resource!, entry);
+
+    disposeScene3DResourceResolver(resolver);
+    expect(controller.signal.aborted).toBe(true);
+    expect(runtime.inFlight.size).toBe(0);
+  });
+});

package/src/sceneResourceResolverTreeShaking.test.ts

@@ -0,0 +1,51 @@
+// @vitest-environment node
+
+import { build } from 'esbuild';
+import { describe, expect, it } from 'vitest';
+
+const resolveDir = getFileUrlDirectory(import.meta.url);
+
+async function bundleScene3DResourceResolverExport(name: string): Promise<string> {
+  const result = await build({
+    bundle: true,
+    format: 'esm',
+    logLevel: 'silent',
+    minify: true,
+    packages: 'external',
+    stdin: {
+      contents: `export { ${name} } from './index.ts';`,
+      resolveDir,
+      sourcefile: `tree-shake-${name}.ts`,
+    },
+    treeShaking: true,
+    write: false,
+  });
+  return result.outputFiles[0].text;
+}
+
+describe('scene resource resolver tree shaking', () => {
+  it('keeps the primitive resolver independent of built-in material listers', async () => {
+    const output = await bundleScene3DResourceResolverExport('createScene3DResourceResolver');
+    expect(output).not.toContain('StandardPbrMaterial');
+    expect(output).not.toContain('UnlitMaterial');
+    expect(output).not.toContain('image resource resolution failed');
+  });
+
+  it('includes built-in material listers only through the named assembly', async () => {
+    const output = await bundleScene3DResourceResolverExport('createBuiltInScene3DResourceResolver');
+    expect(output).toContain('StandardPbrMaterial');
+    expect(output).toContain('UnlitMaterial');
+  });
+
+  it('includes failure logging only through the separately imported guard', async () => {
+    const output = await bundleScene3DResourceResolverExport('enableScene3DResourceFailureGuards');
+    expect(output).toContain('image resource resolution failed');
+  });
+});
+
+function getFileUrlDirectory(url: string): string {
+  const directory = new URL('.', url);
+  const pathname = decodeURIComponent(directory.pathname);
+  if (directory.hostname !== '') return `//${directory.hostname}${pathname}`;
+  return /^\/[A-Za-z]:\//.test(pathname) ? pathname.slice(1) : pathname;
+}

package/src/sceneResourceSignals.test.ts

@@ -0,0 +1,51 @@
+import { connectSignal, emitSignal } from '@flighthq/signals';
+import type { ImageResourceReference, Texture } from '@flighthq/types';
+import { EntityRuntimeKey, ResourceResolutionState, ImageResourceReferenceKind } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createScene3DResourceResolver, disposeScene3DResourceResolver } from './sceneResourceResolver';
+import {
+  createScene3DResourceSignals,
+  enableScene3DResourceSignals,
+  getScene3DResourceSignals,
+} from './sceneResourceSignals';
+
+const ref: ImageResourceReference = {
+  bytes: new Uint8Array(),
+  failure: null,
+  kind: ImageResourceReferenceKind.Embedded,
+  mimeType: null,
+  state: ResourceResolutionState.Resolved,
+};
+
+describe('createScene3DResourceSignals', () => {
+  it('creates a connectable, emittable signal group', () => {
+    const signals = createScene3DResourceSignals();
+    expect(EntityRuntimeKey in signals).toBe(true);
+    let received = 0;
+    connectSignal(signals.onResourceResolved, () => received++);
+    emitSignal(signals.onResourceResolved, { ref, texture: {} as Texture });
+    expect(received).toBe(1);
+  });
+});
+
+describe('enableScene3DResourceSignals', () => {
+  it('stores the group on the resolver and is idempotent', () => {
+    const resolver = createScene3DResourceResolver();
+    const first = enableScene3DResourceSignals(resolver);
+    const second = enableScene3DResourceSignals(resolver);
+    expect(first).toBe(second);
+    expect(getScene3DResourceSignals(resolver)).toBe(first);
+    disposeScene3DResourceResolver(resolver);
+  });
+});
+
+describe('getScene3DResourceSignals', () => {
+  it('returns null until enabled, then the enabled group', () => {
+    const resolver = createScene3DResourceResolver();
+    expect(getScene3DResourceSignals(resolver)).toBeNull();
+    const signals = enableScene3DResourceSignals(resolver);
+    expect(getScene3DResourceSignals(resolver)).toBe(signals);
+    disposeScene3DResourceResolver(resolver);
+  });
+});

package/src/threeDsLoad.test.ts

@@ -0,0 +1,63 @@
+import type * as NetModule from '@flighthq/net';
+import type * as Scene3DFormatsModule from '@flighthq/scene3d-formats';
+import type { NetResponse, Scene3DDocument } from '@flighthq/types';
+import type { Mock } from 'vitest';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import type * as Load3dsModule from './threeDsLoad';
+
+let loadScene3DDocumentFrom3dsUrl: typeof Load3dsModule.loadScene3DDocumentFrom3dsUrl;
+let parse3ds: Mock<typeof Scene3DFormatsModule.parse3ds>;
+let sendNetRequest: Mock<typeof NetModule.sendNetRequest>;
+
+function emptyDocument(): Scene3DDocument {
+  return {
+    animations: [],
+    cameras: [],
+    lights: [],
+    materials: [],
+    meshes: [],
+    metadata: null,
+    nodes: [],
+    resources: [],
+    scenes: [],
+    skins: [],
+  };
+}
+
+function okResponse(body: ArrayBuffer): NetResponse {
+  return { body, headers: {}, ok: true, status: 200, statusText: 'OK', url: 'u' };
+}
+
+beforeAll(async () => {
+  vi.resetModules();
+  parse3ds = vi.fn<typeof Scene3DFormatsModule.parse3ds>();
+  sendNetRequest = vi.fn<typeof NetModule.sendNetRequest>();
+  vi.doMock('@flighthq/net', () => ({ sendNetRequest }));
+  vi.doMock('@flighthq/scene3d-formats', () => ({ parse3ds }));
+  ({ loadScene3DDocumentFrom3dsUrl } = await import('./threeDsLoad'));
+});
+
+afterAll(() => {
+  vi.doUnmock('@flighthq/net');
+  vi.doUnmock('@flighthq/scene3d-formats');
+  vi.resetModules();
+});
+
+afterEach(() => {
+  parse3ds.mockReset();
+  sendNetRequest.mockReset();
+});
+
+describe('loadScene3DDocumentFrom3dsUrl', () => {
+  it('fetches bytes and returns the parsed CPU document without resolving resources', async () => {
+    const document = emptyDocument();
+    parse3ds.mockReturnValue(document);
+    sendNetRequest.mockResolvedValue(okResponse(new Uint8Array([9, 8]).buffer));
+
+    const loaded = await loadScene3DDocumentFrom3dsUrl('model.3ds');
+
+    expect(Array.from(parse3ds.mock.calls[0][0])).toEqual([9, 8]);
+    expect(loaded).toBe(document);
+  });
+});