@aethervtt/shard-runtime 0.0.1 → 0.2.0

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/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,12 @@
-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 { 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 { 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,12 +1,40 @@
-import { App } from "./app.js";
+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,
@@ -15,6 +43,7 @@ import {
   setState
 } from "./state.js";
 import {
+  DevMode,
   DisplayRate,
   FixedTime,
   GlobalRng,
@@ -25,21 +54,46 @@ export {
   AppControl,
   AppControlResource,
   COMMON_RATES,
+  DevMode,
   DisplayRate,
   FixedTime,
+  FrameDemand,
+  FrameDemandState,
   GlobalRng,
+  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>;