@forgeax/engine-runtime 0.1.4 → 0.1.6

package/src/__tests__/shadow-m3-calibrate.ts

@@ -1,203 +0,0 @@
-// shadow-m3-calibrate.ts - feat-20260520-directional-light-shadow-mapping
-// M3 / w15: AC-13 threshold calibration helper.
-//
-// This module is NOT a test file (no .test.ts suffix) — vitest will not
-// auto-discover it. It exports a `calibrateThresholdX` function that measures
-// shadow factor diffs between M2 (naive) and M3 (bias+PCF) on a common fixture
-// and prints the suggested AC_13_THRESHOLD_X.
-//
-// Workflow (plan-strategy D-4):
-//   Step 1 (w15 RED):  write this helper + shadow-m3.dawn.test.ts with
-//                      placeholder X=0.05. Calibration returns trivial diffs
-//                      (M2==M2 before w16). AC-13 stays RED.
-//   Step 2 (w16 impl): implement pbr.wgsl bias+PCF. Compile + build.
-//   Step 3 (w16 calibrate): run this helper via the calibration runner
-//                           shadow-m3-calibrate-run.dawn.test.ts. Collect
-//                           max(diff) and suggested X.
-//   Step 4 (w16 freeze):   edit shadow-m3.dawn.test.ts to set AC_13_THRESHOLD_X
-//                           to the calibrated value. Commit. AC-13 turns GREEN.
-//
-// The helper samples N >= 10 acne-prone ground-plane positions where M2 shows
-// spurious sub-1 shadow factors (acne artifact). It reads shadow factors
-// pre-change (current shader = M2 baseline) and post-change (after M3
-// bias+PCF is deployed). The suggested X = floor(max(diff) * 0.5 * 100) / 100
-// with a floor of 0.02 to avoid vanishing thresholds that invite flakiness.
-
-import type { Renderer } from '@forgeax/engine-render/internal';
-
-/**
- * Shadow factor sample returned by debugSampleShadowFactor.
- * Matches the return type shape from Renderer.debugSampleShadowFactor.
- */
-export interface ShadowFactorSample {
-  readonly shadowFactor: number;
-}
-
-/**
- * Calibration result: per-sample M2/M3 factors + derived threshold.
- */
-export interface CalibrationResult {
-  /** Per-sample data ordered by the input positions array. */
-  samples: CalibrationSample[];
-  /** Maximum |m2Factor - m3Factor| across all samples. */
-  maxDiff: number;
-  /** Suggested AC_13_THRESHOLD_X = max(floor(maxDiff * 0.5 * 100) / 100, 0.02). */
-  suggestedX: number;
-  /** Sample count. */
-  sampleCount: number;
-}
-
-export interface CalibrationSample {
-  position: readonly [number, number, number];
-  m2Factor: number;
-  m3Factor: number;
-  diff: number;
-}
-
-/**
- * Fixed acne probe positions for calibration.
- *
- * All positions lie on the ground plane (y=0) in the -X lit region where M2
- * naive depth comparison produces spurious sub-1 shadow factors due to
- * surface self-shadowing. The cube occluder at (0, 1.3, 0) + light tilting +X
- * means the -X region should be fully lit.
- *
- * SSOT: must stay in sync with shadow-m3.dawn.test.ts acne sample constants.
- */
-export const CALIBRATION_POSITIONS: ReadonlyArray<readonly [number, number, number]> = [
-  [-4, 0, 0],
-  [-3, 0, 2],
-  [-4, 0, -2],
-  [-2.5, 0, -1],
-  [-3.5, 0, 1],
-  [-2, 0, -2.5],
-  [-4.5, 0, -0.5],
-  [-1.5, 0, 2.5],
-  [-3, 0, -1.5],
-  [-5, 0, 0.5],
-  // Extra round to 12 — more samples reduce threshold noise.
-  [-4.2, 0, 1.2],
-  [-3.8, 0, -0.8],
-];
-
-/**
- * Read M2 shadow factors from the renderer (GPU probe, pre-bias/pre-PCF).
- *
- * In the RED phase (before w16), this is the same as M3 — so diffs are zero.
- * After w16 lands (bias+PCF in pbr.wgsl), the renderer reflects the new
- * shader and m2Factors become a historical baseline from the pre-M3 commit.
- *
- * For a single-session implementer, the calibration workflow is:
- *   1. Record M2 factors with the current (naive) shader
- *   2. Apply w16 (pbr.wgsl bias+PCF)
- *   3. Rebuild, re-measure M3 factors
- *   4. Call `computeThresholdX(m2Factors, m3Factors)` on the stored values
- *
- * This function measures the **current** shadow factors via debugSampleShadowFactor.
- */
-export async function measureShadowFactors(
-  renderer: Renderer,
-  positions: ReadonlyArray<readonly [number, number, number]>,
-): Promise<number[]> {
-  const results = await renderer.debugSampleShadowFactor?.(positions);
-  if (!results) throw new Error('debugSampleShadowFactor returned null');
-  return results.map((r) => r.shadowFactor);
-}
-
-/**
- * Compute the suggested AC-13 threshold X from measured M2 and M3 shadow factors.
- *
- * X = max(floor(max(|m2 - m3|) * 0.5 * 100) / 100, 0.02)
- *
- * The 0.5 multiplier gives headroom (roughly half the maximum observed
- * improvement); the floor at 0.02 prevents vanishing thresholds that would
- * make AC-13 flaky at machine-boundary epsilon.
- */
-export function computeThresholdX(
-  m2Factors: readonly number[],
-  m3Factors: readonly number[],
-): { maxDiff: number; suggestedX: number } {
-  let maxDiff = 0;
-  for (let i = 0; i < m2Factors.length && i < m3Factors.length; i++) {
-    const diff = Math.abs((m2Factors[i] as number) - (m3Factors[i] as number));
-    if (diff > maxDiff) maxDiff = diff;
-  }
-  const rawX = Math.floor(maxDiff * 0.5 * 100) / 100;
-  const suggestedX = Math.max(rawX, 0.02);
-  return { maxDiff, suggestedX };
-}
-
-/**
- * Full calibration: reads M2 + M3 shadow factors from the same renderer and
- * computes the suggested threshold.
- *
- * `measureM2`: function returning M2 factors (pre-bias/PCF baseline).
- * `measureM3`: function returning M3 factors (post-bias/PCF with current shader).
- *
- * In a single-session workflow these two calls happen on the same renderer but
- * at different points in time (pre-w16 commit vs post-w16 build).
- */
-export async function calibrateThresholdX(
-  positions: ReadonlyArray<readonly [number, number, number]>,
-  measureM2: () => Promise<number[]>,
-  measureM3: () => Promise<number[]>,
-): Promise<CalibrationResult> {
-  const m2Factors = await measureM2();
-  const m3Factors = await measureM3();
-
-  const { maxDiff, suggestedX } = computeThresholdX(m2Factors, m3Factors);
-
-  const samples: CalibrationSample[] = [];
-  for (let i = 0; i < positions.length; i++) {
-    const pos = positions[i];
-    if (!pos) continue;
-    const m2 = m2Factors[i] as number;
-    const m3 = m3Factors[i] as number;
-    samples.push({
-      position: pos,
-      m2Factor: m2,
-      m3Factor: m3,
-      diff: Math.abs(m2 - m3),
-    });
-  }
-
-  return {
-    samples,
-    maxDiff,
-    suggestedX,
-    sampleCount: samples.length,
-  };
-}
-
-/**
- * Pretty-print calibration result to stdout for implementer consumption.
- */
-export function printCalibrationReport(result: CalibrationResult): void {
-  console.warn('═══════════════════════════════════════════════════════════');
-  console.warn('  M3 AC-13 threshold calibration report');
-  console.warn('═══════════════════════════════════════════════════════════');
-  console.warn(`  Sample count : ${result.sampleCount}`);
-  console.warn('  Sample |' + ' position          | M2 factor | M3 factor | diff');
-  console.warn('  -------|-------------------|-----------|-----------|--------');
-  for (let i = 0; i < result.samples.length; i++) {
-    const s = result.samples[i];
-    if (!s) continue;
-    const posStr = `(${s.position[0].toFixed(1)}, ${s.position[1].toFixed(1)}, ${s.position[2].toFixed(1)})`;
-    console.warn(
-      `  ${String(i).padStart(6)} | ${posStr.padEnd(17)} |` +
-        ` ${s.m2Factor.toFixed(4).padStart(9)} |` +
-        ` ${s.m3Factor.toFixed(4).padStart(9)} |` +
-        ` ${s.diff.toFixed(4).padStart(6)}`,
-    );
-  }
-  console.warn('  -------|-------------------|-----------|-----------|--------');
-  console.warn(`  max(diff)            = ${result.maxDiff.toFixed(4)}`);
-  console.warn(`  suggested X          = ${result.suggestedX.toFixed(2)}`);
-  console.warn('  (X = max(floor(maxDiff * 0.5 * 100) / 100, 0.02))');
-  console.warn('');
-  console.warn(
-    '  Next step: set AC_13_THRESHOLD_X =' +
-      ` ${result.suggestedX.toFixed(2)} in shadow-m3.dawn.test.ts`,
-  );
-  console.warn('═══════════════════════════════════════════════════════════');
-}

package/src/__tests__/shadow-m3.dawn.test.ts

@@ -1,288 +0,0 @@
-// shadow-m3.dawn.test.ts -
-// feat-20260621-merge-directionallightshadow-into-directionallight / M3 / m3-t1.
-//
-// M3 wires the merged DirectionalLight's depthBias / normalBias / pcfKernelSize
-// into the View UBO tail (floats [126/127/128], bytes 504/508/512) and drives
-// the directional shadow bias + variable-width PCF loop from those uniforms
-// (lighting-directional.wgsl::_sampleShadowForCascade, D-1 / D-2). This test is
-// the RED gate for that wiring.
-//
-// AC anchor: requirements AC-03 (shadow params flow from the merged component to
-// the shader) + AC-08 (View UBO byte layout stays fixed: VIEW_PAYLOAD_FLOATS=148
-// / VIEW_UBO_BYTES=592 unchanged; append at tail). plan-strategy D-1 (directional
-// bias mapping: normalBias=slope, depthBias=floor), D-2 (variable-width PCF
-// driven by pcfKernelSize via the merged 5.3-production-shadow-demos AC-14
-// constant-trip-count loop), D-7 (host clamp pcfKernelSize into {1,3,5}).
-//
-// What is observable, and why these assertions:
-//   * The View UBO buffer is created UNIFORM | COPY_DST only (no COPY_SRC) and
-//     there is no debug accessor returning its bytes, so the float-slot
-//     placement cannot be asserted by GPU readback. The debugSampleShadowFactor
-//     probe is a SELF-CONTAINED shader (hardcoded bias + fixed 3x3 textureLoad)
-//     that never binds the View UBO, so it cannot observe pcfKernelSize either.
-//   * The shader-wiring RED gate is therefore asserted against the COMPOSED
-//     engine shader: _sampleShadowForCascade reads view.pcfKernelSize and runs
-//     a kernel/MAX_PCF_HALF constant-trip-count PCF loop (variant-free, merged
-//     from 5.3-production-shadow-demos AC-14), and derives the bias from
-//     view.normalBias / view.depthBias (D-1). Pre-wiring the composed default-standard-pbr shader
-//     has none of these tokens (RED); post-m3-t4 it does (GREEN). The composed
-//     WGSL is the single source the GPU compiles, so this is a faithful gate.
-//   * The merged component is exercised end-to-end on a real device: a single
-//     DirectionalLight (castShadow default true) + cube occluder + ground
-//     populates the shadow atlas, and debugSampleShadowFactor reports occluded
-//     positions shadowed and lit positions lit -- proving the merged shadow
-//     fields drive a working shadow pass.
-//   * Byte-layout invariance (AC-08) is asserted structurally: if the host
-//     payload float count or the WGSL struct byte size drifted out of sync, the
-//     pbr pipeline would fail to compile / validate and renderer.ready /
-//     renderer.draw would not return ok. A clean default-config render across
-//     the four clamped kernel sizes is the proxy for "VIEW_UBO_BYTES unchanged".
-
-import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import {
-  Camera,
-  DirectionalLight,
-  MeshFilter,
-  MeshRenderer,
-} from '@forgeax/engine-render/internal';
-import { Transform } from '@forgeax/engine-scene';
-import { describe, expect, it } from 'vitest';
-import { createRenderer } from '../index';
-import { drawPublished } from './draw-published';
-
-const WIDTH = 256;
-const HEIGHT = 256;
-const TEXTURE_USAGE_COPY_SRC = 0x01;
-const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
-const GROUND_SIZE = 20;
-
-const ENGINE_MANIFEST = await (async () => {
-  const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
-  return buildEngineShaderManifest();
-})();
-const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(
-  JSON.stringify(ENGINE_MANIFEST),
-)}`;
-
-// biome-ignore lint/suspicious/noExplicitAny: dawn-node detection guard
-const dawnReady = typeof navigator !== 'undefined' && (navigator as any).gpu !== undefined;
-
-/** The composed default-standard-pbr WGSL the GPU actually compiles. */
-function composedStandardPbr(): string {
-  const m = ENGINE_MANIFEST.materialShaders.find(
-    (s) => s.identifier === 'forgeax::default-standard-pbr',
-  );
-  if (m === undefined) throw new Error('default-standard-pbr not in engine manifest');
-  return m.composedWgsl;
-}
-
-function createMockCanvas(): { canvas: HTMLCanvasElement; getDevice: () => GPUDevice | undefined } {
-  let sharedDevice: GPUDevice | undefined;
-  const originalRequestAdapter = globalThis.navigator.gpu.requestAdapter.bind(
-    globalThis.navigator.gpu,
-  );
-  globalThis.navigator.gpu.requestAdapter = async (opts) => {
-    const rawAdapter = await originalRequestAdapter(opts);
-    if (rawAdapter === null) return rawAdapter;
-    const originalRequestDevice = rawAdapter.requestDevice.bind(rawAdapter);
-    rawAdapter.requestDevice = async (desc) => {
-      const dev = await originalRequestDevice(desc);
-      if (sharedDevice === undefined) sharedDevice = dev;
-      return dev;
-    };
-    return rawAdapter;
-  };
-  let renderTarget: GPUTexture | undefined;
-  const ensureRenderTarget = (device: GPUDevice, format: GPUTextureFormat): GPUTexture => {
-    if (renderTarget !== undefined) return renderTarget;
-    renderTarget = device.createTexture({
-      size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
-      format,
-      usage: TEXTURE_USAGE_RENDER_ATTACHMENT | TEXTURE_USAGE_COPY_SRC,
-      viewFormats: ['rgba8unorm-srgb'],
-    });
-    return renderTarget;
-  };
-  const canvas = {
-    width: WIDTH,
-    height: HEIGHT,
-    getContext(kind: string): unknown {
-      if (kind !== 'webgpu') return null;
-      return {
-        configure(desc: { device: GPUDevice; format?: GPUTextureFormat }) {
-          ensureRenderTarget(desc.device, desc.format ?? 'rgba8unorm');
-        },
-        unconfigure() {},
-        getCurrentTexture(): GPUTexture {
-          if (renderTarget === undefined) {
-            if (sharedDevice === undefined)
-              throw new Error('render target requested before device captured');
-            return ensureRenderTarget(sharedDevice, 'rgba8unorm');
-          }
-          return renderTarget;
-        },
-      };
-    },
-    addEventListener() {},
-    removeEventListener() {},
-  } as unknown as HTMLCanvasElement;
-  return { canvas, getDevice: () => sharedDevice };
-}
-
-/**
- * Cube occluder above a ground plane, lit by a near-vertical directional light.
- * The camera looks down the -Z axis (orthographic) so the full scene is in the
- * shadow atlas fit. `pcfKernelSize` is set on the single merged DirectionalLight.
- */
-function buildShadowScene(world: World, pcfKernelSize: number): void {
-  const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
-  // Ground plane (flattened cube), top face at y=0. Empty MeshRenderer ->
-  // engine default standard material (shadow-receiving forward pass).
-  world
-    .spawn(
-      {
-        component: Transform,
-        data: {
-          pos: [0, -0.005, 0],
-          quat: [0, 0, 0, 1],
-          scale: [GROUND_SIZE, 0.01, GROUND_SIZE],
-        },
-      },
-      { component: MeshFilter, data: { assetHandle: cubeHandle } },
-      { component: MeshRenderer, data: {} },
-    )
-    .unwrap();
-
-  // Occluder cube, 2x2x2 centred at y=1.5 (bottom at y=0.5).
-  world
-    .spawn(
-      {
-        component: Transform,
-        data: { pos: [0, 1.5, 0], quat: [0, 0, 0, 1], scale: [2, 2, 2] },
-      },
-      { component: MeshFilter, data: { assetHandle: cubeHandle } },
-      { component: MeshRenderer, data: {} },
-    )
-    .unwrap();
-
-  world
-    .spawn({
-      component: DirectionalLight,
-      data: {
-        direction: [0.2, -0.98, 0],
-        color: [1, 1, 1],
-        intensity: 1.5,
-        // Single cascade so the cube/ground land in the tile-0 slot the probe
-        // samples (same migration the prior M2/M3 fixtures relied on).
-        cascadeCount: 1,
-        mapSize: 1024,
-        shadowDistance: 50,
-        pcfKernelSize,
-      },
-    })
-    .unwrap();
-
-  world
-    .spawn(
-      { component: Transform, data: { pos: [0, 0, 10], quat: [0, 0, 0, 1] } },
-      {
-        component: Camera,
-        data: {
-          projection: 1,
-          left: -5,
-          right: 5,
-          bottom: -5,
-          top: 5,
-          near: 0.1,
-          far: 100,
-          fov: 0,
-          aspect: 1,
-        } as Record<string, unknown> as never,
-      },
-    )
-    .unwrap();
-}
-
-describe('shadow M3 dawn: merged DirectionalLight shadow params -> View UBO + variable PCF', () => {
-  it.skipIf(!dawnReady)("'dawn-binding-missing' -- dawn.node binding injection failed", () => {
-    expect(dawnReady).toBe(true);
-  });
-
-  it('composed default-standard-pbr drives shadow bias + PCF from View uniforms (D-1/D-2)', () => {
-    const wgsl = composedStandardPbr();
-    // D-1: bias is derived from the View UBO's normalBias (slope) + depthBias
-    // (floor), replacing the prior hardcoded max(0.05*(1-N.L), 0.005).
-    expect(wgsl).toContain('normalBias');
-    expect(wgsl).toContain('depthBias');
-    // D-2: the directional PCF loop is driven by view.pcfKernelSize via a
-    // runtime-clamped kernel half-extent (constant trip count to MAX_PCF_HALF,
-    // per-iteration radius clip — the variant-free pattern merged from
-    // 5.3-production-shadow-demos AC-14), not a fixed 3x3.
-    expect(wgsl).toContain('pcfKernelSize');
-    // Composition may rename or fold local variables. The runtime width read
-    // and rounding are the textual contract; the pixel and all-kernel tests
-    // below prove the branch behavior through Dawn.
-    expect(wgsl).toMatch(/round\(/);
-  });
-
-  it.skipIf(!dawnReady)(
-    'merged DirectionalLight casts a shadow (occluded < lit) via debugSampleShadowFactor',
-    async () => {
-      const { canvas, getDevice } = createMockCanvas();
-      const renderer = await createRenderer(canvas, {}, { shaderManifestUrl: ENGINE_MANIFEST_URL });
-      expect(renderer.backend).toBe('webgpu');
-      const ready = await renderer.ready;
-      expect(ready.ok).toBe(true);
-
-      const world = new World();
-      buildShadowScene(world, 7);
-      world.update(1 / 60).unwrap();
-      const draw = drawPublished(renderer, world);
-      expect(draw.ok).toBe(true);
-      const device = getDevice();
-      if (device !== undefined) await device.queue.onSubmittedWorkDone();
-
-      // Occluded ground positions under the cube vs a lit position well outside
-      // the shadow. The probe reads the shadow atlas the merged component's
-      // shadow fields populated.
-      const occluded: [number, number, number][] = [
-        [0, 0, 0],
-        [0.5, 0, 0],
-      ];
-      const lit: [number, number, number][] = [[-4, 0, 0]];
-      const occRes = await renderer.debugSampleShadowFactor?.(occluded);
-      const litRes = await renderer.debugSampleShadowFactor?.(lit);
-      expect(occRes).not.toBeNull();
-      expect(litRes).not.toBeNull();
-      if (!occRes || !litRes) throw new Error('debugSampleShadowFactor returned null');
-
-      for (const r of occRes) expect(r.shadowFactor).toBeLessThan(0.5);
-      for (const r of litRes) expect(r.shadowFactor).toBeGreaterThan(0.9);
-    },
-  );
-
-  it.skipIf(!dawnReady)(
-    'all clamped kernel sizes render cleanly (View UBO byte layout intact, AC-08)',
-    async () => {
-      const { canvas, getDevice } = createMockCanvas();
-      const renderer = await createRenderer(canvas, {}, { shaderManifestUrl: ENGINE_MANIFEST_URL });
-      const ready = await renderer.ready;
-      expect(ready.ok).toBe(true);
-      const device = getDevice();
-
-      // Walk every host-clamp target {1,3,5} plus an over-cap value (9 -> 5);
-      // each must drive a valid View UBO write + draw without a structured
-      // RhiError / device loss. A byte layout out of sync with the WGSL struct
-      // would fail compile/validate.
-      for (const ks of [1, 3, 5, 9]) {
-        const world = new World();
-        buildShadowScene(world, ks);
-        world.update(1 / 60).unwrap();
-        const draw = drawPublished(renderer, world);
-        expect(draw.ok, `draw failed at pcfKernelSize=${ks}`).toBe(true);
-        if (device !== undefined) await device.queue.onSubmittedWorkDone();
-      }
-    },
-  );
-});