@jgengine/core 0.10.0 → 0.11.0

package/dist/random/pick.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pick one item uniformly at random from `items` using `rng` (a `() => number` in `[0, 1)`); returns undefined when empty.
+ *
+ * @capability weighted-pick pick one item from a set with an injected random source
+ */
+export declare function pickUniform<T>(rng: () => number, items: readonly T[]): T | undefined;
+/** Pick one item with probability proportional to `weightOf(item)`; skips non-positive weights, returns undefined when nothing is eligible. */
+export declare function pickWeighted<T>(rng: () => number, items: readonly T[], weightOf: (item: T) => number): T | undefined;

package/dist/random/pick.js

@@ -0,0 +1,31 @@
+/**
+ * Pick one item uniformly at random from `items` using `rng` (a `() => number` in `[0, 1)`); returns undefined when empty.
+ *
+ * @capability weighted-pick pick one item from a set with an injected random source
+ */
+export function pickUniform(rng, items) {
+    if (items.length === 0)
+        return undefined;
+    return items[Math.min(items.length - 1, Math.floor(rng() * items.length))];
+}
+/** Pick one item with probability proportional to `weightOf(item)`; skips non-positive weights, returns undefined when nothing is eligible. */
+export function pickWeighted(rng, items, weightOf) {
+    let total = 0;
+    for (const item of items) {
+        const weight = weightOf(item);
+        if (weight > 0)
+            total += weight;
+    }
+    if (total <= 0)
+        return undefined;
+    let roll = rng() * total;
+    for (const item of items) {
+        const weight = weightOf(item);
+        if (weight <= 0)
+            continue;
+        roll -= weight;
+        if (roll <= 0)
+            return item;
+    }
+    return items[items.length - 1];
+}

package/dist/random/rng.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Deterministic 32-bit FNV-1a hash of a string → unsigned int. Same text, same number, on every
+ * platform — the stable seed behind per-id jitter, spread offsets, and content-addressed variation.
+ */
+export declare function hashString(text: string): number;
+/**
+ * Opaque, serializable PRNG cursor for state machines that must persist their own random stream
+ * (a spawn director, a heat/pursuit meter) instead of holding a closure — the state round-trips
+ * through save/load and multiplayer sync, so it can't carry a function. Never read or do
+ * arithmetic on the raw value directly; thread it through {@link stepRandomSeed} only.
+ */
+export type RandomSeed = number & {
+    readonly __randomSeed: unique symbol;
+};
+/** Wraps an already-integer seed (e.g. a `config.seed`) as a {@link RandomSeed} — no hashing. */
+export declare function randomSeedFrom(seed: number): RandomSeed;
+/**
+ * One step of the {@link seededRng} recurrence in pure (seed in, seed out) form — the same
+ * mulberry32-style generator, shared by every state machine that persists its own PRNG cursor
+ * instead of closing over a generator.
+ */
+export declare function stepRandomSeed(seed: RandomSeed): readonly [value: number, next: RandomSeed];
 /** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
 export declare function seededRng(seed: string | number): () => number;
 /** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */

package/dist/random/rng.js

@@ -1,5 +1,8 @@
-function hashSeed(seed) {
-    const text = typeof seed === "number" ? seed.toString() : seed;
+/**
+ * Deterministic 32-bit FNV-1a hash of a string → unsigned int. Same text, same number, on every
+ * platform — the stable seed behind per-id jitter, spread offsets, and content-addressed variation.
+ */
+export function hashString(text) {
     let h = 2166136261 >>> 0;
     for (let i = 0; i < text.length; i++) {
         h ^= text.charCodeAt(i);
@@ -7,15 +10,32 @@ function hashSeed(seed) {
     }
     return h >>> 0;
 }
+function hashSeed(seed) {
+    return hashString(typeof seed === "number" ? seed.toString() : seed);
+}
+/** Wraps an already-integer seed (e.g. a `config.seed`) as a {@link RandomSeed} — no hashing. */
+export function randomSeedFrom(seed) {
+    return (seed | 0);
+}
+/**
+ * One step of the {@link seededRng} recurrence in pure (seed in, seed out) form — the same
+ * mulberry32-style generator, shared by every state machine that persists its own PRNG cursor
+ * instead of closing over a generator.
+ */
+export function stepRandomSeed(seed) {
+    const next = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(next ^ (next >>> 15), 1 | next);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    const value = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    return [value, next];
+}
 /** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
 export function seededRng(seed) {
-    let a = hashSeed(seed) >>> 0;
+    let cursor = randomSeedFrom(hashSeed(seed));
     return () => {
-        a = (a + 0x6d2b79f5) >>> 0;
-        let t = a;
-        t = Math.imul(t ^ (t >>> 15), t | 1);
-        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        const [value, next] = stepRandomSeed(cursor);
+        cursor = next;
+        return value;
     };
 }
 /** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */

package/dist/random/seedLink.d.ts

@@ -1,5 +1,9 @@
 export declare const DEFAULT_SEED_PARAM = "seed";
+/** @internal */
 export declare function withSeedParam(url: string, seed: string | number, param?: string): string;
+/** @internal */
 export declare function seedFromSearch(search: string, param?: string): string | null;
+/** @internal */
 export declare function seedFromUrl(url: string, param?: string): string | null;
+/** @internal */
 export declare function dailySeed(nowMs: number, salt?: string): string;

package/dist/random/seedLink.js

@@ -8,6 +8,7 @@ function splitUrl(url) {
     const query = queryIndex === -1 ? "" : rest.slice(queryIndex + 1);
     return { base, query, hash };
 }
+/** @internal */
 export function withSeedParam(url, seed, param = DEFAULT_SEED_PARAM) {
     const { base, query, hash } = splitUrl(url);
     const params = new URLSearchParams(query);
@@ -15,16 +16,19 @@ export function withSeedParam(url, seed, param = DEFAULT_SEED_PARAM) {
     const queryString = params.toString();
     return `${base}${queryString ? `?${queryString}` : ""}${hash ? `#${hash}` : ""}`;
 }
+/** @internal */
 export function seedFromSearch(search, param = DEFAULT_SEED_PARAM) {
     const normalized = search.startsWith("?") ? search.slice(1) : search;
     const params = new URLSearchParams(normalized);
     const value = params.get(param);
     return value === null || value === "" ? null : value;
 }
+/** @internal */
 export function seedFromUrl(url, param = DEFAULT_SEED_PARAM) {
     const { query } = splitUrl(url);
     return seedFromSearch(query, param);
 }
+/** @internal */
 export function dailySeed(nowMs, salt) {
     const date = new Date(nowMs);
     const year = date.getUTCFullYear().toString().padStart(4, "0");

package/dist/relation/keyedValues.d.ts

@@ -0,0 +1,54 @@
+/** Optional inclusive `[min, max]` clamp applied after a write. Omit an edge for unbounded. */
+export interface NumericBounds {
+    readonly min?: number;
+    readonly max?: number;
+}
+/** Clamp a scalar to `bounds` (identity when `bounds` is omitted). Pure — touches no record. */
+export declare function clampValue(value: number, bounds?: NumericBounds): number;
+/** Current value for `key`, or `fallback` (default `0`) when the record has no entry. */
+export declare function getValue(record: Record<string, number>, key: string, fallback?: number): number;
+/**
+ * Set `key` to `value` (clamped to `bounds`), writing the record in place. Returns the stored value.
+ *
+ * @capability set a bounded keyed value in a caller-owned serializable record
+ */
+export declare function setValue(record: Record<string, number>, key: string, value: number, bounds?: NumericBounds): number;
+/** Add `delta` to `key` (clamped to `bounds`), writing the record in place. Returns the stored value. */
+export declare function addValue(record: Record<string, number>, key: string, delta: number, bounds?: NumericBounds): number;
+/**
+ * Step `key` toward `target` by at most `maxDelta` without overshooting, then clamp
+ * to `bounds`. Writes in place and returns the stored value.
+ *
+ * @capability move a keyed value toward a target by a bounded step
+ */
+export declare function towardValue(record: Record<string, number>, key: string, target: number, maxDelta: number, bounds?: NumericBounds): number;
+/**
+ * Decay `key` toward a `rest` value (default `0`) by `rate` per call — the common
+ * "relationships cool off" / "heat fades" drift. Thin wrapper over {@link towardValue}.
+ */
+export declare function driftValue(record: Record<string, number>, key: string, rate: number, rest?: number, bounds?: NumericBounds): number;
+/** Canonicalizes a two-part relation identity into a single delimiter-safe record key. */
+export interface PairKeyCodec {
+    /** `true` when order matters (a→b differs from b→a); `false` sorts the pair first. */
+    readonly directed: boolean;
+    /** Encode a pair into one record key. Undirected codecs canonicalize by sorting the two ids. */
+    key(a: string, b: string): string;
+    /** Recover the pair from a key. Undirected keys come back in canonical (sorted) order. */
+    parse(key: string): [string, string];
+}
+/** Direction and delimiter policy for {@link createPairKeyCodec}. */
+export interface PairKeyOptions {
+    /** `true` for ordered relations (rivalry-from, owes-to); default `false` (mutual). */
+    readonly directed?: boolean;
+    /** Single-character delimiter between encoded ids (default `"|"`). Collisions are escaped, not forbidden. */
+    readonly separator?: string;
+}
+/**
+ * Build a pair-key codec for keyed relation values. Ids are escaped before joining,
+ * so any id (including ones containing the separator or a backslash) round-trips
+ * through {@link PairKeyCodec.key} → {@link PairKeyCodec.parse} without collision.
+ * Undirected codecs (the default) canonicalize so `key(a, b) === key(b, a)`.
+ *
+ * @capability build a serializable directed/undirected pair key that resists delimiter collisions
+ */
+export declare function createPairKeyCodec(options?: PairKeyOptions): PairKeyCodec;

package/dist/relation/keyedValues.js

@@ -0,0 +1,115 @@
+/**
+ * Pure, serialization-friendly numeric operations over a caller-owned record of
+ * keyed values, plus delimiter-safe pair-key codecs for directed and undirected
+ * relations.
+ *
+ * No hidden state and no social semantics: the record, its bounds, drift rates,
+ * and keys are all caller data. Operations mutate the passed record in place and
+ * return the resulting value, so a game keeps one plain `Record<string, number>`
+ * it can serialize with `JSON.stringify` and restore verbatim. Pair keys are the
+ * injectable canonicalizer — compose `codec.key(a, b)` into any of the ops below.
+ */
+import { clamp, moveTowards } from "../math/scalar.js";
+function applyBounds(value, bounds) {
+    return clamp(value, bounds?.min ?? Number.NEGATIVE_INFINITY, bounds?.max ?? Number.POSITIVE_INFINITY);
+}
+/** Clamp a scalar to `bounds` (identity when `bounds` is omitted). Pure — touches no record. */
+export function clampValue(value, bounds) {
+    return applyBounds(value, bounds);
+}
+/** Current value for `key`, or `fallback` (default `0`) when the record has no entry. */
+export function getValue(record, key, fallback = 0) {
+    const stored = record[key];
+    return stored === undefined ? fallback : stored;
+}
+/**
+ * Set `key` to `value` (clamped to `bounds`), writing the record in place. Returns the stored value.
+ *
+ * @capability set a bounded keyed value in a caller-owned serializable record
+ */
+export function setValue(record, key, value, bounds) {
+    const next = applyBounds(value, bounds);
+    record[key] = next;
+    return next;
+}
+/** Add `delta` to `key` (clamped to `bounds`), writing the record in place. Returns the stored value. */
+export function addValue(record, key, delta, bounds) {
+    return setValue(record, key, getValue(record, key) + delta, bounds);
+}
+/**
+ * Step `key` toward `target` by at most `maxDelta` without overshooting, then clamp
+ * to `bounds`. Writes in place and returns the stored value.
+ *
+ * @capability move a keyed value toward a target by a bounded step
+ */
+export function towardValue(record, key, target, maxDelta, bounds) {
+    const step = maxDelta > 0 ? maxDelta : 0;
+    return setValue(record, key, moveTowards(getValue(record, key), target, step), bounds);
+}
+/**
+ * Decay `key` toward a `rest` value (default `0`) by `rate` per call — the common
+ * "relationships cool off" / "heat fades" drift. Thin wrapper over {@link towardValue}.
+ */
+export function driftValue(record, key, rate, rest = 0, bounds) {
+    return towardValue(record, key, rest, rate, bounds);
+}
+const ESCAPE = "\\";
+function escapeComponent(value, separator) {
+    let out = "";
+    for (const ch of value) {
+        if (ch === ESCAPE || ch === separator)
+            out += ESCAPE;
+        out += ch;
+    }
+    return out;
+}
+function splitEscaped(key, separator) {
+    const parts = [];
+    let current = "";
+    let escaped = false;
+    for (const ch of key) {
+        if (escaped) {
+            current += ch;
+            escaped = false;
+        }
+        else if (ch === ESCAPE) {
+            escaped = true;
+        }
+        else if (ch === separator) {
+            parts.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    parts.push(current);
+    return [parts[0] ?? "", parts[1] ?? ""];
+}
+/**
+ * Build a pair-key codec for keyed relation values. Ids are escaped before joining,
+ * so any id (including ones containing the separator or a backslash) round-trips
+ * through {@link PairKeyCodec.key} → {@link PairKeyCodec.parse} without collision.
+ * Undirected codecs (the default) canonicalize so `key(a, b) === key(b, a)`.
+ *
+ * @capability build a serializable directed/undirected pair key that resists delimiter collisions
+ */
+export function createPairKeyCodec(options = {}) {
+    const directed = options.directed ?? false;
+    const separator = options.separator ?? "|";
+    if (separator.length !== 1) {
+        throw new Error(`pair-key separator must be a single character, got ${JSON.stringify(separator)}`);
+    }
+    if (separator === ESCAPE)
+        throw new Error("pair-key separator cannot be the escape character '\\'");
+    return {
+        directed,
+        key(a, b) {
+            const [first, second] = directed || a <= b ? [a, b] : [b, a];
+            return `${escapeComponent(first, separator)}${separator}${escapeComponent(second, separator)}`;
+        },
+        parse(key) {
+            return splitEscaped(key, separator);
+        },
+    };
+}

package/dist/relation/thresholds.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Generic threshold-crossing detection over ordered numeric boundaries.
+ *
+ * Deliberately relationship-agnostic and stateless: the same helper reports
+ * reputation-tier transitions, meter milestones, temperature bands, ecosystem
+ * pressure, difficulty ramps, or any value moving across labelled cut points.
+ * Callers pass `before`/`after` and receive the crossings between them, so the
+ * logic never lives inside a ledger or owns hidden state.
+ */
+export type ThresholdDirection = "up" | "down";
+/** A labelled cut point on the value axis. `Id` is caller-owned (string, enum, or a policy object). */
+export interface ThresholdBoundary<Id = string> {
+    /** Stable identifier reported when this boundary is crossed. */
+    readonly id: Id;
+    /** Numeric position of the boundary on the value axis. */
+    readonly at: number;
+}
+/** A single boundary transition between a `before` and `after` value. */
+export interface ThresholdCrossing<Id = string> {
+    readonly id: Id;
+    readonly at: number;
+    readonly direction: ThresholdDirection;
+}
+/** Exact-boundary and dead-band policy for {@link crossThresholds}. */
+export interface CrossThresholdsOptions {
+    /**
+     * When true (default) a boundary is *occupied* at `value >= at`; when false it
+     * is occupied only at `value > at`. Controls exact-boundary semantics: with the
+     * default, landing exactly on `at` counts as an upward crossing and keeps you
+     * above on the way down.
+     */
+    readonly inclusive?: boolean;
+    /**
+     * Symmetric dead-band (clamped to `>= 0`). An upward crossing of `at` requires
+     * reaching `at + hysteresis`; a downward crossing requires falling below
+     * `at - hysteresis`. Suppresses flapping when a value oscillates around a
+     * boundary. Defaults to `0` (no dead-band).
+     */
+    readonly hysteresis?: number;
+}
+/**
+ * Report every boundary crossed moving from `before` to `after`.
+ *
+ * Upward moves yield `up` crossings in ascending `at` order; downward moves yield
+ * `down` crossings in descending order. Large jumps report every boundary passed;
+ * a zero-width move reports nothing. Boundaries need not be pre-sorted.
+ *
+ * @capability detect fire-once threshold/milestone/tier crossings when a value moves
+ */
+export declare function crossThresholds<Id>(boundaries: readonly ThresholdBoundary<Id>[], before: number, after: number, options?: CrossThresholdsOptions): ThresholdCrossing<Id>[];
+/**
+ * The highest boundary at-or-below `value` — the band the value currently sits in.
+ * Returns `null` when `value` is below every boundary. Boundaries need not be sorted.
+ *
+ * Tier labels stay caller policy: pass an `Id` object carrying whatever label,
+ * relation, or colour the game needs.
+ *
+ * @capability resolve the current tier/band label for a keyed or scalar value
+ */
+export declare function tierAt<Id>(boundaries: readonly ThresholdBoundary<Id>[], value: number, options?: {
+    readonly inclusive?: boolean;
+}): ThresholdBoundary<Id> | null;

package/dist/relation/thresholds.js

@@ -0,0 +1,62 @@
+/**
+ * Generic threshold-crossing detection over ordered numeric boundaries.
+ *
+ * Deliberately relationship-agnostic and stateless: the same helper reports
+ * reputation-tier transitions, meter milestones, temperature bands, ecosystem
+ * pressure, difficulty ramps, or any value moving across labelled cut points.
+ * Callers pass `before`/`after` and receive the crossings between them, so the
+ * logic never lives inside a ledger or owns hidden state.
+ */
+/**
+ * Report every boundary crossed moving from `before` to `after`.
+ *
+ * Upward moves yield `up` crossings in ascending `at` order; downward moves yield
+ * `down` crossings in descending order. Large jumps report every boundary passed;
+ * a zero-width move reports nothing. Boundaries need not be pre-sorted.
+ *
+ * @capability detect fire-once threshold/milestone/tier crossings when a value moves
+ */
+export function crossThresholds(boundaries, before, after, options = {}) {
+    if (after === before)
+        return [];
+    const inclusive = options.inclusive ?? true;
+    const margin = options.hysteresis !== undefined && options.hysteresis > 0 ? options.hysteresis : 0;
+    const rising = after > before;
+    const occupied = (value, edge) => (inclusive ? value >= edge : value > edge);
+    const crossings = [];
+    for (const boundary of boundaries) {
+        if (rising) {
+            const edge = boundary.at + margin;
+            if (!occupied(before, edge) && occupied(after, edge)) {
+                crossings.push({ id: boundary.id, at: boundary.at, direction: "up" });
+            }
+        }
+        else {
+            const edge = boundary.at - margin;
+            if (occupied(before, edge) && !occupied(after, edge)) {
+                crossings.push({ id: boundary.id, at: boundary.at, direction: "down" });
+            }
+        }
+    }
+    crossings.sort((a, b) => (rising ? a.at - b.at : b.at - a.at));
+    return crossings;
+}
+/**
+ * The highest boundary at-or-below `value` — the band the value currently sits in.
+ * Returns `null` when `value` is below every boundary. Boundaries need not be sorted.
+ *
+ * Tier labels stay caller policy: pass an `Id` object carrying whatever label,
+ * relation, or colour the game needs.
+ *
+ * @capability resolve the current tier/band label for a keyed or scalar value
+ */
+export function tierAt(boundaries, value, options = {}) {
+    const inclusive = options.inclusive ?? true;
+    let match = null;
+    for (const boundary of boundaries) {
+        const occupied = inclusive ? value >= boundary.at : value > boundary.at;
+        if (occupied && (match === null || boundary.at > match.at))
+            match = boundary;
+    }
+    return match;
+}

package/dist/render/color.d.ts

@@ -0,0 +1,12 @@
+/** Split a `#rrggbb` hex color into its `[r, g, b]` channels (0–255).
+ * @internal
+ */
+export declare function hexToRgb(hex: string): readonly [number, number, number];
+/** Combine `[r, g, b]` channels (0–255, rounded) into a `#rrggbb` hex string.
+ * @internal
+ */
+export declare function rgbToHex(r: number, g: number, b: number): string;
+/** Interpolate between two `#rrggbb` colors by fraction `t`, clamped to the endpoints.
+ * @internal
+ */
+export declare function mixHex(from: string, to: string, t: number): string;

package/dist/render/color.js

@@ -0,0 +1,26 @@
+/** Split a `#rrggbb` hex color into its `[r, g, b]` channels (0–255).
+ * @internal
+ */
+export function hexToRgb(hex) {
+    const value = Number.parseInt(hex.slice(1), 16);
+    return [(value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff];
+}
+/** Combine `[r, g, b]` channels (0–255, rounded) into a `#rrggbb` hex string.
+ * @internal
+ */
+export function rgbToHex(r, g, b) {
+    const value = ((Math.round(r) & 0xff) << 16) | ((Math.round(g) & 0xff) << 8) | (Math.round(b) & 0xff);
+    return `#${value.toString(16).padStart(6, "0")}`;
+}
+/** Interpolate between two `#rrggbb` colors by fraction `t`, clamped to the endpoints.
+ * @internal
+ */
+export function mixHex(from, to, t) {
+    if (t <= 0)
+        return from;
+    if (t >= 1)
+        return to;
+    const [fr, fg, fb] = hexToRgb(from);
+    const [tr, tg, tb] = hexToRgb(to);
+    return rgbToHex(fr + (tr - fr) * t, fg + (tg - fg) * t, fb + (tb - fb) * t);
+}

package/dist/render/lookPreset.d.ts

@@ -0,0 +1,41 @@
+import type { BackdropConfig, LightingConfig } from "../game/playableGame.js";
+import type { SkyEnvironmentConfig } from "../world/features.js";
+import type { PostProcessingConfig } from "./postProcessing.js";
+/**
+ * Named default-look preset composing the existing lighting/sky/fog/post knobs into one field.
+ * `"cinematic"` (the default when unset) draws a scene lit like a shipped game — a real day sky
+ * with a view-following shadow-casting sun + hemisphere fill, a network-free image-based-lighting
+ * environment so PBR surfaces catch soft reflections, and a tuned tone-map/bloom/AO/vignette post
+ * stack. `"flat"` opts out of the sky/IBL/post rig to the bare ambient+directional default (pre-#773).
+ * The upgraded default primitive materials — tuned roughness/metalness plus subtle procedural surface
+ * detail so un-modeled boxes/capsules stop reading as flat plastic — apply under both presets.
+ * @capability default-look one field that lights a scene like a shipped game (opt out with "flat")
+ */
+export type LookPreset = "cinematic" | "flat";
+/** Explicit graphics knobs a game may set; the preset only fills the ones left undefined. */
+export interface GameLookInput {
+    look?: LookPreset;
+    lighting?: LightingConfig;
+    backdrop?: BackdropConfig;
+    postProcessing?: PostProcessingConfig;
+    /** True when the world already declares its own sky — the preset then leaves the sky to the world. */
+    hasWorldSky?: boolean;
+}
+/** Concrete lighting/backdrop/post the shell renders after the preset has filled unset knobs. */
+export interface ResolvedGameLook {
+    lighting?: LightingConfig;
+    backdrop?: BackdropConfig;
+    postProcessing?: PostProcessingConfig;
+}
+/** A static day sky: a real dome plus the shell's view-following shadow-casting sun and hemisphere fill. */
+export declare const CINEMATIC_SKY: SkyEnvironmentConfig;
+/** Tuned tone-map + bloom + gentle SSAO + vignette/grade stack — the shipped-game post look. */
+export declare const CINEMATIC_POST_PROCESSING: PostProcessingConfig;
+/**
+ * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"cinematic"`, so a
+ * scene reads lit-like-a-game out of the box; `"flat"` passes the explicit knobs through untouched.
+ * Anything the game authored wins — the preset only fills unset knobs, and it never adds a sky when
+ * the world already owns one (so the sky's tuned sun/hemisphere serve as the lighting rig).
+ * @capability resolve-game-look expand a look preset into concrete lighting/backdrop/post knobs
+ */
+export declare function resolveGameLook(input: GameLookInput): ResolvedGameLook;

package/dist/render/lookPreset.js

@@ -0,0 +1,29 @@
+/** A static day sky: a real dome plus the shell's view-following shadow-casting sun and hemisphere fill. */
+export const CINEMATIC_SKY = { preset: "day" };
+/** Tuned tone-map + bloom + gentle SSAO + vignette/grade stack — the shipped-game post look. */
+export const CINEMATIC_POST_PROCESSING = {
+    toneMapping: "aces",
+    bloom: {},
+    ao: { intensity: 1.4 },
+    grade: {},
+};
+/**
+ * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"cinematic"`, so a
+ * scene reads lit-like-a-game out of the box; `"flat"` passes the explicit knobs through untouched.
+ * Anything the game authored wins — the preset only fills unset knobs, and it never adds a sky when
+ * the world already owns one (so the sky's tuned sun/hemisphere serve as the lighting rig).
+ * @capability resolve-game-look expand a look preset into concrete lighting/backdrop/post knobs
+ */
+export function resolveGameLook(input) {
+    const look = input.look ?? "cinematic";
+    if (look === "flat") {
+        return { lighting: input.lighting, backdrop: input.backdrop, postProcessing: input.postProcessing };
+    }
+    const sky = input.backdrop?.sky ?? (input.hasWorldSky === true ? undefined : CINEMATIC_SKY);
+    const backdrop = sky === input.backdrop?.sky ? input.backdrop : { ...input.backdrop, sky };
+    return {
+        lighting: input.lighting,
+        backdrop,
+        postProcessing: input.postProcessing ?? CINEMATIC_POST_PROCESSING,
+    };
+}

package/dist/render/postProcessing.d.ts

@@ -34,6 +34,17 @@ export interface GradeConfig {
     vignette?: number;
     /** Animated film-grain amplitude. Default 0.012. */
     grain?: number;
+    /** Chromatic-aberration RGB split, in fractions of the frame (~0..0.01), scaled toward the edges. Default 0 (off). */
+    chromaticAberration?: number;
+}
+/** Depth-of-field (bokeh) stage — throws the fore/background out of focus around a focus distance. */
+export interface DofConfig {
+    /** Focus distance from the camera in world units. Default 18. */
+    focus?: number;
+    /** Aperture — larger blurs a shallower slice more aggressively. Default 0.00025. */
+    aperture?: number;
+    /** Maximum blur radius, 0..1. Default 0.01. */
+    maxBlur?: number;
 }
 /**
  * Declarative post-processing chain (RenderPass → AO → Bloom → tone-map output →
@@ -52,5 +63,14 @@ export interface PostProcessingConfig {
     bloom?: BloomConfig | false;
     /** Ambient occlusion. Heavier than the other stages — omit or `false` on low-end targets. Default off (omitted). */
     ao?: AoConfig | false;
+    /** Depth-of-field / bokeh. Heavier stage — omit or `false` to skip. Default off (omitted). */
+    dof?: DofConfig | false;
     grade?: GradeConfig | false;
 }
+/**
+ * A cinematic "product shot" post preset — the full chain on (contact-AO, soft bloom, a warm film
+ * grade with vignette + a touch of grain + chromatic aberration). Meant for a `StudioStage` where a
+ * single parametric asset is framed on a backdrop, so every studio reads shipped, not intern-tier. DoF
+ * is left off by default (it needs a per-scene focus distance); set `dof` to enable it.
+ */
+export declare const STUDIO_STAGE_POST: PostProcessingConfig;

package/dist/render/postProcessing.js

@@ -1 +1,21 @@
-export {};
+/**
+ * A cinematic "product shot" post preset — the full chain on (contact-AO, soft bloom, a warm film
+ * grade with vignette + a touch of grain + chromatic aberration). Meant for a `StudioStage` where a
+ * single parametric asset is framed on a backdrop, so every studio reads shipped, not intern-tier. DoF
+ * is left off by default (it needs a per-scene focus distance); set `dof` to enable it.
+ */
+export const STUDIO_STAGE_POST = {
+    toneMapping: "aces",
+    exposure: 1.05,
+    bloom: { strength: 0.28, radius: 0.6, threshold: 0.8 },
+    ao: { radius: 1.4, intensity: 2.2, distanceFalloff: 3, blend: 1 },
+    grade: {
+        lift: [0.008, 0.008, 0.014],
+        gain: [1.05, 1.02, 0.98],
+        gamma: 0.96,
+        saturation: 1.12,
+        vignette: 0,
+        grain: 0.006,
+        chromaticAberration: 0.001,
+    },
+};