@zkmake/three-meter 0.4.0 → 0.6.0

package/README.md

@@ -16,7 +16,7 @@ load the scene up.
   <img
     src="https://raw.githubusercontent.com/zkmake/three-meter/main/docs/hud-full.png"
     width="320"
-    alt="The HUD in full mode, dark theme: a theme row (light, system, dark), a dim-on-leave toggle, FPS, CPU and GPU sparklines with live values, and a checkbox list of counters (FPS, calls, CPU, GPU, triangles, lines, points, render passes, geometries, textures, shaders) choosing what the compact card shows. Two discs beside it: a drag grip and the compact/full toggle."
+    alt="The HUD in full mode, dark theme. Option rows for theme (light, system, dark), dim on leave, explain metrics and a copy-report button; FPS, CPU and GPU sparklines with live values; then one row per metric, each with an icon, its value and a checkbox choosing whether the compact card shows it (FPS, calls, CPU, GPU, 1% low, frame p99, hitches, triangles, lines, points, render passes, geometries, textures, shaders); and a footer with the three-meter version, the three revision, a WebGL2 backend badge and the GPU name. Two discs beside it: a drag grip and the compact/full toggle."
   />
 </p>
 
@@ -90,8 +90,8 @@ 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.                                                                                 |
 
-`PerformanceMonitor` and `PerfSampler` take `trackGPU` (default true), `gpuQueryPoolSize` (default 5)
-and `historySize` (default 120).
+`PerformanceMonitor` and `PerfSampler` take `trackGPU` (default true), `gpuQueryPoolSize` (default 5),
+`historySize` (default 120) and `frameStatsSize` (default 1000).
 
 ## Theme
 
@@ -143,6 +143,45 @@ monitor.getEnvironment();
 WebGL's unmasked renderer string, and is `null` where the browser hides it. Chrome's WebGPU gives
 vendor and architecture, not the model.
 
+## Reading the panel
+
+Every row has an icon, its value, and a checkbox on the right that puts it in the compact HUD. Hover
+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).
+
+## Stutter
+
+Average FPS hides a hitch every few seconds. Three rows in the full view catch it, and any of them
+can be ticked into the compact HUD:
+
+- **1% low**: mean FPS across the slowest 1% of frames.
+- **Frame p99**: 99% of frames finish within this many ms.
+- **Hitches**: frames over twice the median frame time.
+
+They cover the last `frameStatsSize` frames (1000 by default, about 16 s at 60 Hz). Gaps over a
+second, like a hidden tab, are left out. Read them with `monitor.getFrameStats()`:
+
+```ts
+monitor.getFrameStats();
+// { frames: 1000, lowFps: 97.6, p99Ms: 10.2, hitches: 3 }
+```
+
+## Bug reports
+
+The **report** row's copy button puts a Markdown snapshot on the clipboard: versions, backend, GPU,
+the current metrics, the stutter stats, the viewport and the user agent. Paste it into an issue.
+`formatReport(monitor)` from `@zkmake/three-meter/ui` returns the same text.
+
+```text
+three-meter v0.5.0 · three r186 · WebGL2 · Apple M4 Max
+FPS 120 · 1% low 98 · p99 10.2 ms · hitches 3 / 1,000 frames
+CPU 0.2 ms · GPU 0.7 ms
+Calls 1 · passes 1 · triangles 24,000 · lines 0 · points 0
+Geometries 1 · textures 1 · shaders 1
+Viewport 1280×720 @2x
+Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) …
+```
+
 ## Examples
 
 [`examples/site`](examples/site) is what runs at [three-meter.pages.dev](https://three-meter.pages.dev/):

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as PerformanceMonitorOptions, c as ResourceCounts, i as PerfRenderer, l as Sample, n as Environment, o as RenderBackend, r as GpuTiming, s as RenderCounts, t as PerformanceMonitor, u as TimingMetric } from "./performance-monitor-Br7x3cPt.js";
+import { a as PerfRenderer, c as RenderCounts, d as TimingMetric, i as GpuTiming, l as ResourceCounts, n as Environment, o as PerformanceMonitorOptions, r as FrameStats, s as RenderBackend, t as PerformanceMonitor, u as Sample } from "./performance-monitor-CBN05_BC.js";
 //#region src/core/ring-buffer.d.ts
 /**
  * Fixed-capacity numeric ring buffer. Backs the per-frame timing history the
@@ -32,5 +32,5 @@ type AnimationLoop<Args extends unknown[]> = (...args: Args) => void;
  */
 declare function wrapAnimationLoop<Args extends unknown[]>(monitor: PerformanceMonitor, loop: AnimationLoop<Args>): AnimationLoop<Args>;
 //#endregion
-export { type Environment, type GpuTiming, type PerfRenderer, PerformanceMonitor, type PerformanceMonitorOptions, type RenderBackend, type RenderCounts, type ResourceCounts, RingBuffer, type Sample, type TimingMetric, wrapAnimationLoop };
+export { type Environment, type FrameStats, type GpuTiming, type PerfRenderer, PerformanceMonitor, type PerformanceMonitorOptions, type RenderBackend, type RenderCounts, type ResourceCounts, RingBuffer, type Sample, type TimingMetric, wrapAnimationLoop };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as RingBuffer, t as PerformanceMonitor } from "./performance-monitor-C8dhWJWR.js";
+import { n as RingBuffer, t as PerformanceMonitor } from "./performance-monitor-yxsxs57v.js";
 //#region src/core/wrap-animation-loop.ts
 /**
 * Wrap a `renderer.setAnimationLoop` callback so each tick is one frame:

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

@@ -453,9 +453,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\"/>",
@@ -476,7 +493,42 @@ const createIcon = (name, className) => {
 };
 //#endregion
 //#region package.json
-var version = "0.4.0";
+var version = "0.6.0";
+//#endregion
+//#region src/ui/clipboard.ts
+/**
+* Copy text from a click handler. The async Clipboard API needs a secure
+* context and the `clipboard-write` permission; a dev server opened over a LAN
+* IP has neither, and some embeds deny the permission. The fallback is the old
+* select-a-textarea `execCommand("copy")`, still honoured inside a user gesture.
+*/
+const copyWithSelection = (text) => {
+	const textarea = document.createElement("textarea");
+	textarea.value = text;
+	textarea.setAttribute("readonly", "");
+	textarea.style.position = "fixed";
+	textarea.style.opacity = "0";
+	textarea.style.pointerEvents = "none";
+	const previous = document.activeElement;
+	document.body.append(textarea);
+	textarea.select();
+	try {
+		return document.execCommand("copy");
+	} catch {
+		return false;
+	} finally {
+		textarea.remove();
+		previous?.focus?.();
+	}
+};
+const copyText = async (text) => {
+	try {
+		await navigator.clipboard.writeText(text);
+		return true;
+	} catch {
+		return copyWithSelection(text);
+	}
+};
 //#endregion
 //#region src/ui/format.ts
 /**
@@ -493,6 +545,99 @@ 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
+* GPU, the current sample, stutter stats and the page. Fenced as a `text`
+* code block so GitHub and Slack keep the line breaks.
+*/
+const BACKEND_LABELS = {
+	webgl: "WebGL",
+	webgl2: "WebGL2",
+	webgpu: "WebGPU"
+};
+/** `WebGPU`, `WebGL2`, `WebGL2 fallback`, or `""` before the backend settles. */
+const backendLabel = (environment) => {
+	if (!environment.backend) return "";
+	const label = BACKEND_LABELS[environment.backend];
+	return environment.fallback ? `${label} fallback` : label;
+};
+const ms = (value) => `${value.toFixed(1)} ms`;
+const renderReport = ({ environment, page, sample, stats }) => {
+	const { render, resources } = sample;
+	const heading = [
+		`three-meter v${version}`,
+		environment.three ? `three r${environment.three}` : "",
+		backendLabel(environment),
+		environment.gpu ?? ""
+	].filter(Boolean);
+	const frames = stats.frames === 0 ? `FPS ${Math.round(sample.fps)}` : [
+		`FPS ${Math.round(sample.fps)}`,
+		`1% low ${Math.round(stats.lowFps)}`,
+		`p99 ${ms(stats.p99Ms)}`,
+		`hitches ${formatCount(stats.hitches)} / ${formatCount(stats.frames)} frames`
+	].join(" · ");
+	const lines = [
+		heading.join(" · "),
+		frames,
+		`CPU ${ms(sample.cpu)} · GPU ${sample.gpu.available ? ms(sample.gpu.ms) : "unavailable"}`,
+		[
+			`Calls ${formatCount(render.calls)}`,
+			`passes ${formatCount(render.passes)}`,
+			`triangles ${formatCount(render.triangles)}`,
+			`lines ${formatCount(render.lines)}`,
+			`points ${formatCount(render.points)}`
+		].join(" · "),
+		[
+			`Geometries ${formatCount(resources.geometries)}`,
+			`textures ${formatCount(resources.textures)}`,
+			`shaders ${formatCount(resources.programs)}`
+		].join(" · ")
+	];
+	if (page) lines.push(`Viewport ${page.width}×${page.height} @${page.dpr}x`, page.userAgent);
+	return [
+		"```text",
+		...lines,
+		"```"
+	].join("\n");
+};
+const readPage = () => typeof window === "undefined" ? null : {
+	dpr: window.devicePixelRatio || 1,
+	height: window.innerHeight,
+	userAgent: navigator.userAgent,
+	width: window.innerWidth
+};
+/** The report for `monitor` right now, as Markdown ready to paste into an issue. */
+const formatReport = (monitor) => renderReport({
+	environment: monitor.getEnvironment(),
+	page: readPage(),
+	sample: monitor.getSample(),
+	stats: monitor.getFrameStats()
+});
+//#endregion
 //#region src/ui/sparkline.ts
 function drawSparkline(ctx, width, height, values, style) {
 	ctx.clearRect(0, 0, width, height);
@@ -519,6 +664,7 @@ function drawSparkline(ctx, width, height, values, style) {
 const TIMINGS = [
 	{
 		format: (value) => Math.round(value).toString(),
+		icon: "gauge",
 		label: "FPS",
 		metric: "fps",
 		style: {
@@ -535,6 +681,7 @@ const TIMINGS = [
 	},
 	{
 		format: (value) => value.toFixed(1),
+		icon: "cpu",
 		label: "CPU",
 		metric: "cpu",
 		style: {
@@ -551,6 +698,7 @@ const TIMINGS = [
 	},
 	{
 		format: (value) => value.toFixed(1),
+		icon: "zap",
 		label: "GPU",
 		metric: "gpu",
 		style: {
@@ -584,16 +732,8 @@ const THEME_OPTIONS = [
 	}
 ];
 const RELEASE_URL = `https://github.com/zkmake/three-meter/releases/tag/v${version}`;
-const BACKEND_LABELS = {
-	webgl: "WebGL",
-	webgl2: "WebGL2",
-	webgpu: "WebGPU"
-};
-const backendLabel = (environment) => {
-	if (!environment.backend) return "";
-	const label = BACKEND_LABELS[environment.backend];
-	return environment.fallback ? `${label} fallback` : label;
-};
+/** How long the report button says `copied` / `failed` before reading `copy` again. */
+const COPY_FEEDBACK_MS = 1500;
 const readTiming = (sample, metric) => {
 	switch (metric) {
 		case "fps": return sample.fps;
@@ -604,56 +744,85 @@ const readTiming = (sample, metric) => {
 const isTimingAvailable = (sample, metric) => metric !== "gpu" || sample.gpu.available;
 const NUMBERS = [
 	{
+		icon: "gauge",
 		key: "fps",
 		label: "FPS",
 		read: (sample) => Math.round(sample.fps).toString()
 	},
 	{
+		icon: "layers",
 		key: "calls",
 		label: "Calls",
 		read: (sample) => formatCount(sample.render.calls)
 	},
 	{
+		icon: "cpu",
 		key: "cpu",
 		label: "CPU",
 		read: (sample) => sample.cpu.toFixed(1)
 	},
 	{
+		icon: "zap",
 		key: "gpu",
 		label: "GPU",
 		read: (sample) => sample.gpu.available ? sample.gpu.ms.toFixed(1) : "—"
 	},
 	{
+		icon: "trendingDown",
+		key: "low",
+		label: "1% low",
+		read: (_sample, stats) => stats.frames ? Math.round(stats.lowFps).toString() : "—"
+	},
+	{
+		icon: "timer",
+		key: "p99",
+		label: "Frame p99",
+		read: (_sample, stats) => stats.frames ? stats.p99Ms.toFixed(1) : "—"
+	},
+	{
+		icon: "activity",
+		key: "hitches",
+		label: "Hitches",
+		read: (_sample, stats) => stats.frames ? formatCount(stats.hitches) : "—"
+	},
+	{
+		icon: "triangle",
 		key: "triangles",
 		label: "Triangles",
 		read: (sample) => formatCount(sample.render.triangles)
 	},
 	{
+		icon: "spline",
 		key: "lines",
 		label: "Lines",
 		read: (sample) => formatCount(sample.render.lines)
 	},
 	{
+		icon: "circleDot",
 		key: "points",
 		label: "Points",
 		read: (sample) => formatCount(sample.render.points)
 	},
 	{
+		icon: "repeat",
 		key: "passes",
 		label: "Render passes",
 		read: (sample) => formatCount(sample.render.passes)
 	},
 	{
+		icon: "box",
 		key: "geometries",
 		label: "Geometries",
 		read: (sample) => formatCount(sample.resources.geometries)
 	},
 	{
+		icon: "image",
 		key: "textures",
 		label: "Textures",
 		read: (sample) => formatCount(sample.resources.textures)
 	},
 	{
+		icon: "palette",
 		key: "shaders",
 		label: "Shaders",
 		read: (sample) => formatCount(sample.resources.programs)
@@ -760,7 +929,8 @@ var PerformanceView = class {
 			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 NUMBERS) this.statValueEls.get(config.key).textContent = config.read(sample);
+		const stats = this.monitor.getFrameStats();
+		for (const config of NUMBERS) this.statValueEls.get(config.key).textContent = config.read(sample, stats);
 		this.renderFooter();
 	}
 	/** The monitor caches the environment once its backend settles; until then this re-reads. */
@@ -782,9 +952,10 @@ var PerformanceView = class {
 		this.footerHardwareEl.hidden = backend === "" && gpu === "";
 	}
 	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) element.textContent = config.read(sample);
+			if (config && stats) element.textContent = config.read(sample, stats);
 		}
 		for (const [metric, graph] of this.hudGraphs) {
 			const config = TIMINGS.find((timing) => timing.metric === metric);
@@ -836,7 +1007,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);
+		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) {
@@ -844,21 +1022,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");
@@ -879,14 +1061,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");
@@ -914,7 +1101,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() {
@@ -935,6 +1122,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 = "—";
@@ -960,6 +1148,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 = "—";
@@ -983,6 +1172,31 @@ var PerformanceView = class {
 		applyTheme(this.element, this.theme);
 		for (const [mode, radio] of this.themeRadios) radio.setAttribute("aria-checked", String(mode === this.theme.effective));
 	}
+	buildReportRow() {
+		const row = document.createElement("div");
+		row.className = "perf-monitor__row perf-monitor__row--static";
+		const label = document.createElement("span");
+		label.className = "perf-monitor__label";
+		label.textContent = "report";
+		const button = document.createElement("button");
+		button.type = "button";
+		button.className = "perf-monitor__button";
+		button.title = "Copy versions, GPU and current metrics as Markdown for a bug report";
+		button.textContent = "copy";
+		let resetTimer = 0;
+		const flash = (text) => {
+			button.textContent = text;
+			window.clearTimeout(resetTimer);
+			resetTimer = window.setTimeout(() => {
+				button.textContent = "copy";
+			}, COPY_FEEDBACK_MS);
+		};
+		button.addEventListener("click", () => {
+			copyText(formatReport(this.monitor)).then((copied) => flash(copied ? "copied" : "failed"));
+		});
+		row.append(createIcon("clipboard", "perf-monitor__icon"), label, button);
+		return row;
+	}
 	buildCheckbox(checked, title, onChange) {
 		const checkbox = document.createElement("input");
 		checkbox.type = "checkbox";
@@ -1109,8 +1323,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 {
@@ -1142,6 +1357,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);
 }
@@ -1211,6 +1445,27 @@ const PERF_HUD_STYLES = `
   color: inherit;
 }
 
+.perf-monitor__button {
+  flex: none;
+  min-width: 7ch;
+  padding: 0 6px;
+  border: 1px solid var(--perf-border);
+  border-radius: 3px;
+  background: var(--perf-row);
+  color: var(--perf-fg-dim);
+  font: inherit;
+  cursor: pointer;
+}
+
+.perf-monitor__button:hover {
+  color: var(--perf-fg);
+}
+
+.perf-monitor__button:focus-visible {
+  outline: 1px solid color-mix(in srgb, var(--perf-accent) 60%, transparent);
+  outline-offset: 1px;
+}
+
 .perf-monitor__checkbox {
   flex: none;
   margin: 0;
@@ -1353,7 +1608,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;
 }
 
@@ -1384,6 +1640,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;
@@ -1605,6 +1866,6 @@ const mountPerfHud = (monitor, options = {}) => {
 	};
 };
 //#endregion
-export { dockPanel as a, HudTheme as c, PerformanceView as i, THEME_MODES as l, PERF_HUD_STYLES as n, DEFAULT_STORAGE_KEY as o, injectStyles as r, HudSettings as s, mountPerfHud as t, isThemeMode as u };
+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 };
 
-//# sourceMappingURL=mount-perf-hud-Rf98QNxM.js.map
+//# sourceMappingURL=mount-perf-hud-C5wdjgmM.js.map