@zkmake/three-meter 0.5.0 → 0.7.0

package/dist/{mount-perf-hud-BLs1jkwM.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",
@@ -453,10 +486,26 @@ const dockPanel = (element, options = {}) => {
 //#endregion
 //#region src/ui/icons.ts
 const ICON_MARKUP = {
+	activity: "<path d=\"M22 12h-2.48a2 2 0 0 0-1.93 1.46l-2.35 8.36a.25.25 0 0 1-.48 0L9.24 2.18a.25.25 0 0 0-.48 0l-2.35 8.36A2 2 0 0 1 4.49 12H2\"/>",
+	box: "<path d=\"M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z\"/><path d=\"m3.3 7 8.7 5 8.7-5\"/><path d=\"M12 22V12\"/>",
+	circleDot: "<circle cx=\"12\" cy=\"12\" r=\"10\"/><circle cx=\"12\" cy=\"12\" r=\"1\"/>",
+	cpu: "<rect width=\"16\" height=\"16\" x=\"4\" y=\"4\" rx=\"2\"/><rect width=\"6\" height=\"6\" x=\"9\" y=\"9\" rx=\"1\"/><path d=\"M15 2v2\"/><path d=\"M15 20v2\"/><path d=\"M2 15h2\"/><path d=\"M2 9h2\"/><path d=\"M20 15h2\"/><path d=\"M20 9h2\"/><path d=\"M9 2v2\"/><path d=\"M9 20v2\"/>",
+	gauge: "<path d=\"m12 14 4-4\"/><path d=\"M3.34 19a10 10 0 1 1 17.32 0\"/>",
+	image: "<rect width=\"18\" height=\"18\" x=\"3\" y=\"3\" rx=\"2\" ry=\"2\"/><circle cx=\"9\" cy=\"9\" r=\"2\"/><path d=\"m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21\"/>",
+	info: "<circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M12 16v-4\"/><path d=\"M12 8h.01\"/>",
+	layers: "<path d=\"m12.83 2.18a2 2 0 0 0-1.66 0L2.6 6.08a1 1 0 0 0 0 1.83l8.58 3.91a2 2 0 0 0 1.66 0l8.58-3.9a1 1 0 0 0 0-1.83Z\"/><path d=\"m22 17.65-9.17 4.16a2 2 0 0 1-1.66 0L2 17.65\"/><path d=\"m22 12.65-9.17 4.16a2 2 0 0 1-1.66 0L2 12.65\"/>",
+	palette: "<circle cx=\"13.5\" cy=\"6.5\" r=\".5\" fill=\"currentColor\"/><circle cx=\"17.5\" cy=\"10.5\" r=\".5\" fill=\"currentColor\"/><circle cx=\"8.5\" cy=\"7.5\" r=\".5\" fill=\"currentColor\"/><circle cx=\"6.5\" cy=\"12.5\" r=\".5\" fill=\"currentColor\"/><path d=\"M12 2C6.5 2 2 6.5 2 12s4.5 10 10 10c.926 0 1.648-.746 1.648-1.688 0-.437-.18-.835-.437-1.125-.29-.289-.438-.652-.438-1.125a1.64 1.64 0 0 1 1.668-1.668h1.996c3.051 0 5.555-2.503 5.555-5.554C21.965 6.012 17.461 2 12 2z\"/>",
+	repeat: "<path d=\"m17 2 4 4-4 4\"/><path d=\"M3 11v-1a4 4 0 0 1 4-4h14\"/><path d=\"m7 22-4-4 4-4\"/><path d=\"M21 13v1a4 4 0 0 1-4 4H3\"/>",
+	spline: "<circle cx=\"19\" cy=\"5\" r=\"2\"/><circle cx=\"5\" cy=\"19\" r=\"2\"/><path d=\"M5 17A12 12 0 0 1 17 5\"/>",
+	timer: "<line x1=\"10\" x2=\"14\" y1=\"2\" y2=\"2\"/><line x1=\"12\" x2=\"15\" y1=\"14\" y2=\"11\"/><circle cx=\"12\" cy=\"14\" r=\"8\"/>",
+	trendingDown: "<polyline points=\"22 17 13.5 8.5 8.5 13.5 2 7\"/><polyline points=\"16 17 22 17 22 11\"/>",
+	triangle: "<path d=\"M13.73 4a2 2 0 0 0-3.46 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z\"/>",
+	zap: "<path d=\"M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z\"/>",
 	blend: "<circle cx=\"9\" cy=\"9\" r=\"7\"/><circle cx=\"15\" cy=\"15\" r=\"7\"/>",
 	clipboard: "<rect width=\"8\" height=\"4\" x=\"8\" y=\"2\" rx=\"1\" ry=\"1\"/><path d=\"M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2\"/>",
 	contrast: "<circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M12 18a6 6 0 0 0 0-12v12z\"/>",
 	grip: "<circle cx=\"9\" cy=\"12\" r=\"1\"/><circle cx=\"9\" cy=\"5\" r=\"1\"/><circle cx=\"9\" cy=\"19\" r=\"1\"/><circle cx=\"15\" cy=\"12\" r=\"1\"/><circle cx=\"15\" cy=\"5\" r=\"1\"/><circle cx=\"15\" cy=\"19\" r=\"1\"/>",
+	help: "<circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3\"/><path d=\"M12 17h.01\"/>",
 	monitor: "<rect width=\"20\" height=\"14\" x=\"2\" y=\"3\" rx=\"2\"/><line x1=\"8\" x2=\"16\" y1=\"21\" y2=\"21\"/><line x1=\"12\" x2=\"12\" y1=\"17\" y2=\"21\"/>",
 	moon: "<path d=\"M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z\"/>",
 	sun: "<circle cx=\"12\" cy=\"12\" r=\"4\"/><path d=\"M12 2v2\"/><path d=\"M12 20v2\"/><path d=\"m4.93 4.93 1.41 1.41\"/><path d=\"m17.66 17.66 1.41 1.41\"/><path d=\"M2 12h2\"/><path d=\"M20 12h2\"/><path d=\"m6.34 17.66-1.41 1.41\"/><path d=\"m19.07 4.93-1.41 1.41\"/>",
@@ -477,7 +526,7 @@ const createIcon = (name, className) => {
 };
 //#endregion
 //#region package.json
-var version = "0.5.0";
+var version = "0.7.0";
 //#endregion
 //#region src/ui/clipboard.ts
 /**
@@ -529,6 +578,29 @@ const compact = new Intl.NumberFormat("en-US", {
 });
 const formatCount = (value) => Math.abs(value) < COMPACT_FROM ? exact.format(value) : compact.format(value);
 //#endregion
+//#region src/ui/metric-help.ts
+/**
+* One plain-language line per metric: what it is, and what a bad reading
+* means. Shown as the label's tooltip and, with "explain metrics" on, under
+* each row. Keyed like the stat rows; the graphs reuse `fps`, `cpu`, `gpu`.
+*/
+const METRIC_HELP = {
+	calls: "Separate draw commands sent to the GPU this frame. Fewer is better: merge or instance meshes that share a material.",
+	cpu: "JavaScript time per frame: your update code plus three.js preparing the render. It has to fit the frame budget (16.7 ms at 60 FPS).",
+	fps: "Frames drawn per second. Higher is smoother; most displays top out at 60 or 120.",
+	geometries: "Geometries held in GPU memory. Should level off; a steady climb is a leak, so dispose() what you remove.",
+	gpu: "Time the graphics card spent drawing the frame. High means shaders, overdraw or resolution are the bottleneck.",
+	hitches: "Frames that took over twice as long as usual, in the last 1,000 frames. Each one is a visible stutter.",
+	lines: "Line segments drawn this frame.",
+	low: "Frame rate during the slowest 1% of frames. Far below FPS means stutter the average hides.",
+	p99: "99% of frames finished within this many ms. Above the frame budget (16.7 ms at 60 FPS) means dropped frames.",
+	passes: "Times renderer.render() ran this frame. Shadows, post-processing and extra cameras each add passes.",
+	points: "Points drawn this frame.",
+	shaders: "Compiled shader programs. A jump mid-session usually means a stutter while a new material compiled.",
+	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."
+};
+//#endregion
 //#region src/ui/report.ts
 /**
 * A plain-text snapshot of the monitor for bug reports: versions, backend and
@@ -600,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;
@@ -619,12 +691,24 @@ 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
 const TIMINGS = [
 	{
 		format: (value) => Math.round(value).toString(),
+		icon: "gauge",
 		label: "FPS",
 		metric: "fps",
 		style: {
@@ -641,6 +725,7 @@ const TIMINGS = [
 	},
 	{
 		format: (value) => value.toFixed(1),
+		icon: "cpu",
 		label: "CPU",
 		metric: "cpu",
 		style: {
@@ -657,6 +742,7 @@ const TIMINGS = [
 	},
 	{
 		format: (value) => value.toFixed(1),
+		icon: "zap",
 		label: "GPU",
 		metric: "gpu",
 		style: {
@@ -700,78 +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
@@ -804,6 +942,7 @@ var PerformanceView = class {
 	hudGridEl;
 	hudGraphs = /* @__PURE__ */ new Map();
 	hudNumberEls = /* @__PURE__ */ new Map();
+	budgets;
 	rafId = null;
 	lastPaintAt = 0;
 	resizeObserver;
@@ -816,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();
@@ -845,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();
@@ -866,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. */
@@ -898,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}` : ""}`;
 	}
@@ -951,7 +1112,14 @@ var PerformanceView = class {
 		dimLabel.className = "perf-monitor__label";
 		dimLabel.textContent = "dim on leave";
 		dimRow.append(createIcon("blend", "perf-monitor__icon"), dimLabel, this.dimCheckbox);
-		options.append(themeRow, dimRow, this.buildReportRow());
+		const explainRow = document.createElement("label");
+		explainRow.className = "perf-monitor__row";
+		const explainCheckbox = this.buildCheckbox(false, "Explain each metric", (on) => this.element.classList.toggle("perf-monitor--explain", on));
+		const explainLabel = document.createElement("span");
+		explainLabel.className = "perf-monitor__label";
+		explainLabel.textContent = "explain metrics";
+		explainRow.append(createIcon("help", "perf-monitor__icon"), explainLabel, explainCheckbox);
+		options.append(themeRow, dimRow, explainRow, this.buildReportRow());
 		const graphs = document.createElement("div");
 		graphs.className = "perf-monitor__graphs";
 		for (const config of TIMINGS) {
@@ -959,21 +1127,25 @@ var PerformanceView = class {
 			graph.className = "perf-monitor__graph";
 			const canvas = document.createElement("canvas");
 			canvas.className = "perf-monitor__canvas";
-			const overlay = document.createElement("div");
-			overlay.className = "perf-monitor__graph-overlay";
-			const head = document.createElement("label");
+			const overlay = document.createElement("label");
+			overlay.className = "perf-monitor__graph-overlay perf-monitor__graph-overlay--toggle";
+			const head = document.createElement("span");
 			head.className = "perf-monitor__graph-head";
 			const checkbox = this.buildCheckbox(this.settings.isGraphEnabled(config.metric), `Show ${config.label} graph in HUD`, (on) => this.settings.setGraphEnabled(config.metric, on));
 			this.graphCheckboxes.set(config.metric, checkbox);
 			const label = document.createElement("span");
 			label.className = "perf-monitor__graph-label";
 			label.textContent = config.label;
+			label.title = METRIC_HELP[config.metric] ?? "";
 			const value = document.createElement("span");
 			value.className = "perf-monitor__graph-value";
 			value.textContent = "—";
 			this.graphValueEls.set(config.metric, value);
-			head.append(checkbox, label);
-			overlay.append(head, value);
+			const tail = document.createElement("span");
+			tail.className = "perf-monitor__graph-head";
+			tail.append(value, checkbox);
+			head.append(createIcon(config.icon, "perf-monitor__icon"), label);
+			overlay.append(head, tail);
 			graph.append(canvas, overlay);
 			graphs.append(graph);
 			const ctx = canvas.getContext("2d");
@@ -994,14 +1166,19 @@ var PerformanceView = class {
 			rowEl.className = "perf-monitor__row";
 			const checkbox = this.buildCheckbox(this.settings.isNumberEnabled(config.key), `Show ${config.label} in HUD`, (on) => this.settings.setNumberEnabled(config.key, on));
 			this.statCheckboxes.set(config.key, checkbox);
+			const help = METRIC_HELP[config.key] ?? "";
 			const label = document.createElement("span");
 			label.className = "perf-monitor__label";
 			label.textContent = config.label;
+			label.title = help;
 			const value = document.createElement("span");
 			value.className = "perf-monitor__value";
 			value.textContent = "—";
 			this.statValueEls.set(config.key, value);
-			rowEl.append(checkbox, label, value);
+			const hint = document.createElement("span");
+			hint.className = "perf-monitor__hint";
+			hint.textContent = help;
+			rowEl.append(createIcon(config.icon, "perf-monitor__icon"), label, value, checkbox, hint);
 			stats.append(rowEl);
 		}
 		const footer = document.createElement("div");
@@ -1029,7 +1206,7 @@ var PerformanceView = class {
 		this.footerGpuEl.className = "perf-monitor__footer-gpu";
 		this.footerHardwareEl.append(this.footerBackendEl, this.footerGpuEl);
 		footerBody.append(softwareRow, this.footerHardwareEl);
-		footer.append(this.infoCheckbox, footerBody);
+		footer.append(createIcon("info", "perf-monitor__icon"), footerBody, this.infoCheckbox);
 		this.element.append(hud, options, graphs, stats, footer);
 	}
 	rebuildHud() {
@@ -1050,6 +1227,7 @@ var PerformanceView = class {
 			const label = document.createElement("span");
 			label.className = "perf-monitor__graph-label";
 			label.textContent = config.label;
+			label.title = METRIC_HELP[config.metric] ?? "";
 			const value = document.createElement("span");
 			value.className = "perf-monitor__graph-value";
 			value.textContent = "—";
@@ -1075,6 +1253,7 @@ var PerformanceView = class {
 			const label = document.createElement("span");
 			label.className = "perf-monitor__hud-label";
 			label.textContent = config.label;
+			label.title = METRIC_HELP[config.key] ?? "";
 			const value = document.createElement("span");
 			value.className = "perf-monitor__hud-value";
 			value.textContent = "—";
@@ -1082,6 +1261,7 @@ var PerformanceView = class {
 			this.hudGridEl.append(item);
 			this.hudNumberEls.set(config.key, value);
 		}
+		this.applyBudgetTitles();
 		this.resizeCanvases();
 	}
 	onSelectionChanged() {
@@ -1182,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;
@@ -1196,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;
@@ -1249,8 +1431,9 @@ const PERF_HUD_STYLES = `
   cursor: pointer;
 }
 
-.perf-monitor__graph-overlay .perf-monitor__graph-head {
+.perf-monitor__graph-overlay--toggle {
   pointer-events: auto;
+  cursor: pointer;
 }
 
 .perf-monitor__graph-label {
@@ -1282,6 +1465,25 @@ const PERF_HUD_STYLES = `
   cursor: pointer;
 }
 
+/* Hidden until "explain metrics" is on; then the row wraps it under the label. */
+.perf-monitor__hint {
+  display: none;
+  flex-basis: 100%;
+  padding: 0 0 2px 18px;
+  color: var(--perf-muted);
+  font-size: 10px;
+  line-height: 1.35;
+  opacity: 0.85;
+}
+
+.perf-monitor--explain .perf-monitor__hint {
+  display: block;
+}
+
+.perf-monitor--explain .perf-monitor__section .perf-monitor__row {
+  flex-wrap: wrap;
+}
+
 .perf-monitor__row:nth-child(even) {
   background: var(--perf-row);
 }
@@ -1487,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 {
@@ -1514,7 +1718,8 @@ const PERF_HUD_STYLES = `
 .perf-monitor--compact .perf-monitor__graphs,
 .perf-monitor--compact .perf-monitor__section,
 .perf-monitor--compact:not(.perf-monitor--info) .perf-monitor__footer,
-.perf-monitor--compact .perf-monitor__footer > .perf-monitor__checkbox {
+.perf-monitor--compact .perf-monitor__footer > .perf-monitor__checkbox,
+.perf-monitor--compact .perf-monitor__footer > .perf-monitor__icon {
   display: none;
 }
 
@@ -1545,6 +1750,11 @@ const PERF_HUD_STYLES = `
   max-width: 100%;
 }
 
+/* Room for the hints, so most fit on two or three lines. Plus padding, this fills the host's 20rem cap. */
+.perf-hud--full > .perf-monitor--explain {
+  width: 19rem;
+}
+
 .perf-hud > .perf-monitor {
   position: relative;
   z-index: 1;
@@ -1682,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,
@@ -1757,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),
@@ -1766,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-BLs1jkwM.js.map
+//# sourceMappingURL=mount-perf-hud-DqY_tP6s.js.map