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

package/src/__tests__/dawn/mesh-ssbo-normal-matrix.dawn.test.ts

@@ -0,0 +1,106 @@
+// mesh-ssbo-normal-matrix.dawn.test.ts - feat-20260518-pbr-direct-lighting-mvp
+// M3 / w11 (TDD red): per-instance Mesh SSBO byte layout (mat4 worldFromLocal
+// in [0,64) + mat3 normalMatrix in [64,112) padded as 3 vec4 to 16-byte
+// boundaries, total 112 B inside the 256 B PER_ENTITY_STRIDE slot).
+//
+// Plan-strategy D-5 + AC-08: the Mesh struct in common.wgsl now carries
+// `normalMatrix: mat3x3<f32>` alongside `worldFromLocal: mat4x4<f32>`. The
+// host (render-system-record.ts) computes
+//   normalMatrix = transpose(invert(mat3(worldFromLocal)))
+// once per renderable per frame and writes it to the mesh SSBO slot at
+// byte offset 64 (the mat3 occupies three vec4 columns, each 16 B = 48 B
+// total, ending at offset 112). The remaining 256 - 112 = 144 B in the
+// PER_ENTITY_STRIDE slot is slack reserved for future extensions.
+//
+// Tier: dawn-node (real GPU + queue.submit guarded by skipIf). The full
+// readback gate is covered by `pnpm --filter @forgeax/hello-room smoke` (300 frames
+// pixel-parity); this dawn-tier gate asserts the host-side numeric
+// derivation that feeds the mesh SSBO write path: given a known mat4 of a
+// rotated + non-uniformly scaled entity, the host-derived normalMatrix
+// matches `transpose(invert(mat3(worldFromLocal)))` to epsilon <= 1e-5
+// (the binary judgment that AC-08 motivates).
+
+import { mat3, mat4, quat, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+
+const dawnReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+describe('w11 mesh SSBO normalMatrix host derivation (AC-08, dawn)', () => {
+  it.skipIf(!dawnReady)(
+    'rotated + non-uniformly scaled entity: normalMatrix matches transpose(invert(mat3(worldFromLocal))) within 1e-5',
+    () => {
+      // Build a non-identity transform: yaw 45 deg + non-uniform scale.
+      const m4 = mat4.create();
+      const q = quat.create();
+      q[0] = 0;
+      q[1] = Math.sin(Math.PI / 8);
+      q[2] = 0;
+      q[3] = Math.cos(Math.PI / 8);
+      mat4.compose(m4, vec3.create(0, 0, 0), q, vec3.create(1.5, 0.5, 1));
+      const expectedNormal = mat3.normalMatrix(mat3.create(), m4);
+
+      // Per AC-08 the host writes 9 floats with 16-byte stride (mat3 = 3 vec4)
+      // into the mesh SSBO at offset [64, 112). Construct the host-side
+      // packed payload that render-system-record.ts produces and assert the
+      // mat3 columns land at the canonical std140 offsets.
+      // Float-typed payload mirroring the Mesh struct slot:
+      //   [0..16) mat4 (16 floats), [16..28) mat3 padded (12 floats: 3 vec4)
+      const slot = new Float32Array(28); // 112 bytes
+      for (let i = 0; i < 16; i++) slot[i] = m4[i] ?? 0;
+      // mat3 column 0 -> slot[16..19] (xyz + 1 padding float)
+      slot[16] = expectedNormal[0] ?? 0;
+      slot[17] = expectedNormal[1] ?? 0;
+      slot[18] = expectedNormal[2] ?? 0;
+      // mat3 column 1 -> slot[20..23]
+      slot[20] = expectedNormal[3] ?? 0;
+      slot[21] = expectedNormal[4] ?? 0;
+      slot[22] = expectedNormal[5] ?? 0;
+      // mat3 column 2 -> slot[24..27]
+      slot[24] = expectedNormal[6] ?? 0;
+      slot[25] = expectedNormal[7] ?? 0;
+      slot[26] = expectedNormal[8] ?? 0;
+
+      // Byte-offset checks: mat4 in [0,64), mat3 in [64,112).
+      expect(slot.byteLength).toBe(112);
+
+      // Numeric check: derived normalMatrix must differ from upper-left
+      // mat3 of m4 (the latter is the *wrong* transform; AC-08 motivates
+      // computing transpose(inverse(mat3(...))) explicitly because
+      // non-uniform scale breaks the upper-left mat3 normal transform).
+      const upperLeft = mat3.fromMat4(mat3.create(), m4);
+      let differs = false;
+      for (let i = 0; i < 9; i++) {
+        if (Math.abs((upperLeft[i] ?? 0) - (expectedNormal[i] ?? 0)) > 1e-5) {
+          differs = true;
+          break;
+        }
+      }
+      expect(differs).toBe(true);
+
+      // Numerical: every element finite + matches the closed-form
+      // transpose(invert) of the upper-left mat3 within the AC-08 1e-5 cap.
+      const ref = mat3.transpose(
+        mat3.create(),
+        mat3.invert(mat3.create(), mat3.fromMat4(mat3.create(), m4)),
+      );
+      for (let i = 0; i < 9; i++) {
+        expect(expectedNormal[i] ?? 0).toBeCloseTo(ref[i] ?? 0, 5);
+      }
+    },
+  );
+
+  it.skipIf(!dawnReady)('identity transform: normalMatrix = identity', () => {
+    const m4 = mat4.create();
+    mat4.identity(m4);
+    const n = mat3.normalMatrix(mat3.create(), m4);
+    expect(n[0]).toBeCloseTo(1, 6);
+    expect(n[4]).toBeCloseTo(1, 6);
+    expect(n[8]).toBeCloseTo(1, 6);
+    expect(n[1]).toBeCloseTo(0, 6);
+    expect(n[2]).toBeCloseTo(0, 6);
+    expect(n[3]).toBeCloseTo(0, 6);
+    expect(n[5]).toBeCloseTo(0, 6);
+    expect(n[6]).toBeCloseTo(0, 6);
+    expect(n[7]).toBeCloseTo(0, 6);
+  });
+});

package/src/__tests__/dawn/mesh-update-dawn.test.ts

@@ -0,0 +1,250 @@
+// mesh-update-dawn.test.ts - updateMesh in-place re-upload dawn-tier test
+// (feat-20260531-world-space-msdf-text-rendering M3 / w12).
+//
+// Verifies that updateMesh correctly writes new vertex/index data into
+// existing GPU buffers and, on expansion, creates new buffers while
+// destroying old ones — all without changing the mesh handle id.
+//
+// AC-08 falsification: if updateMesh leaked GPU buffers (create without
+// destroy), the dawn backend would surface this as resource exhaustion
+// or the buffer count would grow across repeated calls. This test
+// validates the structural invariants on a real GPU device.
+
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { PROCEDURAL_FLOATS_PER_VERTEX } from '@forgeax/engine-geometry';
+import { mat4 } from '@forgeax/engine-math';
+import { ok } from '@forgeax/engine-rhi';
+import type { EquirectAsset, MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { GpuResidencyCache } from '../../../../render/src/device/gpu-residency';
+
+const mockCaps = {
+  backendKind: 'webgpu' as const,
+  compute: true,
+  timestampQuery: false,
+  timestampPeriodNanoseconds: null,
+  indirectDrawing: false,
+  textureCompressionBc: false,
+  textureCompressionEtc2: false,
+  textureCompressionAstc: false,
+  multiDrawIndirect: false,
+  pushConstants: false,
+  textureBindingArray: false,
+  samplerAliasing: false,
+  firstInstanceIndirect: false,
+  storageBuffer: true,
+  storageTexture: false,
+  rgba16floatRenderable: true,
+  rg11b10ufloatRenderable: false,
+  float32Filterable: false,
+  maxColorAttachments: 8,
+};
+
+// feat-20260601-device/gpu-residency-extraction M1: mesh GPU residency + updateMesh
+// moved to the store, and register no longer auto-uploads (push severed). The
+// pull-model test premise: register the POD, then explicitly
+// `store.ensureResident(handle, pod)` to upload, then assert + updateMesh.
+
+const dawnReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+function makeSmallMesh(): MeshAsset {
+  const vertices = new Float32Array(4 * PROCEDURAL_FLOATS_PER_VERTEX);
+  const indices = new Uint16Array([0, 1, 2, 0, 2, 3]);
+  return {
+    kind: 'mesh',
+    vertices,
+    indices,
+    attributes: {},
+    aabb: new Float32Array(6),
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: indices.length,
+        vertexCount: vertices.length,
+        topology: 'triangle-list',
+        materialSlot: 0,
+      },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  };
+}
+
+function makeLargerMesh(): MeshAsset {
+  const vertices = new Float32Array(8 * PROCEDURAL_FLOATS_PER_VERTEX);
+  const indices = new Uint16Array([0, 1, 2, 0, 2, 3, 4, 5, 6, 4, 6, 7]);
+  return {
+    kind: 'mesh',
+    vertices,
+    indices,
+    attributes: {},
+    aabb: new Float32Array(6),
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: indices.length,
+        vertexCount: vertices.length,
+        topology: 'triangle-list',
+        materialSlot: 0,
+      },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  };
+}
+
+describe('w12 - updateMesh dawn-tier (AC-08)', () => {
+  it.skipIf(!dawnReady)(
+    '(a) updateMesh in-place re-upload does not create new vbo/ibo',
+    async () => {
+      const adapter = await navigator.gpu.requestAdapter();
+      expect(adapter).not.toBeNull();
+      if (adapter === null) return;
+      const device = await adapter.requestDevice();
+
+      const store = new GpuResidencyCache();
+      const world = new World();
+      store.configureGpuDevice(
+        // biome-ignore lint/suspicious/noExplicitAny: structural rhi device shim
+        device as any,
+        undefined,
+        (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
+        mockCaps,
+      );
+
+      const mesh = makeSmallMesh();
+      const handle = world.allocSharedRef('MeshAsset', mesh);
+      // Pull-model: explicit ensureResident uploads the GPU buffers.
+      const residentRes = store.ensureResident(handle, mesh);
+      expect(residentRes.ok).toBe(true);
+      const before = store.getMeshGpuHandles(handle);
+      expect(before).toBeDefined();
+      if (before === undefined) return;
+      expect(before.vertexBuffer).toBeDefined();
+      expect(before.indexBuffer).toBeDefined();
+
+      const vboBefore = before.vertexBuffer;
+      const iboBefore = before.indexBuffer;
+
+      // In-place update: same size data.
+      if (!(mesh.indices instanceof Uint16Array)) return;
+      store.updateMesh(handle, mesh.vertices, mesh.indices);
+
+      const after = store.getMeshGpuHandles(handle);
+      expect(after).toBeDefined();
+      if (after === undefined) return;
+
+      // Same-size update must reuse the same buffers (no create/destroy).
+      expect(after.vertexBuffer).toBe(vboBefore);
+      expect(after.indexBuffer).toBe(iboBefore);
+      expect(after.indexCount).toBe(mesh.indices.length);
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b) updateMesh expansion creates new buffers and destroys old ones, same handle id',
+    async () => {
+      const adapter = await navigator.gpu.requestAdapter();
+      expect(adapter).not.toBeNull();
+      if (adapter === null) return;
+      const device = await adapter.requestDevice();
+
+      const store = new GpuResidencyCache();
+      const world = new World();
+      store.configureGpuDevice(
+        // biome-ignore lint/suspicious/noExplicitAny: structural rhi device shim
+        device as any,
+        undefined,
+        (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
+        mockCaps,
+      );
+
+      const small = makeSmallMesh();
+      const handle = world.allocSharedRef('MeshAsset', small);
+      const residentRes = store.ensureResident(handle, small);
+      expect(residentRes.ok).toBe(true);
+      const before = store.getMeshGpuHandles(handle);
+      expect(before).toBeDefined();
+      if (before === undefined) return;
+      const vboBefore = before.vertexBuffer;
+      const iboBefore = before.indexBuffer;
+
+      // Expansion: larger data exceeds current buffer capacity.
+      const larger = makeLargerMesh();
+      if (!(larger.indices instanceof Uint16Array)) return;
+      store.updateMesh(handle, larger.vertices, larger.indices);
+
+      const after = store.getMeshGpuHandles(handle);
+      expect(after).toBeDefined();
+      if (after === undefined) return;
+
+      // New buffers should be different from old ones.
+      expect(after.vertexBuffer).not.toBe(vboBefore);
+      expect(after.indexBuffer).not.toBe(iboBefore);
+
+      // New buffer sizes should match the larger data. M-3 / w12: byte sizes
+      // are tracked on the entry (`vboBytes` / `iboBytes`), not on the
+      // GpuBuffer wrapper -- the spec-aligned RHI Buffer interface has no
+      // `.size`.
+      expect(after.vboBytes).toBe(larger.vertices.byteLength);
+
+      // indexCount should reflect the larger data.
+      expect(after.indexCount).toBe(larger.indices.length);
+
+      // The handle id is unchanged — resolveAssetHandle still returns the payload.
+      const result = resolveAssetHandle<MeshAsset>(world, handle);
+      expect(result.ok).toBe(true);
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(c) repeated 50-frame same-size updateMesh does not grow GPU buffer count',
+    async () => {
+      const adapter = await navigator.gpu.requestAdapter();
+      expect(adapter).not.toBeNull();
+      if (adapter === null) return;
+      const device = await adapter.requestDevice();
+
+      const store = new GpuResidencyCache();
+      const world = new World();
+      store.configureGpuDevice(
+        // biome-ignore lint/suspicious/noExplicitAny: structural rhi device shim
+        device as any,
+        undefined,
+        (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
+        mockCaps,
+      );
+
+      const mesh = makeSmallMesh();
+      const handle = world.allocSharedRef('MeshAsset', mesh);
+      const residentRes = store.ensureResident(handle, mesh);
+      expect(residentRes.ok).toBe(true);
+      const before = store.getMeshGpuHandles(handle);
+      expect(before).toBeDefined();
+      if (before === undefined) return;
+
+      const vboFirst = before.vertexBuffer;
+      const iboFirst = before.indexBuffer;
+
+      // 50 frames of same-size updates.
+      if (!(mesh.indices instanceof Uint16Array)) return;
+      for (let frame = 0; frame < 50; frame++) {
+        store.updateMesh(handle, mesh.vertices, mesh.indices);
+      }
+
+      const after = store.getMeshGpuHandles(handle);
+      expect(after).toBeDefined();
+      if (after === undefined) return;
+
+      // Same-size updates reuse the same buffers.
+      expect(after.vertexBuffer).toBe(vboFirst);
+      expect(after.indexBuffer).toBe(iboFirst);
+
+      // Sanity pings to keep import chains live.
+      expect(PROCEDURAL_FLOATS_PER_VERTEX).toBe(12);
+      const _matType: Float32Array = mat4.create();
+      void _matType;
+    },
+  );
+});

package/src/__tests__/dawn/mipmap-srgb-linear.dawn.test.ts

@@ -0,0 +1,124 @@
+// T-M3-02 dawn (real GPU) integration tests for the sRGB / linear mipmap
+// math correctness (research F-3; plan-strategy R4 binary judgment).
+//
+// Physical claim under test:
+//   sample input + render output both on the SAME `*-srgb` view causes
+//   hardware to (decode in -> bilinear in linear -> encode out), which means
+//   a mid-gray byte 188 (~0.5 linear after sRGB decode) downsampled by 2x
+//   stays at ~0.5 linear after the next mip blit; the binary failure mode
+//   is the broken-OpenGL "decode in linear-naive way -> 0.5 linear sinks to
+//   0.218 linear" path. This test asserts the blit chain produces the
+//   correct mid-gray on mip level 1 of a 2x2 -> 1x1 source.
+//
+// The 6-fixture coverage promised in plan-tasks T-M3-02 acceptanceCheck:
+//   - 1x1 / 2x2 / 256x256 / non-pow2 dimension boundaries -> covered by
+//     the pure-formula `numMipLevels` unit tests (T-M3-01 (b) -- the formula
+//     SSOT does not need real-GPU verification);
+//   - sRGB / linear physics -> covered by this dawn integration file
+//     (the `*-srgb` view spec path is the only scenario requiring real GPU).
+//
+// Red-stage scaffolding: implementation lands in T-M3-04 (mipmap-generator.ts)
+// + T-M3-05 (uploadTexture call site).
+
+import { numMipLevels } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import type { DecodedImage, TextureAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { GpuResidencyCache } from '../../../../render/src/device/gpu-residency';
+
+// feat-20260601-device/gpu-residency-extraction M1: uploadTexture moved to the
+// store (POD carries format + mipmap flag, decoded carries pixel bytes; D-2).
+// These cases wire no GPU device, so the upload short-circuits to ok after the
+// consistency assertion (the actual mipmap blit needs a wired + prewarmed
+// device; that path is exercised by the smoke harness). numMipLevels assertions
+// are pure-formula and unaffected.
+
+function makeTexture(
+  format: GPUTextureFormat,
+  width: number,
+  height: number,
+  colorSpace: 'srgb' | 'linear',
+  mipmap: boolean,
+): TextureAsset {
+  return {
+    kind: 'texture',
+    width,
+    height,
+    format,
+    data: new Uint8Array(width * height * 4),
+    colorSpace,
+    mipmap,
+  };
+}
+
+function decoded(
+  bytes: Uint8Array,
+  width: number,
+  height: number,
+  colorSpace: 'srgb' | 'linear',
+  mipmap: boolean,
+): DecodedImage {
+  return {
+    bytes,
+    width,
+    height,
+    mime: 'image/png',
+    colorSpace,
+    mipmap,
+  };
+}
+
+describe('T-M3-02 dawn mipmap chain on rgba8unorm-srgb (sRGB physics)', () => {
+  it('sRGB mid-gray 188 (linear ~0.5) survives 2x2 -> 1x1 downsample', async () => {
+    // 2x2 sRGB-byte 188 (~0.5 linear) source; mipmap=auto enables blit chain.
+    // Spec guarantees: hardware decode -> bilinear in linear -> encode back.
+    // 4 byte-188 samples bilinear-averaged in linear ~ 0.5 linear ~ byte 188
+    // after sRGB encode at mip level 1.
+    const world = new World();
+    const bytes = new Uint8Array(2 * 2 * 4);
+    for (let i = 0; i < 4; i++) {
+      bytes[i * 4 + 0] = 188;
+      bytes[i * 4 + 1] = 188;
+      bytes[i * 4 + 2] = 188;
+      bytes[i * 4 + 3] = 255;
+    }
+    const store = new GpuResidencyCache();
+    const pod = makeTexture('rgba8unorm-srgb', 2, 2, 'srgb', true);
+    const handle = world.allocSharedRef<'TextureAsset', TextureAsset>('TextureAsset', pod);
+    const res = await store.uploadTexture(handle, pod, decoded(bytes, 2, 2, 'srgb', true));
+    expect(res.ok).toBe(true);
+    expect(numMipLevels({ width: 2, height: 2 })).toBe(2);
+  });
+});
+
+describe('T-M3-02 dawn mipmap chain on rgba8unorm (linear physics)', () => {
+  it('linear-byte 128 stays linear-byte 128 across 2x2 -> 1x1 downsample', async () => {
+    // 2x2 linear-byte 128 source (no gamma transform). bilinear average of
+    // 4 identical samples = byte 128. mipmap=auto enables blit chain on
+    // linear format.
+    const world = new World();
+    const bytes = new Uint8Array(2 * 2 * 4);
+    for (let i = 0; i < 4; i++) {
+      bytes[i * 4 + 0] = 128;
+      bytes[i * 4 + 1] = 128;
+      bytes[i * 4 + 2] = 128;
+      bytes[i * 4 + 3] = 255;
+    }
+    const store = new GpuResidencyCache();
+    const pod = makeTexture('rgba8unorm', 2, 2, 'linear', true);
+    const handle = world.allocSharedRef<'TextureAsset', TextureAsset>('TextureAsset', pod);
+    const res = await store.uploadTexture(handle, pod, decoded(bytes, 2, 2, 'linear', true));
+    expect(res.ok).toBe(true);
+  });
+
+  it('256x256 mipmap chain produces 9 levels (numMipLevels SSOT)', async () => {
+    expect(numMipLevels({ width: 256, height: 256 })).toBe(9);
+    const world = new World();
+    const bytes = new Uint8Array(256 * 256 * 4).fill(128);
+    const store = new GpuResidencyCache();
+    const pod = makeTexture('rgba8unorm', 256, 256, 'linear', true);
+    const handle = world.allocSharedRef<'TextureAsset', TextureAsset>('TextureAsset', pod);
+    const res = await store.uploadTexture(handle, pod, decoded(bytes, 256, 256, 'linear', true));
+    expect(res.ok).toBe(true);
+  });
+});