@forgeax/engine-render 0.1.4 → 0.1.6

package/src/environment/graph.ts

@@ -1,588 +0,0 @@
-import type {
-  GraphTexture,
-  GraphTextureView,
-  ImportedTextureDescriptor,
-  RenderGraphBuilder,
-  RenderGraphError,
-  RenderGraphFrame,
-  Result,
-} from '@forgeax/engine-render-graph';
-import type { Texture } from '@forgeax/engine-rhi';
-import { err, ok } from '@forgeax/engine-types';
-import { AtmosphereProducerFailedError } from '../errors/render';
-import type { RenderPipelineFrame } from '../render-pipeline';
-import { environmentConsumerSnapshot } from './generation';
-import type { EnvironmentBundleDescriptors, EnvironmentCubeDescriptor } from './signature';
-
-export const ATMOSPHERE_PRODUCER_PASS_COUNT = 42;
-export const ATMOSPHERE_PARAMS_BYTES = 64;
-export const ATMOSPHERE_PARAMS_SLOT_BYTES = 256;
-export const ATMOSPHERE_BACKGROUND_PARAMS_SLOT = 0;
-/** The Sun disc has a distinct immutable consumer slot. */
-export const ATMOSPHERE_SUN_DISC_PARAMS_SLOT = 43;
-/** One consumer slot per composition draw plus one immutable slot per producer face. */
-export const ATMOSPHERE_PARAMS_SLOT_COUNT = 44;
-export const ATMOSPHERE_PRODUCER_KINDS = ['sky', 'irradiance', 'prefilter'] as const;
-export type AtmosphereProducerKind = (typeof ATMOSPHERE_PRODUCER_KINDS)[number];
-
-export interface EnvironmentProducerPass {
-  readonly name: string;
-  readonly kind: AtmosphereProducerKind;
-  readonly face: 0 | 1 | 2 | 3 | 4 | 5;
-  readonly mipLevel: number;
-  readonly executeIf: (frame: { readonly environmentDirty: boolean }) => boolean;
-}
-
-export interface EnvironmentImportedResource {
-  readonly kind: AtmosphereProducerKind;
-  readonly descriptor: EnvironmentCubeDescriptor;
-  readonly generation: number;
-}
-
-export interface EnvironmentProducerGraph {
-  readonly importedResources: readonly EnvironmentImportedResource[];
-  readonly passes: readonly EnvironmentProducerPass[];
-  readonly dirtyPassCount: number;
-}
-
-export interface EnvironmentGraphTargets {
-  readonly sky: readonly { readonly view: GraphTextureView }[];
-  /** Whole-cube view consumed by the background and material IBL bindings. */
-  readonly skyCube?: GraphTextureView;
-  readonly irradiance: readonly { readonly view: GraphTextureView }[];
-  readonly prefilter: readonly { readonly view: GraphTextureView }[];
-}
-
-export function environmentGenerationDirty<FrameCtx extends RenderPipelineFrame>(
-  frame: FrameCtx,
-): boolean {
-  return frame.frameState.environmentGeneration.candidate !== undefined;
-}
-
-export function environmentGenerationEnabled<FrameCtx extends RenderPipelineFrame>(
-  frame: FrameCtx,
-): boolean {
-  const generation = frame.frameState.environmentGeneration;
-  return generation.active !== undefined || generation.candidate !== undefined;
-}
-
-/** Add the common 42-face producer topology to either built-in pipeline. */
-export function addEnvironmentProducerPasses<FrameCtx extends RenderPipelineFrame>(
-  graph: RenderGraphBuilder<FrameCtx>,
-  target: { readonly view: GraphTextureView },
-  prefix: 'urp' | 'hdrp',
-  executeIf: (frame: FrameCtx) => boolean,
-  environmentTargets?: EnvironmentGraphTargets,
-): Result<number, RenderGraphError> {
-  for (let index = 0; index < ATMOSPHERE_PRODUCER_PASS_COUNT; index += 1) {
-    const kind = index < 6 ? 'sky' : index < 12 ? 'irradiance' : 'prefilter';
-    const face = index % 6;
-    const mip = kind === 'prefilter' ? Math.floor((index - 12) / 6) : 0;
-    const faceTarget = environmentTargets?.[kind]?.[mip * 6 + face] ?? target;
-    const skyCube = environmentTargets?.skyCube;
-    const added = graph.addRasterPass(
-      `${prefix}.atmosphere-producer.${kind}.mip-${mip}.face-${face}`,
-      {
-        accesses: [
-          { resource: faceTarget.view, usage: 'color-attachment' },
-          ...(kind === 'sky' || skyCube === undefined
-            ? []
-            : [{ resource: skyCube, usage: 'sampled-read' as const }]),
-        ],
-        colorAttachments: [
-          {
-            view: faceTarget.view,
-            // Every producer shader covers the full face. Zero is only an
-            // attachment initialization value; radiance comes from the shader.
-            loadOp: 'clear',
-            storeOp: 'store',
-            clearValue: [0, 0, 0, 0],
-          },
-        ],
-        executeIf,
-        encode: ({ pass, frame, resources: graphResources }) => {
-          const resources = frame.pipelineState.perPassResources;
-          const pipeline =
-            kind === 'sky'
-              ? resources.atmosphereCubemapPipeline
-              : kind === 'irradiance'
-                ? resources.atmosphereIrradiancePipeline
-                : resources.atmospherePrefilterPipeline;
-          const layout =
-            kind === 'sky'
-              ? resources.atmosphereCubemapBindGroupLayout
-              : resources.atmosphereIblParamsBindGroupLayout;
-          const paramsBuffer = resources.atmosphereParamsBuffer;
-          const vertexBuffer = resources.atmosphereCubeVertexBuffer;
-          if (
-            pipeline === null ||
-            pipeline === undefined ||
-            layout === null ||
-            layout === undefined ||
-            paramsBuffer === null ||
-            paramsBuffer === undefined ||
-            vertexBuffer === null ||
-            vertexBuffer === undefined
-          ) {
-            throw new AtmosphereProducerFailedError(
-              'execute',
-              `analytic-sky.${kind} producer requires its pipeline, layout, params buffer, and cube vertex buffer`,
-              atmosphereGeneration(frame),
-            );
-          }
-          const paramsSlot = atmosphereParamsSlot(kind, face, mip);
-          writeAtmosphereParams(frame, paramsBuffer, {
-            sunDisc: false,
-            kind,
-            mipLevel: mip,
-            prefilterMips: environmentTargets?.prefilter.length
-              ? Math.max(1, environmentTargets.prefilter.length / 6)
-              : 1,
-            bufferOffset: paramsSlot * ATMOSPHERE_PARAMS_SLOT_BYTES,
-          });
-          const entries = [
-            {
-              binding: 0,
-              resource: {
-                kind: 'buffer' as const,
-                value: {
-                  buffer: paramsBuffer,
-                  offset: paramsSlot * ATMOSPHERE_PARAMS_SLOT_BYTES,
-                  size: ATMOSPHERE_PARAMS_BYTES,
-                },
-              },
-            },
-          ];
-          if (kind !== 'sky') {
-            if (skyCube === undefined) {
-              throw new AtmosphereProducerFailedError(
-                'execute',
-                `analytic-sky.${kind} producer requires the generated sky cube`,
-                atmosphereGeneration(frame),
-              );
-            }
-            const skyView = graphResources.textureView(skyCube);
-            if (!skyView.ok) throw skyView.error;
-            const skyLayout = resources.atmosphereIblSkyBindGroupLayout;
-            const sampler = resources.skyboxSampler;
-            if (
-              skyLayout === null ||
-              skyLayout === undefined ||
-              sampler === null ||
-              sampler === undefined
-            ) {
-              throw new AtmosphereProducerFailedError(
-                'execute',
-                `analytic-sky.${kind} producer requires sky cube layout and sampler`,
-                atmosphereGeneration(frame),
-              );
-            }
-            const skyBindGroup = frame.runtime.device.createBindGroup({
-              layout: skyLayout,
-              entries: [
-                { binding: 0, resource: { kind: 'textureView', value: skyView.value } },
-                { binding: 1, resource: { kind: 'sampler', value: sampler } },
-              ],
-            });
-            if (!skyBindGroup.ok) throw skyBindGroup.error;
-            const paramsBindGroup = frame.runtime.device.createBindGroup({ layout, entries });
-            if (!paramsBindGroup.ok) throw paramsBindGroup.error;
-            pass.setPipeline(pipeline);
-            pass.setBindGroup(0, paramsBindGroup.value);
-            pass.setBindGroup(1, skyBindGroup.value);
-          } else {
-            const bindGroup = frame.runtime.device.createBindGroup({ layout, entries });
-            if (!bindGroup.ok) throw bindGroup.error;
-            pass.setPipeline(pipeline);
-            pass.setBindGroup(0, bindGroup.value);
-          }
-          pass.setVertexBuffer(0, vertexBuffer);
-          pass.draw(6, 1, face * 6, 0);
-          pass.insertDebugMarker(`analytic-sky.${kind}.mip-${mip}.face-${face}`);
-        },
-      },
-    );
-    if (!added.ok) return err(added.error);
-  }
-  return ok(ATMOSPHERE_PRODUCER_PASS_COUNT);
-}
-
-export function addEnvironmentCompositionPass(
-  graph: RenderGraphBuilder<RenderPipelineFrame>,
-  target: { readonly view: GraphTextureView },
-  name:
-    | 'urp.environment-background'
-    | 'urp.sun-disc'
-    | 'hdrp.environment-background-depth-aware'
-    | 'hdrp.sun-disc',
-  executeIf: (frame: RenderPipelineFrame) => boolean,
-  options: {
-    readonly clear?: boolean | undefined;
-    readonly sampled?: GraphTextureView | undefined;
-    readonly sunDisc?: boolean | undefined;
-    /** Depth authority is attached read-only; it is not a shader resource. */
-    readonly depth: GraphTextureView;
-  },
-): Result<void, RenderGraphError> {
-  const accesses = [
-    { resource: target.view, usage: 'color-attachment' as const },
-    ...(options.sampled === undefined
-      ? []
-      : [{ resource: options.sampled, usage: 'sampled-read' as const }]),
-    { resource: options.depth, usage: 'depth-stencil-read' as const },
-  ];
-  return graph.addRasterPass(name, {
-    accesses,
-    colorAttachments: [
-      {
-        view: target.view,
-        loadOp: options.clear === true ? 'clear' : 'load',
-        storeOp: 'store',
-        ...(options.clear === true ? { clearValue: environmentClearColor } : {}),
-      },
-    ],
-    depthStencilAttachment: {
-      view: options.depth,
-      depthReadOnly: true,
-      stencilReadOnly: true,
-    },
-    executeIf,
-    encode: ({ pass, frame, resources }) => {
-      const pipeline = frame.pipelineState.perPassResources.atmosphereBackgroundPipeline;
-      const layout = frame.pipelineState.perPassResources.atmosphereBackgroundBindGroupLayout;
-      const sampler = frame.pipelineState.perPassResources.skyboxSampler;
-      const paramsBuffer = frame.pipelineState.perPassResources.atmosphereParamsBuffer;
-      const sampled =
-        options.sampled === undefined ? undefined : resources.textureView(options.sampled);
-      if (
-        pipeline === null ||
-        pipeline === undefined ||
-        layout === null ||
-        layout === undefined ||
-        sampler === null ||
-        sampler === undefined ||
-        paramsBuffer === null ||
-        paramsBuffer === undefined ||
-        sampled === undefined ||
-        !sampled.ok
-      ) {
-        throw new AtmosphereProducerFailedError(
-          'execute',
-          `${name} requires its pipeline, layout, sampler, params buffer, and sampled sky`,
-          atmosphereGeneration(frame),
-        );
-      }
-      writeAtmosphereParams(frame, paramsBuffer, {
-        sunDisc: options.sunDisc === true,
-        kind: 'background',
-        mipLevel: 0,
-        prefilterMips: 1,
-        bufferOffset:
-          (options.sunDisc === true
-            ? ATMOSPHERE_SUN_DISC_PARAMS_SLOT
-            : ATMOSPHERE_BACKGROUND_PARAMS_SLOT) * ATMOSPHERE_PARAMS_SLOT_BYTES,
-      });
-      const paramsOffset =
-        (options.sunDisc === true
-          ? ATMOSPHERE_SUN_DISC_PARAMS_SLOT
-          : ATMOSPHERE_BACKGROUND_PARAMS_SLOT) * ATMOSPHERE_PARAMS_SLOT_BYTES;
-      const bindGroup = frame.runtime.device.createBindGroup({
-        layout,
-        entries: [
-          { binding: 0, resource: { kind: 'textureView', value: sampled.value } },
-          { binding: 1, resource: { kind: 'sampler', value: sampler } },
-          {
-            binding: 2,
-            resource: {
-              kind: 'buffer',
-              value: { buffer: frame.pipelineState.viewUniformBuffer },
-            },
-          },
-          {
-            binding: 3,
-            resource: {
-              kind: 'buffer',
-              value: { buffer: paramsBuffer, offset: paramsOffset, size: ATMOSPHERE_PARAMS_BYTES },
-            },
-          },
-        ],
-      });
-      if (!bindGroup.ok) throw bindGroup.error;
-      pass.setPipeline(pipeline);
-      pass.setBindGroup(0, bindGroup.value);
-      pass.draw(3, 1, 0, 0);
-      pass.insertDebugMarker(name);
-    },
-  });
-}
-
-function atmosphereGeneration(frame: RenderPipelineFrame): number | undefined {
-  return (
-    frame.frameState.environmentGeneration.candidate?.generation ??
-    frame.frameState.environmentGeneration.active?.generation
-  );
-}
-
-function writeAtmosphereParams(
-  frame: RenderPipelineFrame,
-  buffer: import('@forgeax/engine-rhi').Buffer,
-  options: {
-    readonly sunDisc: boolean;
-    readonly kind: AtmosphereProducerKind | 'background';
-    readonly mipLevel: number;
-    readonly prefilterMips: number;
-    readonly bufferOffset: number;
-  },
-): void {
-  const snapshot = environmentConsumerSnapshot(frame.frameState.environmentGeneration);
-  const atmosphere = snapshot?.atmosphere;
-  // The immutable environment snapshot is already the incident Sun direction.
-  // DirectionalLight/CSM apply the outgoing-ray negation at their own boundary.
-  const direction = snapshot?.direct.direction ?? [0, 1, 0];
-  const color = snapshot?.direct.color ?? [1, 1, 1];
-  const payload = new Float32Array([
-    direction[0] ?? 0,
-    direction[1] ?? 1,
-    direction[2] ?? 0,
-    snapshot?.direct.illuminance ?? 1,
-    color[0] ?? 1,
-    color[1] ?? 1,
-    color[2] ?? 1,
-    0,
-    atmosphere?.turbidity ?? 2,
-    atmosphere?.rayleigh ?? 1,
-    atmosphere?.mieCoefficient ?? 0.005,
-    atmosphere?.mieDirectionalG ?? 0.8,
-    atmosphere?.sunAngularRadius ?? 0.004675,
-    options.sunDisc ? 1 : 0,
-    options.kind === 'prefilter'
-      ? Math.min(1, options.mipLevel / Math.max(1, options.prefilterMips - 1))
-      : 0,
-    options.kind === 'sky'
-      ? 0
-      : options.kind === 'irradiance'
-        ? 1
-        : options.kind === 'prefilter'
-          ? 2
-          : 3,
-  ]);
-  const written = frame.runtime.device.queue.writeBuffer(buffer, options.bufferOffset, payload);
-  if (!written.ok) throw written.error;
-}
-
-/** Stable, HDR clear used when the analytic consumer has no scene geometry. */
-export function environmentClearColor(frame: RenderPipelineFrame): GPUColor {
-  const sun = environmentConsumerSnapshot(frame.frameState.environmentGeneration);
-  if (sun === undefined) return [0, 0, 0, 1];
-  const up = Math.max(0, Math.min(1, sun.direct.direction[1] ?? 0));
-  const color = sun.direct.color;
-  const scale = 0.04 + 0.16 * up;
-  return [
-    Math.max(0, (color[0] ?? 1) * scale),
-    Math.max(0, (color[1] ?? 1) * (scale * 0.92)),
-    Math.max(0, (color[2] ?? 1) * (scale * 0.84 + 0.015)),
-    1,
-  ];
-}
-
-function atmosphereParamsSlot(
-  kind: AtmosphereProducerKind,
-  face: number,
-  mipLevel: number,
-): number {
-  return kind === 'sky' ? 1 + face : kind === 'irradiance' ? 7 + face : 13 + mipLevel * 6 + face;
-}
-
-function resourceRoster(
-  descriptors: EnvironmentBundleDescriptors,
-  generation: number,
-): readonly EnvironmentImportedResource[] {
-  return [
-    { kind: 'sky', descriptor: descriptors.sky, generation },
-    { kind: 'irradiance', descriptor: descriptors.irradiance, generation },
-    { kind: 'prefilter', descriptor: descriptors.prefilter, generation },
-  ];
-}
-
-export function createEnvironmentProducerGraph(input: {
-  readonly descriptors: EnvironmentBundleDescriptors;
-  readonly generation: number;
-  readonly dirty: boolean;
-}): EnvironmentProducerGraph {
-  const passes: EnvironmentProducerPass[] = [];
-  const addFaces = (kind: AtmosphereProducerKind, mipLevel: number): void => {
-    for (let face = 0; face < 6; face += 1) {
-      passes.push({
-        name: `environment.${kind}.mip-${mipLevel}.face-${face}`,
-        kind,
-        face: face as EnvironmentProducerPass['face'],
-        mipLevel,
-        executeIf: (frame) => frame.environmentDirty,
-      });
-    }
-  };
-  addFaces('sky', 0);
-  addFaces('irradiance', 0);
-  for (const descriptor of input.descriptors.mips) addFaces('prefilter', descriptor.mipLevel);
-  return {
-    importedResources: resourceRoster(input.descriptors, input.generation),
-    passes,
-    dirtyPassCount: input.dirty ? passes.length : 0,
-  };
-}
-
-/**
- * Import the candidate bundle on the same graph builder as scene work. The
- * resolver is intentionally frame-scoped: a replaced generation cannot leak
- * a handle from a previous device or frame into the graph.
- */
-export function importEnvironmentResources<FrameCtx extends RenderGraphFrame>(
-  builder: RenderGraphBuilder<FrameCtx>,
-  input: {
-    readonly descriptors: EnvironmentBundleDescriptors;
-    readonly generation: number;
-    readonly resolve: (kind: AtmosphereProducerKind, frame: FrameCtx) => Texture;
-  },
-): Result<Readonly<Record<AtmosphereProducerKind, GraphTexture>>, RenderGraphError> {
-  const imported: Partial<Record<AtmosphereProducerKind, GraphTexture>> = {};
-  for (const kind of ATMOSPHERE_PRODUCER_KINDS) {
-    const descriptor =
-      kind === 'sky'
-        ? input.descriptors.sky
-        : kind === 'irradiance'
-          ? input.descriptors.irradiance
-          : input.descriptors.prefilter;
-    const result = builder.importTexture(
-      `environment.${kind}.generation-${input.generation}`,
-      importedDescriptor(descriptor, kind === 'prefilter' ? input.descriptors.mips.length : 1),
-      (frame) => input.resolve(kind, frame),
-    );
-    if (!result.ok) return result;
-    imported[kind] = result.value;
-  }
-  return ok(imported as Readonly<Record<AtmosphereProducerKind, GraphTexture>>);
-}
-
-/** Import every face/mip view so producer passes write physical candidates. */
-export function importEnvironmentGraphTargets<FrameCtx extends RenderGraphFrame>(
-  builder: RenderGraphBuilder<FrameCtx>,
-  input: {
-    readonly descriptors: EnvironmentBundleDescriptors;
-    readonly generation: number;
-    readonly resolve: (kind: AtmosphereProducerKind, frame: FrameCtx) => Texture;
-  },
-): Result<EnvironmentGraphTargets, RenderGraphError> {
-  const imported = importEnvironmentResources(builder, input);
-  if (!imported.ok) return imported;
-  const targetViews = (
-    kind: AtmosphereProducerKind,
-    mipCount: number,
-  ): Result<readonly { readonly view: GraphTextureView }[], RenderGraphError> => {
-    const texture = imported.value[kind];
-    const views: { readonly view: GraphTextureView }[] = [];
-    for (let mip = 0; mip < mipCount; mip += 1) {
-      for (let face = 0; face < 6; face += 1) {
-        const view = builder.view(texture, {
-          label: `environment.${kind}.generation-${input.generation}.mip-${mip}.face-${face}`,
-          dimension: '2d',
-          baseMipLevel: mip,
-          mipLevelCount: 1,
-          baseArrayLayer: face,
-          arrayLayerCount: 1,
-        });
-        if (!view.ok) return view;
-        views.push({ view: view.value });
-      }
-    }
-    return ok(views);
-  };
-  const sky = targetViews('sky', 1);
-  if (!sky.ok) return sky;
-  const irradiance = targetViews('irradiance', 1);
-  if (!irradiance.ok) return irradiance;
-  const prefilter = targetViews('prefilter', input.descriptors.mips.length);
-  if (!prefilter.ok) return prefilter;
-  const skyCube = builder.view(imported.value.sky, {
-    label: `environment.sky.generation-${input.generation}.cube`,
-    dimension: 'cube',
-    baseMipLevel: 0,
-    mipLevelCount: 1,
-    baseArrayLayer: 0,
-    arrayLayerCount: 6,
-  });
-  if (!skyCube.ok) return skyCube;
-  return ok({
-    sky: sky.value,
-    skyCube: skyCube.value,
-    irradiance: irradiance.value,
-    prefilter: prefilter.value,
-  });
-}
-
-function importedDescriptor(
-  descriptor: EnvironmentCubeDescriptor,
-  mipLevelCount: number,
-): ImportedTextureDescriptor {
-  return {
-    format: descriptor.format,
-    size: {
-      width: descriptor.width,
-      height: descriptor.height,
-      depthOrArrayLayers: descriptor.arrayLayers,
-    },
-    mipLevelCount,
-    dimension: '2d',
-    // WebGPUTextureUsage.RENDER_ATTACHMENT | TEXTURE_BINDING. Kept local so
-    // the graph package does not import runtime policy or a second capability
-    // table.
-    usage: 0x10 | 0x04,
-  };
-}
-
-export type EnvironmentTransactionStage = 'execute' | 'finish' | 'submit';
-
-export interface EnvironmentTransactionAttempt {
-  abort(stage: EnvironmentTransactionStage): void;
-  publish(): void;
-}
-
-export interface EnvironmentTransactionTrace {
-  readonly encoderCount: number;
-  readonly finishCount: number;
-  readonly submitCount: number;
-  readonly executedPassCount: number;
-  readonly abortedStage: EnvironmentTransactionStage | undefined;
-  readonly published: boolean;
-}
-
-/** One shared encoder/finish/submit transaction for environment and scene. */
-export function executeEnvironmentProducerTransaction(input: {
-  readonly graph: EnvironmentProducerGraph;
-  readonly dirty: boolean;
-  readonly environment: EnvironmentTransactionAttempt;
-  readonly temporal: EnvironmentTransactionAttempt;
-  readonly execute: () => boolean;
-  readonly finish: () => boolean;
-  readonly submit: () => boolean;
-}): EnvironmentTransactionTrace {
-  const fail = (
-    stage: EnvironmentTransactionStage,
-    trace: Omit<EnvironmentTransactionTrace, 'abortedStage' | 'published'>,
-  ): EnvironmentTransactionTrace => {
-    input.environment.abort(stage);
-    input.temporal.abort(stage);
-    return { ...trace, abortedStage: stage, published: false };
-  };
-  const base = {
-    encoderCount: 1,
-    finishCount: 0,
-    submitCount: 0,
-    executedPassCount: input.dirty ? input.graph.passes.length : 0,
-  };
-  if (!input.execute()) return fail('execute', base);
-  if (!input.finish()) return fail('finish', { ...base, finishCount: 1 });
-  if (!input.submit()) return fail('submit', { ...base, finishCount: 1, submitCount: 1 });
-  input.temporal.publish();
-  input.environment.publish();
-  return { ...base, finishCount: 1, submitCount: 1, abortedStage: undefined, published: true };
-}

package/src/environment/inspection.ts

@@ -1,107 +0,0 @@
-import type { EnvironmentGenerationState } from './generation';
-
-export type EnvironmentInspectionState =
-  | 'off'
-  | 'building'
-  | 'ready'
-  | 'last-known-good'
-  | 'failed';
-
-export interface EnvironmentInspectionTaa {
-  readonly activeSignature: string | undefined;
-  readonly publishCount: number;
-  readonly resetCount: number;
-  readonly lastResetReason?: string | undefined;
-}
-
-export interface EnvironmentInspectionInput {
-  readonly sourceWorldId?: number | undefined;
-  readonly sourceEntity?: number | undefined;
-  readonly taa?: EnvironmentInspectionTaa | undefined;
-  readonly rebuild?:
-    | {
-        readonly passCount: number;
-        readonly timeMs: number | undefined;
-      }
-    | undefined;
-}
-
-/** Bounded renderer POD; GPU handles and mutable caches are intentionally absent. */
-export interface EnvironmentInspection {
-  readonly state: EnvironmentInspectionState;
-  readonly source: { readonly worldId: number | undefined; readonly entity: number | undefined };
-  readonly desiredSignature: string | undefined;
-  readonly activeSignature: string | undefined;
-  readonly deviceGeneration: string | number;
-  readonly bytes: number;
-  readonly peakBytes: number;
-  readonly rebuildCost: number;
-  readonly rebuild: {
-    readonly passCount: number;
-    readonly timeMs: number | undefined;
-  };
-  readonly failure:
-    | { readonly stage: NonNullable<EnvironmentGenerationState['failureStage']> }
-    | undefined;
-  readonly taa: EnvironmentInspectionTaa;
-}
-
-function stateOf(source: EnvironmentGenerationState): EnvironmentInspectionState {
-  if (source.status === 'building') return 'building';
-  if (source.status === 'failed') return source.active === undefined ? 'failed' : 'last-known-good';
-  if (source.status === 'ready') {
-    return source.failureStage !== undefined && source.active !== undefined
-      ? 'last-known-good'
-      : 'ready';
-  }
-  return 'off';
-}
-
-export function inspectEnvironmentGeneration(
-  source: EnvironmentGenerationState,
-  input: EnvironmentInspectionInput = {},
-): EnvironmentInspection {
-  const failure = source.failureStage === undefined ? undefined : { stage: source.failureStage };
-  const taa = input.taa ?? {
-    activeSignature: source.active?.signature,
-    publishCount: source.publishCount,
-    resetCount: 0,
-  };
-  return Object.freeze({
-    state: stateOf(source),
-    source: Object.freeze({
-      worldId: input.sourceWorldId,
-      entity: input.sourceEntity,
-    }),
-    desiredSignature: source.desired?.signature,
-    activeSignature: source.active?.signature,
-    deviceGeneration: source.deviceGeneration,
-    bytes: source.bytes,
-    peakBytes: source.peakBytes,
-    rebuildCost: source.rebuildCost,
-    rebuild: Object.freeze(input.rebuild ?? { passCount: 0, timeMs: undefined }),
-    failure,
-    taa: Object.freeze({ ...taa }),
-  });
-}
-
-export interface FogEnvironmentProjectionInput {
-  readonly activeSignature: string | undefined;
-  readonly sunDirection: readonly [number, number, number];
-  readonly illuminance: number;
-}
-
-/** Read-only Fog consumer projection. Fog owns no ECS component, pass, or uniform. */
-export function projectFogEnvironment(
-  input: FogEnvironmentProjectionInput,
-): Readonly<FogEnvironmentProjectionInput> {
-  return Object.freeze({
-    activeSignature: input.activeSignature,
-    sunDirection: Object.freeze([
-      input.sunDirection[0],
-      input.sunDirection[1],
-      input.sunDirection[2],
-    ]) as unknown as readonly [number, number, number],
-    illuminance: input.illuminance,
-  });
-}