@forgeax/engine-runtime 0.1.2

package/src/__tests__/dispatch-fullscreen-pass-depth-composite.dawn.test.ts

@@ -0,0 +1,271 @@
+// dispatch-fullscreen-pass-depth-composite.dawn.test.ts -
+// feat-20260702-postprocess-camera-depth-read M3 / w8 (TDD RED).
+//
+// Spy-based dawn integration test for dispatchFullscreenPass compositeOverSwapchain
+// branch with depth reads. Registers a post-process with structured
+// `reads: [{key:'depth', sampleType:'depth'}]` and verifies the
+// createBindGroup entries include depthTexView@3 + depthSampler@4.
+//
+// RED phase: the dispatcher does NOT yet thread depth in the composite
+// branch; bindGroupCreates entries only count 2-3 (color + sampler [+ params]),
+// not the 5 expected for depth. The test is written to verify the full
+// 5-entry shape; assertions fail until w11 (impl: composite depth threading)
+// is committed.
+//
+// Pattern mirrors the existing dispatch-fullscreen-pass-composite-swapchain.dawn.test.ts
+// spy model, with additions:
+//   (a) lookupPostProcess returns entry with structured depth reads + params
+//   (b) frameState.perFrameGraph with getColorTargetTexture returning a mock depth tex
+//   (c) createTextureView returning a mock depth-only view on aspect:'depth-only'
+//   (d) createBindGroup spy asserts entry count == 5 and bindings @3/@4
+
+import type {
+  PostProcessShaderEntry,
+  RenderPipelineContext,
+} from '@forgeax/engine-render/internal';
+import { addFullscreenPass } from '@forgeax/engine-render/internal';
+import { RenderGraph } from '@forgeax/engine-render-graph';
+import { describe, expect, it } from 'vitest';
+
+interface BindGroupEntry {
+  readonly binding: number;
+  readonly resource: { readonly kind: string; readonly value: unknown };
+}
+
+interface Spy {
+  readonly bindGroupCreates: { readonly entries: readonly BindGroupEntry[] }[];
+  readonly beginRenderPassCalls: { readonly view: unknown }[];
+  readonly copyCalls: { readonly src: unknown; readonly dst: unknown }[];
+  readonly createdViewsFrom: unknown[];
+  drawCalls: number;
+}
+
+type ExecuteWithResolve = (c: unknown, r: { resolve: (n: string) => unknown }) => void;
+
+function findPassExecute(
+  graph: RenderGraph<RenderPipelineContext>,
+  passName: string,
+): ExecuteWithResolve | undefined {
+  const passes = (
+    graph as unknown as {
+      passes: {
+        list(): readonly { name: string; descriptor: { execute?: ExecuteWithResolve } }[];
+      };
+    }
+  ).passes.list();
+  return passes.find((p) => p.name === passName)?.descriptor.execute;
+}
+
+function makeSpyCtx(opts: {
+  lookup: (id: string) => PostProcessShaderEntry | undefined;
+  currentTexture: unknown;
+  storageView: unknown;
+  depthTex: unknown;
+  depthOnlyView: unknown;
+  paramsBuffer: unknown;
+}): { ctx: RenderPipelineContext; spy: Spy } {
+  const spy: Spy = {
+    bindGroupCreates: [],
+    beginRenderPassCalls: [],
+    copyCalls: [],
+    createdViewsFrom: [],
+    drawCalls: 0,
+  };
+
+  const passEncoder = {
+    setPipeline(_p: unknown): void {},
+    setBindGroup(_slot: number, _bg: unknown): void {},
+    draw(): void {
+      spy.drawCalls += 1;
+    },
+    end(): void {},
+  };
+
+  const mockGraph = {
+    getColorTargetTexture: (key: string) => (key === 'depth' ? opts.depthTex : undefined),
+  };
+
+  const ctx = {
+    runtime: {
+      lookupPostProcess: opts.lookup,
+      getPostProcessPipeline: (_id: string, _bgl: unknown, _format: string) => ({
+        __pipeline: true,
+      }),
+      getPostProcessParamsBuffer: (_id: string) => opts.paramsBuffer,
+      device: {
+        createBindGroupLayout: (_d: unknown) => ({ ok: true, value: { __bgl: true } }),
+        createSampler: (_d: unknown) => ({ ok: true, value: { __sampler: true } }),
+        createBindGroup: (desc: { readonly entries: readonly BindGroupEntry[] }) => {
+          spy.bindGroupCreates.push({ entries: desc.entries });
+          return { ok: true, value: { __bg: true } };
+        },
+        createTextureView: (tex: unknown, desc: { readonly aspect?: string }) => {
+          spy.createdViewsFrom.push({ tex, desc });
+          if (desc.aspect === 'depth-only') return { ok: true, value: opts.depthOnlyView };
+          return { ok: true, value: opts.storageView };
+        },
+        queue: {
+          writeBuffer: (_buf: unknown, _offset: number, _data: Uint8Array) => ({ ok: true }),
+        },
+      },
+      errorRegistry: { fire: (_e: unknown) => undefined },
+    },
+    pipelineState: { format: 'bgra8unorm', colorAttachmentFormat: 'bgra8unorm-srgb' },
+    currentTexture: opts.currentTexture,
+    targetW: 64,
+    targetH: 64,
+    view: { __swapchainSrgbView: true },
+    encoder: {
+      copyTextureToTexture: (src: { texture: unknown }, dst: { texture: unknown }) => {
+        spy.copyCalls.push({ src: src.texture, dst: dst.texture });
+      },
+      beginRenderPass: (desc: { colorAttachments: readonly { view: unknown }[] }) => {
+        spy.beginRenderPassCalls.push({ view: desc.colorAttachments[0]?.view });
+        return passEncoder;
+      },
+    },
+    postProcessParams: new Map<string, Uint8Array>([['test::depth-overlay', new Uint8Array(16)]]),
+    frameState: { perFrameGraph: mockGraph },
+  } as unknown as RenderPipelineContext;
+  return { ctx, spy };
+}
+
+describe('feat-20260702 M3 w8: dispatchFullscreenPass compositeOverSwapchain depth binding (RED)', () => {
+  it('composite path with depth reads binds 5 entries (depthTexView@3 + depthSampler@4)', () => {
+    const swapTex = { __swapTexture: true };
+    const scratchTex = { __scratchTex: true };
+    const scratchView = { __scratchView: true };
+    const storageView = { __nonSrgbStorageView: true };
+    const depthTex = { __depthTex: true };
+    const depthOnlyView = { __depthOnlyView: true };
+    const paramsBuffer = { __paramsUBO: true };
+
+    const entry: PostProcessShaderEntry = {
+      source: 'fn vs_main(){} fn fs_main(){}',
+      reads: [{ key: 'depth', sampleType: 'depth' }],
+      params: { byteSize: 16, defaultValue: new Uint8Array(16) },
+    };
+
+    const { ctx, spy } = makeSpyCtx({
+      lookup: (id: string) => (id === 'test::depth-overlay' ? entry : undefined),
+      currentTexture: swapTex,
+      storageView,
+      depthTex,
+      depthOnlyView,
+      paramsBuffer,
+    });
+
+    const graph = new RenderGraph<RenderPipelineContext>();
+    graph.addColorTarget('scratch', { format: 'bgra8unorm', size: { w: 64, h: 64 } });
+    addFullscreenPass(graph, 'post-effect-0', {
+      shader: 'test::depth-overlay',
+      color: 'scratch',
+      compositeOverSwapchain: true,
+    });
+
+    const execute = findPassExecute(graph, 'post-effect-0');
+    expect(execute).toBeDefined();
+    if (!execute) return;
+
+    const resolveCtx = {
+      resolve: (n: string) =>
+        n === 'scratch::tex' ? scratchTex : n === 'scratch' ? scratchView : undefined,
+    };
+    execute(ctx, resolveCtx);
+
+    // (a) copy swap-chain -> scratch still fires (color copy path unchanged).
+    expect(spy.copyCalls.length).toBe(1);
+    expect(spy.copyCalls[0]?.src).toBe(swapTex);
+    expect(spy.copyCalls[0]?.dst).toBe(scratchTex);
+
+    // (b) bind-group entries: 5 (color@0 + sampler@1 + params@2 + depthTex@3 + depthSampler@4).
+    const entries = spy.bindGroupCreates[0]?.entries;
+    expect(entries).toBeDefined();
+    if (!entries) return;
+
+    // RED: the dispatcher currently does not thread depth, so entry count is 3
+    // (no depth). After w11 impl, this assertion passes with 5.
+    expect(entries.length).toBe(5);
+
+    // Binding 0 = scene color textureView (scratchView).
+    const e0 = entries.find((e) => e.binding === 0);
+    expect(e0?.resource.kind).toBe('textureView');
+    expect(e0?.resource.value).toBe(scratchView);
+
+    // Binding 1 = sampler.
+    const e1 = entries.find((e) => e.binding === 1);
+    expect(e1?.resource.kind).toBe('sampler');
+
+    // Binding 2 = params buffer.
+    const e2 = entries.find((e) => e.binding === 2);
+    expect(e2?.resource.kind).toBe('buffer');
+
+    // Binding 3 = depth textureView (depth-only).
+    const e3 = entries.find((e) => e.binding === 3);
+    expect(e3?.resource.kind).toBe('textureView');
+    expect(e3?.resource.value).toBe(depthOnlyView);
+
+    // Binding 4 = depth sampler (non-filtering).
+    const e4 = entries.find((e) => e.binding === 4);
+    expect(e4?.resource.kind).toBe('sampler');
+
+    // draw fired.
+    expect(spy.drawCalls).toBe(1);
+  });
+
+  it('depth key not in graph -> throws fullscreen-input-not-found', () => {
+    const swapTex = { __swapTexture: true };
+    const scratchTex = { __scratchTex: true };
+    const scratchView = { __scratchView: true };
+    const paramsBuffer = { __paramsUBO: true };
+
+    const entry: PostProcessShaderEntry = {
+      source: 'fn vs_main(){} fn fs_main(){}',
+      reads: [{ key: 'depth', sampleType: 'depth' }],
+      params: { byteSize: 16, defaultValue: new Uint8Array(16) },
+    };
+
+    const { ctx, spy } = makeSpyCtx({
+      lookup: (id: string) => (id === 'test::depth-throw' ? entry : undefined),
+      currentTexture: swapTex,
+      storageView: { __storage: true },
+      // depthTex is undefined — getColorTargetTexture returns undefined.
+      depthTex: undefined as unknown as Record<string, unknown>,
+      depthOnlyView: { __dummy: true },
+      paramsBuffer,
+    });
+
+    const graph = new RenderGraph<RenderPipelineContext>();
+    graph.addColorTarget('scratch', { format: 'bgra8unorm', size: { w: 64, h: 64 } });
+    addFullscreenPass(graph, 'post-effect-0', {
+      shader: 'test::depth-throw',
+      color: 'scratch',
+      compositeOverSwapchain: true,
+    });
+
+    const execute = findPassExecute(graph, 'post-effect-0');
+    if (!execute) return;
+
+    const resolveCtx = {
+      resolve: (n: string) =>
+        n === 'scratch::tex' ? scratchTex : n === 'scratch' ? scratchView : undefined,
+    };
+
+    // RED: dispatcher currently ignores depth — no throw on missing depth key.
+    // After w11 impl, this throws fullscreen-input-not-found.
+    let caught: unknown = null;
+    try {
+      execute(ctx, resolveCtx);
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).not.toBeNull();
+    const err = caught as { code?: string; detail?: { readsKey?: string; passName?: string } };
+    expect(err.code).toBe('fullscreen-input-not-found');
+    expect(err.detail?.readsKey).toBe('depth');
+    expect(err.detail?.passName).toBe('post-effect-0');
+
+    // fail-fast: no draw before throw.
+    expect(spy.drawCalls).toBe(0);
+  });
+});

package/src/__tests__/dispatch-fullscreen-pass-params.unit.test.ts

@@ -0,0 +1,321 @@
+// dispatch-fullscreen-pass-params.unit.test.ts -
+// feat-20260621-fullscreen-post-process-per-frame-uniform-params-l M-A2 / w6 + w7.
+//
+// Spy/mock unit tests for the per-frame params UBO channel wired into
+// dispatchFullscreenPass's generic (non-FXAA) branch. No real GPU: the device,
+// queue, and per-pass resolveCtx are spied so the structural call chain is
+// validated:
+//
+//   w6 (entry.params !== undefined, the active params channel):
+//     (1) the per-frame `data` is looked up from ctx.postProcessParams by
+//         shader id and written via queue.writeBuffer(ubo, 0, data).
+//     (2) buildFullscreenPostProcessPass yields a 3-entry input BGL
+//         (texture@0 + sampler@1 + buffer@2) -- asserted through
+//         createFullscreenBindGroup's entries (binding 2 present).
+//     (3) the pipeline layout stays 2 BGLs ([emptyPostProcessBgl(group0),
+//         bgl(group1)]) -- params binding goes INTO group(1), q3=B.
+//
+//   w7 (zero-regression + fail-fast):
+//     (1) entry.params === undefined -> 2-entry BGL (no binding 2, no
+//         writeBuffer) -- the 6 existing param-less consumers degrade
+//         byte-identically (R-A7).
+//     (2) register byteSize < 16 -> PostProcessError{code:'params-size-mismatch'}.
+//     (3) register defaultValue.length !== byteSize -> same code.
+//     (4) write-path data.byteLength !== registered byteSize ->
+//         PostProcessError{code:'params-update-size-mismatch'} (detail carries
+//         byteSize / actualLength).
+
+import type { RenderPipelineContext } from '@forgeax/engine-render/internal';
+import {
+  addFullscreenPass,
+  buildBindGroupLayoutDescriptor,
+  type PipelineSpec,
+  PostProcessError,
+} from '@forgeax/engine-render/internal';
+import { RenderGraph } from '@forgeax/engine-render-graph';
+import { describe, expect, it } from 'vitest';
+
+interface BindGroupEntry {
+  readonly binding: number;
+  readonly resource: { readonly kind: string; readonly value: unknown };
+}
+
+interface WriteBufferCall {
+  readonly buffer: unknown;
+  readonly offset: number;
+  readonly data: unknown;
+}
+
+interface DispatchSpy {
+  readonly bindGroupCreates: { readonly entries: readonly BindGroupEntry[] }[];
+  readonly writeBufferCalls: WriteBufferCall[];
+  readonly setBindGroupCalls: { slot: number; bindGroup: unknown }[];
+  drawCalls: number;
+}
+
+type ExecuteWithResolve = (c: unknown, r: { resolve: (n: string) => unknown }) => void;
+
+function findPassExecute(
+  graph: RenderGraph<RenderPipelineContext>,
+  passName: string,
+): ExecuteWithResolve | undefined {
+  const passes = (
+    graph as unknown as {
+      passes: {
+        list(): readonly {
+          name: string;
+          descriptor: { execute?: ExecuteWithResolve };
+        }[];
+      };
+    }
+  ).passes.list();
+  return passes.find((p) => p.name === passName)?.descriptor.execute;
+}
+
+interface PostProcessEntryStub {
+  readonly source: string;
+  readonly params?: { readonly byteSize: number; readonly defaultValue: Uint8Array } | undefined;
+}
+
+function makeSpyCtx(opts: {
+  entry: PostProcessEntryStub;
+  paramsBuffer?: unknown;
+  snapshot?: ReadonlyMap<string, Uint8Array>;
+  view: unknown;
+}): { ctx: RenderPipelineContext; spy: DispatchSpy } {
+  const spy: DispatchSpy = {
+    bindGroupCreates: [],
+    writeBufferCalls: [],
+    setBindGroupCalls: [],
+    drawCalls: 0,
+  };
+
+  const passEncoder = {
+    setPipeline(_p: unknown): void {},
+    setBindGroup(slot: number, bg: unknown): void {
+      spy.setBindGroupCalls.push({ slot, bindGroup: bg });
+    },
+    draw(_v: number, _i: number, _fv: number, _fi: number): void {
+      spy.drawCalls += 1;
+    },
+    end(): void {},
+  };
+
+  const ctx = {
+    runtime: {
+      lookupPostProcess: (_id: string) => opts.entry,
+      getPostProcessPipeline: (_id: string, _bgl: unknown, _format: string) => ({
+        __pipeline: true,
+      }),
+      getPostProcessParamsBuffer: (_id: string) => opts.paramsBuffer,
+      device: {
+        createBindGroupLayout: (_d: unknown) => ({ ok: true, value: { __bgl: true } }),
+        createSampler: (_d: unknown) => ({ ok: true, value: { __sampler: true } }),
+        createBindGroup: (desc: { readonly entries: readonly BindGroupEntry[] }) => {
+          spy.bindGroupCreates.push({ entries: desc.entries });
+          return { ok: true, value: { __bg: true } };
+        },
+        queue: {
+          writeBuffer: (buffer: unknown, offset: number, data: unknown) => {
+            spy.writeBufferCalls.push({ buffer, offset, data });
+            return { ok: true, value: undefined };
+          },
+        },
+      },
+      errorRegistry: { fire: (_e: unknown) => undefined },
+    },
+    view: opts.view,
+    postProcessParams: opts.snapshot ?? new Map<string, Uint8Array>(),
+    encoder: {
+      beginRenderPass: (_desc: unknown) => passEncoder,
+    },
+  } as unknown as RenderPipelineContext;
+  return { ctx, spy };
+}
+
+const SHADER_ID = 'test::params-channel';
+
+function buildAndExecute(opts: {
+  entry: PostProcessEntryStub;
+  paramsBuffer?: unknown;
+  snapshot?: ReadonlyMap<string, Uint8Array>;
+}): { spy: DispatchSpy; threw: unknown } {
+  const inputView = { __input: true };
+  const writeView = { __write: true };
+  const { ctx, spy } = makeSpyCtx({
+    entry: opts.entry,
+    ...(opts.paramsBuffer !== undefined ? { paramsBuffer: opts.paramsBuffer } : {}),
+    ...(opts.snapshot !== undefined ? { snapshot: opts.snapshot } : {}),
+    view: { __swap: true },
+  });
+  const graph = new RenderGraph<RenderPipelineContext>();
+  graph.addColorTarget('rt', { format: 'rgba8unorm', size: { w: 64, h: 64 } });
+  addFullscreenPass(graph, 'pp', {
+    shader: SHADER_ID,
+    color: 'rt',
+    reads: ['offscreenColor'],
+  });
+  const execute = findPassExecute(graph, 'pp');
+  if (!execute) throw new Error('pass execute not found');
+  const resolveCtx = {
+    resolve: (n: string) =>
+      n === 'offscreenColor' ? inputView : n === 'rt' ? writeView : undefined,
+  };
+  let threw: unknown = null;
+  try {
+    execute(ctx, resolveCtx);
+  } catch (e) {
+    threw = e;
+  }
+  return { spy, threw };
+}
+
+describe('M-A2 w6: dispatch 3-entry BGL + per-frame writeBuffer (params channel active)', () => {
+  it('looks up data from snapshot and writes it to the per-id UBO', () => {
+    const ubo = { __ubo: true };
+    const data = Float32Array.of(2.5, 1, 0, 0); // 16 bytes
+    const snapshot = new Map<string, Uint8Array>([[SHADER_ID, new Uint8Array(data.buffer)]]);
+    const { spy, threw } = buildAndExecute({
+      entry: { source: 'fn fs(){}', params: { byteSize: 16, defaultValue: new Uint8Array(16) } },
+      paramsBuffer: ubo,
+      snapshot,
+    });
+    expect(threw).toBeNull();
+    expect(spy.writeBufferCalls.length).toBe(1);
+    expect(spy.writeBufferCalls[0]?.buffer).toBe(ubo);
+    expect(spy.writeBufferCalls[0]?.offset).toBe(0);
+  });
+
+  it('rewrites the registered default when the current world has no params', () => {
+    const ubo = { __ubo: true };
+    const defaultValue = Uint8Array.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16);
+    const { spy, threw } = buildAndExecute({
+      entry: { source: 'fn fs(){}', params: { byteSize: 16, defaultValue } },
+      paramsBuffer: ubo,
+    });
+
+    expect(threw).toBeNull();
+    expect(spy.writeBufferCalls).toEqual([{ buffer: ubo, offset: 0, data: defaultValue }]);
+  });
+
+  it('createFullscreenBindGroup includes binding 2 (the params buffer)', () => {
+    const ubo = { __ubo: true };
+    const snapshot = new Map<string, Uint8Array>([[SHADER_ID, new Uint8Array(16)]]);
+    const { spy } = buildAndExecute({
+      entry: { source: 'fn fs(){}', params: { byteSize: 16, defaultValue: new Uint8Array(16) } },
+      paramsBuffer: ubo,
+      snapshot,
+    });
+    expect(spy.bindGroupCreates.length).toBe(1);
+    const entries = spy.bindGroupCreates[0]?.entries ?? [];
+    const binding2 = entries.find((e) => e.binding === 2);
+    expect(binding2).toBeDefined();
+    expect(binding2?.resource.kind).toBe('buffer');
+    // RHI GPUBufferBinding shape: value is `{ buffer: <handle> }`, not the raw
+    // handle (dawn rejects the raw handle — see createFullscreenBindGroup).
+    expect((binding2?.resource.value as { buffer: unknown }).buffer).toBe(ubo);
+  });
+
+  it('pipeline layout stays 2 BGLs: the fullscreen-post-with-params BGL has 3 entries', () => {
+    // The params binding goes INTO group(1) (q3=B): the dispatcher composes
+    // ONE bind group at slot 1 (group(0) stays the empty post-process BGL).
+    const ubo = { __ubo: true };
+    const snapshot = new Map<string, Uint8Array>([[SHADER_ID, new Uint8Array(16)]]);
+    const { spy } = buildAndExecute({
+      entry: { source: 'fn fs(){}', params: { byteSize: 16, defaultValue: new Uint8Array(16) } },
+      paramsBuffer: ubo,
+      snapshot,
+    });
+    // Exactly one setBindGroup, at slot 1 (group(1)); no extra group is added.
+    expect(spy.setBindGroupCalls.length).toBe(1);
+    expect(spy.setBindGroupCalls[0]?.slot).toBe(1);
+
+    // BGL descriptor: 'fullscreen-post-with-params' is 3-entry.
+    const spec: PipelineSpec = {
+      shader: { id: '', passKind: 'forward', variantSet: undefined },
+      attachments: {
+        colorFormats: ['rgba16float'] as readonly GPUTextureFormat[],
+        depthFormat: undefined,
+        sampleCount: 1,
+      },
+      geometry: { topology: 'triangle-list', vertexLayout: {} },
+      renderState: undefined,
+    } as PipelineSpec;
+    const desc = buildBindGroupLayoutDescriptor(spec, { kind: 'fullscreen-post-with-params' });
+    expect(desc.entries.length).toBe(3);
+    const bufferEntry = desc.entries.find((e) => e.binding === 2);
+    expect(bufferEntry?.buffer?.type).toBe('uniform');
+  });
+});
+
+describe('M-A2 w7: param-less degrade + register / write fail-fast', () => {
+  it('(1) entry.params === undefined -> 2-entry BGL (no binding 2, no writeBuffer)', () => {
+    const { spy, threw } = buildAndExecute({
+      entry: { source: 'fn fs(){}' }, // no params -> param-less consumer
+    });
+    expect(threw).toBeNull();
+    expect(spy.writeBufferCalls.length).toBe(0);
+    expect(spy.bindGroupCreates.length).toBe(1);
+    const entries = spy.bindGroupCreates[0]?.entries ?? [];
+    expect(entries.find((e) => e.binding === 2)).toBeUndefined();
+    // 2-entry BGL descriptor unchanged.
+    const spec: PipelineSpec = {
+      shader: { id: '', passKind: 'forward', variantSet: undefined },
+      attachments: {
+        colorFormats: ['rgba16float'] as readonly GPUTextureFormat[],
+        depthFormat: undefined,
+        sampleCount: 1,
+      },
+      geometry: { topology: 'triangle-list', vertexLayout: {} },
+      renderState: undefined,
+    } as PipelineSpec;
+    const desc = buildBindGroupLayoutDescriptor(spec, { kind: 'fullscreen-post' });
+    expect(desc.entries.length).toBe(2);
+  });
+
+  it('(4) write-path data.byteLength !== byteSize -> params-update-size-mismatch', () => {
+    const ubo = { __ubo: true };
+    // Registered byteSize 16, but snapshot data is 12 bytes -> mismatch.
+    const snapshot = new Map<string, Uint8Array>([[SHADER_ID, new Uint8Array(12)]]);
+    const { spy, threw } = buildAndExecute({
+      entry: { source: 'fn fs(){}', params: { byteSize: 16, defaultValue: new Uint8Array(16) } },
+      paramsBuffer: ubo,
+      snapshot,
+    });
+    expect(threw).not.toBeNull();
+    const err = threw as { code?: string; detail?: { byteSize?: number; actualLength?: number } };
+    expect(err.code).toBe('params-update-size-mismatch');
+    expect(err.detail?.byteSize).toBe(16);
+    expect(err.detail?.actualLength).toBe(12);
+    // Fail-fast before writeBuffer.
+    expect(spy.writeBufferCalls.length).toBe(0);
+  });
+});
+
+// w7 register fail-fast (2)+(3): the register guard from M-A1 / w5
+// (render-system.ts postProcess.register) throws PostProcessError with code
+// 'params-size-mismatch' whose hint carries the min-16B guidance. This asserts
+// the error surface register relies on (.code / .hint / .detail) is intact and
+// AI-actionable. The LIVE throw path (real register() rejecting byteSize < 16
+// and defaultValue-length mismatch) is exercised against a real Renderer in
+// post-process-register-roundtrip.dawn.test.ts.
+describe('M-A2 w7: register-time byteSize fail-fast (params-size-mismatch)', () => {
+  it('(2) byteSize < 16 -> params-size-mismatch hint includes min 16B', () => {
+    const err = new PostProcessError({
+      code: 'params-size-mismatch',
+      detail: { byteSize: 8, actualLength: 8 },
+    });
+    expect(err.code).toBe('params-size-mismatch');
+    expect(err.hint).toContain('16');
+    expect(err.detail.byteSize).toBe(8);
+  });
+
+  it('(3) defaultValue.length !== byteSize -> params-size-mismatch detail carries both', () => {
+    const err = new PostProcessError({
+      code: 'params-size-mismatch',
+      detail: { byteSize: 16, actualLength: 12 },
+    });
+    expect(err.code).toBe('params-size-mismatch');
+    expect(err.detail.actualLength).toBe(12);
+  });
+});

package/src/__tests__/draw-published.ts

@@ -0,0 +1,10 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+
+/** Drive the production attach -> update -> draw contract in direct-render tests. */
+export function drawPublished(renderer: Renderer, world: World): ReturnType<Renderer['draw']> {
+  const attached = renderer.attachWorld(world);
+  if (!attached.ok) throw attached.error;
+  world.update(1 / 60).unwrap();
+  return renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+}

package/src/__tests__/environment-error-exhaustive.test-d.ts

@@ -0,0 +1,28 @@
+// feat-20260704-runtime-tier1-decomposition M2 / w13 (AC-07 c): environment
+// cluster type-level regression guard. EngineEnvironmentError predates the
+// closed-union error model: it has NO `.code` field and is never fanned out
+// through onError (it throws at construction), so the cluster has no
+// *ErrorCode code union. This guard instead pins the class's structured
+// `.detail` shape (EngineEnvironmentErrorDetail) so a future edit that drops or
+// re-types the two optional error carriers is caught at typecheck.
+//
+// See render-error-exhaustive.test-d.ts header for the shared *.test-d.ts
+// pattern rationale.
+
+import type { RhiError } from '@forgeax/engine-rhi';
+import type { EngineEnvironmentError, EngineEnvironmentErrorDetail } from '../errors/environment';
+
+function narrowEnvironmentError(err: EngineEnvironmentError): void {
+  void err.reason; // string
+  const detail: EngineEnvironmentErrorDetail = err.detail;
+  // Both carriers are optional RhiError | Error and read via property access.
+  const webgpu: RhiError | Error | undefined = detail.webgpuError;
+  const wgpu: RhiError | Error | undefined = detail.wgpuError;
+  void webgpu;
+  void wgpu;
+}
+
+export type _EnvironmentChecks = {
+  /** @internal forces tsc to type-check the EngineEnvironmentError detail shape. */
+  _narrow: typeof narrowEnvironmentError;
+};

package/src/__tests__/equirect-bc6h.integration.test.ts

@@ -0,0 +1,35 @@
+import { deriveRenderDataCubemap } from '@forgeax/engine-render/internal';
+import type { EquirectAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function makeEquirect(width: number, height: number): EquirectAsset {
+  const pixels = new Uint16Array(width * height * 4);
+  pixels.fill(0x3c00);
+  return {
+    kind: 'equirect',
+    width,
+    height,
+    format: 'rgba16float',
+    data: new Uint8Array(pixels.buffer),
+    colorSpace: 'linear',
+  };
+}
+
+describe('equirect renderable-source integration', () => {
+  it('accepts the uncompressed rgba16float source required by cubemap render passes', () => {
+    const asset = makeEquirect(64, 32);
+    const source = {
+      kind: 'texture' as const,
+      width: asset.width,
+      height: asset.height,
+      format: asset.format,
+      data: asset.data,
+      colorSpace: asset.colorSpace,
+      mipmap: false,
+    };
+
+    const result = deriveRenderDataCubemap(source);
+
+    expect(result.ok).toBe(true);
+  });
+});