@forgeax/engine-render 0.1.32 → 0.1.34

package/src/__tests__/construct-renderer-identity.unit.test.ts

@@ -2,8 +2,11 @@ import * as render from '@forgeax/engine-render';
 import {
   type EngineEnvironmentError,
   constructRendererHost as internalConstructRendererHost,
+  loadRhiPack as loadRenderRhiPack,
   type RendererHostAssembly,
+  type RhiBackendPack,
 } from '@forgeax/engine-render/internal/construct-renderer';
+import { rhi } from '@forgeax/engine-rhi-null';
 import { describe, expect, it } from 'vitest';
 import type { RenderError } from '../errors/render';
 import type { RenderResult } from '../render-contract';
@@ -21,4 +24,50 @@ describe('construct-renderer internal entry', () => {
     >;
     expect(null as unknown as Return satisfies Expected).toBeNull();
   });
+
+  it('projects backend fields with Render explicit-only instrumentation policy', () => {
+    const createShaderModule = async (..._args: unknown[]) => ({
+      ok: true as const,
+      value: {} as never,
+    });
+    const createShaderModuleImmediate = (..._args: unknown[]) => ({
+      ok: true as const,
+      value: {} as never,
+    });
+    const translateErrorEventToRhiError = (_event: unknown) => ({
+      ok: false as const,
+      error: {} as never,
+    });
+    const rawDeviceAccessor = (_device: unknown) => undefined;
+    const moduleInstrumentation: RhiBackendPack['instrumentation'] = {
+      onFrameBoundary: () => undefined,
+    };
+    const explicitInstrumentation: RhiBackendPack['instrumentation'] = {
+      onDeviceLost: () => undefined,
+    };
+    const module = {
+      rhi,
+      createShaderModule,
+      createShaderModuleImmediate,
+      translateErrorEventToRhiError,
+      _internal_getRawDevice: rawDeviceAccessor,
+      instrumentation: moduleInstrumentation,
+    };
+
+    const implicitPack = loadRenderRhiPack(module);
+    const explicitPack = loadRenderRhiPack(module, explicitInstrumentation);
+    expect(Object.hasOwn(implicitPack, 'instrumentation')).toBe(false);
+    expect(explicitPack.instrumentation).toBe(explicitInstrumentation);
+    expect(explicitPack.rhi).toBe(rhi);
+    expect(explicitPack.createShaderModule).toBe(createShaderModule);
+    expect(explicitPack.createShaderModuleImmediate).toBe(createShaderModuleImmediate);
+    expect(explicitPack.translateErrorEventToRhiError).toBe(translateErrorEventToRhiError);
+    expect(explicitPack._internal_getRawDevice).toBe(rawDeviceAccessor);
+
+    const absentPack = loadRenderRhiPack({ rhi });
+    expect(Object.hasOwn(absentPack, 'createShaderModule')).toBe(false);
+    expect(Object.hasOwn(absentPack, 'createShaderModuleImmediate')).toBe(false);
+    expect(Object.hasOwn(absentPack, 'translateErrorEventToRhiError')).toBe(false);
+    expect(Object.hasOwn(absentPack, '_internal_getRawDevice')).toBe(false);
+  });
 });

package/src/__tests__/detached-recovery-graph.unit.test.ts

@@ -0,0 +1,277 @@
+import type { RhiCommandEncoder, RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { RhiErrorListenerRegistry } from '../lifecycle';
+import type { RenderFrameState } from '../record/frame-snapshot';
+import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
+import type { PipelineState, RenderSystemInternals } from '../record/render-context';
+import {
+  ensureCompiledFrameGraph,
+  executeCompiledFrameGraph,
+  inspectRenderGraphGenerationAllocation,
+  retire as retireCompiledGraph,
+  settleBarrelDistortionGraphCandidate,
+  shareRenderGraphGenerationAllocationOwner,
+} from '../record/typed-frame-graph';
+import type { RenderPipeline } from '../render-pipeline';
+import type { ExtractedLights } from '../render-system-extract';
+
+function createRecoveryGraphHarness() {
+  let failBuild = false;
+  const activePipeline: RenderPipeline = {
+    build: ({ graph }) => {
+      if (failBuild) return { ok: false, error: { code: 'injected-build-failure' } } as never;
+      const buffer = graph.createBuffer('recovery-graph-bytes', { size: 16 });
+      if (!buffer.ok) return buffer;
+      return graph.addCopyPass('recovery-graph-seed', {
+        accesses: [{ resource: buffer.value, usage: 'copy-dst' }],
+        encode: () => undefined,
+      });
+    },
+  };
+  const frameState = {
+    compiledFrameGraph: null,
+    compiledFrameGraphTopologyKey: null,
+    retiredCompiledFrameGraphs: new Set(),
+    activePipeline,
+    installedPipelineConfig: undefined,
+  } as unknown as RenderFrameState;
+  const errorRegistry = new RhiErrorListenerRegistry();
+  let device: RhiDevice | undefined;
+  const internals = {
+    get device() {
+      return device as RhiDevice;
+    },
+    errorRegistry,
+  } as unknown as RenderSystemInternals;
+  const pipelineState = {
+    format: 'rgba8unorm',
+    colorAttachmentFormat: 'rgba8unorm',
+  } as unknown as PipelineState;
+  const lights = {
+    cascadeCount: undefined,
+    pointShadow: [],
+    spot: [],
+  } as unknown as ExtractedLights;
+  return {
+    activePipeline,
+    frameState,
+    internals,
+    pipelineState,
+    lights,
+    setDevice(nextDevice: RhiDevice) {
+      device = nextDevice;
+    },
+    compile() {
+      return ensureCompiledFrameGraph(
+        internals,
+        frameState,
+        pipelineState,
+        makeZeroCameraFallbackSnapshot(),
+        lights,
+        1,
+        1,
+        undefined,
+      );
+    },
+    accept() {
+      settleBarrelDistortionGraphCandidate(frameState, true);
+    },
+    setFail(value: boolean) {
+      failBuild = value;
+    },
+  };
+}
+
+describe('detached recovery graph execution boundary', () => {
+  it('keeps topology inspection while rejecting detached LKG and then retires it on replacement', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const harness = createRecoveryGraphHarness();
+    harness.setDevice(device);
+
+    const candidate = harness.compile();
+    expect(candidate).not.toBeNull();
+    if (candidate === null) return;
+    harness.frameState.compiledFrameGraphTopologyKey = null;
+    harness.frameState.perFrameGraph = null;
+    harness.setFail(true);
+    expect(harness.compile()).toBeNull();
+    expect(harness.frameState.compiledFrameGraph).toBe(candidate);
+
+    harness.setFail(false);
+    const replacement = harness.compile();
+    expect(replacement).not.toBeNull();
+    expect(replacement).not.toBe(candidate);
+    expect(harness.frameState.compiledFrameGraph).toBe(replacement);
+    expect(harness.frameState.compiledFrameGraphTopologyKey).not.toBeNull();
+    expect(harness.frameState.retiredCompiledFrameGraphs.has(candidate)).toBe(false);
+    harness.accept();
+    expect(harness.frameState.retiredCompiledFrameGraphs.has(candidate)).toBe(true);
+
+    harness.setFail(true);
+    expect(harness.compile()).toBe(replacement);
+  });
+
+  it('does not execute or submit a detached graph', () => {
+    const execute = vi.fn(() => ok(undefined));
+    const submit = vi.fn(() => ok(undefined));
+    const frameState = {
+      compiledFrameGraph: { execute },
+      compiledFrameGraphTopologyKey: null,
+      retiredCompiledFrameGraphs: new Set(),
+    } as unknown as RenderFrameState;
+    const internals = {
+      errorRegistry: { fire: vi.fn() },
+      device: { queue: { submit } },
+    } as never;
+
+    const submitted = executeCompiledFrameGraph(
+      internals,
+      frameState,
+      {} as never,
+      {} as RhiCommandEncoder,
+    );
+
+    expect(submitted).toBe(false);
+    expect(execute).not.toHaveBeenCalled();
+    expect(submit).not.toHaveBeenCalled();
+  });
+
+  it('projects active candidate overlap and graph-generation peak bytes', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const harness = createRecoveryGraphHarness();
+    harness.setDevice(device);
+
+    const first = harness.compile();
+    expect(first).not.toBeNull();
+    if (first === null) return;
+    harness.frameState.compiledFrameGraphTopologyKey = null;
+    const replacement = harness.compile();
+    expect(replacement).not.toBeNull();
+    if (replacement === null) return;
+    // The old graph remains live until the replacement submission is accepted.
+    expect(inspectRenderGraphGenerationAllocation(harness.frameState).liveBytes).toBe(32);
+    harness.accept();
+
+    const allocation = inspectRenderGraphGenerationAllocation(harness.frameState);
+    expect(allocation.availability).toBe('complete');
+    expect(allocation.entries).toHaveLength(2);
+    expect(
+      allocation.entries.find((entry) => entry.generation === replacement.inspect().generation)
+        ?.roles,
+    ).toEqual(expect.arrayContaining(['active']));
+    expect(
+      allocation.entries.find((entry) => entry.generation === first.inspect().generation)?.roles,
+    ).toEqual(expect.arrayContaining(['retiring']));
+    expect(allocation.liveBytes).toBe(16);
+    expect(allocation.pendingRetirementBytes).toBe(16);
+    expect(allocation.peakBytes).toBe(32);
+  });
+
+  it('records graph-generation overlap without an allocation inspection sample', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const harness = createRecoveryGraphHarness();
+    harness.setDevice(device);
+
+    const first = harness.compile();
+    expect(first).not.toBeNull();
+    if (first === null) return;
+
+    // Force two ordinary graph replacements. Do not call the allocation
+    // inspection between them: the renderer owner must observe compile and
+    // retirement events itself rather than treating inspect() as a sampler.
+    harness.frameState.compiledFrameGraphTopologyKey = null;
+    const second = harness.compile();
+    expect(second).not.toBeNull();
+    if (second === null) return;
+    harness.accept();
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    harness.frameState.compiledFrameGraphTopologyKey = null;
+    const third = harness.compile();
+    expect(third).not.toBeNull();
+    if (third === null) return;
+    harness.accept();
+
+    // RHI-null retires the old generations on its queue fence. The first
+    // inspection therefore sees one live graph, while peakBytes retains the
+    // live + retiring overlap observed during replacement.
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    const allocation = inspectRenderGraphGenerationAllocation(harness.frameState);
+    expect(allocation.liveBytes).toBe(16);
+    expect(allocation.pendingRetirementBytes).toBe(0);
+    expect(allocation.peakBytes).toBe(32);
+    expect(allocation.entries).toHaveLength(1);
+    expect(allocation.entries[0]?.generation).toBe(third.inspect().generation);
+  });
+
+  it('keeps a failed graph retirement visible in the renderer generation ledger', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const harness = createRecoveryGraphHarness();
+    harness.setDevice(device);
+
+    const first = harness.compile();
+    expect(first).not.toBeNull();
+    if (first === null) return;
+    (device as unknown as { destroyBuffer: RhiDevice['destroyBuffer'] }).destroyBuffer = () =>
+      ({ ok: false, error: { code: 'webgpu-runtime-error' } }) as never;
+    harness.frameState.compiledFrameGraphTopologyKey = null;
+    const replacement = harness.compile();
+    expect(replacement).not.toBeNull();
+    if (replacement === null) return;
+    harness.accept();
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+    const allocation = inspectRenderGraphGenerationAllocation(harness.frameState);
+    const failed = allocation.entries.find(
+      (entry) => entry.generation === first.inspect().generation,
+    );
+    expect(failed?.retirement).toBe('failed');
+    expect(failed?.allocation.pendingRetirementBytes).toBe(16);
+    expect(allocation.failedRetirementCount).toBe(1);
+    expect(allocation.failedRetirementBytes).toBe(16);
+  });
+
+  it('keeps a detached recovery candidate failure in the shared owner', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const harness = createRecoveryGraphHarness();
+    harness.setDevice(device);
+    const active = harness.compile();
+    expect(active).not.toBeNull();
+    if (active === null) return;
+
+    const candidateFrameState = {
+      ...harness.frameState,
+      compiledFrameGraph: null,
+      compiledFrameGraphTopologyKey: null,
+      retiredCompiledFrameGraphs: new Set(),
+    } as unknown as RenderFrameState;
+    shareRenderGraphGenerationAllocationOwner(harness.frameState, candidateFrameState);
+    const candidate = ensureCompiledFrameGraph(
+      harness.internals,
+      candidateFrameState,
+      harness.pipelineState,
+      makeZeroCameraFallbackSnapshot(),
+      harness.lights,
+      1,
+      1,
+      undefined,
+    );
+    expect(candidate).not.toBeNull();
+    if (candidate === null) return;
+
+    (device as unknown as { destroyBuffer: RhiDevice['destroyBuffer'] }).destroyBuffer = () =>
+      ({ ok: false, error: { code: 'webgpu-runtime-error' } }) as never;
+    retireCompiledGraph(candidateFrameState, candidate);
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+    const allocation = inspectRenderGraphGenerationAllocation(harness.frameState);
+    const failed = allocation.entries.find(
+      (entry) => entry.generation === candidate.inspect().generation,
+    );
+    expect(failed?.retirement).toBe('failed');
+    expect(failed?.roles).toEqual(expect.arrayContaining(['retiring']));
+    expect(allocation.failedRetirementCount).toBe(1);
+    expect(allocation.failedRetirementBytes).toBe(16);
+  });
+});

package/src/__tests__/device-loss-fanout.unit.test.ts

@@ -1,4 +1,4 @@
-import type { RhiDevice } from '@forgeax/engine-rhi';
+import { err, type RhiDevice, RhiError } from '@forgeax/engine-rhi';
 import { rhi } from '@forgeax/engine-rhi-null';
 import { describe, expect, it } from 'vitest';
 import { attachDeviceLostFanout } from '../assembly/recovery/device-loss-fanout';
@@ -20,6 +20,41 @@ function deferred<T>(): {
 }
 
 describe('device loss fan-out generation fence', () => {
+  it('forwards replacement-device validation errors and fences retired devices', () => {
+    let current = 0;
+    const errorRegistry = new RhiErrorListenerRegistry();
+    const errors: unknown[] = [];
+    errorRegistry.add((error) => errors.push(error));
+    const failure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'valid GPU work',
+      hint: 'repair the pipeline',
+    });
+    const native: { onuncapturederror?: (event: unknown) => void } = {};
+    attachDeviceLostFanout(
+      { lost: new Promise(() => undefined) } as unknown as RhiDevice,
+      {
+        rhi,
+        _internal_getRawDevice: () => native,
+        translateErrorEventToRhiError: () => err(failure),
+      },
+      {
+        lostRegistry: new LostListenerRegistry(),
+        errorRegistry,
+        healthRegistry: new HealthListenerRegistry(),
+        generation: 1,
+        currentGeneration: () => current,
+      },
+    );
+    expect(native.onuncapturederror).toBeTypeOf('function');
+    current = 1;
+    native.onuncapturederror?.({});
+    expect(errors).toEqual([failure]);
+    current = 2;
+    native.onuncapturederror?.({});
+    expect(errors).toEqual([failure]);
+  });
+
   it('counts a late old-generation notification without changing active health', async () => {
     const lost = deferred<{ readonly reason: 'unknown'; readonly message: string }>();
     const lostRegistry = new LostListenerRegistry();

package/src/__tests__/docs-gate-green.unit.test.ts

@@ -1,22 +1,133 @@
 import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
 import { describe, expect, it } from 'vitest';
 
 function read(relativePath: string): string {
   return readFileSync(new URL(relativePath, import.meta.url), 'utf8');
 }
 
+function publicPackagePaths(): ts.MapLike<string[]> {
+  const paths: ts.MapLike<string[]> = {};
+  for (const packageName of [
+    '@forgeax/engine-assets-runtime',
+    '@forgeax/engine-ecs',
+    '@forgeax/engine-geometry',
+    '@forgeax/engine-render',
+    '@forgeax/engine-scene',
+    '@forgeax/engine-types',
+  ]) {
+    const packageDirectory = packageName.slice('@forgeax/engine-'.length);
+    paths[packageName] = [`packages/${packageDirectory}/src/index.ts`];
+  }
+  return paths;
+}
+
 const renderReadme = read('../../README.md');
 const assetsReadme = read('../../../assets-runtime/README.md');
 const instancesSource = read('../components/instances.ts');
+const repositoryRoot = fileURLToPath(new URL('../../../../', import.meta.url));
+
+function readWaterConsumerCodeBlock(): string {
+  const marker = renderReadme.indexOf('export async function drawProbeLitWater(');
+  const blockStart = renderReadme.lastIndexOf('```ts', marker);
+  const blockEnd = renderReadme.indexOf('```', marker);
+  expect(marker).toBeGreaterThanOrEqual(0);
+  expect(blockStart).toBeGreaterThanOrEqual(0);
+  expect(blockEnd).toBeGreaterThan(blockStart);
+  return renderReadme.slice(blockStart + '```ts'.length, blockEnd);
+}
+
+function semanticDiagnosticsFor(sourceText: string): readonly ts.Diagnostic[] {
+  const virtualFile = path.join(repositoryRoot, 'packages/render/.docs-gate/water-consumer.ts');
+  const options: ts.CompilerOptions = {
+    allowImportingTsExtensions: true,
+    baseUrl: repositoryRoot,
+    ignoreDeprecations: '6.0',
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    noEmit: true,
+    paths: publicPackagePaths(),
+    skipLibCheck: true,
+    strict: true,
+    target: ts.ScriptTarget.ES2022,
+    types: ['node'],
+  };
+  const defaultHost = ts.createCompilerHost(options, true);
+  const host: ts.CompilerHost = {
+    ...defaultHost,
+    fileExists: (fileName) => fileName === virtualFile || defaultHost.fileExists(fileName),
+    readFile: (fileName) =>
+      fileName === virtualFile ? sourceText : defaultHost.readFile(fileName),
+    getSourceFile: (fileName, languageVersion, onError, shouldCreateNewSourceFile) =>
+      fileName === virtualFile
+        ? ts.createSourceFile(fileName, sourceText, languageVersion, true, ts.ScriptKind.TS)
+        : defaultHost.getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile),
+  };
+  const program = ts.createProgram([virtualFile], options, host);
+  const sourceFile = program.getSourceFile(virtualFile);
+  expect(sourceFile).toBeDefined();
+  return [
+    ...program.getOptionsDiagnostics(),
+    ...program.getSyntacticDiagnostics(sourceFile),
+    ...program.getSemanticDiagnostics(sourceFile),
+  ];
+}
+
+function formatDiagnostics(diagnostics: readonly ts.Diagnostic[]): string[] {
+  return diagnostics.map((diagnostic) =>
+    ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'),
+  );
+}
 
 describe('M4 material and Instances documentation contract', () => {
+  it('semantically checks the complete public water consumer code block', () => {
+    const snippet = readWaterConsumerCodeBlock();
+    const recovery = snippet.indexOf('const recoverAndRepublish = async');
+    expect(recovery).toBeGreaterThanOrEqual(0);
+    const diagnostics = semanticDiagnosticsFor(snippet);
+    expect(formatDiagnostics(diagnostics)).toEqual([]);
+    expect(snippet).not.toContain('renderer.initialization');
+    expect(snippet).toContain('const attachment = renderer.attach(world);');
+    expect(snippet).toContain('if (!attachment.ok) throw attachment.error;');
+    expect(snippet).toContain('const attached = attachment.value;');
+    for (const consumer of [
+      'renderer.inspect().frame.deviceGeneration',
+      'renderer.attach(world)',
+      '.draw({',
+    ]) {
+      expect(snippet.indexOf(consumer)).toBeGreaterThanOrEqual(0);
+    }
+    for (const recoveryFact of [
+      "renderer.state() !== 'device-lost'",
+      'await renderer.recover()',
+      'page.reconfigureDevice(nextDeviceGeneration)',
+      'const previousRanges = ranges',
+      'ranges = reserveFreshRanges()',
+      'projectionRevision += 1',
+      'publishDynamicInput(world.getResource(Time).elapsed)',
+      'submitted = await submitAndObserve()',
+      'const inspection = renderer.inspect()',
+      'submitted.deviceGeneration !== publishedDeviceGeneration',
+    ]) {
+      expect(snippet.indexOf(recoveryFact, recovery)).toBeGreaterThanOrEqual(recovery);
+    }
+    expect(snippet).toContain(
+      'renderer.setSurfaceDynamicInput({ page, ranges, projectionRevision, frameTime: now })',
+    );
+    expect(snippet).toContain('retry the same lease after the page and ranges are revalidated');
+    expect(snippet).not.toContain('commitUpload(');
+    expect(snippet).not.toContain('consume(');
+  }, 30_000);
+
   it('keeps resident observation and derived-bounds recovery discoverable', () => {
     for (const token of [
       'renderer.inspect().meshMaterialBindings[]',
       '`ready`, `pending`, `failed`, or `last-known-good`',
       'nearest structured preparation',
       'does not keep a second readiness ledger',
-      '`Instances` is a lightweight ECS association',
+      '`Instances.transforms` holds packed column-major mat4 values in World-managed',
       'derives CPU union bounds',
       'conservative no-cull result',
       'mesh AABB',

package/src/__tests__/dynamic-resolution-plugin.integration.test.ts

@@ -69,13 +69,33 @@ describe('DynamicResolution render component registration', () => {
       shutterAngle: 120,
       maxRadiusPixels: 12,
       sampleCount: 6,
+      targetFps: 60,
     });
     expect(extractFrames([world], 0).cameras[0]?.motionBlur).toEqual({
       shutterAngle: 120,
       maxRadiusPixels: 12,
       sampleCount: 6,
+      targetFps: 60,
     });
 
     await context.fiber.dispose();
   });
+
+  it('routes invalid MotionBlur data through the structured extraction error', async () => {
+    const world = new World();
+    const context = await createWorldContext(world, [renderComponentsPlugin(), scenePlugin()]);
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: Camera, data: { antialias: ANTIALIAS_TAA } },
+        { component: MotionBlur, data: { targetFps: 59.5 } },
+      )
+      .unwrap();
+    world.update(1 / 60).unwrap();
+
+    expect(() => extractCameraSnapshots(world)).toThrowError(
+      expect.objectContaining({ code: 'motion-blur-invalid-params' }),
+    );
+    await context.fiber.dispose();
+  });
 });

package/src/__tests__/environment-fog-lanes.integration.test.ts

@@ -20,6 +20,8 @@ const frame = selectEnvironment({
         mieCoefficient: 0.005,
         mieDirectionalG: 0.8,
         sunAngularRadius: 0.004675,
+        circumsolarStrength: 1,
+        circumsolarWidth: 1,
       },
     },
   ],
@@ -48,6 +50,8 @@ describe('Environment and Fog lane graph contract', () => {
           mieCoefficient: 0.006,
           mieDirectionalG: 0.7,
           sunAngularRadius: 0.01,
+          circumsolarStrength: 1.4,
+          circumsolarWidth: 1.6,
         },
       })
       .unwrap();
@@ -70,6 +74,8 @@ describe('Environment and Fog lane graph contract', () => {
     expect(extracted.environment.source.atmosphere?.mieCoefficient).toBeCloseTo(0.006);
     expect(extracted.environment.source.atmosphere?.mieDirectionalG).toBeCloseTo(0.7);
     expect(extracted.environment.source.atmosphere?.sunAngularRadius).toBeCloseTo(0.01);
+    expect(extracted.environment.source.atmosphere?.circumsolarStrength).toBeCloseTo(1.4);
+    expect(extracted.environment.source.atmosphere?.circumsolarWidth).toBeCloseTo(1.6);
     const signature = JSON.parse(extracted.environment.signature) as {
       environments: [{ atmosphere: Record<string, number> }];
       suns: [{ direction: [number, number, number] }];
@@ -79,6 +85,8 @@ describe('Environment and Fog lane graph contract', () => {
     expect(signature.environments[0].atmosphere.mieCoefficient).toBeCloseTo(0.006);
     expect(signature.environments[0].atmosphere.mieDirectionalG).toBeCloseTo(0.7);
     expect(signature.environments[0].atmosphere.sunAngularRadius).toBeCloseTo(0.01);
+    expect(signature.environments[0].atmosphere.circumsolarStrength).toBeCloseTo(1.4);
+    expect(signature.environments[0].atmosphere.circumsolarWidth).toBeCloseTo(1.6);
     expect(signature.suns[0].direction).toEqual([0, 1, 0]);
   });
 
@@ -162,6 +170,8 @@ describe('Environment and Fog lane graph contract', () => {
           mieCoefficient: 0.005,
           mieDirectionalG: 0.8,
           sunAngularRadius: 0.004675,
+          circumsolarStrength: 1,
+          circumsolarWidth: 1,
         },
       })
       .unwrap();
@@ -190,6 +200,8 @@ describe('Environment and Fog lane graph contract', () => {
         mieCoefficient: 0.005,
         mieDirectionalG: 0.8,
         sunAngularRadius: 0.004675,
+        circumsolarStrength: 1,
+        circumsolarWidth: 1,
       })
       .unwrap();
     const invalid = extractFrames([world], 0);
@@ -203,6 +215,8 @@ describe('Environment and Fog lane graph contract', () => {
         mieCoefficient: 0.006,
         mieDirectionalG: 0.7,
         sunAngularRadius: 0.01,
+        circumsolarStrength: 1,
+        circumsolarWidth: 1,
       })
       .unwrap();
     const corrected = extractFrames([world], 0);

package/src/__tests__/environment-selection.unit.test.ts

@@ -7,6 +7,7 @@ import type {
   EnvironmentCandidate,
   FogCandidate,
 } from '../extract/environment';
+import { SunCardinalityError } from '../index';
 
 const atmosphereParameters: AtmosphereParameters = {
   turbidity: 2,
@@ -14,6 +15,8 @@ const atmosphereParameters: AtmosphereParameters = {
   mieCoefficient: 0.005,
   mieDirectionalG: 0.8,
   sunAngularRadius: 0.004675,
+  circumsolarStrength: 1,
+  circumsolarWidth: 1,
 };
 
 const image = (entityKey: number, sourceKey: string): EnvironmentCandidate => ({
@@ -97,6 +100,7 @@ describe('Environment and Fog selection (M2)', () => {
     expect(result.error.expected).toContain('sun');
     expect(result.error.hint).toContain('sun');
     expect(result.error.detail).toMatchObject({ field, value });
+    expect(result.error).toBeInstanceOf(SunCardinalityError);
   });
 
   it('rejects invalid Fog parameters at the field owner', () => {
@@ -114,6 +118,8 @@ describe('Environment and Fog selection (M2)', () => {
     ['mieCoefficient', { mieCoefficient: -0.001 }],
     ['mieDirectionalG', { mieDirectionalG: 1.1 }],
     ['sunAngularRadius', { sunAngularRadius: Number.POSITIVE_INFINITY }],
+    ['circumsolarStrength', { circumsolarStrength: -0.001 }],
+    ['circumsolarWidth', { circumsolarWidth: 0.1 }],
   ] as const)('rejects invalid Atmosphere.%s with field-owned detail', (field, override) => {
     const result = selection(
       [
@@ -141,6 +147,8 @@ describe('Environment and Fog selection (M2)', () => {
     ['mieCoefficient', 0, 100],
     ['mieDirectionalG', 0, 0.999],
     ['sunAngularRadius', 0, 1],
+    ['circumsolarStrength', 0, 4],
+    ['circumsolarWidth', 0.25, 4],
   ] as const)('accepts the documented %s boundaries', (field, minimum, maximum) => {
     for (const value of [minimum, maximum]) {
       const result = selection(
@@ -165,6 +173,8 @@ describe('Environment and Fog selection (M2)', () => {
     ['mieCoefficient', [-Number.MIN_VALUE, Number.POSITIVE_INFINITY]],
     ['mieDirectionalG', [-Number.MIN_VALUE, 1]],
     ['sunAngularRadius', [-Number.MIN_VALUE, Number.POSITIVE_INFINITY]],
+    ['circumsolarStrength', [-Number.MIN_VALUE, 4.001]],
+    ['circumsolarWidth', [0.249, 4.001]],
   ] as const)('rejects %s values outside the shared shader domain', (field, values) => {
     for (const value of values) {
       const result = selection(
@@ -207,6 +217,8 @@ describe('Environment and Fog selection (M2)', () => {
     expect(baseline.value.source).toMatchObject({ atmosphere: atmosphereParameters });
     expect(baseline.value.signature).not.toBe(changed.value.signature);
     expect(baseline.value.signature).toContain('sunAngularRadius');
+    expect(baseline.value.signature).toContain('circumsolarStrength');
+    expect(baseline.value.signature).toContain('circumsolarWidth');
   });
 
   it('keeps Fog orthogonal and produces identical direct/clustered frame facts', () => {