@forgeax/engine-runtime 0.1.27 → 0.1.29

package/src/__tests__/material-publication.fixture.ts

@@ -0,0 +1,349 @@
+import { World } from '@forgeax/engine-ecs';
+import { createBoxGeometry } from '@forgeax/engine-geometry';
+import { AssetGuid } from '@forgeax/engine-pack';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { attachRecorder, buildFrameModel, decodeTape } from '@forgeax/engine-rhi-debug';
+import { Transform } from '@forgeax/engine-scene';
+import type { MaterialAsset, PackIndexEntry, RuntimeAssetBinding } from '@forgeax/engine-types';
+import { ok } from '@forgeax/engine-types';
+import { expect } from 'vitest';
+import { loadBackendPack } from '../backend-selection';
+import { createDevImportTransport } from '../dev-import-transport';
+import { constructRuntimeRendererHost } from '../renderer-host';
+
+const inspect = (value: unknown) =>
+  JSON.stringify(value, (_key, item) =>
+    item instanceof Error ? { ...item, message: item.message } : item,
+  );
+
+export async function verifyMaterialPublication(options: {
+  readonly binding: RuntimeAssetBinding;
+  readonly guids: readonly string[];
+  readonly shaderManifestUrl: string;
+  readonly update: (value: 'red' | 'blue' | 'broken') => Promise<void>;
+  readonly saveTape?: (bytes: Uint8Array) => void;
+}) {
+  const errors: unknown[] = [];
+  let device: GPUDevice | undefined;
+  let target: GPUTexture | undefined;
+  let surfaceFormat: GPUTextureFormat = 'rgba8unorm';
+  const canvas = {
+    width: 64,
+    height: 64,
+    getContext: () => ({
+      configure(config: GPUCanvasConfiguration) {
+        device = config.device;
+        surfaceFormat = config.format;
+        device.addEventListener('uncapturederror', (event) => errors.push(event.error.message));
+        target = device.createTexture({
+          size: [64, 64],
+          format: config.format,
+          viewFormats: [config.format === 'bgra8unorm' ? 'bgra8unorm-srgb' : 'rgba8unorm-srgb'],
+          usage: 0x10 | 0x01,
+        });
+      },
+      unconfigure() {},
+      getCurrentTexture: () => target,
+    }),
+    addEventListener() {},
+    removeEventListener() {},
+  };
+  const transport = createDevImportTransport(options.binding);
+  const backend = await loadBackendPack({});
+  if (!backend.ok) throw backend.error;
+  if (backend.value.createShaderModule === undefined)
+    throw new Error('missing backend shader factory');
+  const recording = attachRecorder({
+    ...backend.value,
+    createShaderModule: backend.value.createShaderModule,
+  });
+  if (!recording.ok) throw recording.error;
+  const recorder = recording.value;
+  const constructed = await constructRuntimeRendererHost(
+    canvas,
+    {
+      rhi: recorder.backend.rhi,
+      rhiInstrumentation: {
+        resolveSurfaceDevice(device) {
+          const unwrapped = recorder.backend.unwrapDeviceForSurface(device);
+          if (!unwrapped.ok) throw unwrapped.error;
+          return ok(unwrapped.value);
+        },
+      },
+    },
+    {
+      shaderManifestUrl: options.shaderManifestUrl,
+      importTransport: transport,
+    },
+  );
+  if (!constructed.ok) throw constructed.error;
+  const { renderer, assets } = constructed.value;
+  renderer.subscribe((event) => {
+    if (event.kind === 'error') errors.push(event.error);
+  });
+  assets.configureRuntimeBinding(options.binding);
+  const world = new World();
+  try {
+    const catalog = async () => {
+      const response = await fetch(options.binding.catalogUrl);
+      const body = (await response.json()) as {
+        authority: string;
+        entries: PackIndexEntry[];
+        diagnostics?: unknown[];
+      };
+      return body;
+    };
+    const baseline = await catalog();
+    expect(baseline.authority, inspect(baseline)).toBe('authoritative');
+    expect(baseline.entries).toHaveLength(3);
+    const firstGuid = options.guids[0];
+    const childGuid = options.guids[1];
+    const otherGuid = options.guids[2];
+    if (firstGuid === undefined || childGuid === undefined || otherGuid === undefined)
+      throw new Error('missing fixture identity');
+    const firstRow = baseline.entries.find((row) => row.guid === firstGuid);
+    const otherRow = baseline.entries.find((row) => row.guid === otherGuid);
+    if (firstRow === undefined || otherRow === undefined)
+      throw new Error('missing material Catalog row');
+    const transportResult = await transport.fetchPack(firstGuid, options.binding);
+    expect(transportResult.ok, inspect(transportResult)).toBe(true);
+    const packUrl = new URL(firstRow.packageUrl, options.binding.catalogUrl).href;
+    const pack = await (await fetch(packUrl)).json();
+    const row = pack.assets.find((asset: { guid: string }) => asset.guid === firstGuid);
+    const descriptors = Object.values(row.artifacts) as { path: string; byteLength: number }[];
+    const cooked = (
+      row.payload as {
+        cooked: {
+          programs: readonly {
+            specializationKey: string;
+            artifact: { path: string };
+          }[];
+        };
+      }
+    ).cooked;
+    // Material publication is a complete multi-program set: each compiled pass
+    // owns one independently addressable raw WGSL artifact.
+    expect(cooked.programs).toHaveLength(3);
+    expect(descriptors).toHaveLength(cooked.programs.length);
+    const publishedSources = new Map<string, string>();
+    for (const descriptor of descriptors) {
+      const program = cooked.programs.find(
+        (candidate) =>
+          descriptor.path === candidate.artifact.path ||
+          descriptor.path.endsWith(`/${candidate.artifact.path}`),
+      );
+      if (program === undefined) throw new Error(`missing program for ${descriptor.path}`);
+      const response = await fetch(new URL(descriptor.path, packUrl));
+      expect(response.status).toBe(200);
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      expect(bytes.byteLength).toBe(descriptor.byteLength);
+      publishedSources.set(program.specializationKey, new TextDecoder().decode(bytes));
+    }
+    const load = async (guid: string) => {
+      const parsed = AssetGuid.parse(guid);
+      if (!parsed.ok) throw parsed.error;
+      const loaded = await assets.loadByGuid<MaterialAsset>(parsed.value);
+      if (!loaded.ok) throw loaded.error;
+      return loaded.value;
+    };
+    const first = await load(firstGuid);
+    const inherited = await load(childGuid);
+    const other = await load(otherGuid);
+    const firstProjection = assets.getMaterialProjectionForPayload(first);
+    if (firstProjection === undefined) throw new Error('missing first material projection');
+    const shadow = assets.shaderRegistry.findMaterialArtifact('forgeax::default-shadow-caster');
+    if (!shadow.ok) throw shadow.error;
+    for (const program of cooked.programs)
+      expect(assets.shaderRegistry.findMaterialArtifact(program.specializationKey)).toMatchObject({
+        ok: true,
+        value: { source: publishedSources.get(program.specializationKey) },
+      });
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 3], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+    const entity = world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+        {
+          component: MeshFilter,
+          data: {
+            assetHandle: world.allocSharedRef('MeshAsset', createBoxGeometry(1, 1, 1).unwrap()),
+          },
+        },
+        {
+          component: MeshRenderer,
+          data: { materials: [world.allocSharedRef('MaterialAsset', first)] },
+        },
+      )
+      .unwrap();
+    const attached = renderer.attach(world);
+    if (!attached.ok) throw attached.error;
+    const lease = attached.value;
+    const sample = async (material: MaterialAsset) => {
+      world
+        .set(entity, MeshRenderer, {
+          materials: [world.internSharedRef('MaterialAsset', material)],
+        })
+        .unwrap();
+      for (let frame = 0; frame < 15; frame++) {
+        const capture = frame === 14 ? recorder.captureFrame() : undefined;
+        if (capture !== undefined) {
+          const before = await recorder.frameBoundary();
+          if (!before.ok) throw before.error;
+        }
+        world.update().unwrap();
+        const result = renderer.draw({
+          leases: [lease],
+          camera: { lease },
+          environment: { lease },
+        });
+        if (!result.ok) throw result.error;
+        if (capture !== undefined) {
+          const after = await recorder.frameBoundary();
+          if (!after.ok) throw after.error;
+          const captured = await capture;
+          if (!captured.ok) throw captured.error;
+          options.saveTape?.(captured.value.bytes);
+          const decoded = decodeTape(captured.value.bytes);
+          if (!decoded.ok) throw decoded.error;
+          expect(
+            buildFrameModel(decoded.value).works.some(
+              (work) => work.kind === 'draw' || work.kind === 'drawIndexed',
+            ),
+          ).toBe(true);
+        }
+        await new Promise<void>((resolve) => setTimeout(resolve, 0));
+      }
+      if (device === undefined || target === undefined) throw new Error('missing real GPU target');
+      const buffer = device.createBuffer({ size: 256, usage: 0x08 | 0x01 });
+      try {
+        const encoder = device.createCommandEncoder();
+        encoder.copyTextureToBuffer(
+          { texture: target, origin: [32, 32] },
+          { buffer, bytesPerRow: 256 },
+          [1, 1],
+        );
+        device.queue.submit([encoder.finish()]);
+        await buffer.mapAsync(0x01);
+        const pixel = [...new Uint8Array(buffer.getMappedRange()).slice(0, 4)];
+        buffer.unmap();
+        if (surfaceFormat === 'bgra8unorm') [pixel[0], pixel[2]] = [pixel[2] ?? 0, pixel[0] ?? 0];
+        expect(errors, inspect(errors)).toEqual([]);
+        return pixel;
+      } finally {
+        buffer.destroy();
+      }
+    };
+    const red = await sample(first);
+    expect(red[0]).toBeGreaterThan(150);
+    expect(red[2]).toBeLessThan(5);
+    expect(await sample(inherited)).toEqual(red);
+    const overlay = first.passes?.find((pass) => pass.name === 'Overlay');
+    if (overlay === undefined) throw new Error('missing independent Overlay pass');
+    const projection = assets.getMaterialProjectionForPayload(first);
+    const overlayProgram = projection?.passes.find((pass) => pass.name === overlay.name)
+      ?.programs[0];
+    if (overlayProgram === undefined) throw new Error('missing published Overlay program');
+    const overlayMaterial: MaterialAsset = {
+      ...first,
+      passes: [
+        {
+          ...overlay,
+          program: { ...overlay.program, module: overlayProgram.specializationKey },
+          renderState: { ...overlay.renderState, tags: { LightMode: 'Forward' } },
+        },
+      ],
+    };
+    const green = await sample(overlayMaterial);
+    expect(green[0]).toBeLessThan(5);
+    expect(green[1]).toBeGreaterThan(150);
+    expect(green[2]).toBeLessThan(5);
+    const waitFor = async (accept: (value: Awaited<ReturnType<typeof catalog>>) => boolean) => {
+      const deadline = Date.now() + 20_000;
+      while (Date.now() < deadline) {
+        const next = await catalog();
+        if (accept(next)) return next;
+        await new Promise<void>((resolve) => setTimeout(resolve, 50));
+      }
+      const last = await catalog();
+      throw new Error(
+        `material publication did not settle: ${inspect({
+          authority: last.authority,
+          entries: last.entries.map((row) => ({
+            guid: row.guid,
+            revision: row.revision,
+            lifecycle: row.lifecycle,
+          })),
+          diagnostics: last.diagnostics,
+        })}`,
+      );
+    };
+    await options.update('blue');
+    const changed = await waitFor(
+      (next) =>
+        next.authority === 'authoritative' &&
+        next.entries.some(
+          (row) => row.guid === firstGuid && row.packageUrl !== firstRow.packageUrl,
+        ),
+    );
+    expect(changed.entries.find((row) => row.guid === otherGuid)?.packageUrl).toBe(
+      otherRow.packageUrl,
+    );
+    assets.invalidate(firstGuid);
+    const revised = await load(firstGuid);
+    expect(await load(otherGuid)).toBe(other);
+    const revisedProjection = assets.getMaterialProjectionForPayload(revised);
+    if (revisedProjection === undefined) throw new Error('missing revised material projection');
+    // Authored pass modules remain stable semantic identities. Dependency
+    // invalidation is observed through the immutable cooked publication key,
+    // which is what the renderer selects for the new payload generation.
+    expect(revisedProjection.specializationKey).not.toBe(firstProjection.specializationKey);
+    expect(revised.passes?.find((pass) => pass.name === 'Overlay')?.program.module).toBe(
+      overlay.program.module,
+    );
+    const blue = await sample(revised);
+    expect(blue[2]).toBeGreaterThan(150);
+    expect(blue[0]).toBeLessThan(5);
+    expect(await sample(first)).toEqual(red); // Previous live program remains owned.
+    expect(await sample(overlayMaterial)).toEqual(green);
+    expect(assets.shaderRegistry.findMaterialArtifact('forgeax::default-shadow-caster')).toEqual(
+      shadow,
+    );
+    await options.update('broken');
+    await waitFor((next) => next.authority !== 'authoritative');
+    const lastGood = await fetch(
+      new URL(
+        changed.entries.find((row) => row.guid === firstGuid)?.packageUrl ?? '',
+        options.binding.catalogUrl,
+      ),
+    );
+    // A failed producer preserves accepted bytes and live resources; a new
+    // lazy import remains fenced until the author repairs the source.
+    expect(lastGood.status).toBe(200);
+    expect(
+      (await fetch(`${options.binding.importUrlBase}/${firstGuid}`, { method: 'POST' })).status,
+    ).toBe(409);
+    expect(await sample(revised)).toEqual(blue);
+    await options.update('red');
+    await waitFor(
+      (next) =>
+        next.authority === 'authoritative' &&
+        next.entries.some(
+          (row) => row.guid === firstGuid && row.packageUrl === firstRow.packageUrl,
+        ),
+    );
+    assets.invalidate(firstGuid);
+    expect(await sample(await load(firstGuid))).toEqual(red);
+    expect(errors, inspect(errors)).toEqual([]);
+  } finally {
+    const disposed = await renderer.dispose();
+    target?.destroy();
+    device?.destroy();
+    if (!disposed.ok) errors.push(disposed.error);
+    await recorder.dispose();
+  }
+  expect(errors, inspect(errors)).toEqual([]);
+}

package/src/__tests__/material-publication.server.ts

@@ -0,0 +1,109 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AssetGuid, PackageId } from '@forgeax/engine-pack/guid';
+import { createMaterialPackCooker } from '@forgeax/engine-shader-compiler';
+import { createStandaloneRuntimeAssetBinding } from '@forgeax/engine-types';
+import { pluginPack } from '@forgeax/engine-vite-plugin-pack';
+import { createServer } from 'vite';
+
+/** Real disk -> registered cooker -> Vite HTTP producer for both GPU backends. */
+export async function startMaterialPublicationServer() {
+  const root = await mkdtemp(join(tmpdir(), 'forgeax-material-publication-'));
+  const assets = join(root, 'assets');
+  await mkdir(assets);
+  const source = (
+    module: string,
+    color: string,
+    dependency = false,
+  ) => `#define_import_path ${module}
+#import forgeax_view::common::{view, meshes}
+${dependency ? '#import game::color::{shade}' : ''}
+@vertex fn vs_main(@location(0) pos: vec3<f32>, @builtin(instance_index) idx: u32) -> @builtin(position) vec4<f32> {
+  return view.worldViewProj * meshes[idx].worldFromLocal * vec4<f32>(pos, 1.0);
+}
+@fragment fn fs_main() -> @location(0) vec4<f32> { return ${dependency ? 'shade()' : `vec4<f32>(${color})`}; }
+`;
+  const update = (value: 'red' | 'blue' | 'broken') =>
+    writeFile(
+      join(assets, 'color.wgsl'),
+      `#define_import_path game::color\nfn shade() -> vec4<f32> { ${value === 'broken' ? 'broken' : `return vec4<f32>(${value === 'red' ? '1.0, 0.0, 0.0, 1.0' : '0.0, 0.0, 1.0, 1.0'});`} }\n`,
+    );
+  await update('red');
+  await writeFile(join(assets, 'first.wgsl'), source('game::first', '', true));
+  await writeFile(join(assets, 'overlay.wgsl'), source('game::overlay', '0.0, 1.0, 0.0, 1.0'));
+  await writeFile(join(assets, 'other.wgsl'), source('game::other', '1.0, 1.0, 0.0, 1.0'));
+  const guids: string[] = [];
+  for (const [index, name] of ['first', 'other'].entries()) {
+    const packageId = `019a0000-0000-7000-8000-00000000010${index}`;
+    const parsed = PackageId.parse(packageId);
+    if (!parsed.ok) throw parsed.error;
+    guids.push(AssetGuid.format(AssetGuid.derive(parsed.value, 'material/main')));
+    if (index === 0) guids.push(AssetGuid.format(AssetGuid.derive(parsed.value, 'material/child')));
+    const passes = [
+      {
+        name: 'Forward',
+        program: { module: `game::${name}`, vertexEntry: 'vs_main', fragmentEntry: 'fs_main' },
+        renderState: { tags: { LightMode: 'Forward' } },
+      },
+      ...(index === 0
+        ? [
+            {
+              name: 'Overlay',
+              program: {
+                module: 'game::overlay',
+                vertexEntry: 'vs_main',
+                fragmentEntry: 'fs_main',
+              },
+              renderState: { tags: { LightMode: 'Overlay' } },
+            },
+            {
+              name: 'ShadowCaster',
+              program: { module: 'forgeax::default-shadow-caster', vertexEntry: 'vs_main' },
+              renderState: { tags: { LightMode: 'ShadowCaster' } },
+            },
+          ]
+        : []),
+    ];
+    await writeFile(
+      join(assets, `${name}.pack.ts`),
+      `import { definePack, definePackageId } from '@forgeax/engine-pack/source';
+import { ok } from '@forgeax/engine-types';
+export default definePack({ schemaVersion: '2.0.0', packageId: definePackageId('${packageId}'),
+build() { return ok({ 'material/main': ${JSON.stringify({ kind: 'material', passes, parameters: [] })}
+${index === 0 ? `, 'material/child': { kind: 'material', parent: new Uint8Array(${JSON.stringify([...AssetGuid.derive(parsed.value, 'material/main')])}), values: {} }` : ''}
+}); } });\n`,
+    );
+  }
+  const binding = createStandaloneRuntimeAssetBinding('material-publication');
+  const plugin = pluginPack({
+    roots: [assets],
+    runtimeBinding: binding,
+    producerReadiness: 'on-demand',
+    cookers: [createMaterialPackCooker([assets])],
+    ddc: { projectDdcRoot: join(root, '.ddc') },
+  });
+  const server = await createServer({
+    root,
+    configFile: false,
+    logLevel: 'silent',
+    plugins: [plugin],
+    server: { host: '127.0.0.1', port: 0, cors: true },
+  });
+  await server.listen();
+  const baseUrl = server.resolvedUrls?.local[0];
+  if (baseUrl === undefined) throw new Error('Vite has no HTTP listener');
+  return {
+    binding: {
+      ...binding,
+      catalogUrl: new URL(binding.catalogUrl, baseUrl).href,
+      importUrlBase: new URL(binding.importUrlBase, baseUrl).href,
+    },
+    guids,
+    update,
+    async close() {
+      await server.close();
+      await rm(root, { recursive: true, force: true });
+    },
+  };
+}