@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/derive-render-data-skin.unit.test.ts

@@ -0,0 +1,90 @@
+// derive-render-data-skin.unit.test.ts -- geometry-owned projection contract.
+// The render projection must preserve every authored attribute in canonical
+// order, including skin streams, without a parallel stride discriminator.
+
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import type { MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { deriveRenderDataMesh } from '../../../render/src/render-data';
+
+function canonicalAttributes(vertexCount: number): MeshAsset['attributes'] {
+  return {
+    position: new Float32Array(vertexCount * 3),
+    normal: new Float32Array(vertexCount * 3),
+    uv: new Float32Array(vertexCount * 2),
+    tangent: new Float32Array(vertexCount * 4),
+  };
+}
+
+function meshWithoutSkin(): MeshAsset {
+  return {
+    kind: 'mesh',
+    vertices: new Float32Array(4 * 12),
+    indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
+    attributes: canonicalAttributes(4),
+    aabb: new Float32Array(6),
+    submeshes: [
+      { indexOffset: 0, indexCount: 6, vertexCount: 4, topology: 'triangle-list', materialSlot: 0 },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  };
+}
+
+function meshWithSkin(): MeshAsset {
+  const attributes = canonicalAttributes(4);
+  attributes.skinIndex = new Uint16Array(4 * 4);
+  attributes.skinWeight = new Float32Array(4 * 4);
+  return {
+    kind: 'mesh',
+    vertices: new Float32Array(4 * 18),
+    indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
+    attributes,
+    aabb: new Float32Array(6),
+    submeshes: [
+      { indexOffset: 0, indexCount: 6, vertexCount: 4, topology: 'triangle-list', materialSlot: 0 },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  };
+}
+
+describe('deriveRenderDataMesh geometry-owned projection', () => {
+  it('preserves the canonical projection for a mesh with skin streams', () => {
+    const mesh = meshWithSkin();
+    const res = deriveRenderDataMesh(mesh);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.value.layoutProjection).toEqual(deriveVertexLayoutProjection(mesh.attributes));
+    expect(res.value.layoutProjection.arrayStride).toBe(72);
+  });
+
+  it('preserves the canonical projection for a mesh without skin streams', () => {
+    const mesh = meshWithoutSkin();
+    const res = deriveRenderDataMesh(mesh);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.value.layoutProjection).toEqual(deriveVertexLayoutProjection(mesh.attributes));
+    expect(res.value.layoutProjection.arrayStride).toBe(48);
+  });
+
+  it('keeps a skinWeight-only authored map visible in the projection', () => {
+    const mesh: MeshAsset = {
+      ...meshWithoutSkin(),
+      attributes: {
+        ...canonicalAttributes(4),
+        skinWeight: new Float32Array(16),
+      },
+    };
+    const res = deriveRenderDataMesh(mesh);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.value.layoutProjection.attributes.map((attribute) => attribute.key)).toEqual([
+      'position',
+      'normal',
+      'uv',
+      'tangent',
+      'skinWeight',
+    ]);
+  });
+});

package/src/__tests__/draw-published.ts

@@ -0,0 +1,17 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { FrameReceipt, RenderError, Renderer, RenderResult } from '@forgeax/engine-render';
+
+/** Drive the production attach -> update -> draw contract in direct-render tests. */
+export function drawPublished(
+  renderer: Renderer,
+  world: World,
+): RenderResult<FrameReceipt, RenderError> {
+  const attached = renderer.attach(world);
+  if (!attached.ok) throw attached.error;
+  world.update(1 / 60).unwrap();
+  return renderer.draw({
+    leases: [attached.value],
+    camera: { lease: attached.value },
+    environment: { lease: attached.value },
+  });
+}

package/src/__tests__/dynamic-texture-store.unit.test.ts

@@ -0,0 +1,190 @@
+// feat-20260623-world-space-video-asset M4 / w15 — DynamicTextureStore unit.
+//
+// D-3 / AC-08: the transient video texture path is fully independent of
+// GpuResidencyCache.ensureResident (the static "upload once / cache forever"
+// cache). This test pins the three load-bearing properties:
+//   1. isolation — the module does NOT import GpuResidencyCache (source scan).
+//   2. allocate-once — a steady-size clip creates exactly one GPU texture; each
+//      subsequent frame is a copyExternalImageToTexture write, not a new create.
+//   3. resize-on-change — a dimension change destroys the old texture and
+//      allocates a new one (so a clip whose intrinsic size resolves late still
+//      renders correctly).
+// Plus the structured-failure contract (charter P3): a device that rejects the
+// copy returns a Result.err, never throws.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { type DynamicTextureDevice, DynamicTextureStore } from '@forgeax/engine-assets-runtime';
+import type { Result, Texture, TextureView } from '@forgeax/engine-rhi';
+import { err, ok, RhiError } from '@forgeax/engine-rhi';
+import type { Handle } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+const STORE_SRC = fileURLToPath(
+  new URL('../../../assets-runtime/src/dynamic-texture-store.ts', import.meta.url),
+);
+
+interface DeviceProbe {
+  created: number;
+  destroyed: number;
+  copies: number;
+}
+
+function makeMockDevice(
+  probe: DeviceProbe,
+  opts: { copyFails?: boolean } = {},
+): DynamicTextureDevice {
+  let nextTex = 0;
+  return {
+    createTexture: (): Result<Texture, RhiError> => {
+      probe.created += 1;
+      return ok({ __tex: `tex-${++nextTex}` } as unknown as Texture);
+    },
+    createTextureView: (tex: Texture): Result<TextureView, RhiError> =>
+      ok({ __view: tex } as unknown as TextureView),
+    destroyTexture: (): Result<void, RhiError> => {
+      probe.destroyed += 1;
+      return ok(undefined);
+    },
+    queue: {
+      copyExternalImageToTexture: (): Result<void, RhiError> => {
+        probe.copies += 1;
+        if (opts.copyFails === true) {
+          return err(
+            new RhiError({
+              code: 'webgpu-runtime-error',
+              expected: 'copyExternalImageToTexture succeeds',
+              hint: 'video source not yet decodable',
+            }),
+          );
+        }
+        return ok(undefined);
+      },
+    },
+  };
+}
+
+const FAKE_SOURCE = {} as unknown as GPUCopyExternalImageSourceInfo['source'];
+
+function clip(id: number): Handle<'VideoAsset', 'shared'> {
+  return toShared<'VideoAsset'>(id);
+}
+
+describe('DynamicTextureStore isolation (M4 / w15)', () => {
+  it('does NOT import GpuResidencyCache (AC-08 / D-3 independence)', () => {
+    const src = readFileSync(STORE_SRC, 'utf8');
+    // Scan import statements only — the file's prose comments reference the
+    // store/ensureResident to explain WHY they are kept separate (D-3); the
+    // load-bearing invariant is the absence of an actual import edge.
+    const importLines = src.split('\n').filter((l) => /^\s*import\b/.test(l));
+    for (const line of importLines) {
+      expect(line.includes('device/gpu-residency'), `unexpected import: ${line}`).toBe(false);
+    }
+    // No call to the static residency cache method anywhere in executable code
+    // (strip comments first so the explanatory prose does not trip the gate).
+    const stripped = src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+    expect(stripped.includes('ensureResident')).toBe(false);
+  });
+});
+
+describe('DynamicTextureStore lifecycle (M4 / w15)', () => {
+  it('allocate-once: a steady-size clip creates one texture, writes every frame', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe));
+    const h = clip(701);
+
+    for (let frame = 0; frame < 5; frame++) {
+      const res = store.uploadFrame(h, FAKE_SOURCE, 320, 240);
+      expect(res?.ok).toBe(true);
+    }
+    expect(probe.created).toBe(1);
+    expect(probe.copies).toBe(5);
+    expect(probe.destroyed).toBe(0);
+    expect(store.getView(h)).toBeDefined();
+  });
+
+  it('resize-on-change: a dimension change destroys the old texture + allocates a new one', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe));
+    const h = clip(702);
+
+    expect(store.uploadFrame(h, FAKE_SOURCE, 320, 240)?.ok).toBe(true);
+    expect(store.uploadFrame(h, FAKE_SOURCE, 320, 240)?.ok).toBe(true);
+    expect(probe.created).toBe(1);
+
+    // Intrinsic size resolved (e.g. metadata loaded) -> new dimensions.
+    expect(store.uploadFrame(h, FAKE_SOURCE, 640, 480)?.ok).toBe(true);
+    expect(probe.created).toBe(2);
+    expect(probe.destroyed).toBe(1);
+  });
+
+  it('two clips get independent transient textures', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe));
+
+    expect(store.uploadFrame(clip(710), FAKE_SOURCE, 100, 100)?.ok).toBe(true);
+    expect(store.uploadFrame(clip(711), FAKE_SOURCE, 100, 100)?.ok).toBe(true);
+    expect(probe.created).toBe(2);
+    expect(store.getView(clip(710))).not.toBe(store.getView(clip(711)));
+  });
+
+  it('device swap destroys stale entries before reusing a clip', () => {
+    const first: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const second: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    const h = clip(740);
+
+    store.configureGpuDevice(makeMockDevice(first));
+    expect(store.uploadFrame(h, FAKE_SOURCE, 320, 240)?.ok).toBe(true);
+
+    store.configureGpuDevice(makeMockDevice(second));
+    expect(first.destroyed).toBe(1);
+    expect(store.getView(h)).toBeUndefined();
+
+    expect(store.uploadFrame(h, FAKE_SOURCE, 320, 240)?.ok).toBe(true);
+    expect(second.created).toBe(1);
+    expect(second.copies).toBe(1);
+  });
+});
+
+describe('DynamicTextureStore degrade paths (M4 / w15, charter P3)', () => {
+  it('returns undefined (not an error) before a device is wired', () => {
+    const store = new DynamicTextureStore();
+    expect(store.uploadFrame(clip(720), FAKE_SOURCE, 320, 240)).toBeUndefined();
+    expect(store.getView(clip(720))).toBeUndefined();
+  });
+
+  it('returns undefined for zero / unknown source dimensions (metadata pending)', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe));
+    expect(store.uploadFrame(clip(721), FAKE_SOURCE, 0, 0)).toBeUndefined();
+    expect(probe.created).toBe(0);
+  });
+
+  it('returns a structured RhiError when the copy fails (never throws)', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe, { copyFails: true }));
+    const res = store.uploadFrame(clip(722), FAKE_SOURCE, 320, 240);
+    expect(res?.ok).toBe(false);
+    if (res !== undefined && !res.ok) {
+      expect(res.error.code).toBe('webgpu-runtime-error');
+    }
+  });
+
+  it('destroyAll destroys every transient texture + clears the views', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe));
+    store.uploadFrame(clip(730), FAKE_SOURCE, 64, 64);
+    store.uploadFrame(clip(731), FAKE_SOURCE, 64, 64);
+    store.destroyAll();
+    expect(probe.destroyed).toBe(2);
+    expect(store.getView(clip(730))).toBeUndefined();
+  });
+});

package/src/__tests__/environment-error-exhaustive.test-d.ts

@@ -0,0 +1,28 @@
+// feat-20260704-runtime-tier1-decomposition M2 / w13 (AC-07 c): environment
+// cluster type-level regression guard. EngineEnvironmentError predates the
+// closed-union error model: it has NO `.code` field and is never fanned out
+// through onError (it throws at construction), so the cluster has no
+// *ErrorCode code union. This guard instead pins the class's structured
+// `.detail` shape (EngineEnvironmentErrorDetail) so a future edit that drops or
+// re-types the two optional error carriers is caught at typecheck.
+//
+// See render-error-exhaustive.test-d.ts header for the shared *.test-d.ts
+// pattern rationale.
+
+import type { RhiError } from '@forgeax/engine-rhi';
+import type { EngineEnvironmentError, EngineEnvironmentErrorDetail } from '../errors/environment';
+
+function narrowEnvironmentError(err: EngineEnvironmentError): void {
+  void err.reason; // string
+  const detail: EngineEnvironmentErrorDetail = err.detail;
+  // Both carriers are optional RhiError | Error and read via property access.
+  const webgpu: RhiError | Error | undefined = detail.webgpuError;
+  const wgpu: RhiError | Error | undefined = detail.wgpuError;
+  void webgpu;
+  void wgpu;
+}
+
+export type _EnvironmentChecks = {
+  /** @internal forces tsc to type-check the EngineEnvironmentError detail shape. */
+  _narrow: typeof narrowEnvironmentError;
+};

package/src/__tests__/equirect-bc6h.integration.test.ts

@@ -0,0 +1,158 @@
+// equirect renderable-source integration test (feat-20260707 M5 fix, dawn env).
+//
+// The full HDR equirect chain, end to end: an equirect is ALWAYS an IBL / skybox
+// source (Skylight.equirect / SkyboxBackground.equirect drive equirect-to-cube /
+// irradiance / prefilter RENDER passes). A block-compressed HDR format
+// (bc6h-rgb-ufloat) is sample-only, never a color-renderable render target
+// ("BC6HRGBUfloat is not color renderable"), so an equirect is never
+// block-compressed: it is delivered uncompressed rgba16float. This test asserts
+// the equirect loader yields an rgba16float POD and `deriveRenderDataCubemap`
+// accepts it (renderable cube source), regardless of the device bc cap.
+//
+// This replaces the earlier "equirect -> BC6H by cap" premise, which was itself
+// the bug: BC6H equirect broke cube projection with a WebGPU device error.
+//
+// dawn env: the caps triple is printed so the lavapipe/llvmpipe BC-support
+// question stays empirically visible in CI logs; the equirect path is
+// cap-independent (always rgba16float).
+//
+// File is named `.integration.test.ts`; it is added to the dawn project
+// `include` array in the root vitest.config.ts so it runs under the dawn-node GPU
+// env, and skips itself when navigator.gpu is absent (the per-package unit
+// project) rather than failing.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { EquirectAsset } from '@forgeax/engine-types';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { deriveRenderDataCubemap } from '../../../render/src/render-data';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const gpu = globalThis.navigator?.gpu;
+const hasGpu = gpu !== undefined;
+
+const GUID_EQUI = 'c0000000-0000-4000-a000-000065717569';
+const PACK_INDEX_URL = '/test-equirect-renderable-pack-index.json';
+
+function parseGuid(g: string): AssetGuid {
+  const parsed = AssetGuid.parse(g);
+  if (!parsed.ok) throw new Error(`bad guid ${g}`);
+  return parsed.value;
+}
+
+/** A deterministic WxH rgba16float (IEEE-754 binary16) HDR image. */
+function makeHdrHalf(w: number, h: number): Uint8Array {
+  // 0x3c00 = 1.0 in binary16; vary channels so the bytes are non-trivial.
+  const px = new Uint16Array(w * h * 4);
+  for (let i = 0; i < w * h; i++) {
+    px[i * 4] = 0x3c00;
+    px[i * 4 + 1] = 0x3800; // 0.5
+    px[i * 4 + 2] = 0x3400; // 0.25
+    px[i * 4 + 3] = 0x3c00;
+  }
+  return new Uint8Array(px.buffer);
+}
+
+let bcCap = false;
+
+describe.skipIf(!hasGpu)('equirect renderable-source integration (feat-20260707 fix)', () => {
+  const width = 64;
+  const height = 32;
+  let binBytes: Uint8Array;
+  const packageUrl = '/ddc/equirect.pack.json';
+  const artifactUrl = '/ddc/equirect.bin';
+
+  beforeAll(async () => {
+    // biome-ignore lint/style/noNonNullAssertion: skipIf(!hasGpu) guards this
+    const adapter = await gpu!.requestAdapter();
+    if (adapter === null) throw new Error('no GPU adapter under dawn');
+    bcCap = adapter.features.has('texture-compression-bc');
+    // biome-ignore lint/suspicious/noConsole: keep the caps triple empirically visible in CI logs
+    console.info(
+      `[equirect caps] bc=${bcCap} etc2=${adapter.features.has(
+        'texture-compression-etc2',
+      )} astc=${adapter.features.has('texture-compression-astc')}`,
+    );
+    binBytes = makeHdrHalf(width, height);
+  });
+
+  function wireFetch(): void {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = typeof input === 'string' ? input : String(input);
+      if (url === PACK_INDEX_URL) {
+        return {
+          ok: true,
+          json: async () => [{ guid: GUID_EQUI, packageUrl, kind: 'equirect' }],
+        } as Response;
+      }
+      if (url === packageUrl) {
+        return {
+          ok: true,
+          json: async () => ({
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              {
+                guid: GUID_EQUI,
+                kind: 'equirect',
+                payload: {
+                  kind: 'equirect',
+                  width,
+                  height,
+                  format: 'rgba16float',
+                  colorSpace: 'linear',
+                },
+                refs: [],
+                artifacts: {
+                  body: {
+                    path: 'equirect.bin',
+                    mediaType: 'application/x-forgeax-rgba16f',
+                  },
+                },
+              },
+            ],
+          }),
+        } as Response;
+      }
+      if (url === artifactUrl) {
+        return { ok: true, arrayBuffer: async () => binBytes.buffer } as Response;
+      }
+      return { ok: false, status: 404 } as Response;
+    }) as typeof globalThis.fetch;
+  }
+
+  async function loadEquirect(): Promise<EquirectAsset> {
+    wireFetch();
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    reg.configurePackIndex(PACK_INDEX_URL);
+    reg.setTranscodeCaps({ bc: bcCap, etc2: false, astc: false });
+    const res = await reg.loadByGuid<EquirectAsset>(parseGuid(GUID_EQUI));
+    if (!res.ok) throw new Error(`equirect load failed: ${(res.error as { code: string }).code}`);
+    return res.value;
+  }
+
+  it('equirect is uncompressed rgba16float regardless of bc cap (IBL render source)', async () => {
+    const asset = await loadEquirect();
+    expect(asset.kind).toBe('equirect');
+    // Never a block-compressed format: an equirect drives cube RENDER passes and
+    // BC6H is not color-renderable.
+    expect(asset.format).toBe('rgba16float');
+  });
+
+  it('deriveRenderDataCubemap accepts the rgba16float equirect (renderable cube source)', async () => {
+    const asset = await loadEquirect();
+    // deriveRenderDataCubemap consumes a TextureAsset-shaped source; the equirect
+    // POD mirrors that 2D surface.
+    const source = {
+      kind: 'texture' as const,
+      width: asset.width,
+      height: asset.height,
+      format: asset.format,
+      data: asset.data,
+      colorSpace: asset.colorSpace,
+      mipmap: false,
+    };
+    const res = deriveRenderDataCubemap(source);
+    expect(res.ok).toBe(true);
+  });
+});