@aethervtt/shard-runtime 0.0.1 → 0.1.0

package/dist/app.d.ts

@@ -11,6 +11,12 @@ export interface AppOptions {
     now?: () => number;
     /** Seed for the `GlobalRng` resource. Default 0. */
     seed?: number;
+    /**
+     * A development build: missing assets show loudly (checkers), and dev-only checks and issues
+     * run (shader cache misses, color-space mismatches, GL error checks). Read it from `DevMode`.
+     * Default false.
+     */
+    dev?: boolean;
 }
 export interface AppDescription {
     plugins: {
@@ -39,6 +45,39 @@ export interface AppMethod {
         world: World;
     }, params: Record<string, unknown>): unknown;
 }
+/**
+ * Code the app runs happens inside its scopes: plugin builds and ready hooks, frames, pumps, and
+ * disposal. The render plugin uses one to count GPU objects against the app (0052).
+ */
+export interface AppScope {
+    enter(): void;
+    exit(): void;
+}
+/** What a loop runner gives the app while it drives it (0052). */
+export interface FrameDriver {
+    /** Schedules a frame if none is coming (on-demand); a no-op for runners that run every frame. */
+    requestFrame(): void;
+    /** Stops the loop for good. */
+    stop(): void;
+}
+/**
+ * Waits until what the last frame drew is on screen (0062), resolving with when that was on the
+ * app's clock if it knows better than "now". The render plugin sets one: the frame's GPU work done,
+ * then the next animation frame, whose timestamp it resolves with. Without one, a frame counts as
+ * presented when it ends.
+ */
+export type FramePresenter = () => Promise<number | undefined>;
+/** When the app started and became usable, in ms on its clock (`AppOptions.now`) (0062). */
+export interface StartupTimings {
+    /** `init()` was called. NaN before. */
+    initStart: number;
+    /** `init()` resolved. NaN before. */
+    initEnd: number;
+    /** The host called `markUsable()`. NaN before. */
+    usableMarked: number;
+    /** The first frame after `markUsable()` was presented. NaN before. */
+    usable: number;
+}
 /**
  * Owns the world, plugins, and schedules, and runs frames. Hosts drive it with a runner
  * (animation frame, headless, or manual `update` calls).
@@ -50,6 +89,11 @@ export declare class App {
     private readonly now;
     private readonly plugins;
     private readonly pending;
+    /** Plugins in the order they were built; disposal runs it backwards. */
+    private readonly built;
+    private readonly scopes;
+    private driver;
+    private disposing;
     private readonly schedules;
     private readonly systemNames;
     private readonly states;
@@ -59,6 +103,12 @@ export declare class App {
     private startupDone;
     private accumulator;
     private readonly frameListeners;
+    private presenter;
+    /** Traces stamped since the last frame started; the next frame carries them. */
+    private readonly traces;
+    private readonly traceListeners;
+    private readonly usableWaiters;
+    private readonly startup_;
     private readonly appMethods;
     /** The plugin whose `build` is running, so registrations can be attributed to it. */
     private building;
@@ -95,8 +145,68 @@ export declare class App {
     init(): Promise<void>;
     /** Initializes, then hands control to the runner (manual if none was set). */
     run(): Promise<void>;
+    /**
+     * Stops the runner, waits for every plugin's work in flight (`beforeDispose`), then disposes
+     * plugins in reverse build order, so each releases what it created: GPU objects, surfaces,
+     * listeners, workers (0052). Idempotent; afterwards any other
+     * call throws `runtime/disposed`. A plugin whose dispose throws is logged and the rest still run.
+     */
+    dispose(): Promise<void>;
+    /** True once `dispose()` was called. */
+    get disposed(): boolean;
+    /**
+     * Adds a scope around everything the app runs (see `AppScope`). Returns a function that removes
+     * it; don't call that from inside the app's own code (a frame, a plugin's dispose): disposal
+     * drops every scope once plugins are done. Scopes enter in the order added and exit in reverse.
+     */
+    addScope(scope: AppScope): () => void;
+    /**
+     * Called by a loop runner as it starts. `requestFrame` and `dispose` reach the loop through it.
+     */
+    attachDriver(driver: FrameDriver): void;
+    /**
+     * Asks for a frame: an on-demand runner schedules one if none is coming (0052). Host code that
+     * changes what's on screen without writing the world (a canvas style, a DOM overlay) calls it.
+     */
+    requestFrame(): void;
+    /** Sets how a frame waits to be on screen (see `FramePresenter`). The render plugin calls it. */
+    setPresenter(presenter: FramePresenter | undefined): void;
+    /** When init started and ended and when the app became usable, in ms on the app's clock. */
+    get startup(): Readonly<StartupTimings>;
+    /**
+     * The host says the app is usable (for a VTT, once the scene is interactive). The first complete
+     * frame presented after this is the first usable frame (`startup.usable`, `whenUsable()`). Later
+     * calls do nothing.
+     */
+    markUsable(): void;
+    /** Resolves with `startup.usable` once the first usable frame is presented. */
+    whenUsable(): Promise<number>;
+    /**
+     * Stamps a host write (a patch, a token move) for latency: resolves with the ms from now until the
+     * frame that carries it is presented. Call it right after the write. The next frame to start
+     * carries every trace stamped before it; a frame that ends still loading (`LOADING_DEMAND`: a
+     * pipeline compiling, a mesh not uploaded) hands them on, so the latency runs until the write is
+     * visible. `onTrace` listeners see each result.
+     */
+    trace(label: string): Promise<number>;
+    /**
+     * Requests a frame and resolves (with the ms waited) once a complete frame is presented, as
+     * `trace` does, but no `onTrace` listener sees it: for tools waiting on the screen, not for
+     * latency.
+     */
+    whenPresented(): Promise<number>;
+    /** Called with every resolved trace: its label and latency in ms. Returns an unsubscribe function. */
+    onTrace(listener: (label: string, ms: number) => void): () => void;
+    /**
+     * Drops accumulated fixed-step time, so the next frame runs FixedUpdate for its own delta only.
+     * On-demand runners call it on waking, so a scene idle for a minute doesn't simulate the minute.
+     */
+    resetFixedTime(): void;
     /** Runs one frame. `delta` is in seconds. */
     update(delta: number): void;
+    private frame;
+    /** Resolves traces and the usable mark once this frame is on screen. */
+    private present;
     /** Called after every frame with the number of frames completed. Returns an unsubscribe function. */
     onFrame(listener: (frame: number) => void): () => void;
     /**
@@ -106,6 +216,20 @@ export declare class App {
     pump(): void;
     runSchedule(label: ScheduleLabel): void;
     describe(): AppDescription;
+    private assertLive;
+    /**
+     * Runs `fn` inside the app's scopes, as build and ready hooks run. For the part of an async ready
+     * hook after its first await, which runs outside them: what it makes counts against the app.
+     */
+    scoped<T>(fn: () => T): T;
+    /** Enters every scope; returns how many, for the matching `exit`. */
+    private enter;
+    /** Exits the first `n` scopes, so one added inside the section never sees an unmatched exit. */
+    private exit;
+    private buildPlugin;
+    /** Awaits a ready hook; the part that runs before its first await is inside the app's scopes. */
+    private readyPlugin;
+    private disposeAll;
     private schedule;
     private applyStateTransitions;
     private dependencyError;

package/dist/app.js

@@ -14,9 +14,16 @@ import {
   World
 } from "@aethervtt/shard-core";
 import { AppControl, AppControlResource } from "./control.js";
+import { FrameDemand, FrameDemandState, LOADING_DEMAND } from "./demand.js";
 import { Log, LogResource } from "./log.js";
 import { OnEnter, OnExit } from "./state.js";
-import { DisplayRate, FixedTime, GlobalRng, Time } from "./time.js";
+import {
+  DevMode,
+  DisplayRate,
+  FixedTime,
+  GlobalRng,
+  Time
+} from "./time.js";
 const FRAME_SCHEDULES = [Startup, First, PreUpdate, FixedUpdate, Update, PostUpdate, Last];
 const EPSILON = 1e-9;
 const TimePlugin = {
@@ -34,6 +41,11 @@ class App {
   now;
   plugins = /* @__PURE__ */ new Map();
   pending = [];
+  /** Plugins in the order they were built; disposal runs it backwards. */
+  built = [];
+  scopes = [];
+  driver;
+  disposing;
   schedules = /* @__PURE__ */ new Map();
   systemNames = /* @__PURE__ */ new Set();
   states = [];
@@ -43,6 +55,17 @@ class App {
   startupDone = false;
   accumulator = 0;
   frameListeners = /* @__PURE__ */ new Set();
+  presenter;
+  /** Traces stamped since the last frame started; the next frame carries them. */
+  traces = [];
+  traceListeners = /* @__PURE__ */ new Set();
+  usableWaiters = [];
+  startup_ = {
+    initStart: Number.NaN,
+    initEnd: Number.NaN,
+    usableMarked: Number.NaN,
+    usable: Number.NaN
+  };
   appMethods = /* @__PURE__ */ new Map();
   /** The plugin whose `build` is running, so registrations can be attributed to it. */
   building;
@@ -53,15 +76,20 @@ class App {
     this.now = options.now ?? (() => performance.now());
     this.world.insertResource(ProfilerResource, this.profiler);
     this.world.insertResource(GlobalRng, new Rng(options.seed ?? 0));
+    this.world.insertResource(DevMode, { enabled: options.dev ?? false });
     const log = new Log();
     log.now = () => this.world.tryResource(Time)?.elapsed ?? 0;
     this.world.insertResource(LogResource, log);
-    this.world.insertResource(AppControlResource, new AppControl());
+    const control = new AppControl();
+    control.onRequest = () => this.driver?.requestFrame();
+    this.world.insertResource(AppControlResource, control);
+    this.world.insertResource(FrameDemand, new FrameDemandState(this.now));
     this.addPlugin(TimePlugin);
   }
   // --- building --------------------------------------------------------------
   /** Adds plugins. They build in dependency order during `init()`. */
   addPlugin(...plugins) {
+    this.assertLive();
     for (const plugin of plugins) {
       if (this.plugins.has(plugin.name)) {
         throw new ShardError("app/duplicate-plugin", `Plugin "${plugin.name}" was added twice`);
@@ -73,6 +101,7 @@ class App {
   }
   /** Adds protocol methods (see `AppMethod`). A second method with a taken name throws. */
   addMethod(...methods) {
+    this.assertLive();
     for (const method of methods) {
       if (this.appMethods.has(method.name)) {
         throw new ShardError("app/duplicate-method", `Method "${method.name}" was added twice`);
@@ -86,6 +115,7 @@ class App {
     return [...this.appMethods.values()];
   }
   addSystems(schedule, ...systems) {
+    this.assertLive();
     const target = this.schedule(schedule);
     for (const system of systems) {
       const name = "system" in system ? system.system.name : system.name;
@@ -101,6 +131,7 @@ class App {
     return this;
   }
   configureSets(schedule, ...sets) {
+    this.assertLive();
     const target = this.schedule(schedule);
     for (const set of sets) {
       target.configureSet(set);
@@ -135,7 +166,11 @@ class App {
    * itself. Resources and entities stay. For hot reload; returns the removed system names.
    */
   unloadPlugin(name) {
+    this.assertLive();
     const owned = this.owned.get(name);
+    const plugin = this.plugins.get(name);
+    const at = plugin ? this.built.indexOf(plugin) : -1;
+    if (at !== -1) this.built.splice(at, 1);
     this.plugins.delete(name);
     this.owned.delete(name);
     if (!owned) return [];
@@ -159,37 +194,38 @@ class App {
    * first run. Startup systems it adds don't run: startup already happened.
    */
   async loadPlugin(plugin) {
+    this.assertLive();
     if (this.plugins.has(plugin.name)) {
       throw new ShardError("app/duplicate-plugin", `Plugin "${plugin.name}" is already loaded`, {
         hint: "Unload it first (unloadPlugin)."
       });
     }
     this.plugins.set(plugin.name, plugin);
-    this.building = plugin.name;
-    try {
-      plugin.build(this);
-    } finally {
-      this.building = void 0;
-    }
-    await plugin.ready?.(this);
+    this.buildPlugin(plugin);
+    await this.readyPlugin(plugin);
   }
   insertResource(def, value) {
+    this.assertLive();
     this.world.insertResource(def, value);
     return this;
   }
   /** Registers a state machine. `OnEnter(initial)` runs at the start of the first frame. */
   initState(state, initial = state.values[0]) {
+    this.assertLive();
     this.world.insertResource(state.resource, { current: initial, next: void 0 });
     this.states.push({ state, entered: false });
     return this;
   }
   setRunner(runner) {
+    this.assertLive();
     this.runner = runner;
     return this;
   }
   /** Builds plugins in dependency order, then awaits their `ready` hooks. */
   async init() {
+    this.assertLive();
     if (this.initialized) return;
+    if (Number.isNaN(this.startup_.initStart)) this.startup_.initStart = this.now();
     const built = [];
     const builtNames = /* @__PURE__ */ new Set();
     while (this.pending.length > 0) {
@@ -198,32 +234,145 @@ class App {
       );
       if (index === -1) throw this.dependencyError(builtNames);
       const [plugin] = this.pending.splice(index, 1);
-      this.building = plugin.name;
-      try {
-        plugin.build(this);
-      } finally {
-        this.building = void 0;
-      }
+      this.buildPlugin(plugin);
       built.push(plugin);
       builtNames.add(plugin.name);
     }
-    for (const plugin of built) await plugin.ready?.(this);
+    for (const plugin of built) await this.readyPlugin(plugin);
     this.initialized = true;
+    this.startup_.initEnd = this.now();
   }
   /** Initializes, then hands control to the runner (manual if none was set). */
   async run() {
     await this.init();
     await this.runner?.(this);
   }
+  /**
+   * Stops the runner, waits for every plugin's work in flight (`beforeDispose`), then disposes
+   * plugins in reverse build order, so each releases what it created: GPU objects, surfaces,
+   * listeners, workers (0052). Idempotent; afterwards any other
+   * call throws `runtime/disposed`. A plugin whose dispose throws is logged and the rest still run.
+   */
+  dispose() {
+    this.disposing ??= this.disposeAll();
+    return this.disposing;
+  }
+  /** True once `dispose()` was called. */
+  get disposed() {
+    return this.disposing !== void 0;
+  }
+  /**
+   * Adds a scope around everything the app runs (see `AppScope`). Returns a function that removes
+   * it; don't call that from inside the app's own code (a frame, a plugin's dispose): disposal
+   * drops every scope once plugins are done. Scopes enter in the order added and exit in reverse.
+   */
+  addScope(scope) {
+    this.assertLive();
+    this.scopes.push(scope);
+    return () => {
+      const i = this.scopes.indexOf(scope);
+      if (i !== -1) this.scopes.splice(i, 1);
+    };
+  }
+  /**
+   * Called by a loop runner as it starts. `requestFrame` and `dispose` reach the loop through it.
+   */
+  attachDriver(driver) {
+    this.assertLive();
+    this.driver = driver;
+  }
+  /**
+   * Asks for a frame: an on-demand runner schedules one if none is coming (0052). Host code that
+   * changes what's on screen without writing the world (a canvas style, a DOM overlay) calls it.
+   */
+  requestFrame() {
+    this.assertLive();
+    this.driver?.requestFrame();
+  }
+  // --- presentation (0062) ----------------------------------------------------
+  /** Sets how a frame waits to be on screen (see `FramePresenter`). The render plugin calls it. */
+  setPresenter(presenter) {
+    this.presenter = presenter;
+  }
+  /** When init started and ended and when the app became usable, in ms on the app's clock. */
+  get startup() {
+    return this.startup_;
+  }
+  /**
+   * The host says the app is usable (for a VTT, once the scene is interactive). The first complete
+   * frame presented after this is the first usable frame (`startup.usable`, `whenUsable()`). Later
+   * calls do nothing.
+   */
+  markUsable() {
+    this.assertLive();
+    if (!Number.isNaN(this.startup_.usableMarked)) return;
+    this.startup_.usableMarked = this.now();
+    this.driver?.requestFrame();
+  }
+  /** Resolves with `startup.usable` once the first usable frame is presented. */
+  whenUsable() {
+    if (!Number.isNaN(this.startup_.usable)) return Promise.resolve(this.startup_.usable);
+    return new Promise((resolve) => this.usableWaiters.push(resolve));
+  }
+  /**
+   * Stamps a host write (a patch, a token move) for latency: resolves with the ms from now until the
+   * frame that carries it is presented. Call it right after the write. The next frame to start
+   * carries every trace stamped before it; a frame that ends still loading (`LOADING_DEMAND`: a
+   * pipeline compiling, a mesh not uploaded) hands them on, so the latency runs until the write is
+   * visible. `onTrace` listeners see each result.
+   */
+  trace(label) {
+    this.assertLive();
+    return new Promise((resolve) => {
+      this.traces.push({ label, at: this.now(), resolve });
+      this.driver?.requestFrame();
+    });
+  }
+  /**
+   * Requests a frame and resolves (with the ms waited) once a complete frame is presented, as
+   * `trace` does, but no `onTrace` listener sees it: for tools waiting on the screen, not for
+   * latency.
+   */
+  whenPresented() {
+    this.assertLive();
+    return new Promise((resolve) => {
+      this.traces.push({ label: void 0, at: this.now(), resolve });
+      this.driver?.requestFrame();
+    });
+  }
+  /** Called with every resolved trace: its label and latency in ms. Returns an unsubscribe function. */
+  onTrace(listener) {
+    this.assertLive();
+    this.traceListeners.add(listener);
+    return () => this.traceListeners.delete(listener);
+  }
+  /**
+   * Drops accumulated fixed-step time, so the next frame runs FixedUpdate for its own delta only.
+   * On-demand runners call it on waking, so a scene idle for a minute doesn't simulate the minute.
+   */
+  resetFixedTime() {
+    this.accumulator = 0;
+  }
   // --- running ---------------------------------------------------------------
   /** Runs one frame. `delta` is in seconds. */
   update(delta) {
+    this.assertLive();
     if (!this.initialized) {
       throw new ShardError("app/not-initialized", "App.update() was called before init()", {
         hint: "Await app.init() (or app.run()) first."
       });
     }
+    const scoped = this.enter();
+    try {
+      this.frame(delta);
+    } finally {
+      this.exit(scoped);
+    }
+  }
+  frame(delta) {
     const world = this.world;
+    const traces = this.traces.length > 0 ? this.traces.splice(0) : void 0;
+    const usable = Number.isNaN(this.startup_.usable) && !Number.isNaN(this.startup_.usableMarked);
     if (!this.startupDone) {
       this.runSchedule(Startup);
       this.startupDone = true;
@@ -252,9 +401,39 @@ class App {
     this.runSchedule(Last);
     time.frame++;
     for (const listener of this.frameListeners) listener(time.frame);
+    if (!traces && !usable) return;
+    if (world.resource(FrameDemand).isHeld(LOADING_DEMAND)) {
+      if (traces) this.traces.unshift(...traces);
+      return;
+    }
+    this.present(traces, usable);
+  }
+  /** Resolves traces and the usable mark once this frame is on screen. */
+  present(traces, usable) {
+    const done = (when) => {
+      const at = when ?? this.now();
+      if (usable && Number.isNaN(this.startup_.usable)) {
+        this.startup_.usable = at;
+        for (const resolve of this.usableWaiters.splice(0)) resolve(at);
+      }
+      if (!traces) return;
+      for (const trace of traces) {
+        const ms = Math.max(0, at - trace.at);
+        trace.resolve(ms);
+        const label = trace.label;
+        if (label !== void 0) for (const listener of this.traceListeners) listener(label, ms);
+      }
+    };
+    const presenter = this.presenter;
+    if (!presenter) {
+      done();
+      return;
+    }
+    presenter().then(done, () => done());
   }
   /** Called after every frame with the number of frames completed. Returns an unsubscribe function. */
   onFrame(listener) {
+    this.assertLive();
     this.frameListeners.add(listener);
     return () => this.frameListeners.delete(listener);
   }
@@ -263,6 +442,7 @@ class App {
    * without a frame loop (headless servers); loop-driven runners step one frame per tick instead.
    */
   pump() {
+    this.assertLive();
     const control = this.world.resource(AppControlResource);
     while (control.pendingSteps > 0) {
       try {
@@ -301,6 +481,113 @@ class App {
     };
   }
   // --- internals -------------------------------------------------------------
+  assertLive() {
+    if (this.disposing === void 0) return;
+    throw new ShardError("runtime/disposed", "This app was disposed", {
+      hint: "Create a new App; a disposed one has released its GPU objects and listeners."
+    });
+  }
+  /**
+   * Runs `fn` inside the app's scopes, as build and ready hooks run. For the part of an async ready
+   * hook after its first await, which runs outside them: what it makes counts against the app.
+   */
+  scoped(fn) {
+    const n = this.enter();
+    try {
+      return fn();
+    } finally {
+      this.exit(n);
+    }
+  }
+  /** Enters every scope; returns how many, for the matching `exit`. */
+  enter() {
+    const n = this.scopes.length;
+    for (let i = 0; i < n; i++) this.scopes[i].enter();
+    return n;
+  }
+  /** Exits the first `n` scopes, so one added inside the section never sees an unmatched exit. */
+  exit(n) {
+    for (let i = Math.min(n, this.scopes.length) - 1; i >= 0; i--) this.scopes[i].exit();
+  }
+  buildPlugin(plugin) {
+    this.building = plugin.name;
+    const scoped = this.enter();
+    try {
+      plugin.build(this);
+    } finally {
+      this.exit(scoped);
+      this.building = void 0;
+    }
+    this.built.push(plugin);
+  }
+  /** Awaits a ready hook; the part that runs before its first await is inside the app's scopes. */
+  async readyPlugin(plugin) {
+    if (!plugin.ready) return;
+    const scoped = this.enter();
+    let result;
+    try {
+      result = plugin.ready(this);
+    } finally {
+      this.exit(scoped);
+    }
+    await result;
+  }
+  async disposeAll() {
+    const driver = this.driver;
+    this.driver = void 0;
+    driver?.stop();
+    this.frameListeners.clear();
+    this.traceListeners.clear();
+    this.presenter = void 0;
+    this.world.onWake = void 0;
+    this.world.asleep = false;
+    const log = this.world.tryResource(LogResource);
+    let first;
+    for (const plugin of this.built) {
+      if (!plugin.beforeDispose) continue;
+      const scoped = this.enter();
+      let result;
+      try {
+        result = plugin.beforeDispose(this);
+      } catch (err) {
+        first ??= err;
+        log?.error(err);
+        continue;
+      } finally {
+        this.exit(scoped);
+      }
+      try {
+        await result;
+      } catch (err) {
+        first ??= err;
+        log?.error(err);
+      }
+    }
+    for (let i = this.built.length - 1; i >= 0; i--) {
+      const plugin = this.built[i];
+      if (!plugin.dispose) continue;
+      const scoped = this.enter();
+      let result;
+      try {
+        result = plugin.dispose(this);
+      } catch (err) {
+        first ??= err;
+        log?.error(err);
+        continue;
+      } finally {
+        this.exit(scoped);
+      }
+      try {
+        await result;
+      } catch (err) {
+        first ??= err;
+        log?.error(err);
+      }
+    }
+    this.built.length = 0;
+    this.scopes.length = 0;
+    if (first !== void 0) throw first;
+  }
   schedule(label) {
     let schedule = this.schedules.get(label);
     if (!schedule) {

package/dist/control.d.ts

@@ -6,6 +6,8 @@ export declare class AppControl {
     paused: boolean;
     /** Set when a failing frame paused the app, so a fix (e.g. a hot reload) can resume it. */
     pausedByError: boolean;
+    /** Called when steps are queued, so an idle on-demand runner wakes to run them (0052). */
+    onRequest: (() => void) | undefined;
     /** Stepped frames ever requested / ever run. Both only grow; the difference is what's pending. */
     private requested;
     private completed;

package/dist/control.js

@@ -3,6 +3,8 @@ class AppControl {
   paused = false;
   /** Set when a failing frame paused the app, so a fix (e.g. a hot reload) can resume it. */
   pausedByError = false;
+  /** Called when steps are queued, so an idle on-demand runner wakes to run them (0052). */
+  onRequest = void 0;
   /** Stepped frames ever requested / ever run. Both only grow; the difference is what's pending. */
   requested = 0;
   completed = 0;
@@ -16,7 +18,11 @@ class AppControl {
     if (frames <= 0) return Promise.resolve();
     this.requested += frames;
     const target = this.requested;
-    return new Promise((resolve, reject) => this.waiters.push({ target, resolve, reject }));
+    const done = new Promise(
+      (resolve, reject) => this.waiters.push({ target, resolve, reject })
+    );
+    this.onRequest?.();
+    return done;
   }
   /** A stepped frame threw: drops the pending steps and rejects everyone waiting on them. */
   abort(error) {

package/dist/demand.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The frame demand a renderer holds while a frame skipped draws (pipelines compiling, meshes or
+ * materials still loading, 0052). Such a frame isn't complete: traces and the first usable frame
+ * wait for one that is (0062).
+ */
+export declare const LOADING_DEMAND = "render/loading";
+/** How the app's frames are driven: every display refresh, only when needed, or by hand. */
+export type FrameMode = 'continuous' | 'on-demand' | 'manual';
+/**
+ * What keeps an on-demand runner rendering (0052). Holders are named, so `render.describe` can say
+ * who is keeping frames running: awake physics bodies, live particles, playing animations, the
+ * RenderScale controller while probing, or anything a game holds itself.
+ */
+export declare class FrameDemandState {
+    /** Set by the runner. 'manual' until a loop runner starts. */
+    mode: FrameMode;
+    /** Clock time (ms, the app's clock) of the earliest frame `after` asked for; Infinity if none. */
+    dueAt: number;
+    /** Set by the on-demand runner: called when a new demand appears, so an idle runner wakes. */
+    onDemand: (() => void) | undefined;
+    private readonly holders;
+    private readonly now;
+    constructor(now?: () => number);
+    /** Keeps frames running until `release(key)`. Holding a key twice is one hold. */
+    hold(key: string): void;
+    release(key: string): void;
+    /** Holds `key` while `on` is true: one call per frame from a system that tracks a condition. */
+    set(key: string, on: boolean): void;
+    /** Asks for one frame `ms` from now, for ambient loops at low rates. The earliest ask wins. */
+    after(ms: number): void;
+    /** Ms until the frame `after` asked for (0 if overdue); Infinity if none was asked for. */
+    dueIn(): number;
+    /** @internal The runner calls this as a frame starts: a frame that was due is now running. */
+    takeDue(): void;
+    /** Whether anything holds frames running. */
+    get active(): boolean;
+    isHeld(key: string): boolean;
+    /** The keys holding frames running, sorted. */
+    held(): string[];
+    /** The runner's mode, what holds frames, and when the next timed frame is due. For agents. */
+    describe(): {
+        mode: FrameMode;
+        demands: string[];
+        dueInMs: number | null;
+    };
+}
+export declare const FrameDemand: import("@aethervtt/shard-core").ResourceDef<FrameDemandState>;

package/dist/demand.js

@@ -0,0 +1,68 @@
+import { defineResource } from "@aethervtt/shard-core";
+const LOADING_DEMAND = "render/loading";
+class FrameDemandState {
+  /** Set by the runner. 'manual' until a loop runner starts. */
+  mode = "manual";
+  /** Clock time (ms, the app's clock) of the earliest frame `after` asked for; Infinity if none. */
+  dueAt = Number.POSITIVE_INFINITY;
+  /** Set by the on-demand runner: called when a new demand appears, so an idle runner wakes. */
+  onDemand = void 0;
+  holders = /* @__PURE__ */ new Set();
+  now;
+  constructor(now = () => performance.now()) {
+    this.now = now;
+  }
+  /** Keeps frames running until `release(key)`. Holding a key twice is one hold. */
+  hold(key) {
+    if (this.holders.has(key)) return;
+    this.holders.add(key);
+    this.onDemand?.();
+  }
+  release(key) {
+    this.holders.delete(key);
+  }
+  /** Holds `key` while `on` is true: one call per frame from a system that tracks a condition. */
+  set(key, on) {
+    if (on) this.hold(key);
+    else this.holders.delete(key);
+  }
+  /** Asks for one frame `ms` from now, for ambient loops at low rates. The earliest ask wins. */
+  after(ms) {
+    const at = this.now() + Math.max(0, ms);
+    if (at >= this.dueAt) return;
+    this.dueAt = at;
+    this.onDemand?.();
+  }
+  /** Ms until the frame `after` asked for (0 if overdue); Infinity if none was asked for. */
+  dueIn() {
+    return this.dueAt === Number.POSITIVE_INFINITY ? this.dueAt : Math.max(0, this.dueAt - this.now());
+  }
+  /** @internal The runner calls this as a frame starts: a frame that was due is now running. */
+  takeDue() {
+    if (this.dueAt <= this.now() + 1) this.dueAt = Number.POSITIVE_INFINITY;
+  }
+  /** Whether anything holds frames running. */
+  get active() {
+    return this.holders.size > 0;
+  }
+  isHeld(key) {
+    return this.holders.has(key);
+  }
+  /** The keys holding frames running, sorted. */
+  held() {
+    return [...this.holders].sort();
+  }
+  /** The runner's mode, what holds frames, and when the next timed frame is due. For agents. */
+  describe() {
+    const due = this.dueIn();
+    return { mode: this.mode, demands: this.held(), dueInMs: due === Infinity ? null : due };
+  }
+}
+const FrameDemand = defineResource("core/FrameDemand", {
+  description: "What keeps an on-demand runner rendering: hold(key) / release(key) while something must run each frame, after(ms) for one frame later."
+});
+export {
+  FrameDemand,
+  FrameDemandState,
+  LOADING_DEMAND
+};

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-export { App, type AppDescription, type AppMethod, type AppOptions } from './app.js';
+export { App, type AppDescription, type AppMethod, type AppOptions, type AppScope, type FrameDriver, type FramePresenter, type StartupTimings, } from './app.js';
 export { AppControl, AppControlResource } from './control.js';
+export { FrameDemand, FrameDemandState, type FrameMode, LOADING_DEMAND } from './demand.js';
 export { COMMON_RATES, RefreshMeter, rateFromIntervals, snapRate } from './display.js';
 export { Log, type LogEntry, type LogLevel, LogResource } from './log.js';
 export { definePlugin, type Plugin } from './plugin.js';
 export { type AnimationFrameOptions, animationFrameRunner, type HeadlessOptions, headlessRunner, type Runner, } from './runners.js';
 export { defineState, inState, OnEnter, OnExit, type StateDef, type StateValue, setState, } from './state.js';
-export { DisplayRate, type DisplayRateData, FixedTime, type FixedTimeData, GlobalRng, Time, type TimeData, } from './time.js';
+export { DevMode, DisplayRate, type DisplayRateData, FixedTime, type FixedTimeData, GlobalRng, Time, type TimeData, } from './time.js';

package/dist/index.js

@@ -1,5 +1,8 @@
-import { App } from "./app.js";
+import {
+  App
+} from "./app.js";
 import { AppControl, AppControlResource } from "./control.js";
+import { FrameDemand, FrameDemandState, LOADING_DEMAND } from "./demand.js";
 import { COMMON_RATES, RefreshMeter, rateFromIntervals, snapRate } from "./display.js";
 import { Log, LogResource } from "./log.js";
 import { definePlugin } from "./plugin.js";
@@ -15,6 +18,7 @@ import {
   setState
 } from "./state.js";
 import {
+  DevMode,
   DisplayRate,
   FixedTime,
   GlobalRng,
@@ -25,9 +29,13 @@ export {
   AppControl,
   AppControlResource,
   COMMON_RATES,
+  DevMode,
   DisplayRate,
   FixedTime,
+  FrameDemand,
+  FrameDemandState,
   GlobalRng,
+  LOADING_DEMAND,
   Log,
   LogResource,
   OnEnter,

package/dist/plugin.d.ts

@@ -14,5 +14,17 @@ export interface Plugin {
     build(app: App): void;
     /** Optional async setup (e.g. loading WASM), awaited before Startup. */
     ready?(app: App): Promise<void> | void;
+    /**
+     * Releases what `build` and `ready` created that outlives the app: GPU objects, surfaces, DOM
+     * listeners, observers, workers. `app.dispose()` calls it in reverse build order, after the
+     * runner stopped (0052).
+     */
+    dispose?(app: App): Promise<void> | void;
+    /**
+     * Waits for work the plugin started that is still in flight (GPU commands submitted but not
+     * done). `app.dispose()` awaits it on every plugin before any plugin's `dispose`, so nothing is
+     * released while still in use: render's dispose runs last, after others freed their buffers.
+     */
+    beforeDispose?(app: App): Promise<void> | void;
 }
 export declare function definePlugin(plugin: Plugin): Plugin;

package/dist/runners.d.ts

@@ -11,13 +11,28 @@ export declare function headlessRunner(options: HeadlessOptions): Runner;
 export interface AnimationFrameOptions {
     /** Longest delta passed to update, in seconds, e.g. after the tab was hidden. Default 0.25. */
     maxDelta?: number;
-    /** Stops the loop when aborted. */
+    /** Stops the loop when aborted. `app.dispose()` stops it too. */
     signal?: AbortSignal;
     /**
      * Time a few idle frames before the first update to measure the display's refresh rate into
      * DisplayRate (about 12 refreshes: 0.1 s at 120 Hz). Default true.
      */
     measureRefresh?: boolean;
+    /**
+     * continuous (default): a frame every display refresh. on-demand: a frame only when something
+     * changed (0052): a world write, a FrameDemand holder or timer, input, a surface resize, queued
+     * steps, or `app.requestFrame()`. Idle, it requests no animation frames at all.
+     */
+    mode?: 'continuous' | 'on-demand';
+    /**
+     * On-demand, for dev builds: every second while idle, compare the plain-object resources marked
+     * `hostWritable` with their values when the app went idle, and log
+     * `runtime/unmarked-resource-write` for one that changed without waking it. Default false.
+     */
+    checkResourceWrites?: boolean;
 }
-/** Runs a frame per `requestAnimationFrame`. For the browser and Studio. */
+/**
+ * Runs frames on `requestAnimationFrame`, for the browser and Studio: one per display refresh, or
+ * in `mode: 'on-demand'` only while something needs them (0052).
+ */
 export declare function animationFrameRunner(options?: AnimationFrameOptions): Runner;

package/dist/runners.js

@@ -1,4 +1,5 @@
 import { AppControlResource } from "./control.js";
+import { FrameDemand } from "./demand.js";
 import { RefreshMeter, rateFromIntervals } from "./display.js";
 import { LogResource } from "./log.js";
 import { DisplayRate } from "./time.js";
@@ -9,76 +10,157 @@ function headlessRunner(options) {
   };
 }
 const PROBE_INTERVALS = 12;
-function probeRefresh() {
+function probeRefresh(probe) {
   return new Promise((resolve) => {
     if (document.hidden) return resolve(0);
     const intervals = new Float64Array(PROBE_INTERVALS);
     let last = -1;
     let n = 0;
     const tick = (t) => {
-      if (document.hidden) return resolve(0);
+      if (probe.stopped || document.hidden) return resolve(0);
       if (last >= 0) intervals[n++] = t - last;
       last = t;
-      if (n < PROBE_INTERVALS) requestAnimationFrame(tick);
+      if (n < PROBE_INTERVALS) probe.handle = requestAnimationFrame(tick);
       else resolve(rateFromIntervals(intervals));
     };
-    requestAnimationFrame(tick);
+    probe.handle = requestAnimationFrame(tick);
   });
 }
 function animationFrameRunner(options = {}) {
   const maxDelta = options.maxDelta ?? 0.25;
+  const onDemand = options.mode === "on-demand";
   return async (app) => {
-    const display = app.world.tryResource(DisplayRate);
-    if (display && options.measureRefresh !== false) {
-      const hz = await probeRefresh();
+    const world = app.world;
+    const demand = world.resource(FrameDemand);
+    const control = world.resource(AppControlResource);
+    const display = world.tryResource(DisplayRate);
+    const probe = { handle: 0, stopped: false };
+    let handle = 0;
+    let pending = false;
+    let idle = true;
+    let last;
+    let timer;
+    let writes;
+    let finish = () => {
+    };
+    const finished = new Promise((resolve) => {
+      finish = resolve;
+    });
+    const schedule = () => {
+      if (pending || probe.stopped) return;
+      pending = true;
+      handle = requestAnimationFrame(frame);
+    };
+    const onTimer = () => {
+      timer = void 0;
+      schedule();
+    };
+    const armTimer = () => {
+      if (timer !== void 0) clearTimeout(timer);
+      timer = void 0;
+      const due = demand.dueIn();
+      if (due !== Number.POSITIVE_INFINITY) timer = setTimeout(onTimer, due);
+    };
+    const goIdle = () => {
+      idle = true;
+      world.asleep = true;
+      armTimer();
+      writes?.start();
+    };
+    const onVisibility = () => {
+      if (document.hidden) last = void 0;
+    };
+    const stop = () => {
+      if (probe.stopped) return;
+      probe.stopped = true;
+      cancelAnimationFrame(probe.handle);
+      if (pending) cancelAnimationFrame(handle);
+      pending = false;
+      if (timer !== void 0) clearTimeout(timer);
+      timer = void 0;
+      writes?.stop();
+      document.removeEventListener("visibilitychange", onVisibility);
+      options.signal?.removeEventListener("abort", stop);
+      if (onDemand) {
+        world.onWake = void 0;
+        world.asleep = false;
+        demand.onDemand = void 0;
+      }
+      demand.mode = "manual";
+      finish();
+    };
+    const meter = new RefreshMeter(display?.periodMs ?? 1e3 / 60);
+    const frame = (timestamp) => {
+      pending = false;
+      if (probe.stopped) return;
+      const woke = idle;
+      idle = false;
+      writes?.stop();
+      let delta = last === void 0 ? 0 : Math.min((timestamp - last) / 1e3, maxDelta);
+      if (onDemand) {
+        world.asleep = false;
+        demand.takeDue();
+        if (woke && last !== void 0) {
+          delta = 1 / app.fixedHz;
+          app.resetFixedTime();
+        }
+      }
+      if (display && last !== void 0 && !woke) {
+        const hz = meter.sample(timestamp - last);
+        if (hz > 0) {
+          display.hz = hz;
+          display.periodMs = 1e3 / hz;
+          display.source = "measured";
+        }
+      }
+      last = timestamp;
+      try {
+        if (!control.paused) app.update(delta);
+        else if (control.pendingSteps > 0) {
+          app.update(1 / app.fixedHz);
+          control.stepped();
+        }
+      } catch (err) {
+        world.resource(LogResource).error(err);
+        control.paused = true;
+        control.pausedByError = true;
+        control.abort(err);
+        console.error(err);
+      }
+      if (probe.stopped) return;
+      if (!onDemand || demand.active || control.pendingSteps > 0) schedule();
+      if (!pending) goIdle();
+    };
+    options.signal?.addEventListener("abort", stop);
+    app.attachDriver({ requestFrame: onDemand ? schedule : () => {
+    }, stop });
+    demand.mode = onDemand ? "on-demand" : "continuous";
+    if (options.signal?.aborted) stop();
+    if (display && options.measureRefresh !== false && !probe.stopped) {
+      const hz = await probeRefresh(probe);
       if (hz > 0) {
         display.hz = hz;
         display.periodMs = 1e3 / hz;
         display.source = "measured";
+        meter.periodMs = display.periodMs;
       }
     }
-    const meter = new RefreshMeter(display?.periodMs ?? 1e3 / 60);
-    return new Promise((resolve) => {
-      let last;
-      let handle = 0;
-      const onVisibility = () => {
-        if (document.hidden) last = void 0;
-      };
-      const frame = (timestamp) => {
-        const delta = last === void 0 ? 0 : Math.min((timestamp - last) / 1e3, maxDelta);
-        if (display && last !== void 0) {
-          const hz = meter.sample(timestamp - last);
-          if (hz > 0) {
-            display.hz = hz;
-            display.periodMs = 1e3 / hz;
-            display.source = "measured";
-          }
-        }
-        last = timestamp;
-        const control = app.world.resource(AppControlResource);
-        try {
-          if (!control.paused) app.update(delta);
-          else if (control.pendingSteps > 0) {
-            app.update(1 / app.fixedHz);
-            control.stepped();
-          }
-        } catch (err) {
-          app.world.resource(LogResource).error(err);
-          control.paused = true;
-          control.pausedByError = true;
-          control.abort(err);
-          console.error(err);
-        }
-        handle = requestAnimationFrame(frame);
+    if (onDemand && options.checkResourceWrites) {
+      const { ResourceWriteCheck } = await import("./write-check.js");
+      writes = new ResourceWriteCheck(world, world.tryResource(LogResource), () => idle && !pending);
+    }
+    if (probe.stopped) return;
+    if (onDemand) {
+      world.onWake = schedule;
+      demand.onDemand = () => {
+        if (!idle || probe.stopped) return;
+        if (demand.active) schedule();
+        else armTimer();
       };
-      document.addEventListener("visibilitychange", onVisibility);
-      options.signal?.addEventListener("abort", () => {
-        cancelAnimationFrame(handle);
-        document.removeEventListener("visibilitychange", onVisibility);
-        resolve();
-      });
-      handle = requestAnimationFrame(frame);
-    });
+    }
+    document.addEventListener("visibilitychange", onVisibility);
+    schedule();
+    return finished;
   };
 }
 export {

package/dist/testing.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A stand-in for the browser's frame loop, so `animationFrameRunner` runs headless in tests: it
+ * installs `requestAnimationFrame`, `cancelAnimationFrame`, and (when there's none) a visible
+ * `document` on globalThis. Frames only run when the test ticks.
+ */
+export interface FakeFrames {
+    /** Animation frames requested so far. */
+    readonly requested: number;
+    /** Callbacks waiting for the next frame. */
+    readonly pending: number;
+    /** The timestamp the last tick passed, in ms. */
+    readonly now: number;
+    /** `visibilitychange` listeners on the fake document. */
+    readonly listeners: number;
+    /** Advances the clock by `ms` (default one 60 Hz refresh) and runs what was waiting. */
+    tick(ms?: number): number;
+    /** Ticks until nothing waits or `max` frames ran; returns the frames run. */
+    runUntilIdle(max?: number, ms?: number): number;
+    /** Puts the real globals back. */
+    restore(): void;
+}
+export declare function fakeAnimationFrames(): FakeFrames;

package/dist/testing.js

@@ -0,0 +1,64 @@
+function fakeAnimationFrames() {
+  const g = globalThis;
+  const saved = {
+    raf: g.requestAnimationFrame,
+    caf: g.cancelAnimationFrame,
+    document: g.document
+  };
+  let waiting = /* @__PURE__ */ new Map();
+  let nextId = 1;
+  let requested = 0;
+  let now = 0;
+  let listeners = 0;
+  g.requestAnimationFrame = (fn) => {
+    const id = nextId++;
+    requested++;
+    waiting.set(id, fn);
+    return id;
+  };
+  g.cancelAnimationFrame = (id) => {
+    waiting.delete(id);
+  };
+  if (saved.document === void 0) {
+    g.document = {
+      hidden: false,
+      addEventListener: () => void listeners++,
+      removeEventListener: () => void listeners--
+    };
+  }
+  const tick = (ms = 1e3 / 60) => {
+    now += ms;
+    const run = waiting;
+    waiting = /* @__PURE__ */ new Map();
+    for (const fn of run.values()) fn(now);
+    return run.size;
+  };
+  return {
+    get requested() {
+      return requested;
+    },
+    get pending() {
+      return waiting.size;
+    },
+    get now() {
+      return now;
+    },
+    get listeners() {
+      return listeners;
+    },
+    tick,
+    runUntilIdle(max = 1e4, ms) {
+      let frames = 0;
+      while (waiting.size > 0 && frames < max) frames += tick(ms);
+      return frames;
+    },
+    restore() {
+      g.requestAnimationFrame = saved.raf;
+      g.cancelAnimationFrame = saved.caf;
+      g.document = saved.document;
+    }
+  };
+}
+export {
+  fakeAnimationFrames
+};

package/dist/time.d.ts

@@ -32,3 +32,7 @@ export interface DisplayRateData {
 }
 export declare const DisplayRate: import("@aethervtt/shard-core").ResourceDef<DisplayRateData>;
 export declare const GlobalRng: import("@aethervtt/shard-core").ResourceDef<Rng>;
+/** Whether this is a development build (`new App({ dev: true })`). */
+export declare const DevMode: import("@aethervtt/shard-core").ResourceDef<{
+    enabled: boolean;
+}>;

package/dist/time.js

@@ -11,7 +11,12 @@ const DisplayRate = defineResource("core/DisplayRate", {
 const GlobalRng = defineResource("core/GlobalRng", {
   description: "The app root random stream, seeded from AppOptions.seed. Fork it per system."
 });
+const DevMode = defineResource("runtime/DevMode", {
+  description: "Development build: loud fallbacks and dev-only checks.",
+  init: () => ({ enabled: false })
+});
 export {
+  DevMode,
   DisplayRate,
   FixedTime,
   GlobalRng,

package/dist/write-check.d.ts

@@ -0,0 +1,22 @@
+import { type World } from '@aethervtt/shard-core';
+import type { Log } from './log.js';
+/**
+ * The on-demand runner's dev check (0052): while the app is idle, every second, compare the
+ * plain-object resources marked `hostWritable` with their values when it went idle, and log
+ * `runtime/unmarked-resource-write` for one that changed without waking the app. Loaded only when
+ * `checkResourceWrites` is on, so production builds don't carry it.
+ */
+export declare class ResourceWriteCheck {
+    private readonly snapshots;
+    private timer;
+    private readonly world;
+    private readonly log;
+    private readonly quiet;
+    /** `quiet`: still idle with no frame requested, so a change nobody announced is a bug. */
+    constructor(world: World, log: Log | undefined, quiet: () => boolean);
+    /** The app went idle: remember what the resources hold, and check them every second. */
+    start(): void;
+    /** A frame is running (or the loop stopped): writes are fine again. */
+    stop(): void;
+    private verify;
+}

package/dist/write-check.js

@@ -0,0 +1,54 @@
+import { allResources, isPlainObject } from "@aethervtt/shard-core";
+const CHECK_MS = 1e3;
+function hashOf(value) {
+  if (!isPlainObject(value)) return void 0;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return void 0;
+  }
+}
+class ResourceWriteCheck {
+  snapshots = /* @__PURE__ */ new Map();
+  timer;
+  world;
+  log;
+  quiet;
+  /** `quiet`: still idle with no frame requested, so a change nobody announced is a bug. */
+  constructor(world, log, quiet) {
+    this.world = world;
+    this.log = log;
+    this.quiet = quiet;
+  }
+  /** The app went idle: remember what the resources hold, and check them every second. */
+  start() {
+    this.snapshots.clear();
+    for (const def of allResources()) {
+      if (!def.hostWritable) continue;
+      const hash = hashOf(this.world.tryResource(def));
+      if (hash !== void 0) this.snapshots.set(def, hash);
+    }
+    this.timer ??= setInterval(() => this.verify(), CHECK_MS);
+  }
+  /** A frame is running (or the loop stopped): writes are fine again. */
+  stop() {
+    if (this.timer !== void 0) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+  verify() {
+    if (!this.quiet()) return;
+    for (const [def, before] of this.snapshots) {
+      const now = hashOf(this.world.tryResource(def)) ?? "";
+      if (now === before) continue;
+      this.snapshots.set(def, now);
+      this.log?.log("warn", `Resource "${def.name}" changed without waking the app`, {
+        code: "runtime/unmarked-resource-write",
+        path: def.name,
+        hint: "Outside a frame, write resources with world.patchResource or world.touchResource (or call app.requestFrame())."
+      });
+    }
+  }
+}
+export {
+  ResourceWriteCheck
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-runtime",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -8,6 +8,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "files": [
@@ -16,7 +20,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@aethervtt/shard-core": "0.0.1"
+    "@aethervtt/shard-core": "0.1.0"
   },
   "repository": {
     "type": "git",
@@ -28,6 +32,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+    "buildSha": "8e14c9896f82a3554b156f1ffdd68f2cc3e7d78a"
   }
 }