@forgeax/engine-runtime 0.1.21 → 0.1.24

package/src/__tests__/parse-scene-payload-refs.cases.unit.test.ts

@@ -0,0 +1,767 @@
+// @ts-nocheck — merged file: cross-source type narrowing failures from blocks originally outside src/ rootDir
+// Consolidated by feat-20260609-test-pool-startup-reduction-merge-tiny-test-files
+// biome-ignore-all lint/complexity/noUselessLoneBlockStatements: block-scope isolation between merged source files (consolidation paradigm)
+//
+// Source files (N=33):
+//   - packages/runtime/__tests__/asset-registry.test.ts
+//   - packages/runtime/__tests__/loader-registry.test.ts
+//   - packages/runtime/__tests__/wire-default-loaders.test.ts
+//   - packages/runtime/src/__tests__/asset-registry-aabb.test.ts
+//   - packages/runtime/src/__tests__/asset-registry-builtin-nineslice.test.ts
+//   - packages/runtime/src/__tests__/asset-registry-d9-tile-sampler-soft-warn.test.ts
+//   - packages/runtime/src/__tests__/asset-registry-guid.test.ts
+//   - packages/runtime/src/__tests__/asset-registry-material-validate.test.ts
+//   - packages/runtime/src/__tests__/asset-registry-mesh-fail-fast.test.ts
+//   - packages/runtime/src/__tests__/asset-registry-scene.test.ts
+//   - packages/runtime/src/__tests__/asset-registry-sprite-slices-validate.test.ts
+//   - packages/runtime/src/__tests__/auto-select.test.ts
+//   - packages/runtime/src/__tests__/bindgroup-resize-invalidation.test.ts
+//   - packages/runtime/src/__tests__/builtin-guid-ssot.test.ts
+//   - packages/runtime/src/__tests__/builtin-pack.test.ts
+//   - packages/runtime/src/__tests__/cube-texture-narrowing.test.ts
+//   - packages/runtime/src/__tests__/cubemap-upload.test.ts
+//   - packages/runtime/src/__tests__/dev-import-transport.test.ts
+//   - packages/runtime/src/__tests__/font-asset-load.test.ts
+//   - packages/runtime/src/__tests__/handle-quad.test.ts
+//   - packages/runtime/src/__tests__/lazy-catalog.test.ts
+//   - packages/runtime/src/__tests__/load-by-guid-hdr.test.ts
+//   - packages/runtime/src/__tests__/load-by-guid-prod-material-parent.test.ts
+//   - packages/runtime/src/__tests__/load-by-guid-prod.test.ts
+//   - packages/runtime/src/__tests__/mipmap-formula.test.ts
+//   - packages/runtime/src/__tests__/mipmap-pipeline-cache.test.ts
+//   - packages/runtime/src/__tests__/parse-asset-payload-material.test.ts
+//   - packages/runtime/src/__tests__/parse-asset-payload-texture.test.ts
+//   - packages/runtime/src/__tests__/parse-scene-payload-refs.test.ts
+//   - packages/runtime/src/__tests__/register-with-guid-rgba16float.test.ts
+//   - packages/runtime/src/__tests__/resolve-scene-guids.test.ts
+//   - packages/runtime/src/__tests__/upload-texture-consistency.test.ts
+//   - packages/runtime/src/__tests__/verify-revisions.test.ts
+//
+// Paradigm: each block-scope wraps a source file. ancestorTitles[0] is the
+// source-preserved inner describe (NOT the source filename for these 3 files
+// — recovery path: vitest report ancestorTitles -> grep this file -> upstream
+// `// ─── from <name>.test.ts ───` block separator -> source filename).
+// Top-level imports merged + deduped.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import * as assetRegistryModule from '@forgeax/engine-assets-runtime';
+import {
+  AssetRegistry,
+  animationClipLoader,
+  buildSceneChildContext,
+  fontLoader,
+  getOrCreateMipmapPipeline,
+  HANDLE_CUBE,
+  HANDLE_CYLINDER,
+  HANDLE_QUAD,
+  HANDLE_SPHERE,
+  HANDLE_TRIANGLE,
+  INLINE_PACK_LOADERS,
+  LoaderRegistry,
+  materialLoader,
+  meshLoader,
+  mipmapCacheSize,
+  numMipLevels,
+  PACK_ARTIFACT_LOADERS,
+  resolveAssetHandle,
+  sceneLoader,
+  skeletonLoader,
+  skinLoader,
+  textureLoader,
+  walkMaterialPassesOverSharedRefs,
+  wireDefaultLoaders,
+} from '@forgeax/engine-assets-runtime';
+import { audioLoader } from '@forgeax/engine-audio-webaudio';
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import {
+  createBoxGeometry,
+  createPlaneGeometry,
+  meshFromInterleaved,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+} from '@forgeax/engine-geometry';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { ok, ok as rhiOk } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import type {
+  EquirectAsset,
+  Handle,
+  MaterialAsset,
+  MaterialPass,
+  SamplerAsset,
+} from '@forgeax/engine-types';
+import { AssetError, toShared, toUnique, unwrapHandle } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi } from 'vitest';
+import { deriveBuiltin } from '../../../pack/src/builtin';
+import { DeviceScope } from '../../../render/src/device/device-scope';
+import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
+import { createEngineMetrics } from '../../../render/src/engine-metrics';
+import { createRenderer as createRuntimeRenderer } from '../createRenderer';
+import { createDevImportTransport, type ImportTransport } from '../dev-import-transport';
+import { EngineEnvironmentError } from '../errors/environment';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { requireRenderer } from './renderer-test-utils';
+
+vi.mock('@forgeax/engine-rhi-webgpu', async () => {
+  spies.webgpuImportCount += 1;
+  const actualRhi =
+    await vi.importActual<typeof import('@forgeax/engine-rhi')>('@forgeax/engine-rhi');
+  spies.rhiErrorCtor = actualRhi.RhiError;
+  const fakeAdapter = {
+    features: new Set<string>(),
+    limits: {} as Readonly<Record<string, number>>,
+    async requestDevice() {
+      return actualRhi.ok(makeFakeRhiDevice());
+    },
+  };
+  return {
+    rhi: {
+      requestAdapter: async () => {
+        if (spies.rhiWebgpuRequestAdapterShould === 'reject-rhi-not-available') {
+          return actualRhi.err(
+            new actualRhi.RhiError({
+              code: 'rhi-not-available',
+              expected: 'navigator.gpu available',
+              hint: 'unit-test: forced rhi-not-available',
+            }),
+          );
+        }
+        if (spies.rhiWebgpuRequestAdapterShould === 'reject-adapter-null') {
+          return actualRhi.err(
+            new actualRhi.RhiError({
+              code: 'adapter-unavailable',
+              expected: 'requestAdapter returns non-null',
+              hint: 'unit-test: forced adapter-unavailable',
+            }),
+          );
+        }
+        return actualRhi.ok(fakeAdapter);
+      },
+      acquireCanvasContext: (_canvas: unknown) => {
+        return actualRhi.ok({
+          configure: () => actualRhi.ok(undefined),
+          unconfigure: () => actualRhi.ok(undefined),
+          getCurrentTexture: () => actualRhi.ok({ __brand: 'TextureView' }),
+        });
+      },
+    },
+    createShaderModule: async () => actualRhi.ok({ __brand: 'ShaderModule' } as unknown as object),
+    translateErrorEventToRhiError: () =>
+      actualRhi.err(
+        new actualRhi.RhiError({
+          code: 'webgpu-runtime-error',
+          expected: 'GPU error event translates to RhiError',
+          hint: 'unit-test mock event translation',
+        }),
+      ),
+    _internal_getRawDevice: () => undefined,
+  };
+});
+vi.mock('@forgeax/engine-rhi-wgpu', async () => {
+  spies.wgpuImportCount += 1;
+  const actualRhi =
+    await vi.importActual<typeof import('@forgeax/engine-rhi')>('@forgeax/engine-rhi');
+  const fakeAdapter = {
+    features: new Set<string>(),
+    limits: {} as Readonly<Record<string, number>>,
+    async requestDevice() {
+      return actualRhi.ok(makeFakeRhiDevice());
+    },
+  };
+  return {
+    rhi: {
+      requestAdapter: async () => {
+        if (spies.rhiWgpuRequestAdapterShould === 'reject-rhi-not-available') {
+          return actualRhi.err(
+            new actualRhi.RhiError({
+              code: 'rhi-not-available',
+              expected: 'wgpu webgl backend available',
+              hint: 'unit-test: forced rhi-not-available on rhi-wgpu',
+            }),
+          );
+        }
+        return actualRhi.ok(fakeAdapter);
+      },
+      acquireCanvasContext: (_canvas: unknown) => {
+        return actualRhi.ok({
+          configure: () => actualRhi.ok(undefined),
+          unconfigure: () => actualRhi.ok(undefined),
+          getCurrentTexture: () => actualRhi.ok({ __brand: 'TextureView' }),
+        });
+      },
+    },
+    ensureReady: async () => {
+      spies.ensureReadyCount += 1;
+      if (spies.rhiWgpuEnsureReadyShould === 'reject-load-failed') {
+        throw new Error('unit-test: forced rhi-wgpu wasm load failure');
+      }
+      return undefined;
+    },
+    createShaderModule: async () => actualRhi.ok({ __brand: 'ShaderModule' } as unknown as object),
+    translateErrorEventToRhiError: () =>
+      actualRhi.err(
+        new actualRhi.RhiError({
+          code: 'webgpu-runtime-error',
+          expected: 'GPU error event translates to RhiError',
+          hint: 'unit-test mock event translation',
+        }),
+      ),
+    _internal_getRawDevice: () => undefined,
+  };
+});
+const spies = vi.hoisted(() => ({
+  webgpuImportCount: 0,
+  wgpuImportCount: 0,
+  ensureReadyCount: 0,
+  // Failure toggles set by individual tests before invoking createRenderer.
+  rhiWebgpuRequestAdapterShould: 'success' as
+    | 'success'
+    | 'reject-rhi-not-available'
+    | 'reject-adapter-null',
+  rhiWgpuEnsureReadyShould: 'success' as 'success' | 'reject-load-failed',
+  rhiWgpuRequestAdapterShould: 'success' as 'success' | 'reject-rhi-not-available',
+  rhiErrorCtor: undefined as undefined | (new (...args: never[]) => Error),
+  reset(): void {
+    this.webgpuImportCount = 0;
+    this.wgpuImportCount = 0;
+    this.ensureReadyCount = 0;
+    this.rhiWebgpuRequestAdapterShould = 'success';
+    this.rhiWgpuEnsureReadyShould = 'success';
+    this.rhiWgpuRequestAdapterShould = 'success';
+  },
+}));
+function makeFakeRhiDevice(): Record<string, unknown> {
+  let resolveLost!: (info: unknown) => void;
+  const lost = new Promise<unknown>((res) => {
+    resolveLost = res;
+  });
+  void resolveLost;
+  return {
+    __brand: 'RhiDevice',
+    lost,
+    features: new Set<string>(),
+    limits: {},
+    // feat-20260707 M5 / w33: createRenderer projects RhiCaps.textureCompression*
+    // into TranscodeCaps right after building the registry, so the fake device
+    // must expose a caps object (the real RhiDevice always carries one).
+    caps: {
+      textureCompressionBc: false,
+      textureCompressionEtc2: false,
+      textureCompressionAstc: false,
+    },
+    queue: {
+      submit: () => undefined,
+      writeBuffer: () => undefined,
+    },
+    createBuffer: () => ({ ok: true, value: { __brand: 'Buffer' } }),
+    createTexture: () => ({ ok: true, value: { __brand: 'Texture' } }),
+    createBindGroupLayout: () => ({ ok: true, value: { __brand: 'BindGroupLayout' } }),
+    createBindGroup: () => ({ ok: true, value: { __brand: 'BindGroup' } }),
+    createPipelineLayout: () => ({ ok: true, value: { __brand: 'PipelineLayout' } }),
+    createRenderPipeline: () => ({ ok: true, value: { __brand: 'RenderPipeline' } }),
+    createSampler: () => ({ ok: true, value: { __brand: 'Sampler' } }),
+    createShaderModule: () => ({
+      ok: true,
+      value: { __brand: 'ShaderModule' },
+    }),
+    createTextureView: () => ({ ok: true, value: { __brand: 'TextureView' } }),
+    createCommandEncoder: () => ({
+      ok: true,
+      value: {
+        beginRenderPass: () => ({
+          setPipeline: () => undefined,
+          setBindGroup: () => undefined,
+          setVertexBuffer: () => undefined,
+          setIndexBuffer: () => undefined,
+          draw: () => undefined,
+          drawIndexed: () => undefined,
+          end: () => undefined,
+        }),
+        finish: () => ({ __brand: 'CommandBuffer' }),
+      },
+    }),
+  };
+}
+function makeMockCanvas(opts: { webgpu?: 'context' | 'null'; webgl2?: 'context' | 'null' }) {
+  return {
+    width: 800,
+    height: 600,
+    getContext(kind: string): unknown {
+      if (kind === 'webgpu') {
+        if (opts.webgpu === 'context') {
+          return {
+            __mockTag: 'webgpu-canvas-context',
+            configure: () => undefined,
+            unconfigure: () => undefined,
+            getCurrentTexture: () => ({ createView: () => ({}) }),
+          };
+        }
+        return null;
+      }
+      if (kind === 'webgl2') {
+        if (opts.webgl2 === 'context') {
+          return {
+            __mockTag: 'webgl2',
+            getExtension: () => null,
+            getParameter: () => 1,
+            isContextLost: () => false,
+          };
+        }
+        return null;
+      }
+      return null;
+    },
+    addEventListener() {},
+    removeEventListener() {},
+  } as unknown as HTMLCanvasElement;
+}
+function _makeStubGPU(): unknown {
+  return {
+    requestAdapter: async () => ({
+      features: new Set<string>(),
+      limits: {},
+      requestDevice: async () => makeFakeRhiDevice(),
+    }),
+    getPreferredCanvasFormat: () => 'bgra8unorm',
+  };
+}
+
+void [
+  AssetError,
+  AssetGuid,
+  AssetRegistry,
+  DeviceScope,
+  EngineEnvironmentError,
+  GpuResidencyCache,
+  HANDLE_CUBE,
+  HANDLE_CYLINDER,
+  HANDLE_QUAD,
+  HANDLE_SPHERE,
+  HANDLE_TRIANGLE,
+  INLINE_PACK_LOADERS,
+  LoaderRegistry,
+  PACK_ARTIFACT_LOADERS,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+  ShaderRegistry,
+  World,
+  _makeStubGPU,
+  afterEach,
+  animationClipLoader,
+  assetRegistryModule,
+  audioLoader,
+  beforeEach,
+  buildSceneChildContext,
+  createBoxGeometry,
+  createDevImportTransport,
+  createEngineMetrics,
+  createPlaneGeometry,
+  createRuntimeRenderer,
+  defineComponent,
+  deriveBuiltin,
+  describe,
+  expect,
+  expectTypeOf,
+  fileURLToPath,
+  fontLoader,
+  getOrCreateMipmapPipeline,
+  it,
+  makeFakeRhiDevice,
+  makeMockCanvas,
+  makeMockShaderRegistry,
+  materialLoader,
+  meshFromInterleaved,
+  meshLoader,
+  mipmapCacheSize,
+  numMipLevels,
+  ok,
+  readFileSync,
+  requireRenderer,
+  resolveAssetHandle,
+  rhi,
+  rhiOk,
+  sceneLoader,
+  skeletonLoader,
+  skinLoader,
+  spies,
+  textureLoader,
+  toShared,
+  toUnique,
+  unwrapHandle,
+  vi,
+  walkMaterialPassesOverSharedRefs,
+  wireDefaultLoaders,
+];
+type __MergedKeep =
+  | EquirectAsset
+  | Handle
+  | ImportTransport
+  | MaterialAsset
+  | MaterialPass
+  | SamplerAsset;
+
+{
+  // --- from parse-scene-payload-refs.test.ts ---
+  /** Access the private parseAssetPayload method via structural view-cast. */
+  function accessParseScenePayload(reg: AssetRegistry) {
+    // biome-ignore lint/suspicious/noExplicitAny: private method access for unit test
+    const internal = reg as any as {
+      parseAssetPayload(kind: string, payload: Record<string, unknown>, refs?: string[]): unknown;
+    };
+    return (
+      kind: string,
+      payload: Record<string, unknown>,
+      refs?: string[],
+    ): SceneAsset | undefined => {
+      const result = internal.parseAssetPayload(kind, payload, refs);
+      if (result === undefined) return undefined;
+      if (
+        typeof result === 'object' &&
+        result !== null &&
+        'kind' in result &&
+        result.kind === 'scene'
+      ) {
+        return result as SceneAsset;
+      }
+      return undefined;
+    };
+  }
+
+  const GUID_A = 'cbe42beb-8975-5096-b3a1-3dda4cb4c077';
+  const GUID_B = 'f6af7007-158f-4d92-9e47-93bf2f213e1f';
+
+  describe('w1 - parseScenePayload refs normal paths (AC-01)', () => {
+    it('replaces number field values with refs[N] GUID string', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const refs = [GUID_A, GUID_B];
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: {
+              MeshFilter: { assetHandle: 0 },
+              MeshRenderer: { materials: [1] },
+            },
+          },
+        ],
+      };
+      const asset = fn('scene', payload, refs);
+      expect(asset).toBeDefined();
+      if (!asset) return;
+      expect(asset.kind).toBe('scene');
+      expect(asset.entities.length).toBe(1);
+      const comp = asset.entities[0]?.components as Record<string, Record<string, unknown>>;
+      expect(comp.MeshFilter?.assetHandle).toBe(GUID_A); // refs[0]
+      expect(comp.MeshRenderer?.materials).toEqual([GUID_B]); // refs[1]
+    });
+
+    it('replaces refs index 0 (valid zero-index)', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const refs = [GUID_A];
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: { MeshFilter: { assetHandle: 0 } },
+          },
+        ],
+      };
+      const asset = fn('scene', payload, refs);
+      expect(asset).toBeDefined();
+      if (!asset) return;
+      const comp = asset.entities[0]?.components as Record<string, Record<string, unknown>>;
+      expect(comp.MeshFilter?.assetHandle).toBe(GUID_A);
+    });
+
+    it('keeps non-integer number fields unchanged (float values are not refs indices)', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const refs = [GUID_A];
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: {
+              Transform: { pos: [1.5, 2.7, -3.2] },
+              DirectionalLight: { color: 'white', intensity: 0.8 },
+            },
+          },
+        ],
+      };
+      const asset = fn('scene', payload, refs);
+      expect(asset).toBeDefined();
+      if (!asset) return;
+      const comp = asset.entities[0]?.components as Record<string, Record<string, unknown>>;
+      // Non-integer float values are not refs indices — passed through unchanged.
+      expect(comp.Transform?.pos).toEqual([1.5, 2.7, -3.2]);
+      expect(comp.DirectionalLight?.color).toBe('white');
+      expect(comp.DirectionalLight?.intensity).toBe(0.8);
+    });
+
+    it('keeps non-handle integer fields unchanged (Transform posX=0, ChildOf.parent=0)', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const refs = [GUID_A];
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: {
+              ChildOf: { parent: 0 },
+              Transform: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+              MeshFilter: { assetHandle: 0 },
+            },
+          },
+        ],
+      };
+      const asset = fn('scene', payload, refs);
+      expect(asset).toBeDefined();
+      if (!asset) return;
+      const comp = asset.entities[0]?.components as Record<string, Record<string, unknown>>;
+      // Non-handle integer fields are kept as-is (M1-fixup F-1)
+      expect(comp.ChildOf?.parent).toBe(0);
+      expect(comp.Transform?.pos).toEqual([0, 0, 0]);
+      expect(comp.Transform?.quat).toEqual([0, 0, 0, 1]);
+      expect(comp.Transform?.scale).toEqual([1, 1, 1]);
+      // Handle fields are replaced with GUID strings
+      expect(comp.MeshFilter?.assetHandle).toBe(GUID_A);
+    });
+
+    it('multiple nodes all resolve refs correctly', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const refs = [GUID_A, GUID_B];
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: { MeshFilter: { assetHandle: 0 } },
+          },
+          {
+            localId: 1,
+            components: { MeshFilter: { assetHandle: 1 } },
+          },
+          {
+            localId: 2,
+            components: { MeshRenderer: { materials: [0] } },
+          },
+        ],
+      };
+      const asset = fn('scene', payload, refs);
+      expect(asset).toBeDefined();
+      if (!asset) return;
+      expect(asset.entities.length).toBe(3);
+      const comp0 = asset.entities[0]?.components as Record<string, Record<string, unknown>>;
+      const comp1 = asset.entities[1]?.components as Record<string, Record<string, unknown>>;
+      const comp2 = asset.entities[2]?.components as Record<string, Record<string, unknown>>;
+      expect(comp0.MeshFilter?.assetHandle).toBe(GUID_A);
+      expect(comp1.MeshFilter?.assetHandle).toBe(GUID_B);
+      expect(comp2.MeshRenderer?.materials).toEqual([GUID_A]);
+    });
+  });
+
+  describe('w2 - parseScenePayload refs error paths (AC-02, AC-08)', () => {
+    it('returns undefined when refs index is out of bounds (N >= refs.length)', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const refs = [GUID_A]; // length=1, valid indices: 0 only
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: { MeshFilter: { assetHandle: 1 } }, // N=1 >= refs.length
+          },
+        ],
+      };
+      const result = fn('scene', payload, refs);
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined when refs is empty and handle field references index 0', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const refs: string[] = [];
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: { MeshFilter: { assetHandle: 0 } }, // N=0 >= refs.length (0 >= 0)
+          },
+        ],
+      };
+      const result = fn('scene', payload, refs);
+      expect(result).toBeUndefined();
+    });
+
+    it('stops on first error (AC-08): only first out-of-bounds node triggers failure', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const refs = [GUID_A]; // length=1
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: { MeshFilter: { assetHandle: 1 } }, // first node: out of bounds
+          },
+          {
+            localId: 1,
+            components: { MeshFilter: { assetHandle: 0 } }, // second node: valid, but should not be reached
+          },
+        ],
+      };
+      // parseScenePayload returns undefined on first error, so result is undefined
+      // regardless of the second node's validity
+      const result = fn('scene', payload, refs);
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined when index is negative', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const refs = [GUID_A];
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: { MeshFilter: { assetHandle: -1 } },
+          },
+        ],
+      };
+      const result = fn('scene', payload, refs);
+      expect(result).toBeUndefined();
+    });
+
+    it('backward compat: parseScenePayload without refs returns SceneAsset with numbers unchanged', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: {
+              MeshFilter: { assetHandle: 42 },
+              MeshRenderer: { materials: [1024] },
+            },
+          },
+        ],
+      };
+      // No refs passed -- old call signature, numbers should pass through
+      const asset = fn('scene', payload);
+      expect(asset).toBeDefined();
+      if (!asset) return;
+      const comp = asset.entities[0]?.components as Record<string, Record<string, unknown>>;
+      expect(comp.MeshFilter?.assetHandle).toBe(42);
+      expect(comp.MeshRenderer?.materials).toEqual([1024]);
+    });
+
+    it('ignores all integer fields without refs and keeps them as-is (non-handle integers)', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const fn = accessParseScenePayload(reg);
+      const refs = [GUID_A];
+      const payload = {
+        entities: [
+          {
+            localId: 0,
+            components: { Transform: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+          },
+        ],
+      };
+      const asset = fn('scene', payload, refs);
+      expect(asset).toBeDefined();
+      if (!asset) return;
+      const comp = asset.entities[0]?.components as Record<string, Record<string, unknown>>;
+      // M1-fixup F-1: non-handle integer fields (Transform) are preserved as-is.
+      // Only fields in the HANDLE_FIELD_NAMES allowlist get refs resolution.
+      expect(comp.Transform?.pos).toEqual([0, 0, 0]);
+      expect(comp.Transform?.quat).toEqual([0, 0, 0, 1]);
+      expect(comp.Transform?.scale).toEqual([1, 1, 1]);
+    });
+  });
+
+  describe('w2 - fetchPackFile wrapping produces AssetError for failed parse', () => {
+    it('loadByGuid returns asset-parse-failed when scene refs index is out of bounds', async () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      const guid = AssetGuid.parse('00000000-0000-7000-8000-000000000099');
+      if (!guid.ok) throw new Error('expected ok');
+
+      // Register a pack file with a scene containing out-of-bounds refs.
+      // parseAssetPayload returns { ok: false, error }, then fetchPackFile
+      // wraps it as asset-parse-failed.
+      const badPayload = {
+        entities: [
+          {
+            localId: 0,
+            components: { MeshFilter: { assetHandle: 5 } }, // refs length is 3, 5 is out of bounds
+          },
+        ],
+      };
+      const packEntry = {
+        guid: '00000000-0000-7000-8000-000000000099',
+        kind: 'scene',
+        payload: badPayload,
+        refs: [
+          'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+          '11111111-2222-3333-4444-555555555555',
+          'ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj',
+        ],
+      };
+
+      // registerWithGuid wraps the raw pack entry lookup — loadByGuid dev path
+      // directly hits the guid->handle map without fetchPackFile. We verify
+      // the parse failure through the parseAssetPayload structural access
+      // (the fetchPackFile path is an integration concern for smoke tests).
+      // For unit test: use loadByGuid's dev path which registers a
+      // scene asset directly. When we call parseAssetPayload with the
+      // bad refs, it returns undefined, which would become asset-parse-failed
+      // through fetchPackFile.
+      // biome-ignore lint/suspicious/noExplicitAny: private method access
+      const internal = reg as any as {
+        parseAssetPayload(kind: string, payload: Record<string, unknown>, refs?: string[]): unknown;
+      };
+      // F21: scene refs out-of-bounds returns the structured error inline via
+      // the LoaderOutput { ok: false, error } arm (no instance-slot side effect).
+      const result = internal.parseAssetPayload('scene', badPayload, packEntry.refs) as {
+        ok: false;
+        error: { index: number; refsLength: number };
+      };
+      expect(result.ok).toBe(false);
+      expect(result.error.index).toBe(5);
+    });
+
+    it('parseScenePayload returns structured ParseSceneError on refs out-of-bounds (F-2 / AC-02)', () => {
+      const reg = new AssetRegistry(makeMockShaderRegistry());
+      // biome-ignore lint/suspicious/noExplicitAny: private method access
+      const internal = reg as any;
+      const badPayload = {
+        entities: [
+          {
+            localId: 42,
+            components: { MeshFilter: { assetHandle: 5 } },
+          },
+        ],
+      };
+      const refs = ['guid-a', 'guid-b']; // length=2, 5 is out of bounds
+      // F21: the structured error is the return value's `error` field, not a
+      // shared instance slot.
+      const result = internal.parseAssetPayload('scene', badPayload, refs) as {
+        ok: false;
+        error: {
+          localId: number;
+          component: string;
+          field: string;
+          index: number;
+          refsLength: number;
+        };
+      };
+      expect(result.ok).toBe(false);
+      const err = result.error;
+      expect(err.localId).toBe(42);
+      expect(err.component).toBe('MeshFilter');
+      expect(err.field).toBe('assetHandle');
+      expect(err.index).toBe(5);
+      expect(err.refsLength).toBe(2);
+    });
+  });
+}