@aethervtt/shard-runtime 0.1.0 → 0.2.1

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';
@@ -17,6 +17,18 @@ export interface AppOptions {
      * 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: {
@@ -118,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;
@@ -204,7 +222,9 @@ export declare class App {
     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. */

package/dist/app.js

@@ -6,6 +6,7 @@ import {
   PreUpdate,
   Profiler,
   ProfilerResource,
+  ProfilerSettings,
   Rng,
   Schedule,
   ShardError,
@@ -16,6 +17,7 @@ import {
 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 {
   DevMode,
@@ -49,7 +51,7 @@ class App {
   schedules = /* @__PURE__ */ new Map();
   systemNames = /* @__PURE__ */ new Set();
   states = [];
-  profiler = new Profiler();
+  profiler;
   runner;
   initialized = false;
   startupDone = false;
@@ -74,12 +76,17 @@ 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.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);
@@ -110,6 +117,16 @@ 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()];
@@ -369,7 +386,19 @@ class App {
       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);

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;

package/dist/budgets.js

@@ -0,0 +1,256 @@
+import {
+  defineResource,
+  ProfilerResource,
+  ShardError,
+  spanCovers,
+  spanId,
+  spanName,
+  spanStats
+} from "@aethervtt/shard-core";
+import { PerfProviders } from "./perf.js";
+import { PerfScenario } from "./scenario.js";
+const PERF_TRACKS = ["gpu", "cpu"];
+const PerfBudgets = defineResource("runtime/PerfBudgets", {
+  description: "budgets.json and machines.json (0075), as the host loaded them, with the CPU model and a machine override."
+});
+const has = (text, part) => !!part && (text ?? "").toLowerCase().includes(part.toLowerCase());
+function backendOf(description = "") {
+  const d = description.toLowerCase();
+  if (d.includes("metal")) return "metal";
+  if (d.includes("d3d12")) return "d3d12";
+  if (d.includes("d3d11")) return "d3d11";
+  if (d.includes("vulkan")) return "vulkan";
+  if (d.includes("opengl")) return "opengl";
+  return void 0;
+}
+function detectPerfMachine(machines, o = {}) {
+  const names = Object.keys(machines.machines);
+  const gpuText = o.adapter ? [o.adapter.vendor, o.adapter.architecture, o.adapter.device, o.adapter.description].join(" ") : "";
+  const backend = backendOf(o.adapter?.description);
+  let best = names[0] ?? null;
+  let bestScore = -1;
+  let detected = null;
+  for (const name of names) {
+    const m = machines.machines[name];
+    const cpu = has(o.cpu, m.cpu);
+    const gpu = has(gpuText, m.gpu);
+    const score = (cpu ? 2 : 0) + (gpu ? 2 : 0) + (backend && backend === m.backend ? 1 : 0);
+    if (score > bestScore) {
+      bestScore = score;
+      best = name;
+    }
+    if (cpu && gpu && detected === null) detected = name;
+  }
+  const warnings = [];
+  if (o.override) {
+    if (!names.includes(o.override)) {
+      warnings.push({
+        code: "perf/unknown-machine",
+        message: `Machine "${o.override}" isn't in machines.json (${names.join(", ")})`
+      });
+      return { machine: null, source: "unknown", closest: best, warnings };
+    }
+    if (detected && detected !== o.override) {
+      warnings.push({
+        code: "perf/machine-mismatch",
+        message: `The override says "${o.override}", but this looks like "${detected}"`
+      });
+    }
+    return { machine: o.override, source: "override", closest: o.override, warnings };
+  }
+  if (detected) return { machine: detected, source: "detected", closest: detected, warnings };
+  warnings.push({
+    code: "perf/unknown-machine",
+    message: o.cpu ? `No machine in machines.json matches (CPU "${o.cpu}", GPU "${gpuText.trim() || "unknown"}")` : `This host doesn't expose its CPU model, so it can't tell which machine it is (GPU "${gpuText.trim() || "unknown"}")`,
+    hint: "Name it: PerfBudgets.machine (SHARD_MACHINE in Node, ?machine= on playground pages)."
+  });
+  return { machine: null, source: "unknown", closest: best, warnings };
+}
+function resolvePerfScenario(scenario, machine) {
+  const frame = { gpu: null, cpu: null };
+  const slices = { gpu: {}, cpu: {} };
+  const shares = { gpu: {}, cpu: {} };
+  for (const track of PERF_TRACKS) {
+    const ms = machine !== null ? scenario.frame?.[track]?.[machine] : void 0;
+    frame[track] = typeof ms === "number" ? ms : null;
+    const overrides = machine !== null ? scenario.overrides?.[machine]?.[track] : void 0;
+    for (const [slice, share] of Object.entries(scenario.slices?.[track] ?? {})) {
+      shares[track][slice] = share;
+      const absolute = overrides?.[slice];
+      slices[track][slice] = typeof absolute === "number" ? absolute : frame[track] === null ? null : frame[track] * share;
+    }
+  }
+  return { frame, slices, shares };
+}
+const stateCache = /* @__PURE__ */ new WeakMap();
+function perfBudgetState(world, adapter) {
+  const data = world.tryResource(PerfBudgets);
+  if (!data?.budgets || !data.machines) return void 0;
+  adapter ??= world.tryResource(PerfProviders)?.adapter?.(world);
+  const key = `${data.cpu ?? ""}|${data.machine ?? ""}|${adapter ? JSON.stringify(adapter) : ""}`;
+  const cached = stateCache.get(world);
+  if (cached && cached.data === data && cached.key === key) return cached.state;
+  const detection = detectPerfMachine(data.machines, {
+    cpu: data.cpu,
+    adapter,
+    override: data.machine
+  });
+  const state = { data, detection };
+  stateCache.set(world, { key, data, state });
+  return state;
+}
+function scenarioSliceMs(world, scenario, track, slice, adapter) {
+  const state = perfBudgetState(world, adapter);
+  const entry = state?.data.budgets.scenarios[scenario];
+  if (!state || !entry || state.detection.machine === null) return void 0;
+  const ms = resolvePerfScenario(entry, state.detection.machine).slices[track][slice];
+  return ms ?? void 0;
+}
+function coveredMs(profiler, key) {
+  let ms = 0;
+  let any = false;
+  for (const name of profiler.names()) {
+    if (!spanCovers(key, name)) continue;
+    const timing = profiler.timing(name);
+    if (!timing) continue;
+    any = true;
+    let parent = profiler.parentOf(spanId(name));
+    let inside = false;
+    for (let depth = 0; parent >= 0 && depth < 64; depth++) {
+      if (spanCovers(key, spanName(parent))) {
+        inside = true;
+        break;
+      }
+      parent = profiler.parentOf(parent);
+    }
+    if (!inside) ms += timing.avg;
+  }
+  return any ? ms : void 0;
+}
+function measureSlices(profiler, scenario, machine) {
+  const resolved = resolvePerfScenario(scenario, machine);
+  const r3 = (ms) => Math.round(ms * 1e3) / 1e3;
+  const frame = {};
+  const slices = [];
+  for (const track of PERF_TRACKS) {
+    const frameMs = profiler.timing(track === "gpu" ? "gpu:frame" : "frame")?.avg ?? null;
+    frame[track] = {
+      budgetMs: resolved.frame[track],
+      measuredMs: frameMs === null ? null : r3(frameMs)
+    };
+    let used = 0;
+    const keys = Object.keys(resolved.shares[track]);
+    for (const slice of keys) {
+      if (slice === "headroom") continue;
+      const ms = coveredMs(profiler, slice) ?? null;
+      if (ms !== null) used += ms;
+      slices.push(sliceMeasure(slice, track, resolved, ms, frameMs));
+    }
+    if ("headroom" in resolved.shares[track]) {
+      const left = frameMs === null ? null : Math.max(0, frameMs - used);
+      const m = sliceMeasure("headroom", track, resolved, left, frameMs);
+      m.verdict = m.measuredShare === null ? "unmeasured" : m.measuredShare < m.share ? "over" : "pass";
+      slices.push(m);
+    }
+  }
+  return { frame, slices };
+}
+function sliceMeasure(slice, track, resolved, ms, frameMs) {
+  const share = resolved.shares[track][slice];
+  const measuredShare = ms !== null && frameMs !== null && frameMs > 0 ? ms / frameMs : null;
+  const r3 = (v) => Math.round(v * 1e3) / 1e3;
+  return {
+    slice,
+    track,
+    share,
+    budgetMs: resolved.slices[track][slice] ?? null,
+    measuredMs: ms === null ? null : r3(ms),
+    measuredShare: measuredShare === null ? null : r3(measuredShare),
+    verdict: measuredShare === null ? "unmeasured" : measuredShare > share ? "over" : "pass"
+  };
+}
+function describeBudgets(world, options = {}) {
+  const state = perfBudgetState(world, options.adapter);
+  const scenarioName = options.scenario ?? world.tryResource(PerfScenario)?.name ?? null;
+  if (!state) {
+    return {
+      machine: null,
+      source: "unknown",
+      scenario: null,
+      warnings: [
+        {
+          code: "perf/no-budgets",
+          message: "This app has no budgets: the host gave it no budgets.json",
+          hint: "The CLI loads bench/perf/budgets.json from the repo (or perf/budgets.json in the project); shard dev serves it to its page."
+        }
+      ],
+      budgets: []
+    };
+  }
+  const { data, detection } = state;
+  const machine = detection.machine;
+  const on = machine ?? detection.closest;
+  const profiler = world.resource(ProfilerResource);
+  const budgets = [];
+  for (const [key, entry] of Object.entries(data.budgets.spans ?? {})) {
+    const value = on !== null && typeof entry[on] === "number" ? entry[on] : null;
+    const limit = value === null ? null : entry.kind === "guard" ? value * (1 + (entry.margin ?? 0)) : value;
+    const stats = entry.kind === "unit" || entry.kind === "rate" || entry.in ? void 0 : spanStats(profiler, key);
+    const measured = stats ? Math.round(stats.p95 * 1e3) / 1e3 : null;
+    budgets.push({
+      key,
+      kind: entry.kind,
+      ...entry.per ? { per: entry.per } : {},
+      ...entry.in ? { in: entry.in } : {},
+      budget: value,
+      limit,
+      measured,
+      verdict: measured === null ? "unmeasured" : limit === null || machine === null ? "unbudgeted" : measured > limit ? "over" : "pass"
+    });
+  }
+  const rank = { over: 0, pass: 1, unbudgeted: 2, unmeasured: 3 };
+  budgets.sort((a, b) => rank[a.verdict] - rank[b.verdict] || (a.key < b.key ? -1 : 1));
+  let scenario = null;
+  if (scenarioName !== null) {
+    const entry = data.budgets.scenarios[scenarioName];
+    if (!entry) {
+      throw new ShardError("perf/unknown-budget", `No scenario "${scenarioName}" in budgets.json`, {
+        path: scenarioName,
+        hint: `Scenarios: ${Object.keys(data.budgets.scenarios).join(", ")}.`
+      });
+    }
+    const measured = measureSlices(profiler, entry, machine ?? detection.closest);
+    const order = { over: 0, pass: 1, unmeasured: 2 };
+    measured.slices.sort((a, b) => order[a.verdict] - order[b.verdict]);
+    scenario = {
+      name: scenarioName,
+      what: entry.what,
+      resolution: entry.resolution,
+      renderScale: entry.renderScale,
+      fps: entry.fps,
+      frame: measured.frame,
+      slices: measured.slices
+    };
+  }
+  return {
+    machine,
+    source: detection.source,
+    ...machine === null ? { closest: detection.closest } : {},
+    ...data.source ? { from: data.source } : {},
+    scenario,
+    warnings: detection.warnings,
+    budgets
+  };
+}
+export {
+  PERF_TRACKS,
+  PerfBudgets,
+  backendOf,
+  coveredMs,
+  describeBudgets,
+  detectPerfMachine,
+  measureSlices,
+  perfBudgetState,
+  resolvePerfScenario,
+  scenarioSliceMs
+};

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 export { App, type AppDescription, type AppMethod, type AppOptions, type AppScope, type FrameDriver, type FramePresenter, type StartupTimings, } from './app.js';
+export { type BudgetMeasure, type BudgetsDescription, backendOf, coveredMs, type DescribeBudgetsOptions, describeBudgets, detectPerfMachine, type MachineDetection, measureSlices, PERF_TRACKS, type PerfAdapterInfo, type PerfBudgetEntry, type PerfBudgetState, PerfBudgets, type PerfBudgetsData, type PerfBudgetsFile, type PerfMachine, type PerfMachinesFile, type PerfScenarioEntry, type PerfTrack, type PerfWarning, perfBudgetState, type ResolvedPerfScenario, resolvePerfScenario, type ScenarioMeasure, type SliceMeasure, scenarioSliceMs, } from './budgets.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 { capturePerf, captureStamp, describePerf, gpuPassOverlap, isGpuPass, OVERLAP_RATIO, type PerfCaptureOptions, type PerfCaptureResult, type PerfDescribeOptions, type PerfHost, PerfHostResource, PerfProviders, type PerfProvidersData, type PerfSampler, type PerfSamples, perfBreakdown, perfMemory, } from './perf.js';
 export { definePlugin, type Plugin } from './plugin.js';
 export { type AnimationFrameOptions, animationFrameRunner, type HeadlessOptions, headlessRunner, type Runner, } from './runners.js';
+export { PerfScenario, type PerfScenarioData } from './scenario.js';
 export { defineState, inState, OnEnter, OnExit, type StateDef, type StateValue, setState, } from './state.js';
 export { DevMode, DisplayRate, type DisplayRateData, FixedTime, type FixedTimeData, GlobalRng, Time, type TimeData, } from './time.js';

package/dist/index.js

@@ -1,15 +1,40 @@
 import {
   App
 } from "./app.js";
+import {
+  backendOf,
+  coveredMs,
+  describeBudgets,
+  detectPerfMachine,
+  measureSlices,
+  PERF_TRACKS,
+  PerfBudgets,
+  perfBudgetState,
+  resolvePerfScenario,
+  scenarioSliceMs
+} from "./budgets.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 {
+  capturePerf,
+  captureStamp,
+  describePerf,
+  gpuPassOverlap,
+  isGpuPass,
+  OVERLAP_RATIO,
+  PerfHostResource,
+  PerfProviders,
+  perfBreakdown,
+  perfMemory
+} from "./perf.js";
 import { definePlugin } from "./plugin.js";
 import {
   animationFrameRunner,
   headlessRunner
 } from "./runners.js";
+import { PerfScenario } from "./scenario.js";
 import {
   defineState,
   inState,
@@ -38,16 +63,37 @@ export {
   LOADING_DEMAND,
   Log,
   LogResource,
+  OVERLAP_RATIO,
   OnEnter,
   OnExit,
+  PERF_TRACKS,
+  PerfBudgets,
+  PerfHostResource,
+  PerfProviders,
+  PerfScenario,
   RefreshMeter,
   Time,
   animationFrameRunner,
+  backendOf,
+  capturePerf,
+  captureStamp,
+  coveredMs,
   definePlugin,
   defineState,
+  describeBudgets,
+  describePerf,
+  detectPerfMachine,
+  gpuPassOverlap,
   headlessRunner,
   inState,
+  isGpuPass,
+  measureSlices,
+  perfBreakdown,
+  perfBudgetState,
+  perfMemory,
   rateFromIntervals,
+  resolvePerfScenario,
+  scenarioSliceMs,
   setState,
   snapRate
 };

package/dist/perf.d.ts

@@ -0,0 +1,157 @@
+import { type CaptureOptions, type CaptureSummary, type ChromeTrace, type HeapStats, type HotFunction, type Profiler, type SpanStats, type World } from '@aethervtt/shard-core';
+import type { Capture } from '@aethervtt/shard-core/capture';
+/** A sampling profiler the host runs for a capture's window. */
+export interface PerfSampler {
+    stop(): Promise<PerfSamples>;
+}
+export interface PerfSamples {
+    hottest: HotFunction[];
+    /** Stretches of the same top function, for the trace's samples track (browsers). */
+    samples?: {
+        name: string;
+        start: number;
+        ms: number;
+    }[];
+    /** A V8 `.cpuprofile` (Node), written next to the trace. */
+    cpuprofile?: unknown;
+}
+/**
+ * What the host can measure for the profiler. The asset server fills it from the platform
+ * (`HostPerformance` and the file system) when it's configured.
+ */
+export interface PerfHost {
+    /** JS heap: `v8.getHeapStatistics()` in Node, the page's measurements in browsers. */
+    heap?(): HeapStats | undefined;
+    /** Garbage collections as they happen (Node): start on the app's clock, pause, and kind. */
+    onGc?(listener: (start: number, ms: number, kind: string) => void): () => void;
+    /** Starts sampling; undefined where the host can't (`perf/sampling-unavailable`). */
+    startSampler?(): Promise<PerfSampler | undefined>;
+    /** Emits a span to the host's own profiler (Chrome's Performance panel). */
+    measure?(name: string, track: string, start: number, ms: number): void;
+    /** Writes a project file (traces go to `.shard/captures/`). Absent on read-only hosts. */
+    writeText?(path: string, text: string): Promise<void>;
+}
+export declare const PerfHostResource: import("@aethervtt/shard-core").ResourceDef<PerfHost>;
+export interface PerfProvidersData {
+    /** GPU memory by category (the render plugin's ledger). */
+    gpuMemory?: (world: World) => {
+        bytes: number;
+        byCategory: Record<string, number>;
+    };
+    /** More `perf.describe` sections by name (0075 adds budgets). */
+    sections: Map<string, (world: World) => unknown>;
+    /** The GPU adapter's identity (the render plugin), for telling which machine this is (0075). */
+    adapter?: (world: World) => {
+        vendor?: string;
+        architecture?: string;
+        device?: string;
+        description?: string;
+    } | undefined;
+}
+export declare const PerfProviders: import("@aethervtt/shard-core").ResourceDef<PerfProvidersData>;
+export interface PerfDescribeOptions {
+    /** Only spans these keys cover (`spanCovers`: equal, or a prefix ending at "/"). */
+    spans?: readonly string[];
+    /** Most spans per track. Default 30. */
+    top?: number;
+}
+/** GPU memory from the ledger, and the JS heap. */
+export declare function perfMemory(world: World): CaptureSummary['memory'];
+/** Per-pass GPU times summed past this share of `gpu:frame` mean the passes overlap (0075). */
+export declare const OVERLAP_RATIO = 1.1;
+/** Whether a span is a single GPU pass (`gpu:<node>`), not the frame or a group of passes. */
+export declare function isGpuPass(name: string): boolean;
+/**
+ * Whether per-pass GPU times overlap (0075): their averages sum to more than 110% of `gpu:frame`'s.
+ * On tile-based GPUs (Apple, most mobile) passes run concurrently and a pass's timestamps include
+ * waiting for earlier work, so only `gpu:frame` is reliable there, and pass costs come from
+ * ablation (`perf.ablate`). Undefined without GPU timings.
+ */
+export declare function gpuPassOverlap(profiler: Profiler): {
+    passesMs: number;
+    frameMs: number;
+    overlapping: boolean;
+} | undefined;
+/**
+ * `perf.describe` (0074): per-frame, per-schedule, per-system CPU time, GPU passes, worker and
+ * async spans, memory (GPU ledger, JS heap, ECS tables), and the clock.
+ */
+export declare function describePerf(world: World, options?: PerfDescribeOptions): {
+    enabled: boolean;
+    window: number;
+    clock: {
+        resolutionMs: number;
+        isolated: boolean;
+        /** Spans that average under this read mostly the clock's step (`coarse`). */
+        coarseBelowMs: number;
+    };
+    frame: Record<string, unknown> | null;
+    schedules: Record<string, unknown>;
+    commands: Record<string, unknown>;
+    systems: Record<string, unknown>[];
+    gpu: "unavailable" | {
+        frame: Record<string, unknown> | null;
+        quantized: boolean;
+        overlapping: boolean;
+        passesMs?: number | undefined;
+        note?: string | undefined;
+        passes: Record<string, unknown>[];
+    };
+    workers: Record<string, unknown>[];
+    async: Record<string, unknown>[];
+    memory: {
+        gpu: {
+            bytes: number;
+            byCategory: Record<string, number>;
+        };
+        heap?: HeapStats;
+        ecs: {
+            entities: number;
+            archetypes: number;
+            bytes: number;
+        };
+    };
+};
+export interface PerfCaptureOptions extends Omit<CaptureOptions, 'devtools'> {
+    /** Samples with the host's profiler (V8's in Node, JS Self-Profiling in browsers). */
+    sample?: boolean;
+    /** Also shows spans in Chrome's Performance panel (`performance.measure`). Allocates. */
+    devtools?: boolean;
+    /** Writes the trace to `.shard/captures/` when the host can (default true); else it's inline. */
+    write?: boolean;
+    /**
+     * Runs one frame, for hosts without a frame loop (headless, tests). Without it the capture waits
+     * for the loop's frames.
+     */
+    step?: () => void | Promise<void>;
+    /** Builds the Chrome trace (default true). Scenario tests (0075) read the capture instead. */
+    trace?: boolean;
+    /** Returns the capture itself (`result.capture`), for `spanTime` (0075). In-process only. */
+    keep?: boolean;
+}
+export interface PerfCaptureResult {
+    summary: CaptureSummary;
+    /** The capture, with `keep`: per-frame time a budget key covers (`spanTime`), its events. */
+    capture?: Capture;
+    /** Where the trace went, project-relative. */
+    tracePath?: string;
+    /** The trace itself, when it wasn't written. */
+    trace?: ChromeTrace;
+    /** The sampling profile (Node), next to the trace. */
+    profilePath?: string;
+}
+/** A file-name stamp: 2026-10-07T12-30-05-123Z. */
+export declare function captureStamp(date?: Date): string;
+/**
+ * The spans with the highest p95 over the profiler's window, for perf records (0062's version 2):
+ * CPU (main thread, workers, async) and GPU, `frame` and `gpu:frame` aside.
+ */
+export declare function perfBreakdown(world: World, limit?: number): {
+    cpu: SpanStats[];
+    gpu: SpanStats[];
+};
+/**
+ * Captures N frames, or a flight recorder's window around a slow frame (0074). Resolves with the
+ * summary, and the trace's path (or the trace) once it has them.
+ */
+export declare function capturePerf(world: World, options?: PerfCaptureOptions): Promise<PerfCaptureResult>;

package/dist/perf.js

@@ -0,0 +1,245 @@
+import {
+  clockInfo,
+  defineResource,
+  ProfilerResource,
+  ShardError,
+  spanCovers,
+  spanStats,
+  TRACK,
+  trackName
+} from "@aethervtt/shard-core";
+const PerfHostResource = defineResource("runtime/PerfHost", {
+  description: "The host's profiling instruments (0074): heap, GC, sampling, and where traces go."
+});
+const PerfProviders = defineResource("runtime/PerfProviders", {
+  description: "What packages add to perf.describe and capture summaries: GPU memory, sections.",
+  init: () => ({ sections: /* @__PURE__ */ new Map() })
+});
+const r3 = (ms) => Math.round(ms * 1e3) / 1e3;
+function rounded(a) {
+  const out = {
+    span: a.span,
+    last: r3(a.last),
+    avg: r3(a.avg),
+    p50: r3(a.p50),
+    p95: r3(a.p95),
+    max: r3(a.max),
+    samples: a.samples
+  };
+  if (a.coarse) out.coarse = true;
+  return out;
+}
+function heapOf(world) {
+  const fromHost = world.tryResource(PerfHostResource)?.heap?.();
+  if (fromHost) return fromHost;
+  const g = globalThis;
+  const usage = g.process?.memoryUsage?.();
+  if (usage) return { usedBytes: usage.heapUsed, totalBytes: usage.heapTotal, source: "v8" };
+  const memory = g.performance?.memory;
+  if (memory) {
+    return {
+      usedBytes: memory.usedJSHeapSize,
+      totalBytes: memory.totalJSHeapSize,
+      limitBytes: memory.jsHeapSizeLimit,
+      source: "performance.memory"
+    };
+  }
+  return void 0;
+}
+function perfMemory(world) {
+  const gpu = world.tryResource(PerfProviders)?.gpuMemory?.(world) ?? { bytes: 0, byCategory: {} };
+  const heap = heapOf(world);
+  return heap ? { gpu, heap } : { gpu };
+}
+const OVERLAP_RATIO = 1.1;
+function isGpuPass(name) {
+  return name.startsWith("gpu:") && name !== "gpu:frame" && !name.startsWith("gpu:span/");
+}
+function gpuPassOverlap(profiler) {
+  const frame = profiler.timing("gpu:frame");
+  if (!frame || frame.avg <= 0) return void 0;
+  let passes = 0;
+  for (const name of profiler.names()) {
+    if (isGpuPass(name)) passes += profiler.timing(name).avg;
+  }
+  return {
+    passesMs: r3(passes),
+    frameMs: r3(frame.avg),
+    overlapping: passes > frame.avg * OVERLAP_RATIO
+  };
+}
+function describePerf(world, options = {}) {
+  const profiler = world.resource(ProfilerResource);
+  const keys = options.spans;
+  const top = options.top ?? 30;
+  const wanted = (name) => !keys || keys.some((k) => spanCovers(k, name));
+  const byTrack = { main: [], gpu: [], worker: [], async: [] };
+  const schedules = {};
+  const commands = {};
+  for (const name of profiler.names()) {
+    if (!wanted(name)) continue;
+    const stats = spanStats(profiler, name);
+    if (name.startsWith("schedule/")) schedules[name] = rounded(stats);
+    else if (name.startsWith("commands/")) commands[name] = rounded(stats);
+    else if (name !== "frame" && name !== "gpu:frame") byTrack[stats.track]?.push(stats);
+  }
+  const list = (track) => (byTrack[track] ?? []).sort((a, b) => b.avg - a.avg || (a.span < b.span ? -1 : 1)).slice(0, top).map(rounded);
+  const frame = spanStats(profiler, "frame");
+  const gpuFrame = spanStats(profiler, "gpu:frame");
+  const overlap = gpuPassOverlap(profiler);
+  const clock = clockInfo();
+  const ecs = world.stats();
+  let ecsBytes = 0;
+  for (const t of ecs.tables) ecsBytes += t.bytes;
+  const providers = world.tryResource(PerfProviders);
+  const sections = {};
+  for (const [name, fn] of providers?.sections ?? []) sections[name] = fn(world);
+  return {
+    enabled: profiler.enabled,
+    window: profiler.window,
+    clock: {
+      resolutionMs: clock.resolutionMs,
+      isolated: clock.isolated,
+      /** Spans that average under this read mostly the clock's step (`coarse`). */
+      coarseBelowMs: r3(clock.resolutionMs * 4)
+    },
+    frame: frame ? rounded(frame) : null,
+    schedules,
+    commands,
+    systems: list("main"),
+    gpu: profiler.gpu.status === "unavailable" ? "unavailable" : {
+      frame: gpuFrame ? rounded(gpuFrame) : null,
+      quantized: profiler.gpu.quantized,
+      // 0075: pass times that add up to more than the frame overlap, and don't rank passes.
+      overlapping: overlap?.overlapping ?? false,
+      ...overlap?.overlapping ? {
+        passesMs: overlap.passesMs,
+        note: "Pass times overlap (a tile-based GPU): each includes waiting for earlier work, so they sum past gpu:frame and do not rank passes. perf.ablate measures what each pass costs."
+      } : {},
+      passes: list("gpu")
+    },
+    workers: list("worker"),
+    async: list("async"),
+    memory: {
+      ...perfMemory(world),
+      ecs: { entities: ecs.entities, archetypes: ecs.archetypes, bytes: ecsBytes }
+    },
+    ...sections
+  };
+}
+function captureStamp(date = /* @__PURE__ */ new Date()) {
+  return date.toISOString().replace(/[:.]/g, "-");
+}
+function perfBreakdown(world, limit = 10) {
+  const profiler = world.resource(ProfilerResource);
+  const cpu = [];
+  const gpu = [];
+  for (const name of profiler.names()) {
+    if (name === "frame" || name === "gpu:frame") continue;
+    const a = spanStats(profiler, name);
+    const stats = {
+      span: name,
+      track: a.track,
+      calls: a.samples,
+      total: r3(a.avg * a.samples),
+      p50: r3(a.p50),
+      p95: r3(a.p95),
+      max: r3(a.max)
+    };
+    (a.track === "gpu" ? gpu : cpu).push(stats);
+  }
+  const order = (x, y) => y.p95 - x.p95 || (x.span < y.span ? -1 : 1);
+  return { cpu: cpu.sort(order).slice(0, limit), gpu: gpu.sort(order).slice(0, limit) };
+}
+const gcNames = /* @__PURE__ */ new Map();
+async function capturePerf(world, options = {}) {
+  const profiler = world.resource(ProfilerResource);
+  if (profiler.sink) {
+    throw new ShardError("perf/capture-running", "A capture is already running on this app", {
+      hint: "Wait for it to finish, then capture again."
+    });
+  }
+  const { startCapture } = await import("@aethervtt/shard-core/capture");
+  const host = world.tryResource(PerfHostResource);
+  const warnings = [];
+  let sampler;
+  if (options.sample) {
+    sampler = await host?.startSampler?.();
+    if (!sampler) {
+      warnings.push(
+        new ShardError("perf/sampling-unavailable", "This host can't sample JavaScript", {
+          hint: "Node samples with node:inspector; browsers need the JS Self-Profiling API and a Document-Policy: js-profiling header (shard dev and the playground send it)."
+        }).toJSON()
+      );
+    }
+  }
+  const measure = host?.measure;
+  const { step, sample: _, devtools, write, trace: wantTrace, keep, ...captureOptions } = options;
+  const recorder = startCapture(profiler, {
+    ...captureOptions,
+    devtools: devtools && measure ? (name, track, start, ms) => measure(name, trackName(track), start, ms) : void 0
+  });
+  const offGc = host?.onGc?.((start, ms, kind) => {
+    let name = gcNames.get(kind);
+    if (!name) {
+      name = `gc/${kind}`;
+      gcNames.set(kind, name);
+    }
+    profiler.event(name, TRACK.gc, start, ms);
+  });
+  let capture;
+  try {
+    if (step) {
+      while (recorder.running) await step();
+    } else {
+      const limitMs = ((options.timeout ?? 60) + (options.frames ?? 300) / 10) * 1e3;
+      const timer = setTimeout(() => recorder.stop(), limitMs);
+      try {
+        await recorder.done;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    capture = await recorder.done;
+  } catch (err) {
+    recorder.stop();
+    throw err;
+  } finally {
+    offGc?.();
+  }
+  const sampled = sampler ? await sampler.stop() : void 0;
+  const summary = capture.summary({
+    clock: { ...clockInfo(), gpuQuantized: profiler.gpu.quantized },
+    memory: perfMemory(world),
+    hottest: sampled?.hottest,
+    warnings
+  });
+  const result = { summary };
+  if (keep) result.capture = capture;
+  if (wantTrace === false) return result;
+  const trace = capture.trace({ samples: sampled?.samples });
+  if (write !== false && host?.writeText) {
+    const stamp = captureStamp();
+    result.tracePath = `.shard/captures/${stamp}.trace.json`;
+    await host.writeText(result.tracePath, JSON.stringify(trace));
+    if (sampled?.cpuprofile) {
+      result.profilePath = `.shard/captures/${stamp}.cpuprofile`;
+      await host.writeText(result.profilePath, JSON.stringify(sampled.cpuprofile));
+    }
+  } else {
+    result.trace = trace;
+  }
+  return result;
+}
+export {
+  OVERLAP_RATIO,
+  PerfHostResource,
+  PerfProviders,
+  capturePerf,
+  captureStamp,
+  describePerf,
+  gpuPassOverlap,
+  isGpuPass,
+  perfBreakdown,
+  perfMemory
+};

package/dist/scenario.d.ts

@@ -0,0 +1,9 @@
+export interface PerfScenarioData {
+    /** A scenario of budgets.json, or null: no scenario, so nothing adapts to a slice. */
+    name: string | null;
+}
+/**
+ * The scenario the app declares (`App.perfScenario`): features that adapt (0045's foliage) take
+ * their slice of its frame as their target, and the `perf` overlay shows its slices.
+ */
+export declare const PerfScenario: import("@aethervtt/shard-core").ResourceDef<PerfScenarioData>;

package/dist/scenario.js

@@ -0,0 +1,9 @@
+import { defineResource } from "@aethervtt/shard-core";
+const PerfScenario = defineResource("runtime/PerfScenario", {
+  description: "The budget scenario the app runs as (0075): features adapt to its slices, and the perf overlay shows them. null: none.",
+  hostWritable: true,
+  init: () => ({ name: null })
+});
+export {
+  PerfScenario
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-runtime",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@aethervtt/shard-core": "0.1.0"
+    "@aethervtt/shard-core": "0.2.1"
   },
   "repository": {
     "type": "git",
@@ -32,6 +32,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "8e14c9896f82a3554b156f1ffdd68f2cc3e7d78a"
+    "buildSha": "772eb0d2b8a5fc499105708f4ae92c58788cc9ea"
   }
 }