@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/systems/__tests__/transparent-sort.bench.ts

@@ -0,0 +1,218 @@
+// transparent-sort.bench.ts -- transparent-bucket sort 10k-entity p95 gate
+// (feat-20260520-2d-sprite-layer-mvp / M-4 / w27; AC-14).
+//
+// Scope (3 cases x 100 iterations each):
+//   - mode=0 layer-z   (horizontal side-scroller; sortValue = posZ)
+//   - mode=1 layer-y   (JRPG Y-sort foot pivot; sortValue = -(posY - pivotY * sizeY))
+//   - mode=2 layer-yz  (Don't-Starve / isometric blend;
+//                        sortValue = (posY - pivotY * sizeY) + yzAlpha * posZ)
+//
+// AC-14 contract (3 reproducibility anchors):
+//   1. deterministic seed via `createXorshift32(0xCAFE2026)` so the
+//      bench number is a function of the algorithm, not the test data
+//      (w26 + plan-strategy D-3 SSOT, zero npm dep).
+//   2. >= 100 iterations -> tinybench reports a stable p95 across the
+//      whole sample window; `BENCH_OPTS_RUNTIME` pins iterations: 100
+//      so KUBEELA_BENCH=fast does not silently shrink the sample below
+//      the AC floor.
+//   3. Working baseline (implementation phase, R1 F-2 audit trail):
+//      p95 ~ 3 ms / 10k entities on GitHub Actions ubuntu-latest 6 vCPU.
+//      Root cause is V8 closure overhead in Array.prototype.sort + JS
+//      comparator (10k * log2(10k) ~ 140k comparator invocations per
+//      iteration; each crosses the JS<->C++ bridge ~ 20-30 ns).
+//      package.json forgeax.metrics.bench.baseline.threshold = 5 ms
+//      (5_000_000 ns/op) tracks this working baseline.
+//
+//      plan-strategy §2 D-3's 0.5 ms p95 target is DEFERRED to
+//      `feat-future-transparent-sort-radix` (todos.json todo-140).
+//      The future algorithm rewrite (composite-key BigInt64Array.sort
+//      over `(layer << 32) | (sortValueQuantizedInt32 ^ 0x80000000)`,
+//      or a radix sort over the same packed int64) replaces the JS
+//      comparator with a typed-array sort that stays inside C++ and
+//      should clear the 0.5 ms bar. Until that lands, the bench guards
+//      the 5 ms working ceiling — a regression past 5 ms still fails
+//      `pnpm metrics:run` and surfaces a real perf cliff.
+//
+//      Closed-loop trail: ImplementReviewer R1 F-2 (judged "defer +
+//      todo + JSDoc audit trail") in
+//      `.forgeax-harness/forgeax-loop/feat-20260520-2d-sprite-layer-
+//      mvp/implement-review.md` §5 closes here.
+//
+// Fixture shape (10k entries; structurally identical to a real M-4 record
+// stage transparent bucket but with synthetic numbers):
+//   - layer    ~ uniform i32 in [-1000, 1000]
+//   - posX/Y/Z ~ uniform f64 in [0, 100)
+//   - pivotY   ~ uniform f64 in [0, 1]   (matches SpriteMaterialAsset.pivot[1] range)
+//   - sizeY    ~ uniform f64 in [0.5, 2] (matches world-scale-ish sprites)
+//   - sortKey  -- undefined for the base bench; the AC-14 measurement
+//                 does NOT inject overrides because the comparator must
+//                 evaluate the mode formula for every entry to measure
+//                 the worst case.
+//
+// Anchor: requirements §3 AC-14 + plan-strategy §2 D-3 / §5.4 verdict
+// gate / §7 M-4 acceptanceCheck. The active threshold SSOT lives in
+// packages/runtime/package.json#forgeax.metrics.bench.baseline.threshold
+// (5_000_000 ns/op working baseline; R1 F-2 defer note above).
+
+import { World } from '@forgeax/engine-ecs';
+import { bench, describe } from 'vitest';
+import type { TransparentEntry } from '../../../../render/src/systems/transparent-sort-config';
+import {
+  setTransparentSortConfig,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from '../../../../render/src/systems/transparent-sort-config';
+import { transparentSortEntries } from '../transparent-sort';
+import { createXorshift32 } from './_xorshift';
+
+// AC-14 sample size + iterations (plan-strategy D-3 SSOT). Vitest 4.x
+// forwards `iterations` straight to tinybench so the p95 statistic is
+// computed from a >= 100-sample window.
+const N_ENTITIES = 10_000;
+const BENCH_OPTS_RUNTIME = { iterations: 100 } as const;
+
+// Build the synthetic fixture once outside the bench body so allocation
+// cost stays out of the comparator-loop hot path (the math bench files
+// use the same closure pattern via vec3.create(...) above the bench
+// block). The same fixture is shared across all 3 mode benches so a
+// regression in one mode is directly comparable to the others.
+function buildEntries(): readonly TransparentEntry[] {
+  const rng = createXorshift32(0xcafe2026);
+  const out: TransparentEntry[] = new Array(N_ENTITIES);
+  for (let i = 0; i < N_ENTITIES; i++) {
+    const layer = Math.floor(rng() * 2001) - 1000;
+    out[i] = {
+      entityIndex: i,
+      materialHandle: 1024 + (i % 256),
+      layer,
+      posX: rng() * 100,
+      posY: rng() * 100,
+      posZ: rng() * 100,
+      pivotY: rng(),
+      sizeY: 0.5 + rng() * 1.5,
+    };
+  }
+  return out;
+}
+
+const ENTRIES = buildEntries();
+
+// Separate RNG for the mode=3 bench so the camera position does not
+// consume entropy from the entry pool. A second entries fixture with
+// a different seed avoids JIT-coupling the mode=3 bench noise to the
+// mode=0/1/2 bench noise.
+function buildEntriesDist(): readonly TransparentEntry[] {
+  const rng = createXorshift32(0x2dda7a6e);
+  const out: TransparentEntry[] = new Array(N_ENTITIES);
+  for (let i = 0; i < N_ENTITIES; i++) {
+    const layer = Math.floor(rng() * 2001) - 1000;
+    out[i] = {
+      entityIndex: i,
+      materialHandle: 1024 + (i % 256),
+      layer,
+      posX: rng() * 100,
+      posY: rng() * 100,
+      posZ: rng() * 100,
+      pivotY: rng(),
+      sizeY: 0.5 + rng() * 1.5,
+    };
+  }
+  return out;
+}
+
+const ENTRIES_DIST = buildEntriesDist();
+
+// independent RNG for per-iteration camera positions
+const rngDist = createXorshift32(0x9a88_e5b3);
+
+function makeWorld(mode: number): World {
+  const world = new World();
+  const r = setTransparentSortConfig(world, { mode, yzAlpha: 1.0 });
+  if (!r.ok) {
+    // Should be unreachable -- the three constants are by construction
+    // members of the valid {0, 1, 2} set. If this fires the fixture
+    // setup is broken at the harness level; bail loudly so a bench
+    // regression report is not silently meaningless.
+    throw new Error(`[transparent-sort.bench] setTransparentSortConfig failed: ${r.error.code}`);
+  }
+  return world;
+}
+
+describe('transparent-sort 10k entities', () => {
+  const worldZ = makeWorld(TRANSPARENT_SORT_MODE_LAYER_Z);
+  const worldY = makeWorld(TRANSPARENT_SORT_MODE_LAYER_Y);
+  const worldYZ = makeWorld(TRANSPARENT_SORT_MODE_LAYER_YZ);
+  const worldDist = makeWorld(3);
+  // Sink pattern (wiki/vitest-bench section 7.1): forces JIT to keep the
+  // sort result reachable; an unread return value is a dead-store
+  // candidate and the optimiser may then short-circuit the comparator
+  // visits inside Array.prototype.sort. The `_sink` prefix tags it
+  // explicitly as "write-only inside the loop, read once at teardown"
+  // so biome's noUnusedVariables rule does not flag it (we DO read it
+  // once below to satisfy lint + keep V8 from dead-storing).
+  let _sink = 0;
+
+  bench(
+    'mode=0 layer-z (horizontal)',
+    () => {
+      const out = transparentSortEntries(ENTRIES, worldZ);
+      // `?.entityIndex ?? 0` keeps the read total under
+      // noUncheckedIndexedAccess; `| 0` is the canonical int32 sink.
+      _sink ^= (out[0]?.entityIndex ?? 0) | 0;
+    },
+    BENCH_OPTS_RUNTIME,
+  );
+
+  bench(
+    'mode=1 layer-y (JRPG)',
+    () => {
+      const out = transparentSortEntries(ENTRIES, worldY);
+      _sink ^= (out[0]?.entityIndex ?? 0) | 0;
+    },
+    BENCH_OPTS_RUNTIME,
+  );
+
+  bench(
+    "mode=2 layer-yz (isometric / Don't-Starve)",
+    () => {
+      const out = transparentSortEntries(ENTRIES, worldYZ);
+      _sink ^= (out[0]?.entityIndex ?? 0) | 0;
+    },
+    BENCH_OPTS_RUNTIME,
+  );
+
+  // ─── w3: mode=3 distance bench (TDD red phase) ─────────────────────
+
+  // Red: setTransparentSortConfig rejects mode=3 (not yet in VALID_MODES).
+  // When green, the extra cost of 3 squared-distance ops per entry should
+  // add <0.05ms vs the ~3ms p95 baseline on 10k entries (research E4(c)).
+
+  bench(
+    'mode=3 distance (back-to-front squared-distance)',
+    () => {
+      const cameraPos: readonly [number, number, number] = [
+        rngDist() * 100,
+        rngDist() * 100,
+        rngDist() * 100,
+      ];
+      // Red: 3-arg signature does not exist yet; cast bridges the red gap.
+      const out = (
+        transparentSortEntries as (
+          entries: readonly TransparentEntry[],
+          world: World,
+          cameraPos?: readonly [number, number, number],
+        ) => readonly TransparentEntry[]
+      )(ENTRIES_DIST, worldDist, cameraPos);
+      _sink ^= (out[0]?.entityIndex ?? 0) | 0;
+    },
+    BENCH_OPTS_RUNTIME,
+  );
+
+  // Single teardown-time read keeps `_sink` from being a strict
+  // write-only target (lint + JIT both observe the value); the read
+  // path lives inside an arrow predicate so tinybench's harness
+  // never invokes it during the measurement window. Sink pattern
+  // (wiki/vitest-bench section 7.1).
+  void [() => _sink];
+});

package/src/systems/sprite-animation-tick.ts

@@ -0,0 +1,302 @@
+// @forgeax/engine-runtime - sprite-animation tick system (M4 / T-23).
+//
+// Walks every entity that carries `SpriteAnimation`, advances its dt
+// accumulator clock per Time.delta, and writes the current frame's UV slice
+// into the entity's `SpriteRegionOverride` column (auto-adding the
+// component on first observation when the entity does not yet carry it).
+// Designed to sit between `input` / `time` and `RenderSystem.extract` in
+// the schedule (plan-strategy section 2 D-7); the M3 sprite-bucket
+// extract branch (`render-system-extract.ts:861-870`) reads the override
+// column to materialise per-entity UV in the sprite snapshot.
+//
+// Why a stand-alone tick system instead of folding the dt accumulator
+// into the renderer? Charter P5 producer/consumer separation: the
+// renderer is a consumer of presentation state and never writes ECS
+// columns; the tick system owns the per-entity write so the
+// `SpriteRegionOverride.region` slot has exactly one writer (the tick
+// system) and zero readers in the writer tree (the extract branch is a
+// disjoint consumer). Plan-strategy section 1 + section 5 constraint #1
+// pin the boundary; this file is the producer half.
+//
+// Schedule positioning (informational; the App schedule is wired by the
+// host, not this file): input / time -> spriteAnimationTickSystem ->
+// RenderSystem.extract. The tick is `void`-returning under the
+// `Result<void, SpriteAnimationInvalidError>` shape so the schedule's
+// Layer-3 ErrorHandler observes a structured first-error signal without
+// the system aborting mid-pass on healthy entities (charter P3 explicit
+// failure + P4 consistent abstraction with `setTransparentSortConfig`'s
+// `Result<void, ResourceInvalidValueError>` shape).
+//
+// Invariants checked per-entity (AC-09 fail-fast paths; M1 T-05 added
+// `SpriteAnimationInvalidError`):
+//   - `regions.length === frameCount * 4` -> detail.field='regions-length'
+//   - `frameDuration > 0`                  -> detail.field='frame-duration'
+// First error wins; subsequent invalid entities still skip advance but
+// only the first surfaces in the returned Result.err. Healthy entities
+// continue to advance regardless of an invalid sibling (T-19 second
+// it() block locks this).
+//
+// Time.delta sourcing: `world.getResource(Time).delta`. When
+// the resource is missing (e.g. the tick system is invoked outside an
+// `App` rAF loop), dt defaults to 0 and the system runs as a no-op
+// schedule pass. Time.delta is already frame-loop clamped to a sane
+// ceiling by `@forgeax/engine-app frame-loop.ts`; the tick system MUST
+// NOT second-clamp (research F-3 + plan-strategy R-TIME-1). T-22 case
+// (1) feeds dt=30s directly to lock that contract.
+//
+// playbackMode dispatch: the per-entity `playbackMode: u32` column is
+// translated through `spritePlaybackModeFromU32` (M1 SSOT) into the
+// closed `'loop' | 'clamp'` literal union. The advance arm is selected
+// per-tick per-entity so AI users can mutate playbackMode at runtime
+// (e.g. swap LOOP for CLAMP on a death animation) and observe the
+// behavioural switch on the very next tick.
+//
+// Anchors: plan-strategy section 2 D-1 + D-5 + D-6 + D-7 + section 3.1
+// TICK + section 3.2 sequence diagram Tick->Ovr block + section 4 risk
+// R-TIME-1; plan-tasks.json T-23; requirements section 2.1 C system
+// surface + section AC-04 / AC-05 / AC-09 + section 7 boundary table;
+// charter P3 + P4 + P5 + F1.
+
+import { type EntityHandle, Time, type World } from '@forgeax/engine-ecs';
+import { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';
+import {
+  SpriteAnimation,
+  SpriteRegionOverride,
+  spritePlaybackModeFromU32,
+} from '@forgeax/engine-render/authoring';
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+/**
+ * Walk every entity carrying `SpriteAnimation`, advance its dt
+ * accumulator, and write the current frame's UV slice to the entity's
+ * `SpriteRegionOverride` column.
+ *
+ * Returns `Result<void, SpriteAnimationInvalidError>`:
+ *
+ * - `ok(void)` when every observed entity satisfies both invariants
+ *   (`regions.length === frameCount * 4` and `frameDuration > 0`) — the
+ *   pass advanced every entity normally.
+ * - `err(SpriteAnimationInvalidError)` carrying the FIRST entity-level
+ *   invariant violation observed during the pass. The offending entity
+ *   does not advance (its `currentFrame` / `accumDt` columns stay
+ *   untouched); every other healthy entity in the same pass still
+ *   advances normally so AI users observe a "fail one, advance the
+ *   rest" semantics rather than an all-or-nothing abort.
+ *
+ * The returned error is the canonical 4-field structured payload
+ * (`.code` / `.expected` / `.hint` / `.detail`) — narrow on
+ * `err.detail.field` (`'regions-length'` | `'frame-duration'`) to reach
+ * the per-arm recovery hint without parsing the message string
+ * (charter P3 + P4).
+ *
+ * @example Wire into an App schedule between input/time and the renderer:
+ * ```ts
+ * import { createApp } from '@forgeax/engine-app';
+ * import { spriteAnimationTickSystem } from '@forgeax/engine-runtime';
+ *
+ * const app = createApp({ canvas, schedule: { update: [
+ *   spriteAnimationTickSystem,
+ *   // ... other systems
+ * ] } });
+ * ```
+ *
+ * @example Handle the first-error-wins surface:
+ * ```ts
+ * const r = spriteAnimationTickSystem(world);
+ * if (!r.ok) {
+ *   // r.error.code === 'sprite-animation-invalid'
+ *   if (r.error.detail.field === 'regions-length') {
+ *     console.warn(`fix regions buffer length to ${r.error.detail.frameCount * 4}`);
+ *   }
+ * }
+ * ```
+ */
+export function spriteAnimationTickSystem(world: World): Result<void, SpriteAnimationInvalidError> {
+  const dt = world.getResource(Time).delta;
+
+  // Query filters entities carrying SpriteAnimation, so a World that never
+  // spawned the component naturally yields an empty entity set (the pass is a
+  // no-op).
+  // Two-pass to avoid mid-iteration archetype migration. The auto-add
+  // of `SpriteRegionOverride` migrates the entity into a new archetype
+  // (SA + SRO) which a single-pass query would re-visit later in the same
+  // pass — yielding double-advance
+  // for any entity that did not yet carry the override. Collecting
+  // every Entity handle first gives each entity a single tick.
+  const entities = collectAnimEntities(world);
+
+  let firstError: SpriteAnimationInvalidError | null = null;
+  for (const entity of entities) {
+    const entryError = tickEntity(world, entity, dt);
+    if (entryError !== null && firstError === null) {
+      firstError = entryError;
+    }
+  }
+
+  if (firstError !== null) {
+    return err(firstError);
+  }
+  return ok(undefined);
+}
+
+/**
+ * First pass: collect every Entity handle from the ECS Query projection.
+ * Handles remain valid across subsequent migrations because they are stable
+ * index+generation identities, not archetype-row pointers.
+ */
+function collectAnimEntities(world: World): EntityHandle[] {
+  const queryResult = world.query({ with: [SpriteAnimation] });
+  if (!queryResult.ok) return [];
+  const entities: EntityHandle[] = [];
+  for (const row of queryResult.value) entities.push(row.entity);
+  return entities;
+}
+
+/**
+ * Second pass: validate one entity's `SpriteAnimation` invariants,
+ * advance its dt accumulator, and write the per-frame UV slice into
+ * `SpriteRegionOverride`. Returns `null` when the entity advanced
+ * normally; returns a structured `SpriteAnimationInvalidError` instance
+ * when the entity's row violates an invariant (the caller stitches the
+ * first such error into the system's Result.err).
+ */
+function tickEntity(
+  world: World,
+  entity: EntityHandle,
+  dt: number,
+): SpriteAnimationInvalidError | null {
+  const snapRes = world.get(entity, SpriteAnimation);
+  if (!snapRes.ok) {
+    // Defensive: the alive-record check inside world.get already guards
+    // stale handles; reaching here means something racier (component
+    // sweep removed the column mid-pass). Skip silently — the route is
+    // engine-internal, not an AI-user-visible failure mode.
+    return null;
+  }
+  const snap = snapRes.value;
+  const frameCount = snap.frameCount;
+  const frameDuration = snap.frameDuration;
+  const regions = snap.regions;
+
+  // Invariant: regions.length === frameCount * 4 (D-1 fail-fast,
+  // T-19 covers).
+  if (regions.length !== frameCount * 4) {
+    return new SpriteAnimationInvalidError({
+      field: 'regions-length',
+      regionsLength: regions.length,
+      frameCount,
+    });
+  }
+  // Invariant: frameDuration > 0 (covers both === 0 and < 0; T-20 +
+  // T-21 lock both arms to the same .detail.field='frame-duration'
+  // branch — charter P4 consistent abstraction).
+  if (!(frameDuration > 0)) {
+    return new SpriteAnimationInvalidError({
+      field: 'frame-duration',
+      frameDuration,
+    });
+  }
+
+  const advanced = advanceFrame(
+    snap.currentFrame,
+    snap.accumDt + dt,
+    frameDuration,
+    frameCount,
+    snap.playbackMode,
+  );
+
+  // Write the new clock state. Partial set leaves regions / frameCount
+  // / frameDuration / playbackMode untouched (world.set iterates
+  // Object.keys(value)).
+  const writeAnim = world.set(entity, SpriteAnimation, {
+    currentFrame: advanced.currentFrame,
+    accumDt: advanced.accumDt,
+  });
+  if (!writeAnim.ok) return null;
+
+  // Materialise the per-frame UV slice into SpriteRegionOverride.
+  // The slice is guaranteed to be 4 floats by the regions-length
+  // invariant above. A fresh Float32Array is allocated per write so
+  // the column owner's BufferPool slot does not alias the
+  // SpriteAnimation.regions backing array (charter P5 producer
+  // boundary: the override slot is a snapshot, not a view).
+  const sliceStart = advanced.currentFrame * 4;
+  const region = new Float32Array([
+    regions[sliceStart] ?? 0,
+    regions[sliceStart + 1] ?? 0,
+    regions[sliceStart + 2] ?? 0,
+    regions[sliceStart + 3] ?? 0,
+  ]);
+  writeOverride(world, entity, region);
+  return null;
+}
+
+/**
+ * Advance `currentFrame` / `accumDt` per the dt accumulator clock model
+ * (research F-3 + plan-strategy section 2 D-5). `dt` is the
+ * already-frame-loop-clamped Time.delta; the inner while-loop drains
+ * frameDuration units one at a time. The playbackMode discriminator
+ * picks LOOP (wrap) vs CLAMP (halt at last frame) per-tick per-entity
+ * (D-5).
+ */
+function advanceFrame(
+  currentFrameIn: number,
+  accumDtIn: number,
+  frameDuration: number,
+  frameCount: number,
+  playbackModeRaw: number,
+): { currentFrame: number; accumDt: number } {
+  let currentFrame = currentFrameIn;
+  let accumDt = accumDtIn;
+  const playback = spritePlaybackModeFromU32(playbackModeRaw);
+  while (accumDt >= frameDuration) {
+    accumDt -= frameDuration;
+    switch (playback) {
+      case 'loop': {
+        currentFrame = (currentFrame + 1) % frameCount;
+        break;
+      }
+      case 'clamp': {
+        // `min(currentFrame + 1, frameCount - 1)`; once at the last
+        // frame the index stops advancing. The accumDt subtraction
+        // continues so the residue does not pile up across ticks (T-18
+        // second it() block + T-22 case (2b) lock the halt).
+        if (currentFrame < frameCount - 1) {
+          currentFrame += 1;
+        }
+        break;
+      }
+    }
+  }
+  return { currentFrame, accumDt };
+}
+
+/**
+ * Write the per-entity UV region into `SpriteRegionOverride`,
+ * add-or-set with no registration-concept probe.
+ *
+ * `addComponent` is the registration-agnostic entry point: it auto-adds
+ * the `SpriteRegionOverride` column on first use, so a World that only ever
+ * spawned `SpriteAnimation` reaches the override column through this single
+ * call (requirements section 7 boundary table row 2 / charter P3). When the
+ * entity already carries the column, `addComponent` returns
+ * `err(component-already-present)` — the steady-state signal — and we
+ * `set` the region in place. `SpriteRegionOverride` declares no
+ * relationship, so the exclusive auto-reparent arm of `addComponent`
+ * never fires and `component-already-present` is the only present-case
+ * outcome.
+ *
+ * This replaces the former `_getComponentByName` registration gate: the
+ * "is it registered" question is no longer asked at all — `addComponent`
+ * owns registration, and column presence is read from its structured
+ * `Result` rather than a per-World registry lookup.
+ */
+function writeOverride(world: World, entity: EntityHandle, region: Float32Array): void {
+  const added = world.addComponent(entity, {
+    component: SpriteRegionOverride,
+    data: { region },
+  });
+  if (!added.ok && added.error.code === 'component-already-present') {
+    world.set(entity, SpriteRegionOverride, { region });
+  }
+}

package/src/systems/tonemap.ts

@@ -0,0 +1,68 @@
+// @forgeax/engine-runtime - TS port of the WGSL luminance Reinhard
+// extended tonemap (feat-20260519-tonemap-reinhard-mvp / M3 / T-M3.2).
+//
+// Mirrors the fragment-stage formula in `packages/shader/src/tonemap.wgsl`
+// byte-for-byte so AI users (and tests) can predict GPU output without
+// allocating a device:
+//
+//   exposed = L_in * exposure
+//   Y       = dot(exposed, vec3(0.2126, 0.7152, 0.0722))   // Rec. 709
+//   Y_prime = Y * (1 + Y / (Lw * Lw)) / (1 + Y)
+//   scale   = Y_prime / max(Y, TONEMAP_LUMINANCE_EPSILON)
+//   L_out   = exposed * scale
+//
+// The `max(Y, TONEMAP_LUMINANCE_EPSILON)` floor keeps the divisor finite
+// at degenerate inputs (`Y = 0` from black pixels, `Y < 0` from numerical
+// artefacts). The constant is shared with the WGSL fragment via
+// `@forgeax/engine-shader#TONEMAP_LUMINANCE_EPSILON` (D-O3 single SSOT;
+// `1e-5`).
+
+import { TONEMAP_LUMINANCE_EPSILON } from '@forgeax/engine-shader';
+
+/** Rec. 709 luminance weights — match the `vec3(0.2126, 0.7152, 0.0722)`
+ *  literal in `packages/shader/src/tonemap.wgsl` byte-for-byte. */
+export const REC709_LUMA_WEIGHTS = Object.freeze([0.2126, 0.7152, 0.0722] as const);
+
+/**
+ * Compute the post-tonemap LDR colour for a single linear HDR sample.
+ *
+ * Pure function: no GPU device, no allocation cost beyond the 3-element
+ * tuple return. Tests use this to assert the shader-side formula without
+ * spinning up a real adapter (charter proposition 5 consistent abstraction
+ * — TS port and WGSL fragment share the constant + the formula).
+ *
+ * @param l_in    Linear HDR sample as `[r, g, b]` (typically read out of
+ *                an `rgba16float` colour attachment).
+ * @param exposure Pre-multiplier applied before the luminance computation.
+ *                 Values <= 0 are still safe — the floor on Y guarantees
+ *                 a finite result (NaN / Inf cannot escape).
+ * @param whitePoint Bright-end break point Lw. Values <= 0 fall through
+ *                   the same floor; large values approach the basic
+ *                   Reinhard curve `Y / (1 + Y)`.
+ *
+ * @returns Tonemapped LDR colour as `[r, g, b]`. Each channel is finite
+ *          provided `l_in` is finite; clamp to `[0, 1]` at the call site
+ *          if the consumer needs strict swap-chain bounds.
+ */
+export function tonemapReinhardLuminance(
+  l_in: readonly [number, number, number],
+  exposure: number,
+  whitePoint: number,
+): [number, number, number] {
+  const exposedR = (l_in[0] ?? 0) * exposure;
+  const exposedG = (l_in[1] ?? 0) * exposure;
+  const exposedB = (l_in[2] ?? 0) * exposure;
+
+  const wR = REC709_LUMA_WEIGHTS[0];
+  const wG = REC709_LUMA_WEIGHTS[1];
+  const wB = REC709_LUMA_WEIGHTS[2];
+
+  const luma = exposedR * wR + exposedG * wG + exposedB * wB;
+  const lwSq = whitePoint * whitePoint;
+  const lumaPrime = (luma * (1 + luma / lwSq)) / (1 + luma);
+  const scale = lumaPrime / Math.max(luma, TONEMAP_LUMINANCE_EPSILON);
+
+  return [exposedR * scale, exposedG * scale, exposedB * scale];
+}
+
+export { TONEMAP_LUMINANCE_EPSILON } from '@forgeax/engine-shader';