@forgeax/engine-runtime 0.1.23 → 0.1.24

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

@@ -0,0 +1,740 @@
+// @ts-nocheck — merged file: indexed-access checks cascade across noUncheckedIndexedAccess for blocks originally outside src/ rootDir
+// 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=44):
+//   - packages/runtime/__tests__/antialias-from-f32.test.ts
+//   - packages/runtime/src/__tests__/bloom-gating.test.ts
+//   - packages/runtime/src/__tests__/camera-antialias.test.ts
+//   - packages/runtime/src/__tests__/camera-bloom.test.ts
+//   - packages/runtime/src/__tests__/camera-clear-schema.test.ts
+//   - packages/runtime/src/__tests__/camera-ortho.test.ts
+//   - packages/runtime/src/__tests__/fxaa-intermediate-texture.test.ts
+//   - packages/runtime/src/__tests__/fxaa-pipeline.test.ts
+//   - packages/runtime/src/__tests__/ibl-pipeline-cache.test.ts
+//   - packages/runtime/src/__tests__/ibl-runtime-probe.test.ts
+//   - packages/runtime/src/__tests__/render-system-record-warn-once.test.ts
+//   - packages/runtime/src/__tests__/shadow-skip-non-triangle.test.ts
+//   - packages/runtime/src/__tests__/skin-errors-kebab-case.test.ts
+//   - packages/runtime/src/__tests__/skybox-error.test.ts
+//   - packages/runtime/src/__tests__/skybox-shader-compile.test.ts
+//   - packages/runtime/src/__tests__/skylight-bind-group.test.ts
+//   - packages/runtime/src/__tests__/skylight-component.test.ts
+//   - packages/runtime/src/__tests__/skylight-fallback-path.test.ts
+//   - packages/runtime/src/__tests__/skylight-pipeline-layout.test.ts
+//   - packages/runtime/src/__tests__/tonemap-hdr-target.test.ts
+//   - packages/runtime/src/__tests__/tonemap-pipeline-split.test.ts
+//   - packages/runtime/src/__tests__/zero-camera-clear-fallback.test.ts
+//   - packages/runtime/src/components/__tests__/skin.test.ts
+//   - packages/runtime/src/systems/__tests__/advance-animation-player.test.ts
+//   - packages/runtime/src/systems/__tests__/graph-skybox.test.ts
+//   - packages/runtime/src/systems/__tests__/propagate-transforms.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-cap-gate.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-instances-coexist.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-palette-extract.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-pipeline-routing.test.ts
+//   - packages/runtime/src/systems/__tests__/skybox-extract.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-boundary.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-clamp.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-frame-duration-negative.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-frame-duration-zero.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-loop.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-override-probe.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-regions-mismatch.test.ts
+//   - packages/runtime/src/systems/__tests__/tonemap.test.ts
+//   - packages/runtime/src/systems/__tests__/transparent-sort-config-get.test.ts
+//   - packages/runtime/src/systems/__tests__/transparent-sort-config-set.test.ts
+//   - packages/runtime/src/systems/__tests__/transparent-sort.test.ts
+//   - packages/runtime/src/__tests__/render-system-multi-material.test.ts
+//   - packages/runtime/src/__tests__/render-system-record-submesh.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 { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AnimationPlayer } from '@forgeax/engine-animation';
+import type { AssetRuntimeErrorCode } from '@forgeax/engine-assets-runtime';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { EntityHandle, World as WorldType } from '@forgeax/engine-ecs';
+import { ENTITY_NULL_RAW, World } from '@forgeax/engine-ecs';
+import { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';
+import { mat4, vec3 } from '@forgeax/engine-math';
+import type { RenderErrorCode, Renderer as RendererType } from '@forgeax/engine-render';
+import {
+  ANTIALIAS_FXAA,
+  ANTIALIAS_NONE,
+  BLOOM_DISABLED,
+  BLOOM_ENABLED,
+  CAMERA_PROJECTION_ORTHOGRAPHIC,
+  CAMERA_PROJECTION_PERSPECTIVE,
+  Camera,
+  MeshFilter,
+  MeshRenderer,
+  SkyboxBackground,
+  Skylight,
+} from '@forgeax/engine-render';
+import type { BindGroupEntry, Buffer, Sampler, Texture, TextureView } from '@forgeax/engine-rhi';
+import { ok as rhiOk } from '@forgeax/engine-rhi';
+import { ChildOf, Name, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { TONEMAP_LUMINANCE_EPSILON } from '@forgeax/engine-shader';
+import type { SkinErrorCode } from '@forgeax/engine-skinning';
+import {
+  Skin,
+  SkinInstancesCoexistForbiddenError,
+  SkinJointCountExceededError,
+  SkinJointDespawnedError,
+  SkinJointPathUnresolvedError,
+} from '@forgeax/engine-skinning';
+import type {
+  Handle,
+  MaterialAsset,
+  MeshAsset,
+  SkeletonAsset,
+  TextureFormat,
+} from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { worldInternal } from '../../../ecs/src/world-internal';
+import {
+  SPRITE_PLAYBACK_MODE_CLAMP,
+  SPRITE_PLAYBACK_MODE_LOOP,
+  SpriteAnimation,
+  SpriteRegionOverride,
+} from '../../../render/src/components';
+import {
+  type CameraProjection,
+  cameraProjectionFromF32,
+} from '../../../render/src/components/camera';
+import {
+  assembleMaterialWithSkylightEntries,
+  createSkylightFallback,
+  mergeSkylightIntoMaterialBgl,
+} from '../../../render/src/ibl/skylight-bind-group';
+import { buildPbrPipelineLayouts, buildUnlitMaterialBgl } from '../../../render/src/pbr-pipeline';
+import { INSTANCE_STORAGE_STRIDE_FLOATS } from '../../../render/src/record/mesh-ssbo';
+import { selectSwapChainFormat } from '../../../render/src/render-system';
+import { createSkinPaletteAllocator } from '../../../render/src/systems/skin-palette-allocator';
+import type { TransparentEntry } from '../../../render/src/systems/transparent-sort-config';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
+import { drawWithOwners } from './renderer-test-utils';
+
+function componentFieldType(component: { fields: Record<string, { type: string }> }, name: string) {
+  return component.fields[name]?.type;
+}
+
+function componentFieldDefault(
+  component: { fields: Record<string, { default?: unknown }> },
+  name: string,
+) {
+  return component.fields[name]?.default;
+}
+
+function componentSchemaTypes(component: { fields: Record<string, { type: string }> }) {
+  return Object.fromEntries(
+    Object.entries(component.fields).map(([name, field]) => [name, field.type]),
+  );
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+type RendererErrorObservation = {
+  readonly code: string;
+  readonly detail?: unknown;
+  readonly hint?: string;
+};
+
+function unwrapRendererError(value: unknown): RendererErrorObservation {
+  let current = value as RendererErrorObservation;
+  while (
+    current.detail !== undefined &&
+    typeof current.detail === 'object' &&
+    current.detail !== null
+  ) {
+    const cause = (current.detail as { cause?: unknown }).cause;
+    if (
+      cause === undefined ||
+      typeof cause !== 'object' ||
+      cause === null ||
+      typeof (cause as { code?: unknown }).code !== 'string'
+    ) {
+      break;
+    }
+    current = cause as RendererErrorObservation;
+  }
+  return current;
+}
+
+function subscribeRendererErrors(
+  renderer: RendererType,
+  listener: (error: RendererErrorObservation) => void,
+): () => void {
+  return renderer.subscribe((event) => {
+    if (event.kind === 'error') listener(unwrapRendererError(event.error));
+  });
+}
+
+function drawPublished(renderer: RendererType, world: WorldType) {
+  const attached = renderer.attach(world);
+  if (!attached.ok) throw attached.error;
+  world.update().unwrap();
+  return drawWithOwners(renderer, world);
+}
+
+// feat-20260704-runtime-tier1-decomposition M2 / w12: reconstitute the
+// eliminated top-level RuntimeErrorCode aggregate union (D-3) as a test-local
+// alias so the exhaustive-switch bodies below stay byte-identical (AC-09).
+type RuntimeLayerErrorCode = RenderErrorCode | AssetRuntimeErrorCode | SkinErrorCode;
+
+import {
+  AnimationTargetId,
+  bindAnimationTargets,
+  advanceAnimationPlayer as canonicalAdvanceAnimationPlayer,
+} from '@forgeax/engine-animation';
+import { deriveAnimationTargetId } from '@forgeax/engine-animation/target-id';
+import { DeviceScope } from '../../../render/src/device/device-scope';
+import { GpuBuffer } from '../../../render/src/gpu-resource';
+import { getOrCreateIblCache, hasIblCache } from '../../../render/src/ibl/IblPipelineCache';
+import {
+  disposeInstanceBuffers,
+  type InstanceBufferCacheEntry,
+} from '../../../render/src/instance-buffer-cache';
+import { standardPipeline as urpPipeline } from '../../../render/src/pipeline/standard-pipeline';
+import { ZERO_CAMERA_CLEAR_FALLBACK } from '../../../render/src/record/frame-snapshot';
+import {
+  warnMultiLightDirectional,
+  warnMultiLightPoint,
+  warnMultiLightSpot,
+} from '../../../render/src/record/helpers';
+import type { CameraSnapshot } from '../../../render/src/render-contract';
+import {
+  type ExtractedLights,
+  extractFrame,
+  extractFrames,
+  prepareExtractContext,
+} from '../../../render/src/render-system-extract';
+import {
+  getTransparentSortConfig,
+  setTransparentSortConfig,
+  TRANSPARENT_SORT_CONFIG_KEY,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from '../../../render/src/systems/transparent-sort-config';
+import { spriteAnimationTickSystem } from '../systems/sprite-animation-tick';
+import { REC709_LUMA_WEIGHTS, tonemapReinhardLuminance } from '../systems/tonemap';
+import { transparentSortEntries } from '../systems/transparent-sort';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+void [
+  ANTIALIAS_FXAA,
+  ANTIALIAS_NONE,
+  AnimationPlayer,
+  AnimationTargetId,
+  AssetRegistry,
+  BLOOM_DISABLED,
+  BLOOM_ENABLED,
+  CAMERA_PROJECTION_ORTHOGRAPHIC,
+  CAMERA_PROJECTION_PERSPECTIVE,
+  Camera,
+  ChildOf,
+  DeviceScope,
+  ENTITY_NULL_RAW,
+  GpuBuffer,
+  INSTANCE_STORAGE_STRIDE_FLOATS,
+  MeshFilter,
+  MeshRenderer,
+  Name,
+  REC709_LUMA_WEIGHTS,
+  SPRITE_PLAYBACK_MODE_CLAMP,
+  SPRITE_PLAYBACK_MODE_LOOP,
+  Skin,
+  SkinInstancesCoexistForbiddenError,
+  SkinJointCountExceededError,
+  SkinJointDespawnedError,
+  SkinJointPathUnresolvedError,
+  SkyboxBackground,
+  Skylight,
+  SpriteAnimation,
+  SpriteAnimationInvalidError,
+  SpriteRegionOverride,
+  TONEMAP_LUMINANCE_EPSILON,
+  TRANSPARENT_SORT_CONFIG_KEY,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+  Transform,
+  World,
+  ZERO_CAMERA_CLEAR_FALLBACK,
+  afterEach,
+  assembleMaterialWithSkylightEntries,
+  beforeAll,
+  beforeEach,
+  bindAnimationTargets,
+  buildPbrPipelineLayouts,
+  buildUnlitMaterialBgl,
+  cameraProjectionFromF32,
+  canonicalAdvanceAnimationPlayer,
+  componentFieldDefault,
+  componentFieldType,
+  componentSchemaTypes,
+  createSkinPaletteAllocator,
+  createSkylightFallback,
+  deriveAnimationTargetId,
+  describe,
+  disposeInstanceBuffers,
+  drawPublished,
+  drawWithOwners,
+  expect,
+  extractFrame,
+  extractFrames,
+  fileURLToPath,
+  getOrCreateIblCache,
+  getTransparentSortConfig,
+  hasIblCache,
+  it,
+  makeMockShaderRegistry,
+  mat4,
+  mergeSkylightIntoMaterialBgl,
+  prepareExtractContext,
+  propagateTransforms,
+  readFileSync,
+  resolve,
+  rhiOk,
+  selectSwapChainFormat,
+  setTransparentSortConfig,
+  spriteAnimationTickSystem,
+  standardMaterialShaderVariants,
+  subscribeRendererErrors,
+  toShared,
+  tonemapReinhardLuminance,
+  transparentSortEntries,
+  unwrapRendererError,
+  urpPipeline,
+  vec3,
+  vi,
+  warnMultiLightDirectional,
+  warnMultiLightPoint,
+  warnMultiLightSpot,
+  worldInternal,
+];
+type __MergedKeep =
+  | AssetRuntimeErrorCode
+  | BindGroupEntry
+  | Buffer
+  | CameraProjection
+  | CameraSnapshot
+  | EntityHandle
+  | ExtractedLights
+  | Handle
+  | InstanceBufferCacheEntry
+  | MaterialAsset
+  | MeshAsset
+  | RenderErrorCode
+  | RendererErrorObservation
+  | RendererType
+  | RuntimeLayerErrorCode
+  | Sampler
+  | SkeletonAsset
+  | SkinErrorCode
+  | Texture
+  | TextureFormat
+  | TextureView
+  | TransparentEntry
+  | WorldType;
+
+{
+  // --- from render-system-record-submesh.test.ts ---
+
+  const ENGINE = '../createRenderer';
+
+  interface PassSpies {
+    setIndexBuffer: ReturnType<typeof vi.fn>;
+    setVertexBuffer: ReturnType<typeof vi.fn>;
+    draw: ReturnType<typeof vi.fn>;
+    drawIndexed: ReturnType<typeof vi.fn>;
+  }
+
+  function makeMockGL2(): unknown {
+    return {
+      __mockTag: 'webgl2',
+      getExtension: () => null,
+      getParameter: () => 1,
+      isContextLost: () => false,
+    };
+  }
+
+  function makeMockCanvas(): HTMLCanvasElement {
+    const canvas = {
+      width: 800,
+      height: 600,
+      getContext(kind: string): unknown {
+        if (kind === 'webgl2') return makeMockGL2();
+        if (kind === 'webgpu') {
+          return {
+            __mockTag: 'webgpu-canvas-context',
+            configure: () => undefined,
+            unconfigure: () => undefined,
+            getCurrentTexture: () => ({ createView: () => ({}) }),
+          };
+        }
+        return null;
+      },
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+    };
+    return canvas as Partial<HTMLCanvasElement> as HTMLCanvasElement;
+  }
+
+  function makeMockGPUDevice(spies: PassSpies): { device: unknown } {
+    const lost = new Promise<unknown>(() => undefined);
+    const device = {
+      __mockTag: 'gpu-device',
+      lost,
+      features: new Set(),
+      limits: {},
+      queue: {
+        submit: () => undefined,
+        onSubmittedWorkDone: () => Promise.resolve(undefined),
+        writeBuffer: () => undefined,
+        writeTexture: () => undefined,
+      },
+      createShaderModule: () => ({ getCompilationInfo: async () => ({ messages: [] }) }),
+      createBindGroupLayout: () => ({}),
+      createPipelineLayout: () => ({}),
+      createRenderPipeline: () => ({}),
+      createBindGroup: () => ({}),
+      createBuffer: () => ({
+        getMappedRange: () => new ArrayBuffer(64),
+        unmap: () => undefined,
+      }),
+      createCommandEncoder: () => ({
+        beginRenderPass: () => ({
+          setPipeline: () => undefined,
+          setVertexBuffer: spies.setVertexBuffer,
+          setIndexBuffer: spies.setIndexBuffer,
+          setBindGroup: () => undefined,
+          setStencilReference: () => undefined,
+          setViewport: () => undefined,
+          setScissorRect: () => undefined,
+          draw: spies.draw,
+          drawIndexed: spies.drawIndexed,
+          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: Navigator = {
+    userAgent: 'mock-engine-test',
+  } as Partial<Navigator> as Navigator;
+
+  function buildManifestDataUrl(): string {
+    const materialShaderStub = (identifier: string) => ({
+      identifier,
+      sourcePath: `${identifier}.wgsl`,
+      composedWgsl: '/* stub */',
+      paramSchema: '[]',
+      variants:
+        identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
+    });
+    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: '',
+        },
+      ],
+      materialShaders: [
+        materialShaderStub('forgeax::default-standard-pbr'),
+        materialShaderStub('forgeax::default-unlit'),
+      ],
+    };
+    return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+  }
+
+  function makePassSpies(): PassSpies {
+    return {
+      setIndexBuffer: vi.fn(),
+      setVertexBuffer: vi.fn(),
+      draw: vi.fn(),
+      drawIndexed: vi.fn(),
+    };
+  }
+
+  type RendererLike = RendererType;
+
+  async function importEngine(): Promise<{
+    createRenderer: (...args: unknown[]) => Promise<{ unwrap(): RendererLike }>;
+  }> {
+    return (await import(ENGINE)) as never;
+  }
+
+  async function importEcs(): Promise<{
+    World: new () => { spawn: (...componentDatas: unknown[]) => unknown };
+    Query: unknown;
+    addSystem: unknown;
+    Schedule: unknown;
+  }> {
+    return (await import('@forgeax/engine-ecs')) as never;
+  }
+
+  async function importComponents(): Promise<{
+    Transform: unknown;
+    MeshFilter: unknown;
+    MeshRenderer: unknown;
+    Camera: unknown;
+    DirectionalLight: unknown;
+  }> {
+    return {
+      ...(await import('@forgeax/engine-render')),
+      ...(await import('@forgeax/engine-scene')),
+    } as never;
+  }
+
+  function cameraTransform() {
+    return {
+      pos: [0, 0, 5],
+      quat: [0, 0, 0, 1],
+      scale: [1, 1, 1],
+    };
+  }
+
+  function originTransform() {
+    return {
+      pos: [0, 0, 0],
+      quat: [0, 0, 0, 1],
+      scale: [1, 1, 1],
+    };
+  }
+
+  function unlitMaterial(color: readonly [number, number, number] = [1, 0, 0]) {
+    return {
+      kind: 'material' as const,
+      passes: [
+        {
+          name: 'Forward',
+          program: { module: 'forgeax::default-unlit' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+        },
+      ],
+      values: { baseColor: color },
+    };
+  }
+
+  function _singleSubmeshTriangle(): MeshAsset {
+    return {
+      kind: 'mesh',
+      vertices: new Float32Array(3 * 12),
+      indices: new Uint16Array([0, 1, 2]),
+      attributes: {},
+      materialSlots: [{ slotName: 'Default' }],
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          materialSlot: 0,
+          topology: 'triangle-list' as const,
+        },
+      ],
+    };
+  }
+
+  function _threeSubmeshMesh(): MeshAsset {
+    return {
+      kind: 'mesh',
+      vertices: new Float32Array(9 * 12),
+      indices: new Uint16Array([0, 1, 2, 3, 4, 5, 6, 7, 8]),
+      attributes: {},
+      materialSlots: [{ slotName: 'First' }, { slotName: 'Second' }, { slotName: 'Third' }],
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          materialSlot: 0,
+          topology: 'triangle-list' as const,
+        },
+        {
+          indexOffset: 3,
+          indexCount: 3,
+          vertexCount: 3,
+          materialSlot: 1,
+          topology: 'triangle-list' as const,
+        },
+        {
+          indexOffset: 6,
+          indexCount: 3,
+          vertexCount: 3,
+          materialSlot: 2,
+          topology: 'triangle-list' as const,
+        },
+      ],
+    };
+  }
+
+  function _vertexOnlyLineListMesh(): MeshAsset {
+    return {
+      kind: 'mesh',
+      vertices: new Float32Array(2 * 12),
+      attributes: {},
+      materialSlots: [{ slotName: 'Default' }],
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 0,
+          vertexCount: 2,
+          materialSlot: 0,
+          topology: 'line-list' as const,
+        },
+      ],
+    };
+  }
+
+  function _mixedTopologyMesh(): MeshAsset {
+    return {
+      kind: 'mesh',
+      vertices: new Float32Array(5 * 12),
+      indices: new Uint16Array([0, 1, 2, 3, 4]),
+      attributes: {},
+      materialSlots: [{ slotName: 'Triangles' }, { slotName: 'Lines' }],
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          materialSlot: 0,
+          topology: 'triangle-list' as const,
+        },
+        {
+          indexOffset: 3,
+          indexCount: 2,
+          vertexCount: 2,
+          materialSlot: 1,
+          topology: 'line-list' as const,
+        },
+      ],
+    };
+  }
+
+  async function setupRenderer(spies: PassSpies): Promise<{ renderer: RendererLike }> {
+    const { device } = makeMockGPUDevice(spies);
+    vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
+    const { createRenderer } = await importEngine();
+    const renderer = (
+      await createRenderer(
+        makeMockCanvas(),
+        {},
+        {
+          shaderManifestUrl: buildManifestDataUrl(),
+        },
+      )
+    ).unwrap();
+    return { renderer };
+  }
+
+  async function _spawnScene(
+    _renderer: RendererLike,
+    meshAsset: MeshAsset,
+    materialCount: number,
+  ): Promise<unknown> {
+    const { World } = await importEcs();
+    const C = await importComponents();
+    const world = new World();
+    const meshHandle = world.allocSharedRef('MeshAsset', meshAsset) as Handle<
+      'MeshAsset',
+      'shared'
+    >;
+
+    // Mint N unlit materials (one per submesh).
+    const materialHandles: Handle<'MaterialAsset', 'shared'>[] = [];
+    const colors: Array<readonly [number, number, number]> = [
+      [1, 0, 0],
+      [0, 1, 0],
+      [0, 0, 1],
+    ];
+    for (let i = 0; i < materialCount; i++) {
+      materialHandles.push(
+        world.allocSharedRef('MaterialAsset', unlitMaterial(colors[i])) as Handle<
+          'MaterialAsset',
+          'shared'
+        >,
+      );
+    }
+
+    world.spawn(
+      {
+        component: C.Camera,
+        data: {
+          fov: Math.PI / 4,
+          aspect: 16 / 9,
+          near: 0.1,
+          far: 100,
+          projection: 0,
+          left: -1,
+          right: 1,
+          bottom: -1,
+          top: 1,
+        },
+      },
+      { component: C.Transform, data: cameraTransform() },
+    );
+    world.spawn(
+      { component: C.DirectionalLight, data: {} },
+      { component: C.Transform, data: cameraTransform() },
+    );
+    world.spawn(
+      { component: C.MeshRenderer, data: { materials: materialHandles } },
+      { component: C.MeshFilter, data: { assetHandle: meshHandle } },
+      { component: C.Transform, data: originTransform() },
+    );
+    return world;
+  }
+
+  // feat-20260612-skin-palette-per-frame-upload M1 / m1-1: the old
+  // closure-held pipeline assertion is retired with the internal state
+  // boundary. The public inspection snapshot is the supported evidence for
+  // renderer construction and capability health.
+  describe('renderer public inspection contract', () => {
+    beforeEach(() => {
+      vi.stubGlobal('navigator', baseNavigator);
+    });
+
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    it('reports an alive, available renderer through inspect()', async () => {
+      const spies = makePassSpies();
+      const { renderer } = await setupRenderer(spies);
+      const inspection = renderer.inspect();
+      expect(inspection.state).toBe('alive');
+      expect(inspection.surface).toBe('available');
+      expect(inspection.frame.deviceGeneration).toBeGreaterThanOrEqual(0);
+      expect(Array.isArray(inspection.features)).toBe(true);
+      expect(inspection.capabilities).toBeDefined();
+    });
+  });
+}