@zkmake/three-meter 0.11.6 → 0.13.0

package/README.md

@@ -125,6 +125,7 @@ Canvas is its own React root. To run two canvases on one page, pass the same `st
 | `injectStyles`     | `true`             | Append the stylesheet once per document.                                                      |
 | `refreshHz`        | `10`               | Repaint rate.                                                                                 |
 | `budgets`          | timing defaults    | Limits past which a value turns amber. See [Budgets](#budgets).                               |
+| `quality`          | none               | Adaptive quality to show. See [Adaptive quality](#adaptive-quality).                          |
 | `label`            | `"Performance"`    | Accessible name of the panel.                                                                 |
 
 `PerformanceMonitor` and `PerfSampler` take `trackGPU` (default true), `gpuQueryPoolSize` (default 5),
@@ -182,6 +183,41 @@ hud.setBudgets({ gpu: null }); // null drops a default; false drops them all
 
 `PerfHud` takes the same `budgets` prop and applies changes live.
 
+An app that keeps its budgets in one file with [three-audit](../three-audit)'s `defineBudgets`
+passes that file as is. The HUD applies its `frame`: `fps` as `targetFps`, `calls` and
+`triangles`. The same file holds the per-part budgets its tests and the `three-audit` CLI check.
+
+```ts
+import budgets from "./budgets.ts"; // defineBudgets({ frame: { fps: 60, calls: 150, … }, parts })
+
+mountPerfHud(monitor, { budgets });
+```
+
+three-meter reads the file's shape (`AppBudgets`) and doesn't depend on three-audit.
+
+## Adaptive quality
+
+A game that adapts its render quality at runtime with [three-quality](../three-quality) can show
+what it's doing: pass the controller, or in React its store, as `quality`. The card gets one line
+under the grid, `dpr 1.25 · adapting · shadows off`, and the full view a **Quality** row; hover
+either for the level and the last window's p90 frame against the budget.
+
+```ts
+const quality = adaptQuality(renderer); // @zkmake/three-quality
+
+mountPerfHud(monitor, { quality });
+```
+
+```tsx
+import { qualityStore } from "@zkmake/three-quality/react";
+
+<PerfHud quality={qualityStore} />;
+```
+
+three-meter reads the shape (`QualitySource`: a `state` with `dpr`, `phase`, `level`, `levels`
+and `tiers`), so neither package depends on the other: the game ships three-quality and loads
+three-meter behind `?debug`. `hud.setQuality(source)` swaps it later.
+
 ## Top costs
 
 The HUD tells you there are 400 draw calls; **top costs** tells you which objects they come from.

package/dist/{mount-perf-hud-C7CzkVqM.d.ts → mount-perf-hud-C0yuW5JI.d.ts}

@@ -11,12 +11,28 @@ import { p as TimingMetric, t as PerformanceMonitor } from "./performance-monito
  * used, then 60 until one is detected.
  * Counts have no default, since what's reasonable depends on the scene. Pass
  * `null` for a key to drop its default, or `false` for no budgets at all.
+ *
+ * An app's budgets file (`AppBudgets`, from three-audit's `defineBudgets`) works too: its
+ * `frame` sets `targetFps`, `calls` and `triangles`.
  */
 type BudgetKey = "calls" | "cpu" | "fps" | "geometries" | "gpu" | "headroom" | "hitches" | "lines" | "low" | "p99" | "passes" | "points" | "refresh" | "shaders" | "textures" | "triangles";
 type Budgets = Partial<Record<BudgetKey, number | null>> & {
   /** The frame rate the defaults are derived from. Default: the detected refresh rate, else 60. */
   targetFps?: number;
 };
+/**
+ * An app's budgets file, as `@zkmake/three-audit`'s `defineBudgets` returns it. Structural, so
+ * three-meter needs no dependency: only `frame` is read, its `fps` as `targetFps`.
+ */
+type AppBudgets = {
+  readonly frame: {
+    readonly fps?: number | undefined;
+    readonly calls?: number | undefined;
+    readonly triangles?: number | undefined;
+  };
+};
+/** What the HUD's `budgets` option takes: its own budgets, or an app's budgets file. */
+type BudgetsInput = Budgets | AppBudgets;
 type ResolvedBudgets = {
   /** Frame budget in ms, `1000 / targetFps`. */
   frameMs: number;
@@ -25,7 +41,7 @@ type ResolvedBudgets = {
   limits: Partial<Record<BudgetKey, number>>;
 };
 /** `detectedHz` is the monitor's refresh reading; an explicit `targetFps` wins over it. */
-declare const resolveBudgets: (budgets: Budgets | false | undefined, detectedHz?: number | null) => ResolvedBudgets;
+declare const resolveBudgets: (input: BudgetsInput | false | undefined, detectedHz?: number | null) => ResolvedBudgets;
 declare const EDGES: readonly ["left", "right", "top", "bottom"];
 type ScreenEdge = (typeof EDGES)[number];
 type Placement = {
@@ -144,6 +160,31 @@ declare class HudSettings {
   private load;
   private persistAndNotify;
 }
+/**
+ * Adaptive quality, as the HUD shows it: one line, `dpr 1.25 · adapting · shadows off`. The source
+ * is `@zkmake/three-quality`'s controller (`adaptQuality`) or its React store (`qualityStore`),
+ * read by shape like `AppBudgets`, so three-meter needs no dependency and the runtime package none
+ * on this dev tool. Anything with a `state` of this shape works.
+ */
+type QualityReading = {
+  /** The pixel ratio applied. */
+  readonly dpr: number;
+  /** What the controller is doing: `warming`, `adapting`, `steady`, `cpu-bound`, `pinned`. */
+  readonly phase: string;
+  /** 0 is the best rung. */
+  readonly level: number;
+  readonly levels: number;
+  /** The app's tiers by name, `true` while on. */
+  readonly tiers?: Readonly<Record<string, boolean>>;
+  /** The last window's 90th-percentile frame, ms. */
+  readonly p90Ms?: number | null;
+  readonly targetFps?: number;
+};
+/** What the HUD's `quality` option takes. `state` is read on each repaint; `null` shows `—`. */
+type QualitySource = {
+  readonly state: QualityReading | null;
+};
+declare const formatQuality: (reading: QualityReading | null) => string;
 type PerformanceViewMode = "full" | "compact";
 type PerformanceViewOptions = {
   monitor: PerformanceMonitor;
@@ -153,9 +194,15 @@ type PerformanceViewOptions = {
   refreshHz?: number;
   /**
    * Limits past which a value turns amber. Timing budgets default from
-   * `targetFps` (60); `false` turns them all off. See {@link Budgets}.
+   * `targetFps` (60); `false` turns them all off. See {@link Budgets}; an app's
+   * budgets file (`AppBudgets`) applies its `frame`.
+   */
+  budgets?: BudgetsInput | false;
+  /**
+   * Adaptive quality to show, one line in the card and a row in the list: three-quality's
+   * controller or React store, read by shape. See {@link QualitySource}.
    */
-  budgets?: Budgets | false;
+  quality?: QualitySource;
   /** Share one between views to keep them in sync; a fresh instance otherwise. */
   settings?: HudSettings;
   /**
@@ -198,6 +245,12 @@ declare class PerformanceView {
   private budgets;
   private budgetsInput;
   private detectedHz;
+  private quality;
+  private lastQualityText;
+  private hudQualityEl;
+  private hudQualityValueEl;
+  private qualityRowEl;
+  private qualityValueEl;
   private readonly hider;
   private readonly hiddenRows;
   private rafId;
@@ -218,7 +271,9 @@ declare class PerformanceView {
   setMode(mode: PerformanceViewMode): void;
   getMode(): PerformanceViewMode;
   /** Replace the budgets; `false` turns them all off. Applies on the next paint. */
-  setBudgets(budgets: Budgets | false | undefined): void;
+  setBudgets(budgets: BudgetsInput | false | undefined): void;
+  /** Show another quality source, or none. Applies on the next paint. */
+  setQuality(quality: QualitySource | undefined): void;
   dispose(): void;
   private frame;
   private render;
@@ -235,6 +290,9 @@ declare class PerformanceView {
   private costsNote;
   /** The monitor caches the environment once its backend settles; until then this re-reads. */
   private renderFooter;
+  /** One string for both the card's line and the list's row; the DOM is touched only on change. */
+  private renderQuality;
+  private applyQuality;
   /** Budgets follow the detected refresh rate unless `targetFps` was given. */
   private followRefresh;
   private renderHud;
@@ -279,11 +337,17 @@ type MountPerfHudOptions = {
   /** Repaint rate. Default 10. */
   refreshHz?: number;
   /**
-   * Limits past which a value turns amber, e.g. `{ calls: 500, targetFps: 120 }`.
+   * Limits past which a value turns amber, e.g. `{ calls: 500, targetFps: 120 }`,
+   * or the app's budgets file (three-audit's `defineBudgets`), whose `frame` applies.
    * Timing budgets default from `targetFps` (60); `false` turns them all off.
    * Change later with the handle's `setBudgets`.
    */
-  budgets?: Budgets | false;
+  budgets?: BudgetsInput | false;
+  /**
+   * Adaptive quality to show: `@zkmake/three-quality`'s controller (`adaptQuality(…)`) or its React
+   * store (`qualityStore`), read by shape, no dependency. Change later with `setQuality`.
+   */
+  quality?: QualitySource;
   /** Accessible name of the panel. Default `Performance`. */
   label?: string;
 };
@@ -304,9 +368,11 @@ type PerfHudHandle = {
   /** Sets the consumer layer; a pick made in the panel still wins until `settings.setTheme(null)`. */
   setTheme: (mode: ThemeMode) => void;
   /** Replace the budgets; `false` turns them all off. */
-  setBudgets: (budgets: Budgets | false | undefined) => void;
+  setBudgets: (budgets: BudgetsInput | false | undefined) => void;
+  /** Show another quality source, or none. */
+  setQuality: (quality: QualitySource | undefined) => void;
   dispose: () => void;
 };
 declare const mountPerfHud: (monitor: PerformanceMonitor, options?: MountPerfHudOptions) => PerfHudHandle;
-export { dockPanel as C, resolveBudgets as D, ResolvedBudgets as E, ScreenEdge as S, Budgets as T, DefaultPlacement as _, PerformanceViewMode as a, DockPanelOptions as b, HudDefaults as c, HudSettingsOptions as d, HudTheme as f, isThemeMode as g, ThemeMode as h, PerformanceView as i, HudSelection as l, THEME_MODES as m, PerfHudHandle as n, PerformanceViewOptions as o, ResolvedTheme as p, mountPerfHud as r, DEFAULT_STORAGE_KEY as s, MountPerfHudOptions as t, HudSettings as u, DockAlign as v, BudgetKey as w, Placement as x, DockHandle as y };
-//# sourceMappingURL=mount-perf-hud-C7CzkVqM.d.ts.map
+export { BudgetsInput as A, DockPanelOptions as C, AppBudgets as D, dockPanel as E, resolveBudgets as M, BudgetKey as O, DockHandle as S, ScreenEdge as T, THEME_MODES as _, PerformanceViewMode as a, DefaultPlacement as b, QualitySource as c, HudDefaults as d, HudSelection as f, ResolvedTheme as g, HudTheme as h, PerformanceView as i, ResolvedBudgets as j, Budgets as k, formatQuality as l, HudSettingsOptions as m, PerfHudHandle as n, PerformanceViewOptions as o, HudSettings as p, mountPerfHud as r, QualityReading as s, MountPerfHudOptions as t, DEFAULT_STORAGE_KEY as u, ThemeMode as v, Placement as w, DockAlign as x, isThemeMode as y };
+//# sourceMappingURL=mount-perf-hud-C0yuW5JI.d.ts.map

package/dist/{mount-perf-hud-DezuAiPb.js → mount-perf-hud-DefBWWKu.js}

@@ -5,8 +5,18 @@ const FLOORS = /* @__PURE__ */ new Set([
 	"headroom",
 	"low"
 ]);
+const isAppBudgets = (budgets) => "frame" in budgets;
+/** An app's frame budget as the HUD's: only the limits it sets, so the rest keep their defaults. */
+const fromApp = ({ frame }) => {
+	const budgets = {};
+	if (frame.fps !== void 0) budgets.targetFps = frame.fps;
+	if (frame.calls !== void 0) budgets.calls = frame.calls;
+	if (frame.triangles !== void 0) budgets.triangles = frame.triangles;
+	return budgets;
+};
 /** `detectedHz` is the monitor's refresh reading; an explicit `targetFps` wins over it. */
-const resolveBudgets = (budgets, detectedHz = null) => {
+const resolveBudgets = (input, detectedHz = null) => {
+	const budgets = input && isAppBudgets(input) ? fromApp(input) : input;
 	const targetFps = budgets && budgets.targetFps || detectedHz || DEFAULT_TARGET_FPS;
 	const frameMs = 1e3 / targetFps;
 	if (budgets === false) return {
@@ -959,6 +969,34 @@ const PERF_HUD_STYLES = `
   text-align: right;
 }
 
+/* Adaptive quality (three-quality), under the grid: one muted line, the reading in the foreground. */
+.perf-monitor__hud-quality {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+  color: var(--perf-muted);
+  font-size: 10px;
+}
+
+.perf-monitor__hud-quality[hidden],
+.perf-monitor__row[hidden] {
+  display: none;
+}
+
+.perf-monitor__hud-quality .perf-monitor__icon {
+  width: 11px;
+  height: 11px;
+}
+
+.perf-monitor__hud-quality-value {
+  overflow: hidden;
+  color: var(--perf-fg);
+  font-variant-numeric: tabular-nums lining-nums;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .perf-monitor__footer {
   display: flex;
   align-items: flex-start;
@@ -1390,7 +1428,7 @@ const mountDevPanel = (options) => {
 };
 // package.json
 var name = "@zkmake/three-meter";
-var version = "0.11.6";
+var version = "0.13.0";
 // src/ui/clipboard.ts
 /**
 * Copy text from a click handler. The async Clipboard API needs a secure
@@ -1501,6 +1539,23 @@ const METRIC_HELP = {
 	textures: "Textures held in GPU memory. Should level off; a steady climb is a leak, so dispose() what you remove.",
 	triangles: "Triangles drawn this frame. Mostly GPU cost: use lower-poly models or level of detail to cut it."
 };
+// src/ui/quality.ts
+const ratio = (dpr) => Number(dpr.toFixed(2)).toString();
+const tiersOff = (reading) => Object.entries(reading.tiers ?? {}).filter(([, on]) => !on).map(([name]) => name);
+const formatQuality = (reading) => {
+	if (!reading) return "—";
+	const off = tiersOff(reading);
+	return [
+		`dpr ${ratio(reading.dpr)}`,
+		reading.phase,
+		off.length ? `${off.join(", ")} off` : ""
+	].filter(Boolean).join(" · ");
+};
+const qualityTitle = (reading) => {
+	if (!reading) return "Adaptive quality: no controller mounted.";
+	const frame = typeof reading.p90Ms === "number" ? `; p90 frame ${reading.p90Ms.toFixed(1)} ms${reading.targetFps ? ` against ${(1e3 / reading.targetFps).toFixed(1)} ms` : ""}` : "";
+	return `Adaptive quality: level ${reading.level + 1} of ${reading.levels} (1 is the best)${frame}.`;
+};
 // src/ui/report.ts
 /**
 * A plain-text snapshot of the monitor for bug reports: versions, backend and
@@ -1898,6 +1953,12 @@ var PerformanceView = class {
 	budgets;
 	budgetsInput;
 	detectedHz = null;
+	quality;
+	lastQualityText = "";
+	hudQualityEl;
+	hudQualityValueEl;
+	qualityRowEl;
+	qualityValueEl;
 	hider = new Hider();
 	hiddenRows = /* @__PURE__ */ new Map();
 	rafId = null;
@@ -1922,11 +1983,13 @@ var PerformanceView = class {
 		this.minIntervalMs = 1e3 / (options.refreshHz ?? 10);
 		this.budgetsInput = options.budgets;
 		this.budgets = resolveBudgets(options.budgets);
+		this.quality = options.quality;
 		this.element = document.createElement("div");
 		this.element.className = "perf-monitor";
 		this.applyModeClass();
 		this.resizeObserver = new ResizeObserver(() => this.resizeCanvases());
 		this.build();
+		this.applyQuality();
 		this.applyInfoClass();
 		this.rebuildHud();
 		this.onThemeChanged();
@@ -1957,6 +2020,11 @@ var PerformanceView = class {
 		this.budgets = resolveBudgets(budgets, this.detectedHz);
 		this.applyBudgetTitles();
 	}
+	/** Show another quality source, or none. Applies on the next paint. */
+	setQuality(quality) {
+		this.quality = quality;
+		this.applyQuality();
+	}
 	dispose() {
 		this.stop();
 		this.showAllHidden();
@@ -1976,6 +2044,7 @@ var PerformanceView = class {
 		const sample = this.monitor.getSample();
 		const stats = this.monitor.getFrameStats();
 		this.followRefresh(stats.refreshHz);
+		this.renderQuality();
 		if (this.mode === "compact") {
 			this.renderHud(sample, stats);
 			if (this.settings.info) this.renderFooter();
@@ -2110,6 +2179,25 @@ var PerformanceView = class {
 		this.footerGpuEl.title = gpu;
 		this.footerHardwareEl.hidden = backend === "" && gpu === "";
 	}
+	/** One string for both the card's line and the list's row; the DOM is touched only on change. */
+	renderQuality() {
+		if (!this.quality) return;
+		const reading = this.quality.state;
+		const text = formatQuality(reading);
+		const title = qualityTitle(reading);
+		if (`${text}\n${title}` === this.lastQualityText) return;
+		this.lastQualityText = `${text}\n${title}`;
+		this.hudQualityValueEl.textContent = text;
+		this.qualityValueEl.textContent = text;
+		this.hudQualityEl.title = title;
+		this.qualityRowEl.title = title;
+	}
+	applyQuality() {
+		this.hudQualityEl.hidden = !this.quality;
+		this.qualityRowEl.hidden = !this.quality;
+		this.lastQualityText = "";
+		this.renderQuality();
+	}
 	/** Budgets follow the detected refresh rate unless `targetFps` was given. */
 	followRefresh(hz) {
 		if (hz === this.detectedHz) return;
@@ -2161,7 +2249,12 @@ var PerformanceView = class {
 		this.hudGraphsEl.className = "perf-monitor__hud-graphs";
 		this.hudGridEl = document.createElement("div");
 		this.hudGridEl.className = "perf-monitor__hud-grid";
-		hud.append(this.hudGraphsEl, this.hudGridEl);
+		this.hudQualityEl = document.createElement("div");
+		this.hudQualityEl.className = "perf-monitor__hud-quality";
+		this.hudQualityValueEl = document.createElement("span");
+		this.hudQualityValueEl.className = "perf-monitor__hud-quality-value";
+		this.hudQualityEl.append(createIcon("sliders", "perf-monitor__icon"), this.hudQualityValueEl);
+		hud.append(this.hudGraphsEl, this.hudGridEl, this.hudQualityEl);
 		const options = document.createElement("div");
 		options.className = "perf-monitor__section perf-monitor__options";
 		const themeRow = document.createElement("div");
@@ -2236,6 +2329,15 @@ var PerformanceView = class {
 		}
 		const stats = document.createElement("div");
 		stats.className = "perf-monitor__section";
+		this.qualityRowEl = document.createElement("div");
+		this.qualityRowEl.className = "perf-monitor__row perf-monitor__row--static";
+		const qualityLabel = document.createElement("span");
+		qualityLabel.className = "perf-monitor__label";
+		qualityLabel.textContent = "Quality";
+		this.qualityValueEl = document.createElement("span");
+		this.qualityValueEl.className = "perf-monitor__value";
+		this.qualityValueEl.textContent = "—";
+		this.qualityRowEl.append(createIcon("sliders", "perf-monitor__icon"), qualityLabel, this.qualityValueEl);
 		for (const config of NUMBERS) {
 			const rowEl = document.createElement("label");
 			rowEl.className = "perf-monitor__row";
@@ -2256,6 +2358,7 @@ var PerformanceView = class {
 			rowEl.append(createIcon(config.icon, "perf-monitor__icon"), label, value, checkbox, hint);
 			stats.append(rowEl);
 		}
+		stats.append(this.qualityRowEl);
 		const footer = document.createElement("div");
 		footer.className = "perf-monitor__footer";
 		this.infoCheckbox = this.buildCheckbox(this.settings.info, "Show version and environment in HUD", (on) => this.settings.setInfo(on));
@@ -2492,6 +2595,7 @@ const mountPerfHud = (monitor, options = {}) => {
 		budgets: options.budgets,
 		mode: options.mode ?? "compact",
 		monitor,
+		quality: options.quality,
 		refreshHz: options.refreshHz,
 		settings,
 		theme
@@ -2534,6 +2638,7 @@ const mountPerfHud = (monitor, options = {}) => {
 		getMode: () => view.getMode(),
 		setBudgets: (budgets) => view.setBudgets(budgets),
 		setMode,
+		setQuality: (quality) => view.setQuality(quality),
 		getTheme: () => theme.mode,
 		setTheme: (mode) => theme.setMode(mode),
 		settings,
@@ -2541,6 +2646,6 @@ const mountPerfHud = (monitor, options = {}) => {
 		view
 	};
 };
-export { PERF_HUD_STYLES as a, DEFAULT_STORAGE_KEY as c, THEME_MODES as d, isThemeMode as f, mountDevPanel as i, HudSettings as l, PerformanceView as n, injectStyles as o, resolveBudgets as p, formatReport as r, dockPanel as s, mountPerfHud as t, HudTheme as u };
+export { mountDevPanel as a, dockPanel as c, HudTheme as d, THEME_MODES as f, formatQuality as i, DEFAULT_STORAGE_KEY as l, resolveBudgets as m, PerformanceView as n, PERF_HUD_STYLES as o, isThemeMode as p, formatReport as r, injectStyles as s, mountPerfHud as t, HudSettings as u };
 
-//# sourceMappingURL=mount-perf-hud-DezuAiPb.js.map
+//# sourceMappingURL=mount-perf-hud-DefBWWKu.js.map