@aethervtt/shard-runtime 0.0.1 → 0.2.0

package/dist/app.js

@@ -6,6 +6,7 @@ import {
   PreUpdate,
   Profiler,
   ProfilerResource,
+  ProfilerSettings,
   Rng,
   Schedule,
   ShardError,
@@ -14,9 +15,17 @@ 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 { PerfScenario } from "./scenario.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,15 +43,31 @@ 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 = [];
-  profiler = new Profiler();
+  profiler;
   runner;
   initialized = false;
   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;
@@ -51,17 +76,27 @@ class App {
     this.fixedHz = options.fixedHz ?? 60;
     this.maxFixedSteps = options.maxFixedSteps ?? 5;
     this.now = options.now ?? (() => performance.now());
+    const settings = { enabled: true, window: 120, ...options.profiler };
+    this.profiler = new Profiler({ now: this.now, settings });
+    this.world.insertResource(ProfilerSettings, settings);
     this.world.insertResource(ProfilerResource, this.profiler);
     this.world.insertResource(GlobalRng, new Rng(options.seed ?? 0));
+    this.world.insertResource(DevMode, { enabled: options.dev ?? false });
+    this.world.insertResource(PerfScenario, { name: options.perfScenario ?? null });
     const log = new Log();
     log.now = () => this.world.tryResource(Time)?.elapsed ?? 0;
     this.world.insertResource(LogResource, log);
-    this.world.insertResource(AppControlResource, new AppControl());
+    this.profiler.onWarning = (w) => log.log("warn", w.message, { code: w.code, hint: w.hint, path: w.path });
+    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 +108,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`);
@@ -81,11 +117,22 @@ class App {
     }
     return 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() {
+    return this.world.resource(PerfScenario).name;
+  }
+  set perfScenario(name) {
+    this.world.resource(PerfScenario).name = name;
+  }
   /** Methods plugins added, in the order they were added. */
   get methods() {
     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 +148,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 +183,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 +211,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 +251,157 @@ 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);
+    }
+  }
+  /** One frame, timed as the `frame` span (0074). */
+  frame(delta) {
+    const profiler = this.profiler;
+    const token = profiler.beginFrame(this.world.resource(Time).frame);
+    try {
+      this.frameBody(delta);
+    } catch (err) {
+      profiler.cancel(token);
+      throw err;
+    }
+    profiler.endFrame(token);
+  }
+  frameBody(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 +430,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 +471,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 +510,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/budgets.d.ts

@@ -0,0 +1,197 @@
+import { type Profiler, type World } from '@aethervtt/shard-core';
+export type PerfTrack = 'gpu' | 'cpu';
+export declare const PERF_TRACKS: readonly PerfTrack[];
+export interface PerfMachine {
+    /** Part of the CPU model string (`node:os`). */
+    cpu: string;
+    /** Part of the GPU adapter's vendor, architecture, device or description. */
+    gpu: string;
+    backend?: string;
+    display?: [number, number];
+    /** How GPU slices are checked: per-pass timestamps, or ablation where passes overlap. */
+    passTiming?: 'ablation' | 'timestamps';
+    note?: string;
+}
+/** `bench/perf/machines.json`. */
+export interface PerfMachinesFile {
+    machines: Record<string, PerfMachine>;
+}
+export interface PerfBudgetEntry {
+    kind: 'target' | 'unit' | 'rate' | 'guard';
+    per?: string;
+    in?: string;
+    margin?: number;
+    note?: string;
+    /** A number per machine name. */
+    [machine: string]: unknown;
+}
+export interface PerfScenarioEntry {
+    what?: string;
+    resolution?: [number, number];
+    renderScale?: number;
+    fps?: number;
+    /** The frame budget per track, per machine, in ms. */
+    frame: Record<PerfTrack, Record<string, number>>;
+    /** Each track's slices as shares of the frame, `headroom` included; they sum to 1. */
+    slices: Record<PerfTrack, Record<string, number>>;
+    /** Absolute slices in ms per machine, where hardware differs unevenly. */
+    overrides?: Record<string, Partial<Record<PerfTrack, Record<string, number>>>>;
+    note?: string;
+}
+/** `bench/perf/budgets.json`. */
+export interface PerfBudgetsFile {
+    spans: Record<string, PerfBudgetEntry>;
+    scenarios: Record<string, PerfScenarioEntry>;
+}
+export interface PerfBudgetsData {
+    machines: PerfMachinesFile;
+    budgets: PerfBudgetsFile;
+    /** Where they came from (a path or URL), for `perf.budgets`. */
+    source?: string;
+    /** The CPU model, where the host knows it (Node: `os.cpus()[0].model`). Browsers don't. */
+    cpu?: string;
+    /** A machine name that overrides detection (`SHARD_MACHINE`, `?machine=`). */
+    machine?: string;
+}
+/**
+ * Budgets for the running app (0075), handed over by the host: the CLI loads `bench/perf/` from
+ * the repo (or `perf/` in the project), `shard dev` serves them to its page. Absent: no budgets.
+ */
+export declare const PerfBudgets: import("@aethervtt/shard-core").ResourceDef<PerfBudgetsData>;
+export interface PerfAdapterInfo {
+    vendor?: string;
+    architecture?: string;
+    device?: string;
+    description?: string;
+}
+export interface PerfWarning {
+    code: string;
+    message: string;
+    hint?: string;
+}
+export interface MachineDetection {
+    /** The named machine, or null when this one can't be told (or isn't named). */
+    machine: string | null;
+    source: 'detected' | 'override' | 'unknown';
+    /** The machine that matched best, which unknown machines report against. */
+    closest: string | null;
+    warnings: PerfWarning[];
+}
+/** The graphics API an adapter's description names. */
+export declare function backendOf(description?: string): string | undefined;
+/**
+ * Which machine of machines.json this is (the rule `pnpm bench` uses, bench/perf/src/perf.mjs): a
+ * machine matches when both its CPU and GPU strings do. A host that can't tell the CPU model (a
+ * browser) never matches, and gets `perf/unknown-machine`; `override` names the machine instead.
+ */
+export declare function detectPerfMachine(machines: PerfMachinesFile, o?: {
+    cpu?: string;
+    adapter?: PerfAdapterInfo;
+    override?: string;
+}): MachineDetection;
+/** A scenario's frame and slices on one machine, in ms (null without a number). */
+export interface ResolvedPerfScenario {
+    frame: Record<PerfTrack, number | null>;
+    /** Each slice in ms: its share of the frame, or the machine's override. */
+    slices: Record<PerfTrack, Record<string, number | null>>;
+    /** Each slice's share of the frame, as budgets.json states it. */
+    shares: Record<PerfTrack, Record<string, number>>;
+}
+/** A scenario of budgets.json on `machine` (null: shares only). */
+export declare function resolvePerfScenario(scenario: PerfScenarioEntry, machine: string | null): ResolvedPerfScenario;
+/** The detected machine and the app's budgets data, cached until either changes. */
+export interface PerfBudgetState {
+    data: PerfBudgetsData;
+    detection: MachineDetection;
+}
+/**
+ * The app's budgets and which machine it runs on, or undefined without `PerfBudgets`. Cached per
+ * world until the data, the override or the adapter changes; not for per-frame use.
+ */
+export declare function perfBudgetState(world: World, adapter?: PerfAdapterInfo): PerfBudgetState | undefined;
+/**
+ * A scenario slice in ms on the detected machine, or undefined (no budgets, no scenario, no such
+ * slice, or an unknown machine). What 0045's foliage defaults its target to.
+ */
+export declare function scenarioSliceMs(world: World, scenario: string, track: PerfTrack, slice: string, adapter?: PerfAdapterInfo): number | undefined;
+/**
+ * Time a key covers in an average frame, from the profiler's aggregates: the averages of every span
+ * the key covers (`spanCovers`), a span inside another covered span (its `parentOf` chain) counted
+ * once, as `Capture.spanTime` does. A span that doesn't run every frame counts its average run.
+ */
+export declare function coveredMs(profiler: Profiler, key: string): number | undefined;
+export interface SliceMeasure {
+    slice: string;
+    track: PerfTrack;
+    /** Its share of the frame in budgets.json. */
+    share: number;
+    /** Its budget on this machine (ms), or null. */
+    budgetMs: number | null;
+    /** Measured: the covered spans' average, and its share of the measured frame. */
+    measuredMs: number | null;
+    measuredShare: number | null;
+    verdict: 'over' | 'pass' | 'unmeasured';
+}
+/**
+ * Each slice of a scenario against the profiler's aggregates: measured shares of the frame (`frame`
+ * for CPU, `gpu:frame` for GPU) next to the budget's. `headroom` is what the slices leave: the frame
+ * less every slice.
+ */
+export declare function measureSlices(profiler: Profiler, scenario: PerfScenarioEntry, machine: string | null): {
+    frame: Record<PerfTrack, {
+        budgetMs: number | null;
+        measuredMs: number | null;
+    }>;
+    slices: SliceMeasure[];
+};
+export interface BudgetMeasure {
+    key: string;
+    kind: PerfBudgetEntry['kind'];
+    per?: string;
+    in?: string;
+    /** The machine's number (null on an unknown machine). */
+    budget: number | null;
+    /** What a measurement is compared with: a guard's plus its margin. */
+    limit: number | null;
+    /** The span's p95 over the profiler's window, where a span by this name ran. */
+    measured: number | null;
+    verdict: 'over' | 'pass' | 'unmeasured' | 'unbudgeted';
+}
+export interface DescribeBudgetsOptions {
+    /** A scenario to measure; default the app's (`PerfScenario`). */
+    scenario?: string;
+    /** The GPU adapter, for detection. Default: the render plugin's (`PerfProviders.adapter`). */
+    adapter?: PerfAdapterInfo;
+}
+/** A scenario's frame and slices against the profiler's aggregates, over budget first. */
+export interface ScenarioMeasure {
+    name: string;
+    what?: string;
+    resolution?: [number, number];
+    renderScale?: number;
+    fps?: number;
+    frame: Record<PerfTrack, {
+        budgetMs: number | null;
+        measuredMs: number | null;
+    }>;
+    slices: SliceMeasure[];
+}
+/** What `perf.budgets` returns. */
+export interface BudgetsDescription {
+    /** The named machine, or null when this host can't tell (`closest` is then what numbers use). */
+    machine: string | null;
+    source: MachineDetection['source'];
+    closest?: string | null;
+    /** Where the budgets came from. */
+    from?: string;
+    /** The scenario measured (the app's, or the one asked for); null without one. */
+    scenario: ScenarioMeasure | null;
+    warnings: PerfWarning[];
+    budgets: BudgetMeasure[];
+}
+/**
+ * `perf.budgets` (0075): the detected machine, every budget resolved for it, and the latest
+ * measurements against each from the profiler's aggregates (span keys by their p95; the scenario's
+ * slices as shares of the frame), over budget first.
+ */
+export declare function describeBudgets(world: World, options?: DescribeBudgetsOptions): BudgetsDescription;