@forgeax/engine-runtime 0.1.23 → 0.1.24

package/src/__tests__/renderer-device-loss-provider-feasibility.dawn.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+
+// These are the WebGPU COPY_SRC/COPY_DST bits; Dawn runs without a DOM constant global.
+const COPY_SRC = 0x0004;
+const COPY_DST = 0x0008;
+
+type LossObservation = {
+  readonly status: 'lost' | 'insufficient-evidence';
+  readonly reason?: string;
+  readonly message?: string;
+};
+
+type FeasibilityEvidence = {
+  readonly status: 'available' | 'insufficient-evidence';
+  readonly owner: string;
+  readonly command: string;
+  readonly exitStatus: number;
+  readonly submittedWork: boolean;
+  readonly rawDeviceObservation: LossObservation;
+  readonly missingCapability?: string;
+  readonly providerSurface: readonly string[];
+};
+
+const observationDeadlineMs = 250;
+
+function callableProviderSurface(value: object): string[] {
+  return Object.getOwnPropertyNames(value)
+    .filter((name) => /loss|crash|reset|recover/i.test(name))
+    .filter((name) => typeof (value as Record<string, unknown>)[name] === 'function')
+    .sort();
+}
+
+async function submitObservableWork(device: GPUDevice): Promise<void> {
+  const source = device.createBuffer({
+    size: 16,
+    usage: COPY_SRC | COPY_DST,
+  });
+  const destination = device.createBuffer({
+    size: 16,
+    usage: COPY_SRC | COPY_DST,
+  });
+  device.queue.writeBuffer(source, 0, new Uint32Array([0xdecafbad, 1, 2, 3]));
+  const encoder = device.createCommandEncoder();
+  encoder.copyBufferToBuffer(source, 0, destination, 0, 16);
+  device.queue.submit([encoder.finish()]);
+  await device.queue.onSubmittedWorkDone();
+}
+
+async function observeRawLoss(device: GPUDevice): Promise<LossObservation> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<LossObservation>((resolve) => {
+    timer = setTimeout(
+      () =>
+        resolve({
+          status: 'insufficient-evidence',
+          message: `raw GPUDevice.lost remained pending for ${observationDeadlineMs}ms`,
+        }),
+      observationDeadlineMs,
+    );
+  });
+  const loss = device.lost.then((value) => ({
+    status: 'lost' as const,
+    reason: value.reason,
+    message: value.message,
+  }));
+  const observation = await Promise.race([loss, deadline]);
+  if (timer !== undefined) clearTimeout(timer);
+  return observation;
+}
+
+describe('real Dawn device-loss provider feasibility', () => {
+  it('submits real work and reports an auditable provider boundary', async () => {
+    const command =
+      'pnpm exec vitest run --project dawn packages/runtime/src/__tests__/renderer-device-loss-provider-feasibility.dawn.test.ts';
+    const gpu = globalThis.navigator?.gpu;
+    expect(typeof gpu?.requestAdapter).toBe('function');
+    if (typeof gpu?.requestAdapter !== 'function') return;
+
+    const adapter = await gpu.requestAdapter();
+    expect(adapter).not.toBeNull();
+    if (adapter === null) return;
+
+    const device = await adapter.requestDevice();
+    let submittedWork = false;
+    await submitObservableWork(device);
+    submittedWork = true;
+    const rawDeviceObservation = await observeRawLoss(device);
+    const providerSurface = [
+      ...callableProviderSurface(gpu),
+      ...callableProviderSurface(adapter),
+      ...callableProviderSurface(device),
+    ];
+    const evidence: FeasibilityEvidence =
+      rawDeviceObservation.status === 'lost' && rawDeviceObservation.reason !== 'destroyed'
+        ? {
+            status: 'available',
+            owner: 'raw Dawn GPUDevice provider before packages/rhi-webgpu/src/device.ts',
+            command,
+            exitStatus: 0,
+            submittedWork,
+            rawDeviceObservation,
+            providerSurface,
+          }
+        : {
+            status: 'insufficient-evidence',
+            owner: 'raw Dawn GPUDevice provider before packages/rhi-webgpu/src/device.ts',
+            command,
+            exitStatus: 0,
+            submittedWork,
+            rawDeviceObservation,
+            missingCapability:
+              'No test-visible non-destroyed loss injection method is exposed by the real Dawn GPU, adapter, or device objects',
+            providerSurface,
+          };
+    console.log(`[dawn-loss-feasibility] ${JSON.stringify(evidence)}`);
+    expect(evidence.submittedWork).toBe(true);
+    expect(['available', 'insufficient-evidence']).toContain(evidence.status);
+    if (evidence.status === 'available') {
+      expect(evidence.rawDeviceObservation.reason).not.toBe('destroyed');
+    } else {
+      expect(evidence.missingCapability).toBeTruthy();
+    }
+  });
+});

package/src/__tests__/renderer-device-loss-recovery.dawn.test.ts

@@ -0,0 +1,50 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import {
+  insufficientDawnRecoveryEvidence,
+  observeRealLoss,
+  submitRealFrame,
+  testOnlyLossProvider,
+} from './helpers/renderer-device-loss-dawn';
+
+type RecoveryEvidence = ReturnType<typeof insufficientDawnRecoveryEvidence>;
+
+describe('real Dawn renderer device-loss recovery', () => {
+  it('keeps the dual-world recovery contract honest when provider evidence is absent', async () => {
+    const gpu = globalThis.navigator?.gpu;
+    expect(typeof gpu?.requestAdapter).toBe('function');
+    if (typeof gpu?.requestAdapter !== 'function') return;
+    const adapter = await gpu.requestAdapter();
+    expect(adapter).not.toBeNull();
+    if (adapter === null) return;
+    const device = await adapter.requestDevice();
+    const firstWorld = new World();
+    const secondWorld = new World();
+    await submitRealFrame(device);
+    const provider = testOnlyLossProvider();
+    const rawLoss =
+      provider === undefined
+        ? undefined
+        : await (async () => {
+            await provider.injectNonDestroyedLoss?.(device);
+            return observeRealLoss(device);
+          })();
+    let evidence: RecoveryEvidence = insufficientDawnRecoveryEvidence([
+      firstWorld.identity,
+      secondWorld.identity,
+    ]);
+    if (provider !== undefined && rawLoss?.reason === 'unknown') {
+      evidence = insufficientDawnRecoveryEvidence(
+        [firstWorld.identity, secondWorld.identity],
+        'A non-destroyed raw loss was observed, but this fixture does not exercise public Renderer recovery',
+      );
+    }
+    console.log(
+      `[dawn-loss-recovery] ${JSON.stringify({ ...evidence, rawLoss: rawLoss ?? 'provider-missing' })}`,
+    );
+    expect(evidence.submittedWork).toBe(true);
+    expect(evidence.worlds).toHaveLength(2);
+    expect(evidence.status).toBe('insufficient-evidence');
+    expect(evidence.missingCapability).toBeTruthy();
+  });
+});

package/src/__tests__/renderer-draw-world.cases.unit.test.ts

@@ -0,0 +1,514 @@
+// @ts-nocheck — merged file: cross-source node:fs/node:path imports outside @types/node coverage in runtime tsconfig
+// Consolidated by feat-20260609-test-pool-startup-reduction-merge-tiny-test-files
+// biome-ignore-all lint/complexity/noUselessLoneBlockStatements: block-scope isolation between merged source files (consolidation paradigm)
+//
+// Source files (N=33):
+//   - packages/runtime/__tests__/create-renderer-fallback.test.ts
+//   - packages/runtime/src/__tests__/cluster-binner.test.ts
+//   - packages/runtime/src/__tests__/create-renderer-fallback-shader-manifest.test.ts
+//   - packages/runtime/src/__tests__/create-renderer-uniform-fallback.test.ts
+//   - packages/runtime/src/__tests__/createRenderer.test.ts
+//   - packages/runtime/src/__tests__/dispatch-sort.test.ts
+//   - packages/runtime/src/__tests__/engine-metrics.test.ts
+//   - packages/runtime/src/__tests__/device/gpu-residency-caps-guard.test.ts
+//   - packages/runtime/src/__tests__/pass-selector.test.ts
+//   - packages/runtime/src/__tests__/pipeline-builder.test.ts
+//   - packages/runtime/src/__tests__/pipeline-cache-key-topology.test.ts
+//   - packages/runtime/src/__tests__/pipeline-rename-grep-gate.test.ts
+//   - packages/runtime/src/__tests__/pipeline-vertex-stride-branch.test.ts
+//   - packages/runtime/src/__tests__/post-process-register.test.ts
+//   - packages/runtime/src/__tests__/record-all-topology.test.ts
+//   - packages/runtime/src/__tests__/record-draw-branch.test.ts
+//   - packages/runtime/src/__tests__/record-strip-index-format.test.ts
+//   - packages/runtime/src/__tests__/render-query-regression.test.ts
+//   - packages/runtime/src/__tests__/renderer-draw-world.test.ts
+//   - packages/runtime/src/__tests__/renderer-input-snapshot.test.ts
+//   - packages/runtime/src/__tests__/renderer-read-pixels.test.ts
+//   - packages/runtime/src/__tests__/renderer-ready.test.ts
+//   - packages/runtime/src/__tests__/renderstate-pipeline-cache.test.ts
+//   - packages/runtime/src/__tests__/storage-buffer-caps.test.ts
+//   - packages/runtime/src/__tests__/device/gpu-residency.test.ts
+//   - packages/runtime/src/__tests__/render-data.test.ts
+//   - packages/runtime/src/__tests__/hdrp-bgl-slots.test.ts
+//   - packages/runtime/src/__tests__/hdrp-caps-gate.test.ts
+//   - packages/runtime/src/__tests__/hdrp-grid-invalid.test.ts
+//   - packages/runtime/src/__tests__/hdrp-index-list-overflow-once.test.ts
+//   - packages/runtime/src/__tests__/hdrp-light-budget.test.ts
+//   - packages/runtime/src/__tests__/hdrp-pipeline-asset-config.test.ts
+//   - packages/runtime/src/__tests__/m7-hdrp-demo-shape.test.ts
+//
+// Paradigm: each block-scope wraps a source file. ancestorTitles[0] is the
+// source-preserved inner describe (NOT the source filename for these 3 files
+// — recovery path: vitest report ancestorTitles -> grep this file -> upstream
+// `// ─── from <name>.test.ts ───` block separator -> source filename).
+// Top-level imports merged + deduped.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HANDLE_CUBE, HANDLE_TRIANGLE, resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import type { World as WorldType } from '@forgeax/engine-ecs';
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import {
+  buildMeshAttributeMapForUvSets,
+  createBoxGeometry,
+  createConeGeometry,
+  createCylinderGeometry,
+  createPlaneGeometry,
+  createSphereGeometry,
+  createTorusGeometry,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+} from '@forgeax/engine-geometry';
+import { type Mat4, mat4, type Vec3, vec3 } from '@forgeax/engine-math';
+import type { Renderer as RendererType } from '@forgeax/engine-render';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import {
+  err,
+  ok,
+  type PipelineLayout,
+  type RenderPipeline,
+  type Result,
+  type RhiCaps,
+  type RhiDevice,
+  RhiError,
+  ok as rhiOk,
+  type ShaderModule,
+} from '@forgeax/engine-rhi';
+import {
+  acquireCanvasContext as acquireNullCanvasContext,
+  createShaderModule as createNullShaderModule,
+  RhiNullAdapter,
+} from '@forgeax/engine-rhi-null';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import {
+  findVariantByKey,
+  type MaterialShaderEntry,
+  type MaterialShaderManifestEntry,
+  type MaterialShaderManifestVariant,
+} from '@forgeax/engine-shader';
+import {
+  type AssetError,
+  type EquirectAsset,
+  type Handle,
+  type MaterialRenderState,
+  type MeshAsset,
+  type PassSelector,
+  type PrimitiveTopology,
+  type RenderPipelineAsset,
+  type TextureAsset,
+  toShared,
+} from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  bin,
+  type ClusterBinError,
+  calculateSphereClusterBounds,
+  clusterSpaceObjectAabb,
+  deriveCullingRadius,
+  ndcPositionToCluster,
+  viewZToZSlice,
+} from '../../../render/src/cluster-binner';
+import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
+import { createEngineMetrics } from '../../../render/src/engine-metrics';
+import { assertStorageBufferCap } from '../../../render/src/light-buffer-layout';
+import {
+  buildPbrPipelineLayouts,
+  buildPbrViewBglEntries,
+  type PbrCaps,
+} from '../../../render/src/pbr-pipeline';
+import {
+  HdrpInstallError,
+  validateClusterGrid,
+} from '../../../render/src/pipeline/standard-pipeline';
+import {
+  buildPipelineForMaterialShader,
+  type PipelineBuilderContext,
+  type PipelineBuilderShaderModuleFactory,
+} from '../../../render/src/pipeline-builder';
+import {
+  cacheKeyOf,
+  createHdrpBindGroupLayoutDescriptor,
+  type PipelineSpec,
+} from '../../../render/src/pipeline-spec';
+import {
+  deriveRenderDataCubemap,
+  deriveRenderDataMesh,
+  deriveRenderDataTexture,
+} from '../../../render/src/render-data';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+import { matchPass } from '../../../render/src/systems/pass-selector';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
+
+function makeExplicitNullRhi(spies: {
+  setIndexBuffer: ReturnType<typeof vi.fn>;
+  setVertexBuffer: ReturnType<typeof vi.fn>;
+  draw: ReturnType<typeof vi.fn>;
+  drawIndexed: ReturnType<typeof vi.fn>;
+}): unknown {
+  const adapter = new RhiNullAdapter();
+  const requestDevice = adapter.requestDevice.bind(adapter);
+  adapter.requestDevice = async () => {
+    const result = await requestDevice();
+    if (result.ok) {
+      const device = result.value;
+      const createCommandEncoder = device.createCommandEncoder.bind(device);
+      device.createCommandEncoder = (desc) => {
+        const encoderResult = createCommandEncoder(desc);
+        if (!encoderResult.ok) return encoderResult;
+        const encoder = encoderResult.value;
+        const beginRenderPass = encoder.beginRenderPass.bind(encoder);
+        encoder.beginRenderPass = (passDesc) => {
+          const pass = beginRenderPass(passDesc);
+          const draw = pass.draw.bind(pass);
+          const drawIndexed = pass.drawIndexed.bind(pass);
+          const setIndexBuffer = pass.setIndexBuffer.bind(pass);
+          const setVertexBuffer = pass.setVertexBuffer.bind(pass);
+          pass.draw = (...args) => {
+            spies.draw(...args);
+            draw(...args);
+          };
+          pass.drawIndexed = (...args) => {
+            spies.drawIndexed(...args);
+            drawIndexed(...args);
+          };
+          pass.setIndexBuffer = (...args) => {
+            spies.setIndexBuffer(...args);
+            setIndexBuffer(...args);
+          };
+          pass.setVertexBuffer = (...args) => {
+            spies.setVertexBuffer(...args);
+            setVertexBuffer(...args);
+          };
+          return pass;
+        };
+        return { ok: true, value: encoder };
+      };
+    }
+    return result;
+  };
+  return {
+    requestAdapter: async () => ({ ok: true, value: adapter }),
+    acquireCanvasContext: acquireNullCanvasContext,
+    createShaderModule: (device: unknown, desc: { code: string; label?: string }) =>
+      createNullShaderModule(device as never, desc),
+  };
+}
+
+vi.mock('@forgeax/engine-rhi-wgpu', () => {
+  return {
+    rhi: {
+      requestAdapter: async () => ({
+        ok: false,
+        error: {
+          code: 'adapter-unavailable',
+          expected: 'adapter available',
+          hint: 'default mock fail',
+        },
+      }),
+      getPreferredCanvasFormat: () => 'bgra8unorm',
+      acquireCanvasContext: () => ({
+        ok: false,
+        error: {
+          code: 'webgpu-runtime-error',
+          expected: 'context available',
+          hint: 'default mock fail',
+        },
+      }),
+    },
+    ensureReady: async () => undefined,
+  };
+});
+
+void [
+  Camera,
+  ChildOf,
+  GpuResidencyCache,
+  HANDLE_CUBE,
+  HANDLE_TRIANGLE,
+  HdrpInstallError,
+  MeshFilter,
+  MeshRenderer,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+  RhiError,
+  RhiNullAdapter,
+  Transform,
+  World,
+  acquireNullCanvasContext,
+  afterEach,
+  assertStorageBufferCap,
+  beforeEach,
+  bin,
+  buildMeshAttributeMapForUvSets,
+  buildPbrPipelineLayouts,
+  buildPbrViewBglEntries,
+  buildPipelineForMaterialShader,
+  cacheKeyOf,
+  calculateSphereClusterBounds,
+  clusterSpaceObjectAabb,
+  createBoxGeometry,
+  createConeGeometry,
+  createCylinderGeometry,
+  createEngineMetrics,
+  createHdrpBindGroupLayoutDescriptor,
+  createNullShaderModule,
+  createPlaneGeometry,
+  createSphereGeometry,
+  createTorusGeometry,
+  defineComponent,
+  deriveCullingRadius,
+  deriveRenderDataCubemap,
+  deriveRenderDataMesh,
+  deriveRenderDataTexture,
+  describe,
+  dirname,
+  err,
+  existsSync,
+  expect,
+  extractFrame,
+  fileURLToPath,
+  findVariantByKey,
+  it,
+  makeExplicitNullRhi,
+  makeMockShaderRegistry,
+  mat4,
+  matchPass,
+  ndcPositionToCluster,
+  ok,
+  prepareExtractContext,
+  readFileSync,
+  resolve,
+  resolveAssetHandle,
+  rhiOk,
+  standardMaterialShaderVariants,
+  toShared,
+  validateClusterGrid,
+  vec3,
+  vi,
+  viewZToZSlice,
+];
+type __MergedKeep =
+  | AssetError
+  | ClusterBinError
+  | EquirectAsset
+  | Handle
+  | Mat4
+  | MaterialRenderState
+  | MaterialShaderEntry
+  | MaterialShaderManifestEntry
+  | MaterialShaderManifestVariant
+  | MeshAsset
+  | PassSelector
+  | PbrCaps
+  | PipelineBuilderContext
+  | PipelineBuilderShaderModuleFactory
+  | PipelineLayout
+  | PipelineSpec
+  | PrimitiveTopology
+  | RenderPipeline
+  | RenderPipelineAsset
+  | RendererType
+  | Result
+  | RhiCaps
+  | RhiDevice
+  | ShaderModule
+  | TextureAsset
+  | Vec3
+  | WorldType;
+
+{
+  // --- from renderer-draw-world.test.ts ---
+  const _ENGINE = new URL('../../../render/src/assembly/factory.ts', import.meta.url).href;
+  const RENDERER = new URL('../../../render/src/assembly/factory.ts', import.meta.url).href;
+
+  // ─── Mock helpers ───────────────────────────────────────────────────────────
+
+  interface MockGL2Context {
+    __mockTag: 'webgl2';
+    getExtension: () => null;
+    getParameter: () => number;
+    isContextLost: () => boolean;
+  }
+
+  function makeMockGL2(): MockGL2Context {
+    return {
+      __mockTag: 'webgl2',
+      getExtension: () => null,
+      getParameter: () => 1,
+      isContextLost: () => false,
+    };
+  }
+
+  interface CanvasOptions {
+    webgl2: 'context' | 'null';
+    webgpu?: 'context' | 'null';
+  }
+
+  function _makeMockCanvas(opts: CanvasOptions): HTMLCanvasElement {
+    const canvas = {
+      width: 800,
+      height: 600,
+      getContext(kind: string): unknown {
+        if (kind === 'webgl2') {
+          return opts.webgl2 === 'context' ? makeMockGL2() : null;
+        }
+        if (kind === 'webgpu') {
+          if (opts.webgpu === 'context') {
+            return {
+              __mockTag: 'webgpu-canvas-context',
+              configure: () => undefined,
+              unconfigure: () => undefined,
+              getCurrentTexture: () => ({ createView: () => ({}) }),
+            };
+          }
+          return null;
+        }
+        return null;
+      },
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+    } as unknown as HTMLCanvasElement;
+    return canvas;
+  }
+
+  function _makeMockGPUDevice(): { device: unknown } {
+    const lost = new Promise<unknown>(() => undefined);
+    const device = {
+      __mockTag: 'gpu-device',
+      lost,
+      features: new Set(),
+      limits: {},
+      queue: {
+        submit: () => undefined,
+        writeBuffer: () => undefined,
+        // bug-20260519 AC-03 path: zero-manifest path runs through fallback
+        // texture seed (writeTexture) which the legacy 4 cases never reach.
+        writeTexture: () => undefined,
+      },
+      createShaderModule: () => ({
+        getCompilationInfo: async () => ({ messages: [] }),
+      }),
+      createBindGroupLayout: () => ({}),
+      createPipelineLayout: () => ({}),
+      createRenderPipeline: () => ({}),
+      createBindGroup: () => ({}),
+      createBuffer: () => ({
+        getMappedRange: () => new ArrayBuffer(64),
+        unmap: () => undefined,
+      }),
+      createCommandEncoder: () => ({
+        beginRenderPass: () => ({
+          setPipeline: () => undefined,
+          setVertexBuffer: () => undefined,
+          setIndexBuffer: () => undefined,
+          setBindGroup: () => undefined,
+          draw: () => undefined,
+          drawIndexed: () => undefined,
+          end: () => undefined,
+        }),
+        finish: () => ({}),
+      }),
+      createTexture: () => ({
+        createView: () => ({}),
+      }),
+      createSampler: () => ({}),
+      destroy: () => undefined,
+    };
+    return { device };
+  }
+
+  function _makeMockGPU(deviceObj: unknown): unknown {
+    return {
+      requestAdapter: async () => ({
+        requestDevice: async () => deviceObj,
+      }),
+      getPreferredCanvasFormat: () => 'bgra8unorm',
+    };
+  }
+
+  const baseNavigator = { userAgent: 'mock-engine-test' } as unknown as Navigator;
+
+  function _buildManifestDataUrl(): string {
+    // feat-20260518-pbr-direct-lighting-mvp M5 / w22.9: createRenderer's
+    // post-fallback path requires both pbr (`f_schlick(` marker) + unlit
+    // entries; seed two minimal stubs (mock device's createShaderModule does
+    // not parse WGSL).
+    const manifest = {
+      schemaVersion: '1.0.0',
+      entries: [
+        { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },
+        { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+        {
+          hash: 'tonemap0',
+          wgsl: '/* tonemap stub - struct TonemapParams { exposure: f32 }; */',
+          glsl: '',
+          bindings: '',
+        },
+      ],
+    };
+    return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+  }
+
+  beforeEach(() => {
+    vi.stubGlobal('navigator', { ...baseNavigator });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  // ─── Tests ──────────────────────────────────────────────────────────────────
+
+  describe('Renderer.draw(world) K-4 contract rewrite (D-S11)', () => {
+    it('removes the RendererDrawTarget interface from the renderer source file', async () => {
+      // Source-level grep gate: the D-S11 + K-4 rewrite removes the
+      // RendererDrawTarget interface declaration entirely (charter
+      // proposition 5 single PBR main path; no double-shader branching).
+      const fsId = 'node:fs';
+      const pathId = 'node:path';
+      const urlId = 'node:url';
+      const fs = (await import(/* @vite-ignore */ fsId)) as {
+        readFileSync: (p: string, enc: string) => string;
+      };
+      const path = (await import(/* @vite-ignore */ pathId)) as {
+        resolve: (...parts: string[]) => string;
+        dirname: (p: string) => string;
+      };
+      const url = (await import(/* @vite-ignore */ urlId)) as {
+        fileURLToPath: (u: string) => string;
+      };
+      const here = url.fileURLToPath(import.meta.url);
+      const rendererSrc = path.resolve(
+        path.dirname(here),
+        '..',
+        '..',
+        '..',
+        'render',
+        'src',
+        'assembly',
+        'webgpu-renderer.ts',
+      );
+      const text = fs.readFileSync(rendererSrc, 'utf8');
+      expect(text).not.toMatch(/interface RendererDrawTarget/);
+      expect(text).not.toMatch(/RendererDrawTarget/);
+      // Module runtime export must also be absent (already erased by tsc for
+      // type-only members; covers `export type` removal at the surface level).
+      const mod = (await import(RENDERER)) as Record<string, unknown>;
+      expect(mod.RendererDrawTarget).toBeUndefined();
+    });
+  });
+
+  // bug-20260519 AC-03: when a world *does* carry a `MeshRenderer` entity but
+  // the renderer was created without `shaderManifestUrl`, render-time access
+  // to the now-nullable `pipelineState.{unlitPipeline,standardPipeline}` must
+  // feat-20260529 D-3: materials without passes are caught at extract stage
+  // as `material-no-effective-pass` (the shared MaterialError), before
+  // reaching the record-stage pipeline-pick branch. The test's original
+  // bug-20260519 AC-03 intent — "zero-manifest renderer fires structured error
+  // not crash" — is preserved; the detection point has moved upstream.
+  // Original test expected `shader-compile-failed` from the record stage.
+  // After D-3, the material registered below has `kind:'material'` +
+  // `baseColor` but zero passes — the extract stage
+  // walks the parent chain (no parent), finds zero passes, and fires
+  // `material-no-effective-pass` with a recovery hint for adding a pass.
+}