Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

100 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    app.ts
 * @brief   Application builder and web platform integration
 */

import { World } from '../ecs/world';

import { applyAppOptions, applyColorSpace, applyFrameOptions } from './renderOptions';
import type { QualityConfig } from '../render/quality';
import { Schedule, SystemDef, SystemRunner, SystemSet, mergeOrderingEdges, rescopeSystem, type RunCondition } from '../ecs/system';
import { builtinResource, declaredResource, ResourceStorage, Time, TimeData, type ResourceDef } from '../ecs/resource';
import { Speculation, SpeculationInstance } from '../ecs/speculation';
import { prepareAot, type AotHost } from '../ecs/aot/installAot';
import { installNativeAot, nativeAotBindings } from '../ecs/aot/installNativeAot';
import { createNativeHeap } from '../ecs/bridge/nativeHeap';
import type { AotManifest } from '../ecs/aot/AotSystems';
import type { AotRuntime } from '../ecs/aot/AotRuntime';
import { EventRegistry, eventNamed, type EventDef } from '../ecs/event';
import type { ESEngineModule, CppRegistry } from '../wasm';
import type { OutputTransform } from '../postprocess';
import type { BridgeConnectOptions } from '../ecs/bridge/BuiltinBridge';
import { UICameraInfo } from '../ui/core/ui-camera-info';
import { ScreenLayout } from '../ui/core/screen-layout';
import { ScreenOverlay, defaultScreenOverlay } from '../ui/core/screen-overlay';
import { inputPlugin, Input, setInputExecutionHeld } from '../input/input';
import { assetPlugin } from '../asset';
import { prefabsPlugin } from '../prefab/prefabServer';
import { breakablePlugin } from '../breakable/breakable';
import { setWasmErrorHandler } from '../wasm/wasmError';
import { corePlugin, DEFAULT_UI_CAMERA_INFO } from './corePlugin';
import {
    ancestors,
    dependencyEdges,
    detectAmbiguities,
    parallelBatches,
    type Ambiguity,
    type ResolveTargets,
} from './ambiguity';
import { accessOf, conflicts, type SystemAccess } from './access';
import { platformNow } from '../platform';
import { RenderPipeline } from '../render/renderPipeline';
import type { SceneConfig } from '../scene/sceneManager';
import { SceneManager } from '../scene/sceneManager';
import { sceneManagerPlugin } from '../scene/scenePlugin';
import { getDefaultContext } from '../ecs/context';
import { seedEngineComponents, type AnyComponentDef } from '../ecs/component';
import { cameraPlugin } from '../camera/CameraPlugin';
import type { ScreenScalingData } from '../camera/ScreenScaling';
import { Physics2DRuntime } from '../physics/Physics2DRuntime';
import { SubsystemRegistry } from './subsystems';
import { DOMAIN_SCRIPTS, DOMAIN_UNATTRIBUTED, type ScopeCost, type ScopeRemainder, type SystemCost } from './frameProfile';
import type { SideModuleHost } from '../sideModules/host';
import { watchWebGPUDeviceLoss } from '../render/renderer';
import { log } from '../util/logger';

const hostPauseOwners = new WeakMap<App, Set<object>>();

/** Internal host pause ownership, independent of the game's setPaused intent. */
export function setAppHostPaused(app: App, owner: object, paused: boolean): void {
    if (paused) {
        let owners = hostPauseOwners.get(app);
        if (!owners) hostPauseOwners.set(app, owners = new Set());
        owners.add(owner);
    } else {
        const owners = hostPauseOwners.get(app);
        owners?.delete(owner);
        if (!owners?.size) hostPauseOwners.delete(app);
    }
}

// =============================================================================
// Plugin Interface
// =============================================================================

export type PluginDependency = string | ResourceDef<any>;

export interface Plugin {
    name?: string;
    dependencies?: PluginDependency[];
    before?: string[];
    after?: string[];
    /** Cost domain the profiler files this plugin's systems under. Defaults to
     *  `name`; declare it where the two differ, as `camera` producing `render`. */
    profileDomain?: string;
    /**
     * The components this plugin's work is about: while no entity has any of them,
     * its systems are not run — a game that never places water pays nothing for the
     * water plugin each frame. They keep running for one frame after the last one
     * goes, so a plugin can release what it held. Absent: always run.
     */
    activeWhen?: readonly AnyComponentDef[];
    build(app: App): void;
    finish?(app: App): void;
    /** Releases acquired resources on quit or a failed build; must tolerate a
     * partially completed build. */
    cleanup?(app?: App): void;
}

// =============================================================================
// System Entry
// =============================================================================

export type { RunCondition };

/** One frame's costs, attributed. The input `buildFrameProfile` folds. */
export interface FrameCosts {
    systems: SystemCost[];
    scopes: ScopeCost[];
}

/**
 * @experimental What the loop's own clock read for one completed frame. The one
 * place frame time is measured: the profiler, the debug channel and the quality
 * controller all take it from here instead of each keeping a clock.
 */
export interface FrameTiming {
    /** Counts completed frames, so a reader can tell a new one from the last. */
    seq: number;
    /** Interval since the previous frame, before simulation speed or delta clamping. */
    frameMs: number;
    /**
     * How long this frame's own run took, first system to last; -1 where there is
     * no clock. What is left of `frameMs` is time the loop waited for its next
     * turn, so a frame that came late with this inside the budget was not held up
     * by its systems.
     */
    busyMs: number;
}

/** A system still running, and what decides who may start beside it. */
interface InflightSystem {
    /** Its position in the sorted list — how a dependant recognises it. */
    index: number;
    access: SystemAccess;
    done: Promise<void>;
}

/** One plugin's {@link Plugin.activeWhen}, decided once a frame for all its systems. */
interface ActivityGate {
    readonly components: readonly AnyComponentDef[];
    frame: number;
    open: boolean;
    /** Whether any of them existed when last decided: the frame after the last goes still runs. */
    present: boolean;
}

interface SystemEntry {
    startupInvoked?: boolean;
    /** Skipped while the owning plugin's components are absent (see Plugin.activeWhen). */
    gate?: ActivityGate;
    system: SystemDef;
    runBefore?: string[];
    runAfter?: string[];
    runIf?: RunCondition;
    /** The subsystem (owning plugin name) this system belongs to — pets that
     *  subsystem's liveness watchdog when it runs (observability). */
    subsystem?: string;
    /** Came through the project bundle's pending-systems drain — the set hot
     *  reload may swap. "No owning subsystem" is NOT that set: engine systems
     *  registered lazily outside a plugin build (the physics event bridge, the
     *  hot-update rebind) carry no subsystem either, and mistaking them for
     *  user systems vetoed every hot swap in any project that had physics. */
    fromBundle?: boolean;
    /** Cost domain, from the building plugin or the door it came through. */
    domain: string;
}

/**
 * How a rejected schedule reads back to whoever wrote it. The two mistakes that
 * get here look nothing alike in the source and identically at runtime, so the
 * message has to tell them apart: a member that does not exist arrives as
 * `undefined`, and swapped arguments arrive as the system itself.
 */
function describeSchedule(value: unknown): string {
    if (value === undefined) return 'undefined (no such Schedule member?)';
    if (value === null) return 'null';
    if (typeof value === 'number' || typeof value === 'string') return JSON.stringify(value);
    const name = (value as { _name?: unknown } | null)?._name;
    if (typeof name === 'string') return `the system "${name}" (arguments the wrong way round?)`;
    return Object.prototype.toString.call(value);
}

// =============================================================================
// App
// =============================================================================


/** How early a capped frame may land and still count as on time: vsync jitter. */
const CAP_JITTER_MS = 1;
export class App {
    private readonly world_: World;
    private readonly resources_: ResourceStorage;
    private readonly systems_ = new Map<Schedule, SystemEntry[]>();
    private runner_: SystemRunner | null = null;
    /** Whether the once-per-app boot work has run. Not `runner_ !== null`: a
     *  compiled-systems install needs the runner BEFORE the first tick, and
     *  reading the boot from its existence would then skip that work forever. */
    private booted_ = false;
    /** The compiled twins a build installed, or null where it made none. */
    private aot_: AotRuntime | null = null;
    private systemCounter_ = 0;
    private readonly templateToRuntime_ = new Map<symbol, symbol>();
    /** Set name -> runtime system names registered under that set, for dep expansion. */
    private readonly setMembership_ = new Map<string, string[]>();

    private running_ = false;
    private readonly executionHolds_ = new Set<object>();
    private executionEpoch_ = 0;
    private readonly executionObservers_: Array<(held: boolean) => void> = [];
    private loopVersion_ = 0;
    private queuedFrame_: number | null = null;
    /** Whether {@link queuedFrame_} is a timer (hidden + runInBackground) rather than a rAF id. */
    private queuedOnTimer_ = false;
    private runInBackground_ = false;
    private onVisibility_: (() => void) | null = null;
    private frameInFlight_: Promise<void> | null = null;
    private frameTiming_: FrameTiming | null = null;
    private lastTime_ = 0;
    private fixedTimestep_ = 1 / 60;
    private fixedAccumulator_ = 0;
    private maxDeltaTime_ = 0.25;
    private maxFixedSteps_ = 8;
    // Spiral-of-death guard: cap wall time spent on fixed-step catch-up per frame.
    // A sim too heavy to run real-time (e.g. thousands of bodies) then degrades to
    // slow motion instead of freezing — the frame stays responsive. The first step
    // always runs (the check is after a step), so the sim always advances.
    private fixedStepBudgetMs_ = 8;
    private targetFrameInterval_ = 0;
    private nextCapFrameAt_ = 0;

    private module_: ESEngineModule | null = null;
    private ownedCppRegistry_: CppRegistry | null = null;
    private pipeline_: RenderPipeline | null = null;
    private spineInitPromise_?: Promise<unknown>;
    private compiledInstallTail_: Promise<void> = Promise.resolve();
    private readonly installed_plugins_: Plugin[] = [];
    private readonly installedPluginSet_ = new Set<Plugin>();
    private readonly installedPluginNames_ = new Set<string>();
    // Per-App (per-realm) so isolated realms never alias; not a shared resource default.
    private readonly subsystems_ = new SubsystemRegistry();
    /** The plugin currently in build(), so systems it adds inherit its name for
     *  liveness reporting. Null outside a build. */
    private buildingPlugin_: string | null = null;
    /** The cost domain of that plugin, which is its name unless it declared one. */
    private buildingDomain_: string | null = null;
    private buildingGate_: ActivityGate | null = null;
    /** Registration undo actions for the current build; nested builds own theirs. */
    private buildRollback_: Array<() => void> | null = null;
    private addingBundleSystems_ = false;
    // The realm's acquirer for optional native modules (physics, spine). Set once
    // at app creation; physics/spine self-gate off it. Null in headless/test apps.
    private sideModules_: SideModuleHost | null = null;
    /** This App made the host, so quitting disposes it; one handed in is its maker's to end. */
    private ownsSideModules_ = false;
    private pluginsFinished_ = false;
    private readonly eventRegistry_ = new EventRegistry();
    private readonly sortedSystemsCache_ = new Map<Schedule, SystemEntry[]>();
    /** Transitive ordering, per schedule. Invalidated with the sort it follows. */
    private readonly dependencyCache_ = new Map<Schedule, Set<number>[]>();
    private error_handler_: ((error: unknown, systemName: string) => void) | null = null;
    private system_error_handler_: ((error: Error, systemName?: string) => 'continue' | 'pause') | null = null;
    private statsEnabled_ = false;
    private phaseTimings_: Map<string, number> | null = null;
    // Sub-frame CPU scopes inside a single system (e.g. the render system's
    // resolveCameras / submit split) — the JS-side sibling of the engine's C++
    // ES_PROFILE_SCOPE. Null unless stats are on; same per-frame lifecycle as
    // phaseTimings_ (cleared at tick start, read after the tick).
    private frameScopes_: Map<string, ScopeCost> | null = null;
    /** The system being run, so a scope opened inside one is filed under it. */
    private currentSystem_ = '';
    private readonly openScopes_: string[] = [];
    private readonly frameObservers_: Array<(dtMs: number) => void> = [];
    private frame_paused_ = false;
    private user_paused_ = false;
    private step_pending_ = false;
    private steppedFrames_ = 0;
    private play_speed_ = 1.0;

    private constructor() {
        this.world_ = new World();
        this.resources_ = new ResourceStorage();

        for (const s of Object.values(Schedule)) {
            if (typeof s === 'number') {
                this.systems_.set(s, []);
            }
        }
    }

    static new(): App {
        return new App();
    }

    // =========================================================================
    // Plugins
    // =========================================================================

    getPlugin<T extends Plugin>(ctor: new (...args: any[]) => T): T | undefined {
        return this.installed_plugins_.find((p): p is T => p instanceof ctor);
    }

    /** Subsystem lifecycle registry ("which modules loaded/ready/stepping/errored").
     *  Named plugins auto-register in {@link addPlugin}; async plugins (physics)
     *  drive their own initializing→ready/error transitions. */
    get subsystems(): SubsystemRegistry {
        return this.subsystems_;
    }

    /** The realm's optional-native-module acquirer (physics, spine). Physics and
     *  spine pull their wasm from here, so a realm wires its transport once
     *  (fetch / inlined / WeChat) and every subsystem follows. */
    get sideModules(): SideModuleHost | null {
        return this.sideModules_;
    }

    /**
     * `owned` says the host was made for this App alone: quitting then disposes
     * it, with the workers and module instances tied to it. A host shared with
     * anything else is left as it is, and whoever made it disposes it.
     */
    setSideModules(host: SideModuleHost, options?: { owned?: boolean }): void {
        this.sideModules_ = host;
        this.ownsSideModules_ = options?.owned === true;
    }

    addPlugins(plugins: Plugin[]): this {
        const sorted = this.sortPlugins(plugins);
        for (const plugin of sorted) {
            this.addPlugin(plugin);
        }
        return this;
    }

    addPlugin(plugin: Plugin): this {
        if (this.quitting_) throw new Error('Cannot install plugins while App.quit is running');
        if (this.installedPluginSet_.has(plugin)) return this;
        if (plugin.dependencies) {
            for (const dep of plugin.dependencies) {
                if (typeof dep === 'string') {
                    if (!this.installedPluginNames_.has(dep)) {
                        throw new Error(
                            `Plugin "${plugin.name ?? 'unknown'}" requires plugin "${dep}" which has not been installed`
                        );
                    }
                } else {
                    if (!this.hasResource(dep)) {
                        throw new Error(
                            `Plugin "${plugin.name ?? 'unknown'}" requires resource "${dep._name}" which has not been registered`
                        );
                    }
                }
            }
        }
        this.installedPluginSet_.add(plugin);
        this.installed_plugins_.push(plugin);
        if (plugin.name) {
            this.installedPluginNames_.add(plugin.name);
            // Observable from frame zero; string deps give the status UI cascade context.
            this.subsystems_.register(plugin.name, {
                dependsOn: plugin.dependencies?.filter(
                    (d): d is string => typeof d === 'string',
                ),
            });
        }
        const prevBuilding = this.buildingPlugin_;
        const prevDomain = this.buildingDomain_;
        const prevGate = this.buildingGate_;
        const prevRollback = this.buildRollback_;
        const rollback: Array<() => void> = [];
        const buildEpoch = this.quitEpoch_;
        this.buildRollback_ = rollback;
        this.buildingPlugin_ = plugin.name ?? null;
        this.buildingDomain_ = plugin.profileDomain ?? plugin.name ?? null;
        this.buildingGate_ = plugin.activeWhen?.length
            ? { components: plugin.activeWhen, frame: -1, open: true, present: true } : null;
        try {
            plugin.build(this);
            // Sync plugin: live once build() returns → promote. An async plugin
            // (physics) already moved itself off `registered`, so this skips it.
            if (plugin.name && this.subsystems_.phaseOf(plugin.name) === 'registered') {
                this.subsystems_.transition(plugin.name, 'ready');
            }
            // A child installed inside this build remains provisional until the
            // enclosing build commits. Pre-existing plugins never reach here.
            prevRollback?.push(() => this.rollbackPluginBuild_(plugin, rollback, buildEpoch,
                'Enclosing plugin build failed'));
        } catch (e) {
            this.buildRollback_ = null;
            this.rollbackPluginBuild_(plugin, rollback, buildEpoch, e instanceof Error ? e.message : String(e));
            throw e;
        } finally {
            this.buildingPlugin_ = prevBuilding;
            this.buildingDomain_ = prevDomain;
            this.buildingGate_ = prevGate;
            this.buildRollback_ = prevRollback;
        }
        return this;
    }

    private rollbackPluginBuild_(plugin: Plugin, rollback: Array<() => void>, epoch: number, reason: string): void {
        this.installedPluginSet_.delete(plugin);
        const index = this.installed_plugins_.indexOf(plugin);
        if (index >= 0) this.installed_plugins_.splice(index, 1);
        if (plugin.name) {
            if (!this.installed_plugins_.some(p => p.name === plugin.name)) this.installedPluginNames_.delete(plugin.name);
            this.subsystems_.markError(plugin.name, reason);
        }
        // Child resources are released before their parent's, matching quit.
        // Withdraw systems even if resource cleanup throws.
        for (let i = rollback.length - 1; i >= 0 && this.quitEpoch_ === epoch; i--) {
            try { rollback[i](); } catch (rollbackError) {
                log.error('app', 'Failed plugin registration rollback error', rollbackError);
            }
        }
        // Already removed above: a cleanup that quits cannot clean this twice.
        try { if (index >= 0) plugin.cleanup?.(this); } catch (cleanupError) {
            log.error('app', 'Failed plugin build cleanup error', cleanupError);
        }
    }

    addEvent<T>(event: EventDef<T>): this {
        this.eventRegistry_.register(event);
        return this;
    }

    // =========================================================================
    // Systems
    // =========================================================================

    /**
     * The entry list for `schedule`, or a refusal that says what was wrong.
     *
     * Every valid schedule gets its list in the constructor, so a miss means the
     * caller passed something that is not a Schedule — a member that does not
     * exist (`Schedule.LateUpdate` evaluates to `undefined`), or the two
     * arguments the wrong way round. Neither is caught before it runs: the
     * editor and the mini-game exporters bundle project code with esbuild, which
     * strips types without checking them, so a registration TypeScript would
     * have rejected reaches the App intact.
     *
     * It used to be `systems_.get(schedule)!`, which turned both into "Cannot
     * read properties of undefined (reading 'push')" thrown from inside a
     * minified bundle, naming neither the system nor the value.
     */
    /** Whether a plugin's systems run this frame: some entity has one of its components, or had last frame. */
    private gateOpen_(gate: ActivityGate): boolean {
        const frame = this.hasResource(Time) ? this.getResource(Time).frameCount : 0;
        if (gate.frame === frame) return gate.open;
        const world = this.world;
        let present = false;
        for (const c of gate.components) {
            // A cached query: unchanged structure answers without walking anything.
            // A core that cannot answer for the component (compiled out) is not a
            // reason to stop the plugin: it runs as it did before there was a gate.
            try {
                if (world.queryEntities([c]).length > 0) { present = true; break; }
            } catch {
                present = true;
                break;
            }
        }
        gate.open = present || gate.present;
        gate.present = present;
        gate.frame = frame;
        return gate.open;
    }

    private registeringDomain_(): string {
        if (this.buildingDomain_) return this.buildingDomain_;
        return this.addingBundleSystems_ ? DOMAIN_SCRIPTS : DOMAIN_UNATTRIBUTED;
    }

    private scheduleBucket_(schedule: Schedule, systemName: string): SystemEntry[] {
        const bucket = this.systems_.get(schedule);
        if (bucket) return bucket;
        const valid = Object.entries(Schedule)
            .filter(([, v]) => typeof v === 'number')
            .map(([k, v]) => `${k} (${String(v)})`)
            .join(', ');
        throw new Error(
            `addSystemToSchedule("${systemName}"): ${describeSchedule(schedule)} is not a schedule. `
            + `Expected one of: ${valid}. `
            + `Check the Schedule member exists, and that the schedule comes before the system.`,
        );
    }

    /**
     * Register `system` onto `schedule`, adding ordering to its declared edges.
     * `profileDomain` attributes systems registered after an async plugin build
     * returns; otherwise the current build context supplies it.
     */
    addSystemToSchedule(
        schedule: Schedule,
        system: SystemDef,
        options?: {
            runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string;
            /** This system alone, gated as Plugin.activeWhen gates a whole plugin: skipped while no
             *  entity has any of these, and run one frame past the last. Takes precedence over the
             *  building plugin's gate. */
            activeWhen?: readonly AnyComponentDef[];
        }
    ): this {
        const name = system._name || `System_${++this.systemCounter_}`;
        const scoped = rescopeSystem(system, name);
        this.registerSystemEntry_(schedule, system._id, {
            system: scoped,
            runBefore: mergeOrderingEdges(system._runBefore, options?.runBefore),
            runAfter: mergeOrderingEdges(system._runAfter, options?.runAfter),
            runIf: options?.runIf,
            subsystem: this.buildingPlugin_ ?? undefined,
            fromBundle: this.addingBundleSystems_ || undefined,
            domain: options?.profileDomain ?? this.registeringDomain_(),
            ...(options?.activeWhen?.length
                ? { gate: { components: options.activeWhen, frame: -1, open: true, present: true } }
                : this.buildingGate_ ? { gate: this.buildingGate_ } : {}),
        });
        this.sortedSystemsCache_.delete(schedule);
        this.dependencyCache_.delete(schedule);
        return this;
    }

    private registerSystemEntry_(schedule: Schedule, templateId: symbol, entry: SystemEntry): void {
        const bucket = this.scheduleBucket_(schedule, entry.system._name);
        const previous = this.templateToRuntime_.get(templateId);
        this.templateToRuntime_.set(templateId, entry.system._id);
        bucket.push(entry);
        this.buildRollback_?.push(() => {
            const live = this.systems_.get(schedule);
            const index = live?.indexOf(entry) ?? -1;
            if (index >= 0) live!.splice(index, 1);
            this.sortedSystemsCache_.delete(schedule);
            this.dependencyCache_.delete(schedule);
            this.runner_?.evict(entry.system._id);
            // A successful nested plugin may have registered the same template.
            if (this.templateToRuntime_.get(templateId) === entry.system._id) {
                if (previous === undefined) this.templateToRuntime_.delete(templateId);
                else this.templateToRuntime_.set(templateId, previous);
            }
        });
    }

    addSystem(system: SystemDef): this {
        return this.addSystemToSchedule(Schedule.Update, system);
    }

    /**
     * Register systems drained from the PROJECT BUNDLE, marking them as the set
     * hot reload may swap. The bundle drain is the one boundary that separates
     * user-authored systems from everything the engine registers — plugin
     * builds tag themselves, but lazily-added engine systems are told apart
     * from user code only by which door they came through.
     * @internal
     */
    addBundleSystems(entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet }>): this {
        this.addingBundleSystems_ = true;
        try {
            for (const e of entries) {
                // A set expands to its members here, so everything downstream —
                // hot reload included — still sees a flat list of user systems.
                if ((e.system as SystemSet)._kind === 'set') {
                    this.addSystemSetToSchedule(e.schedule as Schedule, e.system as SystemSet);
                } else {
                    this.addSystemToSchedule(e.schedule as Schedule, e.system as SystemDef);
                }
            }
        } finally {
            this.addingBundleSystems_ = false;
        }
        return this;
    }

    addStartupSystem(system: SystemDef): this {
        return this.addSystemToSchedule(Schedule.Startup, system);
    }

    /**
     * Hot-swap the project's (user-authored) system function bodies in place, keeping
     * the live World/Registry/entities — the state-preserving hot-reload fast path
     * (RC10 P3). `incoming` is the freshly re-imported bundle's drained systems.
     *
     * Returns false when the structure changed — a user system was added, removed, or
     * renamed, or a schedule's user-system count differs — because the running systems
     * then no longer line up with the new code, so the caller must full-reload instead.
     * Builtin/plugin systems (those with an owning subsystem) are never touched. The
     * match validates fully before mutating, so a rejected swap leaves the scheduler
     * untouched (no torn half-swap). Component identity is stable by name (see
     * component.ts), so the new functions' queries resolve to the live storage.
     */
    hotSwapSystems(incoming: ReadonlyArray<{ schedule: number; system: SystemDef }>): boolean {
        const bySchedule = new Map<Schedule, SystemDef[]>();
        for (const e of incoming) {
            const arr = bySchedule.get(e.schedule as Schedule);
            if (arr) arr.push(e.system);
            else bySchedule.set(e.schedule as Schedule, [e.system]);
        }
        const userEntries = (s: Schedule): SystemEntry[] =>
            (this.systems_.get(s) ?? []).filter((entry) => entry.fromBundle === true);

        // Startup is exempt from matching in both directions: its entries are
        // CONSUMED when they run (flushStartupSystems truncates the list), so the
        // live side is always empty while a re-imported bundle always queues them
        // again — requiring a match would veto hot swap for every project that
        // uses addStartupSystem. There is nothing to swap either way: a startup
        // body can only run on a cold start, so an edited one takes effect on the
        // next full reload, which is the only time it could.
        // Each rejection names the mismatch: "the structure changed" alone reads
        // as a hot reload that arbitrarily lost the World.
        for (const [schedule, defs] of bySchedule) {
            if (schedule === Schedule.Startup) continue;
            const live = userEntries(schedule);
            if (live.length !== defs.length) {
                log.info('hotReload', `structure: schedule ${Schedule[schedule]} has ${live.length} live user system(s) [${live.map((e) => e.system._name).join(', ')}] vs ${defs.length} incoming [${defs.map((d) => d._name || '(unnamed)').join(', ')}]`);
                return false;
            }
            for (let i = 0; i < live.length; i++) {
                if (!App.systemNamesCompatible(live[i].system._name, defs[i]._name)) {
                    log.info('hotReload', `structure: schedule ${Schedule[schedule]} system #${i} renamed "${live[i].system._name}" -> "${defs[i]._name || '(unnamed)'}"`);
                    return false;
                }
            }
        }
        // A schedule that had user systems the new bundle didn't re-add is structural.
        for (const [schedule, entries] of this.systems_) {
            if (schedule === Schedule.Startup) continue;
            if (!bySchedule.has(schedule) && entries.some((e) => e.fromBundle === true)) {
                log.info('hotReload', `structure: schedule ${Schedule[schedule]} lost its user systems in the new bundle`);
                return false;
            }
        }

        for (const [schedule, defs] of bySchedule) {
            if (schedule === Schedule.Startup) continue;
            const live = userEntries(schedule);
            for (let i = 0; i < live.length; i++) {
                const cur = live[i].system;
                live[i].system = { _id: cur._id, _params: defs[i]._params, _fn: defs[i]._fn, _name: cur._name };
            }
            this.sortedSystemsCache_.delete(schedule);
        this.dependencyCache_.delete(schedule);
        }
        return true;
    }

    /** A live (scoped) system name and a re-imported raw name refer to the same system
     *  if the live one is an explicit name that matches, or both are auto-named (the
     *  live `System_N` placeholder ⇔ an unnamed re-import). */
    private static systemNamesCompatible(liveName: string, rawName: string): boolean {
        return /^System_\d+$/.test(liveName) ? rawName === '' : rawName === liveName;
    }

    /**
     * Register every system in `set` onto `schedule`. Each member gets the set's
     * `runIf`, and the set's `runBefore` / `runAfter` edges on top of any it
     * declared itself; members keep the order they were listed in. Other systems
     * may reference the set's name in their own ordering, and the scheduler
     * expands those references to every member.
     */
    addSystemSetToSchedule(schedule: Schedule, set: SystemSet): this {
        const members: string[] = [];
        for (const sys of set._systems) {
            const name = sys._name || `System_${String(++this.systemCounter_)}`;
            members.push(name);

            const mergedRunBefore = mergeOrderingEdges(sys._runBefore, set._runBefore);
            const mergedRunAfter = mergeOrderingEdges(sys._runAfter, set._runAfter);
            const setCondition = set._runIf;
            const runIf: RunCondition | undefined = setCondition ? (() => setCondition()) : undefined;

            // Use the scoped system name the App would generate so ordering
            // lookups match. Mirrors addSystemToSchedule's naming path.
            const scoped = rescopeSystem(sys, name);
            this.registerSystemEntry_(schedule, sys._id, {
                system: scoped,
                runBefore: mergedRunBefore,
                runAfter: mergedRunAfter,
                runIf,
                subsystem: this.buildingPlugin_ ?? undefined,
                domain: this.registeringDomain_(),
            });
        }
        this.sortedSystemsCache_.delete(schedule);
        this.dependencyCache_.delete(schedule);

        const existing = this.setMembership_.get(set._name);
        const membership = existing ? [...existing, ...members] : members;
        this.setMembership_.set(set._name, membership);
        this.buildRollback_?.push(() => {
            if (this.setMembership_.get(set._name) !== membership) return;
            if (existing) this.setMembership_.set(set._name, existing);
            else this.setMembership_.delete(set._name);
        });
        return this;
    }

    /** Shortcut for `addSystemSetToSchedule(Schedule.Update, set)`. */
    addSystemSet(set: SystemSet): this {
        return this.addSystemSetToSchedule(Schedule.Update, set);
    }

    removeSystem(systemId: symbol): boolean {
        const runtimeId = this.templateToRuntime_.get(systemId) ?? systemId;
        let removed = false;
        for (const [schedule, entries] of this.systems_) {
            const filtered = entries.filter(e => e.system._id !== runtimeId);
            if (filtered.length !== entries.length) {
                this.systems_.set(schedule, filtered);
                this.sortedSystemsCache_.delete(schedule);
        this.dependencyCache_.delete(schedule);
                removed = true;
            }
        }
        if (removed) {
            this.runner_?.evict(runtimeId);
            this.templateToRuntime_.delete(systemId);
        }
        return removed;
    }

    // =========================================================================
    // C++ Integration
    // =========================================================================

    /**
     * Bind the app to an engine core. Part of the embedding contract, which is
     * `esengine/wasm` — a host builds the module and calls this; a game is
     * handed an App that is already connected.
     * `ownedRegistry` transfers a newly constructed instance to this App after
     * the connection guards pass; failed verification releases it too. Omit
     * it for a registry whose lifetime belongs to the embedding host.
     *
     * @internal
     */
    connectCpp(
        cppRegistry: CppRegistry,
        module?: ESEngineModule,
        options?: BridgeConnectOptions & { ownedRegistry?: boolean },
    ): this {
        if (this.quitting_) throw new Error('Cannot connect a registry while App.quit is releasing it');
        if (this.ownedCppRegistry_ && this.ownedCppRegistry_ !== cppRegistry) {
            throw new Error('Quit the App before replacing its owned registry');
        }
        // Factories transfer their newly constructed embind instance here.
        // External connections borrow by default. A failed connection must
        // release the transferred instance, preserving the original diagnostic.
        try { this.world_.connectCpp(cppRegistry, module, options); }
        catch (error) {
            if (options?.ownedRegistry && this.ownedCppRegistry_ !== cppRegistry) {
                this.world_.disconnectCpp();
                try { cppRegistry.delete(); }
                catch (releaseError) { log.warn('app', 'Failed registry connection release error', releaseError); }
            }
            throw error;
        }
        if (options?.ownedRegistry) this.ownedCppRegistry_ = cppRegistry;

        if (module) {
            this.module_ = module;
        }

        return this;
    }

    /** @internal */
    get wasmModule(): ESEngineModule | null {
        return this.module_;
    }

    get pipeline(): RenderPipeline | null {
        return this.pipeline_;
    }

    setPipeline(pipeline: RenderPipeline): void {
        this.pipeline_ = pipeline;
    }

    get spineInitPromise(): Promise<unknown> | undefined {
        return this.spineInitPromise_;
    }

    set spineInitPromise(p: Promise<unknown> | undefined) {
        this.spineInitPromise_ = p;
    }

    async waitForPhysics(): Promise<void> {
        if (!this.hasResource(Physics2DRuntime)) {
            log.warn('app', 'No Physics2DPlugin installed, waitForPhysics() is a no-op');
            return;
        }
        const promise = this.getResource(Physics2DRuntime).initPromise;
        if (promise) await promise;
    }

    get isPhysicsReady(): boolean {
        return this.hasResource(Physics2DRuntime)
            && this.getResource(Physics2DRuntime).module != null;
    }

    // =========================================================================
    // World Access
    // =========================================================================

    get world(): World {
        return this.world_;
    }

    /**
     * Run the compiled twins a build produced instead of the systems' closures.
     * Call it BEFORE the world has any pooled component: the rows must be in the
     * memory the module reads. Refuses rather than degrades — a module built for
     * other offsets reads a different field, which is not an error.
     *
     * @experimental
     */
    async useCompiledSystems(opts: {
        readonly host: AotHost;
        readonly manifest: AotManifest;
        readonly wasm: BufferSource;
    }): Promise<void> {
        const installation = this.reserveCompiledInstall_();
        await installation.ready;
        try {
            const epoch = installation.epoch;
            this.checkCompiledInstallEpoch_(epoch);
            this.ensureTime_();
            const runtime = await prepareAot({
                world: this.world_,
                host: opts.host,
                manifest: opts.manifest,
                wasm: opts.wasm,
                beforeCommit: () => this.checkCompiledInstallEpoch_(epoch),
                resourceFields: (name) => {
                    const def = builtinResource(name) ?? this.resources_.getByName(name) ?? declaredResource(name);
                    if (def === undefined) return undefined;
                    const value = this.resources_.get(def);
                    return typeof value === 'object' && value !== null ? Object.keys(value) : [];
                },
                // A manifest carries event NAMES; the registry answers for the ones
                // some system has asked for a reader or a writer of.
                events: (name) => {
                    // Through the DEFINITION, so the bus exists whether or not an
                    // interpreted system has asked for one yet: a twin sending into
                    // a bus nobody had made would drop its payloads and say nothing.
                    const def = eventNamed(name);
                    if (def === undefined) return undefined;
                    const bus = this.eventRegistry_.getBus(def);
                    return { read: () => bus.getReadBuffer(), send: (payload) => bus.send(payload) };
                },
                resources: (name) => {
                    // The engine's own by name, and the PROJECT's through the
                    // storage's own name registry — a compiled system reads either.
                    const def = builtinResource(name) ?? this.resources_.getByName(name) ?? declaredResource(name);
                    // `get`, not `has` then `get`: a slot holding a materialised
                    // default is what an INTERPRETED system reads, and a twin has to
                    // see the same world or the two stop being the same program.
                    return def === undefined
                        ? undefined
                        : this.resources_.get(def) as Readonly<Record<string, unknown>>;
                },
            });
            if (epoch !== this.quitEpoch_) {
                runtime.dispose?.();
                throw new Error('Compiled systems installation was cancelled by App.quit');
            }
            this.commitCompiledRuntime_(runtime, epoch);
        } finally {
            installation.done();
        }
    }

    private reserveCompiledInstall_(): { ready: Promise<void>; done(): void; epoch: number } {
        const ready = this.compiledInstallTail_;
        let done!: () => void;
        this.compiledInstallTail_ = new Promise<void>(resolve => { done = resolve; });
        return { ready, done, epoch: this.quitEpoch_ };
    }

    private checkCompiledInstallEpoch_(epoch: number): void {
        if (this.quitting_ || epoch !== this.quitEpoch_) {
            throw new Error('Compiled systems installation was cancelled by App.quit');
        }
    }

    private commitCompiledRuntime_(runtime: AotRuntime, epoch: number): void {
        const previous = this.aot_;
        try { this.runner_?.useAot(runtime); }
        catch (error) {
            try { this.runner_?.useAot(previous); } catch (restoreError) { log.warn('app', 'Compiled dispatch restore error', restoreError); }
            try { runtime.dispose?.(); } catch (releaseError) { log.warn('app', 'Compiled installation cleanup error', releaseError); }
            throw error;
        }
        this.aot_ = runtime;
        try { previous?.dispose?.(); } catch (releaseError) { log.warn('app', 'Compiled runtime replacement cleanup error', releaseError); }
        this.checkCompiledInstallEpoch_(epoch);
    }

    /**
     * Which systems this App is running compiled, and how many twin calls have
     * happened. `installed` without `calls` rising means the module loaded and
     * nothing dispatched to it — which no differential can report, because the
     * closure it replaced computes the same answer.
     *
     * @experimental
     */
    get compiledSystems(): { readonly installed: readonly string[]; readonly calls: number } {
        return {
            installed: this.aot_?.systems.names() ?? [],
            calls: this.aot_?.systems.calls ?? 0,
        };
    }

    // =========================================================================
    // Configuration
    // =========================================================================

    setFixedTimestep(timestep: number): this {
        this.fixedTimestep_ = timestep;
        return this;
    }

    /** The fixed-update timestep (seconds) — the FixedUpdate / physics cadence. */
    getFixedTimestep(): number {
        return this.fixedTimestep_;
    }

    setMaxDeltaTime(v: number): this {
        this.maxDeltaTime_ = v;
        return this;
    }

    setMaxFixedSteps(v: number): this {
        this.maxFixedSteps_ = v;
        return this;
    }

    onError(handler: (error: unknown, systemName: string) => void): this {
        this.error_handler_ = handler;
        return this;
    }

    onSystemError(handler: (error: Error, systemName?: string) => 'continue' | 'pause'): this {
        this.system_error_handler_ = handler;
        return this;
    }

    onWasmError(handler: (error: unknown, context: string) => void): this {
        setWasmErrorHandler(handler);
        return this;
    }

    /** Pause simulation time and ordinary systems; presentation opt-ins and Last still run. */
    setPaused(paused: boolean): void {
        this.user_paused_ = paused;
    }

    isPaused(): boolean {
        return this.user_paused_ || !!hostPauseOwners.get(this)?.size;
    }

    stepFrame(): void {
        if (this.isExecutionHeld()) return;
        this.step_pending_ = true;
    }

    setPlaySpeed(speed: number): void {
        this.play_speed_ = Math.max(0.1, Math.min(4.0, speed));
    }

    setTargetFrameRate(fps: number): void {
        this.targetFrameInterval_ = fps > 0 ? 1000 / fps : 0;
        this.nextCapFrameAt_ = 0;
        // A native host steps the app from its own display-driven loop, not from mainLoop above, so the cap
        // is the host's to hold (and to tell the OS, so the panel settles on a rate the game can keep).
        (globalThis as { es_setTargetFrameRate?: (fps: number) => void }).es_setTargetFrameRate?.(fps > 0 ? fps : 0);
    }

    /**
     * Keep simulating while the page is hidden — a window behind others, a
     * minimized one, or one never shown (an editor driven by automation).
     *
     * A browser stops `requestAnimationFrame` for a hidden document, so without
     * this the game holds still there: what a shipped game wants, since nobody is
     * watching and the battery is. An editor's Play wants the opposite; Unity
     * calls the same switch `Application.runInBackground`. While hidden the loop
     * runs on a timer at the frame cap (60 fps when uncapped).
     */
    setRunInBackground(on: boolean): void {
        this.runInBackground_ = on;
        if (typeof document === 'undefined') return;
        if (on && !this.onVisibility_) {
            // A rAF queued just before the page hid never fires: move it to the timer.
            this.onVisibility_ = () => {
                if (this.queuedFrame_ === null || this.queuedOnTimer_ || document.visibilityState !== 'hidden') return;
                if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this.queuedFrame_);
                this.queuedFrame_ = null;
                this.queueLoopFrame_();
            };
            document.addEventListener('visibilitychange', this.onVisibility_);
        } else if (!on && this.onVisibility_) {
            document.removeEventListener('visibilitychange', this.onVisibility_);
            this.onVisibility_ = null;
        }
    }

    getRunInBackground(): boolean {
        return this.runInBackground_;
    }

    getTargetFrameRate(): number {
        return this.targetFrameInterval_ > 0 ? 1000 / this.targetFrameInterval_ : 0;
    }

    getPlaySpeed(): number {
        return this.play_speed_;
    }

    // =========================================================================
    // Stats
    // =========================================================================

    enableStats(): this {
        this.statsEnabled_ = true;
        this.phaseTimings_ = new Map();
        this.frameScopes_ = new Map();
        this.runner_?.setTimingEnabled(true);
        return this;
    }

    getSystemTimings(): ReadonlyMap<string, number> | null {
        return this.runner_?.getTimings() ?? null;
    }

    getPhaseTimings(): ReadonlyMap<string, number> | null {
        return this.phaseTimings_;
    }

    /** @experimental The last completed frame's clock readings; see {@link FrameTiming}. */
    getFrameTiming(): Readonly<FrameTiming> | null {
        return this.frameTiming_;
    }

    /** Frames requested by stepping controls, excluded from wall-clock FPS windows. */
    getSteppedFrameCount(): number {
        return this.steppedFrames_;
    }

    /**
     * Sub-frame CPU scopes recorded this frame via {@link measureFrameScope} —
     * the finer breakdown within a single system, keyed by scope name. Null when
     * stats aren't enabled. Sibling of {@link getSystemTimings} /
     * {@link getPhaseTimings}; surfaces as the profiler's `js.*` rows.
     */
    getFrameScopes(): ReadonlyMap<string, number> | null {
        if (!this.frameScopes_) return null;
        const flat = new Map<string, number>();
        for (const [name, scope] of this.frameScopes_) flat.set(name, scope.ms);
        return flat;
    }

    /**
     * This frame's costs with the attribution a profile tree needs: which domain
     * owns each system, which system each scope ran inside. Null when stats are
     * off. Feed to `buildFrameProfile`, which is where the tree is derived.
     */
    getFrameCosts(): FrameCosts | null {
        if (!this.frameScopes_) return null;
        const timings = this.runner_?.getTimings();
        const domains = new Map<string, string>();
        for (const entries of this.systems_.values()) {
            for (const entry of entries) domains.set(entry.system._name, entry.domain);
        }
        const queryCosts = this.runner_?.getQueryCosts();
        const systems: SystemCost[] = [];
        for (const [name, ms] of timings ?? []) {
            const query = queryCosts?.get(name);
            systems.push({
                name,
                ms,
                domain: domains.get(name) ?? DOMAIN_UNATTRIBUTED,
                ...(query ? { query } : {}),
            });
        }
        return { systems, scopes: [...this.frameScopes_.values()] };
    }

    /**
     * Time `fn` as a named sub-frame scope (accumulated if the name repeats in a
     * frame). A no-op passthrough when stats are off, so shipped games pay only a
     * single branch. Use it to split a heavy system into attributable pieces.
     *
     * `remainder: 'wait'` declares that whatever time is left under this scope
     * once its native scopes are subtracted is CPU blocked, not work — the
     * swapchain block a GPU submit absorbs, or an await. The profiler keeps such
     * time out of every cost total instead of reporting it as a hotspot.
     */
    measureFrameScope<T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder }): T {
        const scopes = this.frameScopes_;
        if (!scopes) return fn();
        const parent = this.openScopes_[this.openScopes_.length - 1];
        this.openScopes_.push(name);
        const t0 = performance.now();
        try {
            return fn();
        } finally {
            const elapsed = performance.now() - t0;
            this.openScopes_.pop();
            const prev = scopes.get(name);
            scopes.set(name, {
                name,
                ms: (prev?.ms ?? 0) + elapsed,
                system: prev?.system ?? this.currentSystem_,
                remainder: options?.remainder ?? 'work',
                ...(parent !== undefined ? { parent } : {}),
            });
        }
    }

    /**
     * Observe the end of every frame, once its systems have run and its timings
     * are final. Returns a disposer.
     *
     * A broadcast, not a slot: a recorder and a game's own budget alarm both
     * watch without either taking the hook from the other.
     */
    onFrameEnd(fn: (dtMs: number) => void): () => void {
        this.frameObservers_.push(fn);
        return () => {
            const i = this.frameObservers_.indexOf(fn);
            if (i >= 0) this.frameObservers_.splice(i, 1);
        };
    }

    getEntityCount(): number {
        return this.world_.entityCount();
    }

    // =========================================================================
    // Resource Access
    // =========================================================================

    insertResource<T>(resource: ResourceDef<T>, value: T): this {
        this.resources_.insert(resource, value);
        return this;
    }

    getResource<T>(resource: ResourceDef<T>): T {
        return this.resources_.get(resource);
    }

    hasResource<T>(resource: ResourceDef<T>): boolean {
        return this.resources_.has(resource);
    }

    getResourceByName(name: string): unknown | undefined {
        // The storage learns a name on INSERT; a declared one `get` materialises
        // at its default, which is what an interpreted system reads on its first
        // frame. Without this the AOT handshake refused a resource that was there.
        const def = builtinResource(name) ?? this.resources_.getByName(name) ?? declaredResource(name);
        return def ? this.resources_.get(def) : undefined;
    }

    getResourceChangeTick(name: string): number {
        const def = this.resources_.getByName(name);
        return def ? this.resources_.getChangeTick(def) : 0;
    }

    getRegisteredResourceNames(): string[] {
        return this.resources_.getRegisteredNames();
    }

    /**
     * Every resource this app holds, as `[name, value]` — what an inspector
     * shows. Includes the slots only a read has materialised, which
     * {@link getRegisteredResourceNames} (insert-only) does not.
     */
    getResourceEntries(): Array<[string, unknown]> {
        return this.resources_.entries();
    }

    // =========================================================================
    // Scene Management
    // =========================================================================

    registerScene(config: SceneConfig): this {
        this.getResource(SceneManager).register(config);
        return this;
    }

    setInitialScene(name: string): this {
        this.getResource(SceneManager).setInitial(name);
        return this;
    }

    // =========================================================================
    // Compiled systems (AOT)
    // =========================================================================

    /**
     * How many compiled twins this App runs. Zero unless a build installed some,
     * which is the whole of the mode policy — and the one number that tells a
     * shipped AOT build apart from a shipped interpreted one from outside.
     */
    get compiledSystemCount(): number {
        return this.aot_?.systems.size ?? 0;
    }

    /**
     * Install the compiled twins a build produced, and answer how many
     * (docs/REARCH_AOT.md §9). Call it BEFORE any component exists — a twin reads
     * rows in the ENGINE's memory, and refuses rather than move rows already
     * allocated elsewhere, or trust a module built for other offsets.
     */
    async installCompiledSystems(
        source: string | BufferSource, manifest: AotManifest,
    ): Promise<number> {
        const installation = this.reserveCompiledInstall_();
        await installation.ready;
        try {
            const epoch = installation.epoch;
            this.checkCompiledInstallEpoch_(epoch);
            // Which road is a fact about the HOST, not about the caller: a host
            // that loads a library packs the rows itself, and an address there is a
            // pointer nothing here can hold.
            const native = this.installNative_(source, manifest);
            if (native !== null) return native;
            const wasm = source;
            const module = this.module_;
            if (!module) {
                throw new Error('installCompiledSystems: this App has no engine module, and a compiled '
                    + 'system reads the memory of one');
            }
            const memory = module.wasmMemory;
            // An engine built as plain JavaScript (wasm2js, for a host without
            // WebAssembly) has an ArrayBuffer where the Memory would be, and a
            // compiled system is a wasm module that cannot import it. Not an error:
            // every system keeps running interpreted, which is the no-cliff rule.
            if (memory && (typeof WebAssembly === 'undefined' || !(memory instanceof WebAssembly.Memory))) {
                log.info('runtime', 'AOT: this engine runs without WebAssembly, so its compiled systems stay interpreted');
                return 0;
            }
            if (!memory) {
                throw new Error('installCompiledSystems: this engine artifact does not export '
                    + "'wasmMemory', so there is no memory for the module to import — rebuild the engine");
            }
            // Read through to the module rather than captured: emscripten REPLACES
            // the heap view when the heap grows, and a snapshot taken here would be
            // detached by the first allocation that grows it.
            const host: AotHost = {
                allocatorIdentity: module,
                memory,
                _malloc: (size: number) => module._malloc(size),
                _free: (ptr: number) => module._free(ptr),
                get HEAPU8(): Uint8Array { return module.HEAPU8; },
            };
            this.ensureTime_();
            const runtime = await prepareAot({
                world: this.world_,
                host,
                manifest,
                wasm,
                beforeCommit: () => this.checkCompiledInstallEpoch_(epoch),
                resources: (name: string) => this.getResourceByName(name) as
                    Readonly<Record<string, unknown>> | undefined,
            });
            if (epoch !== this.quitEpoch_) {
                runtime.dispose?.();
                throw new Error('Compiled systems installation was cancelled by App.quit');
            }
            this.ensureRunner_();
            this.commitCompiledRuntime_(runtime, epoch);
            return runtime.systems.size;
        } finally {
            installation.done();
        }
    }

    /**
     * The same, where the host loads a library. Null when this is not such a
     * host, which is every host but a native one — and then the caller falls
     * through to the module road above.
     */
    private installNative_(module: string | BufferSource, manifest: AotManifest): number | null {
        if (typeof module !== 'string') return null;
        const bindings = nativeAotBindings();
        const heap = createNativeHeap();
        if (bindings === null || heap === null) return null;
        this.ensureTime_();
        const epoch = this.quitEpoch_;
        const runtime = installNativeAot({
            world: this.world_,
            runner: this.ensureRunner_(),
            modulePath: module,
            manifest,
            heap,
            bindings,
            resources: (name: string) => this.getResourceByName(name) as
                Readonly<Record<string, unknown>> | undefined,
        });
        if (runtime === null) return 0;
        if (epoch !== this.quitEpoch_) {
            runtime.dispose?.();
            this.runner_?.useAot(this.aot_);
            throw new Error('Compiled systems installation was cancelled by App.quit');
        }
        this.commitCompiledRuntime_(runtime, epoch);
        return runtime.systems.size;
    }

    // =========================================================================
    // Run
    // =========================================================================

    async tick(delta: number): Promise<void> {
        if (this.isExecutionHeld()) return;
        const epoch = this.executionEpoch_;
        this.frame_paused_ = false;
        this.boot_();

        await this.flushStartupSystems_();
        if (epoch !== this.executionEpoch_ || this.isExecutionHeld()) return;
        await this.runFrame_(delta);
    }

    /** Hold frame execution without changing the game's own pause state. */
    holdExecution(): () => void {
        const owner = {}, quitEpoch = this.quitEpoch_;
        const first = this.executionHolds_.size === 0;
        this.executionHolds_.add(owner);
        if (first) {
            this.executionEpoch_++;
            this.frame_paused_ = true;
            this.invalidateLoop_();
            if (this.hasResource(Input)) setInputExecutionHeld(this.getResource(Input), this, true);
            this.notifyExecution_();
        }
        return () => {
            if (quitEpoch !== this.quitEpoch_ || !this.executionHolds_.delete(owner) || this.executionHolds_.size) return;
            if (this.hasResource(Input)) setInputExecutionHeld(this.getResource(Input), this, false);
            this.notifyExecution_();
            if (this.isExecutionHeld()) return;
            const version = this.loopVersion_;
            // An interrupted asynchronous frame settles before another frame starts.
            void (this.frameInFlight_ ?? Promise.resolve()).then(() => {
                if (!this.running_ || this.isExecutionHeld() || version !== this.loopVersion_) return;
                this.lastTime_ = platformNow();
                if (typeof requestAnimationFrame === 'function') this.queueLoopFrame_();
                else void this.mainLoop();
            });
        };
    }

    isExecutionHeld(): boolean { return this.executionHolds_.size > 0; }

    /** Observe execution holds, including the initial state. Media/timer owners can cooperate here. */
    onExecutionChange(callback: (held: boolean) => void): () => void {
        this.executionObservers_.push(callback);
        this.callExecutionObserver_(callback);
        return () => {
            const index = this.executionObservers_.indexOf(callback);
            if (index >= 0) this.executionObservers_.splice(index, 1);
        };
    }

    private notifyExecution_(): void {
        for (const callback of [...this.executionObservers_]) {
            this.callExecutionObserver_(callback);
        }
    }

    private callExecutionObserver_(callback: (held: boolean) => void): void {
        try {
            const result: unknown = callback(this.isExecutionHeld());
            if (result instanceof Promise) void result.catch(error => log.error('app', 'Execution observer error', error));
        } catch (error) { log.error('app', 'Execution observer error', error); }
    }

    /**
     * Advance exactly `frames` frames of exactly `dt` seconds, with the rAF loop held
     * off for the duration — "let the game run a bit", made reproducible.
     *
     * The loop it replaces is wall-clock and browser-scheduled: a backgrounded tab is
     * throttled to about one frame a second, so an observer that steps by waiting sees
     * a frozen game and concludes the game is broken. Worse, there was no other door —
     * a driver that needed the next 30 frames of simulation had to reach for
     * `runFrame_`, and reaching for a private method is a thing that keeps working
     * until the day it doesn't.
     *
     * A PAUSED app still steps here: advancing frame by frame is exactly what stepping
     * a paused game means. The pause (and the loop) are restored afterwards, with the
     * clock re-based so the first resumed frame is not handed the whole excursion as
     * its delta.
     */
    async stepFrames(frames = 1, dt = 1 / 60): Promise<void> {
        if (this.isExecutionHeld()) return;
        const executionEpoch = this.executionEpoch_, quitEpoch = this.quitEpoch_;
        const previousStep = this.step_pending_;
        const wasRunning = this.running_;
        const wasPaused = this.user_paused_;
        this.invalidateLoop_();
        const version = this.loopVersion_;
        this.running_ = false;
        try {
            await this.frameInFlight_;
            this.user_paused_ = false;
            for (let i = 0; i < frames; i++) {
                if (this.isExecutionHeld() || executionEpoch !== this.executionEpoch_) break;
                this.step_pending_ = true; await this.tick(dt);
            }
        } finally {
            if (quitEpoch === this.quitEpoch_) {
                this.user_paused_ = wasPaused;
                if (executionEpoch !== this.executionEpoch_ || this.isExecutionHeld()) this.step_pending_ = previousStep;
            }
            if (wasRunning && quitEpoch === this.quitEpoch_
                && (version === this.loopVersion_ || executionEpoch !== this.executionEpoch_)) {
                this.lastTime_ = platformNow();
                this.running_ = true;
                // Resumed on the next animation frame, not by starting one here:
                // a frame begun inside this call's own microtask drain swallows
                // the input edge a caller injects the moment it returns.
                if (!this.isExecutionHeld()) {
                    if (typeof requestAnimationFrame === 'function') this.queueLoopFrame_();
                    else void this.mainLoop();
                }
            }
        }
    }

    async run(): Promise<void> {
        if (this.running_) {
            return;
        }

        this.running_ = true;
        if (this.isExecutionHeld()) return;
        const version = this.loopVersion_;
        this.frame_paused_ = false;
        this.boot_();
        await this.flushStartupSystems_();

        if (!this.running_ || this.isExecutionHeld() || version !== this.loopVersion_) return;

        this.lastTime_ = platformNow();
        this.mainLoop();
    }

    private invalidateLoop_(): void {
        this.loopVersion_++;
        if (this.queuedFrame_ !== null) {
            if (this.queuedOnTimer_) clearTimeout(this.queuedFrame_);
            else if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this.queuedFrame_);
        }
        this.queuedFrame_ = null;
    }

    private queueLoopFrame_(): void {
        if (this.isExecutionHeld() || this.queuedFrame_ !== null) return;
        if (typeof requestAnimationFrame !== 'function') return;
        const version = this.loopVersion_;
        const hidden = typeof document !== 'undefined' && document.visibilityState === 'hidden';
        if (hidden && this.runInBackground_) {
            // No rAF arrives for a hidden document; a timer at the frame cadence does.
            this.queuedOnTimer_ = true;
            this.queuedFrame_ = setTimeout(() => {
                if (version !== this.loopVersion_) return;
                this.queuedFrame_ = null;
                void this.mainLoop(platformNow(), version);
            }, this.targetFrameInterval_ > 0 ? this.targetFrameInterval_ : 1000 / 60) as unknown as number;
            return;
        }
        this.queuedOnTimer_ = false;
        this.queuedFrame_ = requestAnimationFrame((time) => {
            if (version !== this.loopVersion_) return;
            this.queuedFrame_ = null;
            return this.mainLoop(time, version);
        });
    }

    private mainLoop = async (rafTime?: number, version = this.loopVersion_): Promise<void> => {
        if (!this.running_ || this.isExecutionHeld() || version !== this.loopVersion_) {
            return;
        }

        // The frame clock is the rAF timestamp — the vsync being drawn for — not
        // callback entry, whose jitter would enter delta twice and judder motion.
        // A host that passes no timestamp keeps the old measurement.
        const currentTime = typeof rafTime === 'number' && rafTime > 0 ? rafTime : platformNow();
        const deltaMs = currentTime - this.lastTime_;

        // A cadence, not a minimum gap: a cap of two vsyncs measured frame to frame
        // loses to jitter half the time and waits a third (30 fps on 60 Hz ran at 24).
        if (this.targetFrameInterval_ > 0) {
            if (currentTime < this.nextCapFrameAt_ - CAP_JITTER_MS) {
                this.queueLoopFrame_();
                return;
            }
            // More than a frame behind (a stall, a hidden page): the cadence restarts here.
            this.nextCapFrameAt_ = currentTime - this.nextCapFrameAt_ > this.targetFrameInterval_
                ? currentTime + this.targetFrameInterval_
                : this.nextCapFrameAt_ + this.targetFrameInterval_;
        }

        this.lastTime_ = currentTime;

        // Never negative: two clocks with different origins meet on the first frame
        // after run()/stepFrames seeds lastTime_ from platformNow(), and time running
        // backwards is worse than a frame that stands still.
        const rawDelta = Math.max(0, Math.min(deltaMs / 1000, this.maxDeltaTime_));
        const delta = rawDelta * this.play_speed_;

        this.frame_paused_ = false;
        this.boot_();
        await this.flushStartupSystems_();
        if (!this.running_ || this.isExecutionHeld() || version !== this.loopVersion_) return;
        const frame = this.runFrame_(delta, Math.max(0, deltaMs));
        this.frameInFlight_ = frame;
        try { await frame; }
        finally { if (this.frameInFlight_ === frame) this.frameInFlight_ = null; }

        if (this.running_ && version === this.loopVersion_) this.queueLoopFrame_();
    };

    private quitting_ = false;
    private quitEpoch_ = 0;

    quit(options?: { keepRenderer?: boolean }): void {
        if (this.quitting_) return;
        this.quitting_ = true;
        this.quitEpoch_++;
        try { this.quit_(options); }
        finally { this.quitting_ = false; }
    }

    private quit_(options?: { keepRenderer?: boolean }): void {
        this.executionEpoch_++;
        this.executionHolds_.clear();
        if (this.hasResource(Input)) setInputExecutionHeld(this.getResource(Input), this, false);
        this.invalidateLoop_();
        this.setRunInBackground(false);
        this.running_ = false;

        for (let i = this.installed_plugins_.length - 1; i >= 0; i--) {
            try { this.installed_plugins_[i].cleanup?.(this); } catch (e) {
                log.error('app', 'Plugin cleanup error', e);
            }
        }
        this.installed_plugins_.length = 0;
        this.executionObservers_.length = 0;
        this.installedPluginSet_.clear();
        this.installedPluginNames_.clear();

        for (const entity of this.world_.getAllEntities()) {
            try { this.world_.despawn(entity); } catch (e) { log.warn('app', 'Shutdown despawn error', e); }
        }
        const aot = this.aot_;
        this.aot_ = null;
        this.runner_?.useAot(null);
        try { aot?.dispose?.(); }
        catch (e) { log.warn('app', 'Shutdown compiled-runtime release error', e); }
        try { this.world_.releaseScriptPools(); }
        catch (e) { log.warn('app', 'Shutdown script-pool release error', e); }
        this.world_.disconnectCpp();
        const ownedRegistry = this.ownedCppRegistry_;
        this.ownedCppRegistry_ = null;
        try { ownedRegistry?.delete(); }
        catch (e) { log.warn('app', 'Shutdown registry release error', e); }
        // After the plugins, which may still have asked it for something on their way out.
        const modules = this.ownsSideModules_ ? this.sideModules_ : null;
        this.ownsSideModules_ = false;
        try { modules?.dispose?.(); }
        catch (e) { log.warn('app', 'Shutdown module-host release error', e); }

        for (const [, entries] of this.systems_) {
            entries.length = 0;
        }
        this.sortedSystemsCache_.clear();
        this.dependencyCache_.clear();
        this.templateToRuntime_.clear();
        this.systemCounter_ = 0;

        this.pipeline_ = null;
        this.runner_ = null;
        this.booted_ = false;
        this.aot_ = null;
        // Tear down the C++ engine context too: previously quit() only cleared
        // JS state and dropped the module reference, so the EstellaContext was
        // never shut down — it leaked its GPU subsystems + WebGL context, and a
        // later init silently reused the stale (still-"initialized") singleton.
        // shutdownRenderer is null-safe (no-op if no renderer was initialized).
        // `keepRenderer` skips it: hot-reload rebuilds the App but reuses the live
        // module + GL + renderer (EstellaContext::shutdown destroys the WebGL
        // context), so only a full quit tears the renderer down.
        if (!options?.keepRenderer) {
            this.module_?.shutdownRenderer?.();
            this.module_ = null;
        }
    }

    // =========================================================================
    // Internal
    // =========================================================================

    /**
     * The runner, made on demand. Making one is free and decides nothing — what
     * has to happen exactly once before a frame is in `boot_`, so a caller that
     * needs the runner early (a compiled-systems install) does not consume the
     * boot by asking.
     */
    private ensureRunner_(): SystemRunner {
        if (!this.runner_) {
            this.runner_ = new SystemRunner(this.world_, this.resources_, this.eventRegistry_);
            // Twins prepared before there was a runner. `useCompiledSystems` can be
            // called on a fresh App, and its `runner_?.useAot` would drop them for
            // good — a compiled build that silently runs its closures instead.
            if (this.aot_) {
                this.runner_.useAot(this.aot_);
            }
            if (this.statsEnabled_) {
                this.runner_.setTimingEnabled(true);
            }
        }
        return this.runner_;
    }

    /**
     * The clock, before anything asks for it. Installing compiled systems is one
     * such thing and it runs BEFORE the first frame: a twin declaring `Res(Time)`
     * is refused outright if this App cannot yet say what Time's fields are.
     */
    private ensureSpeculation_(): void {
        if (this.resources_.has(Speculation)) return;
        this.resources_.insert(Speculation, new SpeculationInstance(this.world, this.resources_, this.eventRegistry_));
    }

    private ensureTime_(): void {
        if (this.resources_.has(Time)) return;
        this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 });
        this.ensureSpeculation_();
    }

    /** Once per app, on the way into the first frame: the clock every system
     *  reads, and the plugins' last chance to add one. */
    private boot_(): void {
        this.ensureRunner_();
        if (this.booted_) return;
        this.booted_ = true;
        this.ensureTime_();
        this.finishPlugins_();
    }

    private async runFrame_(delta: number, frameMs = delta * 1000): Promise<void> {
        if (this.isExecutionHeld()) return;
        const executionEpoch = this.executionEpoch_;
        const current = () => !this.isExecutionHeld() && executionEpoch === this.executionEpoch_;
        const frameClock = typeof performance !== 'undefined' && typeof performance.now === 'function' ? performance : null;
        const frameStart = frameClock ? frameClock.now() : 0;
        this.runner_?.clearTimings();
        this.phaseTimings_?.clear();
        this.frameScopes_?.clear();
        this.eventRegistry_.swapAll();
        this.world_.advanceTick();
        this.updateTime(delta);
        this.world_.resetQueryPool();
        this.frame_paused_ = false;

        if (this.isPaused() && !this.step_pending_) {
            await this.runSchedule(Schedule.First, executionEpoch, true);
            await this.runSchedule(Schedule.PreUpdate, executionEpoch, true);
            await this.runSchedule(Schedule.Update, executionEpoch, true);
            await this.runSchedule(Schedule.PostUpdate, executionEpoch, true);
            await this.runSchedule(Schedule.Last, executionEpoch);
        } else {
            await this.runSchedule(Schedule.First, executionEpoch);
            if (!current()) return;

            // The SCALED delta, so Time.scale = 0 stops the fixed steps too —
            // otherwise physics would keep stepping through a paused world.
            this.fixedAccumulator_ += this.resources_.get(Time).delta;
            let fixedSteps = 0;
            // Fixed steps read the input edge mirrors (which persist across frames
            // until a step consumes them) so a press on a sub-timestep frame isn't
            // lost and a catch-up frame doesn't replay it. Null when no input plugin
            // is installed (headless / bare App).
            const input = this.resources_.has(Input) ? this.resources_.get(Input) : null;
            // Direct performance.now() (not platformNow) so the budget guard needs
            // no platform init (unit tests call tick() without it) and degrades to a
            // no-op where performance is absent — the maxFixedSteps cap still applies.
            const perf = typeof performance !== 'undefined' && typeof performance.now === 'function' ? performance : null;
            const fixedStart = perf ? perf.now() : 0;
            while (this.fixedAccumulator_ >= this.fixedTimestep_ && fixedSteps < this.maxFixedSteps_) {
                this.fixedAccumulator_ -= this.fixedTimestep_;
                // Every system inside one fixed step sees the same tick number
                // (1-based) — the simulation time axis netcode stamps packets with.
                this.resources_.get(Time).fixedTick++;
                input?.beginFixedStep();
                await this.runSchedule(Schedule.FixedPreUpdate, executionEpoch);
                await this.runSchedule(Schedule.FixedUpdate, executionEpoch);
                await this.runSchedule(Schedule.FixedPostUpdate, executionEpoch);
                input?.endFixedStep();
                if (!current()) return;
                fixedSteps++;
                // Stop catching up once this frame's fixed steps blow the time
                // budget — drop the backlog below so we don't spiral.
                if (perf && perf.now() - fixedStart >= this.fixedStepBudgetMs_) break;
            }
            // Hit the step cap or the time budget with a step still pending → the
            // sim can't keep real-time; drop the backlog so the accumulator can't
            // grow unbounded (graceful slow motion instead of a death spiral).
            if (this.fixedAccumulator_ >= this.fixedTimestep_) {
                this.fixedAccumulator_ = 0;
            }
            // Remainder fraction into the current fixed step — render-time systems
            // (physics interpolation) lerp prev→current by this for smooth motion.
            this.resources_.get(Time).fixedAlpha =
                this.fixedTimestep_ > 0 ? this.fixedAccumulator_ / this.fixedTimestep_ : 0;

            await this.runSchedule(Schedule.PreUpdate, executionEpoch);
            await this.runSchedule(Schedule.Update, executionEpoch);
            await this.runSchedule(Schedule.PostUpdate, executionEpoch);
            await this.runSchedule(Schedule.Last, executionEpoch);

            if (this.step_pending_) {
                this.step_pending_ = false;
            }
        }

        if (!current()) return;
        this.frameTiming_ = {
            seq: (this.frameTiming_?.seq ?? 0) + 1, frameMs,
            busyMs: frameClock ? frameClock.now() - frameStart : -1,
        };
        for (const observe of this.frameObservers_) {
            try { observe(frameMs); } catch (e) {
                log.error('app', 'Frame observer error', e);
            }
        }
    }

    private finishPlugins_(): void {
        if (this.pluginsFinished_) return;
        this.pluginsFinished_ = true;
        for (const plugin of this.installed_plugins_) {
            try { plugin.finish?.(this); } catch (e) {
                log.error('app', `Plugin "${plugin.name ?? 'unknown'}" finish error`, e);
            }
        }
    }

    private sortPlugins(plugins: Plugin[]): Plugin[] {
        if (plugins.length <= 1) return plugins;

        const nameToIndex = new Map<string, number>();
        for (let i = 0; i < plugins.length; i++) {
            const name = plugins[i].name;
            if (name) {
                if (nameToIndex.has(name)) {
                    log.warn('app', `Duplicate plugin name "${name}" at indices ${nameToIndex.get(name)} and ${i}`);
                }
                nameToIndex.set(name, i);
            }
        }

        const edges = new Map<number, Set<number>>();
        for (let i = 0; i < plugins.length; i++) {
            edges.set(i, new Set());
        }

        for (let i = 0; i < plugins.length; i++) {
            const plugin = plugins[i];
            if (plugin.dependencies) {
                for (const dep of plugin.dependencies) {
                    if (typeof dep !== 'string') continue;
                    const depIndex = nameToIndex.get(dep);
                    if (depIndex !== undefined) {
                        edges.get(i)!.add(depIndex);
                    }
                }
            }
            if (plugin.after) {
                for (const target of plugin.after) {
                    const targetIndex = nameToIndex.get(target);
                    if (targetIndex !== undefined) {
                        edges.get(i)!.add(targetIndex);
                    }
                }
            }
            if (plugin.before) {
                for (const target of plugin.before) {
                    const targetIndex = nameToIndex.get(target);
                    if (targetIndex !== undefined) {
                        edges.get(targetIndex)!.add(i);
                    }
                }
            }
        }

        const sorted: Plugin[] = [];
        const visited = new Set<number>();
        const visiting = new Set<number>();
        const path: number[] = [];

        const visit = (index: number): void => {
            if (visited.has(index)) return;
            if (visiting.has(index)) {
                const cycleStart = path.indexOf(index);
                const cycle = path.slice(cycleStart).concat(index);
                const names = cycle.map(i => plugins[i].name ?? `<index ${i}>`);
                throw new Error(`Circular plugin dependency: ${names.join(' -> ')}`);
            }
            visiting.add(index);
            path.push(index);
            for (const dep of edges.get(index)!) {
                visit(dep);
            }
            path.pop();
            visiting.delete(index);
            visited.add(index);
            sorted.push(plugins[index]);
        };

        for (let i = 0; i < plugins.length; i++) {
            visit(i);
        }
        return sorted;
    }

    /**
     * Expands an ordering name to the indices it refers to — a system, or every
     * member of a set that is also in this schedule. A name matching neither
     * resolves to nothing, which is how ordering against a system that was never
     * registered stays a no-op rather than an error.
     */
    private resolverFor(systems: readonly SystemEntry[]): ResolveTargets {
        const nameToIndex = new Map<string, number>();
        for (let i = 0; i < systems.length; i++) {
            nameToIndex.set(systems[i].system._name, i);
        }
        return (name: string): number[] => {
            const direct = nameToIndex.get(name);
            if (direct !== undefined) return [direct];
            const members = this.setMembership_.get(name);
            if (!members) return [];
            const out: number[] = [];
            for (const m of members) {
                const idx = nameToIndex.get(m);
                if (idx !== undefined) out.push(idx);
            }
            return out;
        };
    }

    /**
     * Pairs of systems in `schedule` that touch the same data with nothing
     * saying which runs first, so their order is whatever registration and the
     * sort happened to produce.
     *
     * @beta
     */
    scheduleAmbiguities(schedule: Schedule): Ambiguity[] {
        const systems = this.systems_.get(schedule) ?? [];
        return detectAmbiguities(systems, this.resolverFor(systems));
    }

    /**
     * `schedule` grouped into batches that could run at the same time — how much
     * of it is inherently sequential. A measurement: the schedule starts systems
     * in sorted order, overlapping only what awaits. See {@link parallelBatches}.
     *
     * @beta
     */
    scheduleBatches(schedule: Schedule): string[][] {
        const systems = this.systems_.get(schedule) ?? [];
        return parallelBatches(systems, this.resolverFor(systems));
    }

    private sortSystems(systems: SystemEntry[]): SystemEntry[] {
        if (systems.length <= 1) {
            return systems;
        }

        const resolveTargets = this.resolverFor(systems);

        // `adj[i]` lists indices that must run *before* system `i` — the same
        // edges the ambiguity check reads, so what orders a schedule and what
        // judges its order can never be two answers.
        const adj = dependencyEdges(systems, resolveTargets);

        // DFS topological sort with path-aware cycle reporting.
        // color: 0 = unvisited, 1 = in the current DFS stack (GRAY), 2 = done.
        const GRAY = 1, BLACK = 2;
        const color = new Uint8Array(systems.length);
        const stack: number[] = [];
        const sorted: SystemEntry[] = [];

        const visit = (index: number): void => {
            if (color[index] === BLACK) return;
            if (color[index] === GRAY) {
                const cycleStart = stack.indexOf(index);
                const path = stack.slice(cycleStart).map(i => systems[i].system._name);
                path.push(systems[index].system._name);
                throw new Error(`Circular system dependency: ${path.join(' → ')}`);
            }
            color[index] = GRAY;
            stack.push(index);
            for (const dep of adj[index]) visit(dep);
            stack.pop();
            color[index] = BLACK;
            sorted.push(systems[index]);
        };

        for (let i = 0; i < systems.length; i++) visit(i);
        return sorted;
    }

    private startupInFlight_: Promise<void> | null = null;

    private async flushStartupSystems_(): Promise<void> {
        const startup = this.systems_.get(Schedule.Startup)!;
        const executionEpoch = this.executionEpoch_;
        while (startup.length && !this.isExecutionHeld() && !this.frame_paused_ && executionEpoch === this.executionEpoch_) {
            if (!this.startupInFlight_) {
                this.startupInFlight_ = Promise.resolve().then(async () => {
                    await this.runSchedule(Schedule.Startup, executionEpoch);
                    for (let index = startup.length - 1; index >= 0; index--) {
                        if (startup[index].startupInvoked) startup.splice(index, 1);
                    }
                    this.sortedSystemsCache_.delete(Schedule.Startup);
                    this.dependencyCache_.delete(Schedule.Startup);
                }).finally(() => { this.startupInFlight_ = null; });
            }
            await this.startupInFlight_;
        }
    }

    private async runSchedule(schedule: Schedule, executionEpoch = this.executionEpoch_, pausedOnly = false): Promise<void> {
        const rawSystems = this.systems_.get(schedule);
        if (!rawSystems || !this.runner_ || this.frame_paused_ || this.isExecutionHeld() || executionEpoch !== this.executionEpoch_) {
            return;
        }

        let systems = this.sortedSystemsCache_.get(schedule);
        if (!systems) {
            if (rawSystems.some(s => s.runBefore || s.runAfter)) {
                systems = this.sortSystems(rawSystems);
            } else {
                systems = rawSystems;
            }
            this.sortedSystemsCache_.set(schedule, systems);
        }

        const t0 = this.phaseTimings_ ? performance.now() : 0;

        // Systems that returned a promise and have not settled. A synchronous
        // system runs to completion the moment it starts, so this is empty for a
        // schedule of synchronous systems and the loop below is the old one.
        const inflight: InflightSystem[] = [];
        const settle = async (): Promise<void> => {
            const waiting = inflight.map((f) => f.done);
            inflight.length = 0;
            await Promise.all(waiting);
        };

        for (let i = 0; i < systems.length; i++) {
            const entry = systems[i];
            if (this.frame_paused_ || this.isExecutionHeld() || executionEpoch !== this.executionEpoch_) break;
            if (schedule === Schedule.Startup && entry.startupInvoked) continue;
            if (pausedOnly && !entry.system._runWhenPaused) continue;
            if (entry.runIf && !entry.runIf()) { if (schedule === Schedule.Startup) entry.startupInvoked = true; continue; }
            if (entry.gate && schedule !== Schedule.Startup && !this.gateOpen_(entry.gate)) continue;

            // Where the declarations are spent rather than reported: a system
            // starts beside an unfinished one only when it neither depends on it
            // nor touches what it touches — undeclared conflicts with everything.
            if (inflight.length > 0) {
                const dependsOn = this.dependenciesFor(schedule, systems)[i];
                const access = accessOf(entry.system);
                const blocked = inflight.some(
                    (f) => dependsOn.has(f.index) || conflicts(access, f.access),
                );
                if (blocked) await settle();
            }

            if (this.frame_paused_ || this.isExecutionHeld() || executionEpoch !== this.executionEpoch_) break;
            if (schedule === Schedule.Startup) entry.startupInvoked = true;

            try {
                this.currentSystem_ = entry.system._name;
                const result = this.runner_.run(entry.system);
                if (result instanceof Promise) {
                    inflight.push({
                        index: i,
                        access: accessOf(entry.system),
                        done: result.then(
                            () => { this.markSystemStepped(entry); },
                            (e) => { this.reportSystemError(e, entry.system._name); },
                        ),
                    });
                } else {
                    this.markSystemStepped(entry);
                }
            } catch (e) {
                this.reportSystemError(e, entry.system._name);
            } finally {
                // Only meaningful for the synchronous stretch: a system parked at
                // an await has no claim on it while someone else runs.
                this.currentSystem_ = '';
            }
        }

        await settle();

        if (this.phaseTimings_) {
            this.phaseTimings_.set(Schedule[schedule], performance.now() - t0);
        }
    }

    /**
     * What must finish before each system of `systems` may start, transitively.
     *
     * Ordering edges are a stronger statement than access: two systems that touch
     * nothing in common may still have been ordered on purpose, and starting the
     * second beside the first would silently ignore that.
     */
    private dependenciesFor(schedule: Schedule, systems: readonly SystemEntry[]): Set<number>[] {
        let deps = this.dependencyCache_.get(schedule);
        if (!deps) {
            deps = ancestors(dependencyEdges(systems, this.resolverFor(systems)));
            this.dependencyCache_.set(schedule, deps);
        }
        return deps;
    }

    /** Liveness: a system ran, so its owning subsystem stepped this frame. */
    private markSystemStepped(entry: SystemEntry): void {
        if (entry.subsystem) this.subsystems_.markStepped(entry.subsystem);
    }

    /**
     * Report one system's failure. Pausing stops the schedule from STARTING
     * anything else; what is already in flight still has to be waited for, since
     * a promise cannot be taken back.
     */
    private reportSystemError(e: unknown, name: string): void {
        log.error('app', `System "${name}" threw an error`, e);
        if (this.error_handler_) {
            this.error_handler_(e, name);
        }
        if (this.system_error_handler_) {
            const err = e instanceof Error ? e : new Error(String(e));
            if (this.system_error_handler_(err, name) === 'pause') {
                this.frame_paused_ = true;
            }
        }
    }

    private updateTime(delta: number): void {
        const time = this.resources_.get(Time);
        const scale = time.scale >= 0 ? time.scale : 0;
        time.unscaledDelta = delta;
        time.delta = this.isPaused() && !this.step_pending_ ? 0 : delta * scale;
        time.elapsed += time.delta;
        time.frameCount++;
        if (this.step_pending_) this.steppedFrames_++;
        time.fixedDelta = this.fixedTimestep_;
    }
}

// =============================================================================
// Web App Factory
// =============================================================================

/**
 * How the host provides the render surface the C++ renderer binds to — the single
 * seam every platform's renderer init flows through:
 *   - `gl-context`: an emscripten-registered WebGL2 context handle (web/desktop/WeChat).
 *   - `webgpu`: the host acquired a GPUDevice (navigator.gpu) and passed it as the
 *     module factory's `preinitializedWebGPUDevice` before instantiation; the engine
 *     owns the swapchain, resolving the canvas via `canvasSelector` (default '#canvas',
 *     via document.querySelector — so the canvas must be in the DOM).
 *   - `default`: the module resolves its own surface (module.initRenderer()).
 *
 * Native (wasm-on-JSC, no DOM): the host injects the device AND an already-built
 * CAMetalLayer/ANativeWindow surface, so `{ kind: 'webgpu' }` omits `canvasSelector`
 * and must not reach the '#canvas' fallback.
 */
export type RenderSurfaceSource =
    | {
        readonly kind: 'gl-context';
        readonly handle: number;
        /** The context is WeChat's EmscriptenGLX one, whose GL calls the linked
         *  library issues natively rather than through the JS glue. */
        readonly glx?: boolean;
    }
    | {
        readonly kind: 'webgpu';
        readonly canvasSelector?: string;
        /** Configure the swapchain so the engine can read its own frames back
         *  (`captureFrame`). Fixed at surface configuration, hence here. */
        readonly readback?: boolean;
    }
    | { readonly kind: 'default' };

export interface WebAppOptions {
    getViewportSize?: () => { width: number; height: number };
    /**
     * How the host provides the render surface (WebGL2 context handle / WebGPU
     * device + swapchain / headless default). See {@link RenderSurfaceSource}.
     * Omitted ⇒ `{ kind: 'default' }` (module.initRenderer resolves its own).
     */
    renderSurface?: RenderSurfaceSource;
    plugins?: Plugin[];
    /** The realm's optional-native-module acquirer; set before plugins build so
     *  SpinePlugin (and later physics) can pull from it. See {@link App.sideModules}. */
    sideModules?: SideModuleHost;
    /** `sideModules` was made for this App alone, so quitting disposes it. See {@link App.setSideModules}. */
    ownsSideModules?: boolean;
    /**
     * Bitmask of render layers (bits 0..31) that sort by world Y within the
     * layer — top-down occlusion (lower on screen draws on top). Project-level
     * setting (Project Settings → Rendering); change later via Renderer.setYSortLayers.
     */
    ySortLayers?: number;
    /**
     * Bitmask of render layers (bits 0..31) that resolve by real depth instead of
     * painter's order — the 2.5D opt-in. Opaque draws in such a layer write the
     * depth buffer and sort front-to-back; blended ones test without writing and
     * stay back-to-front. A layer that also y-sorts keeps y-sorting.
     * Project-level setting (Project Settings → Rendering).
     */
    depthLayers?: number;
    /**
     * Project color space (Project Settings → Rendering). 'linear' renders in
     * linear light: sRGB decode on sample, linear blending in sRGB-format
     * intermediates, and an explicit linear→sRGB encode in the final blit.
     * Must be declared at app creation — shaders compile against it.
     */
    colorSpace?: 'gamma' | 'linear';
    /**
     * The curve the frame applies on its way to the display, once and last. `aces`
     * engages the capture the way an effect does, so a scene that asks for one goes
     * through the graph even with an empty stack. Declared by the host for now — it
     * is not yet a field of the project manifest. See {@link OutputTransform}.
     */
    outputTransform?: OutputTransform;
    /**
     * Scene-target multisampling (Project Settings → Rendering). 1 turns it off;
     * 4 is the default and what a browser gives its own drawing buffer. The
     * device clamps it, so this is what the project WANTS, not what it gets.
     */
    msaaSamples?: number;
    quality?: QualityConfig;
    /**
     * Seed the engine's randomness so this run reproduces — a replay, a bug
     * report, a pixel assertion. Absent, every run differs, which is what a
     * player wants of particles.
     */
    randomSeed?: number;
    /**
     * Project camera fit (Project Settings → Display). When set with a real
     * scaleMode (≥ 0), the MAIN scene camera letterboxes this design resolution
     * into the actual aspect regardless of any UI Canvas; omitted / scaleMode = -1
     * keeps the legacy behavior (Canvas fit when present, else raw orthoSize). See
     * {@link ScreenScaling}.
     */
    screenFit?: ScreenScalingData;
}

/** The graphics API a web app's renderer draws through, as a connected device reports it. */
export type GraphicsPath = 'WebGPU' | 'WebGL2' | 'EmscriptenGLX';
interface AppSurface {
    graphics: GraphicsPath | null;
    size: (() => { width: number; height: number }) | null;
}
const surfaces = new WeakMap<App, AppSurface>();

/** Null for an app whose module resolved its own surface. */
export function graphicsPathOf(app: App): GraphicsPath | null {
    return surfaces.get(app)?.graphics ?? null;
}

/**
 * Tell @p app the size its host draws at — what a host that builds its App
 * without {@link createWebApp} (the native core) does, so frame read-back and
 * anything else asking {@link surfaceSizeOf} gets the same answer on every core.
 * @internal
 */
export function setAppSurfaceSize(app: App, size: () => { width: number; height: number }): void {
    surfaces.set(app, { graphics: surfaces.get(app)?.graphics ?? null, size });
}

/** The size the engine draws at, as its host reports it; null when the host did not say. */
export function surfaceSizeOf(app: App): { width: number; height: number } | null {
    return surfaces.get(app)?.size?.() ?? null;
}

export function graphicsPathFor(surface: RenderSurfaceSource): GraphicsPath | null {
    switch (surface.kind) {
        case 'webgpu': return 'WebGPU';
        case 'gl-context': return surface.glx ? 'EmscriptenGLX' : 'WebGL2';
        case 'default': return null;
    }
}

export function createWebApp(module: ESEngineModule, options?: WebAppOptions): App {
    // Restore any engine components a prior project hot-reload's clearUserComponents
    // wiped, so the scene about to load can still resolve them (no-op before the SDK
    // entry snapshots the baseline — e.g. in unit tests that never load it).
    seedEngineComponents();
    const app = App.new();
    if (options?.sideModules) app.setSideModules(options.sideModules, { owned: options.ownsSideModules });
    const cppRegistry = new module.Registry() as unknown as CppRegistry;

    try {
        app.connectCpp(cppRegistry, module, { strict: true, ownedRegistry: true });

        // BEFORE renderer init: shader compilation reads the color-space global.
        applyColorSpace(module, options);
        if (options?.randomSeed !== undefined) module.engine_setRandomSeed?.(options.randomSeed >>> 0);

        const surface: RenderSurfaceSource = options?.renderSurface ?? { kind: 'default' };
        switch (surface.kind) {
            case 'webgpu': {
                const size = options?.getViewportSize?.() ?? { width: 800, height: 600 };
                // The canvas' own preference: configuring anything else makes the
                // browser copy the whole frame on every present.
                const preferBGRA = (navigator as unknown as {
                    gpu?: { getPreferredCanvasFormat?(): string };
                }).gpu?.getPreferredCanvasFormat?.() === 'bgra8unorm';
                if (!module.initRendererWebGPU(
                    surface.canvasSelector ?? '#canvas', size.width, size.height,
                    surface.readback === true, preferBGRA)) {
                    throw new Error(
                        'WebGPU renderer initialization failed — the module needs a ' +
                        'preinitializedWebGPUDevice and a WebGPU-enabled engine build.');
                }
                watchWebGPUDeviceLoss(module);
                break;
            }
            case 'gl-context':
                if (!module.initRendererWithContext(surface.handle)) {
                    throw new Error(`WebGL2 renderer initialization failed for context ${surface.handle}.`);
                }
                break;
            case 'default':
                if (!module.initRenderer()) {
                    throw new Error('WebGL2 renderer initialization failed for the default canvas.');
                }
                break;
        }
        surfaces.set(app, { graphics: graphicsPathFor(surface), size: options?.getViewportSize ?? null });
        applyFrameOptions(module, options);

        app.addPlugin(corePlugin);
        app.setPipeline(new RenderPipeline());
        app.insertResource(UICameraInfo, { ...DEFAULT_UI_CAMERA_INFO });
        app.insertResource(ScreenLayout, { ...ScreenLayout._default });
        app.insertResource(ScreenOverlay, defaultScreenOverlay());
        app.addPlugin(cameraPlugin(options?.getViewportSize));
        app.addPlugin(assetPlugin);
        app.addPlugin(prefabsPlugin);
        app.addPlugin(breakablePlugin);
        app.addPlugin(inputPlugin);
        app.addPlugin(sceneManagerPlugin);
        if (options?.plugins) {
            app.addPlugins(options.plugins);
        }

        applyAppOptions(app, options);
        return app;
    } catch (error) {
        try { app.quit({ keepRenderer: true }); }
        catch (releaseError) { log.warn('app', 'Failed web App construction cleanup error', releaseError); }
        throw error;
    }
}

/**
 * Install a {@link Plugin} from a project bundle — the module-level twin of
 * {@link App.addPlugin}, and the door a plugin PACKAGE is installed through: a
 * bundle is imported before an App exists.
 *
 * @experimental
 */
export function addPlugin(plugin: Plugin): void {
    getDefaultContext().pendingPlugins.push(plugin);
}

/**
 * Install everything a project bundle registered at module level. One door, so a
 * host cannot drain half of it — plugins first, because a project's own system
 * may read a resource one of them inserts.
 *
 * @experimental
 */
export function flushPendingRegistrations(app: App): void {
    const context = getDefaultContext();
    for (const plugin of context.drainPendingPlugins()) app.addPlugin(plugin as Plugin);
    app.addBundleSystems(context.drainPendingSystems() as ReadonlyArray<{ schedule: number; system: SystemDef }>);
}