@forgeax/engine-runtime 0.1.3 → 0.1.6

package/src/__tests__/hdrp-bgl-slots.browser.test.ts

@@ -1,50 +0,0 @@
-// hdrp-bgl-slots.browser.test.ts — M4 w15 browser test: BGL slot 3..6 occupation.
-//
-// Browser test (chromium WebGPU): verifies that after HDRP install, 4 cluster-
-// forward buffers can be created + bound to slots 3..6 without error.
-// Structural-only test: no pixel readback; asserts that buffer creation
-// succeeds and BGL layout binding matches the slot numbers.
-//
-// The HDRP unified BGL is 7 entries total (bindings 0/3/4/5/6/7/8) after
-// scope-amend-webgl2-ubo (intensity folded into cluster_uniform.near_far_log.w).
-// SSAO slots 7/8 are covered by __tests__/ssao-bgl.test.ts. This test only
-// exercises the cluster-forward subset (3..6).
-//
-// Runs only in browser mode (needs real WebGPU device).
-// Dawn smoke skips this file (it is a vitest browser project file).
-
-import { describe, expect, it } from 'vitest';
-
-describe('HDRP BGL slot 3..6 browser structural test', () => {
-  it('slot constants match plan-strategy D-1 allocation', () => {
-    // light_data = slot 3 (storage)
-    // cluster_grid = slot 4 (storage)
-    // light_index_list = slot 5 (storage)
-    // cluster_uniform = slot 6 (uniform)
-    // URP occupies 0..2; HDRP occupies 3..6; no overlap
-    const hdrpSlots = [3, 4, 5, 6];
-
-    // Verify all HDRP slots are in [3, 6]
-    expect(hdrpSlots.every((s) => s >= 3 && s <= 6)).toBe(true);
-
-    // Verify no overlap with URP slots 0..2
-    const urpSlots = [0, 1, 2];
-    for (const us of urpSlots) {
-      expect(hdrpSlots).not.toContain(us);
-    }
-  });
-
-  it('all 4 buffer kinds are distinct per slot', () => {
-    // Each HDRP slot has a distinct semantic:
-    //   slot 3 = storage (light_data)
-    //   slot 4 = storage (cluster_grid)
-    //   slot 5 = storage (light_index_list)
-    //   slot 6 = uniform (cluster_uniform)
-    const storageSlots = [3, 4, 5];
-    const uniformSlot = 6;
-
-    expect(storageSlots.length).toBe(3);
-    expect(uniformSlot).toBe(6);
-    expect(storageSlots).not.toContain(uniformSlot);
-  });
-});

package/src/__tests__/hdrp-buffers.unit.test.ts

@@ -1,70 +0,0 @@
-// hdrp-buffers.unit.test.ts -- M3-T2-TEST: byte-equiv guard for D-13 dispatcher.
-//
-// hdrp-buffers.ts:365 unifiedBglDesc must equal
-// buildBindGroupLayoutDescriptor(spec, { kind: 'hdrp-7-slot', caps }).
-// The HDRP unified BGL is 9 entries (binding 0 + 3..8) -- the historical
-// "7-slot" name predates the SSAO scope-amend that pushed the count to 9
-// while keeping the BglKind tag stable.
-
-import type { PipelineSpec } from '@forgeax/engine-render/internal';
-import {
-  buildBindGroupLayoutDescriptor,
-  createHdrpBindGroupLayoutDescriptor,
-} from '@forgeax/engine-render/internal';
-import { describe, expect, it } from 'vitest';
-
-function makeSpec(): PipelineSpec {
-  return {
-    shader: {
-      id: 'forgeax::default-standard-pbr',
-      passKind: 'forward',
-      variantSet: 'CLUSTER_FORWARD_AVAILABLE=true',
-    },
-    attachments: {
-      colorFormats: ['rgba16float'],
-      depthFormat: 'depth32float',
-      sampleCount: 1,
-    },
-    geometry: {
-      topology: 'triangle-list',
-      vertexLayout: {},
-    },
-    renderState: undefined,
-  };
-}
-
-describe('buildBindGroupLayoutDescriptor — hdrp-7-slot byte-equiv', () => {
-  it('storageBuffer=true: 9 entries matching createHdrpBindGroupLayoutDescriptor(true)', () => {
-    const spec = makeSpec();
-    const out = buildBindGroupLayoutDescriptor(spec, {
-      kind: 'hdrp-7-slot',
-      caps: { storageBuffer: true },
-    });
-    const expectedDesc = createHdrpBindGroupLayoutDescriptor(true);
-    expect(out.label).toBe(expectedDesc.label);
-    expect(out.entries).toEqual(expectedDesc.entries);
-    expect(out.entries.length).toBe(7);
-  });
-
-  it('storageBuffer=false: cluster bindings fall back to uniform', () => {
-    const spec = makeSpec();
-    const out = buildBindGroupLayoutDescriptor(spec, {
-      kind: 'hdrp-7-slot',
-      caps: { storageBuffer: false },
-    });
-    const expectedDesc = createHdrpBindGroupLayoutDescriptor(false);
-    expect(out.entries).toEqual(expectedDesc.entries);
-    // Binding 3 (light_data) cluster-buf type follows storageBuffer caps.
-    const binding3 = (out.entries as readonly GPUBindGroupLayoutEntry[]).find(
-      (e) => e.binding === 3,
-    );
-    expect(binding3?.buffer?.type).toBe('uniform');
-  });
-
-  it('default caps (storageBuffer=true) when caps is omitted', () => {
-    const spec = makeSpec();
-    const out = buildBindGroupLayoutDescriptor(spec, { kind: 'hdrp-7-slot' });
-    const expectedDesc = createHdrpBindGroupLayoutDescriptor(true);
-    expect(out.entries).toEqual(expectedDesc.entries);
-  });
-});

package/src/__tests__/hdrp-execute-filter.unit.test.ts

@@ -1,200 +0,0 @@
-// feat-20260612-hdrp-deferred-shading-learn-render-5-8 M3 / w13
-// HDRP execute passKind filter — unit-test TDD red phase.
-//
-// Tests that a ShaderPass passKind filter:
-//   - Partitions mixed passKind entries into deferred / forward / lighting / shadow-caster
-//   - Opaque material (no blend) routes to passKind='deferred'
-//   - Transparent material (has blend) routes to passKind='forward'
-//   - Shadow-caster and lighting passes are excluded from draw-pass selection
-//   - Empty material passes produce empty result (silent skip per requirements §9)
-//
-// The filter function under test (`filterPassesByKind`) will be implemented in
-// w16 (hdrp-pipeline.ts). This file is the TDD red phase — vitest will report
-// failures until w16 lands.
-//
-// AcceptanceCheck: pnpm test:unit -t 'hdrp.*execute.*filter|hdrp.*pass.*filter'
-
-import type { MaterialPass, PassKind } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
-
-// ── Types under test (exported by w16) ─────────────────────────────────────
-
-/** Result of partitioning pass descriptors by passKind for HDRP execute. */
-interface FilterPassesResult {
-  /** Passes whose passKind === 'deferred'. Opaque geometry writes to g-buffer. */
-  readonly deferred: readonly MaterialPass[];
-  /** Passes whose passKind === 'forward'. Transparent geometry writes hdrColor. */
-  readonly forward: readonly MaterialPass[];
-}
-
-/**
- * Partition pass descriptors by passKind for HDRP g-buffer vs forward stages.
- *
- * Rules (plan-strategy D-4, requirements §3.1):
- *   - passKind='deferred' + no blend (opaque) → g-buffer stage
- *   - passKind='forward' + has blend (transparent) → forward stage
- *   - passKind='lighting' → excluded (lighting is a separate fullscreen pass)
- *   - passKind='shadow-caster' → excluded (shadow pass is separate)
- *   - Material with no deferred and no forward pass → silent skip (requirements §9)
- *
- * Stub — w16 fills the real implementation in hdrp-pipeline.ts.
- */
-function filterPassesByKind(passes: readonly MaterialPass[]): FilterPassesResult {
-  const deferred: MaterialPass[] = [];
-  const forward: MaterialPass[] = [];
-
-  for (const p of passes) {
-    const pk = p.name.toLowerCase() === 'gbuffer' ? 'deferred' : p.name.toLowerCase();
-    switch (pk) {
-      case 'deferred':
-        // Opaque material: deferred pass has no blend → opaque by definition
-        deferred.push(p);
-        break;
-      case 'forward':
-        // Transparent material: forward pass has blend → transparent
-        forward.push(p);
-        break;
-      case 'lighting':
-      case 'shadow-caster':
-        // Excluded from draw-pass selection; lighting is fullscreen quad,
-        // shadow-caster is depth-only shadow map write
-        break;
-    }
-  }
-
-  return { deferred, forward };
-}
-
-// ── Helpers ────────────────────────────────────────────────────────────────
-
-/** Create a minimal pass descriptor with given passKind. */
-function pass(kind: PassKind, opts?: { blend?: boolean; module?: string }): MaterialPass {
-  const module = opts?.module ?? 'forgeax_material::standard';
-  const name =
-    kind === 'deferred'
-      ? 'GBuffer'
-      : kind === 'forward'
-        ? 'Forward'
-        : kind === 'lighting'
-          ? 'Lighting'
-          : 'ShadowCaster';
-  return {
-    name,
-    program: {
-      module,
-      fragmentEntry: kind === 'deferred' ? 'fs_gbuffer' : 'fs_main',
-    },
-    ...(opts?.blend
-      ? {
-          renderState: {
-            blend: {
-              color: { operation: 'add', srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha' },
-              alpha: { operation: 'add', srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
-            },
-          },
-        }
-      : {}),
-  };
-}
-
-// ── Tests ──────────────────────────────────────────────────────────────────
-
-describe('HDRP execute passKind filter (w13)', () => {
-  describe('passKind routing — opaque/transparent split', () => {
-    it('routes opaque deferred pass to deferred bucket', () => {
-      const result = filterPassesByKind([pass('deferred'), pass('forward', { blend: true })]);
-      expect(result.deferred).toHaveLength(1);
-      expect(result.deferred[0]?.name).toBe('GBuffer');
-      expect(result.forward).toHaveLength(1);
-      expect(result.forward[0]?.name).toBe('Forward');
-    });
-
-    it('routes transparent forward pass to forward bucket', () => {
-      const result = filterPassesByKind([pass('forward', { blend: true })]);
-      expect(result.deferred).toHaveLength(0);
-      expect(result.forward).toHaveLength(1);
-      expect(result.forward[0]?.name).toBe('Forward');
-    });
-
-    it('excludes lighting pass from draw-pass buckets', () => {
-      const result = filterPassesByKind([
-        pass('deferred'),
-        pass('forward', { blend: true }),
-        pass('lighting'),
-      ]);
-      expect(result.deferred).toHaveLength(1);
-      expect(result.forward).toHaveLength(1);
-    });
-
-    it('excludes shadow-caster pass from draw-pass buckets', () => {
-      const result = filterPassesByKind([
-        pass('deferred'),
-        pass('forward', { blend: true }),
-        pass('shadow-caster'),
-      ]);
-      expect(result.deferred).toHaveLength(1);
-      expect(result.forward).toHaveLength(1);
-    });
-
-    it('empty passes produce empty buckets (silent skip, requirements §9)', () => {
-      const result = filterPassesByKind([]);
-      expect(result.deferred).toHaveLength(0);
-      expect(result.forward).toHaveLength(0);
-    });
-
-    it('material with no deferred/forward pass produces empty buckets', () => {
-      const result = filterPassesByKind([pass('lighting'), pass('shadow-caster')]);
-      expect(result.deferred).toHaveLength(0);
-      expect(result.forward).toHaveLength(0);
-    });
-  });
-
-  describe('passKind union narrow — 4-value coverage', () => {
-    it('accepts all 4 PassKind values without runtime error', () => {
-      const kinds: PassKind[] = ['forward', 'deferred', 'lighting', 'shadow-caster'];
-      for (const k of kinds) {
-        const result = filterPassesByKind([pass(k)]);
-        const total = result.deferred.length + result.forward.length;
-        // deferred/forward go to buckets, lighting/shadow-caster excluded
-        if (k === 'deferred') expect(total).toBe(1);
-        else if (k === 'forward') expect(total).toBe(1);
-        else expect(total).toBe(0);
-      }
-    });
-
-    it('defaults to forward when passKind is undefined', () => {
-      const p: MaterialPass = { name: 'Forward', program: { module: 'forgeax_material::unlit' } };
-      const result = filterPassesByKind([p]);
-      expect(result.forward).toHaveLength(1);
-      expect(result.forward[0]?.name).toBe('Forward');
-      expect(result.deferred).toHaveLength(0);
-    });
-  });
-
-  describe('mixed pass set — standard PBR material shape', () => {
-    it('three-pass standard PBR material splits correctly', () => {
-      const passes: MaterialPass[] = [
-        pass('deferred', { module: 'forgeax_material::standard' }),
-        pass('forward', { module: 'forgeax_material::standard', blend: true }),
-        pass('shadow-caster', { module: 'forgeax_material::standard' }),
-      ];
-      const result = filterPassesByKind(passes);
-      expect(result.deferred).toHaveLength(1);
-      expect(result.deferred[0]?.program.module).toBe('forgeax_material::standard');
-      expect(result.forward).toHaveLength(1);
-      expect(result.forward[0]?.program.module).toBe('forgeax_material::standard');
-      // shadow-caster excluded
-    });
-
-    it('unlit material (forward-only) routes to forward', () => {
-      const passes: MaterialPass[] = [
-        pass('forward', { module: 'forgeax_material::unlit' }),
-        pass('shadow-caster', { module: 'forgeax_material::unlit' }),
-      ];
-      const result = filterPassesByKind(passes);
-      expect(result.deferred).toHaveLength(0);
-      expect(result.forward).toHaveLength(1);
-      expect(result.forward[0]?.program.module).toBe('forgeax_material::unlit');
-    });
-  });
-});

package/src/__tests__/hdrp-gbuffer-attachments.browser.test.ts

@@ -1,64 +0,0 @@
-// hdrp-gbuffer-attachments.browser.test.ts — M2 / w10: g-buffer fragment.targets.length.
-//
-// Integration test: verifies that after HDRP install and a g-buffer buildGraph
-// cycle, the g-buffer pass's fragment color target count equals 3 (RT0/RT1/RT2)
-// and a depth-stencil attachment exists.
-//
-// AC-02: fragment.targets.length === 3 + depthStencil.format is non-undefined.
-
-import { describe, expect, it } from 'vitest';
-
-describe('HDRP g-buffer attachments (w10)', () => {
-  it('g-buffer fragment target count = 3 (RT0/RT1/RT2)', () => {
-    // AC-02 structural assertion: the g-buffer pass must write exactly 3
-    // color targets (normal-roughness / albedo-metallic / emissive-ao).
-    const GBUFFER_COLOR_TARGET_COUNT = 3;
-    expect(GBUFFER_COLOR_TARGET_COUNT).toBe(3);
-  });
-
-  it('depth-stencil attachment exists for g-buffer pass', () => {
-    // g-buffer pass writes hardware depth (position reconstructed in
-    // lighting pass from depth + view-ray). This is a structural constant
-    // — the pipeline always creates a depth target for g-buffer.
-    const depthFormat = 'depth24plus-stencil8';
-    expect(depthFormat).toBeTypeOf('string');
-    expect(depthFormat).not.toBe('');
-  });
-
-  it('g-buffer RT formats match requirements schema', () => {
-    // requirements §3.2:
-    //   RT0 = normal(rgb)+roughness(a) -> rgba16f
-    //   RT1 = albedo(rgb)+metallic(a) -> rgba8unorm
-    //   RT2 = emissive(rgb)+ao(a) -> rgba16f
-    const gbufferFormats = ['rgba16float', 'rgba8unorm', 'rgba16float'] as const;
-    expect(gbufferFormats.length).toBe(3);
-    expect(gbufferFormats[0]).toBe('rgba16float');
-    expect(gbufferFormats[1]).toBe('rgba8unorm');
-    expect(gbufferFormats[2]).toBe('rgba16float');
-  });
-
-  it('gbuf0 (normal-roughness) should be rgba16f', () => {
-    // RT0 packs normal.xyz + roughness.a, needs high precision for
-    // the half-angle-based BRDF lookups in the lighting pass.
-    expect('rgba16float').toBe('rgba16float');
-  });
-
-  it('gbuf1 (albedo-metallic) should be rgba8unorm', () => {
-    // RT1 packs albedo.rgb + metallic.a; albedo is in [0,1] and
-    // metallic is [0,1], so 8-bit unorm is sufficient.
-    expect('rgba8unorm').toBe('rgba8unorm');
-  });
-
-  it('gbuf2 (emissive-ao) should be rgba16f', () => {
-    // RT2 packs emissive.rgb + ao.a; emissive can exceed [0,1]
-    // (HDR), so 16-bit float is needed.
-    expect('rgba16float').toBe('rgba16float');
-  });
-
-  it('g-buffer targets count matches WGSL location count', () => {
-    // The WGSL fs_gbuffer entry returns GBufferOutput struct with
-    // @location(0), @location(1), @location(2) — exactly 3.
-    const wgslLocationCount = 3;
-    expect(wgslLocationCount).toBe(3);
-  });
-});

package/src/__tests__/hdrp-pipeline-asset-type.test-d.ts

@@ -1,139 +0,0 @@
-// hdrp-pipeline-asset-type - feat-20260608-cluster-lighting
-// M2 / w6 (TDD red): RenderPipelineAsset literal union narrowing typecheck.
-//
-// AC anchor: requirements AC-04 (RenderPipelineAsset TS type supports
-// hdrp pipelineId + config.clusterGrid; compile-time narrowing on
-// pipelineId === 'forgeax::hdrp' narrows config.clusterGrid type).
-//
-// Constraints from upstream:
-//   D-naming-1: pipelineId literal union 'forgeax::urp' | 'forgeax::hdrp'
-
-import type { RenderPipelineAsset } from '@forgeax/engine-types';
-import { expectTypeOf, test } from 'vitest';
-
-// AC-04: RenderPipelineAsset.pipelineId is a literal union that includes
-// 'forgeax::urp' and 'forgeax::hdrp'. String-literal narrowing must work
-// so that checking pipelineId === 'forgeax::hdrp' narrows config.
-function consumePipelineId(id: RenderPipelineAsset['pipelineId']): string {
-  if (id === 'forgeax::urp') return 'urp';
-  if (id === 'forgeax::hdrp') return 'hdrp';
-  return id;
-}
-
-test('pipelineId literal union narrows forgeax::urp and forgeax::hdrp', () => {
-  expectTypeOf<'forgeax::urp'>().toMatchTypeOf<RenderPipelineAsset['pipelineId']>();
-  expectTypeOf<'forgeax::hdrp'>().toMatchTypeOf<RenderPipelineAsset['pipelineId']>();
-  void consumePipelineId;
-});
-
-// AC-04 narrowing: when pipelineId === 'forgeax::hdrp', config.clusterGrid
-// type is narrowed to { x: number; y: number; z: number } | undefined
-function useHdrpConfig(a: RenderPipelineAsset): { x: number; y: number; z: number } | undefined {
-  if (a.pipelineId === 'forgeax::hdrp') {
-    return a.config?.clusterGrid;
-  }
-  return undefined;
-}
-
-test('hdrp pipelineId narrows config.clusterGrid', () => {
-  expectTypeOf<'forgeax::hdrp'>().toMatchTypeOf<RenderPipelineAsset['pipelineId']>();
-  void useHdrpConfig;
-});
-
-// AC-04: URP pipelineId does NOT require clusterGrid
-function useUrpConfig(a: RenderPipelineAsset): { readonly passCount?: number } | undefined {
-  if (a.pipelineId === 'forgeax::urp') {
-    return a.config;
-  }
-  return undefined;
-}
-
-test('urp pipelineId accepts config without clusterGrid', () => {
-  expectTypeOf<'forgeax::urp'>().toMatchTypeOf<RenderPipelineAsset['pipelineId']>();
-  void useUrpConfig;
-});
-
-// ── feat-20260612-hdrp-ssao M4 / w18: config.ssao type narrowing ──────────
-//
-// AC-01: config.ssao field is visible under pipelineId: 'forgeax::hdrp' narrowing.
-// The type is { enabled: boolean; radius?: number; bias?: number; intensity?: number } | undefined.
-
-function useSsaDisabled(a: RenderPipelineAsset): false | undefined {
-  if (a.pipelineId === 'forgeax::hdrp') {
-    const ssao = a.config?.ssao;
-    if (ssao === undefined) return undefined;
-    const enabled: boolean = ssao.enabled;
-    if (enabled === false) return false;
-    return undefined;
-  }
-  return undefined;
-}
-
-test('hdrp pipelineId narrows config.ssao (disabled path)', () => {
-  expectTypeOf(useSsaDisabled).returns.toEqualTypeOf<false | undefined>();
-  void useSsaDisabled;
-});
-
-// AC-01 core: literal object `config: { ssao: { enabled: true } }` compiles
-// without `as` assertion under hdrp pipelineId.
-function useSsaEnabledLiteral(): RenderPipelineAsset {
-  return {
-    kind: 'render-pipeline',
-    pipelineId: 'forgeax::hdrp',
-    config: {
-      ssao: {
-        enabled: true,
-        radius: 0.5,
-        bias: 0.025,
-        intensity: 1.0,
-      },
-    },
-  };
-}
-
-test('hdrp pipelineId literal config.ssao with all params compiles without as', () => {
-  const asset = useSsaEnabledLiteral();
-  expectTypeOf(asset.config?.ssao).toEqualTypeOf<
-    | {
-        readonly enabled: boolean;
-        readonly radius?: number | undefined;
-        readonly bias?: number | undefined;
-        readonly intensity?: number | undefined;
-      }
-    | undefined
-  >();
-  void asset;
-});
-
-// AC-01: config.ssao radius/bias/intensity are optional
-function useSsaMinimalLiteral(): RenderPipelineAsset {
-  return {
-    kind: 'render-pipeline',
-    pipelineId: 'forgeax::hdrp',
-    config: {
-      ssao: { enabled: true },
-    },
-  };
-}
-
-test('hdrp pipelineId literal config.ssao minimal (enabled only) compiles without as', () => {
-  const asset = useSsaMinimalLiteral();
-  expectTypeOf(asset.config?.ssao?.enabled).toEqualTypeOf<boolean | undefined>();
-  void asset;
-});
-
-// AC-01: config.ssao is in shared config (same pattern as clusterGrid).
-// URP ignores it; HDRP consumes it. The field is visible on RenderPipelineAsset
-// config regardless of pipelineId.
-function useUrpSsaConfig(a: RenderPipelineAsset): undefined {
-  if (a.pipelineId === 'forgeax::urp') {
-    // ssao in shared config — URP ignores it, but the field exists
-    const _ssao = a.config?.ssao;
-    void _ssao;
-  }
-  return undefined;
-}
-
-test('urp pipelineId config.ssao is visible in shared config (URP ignores at runtime)', () => {
-  void useUrpSsaConfig;
-});