@forgeax/engine-render 0.1.2

package/src/__tests__/fog-custom-render-feature.fixture.ts

@@ -0,0 +1,33 @@
+import type { RenderFeature } from '@forgeax/engine-render';
+import { ok } from '@forgeax/engine-types';
+
+export interface FogCustomRenderFrame {
+  readonly frameNumber: number;
+}
+
+export const fogCustomRenderFeature = {
+  identity: 'fixture.custom-fog-overlay',
+  extract(context) {
+    return ok<FogCustomRenderFrame>({ frameNumber: context.frameNumber });
+  },
+  prepare(data, context) {
+    void data;
+    void context;
+    return ok(undefined);
+  },
+  contribute(data, context) {
+    void data;
+    return context.staging.addPass('overlay', {
+      reads: ['scene-color'],
+      writes: ['scene-color'],
+      execute: () => undefined,
+    });
+  },
+} satisfies RenderFeature<FogCustomRenderFrame>;
+
+export const fogCustomRenderFeatureResponsibility = Object.freeze({
+  fogOwner: 'engine-render',
+  consumes: ['scene-color'],
+  writes: ['scene-color'],
+  doesNotOwn: ['fog-texture', 'fog-history', 'fog-bind-group'],
+} as const);

package/src/__tests__/fog-custom-render-feature.integration.test.ts

@@ -0,0 +1,76 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { beforeAll, describe, expect, it } from 'vitest';
+import {
+  fogCustomRenderFeature,
+  fogCustomRenderFeatureResponsibility,
+} from './fog-custom-render-feature.fixture';
+
+const WORKTREE_ROOT = resolve(fileURLToPath(new URL('.', import.meta.url)), '../../../..');
+const FEATURE_ID = 'feat-20260823-scene-fog-height-aerial-perspective-v1';
+const FEATURE_DIR =
+  process.env.FORGEAX_FOG_FEATURE_DIR ??
+  resolve(WORKTREE_ROOT, `.forgeax-harness/forgeax-loop/${FEATURE_ID}`);
+const EVIDENCE_PATH = resolve(FEATURE_DIR, 'evidence/custom-render-feature-compile.json');
+const FIXTURE_PATH = 'packages/render/src/__tests__/fog-custom-render-feature.fixture.ts';
+
+let compileExitCode = 1;
+let fixtureSource = '';
+let moduleImport = false;
+let overlay = false;
+
+describe('custom RenderFeature responsibility fixture', () => {
+  // This hook launches a package-level TypeScript compiler. Coverage workers
+  // share the CI runner and can legitimately make that cold compile exceed
+  // Vitest's 10s default even though the source contract is healthy.
+  beforeAll(() => {
+    const compileCommand = 'pnpm exec tsc -p packages/render/tsconfig.json --noEmit';
+    const compile = spawnSync(
+      'pnpm',
+      ['exec', 'tsc', '-p', 'packages/render/tsconfig.json', '--noEmit'],
+      {
+        cwd: WORKTREE_ROOT,
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+      },
+    );
+    compileExitCode = compile.status ?? 1;
+    moduleImport = fogCustomRenderFeature.identity === 'fixture.custom-fog-overlay';
+    overlay =
+      fogCustomRenderFeatureResponsibility.fogOwner === 'engine-render' &&
+      fogCustomRenderFeatureResponsibility.consumes.includes('scene-color') &&
+      fogCustomRenderFeatureResponsibility.writes.includes('scene-color') &&
+      fogCustomRenderFeatureResponsibility.doesNotOwn.includes('fog-history');
+    fixtureSource = readFileSync(resolve(WORKTREE_ROOT, FIXTURE_PATH), 'utf8');
+    const evidence = {
+      schemaVersion: 'forgeax-fog-custom-render-feature-compile-v1',
+      featureId: FEATURE_ID,
+      fixturePath: FIXTURE_PATH,
+      compiler: 'typescript',
+      command: compileCommand,
+      exitCode: compileExitCode,
+      moduleImport: moduleImport ? 'pass' : 'fail',
+      overlay: overlay ? 'pass' : 'fail',
+      stderr: compile.stderr.slice(-2000),
+    };
+    mkdirSync(dirname(EVIDENCE_PATH), { recursive: true });
+    writeFileSync(EVIDENCE_PATH, `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
+  }, 30_000);
+
+  it('compiles the render fixture', () => {
+    expect(compileExitCode).toBe(0);
+  });
+
+  it('imports the public RenderFeature contract', () => {
+    expect(moduleImport).toBe(true);
+    expect(fixtureSource).toContain('satisfies RenderFeature<FogCustomRenderFrame>');
+  });
+
+  it('keeps fog ownership in the engine render boundary', () => {
+    expect(overlay).toBe(true);
+    expect(fixtureSource).toContain("'scene-color'");
+    expect(fixtureSource).not.toMatch(/fog(?:History|Texture|Buffer|BindGroup|post-process)/i);
+  });
+});

package/src/__tests__/fog-inspection.integration.test.ts

@@ -0,0 +1,127 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { Fog } from '../components';
+import { PersistentRenderScene } from '../persistent-render-scene';
+import { extractFrames } from '../render-system-extract';
+import { runFogAiUserWalkthrough } from './fog-ai-user.fixture';
+
+interface FogInspectionExpectation {
+  readonly enabled: boolean;
+  readonly resourceOwner: number | undefined;
+  readonly entity: number | undefined;
+  readonly revision: number | undefined;
+  readonly reactive: boolean;
+  readonly failure: string | undefined;
+}
+
+interface FogPersistentInspectionExpectation {
+  readonly fog: FogInspectionExpectation;
+}
+
+interface FogSnapshotExpectation {
+  readonly color: readonly [number, number, number];
+  readonly density: number;
+  readonly heightFalloff: number;
+  readonly maxOpacity: number;
+  readonly revision: number;
+}
+
+interface FogOwnerApi {
+  readonly stageFogCandidate: (candidate: {
+    readonly snapshot: FogSnapshotExpectation;
+    readonly resourceOwner: number;
+    readonly entity: number;
+  }) => void;
+  readonly stageFogSubmission: () => void;
+  readonly stageFogFailure: (failure: {
+    readonly code: string;
+    readonly resourceOwner: number;
+  }) => void;
+}
+
+function fogInspection(persistent: PersistentRenderScene): FogInspectionExpectation {
+  return (persistent.inspect() as unknown as FogPersistentInspectionExpectation).fog;
+}
+
+describe('Fog retained snapshot inspection', () => {
+  it('publishes only after successful submit and retains LKG across failed candidates', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Fog, data: {} }).unwrap();
+    const persistent = new PersistentRenderScene();
+    const frame = extractFrames([world], 0);
+    const fogOwner = persistent as unknown as FogOwnerApi;
+
+    persistent.extract(world, 0, () => frame);
+    fogOwner.stageFogCandidate({
+      snapshot: (frame as unknown as { fog: FogSnapshotExpectation }).fog,
+      resourceOwner: 0,
+      entity,
+    });
+    expect(fogInspection(persistent)).toMatchObject({
+      enabled: false,
+      reactive: false,
+      failure: undefined,
+    });
+
+    fogOwner.stageFogSubmission();
+    const accepted = fogInspection(persistent);
+    expect(accepted).toMatchObject({
+      enabled: true,
+      resourceOwner: 0,
+      entity,
+      reactive: true,
+      failure: undefined,
+    });
+    const revision = accepted.revision;
+    expect(revision).toEqual(expect.any(Number));
+
+    fogOwner.stageFogFailure({
+      code: 'fog-parameters-invalid',
+      resourceOwner: 0,
+    });
+    expect(fogInspection(persistent)).toMatchObject({
+      enabled: true,
+      entity,
+      revision,
+      failure: 'fog-parameters-invalid',
+    });
+
+    world.despawn(entity).unwrap();
+    const replacement = world.spawn({ component: Fog, data: { density: 0.02 } }).unwrap();
+    const replacementFrame = extractFrames([world], 0);
+    fogOwner.stageFogCandidate({
+      snapshot: (replacementFrame as unknown as { fog: FogSnapshotExpectation }).fog,
+      resourceOwner: 0,
+      entity: replacement,
+    });
+    fogOwner.stageFogSubmission();
+    const next = fogInspection(persistent);
+    expect(next.entity).toBe(replacement);
+    expect(next.entity).not.toBe(entity);
+    expect(next.revision).not.toBe(revision);
+    expect(next.failure).toBeUndefined();
+  });
+
+  it('keeps inspection bounded and does not expose Fog parameters or GPU handles', () => {
+    const persistent = new PersistentRenderScene();
+    const inspection = fogInspection(persistent);
+    expect(Object.keys(inspection).sort()).toEqual([
+      'enabled',
+      'entity',
+      'failure',
+      'reactive',
+      'resourceOwner',
+      'revision',
+    ]);
+    expect(inspection).not.toHaveProperty('color');
+    expect(inspection).not.toHaveProperty('density');
+    expect(inspection).not.toHaveProperty('heightFalloff');
+    expect(inspection).not.toHaveProperty('maxOpacity');
+    expect(inspection).not.toHaveProperty('handle');
+    expect(JSON.stringify(inspection).length).toBeLessThan(256);
+  });
+
+  it('supports the public cold-start authoring and structured recovery walkthrough', async () => {
+    await runFogAiUserWalkthrough();
+  });
+});

package/src/__tests__/fog-owner-state.integration.test.ts

@@ -0,0 +1,112 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it, vi } from 'vitest';
+import { Fog } from '../components';
+import { extractFrames } from '../render-system-extract';
+
+interface FogSnapshotExpectation {
+  readonly color: readonly [number, number, number];
+  readonly density: number;
+  readonly heightFalloff: number;
+  readonly maxOpacity: number;
+  readonly revision: number;
+}
+
+interface FogFrameExpectation {
+  readonly fog: FogSnapshotExpectation | undefined;
+}
+
+function fogFrom(frame: unknown): FogSnapshotExpectation | undefined {
+  return (frame as FogFrameExpectation).fog;
+}
+
+describe('Fog resourceOwner selection and failure contract', () => {
+  it('selects only the resourceOwner and maps 0/1/N to disabled/active/conflict', () => {
+    const cameraWorld = new World();
+    const resourceWorld = new World();
+    const overlayWorld = new World();
+    cameraWorld.spawn({ component: Fog, data: {} }).unwrap();
+    overlayWorld.spawn({ component: Fog, data: {} }).unwrap();
+
+    const disabled = extractFrames([cameraWorld, resourceWorld, overlayWorld], {
+      cameraOwner: 0,
+      resourceOwner: 1,
+    });
+    expect(fogFrom(disabled)).toBeUndefined();
+
+    const resourceFog = resourceWorld.spawn({ component: Fog, data: {} }).unwrap();
+    const active = extractFrames([cameraWorld, resourceWorld, overlayWorld], {
+      cameraOwner: 0,
+      resourceOwner: 1,
+    });
+    expect(fogFrom(active)).toMatchObject({
+      color: [0.5, 0.5, 0.5],
+      heightFalloff: 0,
+      maxOpacity: 1,
+    });
+    expect(fogFrom(active)?.density).toBeCloseTo(0.01, 5);
+
+    resourceWorld.spawn({ component: Fog, data: { density: 0.02 } }).unwrap();
+    const errors: unknown[] = [];
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation((_message, error) => {
+      errors.push(error);
+    });
+    const conflict = extractFrames([cameraWorld, resourceWorld, overlayWorld], {
+      cameraOwner: 0,
+      resourceOwner: 1,
+    });
+    expect(fogFrom(conflict)).toBeUndefined();
+    expect(errors.at(-1)).toMatchObject({
+      code: 'fog-owner-conflict',
+      detail: {
+        resourceOwner: 1,
+        entities: expect.arrayContaining([resourceFog]),
+        omitted: 0,
+      },
+    });
+    errorSpy.mockRestore();
+  });
+
+  it.each([
+    ['color', { color: [-1, 0, 0] }],
+    ['density', { density: Number.NaN }],
+    ['heightFalloff', { heightFalloff: Number.POSITIVE_INFINITY }],
+    ['maxOpacity', { maxOpacity: 2 }],
+  ] as const)('rejects invalid %s without replacing it', (field, patch) => {
+    const world = new World();
+    const entity = world.spawn({ component: Fog, data: {} }).unwrap();
+    world.set(entity, Fog, patch).unwrap();
+    const errors: unknown[] = [];
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation((_message, error) => {
+      errors.push(error);
+    });
+
+    const frame = extractFrames([world], 0);
+
+    expect(fogFrom(frame)).toBeUndefined();
+    expect(errors.at(-1)).toMatchObject({
+      code: 'fog-parameters-invalid',
+      detail: {
+        entity,
+        field,
+        expected: expect.any(String),
+      },
+    });
+    expect((errors.at(-1) as { detail?: { actual?: unknown } }).detail?.actual).toBeDefined();
+    errorSpy.mockRestore();
+  });
+
+  it('derives a new revision for every accepted component change without debounce', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Fog, data: {} }).unwrap();
+    const initial = fogFrom(extractFrames([world], 0));
+    expect(initial?.revision).toEqual(expect.any(Number));
+
+    world.set(entity, Fog, { density: 0.02 }).unwrap();
+    const changed = fogFrom(extractFrames([world], 0));
+    expect(changed?.revision).not.toBe(initial?.revision);
+
+    world.set(entity, Fog, { density: 0.03 }).unwrap();
+    const changedAgain = fogFrom(extractFrames([world], 0));
+    expect(changedAgain?.revision).not.toBe(changed?.revision);
+  });
+});

package/src/__tests__/fog-pipeline-topology.integration.test.ts

@@ -0,0 +1,93 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const urp = readFileSync(new URL('../urp-pipeline.ts', import.meta.url), 'utf8');
+const hdrp = readFileSync(new URL('../hdrp-pipeline.ts', import.meta.url), 'utf8');
+const skybox = readFileSync(new URL('../record/skybox-post-pass.ts', import.meta.url), 'utf8');
+const temporal = readFileSync(new URL('../features/scene-temporal.ts', import.meta.url), 'utf8');
+const pipelineSpec = readFileSync(new URL('../pipeline-spec.ts', import.meta.url), 'utf8');
+const deferredLighting = readFileSync(
+  new URL('../../../shader/src/hdrp-deferred-lighting.wgsl', import.meta.url),
+  'utf8',
+);
+
+function ordered(source: string, labels: readonly string[]): boolean {
+  let cursor = -1;
+  for (const label of labels) {
+    const next = source.indexOf(label, cursor + 1);
+    if (next === -1) return false;
+    cursor = next;
+  }
+  return true;
+}
+
+describe('Fog scene-radiance pipeline topology', () => {
+  it('keeps Fog before temporal resolve, bloom, tone/output, and overlay in URP', () => {
+    expect(
+      ordered(urp, [
+        'scene-radiance-fog',
+        'resolveTemporal',
+        'addTypedBloomPasses',
+        'addTypedTonemapPass',
+        'addTypedDebugOverlayPass',
+      ]),
+    ).toBe(true);
+    expect(urp).toContain('scene-radiance-fog-opaque-fragment');
+    expect(urp).not.toMatch(/fog(?:History|Texture|Buffer|BindGroup|post-process)/i);
+  });
+
+  it('keeps HDRP deferred Fog at lighting output and forward Fog at fragment output', () => {
+    expect(hdrp).toContain('scene-radiance-fog-deferred-output');
+    expect(hdrp).toContain('scene-radiance-fog-forward-fragment');
+    expect(hdrp).not.toContain("name: 'fog-post-process'");
+    expect(hdrp.indexOf('scene-radiance-fog-deferred-output')).toBeLessThan(
+      hdrp.indexOf("name: 'forward'"),
+    );
+    expect(hdrp.indexOf('scene-radiance-fog-forward-fragment')).toBeLessThan(
+      hdrp.indexOf('const temporalRaster = addSceneTemporalRasterPass'),
+    );
+    expect(hdrp).toContain('encodeDeferredLightingPass');
+    expect(hdrp).not.toContain('encode: () => undefined');
+    expect(deferredLighting).toContain('fs_lighting');
+    expect(deferredLighting).toContain('inverseViewProj');
+    expect(deferredLighting).toContain('gbufferNormal');
+    expect(deferredLighting).toContain('gbufferEmissive');
+    expect(deferredLighting).toContain('view.lightDir');
+    expect(deferredLighting).toContain('apply_fog');
+    expect(deferredLighting).toContain('if (depth >= 0.999999)');
+    expect(deferredLighting).toContain('discard;');
+  });
+
+  it('keeps deferred Fog capability-gated and depth sampling layout-compatible', () => {
+    expect(hdrp).toContain("frame.runtime.device.caps.backendKind === 'wgpu-webgl2'");
+    expect(deferredLighting).toContain('textureSampleLevel(sceneDepth, depthSampler, in.uv, 0)');
+    expect(deferredLighting).toContain(
+      'textureSampleLevel(gbufferAlbedo, gbufferSampler, in.uv, 0)',
+    );
+    expect(deferredLighting).toContain(
+      'textureSampleLevel(gbufferNormal, gbufferSampler, in.uv, 0)',
+    );
+    expect(deferredLighting).toContain(
+      'textureSampleLevel(gbufferEmissive, gbufferSampler, in.uv, 0)',
+    );
+    expect(pipelineSpec).toContain("label: 'fullscreen-post-with-gbuffer-depth-bgl'");
+    expect(pipelineSpec).toContain('...buildFullscreenPostInputEntries(spec)');
+    expect(pipelineSpec).toContain("texture: { sampleType: 'float', viewDimension: '2d' }");
+    expect(pipelineSpec).toContain("sampler: { type: 'non-filtering' }");
+  });
+
+  it('keeps Skybox on the world-ray Fog path and bypasses overlays and temporal facts', () => {
+    expect(skybox).toContain('scene-radiance-fog-skybox');
+    expect(skybox).toContain('FogRay');
+    expect(skybox).toContain('camera far');
+    expect(skybox).not.toContain('scene-temporal');
+    expect(temporal).not.toContain('apply_fog');
+    expect(temporal).not.toContain('FogViewParams');
+  });
+
+  it('has no second Fog resource/pass/history owner', () => {
+    for (const source of [urp, hdrp, skybox, temporal]) {
+      expect(source).not.toMatch(/fog(?:History|Texture|Buffer|BindGroup|post-process)/i);
+    }
+  });
+});

package/src/__tests__/fog-public-surface.integration.test.ts

@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Fog } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+const WORKTREE_ROOT = resolve(fileURLToPath(new URL('.', import.meta.url)), '../../../..');
+const README = readFileSync(resolve(WORKTREE_ROOT, 'packages/render/README.md'), 'utf8');
+const RENDER_INDEX = readFileSync(resolve(WORKTREE_ROOT, 'packages/render/src/index.ts'), 'utf8');
+
+describe('Fog public surface and documentation contract', () => {
+  it('keeps the single public authoring and bounded inspection route indexable', () => {
+    expect(Fog.name).toBe('Fog');
+    for (const token of [
+      '## Fog: authoring, inspection, and recovery',
+      "import { Fog } from '@forgeax/engine-render';",
+      'world.spawn({ component: Fog',
+      'resourceOwner',
+      'renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })',
+      'renderer.renderScene.fog',
+      'bounded inspection',
+    ]) {
+      expect(README).toContain(token);
+    }
+    expect(RENDER_INDEX).toContain('Fog,');
+  });
+
+  it('documents both closed Fog errors as exhaustive structured recovery', () => {
+    for (const token of [
+      'FogOwnerConflictError',
+      'FogParametersInvalidError',
+      'fog-owner-conflict',
+      'fog-parameters-invalid',
+      '.code',
+      '.detail',
+      '.expected',
+      '.hint',
+      'switch (error.code)',
+      'retry draw',
+    ]) {
+      expect(README).toContain(token);
+    }
+  });
+
+  it('links real backend evidence and the custom-feature compile artifact', () => {
+    for (const token of [
+      'pnpm --filter @forgeax/bevy-fog smoke',
+      'pnpm --filter @forgeax/bevy-fog smoke:browser',
+      'evidence/dawn-fog-trace.json',
+      'evidence/browser-fog-trace.json',
+      'Custom RenderFeature responsibility',
+      'custom-render-feature-compile.json',
+      'observed',
+      'verdict',
+      'confidence',
+    ]) {
+      expect(README).toContain(token);
+    }
+  });
+});

package/src/__tests__/fog-ray-contract.integration.test.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const fogWgsl = readFileSync(
+  fileURLToPath(new URL('../../../shader/src/fog.wgsl', import.meta.url)),
+  'utf8',
+);
+
+interface RayFacts {
+  readonly origin: readonly [number, number, number];
+  readonly direction: readonly [number, number, number];
+  readonly distance: number;
+}
+
+function perspectiveRay(
+  camera: readonly [number, number, number],
+  fragment: readonly [number, number, number],
+): RayFacts {
+  const dx = fragment[0] - camera[0];
+  const dy = fragment[1] - camera[1];
+  const dz = fragment[2] - camera[2];
+  const distance = Math.hypot(dx, dy, dz);
+  return {
+    origin: camera,
+    direction: [dx / distance, dy / distance, dz / distance],
+    distance,
+  };
+}
+
+function orthographicRay(
+  cameraPlaneOrigin: readonly [number, number, number],
+  direction: readonly [number, number, number],
+  fragment: readonly [number, number, number],
+): RayFacts {
+  const dx = fragment[0] - cameraPlaneOrigin[0];
+  const dy = fragment[1] - cameraPlaneOrigin[1];
+  const dz = fragment[2] - cameraPlaneOrigin[2];
+  const distance = Math.hypot(dx, dy, dz);
+  return { origin: cameraPlaneOrigin, direction, distance };
+}
+
+describe('Fog real world-ray contract (M2)', () => {
+  it('uses origin, normalized direction, and true distance as module inputs', () => {
+    const perspective = perspectiveRay([0, 1, 3], [3, 2, -1]);
+    expect(perspective.origin).toEqual([0, 1, 3]);
+    expect(Math.hypot(...perspective.direction)).toBeCloseTo(1, 8);
+    expect(perspective.distance).toBeCloseTo(Math.sqrt(26), 8);
+
+    const orthographic = orthographicRay([2, 10, 4], [0, -1, 0], [3, 6, 4]);
+    expect(orthographic.origin).toEqual([2, 10, 4]);
+    expect(orthographic.direction).toEqual([0, -1, 0]);
+    expect(orthographic.distance).toBeCloseTo(Math.sqrt(17), 8);
+  });
+
+  it('does not derive Fog distance from fixed camera planes or non-linear depth', () => {
+    expect(fogWgsl).toContain('ray.origin');
+    expect(fogWgsl).toContain('ray.direction');
+    expect(fogWgsl).toContain('ray.distance');
+    expect(fogWgsl).not.toMatch(/\bnear\b/);
+    expect(fogWgsl).not.toMatch(/\bfar\b/);
+    expect(fogWgsl).not.toMatch(/\bdepth\b/);
+    expect(fogWgsl).not.toContain('texture');
+  });
+
+  it('preserves height direction instead of collapsing all rays to horizontal', () => {
+    const upward = [0, 1, 0] as const;
+    const downward = [0, -1, 0] as const;
+    expect(upward[1]).toBeGreaterThan(0);
+    expect(downward[1]).toBeLessThan(0);
+    expect(fogWgsl).toContain('direction.y');
+  });
+});

package/src/__tests__/fog-source-absence.integration.test.ts

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const WORKTREE_ROOT = resolve(fileURLToPath(new URL('.', import.meta.url)), '../../../..');
+const APP_ROOT = resolve(WORKTREE_ROOT, 'apps/bevy/fog');
+const PRODUCTION_FILES = [
+  'index.html',
+  'src/fog.ts',
+  'src/main.ts',
+  'src/oracle.mjs',
+  'src/runner.mjs',
+] as const;
+
+describe('Bevy Fog one-cut source absence contract', () => {
+  it('keeps the app on the public Engine Fog owner', () => {
+    const source = PRODUCTION_FILES.map((file) =>
+      readFileSync(resolve(APP_ROOT, file), 'utf8'),
+    ).join('\n');
+
+    expect(source).toContain("from '@forgeax/engine-render'");
+    expect(source).toContain('Fog');
+    for (const forbidden of [
+      'FOG_POSTPROCESS_ID',
+      'packFogParams',
+      'FogRenderer',
+      'installFogPostProcess',
+      'SceneFog',
+      'getSceneFog',
+      'setSceneFog',
+      'addTypedFogPass',
+      'fog-post-process',
+      'fullscreen fallback',
+      'FOG_MODE',
+      'FOG_LINEAR',
+      'FOG_EXP2',
+    ]) {
+      expect(source).not.toContain(forbidden);
+    }
+    expect(existsSync(resolve(APP_ROOT, 'src/fog.wgsl'))).toBe(false);
+  });
+
+  it('does not reintroduce a Fog-specific resource or temporal owner', () => {
+    const source = PRODUCTION_FILES.map((file) =>
+      readFileSync(resolve(APP_ROOT, file), 'utf8'),
+    ).join('\n');
+    expect(source).not.toMatch(/fog(?:History|Texture|Buffer|BindGroup|Pass|Registry)/i);
+    expect(source).not.toContain('@forgeax/engine-render/internal');
+  });
+});