@aethervtt/shard-runtime 0.0.1 → 0.2.0

package/dist/app.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentDef, type ResourceDef, type ScheduleLabel, type SystemConfig, type SystemDef, type SystemDescription, type SystemSetConfig, World } from '@aethervtt/shard-core';
+import { type ComponentDef, type ProfilerSettingsData, type ResourceDef, type ScheduleLabel, type SystemConfig, type SystemDef, type SystemDescription, type SystemSetConfig, World } from '@aethervtt/shard-core';
 import type { Plugin } from './plugin.js';
 import type { Runner } from './runners.js';
 import { type StateDef } from './state.js';
@@ -11,6 +11,24 @@ 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;
+    /**
+     * The profiler (0074): `enabled: false` turns spans off for builds that want every microsecond;
+     * `window` is how many runs aggregates cover. Also `ProfilerSettings` at runtime. Default on, 120.
+     */
+    profiler?: Partial<ProfilerSettingsData>;
+    /**
+     * The budget scenario the app runs as (0075, `bench/perf/budgets.json`): features that adapt
+     * (0045's foliage) default their target to their slice of its frame, and the `perf` overlay shows
+     * its slices. Default none: nothing adapts. Also `App.perfScenario` and the `PerfScenario`
+     * resource at runtime.
+     */
+    perfScenario?: string | null;
 }
 export interface AppDescription {
     plugins: {
@@ -39,6 +57,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 +101,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 +115,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;
@@ -68,6 +130,12 @@ export declare class App {
     addPlugin(...plugins: Plugin[]): this;
     /** Adds protocol methods (see `AppMethod`). A second method with a taken name throws. */
     addMethod(...methods: AppMethod[]): this;
+    /**
+     * The budget scenario the app declares (0075): features with a budget resource adapt to their
+     * slice of its frame, and the `perf` overlay shows its slices. null (the default): none.
+     */
+    get perfScenario(): string | null;
+    set perfScenario(name: string | null);
     /** Methods plugins added, in the order they were added. */
     get methods(): readonly AppMethod[];
     addSystems(schedule: ScheduleLabel, ...systems: SystemInput[]): this;
@@ -95,8 +163,70 @@ 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;
+    /** One frame, timed as the `frame` span (0074). */
+    private frame;
+    private frameBody;
+    /** 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 +236,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;