@waica/engine 0.18.0 → 0.19.1

package/README.md

@@ -194,6 +194,28 @@ game.time.now  // seconds of Game Time since the Game started
 - **Scope.** A timer or tween is scene-scoped by default: `unloadScene()` and every scene load — including a Game's first — cancel it, running no callback. `{ scope: 'session' }` survives a scene change. `{ owner: entity }` cancels it immediately when that entity is destroyed, whatever its scope; an owner already dead at scheduling time yields an inactive handle. `game.dispose()` cancels everything in both scopes. This is the opposite default from `game.onUpdate`/`game.events` (ADR 0011), which survive a scene change by construction, and the same one `game.audio.play()` uses (ADR 0012) — see ADR 0017 for why timers follow audio's rule rather than the host-subscription one: a timer's callback almost always closes over the scene that scheduled it.
 - **No Promises.** Nothing here returns one, and nothing is async — a `.then` continuation is not step-exact (it runs after the whole synchronous frame), which is exactly what `game.time` exists to avoid. Compose delays with `after`, not `await`.
 
+## game.cameraEffects: shake, fade and flash
+
+Every `Game` owns a `cameraEffects: CameraEffects` service beside `game.camera`, which stays the plain `THREE.OrthographicCamera` (ADR 0020). Effects advance only inside a Simulation Step, right after the scene camera, so nothing moves while the Game is not simulating, is stopped, or a Run Session is paused; `step { frames: N }` advances them by exactly N steps.
+
+```ts
+game.cameraEffects.shake({ intensity: 0.3, seconds: 0.25 })          // world units, decaying to 0
+const out = game.cameraEffects.fade({ to: 'black', seconds: 0.4 })   // 'black' | 'white' | '#rrggbb' | 'clear'
+game.cameraEffects.flash({ color: 'white', seconds: 0.15 })          // up to 1, back to exactly 0
+out.cancel()                                                          // opacity stays where it was
+await out.done                                                        // true: completed; false: cancelled or replaced
+```
+
+- **Shake.** An offset added to the camera only while drawing (the world render and Anchored Pieces), never to the base center that follow, deadzone and limits compute, so smoothing never feeds on it. Each axis stays within `intensity · (1 − ease(t / seconds))` (`easing` takes `game.time`'s names, `'linear'` by default) and is exactly `{0, 0}` from `seconds` on. Overlapping shakes apply the largest current amplitude. The jitter is deterministic per Simulation Step (no `Math.random`), so a Run Session reproduces it. It is not re-clamped to `limits`: at a map edge up to `intensity` beyond them can show. Under a fixed `resolution` the offset snaps to whole screen pixels; the base center is never snapped.
+- **Fade.** Carries an HTML layer over the game viewport — inside the letterbox, above the world, UI Pieces and Anchored Pieces — from its current opacity to 1 in the given color, or to 0 with `'clear'`, and then holds. A new `fade` cancels a running one (its `done` resolves `false`) and starts from the current opacity.
+- **Flash.** Its own layer above the Fade, shown at opacity 1 and returned to exactly 0 over `seconds`; it never changes the Fade.
+- **Scope.** A Fade is session-scoped: it survives `unloadScene()` and every scene load with its color, opacity and any running progress, so it can cover a scene change. A Shake or Flash is scene-scoped: `unloadScene()` ends it, running no callback (its `done` resolves `false`). `game.dispose()` ends everything and removes the layers. This follows the audio and timer scope notes above (ADR 0011, ADR 0017): a transition fade is exactly the case that must cross a scene change.
+- **Invalid arguments never throw.** A non-finite or negative `seconds`/`intensity`, an unknown color or an unknown easing logs one `[waica]` warning and returns a handle whose `done` resolves `false`; no effect changes.
+- **Scene Transition.** `SceneTransition` takes `fadeSeconds` (default 0: a hard cut) and `fadeColor` (default `'black'`): it fades out over `fadeSeconds`, loads its destination, then clears over `fadeSeconds` in the incoming scene. Simulation and input keep running; the component ignores further triggers during its outgoing fade. The Runtime Bridge `scene` operation stays a hard cut.
+- **Runtime Snapshot.** Every snapshot carries `camera: { shake: { x, y }, fade: { color, opacity }, flash: { color, opacity } }` from the last completed step, under the `'camera-effects'` capability.
+
+A Fade to a color that nothing clears leaves the view covered; the engine does not warn.
+
 ## game.ui.attach: Anchored Pieces
 
 A UI Piece shown with `game.ui.show(name)` is a screen-space singleton. `game.ui.attach(piece, entity, options?)` instead creates an **Anchored Piece**: a new instance of the piece that follows `entity` across the screen, with its own shadow root and its own values. Every call is a new instance — five orcs can each carry a `health-bar` — and the screen piece of the same name is never mounted, shown or changed by it.

package/dist/animation/sheet.js

@@ -11,11 +11,13 @@ export function sheetFrameCount(sheet) {
  */
 export function locateFrame(sheets, frame) {
     let rest = Math.max(0, Math.floor(frame));
-    for (let i = 0; i < sheets.length; i++) {
-        const count = sheetFrameCount(sheets[i]);
+    let i = 0;
+    for (const sheet of sheets) {
+        const count = sheetFrameCount(sheet);
         if (rest < count || i === sheets.length - 1)
             return { sheet: i, frame: Math.min(rest, count - 1) };
         rest -= count;
+        i++;
     }
     return { sheet: 0, frame: 0 };
 }
@@ -28,7 +30,11 @@ const positive = (value) => typeof value === 'number' && Number.isFinite(value)
 export function sheetCell(imageWidth, imageHeight, cols, rows, frame, params = {}) {
     if (params.cells?.length) {
         const index = Math.min(Math.max(0, Math.floor(frame)), params.cells.length - 1);
-        return params.cells[index];
+        const cell = params.cells[index];
+        // Invariant: the index is clamped into a non-empty cells array.
+        if (!cell)
+            throw new Error(`sheetCell: missing cell at clamped index ${index}`);
+        return cell;
     }
     const c = Math.max(1, Math.floor(cols));
     const r = Math.max(1, Math.floor(rows));

package/dist/assets/asset-loader.js

@@ -1,5 +1,6 @@
 import * as THREE from 'three';
 import { ThreeTextureBackend } from './texture-backend.js';
+import { reportRejection } from '../report-rejection.js';
 /**
  * Not `base.clone()`: `Texture.copy` sets `needsUpdate`, which bumps the
  * shared Source's version — a GPU re-upload of the same image for every
@@ -52,10 +53,10 @@ export class AssetLoader {
         if (entry.outcome === null) {
             // Chained here, before the consumer chains its own continuation on
             // `settled`, so the clone is uploadable by the time that one runs.
-            void entry.settled.then((outcome) => {
+            reportRejection(entry.settled.then((outcome) => {
                 if (outcome === 'loaded')
                     texture.version = entry.base.version;
-            });
+            }), 'texture upload');
         }
         return { texture, settled: entry.settled };
     }

package/dist/audio/web-audio-backend.js

@@ -1,3 +1,4 @@
+import { reportRejection } from '../report-rejection.js';
 /**
  * The real WebAudio implementation (ADR 0013's default). Builds a small
  * mixing graph — one GainNode per sound feeding a StereoPannerNode, feeding
@@ -90,13 +91,19 @@ export class WebAudioBackend {
             this.masterGain.gain.value = volume;
     }
     suspend() {
-        void this.context?.suspend();
+        const suspending = this.context?.suspend();
+        if (suspending)
+            reportRejection(suspending, 'audio suspend');
     }
     resume() {
-        void this.ensureContext()?.resume();
+        const resuming = this.ensureContext()?.resume();
+        if (resuming)
+            reportRejection(resuming, 'audio resume');
     }
     close() {
-        void this.context?.close();
+        const closing = this.context?.close();
+        if (closing)
+            reportRejection(closing, 'audio close');
         this.context = null;
         this.masterGain = null;
         this.channelGains.clear();
@@ -120,11 +127,13 @@ export class WebAudioBackend {
         const existing = this.channelGains.get(channel);
         if (existing)
             return existing;
-        // Safe: only called once ensureContext() has already produced a context.
-        const context = this.context;
+        const { context, masterGain } = this;
+        // Invariant: only called once ensureContext() has produced the context and master gain.
+        if (!context || !masterGain)
+            throw new Error('ensureChannelGain called before ensureContext');
         const gain = context.createGain();
         gain.gain.value = this.effectiveChannelGain(channel);
-        gain.connect(this.masterGain);
+        gain.connect(masterGain);
         this.channelGains.set(channel, gain);
         return gain;
     }

package/dist/authoring-defaults.js

@@ -5,11 +5,11 @@ function isSerializable(value) {
     const kind = typeof value;
     if (kind === 'string' || kind === 'number' || kind === 'boolean')
         return true;
-    if (kind !== 'object')
+    if (typeof value !== 'object')
         return false;
     if (Array.isArray(value))
         return true;
-    const proto = Object.getPrototypeOf(value);
+    const proto = Reflect.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
 /**
@@ -32,7 +32,7 @@ export function authoringDefaults(Class, onError) {
     }
     const transient = new Set(Class.transient ?? []);
     const keys = new Set(Object.keys(instance));
-    for (let proto = Object.getPrototypeOf(instance); proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+    for (let proto = Reflect.getPrototypeOf(instance); proto && proto !== Object.prototype; proto = Reflect.getPrototypeOf(proto)) {
         for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto))) {
             if (descriptor.set)
                 keys.add(key);
@@ -42,7 +42,7 @@ export function authoringDefaults(Class, onError) {
     for (const key of keys) {
         if (EXCLUDED_KEYS.has(key) || key.startsWith('_') || transient.has(key))
             continue;
-        const value = instance[key];
+        const value = Reflect.get(instance, key);
         if (value === undefined || !isSerializable(value))
             continue;
         result[key] = value;

package/dist/camera-effects.d.ts

@@ -0,0 +1,142 @@
+import type { ViewportRect } from './anchored-pieces.js';
+import { type EasingName } from './game-time.js';
+/** A Camera Effect color: a name or a six-digit hex, case-insensitive. */
+export type CameraEffectColor = 'black' | 'white' | `#${string}`;
+export interface ShakeOptions {
+    /** The largest offset, in world units, on each axis. Finite and >= 0. */
+    intensity: number;
+    /** Seconds of Game Time until the offset reaches 0. Finite and >= 0. */
+    seconds: number;
+    /** How the amplitude decays from `intensity` to 0; default `'linear'`. */
+    easing?: EasingName;
+}
+export interface FadeOptions {
+    /** The color to carry the view to (opacity 1), or `'clear'` (opacity 0, color kept). */
+    to: CameraEffectColor | 'clear';
+    /** Seconds of Game Time from the current opacity to the target. Finite and >= 0. */
+    seconds: number;
+    easing?: EasingName;
+}
+export interface FlashOptions {
+    color: CameraEffectColor;
+    /** Seconds of Game Time from opacity 1 back to 0. Finite and >= 0. */
+    seconds: number;
+}
+/** What `shake`, `fade` and `flash` hand back. */
+export interface CameraEffectHandle {
+    /** Stops the effect where it is. Idempotent; resolves `done` with false. */
+    cancel(): void;
+    /** True once the effect completed; false if cancelled, replaced, ended by its scope or invalid. */
+    readonly done: Promise<boolean>;
+    /**
+     * True once a *later* call to the same kind of effect has taken over
+     * before this one ended on its own — false while it is still running,
+     * and false once it ends on its own accord (completes, is cancelled, or
+     * ends by its scope) with nothing else in its place. A Shake never
+     * supersedes another (CA-7: overlapping shakes coexist), so this is
+     * always false for a Shake handle. Unlike `done`, this reads
+     * synchronously: a Promise only notifies its `.then()` in a microtask,
+     * which can land well after a caller scheduled on Game Time needs the
+     * answer on an exact Simulation Step (PR #98 review, `scene-
+     * transition.ts`).
+     */
+    readonly superseded: boolean;
+}
+/** The effects' state after the last completed Simulation Step (read-only copy). */
+export interface CameraEffectsState {
+    /** The offset, in world units, added to the camera only while drawing. */
+    shake: {
+        x: number;
+        y: number;
+    };
+    fade: {
+        color: string;
+        opacity: number;
+    };
+    flash: {
+        color: string;
+        opacity: number;
+    };
+}
+export interface CameraEffectsOptions {
+    /** Where the Fade and Flash layers mount (the canvas's parent); resolved lazily. */
+    host: () => HTMLElement;
+    /** One screen pixel in world units under a fixed resolution, or null (no snap). */
+    pixel: () => number | null;
+}
+declare const ADVANCE: unique symbol;
+declare const LAYOUT: unique symbol;
+/**
+ * Screen-level Camera Effects (issue #74, ADR 0020): Shake, Fade and Flash,
+ * beside `game.camera` and never written into it. They advance only inside
+ * a Simulation Step, right after the scene camera (spec inference 9), so
+ * nothing moves while the Game is not simulating or a Run Session is
+ * paused. A Shake is an offset the Game adds to the camera only while it
+ * draws; a Fade and a Flash are HTML layers over the letterboxed game
+ * viewport, above the UI overlay. A Fade is session-scoped (it survives a
+ * scene change, ADR 0011); a Shake or Flash dies with its scene.
+ */
+export declare class CameraEffects {
+    private readonly options;
+    private steps;
+    private readonly shakes;
+    private offset;
+    private fadeRun;
+    private flashRun;
+    private readonly fadeLayer;
+    private readonly flashLayer;
+    private rect;
+    constructor(options: CameraEffectsOptions);
+    /** A fresh copy of the effects after the last completed Simulation Step. */
+    get state(): CameraEffectsState;
+    /**
+     * Jitters the drawn view by up to `intensity` world units per axis,
+     * decaying to 0 over `seconds`. Overlapping shakes apply the largest
+     * current amplitude. Not re-clamped to the scene camera's limits; snapped
+     * to whole screen pixels under a fixed resolution.
+     */
+    shake(options: ShakeOptions): CameraEffectHandle;
+    /**
+     * Carries the Fade layer from its current opacity to 1 in `to`'s color,
+     * or to 0 with `'clear'`, over `seconds`; the result then holds. A new
+     * fade cancels a running one (its `done` resolves false).
+     */
+    fade(options: FadeOptions): CameraEffectHandle;
+    /**
+     * Shows the Flash layer at opacity 1 in `color` and returns it to exactly
+     * 0 over `seconds`, independent of (and drawn above) the Fade. A new flash
+     * replaces a running one.
+     */
+    flash(options: FlashOptions): CameraEffectHandle;
+    /**
+     * Ends every Shake and Flash (their `done` resolves false) and keeps the
+     * Fade — opacity, color and any running progress. Called by
+     * `Game.unloadScene()`.
+     */
+    unloadScene(): void;
+    /** Ends every effect and removes the layers (`Game.dispose()`). */
+    dispose(): void;
+    /** Engine-internal: see advanceCameraEffects. */
+    [ADVANCE](): void;
+    /** Engine-internal: see layoutCameraEffects. */
+    [LAYOUT](rect: ViewportRect): void;
+    /** Normalized progress of a timed effect after the current step: 1 at (and past) its end. */
+    private progress;
+    private advanceShakes;
+    /** Mirrors both layers' state onto their elements, mounting them on first need. */
+    private draw;
+    private mount;
+    /** Sizes a layer to the game viewport (the whole host until the Game lays it out). */
+    private place;
+    private invalid;
+}
+/**
+ * Engine-internal: advances every Camera Effect by exactly one Simulation
+ * Step. `Game.simulateStep()` calls it right after the scene camera, so
+ * nothing advances while the Game is not simulating. Not re-exported from
+ * the package entry.
+ */
+export declare function advanceCameraEffects(effects: CameraEffects): void;
+/** Engine-internal: sizes the Fade and Flash layers to the game viewport (`Game.resize()`). */
+export declare function layoutCameraEffects(effects: CameraEffects, rect: ViewportRect): void;
+export {};

package/dist/camera-effects.js

@@ -0,0 +1,338 @@
+import { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
+import { resolveEasing } from './game-time.js';
+const COLORS = new Map([
+    ['black', '#000000'],
+    ['white', '#ffffff'],
+]);
+/** Above the UI overlay (`ui.ts`, z-index 9000): a Fade covers the HUD too. */
+const FADE_Z = 9001;
+const FLASH_Z = 9002;
+const ADVANCE = Symbol('waica.cameraEffects.advance');
+const LAYOUT = Symbol('waica.cameraEffects.layout');
+function normalizeColor(value) {
+    if (typeof value !== 'string')
+        return null;
+    const named = COLORS.get(value);
+    if (named !== undefined)
+        return named;
+    return /^#[0-9a-fA-F]{6}$/.test(value) ? value.toLowerCase() : null;
+}
+function validSeconds(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function easingOf(value) {
+    if (value !== undefined && typeof value !== 'string')
+        return null;
+    return resolveEasing(value);
+}
+/**
+ * Integer-only hash of (shake creation step, current step, axis) into
+ * [0, 1): the same bits in Node and every browser (spec inference 3), so a
+ * Run Session reproduces a shake frame for frame. No global RNG.
+ */
+function jitter(seed, step, axis) {
+    let h = (Math.imul(seed + 1, 0x9e3779b1) ^ Math.imul(step + 1, 0x85ebca77) ^ Math.imul(axis + 1, 0xc2b2ae3d)) >>> 0;
+    h = Math.imul(h ^ (h >>> 16), 0x7feb352d) >>> 0;
+    h = Math.imul(h ^ (h >>> 15), 0x846ca68b) >>> 0;
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+function settledHandle(done, cancel, superseded) {
+    return {
+        cancel,
+        done,
+        get superseded() {
+            return superseded();
+        },
+    };
+}
+/**
+ * Screen-level Camera Effects (issue #74, ADR 0020): Shake, Fade and Flash,
+ * beside `game.camera` and never written into it. They advance only inside
+ * a Simulation Step, right after the scene camera (spec inference 9), so
+ * nothing moves while the Game is not simulating or a Run Session is
+ * paused. A Shake is an offset the Game adds to the camera only while it
+ * draws; a Fade and a Flash are HTML layers over the letterboxed game
+ * viewport, above the UI overlay. A Fade is session-scoped (it survives a
+ * scene change, ADR 0011); a Shake or Flash dies with its scene.
+ */
+export class CameraEffects {
+    options;
+    steps = 0;
+    shakes = [];
+    offset = { x: 0, y: 0 };
+    fadeRun = null;
+    flashRun = null;
+    fadeLayer = { color: '#000000', opacity: 0, element: null };
+    flashLayer = { color: '#ffffff', opacity: 0, element: null };
+    rect = null;
+    constructor(options) {
+        this.options = options;
+    }
+    /** A fresh copy of the effects after the last completed Simulation Step. */
+    get state() {
+        return {
+            shake: { ...this.offset },
+            fade: { color: this.fadeLayer.color, opacity: this.fadeLayer.opacity },
+            flash: { color: this.flashLayer.color, opacity: this.flashLayer.opacity },
+        };
+    }
+    /**
+     * Jitters the drawn view by up to `intensity` world units per axis,
+     * decaying to 0 over `seconds`. Overlapping shakes apply the largest
+     * current amplitude. Not re-clamped to the scene camera's limits; snapped
+     * to whole screen pixels under a fixed resolution.
+     */
+    shake(options) {
+        const { intensity, seconds } = options;
+        if (!validSeconds(intensity))
+            return this.invalid('shake(): intensity must be a finite number >= 0');
+        if (!validSeconds(seconds))
+            return this.invalid('shake(): seconds must be a finite number >= 0');
+        const ease = easingOf(options.easing);
+        if (!ease)
+            return this.invalid('shake(): easing must be a known easing name');
+        let resolve = () => { };
+        const done = new Promise((r) => (resolve = r));
+        const entry = { start: this.steps, seconds, ease, resolve, intensity, superseded: false };
+        this.shakes.push(entry);
+        return settledHandle(done, () => {
+            const index = this.shakes.indexOf(entry);
+            if (index === -1)
+                return;
+            this.shakes.splice(index, 1);
+            entry.resolve(false);
+        }, 
+        // Never superseded (CA-7): overlapping shakes coexist, so nothing
+        // ever sets a Shake entry's flag; it stays false for its own life.
+        () => entry.superseded);
+    }
+    /**
+     * Carries the Fade layer from its current opacity to 1 in `to`'s color,
+     * or to 0 with `'clear'`, over `seconds`; the result then holds. A new
+     * fade cancels a running one (its `done` resolves false).
+     */
+    fade(options) {
+        const clear = options.to === 'clear';
+        const color = clear ? this.fadeLayer.color : normalizeColor(options.to);
+        if (!color)
+            return this.invalid(`fade(): unknown color "${String(options.to)}"; use 'black', 'white', '#rrggbb' or 'clear'`);
+        if (!validSeconds(options.seconds))
+            return this.invalid('fade(): seconds must be a finite number >= 0');
+        const ease = easingOf(options.easing);
+        if (!ease)
+            return this.invalid('fade(): easing must be a known easing name');
+        // Marks the outgoing fade superseded (not just cancelled) before
+        // resolving `done` false: a caller checking `.superseded` later must
+        // see this, whatever happens to the layer afterwards (PR #98 review).
+        if (this.fadeRun)
+            this.fadeRun.superseded = true;
+        this.fadeRun?.resolve(false);
+        let resolve = () => { };
+        const done = new Promise((r) => (resolve = r));
+        const entry = {
+            start: this.steps,
+            seconds: options.seconds,
+            ease,
+            resolve,
+            from: this.fadeLayer.opacity,
+            to: clear ? 0 : 1,
+            superseded: false,
+        };
+        this.fadeRun = entry;
+        this.fadeLayer.color = color;
+        this.draw();
+        return settledHandle(done, () => {
+            if (this.fadeRun !== entry)
+                return;
+            this.fadeRun = null;
+            entry.resolve(false);
+        }, () => entry.superseded);
+    }
+    /**
+     * Shows the Flash layer at opacity 1 in `color` and returns it to exactly
+     * 0 over `seconds`, independent of (and drawn above) the Fade. A new flash
+     * replaces a running one.
+     */
+    flash(options) {
+        const color = normalizeColor(options.color);
+        if (!color)
+            return this.invalid(`flash(): unknown color "${String(options.color)}"; use 'black', 'white' or '#rrggbb'`);
+        if (!validSeconds(options.seconds))
+            return this.invalid('flash(): seconds must be a finite number >= 0');
+        if (this.flashRun)
+            this.flashRun.superseded = true;
+        this.flashRun?.resolve(false);
+        let resolve = () => { };
+        const done = new Promise((r) => (resolve = r));
+        const entry = { start: this.steps, seconds: options.seconds, ease: (t) => t, resolve, superseded: false };
+        this.flashRun = entry;
+        this.flashLayer.color = color;
+        this.flashLayer.opacity = 1;
+        this.draw();
+        return settledHandle(done, () => {
+            if (this.flashRun !== entry)
+                return;
+            this.flashRun = null;
+            this.flashLayer.opacity = 0;
+            this.draw();
+            entry.resolve(false);
+        }, () => entry.superseded);
+    }
+    /**
+     * Ends every Shake and Flash (their `done` resolves false) and keeps the
+     * Fade — opacity, color and any running progress. Called by
+     * `Game.unloadScene()`.
+     */
+    unloadScene() {
+        for (const shake of this.shakes.splice(0))
+            shake.resolve(false);
+        this.offset = { x: 0, y: 0 };
+        this.flashRun?.resolve(false);
+        this.flashRun = null;
+        this.flashLayer.opacity = 0;
+        this.draw();
+    }
+    /** Ends every effect and removes the layers (`Game.dispose()`). */
+    dispose() {
+        this.unloadScene();
+        this.fadeRun?.resolve(false);
+        this.fadeRun = null;
+        this.fadeLayer.color = '#000000';
+        this.fadeLayer.opacity = 0;
+        for (const layer of [this.fadeLayer, this.flashLayer]) {
+            layer.element?.remove();
+            layer.element = null;
+        }
+    }
+    /** Engine-internal: see advanceCameraEffects. */
+    [ADVANCE]() {
+        this.steps += 1;
+        this.advanceShakes();
+        const fade = this.fadeRun;
+        if (fade) {
+            const t = this.progress(fade);
+            this.fadeLayer.opacity = t >= 1 ? fade.to : fade.from + (fade.to - fade.from) * fade.ease(t);
+            if (t >= 1) {
+                this.fadeRun = null;
+                fade.resolve(true);
+            }
+        }
+        const flash = this.flashRun;
+        if (flash) {
+            const t = this.progress(flash);
+            this.flashLayer.opacity = t >= 1 ? 0 : 1 - flash.ease(t);
+            if (t >= 1) {
+                this.flashRun = null;
+                flash.resolve(true);
+            }
+        }
+        this.draw();
+    }
+    /** Engine-internal: see layoutCameraEffects. */
+    [LAYOUT](rect) {
+        this.rect = { ...rect };
+        for (const layer of [this.fadeLayer, this.flashLayer]) {
+            if (layer.element)
+                this.place(layer.element);
+        }
+    }
+    /** Normalized progress of a timed effect after the current step: 1 at (and past) its end. */
+    progress(entry) {
+        const elapsed = (this.steps - entry.start) * SIMULATION_STEP;
+        if (elapsed >= entry.seconds - SIMULATION_TIME_EPSILON)
+            return 1;
+        return elapsed / entry.seconds;
+    }
+    advanceShakes() {
+        let amplitude = 0;
+        let seed = 0;
+        for (const shake of [...this.shakes]) {
+            const t = this.progress(shake);
+            if (t >= 1) {
+                this.shakes.splice(this.shakes.indexOf(shake), 1);
+                shake.resolve(true);
+                continue;
+            }
+            const current = shake.intensity * (1 - shake.ease(t));
+            if (current > amplitude) {
+                amplitude = current;
+                seed = shake.start;
+            }
+        }
+        if (amplitude <= 0) {
+            this.offset = { x: 0, y: 0 };
+            return;
+        }
+        const pixel = this.options.pixel();
+        const axis = (index) => {
+            const raw = amplitude * (2 * jitter(seed, this.steps, index) - 1);
+            // Truncating toward zero keeps a snapped offset inside the envelope.
+            const snapped = pixel ? Math.trunc(raw / pixel) * pixel : raw;
+            return snapped + 0;
+        };
+        this.offset = { x: axis(0), y: axis(1) };
+    }
+    /** Mirrors both layers' state onto their elements, mounting them on first need. */
+    draw() {
+        const needed = this.fadeLayer.opacity > 0 || this.flashLayer.opacity > 0;
+        if (needed && !this.fadeLayer.element)
+            this.mount();
+        for (const layer of [this.fadeLayer, this.flashLayer]) {
+            const element = layer.element;
+            if (!element)
+                continue;
+            element.style.backgroundColor = layer.color;
+            element.style.opacity = String(layer.opacity);
+            element.style.display = layer.opacity > 0 ? '' : 'none';
+        }
+    }
+    mount() {
+        const host = this.options.host();
+        if (getComputedStyle(host).position === 'static')
+            host.style.position = 'relative';
+        for (const [layer, name, z] of [
+            [this.fadeLayer, 'fade', FADE_Z],
+            [this.flashLayer, 'flash', FLASH_Z],
+        ]) {
+            const element = document.createElement('div');
+            element.dataset.waicaCameraEffect = name;
+            element.style.position = 'absolute';
+            element.style.pointerEvents = 'none';
+            element.style.zIndex = String(z);
+            element.style.display = 'none';
+            this.place(element);
+            host.append(element);
+            layer.element = element;
+        }
+    }
+    /** Sizes a layer to the game viewport (the whole host until the Game lays it out). */
+    place(element) {
+        const rect = this.rect;
+        if (!rect) {
+            element.style.inset = '0';
+            return;
+        }
+        element.style.inset = '';
+        element.style.left = `${rect.x}px`;
+        element.style.top = `${rect.y}px`;
+        element.style.width = `${rect.width}px`;
+        element.style.height = `${rect.height}px`;
+    }
+    invalid(message) {
+        console.warn(`[waica] cameraEffects.${message}`);
+        return settledHandle(Promise.resolve(false), () => { }, () => false);
+    }
+}
+/**
+ * Engine-internal: advances every Camera Effect by exactly one Simulation
+ * Step. `Game.simulateStep()` calls it right after the scene camera, so
+ * nothing advances while the Game is not simulating. Not re-exported from
+ * the package entry.
+ */
+export function advanceCameraEffects(effects) {
+    effects[ADVANCE]();
+}
+/** Engine-internal: sizes the Fade and Flash layers to the game viewport (`Game.resize()`). */
+export function layoutCameraEffects(effects, rect) {
+    effects[LAYOUT](rect);
+}