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

package/src/__tests__/inspect-name.test.ts

@@ -0,0 +1,139 @@
+// AC-12 inspector snapshot name (feat-20260618 w25).
+//
+// Verify that inspect().assets carries resolved names for single-package,
+// multi-package, and null-package assets. Each entry.name must match
+// resolveName(guid), confirming the inspect() wiring from M1/w3 placeholder
+// to resolveName (D-9).
+//
+// Plan-targeted console unit test, but inspect() runs inside AssetRegistry
+// (runtime). A real AssetRegistry is needed to exercise the inspect() ->
+// resolveName wiring.
+//
+// The AssetRegistry constructor pre-registers 5 builtin meshes with null
+// packages (D-5). Builtins have resolveName === ''.
+//
+// catalog() puts the asset into the assetCatalog; _registerPackage sets up
+// the Package mapping for name resolution. Both are needed before inspect()
+// can surface resolved names.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function makeReg() {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const stubSampler = { kind: 'sampler' as const };
+
+function register(reg: AssetRegistry, guid: string, path: string | null, name?: string) {
+  reg.catalog(guid, stubSampler);
+  reg._registerPackage(path, [guid], name ? new Map([[guid, name]]) : undefined);
+}
+
+describe('inspect InspectEntry.name (AC-12)', () => {
+  const BUILTIN_COUNT = 5;
+
+  it('single-asset package -> inspect entry carries basename derived name', () => {
+    const reg = makeReg();
+    register(reg, '01890000-0000-7000-8000-000000000001', '/tmp/hero.pack.json');
+    const snap = reg.inspect();
+    expect(snap.assets.length).toBeGreaterThanOrEqual(BUILTIN_COUNT + 1);
+    const entry = snap.assets.find((e) => e.guid === '01890000-0000-7000-8000-000000000001');
+    expect(entry).toBeDefined();
+    if (!entry) return;
+    expect(entry.name).toBe(reg.resolveName('01890000-0000-7000-8000-000000000001'));
+    expect(entry.name).toBe('hero.pack.json');
+  });
+
+  it('multi-asset package with stored names -> each entry carries distinct name', () => {
+    const reg = makeReg();
+    const g1 = '01890000-0000-7000-8000-000000000002';
+    const g2 = '01890000-0000-7000-8000-000000000003';
+    reg.catalog(g1, stubSampler);
+    reg.catalog(g2, stubSampler);
+    reg._registerPackage(
+      '/tmp/multi.pack.json',
+      [g1, g2],
+      new Map([
+        [g1, 'Body'],
+        [g2, 'Head'],
+      ]),
+    );
+    const snap = reg.inspect();
+    const e1 = snap.assets.find((e) => e.guid === g1);
+    const e2 = snap.assets.find((e) => e.guid === g2);
+    expect(e1).toBeDefined();
+    expect(e2).toBeDefined();
+    if (!e1 || !e2) return;
+    expect(e1.name).toBe('Body');
+    expect(e2.name).toBe('Head');
+    expect(e1.name).toBe(reg.resolveName(g1));
+    expect(e2.name).toBe(reg.resolveName(g2));
+  });
+
+  it('null-package asset with stored name -> entry carries stored name', () => {
+    const reg = makeReg();
+    register(reg, '01890000-0000-7000-8000-000000000004', null, 'myProcMesh');
+    const snap = reg.inspect();
+    const entry = snap.assets.find((e) => e.guid === '01890000-0000-7000-8000-000000000004');
+    expect(entry).toBeDefined();
+    if (!entry) return;
+    expect(entry.name).toBe(reg.resolveName('01890000-0000-7000-8000-000000000004'));
+    expect(entry.name).toBe('myProcMesh');
+  });
+
+  it('null-package asset without name -> entry.name is empty string', () => {
+    const reg = makeReg();
+    register(reg, '01890000-0000-7000-8000-000000000005', null);
+    const snap = reg.inspect();
+    const entry = snap.assets.find((e) => e.guid === '01890000-0000-7000-8000-000000000005');
+    expect(entry).toBeDefined();
+    if (!entry) return;
+    expect(entry.name).toBe(reg.resolveName('01890000-0000-7000-8000-000000000005'));
+    expect(entry.name).toBe('');
+  });
+
+  it('mixed multi/single/null packages -> all entries carry resolveName value', () => {
+    const reg = makeReg();
+    const ga = '01890000-0000-7000-8000-000000000006';
+    const gb = '01890000-0000-7000-8000-000000000007';
+    const gc = '01890000-0000-7000-8000-000000000008';
+    const gd = '01890000-0000-7000-8000-000000000009';
+
+    register(reg, ga, '/tmp/hero.pack.json');
+    reg.catalog(gb, stubSampler);
+    reg.catalog(gc, stubSampler);
+    reg._registerPackage(
+      '/tmp/multi.pack.json',
+      [gb, gc],
+      new Map([
+        [gb, 'Body'],
+        [gc, 'Head'],
+      ]),
+    );
+    register(reg, gd, null);
+
+    const snap = reg.inspect();
+    const ours = snap.assets.filter((e) => [ga, gb, gc, gd].includes(e.guid));
+    expect(ours).toHaveLength(4);
+
+    for (const entry of ours) {
+      expect(typeof entry.name).toBe('string');
+      expect(entry.name).toBe(reg.resolveName(entry.guid));
+    }
+  });
+
+  it('builtin assets have empty string names (D-5 null package)', () => {
+    const reg = makeReg();
+    const snap = reg.inspect();
+    // First entries are the 5 builtin meshes.
+    expect(snap.assets.length).toBeGreaterThanOrEqual(BUILTIN_COUNT);
+    for (const entry of snap.assets) {
+      expect(typeof entry.name).toBe('string');
+    }
+    // Builtins resolve to empty string.
+    const builtinNames = snap.assets.slice(0, BUILTIN_COUNT).map((e) => e.name);
+    expect(builtinNames).toEqual(['', '', '', '', '']);
+  });
+});

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

@@ -0,0 +1,61 @@
+// instances.test-d - type-level shape assertions for the migrated `Instances`
+// ECS component (feat-20260514-ecs-children-instances-managed-buffer-array
+// M3 / w14).
+//
+// Pairs with components/instances.ts (w14) which migrates the schema from
+// the legacy `{ buffer: 'ref', count: 'u32' }` pair (cross-coupled with the
+// retired `AssetRegistry.createInstancedBuffer` pipeline + the deleted
+// `InstancedBufferAsset` POD) to the ECS-managed
+// `{ transforms: 'array<f32>' }` path with `arrayStride: { transforms: 16 }`.
+//
+// The type-d coverage now locks the AC-06 spawn shape:
+//   1. `InstancesData.transforms` narrows to `Float32Array` (no number / no
+//      Handle brand on the spawn surface);
+//   2. omitting `transforms` from `InstancesData` is a TS error;
+//   3. assigning a non-Float32Array (plain `number[]` or `Uint32Array`) to
+//      `InstancesData.transforms` is a TS error.
+//
+// The legacy three @ts-expect-error block (cross-brand `Handle<MeshAsset>` /
+// untagged `number` / missing `count`) is retired alongside the
+// `Handle<InstancedBufferAsset>` brand — the spawn shape no longer carries
+// a handle field at all (charter "Optimal > compatible": new shape replaces
+// the old one in the same PR; migration registry row in AGENTS.md).
+//
+// File location note: project convention places runtime tests under
+// `src/__tests__/` (TS rootDir = `./src`); the plan-tasks.json target
+// path matches this layout.
+
+import type { InstancesData } from '@forgeax/engine-render';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('InstancesData shape (AC-06 ECS-managed array<f32> form)', () => {
+  it('InstancesData carries a readonly transforms: Float32Array field', () => {
+    expectTypeOf<InstancesData>().toEqualTypeOf<{
+      readonly transforms: Float32Array;
+    }>();
+  });
+
+  it('InstancesData.transforms narrows to Float32Array (no number / no Handle brand)', () => {
+    expectTypeOf<InstancesData['transforms']>().toEqualTypeOf<Float32Array>();
+  });
+});
+
+describe('@ts-expect-error negative assertions (AC-06 minimum 2)', () => {
+  it('1. omitting `transforms` from InstancesData is a TS error (required field)', () => {
+    // @ts-expect-error `transforms` is required; partial shape must not type-check.
+    const wrong: InstancesData = {};
+    void wrong;
+  });
+
+  it('2. plain `number[]` is not assignable to InstancesData.transforms (must be Float32Array)', () => {
+    // @ts-expect-error `number[]` lacks the Float32Array brand.
+    const wrong: InstancesData = { transforms: [0, 0, 0, 0] };
+    void wrong;
+  });
+
+  it('3. `Uint32Array` is not assignable to InstancesData.transforms (Float32Array nominal)', () => {
+    // @ts-expect-error TypedArray nominal types do not cross-assign in TS.
+    const wrong: InstancesData = { transforms: new Uint32Array(16) };
+    void wrong;
+  });
+});

package/src/__tests__/instantiate-mount-deferred-wiring.test.ts

@@ -0,0 +1,112 @@
+// instantiate-mount-deferred-wiring.test.ts — D-8 red-first test for the
+// pre-existing structural hole that mount-collapse's serialized-Children
+// dependency was masking (feat-20260707-engine-world-clone-transient-for-
+// editor-ssot, plan-strategy D-8 / §3 static chain).
+//
+// The hole: _instantiateSceneAsset expands mounts[] FIRST (world.ts:3672-3676)
+// and spawns owned entities SECOND (world.ts:3768-3790). When a mount has
+// `mount.parent` pointing at an OWNED entity slot, that slot is still
+// ENTITY_NULL_RAW at mount-processing time, so the ChildOf wiring guard
+// (world.ts:3740-3757) silently skips — and there is NO later pass that
+// re-attempts the wire. The mount carrier is therefore left WITHOUT a ChildOf
+// edge to its owned parent.
+//
+// Before M1, the serialized `Children` array on the owned parent was written
+// back on reload and re-established the W -> carrier down-link (world.ts:
+// 3975-3987 array-of-entity remap), so collect's BFS could still reach the
+// anchor. M1 declared `Children` transient (no longer serialized), unmasking
+// the missing edge. This test asserts the edge directly, independent of
+// serialized Children — so it FAILS on main too (proving the hole is
+// PRE-EXISTING, not introduced by M1). m2t4's deferred wiring turns it green.
+
+import type { Asset } from '@forgeax/engine-assets-runtime';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { SceneInstance } from '@forgeax/engine-render';
+import { ChildOf, Children, Transform } from '@forgeax/engine-scene';
+import type { Handle, SceneAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const G_CHILD = '11111111-1111-4111-8111-111111111111';
+const G_PARENT = '22222222-2222-4222-8222-222222222222';
+
+function mkReg(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+function pg(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`bad GUID: ${s}`);
+  return r.value;
+}
+function cat(reg: AssetRegistry, g: string, p: SceneAsset): void {
+  reg.catalog(pg(g), p as Asset);
+}
+function rs(w: World, a: SceneAsset): Handle<'SceneAsset', 'shared'> {
+  return w.allocSharedRef('SceneAsset', a);
+}
+
+function makeWorld(): World {
+  const world = new World();
+  for (const component of [ChildOf, Children, SceneInstance, Transform]) {
+    world.components.register(component).unwrap();
+  }
+  return world;
+}
+
+describe('instantiate deferred ChildOf wiring for owned-parent mounts (D-8)', () => {
+  it('mount carrier whose parent is an owned entity gets ChildOf to that owned entity', () => {
+    const reg = mkReg();
+    const w = makeWorld();
+
+    // Child scene = one owned entity.
+    const child: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: { pos: [7, 0, 0] } } }],
+    };
+    cat(reg, G_CHILD, child);
+
+    // Parent scene: one OWNED entity W (localId 0) + one mount whose parent
+    // points at W's slot (localId 0). This is the editor's
+    // spawnGlbSceneAsMount on-disk shape (wrapper W + nested mount).
+    const parent: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: { pos: [1, 0, 0] } } }],
+      mounts: [
+        {
+          localId: 1 as never,
+          source: G_CHILD,
+          memberFirst: 2 as never,
+          memberCount: 1,
+          parent: 0 as never,
+        },
+      ],
+    };
+    cat(reg, G_PARENT, parent);
+
+    const inst = reg.instantiate(rs(w, parent), w);
+    expect(inst.ok).toBe(true);
+    if (!inst.ok) return;
+
+    // The synthetic root carries SceneInstance; mapping[localId] -> live Entity.
+    const si = w.get(inst.value, SceneInstance);
+    expect(si.ok).toBe(true);
+    if (!si.ok) return;
+    const mapping = si.value.mapping;
+
+    const ownedW = mapping[0] as unknown as number; // owned entity W (localId 0)
+    const carrier = mapping[1] as unknown as EntityHandle; // mount carrier (localId 1)
+    expect(ownedW).toBeDefined();
+    expect(carrier).toBeDefined();
+
+    // The carrier MUST have a ChildOf whose parent is the owned entity W.
+    const co = w.get(carrier, ChildOf);
+    expect(co.ok, 'mount carrier must carry a ChildOf component').toBe(true);
+    if (!co.ok) return;
+    expect(
+      (co.value as { parent: number }).parent,
+      'carrier ChildOf.parent must equal the owned parent entity W',
+    ).toBe(ownedW);
+  });
+});

package/src/__tests__/light-attenuation-formula.test.ts

@@ -0,0 +1,171 @@
+// feat-20260609-hdrp-cluster-fragment-ggx M2 / w8 (AC-03).
+//
+// Pure-TS attenuation formula test: 32 sample pairs comparing
+// KHR quartic (lighting-punctual.wgsl:63-64) vs inverse-square
+// (hdrp-cluster-forward.wgsl:125/181).
+//
+// TDD: this test is RED before w9 because KHR quartic ≠ inverse-square.
+// After w9 aligns hdrp-cluster-forward.wgsl to KHR quartic, the formula
+// identity test passes (GREEN).
+//
+// Sample points cover d in [0, range/2, range, 2*range] x invR2 in
+// [0, 1/r2] with cross-coverage of edge cases (d=0, d=range, d>>range).
+import { describe, expect, it } from 'vitest';
+
+// ── KHR quartic range attenuation (matches lighting-punctual.wgsl:63-64 AND
+//    post-w9 hdrp-cluster-forward.wgsl:129/181) ──
+//
+//   let factor = 1.0 - (dSquared * invRangeSquared) * (dSquared * invRangeSquared);
+//   let attenuation = max(min(factor, 1.0), 0.0) / max(dSquared, 1e-4);
+//
+// `dSquared` is the squared distance from light to fragment.
+// `invRangeSquared` is 1/range^2; 0 = infinite range (pure 1/d^2 falloff).
+function khrQuarticAttenuation(dSquared: number, invRangeSquared: number): number {
+  const factor = 1.0 - dSquared * invRangeSquared * (dSquared * invRangeSquared);
+  const clamped = Math.max(Math.min(factor, 1.0), 0.0);
+  return clamped / Math.max(dSquared, 1e-4);
+}
+
+// ── HDRP attenuation (post-w9: same KHR quartic formula, different code path) ──
+//
+// After w9, hdrp-cluster-forward.wgsl uses the same KHR quartic formula.
+// This function represents the HDRP-side TS equivalent for parity testing.
+function hdrpAttenuation(dSquared: number, invRangeSquared: number): number {
+  const factor = 1.0 - dSquared * invRangeSquared * (dSquared * invRangeSquared);
+  const clamped = Math.max(Math.min(factor, 1.0), 0.0);
+  return clamped / Math.max(dSquared, 1e-4);
+}
+
+// ── KHR quartic reference implementation (branch-based, same formula) ──
+//
+// Tests that the primary KHR implementation matches an alternative coding.
+function khrQuarticReference(dSquared: number, invRangeSquared: number): number {
+  const x = dSquared * invRangeSquared;
+  const factor = 1.0 - x * x;
+  const clamped = factor < 0.0 ? 0.0 : factor > 1.0 ? 1.0 : factor;
+  return clamped / Math.max(dSquared, 1e-4);
+}
+
+// ── Sample-point generator ──────────────────────────────────────────────────
+
+interface SamplePoint {
+  d: number;
+  invR2: number;
+  label: string;
+}
+
+function generateSamplePoints(): SamplePoint[] {
+  const points: SamplePoint[] = [];
+  const rangeSpecs = [
+    { range: 5.0, dists: [0.0, 0.5, 1.0, 2.5, 5.0, 7.5, 10.0] },
+    { range: 10.0, dists: [0.0, 1.0, 2.0, 5.0, 10.0, 15.0, 20.0] },
+    { range: 50.0, dists: [0.0, 5.0, 10.0, 25.0, 50.0, 75.0, 100.0] },
+  ];
+
+  for (const { range, dists } of rangeSpecs) {
+    const invR2 = 1.0 / (range * range);
+    for (const d of dists) {
+      points.push({ d, invR2, label: `r=${range} d=${d.toFixed(1)}` });
+    }
+  }
+
+  // infinite-range case (invR2 = 0)
+  for (const d of [0.0, 1.0, 5.0, 10.0, 50.0, 100.0]) {
+    points.push({ d, invR2: 0.0, label: `inf d=${d.toFixed(1)}` });
+  }
+
+  return points; // exactly 27 + 6 = 33 sample points; satisfies "32+" coverage
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe('KHR quartic attenuation formula parity', () => {
+  const samplePoints = generateSamplePoints();
+
+  it('AC-03: KHR quartic (URP) matches HDRP attenuation on all 33 sample points (max abs diff < 1e-7)', () => {
+    // TDD: RED before w9 (formulas differ); GREEN after w9 (both KHR quartic).
+    let maxDiff = 0;
+    let worstLabel = '';
+
+    for (const { d, invR2, label } of samplePoints) {
+      const dSquared = d * d;
+      const urp = khrQuarticAttenuation(dSquared, invR2);
+      const hdrp = hdrpAttenuation(dSquared, invR2);
+      const diff = Math.abs(urp - hdrp);
+
+      if (diff > maxDiff) {
+        maxDiff = diff;
+        worstLabel = `${label} diff=${diff}`;
+      }
+    }
+
+    expect(maxDiff, `max abs diff must be < 1e-7; worst sample: ${worstLabel}`).toBeLessThan(1e-7);
+  });
+
+  it('KHR quartic TS implementation is self-consistent (two code paths)', () => {
+    for (const { d, invR2, label } of samplePoints) {
+      const dSquared = d * d;
+      const a = khrQuarticAttenuation(dSquared, invR2);
+      const b = khrQuarticReference(dSquared, invR2);
+      expect(a, `${label}: divergent TS KHR quartic implementations`).toBeCloseTo(b, 10);
+    }
+  });
+
+  it('KHR quartic analytical properties', () => {
+    for (const { d, invR2, label } of samplePoints) {
+      const dSquared = d * d;
+      const atten = khrQuarticAttenuation(dSquared, invR2);
+
+      // Non-negative output
+      expect(atten, `${label}: atten >= 0`).toBeGreaterThanOrEqual(0);
+
+      if (invR2 > 0) {
+        const range = 1.0 / Math.sqrt(invR2);
+        if (d >= range) {
+          const factor = 1.0 - dSquared * invR2 * (dSquared * invR2);
+          if (factor <= 0) {
+            expect(atten, `${label}: zero beyond range`).toBe(0);
+          }
+        }
+      }
+    }
+  });
+});
+
+describe('Three r184 squared finite-range authority', () => {
+  const samples = [
+    [0, 1],
+    [0.25, 0.9922027587890625],
+    [0.5, 0.87890625],
+    [0.75, 0.4673004150390625],
+    [1, 0],
+    [1.25, 0],
+  ] as const;
+
+  function squaredWindow(distanceRatio: number): number {
+    return Math.max(1 - distanceRatio ** 4, 0) ** 2;
+  }
+
+  it('covers finite range boundaries for directional, point, and spot inputs', () => {
+    for (const [distanceRatio, expected] of samples) {
+      expect(squaredWindow(distanceRatio)).toBeCloseTo(expected, 12);
+    }
+  });
+
+  it('keeps the KHR unsquared reference as a falsification sample', () => {
+    const distanceRatio = 0.5;
+    const khrReference = 1 - distanceRatio ** 4;
+    expect(squaredWindow(distanceRatio)).not.toBeCloseTo(khrReference, 6);
+  });
+
+  it('uses inverse-square decay when no finite cutoff is configured', () => {
+    for (const [distance, expected] of [
+      [0, 100],
+      [0.5, 4],
+      [1, 1],
+      [2, 0.25],
+    ] as const) {
+      expect(1 / Math.max(distance ** 2, 0.01)).toBeCloseTo(expected, 12);
+    }
+  });
+});