@forgeax/engine-assets-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/registry-load-state.unit.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { LoadStateStore } from '../registry/load-state';
+
+const ROOT = '11111111-1111-4111-8111-111111111111';
+const REF = '22222222-2222-4222-8222-222222222222';
+
+describe('registry load state', () => {
+  it('keeps provisional records out of the public-ready fast path', () => {
+    const states = new LoadStateStore();
+    states.begin(ROOT, [REF]);
+    states.resolveAsset(ROOT, { kind: 'root' });
+
+    expect(states.get(ROOT)?.status).toBe('provisional');
+    expect(states.getReady(ROOT)).toBeUndefined();
+
+    states.begin(REF, []);
+    states.resolveAsset(REF, { kind: 'ref' });
+    states.promoteReady(REF);
+    states.promoteReady(ROOT);
+    expect(states.getReady(ROOT)).toEqual({ kind: 'root' });
+  });
+
+  it('purges a failed closure and returns to Unloaded for retry', () => {
+    const states = new LoadStateStore();
+    states.begin(ROOT, [REF]);
+    states.begin(REF, []);
+    states.resolveAsset(ROOT, { kind: 'root' });
+    states.fail(ROOT, { code: 'artifact-failed' });
+
+    expect(states.get(ROOT)?.status).toBe('unloaded');
+    expect(states.get(REF)?.status).toBe('unloaded');
+    expect(states.getReady(ROOT)).toBeUndefined();
+    expect(states.begin(ROOT, [REF]).status).toBe('provisional');
+  });
+});

package/src/__tests__/registry-package-cache.unit.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it, vi } from 'vitest';
+import { AssetRegistry } from '../asset-registry';
+
+const GUID_A = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
+const GUID_B = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb';
+
+function pack() {
+  return {
+    schemaVersion: '2.0.0',
+    kind: 'internal-text-package',
+    assets: [
+      { guid: GUID_A, kind: 'host-blob', payload: { value: 'a' }, refs: [], artifacts: {} },
+      { guid: GUID_B, kind: 'host-blob', payload: { value: 'b' }, refs: [], artifacts: {} },
+    ],
+  };
+}
+
+function registryWithLoader() {
+  const registry = new AssetRegistry({} as never);
+  registry.loaders.register({
+    kind: 'host-blob',
+    load: (payload) => ({ kind: 'host-blob', ...payload }),
+  });
+  return registry;
+}
+
+describe('registry package cache', () => {
+  it('fetches and parses a shared package once for concurrent assets', async () => {
+    const registry = registryWithLoader();
+    registry.configurePackIndex('/pack-index.json');
+    const fetcher = vi.fn(async (url: string) => {
+      if (url.endsWith('pack-index.json')) {
+        return new Response(
+          JSON.stringify([
+            { guid: GUID_A, packageUrl: '/shared.pack.json', kind: 'host-blob', sourcePath: 'a' },
+            { guid: GUID_B, packageUrl: '/shared.pack.json', kind: 'host-blob', sourcePath: 'b' },
+          ]),
+        );
+      }
+      return new Response(JSON.stringify(pack()));
+    });
+    vi.stubGlobal('fetch', fetcher);
+
+    const [a, b] = await Promise.all([
+      registry.loadByGuid<{ kind: string; value: string }>(registry.parseGuid(GUID_A)),
+      registry.loadByGuid<{ kind: string; value: string }>(registry.parseGuid(GUID_B)),
+    ]);
+
+    expect(a.ok).toBe(true);
+    expect(b.ok).toBe(true);
+    expect(fetcher.mock.calls.filter(([url]) => url.endsWith('shared.pack.json'))).toHaveLength(1);
+  });
+});

package/src/__tests__/registry-public-ready.unit.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { LoadStateStore } from '../registry/load-state';
+
+const ROOT = '11111111-1111-4111-8111-111111111111';
+const REF = '22222222-2222-4222-8222-222222222222';
+
+describe('public-ready fast path', () => {
+  it('returns only SCC-promoted values and never provisional or failed records', () => {
+    const states = new LoadStateStore();
+    states.begin(ROOT, [REF]);
+    states.resolveAsset(ROOT, { kind: 'root' });
+    expect(states.getReady(ROOT)).toBeUndefined();
+
+    states.begin(REF, []);
+    states.resolveAsset(REF, { kind: 'ref' });
+    states.fail(REF, { code: 'missing-artifact' });
+    expect(states.getReady(ROOT)).toBeUndefined();
+    expect(states.getReady(REF)).toBeUndefined();
+
+    states.begin(ROOT, [REF]);
+    states.begin(REF, []);
+    states.resolveAsset(REF, { kind: 'ref' });
+    states.resolveAsset(ROOT, { kind: 'root' });
+    states.promoteReady(REF);
+    states.promoteReady(ROOT);
+    expect(states.getReady(ROOT)).toEqual({ kind: 'root' });
+  });
+
+  it('purge removes the old failure so retry uses a new record', () => {
+    const states = new LoadStateStore();
+    states.begin(ROOT, []);
+    states.fail(ROOT, { code: 'decode-failed' });
+    expect(states.get(ROOT)?.status).toBe('unloaded');
+    const retry = states.begin(ROOT, []);
+    expect(retry.status).toBe('provisional');
+    expect(retry.error).toBeUndefined();
+  });
+});

package/src/__tests__/resolve-asset-handle.unit.test.ts

@@ -0,0 +1,238 @@
+// @forgeax/engine-assets-runtime -- resolveAssetHandle + material-walk coverage
+// (fix issue #709). Exercises the two-tier slot dispatch (builtin vs user-tier),
+// the stale/released/not-found error arms, and the material parent-chain walk
+// (single, inherited, override-by-name, missing-parent, cycle).
+
+import { World } from '@forgeax/engine-ecs';
+import type { Asset, Handle, MaterialAsset } from '@forgeax/engine-types';
+import { BUILTIN_BASE, handleGeneration, handleSlot, toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { HANDLE_CUBE } from '../handles';
+import { resolveAssetHandle, walkMaterialPassesOverSharedRefs } from '../resolve-asset-handle';
+
+describe('resolveAssetHandle two-tier dispatch', () => {
+  it('resolves a builtin mesh handle (slot < BUILTIN_BASE)', () => {
+    const res = resolveAssetHandle(new World(), HANDLE_CUBE as Handle<string, 'shared'>);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect((res.value as { kind: string }).kind).toBe('mesh');
+  });
+
+  it('errors with asset-not-found for an unoccupied builtin slot', () => {
+    const bogus = toShared<'MeshAsset'>(999); // in [1, BUILTIN_BASE) but not a real builtin
+    const res = resolveAssetHandle(new World(), bogus as Handle<string, 'shared'>);
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect((res.error as { code: string }).code).toBe('asset-not-found');
+  });
+
+  it('resolves a user-tier handle minted via allocSharedRef', () => {
+    const world = new World();
+    const payload = { kind: 'material', passes: [] } as unknown as Asset;
+    const handle = world.allocSharedRef('MaterialAsset', payload);
+    const res = resolveAssetHandle(world, handle as Handle<string, 'shared'>);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.value).toBe(payload);
+  });
+
+  it('forwards the stale error after the handle slot is released + re-allocated', () => {
+    const world = new World();
+    const handle = world.allocSharedRef('MaterialAsset', { kind: 'material' } as unknown as Asset);
+    world.sharedRefs.release(handle as Handle<string, 'shared'>);
+    // Releasing bumps the slot generation, so the stale handle now resolves to
+    // the transparently-forwarded shared-ref-stale error (D-3 / AC-10), not a
+    // flattened asset-not-found.
+    const res = resolveAssetHandle(world, handle as Handle<string, 'shared'>);
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect((res.error as { code: string }).code).toBe('shared-ref-stale');
+  });
+
+  it('forwards exact stale detail without exposing the replacement payload', () => {
+    const world = new World();
+    const oldPayload = { kind: 'material', values: { baseColor: [1, 0, 0] } } as unknown as Asset;
+    const oldHandle = world.allocSharedRef('MaterialAsset', oldPayload);
+    const oldSlot = handleSlot(oldHandle);
+    const oldGeneration = handleGeneration(oldHandle);
+
+    expect(world.sharedRefs.release(oldHandle).ok).toBe(true);
+    const replacementPayload = {
+      kind: 'material',
+      values: { baseColor: [0, 0, 1] },
+    } as unknown as Asset;
+    const replacementHandle = world.allocSharedRef('MaterialAsset', replacementPayload);
+
+    expect(handleSlot(replacementHandle)).toBe(oldSlot);
+    expect(handleGeneration(replacementHandle)).toBe(oldGeneration + 1);
+
+    const res = resolveAssetHandle(world, oldHandle as Handle<string, 'shared'>);
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect(res.error.code).toBe('shared-ref-stale');
+    expect(res.error.detail).toEqual({
+      slot: oldSlot,
+      expectedGeneration: oldGeneration,
+      actualGeneration: handleGeneration(replacementHandle),
+    });
+    expect('value' in res.error).toBe(false);
+
+    const foreignModuleWorld = {
+      sharedRefs: {
+        resolve: () => ({
+          ok: false,
+          error: {
+            code: 'shared-ref-stale' as const,
+            detail: {
+              slot: oldSlot,
+              expectedGeneration: oldGeneration,
+              actualGeneration: handleGeneration(replacementHandle),
+            },
+          },
+        }),
+      },
+    } as unknown as World;
+    const bridged = resolveAssetHandle(foreignModuleWorld, oldHandle as Handle<string, 'shared'>);
+    expect(bridged).toEqual({
+      ok: false,
+      error: {
+        code: 'shared-ref-stale',
+        detail: {
+          slot: oldSlot,
+          expectedGeneration: oldGeneration,
+          actualGeneration: handleGeneration(replacementHandle),
+        },
+      },
+    });
+
+    const replacement = resolveAssetHandle(world, replacementHandle as Handle<string, 'shared'>);
+    expect(replacement).toMatchObject({ ok: true, value: replacementPayload });
+    expect(replacement.ok && replacement.value).not.toBe(oldPayload);
+  });
+
+  it('errors with asset-not-found for an unallocated user-tier slot', () => {
+    const res = resolveAssetHandle(
+      new World(),
+      toShared<'MeshAsset'>(BUILTIN_BASE + 5) as Handle<string, 'shared'>,
+    );
+    expect(res.ok).toBe(false);
+  });
+});
+
+function mat(over: Partial<MaterialAsset>): MaterialAsset {
+  return { kind: 'material', ...over } as MaterialAsset;
+}
+
+describe('walkMaterialPassesOverSharedRefs', () => {
+  it('returns the passes of a single childless material', () => {
+    const world = new World();
+    const handle = world.allocSharedRef(
+      'MaterialAsset',
+      mat({
+        passes: [{ name: 'main', program: { module: 'forgeax::standard' } }],
+        values: { a: 1 },
+      }),
+    );
+    const res = walkMaterialPassesOverSharedRefs(world, handle, { lookup: () => undefined });
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.value.passes.map((p) => p.name)).toEqual(['main']);
+    expect(res.value.values).toEqual({ a: 1 });
+  });
+
+  it('inherits parent passes when the child declares none, merging values', () => {
+    const world = new World();
+    const parent = mat({
+      passes: [{ name: 'base', program: { module: 'forgeax::standard' } }],
+      values: { a: 1, b: 2 },
+    });
+    const child = mat({ parent: 'p-guid' as never, values: { b: 20 } });
+    const handle = world.allocSharedRef('MaterialAsset', child);
+    const res = walkMaterialPassesOverSharedRefs(world, handle, { lookup: () => parent });
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.value.passes.map((p) => p.name)).toEqual(['base']);
+    expect(res.value.values).toEqual({ a: 1, b: 20 }); // child overrides
+  });
+
+  it('inherits the root parameter contract without child declaration merging', () => {
+    const world = new World();
+    const parent = mat({
+      passes: [{ name: 'base', program: { module: 'forgeax::standard' } }],
+      parameters: [
+        { name: 'baseColor', type: 'color' },
+        { name: 'roughness', type: 'f32' },
+      ],
+    });
+    const child = mat({
+      parent: 'p-guid' as never,
+      parameters: [
+        { name: 'roughness', type: 'f32' },
+        { name: 'normalTexture', type: 'texture' },
+      ],
+    });
+    const handle = world.allocSharedRef('MaterialAsset', child);
+    const res = walkMaterialPassesOverSharedRefs(world, handle, { lookup: () => parent });
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.value.parameters).toEqual([
+      { name: 'baseColor', type: 'color' },
+      { name: 'roughness', type: 'f32' },
+    ]);
+  });
+
+  it('child passes override parent by name and append new ones', () => {
+    const world = new World();
+    const parent = mat({
+      passes: [
+        { name: 'shadow', program: { module: 'forgeax::shadow' } },
+        { name: 'main', program: { module: 'forgeax::parent-main' } },
+      ],
+    });
+    const child = mat({
+      parent: 'p-guid' as never,
+      passes: [
+        { name: 'main', program: { module: 'forgeax::child-main' } },
+        { name: 'extra', program: { module: 'forgeax::extra' } },
+      ],
+    });
+    const handle = world.allocSharedRef('MaterialAsset', child);
+    const res = walkMaterialPassesOverSharedRefs(world, handle, { lookup: () => parent });
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    const byName = new Map(res.value.passes.map((p) => [p.name, p.program.module]));
+    expect(byName.get('main')).toBe('forgeax::child-main'); // overridden
+    expect(byName.get('extra')).toBe('forgeax::extra'); // appended
+    expect(byName.get('shadow')).toBe('forgeax::shadow'); // inherited
+  });
+
+  it('errors when the parent is not catalogued', () => {
+    const world = new World();
+    const child = mat({ parent: 'missing-guid' as never });
+    const handle = world.allocSharedRef('MaterialAsset', child);
+    const res = walkMaterialPassesOverSharedRefs(world, handle, { lookup: () => undefined });
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect((res.error as { code: string }).code).toBe('material-parent-not-found');
+  });
+
+  it('detects a parent cycle', () => {
+    const world = new World();
+    // A -> B -> A: lookup returns a material whose parent points back.
+    const a = mat({ parent: 'guid-b' as never });
+    const b = mat({ parent: 'guid-a' as never });
+    const handle = world.allocSharedRef('MaterialAsset', a);
+    const registry = {
+      lookup: (guid: string | { toString(): string }) => {
+        const g = String(guid).toLowerCase();
+        if (g.includes('guid-b')) return b;
+        if (g.includes('guid-a')) return a;
+        return undefined;
+      },
+    };
+    const res = walkMaterialPassesOverSharedRefs(world, handle, registry as never);
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect((res.error as { code: string }).code).toBe('material-circular-inheritance');
+  });
+});

package/src/__tests__/scene-handle-fields.unit.test.ts

@@ -0,0 +1,129 @@
+// @forgeax/engine-assets-runtime -- scene-handle-fields coverage (fix issue #709).
+// extractSceneEntityHandleGuids + extractMountOverrideHandleGuids identify
+// shared<T> / array<shared<T>> schema fields via resolveComponent and read the
+// raw GUID string(s). Uses test-unique component names to avoid colliding with
+// the engine's real component registry in the shared coverage run.
+
+import { type Component, defineComponent } from '@forgeax/engine-ecs';
+import type { MountOverride } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  extractMountOverrideHandleGuids,
+  extractSceneEntityHandleGuids,
+} from '../scene-handle-fields';
+
+const T709MeshFilter = defineComponent('T709MeshFilter', { assetHandle: 'shared<MeshAsset>' });
+const T709MeshRenderer = defineComponent('T709MeshRenderer', {
+  materials: 'array<shared<MaterialAsset>>',
+});
+const T709Transform = defineComponent('T709Transform', { x: 'f32' });
+const components = new Map<string, Component>([
+  [T709MeshFilter.name, T709MeshFilter],
+  [T709MeshRenderer.name, T709MeshRenderer],
+  [T709Transform.name, T709Transform],
+]);
+
+describe('extractSceneEntityHandleGuids', () => {
+  it('extracts scalar shared<T> GUID strings', () => {
+    const entries = extractSceneEntityHandleGuids(components, [
+      { localId: 5, components: { T709MeshFilter: { assetHandle: 'mesh-guid' } } },
+    ]);
+    expect(entries).toEqual([
+      {
+        entityLocalId: 5,
+        componentName: 'T709MeshFilter',
+        fieldName: 'assetHandle',
+        guidString: 'mesh-guid',
+      },
+    ]);
+  });
+
+  it('extracts array<shared<T>> element GUIDs with their arrayIndex', () => {
+    const entries = extractSceneEntityHandleGuids(components, [
+      { localId: 1, components: { T709MeshRenderer: { materials: ['m0', 'm1'] } } },
+    ]);
+    expect(entries).toEqual([
+      {
+        entityLocalId: 1,
+        componentName: 'T709MeshRenderer',
+        fieldName: 'materials',
+        guidString: 'm0',
+        arrayIndex: 0,
+      },
+      {
+        entityLocalId: 1,
+        componentName: 'T709MeshRenderer',
+        fieldName: 'materials',
+        guidString: 'm1',
+        arrayIndex: 1,
+      },
+    ]);
+  });
+
+  it('skips unknown components, non-shared fields, and already-resolved numbers', () => {
+    const entries = extractSceneEntityHandleGuids(components, [
+      { localId: 0, components: { NotRegistered709: { assetHandle: 'x' } } },
+      { localId: 1, components: { T709Transform: { x: 3 } } },
+      { localId: 2, components: { T709MeshFilter: { assetHandle: 42 } } },
+      { localId: 3, components: { T709MeshRenderer: { materials: [7, 'm-str'] } } },
+    ]);
+    // Only the string array element survives.
+    expect(entries).toEqual([
+      {
+        entityLocalId: 3,
+        componentName: 'T709MeshRenderer',
+        fieldName: 'materials',
+        guidString: 'm-str',
+        arrayIndex: 1,
+      },
+    ]);
+  });
+});
+
+describe('extractMountOverrideHandleGuids', () => {
+  it('patch form (field present) extracts one GUID from a shared field', () => {
+    const overrides: MountOverride[] = [
+      { localId: 1 as never, comp: 'T709MeshFilter', field: 'assetHandle', value: 'mesh-guid' },
+    ];
+    const entries = extractMountOverrideHandleGuids(components, overrides);
+    expect(entries).toEqual([
+      {
+        overrideIndex: 0,
+        componentName: 'T709MeshFilter',
+        fieldName: 'assetHandle',
+        guidString: 'mesh-guid',
+      },
+    ]);
+  });
+
+  it('add form (field absent, value is a per-field map) extracts array GUIDs', () => {
+    const overrides: MountOverride[] = [
+      { localId: 1 as never, comp: 'T709MeshRenderer', value: { materials: ['a', 'b'] } },
+    ];
+    const entries = extractMountOverrideHandleGuids(components, overrides);
+    expect(entries).toEqual([
+      {
+        overrideIndex: 0,
+        componentName: 'T709MeshRenderer',
+        fieldName: 'materials',
+        guidString: 'a',
+        arrayIndex: 0,
+      },
+      {
+        overrideIndex: 0,
+        componentName: 'T709MeshRenderer',
+        fieldName: 'materials',
+        guidString: 'b',
+        arrayIndex: 1,
+      },
+    ]);
+  });
+
+  it('skips unknown components and non-object add values', () => {
+    const overrides: MountOverride[] = [
+      { localId: 1 as never, comp: 'NotRegistered709', value: { assetHandle: 'x' } },
+      { localId: 2 as never, comp: 'T709MeshFilter', value: 5 },
+    ];
+    expect(extractMountOverrideHandleGuids(components, overrides)).toEqual([]);
+  });
+});

package/src/__tests__/scene-payload.unit.test.ts

@@ -0,0 +1,151 @@
+// @forgeax/engine-assets-runtime -- parseScenePayload coverage (fix issue #709).
+// Exercises the entities/mounts/skinGuids refs-resolution branches + fail-fast
+// return shapes. parseScenePayload keys handle fields off the HANDLE_FIELD_NAMES
+// / HANDLE_ARRAY_FIELD_NAMES name allowlists, so no component registration needed.
+
+import type { SceneAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { parseScenePayload } from '../scene-payload';
+
+function isScene(v: unknown): v is SceneAsset {
+  return typeof v === 'object' && v !== null && (v as { kind?: string }).kind === 'scene';
+}
+
+describe('parseScenePayload without refs', () => {
+  it('returns undefined when entities is not an array', () => {
+    expect(parseScenePayload({})).toBeUndefined();
+    expect(parseScenePayload({ entities: 'nope' })).toBeUndefined();
+  });
+
+  it('returns undefined when an entity localId is not a number', () => {
+    expect(parseScenePayload({ entities: [{ localId: 'x', components: {} }] })).toBeUndefined();
+  });
+
+  it('passes component fields through verbatim (no refs table)', () => {
+    const out = parseScenePayload({
+      entities: [{ localId: 0, components: { MeshFilter: { assetHandle: 3 } } }],
+    });
+    expect(isScene(out)).toBe(true);
+    if (!isScene(out)) return;
+    expect(out.entities[0]?.components.MeshFilter?.assetHandle).toBe(3);
+  });
+});
+
+describe('parseScenePayload with refs', () => {
+  it('resolves ParticleEffectPlayer.effect through the scalar refs contract', () => {
+    const out = parseScenePayload(
+      {
+        entities: [
+          { localId: 0, components: { ParticleEffectPlayer: { effect: 1, seed: 424242 } } },
+        ],
+      },
+      ['scene-guid', 'particle-effect-guid'],
+    );
+    expect(out).toMatchObject({
+      entities: [
+        { components: { ParticleEffectPlayer: { effect: 'particle-effect-guid', seed: 424242 } } },
+      ],
+    });
+  });
+
+  const refs = ['guid-a', 'guid-b', 'guid-c'];
+
+  it('resolves a scalar handle field index to its GUID string', () => {
+    const out = parseScenePayload(
+      { entities: [{ localId: 0, components: { MeshFilter: { assetHandle: 1 } } }] },
+      refs,
+    );
+    expect(isScene(out)).toBe(true);
+    if (!isScene(out)) return;
+    expect(out.entities[0]?.components.MeshFilter?.assetHandle).toBe('guid-b');
+  });
+
+  it('keeps non-handle integer fields as-is (e.g. ChildOf.parent)', () => {
+    const out = parseScenePayload(
+      { entities: [{ localId: 0, components: { ChildOf: { parent: 2 } } }] },
+      refs,
+    );
+    if (!isScene(out)) throw new Error('expected scene');
+    expect(out.entities[0]?.components.ChildOf?.parent).toBe(2);
+  });
+
+  it('resolves array<handle> fields (materials) element-wise', () => {
+    const out = parseScenePayload(
+      { entities: [{ localId: 0, components: { MeshRenderer: { materials: [0, 2] } } }] },
+      refs,
+    );
+    if (!isScene(out)) throw new Error('expected scene');
+    expect(out.entities[0]?.components.MeshRenderer?.materials).toEqual(['guid-a', 'guid-c']);
+  });
+
+  it('returns a ParseSceneError for an out-of-bounds scalar handle index', () => {
+    const out = parseScenePayload(
+      { entities: [{ localId: 7, components: { MeshFilter: { assetHandle: 9 } } }] },
+      refs,
+    );
+    expect(isScene(out)).toBe(false);
+    expect(out).toMatchObject({
+      localId: 7,
+      component: 'MeshFilter',
+      field: 'assetHandle',
+      index: 9,
+      refsLength: 3,
+    });
+  });
+
+  it('returns a ParseSceneError for an out-of-bounds array handle element', () => {
+    const out = parseScenePayload(
+      { entities: [{ localId: 1, components: { MeshRenderer: { materials: [0, 99] } } }] },
+      refs,
+    );
+    expect(isScene(out)).toBe(false);
+    expect(out).toMatchObject({ localId: 1, field: 'materials[1]', index: 99 });
+  });
+
+  it('resolves mounts[].source through refs', () => {
+    const out = parseScenePayload(
+      {
+        entities: [{ localId: 0, components: {} }],
+        mounts: [{ localId: 1, source: 2, memberFirst: 2, memberCount: 0 }],
+      },
+      refs,
+    );
+    if (!isScene(out)) throw new Error('expected scene');
+    expect(out.mounts?.[0]?.source).toBe('guid-c');
+  });
+
+  it('returns undefined when a mount source index is out of bounds', () => {
+    const out = parseScenePayload(
+      {
+        entities: [{ localId: 0, components: {} }],
+        mounts: [{ localId: 1, source: 42, memberFirst: 2, memberCount: 0 }],
+      },
+      refs,
+    );
+    expect(out).toBeUndefined();
+  });
+
+  it('resolves skinGuids from refs indices and passes pre-resolved strings through', () => {
+    const idx = parseScenePayload(
+      { entities: [{ localId: 0, components: {} }], skinGuids: [0, 2] },
+      refs,
+    );
+    if (!isScene(idx)) throw new Error('expected scene');
+    expect(idx.skinGuids).toEqual(['guid-a', 'guid-c']);
+
+    const strs = parseScenePayload({
+      entities: [{ localId: 0, components: {} }],
+      skinGuids: ['g1'],
+    });
+    if (!isScene(strs)) throw new Error('expected scene');
+    expect(strs.skinGuids).toEqual(['g1']);
+  });
+
+  it('returns undefined when a skinGuids index is out of bounds', () => {
+    const out = parseScenePayload(
+      { entities: [{ localId: 0, components: {} }], skinGuids: [99] },
+      refs,
+    );
+    expect(out).toBeUndefined();
+  });
+});