@jgengine/core 0.18.0 → 0.19.0

package/dist/physics/worldColliders.d.ts

@@ -0,0 +1,13 @@
+import type { GameContext } from "../runtime/gameContextTypes.js";
+import type { PhysicsBackend } from "./physicsBackend.js";
+/** Handle for synchronizing authored static world collision with a physics backend. */
+export interface WorldColliderSync {
+    /** Rebuild static terrain and object bodies from the current context. */
+    sync(): void;
+    /** Remove all bodies owned by this synchronizer and stop reacting to scene changes. */
+    dispose(): void;
+}
+/** Mirrors static scene-object physical colliders, `ctx.world.solids` and the context's ground field into a physics backend.
+ * @capability world-physics-colliders Synchronize terrain and authored static colliders with a physics backend.
+ */
+export declare function syncWorldColliders(backend: PhysicsBackend, ctx: GameContext): WorldColliderSync;

package/dist/physics/worldColliders.js

@@ -0,0 +1,128 @@
+import { colliderWorldCenter, resolveColliders } from "../scene/colliders.js";
+const TERRAIN_SEGMENTS = 32;
+function bodyShape(shape) {
+    if (shape.kind === "sphere")
+        return { kind: "sphere", radius: shape.radius };
+    if (shape.kind === "aabb")
+        return { kind: "box", halfExtents: shape.halfExtents };
+    return { kind: "trimesh", vertices: shape.mesh.positions, indices: shape.mesh.indices };
+}
+function bodyPosition(shape, position, rotationY) {
+    return colliderWorldCenter({ name: "body", purpose: "physical", shape, damageEligible: false, blocks: true }, position, rotationY);
+}
+/** Mirrors static scene-object physical colliders, `ctx.world.solids` and the context's ground field into a physics backend.
+ * @capability world-physics-colliders Synchronize terrain and authored static colliders with a physics backend.
+ */
+export function syncWorldColliders(backend, ctx) {
+    const objectBodies = new Map();
+    const solidBodies = [];
+    let solidsVersion = -1;
+    let terrainBody = null;
+    let disposed = false;
+    function rebuildTerrain() {
+        if (terrainBody !== null)
+            backend.removeBody(terrainBody);
+        terrainBody = null;
+        const bounds = ctx.world.ground.bounds;
+        if (bounds === undefined)
+            return;
+        const columns = TERRAIN_SEGMENTS + 1;
+        const rows = TERRAIN_SEGMENTS + 1;
+        const heights = new Float32Array(columns * rows);
+        for (let row = 0; row < rows; row += 1) {
+            const z = -bounds.d / 2 + (row / TERRAIN_SEGMENTS) * bounds.d;
+            for (let column = 0; column < columns; column += 1) {
+                const x = -bounds.w / 2 + (column / TERRAIN_SEGMENTS) * bounds.w;
+                heights[row * columns + column] = ctx.world.ground.sampleHeight(x, z);
+            }
+        }
+        terrainBody = backend.addBody({
+            shape: { kind: "heightfield", rows, columns, heights, scale: [bounds.w / TERRAIN_SEGMENTS, 1, bounds.d / TERRAIN_SEGMENTS] },
+            position: [0, 0, 0],
+            kind: "static",
+            userData: { kind: "terrain" },
+        });
+    }
+    function syncObject(objectId) {
+        const old = objectBodies.get(objectId);
+        if (old !== undefined) {
+            backend.removeBody(old);
+            objectBodies.delete(objectId);
+        }
+        const object = ctx.scene.object.get(objectId);
+        if (object === null)
+            return;
+        const body = resolveColliders(ctx.scene.object.collidersOf(objectId)).find((collider) => collider.purpose === "physical");
+        if (body === undefined)
+            return;
+        const handle = backend.addBody({
+            shape: bodyShape(body.shape),
+            position: bodyPosition(body.shape, object.position, object.rotationY),
+            rotation: [0, Math.sin(object.rotationY / 2), 0, Math.cos(object.rotationY / 2)],
+            kind: "static",
+            userData: { kind: "object", instanceId: object.instanceId, catalogId: object.catalogId },
+        });
+        objectBodies.set(objectId, handle);
+    }
+    function syncSolids() {
+        const solids = ctx.world.solids;
+        if (solids.version() === solidsVersion)
+            return;
+        solidsVersion = solids.version();
+        for (const handle of solidBodies)
+            backend.removeBody(handle);
+        solidBodies.length = 0;
+        for (const layer of solids.layers()) {
+            for (const solid of solids.layer(layer)) {
+                const yaw = solid.rotationY ?? 0;
+                solidBodies.push(backend.addBody({
+                    shape: { kind: "box", halfExtents: [solid.halfExtents[0], solid.halfExtents[1], solid.halfExtents[2]] },
+                    position: [solid.center[0], solid.center[1], solid.center[2]],
+                    rotation: [0, Math.sin(yaw / 2), 0, Math.cos(yaw / 2)],
+                    kind: "static",
+                    userData: { kind: "solid", layer },
+                }));
+            }
+        }
+    }
+    function sync() {
+        if (disposed)
+            return;
+        rebuildTerrain();
+        syncSolids();
+        const ids = new Set(ctx.scene.object.ids());
+        for (const [objectId, handle] of objectBodies) {
+            if (!ids.has(objectId)) {
+                backend.removeBody(handle);
+                objectBodies.delete(objectId);
+            }
+        }
+        for (const objectId of ids)
+            syncObject(objectId);
+    }
+    const unsubscribeObjects = ctx.scene.object.subscribe(sync);
+    const unsubscribeSolids = ctx.world.solids.subscribe(() => {
+        if (!disposed)
+            syncSolids();
+    });
+    sync();
+    return {
+        sync,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            unsubscribeObjects();
+            unsubscribeSolids();
+            for (const handle of solidBodies)
+                backend.removeBody(handle);
+            solidBodies.length = 0;
+            if (terrainBody !== null)
+                backend.removeBody(terrainBody);
+            terrainBody = null;
+            for (const handle of objectBodies.values())
+                backend.removeBody(handle);
+            objectBodies.clear();
+        },
+    };
+}

package/dist/puzzle/cellGrid.d.ts

@@ -1,8 +1,10 @@
+/** A fixed-size 2D board of cells, row-major from the top-left; `null` is an empty cell. Plain data, so it serializes and restores as-is. */
 export interface CellGrid<T> {
     readonly width: number;
     readonly height: number;
     readonly cells: readonly (T | null)[];
 }
+/** A straight line of matching cells found by {@link findRuns}. */
 export interface CellRun<T> {
     readonly value: T;
     readonly cells: readonly {
@@ -11,25 +13,29 @@ export interface CellRun<T> {
     }[];
     readonly direction: "row" | "column";
 }
-/** @internal */
+/**
+ * An empty `width` × `height` board. Every helper here returns a new grid, so a store slot can hold it
+ * and undo, replay, and save/restore work without copying.
+ * @capability cell-grid immutable 2D board of cells with row clears, gravity collapse, and match runs
+ */
 export declare function createCellGrid<T>(width: number, height: number): CellGrid<T>;
-/** @internal */
+/** Whether `(x, y)` lies on the board. */
 export declare function inGridBounds<T>(grid: CellGrid<T>, x: number, y: number): boolean;
-/** @internal */
+/** The value at `(x, y)`, or `null` when empty or off the board. */
 export declare function cellAt<T>(grid: CellGrid<T>, x: number, y: number): T | null;
-/** @internal */
+/** A copy with `(x, y)` set to `value`; off-board writes return the grid unchanged. */
 export declare function withCell<T>(grid: CellGrid<T>, x: number, y: number, value: T | null): CellGrid<T>;
-/** @internal */
+/** A copy with every in-bounds entry written; one allocation for a whole piece or stamp. */
 export declare function withCells<T>(grid: CellGrid<T>, entries: readonly {
     readonly x: number;
     readonly y: number;
     readonly value: T | null;
 }[]): CellGrid<T>;
-/** @internal */
+/** Indices of rows with no empty cell, top to bottom. */
 export declare function fullRows<T>(grid: CellGrid<T>): number[];
-/** @internal */
+/** A copy with `rows` removed and the rows above shifted down, refilling empty rows at the top. */
 export declare function clearRows<T>(grid: CellGrid<T>, rows: readonly number[]): CellGrid<T>;
-/** @internal */
+/** A copy where every column's cells fall to the bottom, keeping their order. */
 export declare function collapseColumns<T>(grid: CellGrid<T>): CellGrid<T>;
-/** @internal */
+/** Horizontal and vertical runs of at least `minLength` cells whose values `matches` (default `===`). */
 export declare function findRuns<T>(grid: CellGrid<T>, minLength: number, matches?: (a: T, b: T) => boolean): CellRun<T>[];

package/dist/puzzle/cellGrid.js

@@ -1,18 +1,22 @@
-/** @internal */
+/**
+ * An empty `width` × `height` board. Every helper here returns a new grid, so a store slot can hold it
+ * and undo, replay, and save/restore work without copying.
+ * @capability cell-grid immutable 2D board of cells with row clears, gravity collapse, and match runs
+ */
 export function createCellGrid(width, height) {
     return { width, height, cells: new Array(width * height).fill(null) };
 }
-/** @internal */
+/** Whether `(x, y)` lies on the board. */
 export function inGridBounds(grid, x, y) {
     return x >= 0 && x < grid.width && y >= 0 && y < grid.height;
 }
-/** @internal */
+/** The value at `(x, y)`, or `null` when empty or off the board. */
 export function cellAt(grid, x, y) {
     if (!inGridBounds(grid, x, y))
         return null;
     return grid.cells[y * grid.width + x] ?? null;
 }
-/** @internal */
+/** A copy with `(x, y)` set to `value`; off-board writes return the grid unchanged. */
 export function withCell(grid, x, y, value) {
     if (!inGridBounds(grid, x, y))
         return grid;
@@ -20,7 +24,7 @@ export function withCell(grid, x, y, value) {
     cells[y * grid.width + x] = value;
     return { width: grid.width, height: grid.height, cells };
 }
-/** @internal */
+/** A copy with every in-bounds entry written; one allocation for a whole piece or stamp. */
 export function withCells(grid, entries) {
     const cells = grid.cells.slice();
     for (const entry of entries) {
@@ -29,7 +33,7 @@ export function withCells(grid, entries) {
     }
     return { width: grid.width, height: grid.height, cells };
 }
-/** @internal */
+/** Indices of rows with no empty cell, top to bottom. */
 export function fullRows(grid) {
     const rows = [];
     for (let y = 0; y < grid.height; y += 1) {
@@ -45,7 +49,7 @@ export function fullRows(grid) {
     }
     return rows;
 }
-/** @internal */
+/** A copy with `rows` removed and the rows above shifted down, refilling empty rows at the top. */
 export function clearRows(grid, rows) {
     const removed = new Set(rows);
     const kept = [];
@@ -62,7 +66,7 @@ export function clearRows(grid, rows) {
         cells.push(...row);
     return { width: grid.width, height: grid.height, cells };
 }
-/** @internal */
+/** A copy where every column's cells fall to the bottom, keeping their order. */
 export function collapseColumns(grid) {
     const cells = grid.cells.slice();
     for (let x = 0; x < grid.width; x += 1) {
@@ -96,7 +100,7 @@ function scanRuns(length, cellAtIndex, minLength, matches) {
     }
     return runs;
 }
-/** @internal */
+/** Horizontal and vertical runs of at least `minLength` cells whose values `matches` (default `===`). */
 export function findRuns(grid, minLength, matches = (a, b) => a === b) {
     const runs = [];
     for (let y = 0; y < grid.height; y += 1) {

package/dist/random/rng.d.ts

@@ -20,10 +20,21 @@ export declare function randomSeedFrom(seed: number): RandomSeed;
  * instead of closing over a generator.
  */
 export declare function stepRandomSeed(seed: RandomSeed): readonly [value: number, next: RandomSeed];
+/** A {@link seededRng} stream: callable like any `() => number`, with its cursor readable and restorable for snapshots and replay. */
+export interface SeededRng {
+    (): number;
+    /** The current cursor; feed it back to {@link restore} (or a fresh stream's `restore`) to resume the exact sequence. */
+    state(): number;
+    restore(cursor: number): void;
+}
 /** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
  *
  * @capability seeded-random injected deterministic randomness for game logic — never `Math.random` in a simulation
  */
-export declare function seededRng(seed: string | number): () => number;
+export declare function seededRng(seed: string | number): SeededRng;
+/** The cursor of a seeded stream, or `null` for a generator that carries no state (an injected closure, `Math.random`). */
+export declare function rngStateOf(rng: () => number): number | null;
+/** Restore a seeded stream's cursor; a no-op for generators that carry no state. */
+export declare function restoreRng(rng: () => number, cursor: number): void;
 /** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */
 export declare function seededStreams(seed: string | number): (stream: string) => () => number;

package/dist/random/rng.js

@@ -35,11 +35,28 @@ export function stepRandomSeed(seed) {
  */
 export function seededRng(seed) {
     let cursor = randomSeedFrom(hashSeed(seed));
-    return () => {
-        const [value, next] = stepRandomSeed(cursor);
-        cursor = next;
+    const next = () => {
+        const [value, following] = stepRandomSeed(cursor);
+        cursor = following;
         return value;
     };
+    const rng = next;
+    rng.state = () => cursor;
+    rng.restore = (value) => {
+        cursor = randomSeedFrom(value);
+    };
+    return rng;
+}
+/** The cursor of a seeded stream, or `null` for a generator that carries no state (an injected closure, `Math.random`). */
+export function rngStateOf(rng) {
+    const candidate = rng;
+    return typeof candidate.state === "function" ? candidate.state() : null;
+}
+/** Restore a seeded stream's cursor; a no-op for generators that carry no state. */
+export function restoreRng(rng, cursor) {
+    const candidate = rng;
+    if (typeof candidate.restore === "function")
+        candidate.restore(cursor);
 }
 /** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */
 export function seededStreams(seed) {

package/dist/render/environment.d.ts

@@ -0,0 +1,23 @@
+/** A declarative source for image-based scene lighting. */
+export type EnvironmentSource = 
+/** Procedural two-color sky probe, preserving the engine default. */
+{
+    kind: "gradient";
+    sky: string;
+    ground: string;
+    sun?: string;
+    intensity?: number;
+}
+/** Equirectangular HDR or EXR environment map loaded from `url`. */
+ | {
+    kind: "hdri";
+    url: string;
+    rotation?: number;
+    intensity?: number;
+}
+/** Six faces of a cube environment map, in three.js cube-loader order. */
+ | {
+    kind: "cube";
+    urls: [string, string, string, string, string, string];
+    intensity?: number;
+};

package/dist/render/environment.js

@@ -0,0 +1 @@
+export {};

package/dist/render/lookPreset.d.ts

@@ -2,16 +2,19 @@ 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
+ * Named look preset composing the existing lighting/sky/fog/post knobs into one field.
+ * `"neutral"` (the default when unset) keeps presentation unstyled; `"cinematic"` 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).
+ * stack. `"comic"` adds ink outlines and cel bands over a saturated grade (Borderlands-style);
+ * `"retro"` pixelates and posterizes the frame. `"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";
+export type LookPreset = "neutral" | "photoreal" | "toon" | "comic" | "retro" | "cinematic" | "flat";
+/** Every look preset name, for pickers and validating a preset read from a URL or file. */
+export declare const LOOK_PRESETS: readonly LookPreset[];
 /** Explicit graphics knobs a game may set; the preset only fills the ones left undefined. */
 export interface GameLookInput {
     look?: LookPreset;
@@ -31,9 +34,19 @@ export interface ResolvedGameLook {
 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;
+/** Unstyled baseline: a stable linear presentation with no genre-specific grading. */
+export declare const NEUTRAL_POST_PROCESSING: PostProcessingConfig;
+/** High-contrast physically based presentation for authored HDR environments. */
+export declare const PHOTOREAL_POST_PROCESSING: PostProcessingConfig;
+/** Clean graphic presentation; toon materials remain game-owned while this sets the grade. */
+export declare const TOON_POST_PROCESSING: PostProcessingConfig;
+/** Ink outlines, four cel bands and a punchy grade — a hand-inked comic look on any model. */
+export declare const COMIC_POST_PROCESSING: PostProcessingConfig;
+/** Chunky pixels and posterized colour with no smoothing — a low-resolution retro look. */
+export declare const RETRO_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.
+ * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"neutral"`;
+ * `"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

package/dist/render/lookPreset.js

@@ -1,3 +1,5 @@
+/** Every look preset name, for pickers and validating a preset read from a URL or file. */
+export const LOOK_PRESETS = ["neutral", "photoreal", "cinematic", "toon", "comic", "retro", "flat"];
 /** 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. */
@@ -7,23 +9,73 @@ export const CINEMATIC_POST_PROCESSING = {
     ao: { intensity: 1.4 },
     grade: {},
 };
+/** Unstyled baseline: a stable linear presentation with no genre-specific grading. */
+export const NEUTRAL_POST_PROCESSING = {
+    toneMapping: "agx",
+    bloom: false,
+    ao: false,
+    grade: false,
+};
+/** High-contrast physically based presentation for authored HDR environments. */
+export const PHOTOREAL_POST_PROCESSING = {
+    toneMapping: "aces",
+    bloom: { strength: 0.28, radius: 0.58, threshold: 0.9 },
+    ao: { intensity: 1.25, radius: 1.6 },
+    grade: { saturation: 1.04, vignette: 0.08, grain: 0.004 },
+};
+/** Clean graphic presentation; toon materials remain game-owned while this sets the grade. */
+export const TOON_POST_PROCESSING = {
+    toneMapping: "linear",
+    bloom: { strength: 0.08, radius: 0.35, threshold: 1.1 },
+    ao: { intensity: 0.8, radius: 1.2 },
+    grade: { saturation: 1.18, gamma: 1, vignette: 0, grain: 0 },
+};
+/** Ink outlines, four cel bands and a punchy grade — a hand-inked comic look on any model. */
+export const COMIC_POST_PROCESSING = {
+    toneMapping: "aces",
+    exposure: 1.05,
+    aa: "msaa",
+    bloom: { strength: 0.12, radius: 0.4, threshold: 1 },
+    ao: { intensity: 1, radius: 1.2 },
+    stylize: { outline: { thickness: 1.5 }, bands: 4 },
+    grade: { saturation: 1.3, gamma: 0.94, vignette: 0.15, grain: 0 },
+};
+/** Chunky pixels and posterized colour with no smoothing — a low-resolution retro look. */
+export const RETRO_POST_PROCESSING = {
+    toneMapping: "aces",
+    aa: false,
+    bloom: false,
+    ao: false,
+    stylize: { pixelSize: 3, bands: 6 },
+    grade: { saturation: 1.15, gamma: 1, vignette: 0, grain: 0 },
+};
+const PRESET_POST = {
+    photoreal: PHOTOREAL_POST_PROCESSING,
+    toon: TOON_POST_PROCESSING,
+    comic: COMIC_POST_PROCESSING,
+    retro: RETRO_POST_PROCESSING,
+    cinematic: CINEMATIC_POST_PROCESSING,
+};
 /**
- * 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.
+ * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"neutral"`;
+ * `"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";
+    const look = input.look ?? "neutral";
     if (look === "flat") {
         return { lighting: input.lighting, backdrop: input.backdrop, postProcessing: input.postProcessing };
     }
+    if (look === "neutral") {
+        return { lighting: input.lighting, backdrop: input.backdrop, postProcessing: input.postProcessing ?? NEUTRAL_POST_PROCESSING };
+    }
     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,
+        postProcessing: input.postProcessing ?? PRESET_POST[look],
     };
 }

package/dist/render/postProcessing.d.ts

@@ -6,7 +6,11 @@ export interface BloomConfig {
     strength?: number;
     /** Glow spread radius, 0..1. Default 0.55. */
     radius?: number;
-    /** Luminance above which a pixel blooms, 0..1. Default 0.85. */
+    /**
+     * Luminance above which a pixel blooms. Default 0.85. Measured on raw HDR
+     * before the tone-map/exposure stage, so lowering `exposure` does not change
+     * which pixels bloom — push past 1.0 to select only emissives.
+     */
     threshold?: number;
 }
 /** Ground-truth ambient occlusion stage — darkens contact creases and cavities for depth. */
@@ -22,6 +26,11 @@ export interface AoConfig {
 }
 /** Final colour-grade stage: lift/gain/gamma, saturation, vignette, film grain — applied in display space after tone mapping. */
 export interface GradeConfig {
+    /** Optional 2D strip LUT URL. The strip contains size square tiles, one tile per blue slice. */
+    lut?: {
+        url: string;
+        size?: number;
+    };
     /** Additive shadow tint (RGB, ~0..0.1). Default cool [0.012, 0.010, 0.018]. */
     lift?: readonly [number, number, number];
     /** Multiplicative highlight tint (RGB, ~1). Default warm [1.05, 1.02, 0.98]. */
@@ -46,6 +55,34 @@ export interface DofConfig {
     /** Maximum blur radius, 0..1. Default 0.01. */
     maxBlur?: number;
 }
+/** Ink outlines traced from depth and surface-normal edges — silhouettes plus interior creases. */
+export interface OutlineConfig {
+    /** Line colour (CSS). Default near-black "#101014". */
+    color?: string;
+    /** Line thickness in render pixels. Default 1. */
+    thickness?: number;
+    /** Line opacity, 0..1. Default 1. */
+    opacity?: number;
+    /** Relative depth jump that counts as a silhouette edge. Lower draws more lines. Default 0.08. */
+    depthThreshold?: number;
+    /** Normal difference (1 − cos angle) that counts as a crease. Lower draws more lines. Default 0.35. */
+    normalThreshold?: number;
+    /** Distance in world units at which lines have faded out, so far scenery stays clean. Default 160. */
+    fadeDistance?: number;
+}
+/**
+ * Art-style stage that turns the same models and lighting into a different look without
+ * touching materials: ink outlines (comic / Borderlands), cel bands (cartoon), pixelation (retro).
+ * Runs after tone mapping, before the grade.
+ */
+export interface StylizeConfig {
+    /** Ink outlines. Omitted or `false` draws none. */
+    outline?: OutlineConfig | false;
+    /** Quantize brightness into this many cel-shading bands, keeping hue. 0 or omitted is off; 3–6 reads as cartoon. */
+    bands?: number;
+    /** Snap the frame to blocks of this many render pixels for a retro look. 0, 1 or omitted is off. */
+    pixelSize?: number;
+}
 /**
  * Edge antialiasing for the post chain. SMAA runs in linear-sRGB before the output
  * tone-map and cleans alpha-tested foliage/particles that MSAA samples alone leave crawling.
@@ -77,6 +114,8 @@ export interface PostProcessingConfig {
     /** Depth-of-field / bokeh. Heavier stage — omit or `false` to skip. Default off (omitted). */
     dof?: DofConfig | false;
     grade?: GradeConfig | false;
+    /** Art-style stage: outlines, cel bands, pixelation. Default off (omitted). */
+    stylize?: StylizeConfig | false;
 }
 /**
  * A cinematic "product shot" post preset — the full chain on (contact-AO, soft bloom, a warm film

package/dist/render/postProcessing.js

@@ -8,7 +8,7 @@ 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 },
+    ao: { radius: 1.1, intensity: 1.5, distanceFalloff: 3, blend: 1 },
     grade: {
         lift: [0.008, 0.008, 0.014],
         gain: [1.05, 1.02, 0.98],

package/dist/render/sprite2d.d.ts

@@ -0,0 +1,38 @@
+import type { SpriteAtlas } from "../assets/spriteAtlas.js";
+/** Serializable playback position for a named sprite animation. */
+export interface SpriteClipState {
+    animation: string;
+    frameIndex: number;
+    elapsed: number;
+    done: boolean;
+}
+/** Create a renderer-independent sprite animation player.
+ * @capability sprite-2d animate a sprite atlas clip from headless or rendered game code
+ */
+export declare function createSpriteClipPlayer(atlas: SpriteAtlas): {
+    play(name: string): void;
+    advance(dt: number): void;
+    frame: () => {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        pivot?: [number, number];
+    } | undefined;
+    snapshot: () => {
+        animation: string;
+        frameIndex: number;
+        elapsed: number;
+        done: boolean;
+    };
+    restore(next: SpriteClipState): void;
+    retune(next: {
+        speed: number;
+    }): void;
+};
+/** Canonical layers used by 2D presentations. */
+export declare const SortingLayers: readonly ["background", "world", "actors", "effects", "foreground", "ui"];
+/** Resolve a layer name and local offset into a stable render order.
+ * @capability sprite-2d order sprites by named presentation layers
+ */
+export declare function sortingOrder(layers: readonly string[], layer: string, offset?: number): number;

package/dist/render/sprite2d.js

@@ -0,0 +1,40 @@
+/** Create a renderer-independent sprite animation player.
+ * @capability sprite-2d animate a sprite atlas clip from headless or rendered game code
+ */
+export function createSpriteClipPlayer(atlas) {
+    let state = { animation: Object.keys(atlas.animations)[0] ?? "", frameIndex: 0, elapsed: 0, done: false };
+    let speed = 1;
+    const current = () => { const animation = atlas.animations[state.animation]; if (!animation)
+        return undefined; return atlas.frames[animation.frames[state.frameIndex]]; };
+    return {
+        play(name) { if (!atlas.animations[name])
+            throw new Error(`Unknown sprite animation: ${name}.`); state = { animation: name, frameIndex: 0, elapsed: 0, done: false }; },
+        advance(dt) { if (!Number.isFinite(dt) || dt < 0)
+            throw new Error("dt must be non-negative."); const animation = atlas.animations[state.animation]; if (!animation || state.done)
+            return; state.elapsed += dt * speed; const duration = 1 / animation.fps; while (state.elapsed >= duration && !state.done) {
+            state.elapsed -= duration;
+            if (state.frameIndex + 1 < animation.frames.length)
+                state.frameIndex += 1;
+            else if (animation.loop === false) {
+                state.frameIndex = animation.frames.length - 1;
+                state.done = true;
+            }
+            else
+                state.frameIndex = 0;
+        } },
+        frame: current,
+        snapshot: () => ({ ...state }),
+        restore(next) { if (!atlas.animations[next.animation])
+            throw new Error(`Unknown sprite animation: ${next.animation}.`); state = { ...next }; },
+        retune(next) { if (!Number.isFinite(next.speed) || next.speed < 0)
+            throw new Error("speed must be non-negative."); speed = next.speed; },
+    };
+}
+/** Canonical layers used by 2D presentations. */
+export const SortingLayers = ["background", "world", "actors", "effects", "foreground", "ui"];
+/** Resolve a layer name and local offset into a stable render order.
+ * @capability sprite-2d order sprites by named presentation layers
+ */
+export function sortingOrder(layers, layer, offset = 0) { const index = layers.indexOf(layer); if (index < 0)
+    throw new Error(`Unknown sorting layer: ${layer}.`); if (!Number.isFinite(offset))
+    throw new Error("offset must be finite."); return index + offset; }