@forgeax/engine-assets-runtime 0.1.4 → 0.1.7

package/src/__tests__/decode-image-bytes.browser.test.ts

@@ -0,0 +1,102 @@
+// @forgeax/engine-assets-runtime -- decodeImageBytes browser e2e test
+// (tweak-20260714-runtime-image-bytes-decoder-add-decodeimagebytes M3 / m3-1).
+//
+// Runs under the vitest browser project (chromium + real createImageBitmap +
+// OffscreenCanvas 2D). Anchors the end-to-end "bytes -> POD -> world column
+// handle" happy path that the Node-side unit test cannot exercise (Node has
+// no createImageBitmap; unit test only covers the structured-failure arms).
+//
+// Coverage:
+//   - AC-01: real PNG bytes -> ok(TextureAsset) with all POD fields populated
+//     (kind / width / height / format / data / colorSpace / mipmap /
+//     mipLevelCount); default (opts omitted) drives srgb + mipmap=true, and a
+//     second run with opts.colorSpace='linear' + opts.mipmap=false confirms
+//     the two POD fields the opts derive (format + mipLevelCount).
+//   - AC-02: the returned POD is accepted by `world.allocSharedRef(
+//     'TextureAsset', pod)` -- the SSOT runtime column-handle path (charter
+//     P4 consistent abstraction: the same POD any static loader would
+//     produce). The handle is a live u32 whose resolve returns payload
+//     identity (structural equivalence, not deep-copy).
+//   - AC-03 (regression): running this file alongside the existing browser
+//     project confirms the pre-existing static loader path is unaffected
+//     (checked by the M3 boundary sweep `pnpm test:browser`, no new arms
+//     added here).
+//
+// Fixture: 1x1 red PNG inlined as base64 (67 bytes) -- keeps the whole
+// contract self-contained in this one file so an AI user grep-discovering
+// the test does not need to chase a binary fixture (charter F1 single-page).
+
+import { World } from '@forgeax/engine-ecs';
+import type { TextureAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { decodeImageBytes } from '../decode-image-bytes';
+import { numMipLevels } from '../mipmap-generator';
+
+// 1x1 red PNG (RGBA 8-bit). Universally decodable by browser createImageBitmap.
+const PNG_1X1_RED_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==';
+
+function pngBytes(): Uint8Array {
+  const bin = atob(PNG_1X1_RED_BASE64);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes;
+}
+
+describe('decodeImageBytes browser real-PNG happy path (AC-01)', () => {
+  it('AC-01: real PNG bytes -> ok(TextureAsset) with all POD fields populated (default srgb + mipmap)', async () => {
+    const result = await decodeImageBytes(pngBytes(), 'image/png');
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const pod = result.value;
+    expect(pod.kind).toBe('texture');
+    expect(pod.width).toBeGreaterThan(0);
+    expect(pod.height).toBeGreaterThan(0);
+    // RGBA8 tight-packed: width * height * 4 bytes.
+    expect(pod.data.length).toBe(pod.width * pod.height * 4);
+    expect(pod.format).toBe('rgba8unorm-srgb');
+    expect(pod.colorSpace).toBe('srgb');
+    expect(pod.mipmap).toBe(true);
+    expect(pod.mipLevelCount).toBe(numMipLevels({ width: pod.width, height: pod.height }));
+  });
+
+  it('AC-01: opts.colorSpace="linear" + opts.mipmap=false narrows format + mipLevelCount', async () => {
+    const result = await decodeImageBytes(pngBytes(), 'image/png', {
+      colorSpace: 'linear',
+      mipmap: false,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const pod = result.value;
+    expect(pod.format).toBe('rgba8unorm');
+    expect(pod.colorSpace).toBe('linear');
+    expect(pod.mipmap).toBe(false);
+    expect(pod.mipLevelCount).toBe(1);
+  });
+});
+
+describe('decodeImageBytes browser structural equivalence with static loader path (AC-02)', () => {
+  it('AC-02: POD is accepted by world.allocSharedRef and resolves back to the same identity', async () => {
+    const result = await decodeImageBytes(pngBytes(), 'image/png');
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const pod = result.value;
+
+    const world = new World();
+    const handle = world.allocSharedRef<'TextureAsset', TextureAsset>('TextureAsset', pod);
+    // Handle is a branded u32 -- must be a finite non-negative integer.
+    expect(typeof handle).toBe('number');
+    expect(Number.isFinite(handle as unknown as number)).toBe(true);
+    expect(handle as unknown as number).toBeGreaterThan(0);
+
+    // Structural equivalence: the shared-ref store round-trips the SAME POD
+    // reference (identity preserved, no deep-copy) -- what any static
+    // texture loader path produces after allocSharedRef.
+    const resolved = world.sharedRefs.resolve<'TextureAsset', TextureAsset>(handle);
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok) return;
+    expect(resolved.value).toBe(pod);
+    expect(resolved.value.kind).toBe('texture');
+    expect(resolved.value.format).toBe('rgba8unorm-srgb');
+  });
+});

package/src/__tests__/decode-image-bytes.test-d.ts

@@ -0,0 +1,108 @@
+// @forgeax/engine-assets-runtime -- decodeImageBytes type-only contract test
+// (tweak-20260714-runtime-image-bytes-decoder-add-decodeimagebytes M1 / m1-1).
+//
+// AC-05 + AC-06 compile-time narrowing anchor. The vitest typecheck project
+// runs `.test-d.ts` files so any drift in the exported signature / Result
+// narrowing / ImageErrorDetail per-code shape trips CI (charter P4 explicit
+// failure -- typechecker acts as the reviewer).
+//
+// The SSOT `ImageError` type correlates the envelope `.code` with its
+// per-code `.detail` shape, so consumers switch on one discriminant.
+
+import type { ImageError, Result, TextureAsset } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import { decodeImageBytes } from '../index';
+
+describe('decodeImageBytes signature (AC-05 / AC-06 / opts compat)', () => {
+  it('returns Promise<Result<TextureAsset, ImageError>>', () => {
+    expectTypeOf(decodeImageBytes).returns.toEqualTypeOf<
+      Promise<Result<TextureAsset, ImageError>>
+    >();
+  });
+
+  it('AC-05: `if (r.ok)` narrows r.value to TextureAsset, else r.error to ImageError', async () => {
+    const r = await decodeImageBytes(new Uint8Array(), 'image/png');
+    if (r.ok) {
+      expectTypeOf(r.value).toEqualTypeOf<TextureAsset>();
+    } else {
+      expectTypeOf(r.error).toEqualTypeOf<ImageError>();
+    }
+  });
+
+  it('AC-06: `switch (err.code)` narrows err.detail per-code (exhaustive)', async () => {
+    const r = await decodeImageBytes(new Uint8Array(), 'image/png');
+    if (r.ok) return;
+    // Exhaustive over the correlated ImageError union so a future minor-add
+    // to ImageErrorCode fails compilation here until this file catches up.
+    switch (r.error.code) {
+      case 'image-decode-failed': {
+        expectTypeOf(r.error.detail.reason).toBeString();
+        expectTypeOf(r.error.detail.path).toEqualTypeOf<string | undefined>();
+        break;
+      }
+      case 'image-format-unsupported': {
+        expectTypeOf(r.error.detail.actualMime).toBeString();
+        break;
+      }
+      case 'image-dimension-out-of-bounds': {
+        expectTypeOf(r.error.detail.requested.width).toBeNumber();
+        expectTypeOf(r.error.detail.limit).toBeNumber();
+        break;
+      }
+      case 'image-meta-missing': {
+        expectTypeOf(r.error.detail.sourcePath).toBeString();
+        expectTypeOf(r.error.detail.expectedSidecarPath).toBeString();
+        break;
+      }
+      case 'image-hdr-decode-failed': {
+        expectTypeOf(r.error.detail.reason).toBeString();
+        break;
+      }
+      case 'atlas-empty-input': {
+        expectTypeOf(r.error.detail.receivedCount).toBeNumber();
+        break;
+      }
+      case 'atlas-size-exceeded': {
+        expectTypeOf(r.error.detail.maxAtlasSize).toBeNumber();
+        break;
+      }
+      case 'atlas-region-mismatch': {
+        expectTypeOf(r.error.detail.atlasPixels).toBeNumber();
+        break;
+      }
+    }
+  });
+
+  it('opts compat: all optional, partial, and full forms compile', async () => {
+    await decodeImageBytes(new Uint8Array(), 'image/png');
+    await decodeImageBytes(new Uint8Array(), 'image/png', { colorSpace: 'linear' });
+    await decodeImageBytes(new Uint8Array(), 'image/png', { mipmap: false });
+    await decodeImageBytes(new Uint8Array(), 'image/png', {
+      colorSpace: 'srgb',
+      mipmap: true,
+    });
+    await decodeImageBytes(new ArrayBuffer(0), 'image/png');
+  });
+
+  it('AC-05 negative: `if (!r.ok)` MUST NOT let r.value type-check (@ts-expect-error)', async () => {
+    const r = await decodeImageBytes(new Uint8Array(), 'image/png');
+    if (!r.ok) {
+      // @ts-expect-error -- on the err branch `r` is `ResultErr<ImageError>`
+      // and has no `.value` property; if this line ever compiles, the
+      // Result narrowing broke.
+      const _v: TextureAsset = r.value;
+      void _v;
+    }
+  });
+
+  it('AC-06 negative: `reason` is not on the image-format-unsupported detail arm (@ts-expect-error)', async () => {
+    const r = await decodeImageBytes(new Uint8Array(), 'image/png');
+    if (r.ok) return;
+    if (r.error.detail.code === 'image-format-unsupported') {
+      // @ts-expect-error -- `reason` belongs to the image-decode-failed arm;
+      // it must NOT be reachable on the image-format-unsupported arm.
+      const _r: string = r.error.detail.reason;
+      void _r;
+    }
+  });
+});

package/src/__tests__/decode-image-bytes.test.ts

@@ -0,0 +1,90 @@
+// @forgeax/engine-assets-runtime -- decodeImageBytes unit test skeleton
+// (tweak-20260714-runtime-image-bytes-decoder-add-decodeimagebytes M1 / m1-1).
+//
+// Red skeleton at M1: the M1 stub throws 'not-implemented', so any behavioural
+// assertion here is red until M2 fills the function body. Two forever-tests
+// still hold at M1:
+//   - AC-07 (a): the symbol is importable from the @forgeax/engine-assets-
+//     runtime main barrel (grep-discoverable single-hop entry point).
+//   - AC-07 (b): the source file leads with a `/**` TSDoc block on the
+//     exported function (charter F1: single-page contract).
+//
+// Behavioural AC-04 / AC-08 / AC-09 arms are declared here in the exhaustive
+// switch skeleton so the M1 red matches the M2 green surface without churn
+// (charter P3 explicit failure -- red arms declare the target shape).
+
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { decodeImageBytes } from '../index';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+describe('decodeImageBytes barrel + TSDoc contract (AC-07)', () => {
+  it('is exported from the @forgeax/engine-assets-runtime main barrel', () => {
+    expect(typeof decodeImageBytes).toBe('function');
+  });
+
+  it('carries a leading `/**` TSDoc block on the exported function', () => {
+    const src = readFileSync(join(here, '..', 'decode-image-bytes.ts'), 'utf8');
+    // The exported function must be immediately preceded by a `*/` closing
+    // its TSDoc block; the `/**` opener must appear before that. This is a
+    // structural (not textual) check on the AI user's IDE-hover surface.
+    const exportIdx = src.indexOf('export async function decodeImageBytes(');
+    expect(exportIdx).toBeGreaterThan(0);
+    const preface = src.slice(0, exportIdx);
+    const jsdocClose = preface.lastIndexOf('*/');
+    const jsdocOpen = preface.lastIndexOf('/**');
+    expect(jsdocOpen).toBeGreaterThan(0);
+    expect(jsdocClose).toBeGreaterThan(jsdocOpen);
+  });
+});
+
+describe('decodeImageBytes structured failure surface (AC-04 / AC-08 / AC-09)', () => {
+  it('AC-08: unsupported mime -> err with image-format-unsupported', async () => {
+    const result = await decodeImageBytes(new Uint8Array([1]), 'image/gif');
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    const expected =
+      "mime is one of ['image/png', 'image/jpeg', 'image/x-tga']; texture format <-> colorSpace family agrees";
+    const hint =
+      'supports PNG / JPG / TGA true-color sources; convert unsupported formats with: magick convert <input> <output>.png; check importSettings.colorSpace consistency with format family if formatColorSpaceConflict present';
+    expect(result.error.code).toBe('image-format-unsupported');
+    expect(result.error.detail).toEqual({
+      code: 'image-format-unsupported',
+      actualMime: 'image/gif',
+    });
+    expect(result.error.expected).toBe(expected);
+    expect(result.error.hint).toBe(hint);
+    expect(result.error.name).toBe('ImageError');
+    expect(result.error.message).toBe(
+      `[ImageError image-format-unsupported] expected: ${expected}; hint: ${hint}`,
+    );
+  });
+
+  it('AC-09: corrupt bytes with declared mime -> err with image-decode-failed', async () => {
+    // Node env has no createImageBitmap; the decoder returns the structured
+    // env-missing failure through the same `image-decode-failed` arm as a
+    // real decoder rejection in the browser (charter P3 explicit failure --
+    // AI users switch on one arm regardless of environment).
+    const result = await decodeImageBytes(new Uint8Array([0, 0, 0]), 'image/png');
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('image-decode-failed');
+    if (result.error.detail.code === 'image-decode-failed') {
+      expect(typeof result.error.detail.reason).toBe('string');
+      expect(result.error.detail.reason.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('runtime-only bytes remain orthogonal to static pack loading', () => {
+  it('keeps the bytes decoder available without accepting static catalog rows', async () => {
+    const result = await decodeImageBytes(new Uint8Array([0]), 'image/gif');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('image-format-unsupported');
+  });
+});

package/src/__tests__/decode-image-mime-owner.test.ts

@@ -1,16 +1,13 @@
 /// <reference types="node" />
 
 import { readFileSync } from 'node:fs';
-import type { decodeImageBytes } from '@forgeax/engine-image';
 import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { decodeImageBytes } from '../index';
 
 type ExpectedSupportedMime = 'image/png' | 'image/jpeg';
 type PublicMime = Parameters<typeof decodeImageBytes>[1];
 
-const decoderSource = readFileSync(
-  new URL('../../../image/src/runtime/decode-image-bytes.ts', import.meta.url),
-  'utf8',
-);
+const decoderSource = readFileSync(new URL('../decode-image-bytes.ts', import.meta.url), 'utf8');
 
 describe('decodeImageBytes supported MIME owner', () => {
   it('keeps the supported MIME vocabulary and public boundary exact', () => {

package/src/__tests__/dynamic-texture-store.unit.test.ts

@@ -0,0 +1,115 @@
+// @forgeax/engine-assets-runtime -- DynamicTextureStore coverage (fix issue #709).
+// Transient per-frame video texture store: configureGpuDevice / uploadFrame
+// (allocate-once + resize-realloc + copy) / getView / destroyAll, driven by a
+// small in-memory device stub (no GPU).
+
+import type { Result, RhiError, Texture, TextureView } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import type { Handle } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  type CopyExternalImageSource,
+  type DynamicTextureDevice,
+  DynamicTextureStore,
+} from '../dynamic-texture-store';
+
+interface Counters {
+  created: number;
+  destroyed: number;
+  copies: number;
+}
+
+function makeDevice(counters: Counters): DynamicTextureDevice {
+  let nextTex = 0;
+  return {
+    createTexture: () => {
+      counters.created++;
+      return ok({ tag: `tex-${nextTex++}` } as unknown as Texture);
+    },
+    createTextureView: (tex: Texture) =>
+      ok({ tag: `view-of-${(tex as unknown as { tag: string }).tag}` } as unknown as TextureView),
+    destroyTexture: () => {
+      counters.destroyed++;
+      return ok(undefined) as Result<void, RhiError>;
+    },
+    queue: {
+      copyExternalImageToTexture: () => {
+        counters.copies++;
+        return ok(undefined) as Result<void, RhiError>;
+      },
+    },
+  };
+}
+
+const CLIP = toShared<'VideoAsset'>(2000) as Handle<'VideoAsset', 'shared'>;
+const SOURCE = {} as CopyExternalImageSource;
+
+describe('DynamicTextureStore', () => {
+  it('returns undefined before a device is wired', () => {
+    const store = new DynamicTextureStore();
+    expect(store.uploadFrame(CLIP, SOURCE, 16, 16)).toBeUndefined();
+  });
+
+  it('returns undefined for a non-positive source size', () => {
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeDevice({ created: 0, destroyed: 0, copies: 0 }));
+    expect(store.uploadFrame(CLIP, SOURCE, 0, 16)).toBeUndefined();
+    expect(store.uploadFrame(CLIP, SOURCE, 16, -1)).toBeUndefined();
+  });
+
+  it('allocates once, then re-uploads in place for a steady-size clip', () => {
+    const counters = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeDevice(counters));
+
+    const a = store.uploadFrame(CLIP, SOURCE, 32, 32);
+    const b = store.uploadFrame(CLIP, SOURCE, 32, 32);
+    expect(a?.ok).toBe(true);
+    expect(b?.ok).toBe(true);
+    expect(counters.created).toBe(1); // allocate-once
+    expect(counters.copies).toBe(2); // re-uploaded each frame
+    if (a?.ok && b?.ok) expect(a.value).toBe(b.value); // same view reused
+  });
+
+  it('reallocates (destroys old, creates new) when the source size changes', () => {
+    const counters = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeDevice(counters));
+    store.uploadFrame(CLIP, SOURCE, 32, 32);
+    store.uploadFrame(CLIP, SOURCE, 64, 64);
+    expect(counters.created).toBe(2);
+    expect(counters.destroyed).toBe(1);
+  });
+
+  it('getView returns the current view after an upload, undefined before', () => {
+    const store = new DynamicTextureStore();
+    expect(store.getView(CLIP)).toBeUndefined();
+    store.configureGpuDevice(makeDevice({ created: 0, destroyed: 0, copies: 0 }));
+    store.uploadFrame(CLIP, SOURCE, 8, 8);
+    expect(store.getView(CLIP)).toBeDefined();
+  });
+
+  it('destroyAll destroys every transient texture and clears the map', () => {
+    const counters = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeDevice(counters));
+    store.uploadFrame(CLIP, SOURCE, 8, 8);
+    store.uploadFrame(toShared<'VideoAsset'>(2001) as Handle<'VideoAsset', 'shared'>, SOURCE, 8, 8);
+    store.destroyAll();
+    expect(counters.destroyed).toBe(2);
+    expect(store.getView(CLIP)).toBeUndefined();
+  });
+
+  it('surfaces a structured error when texture allocation fails', () => {
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice({
+      createTexture: () => ({ ok: false, error: { code: 'rhi-not-available' } }) as never,
+      createTextureView: () => ok({} as unknown as TextureView),
+      destroyTexture: () => ok(undefined) as Result<void, RhiError>,
+      queue: { copyExternalImageToTexture: () => ok(undefined) as Result<void, RhiError> },
+    });
+    const res = store.uploadFrame(CLIP, SOURCE, 8, 8);
+    expect(res?.ok).toBe(false);
+  });
+});

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

@@ -0,0 +1,92 @@
+// @forgeax/engine-assets-runtime -- asset-cluster error class coverage
+// (fix issue #709). Exercises every constructor branch + .code / .expected /
+// .hint / .detail four-field surface of the closed AssetRuntimeError union.
+
+import { describe, expect, it } from 'vitest';
+import {
+  MaterialResolvedEmptyPassesError,
+  MeshSsboCapacityExceededError,
+  MeshSsboCeilingReachedError,
+  SceneCollectAssetGuidUnresolvedError,
+  SceneCollectEntityRefOutOfClosureError,
+} from '../errors/asset';
+
+describe('MaterialResolvedEmptyPassesError', () => {
+  it('missing-parent reason carries the parent handle in expected/hint/detail', () => {
+    const e = new MaterialResolvedEmptyPassesError('mat-guid', 'missing-parent', 42);
+    expect(e.code).toBe('material-resolved-empty-passes');
+    expect(e.name).toBe('MaterialResolvedEmptyPassesError');
+    expect(e.detail).toEqual({
+      materialGuid: 'mat-guid',
+      reason: 'missing-parent',
+      missingParentHandle: 42,
+    });
+    expect(e.expected).toContain('42');
+    expect(e.hint).toContain('mat-guid');
+    expect(e.message).toContain('42');
+  });
+
+  it('no-pass-in-chain reason omits missingParentHandle from detail', () => {
+    const e = new MaterialResolvedEmptyPassesError('mat-guid', 'no-pass-in-chain');
+    expect(e.detail).toEqual({ materialGuid: 'mat-guid', reason: 'no-pass-in-chain' });
+    expect('missingParentHandle' in e.detail).toBe(false);
+    expect(e.expected).toContain('at least one material');
+    expect(e.message).toContain('zero passes');
+  });
+
+  it('missing-parent with undefined handle still omits it from detail', () => {
+    const e = new MaterialResolvedEmptyPassesError('g', 'missing-parent', undefined);
+    expect('missingParentHandle' in e.detail).toBe(false);
+  });
+});
+
+describe('MeshSsboCapacityExceededError', () => {
+  it('surfaces requested / capacity / ceiling across all four fields', () => {
+    const e = new MeshSsboCapacityExceededError(100, 64, 1024);
+    expect(e.code).toBe('mesh-ssbo-capacity-exceeded');
+    expect(e.name).toBe('MeshSsboCapacityExceededError');
+    expect(e.detail).toEqual({ requested: 100, capacity: 64, ceiling: 1024 });
+    expect(e.expected).toContain('100');
+    expect(e.hint).toContain('100');
+    expect(e.message).toContain('100');
+  });
+});
+
+describe('MeshSsboCeilingReachedError', () => {
+  it('surfaces requested / capacity / ceiling across all four fields', () => {
+    const e = new MeshSsboCeilingReachedError(200, 128, 2048);
+    expect(e.code).toBe('mesh-ssbo-ceiling-reached');
+    expect(e.name).toBe('MeshSsboCeilingReachedError');
+    expect(e.detail).toEqual({ requested: 200, capacity: 128, ceiling: 2048 });
+    expect(e.expected).toContain('2048');
+    expect(e.hint).toContain('2048');
+    expect(e.message).toContain('200');
+  });
+});
+
+describe('SceneCollectEntityRefOutOfClosureError', () => {
+  it('carries entity / field / target and composes an expected+hint message', () => {
+    const e = new SceneCollectEntityRefOutOfClosureError(3, 'target', 99);
+    expect(e.code).toBe('scene-collect-entity-ref-out-of-closure');
+    expect(e.name).toBe('SceneCollectEntityRefOutOfClosureError');
+    expect(e.detail).toEqual({ entity: 3, field: 'target', target: 99 });
+    expect(e.message).toBe(`${e.expected} — ${e.hint}`);
+  });
+});
+
+describe('SceneCollectAssetGuidUnresolvedError', () => {
+  it('numeric ref (collect path) populates detail.handle only', () => {
+    const e = new SceneCollectAssetGuidUnresolvedError('meshHandle', 7);
+    expect(e.code).toBe('scene-collect-asset-guid-unresolved');
+    expect(e.detail).toEqual({ field: 'meshHandle', handle: 7 });
+    expect('guid' in e.detail).toBe(false);
+    expect(e.expected).toContain('handle 7');
+  });
+
+  it('string ref (serialize path) populates detail.guid only', () => {
+    const e = new SceneCollectAssetGuidUnresolvedError('meshHandle', 'abc-guid');
+    expect(e.detail).toEqual({ field: 'meshHandle', guid: 'abc-guid' });
+    expect('handle' in e.detail).toBe(false);
+    expect(e.expected).toContain("guid 'abc-guid'");
+  });
+});