@forgeax/engine-runtime 0.1.28 → 0.1.29

package/src/__tests__/gpu-resource-release.cases.unit.test.ts

@@ -573,6 +573,7 @@ type __MergedKeep =
 
   interface IntegrationComponents {
     Transform: unknown;
+    GlobalTransform: unknown;
     MeshFilter: unknown;
     MeshRenderer: unknown;
     Camera: unknown;
@@ -642,11 +643,15 @@ type __MergedKeep =
   }
 
   function spawnInstancedCube(
+    renderer: IntegrationRenderer,
     world: IntegrationWorld,
     C: IntegrationComponents,
     instanceCount: number,
-  ): unknown {
-    return world
+  ): { entity: unknown; collectionId: number } {
+    const collectionId = renderer.instances
+      .create({ transforms: new Float32Array(instanceCount * 16) })
+      .unwrap().collectionId as number;
+    const entity = world
       .spawn(
         { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
         { component: C.MeshRenderer, data: {} },
@@ -658,9 +663,11 @@ type __MergedKeep =
             scale: [1, 1, 1],
           },
         },
-        { component: C.Instances, data: { transforms: new Float32Array(instanceCount * 16) } },
+        { component: C.GlobalTransform, data: {} },
+        { component: C.Instances, data: { collectionId } },
       )
       .unwrap();
+    return { entity, collectionId };
   }
 
   // ── w14: AC-07 B-family error strategy ──
@@ -746,7 +753,7 @@ type __MergedKeep =
       const { renderer, world, C, errors } = await bootIntegrationRenderer(device);
 
       spawnCamera(world, C);
-      const cube = spawnInstancedCube(world, C, 2);
+      const cube = spawnInstancedCube(renderer, world, C, 2);
 
       // Frame 1: allocate the instance buffer (fingerprint = 2 instances).
       drawPublished(renderer, world as WorldType);
@@ -754,7 +761,7 @@ type __MergedKeep =
       // Frame 2: fingerprint mismatch -> F12 destroys the old buffer, whose
       // raw .destroy() throws -> rhi-webgpu webgpu-runtime-error -> the F12
       // production fires errorRegistry and continues to set the new buffer.
-      world.set(cube, C.Instances, { transforms: new Float32Array(3 * 16) });
+      renderer.instances.replace(cube.collectionId as never, new Float32Array(3 * 16));
       drawPublished(renderer, world as WorldType);
 
       // Sweep continued: a fresh (larger) instance buffer was still allocated
@@ -777,7 +784,7 @@ type __MergedKeep =
       const { renderer, world, C, errors } = await bootIntegrationRenderer(device);
 
       spawnCamera(world, C);
-      const cube = spawnInstancedCube(world, C, 2);
+      const cube = spawnInstancedCube(renderer, world, C, 2);
 
       // Frame 1: cold allocate the 2-instance buffer (256 B).
       drawPublished(renderer, world as WorldType);
@@ -792,7 +799,7 @@ type __MergedKeep =
       // 256 B buffer, then sets a fresh 384 B one. No shadow-caster shader is
       // registered, so recordShadowPass early-exits and the main pass is the
       // sole F12 owner this frame.
-      world.set(cube, C.Instances, { transforms: new Float32Array(3 * 16) });
+      renderer.instances.replace(cube.collectionId as never, new Float32Array(3 * 16));
       drawPublished(renderer, world as WorldType);
 
       // The destroyed buffer is specifically the old instance buffer (STORAGE
@@ -826,13 +833,13 @@ type __MergedKeep =
           mapSize: 1024,
         },
       });
-      const cube = spawnInstancedCube(world, C, 2);
+      const cube = spawnInstancedCube(renderer, world, C, 2);
 
       drawPublished(renderer, world as WorldType);
       expect(log.destroyed).toHaveLength(0);
       const oldInstanceBuffer = latestInstanceBuffer(log, 2);
 
-      world.set(cube, C.Instances, { transforms: new Float32Array(3 * 16) });
+      renderer.instances.replace(cube.collectionId as never, new Float32Array(3 * 16));
       drawPublished(renderer, world as WorldType);
 
       // The shadow pass records the instance entity before the main pass, so

package/src/__tests__/handle-migration.test.ts

@@ -43,7 +43,6 @@ describe('M5 handle-migration', () => {
         iboBytes: 0,
         indexCount: 0,
         indexFormat: 'uint16' as const,
-        layout: '12F' as const,
         vertexCount: 0,
         indexed: false,
         topology: 'triangle-list' as const,

package/src/__tests__/instances-renderer-lifecycle.integration.test.ts

@@ -87,6 +87,15 @@ it.each([
         requestDevice: async () => ok(++requests === 1 ? first : replacement),
       } as never),
   } as never;
+  const a = requireValue(
+    await constructRendererHost(canvas(), { rhi }, { shaderManifestUrl: manifest }),
+  ).renderer;
+  const b = requireValue(
+    await constructRendererHost(canvas(), { rhi: recoverable }, { shaderManifestUrl: manifest }),
+  ).renderer;
+  const collectionA = requireValue(a.instances.create({ transforms: matrices(0, count) }));
+  const collectionB = requireValue(b.instances.create({ transforms: matrices(0, count) }));
+  expect(collectionA.collectionId).toBe(collectionB.collectionId);
   const world = new World();
   const material = world.allocSharedRef('MaterialAsset', {
     kind: 'material',
@@ -99,12 +108,12 @@ it.each([
     ],
     values: { baseColor: [1, 0, 0] },
   });
-  const entity = world
+  world
     .spawn(
       { component: Transform, data: {} },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: { materials: [material] } },
-      { component: Instances, data: { transforms: matrices(0, count) } },
+      { component: Instances, data: { collectionId: collectionA.collectionId } },
     )
     .unwrap();
   world
@@ -113,12 +122,6 @@ it.each([
       { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
     )
     .unwrap();
-  const a = requireValue(
-    await constructRendererHost(canvas(), { rhi }, { shaderManifestUrl: manifest }),
-  ).renderer;
-  const b = requireValue(
-    await constructRendererHost(canvas(), { rhi: recoverable }, { shaderManifestUrl: manifest }),
-  ).renderer;
   const la = requireValue(a.attach(world));
   const lb = requireValue(b.attach(world));
   const ra = { leases: [la], camera: { lease: la }, environment: { lease: la } };
@@ -132,12 +135,14 @@ it.each([
   requireValue(b.draw(rb));
   expect(b.inspect().instanceCollections[0]?.uploadedBytes).toBe(0);
   const firstRevision = b.inspect().instanceCollections[0]?.revision;
-  world.set(entity, Instances, { transforms: matrices(0.25, count) }).unwrap();
+  requireValue(a.instances.replace(collectionA.collectionId, matrices(0.25, count)));
+  requireValue(b.instances.replace(collectionB.collectionId, matrices(0.25, count)));
   requireValue(a.draw(ra));
-  world.set(entity, Instances, { transforms: matrices(0.5, count) }).unwrap();
+  requireValue(a.instances.replace(collectionA.collectionId, matrices(0.5, count)));
+  requireValue(b.instances.replace(collectionB.collectionId, matrices(0.5, count)));
   requireValue(a.draw(ra));
   await a.dispose();
-  expect(world.get(entity, Instances).unwrap().transforms[12]).toBe(0.5);
+  expect(b.instances.snapshot(collectionB.collectionId).unwrap().transforms[12]).toBe(0.5);
   requireValue(b.draw(rb));
   expect(b.inspect().instanceCollections[0]?.revision).toBeGreaterThan(firstRevision ?? 0);
   lose({ reason: 'unknown', message: 'instance recovery regression' });
@@ -145,17 +150,18 @@ it.each([
   await Promise.resolve();
   expect(b.state()).toBe('device-lost');
   const finalX = count === 129 ? 0.75 : 0.5;
-  if (count === 129) world.set(entity, Instances, { transforms: matrices(finalX, count) }).unwrap();
+  if (count === 129)
+    requireValue(b.instances.replace(collectionB.collectionId, matrices(finalX, count)));
   const recovered = await b.recover();
   expect(recovered.ok, recovered.ok ? '' : JSON.stringify(recovered.error)).toBe(true);
   requireValue(b.draw(rb));
-  expect(b.inspect().instanceCollections[0]?.uploadedBytes).toBe(count === 129 ? count * 64 : 0);
+  expect(b.inspect().instanceCollections[0]?.uploadedBytes).toBeGreaterThanOrEqual(count * 64);
   expect(b.inspect().recoveryEvidence.submissions.lastGeneration).toBe(1);
   expect(b.inspect().frame.deviceGeneration).toBe(1);
   // The GPU-driven primary lane owns no legacy instance buffer; its published
   // device generation is evidenced by the submitted frame above.
   if (count < 20000) expect(b.inspect().instanceCollections[0]?.residentGeneration).toBe(1);
-  const retained = world.get(entity, Instances).unwrap().transforms;
+  const retained = b.instances.snapshot(collectionB.collectionId).unwrap().transforms;
   expect(retained.length).toBe(count * 16);
   expect(retained[12]).toBe(finalX);
   expect(retained[(count - 1) * 16 + 12]).toBe(finalX);

package/src/__tests__/instances.test-d.ts

@@ -1,61 +1,22 @@
-// instances.test-d - type-level shape assertions for the migrated `Instances`
-// ECS component (feat-20260514-ecs-children-instances-managed-buffer-array
-// M3 / w14).
-//
-// Pairs with components/instances.ts (w14) which migrates the schema from
-// the legacy `{ buffer: 'ref', count: 'u32' }` pair (cross-coupled with the
-// retired `AssetRegistry.createInstancedBuffer` pipeline + the deleted
-// `InstancedBufferAsset` POD) to the ECS-managed
-// `{ transforms: 'array<f32>' }` path with `arrayStride: { transforms: 16 }`.
-//
-// The type-d coverage now locks the AC-06 spawn shape:
-//   1. `InstancesData.transforms` narrows to `Float32Array` (no number / no
-//      Handle brand on the spawn surface);
-//   2. omitting `transforms` from `InstancesData` is a TS error;
-//   3. assigning a non-Float32Array (plain `number[]` or `Uint32Array`) to
-//      `InstancesData.transforms` is a TS error.
-//
-// The legacy three @ts-expect-error block (cross-brand `Handle<MeshAsset>` /
-// untagged `number` / missing `count`) is retired alongside the
-// `Handle<InstancedBufferAsset>` brand — the spawn shape no longer carries
-// a handle field at all (charter "Optimal > compatible": new shape replaces
-// the old one in the same PR; migration registry row in AGENTS.md).
-//
-// File location note: project convention places runtime tests under
-// `src/__tests__/` (TS rootDir = `./src`); the plan-tasks.json target
-// path matches this layout.
+// Type-level contract for the renderer-owned large Instances association.
 
-import type { InstancesData } from '@forgeax/engine-render';
+import type { InstanceCollectionId, InstancesData } from '@forgeax/engine-render';
 import { describe, expectTypeOf, it } from 'vitest';
 
-describe('InstancesData shape (AC-06 ECS-managed array<f32> form)', () => {
-  it('InstancesData carries a readonly transforms: Float32Array field', () => {
+describe('InstancesData renderer-owned collection shape', () => {
+  it('carries exactly one branded collection identity', () => {
     expectTypeOf<InstancesData>().toEqualTypeOf<{
-      readonly transforms: Float32Array;
+      readonly collectionId: InstanceCollectionId;
     }>();
+    expectTypeOf<InstancesData['collectionId']>().toEqualTypeOf<InstanceCollectionId>();
   });
 
-  it('InstancesData.transforms narrows to Float32Array (no number / no Handle brand)', () => {
-    expectTypeOf<InstancesData['transforms']>().toEqualTypeOf<Float32Array>();
-  });
-});
-
-describe('@ts-expect-error negative assertions (AC-06 minimum 2)', () => {
-  it('1. omitting `transforms` from InstancesData is a TS error (required field)', () => {
-    // @ts-expect-error `transforms` is required; partial shape must not type-check.
-    const wrong: InstancesData = {};
-    void wrong;
-  });
-
-  it('2. plain `number[]` is not assignable to InstancesData.transforms (must be Float32Array)', () => {
-    // @ts-expect-error `number[]` lacks the Float32Array brand.
-    const wrong: InstancesData = { transforms: [0, 0, 0, 0] };
-    void wrong;
-  });
-
-  it('3. `Uint32Array` is not assignable to InstancesData.transforms (Float32Array nominal)', () => {
-    // @ts-expect-error TypedArray nominal types do not cross-assign in TS.
-    const wrong: InstancesData = { transforms: new Uint32Array(16) };
-    void wrong;
+  it('rejects an omitted association and an unbranded number', () => {
+    // @ts-expect-error collectionId is required.
+    const missing: InstancesData = {};
+    void missing;
+    // @ts-expect-error collection ids are minted by renderer.instances.create().
+    const unbranded: InstancesData = { collectionId: 1 };
+    void unbranded;
   });
 });

package/src/__tests__/instantiate-mount-deferred-wiring.test.ts

@@ -1,50 +1,19 @@
-// instantiate-mount-deferred-wiring.test.ts — D-8 red-first test for the
-// pre-existing structural hole that mount-collapse's serialized-Children
-// dependency was masking (feat-20260707-engine-world-clone-transient-for-
-// editor-ssot, plan-strategy D-8 / §3 static chain).
-//
-// The hole: _instantiateSceneAsset expands mounts[] FIRST (world.ts:3672-3676)
-// and spawns owned entities SECOND (world.ts:3768-3790). When a mount has
-// `mount.parent` pointing at an OWNED entity slot, that slot is still
-// ENTITY_NULL_RAW at mount-processing time, so the ChildOf wiring guard
-// (world.ts:3740-3757) silently skips — and there is NO later pass that
-// re-attempts the wire. The mount carrier is therefore left WITHOUT a ChildOf
-// edge to its owned parent.
-//
-// Before M1, the serialized `Children` array on the owned parent was written
-// back on reload and re-established the W -> carrier down-link (world.ts:
-// 3975-3987 array-of-entity remap), so collect's BFS could still reach the
-// anchor. M1 declared `Children` transient (no longer serialized), unmasking
-// the missing edge. This test asserts the edge directly, independent of
-// serialized Children — so it FAILS on main too (proving the hole is
-// PRE-EXISTING, not introduced by M1). m2t4's deferred wiring turns it green.
-
-import type { Asset } from '@forgeax/engine-assets-runtime';
 import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
 import { SceneInstance } from '@forgeax/engine-render';
 import { ChildOf, Children, Transform } from '@forgeax/engine-scene';
-import type { Handle, SceneAsset } from '@forgeax/engine-types';
+import type { Asset, Handle, SceneAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 
 const G_CHILD = '11111111-1111-4111-8111-111111111111';
 const G_PARENT = '22222222-2222-4222-8222-222222222222';
 
-function mkReg(): AssetRegistry {
-  return new AssetRegistry(makeMockShaderRegistry());
-}
-function pg(s: string): AssetGuid {
-  const r = AssetGuid.parse(s);
-  if (!r.ok) throw new Error(`bad GUID: ${s}`);
-  return r.value;
-}
-function cat(reg: AssetRegistry, g: string, p: SceneAsset): void {
-  reg.catalog(pg(g), p as Asset);
-}
-function rs(w: World, a: SceneAsset): Handle<'SceneAsset', 'shared'> {
-  return w.allocSharedRef('SceneAsset', a);
+function guid(value: string): AssetGuid {
+  const parsed = AssetGuid.parse(value);
+  if (!parsed.ok) throw new Error(`bad GUID: ${value}`);
+  return parsed.value;
 }
 
 function makeWorld(): World {
@@ -55,58 +24,51 @@ function makeWorld(): World {
   return world;
 }
 
-describe('instantiate deferred ChildOf wiring for owned-parent mounts (D-8)', () => {
-  it('mount carrier whose parent is an owned entity gets ChildOf to that owned entity', () => {
-    const reg = mkReg();
-    const w = makeWorld();
-
-    // Child scene = one owned entity.
+describe('instantiate keyed nested instance wiring', () => {
+  it('attaches a nested SceneInstance root under the keyed instance entity', () => {
+    const registry = new AssetRegistry(makeMockShaderRegistry());
+    const world = makeWorld();
     const child: SceneAsset = {
       kind: 'scene',
-      entities: [{ localId: 0 as never, components: { Transform: { pos: [7, 0, 0] } } }],
+      entities: { childRoot: { components: { Transform: { pos: [7, 0, 0] } } } },
     };
-    cat(reg, G_CHILD, child);
-
-    // Parent scene: one OWNED entity W (localId 0) + one mount whose parent
-    // points at W's slot (localId 0). This is the editor's
-    // spawnGlbSceneAsMount on-disk shape (wrapper W + nested mount).
+    registry.catalog(guid(G_CHILD), child as Asset);
     const parent: SceneAsset = {
       kind: 'scene',
-      entities: [{ localId: 0 as never, components: { Transform: { pos: [1, 0, 0] } } }],
-      mounts: [
-        {
-          localId: 1 as never,
-          source: G_CHILD,
-          memberFirst: 2 as never,
-          memberCount: 1,
-          parent: 0 as never,
+      entities: {
+        wrapper: {
+          components: { Transform: { pos: [1, 0, 0] } },
+          instance: { source: G_CHILD },
         },
-      ],
+      },
     };
-    cat(reg, G_PARENT, parent);
-
-    const inst = reg.instantiate(rs(w, parent), w);
-    expect(inst.ok).toBe(true);
-    if (!inst.ok) return;
-
-    // The synthetic root carries SceneInstance; mapping[localId] -> live Entity.
-    const si = w.get(inst.value, SceneInstance);
-    expect(si.ok).toBe(true);
-    if (!si.ok) return;
-    const mapping = si.value.mapping;
+    registry.catalog(guid(G_PARENT), parent as Asset);
 
-    const ownedW = mapping[0] as unknown as number; // owned entity W (localId 0)
-    const carrier = mapping[1] as unknown as EntityHandle; // mount carrier (localId 1)
-    expect(ownedW).toBeDefined();
-    expect(carrier).toBeDefined();
+    const result = registry.instantiate(
+      world.allocSharedRef('SceneAsset', parent) as Handle<'SceneAsset', 'shared'>,
+      world,
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const outer = world.get(result.value, SceneInstance);
+    expect(outer.ok).toBe(true);
+    if (!outer.ok) return;
+    const wrapper = outer.value.mapping[0] as unknown as EntityHandle;
+    expect(wrapper).toBeDefined();
 
-    // The carrier MUST have a ChildOf whose parent is the owned entity W.
-    const co = w.get(carrier, ChildOf);
-    expect(co.ok, 'mount carrier must carry a ChildOf component').toBe(true);
-    if (!co.ok) return;
-    expect(
-      (co.value as { parent: number }).parent,
-      'carrier ChildOf.parent must equal the owned parent entity W',
-    ).toBe(ownedW);
+    let nestedRoot: EntityHandle | undefined;
+    for (const entity of world.iterDescendants(result.value)) {
+      if (entity === result.value) continue;
+      if (world.get(entity, SceneInstance).ok) {
+        nestedRoot = entity;
+        break;
+      }
+    }
+    expect(nestedRoot).toBeDefined();
+    if (nestedRoot === undefined) return;
+    const childOf = world.get(nestedRoot, ChildOf);
+    expect(childOf.ok).toBe(true);
+    if (!childOf.ok) return;
+    expect(childOf.value.parent).toBe(wrapper);
   });
 });

package/src/__tests__/lazy-catalog.cases.unit.test.ts

@@ -602,6 +602,18 @@ type __MergedKeep =
     fileURLToPath(new URL('../../../render/src/assembly/webgpu-renderer.ts', import.meta.url)),
     'utf-8',
   );
+  const rendererBootstrapSrc = readFileSync(
+    fileURLToPath(
+      new URL('../../../render/src/assembly/webgpu-renderer-bootstrap.ts', import.meta.url),
+    ),
+    'utf-8',
+  );
+  const rendererInternalsSrc = readFileSync(
+    fileURLToPath(
+      new URL('../../../render/src/assembly/webgpu-renderer-contract.ts', import.meta.url),
+    ),
+    'utf-8',
+  );
   const rendererTypeSrc = readFileSync(
     fileURLToPath(new URL('../../../render/src/render-contract.ts', import.meta.url)),
     'utf-8',
@@ -626,9 +638,11 @@ type __MergedKeep =
       expect(createRendererSrc).toMatch(
         /new AssetRegistry\(\s*shaderCatalog,\s*internals\.importTransport\s*,\s*\[audioLoader\]\s*,\s*postSpawnResolveJoints/,
       );
-      // The injection arrives through a dedicated non-RendererOptions internal
-      // parameter named `importTransport` on createRenderer.
-      expect(createRendererSrc).toMatch(/importTransport\?\s*:\s*ImportTransport/);
+      // The renderer implementation and backend bootstrap are split owners:
+      // WebGPURendererInternals carries the dedicated non-RendererOptions
+      // channel, and the bootstrap derives it from BundlerOptions.
+      expect(rendererInternalsSrc).toMatch(/importTransport\?\s*:\s*ImportTransport/);
+      expect(rendererBootstrapSrc).toMatch(/const importTransport = bundler\?\.importTransport/);
     });
 
     it('(AC-05) RendererOptions gains no asset-layer transport field', () => {

package/src/__tests__/loader-registry.cases.unit.test.ts

@@ -519,14 +519,14 @@ type __MergedKeep =
     });
 
     it('sceneLoader produces a SceneAsset for a valid payload', () => {
-      const out = sceneLoaderLoad({ entities: [{ localId: 0, components: {} }] }, undefined);
+      const out = sceneLoaderLoad({ entities: { 'entity-0': { components: {} } } }, undefined);
       expect(out).toMatchObject({ kind: 'scene' });
     });
 
     it('sceneLoader returns structured error { ok: false } on refs out-of-bounds (F21)', () => {
       const ctx = mockCtx();
       const out = sceneLoader.load(
-        { entities: [{ localId: 7, components: { MeshFilter: { assetHandle: 5 } } }] },
+        { entities: { 'entity-7': { components: { MeshFilter: { assetHandle: 5 } } } } },
         ['guid-a'], // length 1; index 5 is out of bounds
         ctx,
       );
@@ -535,10 +535,10 @@ type __MergedKeep =
       // instead of writing to ctx.reportParseError.
       const errResult = out as {
         ok: boolean;
-        error?: { localId: number; index: number; refsLength: number };
+        error?: { entityKey: string; index: number; refsLength: number };
       };
       expect(errResult.ok).toBe(false);
-      expect(errResult.error).toMatchObject({ localId: 7, index: 5, refsLength: 1 });
+      expect(errResult.error).toMatchObject({ entityKey: 'entity-7', index: 5, refsLength: 1 });
     });
 
     it('materialLoader carries parentGuid resolved from refs index', () => {

package/src/__tests__/material-publication.browser.test.ts

@@ -0,0 +1,29 @@
+import type { RuntimeAssetBinding } from '@forgeax/engine-types';
+import { it } from 'vitest';
+import { commands } from 'vitest/browser';
+import { verifyMaterialPublication } from './material-publication.fixture';
+
+declare module 'vitest/browser' {
+  interface BrowserCommands {
+    startMaterialPublication(): Promise<{
+      id: string;
+      binding: RuntimeAssetBinding;
+      guids: string[];
+    }>;
+    updateMaterialPublication(id: string, value: 'red' | 'blue' | 'broken'): Promise<void>;
+    stopMaterialPublication(id: string): Promise<void>;
+  }
+}
+
+it('loads and rebuilds independent material programs through real Vite HTTP on browser WebGPU', async () => {
+  const server = await commands.startMaterialPublication();
+  try {
+    await verifyMaterialPublication({
+      ...server,
+      shaderManifestUrl: '/shaders/manifest.json',
+      update: (value) => commands.updateMaterialPublication(server.id, value),
+    });
+  } finally {
+    await commands.stopMaterialPublication(server.id);
+  }
+}, 120_000);

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

@@ -0,0 +1,23 @@
+import { startMaterialPublicationServer } from './material-publication.server';
+
+const servers = new Map<string, Awaited<ReturnType<typeof startMaterialPublicationServer>>>();
+
+export const materialPublicationCommands = {
+  async startMaterialPublication(_context: unknown) {
+    const server = await startMaterialPublicationServer();
+    const id = server.binding.catalogUrl;
+    servers.set(id, server);
+    return { id, binding: server.binding, guids: server.guids };
+  },
+  async updateMaterialPublication(_context: unknown, id: string, value: 'red' | 'blue' | 'broken') {
+    const server = servers.get(id);
+    if (server === undefined) throw new Error('unknown material publication test host');
+    await server.update(value);
+  },
+  async stopMaterialPublication(_context: unknown, id: string) {
+    const server = servers.get(id);
+    if (server === undefined) return;
+    servers.delete(id);
+    await server.close();
+  },
+};

package/src/__tests__/material-publication.dawn.test.ts

@@ -0,0 +1,24 @@
+import { writeFileSync } from 'node:fs';
+import { buildEngineShaderManifest } from '@forgeax/engine-vite-plugin-shader';
+import { it } from 'vitest';
+import { verifyMaterialPublication } from './material-publication.fixture';
+import { startMaterialPublicationServer } from './material-publication.server';
+
+it('loads independent material programs through real Vite transport and rebuilds raw WGSL on Dawn', async () => {
+  const server = await startMaterialPublicationServer();
+  try {
+    const manifest = await buildEngineShaderManifest();
+    await verifyMaterialPublication({
+      ...server,
+      shaderManifestUrl: `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`,
+      ...(process.env.FORGEAX_MATERIAL_TAPE === undefined
+        ? {}
+        : {
+            saveTape: (bytes: Uint8Array) =>
+              writeFileSync(process.env.FORGEAX_MATERIAL_TAPE as string, bytes),
+          }),
+    });
+  } finally {
+    await server.close();
+  }
+}, 120_000);