@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/render-system-record.unit.test.ts

@@ -0,0 +1,269 @@
+// render-system-record.unit.test.ts
+// feat-20260615-pipeline-spec-ssot M6-T1-TEST.
+//
+// Reverse-evidence ("falsify the silent fallback") tests for the M6-T1
+// deletion of `selectStandardFallbackPipeline`. The pre-M6 record stage
+// silently fell back to URP `pipelineState.standardPipeline*` whenever the
+// per-MaterialShader cache returned null and HDRP was inactive. M6 removes
+// that branch: cache miss now resolves to null and the per-submesh draw is
+// skipped (mirroring the HDRP-active and skin-shader miss-skip semantics
+// that existed before). The fallback path is no longer reachable.
+//
+// What this file asserts:
+//   1. The exported `selectStandardFallbackPipeline` symbol is gone --
+//      grep gate at runtime via `import * as mod`.
+//   2. `getOrBuildPipeline` throws `PipelineSpecError` on a build failure
+//      rather than returning a silently-substituted boot-time fallback.
+//      This is the charter P3 explicit-failure invariant the M6 cleanup
+//      preserves end-to-end (no silent route remains in the chain).
+//   3. The MSAA route (sampleCount=4) takes a distinct cache slot from the
+//      non-MSAA route -- evidence that the record stage never folds the
+//      MSAA path back onto a non-MSAA boot-prewarmed pipeline (the old
+//      `selectGeometryPipeline(... 'standard', tonemapActive, msaaActive)`
+//      branch did exactly that fold via the `*PipelineMsaa` field hand-off).
+//
+// Anchors:
+//   - plan-strategy §M6 / D-2: silent fallback removal is the core invariant.
+//   - implement-decisions §M6-T1: dedicated function + 1 record-stage call
+//     site (line ~5080) go; the only remaining path through "shader cache
+//     returned null" is `smPipelineHandle === null -> continue` skip-draw.
+
+import { describe, expect, it } from 'vitest';
+import type { InstanceBufferCacheEntry } from '../../../render/src/instance-buffer-cache';
+import {
+  cacheKeyOf,
+  getOrBuildPipeline,
+  type PipelineDeviceProvider,
+  type PipelineSpec,
+  PipelineSpecError,
+} from '../../../render/src/pipeline-spec';
+import {
+  interleaveSpriteInstanceBuffer,
+  type SpriteInstancesSnapshot,
+  spriteInstancesCacheHit,
+} from '../../../render/src/record/main-pass-sprite-draws';
+
+const SPEC_BASE: PipelineSpec = {
+  shader: { id: 'forgeax::default-standard-pbr', passKind: 'forward', variantSet: undefined },
+  attachments: {
+    colorFormats: ['bgra8unorm-srgb' as unknown as GPUTextureFormat],
+    depthFormat: 'depth24plus-stencil8' as unknown as GPUTextureFormat,
+    sampleCount: 1,
+  },
+  geometry: {
+    topology: 'triangle-list',
+    vertexLayout: {
+      position: new Float32Array(0),
+    },
+  },
+  renderState: undefined,
+};
+
+const SPEC_MSAA: PipelineSpec = {
+  ...SPEC_BASE,
+  attachments: { ...SPEC_BASE.attachments, sampleCount: 4 },
+};
+
+describe('render-system-record M6-T1 silent fallback removal', () => {
+  it('selectStandardFallbackPipeline export is gone (grep gate)', async () => {
+    const mod = await import('@forgeax/engine-render');
+    expect((mod as Record<string, unknown>).selectStandardFallbackPipeline).toBeUndefined();
+  });
+
+  it('getOrBuildPipeline throws PipelineSpecError on build failure (no silent fallback)', () => {
+    const cache = new Map();
+    const deviceProvider: PipelineDeviceProvider = {
+      createRenderPipeline: () => ({
+        ok: false,
+        error: { code: 'webgpu-runtime-error', message: 'simulated build failure' },
+      }),
+    };
+    let caught: unknown;
+    try {
+      getOrBuildPipeline(SPEC_BASE, deviceProvider, cache);
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PipelineSpecError);
+    expect((caught as PipelineSpecError).code).toBe('pipeline-build-failed');
+    // Critical: no boot-time URP `standardPipeline` is substituted for the
+    // failure. Charter P3 explicit failure surfaces upward; the record
+    // stage's `if (smPipelineHandle === null) continue` then skip-draws.
+  });
+
+  it('MSAA route takes a distinct cache slot from non-MSAA (sampleCount=4)', () => {
+    const baseKey = cacheKeyOf(SPEC_BASE);
+    const msaaKey = cacheKeyOf(SPEC_MSAA);
+    expect(baseKey).not.toBe(msaaKey);
+    // The pre-M6 silent fallback could route an MSAA frame through a
+    // boot-prewarmed standard handle even when the per-shader cache missed,
+    // collapsing the MSAA spec onto the sampleCount=1 slot.
+    // M6 removes that path; identity of the cache key is the witness that
+    // sampleCount is part of the hash and never folds onto sampleCount=1.
+  });
+});
+
+// ─── feat-20260625 M3 / w9 — sprite-pass 80B interleaved single-buffer cache ──
+//
+// TDD-RED contract for the sprite-pass `SpriteInstances` upload path. The
+// plan-strategy §2 D-1 invariant:
+//
+//   The per-entity `SpriteInstances` carries mat4 transforms (16f, 64B) and
+//   per-instance UV regions (vec4, 4f, 16B). They share the same instance
+//   count and ride a SINGLE GPU buffer (one binding slot @group(3) @binding(0))
+//   with interleaved layout 80B per instance:
+//     [mat4(16f), region(4f), mat4(16f), region(4f), ...]
+//
+//   The record stage MUST:
+//     - upload `transforms.byteLength + regions.byteLength` bytes (= 80*N);
+//     - cache the GpuBuffer keyed by the entity packed u32 (cacheKey from the
+//       extract snapshot — D-9);
+//     - reuse the buffer iff (uploadedArchVersion === snapshot.archVersion
+//       AND uploadedByteLength === requestedBytes); otherwise destroy + realloc.
+//
+// Sub-assertions covered (5):
+//   (a) `interleaveSpriteInstanceBuffer(transforms, regions)` produces a
+//       Float32Array of length `N * (16 + 4) === N * 20` and total byte length
+//       `transforms.byteLength + regions.byteLength` (= 80*N).
+//   (b) Per-instance layout: byte [0..64) is the mat4, byte [64..80) is the
+//       region; second instance starts at byte 80. Probe values: distinct mat4
+//       and region per instance verify the interleave ordering.
+//   (c) Cache hit fires when both `archVersion` and `byteLength` match — the
+//       same buffer instance is reused (no `createBuffer` round).
+//   (d) Cache miss fires (byteLength change): byteLength delta marks the cache
+//       fingerprint invalid; the record stage must replace the entry.
+//   (e) Reverse-evidence: same `cacheKey` but `byteLength` changes -> cache
+//       miss (fingerprint triple is *all three* values; cacheKey alone is not
+//       sufficient).
+//
+// Anchors:
+//   - requirements AC-05 (sprite-pass 80B interleave + record-stage upload)
+//   - plan-strategy §2 D-1 (interleaved single buffer + single binding slot)
+//   - plan-strategy §2 D-9 (cacheKey still packed Entity u32)
+//   - research §Q-R-2.2 (cache fingerprint triple), §Q-R-2.4 (BGL untouched)
+
+const TRANSFORMS_PER_INSTANCE = 16;
+const REGIONS_PER_INSTANCE = 4;
+const BYTES_PER_INSTANCE = 80; // 64 (mat4) + 16 (region)
+
+function makeTransforms(count: number, seed: number): Float32Array {
+  const out = new Float32Array(count * TRANSFORMS_PER_INSTANCE);
+  for (let i = 0; i < out.length; i++) out[i] = seed + i;
+  return out;
+}
+
+function makeRegions(count: number, seed: number): Float32Array {
+  const out = new Float32Array(count * REGIONS_PER_INSTANCE);
+  for (let i = 0; i < out.length; i++) out[i] = seed + i;
+  return out;
+}
+
+// Minimal `GpuBuffer`-shaped stand-in for the cache entry — the cache test
+// only exercises fingerprint comparison; buffer-internal behaviour is OOS.
+const MOCK_BUFFER = {
+  handle: { id: 'mock' } as unknown,
+  isDestroyed: false,
+  destroy: () => ({ ok: true as const, value: undefined }),
+  // biome-ignore lint/suspicious/noExplicitAny: stand-in, full shape unused
+} as any;
+
+describe('render-system-record sprite-pass 80B interleaved upload (w9, AC-05)', () => {
+  it('(a) interleaveSpriteInstanceBuffer length === N * (16 + 4) === transforms.byteLength + regions.byteLength', () => {
+    const N = 4;
+    const transforms = makeTransforms(N, 0);
+    const regions = makeRegions(N, 1000);
+    const out = interleaveSpriteInstanceBuffer(transforms, regions);
+    expect(out).toBeInstanceOf(Float32Array);
+    expect(out.length).toBe(N * (TRANSFORMS_PER_INSTANCE + REGIONS_PER_INSTANCE));
+    expect(out.byteLength).toBe(transforms.byteLength + regions.byteLength);
+    expect(out.byteLength).toBe(N * BYTES_PER_INSTANCE);
+  });
+
+  it('(b) per-instance layout: mat4 @ [0..16), region @ [16..20); second instance @ [20..40)', () => {
+    const N = 2;
+    // Distinct probe values: instance 0 mat4=[100..115], region=[200..203];
+    //                       instance 1 mat4=[300..315], region=[400..403].
+    const transforms = new Float32Array([
+      100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 300, 301, 302,
+      303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315,
+    ]);
+    const regions = new Float32Array([200, 201, 202, 203, 400, 401, 402, 403]);
+    const out = interleaveSpriteInstanceBuffer(transforms, regions);
+    expect(out.length).toBe(N * 20);
+    // Instance 0
+    for (let i = 0; i < 16; i++) expect(out[i]).toBe(100 + i);
+    for (let i = 0; i < 4; i++) expect(out[16 + i]).toBe(200 + i);
+    // Instance 1
+    for (let i = 0; i < 16; i++) expect(out[20 + i]).toBe(300 + i);
+    for (let i = 0; i < 4; i++) expect(out[36 + i]).toBe(400 + i);
+  });
+
+  it('(c) cache hit when (archVersion, byteLength) both match (cacheKey + triple fingerprint, D-9)', () => {
+    const cache = new Map<number, InstanceBufferCacheEntry>();
+    const entityKey = 7;
+    const snap: SpriteInstancesSnapshot = {
+      transforms: makeTransforms(4, 0),
+      regions: makeRegions(4, 0),
+      instanceCount: 4,
+      cacheKey: entityKey,
+      archVersion: 1,
+    };
+    const requestedBytes = snap.transforms.byteLength + snap.regions.byteLength;
+    cache.set(entityKey, {
+      buffer: MOCK_BUFFER,
+      uploadedArchVersion: 1,
+      uploadedByteLength: requestedBytes,
+    });
+    expect(spriteInstancesCacheHit(cache.get(entityKey), snap, requestedBytes)).toBe(true);
+  });
+
+  it('(d) cache miss when archVersion bumps (archetype grew/reallocated)', () => {
+    const cache = new Map<number, InstanceBufferCacheEntry>();
+    const entityKey = 9;
+    const snap: SpriteInstancesSnapshot = {
+      transforms: makeTransforms(4, 0),
+      regions: makeRegions(4, 0),
+      instanceCount: 4,
+      cacheKey: entityKey,
+      archVersion: 2,
+    };
+    const requestedBytes = snap.transforms.byteLength + snap.regions.byteLength;
+    cache.set(entityKey, {
+      buffer: MOCK_BUFFER,
+      uploadedArchVersion: 1, // stale
+      uploadedByteLength: requestedBytes,
+    });
+    expect(spriteInstancesCacheHit(cache.get(entityKey), snap, requestedBytes)).toBe(false);
+  });
+
+  it('(e) reverse-evidence: same cacheKey but byteLength changes -> cache miss', () => {
+    const cache = new Map<number, InstanceBufferCacheEntry>();
+    const entityKey = 11;
+    // First record: 4 instances.
+    const snap4: SpriteInstancesSnapshot = {
+      transforms: makeTransforms(4, 0),
+      regions: makeRegions(4, 0),
+      instanceCount: 4,
+      cacheKey: entityKey,
+      archVersion: 1,
+    };
+    const requestedBytes4 = snap4.transforms.byteLength + snap4.regions.byteLength;
+    cache.set(entityKey, {
+      buffer: MOCK_BUFFER,
+      uploadedArchVersion: 1,
+      uploadedByteLength: requestedBytes4,
+    });
+    // Second record on the same entity: 8 instances (grew). archVersion stays
+    // at 1 to isolate the byteLength axis -- only the byte count changed.
+    const snap8: SpriteInstancesSnapshot = {
+      transforms: makeTransforms(8, 0),
+      regions: makeRegions(8, 0),
+      instanceCount: 8,
+      cacheKey: entityKey,
+      archVersion: 1,
+    };
+    const requestedBytes8 = snap8.transforms.byteLength + snap8.regions.byteLength;
+    expect(requestedBytes8).not.toBe(requestedBytes4);
+    expect(spriteInstancesCacheHit(cache.get(entityKey), snap8, requestedBytes8)).toBe(false);
+  });
+});

package/src/__tests__/render-system-skin-bg.unit.test.ts

@@ -0,0 +1,143 @@
+// feat-20260611 R2 / M8 / w29 (IS-14): record-stage skin BindGroup unit test.
+//
+// Why this file exists:
+//   M8 wires the record stage to bind a 2-binding `pbr-skin-mesh-array-bgl`
+//   (binding 0 mesh-array UBO + binding 1 palette UBO) at group(2) when
+//   the per-entry skin discriminator (`entry.source.skin !== undefined`) is
+//   set. R1 of this loop discovered the prior 1-binding `pbr-mesh-bg`
+//   build path triggered every-frame BGL-mismatch device errors against
+//   `pbr-skin-pl`, but every static gate (typecheck / unit / dawn smoke)
+//   stayed GREEN -- the regression only surfaced in browser deviceErrors.
+//   This test lifts the BGL-shape check from the device runtime to a
+//   compile-and-run unit gate so the next regression at this slot fails
+//   fast in CI rather than at frame N.
+//
+// What this test asserts:
+//   (1) `buildPbrSkinLayouts` returns a 2-entry meshArrayBgl labeled
+//       `pbr-skin-mesh-array-bgl` with bindings 0 + 1 both
+//       `hasDynamicOffset: true`. This is the BGL the record stage
+//       must use to build a BG matching `pbr-skin-pl`.
+//   (2) The skin pipeline layout `pbr-skin-pl` references the SAME
+//       skin meshArrayBgl handle at slot 2, NOT the standard PBR
+//       `pbr-mesh-array-bgl`. This pins the BG-vs-PipelineLayout
+//       contract that R1 violated.
+//   (3) Regression guard: `buildPbrPipelineLayouts` (URP) returns a
+//       1-entry meshArrayBgl labeled `pbr-mesh-array-bgl`. M8 must
+//       NOT leak the 2-entry skin BGL into the URP path.
+//
+// What this test deliberately does NOT cover:
+//   - The actual `pass.setBindGroup(2, ...)` dispatch site is exercised
+//     by `apps/hello/skin/scripts/smoke-browser.mjs` (w27 strict gate +
+//     w30 rerun); driving recordFrame from a unit fixture would mock too
+//     much of the renderer to be a useful regression net.
+//   - Palette UBO data correctness (joint world * IBM premultiply): the
+//     skin animator integration is OOS-3 of feat-20260611. This test
+//     cares only about BGL shape + buffer-binding contract.
+
+import type { BindGroupLayout, PipelineLayout, RhiError } from '@forgeax/engine-rhi';
+import { ok, type Result } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import {
+  buildPbrPipelineLayouts,
+  buildPbrSkinLayouts,
+  type PbrPipelineDevice,
+} from '../../../render/src/pbr-pipeline';
+
+interface CapturedBglDesc {
+  readonly label: string | undefined;
+  readonly entries: readonly GPUBindGroupLayoutEntry[];
+}
+
+interface CapturedPipelineLayoutDesc {
+  readonly label: string | undefined;
+  readonly bindGroupLayouts: readonly BindGroupLayout[];
+}
+
+interface MockDeviceCapture {
+  readonly bgls: CapturedBglDesc[];
+  readonly pipelineLayouts: CapturedPipelineLayoutDesc[];
+  readonly bglByHandle: Map<BindGroupLayout, CapturedBglDesc>;
+}
+
+function makeMockDevice(): { device: PbrPipelineDevice; capture: MockDeviceCapture } {
+  const bgls: CapturedBglDesc[] = [];
+  const pipelineLayouts: CapturedPipelineLayoutDesc[] = [];
+  const bglByHandle = new Map<BindGroupLayout, CapturedBglDesc>();
+  const device: PbrPipelineDevice = {
+    createBindGroupLayout(desc): Result<BindGroupLayout, RhiError> {
+      const captured: CapturedBglDesc = { label: desc.label, entries: desc.entries ?? [] };
+      bgls.push(captured);
+      // Each call returns a fresh opaque handle; using a plain object lets us
+      // reference-compare layouts later (the assertion at (2) needs handle
+      // equality between the skin meshArrayBgl and pbr-skin-pl slot 2).
+      const handle = {} as BindGroupLayout;
+      bglByHandle.set(handle, captured);
+      return ok(handle);
+    },
+    createPipelineLayout(desc): Result<PipelineLayout, RhiError> {
+      pipelineLayouts.push({ label: desc.label, bindGroupLayouts: [...desc.bindGroupLayouts] });
+      return ok({} as PipelineLayout);
+    },
+  };
+  return { device, capture: { bgls, pipelineLayouts, bglByHandle } };
+}
+
+describe('feat-20260611 R2 / M8 / w29 — record-stage skin BindGroup BGL contract', () => {
+  it('(1) buildPbrSkinLayouts returns a 2-entry meshArrayBgl labeled pbr-skin-mesh-array-bgl with bindings 0 + 1 both hasDynamicOffset:true (storage path)', () => {
+    const { device, capture } = makeMockDevice();
+    const pbr = buildPbrPipelineLayouts(device, { storageBuffer: true });
+    const skin = buildPbrSkinLayouts(device, { storageBuffer: true }, pbr);
+
+    const skinDesc = capture.bglByHandle.get(skin.meshArrayBgl);
+    expect(skinDesc).toBeDefined();
+    expect(skinDesc?.label).toBe('pbr-skin-mesh-array-bgl');
+    expect(skinDesc?.entries).toHaveLength(2);
+    expect(skinDesc?.entries[0]?.binding).toBe(0);
+    expect(skinDesc?.entries[0]?.buffer?.hasDynamicOffset).toBe(true);
+    expect(skinDesc?.entries[0]?.buffer?.type).toBe('read-only-storage');
+    expect(skinDesc?.entries[1]?.binding).toBe(1);
+    expect(skinDesc?.entries[1]?.buffer?.hasDynamicOffset).toBe(true);
+    expect(skinDesc?.entries[1]?.buffer?.type).toBe('read-only-storage');
+  });
+
+  it('(1b) uniform fallback path: buildPbrSkinLayouts BGL bindings 0 + 1 both type=uniform', () => {
+    const { device, capture } = makeMockDevice();
+    const pbr = buildPbrPipelineLayouts(device, { storageBuffer: false });
+    const skin = buildPbrSkinLayouts(device, { storageBuffer: false }, pbr);
+
+    const skinDesc = capture.bglByHandle.get(skin.meshArrayBgl);
+    expect(skinDesc?.entries[0]?.buffer?.type).toBe('uniform');
+    expect(skinDesc?.entries[1]?.buffer?.type).toBe('uniform');
+  });
+
+  it('(2) pbr-skin-pl slot 2 === skin meshArrayBgl handle (NOT the standard pbr-mesh-array-bgl) — pins the BG vs PipelineLayout contract R1 violated', () => {
+    const { device, capture } = makeMockDevice();
+    const pbr = buildPbrPipelineLayouts(device, { storageBuffer: true });
+    const skin = buildPbrSkinLayouts(device, { storageBuffer: true }, pbr);
+
+    // Find the pipeline layout descriptor labeled 'pbr-skin-pl'.
+    const skinPlDesc = capture.pipelineLayouts.find((d) => d.label === 'pbr-skin-pl');
+    expect(skinPlDesc).toBeDefined();
+    expect(skinPlDesc?.bindGroupLayouts).toHaveLength(4);
+    // Slot 2 must be the skin meshArrayBgl handle, NOT pbr.meshArrayBgl.
+    expect(skinPlDesc?.bindGroupLayouts[2]).toBe(skin.meshArrayBgl);
+    expect(skinPlDesc?.bindGroupLayouts[2]).not.toBe(pbr.meshArrayBgl);
+    // View / material / instances slots are reused from the URP bundle (factory
+    // contract: only meshArrayBgl is fresh).
+    expect(skinPlDesc?.bindGroupLayouts[0]).toBe(pbr.viewBgl);
+    expect(skinPlDesc?.bindGroupLayouts[1]).toBe(pbr.materialBgl);
+    expect(skinPlDesc?.bindGroupLayouts[3]).toBe(pbr.instancesBgl);
+  });
+
+  it('(3) regression guard: buildPbrPipelineLayouts (URP) returns 1-entry meshArrayBgl labeled pbr-mesh-array-bgl — M8 must NOT leak the 2-entry skin BGL into URP', () => {
+    const { device, capture } = makeMockDevice();
+    const pbr = buildPbrPipelineLayouts(device, { storageBuffer: true });
+
+    const urpMeshDesc = capture.bglByHandle.get(pbr.meshArrayBgl);
+    expect(urpMeshDesc).toBeDefined();
+    expect(urpMeshDesc?.label).toBe('pbr-mesh-array-bgl');
+    expect(urpMeshDesc?.entries).toHaveLength(1);
+    expect(urpMeshDesc?.entries[0]?.binding).toBe(0);
+    expect(urpMeshDesc?.entries[0]?.buffer?.hasDynamicOffset).toBe(true);
+  });
+});

package/src/__tests__/renderer-consumer.test-d.ts

@@ -0,0 +1,18 @@
+import type {
+  FrameObservationRequest,
+  FrameReceipt,
+  RenderError,
+  Renderer,
+  RenderFrameInput,
+  RenderResult,
+} from '@forgeax/engine-render';
+
+const consume = async (renderer: Renderer, request: RenderFrameInput): Promise<boolean> => {
+  const drawn: RenderResult<FrameReceipt, RenderError> = renderer.draw(request);
+  if (!drawn.ok) return false;
+  const observed = await renderer.observe(drawn.value, {
+    include: ['timings'],
+  } satisfies FrameObservationRequest);
+  return observed.ok;
+};
+void consume;

package/src/__tests__/renderer-health.unit.test.ts

@@ -0,0 +1,45 @@
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import type { HealthReason, HealthSnapshot } from '../../../render/src/lifecycle';
+import { requireRenderer } from './renderer-test-utils';
+
+function canvas(): HTMLCanvasElement {
+  return { width: 64, height: 64, getContext: () => null } as unknown as HTMLCanvasElement;
+}
+
+const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+
+describe('renderer inspection and recovery contract', () => {
+  it('keeps health vocabulary closed for inspection consumers', () => {
+    function describeReason(reason: HealthReason): string {
+      switch (reason) {
+        case 'alive':
+          return 'alive';
+        case 'device-lost':
+          return 'device-lost';
+        case 'internal-fault':
+          return 'internal-fault';
+      }
+    }
+
+    const snapshot: HealthSnapshot = { reason: 'alive', recoverable: false };
+    expect(describeReason(snapshot.reason)).toBe('alive');
+  });
+
+  it('uses inspect for the public ready state and recover for an explicit retry', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    expect(renderer.inspect().state).toBe('alive');
+    const recovery = await renderer.recover();
+    expect(recovery.ok).toBe(false);
+    if (!recovery.ok) expect(recovery.error.code).toBe('renderer-state-invalid');
+    await renderer.dispose();
+  });
+
+  it('does not expose the removed health or device getters', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    expect(renderer).not.toHaveProperty('health');
+    expect(renderer).not.toHaveProperty('device');
+    expect(renderer).not.toHaveProperty('ready');
+    renderer.dispose();
+  });
+});

package/src/__tests__/renderer-lifecycle.integration.test.ts

@@ -0,0 +1,42 @@
+import { World } from '@forgeax/engine-ecs';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { requireRenderer } from './renderer-test-utils';
+
+function canvas(): HTMLCanvasElement {
+  return { width: 32, height: 32, getContext: () => null } as unknown as HTMLCanvasElement;
+}
+
+const manifest = `data:application/json,${encodeURIComponent(
+  JSON.stringify({
+    schemaVersion: '1.0.0',
+    entries: [
+      { hash: 'pbr00000', wgsl: '/* pbr */', glsl: '', bindings: '' },
+      { hash: 'unlit000', wgsl: '/* unlit */', glsl: '', bindings: '' },
+      { hash: 'tonemap0', wgsl: '/* tonemap */', glsl: '', bindings: '' },
+    ],
+  }),
+)}`;
+
+describe('renderer lifecycle assembly', () => {
+  it('keeps dispose idempotent after attach and draw', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    const attached = renderer.attach(new World());
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    renderer.dispose();
+    renderer.dispose();
+    expect(
+      renderer.draw({
+        leases: [attached.value],
+        camera: { lease: attached.value },
+        environment: { lease: attached.value },
+      }).ok,
+    ).toBe(false);
+  });
+});

package/src/__tests__/renderer-recover.unit.test.ts

@@ -0,0 +1,55 @@
+import { World } from '@forgeax/engine-ecs';
+import type { FrameReceipt } from '@forgeax/engine-render';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { requireRenderer } from './renderer-test-utils';
+
+function canvas(): HTMLCanvasElement {
+  return { width: 64, height: 64, getContext: () => null } as unknown as HTMLCanvasElement;
+}
+
+const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+
+describe('renderer recovery and receipt contract', () => {
+  it('returns a structured not-needed result while inspection is healthy', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    expect(renderer.inspect().state).toBe('alive');
+    const result = await renderer.recover();
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('renderer-state-invalid');
+      expect(result.error.hint.length).toBeGreaterThan(0);
+    }
+    await renderer.dispose();
+  });
+
+  it('observes only a receipt from the current frame generation', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    const world = new World();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    expect(world.update().ok).toBe(true);
+    const frame = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+    const receipt: FrameReceipt = frame.value;
+    const observed = await renderer.observe(receipt, { include: ['draws', 'bindings'] });
+    expect(observed.ok).toBe(true);
+    if (observed.ok) expect(observed.value.frameId).toBe(receipt.frameId);
+    await renderer.dispose();
+  });
+
+  it('does not recover a disposed renderer or reopen a second frame path', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    renderer.dispose();
+    expect(renderer.inspect().state).toBe('disposed');
+    const result = await renderer.recover();
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('renderer-state-invalid');
+  });
+});

package/src/__tests__/renderer-result.test-d.ts

@@ -0,0 +1,36 @@
+// w23 — Renderer.draw / ready Result<void, RhiError> shape assertions.
+//
+// Charter: proposition 4 (explicit failure - Result.err over reject /
+// fan-out-only) + proposition 5 (consistent abstraction - draw / ready
+// both expose the same .ok discriminator).
+//
+// Anchors: requirements AC-13 (Renderer.draw/ready Result form);
+//          plan-strategy D-P7 break-point #4; w23 test SSOT.
+
+import type {
+  FrameReceipt,
+  RenderError,
+  Renderer,
+  RenderFrameInput,
+  RenderResult,
+  RenderWorldLease,
+} from '@forgeax/engine-render';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('M6 — Renderer.draw returns Result<FrameReceipt, RenderError>', () => {
+  it('Renderer.draw(request) return type is Result<FrameReceipt, RenderError>', () => {
+    type RetType = ReturnType<Renderer['draw']>;
+    expectTypeOf<RetType>().toEqualTypeOf<RenderResult<FrameReceipt, RenderError>>();
+  });
+});
+
+describe('M6 — Renderer.attach returns a lease and draw consumes it', () => {
+  it('Renderer.attach returns RenderWorldLease and draw consumes RenderFrameInput', () => {
+    type AttachType = Renderer['attach'];
+    type DrawArg = Parameters<Renderer['draw']>[0];
+    expectTypeOf<AttachType>().returns.toEqualTypeOf<
+      RenderResult<RenderWorldLease, import('@forgeax/engine-render').RenderError>
+    >();
+    expectTypeOf<DrawArg>().toEqualTypeOf<RenderFrameInput>();
+  });
+});