@forgeax/engine-runtime 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-runtime",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -26,37 +26,37 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-animation": "0.1.6",
-    "@forgeax/engine-assets-runtime": "0.1.6",
-    "@forgeax/engine-audio-webaudio": "0.1.6",
-    "@forgeax/engine-codec": "0.1.6",
-    "@forgeax/engine-debug-draw": "0.1.6",
-    "@forgeax/engine-ecs": "0.1.6",
-    "@forgeax/engine-font": "0.1.6",
-    "@forgeax/engine-geometry": "0.1.6",
-    "@forgeax/engine-graphics-extras": "0.1.6",
-    "@forgeax/engine-image": "0.1.6",
-    "@forgeax/engine-input": "0.1.6",
-    "@forgeax/engine-math": "0.1.6",
-    "@forgeax/engine-pack": "0.1.6",
-    "@forgeax/engine-profiler": "0.1.6",
-    "@forgeax/engine-render": "0.1.6",
-    "@forgeax/engine-render-graph": "0.1.6",
-    "@forgeax/engine-rhi": "0.1.6",
-    "@forgeax/engine-rhi-null": "0.1.6",
-    "@forgeax/engine-rhi-webgpu": "0.1.6",
-    "@forgeax/engine-rhi-wgpu": "0.1.6",
-    "@forgeax/engine-scene": "0.1.6",
-    "@forgeax/engine-shader": "0.1.6",
-    "@forgeax/engine-skinning": "0.1.6",
-    "@forgeax/engine-types": "0.1.6",
-    "@forgeax/engine-vfx": "0.1.6"
+    "@forgeax/engine-animation": "0.1.7",
+    "@forgeax/engine-assets-runtime": "0.1.7",
+    "@forgeax/engine-audio-webaudio": "0.1.7",
+    "@forgeax/engine-codec": "0.1.7",
+    "@forgeax/engine-debug-draw": "0.1.7",
+    "@forgeax/engine-ecs": "0.1.7",
+    "@forgeax/engine-font": "0.1.7",
+    "@forgeax/engine-geometry": "0.1.7",
+    "@forgeax/engine-graphics-extras": "0.1.7",
+    "@forgeax/engine-image": "0.1.7",
+    "@forgeax/engine-input": "0.1.7",
+    "@forgeax/engine-math": "0.1.7",
+    "@forgeax/engine-pack": "0.1.7",
+    "@forgeax/engine-profiler": "0.1.7",
+    "@forgeax/engine-render": "0.1.7",
+    "@forgeax/engine-render-graph": "0.1.7",
+    "@forgeax/engine-rhi": "0.1.7",
+    "@forgeax/engine-rhi-null": "0.1.7",
+    "@forgeax/engine-rhi-webgpu": "0.1.7",
+    "@forgeax/engine-rhi-wgpu": "0.1.7",
+    "@forgeax/engine-scene": "0.1.7",
+    "@forgeax/engine-shader": "0.1.7",
+    "@forgeax/engine-skinning": "0.1.7",
+    "@forgeax/engine-types": "0.1.7",
+    "@forgeax/engine-vfx": "0.1.7"
   },
   "devDependencies": {
-    "@forgeax/engine-import": "0.1.6",
-    "@forgeax/engine-naga": "0.1.6",
-    "@forgeax/engine-state": "0.1.6",
-    "@forgeax/engine-vite-plugin-shader": "0.1.6",
+    "@forgeax/engine-import": "0.1.7",
+    "@forgeax/engine-naga": "0.1.7",
+    "@forgeax/engine-state": "0.1.7",
+    "@forgeax/engine-vite-plugin-shader": "0.1.7",
     "@types/node": "^20.14.0"
   },
   "forgeax": {

package/src/__tests__/asset-registry-guid-reverse.test.ts

@@ -18,6 +18,7 @@ import * as SceneOwner from '@forgeax/engine-scene';
 import {
   type Asset,
   AssetRegistry,
+  HANDLE_CUBE,
   resolveAssetHandle,
   SceneCollectAssetGuidUnresolvedError,
 } from '@forgeax/engine-assets-runtime';
@@ -205,6 +206,38 @@ describe('m1-t2 — uncatalogued scene MISS path', () => {
   });
 });
 
+describe('builtin reverse lookup ownership', () => {
+  it('collects a builtin mesh GUID without cataloguing the process-static payload', () => {
+    const registry = { guidOf: () => undefined };
+    const world = new World();
+    prepareWorld(world);
+    const scene: SceneAsset = {
+      kind: 'scene',
+      entities: [
+        {
+          localId: 0 as never,
+          components: {
+            Transform: {},
+            MeshFilter: { assetHandle: HANDLE_CUBE as never },
+          },
+        },
+      ],
+    };
+    const sceneHandle = world.allocSharedRef<'SceneAsset', SceneAsset>('SceneAsset', scene);
+    const instantiated = SceneOwner.worldInstantiateScene(world, sceneHandle);
+    expect(instantiated.ok).toBe(true);
+    if (!instantiated.ok) return;
+
+    const collected = rootsToSceneAsset(registry, world, [instantiated.value.root]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    const meshEntity = collected.value.entities.find(
+      (entity) => entity.components.MeshFilter !== undefined,
+    );
+    expect(meshEntity?.components.MeshFilter?.assetHandle).toBe(GUID_A);
+  });
+});
+
 // ── w14 (M4) PROBE: mounted-scene-with-material identity anchor ──────────
 //
 // feat-20260713 M4 / w14 (D-6, probe-first). Empirically anchors the true

package/src/__tests__/dawn/material-cooked-fixture.dawn.test.ts

@@ -3,9 +3,22 @@ import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
 type CookedRecord = {
-  readonly key: string;
-  readonly bytes: string;
-  readonly values: unknown;
+  readonly specializationKey: string;
+  readonly artifactDigest: string;
+  readonly artifact: { readonly digest: string; readonly bytes: readonly number[] };
+  readonly resolved?: {
+    readonly values?: unknown;
+  };
+  readonly receipt?: {
+    readonly identity?: {
+      readonly layoutIdentity?: string;
+      readonly programIdentity?: string;
+      readonly pipelineIdentity?: string;
+      readonly cookIdentity?: string;
+      readonly compilerFingerprint?: string;
+    };
+    readonly schemaVersion?: string;
+  };
 };
 
 type MaterialRow = {
@@ -34,9 +47,29 @@ describe('custom-shader cooked MaterialAsset fixture', () => {
     const derived = fixture.assets.find((asset) => asset.payload.role === 'derived');
     expect(root?.payload.cooked).toBeDefined();
     expect(derived?.payload.cooked).toBeDefined();
-    expect(derived?.payload.cooked?.key).toBe(root?.payload.cooked?.key);
-    expect(derived?.payload.cooked?.bytes).toBe(root?.payload.cooked?.bytes);
-    expect(derived?.payload.cooked?.values).toEqual(root?.payload.cooked?.values);
+    expect(derived?.payload.cooked?.specializationKey).toBe(
+      root?.payload.cooked?.specializationKey,
+    );
+    expect(derived?.payload.cooked?.artifactDigest).toBe(root?.payload.cooked?.artifactDigest);
+    expect(derived?.payload.cooked?.artifact.bytes).toEqual(root?.payload.cooked?.artifact.bytes);
+    expect(derived?.payload.cooked?.resolved?.values).toEqual(
+      root?.payload.cooked?.resolved?.values,
+    );
+  });
+
+  it('keeps cooked layout identity and authored coordinate transforms', () => {
+    const root = fixture.assets.find((asset) => asset.payload.role === 'root');
+    const cooked = root?.payload.cooked;
+    expect(cooked?.receipt?.schemaVersion).toBe('material-cook/3');
+    expect(cooked?.receipt?.identity?.layoutIdentity).toMatch(/^sha256-/);
+    expect(cooked?.receipt?.identity?.programIdentity).toMatch(/^sha256:/);
+    expect(cooked?.receipt?.identity?.pipelineIdentity).toMatch(/^sha256:/);
+    expect(cooked?.receipt?.identity?.cookIdentity).toMatch(/^sha256:/);
+    expect(cooked?.receipt?.identity?.compilerFingerprint).toMatch(/^sha256-/);
+    expect(cooked?.resolved?.values).toMatchObject({
+      baseColorUvTransform: [0, 0, 1, 1],
+      normalUvTransform: [0.125, 0.25, 2, 2],
+    });
   });
 
   it('runs the real Dawn path for exactly 300 frames without unexpected RHI errors', () => {

package/src/__tests__/errors.unit.test.ts

@@ -500,6 +500,18 @@ type RuntimeLayerError = RenderError | AssetRuntimeError | SkinError;
               return 'render feature prepared state mismatch';
             case 'render-feature-draw-recording-failed':
               return 'render feature draw recording failed';
+            case 'points-lines-invalid-style':
+              return 'points lines invalid style';
+            case 'points-lines-topology-mismatch':
+              return 'points lines topology mismatch';
+            case 'points-lines-style-unsupported':
+              return 'points lines style unsupported';
+            case 'points-lines-material-unsupported':
+              return 'points lines material unsupported';
+            case 'points-lines-budget-exceeded':
+              return 'points lines budget exceeded';
+            case 'points-lines-prepare-failed':
+              return 'points lines prepare failed';
           }
         }
         expect(exhaustive('equirect-projection-failed')).toBe('equirect projection failed');
@@ -620,6 +632,18 @@ type RuntimeLayerError = RenderError | AssetRuntimeError | SkinError;
               return 'ok';
             case 'render-feature-draw-recording-failed':
               return 'ok';
+            case 'points-lines-invalid-style':
+              return 'ok';
+            case 'points-lines-topology-mismatch':
+              return 'ok';
+            case 'points-lines-style-unsupported':
+              return 'ok';
+            case 'points-lines-material-unsupported':
+              return 'ok';
+            case 'points-lines-budget-exceeded':
+              return 'ok';
+            case 'points-lines-prepare-failed':
+              return 'ok';
           }
         }
         expect(exhaustive('hdrp-deferred-caps-insufficient')).toBe('ok');

package/src/__tests__/lights.unit.test.ts

@@ -2232,10 +2232,11 @@ function spawnValidatedLight(
     //
     // visibility flags mirror the WebGPU GPUShaderStage bitmask:
     //   VERTEX = 0x1, FRAGMENT = 0x2.
+    const VISIBILITY_VERTEX = 0x1;
     const VISIBILITY_FRAGMENT = 0x2;
     const VISIBILITY_VERTEX_FRAGMENT = 0x1 | 0x2;
 
-    describe('binding 8 = spotShadowMap (D-5 always-on, last view-BG entry)', () => {
+    describe('binding 8 = spotShadowMap (D-5 always-on shadow entry)', () => {
       it('declares binding 8 as a depth 2D texture, FRAGMENT-only', () => {
         const entries = buildPbrViewBglEntries({ storageBuffer: true });
         const b8 = entries.find((e) => e.binding === 8);
@@ -2253,10 +2254,12 @@ function spawnValidatedLight(
         expect(noStorage.some((e) => e.binding === 8)).toBe(true);
       });
 
-      it('binding 8 is the last entry (no binding 9)', () => {
+      it('reserves binding 9 and keeps Points/Lines at binding 10', () => {
         const entries = buildPbrViewBglEntries({ storageBuffer: true });
         expect(entries.some((e) => e.binding === 9)).toBe(false);
-        expect(entries.some((e) => e.binding === 10)).toBe(false);
+        const pointsLines = entries.find((e) => e.binding === 10);
+        expect(pointsLines?.buffer?.type).toBe('uniform');
+        expect(pointsLines?.visibility).toBe(VISIBILITY_VERTEX);
       });
     });
 
@@ -2272,18 +2275,19 @@ function spawnValidatedLight(
     // UBO (binding 0). This block locks that the spot matrices add ZERO new view
     // BGL buffer bindings (the WebGL2 budget invariant).
     describe('spotLightViewProj folded into View UBO (binding 0), not a new binding', () => {
-      it('view BGL declares no uniform buffer beyond binding 7 (only binding 0 = view, 6/7 = point/cascade)', () => {
+      it('view BGL includes only the vertex Points/Lines UBO beyond binding 7', () => {
         // Enumerate uniform-buffer entries on the view BGL. After the w25 fold,
-        // the only uniform buffers are binding 0 (View UBO, carries the spot
-        // matrices in its tail), binding 6 (point shadowParams) and binding 7
-        // (shadowCasterCascade). No standalone spot-matrix uniform buffer.
+        // uniform buffers are binding 0 (View UBO, carries the spot matrices
+        // in its tail), binding 6 (point shadowParams), binding 7
+        // (shadowCasterCascade), and binding 10 (Points/Lines view). No
+        // standalone spot-matrix uniform buffer exists.
         const entries = buildPbrViewBglEntries({ storageBuffer: true });
         const uniformBufferBindings = entries
           .filter((e) => e.buffer?.type === 'uniform')
           .map((e) => e.binding)
           .sort((a, b) => a - b);
         // storageBuffer=true: bindings 1+2 are read-only-storage (not uniform).
-        expect(uniformBufferBindings).toEqual([0, 6, 7]);
+        expect(uniformBufferBindings).toEqual([0, 6, 7, 10]);
       });
 
       it('storageBuffer=false: WebGL2 fallback uniform-buffer bindings stay within budget', () => {
@@ -2348,12 +2352,12 @@ function spawnValidatedLight(
       });
     });
 
-    describe('full binding roster is contiguous 0..8', () => {
-      it('exposes exactly bindings 0..8 with no gaps (binding 9 folded into View UBO, w25)', () => {
+    describe('full binding roster reserves 9 for Points/Lines at 10', () => {
+      it('exposes bindings 0..8 plus binding 10, with binding 9 reserved', () => {
         const bindings = buildPbrViewBglEntries({ storageBuffer: true })
           .map((e) => e.binding)
           .sort((a, b) => a - b);
-        expect(bindings).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8]);
+        expect(bindings).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 10]);
       });
     });
   });

package/src/__tests__/pbr-pipeline.unit.test.ts

@@ -44,7 +44,7 @@ function makeSpec(): PipelineSpec {
 
 describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', () => {
   describe('pbr-view', () => {
-    it('storageBuffer=true: 9 entries with read-only-storage on bindings 1+2', () => {
+    it('storageBuffer=true: 10 entries with read-only-storage on bindings 1+2', () => {
       const spec = makeSpec();
       const out = buildBindGroupLayoutDescriptor(spec, {
         kind: 'pbr-view',
@@ -56,12 +56,15 @@ describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', (
       };
       expect(out).toEqual(expected);
       // feat-20260625-spot-light-shadow-mapping: binding 8 (spot shadow atlas,
-      // w14) raised the view BGL to 9 entries (always-on, D-5). w25 (scope-amend
+      // w14) raised the view BGL to 9 entries (always-on, D-5). The
+      // Points/Lines viewport UBO occupies binding 10, while w25 (scope-amend
       // webkit-fallback) folded the former binding 9 spotLightViewProj matrices
       // UBO into the View UBO (`view.spotLightViewProj`), so the BGL stays at 9
-      // entries (bindings 0..8) — keeping the WebGL2 fallback fragment uniform-
+      // entries (bindings 0..8 plus binding 10) — keeping the WebGL2 fallback fragment uniform-
       // buffer count <= 11 (GLES 3.0).
-      expect(out.entries.length).toBe(9);
+      expect(out.entries.length).toBe(10);
+      expect(out.entries.find((entry) => entry.binding === 9)).toBeUndefined();
+      expect(out.entries.find((entry) => entry.binding === 10)?.buffer?.type).toBe('uniform');
     });
 
     it('storageBuffer=false: bindings 1+2 fall back to uniform', () => {

package/src/__tests__/render-error-exhaustive.test-d.ts

@@ -84,6 +84,18 @@ function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
       return code;
     case 'render-feature-draw-recording-failed':
       return code;
+    case 'points-lines-invalid-style':
+      return code;
+    case 'points-lines-topology-mismatch':
+      return code;
+    case 'points-lines-style-unsupported':
+      return code;
+    case 'points-lines-material-unsupported':
+      return code;
+    case 'points-lines-budget-exceeded':
+      return code;
+    case 'points-lines-prepare-failed':
+      return code;
     default: {
       const exhaustive: never = code;
       return exhaustive;
@@ -240,6 +252,30 @@ function narrowRenderError(err: RenderError): void {
       void err.detail.authoredValue;
       void err.detail.projected;
       break;
+    case 'points-lines-invalid-style':
+      void err.detail.component;
+      void err.detail.field;
+      break;
+    case 'points-lines-topology-mismatch':
+      void err.detail.submesh;
+      void err.detail.actual;
+      break;
+    case 'points-lines-style-unsupported':
+      void err.detail.member;
+      void err.detail.supported;
+      break;
+    case 'points-lines-material-unsupported':
+      void err.detail.material;
+      void err.detail.pass;
+      break;
+    case 'points-lines-budget-exceeded':
+      void err.detail.requested;
+      void err.detail.limit;
+      break;
+    case 'points-lines-prepare-failed':
+      void err.detail.owner;
+      void err.detail.generation;
+      break;
     default: {
       const exhaustive: never = err;
       void exhaustive;

package/src/__tests__/render-feature-prepared-graphics.browser.test.ts

@@ -45,6 +45,10 @@ describe('prepared graphics browser contract', () => {
     canvas.remove();
   });
 
+  // This negative path intentionally exercises a real WebGPU pipeline before
+  // the renderer reports the structured stage error. Its cold lavapipe start
+  // has exceeded Vitest's 15s default in CI; keep the assertion bounded at the
+  // owner rather than weakening the global browser timeout.
   it('reports forged prepared state through subscribe without renderer diagnostics getters', async () => {
     if (typeof navigator?.gpu?.requestAdapter !== 'function') {
       throw new Error('WebGPU is unavailable');
@@ -80,5 +84,5 @@ describe('prepared graphics browser contract', () => {
     });
     expect(renderer).not.toHaveProperty('renderFeatureDiagnostics');
     canvas.remove();
-  });
+  }, 30_000);
 });

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

@@ -49,6 +49,8 @@ describe('subscribe projects the discriminated Renderer event contract', () => {
           return `${event.previous}->${event.current}`;
         case 'error':
           return event.error.code;
+        case 'frame-submitted':
+          return `frame:${event.frameId}@${event.deviceGeneration}`;
       }
     };
     expectTypeOf(describeEvent).returns.toEqualTypeOf<string>();

package/src/__tests__/rhi-null-command-flow.unit.test.ts

@@ -17,6 +17,12 @@ function frameRequest(lease: Parameters<Renderer['draw']>[0]['leases'][number])
 describe('RhiNull command flow', () => {
   it('returns the synchronous receipt after the host submits a frame', async () => {
     const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    const events: Array<{
+      readonly kind: string;
+      readonly frameId?: number;
+      readonly deviceGeneration?: number;
+    }> = [];
+    const unsubscribe = renderer.subscribe((event) => events.push(event));
     const world = new World();
     const attached = renderer.attach(world);
     expect(attached.ok).toBe(true);
@@ -26,9 +32,17 @@ describe('RhiNull command flow', () => {
     const frame = renderer.draw(frameRequest(attached.value));
     expect(frame.ok).toBe(true);
     if (!frame.ok) return;
+    expect(events.filter((event) => event.kind === 'frame-submitted')).toEqual([
+      {
+        kind: 'frame-submitted',
+        frameId: frame.value.frameId,
+        deviceGeneration: frame.value.deviceGeneration,
+      },
+    ]);
     const completed = await frame.value.completed;
     expect(completed.ok).toBe(true);
     expect(renderer.inspect().frame.frameId).toBe(frame.value.frameId);
+    unsubscribe();
     renderer.dispose();
   });
 

package/src/__tests__/sprite-lit-bgl-byte-identical.test.ts

@@ -47,7 +47,7 @@ function makeSpec(shaderId: string): PipelineSpec {
 
 describe('sprite-lit BGL byte-identical to sprite (AC-07, w4/w5 close)', () => {
   describe('pbr-view BGL (light buffers; binding 1+2)', () => {
-    it('sprite-lit vs sprite share the same 9-entry pbr-view BGL under storage-buffer caps', () => {
+    it('sprite-lit vs sprite share the same 10-entry pbr-view BGL under storage-buffer caps', () => {
       const spriteSpec = makeSpec('forgeax::sprite');
       const spriteLitSpec = makeSpec('forgeax::sprite-lit');
       const sprite = buildBindGroupLayoutDescriptor(spriteSpec, {
@@ -59,10 +59,10 @@ describe('sprite-lit BGL byte-identical to sprite (AC-07, w4/w5 close)', () => {
         caps: { storageBuffer: true },
       });
       expect(JSON.stringify(spriteLit)).toBe(JSON.stringify(sprite));
-      expect(spriteLit.entries.length).toBe(9); // feat-20260625 spot shadow added binding 8 → view BGL grew 8→9
+      expect(spriteLit.entries.length).toBe(10); // binding 10 is the shared Points/Lines view UBO
     });
 
-    it('sprite-lit vs sprite share the same 9-entry pbr-view BGL under uniform fallback caps (AC-10)', () => {
+    it('sprite-lit vs sprite share the same 10-entry pbr-view BGL under uniform fallback caps (AC-10)', () => {
       const spriteSpec = makeSpec('forgeax::sprite');
       const spriteLitSpec = makeSpec('forgeax::sprite-lit');
       const sprite = buildBindGroupLayoutDescriptor(spriteSpec, {

package/src/__tests__/ssao-passes.test.ts

@@ -778,6 +778,10 @@ describe('post-process bindgroup identity cache (issue #670)', () => {
       views.bloomBlurV,
     );
     expect(bindGroupCreates[5]?.entries[0]?.resource.value).toBe(views.cubemap);
+    expect(bindGroupCreates[5]?.entries[2]?.resource.value).toEqual({
+      buffer: ctx.pipelineState.viewUniformBuffer,
+      size: 960,
+    });
 
     recordAll();
     expect(bindGroupCreates).toHaveLength(6);

package/src/collect-scene-asset.ts

@@ -44,8 +44,8 @@
 //   proven to be a mount entity, components is left undefined (one-time
 //   normalization on first reload; fixed-point from second collect onward).
 
-import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import {
+  builtinMeshGuid,
   resolveAssetHandle,
   SceneCollectAssetGuidUnresolvedError,
   SceneCollectEntityRefOutOfClosureError,
@@ -78,6 +78,11 @@ import type {
 } from '@forgeax/engine-types';
 import { foldMountOverrides } from './scene-utils/mount-override-fold';
 
+/** The collector needs identity lookup, not an authoring registry implementation. */
+export interface SceneAssetGuidLookup {
+  guidOf(asset: Asset): string | undefined;
+}
+
 // Shared helpers
 function _isArrayLike(value: unknown): value is ArrayLike<unknown> {
   // SceneAsset values are ordinary JSON arrays at the boundary. Use the
@@ -116,14 +121,16 @@ function classifyFieldSchema(fieldType: string | undefined): SchemaFieldClass |
 // lives in exactly one place; `field` names the failing field in the error.
 function _handleToGuid(
   world: World,
-  registry: AssetRegistry,
+  registry: SceneAssetGuidLookup,
   handle: number,
   field: string,
 ): Result<string | undefined, SceneCollectAssetGuidUnresolvedError> {
   if (handle === 0) return ok(undefined); // NULL sentinel
+  const builtinGuid = builtinMeshGuid(handle as unknown as Handle<string, 'shared'>);
+  if (builtinGuid !== undefined) return ok(builtinGuid);
   const assetRes = resolveAssetHandle(world, handle as unknown as Handle<string, 'shared'>);
   if (!assetRes.ok) return err(new SceneCollectAssetGuidUnresolvedError(field, handle));
-  const guid = registry._guidForAsset(assetRes.value as Asset);
+  const guid = registry.guidOf(assetRes.value as Asset);
   if (guid === undefined) return err(new SceneCollectAssetGuidUnresolvedError(field, handle));
   return ok(guid);
 }
@@ -135,7 +142,7 @@ function _handleToGuid(
 // values pass through untouched.
 function _serializeSharedFieldValue(
   world: World,
-  registry: AssetRegistry,
+  registry: SceneAssetGuidLookup,
   classification: SchemaFieldClass,
   value: unknown,
   field: string,
@@ -166,7 +173,7 @@ function _serializeSharedFieldValue(
 // override IS that field so it cannot be omitted). Non-shared fields pass through.
 function _serializeOverrideValueHandles(
   world: World,
-  registry: AssetRegistry,
+  registry: SceneAssetGuidLookup,
   ov: MountOverride,
 ): Result<unknown, SceneCollectAssetGuidUnresolvedError> {
   const comp = world.components.resolve(ov.comp);
@@ -253,7 +260,7 @@ export function serializeSceneAssetToPack(
  * filter (not subtree pruning): graft entities under members survive as owned.
  */
 export function rootsToSceneAsset(
-  registry: AssetRegistry,
+  registry: SceneAssetGuidLookup,
   world: World,
   roots: EntityHandle[],
 ): Result<
@@ -415,7 +422,7 @@ export function rootsToSceneAsset(
           sh.value as unknown as number,
         ),
       );
-    const g = registry._guidForAsset(pr.value as Asset);
+    const g = registry.guidOf(pr.value as Asset);
     if (g === undefined)
       return err(
         new SceneCollectAssetGuidUnresolvedError(

package/src/index.ts

@@ -326,7 +326,11 @@ export { quat } from '@forgeax/engine-math';
 // collectSceneAsset removed — replaced by rootsToSceneAsset (forest entry,
 // schema-derived field dispatch, engine-self-contained GUID resolution).
 // serializeSceneAssetToPack now uses schema-derived refs[] index (D-1/D-2).
-export { rootsToSceneAsset, serializeSceneAssetToPack } from './collect-scene-asset';
+export {
+  rootsToSceneAsset,
+  type SceneAssetGuidLookup,
+  serializeSceneAssetToPack,
+} from './collect-scene-asset';
 // feat-20260626 M6 / m6-4: debug-draw auto-attach glue is re-exported from the
 // main barrel (was a separate tsup entry). The separate entry produced a SECOND
 // module copy of the mutable `registeredDebugDraw` registry: createApp set it on