@zkmake/three-meter 0.12.0 → 0.13.1

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),
@@ -194,6 +195,29 @@ 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.
@@ -337,6 +361,25 @@ Styles inject at runtime by default. To link them instead, pass `injectStyles: f
 
 The package never reads `NODE_ENV` or `import.meta.env`. Whether the HUD exists in production is
 your call. Gate the import in the app with a `?debug=` query, a build flag or a dynamic `import()`.
+[three-devtools](../three-devtools) is that gate, done once.
+
+A dynamic `import()` only keeps the HUD out of the first load if the bundler leaves it in its own
+chunk. A catch-all chunk group that sends every `node_modules` module to one `vendor` chunk (Vite's
+`codeSplitting.groups`, `manualChunks`) pulls the meter into a chunk `index.html` preloads, so every
+player downloads it. Leave `@zkmake` out of that group:
+
+```ts
+// vite.config.ts, build.rolldownOptions.output.codeSplitting.groups
+{
+  name: "vendor",
+  // Everything in node_modules but @zkmake, whose dev tools load behind ?debug.
+  test: /^(?!.*[\\/]node_modules[\\/]@zkmake[\\/]).*[\\/]node_modules[\\/]/,
+  priority: 10,
+},
+```
+
+Then check a production build: no chunk that `index.html` loads or preloads contains
+`PerformanceMonitor`.
 
 ## Contract
 

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

@@ -160,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;
@@ -173,6 +198,11 @@ type PerformanceViewOptions = {
    * 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}.
+   */
+  quality?: QualitySource;
   /** Share one between views to keep them in sync; a fresh instance otherwise. */
   settings?: HudSettings;
   /**
@@ -215,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;
@@ -236,6 +272,8 @@ declare class PerformanceView {
   getMode(): PerformanceViewMode;
   /** Replace the budgets; `false` turns them all off. Applies on the next paint. */
   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;
@@ -252,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;
@@ -302,6 +343,11 @@ type MountPerfHudOptions = {
    * Change later with the handle's `setBudgets`.
    */
   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;
 };
@@ -323,8 +369,10 @@ type PerfHudHandle = {
   setTheme: (mode: ThemeMode) => void;
   /** Replace the budgets; `false` turns them all off. */
   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, BudgetsInput as D, Budgets as E, ResolvedBudgets as O, ScreenEdge as S, BudgetKey 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, resolveBudgets as k, 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, AppBudgets as w, Placement as x, DockHandle as y };
-//# sourceMappingURL=mount-perf-hud-Cg_iAuFQ.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-CJju0oTc.js → mount-perf-hud-DZ1_LUZ8.js}

@@ -969,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;
@@ -1400,7 +1428,7 @@ const mountDevPanel = (options) => {
 };
 // package.json
 var name = "@zkmake/three-meter";
-var version = "0.12.0";
+var version = "0.13.1";
 // src/ui/clipboard.ts
 /**
 * Copy text from a click handler. The async Clipboard API needs a secure
@@ -1511,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
@@ -1908,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;
@@ -1932,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();
@@ -1967,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();
@@ -1986,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();
@@ -2120,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;
@@ -2171,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");
@@ -2246,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";
@@ -2266,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));
@@ -2502,6 +2595,7 @@ const mountPerfHud = (monitor, options = {}) => {
 		budgets: options.budgets,
 		mode: options.mode ?? "compact",
 		monitor,
+		quality: options.quality,
 		refreshHz: options.refreshHz,
 		settings,
 		theme
@@ -2544,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,
@@ -2551,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-CJju0oTc.js.map
+//# sourceMappingURL=mount-perf-hud-DZ1_LUZ8.js.map