@forgeax/engine-runtime 0.1.3 → 0.1.6

package/src/__tests__/helpers/scene-asset-port.ts

@@ -1,23 +0,0 @@
-import { AssetGuid } from '@forgeax/engine-pack/guid';
-import type { Asset } from '@forgeax/engine-types';
-import { createSceneAssetPort, type SceneAssetPort } from '../../scene-asset-port';
-
-export interface TestSceneAssetStore {
-  readonly port: SceneAssetPort;
-  add(guid: string | AssetGuid, asset: Asset): void;
-}
-
-function guidKey(guid: string | AssetGuid): string {
-  return typeof guid === 'string' ? guid : AssetGuid.format(guid);
-}
-
-export function createTestSceneAssetStore(): TestSceneAssetStore {
-  const guids = new WeakMap<object, string>();
-  const port = createSceneAssetPort((asset) => guids.get(asset));
-  return {
-    port,
-    add(guid, asset) {
-      guids.set(asset, guidKey(guid));
-    },
-  };
-}

package/src/__tests__/material-derived-coordinates.integration.test.ts

@@ -1,100 +0,0 @@
-import { writeDerivedMaterialPayload } from '@forgeax/engine-render/internal';
-import { describe, expect, it } from 'vitest';
-
-const schema = [
-  { name: 'albedo', type: 'texture2d' as const },
-  { name: 'normal', type: 'texture2d' as const },
-];
-
-describe('material texture coordinate producer to record', () => {
-  it('preserves odd physical extent correction and authored transforms', () => {
-    const result = writeDerivedMaterialPayload({
-      material: 'coordinates-a',
-      schema,
-      values: {},
-      coordinates: {
-        albedo: {
-          set: 2,
-          transform: { offset: [0.125, 0.25], scale: [2, 3], rotation: 0.5 },
-          physicalUvScale: [2085 / 2088, 1573 / 1576],
-        },
-        normal: {
-          set: 4,
-          transform: { offset: [0.75, 0.5], scale: [4, 5], rotation: -0.25 },
-          physicalUvScale: [7 / 12, 8 / 12],
-        },
-      },
-    });
-    expect(result.ok).toBe(true);
-    if (!result.ok) return;
-    const values = new Float32Array(result.value.buffer);
-    expect(Array.from(values.slice(0, 8))).toEqual(
-      Array.from(new Float32Array([0.125, 0.25, 2, 3, 2, 0.5, 2085 / 2088, 1573 / 1576])),
-    );
-    expect(Array.from(values.slice(8, 16))).toEqual(
-      Array.from(new Float32Array([0.75, 0.5, 4, 5, 4, -0.25, 7 / 12, 8 / 12])),
-    );
-  });
-
-  it('resolves omitted coordinates and rejects non-finite coordinate metadata', () => {
-    const missing = writeDerivedMaterialPayload({
-      material: 'slot-missing',
-      schema,
-      values: {},
-      coordinates: { albedo: { set: 0, physicalUvScale: [1, 1] } },
-    });
-    expect(missing.ok).toBe(true);
-    if (missing.ok) {
-      const values = new Float32Array(missing.value.buffer);
-      expect(Array.from(values.slice(8, 16))).toEqual([0, 0, 1, 1, 0, 0, 1, 1]);
-    }
-
-    const nonFinite = writeDerivedMaterialPayload({
-      material: 'slot-nan',
-      schema,
-      values: {},
-      coordinates: {
-        albedo: {
-          set: 0,
-          transform: { offset: [Number.NaN, 0], scale: [1, 1], rotation: 0 },
-          physicalUvScale: [1, 1],
-        },
-        normal: {
-          set: 0,
-          transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
-          physicalUvScale: [1, 1],
-        },
-      },
-    });
-    expect(nonFinite.ok).toBe(false);
-    if (!nonFinite.ok && nonFinite.error.code === 'material-texture-coordinate-invalid') {
-      expect(nonFinite.error.detail.reason).toBe('non-finite');
-    }
-  });
-
-  it('keeps resource and coordinate ownership isolated when slot order changes', () => {
-    const first = writeDerivedMaterialPayload({
-      material: 'slot-a',
-      schema,
-      values: {},
-      coordinates: {
-        albedo: { set: 1, physicalUvScale: [0.5, 0.5] },
-        normal: { set: 2, physicalUvScale: [0.75, 0.75] },
-      },
-    });
-    const second = writeDerivedMaterialPayload({
-      material: 'slot-b',
-      schema: [...schema].reverse(),
-      values: {},
-      coordinates: {
-        normal: { set: 9, physicalUvScale: [0.25, 0.25] },
-        albedo: { set: 8, physicalUvScale: [0.125, 0.125] },
-      },
-    });
-    expect(first.ok).toBe(true);
-    expect(second.ok).toBe(true);
-    if (!first.ok || !second.ok) return;
-    expect(new Float32Array(first.value.buffer)[4]).toBe(1);
-    expect(new Float32Array(second.value.buffer)[4]).toBe(9);
-  });
-});

package/src/__tests__/pipeline-layout-selection.test.ts

@@ -1,298 +0,0 @@
-// pipeline-layout-selection.test.ts
-// feat-20260609-hdrp-cluster-fragment-ggx M4.5 / w35 (test, TDD red phase).
-//
-// Verifies that the per-variant PipelineLayout selector correctly picks
-// `hdrpPbrPipelineLayout` for HDRP variants (CLUSTER_FORWARD_AVAILABLE=true
-// or canonical '' all-true) and `pbrPipelineLayout` for URP variants
-// (CLUSTER_FORWARD_AVAILABLE=false / undefined).
-//
-// Anchors:
-//   - plan-strategy D-10: per-variant PipelineLayout (option A) -- boot-time
-//     build a second `hdrpPbrPipelineLayout` with HDRP 7-slot BGL; selector
-//     dispatches by `variantSet`.
-//   - plan-strategy D-11: variantSet `''` is canonical all-true (when the
-//     shader declares CLUSTER_FORWARD_AVAILABLE axis) -- HDRP path.
-//   - implement-decisions section 3: hotfix-1 left URP-side standard pipeline
-//     using the 1-slot pbr-mesh-array BGL, mismatching HDRP 7-slot BGL.
-//
-// Mocks:
-//   PipelineLayout is an opaque RHI handle; we use sentinel objects to test
-//   reference identity (the selector returns one of two layouts).
-//
-// TDD red phase (w35): `selectPipelineLayoutForVariant` does NOT exist and
-// pipelineState carries no `hdrpPbrPipelineLayout` field yet. Test imports
-// will fail until w36 lands the boot-time build + w37 lands the selector.
-
-import {
-  resolveMaterialShaderVariantSet,
-  selectPipelineLayoutForVariant,
-} from '@forgeax/engine-render/internal';
-import type { PipelineLayout } from '@forgeax/engine-rhi';
-import { describe, expect, it } from 'vitest';
-
-// Sentinel handles -- structurally `unknown` opaque tokens.
-const URP_LAYOUT = { __brand: 'urp' } as unknown as PipelineLayout;
-const HDRP_LAYOUT = { __brand: 'hdrp' } as unknown as PipelineLayout;
-// bug-20260611-skin-pipeline-layout: selector state shape now includes
-// `pbrSkinPipelineLayout`. Pre-existing HDRP/URP routing tests pass null
-// for the skin slot to keep their behaviour byte-identical to pre-bug;
-// dedicated skin-routing cases live below in their own describe block.
-const SKIN_LAYOUT = { __brand: 'skin' } as unknown as PipelineLayout;
-
-const FULL_STATE = {
-  pbrPipelineLayout: URP_LAYOUT,
-  hdrpPbrPipelineLayout: HDRP_LAYOUT,
-  pbrSkinPipelineLayout: null,
-};
-
-describe('selectPipelineLayoutForVariant -- HDRP vs URP routing (M4.5 / w35)', () => {
-  it('(a) HDRP variantSet `CLUSTER_FORWARD_AVAILABLE=true+...` -> hdrpPbrPipelineLayout', () => {
-    const layout = selectPipelineLayoutForVariant(
-      FULL_STATE,
-      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
-    );
-    expect(layout).toBe(HDRP_LAYOUT);
-  });
-
-  it("(a) HDRP variantSet '' (canonical all-true) -> hdrpPbrPipelineLayout", () => {
-    // Per D-11: '' is the canonical all-true variant key -- equivalent to
-    // explicit `CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true`
-    // when the shader declares both axes. boot-time registers the HDRP-active
-    // entry under '' (createRenderer.ts:2483-2485), so the selector must
-    // route '' to the HDRP layout.
-    const layout = selectPipelineLayoutForVariant(FULL_STATE, '');
-    expect(layout).toBe(HDRP_LAYOUT);
-  });
-
-  it("(b) URP variantSet `CLUSTER_FORWARD_AVAILABLE=false+...' -> pbrPipelineLayout", () => {
-    const layout = selectPipelineLayoutForVariant(
-      FULL_STATE,
-      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
-    );
-    expect(layout).toBe(URP_LAYOUT);
-  });
-
-  it('(b) URP variantSet without CLUSTER_FORWARD_AVAILABLE axis -> pbrPipelineLayout', () => {
-    // STORAGE_BUFFER_AVAILABLE-only variant (shader without the cluster axis
-    // declared). Selector must fall back to pbrPipelineLayout because the
-    // entry was not registered as HDRP-active.
-    const layout = selectPipelineLayoutForVariant(FULL_STATE, 'STORAGE_BUFFER_AVAILABLE=true');
-    expect(layout).toBe(URP_LAYOUT);
-  });
-
-  it('(c) variantSet undefined -> pbrPipelineLayout (backward-compat default)', () => {
-    const layout = selectPipelineLayoutForVariant(FULL_STATE, undefined);
-    expect(layout).toBe(URP_LAYOUT);
-  });
-
-  it('null pipelineState -> null (Camera-only / empty-manifest path)', () => {
-    expect(selectPipelineLayoutForVariant(null, '')).toBeNull();
-    expect(selectPipelineLayoutForVariant(null, undefined)).toBeNull();
-    expect(
-      selectPipelineLayoutForVariant(
-        null,
-        'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
-      ),
-    ).toBeNull();
-  });
-
-  it('hdrpPbrPipelineLayout null but pbrPipelineLayout non-null -> graceful URP fallback for HDRP variant', () => {
-    // When manifest has the cluster axis but boot-time HDRP layout build
-    // failed (e.g., storage buffer not capable), HDRP variant falls back to
-    // URP layout instead of returning null. This avoids hard-disabling the
-    // PSO build path; the WGSL itself will be the URP variant via
-    // findVariantByKey resolution upstream.
-    const partial = {
-      pbrPipelineLayout: URP_LAYOUT,
-      hdrpPbrPipelineLayout: null,
-      pbrSkinPipelineLayout: null,
-    };
-    expect(selectPipelineLayoutForVariant(partial, '')).toBe(URP_LAYOUT);
-    expect(
-      selectPipelineLayoutForVariant(
-        partial,
-        'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
-      ),
-    ).toBe(URP_LAYOUT);
-  });
-
-  it('pbrPipelineLayout null -> null (URP variant has no fallback)', () => {
-    const partial = {
-      pbrPipelineLayout: null,
-      hdrpPbrPipelineLayout: HDRP_LAYOUT,
-      pbrSkinPipelineLayout: null,
-    };
-    expect(selectPipelineLayoutForVariant(partial, undefined)).toBeNull();
-    expect(
-      selectPipelineLayoutForVariant(
-        partial,
-        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
-      ),
-    ).toBeNull();
-  });
-});
-
-// bug-20260611-skin-pipeline-layout-mesh-array-bgl-2bindings:
-// dedicated tests for the LayoutKind='pbr-skin' branch + grep gate.
-describe('selectPipelineLayoutForVariant -- skin LayoutKind routing (bug-20260611)', () => {
-  it('(a) layoutKind=pbr-skin -> pbrSkinPipelineLayout', () => {
-    const state = {
-      pbrPipelineLayout: URP_LAYOUT,
-      hdrpPbrPipelineLayout: HDRP_LAYOUT,
-      pbrSkinPipelineLayout: SKIN_LAYOUT,
-    };
-    expect(selectPipelineLayoutForVariant(state, undefined, 'pbr-skin')).toBe(SKIN_LAYOUT);
-  });
-
-  it('(b) layoutKind=pbr-skin + variantSet="" -> pbrSkinPipelineLayout (skin overrides HDRP)', () => {
-    // HDRP × skin is OOS-1; skin routing wins. Tests the precedence ordering.
-    const state = {
-      pbrPipelineLayout: URP_LAYOUT,
-      hdrpPbrPipelineLayout: HDRP_LAYOUT,
-      pbrSkinPipelineLayout: SKIN_LAYOUT,
-    };
-    expect(selectPipelineLayoutForVariant(state, '', 'pbr-skin')).toBe(SKIN_LAYOUT);
-  });
-
-  it('(c) layoutKind=pbr-skin + pbrSkinPipelineLayout=null -> null (charter P3 explicit fail, AC-10)', () => {
-    // Explicit failure -- no silent fallback to URP layout. Mirrors memory
-    // anchor `hdrp-active-must-not-fallback-to-urp-pipeline`.
-    const state = {
-      pbrPipelineLayout: URP_LAYOUT,
-      hdrpPbrPipelineLayout: HDRP_LAYOUT,
-      pbrSkinPipelineLayout: null,
-    };
-    expect(selectPipelineLayoutForVariant(state, undefined, 'pbr-skin')).toBeNull();
-  });
-
-  it('(d) layoutKind=undefined + skin layout present -> still URP/HDRP path (back-compat)', () => {
-    // Existing PBR/HDRP callers (no layoutKind argument) MUST NOT pick the
-    // skin layout. AC-08 no-collateral.
-    const state = {
-      pbrPipelineLayout: URP_LAYOUT,
-      hdrpPbrPipelineLayout: HDRP_LAYOUT,
-      pbrSkinPipelineLayout: SKIN_LAYOUT,
-    };
-    expect(selectPipelineLayoutForVariant(state, undefined)).toBe(URP_LAYOUT);
-    expect(selectPipelineLayoutForVariant(state, '')).toBe(HDRP_LAYOUT);
-  });
-});
-
-describe('resolveMaterialShaderVariantSet -- backend capability routing', () => {
-  const pbrVariants = [
-    { defines: { CLUSTER_FORWARD_AVAILABLE: false, STORAGE_BUFFER_AVAILABLE: false } },
-    { defines: { CLUSTER_FORWARD_AVAILABLE: false, STORAGE_BUFFER_AVAILABLE: true } },
-    { defines: { CLUSTER_FORWARD_AVAILABLE: true, STORAGE_BUFFER_AVAILABLE: true } },
-  ];
-
-  it('rewrites the storage axis for the WebGL2 fallback', () => {
-    expect(
-      resolveMaterialShaderVariantSet(
-        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
-        pbrVariants,
-        'wgpu-webgl2',
-        false,
-      ),
-    ).toBe('CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false');
-  });
-
-  it('preserves the requested native variant when the backend supports storage buffers', () => {
-    expect(
-      resolveMaterialShaderVariantSet(
-        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
-        pbrVariants,
-        'webgpu',
-        true,
-      ),
-    ).toBe('CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true');
-  });
-
-  it('does not rewrite shaders without capability axes', () => {
-    expect(
-      resolveMaterialShaderVariantSet(
-        'MY_FEATURE=true',
-        [{ defines: { MY_FEATURE: true } }],
-        'wgpu-webgl2',
-        false,
-      ),
-    ).toBe('MY_FEATURE=true');
-  });
-});
-
-// bug-20260708 M2 (c) AC-04: dedicated tests for the LayoutKind='sprite-urp'
-// branch. Sprite / sprite-lit shaders reuse the URP 1-slot mesh-array
-// pipeline layout but their canonical all-true variant key ''
-// (SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET === '') MUST NOT be
-// mis-routed through the variantSet==='' -> HDRP branch. Prevents
-// R-1' device-lost when a SpriteInstances batch requests the canonical
-// PIR=true variant.
-describe('selectPipelineLayoutForVariant -- sprite-urp LayoutKind routing (bug-20260708)', () => {
-  const SPRITE_FULL_STATE = {
-    pbrPipelineLayout: URP_LAYOUT,
-    hdrpPbrPipelineLayout: HDRP_LAYOUT,
-    pbrSkinPipelineLayout: SKIN_LAYOUT,
-  };
-
-  it('(a) layoutKind=sprite-urp + variantSet=undefined -> pbrPipelineLayout (character / sprite-atlas per-entity path)', () => {
-    expect(selectPipelineLayoutForVariant(SPRITE_FULL_STATE, undefined, 'sprite-urp')).toBe(
-      URP_LAYOUT,
-    );
-  });
-
-  it('(b) layoutKind=sprite-urp + variantSet="" -> pbrPipelineLayout (SpriteInstances canonical PIR=true batch, NOT HDRP)', () => {
-    // Critical assertion. Without the sprite-urp branch the canonical ''
-    // variantSet falls into the isHdrpVariant branch of
-    // selectPipelineLayoutForVariant (variantSet === '' short-circuit) and
-    // returns HDRP_LAYOUT — a 7-slot mesh-array BGL incompatible with the
-    // sprite shader's group(2) binding shape. R-1' device-lost path.
-    expect(selectPipelineLayoutForVariant(SPRITE_FULL_STATE, '', 'sprite-urp')).toBe(URP_LAYOUT);
-  });
-
-  it('(c) layoutKind=sprite-urp overrides variantSet with CLUSTER_FORWARD_AVAILABLE=true -> URP (sprite has no HDRP variant)', () => {
-    // Sprite shaders never emit CLUSTER_FORWARD_AVAILABLE axis; this
-    // scenario is a defensive check that sprite-urp routing is stable
-    // even if some caller mis-passes an HDRP-like variantSet.
-    expect(
-      selectPipelineLayoutForVariant(
-        SPRITE_FULL_STATE,
-        'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
-        'sprite-urp',
-      ),
-    ).toBe(URP_LAYOUT);
-  });
-
-  it('(d) layoutKind=sprite-urp + pbrPipelineLayout=null -> null (URP layout unavailable, charter P3 explicit fail)', () => {
-    const partial = {
-      pbrPipelineLayout: null,
-      hdrpPbrPipelineLayout: HDRP_LAYOUT,
-      pbrSkinPipelineLayout: SKIN_LAYOUT,
-    };
-    expect(selectPipelineLayoutForVariant(partial, undefined, 'sprite-urp')).toBeNull();
-    expect(selectPipelineLayoutForVariant(partial, '', 'sprite-urp')).toBeNull();
-  });
-
-  it('(e) pbr-skin still wins over sprite-urp when both would apply (skin precedence anchored earlier in selector)', () => {
-    // Defensive: if a call ever lands with layoutKind='pbr-skin' + a
-    // sprite-like variantSet, the skin branch must take precedence (order
-    // of switch arms in the selector). This pins the ordering so a future
-    // reshuffle of the switch arms doesn't silently accept sprite routing
-    // for a skin caller.
-    expect(selectPipelineLayoutForVariant(SPRITE_FULL_STATE, '', 'pbr-skin')).toBe(SKIN_LAYOUT);
-  });
-});
-
-describe('selectPipelineLayoutForVariant -- unlit-urp LayoutKind routing', () => {
-  it("keeps default-unlit's canonical all-true variant on the URP layout", () => {
-    expect(selectPipelineLayoutForVariant(FULL_STATE, '', 'unlit-urp')).toBe(URP_LAYOUT);
-  });
-
-  it('keeps default-unlit false-color variants on the URP layout', () => {
-    expect(
-      selectPipelineLayoutForVariant(
-        FULL_STATE,
-        'STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
-        'unlit-urp',
-      ),
-    ).toBe(URP_LAYOUT);
-  });
-});

package/src/__tests__/post-process-reads-narrowing.test-d.ts

@@ -1,52 +0,0 @@
-// w2 — tsc-only narrowing probe for PostProcessReadSampleType at the register
-// call site (plan-strategy D-1 / AC-08).
-//
-// Verifies that the closed union `PostProcessReadSampleType = 'depth'` narrows
-// misspellings at the `renderer.postProcess.register(id, { reads })` call site
-// without `as` assertions.  Bare `string[]` remains backward-compatible (AC-03).
-//
-// feat-20260702-postprocess-camera-depth-read M1 / w2.
-
-import type {
-  PostProcessReadEntry,
-  PostProcessReadSampleType,
-} from '@forgeax/engine-render/internal';
-import { describe, expectTypeOf, it } from 'vitest';
-
-describe('w2 PostProcessReadSampleType narrowing at register call site', () => {
-  it('PostProcessReadSampleType = "depth" is a singleton closed union', () => {
-    expectTypeOf<PostProcessReadSampleType>().toEqualTypeOf<'depth'>();
-  });
-
-  it('AC-08: misspelled sampleType "deptth" is a type error at the register call site', () => {
-    // The closed union PostProcessReadSampleType = 'depth' only; 'deptth' is
-    // not assignable — TS reports a type error at this literal.
-    // @ts-expect-error — 'deptth' is not assignable to type 'PostProcessReadSampleType'
-    const _bad: PostProcessReadSampleType = 'deptth';
-  });
-
-  it('AC-08: structured entry with misspelled sampleType fails at the call site', () => {
-    // @ts-expect-error — 'deptth' not assignable to type 'PostProcessReadSampleType'
-    const _badEntry: PostProcessReadEntry = { key: 'depth', sampleType: 'deptth' };
-  });
-
-  it('structured depth entry: { key, sampleType: "depth" } is a valid PostProcessReadEntry', () => {
-    const e: PostProcessReadEntry = { key: 'depth', sampleType: 'depth' };
-    void e;
-  });
-
-  it('structured color entry: { key } without sampleType is a valid PostProcessReadEntry', () => {
-    const e: PostProcessReadEntry = { key: 'sceneColor' };
-    void e;
-  });
-
-  it('AC-03: bare string entries are valid in reads (backward-compatible)', () => {
-    // The reads array accepts string | PostProcessReadEntry elements.
-    // A bare string literal is a valid element alongside structured entries.
-    const r: readonly (string | PostProcessReadEntry)[] = [
-      'sceneColor',
-      { key: 'depth', sampleType: 'depth' },
-    ];
-    void r;
-  });
-});