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

package/src/__tests__/four-path-compression.integration.test.ts

@@ -0,0 +1,395 @@
+// w16 — Integration: 4-path compressed-fixture loading (AC-02)
+//
+// Validates that all 4 binary loading paths (texture, equirect, font, mesh)
+// work with compressed assets. The loaders mechanically pass
+// `entry.compression` to fetchBinary; the decompression gate inside
+// fetchBinary handles the rest. Zero loader-side logic rewrite.
+//
+// This test is TDD-RED before w19 — fetchBinary currently has no
+// decompression gate, so loading compressed assets fails.
+//
+// Plan decisions:
+//   AC-02: 4 paths through fetchBinary
+//   D-2: pass entry.compression value, not entire entry
+//   E9: mesh inline (import-runner.ts:422-427) excluded — not in scope
+//   D-10: all fixture data programmatic
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { packMeshBinV4 } from '@forgeax/engine-import';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MeshAsset } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const GUID_MESH = 'c0000000-0000-4000-a000-00006d657368';
+const GUID_TEX = 'c0000000-0000-4000-a000-000074657874';
+const GUID_EQUI = 'c0000000-0000-4000-a000-000065717569';
+const GUID_FONT = 'c0000000-0000-4000-a000-0000666f6e74';
+
+const PACK_INDEX_URL = '/test-four-path-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;
+}
+
+/**
+ * Minimal synthetic mesh bin payload — v2 header, 3 vertices of 12 floats,
+ * Uint16 indices, JSON submesh + aabb tail. Compatible with unpackMeshBin.
+ */
+function makeMeshBinPayload(): Uint8Array {
+  const vertices = new Float32Array(36);
+  for (let i = 0; i < 3; i++) {
+    const b = i * 12;
+    vertices[b + 0] = i * 1;
+    vertices[b + 1] = 0;
+    vertices[b + 2] = 0;
+    vertices[b + 3] = 0;
+    vertices[b + 4] = 1;
+    vertices[b + 5] = 0;
+    vertices[b + 6] = 0;
+    vertices[b + 7] = 0;
+    vertices[b + 8] = 1;
+    vertices[b + 9] = 0;
+    vertices[b + 10] = 0;
+    vertices[b + 11] = 1;
+  }
+  const indices = new Uint16Array([0, 1, 2]);
+
+  const packed = packMeshBinV4(
+    {
+      vertices,
+      indices,
+      attributes: {
+        position: new Float32Array(9),
+        normal: new Float32Array(9),
+        uv: new Float32Array(6),
+        tangent: new Float32Array(12),
+      },
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          topology: 'triangle-list',
+          materialSlot: 0,
+        },
+      ],
+      aabb: new Float32Array([0, 0, 0, 1, 1, 1]),
+    },
+    'runtime://four-path',
+  );
+  if (!packed.ok) throw new Error(packed.error.actual);
+  return packed.value;
+}
+
+let originalFetch: typeof globalThis.fetch;
+
+describe('w16: 4-path compressed-fixture loading', () => {
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  /**
+   * Path 1: mesh loadByGuidProd loads compressed mesh .bin → MeshAsset POD
+   *
+   * TDD-RED: Before w19, fetchBinary does not decompress — the zstd bytes
+   * reach unpackMeshBin → version check reads random bytes → returns undefined
+   * → asset-parse-failed. After w19, the decompression gate decompresses
+   * first → unpackMeshBin sees original v2 header → succeeds.
+   */
+  it('path 1: mesh loadByGuid loads compressed mesh .bin → MeshAsset', async () => {
+    const original = makeMeshBinPayload();
+    const { compressZstd } = await import('@forgeax/engine-codec/encode');
+    const compRes = await compressZstd(original);
+    if (!compRes.ok) throw new Error('compressZstd failed');
+
+    globalThis.fetch = vi.fn().mockImplementation((input: string) => {
+      const url = typeof input === 'string' ? input : String(input);
+      if (url === PACK_INDEX_URL) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve([
+              {
+                guid: GUID_MESH,
+                packageUrl: `/ddc/${GUID_MESH}.pack.json`,
+                kind: 'mesh',
+              },
+            ]),
+        });
+      }
+      if (url === `/ddc/${GUID_MESH}.pack.json`) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              schemaVersion: '2.0.0',
+              kind: 'internal-text-package',
+              assets: [
+                {
+                  guid: GUID_MESH,
+                  kind: 'mesh',
+                  payload: {},
+                  refs: [],
+                  artifacts: {
+                    body: {
+                      path: `${GUID_MESH}.bin`,
+                      mediaType: 'application/x-forgeax-mesh',
+                      contentEncoding: 'zstd',
+                    },
+                  },
+                },
+              ],
+            }),
+        });
+      }
+      return Promise.resolve({
+        ok: true,
+        arrayBuffer: () => Promise.resolve(compRes.value.buffer),
+      });
+    }) as typeof globalThis.fetch;
+
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    reg.configurePackIndex(PACK_INDEX_URL);
+
+    const result = await reg.loadByGuid<MeshAsset>(parseGuid(GUID_MESH));
+
+    // TDD-RED: after w19, this becomes true
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.kind).toBe('mesh');
+      expect(result.value.indices).toBeDefined();
+      expect((result.value.indices as Uint16Array).length).toBe(3);
+    }
+  });
+
+  /**
+   * Path 2: textureLoader loads compressed texture .bin → TextureAsset
+   *
+   * TDD-RED: same issue — the compressed bytes reach the texture loader's
+   * data field, get uploaded to GPU as corrupt texture. After w19,
+   * fetchBinary decompresses first → loader sees raw RGBA bytes.
+   *
+   * For the TDD stage we construct a simple RGBA pixel payload (4 bytes)
+   * so the loader can still produce a texture asset (shape test).
+   */
+  it('path 2: textureLoader loads compressed texture .bin → TextureAsset', async () => {
+    // 4x4 RGBA8 texture = 64 bytes raw pixel data
+    const rawPixels = new Uint8Array(64);
+    for (let i = 0; i < 64; i++) {
+      rawPixels[i] = (i * 17) % 256;
+    }
+    const { compressZstd } = await import('@forgeax/engine-codec/encode');
+    const compRes = await compressZstd(rawPixels);
+    if (!compRes.ok) throw new Error('compressZstd failed');
+
+    globalThis.fetch = vi.fn().mockImplementation((input: string) => {
+      const url = typeof input === 'string' ? input : String(input);
+      if (url === PACK_INDEX_URL) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve([
+              {
+                guid: GUID_TEX,
+                packageUrl: `/ddc/${GUID_TEX}.pack.json`,
+                kind: 'texture',
+              },
+            ]),
+        });
+      }
+      if (url === `/ddc/${GUID_TEX}.pack.json`) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              schemaVersion: '2.0.0',
+              kind: 'internal-text-package',
+              assets: [
+                {
+                  guid: GUID_TEX,
+                  kind: 'texture',
+                  payload: {
+                    width: 4,
+                    height: 4,
+                    format: 'rgba8unorm',
+                    colorSpace: 'srgb',
+                  },
+                  refs: [],
+                  artifacts: {
+                    body: {
+                      path: `${GUID_TEX}.bin`,
+                      mediaType: 'application/x-forgeax-rgba8',
+                      contentEncoding: 'zstd',
+                    },
+                  },
+                },
+              ],
+            }),
+        });
+      }
+      return Promise.resolve({
+        ok: true,
+        arrayBuffer: () => Promise.resolve(compRes.value.buffer),
+      });
+    }) as typeof globalThis.fetch;
+
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    reg.configurePackIndex(PACK_INDEX_URL);
+
+    const result = await reg.loadByGuid(parseGuid(GUID_TEX));
+    // TDD-RED: after w19 this becomes true — the decompressed bytes
+    // produce a valid 64-byte data field.
+    expect(result.ok).toBe(true);
+  });
+
+  /**
+   * Path 3: equirectLoader loads compressed equirect .bin → TextureAsset
+   * Same shape as textureLoader.
+   */
+  it('path 3: equirectLoader loads compressed equirect .bin', async () => {
+    const rawPixels = new Uint8Array(64);
+    for (let i = 0; i < 64; i++) {
+      rawPixels[i] = (i * 17) % 256;
+    }
+    const { compressZstd } = await import('@forgeax/engine-codec/encode');
+    const compRes = await compressZstd(rawPixels);
+    if (!compRes.ok) throw new Error('compressZstd failed');
+
+    globalThis.fetch = vi.fn().mockImplementation((input: string) => {
+      const url = typeof input === 'string' ? input : String(input);
+      if (url === PACK_INDEX_URL) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve([
+              {
+                guid: GUID_EQUI,
+                packageUrl: `/ddc/${GUID_EQUI}.pack.json`,
+                kind: 'equirect',
+              },
+            ]),
+        });
+      }
+      if (url === `/ddc/${GUID_EQUI}.pack.json`) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              schemaVersion: '2.0.0',
+              kind: 'internal-text-package',
+              assets: [
+                {
+                  guid: GUID_EQUI,
+                  kind: 'equirect',
+                  payload: { width: 4, height: 4, format: 'rgba16float', colorSpace: 'linear' },
+                  refs: [],
+                  artifacts: {
+                    body: {
+                      path: `${GUID_EQUI}.bin`,
+                      mediaType: 'application/x-forgeax-rgba16f',
+                      contentEncoding: 'zstd',
+                    },
+                  },
+                },
+              ],
+            }),
+        });
+      }
+      return Promise.resolve({
+        ok: true,
+        arrayBuffer: () => Promise.resolve(compRes.value.buffer),
+      });
+    }) as typeof globalThis.fetch;
+
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    reg.configurePackIndex(PACK_INDEX_URL);
+
+    const result = await reg.loadByGuid(parseGuid(GUID_EQUI));
+    expect(result.ok).toBe(true);
+  });
+
+  /**
+   * Path 4: fontLoader loads compressed font pack JSON
+   *
+   * Unlike mesh/texture, font data is JSON (TextDecoder). The decompressed
+   * bytes must be valid JSON. Font loading through loadByGuid for a 'font'
+   * kind requires the font loader to be registered.
+   */
+  it('path 4: fontLoader loads compressed font pack JSON', async () => {
+    const fontPack = JSON.stringify({
+      assets: [{ guid: GUID_FONT, kind: 'font', payload: {} }],
+    });
+    const fontBytes = new TextEncoder().encode(fontPack);
+    const { compressZstd } = await import('@forgeax/engine-codec/encode');
+    const compRes = await compressZstd(fontBytes);
+    if (!compRes.ok) throw new Error('compressZstd failed');
+
+    globalThis.fetch = vi.fn().mockImplementation((input: string) => {
+      const url = typeof input === 'string' ? input : String(input);
+      if (url === PACK_INDEX_URL) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve([
+              {
+                guid: GUID_FONT,
+                packageUrl: `/ddc/${GUID_FONT}.pack.json`,
+                kind: 'font',
+              },
+            ]),
+        });
+      }
+      if (url === `/ddc/${GUID_FONT}.pack.json`) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              schemaVersion: '2.0.0',
+              kind: 'internal-text-package',
+              assets: [
+                {
+                  guid: GUID_FONT,
+                  kind: 'font',
+                  payload: {},
+                  refs: [],
+                  artifacts: {
+                    body: {
+                      path: `${GUID_FONT}.json`,
+                      mediaType: 'application/json',
+                      contentEncoding: 'zstd',
+                    },
+                  },
+                },
+              ],
+            }),
+        });
+      }
+      return Promise.resolve({
+        ok: true,
+        arrayBuffer: () => Promise.resolve(compRes.value.buffer),
+      });
+    }) as typeof globalThis.fetch;
+
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    reg.configurePackIndex(PACK_INDEX_URL);
+
+    const result = await reg.loadByGuid(parseGuid(GUID_FONT));
+    // Font loader requires atlasGuid/samplerGuid/specific payload fields.
+    // The decompression gate successfully decompresses the zstd bytes —
+    // the font loader then rejects the content for missing fields.
+    // Key assertion: the error code is from font-loader validation
+    // (asset-parse-failed), not from fetchBinary decompression gate.
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      // Font loader rejects payload lacking atlasGuid/samplerGuid
+      expect(result.error.code).toBe('asset-parse-failed');
+    }
+  });
+});

package/src/__tests__/frame-targets-shadow-regression.unit.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { resolveShadowMapSize } from '../../../render/src/record/frame-targets';
+
+describe('frame targets shadow removal', () => {
+  it('fits a cascaded shadow atlas within the device texture limit', () => {
+    const internals = {
+      device: { limits: { maxTextureDimension2D: 2048 } },
+    };
+    const lights = { shadowMapSize: 2048, cascadeCount: 4 };
+
+    expect(resolveShadowMapSize(internals as never, lights as never)).toBe(1024);
+    expect(resolveShadowMapSize(internals as never, { ...lights, cascadeCount: 1 } as never)).toBe(
+      2048,
+    );
+  });
+
+  it('reserves the WebGL2 depth-texture ceiling below the generic texture limit', () => {
+    const internals = {
+      device: {
+        caps: { backendKind: 'wgpu-webgl2' },
+        limits: { maxTextureDimension2D: 2048 },
+      },
+    };
+    const lights = { shadowMapSize: 2048, cascadeCount: 1 };
+
+    expect(resolveShadowMapSize(internals as never, lights as never)).toBe(1024);
+  });
+});

package/src/__tests__/fullscreen-feature-host.dawn.test.ts

@@ -0,0 +1,80 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { createFullscreenRenderFeature } from '../../../render/src/features/fullscreen';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../../../render/src/features/host';
+import { createRenderFeatureTarget } from '../../../render/src/features/targets';
+
+const SOURCE = `
+@vertex fn vs_main(@builtin(vertex_index) index: u32) -> @builtin(position) vec4<f32> {
+  let x = select(-1.0, 3.0, index == 1u);
+  let y = select(-1.0, 3.0, index == 2u);
+  return vec4<f32>(x, y, 0.0, 1.0);
+}
+@fragment fn fs_main() -> @location(0) vec4<f32> {
+  return vec4<f32>(1.0, 0.0, 1.0, 1.0);
+}`;
+
+const feature = createFullscreenRenderFeature({
+  identity: 'test::fullscreen-feature',
+  source: SOURCE,
+});
+
+describe('fullscreen feature host contract', () => {
+  it('keeps the effect declaration inside the producer plan', () => {
+    const host = createRenderFeatureHost([feature]);
+
+    expect(host.ok).toBe(true);
+    if (!host.ok) return;
+    expect(host.value.features).toHaveLength(1);
+    const [registered] = host.value.features;
+    expect(registered).toBeDefined();
+    const planned = runRenderFeatureFrame(host.value, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: {} as unknown as RhiCaps,
+      targets: [],
+    });
+    expect(planned.plans[0]?.plan.resources[0]).toMatchObject({
+      kind: 'fullscreen-program',
+      name: 'fullscreen.test--fullscreen-feature',
+      source: SOURCE,
+    });
+  });
+
+  it('rejects duplicate producer identities at host construction', () => {
+    const duplicate = createFullscreenRenderFeature({
+      identity: feature.identity,
+      source: SOURCE,
+    });
+    const host = createRenderFeatureHost([feature, duplicate]);
+
+    expect(host.ok).toBe(false);
+    if (host.ok) return;
+    expect(host.error.code).toBe('render-feature-registration-conflict');
+  });
+
+  it('builds one closed plan without a late registry mutation', () => {
+    const host = createRenderFeatureHost([feature]);
+    expect(host.ok).toBe(true);
+    if (!host.ok) return;
+    const planned = runRenderFeatureFrame(host.value, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: {} as unknown as RhiCaps,
+      targets: [
+        createRenderFeatureTarget({ kind: 'scene-color', format: 'rgba16float', sampleCount: 1 }),
+      ],
+    });
+
+    expect(planned.errors).toEqual([]);
+    expect(planned.plans).toHaveLength(1);
+    expect(planned.plans[0]?.plan.resources[0]).toMatchObject({
+      kind: 'fullscreen-program',
+      name: 'fullscreen.test--fullscreen-feature',
+      source: SOURCE,
+    });
+    expect(planned.plans[0]?.plan.passes).toEqual([]);
+  });
+});

package/src/__tests__/fullscreen-post-bgl-depth.test.ts

@@ -0,0 +1,133 @@
+// fullscreen-post-bgl-depth.test.ts —
+// feat-20260702-postprocess-camera-depth-read M2 / w4.
+//
+// Structural assertions for the 'fullscreen-post-with-scene-depth' BGL kind:
+// (a) 5-entry layout (color@0 + sampler@1 + params@2 + depthTex@3 + depthSampler@4).
+// (b) depthTex@3 uses sampleType:'depth', viewDimension:'2d'.
+// (c) depthSampler@4 uses type:'non-filtering' (plan-strategy D-2).
+// (d) Existing 'fullscreen-post' and 'fullscreen-post-with-params' BGL shapes
+//     are unchanged (AC-03 regression gate — pin the entry counts so a future
+//     change to those kinds breaks this test).
+
+import { describe, expect, it } from 'vitest';
+import {
+  buildBindGroupLayoutDescriptor,
+  type PipelineSpec,
+} from '../../../render/src/pipeline-spec';
+
+function makeSpec(colorFormats: GPUTextureFormat[] = ['rgba16float']): PipelineSpec {
+  return {
+    shader: { id: '', passKind: 'forward', variantSet: undefined },
+    attachments: { colorFormats, depthFormat: undefined, sampleCount: 1 },
+    geometry: { topology: 'triangle-list', vertexLayout: {} },
+    renderState: undefined,
+  };
+}
+
+describe('buildBindGroupLayoutDescriptor — fullscreen-post-with-scene-depth', () => {
+  it('returns label fullscreen-post-with-scene-depth-bgl', () => {
+    const spec = makeSpec();
+    const out = buildBindGroupLayoutDescriptor(spec, {
+      kind: 'fullscreen-post-with-scene-depth',
+    });
+    expect(out.label).toBe('fullscreen-post-with-scene-depth-bgl');
+  });
+
+  it('has exactly 5 entries', () => {
+    const spec = makeSpec();
+    const out = buildBindGroupLayoutDescriptor(spec, {
+      kind: 'fullscreen-post-with-scene-depth',
+    });
+    expect(out.entries).toHaveLength(5);
+  });
+
+  it('binding 0 = texture(float, 2d)', () => {
+    const spec = makeSpec();
+    const out = buildBindGroupLayoutDescriptor(spec, {
+      kind: 'fullscreen-post-with-scene-depth',
+    });
+    const e = out.entries[0];
+    expect(e?.binding).toBe(0);
+    expect(e?.visibility).toBe(0x2); // FRAGMENT
+    expect(e?.texture?.sampleType).toBe('float');
+    expect(e?.texture?.viewDimension).toBe('2d');
+  });
+
+  it('binding 1 = sampler(filtering)', () => {
+    const spec = makeSpec();
+    const out = buildBindGroupLayoutDescriptor(spec, {
+      kind: 'fullscreen-post-with-scene-depth',
+    });
+    const e = out.entries[1];
+    expect(e?.binding).toBe(1);
+    expect(e?.visibility).toBe(0x2);
+    expect(e?.sampler?.type).toBe('filtering');
+  });
+
+  it('binding 2 = buffer(uniform) — params always present (D-3)', () => {
+    const spec = makeSpec();
+    const out = buildBindGroupLayoutDescriptor(spec, {
+      kind: 'fullscreen-post-with-scene-depth',
+    });
+    const e = out.entries[2];
+    expect(e?.binding).toBe(2);
+    expect(e?.visibility).toBe(0x2);
+    expect(e?.buffer?.type).toBe('uniform');
+  });
+
+  it('binding 3 = texture(depth, 2d)', () => {
+    const spec = makeSpec();
+    const out = buildBindGroupLayoutDescriptor(spec, {
+      kind: 'fullscreen-post-with-scene-depth',
+    });
+    const e = out.entries[3];
+    expect(e?.binding).toBe(3);
+    expect(e?.visibility).toBe(0x2);
+    expect(e?.texture?.sampleType).toBe('depth');
+    expect(e?.texture?.viewDimension).toBe('2d');
+  });
+
+  it('binding 4 = sampler(non-filtering) — D-2 nearest+clamp, NOT comparison', () => {
+    const spec = makeSpec();
+    const out = buildBindGroupLayoutDescriptor(spec, {
+      kind: 'fullscreen-post-with-scene-depth',
+    });
+    const e = out.entries[4];
+    expect(e?.binding).toBe(4);
+    expect(e?.visibility).toBe(0x2);
+    expect(e?.sampler?.type).toBe('non-filtering');
+  });
+
+  describe('AC-03 regression: existing kinds unchanged', () => {
+    it("'fullscreen-post' still 2 entries", () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, { kind: 'fullscreen-post' });
+      expect(out.entries).toHaveLength(2);
+    });
+
+    it("'fullscreen-post-with-params' still 3 entries", () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, {
+        kind: 'fullscreen-post-with-params',
+      });
+      expect(out.entries).toHaveLength(3);
+    });
+  });
+});
+
+describe('buildBindGroupLayoutDescriptor — fullscreen-post-with-scene-depth-msaa', () => {
+  it('declares a multisampled depth texture with the same five-slot ABI', () => {
+    const out = buildBindGroupLayoutDescriptor(makeSpec(), {
+      kind: 'fullscreen-post-with-scene-depth-msaa',
+    });
+    expect(out.label).toBe('fullscreen-post-with-scene-depth-msaa-bgl');
+    expect(out.entries).toHaveLength(5);
+    expect(out.entries[2]?.buffer?.type).toBe('uniform');
+    expect(out.entries[3]?.texture).toMatchObject({
+      sampleType: 'depth',
+      viewDimension: '2d',
+      multisampled: true,
+    });
+    expect(out.entries[4]?.sampler?.type).toBe('non-filtering');
+  });
+});