@jgengine/core 0.18.1 → 0.21.0

package/dist/physics/vehicleObstacles.d.ts

@@ -1,4 +1,5 @@
 import { type CollisionObstacle } from "../movement/movementModel.js";
+import type { KinematicVehicleOptions } from "./kinematicVehicle.js";
 /**
  * A single blocked-move event a car can react to (#1051): crash damage, screen shake, a metal-crunch
  * cue. Reported once, when a move is first vetoed, then consumed by {@link VehicleObstacleClamp.takeImpact}.
@@ -17,8 +18,8 @@ export interface VehicleImpact {
  * {@link takeImpact} once per tick for the crash it produced.
  */
 export interface VehicleObstacleClamp {
-    /** Resolve an attempted `from`→`to` XZ move to the destination actually allowed (slide-along). */
-    clampMove(from: readonly [number, number], to: readonly [number, number]): readonly [number, number];
+    /** Resolve an attempted XZ move; recovery endpoints carry permitted world-unit displacement in `motion`. */
+    clampMove: NonNullable<KinematicVehicleOptions["clampMove"]>;
     /** Impact recorded since last take, consumed on read (null when none). Closing speed is the velocity component into the obstacle at block time, units/s. */
     takeImpact(): VehicleImpact | null;
 }

package/dist/physics/vehicleObstacles.js

@@ -106,11 +106,30 @@ export function createVehicleObstacleClamp(options) {
                 return to;
             const attemptedX = to[0] - from[0];
             const attemptedZ = to[1] - from[1];
-            const step = resolveObstacleStep([from[0], CAR_BODY_MID_Y, from[1]], attemptedX, attemptedZ, vehicleView(obstacles), radius);
-            const blockedX = attemptedX - step.stepX;
-            const blockedZ = attemptedZ - step.stepZ;
-            if (blockedX === 0 && blockedZ === 0)
+            const current = [from[0], CAR_BODY_MID_Y, from[1]];
+            const solids = vehicleView(obstacles);
+            const step = resolveObstacleStep(current, attemptedX, attemptedZ, solids, radius);
+            if (attemptedX === step.stepX && attemptedZ === step.stepZ)
                 return to;
+            // The resolver's zero-step escape is the same positional recovery included in `step`.
+            // Separate it from motion using this tick's already sampled solids, never a second callback.
+            // This preserves the resolver's tangential projection, including diagonal/compound contacts.
+            const escape = resolveObstacleStep(current, 0, 0, solids, radius);
+            const recovering = escape.stepX !== 0 || escape.stepZ !== 0;
+            // Recover first, then collide the motor move at that safe origin. Otherwise the resolver
+            // excludes the penetrated box and permits driving straight back into it on every tick.
+            const motion = recovering
+                ? resolveObstacleStep([from[0] + escape.stepX, CAR_BODY_MID_Y, from[1] + escape.stepZ], attemptedX, attemptedZ, solids, radius)
+                : step;
+            // One bounded recovery pass may meet another overlapping solid. Keep that second escape
+            // positional too; overlapping/inconsistent solids never become an unbounded recovery loop.
+            const secondaryEscape = recovering
+                ? resolveObstacleStep([from[0] + escape.stepX, CAR_BODY_MID_Y, from[1] + escape.stepZ], 0, 0, solids, radius)
+                : { stepX: 0, stepZ: 0 };
+            const motionX = motion.stepX - secondaryEscape.stepX;
+            const motionZ = motion.stepZ - secondaryEscape.stepZ;
+            const blockedX = attemptedX - motionX;
+            const blockedZ = attemptedZ - motionZ;
             const blockedMag = Math.hypot(blockedX, blockedZ);
             if (blockedMag > BLOCK_EPSILON) {
                 const dt = options.dt();
@@ -123,7 +142,12 @@ export function createVehicleObstacleClamp(options) {
                     };
                 }
             }
-            return [from[0] + step.stepX, from[1] + step.stepZ];
+            const result = [from[0] + escape.stepX + motion.stepX, from[1] + escape.stepZ + motion.stepZ];
+            if (recovering) {
+                // Per-result tuples stay stable if a host retains a prior result for diagnostics.
+                return Object.assign(result, { motion: [motionX, motionZ] });
+            }
+            return result;
         },
         takeImpact() {
             const impact = pending;

package/dist/physics/worldColliders.d.ts

@@ -7,7 +7,7 @@ export interface WorldColliderSync {
     /** Remove all bodies owned by this synchronizer and stop reacting to scene changes. */
     dispose(): void;
 }
-/** Mirrors static scene-object physical colliders and the context's ground field into a physics backend.
+/** 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

@@ -10,11 +10,13 @@ function bodyShape(shape) {
 function bodyPosition(shape, position, rotationY) {
     return colliderWorldCenter({ name: "body", purpose: "physical", shape, damageEligible: false, blocks: true }, position, rotationY);
 }
-/** Mirrors static scene-object physical colliders and the context's ground field into a physics backend.
+/** 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() {
@@ -62,10 +64,32 @@ export function syncWorldColliders(backend, ctx) {
         });
         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)) {
@@ -76,7 +100,11 @@ export function syncWorldColliders(backend, ctx) {
         for (const objectId of ids)
             syncObject(objectId);
     }
-    const unsubscribe = ctx.scene.object.subscribe(sync);
+    const unsubscribeObjects = ctx.scene.object.subscribe(sync);
+    const unsubscribeSolids = ctx.world.solids.subscribe(() => {
+        if (!disposed)
+            syncSolids();
+    });
     sync();
     return {
         sync,
@@ -84,7 +112,11 @@ export function syncWorldColliders(backend, ctx) {
             if (disposed)
                 return;
             disposed = true;
-            unsubscribe();
+            unsubscribeObjects();
+            unsubscribeSolids();
+            for (const handle of solidBodies)
+                backend.removeBody(handle);
+            solidBodies.length = 0;
             if (terrainBody !== null)
                 backend.removeBody(terrainBody);
             terrainBody = null;

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/render/lookPreset.d.ts

@@ -6,12 +6,15 @@ import type { PostProcessingConfig } from "./postProcessing.js";
  * `"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 = "neutral" | "photoreal" | "toon" | "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;
@@ -37,6 +40,10 @@ export declare const NEUTRAL_POST_PROCESSING: PostProcessingConfig;
 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 `"neutral"`;
  * `"flat"` passes the explicit knobs through untouched.

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. */
@@ -28,6 +30,32 @@ export const TOON_POST_PROCESSING = {
     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 `"neutral"`;
  * `"flat"` passes the explicit knobs through untouched.
@@ -48,7 +76,6 @@ export function resolveGameLook(input) {
     return {
         lighting: input.lighting,
         backdrop,
-        postProcessing: input.postProcessing ??
-            (look === "toon" ? TOON_POST_PROCESSING : look === "photoreal" ? PHOTOREAL_POST_PROCESSING : CINEMATIC_POST_PROCESSING),
+        postProcessing: input.postProcessing ?? PRESET_POST[look],
     };
 }

package/dist/render/postProcessing.d.ts

@@ -55,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.
@@ -86,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/runtime/cameraDirector.d.ts

@@ -1,16 +1,67 @@
-import type { ChaseCameraConfig, CinematicCameraConfig } from "../game/playableGame.js";
-/** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11), or a whole driving-feel overlay (speed→FOV, lead, bank, speed shake, drift-lag) applied only while a vehicle is piloted (#1299). */
-export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse">>;
+import type { CameraRigKind, ChaseCameraConfig, ChaseView, CinematicCameraConfig, GameCameraConfig } from "../game/playableGame.js";
+import type { GameContext } from "./gameContext.js";
+/** Data overlay for an existing rig; callbacks and Canvas projection/preferences remain configured by the game. */
+export type CameraRigConfig = Omit<GameCameraConfig, "rig" | "projection" | "pixelPerfect" | "frustum" | "playerFov" | "weapon" | "onCameraFollow">;
+/** Runtime rig selection and detached data overlay over the configured camera. */
+export interface CameraRigOverride {
+    kind: CameraRigKind;
+    config: CameraRigConfig;
+}
+/** Camera policy state before the JSON-safe snapshot number encoding. */
+export interface CameraDirectorState {
+    followEntityId?: string | null;
+    rig: CameraRigOverride | null;
+    cinematic: CinematicCameraConfig | null;
+    chase: ChaseCameraTuning | null;
+}
+type CameraSerialized<T> = T extends number ? number | {
+    $cameraNumber: "Infinity";
+} : T extends object ? {
+    [Key in keyof T]: CameraSerialized<T[Key]>;
+} : T;
+/** JSON-safe camera policy; documented instant chase responses use an explicit Infinity marker. */
+export type CameraDirectorSnapshot = CameraSerialized<CameraDirectorState>;
+/** @internal */
+export declare function validateCameraRig(kind: CameraRigKind, config?: CameraRigConfig): void;
+/** @internal */
+export declare function validateChaseCameraTuning(tuning: ChaseCameraTuning | null): void;
+/** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11), a whole driving-feel overlay applied only while a vehicle is piloted (#1299), or a `view` switch between chase and seat cameras. */
+export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse" | "headingSource" | "distanceBySpeed" | "pitchFollow" | "fovKick" | "lookBackAction" | "collision" | "view">>;
+/** Default order {@link nextChaseView} cycles through. */
+export declare const CHASE_VIEWS: readonly ChaseView[];
+/**
+ * The view after `current` in `views`, wrapping at the end; a view missing from the list starts the cycle over.
+ * Pair with `setChaseTuning` to bind a "change camera" key:
+ * `ctx.camera.setChaseTuning({ ...ctx.camera.chaseTuning(), view: nextChaseView(view) })`.
+ *
+ * @capability chase-view-cycle cycle a vehicle camera between chase, hood and cockpit views at runtime
+ */
+export declare function nextChaseView(current: ChaseView, views?: readonly ChaseView[]): ChaseView;
 export interface CameraDirector {
     follow(entityId: string | null): void;
     /** `undefined` means no runtime override — the shell falls back to the static `playable.camera.followEntityId`. `null` means explicitly follow nothing. */
     followedEntityId(): string | null | undefined;
+    /** Replace the runtime rig overlay; `null` restores the game's configured rig/config. Existing chase tuning remains independent. */
+    setRig(kind: CameraRigKind | null, config?: CameraRigConfig): void;
+    rig(): CameraRigOverride | null;
     setCinematic(config: CinematicCameraConfig | null): void;
     cinematic(): CinematicCameraConfig | null;
     /** Overlay a runtime patch on the chase rig's config — a boss-intro pull-back, drift zoom-out; `null` restores the static config. */
     setChaseTuning(tuning: ChaseCameraTuning | null): void;
     chaseTuning(): ChaseCameraTuning | null;
+    /** Add a transient FOV impulse in degrees (a landing, a hit, a boost) that the chase rig layers on and decays per `camera.chase.fovKick`. Kicks from one frame sum. */
+    kickFov(degrees: number): void;
+    /** Drain the FOV impulses queued since the last call; the shell's chase rig calls this once per frame. */
+    takeFovKick(): number;
+    snapshot(): CameraDirectorSnapshot;
+    /** Invalid state throws before changing any camera field. */
+    restore(state: CameraDirectorSnapshot): void;
+    /** Clear runtime policy and transient FOV kicks; configured camera data remains untouched. */
+    reset(): void;
     subscribe(listener: () => void): () => void;
 }
 /** @internal */
 export declare function createCameraDirector(): CameraDirector;
+/** Local camera policy is saved, never broadcast to another player's presentation. @internal */
+export declare function installCameraPersistence(ctx: GameContext): void;
+export {};