@forgeax/engine-runtime 0.1.24 → 0.1.26

package/src/__tests__/surface-standard-pipeline.dawn.test.ts

@@ -0,0 +1,346 @@
+import { execFileSync } from 'node:child_process';
+import { createServer as createTcpServer } from 'node:net';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import {
+  createStandaloneRuntimeAssetBinding,
+  type RuntimeAssetBinding,
+} from '@forgeax/engine-types';
+import { createServer, loadConfigFromFile } from 'vite';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createDevImportTransport } from '../dev-import-transport';
+import { constructRuntimeRendererHost } from '../renderer-host';
+import {
+  assertMaterialPayload,
+  assertSurfacePixelFalsification,
+  parseSurfaceGuid,
+  populateSurfaceWorld,
+  SURFACE_CASES,
+  SURFACE_CLOSURE,
+  SURFACE_HEIGHT,
+  SURFACE_WIDTH,
+} from './surface-standard-pipeline.runtime-fixture';
+
+const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const EVIDENCE_SOURCE_SHA = execFileSync('git', ['rev-parse', 'HEAD'], {
+  cwd: rootDir,
+  encoding: 'utf8',
+}).trim();
+const EVIDENCE_BUILD_ID = `vitest-dawn-${EVIDENCE_SOURCE_SHA.slice(0, 12)}`;
+
+async function loadPreviewConfig() {
+  const previousSurfaceOnly = process.env.FORGEAX_SURFACE_ONLY;
+  process.env.FORGEAX_SURFACE_ONLY = '1';
+  try {
+    const loaded = await loadConfigFromFile(
+      { command: 'serve', mode: 'test', isSsrBuild: false, isPreview: false },
+      resolve(rootDir, 'apps/preview/vite.config.ts'),
+      rootDir,
+    );
+    if (loaded === null) throw new Error('surface-standard: Preview Vite config unavailable');
+    return loaded.config;
+  } finally {
+    if (previousSurfaceOnly === undefined) delete process.env.FORGEAX_SURFACE_ONLY;
+    else process.env.FORGEAX_SURFACE_ONLY = previousSurfaceOnly;
+  }
+}
+
+async function allocateLoopbackPort(): Promise<number> {
+  const probe = createTcpServer();
+  try {
+    await new Promise<void>((resolveListen, rejectListen) => {
+      const onError = (error: Error): void => {
+        probe.off('listening', onListening);
+        rejectListen(error);
+      };
+      const onListening = (): void => {
+        probe.off('error', onError);
+        resolveListen();
+      };
+      probe.once('error', onError);
+      probe.once('listening', onListening);
+      probe.listen(0, '127.0.0.1');
+    });
+    const address = probe.address();
+    if (address === null || typeof address === 'string') {
+      throw new Error('surface-standard: loopback port probe did not expose a TCP address');
+    }
+    expect(address.port).toBeGreaterThan(0);
+    return address.port;
+  } finally {
+    if (probe.listening) {
+      await new Promise<void>((resolveClose) => probe.close(() => resolveClose()));
+    }
+  }
+}
+
+const BYTES_PER_ROW = Math.ceil((SURFACE_WIDTH * 4) / 256) * 256;
+const TEXTURE_USAGE_COPY_SRC = 0x01;
+const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
+const BUFFER_USAGE_MAP_READ = 0x0001;
+const BUFFER_USAGE_COPY_DST = 0x0008;
+const MAP_MODE_READ = 0x0001;
+const DAWN_TEARDOWN_TIMEOUT_MS = 60_000;
+
+type DawnCanvas = HTMLCanvasElement & { target?: GPUTexture };
+
+function absoluteBinding(binding: RuntimeAssetBinding, baseUrl: string): RuntimeAssetBinding {
+  return {
+    ...binding,
+    catalogUrl: new URL(binding.catalogUrl, baseUrl).href,
+    importUrlBase: new URL(binding.importUrlBase, baseUrl).href,
+    packageUrlBase: new URL(binding.packageUrlBase, baseUrl).href,
+  };
+}
+
+function createDawnCanvas(onDevice: (device: GPUDevice) => void): DawnCanvas {
+  const canvas = {
+    width: SURFACE_WIDTH,
+    height: SURFACE_HEIGHT,
+    getContext(kind: string): unknown {
+      if (kind !== 'webgpu') return null;
+      return {
+        configure(descriptor: { device: GPUDevice; format?: GPUTextureFormat }) {
+          onDevice(descriptor.device);
+          canvas.target = descriptor.device.createTexture({
+            size: { width: SURFACE_WIDTH, height: SURFACE_HEIGHT, depthOrArrayLayers: 1 },
+            format: descriptor.format ?? 'rgba8unorm',
+            usage: TEXTURE_USAGE_RENDER_ATTACHMENT | TEXTURE_USAGE_COPY_SRC,
+            viewFormats: ['rgba8unorm-srgb'],
+          });
+        },
+        unconfigure() {},
+        getCurrentTexture() {
+          if (canvas.target === undefined)
+            throw new Error('surface-standard: target not configured');
+          return canvas.target;
+        },
+      };
+    },
+    addEventListener() {},
+    removeEventListener() {},
+  } as unknown as DawnCanvas;
+  return canvas;
+}
+
+async function readPresentedPixels(device: GPUDevice, texture: GPUTexture): Promise<Uint8Array> {
+  const buffer = device.createBuffer({
+    size: BYTES_PER_ROW * SURFACE_HEIGHT,
+    usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST,
+  });
+  const encoder = device.createCommandEncoder();
+  encoder.copyTextureToBuffer(
+    { texture },
+    { buffer, bytesPerRow: BYTES_PER_ROW, rowsPerImage: SURFACE_HEIGHT },
+    { width: SURFACE_WIDTH, height: SURFACE_HEIGHT, depthOrArrayLayers: 1 },
+  );
+  device.queue.submit([encoder.finish()]);
+  await device.queue.onSubmittedWorkDone();
+  await buffer.mapAsync(MAP_MODE_READ);
+  const pixels = new Uint8Array(buffer.getMappedRange().slice(0));
+  buffer.unmap();
+  buffer.destroy();
+  return pixels;
+}
+
+function samplePresentedPixel(
+  pixels: Uint8Array,
+  index: number,
+): readonly [number, number, number, number] {
+  const x = Math.min(
+    SURFACE_WIDTH - 1,
+    Math.max(0, Math.floor(((index + 0.5) * SURFACE_WIDTH) / SURFACE_CASES.length)),
+  );
+  const offset = Math.floor(SURFACE_HEIGHT / 2) * BYTES_PER_ROW + x * 4;
+  return [
+    pixels[offset] ?? 0,
+    pixels[offset + 1] ?? 0,
+    pixels[offset + 2] ?? 0,
+    pixels[offset + 3] ?? 0,
+  ];
+}
+
+describe('Standard Surface runtime Dawn publication', () => {
+  let renderer: Renderer | undefined;
+  let server: Awaited<ReturnType<typeof createServer>> | undefined;
+  let canvas: DawnCanvas | undefined;
+  let device: GPUDevice | undefined;
+
+  afterEach(async () => {
+    await renderer?.dispose();
+    if (canvas?.target !== undefined) canvas.target.destroy();
+    device?.destroy();
+    await server?.close();
+    renderer = undefined;
+    canvas = undefined;
+    device = undefined;
+    server = undefined;
+  }, DAWN_TEARDOWN_TIMEOUT_MS);
+
+  it('publishes and renders the same four cooked GUIDs through Dawn Runtime Renderer', async () => {
+    const binding = createStandaloneRuntimeAssetBinding('preview');
+    const previewInlineConfig = await loadPreviewConfig();
+    const previewServer = {
+      host: '127.0.0.1',
+      port: await allocateLoopbackPort(),
+      strictPort: true,
+      ...(previewInlineConfig.server?.fs === undefined
+        ? {}
+        : { fs: previewInlineConfig.server.fs }),
+    };
+    server = await createServer({
+      ...previewInlineConfig,
+      configFile: false,
+      root: resolve(rootDir, 'apps/preview'),
+      logLevel: 'error',
+      server: previewServer,
+    });
+    await server.listen();
+    const baseUrl = server.resolvedUrls?.local[0];
+    if (baseUrl === undefined)
+      throw new Error('surface-standard: Dawn publication server URL unavailable');
+    const liveBinding = absoluteBinding(binding, baseUrl);
+    const shaderManifestUrl = new URL('shaders/manifest.json', baseUrl).href;
+    canvas = createDawnCanvas((created) => {
+      device ??= created;
+    });
+    const constructed = await constructRuntimeRendererHost(
+      canvas,
+      {},
+      {
+        shaderManifestUrl,
+        importTransport: createDevImportTransport(liveBinding),
+      },
+    );
+    expect(constructed.ok).toBe(true);
+    if (!constructed.ok) throw constructed.error;
+    renderer = constructed.value.renderer;
+    const assets = constructed.value.assets;
+    assets.configureRuntimeBinding(liveBinding);
+    const catalogDeadline = Date.now() + 180_000;
+    while (!(await assets.refreshCatalog())) {
+      if (Date.now() >= catalogDeadline) {
+        throw new Error(
+          `surface-standard: timed out waiting for catalog ${liveBinding.catalogUrl}`,
+        );
+      }
+      await new Promise<void>((resolveWait) => setTimeout(resolveWait, 100));
+    }
+    const catalog = assets.listCatalog();
+    const materials: MaterialAsset[] = [];
+    const publications = [];
+    for (const surfaceCase of SURFACE_CASES) {
+      const row = catalog.find((entry) => entry.guid.toLowerCase() === surfaceCase.guid);
+      expect(row?.sourceKey).toBe(surfaceCase.sourceKey);
+      expect(row?.packageUrl).toMatch(/^http/);
+      const publicationResponse = await fetch(row?.packageUrl ?? '');
+      expect(publicationResponse.ok).toBe(true);
+      const publication = (await publicationResponse.json()) as {
+        generation?: unknown;
+        digest?: unknown;
+      };
+      expect(Number.isSafeInteger(publication.generation)).toBe(true);
+      expect(typeof publication.digest).toBe('string');
+      const loaded = await assets.loadByGuid<MaterialAsset>(parseSurfaceGuid(surfaceCase.guid));
+      expect(loaded.ok).toBe(true);
+      if (!loaded.ok) throw loaded.error;
+      const material = assertMaterialPayload(surfaceCase, loaded.value);
+      materials.push(material);
+      publications.push({ surfaceCase, row, publication, material });
+    }
+    const world = new World();
+    populateSurfaceWorld(world, materials);
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) throw attached.error;
+    // Standard material pipelines are compiled lazily on first use. Submit
+    // enough frames for the authored Surface artifacts to publish their PSOs
+    // before taking the Dawn readback, matching the browser evidence lane.
+    for (let frame = 0; frame < 6; frame += 1) {
+      world.update(1 / 60).unwrap();
+      const drawn = renderer.draw({
+        leases: [attached.value],
+        camera: { lease: attached.value },
+        environment: { lease: attached.value },
+      });
+      expect(drawn.ok).toBe(true);
+      if (!drawn.ok) throw drawn.error;
+      const completion = await drawn.value.completed;
+      expect(completion.ok).toBe(true);
+      if (!completion.ok) throw completion.error;
+    }
+    if (device === undefined || canvas.target === undefined)
+      throw new Error('surface-standard: Dawn target unavailable');
+    const pixels = await readPresentedPixels(device, canvas.target);
+    const observed = renderer.inspect();
+    expect(observed.perFramePassNames.some((name) => name.toLowerCase().includes('shadow'))).toBe(
+      true,
+    );
+    expect(observed.perFramePassNames).toContain('main');
+    const records = publications.map(({ surfaceCase, row, publication, material }, index) => {
+      const samples = samplePresentedPixel(pixels, index);
+      const program = material.passes?.[0]?.program;
+      expect(samples[3]).toBe(255);
+      expect(samples[0] + samples[1] + samples[2]).toBeGreaterThan(0);
+      return {
+        id: surfaceCase.id,
+        materialGuid: surfaceCase.guid,
+        sourceKey: row?.sourceKey,
+        publicationGeneration: publication.generation,
+        publicationDigest: publication.digest,
+        closure: SURFACE_CLOSURE,
+        rootPlan: surfaceCase.rootPlan,
+        pass: surfaceCase.pass,
+        actualPasses: material.passes?.map((entry) => entry.name),
+        selectedEntries: material.passes?.map((entry) => ({
+          name: entry.name,
+          fragmentEntry: entry.program.fragmentEntry,
+          lightMode: (entry.renderState?.tags as Record<string, string> | undefined)?.LightMode,
+        })),
+        cookIdentity: publication.digest,
+        programIdentity: program?.module ?? 'unavailable',
+        pipelineIdentity: `${surfaceCase.pass}:${surfaceCase.rootPlan}:${program?.module ?? 'unavailable'}`,
+        sourceClosure: surfaceCase.sourceClosure,
+        backend: 'dawn-native',
+        backendKind: observed.capabilities.backendKind,
+        frameId: observed.observation.frameId,
+        samples,
+        artifact: row?.packageUrl,
+        provenance: {
+          sourceSha: EVIDENCE_SOURCE_SHA,
+          buildId: EVIDENCE_BUILD_ID,
+          frameId: observed.observation.frameId,
+          artifact: row?.packageUrl,
+          readbackKind: 'gpu-texture-copy',
+          readbackFormat: 'rgba8unorm',
+          readbackWidth: SURFACE_WIDTH,
+          readbackHeight: SURFACE_HEIGHT,
+          clearColor: [0, 0, 0, 1],
+          closure: SURFACE_CLOSURE,
+          rootPlan: surfaceCase.rootPlan,
+          pass: surfaceCase.pass,
+          actualPasses: material.passes?.map((entry) => entry.name),
+          selectedEntries: material.passes?.map((entry) => ({
+            name: entry.name,
+            fragmentEntry: entry.program.fragmentEntry,
+            lightMode: (entry.renderState?.tags as Record<string, string> | undefined)?.LightMode,
+          })),
+          cookIdentity: publication.digest,
+          programIdentity: program?.module ?? 'unavailable',
+          pipelineIdentity: `${surfaceCase.pass}:${surfaceCase.rootPlan}:${program?.module ?? 'unavailable'}`,
+          sourceClosure: surfaceCase.sourceClosure,
+          lane: 'dawn-native',
+        },
+      };
+    });
+    assertSurfacePixelFalsification(records);
+    expect(new Set(records.map((record) => record.materialGuid))).toHaveLength(4);
+    expect(records.every((record) => record.backend === 'dawn-native')).toBe(true);
+    expect(records.every((record) => record.backendKind === 'webgpu')).toBe(true);
+    // biome-ignore lint/suspicious/noConsole: runtime provenance is the test artifact.
+    console.log(JSON.stringify({ backend: 'dawn-native', lane: 'runtime', records }));
+  }, 120000);
+});

package/src/__tests__/surface-standard-pipeline.runtime-fixture.ts

@@ -0,0 +1,184 @@
+import type { World } from '@forgeax/engine-ecs';
+import { createPlaneGeometry } from '@forgeax/engine-geometry';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { Camera, DirectionalLight, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { surfaceEvidenceGuid } from '../../../../apps/preview/src/surface-standard-evidence-identity';
+import {
+  assetGuid,
+  PACKAGE_IDS,
+  RUSTED_IRON_MATERIAL_GUID,
+} from '../../../../templates/game-3d/assets/shared/asset-refs';
+
+export const SURFACE_CLOSURE = 'forgeax_material::surface_v1';
+export const SURFACE_WIDTH = 960;
+export const SURFACE_HEIGHT = 540;
+export const SURFACE_PIXEL_EPSILON = 0.05;
+
+export const SURFACE_CASES = [
+  {
+    id: 'default-base',
+    guid: AssetGuid.format(assetGuid(PACKAGE_IDS.materials, 'material/ground')),
+    sourceKey: 'material/ground',
+    sourceClosure: ['templates/game-3d/assets/materials.pack.ts'],
+    pass: 'deferred',
+    rootPlan: 'base-deferred',
+  },
+  {
+    id: 'custom-base',
+    guid: AssetGuid.format(RUSTED_IRON_MATERIAL_GUID),
+    sourceKey: 'material/rusted-iron',
+    sourceClosure: [
+      'templates/game-3d/assets/materials.pack.ts',
+      'templates/game-3d/assets/shaders/rusted-iron.wgsl',
+    ],
+    pass: 'deferred',
+    rootPlan: 'base-deferred',
+  },
+  {
+    id: 'default-physical',
+    guid: surfaceEvidenceGuid('material/painted-evidence'),
+    sourceKey: 'material/painted-evidence',
+    sourceClosure: ['apps/preview/assets/surface-standard-evidence.pack.ts'],
+    pass: 'forward',
+    rootPlan: 'physical-forward',
+  },
+  {
+    id: 'custom-physical',
+    guid: surfaceEvidenceGuid('material/rusted-iron-custom-physical'),
+    sourceKey: 'material/rusted-iron-custom-physical',
+    sourceClosure: [
+      'apps/preview/assets/surface-standard-evidence.pack.ts',
+      'templates/game-3d/assets/shaders/rusted-iron.wgsl',
+    ],
+    pass: 'forward',
+    rootPlan: 'physical-forward',
+  },
+] as const;
+
+export type SurfaceCase = (typeof SURFACE_CASES)[number];
+
+export function parseSurfaceGuid(guid: string): AssetGuid {
+  const parsed = AssetGuid.parse(guid);
+  if (!parsed.ok) throw new Error(`surface-standard: invalid fixture GUID ${guid}`);
+  return parsed.value;
+}
+
+export function assertMaterialPayload(
+  surfaceCase: SurfaceCase,
+  material: MaterialAsset,
+): MaterialAsset {
+  if (material.passes === undefined || material.passes.length === 0) {
+    throw new Error(`surface-standard: ${surfaceCase.id} has no cooked passes`);
+  }
+  const expectedSurfaceModule = surfaceCase.id.includes('custom')
+    ? 'game_3d::rusted_iron_surface'
+    : 'forgeax_material::default_standard_surface';
+  const firstPass = material.passes[0];
+  if (firstPass?.program.module !== 'forgeax_material::standard') {
+    throw new Error(`surface-standard: ${surfaceCase.id} selected a non-Standard program`);
+  }
+  if (firstPass.program.moduleSlots?.surface !== expectedSurfaceModule) {
+    throw new Error(
+      `surface-standard: ${surfaceCase.id} Surface module mismatch; expected ${expectedSurfaceModule} observed ${firstPass.program.moduleSlots?.surface ?? '<missing>'}`,
+    );
+  }
+  const passNames = material.passes.map((pass) => pass.name);
+  const expectedPasses =
+    surfaceCase.pass === 'deferred'
+      ? ['forward', 'deferred', 'shadow-caster']
+      : ['forward', 'shadow-caster'];
+  if (
+    passNames.length !== expectedPasses.length ||
+    expectedPasses.some((name, index) => passNames[index] !== name)
+  ) {
+    throw new Error(
+      `surface-standard: ${surfaceCase.id} pass policy mismatch; expected ${expectedPasses.join(',')} observed ${passNames.join(',')}`,
+    );
+  }
+  const expectedEntries = expectedPasses.map((name) => ({
+    name,
+    fragmentEntry:
+      name === 'forward' ? 'fs_main' : name === 'deferred' ? 'fs_gbuffer' : 'fs_shadow',
+    lightMode: name === 'forward' ? 'Forward' : name === 'deferred' ? 'Deferred' : 'ShadowCaster',
+  }));
+  for (const [index, expected] of expectedEntries.entries()) {
+    const actual = material.passes[index];
+    const actualLightMode = (actual?.renderState?.tags as Record<string, string> | undefined)
+      ?.LightMode;
+    if (
+      actual?.program.fragmentEntry !== expected.fragmentEntry ||
+      actualLightMode !== expected.lightMode
+    ) {
+      throw new Error(
+        `surface-standard: ${surfaceCase.id} entry mismatch at ${expected.name}; expected ${expected.fragmentEntry}/${expected.lightMode}`,
+      );
+    }
+  }
+  return material;
+}
+
+export function assertSurfacePixelFalsification(
+  records: readonly {
+    readonly id: string;
+    readonly samples: readonly [number, number, number, number];
+  }[],
+): void {
+  const byId = new Map(records.map((record) => [record.id, record.samples]));
+  const distance = (left: readonly number[], right: readonly number[]) =>
+    Math.max(...left.slice(0, 3).map((value, index) => Math.abs(value - (right[index] ?? 0)))) /
+    255;
+  for (const [customId, defaultId] of [
+    ['custom-base', 'default-base'],
+    ['custom-physical', 'default-physical'],
+  ] as const) {
+    const custom = byId.get(customId);
+    const baseline = byId.get(defaultId);
+    if (custom === undefined || baseline === undefined) {
+      throw new Error(
+        `surface-standard: pixel falsification pair missing (${defaultId}, ${customId})`,
+      );
+    }
+    if (distance(custom, baseline) <= SURFACE_PIXEL_EPSILON) {
+      throw new Error(
+        `surface-standard: ${customId} is pixel-identical to ${defaultId}; custom Surface was not observed`,
+      );
+    }
+  }
+}
+
+export function populateSurfaceWorld(world: World, materials: readonly MaterialAsset[]): void {
+  const plane = createPlaneGeometry(1.3, 1.3);
+  if (!plane.ok) throw new Error(`surface-standard: plane geometry failed: ${plane.error.code}`);
+  const mesh = world.allocSharedRef('MeshAsset', plane.value);
+  for (const [index, material] of materials.entries()) {
+    const handle = world.allocSharedRef('MaterialAsset', material);
+    world.spawn(
+      { component: Transform, data: { pos: [(index - 1.5) * 1.45, 0, 0] } },
+      { component: MeshFilter, data: { assetHandle: mesh } },
+      { component: MeshRenderer, data: { materials: [handle] } },
+    );
+  }
+  world.spawn(
+    { component: Transform, data: { pos: [0, 0, 4] } },
+    {
+      component: Camera,
+      data: {
+        fov: Math.PI / 4,
+        aspect: SURFACE_WIDTH / SURFACE_HEIGHT,
+        near: 0.1,
+        far: 20,
+        clearColor: [0, 0, 0, 1],
+      },
+    },
+  );
+  world.spawn({
+    component: DirectionalLight,
+    data: { direction: [0, 0, -1], color: [1, 1, 1], intensity: 1, castShadow: true },
+  });
+  // The standalone renderer host does not install scenePlugin for this
+  // fixture. Publish the authored local transforms before extract so the
+  // camera and four cells reach the real render path with their world poses.
+  propagateTransforms(world).unwrap();
+}

package/src/__tests__/surface-standard-pipeline.vite.d.ts

@@ -0,0 +1,12 @@
+declare module 'virtual:forgeax/bundler' {
+  export function forgeaxBundlerAdapter(): import('@forgeax/engine-app').BundlerAdapter;
+}
+
+declare module 'virtual:forgeax/pack-runtime' {
+  import type { ImportTransport, RuntimeAssetBinding } from '@forgeax/engine-types';
+
+  export const runtimeBinding: RuntimeAssetBinding | undefined;
+  export function createRuntimeAssetImportTransport(
+    binding?: RuntimeAssetBinding,
+  ): ImportTransport | undefined;
+}

package/src/__tests__/tonemap-hdr-target.cases.unit.test.ts

@@ -407,7 +407,13 @@ type __MergedKeep =
       __mockTag: 'gpu-device',
       lost,
       features: new Set(),
-      limits: {},
+      // Model a native WebGPU device: the test below asserts the preferred
+      // swap-chain format selected by the storage-buffer path. An empty limits
+      // object describes a downlevel device and correctly selects the rgba
+      // fallback instead.
+      limits: {
+        maxStorageBuffersPerShaderStage: 8,
+      },
       queue: {
         submit: () => undefined,
         writeBuffer: () => undefined,