@forgeax/engine-shader 0.1.2

package/src/ShaderRegistry.ts

@@ -0,0 +1,519 @@
+// @forgeax/engine-shader/ShaderRegistry — runtime shader registry, instance-per-engine shape.
+//
+// Shape rules (plan-strategy §S-10 / D-R10 / OQ-5 close + AC-03):
+// - instance-per-engine — must be created via
+//   `new ShaderRegistry({device, manifestUrl})`; module-level singletons
+//   (`export const registry = ...`) and static methods (`static get`) are
+//   forbidden — aligned with the instance-based style of
+//   `Engine.create({ rhi })`.
+// - Physical isolation — this file does **not** import @forgeax/engine-shader-compiler /
+//   @forgeax/engine-naga / @forgeax/engine-wgpu-wasm (guarded by the AC-06 triple-grep gate;
+//   feat-20260511-naga-rhi-wgpu-merge M4 replaced the legacy single-shim ban
+//   with the merged ban list).
+// - Result model — `loadManifest()` / `get()` always go through Result.ok /
+//   Result.err and **never throw** (AGENTS.md "Errors are structured" / charter
+//   proposition 4: explicit failure).
+// - 9-member error union — `get()` returns
+//   `Result<ShaderModule, RhiError | ShaderError>` (AGENTS.md "RHI / Shader /
+//   error-model contract").
+
+import type { Result, RhiError, ShaderModule } from '@forgeax/engine-rhi';
+import type {
+  ImmutableParamSchemaProjection,
+  ManifestEntry,
+  ParamSchemaEntry,
+  ParamSchemaProjectionOwnerStats,
+} from '@forgeax/engine-types';
+import { findUndeclaredSampledTextures, ParamSchemaProjectionOwner } from '@forgeax/engine-types';
+import {
+  err,
+  manifestMalformed,
+  materialShaderNotFound,
+  ok,
+  type ShaderError,
+  type Result as ShaderResult,
+  shaderNotFound,
+} from './errors.js';
+import type { MaterialShaderManifestEntry } from './types.js';
+
+// ─── Device dependency-injection interface ──────────────────────────────────────
+
+/**
+ * Device dependency-injection interface — ShaderRegistry does not directly
+ * depend on `@forgeax/engine-rhi-webgpu` (physical isolation); the caller (engine or
+ * tests) supplies a device-like object that implements
+ * `createShaderModule(desc) → Result<ShaderModule, RhiError>`.
+ *
+ * Difference from the top-level async `createShaderModule(device, desc)` in
+ * `@forgeax/engine-rhi-webgpu`:
+ * - This interface is synchronous — so `registry.get()` can return a cached
+ *   module synchronously.
+ * - The caller is responsible for wrapping the async real path into a sync one
+ *   (e.g. the engine pre-compiles and caches modules during `loadManifest`).
+ *
+ * Mock test shape: a direct sync implementation (see `createMockDevice` in
+ * src/__tests__/registry.test.ts).
+ */
+export interface ShaderRegistryDevice {
+  createShaderModule(desc: {
+    readonly code: string;
+    readonly label?: string | undefined;
+  }): Result<ShaderModule, RhiError>;
+}
+
+// ─── MaterialShader registry types (feat-20260523-shader-template-instance-split M5) ──
+
+/**
+ * The `forgeax::` prefix reserves engine-shipped material shader identifiers
+ * (plan-strategy D-DefaultStandardPbr-Identifier + §8 charter F1 grep gate).
+ * AI users grep `forgeax::` to enumerate every reserved shader identifier in
+ * one shot. Custom user-side shaders pick their own identifier path
+ * (typically `<package>::<id>`) — anything that is not a `<guid>`
+ * (UUIDv5/v7) shape and not `forgeax::*`.
+ */
+export const FORGEAX_RESERVED_PATH_PREFIX = 'forgeax::' as const;
+
+/**
+ * Material shader admission input accepted by
+ * `installMaterialArtifact(identifier, entry)`. `findMaterialArtifact`
+ * returns a {@link RegisteredMaterialShaderEntry} with the immutable schema
+ * projection attached.
+ *
+ * - `source`: composed WGSL source (post-naga_oil); the final form fed to
+ *   `device.createShaderModule({ code })` at pipeline-build time.
+ * - `paramSchema`: closed list of `{name, type, default?}` triples that the
+ *   `MaterialAsset.payload.values` is validated against at register-time
+ *   (feat-20260523-shader-template-instance-split M4 3-tier validation). Per
+ *   feat-20260613-material-paramschema-driven-binding M3 / w12-w13, the
+ *   paramSchema is also the SSOT for the pipeline BGL via
+ *   `derive(paramSchema).bglEntries` — there is no longer a separate
+ *   `bindingLayout` field on this entry (D-1 / D-2).
+ *
+ * The shape is symmetric across engine-default + user-custom paths
+ * (charter P4 consistent abstraction): both go through the same
+ * `installMaterialArtifact` API regardless of whether the host wires the
+ * default-standard-pbr triple at boot or the user registers a custom
+ * shader after asset import.
+ */
+export interface MaterialShaderEntry {
+  readonly source: string;
+  readonly paramSchema: readonly ParamSchemaEntry[];
+}
+
+/** Registry-owned runtime shape published after immutable schema admission. */
+export interface RegisteredMaterialShaderEntry extends MaterialShaderEntry {
+  readonly paramSchemaProjection: ImmutableParamSchemaProjection;
+}
+
+// ─── Public registry types ──────────────────────────────────────────────────────
+
+export interface ShaderRegistryOptions {
+  readonly device: ShaderRegistryDevice;
+  /**
+   * URL the registry fetches `manifest.json` from. `undefined` puts the
+   * registry into the **zero-entry** mode: `loadManifest()` resolves
+   * `Result.ok(undefined)` without issuing a fetch and `entries()` returns
+   * an empty iterator. This is the bug-20260519 clear-pass-only path
+   * where AI users build a `Camera`-only world (no PBR / unlit pipeline
+   * is ever needed). `createRenderer.ts` Step 2 narrows on
+   * `manifestEntries.length > 0` to skip the dual `createShaderModule`
+   * compile in the same path (charter P3 + plan-strategy D-1 + D-2).
+   */
+  readonly manifestUrl: string | undefined;
+}
+
+// ─── ShaderRegistry main class (instance-per-engine) ============================
+
+/**
+ * Runtime shader registry — content-addressable manifest lookup →
+ * `device.createShaderModule`.
+ *
+ * Usage:
+ * ```
+ * const registry = new ShaderRegistry({ device, manifestUrl: '/shaders/manifest.json' });
+ * const loaded = await registry.loadManifest();
+ * if (!loaded.ok) handleError(loaded.error); // ShaderError.manifest-malformed
+ *
+ * const result = registry.get('abc12345');
+ * if (!result.ok) handleError(result.error); // RhiError | ShaderError.shader-not-found
+ * else useModule(result.value);
+ * ```
+ *
+ * `static get` / module-level singletons are **forbidden** (plan-strategy
+ * §S-10).
+ */
+export class ShaderRegistry {
+  readonly #device: ShaderRegistryDevice;
+  readonly #manifestUrl: string | undefined;
+  // hash → ManifestEntry index (populated after loadManifest).
+  readonly #entries = new Map<string, ManifestEntry>();
+  // hash → ShaderModule cache (populated lazily on first get()).
+  readonly #moduleCache = new Map<string, ShaderModule>();
+  // identifier → MaterialShaderEntry index (populated by
+  // installMaterialArtifact; feat-20260523-shader-template-instance-split M5 / T05).
+  readonly #materialShaders = new Map<string, RegisteredMaterialShaderEntry>();
+  readonly #paramSchemaProjectionOwner = new ParamSchemaProjectionOwner();
+  readonly #materialShaderManifestEntries: MaterialShaderManifestEntry[] = [];
+  #manifestLoaded = false;
+
+  constructor(opts: ShaderRegistryOptions) {
+    this.#device = opts.device;
+    this.#manifestUrl = opts.manifestUrl;
+  }
+
+  /**
+   * Loads manifest.json and populates the hash → ManifestEntry index.
+   *
+   * Failure paths (charter proposition 4: explicit failure):
+   * - fetch / data: URL parse failed → `Result.err(ShaderError.manifest-malformed)`
+   * - JSON.parse failed → ditto
+   * - schema missing the `entries` field / an entries element missing
+   *   hash/wgsl/bindings → ditto
+   * - a material shader row is incomplete → ditto
+   *
+   * Validation is atomic: the registry does not publish any entry or
+   * material shader row until the complete document has been validated.
+   *
+   * Idempotent: subsequent calls reuse the first result (never re-fetch;
+   * charter proposition 6: idempotency).
+   */
+  async loadManifest(): Promise<ShaderResult<void, ShaderError>> {
+    if (this.#manifestLoaded) return ok(undefined);
+
+    // bug-20260519 D-2: zero-entry mode. `manifestUrl === undefined` means
+    // the host opted out of shipping a shader manifest (Camera-only /
+    // clear-pass-only LO 1.1 path); resolve `Result.ok` without issuing a
+    // fetch. `entries()` then yields nothing and createRenderer Step 2
+    // skips the dual `createShaderModule` compile (D-1 + D-3 nullable
+    // PipelineState). Subsequent `get(hash)` calls fall through to the
+    // shader-not-found arm via the empty entries map (charter P3
+    // explicit failure on misuse).
+    if (this.#manifestUrl === undefined) {
+      this.#manifestLoaded = true;
+      return ok(undefined);
+    }
+
+    let raw: string;
+    try {
+      const response = await fetch(this.#manifestUrl);
+      raw = await response.text();
+    } catch (e) {
+      return err(
+        manifestMalformed({
+          message: `ShaderRegistry: failed to fetch manifest at ${this.#manifestUrl}`,
+          hint: 'verify manifest URL is reachable; check bundler emitFile output path',
+          reason: e instanceof Error ? e.message : String(e),
+        }),
+      );
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (e) {
+      return err(
+        manifestMalformed({
+          message: 'ShaderRegistry: manifest JSON parse failed',
+          hint: 'manifest.json must be valid JSON; rebuild via @forgeax/engine-vite-plugin-shader generateBundle',
+          reason: e instanceof Error ? e.message : String(e),
+        }),
+      );
+    }
+
+    if (typeof parsed !== 'object' || parsed === null || !('entries' in parsed)) {
+      return err(
+        manifestMalformed({
+          message: 'ShaderRegistry: manifest missing required `entries` field',
+          hint: 'manifest schema requires top-level `entries: ManifestEntry[]`',
+        }),
+      );
+    }
+
+    const entries = (parsed as { entries: unknown }).entries;
+    if (!Array.isArray(entries)) {
+      return err(
+        manifestMalformed({
+          message: 'ShaderRegistry: manifest.entries is not an array',
+          hint: 'manifest schema requires `entries: ManifestEntry[]`',
+        }),
+      );
+    }
+
+    const validatedEntries: ManifestEntry[] = [];
+    for (const entry of entries) {
+      if (!isValidManifestEntry(entry)) {
+        return err(
+          manifestMalformed({
+            message: 'ShaderRegistry: manifest entry missing required fields',
+            hint: 'every entry needs {hash, wgsl, glsl, bindings} per @forgeax/engine-types.ManifestEntry',
+            reason: `bad entry: ${JSON.stringify(entry)}`,
+          }),
+        );
+      }
+      validatedEntries.push(entry);
+    }
+
+    // feat-20260526-pbr-uniform-fallback-no-storage-buffer M3 / w12:
+    // parse and store materialShaders[] from the manifest for
+    // createRenderer variant resolution. Non-existent / non-array
+    // materialShaders is treated as empty (backward-compatible with
+    // manifests from pre-M2 build runs).
+    const parsedSlim = parsed as { materialShaders?: unknown };
+    const validatedMaterialShaderEntries: MaterialShaderManifestEntry[] = [];
+    if (Array.isArray(parsedSlim.materialShaders)) {
+      for (const ms of parsedSlim.materialShaders) {
+        if (!isValidMaterialShaderManifestEntry(ms)) {
+          return err(
+            manifestMalformed({
+              message: 'ShaderRegistry: manifest material shader entry missing required fields',
+              hint: 'every material shader entry needs {identifier, sourcePath, composedWgsl, paramSchema, variants}',
+              reason: `bad material shader entry: ${JSON.stringify(ms)}`,
+            }),
+          );
+        }
+        validatedMaterialShaderEntries.push(ms);
+      }
+    }
+
+    this.#entries.clear();
+    for (const entry of validatedEntries) {
+      this.#entries.set(entry.hash, entry);
+    }
+    this.#materialShaderManifestEntries.length = 0;
+    this.#materialShaderManifestEntries.push(...validatedMaterialShaderEntries);
+    this.#manifestLoaded = true;
+    return ok(undefined);
+  }
+
+  /**
+   * Iterate every `ManifestEntry` populated by the most recent successful
+   * `loadManifest()` call. Order matches the manifest JSON `entries` array
+   * (insertion order; charter P2 structured-over-prose: AI users walk this
+   * to discover engine-shipped entries by content marker without
+   * re-fetching the manifest).
+   *
+   * Returns an empty iterator when no manifest has been loaded yet
+   * (charter P3 explicit failure: the empty case is not an error — the
+   * absent SSOT is the absent contract).
+   */
+  entries(): IterableIterator<ManifestEntry> {
+    return this.#entries.values();
+  }
+
+  /**
+   * Looks up a hash and forwards to `device.createShaderModule` (creates lazily
+   * on first hit, then caches).
+   *
+   * Error paths:
+   * - hash miss → `Result.err(ShaderError.shader-not-found)`
+   * - device.createShaderModule failed → `Result.err(RhiError)` passes through
+   *   (it is **not** wrapped as a ShaderError).
+   *
+   * Sync shape: on cache miss, the underlying `device.createShaderModule` is
+   * called synchronously; the caller is responsible for handling the async
+   * real path at the device-wrapper layer (e.g. the engine pre-compiles
+   * during `loadManifest`).
+   */
+  get(hash: string): Result<ShaderModule, RhiError | ShaderError> {
+    const cachedModule = this.#moduleCache.get(hash);
+    if (cachedModule !== undefined) {
+      return ok(cachedModule);
+    }
+
+    const entry = this.#entries.get(hash);
+    if (entry === undefined) {
+      return err(
+        shaderNotFound({
+          hash,
+          hint: 'verify manifest.json contains the expected hash; rerun build to regenerate manifest',
+        }),
+      );
+    }
+
+    const result = this.#device.createShaderModule({ code: entry.wgsl, label: hash });
+    if (!result.ok) {
+      return result;
+    }
+    this.#moduleCache.set(hash, result.value);
+    return result;
+  }
+
+  // ─── MaterialShader registry surface ───────────────────────────────────────
+  // (feat-20260523-shader-template-instance-split M5 / T05 — plan-strategy
+  // D-DefaultStandardPbr-Identifier).
+  //
+  // Two-tier identifier namespace:
+  //   - `forgeax::*`  — engine-shipped reserved prefix; the host wires
+  //     `forgeax::default-standard-pbr` at engine boot from the
+  //     vite-plugin-shader manifest's `materialShaders[]` row + the
+  //     `default-standard-pbr.schema.json` SSOT (M5 / T08 + M6).
+  //   - any other identifier — user-side custom material shader, registered
+  //     after asset import.
+  //
+  // The registry is the runtime SSOT consumed by:
+  //   - the material decoder's `'::' two-way dispatch` (M4 / T01) — the path
+  //     branch validates against `paramSchema` and feeds `MaterialSnapshot.
+  //     materialShaderId` (M4 / T05).
+  //   - `render-system-record`'s pipeline cache key (M4 / T06) — same
+  //     identifier feeds the per-pipeline `(materialShaderId, stateHash)` key.
+
+  /**
+   * Register a material shader entry under a stable identifier.
+   *
+   * **Throws** on:
+   *   - duplicate registration of the same identifier (programmer error per
+   *     AGENTS.md "explicit registration" + Inspector "fail-fast no overwrite"
+   *     pattern; charter P3 explicit failure on misuse).
+   *
+   * Successful path returns void — the registry mutates in-place. Use
+   * {@link findMaterialArtifact} to read back.
+   *
+   * Identifier conventions (charter F1 / plan-strategy §8 §2):
+   *   - `forgeax::<kebab-case>` — engine-shipped reserved prefix; the host
+   *     registers `forgeax::default-standard-pbr` at boot.
+   *   - `<package>::<id>` or `<guid>` — user-side custom shaders.
+   *
+   * @example
+   * ```ts
+   * const registry = new ShaderRegistry({ device, manifestUrl });
+   * registry.installMaterialArtifact('forgeax::default-standard-pbr', {
+   *   source: composedWgsl,
+   *   paramSchema: defaultStandardPbrSchema,
+   * });
+   * ```
+   */
+  installMaterialArtifact(identifier: string, entry: MaterialShaderEntry): void {
+    if (this.#materialShaders.has(identifier)) {
+      throw new Error(
+        `ShaderRegistry: material shader identifier '${identifier}' already registered; same-name re-register is forbidden (AGENTS.md "explicit registration" + Inspector "fail-fast no overwrite" pattern). Use findMaterialArtifact to read back the existing entry.`,
+      );
+    }
+    // bug-20260619: user shaders registered directly here bypass the build-time
+    // superset gate (vite-plugin-shader's WGSL reflection). A schema that omits
+    // a texture field the WGSL actually samples would let the extract stage's
+    // `validateTextureHandle` silently drop the handle and fall back to the
+    // default white texture (opaque-white grass/windows in the LO 4.3 blending
+    // demo). Fail fast at register time instead (charter P3 explicit failure).
+    // Scoped to user shaders: engine `forgeax::*` shaders go through the
+    // build-time gate and may sample engine-injected textures (emissive /
+    // occlusion) absent from their schema by design.
+    const paramSchemaProjection = this.#paramSchemaProjectionOwner.admit({
+      ownerId: identifier,
+      revision: 1,
+      schema: entry.paramSchema,
+    });
+    if (!identifier.startsWith(FORGEAX_RESERVED_PATH_PREFIX)) {
+      const undeclared = findUndeclaredSampledTextures(entry.source, paramSchemaProjection.schema);
+      if (undeclared.length > 0) {
+        throw new Error(
+          `ShaderRegistry: material shader '${identifier}' samples texture(s) [${undeclared.join(', ')}] in its WGSL but its paramSchema does not declare them as texture entries. Add { name: '${undeclared[0]}', type: 'texture2d' } (and any others listed) to the paramSchema, or the engine would silently bind the default white texture (charter P3 explicit failure; see docs/handover/2026-06-19-blending-transparency-regression-bisect.md).`,
+        );
+      }
+    }
+    this.#materialShaders.set(
+      identifier,
+      Object.freeze({
+        source: entry.source,
+        paramSchema: paramSchemaProjection.schema,
+        paramSchemaProjection,
+      }),
+    );
+  }
+
+  /**
+   * Lookup a previously-registered material shader entry by identifier.
+   *
+   * Returns `Result.ok(entry)` on hit, `Result.err(material-shader-not-found)`
+   * on miss. The `Result` shape mirrors `get(hash)` for consistent
+   * abstraction across the runtime registry surface (charter P4).
+   *
+   * @example
+   * ```ts
+   * const r = registry.findMaterialArtifact('forgeax::default-standard-pbr');
+   * if (!r.ok) return handleError(r.error);
+   * const { source, paramSchema } = r.value;
+   * ```
+   */
+  findMaterialArtifact(
+    identifier: string,
+  ): ShaderResult<RegisteredMaterialShaderEntry, ShaderError> {
+    const entry = this.#materialShaders.get(identifier);
+    if (entry === undefined) {
+      return err(
+        materialShaderNotFound({
+          identifier,
+          expected: Array.from(this.#materialShaders.keys()),
+          hint: `register the shader via ShaderRegistry.installMaterialArtifact('${identifier}', ...) at engine boot, or grep '${FORGEAX_RESERVED_PATH_PREFIX}' to enumerate engine-shipped reserved identifiers`,
+        }),
+      );
+    }
+    return ok(entry);
+  }
+
+  /**
+   * Iterate every registered material shader identifier in registration
+   * order (charter F1 grep gate: `for (const id of registry.materialShaderIdentifiers())`
+   * lists every `forgeax::*` + user shader without a private-field reach-in).
+   */
+  materialShaderIdentifiers(): IterableIterator<string> {
+    return this.#materialShaders.keys();
+  }
+
+  /** Runtime diagnostic counters for the immutable ParamSchema owner. */
+  paramSchemaProjectionStats(): ParamSchemaProjectionOwnerStats {
+    return this.#paramSchemaProjectionOwner.stats();
+  }
+
+  /**
+   * Iterate every MaterialShaderManifestEntry parsed from manifest.json's
+   * `materialShaders[]` field during `loadManifest()`.
+   *
+   * feat-20260526-pbr-uniform-fallback-no-storage-buffer M3 / w12:
+   * createRenderer variant resolution consumes this list to select the
+   * correct variant (by `caps.storageBuffer`) and register the resolved
+   * WGSL via `installMaterialArtifact`.
+   *
+   * Returns an empty iterator when no manifest has been loaded yet or
+   * the manifest lacks `materialShaders` (backward-compatible).
+   */
+  materialShaderManifestEntries(): IterableIterator<MaterialShaderManifestEntry> {
+    return this.#materialShaderManifestEntries.values();
+  }
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────────────
+
+function isValidManifestEntry(value: unknown): value is ManifestEntry {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.hash !== 'string') return false;
+  if (typeof v.wgsl !== 'string') return false;
+  // glsl allows string | undefined | null (manifest.json may serialize null as
+  // 'glsl: null').
+  if (v.glsl !== undefined && v.glsl !== null && typeof v.glsl !== 'string') return false;
+  if (typeof v.bindings !== 'string') return false;
+  return true;
+}
+
+function isValidMaterialShaderManifestEntry(value: unknown): value is MaterialShaderManifestEntry {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.identifier !== 'string') return false;
+  if (typeof v.sourcePath !== 'string') return false;
+  if (typeof v.composedWgsl !== 'string') return false;
+  if (typeof v.paramSchema !== 'string') return false;
+  if (!Array.isArray(v.variants)) return false;
+  if (!v.variants.every(isValidMaterialShaderManifestVariant)) return false;
+  return v.uvSetCount === undefined || typeof v.uvSetCount === 'number';
+}
+
+function isValidMaterialShaderManifestVariant(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.definesKey !== 'string') return false;
+  if (typeof v.composedWgsl !== 'string') return false;
+  if (typeof v.defines !== 'object' || v.defines === null || Array.isArray(v.defines)) {
+    return false;
+  }
+  return Object.values(v.defines).every((define) => typeof define === 'boolean');
+}

package/src/__tests__/atmosphere-background.test.ts

@@ -0,0 +1,33 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+let source = '';
+
+beforeAll(async () => {
+  const fs = await import(/* @vite-ignore */ 'node:fs');
+  const path = await import(/* @vite-ignore */ 'node:path');
+  const url = await import(/* @vite-ignore */ 'node:url');
+  source = fs.readFileSync(
+    path.resolve(
+      path.dirname(url.fileURLToPath(import.meta.url)),
+      '..',
+      'atmosphere-background.wgsl',
+    ),
+    'utf8',
+  );
+});
+
+describe('analytic atmosphere background ray and disc', () => {
+  it('reconstructs a camera-relative world ray before comparing the Sun direction', () => {
+    expect(source).toMatch(/world\.xyz\s*\/\s*world\.w\s*-\s*view\.cameraPos/);
+    expect(source).toContain('atmosphere_sun_disc_radiance');
+    expect(source).toMatch(/dot\(normalize\(viewDirection\),\s*normalize\(sunDirection\)\)/);
+  });
+
+  it('keeps the Sun disc out of the generated cube and IBL path', () => {
+    expect(source).toContain('sunDiscEnabled');
+    expect(source).toContain('atmosphere.sunDirection.y > 0.0');
+    expect(source).toContain('solidAngle');
+    expect(source).toContain('textureSample(sky, skySampler, cubeDirection)');
+    expect(source).toContain('vec3<f32>(direction.x, -direction.y, direction.z)');
+  });
+});

package/src/__tests__/atmosphere-cubemap-orientation.test.ts

@@ -0,0 +1,68 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+type Direction = readonly [number, number, number];
+
+let cubeSource = '';
+let iblSource = '';
+
+beforeAll(async () => {
+  const fs = await import(/* @vite-ignore */ 'node:fs');
+  const path = await import(/* @vite-ignore */ 'node:path');
+  const url = await import(/* @vite-ignore */ 'node:url');
+  const shaderRoot = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
+  cubeSource = fs.readFileSync(path.resolve(shaderRoot, 'atmosphere-cubemap.wgsl'), 'utf8');
+  iblSource = fs.readFileSync(path.resolve(shaderRoot, 'atmosphere-ibl.wgsl'), 'utf8');
+});
+
+function worldDirection(face: number, x: number, y: number): Direction {
+  switch (face) {
+    case 0:
+      return [1, -y, -x];
+    case 1:
+      return [-1, -y, x];
+    case 2:
+      return [x, -1, -y];
+    case 3:
+      return [x, 1, y];
+    case 4:
+      return [x, -y, 1];
+    default:
+      return [-x, -y, -1];
+  }
+}
+
+function sameDirection(left: Direction, right: Direction): boolean {
+  return left.every((value, index) => Math.abs(value - (right[index] ?? 0)) < 1e-8);
+}
+
+describe('analytic cubemap world-direction convention', () => {
+  it('keeps every sampled face edge continuous with another face', () => {
+    const samples = [-1, -0.5, 0, 0.5, 1];
+    const edges: { readonly face: number; readonly direction: Direction }[] = [];
+    for (let face = 0; face < 6; face += 1) {
+      for (const sample of samples) {
+        edges.push({ face, direction: worldDirection(face, -1, sample) });
+        edges.push({ face, direction: worldDirection(face, 1, sample) });
+        edges.push({ face, direction: worldDirection(face, sample, -1) });
+        edges.push({ face, direction: worldDirection(face, sample, 1) });
+      }
+    }
+    for (const edge of edges) {
+      expect(
+        edges.some(
+          (candidate) =>
+            candidate.face !== edge.face && sameDirection(candidate.direction, edge.direction),
+        ),
+      ).toBe(true);
+    }
+  });
+
+  it('pins the corrected Y faces and applies the same convention to IBL', () => {
+    for (const source of [cubeSource, iblSource]) {
+      expect(source).toContain('case 2u: { output.direction = vec3<f32>(x, -1.0, -y); }');
+      expect(source).toContain('case 3u: { output.direction = vec3<f32>(x, 1.0, y); }');
+    }
+    expect(iblSource).toContain('-sampleDirection.y');
+    expect(iblSource).toContain('-lightDirection.y');
+  });
+});