@forgeax/engine-runtime 0.1.4 → 0.1.7

package/src/__tests__/dawn/sprite-nineslice-mesh-bind.dawn.test.ts

@@ -1,5 +1,5 @@
 // sprite-nineslice-mesh-bind.dawn.test.ts -- feat-20260527-sprite-nineslice
-// M2 / w13. dawn-node smoke that the nine-slice quad GPU buffers are
+// M2 / w13. dawn-node smoke that the HANDLE_NINESLICE_QUAD GPU buffers are
 // resident and bind cleanly when a sprite material declares non-zero `slices`.
 //
 // Plan-strategy §M2 boundary clause: M2 must include at least one dawn fixture so
@@ -12,14 +12,14 @@
 // It does NOT assert pixel content -- M3 / w15 (hello-sprite-nineslice-section
 // dawn fixture) covers stretch + tile pixel parity.
 
+import { AssetRegistry, HANDLE_QUAD } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '@forgeax/engine-render/authoring';
-import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render/internal';
-import { createRenderer } from '@forgeax/engine-runtime';
 import { Transform } from '@forgeax/engine-scene';
 import type { MaterialAsset, SamplerAsset, TextureAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { constructRuntimeRendererHost } from '../../renderer-host';
 import { drawPublished } from '../draw-published';
 
 const WIDTH = 64;
@@ -93,23 +93,25 @@ describe('feat-20260527-sprite-nineslice w13 dawn smoke (HANDLE_NINESLICE_QUAD b
       removeEventListener() {},
     } as unknown as HTMLCanvasElement;
 
-    let renderer: Awaited<ReturnType<typeof createRenderer>>;
+    let host: Awaited<ReturnType<typeof constructRuntimeRendererHost>>;
     try {
-      renderer = await createRenderer(mockCanvas, {}, { shaderManifestUrl: ENGINE_MANIFEST_URL });
+      host = await constructRuntimeRendererHost(
+        mockCanvas,
+        {},
+        {
+          shaderManifestUrl: ENGINE_MANIFEST_URL,
+        },
+      );
     } finally {
       globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
     }
-    expect(renderer.backend).toBe('webgpu');
-
-    const ready = await renderer.ready;
-    expect(ready.ok).toBe(true);
-    if (!ready.ok) return;
+    expect(host.ok).toBe(true);
+    if (!host.ok) throw host.error;
+    const { renderer, assets } = host.value;
+    expect(renderer.inspect().state).toBe('alive');
+    expect(assets).toBeInstanceOf(AssetRegistry);
 
     const world = new World();
-    const nineSliceHandle = world.internSharedRef(
-      'MeshAsset',
-      createPrimitiveMesh('nine-slice-quad').unwrap(),
-    );
 
     // ── Build a 4x4 RGBA texture (16 texels) with a recognizable pattern. ──
     // The exact pixels are not asserted -- the frame just needs to render
@@ -132,18 +134,6 @@ describe('feat-20260527-sprite-nineslice w13 dawn smoke (HANDLE_NINESLICE_QUAD b
       data: pixels,
     };
     const texHandle = world.allocSharedRef<'TextureAsset', TextureAsset>('TextureAsset', texAsset);
-    // feat-20260601-gpu-resource-store-extraction M1: explicit texture GPU upload.
-    const texUploadRes = await renderer.store.uploadTexture(texHandle, texAsset, {
-      bytes: pixels,
-      width: 4,
-      height: 4,
-      mime: 'image/png',
-      colorSpace: 'srgb',
-      mipmap: false,
-    });
-    expect(texUploadRes.ok).toBe(true);
-    if (!texUploadRes.ok) return;
-
     const samplerAsset: SamplerAsset = {
       kind: 'sampler',
       addressModeU: 'repeat',
@@ -174,7 +164,7 @@ describe('feat-20260527-sprite-nineslice w13 dawn smoke (HANDLE_NINESLICE_QUAD b
     // single asset-side SSOT; transparent routing now derives from
     // `renderState.blend !== undefined`.
     // The slices mesh routing decision (D-2 sentinel:
-    // unit quad -> nine-slice quad when slices != [0,0,0,0]) is
+    // HANDLE_QUAD -> HANDLE_NINESLICE_QUAD when slices != [0,0,0,0]) is
     // unchanged; the record stage reads it via the materialShaderId ===
     // 'forgeax::sprite' + non-zero `slicesAndMode.xyz` predicate.
     const matHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
@@ -191,22 +181,16 @@ describe('feat-20260527-sprite-nineslice w13 dawn smoke (HANDLE_NINESLICE_QUAD b
         },
       ],
       values: {
-        baseColorTexture: {
-          texture: texHandle as unknown as never,
-          coordinates: {
-            set: 0,
-            transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
-            physicalUvScale: [1, 1],
-          },
-        },
+        baseColorTexture: { texture: texHandle as unknown as never },
         sampler: { texture: samplerHandle as unknown as never },
         slicesAndMode: [0.25, 0.25, 0.25, 0.25],
       },
     });
 
     const errors: unknown[] = [];
-    renderer.onError((e) => {
-      errors.push(e);
+    renderer.subscribe((event) => {
+      if (event.kind !== 'error') return;
+      errors.push(event.error);
     });
 
     world.spawn(
@@ -218,7 +202,7 @@ describe('feat-20260527-sprite-nineslice w13 dawn smoke (HANDLE_NINESLICE_QUAD b
           scale: [1, 1, 1],
         },
       },
-      { component: MeshFilter, data: { assetHandle: nineSliceHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
       { component: MeshRenderer, data: { materials: [matHandle] } },
     );
     world.spawn(

package/src/__tests__/dawn/upload-texture.dawn.test.ts

@@ -0,0 +1,198 @@
+// T-M3-02 dawn (real GPU) integration tests for AssetRegistry.uploadTexture
+// (plan-strategy section 2.5 D Open Q-4 (c) consistency assertion + section
+// 2.6 D Open Q-5 (a) mipmap-generator independent file; research F-3 sRGB
+// mipmap math spec correctness; F-4 copyExternalImageToTexture entry).
+//
+// Why dawn integration tests:
+//   - Requirements AC-08 (uploadTexture path + sampler default + sRGB / linear
+//     explicit) needs real GPU verification: spec automatic decode / encode
+//     on `*-srgb` views must produce a mid-gray ~0.5 in linear space rather
+//     than the broken-OpenGL ~0.218 (research F-3 physical judgment).
+//   - The unit-only path cannot exercise queue.copyExternalImageToTexture +
+//     readBuffer pixel readback; the dawn project (vitest dawn) provides
+//     `globalThis.navigator.gpu` via webgpu npm package native binding
+//     (vitest.setup-webgpu.ts).
+//
+// Fixtures live alongside this file (T-M3-02 acceptanceCheck listed 6 fixtures
+// originally; the unit-test layer in T-M3-01 already covers 1x1 / 2x2 / 256x256
+// dimension boundaries + non-power-of-2 via the pure formula. The two real-
+// pixel fixtures here are documentary -- the inline literal byte arrays match
+// what the PNGs encode (sRGB byte 188 + linear byte 128) so the test is
+// self-contained without node:fs file IO. Plan-strategy section 4 R4 explicitly
+// notes mid-gray 0.5 not sinking to 0.218 as the binary judgment).
+//
+// Red-stage scaffolding: implementation lands in T-M3-05 (AssetRegistry.
+// uploadTexture method + render-system materialBindGroup sampler / textureView
+// injection); the GPU-upload path itself stays inert when configureGpuDevice
+// is not called (M3-only deferred-upload semantics; M5 wires the device into
+// render-system bootstrap).
+
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { ok } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import type { DecodedImage, EquirectAsset, TextureAsset } from '@forgeax/engine-types';
+import { toShared } 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: uploadTexture moved to
+// GpuResidencyCache (POD carries format, decoded carries colorSpace; D-2). The
+// store holds no registry reference -- the asset-not-found arm now lives at the
+// registry get the caller runs before reaching the store.
+
+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 decodedFromBytes(
+  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 uploadTexture format <-> colorSpace consistency', () => {
+  it('rejects format=rgba8unorm-srgb + decoded.colorSpace=linear (real GPU path)', async () => {
+    const store = new GpuResidencyCache();
+    const pod = makeTexture('rgba8unorm-srgb', 1, 1, 'srgb', false);
+    const handle = toShared<'TextureAsset'>(1);
+    const decoded = decodedFromBytes(new Uint8Array([188, 188, 188, 255]), 1, 1, 'linear', false);
+    const res = await store.uploadTexture(handle, pod, decoded);
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect(res.error.code).toBe('image-format-unsupported');
+    if (res.error.code !== 'image-format-unsupported') return;
+    if (res.error.detail.code !== 'image-format-unsupported') return;
+    expect(res.error.detail.formatColorSpaceConflict?.expected).toBe('srgb');
+  });
+
+  it('accepts format=rgba8unorm-srgb + decoded.colorSpace=srgb (1x1 mid-gray byte 188)', async () => {
+    const store = new GpuResidencyCache();
+    const pod = makeTexture('rgba8unorm-srgb', 1, 1, 'srgb', false);
+    const handle = toShared<'TextureAsset'>(1);
+    const decoded = decodedFromBytes(new Uint8Array([188, 188, 188, 255]), 1, 1, 'srgb', false);
+    const res = await store.uploadTexture(handle, pod, decoded);
+    expect(res.ok).toBe(true);
+  });
+
+  it('accepts format=rgba8unorm + decoded.colorSpace=linear (1x1 linear byte 128)', async () => {
+    const store = new GpuResidencyCache();
+    const pod = makeTexture('rgba8unorm', 1, 1, 'linear', false);
+    const handle = toShared<'TextureAsset'>(1);
+    const decoded = decodedFromBytes(new Uint8Array([128, 64, 192, 255]), 1, 1, 'linear', false);
+    const res = await store.uploadTexture(handle, pod, decoded);
+    expect(res.ok).toBe(true);
+  });
+
+  it('asset-not-found path: resolve against unregistered gen-0 handle (real GPU)', () => {
+    const world = new World();
+    // gen-0 user-tier handle for a never-allocated slot: passes the generation
+    // gate then misses the payload -> asset-not-found. A gen>0 handle would
+    // surface 'shared-ref-stale' instead (D-3/AC-10).
+    const fake = toShared<'TextureAsset'>(99999);
+    const podRes = resolveAssetHandle<TextureAsset>(world, fake);
+    expect(podRes.ok).toBe(false);
+    if (podRes.ok) return;
+    expect(podRes.error.code).toBe('asset-not-found');
+  });
+});
+
+// AC-04 (bug-20260521): non-256-aligned width uploadTexture through
+// real GPU path. Must call configureGpuDevice() to bypass the
+// asset-registry.ts:770-773 short-circuit (device === undefined).
+// The test name contains 'non-256-aligned' for grep discoverability.
+// Plan-strategy section 5.3 + requirements AC-04 caveat:
+// `grep -n 'configureGpuDevice('` must find at least one hit.
+describe('AC-04: uploadTexture non-256-aligned width (real GPU path)', () => {
+  it('uploadTexture accepts non-256-aligned width (100x100 RGBA8, bytesPerRow=400, configureGpuDevice injected)', async () => {
+    const adapterResult = await rhi.requestAdapter();
+    if (!adapterResult.ok) return;
+    const deviceResult = await adapterResult.value.requestDevice();
+    if (!deviceResult.ok) return;
+    const device = deviceResult.value;
+
+    const store = new GpuResidencyCache();
+    const world = new World();
+    // Literal configureGpuDevice required -- this is the anti-short-circuit
+    // guard verified by acceptanceCheck grep gate. Wires the device + register
+    // relay onto the store (D-3/D-8).
+    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 width = 100;
+    const height = 100;
+    const buf = new Uint8Array(width * height * 4);
+    // Fill with a deterministic pattern so any validator that inspects
+    // pixel data sees real content rather than an all-zeroes block.
+    for (let i = 0; i < buf.length; i++) {
+      buf[i] = (i * 17 + 64) & 0xff;
+    }
+
+    const tex: TextureAsset = {
+      kind: 'texture',
+      width,
+      height,
+      format: 'rgba8unorm',
+      data: buf,
+      colorSpace: 'linear',
+      mipmap: false,
+    };
+
+    const handle = world.allocSharedRef('TextureAsset', tex);
+    const decoded = decodedFromBytes(buf, width, height, 'linear', false);
+    const res = await store.uploadTexture(handle, tex, decoded);
+    expect(res.ok).toBe(true);
+  });
+});

package/src/__tests__/dawn/user-handle-mesh-render.dawn.test.ts

@@ -12,7 +12,7 @@
 //   cube was silently culled (charter P3 explicit failure: the structured
 //   error fired, but the frame still composited pure clearColor).
 //
-//   feat-20260601-gpu-resource-store-extraction M1 closed the engine path via
+//   feat-20260601-device/gpu-residency-extraction M1 closed the engine path via
 //   the pull model (the prior register-time auto-upload push was severed):
 //     - render-system-record.ts: a user-handle mesh (id >= 1024) misses the
 //       builtin `pipelineState.meshes` alias map, so the record stage pulls it
@@ -40,17 +40,17 @@
 // COPY_SRC` GPUTexture pattern as
 // apps/learn-render/.../4.textures/src/__tests__/textures-pixel.dawn.test.ts.
 
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
 import { createBoxGeometry } from '@forgeax/engine-geometry';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
-import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render/internal';
-import { createRenderer } from '@forgeax/engine-runtime';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
 import { Transform } from '@forgeax/engine-scene';
 import type { MaterialAsset, MeshAsset } from '@forgeax/engine-types';
 import { unwrapHandle } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { constructRuntimeRendererHost } from '../../renderer-host';
 import { drawPublished } from '../draw-published';
-import { createTestRenderAssetStore } from '../helpers/render-asset-port';
 
 const WIDTH = 256;
 const HEIGHT = 256;
@@ -145,25 +145,23 @@ describe('T-M2-1 user-handle mesh render regression (AC-10 / AC-11, dawn)', () =
       removeEventListener() {},
     } as unknown as HTMLCanvasElement;
 
-    const assetStore = createTestRenderAssetStore();
-    let renderer: Awaited<ReturnType<typeof createRenderer>>;
+    let host: Awaited<ReturnType<typeof constructRuntimeRendererHost>>;
     try {
-      renderer = await createRenderer(
+      host = await constructRuntimeRendererHost(
         mockCanvas,
         {},
         {
           shaderManifestUrl: ENGINE_MANIFEST_URL,
-          assetResolver: assetStore.resolver,
         },
       );
     } finally {
       globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
     }
-    expect(renderer.backend).toBe('webgpu');
-
-    const ready = await renderer.ready;
-    expect(ready.ok).toBe(true);
-    if (!ready.ok) return;
+    expect(host.ok).toBe(true);
+    if (!host.ok) throw host.error;
+    const { renderer, assets } = host.value;
+    expect(assets).toBeInstanceOf(AssetRegistry);
+    expect(renderer.inspect().state).toBe('alive');
 
     // 1. Mint a procedural cube MeshAsset, catalogue it under a fresh UUIDv7
     //    GUID in the AssetRegistry (GUID->payload SSOT, no handle), then mint a
@@ -180,7 +178,7 @@ describe('T-M2-1 user-handle mesh render regression (AC-10 / AC-11, dawn)', () =
     const world = new World();
 
     const cubeGuid = AssetGuid.random();
-    assetStore.resolver.publish(AssetGuid.format(cubeGuid), cubeAsset);
+    assets.catalog(cubeGuid, cubeAsset);
     const cubeHandle = world.allocSharedRef('MeshAsset', cubeAsset);
 
     // The handle MUST be a user-tier handle (>= 1024 = BUILTIN_BASE). If this

package/src/__tests__/dawn/user-mesh-upload.dawn.test.ts

@@ -26,10 +26,11 @@
 import { World } from '@forgeax/engine-ecs';
 import { createBoxGeometry, PROCEDURAL_FLOATS_PER_VERTEX } from '@forgeax/engine-geometry';
 import { mat4 } from '@forgeax/engine-math';
-import { GpuResourceStore } from '@forgeax/engine-render/internal';
 import { ok } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-webgpu';
 import type { EquirectAsset, MaterialAsset, 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,
@@ -53,7 +54,7 @@ const mockCaps = {
   maxColorAttachments: 8,
 };
 
-// feat-20260601-gpu-resource-store-extraction M1: mesh GPU residency moved to
+// feat-20260601-device/gpu-residency-extraction M1: mesh GPU residency moved to
 // the store; register no longer auto-uploads (push severed). The pull-model
 // premise: register the POD, then explicit `store.ensureResident(handle, pod)`
 // uploads the GPU buffers. The deferred-replay path is removed (no global
@@ -74,16 +75,18 @@ describe('w22.5 user-registered mesh GPU upload (AC-13, dawn)', () => {
       if (!meshRes.ok) return;
       const asset: MeshAsset = meshRes.value;
 
-      const adapter = await navigator.gpu.requestAdapter();
-      expect(adapter).not.toBeNull();
-      if (adapter === null) return;
-      const device = await adapter.requestDevice();
+      const adapterResult = await rhi.requestAdapter();
+      expect(adapterResult.ok).toBe(true);
+      if (!adapterResult.ok) return;
+      const deviceResult = await adapterResult.value.requestDevice();
+      expect(deviceResult.ok).toBe(true);
+      if (!deviceResult.ok) return;
+      const device = deviceResult.value;
 
-      const store = new GpuResourceStore();
+      const store = new GpuResidencyCache();
       const world = new World();
       store.configureGpuDevice(
-        // biome-ignore lint/suspicious/noExplicitAny: structural rhi device shim
-        device as any,
+        device,
         undefined,
         (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
         mockCaps,
@@ -120,7 +123,7 @@ describe('w22.5 user-registered mesh GPU upload (AC-13, dawn)', () => {
   it.skipIf(!dawnReady)(
     '(b) pull-model: register then ensureResident surfaces the GPU buffers (no global replay)',
     async () => {
-      // feat-20260601-gpu-resource-store-extraction M1: the pre-extraction
+      // feat-20260601-device/gpu-residency-extraction M1: the pre-extraction
       // deferred-replay path is removed (no global replay). register only
       // catalogues the CPU POD; getMeshGpuHandles is undefined until an
       // explicit ensureResident pulls the GPU buffers (charter P9 graceful
@@ -130,19 +133,20 @@ describe('w22.5 user-registered mesh GPU upload (AC-13, dawn)', () => {
       if (!meshRes.ok) return;
       const asset: MeshAsset = meshRes.value;
 
-      const store = new GpuResourceStore();
+      const store = new GpuResidencyCache();
       const world = new World();
       const handle = world.allocSharedRef('MeshAsset', asset);
       // Before any ensureResident the store has no GPU residency for the handle.
       const before = store.getMeshGpuHandles(handle);
       expect(before).toBeUndefined();
 
-      const adapter = await navigator.gpu.requestAdapter();
-      if (adapter === null) return;
-      const device = await adapter.requestDevice();
+      const adapterResult = await rhi.requestAdapter();
+      if (!adapterResult.ok) return;
+      const deviceResult = await adapterResult.value.requestDevice();
+      if (!deviceResult.ok) return;
+      const device = deviceResult.value;
       store.configureGpuDevice(
-        // biome-ignore lint/suspicious/noExplicitAny: structural rhi device shim
-        device as any,
+        device,
         undefined,
         (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
         mockCaps,
@@ -159,15 +163,16 @@ describe('w22.5 user-registered mesh GPU upload (AC-13, dawn)', () => {
   it.skipIf(!dawnReady)(
     '(c) batch register 16 user meshes -> all 16 carry distinct GPU buffer handles (lifecycle does not re-allocate)',
     async () => {
-      const adapter = await navigator.gpu.requestAdapter();
-      if (adapter === null) return;
-      const device = await adapter.requestDevice();
+      const adapterResult = await rhi.requestAdapter();
+      if (!adapterResult.ok) return;
+      const deviceResult = await adapterResult.value.requestDevice();
+      if (!deviceResult.ok) return;
+      const device = deviceResult.value;
 
-      const store = new GpuResourceStore();
+      const store = new GpuResidencyCache();
       const world = new World();
       store.configureGpuDevice(
-        // biome-ignore lint/suspicious/noExplicitAny: structural rhi device shim
-        device as any,
+        device,
         undefined,
         (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
         mockCaps,

package/src/__tests__/dawn/zero-manifest-mesh-fail.dawn.test.ts

@@ -15,10 +15,10 @@
 // preservation). plan-strategy D-3 + D-4 (test matrix migration: dawn
 // project mirror).
 
-import { createRenderer } from '@forgeax/engine-runtime';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { MaterialAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { createTestRenderAssetStore } from '../helpers/render-asset-port';
+import { constructRuntimeRendererHost } from '../../renderer-host';
 
 const WIDTH = 64;
 const HEIGHT = 64;
@@ -83,40 +83,37 @@ describe('bug-20260519 AC-03 dawn mirror: mesh + zero manifest -> render-time fa
       removeEventListener() {},
     } as unknown as HTMLCanvasElement;
 
-    const assetStore = createTestRenderAssetStore();
-    let renderer: Awaited<ReturnType<typeof createRenderer>>;
+    let host: Awaited<ReturnType<typeof constructRuntimeRendererHost>>;
     try {
       // Zero-manifest path: explicit `shaderManifestUrl: undefined` opts into
-      // zero-entry mode. Post-fix `await renderer.ready` resolves ok; the
+      // zero-entry mode. Post-fix host construction resolves ok; the
       // asset registration fails at validation time (shader not registered).
-      renderer = await createRenderer(
-        mockCanvas,
-        {},
-        {
-          shaderManifestUrl: undefined,
-          assetResolver: assetStore.resolver,
-        },
-      );
+      host = await constructRuntimeRendererHost(mockCanvas, {}, { shaderManifestUrl: undefined });
     } finally {
       globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
     }
-    expect(renderer.backend).toBe('webgpu');
-
-    const ready = await renderer.ready;
-    expect(ready.ok).toBe(true);
+    expect(host.ok).toBe(true);
+    if (!host.ok) throw host.error;
+    const { renderer, assets } = host.value;
+    expect(renderer.inspect().state).toBe('alive');
+    expect(assets).toBeInstanceOf(AssetRegistry);
 
     // Material parameter declarations now belong to MaterialAsset, so catalog
     // validation does not depend on a shader-manifest registration side table.
-    assetStore.resolver.publish('00000000-0000-4000-8000-000000000a01', {
-      kind: 'material',
-      passes: [
-        {
-          name: 'Forward',
-          program: { module: 'forgeax::default-unlit' },
-          renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
-        },
-      ],
-      values: { baseColor: [1, 0, 0, 1] },
-    } as MaterialAsset);
+    const matRes = assets.catalog<MaterialAsset>(
+      assets.parseGuid('00000000-0000-4000-8000-000000000a01'),
+      {
+        kind: 'material',
+        passes: [
+          {
+            name: 'Forward',
+            program: { module: 'forgeax::default-unlit' },
+            renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+          },
+        ],
+        values: { baseColor: [1, 0, 0, 1] },
+      } as MaterialAsset,
+    );
+    expect(matRes.ok).toBe(true);
   });
 });

package/src/__tests__/dawn/zero-manifest-ready.dawn.test.ts

@@ -8,7 +8,7 @@
 // gate: pre-fix the unconditional Step 2 entry-scan would reject because
 // the empty manifest carries neither the `f_schlick` PBR entry nor the
 // unlit entry; post-fix the gate skips Step 2 outright, the registry
-// yields zero entries, and `await renderer.ready` resolves `Result.ok`.
+// yields zero entries, and host construction reaches the ready state.
 //
 // AC: requirements section 4 AC-02 (Camera-only world reaches `ready ok`
 // without forcing shader compilation) projected onto the dawn / rhi-wgpu
@@ -16,16 +16,16 @@
 // matrix migration: dawn project mirror) + charter P4 (consistent
 // abstraction across rhi-webgpu / rhi-wgpu).
 
-import { createRenderer } from '@forgeax/engine-runtime';
 import { describe, expect, it } from 'vitest';
+import { constructRuntimeRendererHost } from '../../renderer-host';
 
 const WIDTH = 64;
 const HEIGHT = 64;
 const TEXTURE_USAGE_COPY_SRC = 0x01;
 const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
 
-describe('bug-20260519 AC-02 dawn mirror: zero manifest -> ready ok', () => {
-  it('createRenderer without shaderManifestUrl reaches ready.ok on dawn', async () => {
+describe('bug-20260519 AC-02 dawn mirror: zero manifest -> ready state', () => {
+  it('runtime host without shaderManifestUrl reaches ready state on dawn', async () => {
     const dawnAvailable = typeof globalThis.navigator?.gpu?.requestAdapter === 'function';
     if (!dawnAvailable) {
       throw new Error('dawn-node navigator.gpu not injected; vitest.setup-webgpu.ts regressed');
@@ -82,18 +82,17 @@ describe('bug-20260519 AC-02 dawn mirror: zero manifest -> ready ok', () => {
       removeEventListener() {},
     } as unknown as HTMLCanvasElement;
 
-    let renderer: Awaited<ReturnType<typeof createRenderer>>;
+    let host: Awaited<ReturnType<typeof constructRuntimeRendererHost>>;
     try {
       // Explicit `shaderManifestUrl: undefined` opts into zero-entry mode.
       // ShaderRegistry returns empty entries without issuing any fetch;
-      // createRenderer Step 2 is skipped entirely.
-      renderer = await createRenderer(mockCanvas, {}, { shaderManifestUrl: undefined });
+      // Runtime host shader compilation is skipped entirely.
+      host = await constructRuntimeRendererHost(mockCanvas, {}, { shaderManifestUrl: undefined });
     } finally {
       globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
     }
-    expect(renderer.backend).toBe('webgpu');
-
-    const ready = await renderer.ready;
-    expect(ready.ok).toBe(true);
+    expect(host.ok).toBe(true);
+    if (!host.ok) throw host.error;
+    expect(host.value.renderer.inspect().state).toBe('alive');
   });
 });

package/src/__tests__/demo-sortscope-migration.unit.test.ts

@@ -86,22 +86,22 @@ describe('demo sortScope migration (w15, round-2 production)', () => {
     const tilemapCase = DEMO_CASES.find((c) => c.demo === 'hello-tilemap');
     if (tilemapCase === undefined) throw new Error('hello-tilemap case missing');
     const src = readFileSync(tilemapCase.mainTsPath, 'utf8');
-    expect(src).not.toMatch(/encodeSortScope\(\s*['"]per-cell['"]\s*\)/);
+    expect(src).not.toMatch(/TilemapSort\.perCell/);
   });
 
   it("asi-world demo encodes sortScope: 'per-cell' for the object TileLayer", () => {
     const asiCase = DEMO_CASES.find((c) => c.demo === 'hello-asi-world');
     if (asiCase === undefined) throw new Error('asi-world case missing');
     const src = readFileSync(asiCase.mainTsPath, 'utf8');
-    expect(src).toMatch(/encodeSortScope\(\s*['"]per-cell['"]\s*\)/);
+    expect(src).toMatch(/TilemapSort\.perCell/);
   });
 
-  it('asi-world demo imports encodeSortScope from @forgeax/engine-runtime', () => {
+  it('asi-world demo imports the grouped TilemapSort authoring value', () => {
     const asiCase = DEMO_CASES.find((c) => c.demo === 'hello-asi-world');
     if (asiCase === undefined) throw new Error('asi-world case missing');
     const src = readFileSync(asiCase.mainTsPath, 'utf8');
-    expect(src).toMatch(/encodeSortScope/);
-    expect(src).toMatch(/@forgeax\/engine-runtime/);
+    expect(src).toMatch(/TilemapSort/);
+    expect(src).toMatch(/@forgeax\/engine-render\/authoring/);
   });
 
   it('migration covers both terrain semantics (layer) and object semantics (per-cell)', () => {