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

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

@@ -0,0 +1,123 @@
+// Name component (built-in, runtime-owned) — schema literal + identity +
+// AC-13 invariant + spawn/set fallback. Migrated from
+// packages/ecs/src/__tests__/hierarchy.unit.test.ts (name-component +
+// name-mutation paragraphs) by tweak-20260612-ecs-concept-compression: Name's
+// authoritative location is now @forgeax/engine-runtime, not the ECS framework.
+
+import { type SchemaOf, World } from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { Name } from '@forgeax/engine-scene';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('Name component --- schema literal (w2, AC-03 a/d)', () => {
+  it('componentSchema(Name) deep-equals { value: "string" } (KD-4 single field)', () => {
+    expect(componentSchema(Name)).toEqual({ value: 'string' });
+    expect(Object.keys(componentSchema(Name))).toEqual(['value']);
+  });
+
+  it('componentSchema(Name).value preserved as literal "string", not widened', () => {
+    type ValueField = SchemaOf<typeof Name>['value'];
+    expectTypeOf<ValueField>().toEqualTypeOf<'string'>();
+  });
+});
+
+describe('Name component --- identity (w2, AC-03 b)', () => {
+  it('Name.name === "Name" (no Component suffix per AGENTS.md naming)', () => {
+    expect(Name.name).toBe('Name');
+  });
+});
+
+describe('Name component --- single-import surface (w2, AC-03 c / AC-11)', () => {
+  it('Name resolves through the runtime barrel re-export', () => {
+    expect(Name).toBeDefined();
+    expect(typeof Name).toBe('object');
+  });
+});
+
+describe('Name component --- AC-13 schema invariant (w20)', () => {
+  it("componentSchema(Name)['value'] is the literal 'string'", () => {
+    expect(componentSchema(Name).value).toBe('string');
+    type ValueField = SchemaOf<typeof Name>['value'];
+    expectTypeOf<ValueField>().toEqualTypeOf<'string'>();
+  });
+
+  it('world.get(e, Name).unwrap().value returns a native JS string at runtime', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: { value: 'Hero' } }).unwrap();
+    const value = w.get(e, Name).unwrap().value;
+    expect(typeof value).toBe('string');
+    expect(value).toBe('Hero');
+  });
+
+  it('world.get(e, Name).unwrap().value infers as string at the type level', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: { value: 'X' } }).unwrap();
+    const value = w.get(e, Name).unwrap().value;
+    expectTypeOf(value).toEqualTypeOf<string>();
+  });
+});
+
+describe('w10 --- Name spawn + read (AC-04 a)', () => {
+  it('spawn with { value: "Player" } -> get returns native string "Player"', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: { value: 'Player' } }).unwrap();
+    const got = w.get(e, Name);
+    if (!got.ok) throw new Error('expected ok');
+    expect(got.value.value).toBe('Player');
+    expect(typeof got.value.value).toBe('string');
+  });
+});
+
+describe('w10 --- Name rename via world.set (AC-04 b)', () => {
+  it('world.set overwrites value; subsequent get returns the new string', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: { value: 'Player' } }).unwrap();
+    w.set(e, Name, { value: 'Boss' }).unwrap();
+    const got = w.get(e, Name);
+    if (!got.ok) throw new Error('expected ok');
+    expect(got.value.value).toBe('Boss');
+    expect(typeof got.value.value).toBe('string');
+  });
+
+  it('successive sets each show through to the next read', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: { value: 'a' } }).unwrap();
+    w.set(e, Name, { value: 'bb' }).unwrap();
+    expect(w.get(e, Name).unwrap().value).toBe('bb');
+    w.set(e, Name, { value: 'ccc' }).unwrap();
+    expect(w.get(e, Name).unwrap().value).toBe('ccc');
+  });
+});
+
+describe('w10 --- AC-06 spawn fallback (raw=undefined / null / number -> "")', () => {
+  it('spawn with no data field reads as empty string', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: {} }).unwrap();
+    const got = w.get(e, Name);
+    if (!got.ok) throw new Error('expected ok');
+    expect(got.value.value).toBe('');
+    expect(typeof got.value.value).toBe('string');
+  });
+
+  it('spawn with data.value=null reads as empty string', () => {
+    const w = new World();
+    // @ts-expect-error AC-09 strict signature rejects null; runtime
+    // fallback (AC-06) coerces null to '' — testing that runtime path.
+    const e = w.spawn({ component: Name, data: { value: null } }).unwrap();
+    const got = w.get(e, Name);
+    if (!got.ok) throw new Error('expected ok');
+    expect(got.value.value).toBe('');
+    expect(typeof got.value.value).toBe('string');
+  });
+
+  it('spawn with data.value=<number> reads as empty string', () => {
+    const w = new World();
+    // @ts-expect-error AC-09 strict signature rejects number for `string` field;
+    // runtime fallback (AC-06) coerces non-string to '' — testing that runtime path.
+    const e = w.spawn({ component: Name, data: { value: 42 } }).unwrap();
+    const got = w.get(e, Name);
+    if (!got.ok) throw new Error('expected ok');
+    expect(got.value.value).toBe('');
+    expect(typeof got.value.value).toBe('string');
+  });
+});

package/src/__tests__/new-kind-refs-contract.test.ts

@@ -0,0 +1,132 @@
+// feat-20260622 M6 / w23 — AC-07 contract: a new reference does NOT require any
+// change to a graph-walk axis. The recursion source is `envelope.refs` (D-5), so
+// when the importer puts a referenced GUID into refs[], the recursive loadByGuid
+// walk pulls it -- no exhaustive `switch (asset.kind)` arm to add, no per-kind
+// runtime walker to extend. feat-20260623 M2: the ASSET_BRAND table (the only
+// kind-exhaustive mapping a new Asset kind previously touched) is now retired;
+// a new kind requires zero engine-type changes (brand concept eliminated).
+//
+// This locks the structural win of the refs-as-SSOT pivot: adding a reference
+// field to any Asset member surfaces in the load graph through refs[] alone.
+//
+// The retired graph-walk mechanisms (collect-refs.ts + the
+// asset-registry.recursive.test-d.ts exhaustive-switch guard) are deleted in
+// w19; their absence is enforced structurally -- nothing imports them and the
+// milestone grep gate asserts the retired ref-collection switch leaves zero
+// references across the tree.
+// (A filesystem existsSync check is intentionally avoided: node:fs/node:path
+// named imports are outside @types/node coverage in the runtime tsconfig.)
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const PARENT_GUID = 'c0000000-0000-4000-c000-000000000001';
+const EXTRA_REF_GUID = 'c0000000-0000-4000-c000-000000000002';
+
+function parseGuid(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`invalid test GUID: ${s}`);
+  return r.value;
+}
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const stubMaterial: MaterialAsset = {
+  kind: 'material',
+  passes: [
+    {
+      name: 'forward',
+      program: { module: 'test::dummy' },
+      renderState: { tags: { LightMode: 'Forward' } },
+    },
+  ],
+  values: {},
+};
+
+afterEach(() => {
+  // biome-ignore lint/suspicious/noExplicitAny: test teardown
+  delete (globalThis as any).fetch;
+});
+
+describe('AC-07 — a new reference appears in the load graph via envelope.refs', () => {
+  it('an extra ref the importer adds to refs[] is recursively loaded', async () => {
+    const reg = makeRegistry();
+
+    // The "extra reference" sub-asset is pre-registered in dev mode so the
+    // recursive walk hits the fast-path. Stand-in for "importer added a brand
+    // new reference field whose GUID it dropped into refs[]".
+    reg.catalog(parseGuid(EXTRA_REF_GUID), {
+      kind: 'texture',
+      width: 1,
+      height: 1,
+      format: 'rgba8unorm',
+      data: new Uint8Array(4),
+      colorSpace: 'srgb',
+      mipmap: false,
+    });
+
+    const packIndex = [
+      { guid: PARENT_GUID, packageUrl: '/packs/parent.pack.json', kind: 'material' },
+    ];
+    // The pack body carries refs[] = [EXTRA_REF_GUID]. No new switch arm, no
+    // per-kind walker change -- the GUID in refs[] is the entire wiring.
+    const parentPack = {
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      assets: [
+        {
+          guid: PARENT_GUID,
+          kind: 'material',
+          payload: {
+            passes: [
+              {
+                name: 'forward',
+                program: { module: 'test::dummy' },
+                renderState: { tags: { LightMode: 'Forward' } },
+              },
+            ],
+            values: {},
+          },
+          refs: [EXTRA_REF_GUID],
+        },
+      ],
+    };
+
+    reg.configurePackIndex('/pack-index.json');
+    const fetchMock = vi.fn().mockImplementation((url: string) => {
+      if (url === '/pack-index.json') {
+        return Promise.resolve({ ok: true, json: () => Promise.resolve(packIndex) });
+      }
+      if (url === '/packs/parent.pack.json') {
+        return Promise.resolve({ ok: true, json: () => Promise.resolve(parentPack) });
+      }
+      return Promise.resolve({ ok: false, status: 404 });
+    });
+    globalThis.fetch = fetchMock as typeof globalThis.fetch;
+
+    const result = await reg.loadByGuid<MaterialAsset>(parseGuid(PARENT_GUID));
+    expect(result.ok).toBe(true);
+    // The extra reference is in the load graph purely because it is in refs[].
+    expect(reg.lookup(parseGuid(EXTRA_REF_GUID))).not.toBe(undefined);
+  });
+
+  it('catalog() inline path: refs[] drives recursion with no walker', async () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(EXTRA_REF_GUID), {
+      kind: 'sampler',
+      magFilter: 'linear',
+      minFilter: 'linear',
+    });
+    // Direct register with an explicit refs edge; loadByGuid fast-path returns
+    // the body and the refs edge is the recursion source.
+    reg.catalog(parseGuid(PARENT_GUID), stubMaterial, [{ guid: EXTRA_REF_GUID }]);
+    const result = await reg.loadByGuid<MaterialAsset>(parseGuid(PARENT_GUID));
+    expect(result.ok).toBe(true);
+    expect(reg.lookup(parseGuid(EXTRA_REF_GUID))).not.toBe(undefined);
+  });
+});

package/src/__tests__/node-shims.d.ts

@@ -0,0 +1,31 @@
+// Ambient declarations for node:* modules used by dawn tests that read the
+// hello-triangle compiled shader manifest at runtime. The runtime package's
+// tsconfig does not enable @types/node (production target is browser); these
+// minimal shims keep tsc green for the small set of dawn test files that read
+// compiled shader manifests at runtime.
+//
+// Used by shader-manifest Dawn fixtures and the runtime benchmark fixtures.
+// - tilemap-chunk-y-sort-bench.unit.test.ts (perf_hooks + process.env)
+// - record-fold-scene-instances.unit.test.ts (readdirSync + dirname)
+// - basis-catalog-dispatch.integration.test.ts (existsSync pkg-built gate)
+
+declare module 'node:fs' {
+  export function readFileSync(path: string, encoding: string): string;
+  export function readdirSync(path: string): string[];
+  export function existsSync(path: string): boolean;
+}
+
+declare module 'node:path' {
+  export function resolve(...paths: string[]): string;
+  export function dirname(p: string): string;
+}
+
+declare module 'node:url' {
+  export function fileURLToPath(url: string | URL): string;
+}
+
+declare module 'node:perf_hooks' {
+  export const performance: { now(): number };
+}
+
+declare const process: { env: Record<string, string | undefined> };

package/src/__tests__/package-promotion.test.ts

@@ -0,0 +1,88 @@
+// 1->N package promotion idempotence — AC-05 (feat-20260618 w12).
+//
+// Red-first: written before w11 adds the promotion branch to registerPackage.
+//
+// Coverage:
+//   AC-05 — when a single-asset package gains a second asset, the original
+//           asset's derived basename is frozen as its stored name so it keeps
+//           the same resolveName (now via the multi-asset branch), with no error
+//           and no caller awareness. Promotion is idempotent: re-registering the
+//           same path does not overwrite an already-frozen name.
+//
+// The promotion is observable through `package.xor-invariant-violated`: when the
+// original asset already carries a stored name at promotion time (the abnormal
+// single-asset-with-name state, D-4), the freeze must not overwrite it and the
+// soft-violation counter increments. Without w11 there is no promotion branch,
+// so the counter never fires (the falsifying assertion).
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { SamplerAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createEngineMetrics } from '../../../render/src/engine-metrics';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const G1 = 'c0000000-0000-4000-c000-000000000001';
+const G2 = 'c0000000-0000-4000-c000-000000000002';
+const PATH = 'assets/scene.glb';
+
+function parseGuid(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`invalid test GUID: ${s}`);
+  return r.value;
+}
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const sampler: SamplerAsset = { kind: 'sampler' };
+
+describe('1->N package promotion (AC-05)', () => {
+  it('single asset derives basename', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(G1), sampler);
+    reg._registerPackage(PATH, [G1]);
+    expect(reg.resolveName(G1)).toBe('scene.glb');
+  });
+
+  it('adding a second asset keeps the original name unchanged, no error', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(G1), sampler);
+    reg._registerPackage(PATH, [G1]);
+    reg.catalog(parseGuid(G2), sampler);
+    reg._registerPackage(PATH, [G2], new Map([[G2, 'SecondAsset']]));
+
+    expect(reg.resolveName(G1)).toBe('scene.glb');
+    expect(reg.resolveName(G2)).toBe('SecondAsset');
+    expect(reg.packageOf(G1)?.assetCount).toBe(2);
+  });
+
+  it('re-registering the same path is idempotent (does not overwrite frozen name)', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(G1), sampler);
+    reg._registerPackage(PATH, [G1]);
+    reg.catalog(parseGuid(G2), sampler);
+    reg._registerPackage(PATH, [G2], new Map([[G2, 'SecondAsset']]));
+    reg._registerPackage(PATH, [G1, G2], new Map([[G2, 'SecondAsset']]));
+
+    expect(reg.resolveName(G1)).toBe('scene.glb');
+    expect(reg.resolveName(G2)).toBe('SecondAsset');
+  });
+
+  it('abnormal single-asset-with-name state bumps the xor counter and is not overwritten', () => {
+    const reg = makeRegistry();
+    const metrics = createEngineMetrics();
+    reg.setMetrics(metrics);
+    // Abnormal: a single-asset package whose lone asset already carries a name.
+    reg.catalog(parseGuid(G1), sampler);
+    reg._registerPackage(PATH, [G1], new Map([[G1, 'PreNamed']]));
+    reg.catalog(parseGuid(G2), sampler);
+    // Promotion fires: the pre-existing name is preserved (not overwritten by
+    // basename) and the soft-violation counter records the abnormal state.
+    reg._registerPackage(PATH, [G2], new Map([[G2, 'SecondAsset']]));
+
+    expect(reg.resolveName(G1)).toBe('PreNamed');
+    expect(metrics.snapshot()['package.xor-invariant-violated']).toBe(1);
+  });
+});

package/src/__tests__/package-rename.test.ts

@@ -0,0 +1,103 @@
+// rename API (in-memory) three classes + two error paths — AC-06 (feat-20260618 w14).
+//
+// Red-first: written before w13 implements rename.
+//
+// Coverage:
+//   1. null-package asset rename -> resolveName returns the new name
+//   2. multi-asset package rename -> resolveName returns the new name
+//   3. single-asset package rename -> resolveName + packagePath leaf both sync
+//   4. name collision inside the same package -> err(asset-invalid-value)
+//   5. target guid not registered -> err(asset-not-found)
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { SamplerAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const NULL_PKG = 'd0000000-0000-4000-d000-000000000001';
+const MULTI_A = 'd0000000-0000-4000-d000-000000000002';
+const MULTI_B = 'd0000000-0000-4000-d000-000000000003';
+const SINGLE = 'd0000000-0000-4000-d000-000000000004';
+const MISSING = 'd0000000-0000-4000-d000-0000000000ff';
+
+function parseGuid(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`invalid test GUID: ${s}`);
+  return r.value;
+}
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const sampler: SamplerAsset = { kind: 'sampler' };
+
+describe('rename API (AC-06)', () => {
+  it('null-package asset rename updates the stored name', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(NULL_PKG), sampler);
+    reg._registerPackage(null, [NULL_PKG], new Map([[NULL_PKG, 'old']]));
+
+    const r = reg.rename(NULL_PKG, 'fresh');
+    expect(r.ok).toBe(true);
+    expect(reg.resolveName(NULL_PKG)).toBe('fresh');
+  });
+
+  it('multi-asset package rename updates the entry stored name', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(MULTI_A), sampler);
+    reg.catalog(parseGuid(MULTI_B), sampler);
+    reg._registerPackage(
+      'assets/char.glb',
+      [MULTI_A, MULTI_B],
+      new Map([
+        [MULTI_A, 'Body'],
+        [MULTI_B, 'Head'],
+      ]),
+    );
+
+    const r = reg.rename(MULTI_A, 'Torso');
+    expect(r.ok).toBe(true);
+    expect(reg.resolveName(MULTI_A)).toBe('Torso');
+    expect(reg.resolveName(MULTI_B)).toBe('Head');
+  });
+
+  it('single-asset package rename syncs resolveName and packagePath leaf', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(SINGLE), sampler);
+    reg._registerPackage('assets/hero.glb', [SINGLE]);
+
+    const r = reg.rename(SINGLE, 'villain');
+    expect(r.ok).toBe(true);
+    expect(reg.resolveName(SINGLE)).toBe('villain');
+    const pkg = reg.packageOf(SINGLE);
+    expect(pkg).not.toBeNull();
+    expect(pkg?.path.endsWith('villain')).toBe(true);
+  });
+
+  it('name collision inside the same package returns asset-invalid-value', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(MULTI_A), sampler);
+    reg.catalog(parseGuid(MULTI_B), sampler);
+    reg._registerPackage(
+      'assets/char.glb',
+      [MULTI_A, MULTI_B],
+      new Map([
+        [MULTI_A, 'Body'],
+        [MULTI_B, 'Head'],
+      ]),
+    );
+
+    const r = reg.rename(MULTI_A, 'Head');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.code).toBe('asset-invalid-value');
+  });
+
+  it('renaming a missing guid returns asset-not-found', () => {
+    const reg = makeRegistry();
+    const r = reg.rename(MISSING, 'whatever');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.code).toBe('asset-not-found');
+  });
+});

package/src/__tests__/pass-selector.unit.test.ts

@@ -0,0 +1,102 @@
+import type { MaterialPass, PassSelector } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { matchPass, selectPasses } from '../../../render/src/systems/pass-selector';
+
+/*
+ * feat-20260609 M1 / T-003: typed scene/shadow selector required.
+ *
+ * These tests verify the PassSelector matching semantics:
+ *   - selector: {} matches every pass (AC-02)
+ *   - selector with a key filters passes that have that tag key + value in the
+ *     allowed list
+ *   - selector with multiple keys requires all keys to match (AND logic)
+ */
+
+function makePass(name: string, tags?: Record<string, string>): MaterialPass {
+  if (tags !== undefined) {
+    return { name, program: { module: 'forgeax_material::unlit' }, renderState: { tags } };
+  }
+  return { name, program: { module: 'forgeax_material::unlit' } };
+}
+
+describe('pass-selector semantics', () => {
+  describe('selector: {} = match all', () => {
+    it('returns the input array reference (no filtering) for empty selector', () => {
+      const passes = [
+        makePass('Forward', { LightMode: 'Forward' }),
+        makePass('ShadowCaster', { LightMode: 'ShadowCaster' }),
+        makePass('Untagged'),
+      ];
+      const result = selectPasses(passes, {});
+      // AC-02: empty selector returns the input reference unchanged (no array copy)
+      expect(result).toBe(passes);
+      expect(result.length).toBe(3);
+    });
+
+    it('returns empty array reference when input is empty and selector is empty', () => {
+      const passes: MaterialPass[] = [];
+      const result = selectPasses(passes, {});
+      expect(result).toBe(passes);
+      expect(result.length).toBe(0);
+    });
+  });
+
+  describe('selector filtering', () => {
+    it('filters passes by single tag key', () => {
+      const passes = [
+        makePass('Forward', { LightMode: 'Forward' }),
+        makePass('ShadowCaster', { LightMode: 'ShadowCaster' }),
+        makePass('Untagged'),
+      ];
+      const selector: PassSelector = { LightMode: ['Forward'] };
+      const result = selectPasses(passes, selector);
+      expect(result.length).toBe(1);
+      expect(result[0]?.name).toBe('Forward');
+    });
+
+    it('filters passes by multiple allowed values for one key', () => {
+      const passes = [
+        makePass('Forward', { LightMode: 'Forward' }),
+        makePass('ShadowCaster', { LightMode: 'ShadowCaster' }),
+        makePass('Untagged'),
+      ];
+      const selector: PassSelector = { LightMode: ['Forward', 'ShadowCaster'] };
+      const result = selectPasses(passes, selector);
+      expect(result.length).toBe(2);
+      expect(result.map((p) => p.name).sort()).toEqual(['Forward', 'ShadowCaster']);
+    });
+
+    it('returns empty array when no pass matches', () => {
+      const passes = [makePass('Forward', { LightMode: 'Forward' })];
+      const selector: PassSelector = { LightMode: ['ShadowCaster'] };
+      const result = selectPasses(passes, selector);
+      expect(result.length).toBe(0);
+    });
+
+    it('requires all selector keys to match (AND logic)', () => {
+      const passes = [
+        makePass('A', { Kind: 'Opaque', RenderType: 'Main' }),
+        makePass('B', { Kind: 'Transparent', RenderType: 'Main' }),
+        makePass('C', { Kind: 'Opaque', RenderType: 'Shadow' }),
+      ];
+      const selector: PassSelector = { Kind: ['Opaque'], RenderType: ['Main'] };
+      const result = selectPasses(passes, selector);
+      expect(result.length).toBe(1);
+      expect(result[0]?.name).toBe('A');
+    });
+  });
+
+  describe('matchPass edge cases', () => {
+    it('tags with no matching key -> false', () => {
+      expect(matchPass({ LightMode: 'Forward' }, { LightMode: ['ShadowCaster'] })).toBe(false);
+    });
+
+    it('missing key in tags -> false', () => {
+      expect(matchPass({}, { LightMode: ['Forward'] })).toBe(false);
+    });
+
+    it('empty allowed values array -> false', () => {
+      expect(matchPass({ LightMode: 'Forward' }, { LightMode: [] })).toBe(false);
+    });
+  });
+});