@zkmake/three-meter 0.6.0 → 0.7.0

package/README.md

@@ -89,6 +89,7 @@ Canvas is its own React root. To run two canvases on one page, pass the same `st
 | `parent`           | `document.body`    | Where the host element is appended.                                                           |
 | `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).                               |
 
 `PerformanceMonitor` and `PerfSampler` take `trackGPU` (default true), `gpuQueryPoolSize` (default 5),
 `historySize` (default 120) and `frameStatsSize` (default 1000).
@@ -118,7 +119,7 @@ hud.theme.subscribe(() => syncMyPageWith(hud.theme.resolved));
 
 The resolved theme lands on `data-theme` of `.perf-hud` and `.perf-monitor`. To restyle either
 palette, override the `--perf-*` custom properties (`bg`, `fg`, `fg-dim`, `muted`, `row`,
-`border`, `accent`, `shadow`) on those selectors.
+`border`, `accent`, `warn`, `shadow`) on those selectors. `warn` is the over-budget amber.
 
 ## GPU timing
 
@@ -149,6 +150,23 @@ Every row has an icon, its value, and a checkbox on the right that puts it in th
 a label for a one-line explanation of the metric and what a bad reading means, or tick **explain
 metrics** to show them all under the rows (also works on touch).
 
+## Budgets
+
+A value past its budget turns amber in the full view and the compact HUD, and its tooltip names the
+budget. The FPS, CPU and GPU graphs draw the budget as a dashed line once the series reaches it; the
+scale never stretches to fit it, so a quiet graph keeps its detail.
+
+Timing budgets come from `targetFps` (60 by default): FPS at least 95% of it, 1% low at least half,
+CPU and GPU within one frame (16.7 ms), frame p99 within one and a half. Counts have no default,
+since what's reasonable depends on the scene. Set your own:
+
+```ts
+mountPerfHud(monitor, { budgets: { targetFps: 120, calls: 500, triangles: 2_000_000 } });
+hud.setBudgets({ gpu: null }); // null drops a default; false drops them all
+```
+
+`PerfHud` takes the same `budgets` prop and applies changes live.
+
 ## Stutter
 
 Average FPS hides a hitch every few seconds. Three rows in the full view catch it, and any of them

package/dist/{mount-perf-hud-CmINOH3T.d.ts → mount-perf-hud-6LeJ93Jg.d.ts}

@@ -1,4 +1,28 @@
 import { d as TimingMetric, t as PerformanceMonitor } from "./performance-monitor-CBN05_BC.js";
+//#region src/ui/budgets.d.ts
+/**
+ * Budgets: the value each metric should stay within. A reading past its
+ * budget turns amber in the card, and the FPS / CPU / GPU graphs draw the
+ * line once the series reaches it. `fps` and `low` are floors (worse below);
+ * everything else is a ceiling (worse above).
+ *
+ * Timing budgets default from `targetFps` (60): FPS at least 95% of it, 1%
+ * low at least half, CPU and GPU within one frame, p99 within one and a half.
+ * 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.
+ */
+type BudgetKey = "calls" | "cpu" | "fps" | "geometries" | "gpu" | "hitches" | "lines" | "low" | "p99" | "passes" | "points" | "shaders" | "textures" | "triangles";
+type Budgets = Partial<Record<BudgetKey, number | null>> & {
+  /** The frame rate the defaults are derived from. Default 60. */
+  targetFps?: number;
+};
+type ResolvedBudgets = {
+  /** Frame budget in ms, `1000 / targetFps`. */
+  frameMs: number;
+  limits: Partial<Record<BudgetKey, number>>;
+};
+declare const resolveBudgets: (budgets: Budgets | false | undefined) => ResolvedBudgets;
+//#endregion
 //#region src/ui/dock-panel.d.ts
 declare const EDGES: readonly ["left", "right", "top", "bottom"];
 type ScreenEdge = (typeof EDGES)[number];
@@ -131,6 +155,11 @@ type PerformanceViewOptions = {
   mode?: PerformanceViewMode;
   /** Repaint rate. Default 10. */
   refreshHz?: number;
+  /**
+   * Limits past which a value turns amber. Timing budgets default from
+   * `targetFps` (60); `false` turns them all off. See {@link Budgets}.
+   */
+  budgets?: Budgets | false;
   /** Share one between views to keep them in sync; a fresh instance otherwise. */
   settings?: HudSettings;
   /**
@@ -171,6 +200,7 @@ declare class PerformanceView {
   private hudGridEl;
   private readonly hudGraphs;
   private readonly hudNumberEls;
+  private budgets;
   private rafId;
   private lastPaintAt;
   private readonly resizeObserver;
@@ -180,12 +210,19 @@ declare class PerformanceView {
   stop(): void;
   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;
   dispose(): void;
   private frame;
   private render;
   /** The monitor caches the environment once its backend settles; until then this re-reads. */
   private renderFooter;
   private renderHud;
+  private paintNumber;
+  /** Value and sparkline, with the budget line drawn once the series reaches it. */
+  private paintGraph;
+  /** Each value's tooltip names its budget, so amber explains itself. */
+  private applyBudgetTitles;
   private formatTiming;
   private build;
   private rebuildHud;
@@ -221,6 +258,12 @@ type MountPerfHudOptions = {
   injectStyles?: boolean;
   /** Repaint rate. Default 10. */
   refreshHz?: number;
+  /**
+   * Limits past which a value turns amber, e.g. `{ calls: 500, targetFps: 120 }`.
+   * Timing budgets default from `targetFps` (60); `false` turns them all off.
+   * Change later with the handle's `setBudgets`.
+   */
+  budgets?: Budgets | false;
   /** Accessible name of the panel. Default `Performance`. */
   label?: string;
 };
@@ -240,9 +283,11 @@ type PerfHudHandle = {
   getTheme: () => ThemeMode;
   /** 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;
   dispose: () => void;
 };
 declare const mountPerfHud: (monitor: PerformanceMonitor, options?: MountPerfHudOptions) => PerfHudHandle;
 //#endregion
-export { dockPanel as C, ScreenEdge as S, 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, Placement as x, DockHandle as y };
-//# sourceMappingURL=mount-perf-hud-CmINOH3T.d.ts.map
+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-6LeJ93Jg.d.ts.map

package/dist/{mount-perf-hud-C5wdjgmM.js → mount-perf-hud-DqY_tP6s.js}

@@ -1,3 +1,36 @@
+//#region src/ui/budgets.ts
+const DEFAULT_TARGET_FPS = 60;
+const FLOORS = /* @__PURE__ */ new Set(["fps", "low"]);
+const resolveBudgets = (budgets) => {
+	const targetFps = budgets && budgets.targetFps || DEFAULT_TARGET_FPS;
+	const frameMs = 1e3 / targetFps;
+	if (budgets === false) return {
+		frameMs,
+		limits: {}
+	};
+	const merged = {
+		cpu: frameMs,
+		fps: targetFps * .95,
+		gpu: frameMs,
+		low: targetFps / 2,
+		p99: frameMs * 1.5,
+		...budgets
+	};
+	const limits = {};
+	for (const [key, limit] of Object.entries(merged)) if (key !== "targetFps" && typeof limit === "number" && Number.isFinite(limit)) limits[key] = limit;
+	return {
+		frameMs,
+		limits
+	};
+};
+const isFloor = (key) => FLOORS.has(key);
+/** `null` means the value isn't known yet (no frames, no GPU timer), which is never over. */
+const isOverBudget = (resolved, key, value) => {
+	const limit = resolved.limits[key];
+	if (limit === void 0 || value === null) return false;
+	return isFloor(key) ? value < limit : value > limit;
+};
+//#endregion
 //#region src/ui/theme.ts
 const THEME_MODES = [
 	"dark",
@@ -493,7 +526,7 @@ const createIcon = (name, className) => {
 };
 //#endregion
 //#region package.json
-var version = "0.6.0";
+var version = "0.7.0";
 //#endregion
 //#region src/ui/clipboard.ts
 /**
@@ -639,7 +672,7 @@ const formatReport = (monitor) => renderReport({
 });
 //#endregion
 //#region src/ui/sparkline.ts
-function drawSparkline(ctx, width, height, values, style) {
+function drawSparkline(ctx, width, height, values, style, guide) {
 	ctx.clearRect(0, 0, width, height);
 	if (values.length < 2) return;
 	let max = 0;
@@ -658,6 +691,17 @@ function drawSparkline(ctx, width, height, values, style) {
 	ctx.closePath();
 	ctx.fillStyle = style.fill;
 	ctx.fill();
+	if (guide && guide.value > 0 && guide.value <= range) {
+		const y = Math.round(toY(guide.value)) + .5;
+		ctx.save();
+		ctx.setLineDash([3, 3]);
+		ctx.strokeStyle = guide.color;
+		ctx.beginPath();
+		ctx.moveTo(0, y);
+		ctx.lineTo(width, y);
+		ctx.stroke();
+		ctx.restore();
+	}
 }
 //#endregion
 //#region src/ui/performance-view.ts
@@ -742,92 +786,130 @@ const readTiming = (sample, metric) => {
 	}
 };
 const isTimingAvailable = (sample, metric) => metric !== "gpu" || sample.gpu.available;
+const whole = (value) => Math.round(value).toString();
+const tenths = (value) => value.toFixed(1);
 const NUMBERS = [
 	{
+		format: whole,
 		icon: "gauge",
 		key: "fps",
 		label: "FPS",
-		read: (sample) => Math.round(sample.fps).toString()
+		value: (sample) => sample.fps || null
 	},
 	{
+		format: formatCount,
 		icon: "layers",
 		key: "calls",
 		label: "Calls",
-		read: (sample) => formatCount(sample.render.calls)
+		value: (sample) => sample.render.calls
 	},
 	{
+		format: tenths,
 		icon: "cpu",
 		key: "cpu",
 		label: "CPU",
-		read: (sample) => sample.cpu.toFixed(1)
+		unit: "ms",
+		value: (sample) => sample.cpu
 	},
 	{
+		format: tenths,
 		icon: "zap",
 		key: "gpu",
 		label: "GPU",
-		read: (sample) => sample.gpu.available ? sample.gpu.ms.toFixed(1) : "—"
+		unit: "ms",
+		value: (sample) => sample.gpu.available ? sample.gpu.ms : null
 	},
 	{
+		format: whole,
 		icon: "trendingDown",
 		key: "low",
 		label: "1% low",
-		read: (_sample, stats) => stats.frames ? Math.round(stats.lowFps).toString() : "—"
+		value: (_sample, stats) => stats.frames ? stats.lowFps : null
 	},
 	{
+		format: tenths,
 		icon: "timer",
 		key: "p99",
 		label: "Frame p99",
-		read: (_sample, stats) => stats.frames ? stats.p99Ms.toFixed(1) : "—"
+		unit: "ms",
+		value: (_sample, stats) => stats.frames ? stats.p99Ms : null
 	},
 	{
+		format: formatCount,
 		icon: "activity",
 		key: "hitches",
 		label: "Hitches",
-		read: (_sample, stats) => stats.frames ? formatCount(stats.hitches) : "—"
+		value: (_sample, stats) => stats.frames ? stats.hitches : null
 	},
 	{
+		format: formatCount,
 		icon: "triangle",
 		key: "triangles",
 		label: "Triangles",
-		read: (sample) => formatCount(sample.render.triangles)
+		value: (sample) => sample.render.triangles
 	},
 	{
+		format: formatCount,
 		icon: "spline",
 		key: "lines",
 		label: "Lines",
-		read: (sample) => formatCount(sample.render.lines)
+		value: (sample) => sample.render.lines
 	},
 	{
+		format: formatCount,
 		icon: "circleDot",
 		key: "points",
 		label: "Points",
-		read: (sample) => formatCount(sample.render.points)
+		value: (sample) => sample.render.points
 	},
 	{
+		format: formatCount,
 		icon: "repeat",
 		key: "passes",
 		label: "Render passes",
-		read: (sample) => formatCount(sample.render.passes)
+		value: (sample) => sample.render.passes
 	},
 	{
+		format: formatCount,
 		icon: "box",
 		key: "geometries",
 		label: "Geometries",
-		read: (sample) => formatCount(sample.resources.geometries)
+		value: (sample) => sample.resources.geometries
 	},
 	{
+		format: formatCount,
 		icon: "image",
 		key: "textures",
 		label: "Textures",
-		read: (sample) => formatCount(sample.resources.textures)
+		value: (sample) => sample.resources.textures
 	},
 	{
+		format: formatCount,
 		icon: "palette",
 		key: "shaders",
 		label: "Shaders",
-		read: (sample) => formatCount(sample.resources.programs)
+		value: (sample) => sample.resources.programs
 	}
 ];
+const NUMBER_BY_KEY = new Map(NUMBERS.map((config) => [config.key, config]));
+/** Canvas can't read CSS custom properties; the budget line's amber per theme. */
+const GUIDE_COLOR = {
+	dark: "rgba(245, 158, 11, 0.75)",
+	light: "rgba(180, 83, 9, 0.7)"
+};
+/** `Budget: at most 16.7 ms` / `at least 57`, or `""` without one. */
+const budgetTitle = (budgets, key) => {
+	const limit = budgets.limits[key];
+	const config = NUMBER_BY_KEY.get(key);
+	if (limit === void 0 || !config) return "";
+	return `Budget: ${isFloor(key) ? "at least" : "at most"} ${config.format(limit)}${config.unit ? ` ${config.unit}` : ""}`;
+};
+/** The sample value a timing graph shows, `null` when not known. */
+const timingValue = (sample, metric) => {
+	if (!isTimingAvailable(sample, metric)) return null;
+	const value = readTiming(sample, metric);
+	return metric === "fps" && value === 0 ? null : value;
+};
 /**
 * Host-agnostic widget that paints {@link Sample}s. Mount {@link element}
 * anywhere; the view drives its own throttled repaint. Compact is the floating
@@ -860,6 +942,7 @@ var PerformanceView = class {
 	hudGridEl;
 	hudGraphs = /* @__PURE__ */ new Map();
 	hudNumberEls = /* @__PURE__ */ new Map();
+	budgets;
 	rafId = null;
 	lastPaintAt = 0;
 	resizeObserver;
@@ -872,6 +955,7 @@ var PerformanceView = class {
 		this.theme.setOverride(this.settings.theme);
 		this.mode = options.mode ?? "full";
 		this.minIntervalMs = 1e3 / (options.refreshHz ?? 10);
+		this.budgets = resolveBudgets(options.budgets);
 		this.element = document.createElement("div");
 		this.element.className = "perf-monitor";
 		this.applyModeClass();
@@ -901,6 +985,11 @@ var PerformanceView = class {
 	getMode() {
 		return this.mode;
 	}
+	/** Replace the budgets; `false` turns them all off. Applies on the next paint. */
+	setBudgets(budgets) {
+		this.budgets = resolveBudgets(budgets);
+		this.applyBudgetTitles();
+	}
 	dispose() {
 		this.stop();
 		this.unsubscribe();
@@ -922,15 +1011,9 @@ var PerformanceView = class {
 			if (this.settings.info) this.renderFooter();
 			return;
 		}
-		for (const config of TIMINGS) {
-			const available = isTimingAvailable(sample, config.metric);
-			const valueEl = this.graphValueEls.get(config.metric);
-			valueEl.textContent = available ? this.formatTiming(config, readTiming(sample, config.metric)) : "unavailable";
-			const graph = this.graphCanvases.get(config.metric);
-			drawSparkline(graph.ctx, graph.width, graph.height, available ? this.monitor.getHistory(config.metric) : [], config.style[this.theme.resolved]);
-		}
+		for (const config of TIMINGS) this.paintGraph(config, sample, this.graphValueEls.get(config.metric), this.graphCanvases.get(config.metric), "unavailable");
 		const stats = this.monitor.getFrameStats();
-		for (const config of NUMBERS) this.statValueEls.get(config.key).textContent = config.read(sample, stats);
+		for (const config of NUMBERS) this.paintNumber(config, this.statValueEls.get(config.key), sample, stats);
 		this.renderFooter();
 	}
 	/** The monitor caches the environment once its backend settles; until then this re-reads. */
@@ -954,16 +1037,38 @@ var PerformanceView = class {
 	renderHud(sample) {
 		const stats = this.hudNumberEls.size > 0 ? this.monitor.getFrameStats() : null;
 		for (const [key, element] of this.hudNumberEls) {
-			const config = NUMBERS.find((number) => number.key === key);
-			if (config && stats) element.textContent = config.read(sample, stats);
+			const config = NUMBER_BY_KEY.get(key);
+			if (config && stats) this.paintNumber(config, element, sample, stats);
 		}
 		for (const [metric, graph] of this.hudGraphs) {
 			const config = TIMINGS.find((timing) => timing.metric === metric);
-			const available = isTimingAvailable(sample, metric);
-			graph.valueEl.textContent = available ? this.formatTiming(config, readTiming(sample, metric)) : "—";
-			drawSparkline(graph.ctx, graph.width, graph.height, available ? this.monitor.getHistory(metric) : [], config.style[this.theme.resolved]);
+			this.paintGraph(config, sample, graph.valueEl, graph, "—");
 		}
 	}
+	paintNumber(config, element, sample, stats) {
+		const value = config.value(sample, stats);
+		element.textContent = value === null ? "—" : config.format(value);
+		element.classList.toggle("is-over", isOverBudget(this.budgets, config.key, value));
+	}
+	/** Value and sparkline, with the budget line drawn once the series reaches it. */
+	paintGraph(config, sample, valueEl, graph, missing) {
+		const value = timingValue(sample, config.metric);
+		const available = isTimingAvailable(sample, config.metric);
+		const limit = this.budgets.limits[config.metric];
+		valueEl.textContent = available ? this.formatTiming(config, readTiming(sample, config.metric)) : missing;
+		valueEl.classList.toggle("is-over", isOverBudget(this.budgets, config.metric, value));
+		drawSparkline(graph.ctx, graph.width, graph.height, available ? this.monitor.getHistory(config.metric) : [], config.style[this.theme.resolved], limit === void 0 ? void 0 : {
+			color: GUIDE_COLOR[this.theme.resolved],
+			value: limit
+		});
+	}
+	/** Each value's tooltip names its budget, so amber explains itself. */
+	applyBudgetTitles() {
+		for (const [key, element] of this.statValueEls) element.title = budgetTitle(this.budgets, key);
+		for (const [key, element] of this.hudNumberEls) element.title = budgetTitle(this.budgets, key);
+		for (const [metric, element] of this.graphValueEls) element.title = budgetTitle(this.budgets, metric);
+		for (const [metric, graph] of this.hudGraphs) graph.valueEl.title = budgetTitle(this.budgets, metric);
+	}
 	formatTiming(config, value) {
 		return `${config.format(value)}${config.unit ? ` ${config.unit}` : ""}`;
 	}
@@ -1156,6 +1261,7 @@ var PerformanceView = class {
 			this.hudGridEl.append(item);
 			this.hudNumberEls.set(config.key, value);
 		}
+		this.applyBudgetTitles();
 		this.resizeCanvases();
 	}
 	onSelectionChanged() {
@@ -1256,6 +1362,7 @@ const PERF_HUD_STYLES = `
   --perf-row: rgba(255, 255, 255, 0.04);
   --perf-border: rgba(255, 255, 255, 0.12);
   --perf-accent: #60a5fa;
+  --perf-warn: #f59e0b;
   --perf-shadow: 0 8px 24px rgba(0, 0, 0, 0.32);
 
   color-scheme: dark;
@@ -1270,6 +1377,7 @@ const PERF_HUD_STYLES = `
   --perf-row: rgba(0, 0, 0, 0.05);
   --perf-border: rgba(0, 0, 0, 0.12);
   --perf-accent: #2563eb;
+  --perf-warn: #b45309;
   --perf-shadow: 0 8px 24px rgba(0, 0, 0, 0.16);
 
   color-scheme: light;
@@ -1581,13 +1689,15 @@ const PERF_HUD_STYLES = `
 }
 
 .perf-monitor__badge.is-fallback {
-  border-color: #f59e0b;
-  color: #f59e0b;
+  border-color: var(--perf-warn);
+  color: var(--perf-warn);
 }
 
-.perf-monitor[data-theme="light"] .perf-monitor__badge.is-fallback {
-  border-color: #d97706;
-  color: #b45309;
+/* Past its budget. The value's tooltip names the budget. */
+.perf-monitor__value.is-over,
+.perf-monitor__hud-value.is-over,
+.perf-monitor__graph-value.is-over {
+  color: var(--perf-warn);
 }
 
 .perf-monitor__link {
@@ -1782,6 +1892,7 @@ const mountPerfHud = (monitor, options = {}) => {
 	const toggle = disc("Toggle full performance metrics", "", "sliders");
 	tools.append(grip, toggle);
 	const view = new PerformanceView({
+		budgets: options.budgets,
 		mode: options.mode ?? "compact",
 		monitor,
 		refreshHz: options.refreshHz,
@@ -1857,6 +1968,7 @@ const mountPerfHud = (monitor, options = {}) => {
 		},
 		element: host,
 		getMode: () => view.getMode(),
+		setBudgets: (budgets) => view.setBudgets(budgets),
 		setMode,
 		getTheme: () => theme.mode,
 		setTheme: (mode) => theme.setMode(mode),
@@ -1866,6 +1978,6 @@ const mountPerfHud = (monitor, options = {}) => {
 	};
 };
 //#endregion
-export { formatReport as a, HudSettings as c, isThemeMode as d, PerformanceView as i, HudTheme as l, PERF_HUD_STYLES as n, dockPanel as o, injectStyles as r, DEFAULT_STORAGE_KEY as s, mountPerfHud as t, THEME_MODES as u };
+export { formatReport as a, HudSettings as c, isThemeMode as d, resolveBudgets as f, PerformanceView as i, HudTheme as l, PERF_HUD_STYLES as n, dockPanel as o, injectStyles as r, DEFAULT_STORAGE_KEY as s, mountPerfHud as t, THEME_MODES as u };
 
-//# sourceMappingURL=mount-perf-hud-C5wdjgmM.js.map
+//# sourceMappingURL=mount-perf-hud-DqY_tP6s.js.map