@forgeax/engine-render 0.1.4 → 0.1.6

package/src/record/__tests__/render-submission.perf.test.ts

@@ -1,141 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { describe, expect, it } from 'vitest';
-import { commandBufferPlanForFrame, createShadowSubmitModeState } from '../shadow-submit-mode';
-
-type WorkloadPass = {
-  readonly name: string;
-  readonly draws: readonly string[];
-};
-
-type SubmissionProbe = {
-  readonly events: string[];
-  readonly rawSubmitCount: number;
-  readonly rendererSubmitCount: number;
-};
-
-const publicWorkloadDescriptor: readonly WorkloadPass[] = [
-  { name: 'shadow', draws: ['shadow-caster'] },
-  { name: 'main', draws: ['forward-geometry', 'post-process'] },
-];
-
-function makeProbe(duplicateRhiSubmit: boolean): SubmissionProbe {
-  const events: string[] = [];
-  let rawSubmitCount = 0;
-  let rendererSubmitCount = 0;
-
-  const rawQueue = {
-    submit: () => {
-      rawSubmitCount += 1;
-      events.push('rhi-wrapper:raw-submit');
-      return { ok: true as const, value: undefined };
-    },
-  };
-  const queue = {
-    submit: (buffers: readonly unknown[]) => {
-      rendererSubmitCount += 1;
-      events.push(`renderer-submit:${buffers.length}`);
-      const first = rawQueue.submit();
-      if (duplicateRhiSubmit) rawQueue.submit();
-      return first;
-    },
-  };
-  for (const pass of publicWorkloadDescriptor) {
-    for (const draw of pass.draws) events.push(`draw:${pass.name}:${draw}`);
-  }
-  events.push('renderer-finish');
-  const plan = commandBufferPlanForFrame(createShadowSubmitModeState(), [], {
-    label: 'render-system-frame',
-  } as never);
-  expect(plan.ok).toBe(true);
-  if (plan.ok) {
-    for (const submission of plan.value.rawSubmissions) {
-      queue.submit(submission.commandBuffers);
-    }
-  }
-  return { events, rawSubmitCount, rendererSubmitCount };
-}
-
-function assertBoundedSubmission(probe: SubmissionProbe): void {
-  const drawEvents = probe.events.filter((event) => event.startsWith('draw:'));
-  const finishIndex = probe.events.indexOf('renderer-finish');
-  const submitIndex = probe.events.findIndex((event) => event.startsWith('renderer-submit:'));
-
-  expect(drawEvents).toEqual(
-    publicWorkloadDescriptor.flatMap((pass) =>
-      pass.draws.map((draw) => `draw:${pass.name}:${draw}`),
-    ),
-  );
-  expect(finishIndex).toBeGreaterThan(
-    probe.events.indexOf(drawEvents[drawEvents.length - 1] ?? ''),
-  );
-  expect(submitIndex).toBeGreaterThan(finishIndex);
-  expect(probe.rendererSubmitCount).toBe(1);
-  expect(probe.rawSubmitCount).toBe(1);
-}
-
-function findSubmitLines(source: string, pattern: RegExp): number[] {
-  return source.split('\n').flatMap((line, index) => (pattern.test(line) ? [index + 1] : []));
-}
-
-describe('render submission owner admission', () => {
-  it('preserves draw order and finish-before-submit at the renderer seam', () => {
-    const probe = makeProbe(false);
-    assertBoundedSubmission(probe);
-  });
-
-  it('fails the bounded assertion for the matched duplicated-RHI negative control', () => {
-    const pathological = makeProbe(true);
-    expect(() => assertBoundedSubmission(pathological)).toThrow();
-  });
-
-  it('records the renderer-versus-RHI admission result before implementation', () => {
-    const frameTargets = readFileSync(new URL('../frame-targets.ts', import.meta.url), 'utf8');
-    const shadowPass = readFileSync(new URL('../shadow-pass.ts', import.meta.url), 'utf8');
-    const rhiWgpuQueue = readFileSync(
-      new URL('../../../../rhi-wgpu/src/queue.ts', import.meta.url),
-      'utf8',
-    );
-    const rhiWebgpuDevice = readFileSync(
-      new URL('../../../../rhi-webgpu/src/device.ts', import.meta.url),
-      'utf8',
-    );
-    const rendererSubmissionSites = [
-      {
-        file: 'packages/render/src/record/frame-targets.ts',
-        lines: findSubmitLines(frameTargets, /internals\.device\.queue\.submit\s*\(/),
-      },
-      {
-        file: 'packages/render/src/record/shadow-pass.ts',
-        lines: findSubmitLines(shadowPass, /runtime\.device\.queue\.submit\s*\(/),
-      },
-    ];
-    const rhiWrapperSites = [
-      {
-        file: 'packages/rhi-wgpu/src/queue.ts',
-        lines: findSubmitLines(rhiWgpuQueue, /raw\.submit\.call\s*\(/),
-      },
-      {
-        file: 'packages/rhi-webgpu/src/device.ts',
-        lines: findSubmitLines(rhiWebgpuDevice, /rawQueue\.submit\s*\(/),
-      },
-    ];
-    const admission = {
-      status: 'inconclusive',
-      rendererSubmissionSites,
-      rhiWrapperSites,
-      matchedNegativeControl: {
-        variant: 'duplicated-rhi-wrapper-submit',
-        reproducesBoundedFailure: true,
-      },
-      reason:
-        'Renderer record code owns multiple submission boundaries, including the documented shadow depth barrier; the matched RHI control only fails when it is deliberately made to duplicate raw submit. The focused node test cannot attribute the public GPU-process pacing symptom to one renderer submission without backend evidence.',
-    } as const;
-
-    // biome-ignore lint/suspicious/noConsole: admission evidence is the task output
-    console.info(`[m6-owner-admission] ${JSON.stringify(admission)}`);
-    expect(admission.status).toBe('inconclusive');
-    expect(rendererSubmissionSites.some((site) => site.lines.length > 0)).toBe(true);
-    expect(rhiWrapperSites.every((site) => site.lines.length > 0)).toBe(true);
-    expect(admission.matchedNegativeControl.reproducesBoundedFailure).toBe(true);
-  });
-});

package/src/record/__tests__/shadow-submit-mode.unit.test.ts

@@ -1,88 +0,0 @@
-import { expect, test } from 'vitest';
-
-import {
-  SHADOW_SUBMIT_MODES,
-  type ShadowSubmitModeRequest,
-  validateShadowSubmitModeRequest,
-} from '../shadow-submit-mode';
-
-const identity = {
-  carrierId: 'studio-carrier-1',
-  pageIdentity: 'page-1',
-  browserRealmId: 'realm-1',
-  runtimeId: 'runtime-1',
-  canvasIdentity: 'canvas-1',
-  rendererGeneration: 'renderer-generation-1',
-} as const;
-
-function request(overrides: Partial<ShadowSubmitModeRequest> = {}): ShadowSubmitModeRequest {
-  return {
-    schema: 'renderer-owner-admission/v1',
-    shadowSubmitMode: 'independent',
-    identity,
-    ...overrides,
-  };
-}
-
-test('renderer mode exposes exactly the independent and coalesced values', () => {
-  expect(SHADOW_SUBMIT_MODES).toEqual(['independent', 'coalesced-with-frame']);
-  expect(validateShadowSubmitModeRequest(request()).ok).toBe(true);
-  expect(
-    validateShadowSubmitModeRequest(request({ shadowSubmitMode: 'coalesced-with-frame' })).ok,
-  ).toBe(true);
-});
-
-test('renderer mode rejects an unknown mode and preserves a structured recovery error', () => {
-  const result = validateShadowSubmitModeRequest(
-    request({ shadowSubmitMode: 'all-at-once' as never }),
-  );
-
-  expect(result).toMatchObject({
-    ok: false,
-    error: {
-      code: 'renderer-owner-admission-invalid-mode',
-      category: 'precondition',
-      expected: { shadowSubmitMode: SHADOW_SUBMIT_MODES },
-      recoveryActions: ['renderer.ownerAdmission.rediscover'],
-      safeRerun: true,
-    },
-  });
-});
-
-test('renderer mode requires every selected carrier and renderer identity field', () => {
-  for (const field of Object.keys(identity) as Array<keyof typeof identity>) {
-    const incompleteIdentity = { ...identity };
-    delete incompleteIdentity[field];
-    const result = validateShadowSubmitModeRequest(
-      request({ identity: incompleteIdentity as never }),
-    );
-
-    expect(result).toMatchObject({
-      ok: false,
-      error: {
-        code: 'renderer-owner-admission-identity-mismatch',
-        category: 'precondition',
-        expected: { identityFields: Object.keys(identity) },
-        recoveryActions: ['renderer.ownerAdmission.rediscover'],
-        safeRerun: true,
-      },
-    });
-  }
-});
-
-test('renderer mode rejects a generation drift before a frame-boundary apply', () => {
-  const result = validateShadowSubmitModeRequest(
-    request({
-      identity: { ...identity, rendererGeneration: '' },
-    }),
-  );
-
-  expect(result).toMatchObject({
-    ok: false,
-    error: {
-      code: 'renderer-owner-admission-identity-mismatch',
-      observed: { rendererGeneration: '' },
-      recoveryActions: ['renderer.ownerAdmission.rediscover'],
-    },
-  });
-});

package/src/record/__tests__/view-ubo-layout.unit.test.ts

@@ -1,101 +0,0 @@
-import { vec3 } from '@forgeax/engine-math';
-import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
-import { ok } from '@forgeax/engine-rhi';
-import { describe, expect, it } from 'vitest';
-import type {
-  CameraSnapshot,
-  DirectionalLightSnapshot,
-  ExtractedLights,
-  FogSnapshot,
-} from '../../render-system-extract';
-import { VIEW_UNIFORM_BYTES, VIEW_UNIFORM_SLOT_STRIDE, writeViewUbo } from '../view-ubo';
-
-function camera(): CameraSnapshot {
-  return {
-    worldId: 0,
-    entityKey: 0,
-    position: vec3.create(0, 1, 3),
-    world: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 1, 3, 1]),
-    fov: Math.PI / 4,
-    aspect: 1,
-    near: 0.1,
-    far: 100,
-    projection: 'perspective',
-    orthoLeft: -1,
-    orthoRight: 1,
-    orthoBottom: -1,
-    orthoTop: 1,
-    tonemap: 'none',
-    exposure: 1,
-    whitePoint: 4,
-    antialias: 'none',
-    historyVersion: 0,
-    bloom: 'off',
-    bloomThreshold: 1,
-    bloomIntensity: 1,
-    bloomBlurRadius: 4,
-    clearColor: [0, 0, 0, 1],
-  };
-}
-
-const light: DirectionalLightSnapshot = {
-  kind: 'directional',
-  direction: vec3.create(0, -1, 0),
-  color: vec3.create(1, 1, 1),
-  intensity: 1,
-};
-
-const lights = {
-  directional: light,
-  directionalCount: 1,
-  point: [],
-  spot: [],
-  lightViewProj: undefined,
-  splitPlanes: undefined,
-  cascadeCount: undefined,
-  cascadeBlend: undefined,
-  depthBias: undefined,
-  normalBias: undefined,
-  pcfKernelSize: undefined,
-  pointShadow: [],
-} as unknown as ExtractedLights;
-
-function capture(fog: FogSnapshot): Float32Array {
-  let payload: Float32Array | undefined;
-  const queue = {
-    writeBuffer: (_buffer: Buffer, _offset: number, data: ArrayBufferView | ArrayBuffer) => {
-      payload = new Float32Array((data as ArrayBufferView).buffer);
-      return ok(undefined);
-    },
-  } as unknown as RhiQueue;
-  writeViewUbo(queue, {} as Buffer, camera(), light, lights, [], undefined, fog);
-  if (payload === undefined) throw new Error('writeViewUbo did not write');
-  return payload;
-}
-
-describe('View UBO Fog payload ABI', () => {
-  it('derives a 16-byte aligned payload inside the existing View slot', () => {
-    expect(VIEW_UNIFORM_BYTES).toBeGreaterThan(928);
-    expect(VIEW_UNIFORM_BYTES % 16).toBe(0);
-    expect(VIEW_UNIFORM_BYTES).toBeLessThanOrEqual(VIEW_UNIFORM_SLOT_STRIDE);
-  });
-
-  it('packs color, density, heightFalloff, and maxOpacity after existing View facts', () => {
-    const payload = capture({
-      color: [0.2, 1.5, 3.0],
-      density: 0.035,
-      heightFalloff: 0.28,
-      maxOpacity: 0.92,
-      revision: 7,
-    });
-    expect(payload.length).toBe(VIEW_UNIFORM_BYTES / 4);
-    expect(payload[232]).toBeCloseTo(0.2, 6);
-    expect(payload[233]).toBeCloseTo(1.5, 6);
-    expect(payload[234]).toBeCloseTo(3.0, 6);
-    expect(payload[235]).toBeCloseTo(0.035, 6);
-    expect(payload[236]).toBeCloseTo(0.28, 6);
-    expect(payload[237]).toBeCloseTo(0.92, 6);
-    expect(payload[238]).toBe(0);
-    expect(payload[239]).toBe(0);
-  });
-});

package/src/record/frame-observation.ts

@@ -1,122 +0,0 @@
-import {
-  type CurrentFrameObservationLease,
-  createCurrentFrameObservationLease,
-  type ResolvedColorTargetDescriptor,
-} from '@forgeax/engine-render-graph';
-import type { Texture } from '@forgeax/engine-rhi';
-import { err, ok, type Result } from '@forgeax/engine-rhi';
-import {
-  ObservationUnavailableError,
-  type ObservationUnavailableReason,
-} from '../errors/render.js';
-
-export interface FrameObservationSource {
-  readonly texture: Texture;
-  readonly descriptor: ResolvedColorTargetDescriptor;
-  readonly frameId: number;
-  readonly pipelineId: 'forgeax::urp' | 'forgeax::hdrp';
-  readonly backendId: string;
-}
-
-export type FrameObservationReadback = (
-  lease: CurrentFrameObservationLease,
-) => Promise<Result<Uint8Array, Error>>;
-
-export interface FrameObservationOptions {
-  readonly semantic: 'linear-hdr';
-  readonly readback: FrameObservationReadback;
-}
-
-export interface FrameObservationMetadata {
-  readonly format: string;
-  readonly size: { readonly width: number; readonly height: number };
-  readonly usage: number;
-  readonly sample: number;
-  readonly frameId: number;
-  readonly lifetime: { readonly frameId: number; readonly state: 'active' | 'retired' };
-  readonly pipelineId: 'forgeax::urp' | 'forgeax::hdrp';
-  readonly backendId: string;
-}
-
-export interface FrameObservation {
-  readonly bytes: Uint8Array;
-  readonly metadata: FrameObservationMetadata;
-}
-
-function unavailable(
-  reason: ObservationUnavailableReason,
-  hint: string,
-): Result<never, ObservationUnavailableError> {
-  return err(new ObservationUnavailableError(reason, hint));
-}
-
-function mapLeaseFailure(code: string, hint: string): Result<never, ObservationUnavailableError> {
-  let reason: ObservationUnavailableReason = 'resource';
-  if (code === 'observation-stale') reason = 'stale';
-  else if (code === 'observation-invalid-format') reason = 'format';
-  else if (code === 'observation-missing-copy-src') reason = 'copy-src';
-  return unavailable(reason, hint);
-}
-
-export async function observeCurrentFrame(
-  options: FrameObservationOptions,
-  source: FrameObservationSource | undefined,
-  currentFrameId: number,
-): Promise<Result<FrameObservation, ObservationUnavailableError>> {
-  if (options.semantic !== 'linear-hdr') {
-    return unavailable('identity', 'request the producer-owned linear-hdr semantic');
-  }
-  if (source === undefined) {
-    return unavailable(
-      'no-frame',
-      'draw a frame through a supported URP or HDRP producer before requesting observation',
-    );
-  }
-  if (
-    (source.pipelineId !== 'forgeax::urp' && source.pipelineId !== 'forgeax::hdrp') ||
-    source.backendId.length === 0
-  ) {
-    return unavailable(
-      'identity',
-      'observe a producer with explicit pipeline and backend identity',
-    );
-  }
-
-  const leaseResult = createCurrentFrameObservationLease(
-    { ...source.descriptor, texture: source.texture, frameId: source.frameId },
-    currentFrameId,
-  );
-  if (!leaseResult.ok) {
-    return mapLeaseFailure(leaseResult.error.code, leaseResult.error.hint);
-  }
-
-  let bytesResult: Result<Uint8Array, Error>;
-  try {
-    bytesResult = await options.readback(leaseResult.value);
-  } catch (cause) {
-    const message = cause instanceof Error ? cause.message : String(cause);
-    return unavailable('readback-failed', `retry the current-frame readback after: ${message}`);
-  }
-  if (!bytesResult.ok) {
-    return unavailable('readback-failed', bytesResult.error.message);
-  }
-
-  const activeResult = leaseResult.value.beginReadback();
-  if (!activeResult.ok) {
-    return mapLeaseFailure(activeResult.error.code, activeResult.error.hint);
-  }
-
-  return ok({
-    bytes: bytesResult.value,
-    metadata: {
-      format: leaseResult.value.descriptor.format,
-      size: leaseResult.value.descriptor.size,
-      usage: leaseResult.value.descriptor.usage,
-      sample: source.descriptor.sample,
-      frameId: source.frameId,
-      lifetime: leaseResult.value.lifetime,
-      pipelineId: source.pipelineId,
-      backendId: source.backendId,
-    },
-  });
-}

package/src/record/index.ts

@@ -1,15 +0,0 @@
-// @forgeax/engine-runtime - RenderSystem record cluster barrel (feat-20260704 M3/w17).
-export * from './frame';
-export * from './frame-observation';
-export * from './frame-snapshot';
-export * from './frame-targets';
-export * from './helpers';
-export * from './main-pass';
-export * from './main-pass-material';
-export * from './main-pass-skin';
-export * from './main-pass-sprite';
-export * from './material-payload';
-export * from './mesh-ssbo';
-export * from './shadow-pass';
-export * from './skybox-post-pass';
-export * from './view-ubo';

package/src/record/main-pass-skin.ts

@@ -1,51 +0,0 @@
-import { MESH_PER_ENTITY_STRIDE } from './mesh-ssbo';
-
-/**
- * feat-20260612-skin-palette-per-frame-upload M3 / m3-2: pure helper that
- * builds the `setBindGroup(2, ...)` dynamic-offset tuple at the skin /
- * non-skin draw site.
- *
- * - Skin entries (`skinByteOffset !== undefined`) bind a 3-entry mesh-array
- *   BGL (binding 0 mesh-array UBO, bindings 1/2 current/previous palette UBOs;
- *   all `hasDynamicOffset: true`), so the tuple carries three offsets: the
- *   mesh slot follows the per-entity 256-byte stride and both palette slots
- *   carry the per-entity cursor M2 m2-6 wrote into
- *   `entry.source.skin.byteOffset`.
- * - Non-skin entries bind the URP / HDRP 1-entry mesh-array BGL, so the
- *   tuple carries only the mesh slot offset (length 1). Adding palette
- *   offset there would trip WebGPU validation against the 1-binding BGL.
- *
- * Extracted from the inline `group2DynamicOffsets = [i * MESH_PER_ENTITY_STRIDE,
- * 0]` site (PR #353 stub) so the contract `group2DynamicOffsets[1] ===
- * byteOffset` is testable from a focused unit fixture without driving
- * recordFrame end-to-end.
- *
- * @internal -- exported for unit test access (m3-1)
- */
-export function _computeSkinGroup2DynOffsets(
-  meshSlotIdx: number,
-  skinByteOffset: number | undefined,
-): readonly number[] {
-  const meshOffset = meshSlotIdx * MESH_PER_ENTITY_STRIDE;
-  if (skinByteOffset === undefined) return [meshOffset];
-  return [meshOffset, skinByteOffset, skinByteOffset];
-}
-
-/**
- * feat-20260612-skin-palette-per-frame-upload M3 / m3-2: read-side accessor
- * for the per-frame skin BG cache miss / hit counters published by the
- * record stage. Mirrors the existing `bindGroupCounts.createBindGroup`
- * surface but scoped to the skin-mesh BG cache so the m3-1 acceptanceCheck
- * (miss=1 + hit=N-1 across N skinned entities sharing one allocator buffer
- * + mesh SSBO) can be observed without traversing the full record-stage
- * dispatch log. The PipelineState carries the mutable counter object
- * (`_skinBgCacheStats: { miss, hit }`); the record-stage cache miss / hit
- * branches bump it; this accessor returns the live reference.
- *
- * @internal -- exported for unit test access (m3-1)
- */
-export function _skinBgCacheStats(pipelineState: {
-  readonly _skinBgCacheStats: { miss: number; hit: number };
-}): { miss: number; hit: number } {
-  return pipelineState._skinBgCacheStats;
-}

package/src/record/main-pass-sprite.ts

@@ -1,166 +0,0 @@
-import type { MaterialSnapshot, SpriteInstancesSnapshot } from '../render-system-extract';
-
-// ─── feat-20260625 M3 / w11 — sprite-pass 80B interleaved upload helpers ─────
-//
-// Plan-strategy D-1 (interleaved single buffer 80B/instance) + D-9 (cacheKey
-// = entity packed u32). The sprite-pass record stage consumes
-// `SpriteInstancesSnapshot` (from render-system-extract) and produces a single
-// GPU buffer interleaving mat4 transforms with vec4 regions per instance;
-// the BGL stays untouched (D-1 single binding slot @group(3) @binding(0)).
-//
-// Layout (per instance, byte offset 0..80):
-//   [0..64)  mat4 column-major (16 f32)
-//   [64..80) region vec4 [uMin, vMin, uW, vH] (4 f32)
-//   second instance starts at byte 80.
-//
-// The cache fingerprint is the triple `(cacheKey, archVersion, byteLength)`;
-// `spriteInstancesCacheHit` is the boolean side of the fingerprint check the
-// record stage runs once per sprite-pass entity. Pure functions — the GPU
-// device + buffer wrapper layer stays out of this module so the unit test
-// (w9) exercises both helpers without standing up a device mock.
-
-/** Re-export of the extract-stage snapshot so test sites can build it. */
-export type { SpriteInstancesSnapshot };
-
-/**
- * Interleave SpriteInstances transforms (stride 16) and regions (stride 4)
- * into a single Float32Array with stride 20 (= 80 bytes per instance,
- * plan-strategy D-1). Callers feed the output buffer to
- * `device.queue.writeBuffer` against the per-entity GPU buffer slot.
- *
- * Pre-conditions guaranteed by render-system-extract M3 / w10:
- *   - `transforms.length` is a multiple of 16
- *   - `regions.length` is a multiple of 4
- *   - `transforms.length / 16 === regions.length / 4`
- *
- * Violations fire `sprite-instances-count-mismatch` at the extract entry and
- * never reach this helper. The helper itself does NOT re-validate the
- * pre-conditions — single-validator invariant (charter P4 explicit failure
- * routed once at the extract boundary; downstream consumers trust the
- * snapshot shape).
- *
- * @param transforms — packed mat4 (column-major) Float32Array (stride 16).
- * @param regions    — packed vec4 [uMin, vMin, uW, vH] Float32Array (stride 4).
- * @returns interleaved Float32Array with length `(transforms.length + regions.length)`.
- */
-export function interleaveSpriteInstanceBuffer(
-  transforms: Float32Array,
-  regions: Float32Array,
-  previousTransforms: Float32Array | undefined = undefined,
-  includePrevious = true,
-): Float32Array {
-  const count = transforms.length / 16;
-  const stride = includePrevious ? 36 : 20;
-  const out = new Float32Array(count * stride);
-  for (let i = 0; i < count; i++) {
-    const dstBase = i * stride;
-    const tSrcBase = i * 16;
-    const rSrcBase = i * 4;
-    // mat4 (16 floats) — explicit loop avoids subarray copy overhead.
-    for (let k = 0; k < 16; k++) out[dstBase + k] = transforms[tSrcBase + k] ?? 0;
-    if (includePrevious) {
-      for (let k = 0; k < 16; k++) {
-        out[dstBase + 16 + k] = previousTransforms?.[tSrcBase + k] ?? transforms[tSrcBase + k] ?? 0;
-      }
-    }
-    // region (4 floats).
-    const regionOffset = includePrevious ? 32 : 16;
-    for (let k = 0; k < 4; k++) out[dstBase + regionOffset + k] = regions[rSrcBase + k] ?? 0;
-  }
-  return out;
-}
-
-/**
- * Boolean side of the per-entity sprite-pass GPU buffer cache fingerprint
- * check. Returns true iff the existing entry is byte-for-byte safe to reuse:
- *
- *   - `entry` exists (the entity has been recorded at least once);
- *   - `entry.uploadedArchVersion === snapshot.archVersion` (archetype
- *     storage has not been re-allocated since last upload);
- *   - `entry.uploadedByteLength === requestedBytes` (byte count matches the
- *     interleaved layout this frame would write).
- *
- * The record stage gates the `createBuffer + queue.writeBuffer` round on the
- * negation of this predicate; a hit short-circuits to a `writeBuffer`-only
- * refresh against the existing GPU buffer.
- *
- * @param entry — cached `InstanceBufferCacheEntry` for this `cacheKey`, or
- *   `undefined` if the entity has never been recorded.
- * @param snapshot — current frame's snapshot (carries `cacheKey + archVersion`).
- * @param requestedBytes — `transforms.byteLength + regions.byteLength` =
- *   80 * `instanceCount` for SpriteInstances (D-1 interleaved layout).
- */
-export function spriteInstancesCacheHit(
-  entry: import('../instance-buffer-cache').InstanceBufferCacheEntry | undefined,
-  snapshot: SpriteInstancesSnapshot,
-  requestedBytes: number,
-): boolean {
-  if (entry === undefined) return false;
-  if (entry.uploadedArchVersion !== snapshot.archVersion) return false;
-  if (entry.uploadedByteLength !== requestedBytes) return false;
-  return true;
-}
-
-// === feat-20260625 M2 / w7 transparent-aware helpers ============================
-//
-// Three small pure helpers replace the inline sprite-specific switches inside
-// recordFrame so the transparent / sprite / pipeline-miss paths become unit-
-// testable without a GPU device (charter P2 structure-over-prose).
-//
-// Plan anchors:
-//   - requirements AC-05 / AC-14
-//   - plan-strategy section 2 D-3 (MaterialSnapshot.transparent drives split
-//     + blend; charter P3 explicit failure on cache miss)
-//   - plan-strategy section 5.6 gate R-H (helpers only read MaterialSnapshot
-//     paramSnapshot / transparent fields; they MUST NOT touch
-//     the MaterialAsset registry directly or cast over firstMaterial)
-
-/**
- * Decides whether the LDR (tonemapActive=false) main pass needs the
- * sprite-style split into two serial sub-passes (geometry sRGB + transparent
- * unorm). Triggered by any validated dispatch entry carrying
- * `material.transparent === true` — derived by the extract stage from
- * `passes[0].renderState.blend !== undefined` (post-feat-20260626-collapse
- * SSOT, plan-strategy D-3; MaterialPass no longer carries a
- * dedicated `transparent` field).
- *
- * feat-20260625-refactor-sprite-as-transparent-mesh M3 / w13: the M2 union
- * with `shadingModel === 'sprite'` is gone — sprite materials now declare
- * `transparent: true` on their pass descriptor (or extract folds it onto
- * `MaterialSnapshot.transparent`), so the legacy arm is redundant.
- *
- * @internal
- */
-export function computeSplitLdrSprite(
-  validatedOrdered: readonly (
-    | {
-        readonly source: {
-          readonly material: MaterialSnapshot;
-          readonly materials?: readonly MaterialSnapshot[];
-        };
-      }
-    | undefined
-  )[],
-  tonemapActive: boolean,
-): boolean {
-  if (tonemapActive) return false;
-  for (let i = 0; i < validatedOrdered.length; i++) {
-    const v = validatedOrdered[i];
-    if (v === undefined) continue;
-    // feat-city-glb Bug 5 (per-submesh transparency): trip the split when ANY
-    // submesh material is transparent, not just the entity-level material[0].
-    // A multi-material mesh (e.g. opaque road + BLEND crosswalk decal submesh)
-    // has an opaque material[0] but a transparent submesh that must route to
-    // the blend sub-pass. Fall back to `material` when `materials` is absent
-    // (single-material entities / test fixtures) — identical to the old check.
-    const mats = v.source.materials;
-    if (mats !== undefined) {
-      for (let j = 0; j < mats.length; j++) {
-        if (mats[j]?.transparent === true) return true;
-      }
-    } else if (v.source.material.transparent === true) {
-      return true;
-    }
-  }
-  return false;
-}