@forgeax/engine-render 0.1.29 → 0.1.31

package/src/__tests__/reflection-probe-authoring.unit.test.ts

@@ -57,15 +57,17 @@ describe('ReflectionProbe authoring and admission', () => {
   it('admits the profile boundary and rejects the first over-budget probe', () => {
     const probe = { halfExtents: [1, 1, 1] as const, priority: 0, intensity: 1, resolution: 256 };
     const bytes = estimateReflectionProbeBytes(probe.resolution);
-    expect(bytes * DEFAULT_REFLECTION_PROBE_LIMITS.maxProbes).toBeLessThanOrEqual(
-      DEFAULT_REFLECTION_PROBE_LIMITS.maxBytes,
-    );
-    expect(admitReflectionProbe(probe, { acceptedCount: 15, acceptedBytes: bytes * 15 })).toEqual({
-      ok: true,
-      acceptedBytes: bytes * 16,
-    });
-    expect(admitReflectionProbe(probe, { acceptedCount: 16, acceptedBytes: bytes * 16 }).ok).toBe(
-      false,
-    );
+    const count = Math.floor(DEFAULT_REFLECTION_PROBE_LIMITS.maxBytes / bytes);
+    expect(count).toBe(5);
+    expect(
+      admitReflectionProbe(probe, { acceptedCount: count - 1, acceptedBytes: bytes * (count - 1) }),
+    ).toEqual({ ok: true, acceptedBytes: bytes * count });
+    expect(
+      admitReflectionProbe(probe, { acceptedCount: count, acceptedBytes: bytes * count }).ok,
+    ).toBe(false);
+    expect(
+      admitReflectionProbe({ ...probe, resolution: 16 }, { acceptedCount: 16, acceptedBytes: 0 })
+        .ok,
+    ).toBe(false);
   });
 });

package/src/__tests__/reflection-probe-box.dawn.test.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+import { expect, it } from 'vitest';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_STORAGE,
+} from '../gpu-usage';
+
+it('projects only interior probe rays and preserves the sign of nearly parallel axes', async () => {
+  const source = readFileSync('packages/shader/src/ibl-sampling.wgsl', 'utf8');
+  const helper = source.slice(
+    source.indexOf('fn box_project('),
+    source.indexOf('// Split-sum probe sample.'),
+  );
+  const adapter = await navigator.gpu.requestAdapter();
+  if (!adapter) throw new Error('Dawn adapter unavailable');
+  const device = await adapter.requestDevice();
+  const errors: string[] = [];
+  device.addEventListener('uncapturederror', (event) => errors.push(event.error.message));
+  const output = device.createBuffer({
+    size: 48,
+    usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC,
+  });
+  const readback = device.createBuffer({
+    size: 48,
+    usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ,
+  });
+  try {
+    const module = device.createShaderModule({
+      code: `${helper}
+      @group(0) @binding(0) var<storage, read_write> result: array<vec4f>;
+      @compute @workgroup_size(1) fn main() {
+        result[0] = vec4f(box_project(vec3f(4,-1,3),vec3f(0,1,0),vec3f(0),vec3f(1)),0);
+        result[1] = vec4f(box_project(vec3f(4,-1,3),vec3f(0,-1,0),vec3f(0),vec3f(1)),0);
+        result[2] = vec4f(box_project(vec3f(0.5,0.25,-0.2),vec3f(-0.000001,0.6,0.8),vec3f(0),vec3f(1)),0);
+      }`,
+    });
+    const pipeline = await device.createComputePipelineAsync({
+      layout: 'auto',
+      compute: { module, entryPoint: 'main' },
+    });
+    const group = device.createBindGroup({
+      layout: pipeline.getBindGroupLayout(0),
+      entries: [{ binding: 0, resource: { buffer: output } }],
+    });
+    const encoder = device.createCommandEncoder();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, group);
+    pass.dispatchWorkgroups(1);
+    pass.end();
+    encoder.copyBufferToBuffer(output, 0, readback, 0, 48);
+    device.queue.submit([encoder.finish()]);
+    await readback.mapAsync(1);
+    const values = new Float32Array(readback.getMappedRange()).slice();
+    readback.unmap();
+    expect(Array.from(values.slice(0, 3))).toEqual([0, 1, 0]);
+    expect(Array.from(values.slice(4, 7))).toEqual([0, -1, 0]);
+    // The finite ray exits the y=1 face at t=1.25, independently of its tiny x component.
+    const intersection = [0.5 - 0.000001 * 1.25, 1, 0.8] as const;
+    const length = Math.hypot(...intersection);
+    for (const axis of [0, 1, 2] as const)
+      expect(values[8 + axis]).toBeCloseTo(intersection[axis] / length, 5);
+    expect(errors).toEqual([]);
+  } finally {
+    readback.destroy();
+    output.destroy();
+    device.destroy();
+  }
+});

package/src/__tests__/reflection-probe-filter.unit.test.ts

@@ -43,6 +43,15 @@ describe('ReflectionProbe bounded filtering and table projection', () => {
     expect(table.cpuIndexByPrimitive('0:9')).toBe(1);
   });
 
+  it('does not turn an outside ray into a direction from the box center', () => {
+    expect(boxProjectReflectionDirection([0, 1, 0], [0, 0, 0], [1, 1, 1], [4, -1, 3])).toEqual([
+      0, 1, 0,
+    ]);
+    expect(boxProjectReflectionDirection([0, -1, 0], [0, 0, 0], [1, 1, 1], [4, -1, 3])).toEqual([
+      0, -1, 0,
+    ]);
+  });
+
   it('projects a reflection direction from inside and outside the box', () => {
     expect(boxProjectReflectionDirection([1, 0, 0], [0, 0, 0], [2, 2, 2], [0, 0, 0])).toEqual([
       1, 0, 0,

package/src/__tests__/reflection-probe-orientation.dawn.test.ts

@@ -0,0 +1,294 @@
+import { readFileSync } from 'node:fs';
+import { mat4 } from '@forgeax/engine-math';
+import { expect, it } from 'vitest';
+import { buildCubeCameraFaceViews } from '../capture/cube-views';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_UNIFORM,
+  GPU_BUFFER_USAGE_VERTEX,
+} from '../gpu-usage';
+import { CAPTURE_VIEW_PROJS, CUBEMAP_FACE_VERTICES } from '../ibl/IblPipelineCache';
+
+// Independent WebGPU cube lookup coordinates, sampled away from face seams.
+function direction(face: number, x: number, y: number, size: number) {
+  const u = ((x + 0.5) * 2) / size - 1;
+  const v = ((y + 0.5) * 2) / size - 1;
+  const vector =
+    [
+      [1, -v, -u],
+      [-1, -v, u],
+      [u, 1, v],
+      [u, -1, -v],
+      [u, -v, 1],
+      [-u, -v, -1],
+    ][face] ?? [];
+  const length = Math.hypot(...vector);
+  return vector.map((value) => value / length);
+}
+
+function shader(file: string) {
+  return readFileSync(`packages/shader/src/${file}`, 'utf8').replace(
+    /^#(?:define_import_path|import).*$/gm,
+    '',
+  );
+}
+
+function half(bits: number) {
+  const exponent = (bits >>> 10) & 31;
+  const fraction = bits & 1023;
+  return (
+    (bits & 32768 ? -1 : 1) *
+    (exponent === 0 ? fraction * 2 ** -24 : (1 + fraction / 1024) * 2 ** (exponent - 15))
+  );
+}
+
+it('preserves asymmetric world directions through cube capture, PMREM and probe lookup', async () => {
+  const adapter = await navigator.gpu.requestAdapter();
+  if (adapter === null) throw new Error('Dawn adapter unavailable');
+  const device = await adapter.requestDevice();
+  const errors: string[] = [];
+  device.addEventListener('uncapturederror', (event) => errors.push(event.error.message));
+  const size = 16;
+  const cube = (format: GPUTextureFormat, usage: number) =>
+    device.createTexture({ size: [size, size, 6], format, usage });
+  const source = cube('rgba8unorm', GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING);
+  const raw = cube(
+    'rgba16float',
+    GPU_TEXTURE_USAGE_RENDER_ATTACHMENT | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+  );
+  const filtered = cube(
+    'rgba16float',
+    GPU_TEXTURE_USAGE_RENDER_ATTACHMENT | GPU_TEXTURE_USAGE_COPY_SRC,
+  );
+  const depth = device.createTexture({
+    size: [size, size],
+    format: 'depth24plus-stencil8',
+    usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  });
+  const readback = device.createBuffer({
+    size: 256 * size * 6,
+    usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ,
+  });
+  const captureUniforms = device.createBuffer({
+    size: 256 * 6,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  const faceUniforms = device.createBuffer({
+    size: 256 * 6,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  const filterUniforms = device.createBuffer({
+    size: 16,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  const vertices = device.createBuffer({
+    size: CUBEMAP_FACE_VERTICES.byteLength,
+    usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  try {
+    const shared = shader('ibl-shared.wgsl');
+    const background = device.createShaderModule({
+      code: shared + shader('ibl-probe-background.wgsl'),
+    });
+    const prefilter = device.createShaderModule({ code: shared + shader('ibl-prefilter.wgsl') });
+    const capturePipeline = await device.createRenderPipelineAsync({
+      layout: 'auto',
+      vertex: { module: background, entryPoint: 'probe_background_vs' },
+      fragment: {
+        module: background,
+        entryPoint: 'probe_background_fs',
+        targets: [{ format: 'rgba16float' }],
+      },
+      depthStencil: {
+        format: 'depth24plus-stencil8',
+        depthWriteEnabled: false,
+        depthCompare: 'less-equal',
+      },
+    });
+    const filterPipeline = await device.createRenderPipelineAsync({
+      layout: 'auto',
+      vertex: {
+        module: prefilter,
+        entryPoint: 'cubemap_vs',
+        buffers: [
+          { arrayStride: 12, attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }] },
+        ],
+      },
+      fragment: {
+        module: prefilter,
+        entryPoint: 'prefilterEnv_fs',
+        targets: [{ format: 'rgba16float' }],
+      },
+      primitive: { cullMode: 'none' },
+    });
+    const sampler = device.createSampler({
+      magFilter: 'linear',
+      minFilter: 'linear',
+      addressModeU: 'clamp-to-edge',
+      addressModeV: 'clamp-to-edge',
+    });
+    const sourceView = source.createView({ dimension: 'cube' });
+    const rawView = raw.createView({ dimension: 'cube' });
+    const filterGroup = device.createBindGroup({
+      layout: filterPipeline.getBindGroupLayout(1),
+      entries: [
+        { binding: 0, resource: rawView },
+        { binding: 1, resource: sampler },
+      ],
+    });
+    device.queue.writeBuffer(vertices, 0, CUBEMAP_FACE_VERTICES);
+    device.queue.writeBuffer(filterUniforms, 0, new Float32Array([0, size, 1, 1]));
+    const views = buildCubeCameraFaceViews({ position: [3, 5, -7], near: 0.1, far: 100 });
+    const encoder = device.createCommandEncoder();
+    for (let face = 0; face < 6; face++) {
+      const pixels = new Uint8Array(size * size * 4);
+      for (let y = 0; y < size; y++)
+        for (let x = 0; x < size; x++) {
+          const d = direction(face, x, y, size);
+          pixels.set(
+            [
+              Math.round((0.5 + 0.4 * (d[0] ?? 0)) * 255),
+              Math.round((0.5 - 0.4 * (d[1] ?? 0)) * 255),
+              Math.round((0.5 + 0.4 * (d[2] ?? 0)) * 255),
+              255,
+            ],
+            (y * size + x) * 4,
+          );
+        }
+      device.queue.writeTexture(
+        { texture: source, origin: [0, 0, face] },
+        pixels,
+        { bytesPerRow: size * 4 },
+        [size, size],
+      );
+      const pose = mat4.invert(mat4.create(), views[face]?.view ?? mat4.create());
+      device.queue.writeBuffer(
+        captureUniforms,
+        face * 256,
+        new Float32Array([
+          ...pose.slice(0, 3),
+          0,
+          ...pose.slice(4, 7),
+          0,
+          ...pose.slice(8, 11),
+          0,
+          0,
+          0,
+          0,
+          1,
+          1,
+          1,
+          1,
+          0,
+        ]),
+      );
+      device.queue.writeBuffer(faceUniforms, face * 256, CAPTURE_VIEW_PROJS[face] ?? mat4.create());
+      const group = device.createBindGroup({
+        layout: capturePipeline.getBindGroupLayout(0),
+        entries: [
+          { binding: 0, resource: sourceView },
+          { binding: 1, resource: sampler },
+          { binding: 2, resource: { buffer: captureUniforms, offset: face * 256, size: 80 } },
+        ],
+      });
+      const pass = encoder.beginRenderPass({
+        colorAttachments: [
+          {
+            view: raw.createView({ dimension: '2d', baseArrayLayer: face, arrayLayerCount: 1 }),
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: [0, 0, 0, 1],
+          },
+        ],
+        depthStencilAttachment: {
+          view: depth.createView(),
+          depthClearValue: 1,
+          depthLoadOp: 'clear',
+          depthStoreOp: 'discard',
+          stencilClearValue: 0,
+          stencilLoadOp: 'clear',
+          stencilStoreOp: 'discard',
+        },
+      });
+      pass.setPipeline(capturePipeline);
+      pass.setBindGroup(0, group);
+      pass.draw(3);
+      pass.end();
+    }
+    for (let face = 0; face < 6; face++) {
+      const group = device.createBindGroup({
+        layout: filterPipeline.getBindGroupLayout(0),
+        entries: [
+          { binding: 0, resource: { buffer: faceUniforms, offset: face * 256, size: 64 } },
+          { binding: 1, resource: { buffer: filterUniforms } },
+        ],
+      });
+      const pass = encoder.beginRenderPass({
+        colorAttachments: [
+          {
+            view: filtered.createView({
+              dimension: '2d',
+              baseArrayLayer: face,
+              arrayLayerCount: 1,
+            }),
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: [0, 0, 0, 1],
+          },
+        ],
+      });
+      pass.setPipeline(filterPipeline);
+      pass.setBindGroup(0, group);
+      pass.setBindGroup(1, filterGroup);
+      pass.setVertexBuffer(0, vertices);
+      pass.draw(6, 1, face * 6);
+      pass.end();
+    }
+    encoder.copyTextureToBuffer(
+      { texture: filtered },
+      { buffer: readback, bytesPerRow: 256, rowsPerImage: size },
+      [size, size, 6],
+    );
+    device.queue.submit([encoder.finish()]);
+    await readback.mapAsync(1);
+    const data = new DataView(readback.getMappedRange());
+    let maximum = 0;
+    for (let face = 0; face < 6; face++)
+      for (let y = 2; y < size - 2; y++)
+        for (let x = 2; x < size - 2; x++) {
+          const d = direction(face, x, y, size);
+          for (let channel = 0; channel < 3; channel++)
+            maximum = Math.max(
+              maximum,
+              Math.abs(
+                half(data.getUint16((face * size + y) * 256 + x * 8 + channel * 2, true)) -
+                  (0.5 + 0.4 * (d[channel] ?? 0)),
+              ),
+            );
+        }
+    expect(errors).toEqual([]);
+    expect(maximum).toBeLessThan(0.04);
+    readback.unmap();
+  } finally {
+    for (const resource of [
+      source,
+      raw,
+      filtered,
+      depth,
+      readback,
+      captureUniforms,
+      faceUniforms,
+      filterUniforms,
+      vertices,
+    ])
+      resource.destroy();
+    device.destroy();
+  }
+});

package/src/__tests__/reflection-probe-record-owner.characterization.unit.test.ts

@@ -28,7 +28,7 @@ describe('ReflectionProbeRecordOwner characterization', () => {
     expect(ownerContractsSource).toContain('active: ProbeCubeSet | undefined;');
     expect(ownerContractsSource).toContain('candidate: ProbeCubeSet;');
     expect(ownerContractsSource).toContain('spare: ProbeCubeSet | undefined;');
-    expect(ownerSource).toContain('const active = resource.active;');
+    expect(ownerSource).toContain('const active = resource.activeFact?.center.every');
     expect(ownerSource).toContain('if (active === undefined) return undefined;');
     expect(ownerSource).toContain('filteredView: active.cubeView');
   });
@@ -51,7 +51,9 @@ describe('ReflectionProbeRecordOwner characterization', () => {
 
   it('discards failed completion and preserves incremental filter state', () => {
     expect(ownerSource).toContain('fallbackRequested,');
-    expect(ownerSource).toContain('if (!fallbackRequested)');
+    expect(ownerSource).toMatch(
+      /if \(fallbackRequested\)\s+await this\.completeFallbackSubmission\(/,
+    );
     expect(ownerSource).toContain('if (pending.step === undefined) continue;');
     expect(ownerSource).toContain('if (resource.pending !== undefined) continue;');
 
@@ -70,7 +72,7 @@ describe('ReflectionProbeRecordOwner characterization', () => {
   });
 
   it('resets capture work on revision changes while retaining active generation identity', () => {
-    expect(ownerSource).toContain('if (existing.fact.revision !== fact.revision)');
+    expect(ownerSource).toContain('existing.captureFact.revision !== fact.revision');
     expect(ownerSource).toContain('activeGeneration: existing.filter.activeGeneration');
     expect(ownerSource).toContain('existing.rawFaceCursor = 0;');
     expect(ownerSource).toContain('this.resources.clear();');
@@ -98,18 +100,6 @@ describe('ReflectionProbeRecordOwner characterization', () => {
     expect(ownerSource).toContain("pending.projection.source === 'neutral'");
   });
 
-  it('does not publish an active receipt from a descriptor without readback', () => {
-    expect(ownerSource).toContain('fallbackOutput?.readback === undefined');
-    expect(ownerSource).toContain('this.fallbackReadback = Object.freeze');
-    expect(ownerSource).toContain("readbackStatus: 'complete'");
-    expect(ownerSource).not.toContain("readbackStatus: 'scheduled'");
-    expect(ownerSource).toContain('readbackHash: readback.hash');
-    expect(ownerSource).not.toContain('linearHdr: readback.linearHdr');
-    expect(ownerSource).toContain('reflectionFallbackProjectionSignature(latest.projection)');
-    expect(ownerSource).toContain('pending.frameId <= committedFrame');
-    expect(ownerSource).toContain('latestFallbackTickets');
-  });
-
   it('keeps fallback capability and recovery facts on the same owner', () => {
     expect(ownerSource).toContain('private fallbackFormatAvailable: boolean;');
     expect(ownerSource).toContain('this.refreshFallbackCapabilities(frameId);');

package/src/__tests__/reflection-probe-updates.unit.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest';
+import type { RenderSystemInternals } from '../record/render-context';
+import { createProbeFilterState } from '../reflection/filter';
+import type { ReflectionProbeFact } from '../reflection/projection';
+import { ReflectionProbeRecordOwner } from '../reflection/record-owner';
+
+// Tests exercise the existing owner without widening its production API.
+type ProbeOwnerFixture = {
+  resources: ReflectionProbeRecordOwner['resources'];
+  resourceFor: ReflectionProbeRecordOwner['resourceFor'];
+  completeSubmission: ReflectionProbeRecordOwner['completeSubmission'];
+};
+
+function fixture(intent: 'once' | 'on-change' | 'continuous') {
+  const owner = new ReflectionProbeRecordOwner({
+    device: { caps: { rgba16floatRenderable: true }, queue: { writeBuffer: () => ({ ok: true }) } },
+    deviceScope: { generation: 1 },
+  } as unknown as RenderSystemInternals) as unknown as ProbeOwnerFixture;
+  const fact: ReflectionProbeFact = {
+    worldId: 0,
+    entityKey: 1,
+    center: [0, 0, 0],
+    halfExtents: [2, 2, 2],
+    intensity: 1,
+    priority: 0,
+    resolution: 64,
+    revision: 1,
+    updateIntent: intent,
+  };
+  const resource = {
+    fact,
+    captureFact: fact,
+    diffusePayload: [0, 0, 0, 0, 0, 0, 0, 1],
+    captureSceneRevision: '1',
+    index: 0,
+    filter: {
+      ...createProbeFilterState({ probeIndex: 0, mipCount: 5, activeGeneration: 1 }),
+      cursor: 30,
+    },
+    rawFaceCursor: 6,
+    raw: { size: 64, faceViews: new Array(6) },
+    active: {},
+    candidate: {},
+    spare: undefined,
+  } as unknown as NonNullable<ReturnType<(typeof owner)['resourceFor']>>;
+  owner.resources.set('0:1', resource);
+  return { owner, fact, resource };
+}
+
+describe('ReflectionProbe real resource update ownership', () => {
+  it.each([
+    'continuous',
+    'on-change',
+  ] as const)('starts another bounded capture for %s', (intent) => {
+    const { owner, fact, resource } = fixture(intent);
+    owner.resourceFor('0:1', fact, 0, '2');
+    expect(resource.rawFaceCursor).toBe(0);
+    expect(resource.filter.cursor).toBe(0);
+    expect(resource.filter.activeGeneration).toBe(1);
+  });
+  it('keeps once probes steady across ordinary scene changes', () => {
+    const { owner, fact, resource } = fixture('once');
+    owner.resourceFor('0:1', fact, 0, '2');
+    expect(resource.rawFaceCursor).toBe(6);
+    expect(resource.filter.cursor).toBe(30);
+  });
+  it('coalesces a changing scene without starving an in-progress capture', () => {
+    const { owner, fact, resource } = fixture('on-change');
+    resource.rawFaceCursor = 3;
+    resource.filter = { ...resource.filter, cursor: 0 };
+    owner.resourceFor('0:1', { ...fact, revision: 2 }, 0, '2');
+    expect(resource.rawFaceCursor).toBe(3);
+  });
+  it('commits capture tickets even when no fallback MRT was requested', async () => {
+    const { owner, resource } = fixture('once');
+    resource.rawFaceCursor = 2;
+    const pending = { rawCaptureFace: 2, step: undefined };
+    resource.pending = pending;
+    await owner.completeSubmission(
+      true,
+      new Map(),
+      Promise.resolve(),
+      undefined,
+      false,
+      [{ resource, pending }],
+      1,
+      37,
+    );
+    expect(resource.rawFaceCursor).toBe(3);
+    expect(resource.pending).toBeUndefined();
+  });
+  it('failed submissions retry the same face', async () => {
+    const { owner, resource } = fixture('once');
+    resource.rawFaceCursor = 2;
+    const pending = { rawCaptureFace: 2, step: undefined };
+    resource.pending = pending;
+    await owner.completeSubmission(
+      false,
+      new Map(),
+      undefined,
+      undefined,
+      false,
+      [{ resource, pending }],
+      1,
+      37,
+    );
+    expect(resource.rawFaceCursor).toBe(2);
+    expect(resource.pending).toBeUndefined();
+  });
+  it('a stale completion cannot advance a replaced pending ticket', async () => {
+    const { owner, resource } = fixture('once');
+    resource.rawFaceCursor = 2;
+    const old = { rawCaptureFace: 2, step: undefined };
+    const current = { rawCaptureFace: 2, step: undefined };
+    resource.pending = current;
+    await owner.completeSubmission(
+      true,
+      new Map(),
+      undefined,
+      undefined,
+      false,
+      [{ resource, pending: old }],
+      1,
+      37,
+    );
+    expect(resource.rawFaceCursor).toBe(2);
+    expect(resource.pending).toBe(current);
+  });
+});

package/src/__tests__/render-error-code-owner.test-d.ts

@@ -36,6 +36,9 @@ const expectedCodes = [
   'observation-unavailable',
   'scene-data-unavailable',
   'taa-unavailable',
+  'dynamic-resolution-invalid-parameter',
+  'dynamic-resolution-requires-taa',
+  'dynamic-resolution-timing-unavailable',
   'shadow-invalid-config',
   'equirect-projection-failed',
   'standard-light-budget-exceeded',

package/src/__tests__/render-error-detail-ssot.test-d.ts

@@ -36,6 +36,7 @@ type ExpectedPostProcessDetails = {
   readonly 'fullscreen-input-not-found': FullscreenInputNotFoundDetail;
   readonly 'ssao-radius-non-positive': SsaoRadiusNonPositiveDetail;
   readonly 'ssao-bias-negative': SsaoBiasNegativeDetail;
+  readonly 'ssao-parameter-invalid': { readonly paramName: string; readonly value: unknown };
   readonly 'params-size-mismatch': PostProcessParamsSizeMismatchDetail;
   readonly 'params-update-size-mismatch': PostProcessParamsUpdateSizeMismatchDetail;
 };
@@ -60,7 +61,7 @@ describe('render error detail aliases derive from their code resolvers', () => {
     >();
   });
 
-  it('keeps the exact seven-code vocabulary and derives the public code view', () => {
+  it('keeps the closed parameter-validation vocabulary and derives the public code view', () => {
     expectTypeOf<PostProcessErrorCode>().toEqualTypeOf<ExpectedPostProcessCodes>();
     expectTypeOf<ExpectedPostProcessCodes>().toEqualTypeOf<PostProcessErrorCode>();
     expectTypeOf<PostProcessErrorType['code']>().toEqualTypeOf<PostProcessErrorCode>();
@@ -140,6 +141,9 @@ describe('render error detail aliases derive from their code resolvers', () => {
           expectTypeOf(error.detail.paramName).toEqualTypeOf<string>();
           expectTypeOf(error.detail.value).toEqualTypeOf<number>();
           return `${error.detail.paramName}:${error.detail.value}`;
+        case 'ssao-parameter-invalid':
+          expectTypeOf(error.detail.value).toEqualTypeOf<unknown>();
+          return error.detail.paramName;
         case 'ssao-bias-negative':
           expectTypeOf(error.detail.paramName).toEqualTypeOf<string>();
           expectTypeOf(error.detail.value).toEqualTypeOf<number>();

package/src/__tests__/render-extent.unit.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import {
+  deriveRenderExtent,
+  renderExtentSize,
+  standardExtentDomainPlan,
+} from '../pipeline/render-extent';
+
+describe('RenderExtent', () => {
+  it('keeps output and internal domains distinct at a fixed TAAU scale', () => {
+    const extent = deriveRenderExtent({
+      outputWidth: 1920,
+      outputHeight: 1080,
+      requestedScale: 0.67,
+      generation: 4,
+    });
+
+    expect(extent).toMatchObject({
+      outputWidth: 1920,
+      outputHeight: 1080,
+      internalWidth: 1256,
+      internalHeight: 704,
+      scale: 0.65625,
+      generation: 4,
+    });
+    expect(renderExtentSize(extent, 'internal')).toEqual({ width: 1256, height: 704 });
+    expect(renderExtentSize(extent, 'output')).toEqual({ width: 1920, height: 1080 });
+  });
+
+  it('keeps a non-8-aligned output domain exact while fixed TAAU aligns only its internal domain', () => {
+    const extent = deriveRenderExtent({
+      outputWidth: 200,
+      outputHeight: 150,
+      requestedScale: 0.67,
+      generation: 2,
+    });
+
+    expect(renderExtentSize(extent, 'output')).toEqual({ width: 200, height: 150 });
+    expect(renderExtentSize(extent, 'internal')).toEqual({ width: 128, height: 96 });
+    expect(extent.outputWidth).not.toBe(extent.internalWidth);
+    expect(extent.outputHeight).not.toBe(extent.internalHeight);
+  });
+
+  it('keeps tiny surfaces native and assigns persistent/history domains explicitly', () => {
+    const extent = deriveRenderExtent({
+      outputWidth: 7,
+      outputHeight: 5,
+      requestedScale: 0.5,
+      generation: 9,
+    });
+    const plan = standardExtentDomainPlan(extent, 'cpu-webgl2');
+
+    expect(extent.internalWidth).toBe(7);
+    expect(extent.internalHeight).toBe(5);
+    expect(extent.scale).toBe(1);
+    expect(plan.resources).toEqual(
+      expect.arrayContaining([
+        { name: 'scene', domain: 'internal' },
+        { name: 'taa-history', domain: 'output' },
+        { name: 'output', domain: 'output' },
+      ]),
+    );
+  });
+});