@zkmake/three-meter 0.9.2 → 0.10.0

package/dist/{mount-perf-hud-BL84ddLm.js → mount-perf-hud-U_Xlj0Od.js}

@@ -1,17 +1,24 @@
 //#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 FLOORS = /* @__PURE__ */ new Set([
+	"fps",
+	"headroom",
+	"low"
+]);
+/** `detectedHz` is the monitor's refresh reading; an explicit `targetFps` wins over it. */
+const resolveBudgets = (budgets, detectedHz = null) => {
+	const targetFps = budgets && budgets.targetFps || detectedHz || DEFAULT_TARGET_FPS;
 	const frameMs = 1e3 / targetFps;
 	if (budgets === false) return {
 		frameMs,
-		limits: {}
+		limits: {},
+		targetFps
 	};
 	const merged = {
 		cpu: frameMs,
 		fps: targetFps * .95,
 		gpu: frameMs,
+		headroom: 0,
 		low: targetFps / 2,
 		p99: frameMs * 1.5,
 		...budgets
@@ -20,7 +27,8 @@ const resolveBudgets = (budgets) => {
 	for (const [key, limit] of Object.entries(merged)) if (key !== "targetFps" && typeof limit === "number" && Number.isFinite(limit)) limits[key] = limit;
 	return {
 		frameMs,
-		limits
+		limits,
+		targetFps
 	};
 };
 const isFloor = (key) => FLOORS.has(key);
@@ -486,6 +494,9 @@ const dockPanel = (element, options = {}) => {
 //#endregion
 //#region src/ui/icons.ts
 const ICON_MARKUP = {
+	eye: "<path d=\"M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0\"/><circle cx=\"12\" cy=\"12\" r=\"3\"/>",
+	eyeOff: "<path d=\"M10.733 5.076a10.744 10.744 0 0 1 11.205 6.575 1 1 0 0 1 0 .696 10.747 10.747 0 0 1-1.444 2.49\"/><path d=\"M14.084 14.158a3 3 0 0 1-4.242-4.242\"/><path d=\"M17.479 17.499a10.75 10.75 0 0 1-15.417-5.151 1 1 0 0 1 0-.696 10.75 10.75 0 0 1 4.446-5.143\"/><path d=\"m2 2 20 20\"/>",
+	hourglass: "<path d=\"M5 22h14\"/><path d=\"M5 2h14\"/><path d=\"M17 22v-4.172a2 2 0 0 0-.586-1.414L12 12l-4.414 4.414A2 2 0 0 0 7 17.828V22\"/><path d=\"M7 2v4.172a2 2 0 0 0 .586 1.414L12 12l4.414-4.414A2 2 0 0 0 17 6.172V2\"/>",
 	flame: "<path d=\"M8.5 14.5A2.5 2.5 0 0 0 11 12c0-1.38-.5-2-1-3-1.072-2.143-.224-4.054 2-6 .5 2.5 2 4.9 4 6.5 2 1.6 3 3.5 3 5.5a7 7 0 1 1-14 0c0-1.153.433-2.294 1-3a2.5 2.5 0 0 0 2.5 2.5z\"/>",
 	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\"/>",
@@ -528,7 +539,7 @@ const createIcon = (name, className) => {
 //#endregion
 //#region package.json
 var name = "@zkmake/three-meter";
-var version = "0.9.2";
+var version = "0.10.0";
 //#endregion
 //#region src/ui/clipboard.ts
 /**
@@ -580,6 +591,45 @@ 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/hider.ts
+var Hider = class {
+	groups = /* @__PURE__ */ new Map();
+	/** Each hidden object's `visible` from before the first group hid it. */
+	original = /* @__PURE__ */ new Map();
+	hide(key, objects) {
+		if (this.groups.has(key)) return;
+		const hideable = objects.filter((object) => typeof object === "object" && object !== null);
+		this.groups.set(key, hideable);
+		for (const object of hideable) {
+			if (!this.original.has(object)) this.original.set(object, object.visible !== false);
+			object.visible = false;
+		}
+	}
+	show(key) {
+		const objects = this.groups.get(key);
+		if (!objects) return;
+		this.groups.delete(key);
+		for (const object of objects) if (!this.heldElsewhere(object)) {
+			object.visible = this.original.get(object) ?? true;
+			this.original.delete(object);
+		}
+	}
+	isHidden(key) {
+		return this.groups.has(key);
+	}
+	/** Hidden group keys, in the order they were hidden. */
+	keys() {
+		return [...this.groups.keys()];
+	}
+	restoreAll() {
+		for (const key of this.keys()) this.show(key);
+	}
+	heldElsewhere(object) {
+		for (const objects of this.groups.values()) if (objects.includes(object)) return true;
+		return false;
+	}
+};
+//#endregion
 //#region src/ui/metric-help.ts
 /**
 * One plain-language line per metric: what it is, and what a bad reading
@@ -591,6 +641,8 @@ const METRIC_HELP = {
 	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.",
+	headroom: "Spare time left in each frame: the frame budget minus whichever of CPU and GPU took longer. Below zero, frames miss the display's refresh.",
+	refresh: "The rate the loop runs at when it keeps up: the display's refresh rate, or the app's own cap. Budgets use it unless you set targetFps.",
 	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.",
@@ -641,10 +693,15 @@ const renderReport = ({ cost, environment, page, sample, stats }) => {
 		`p99 ${ms(stats.p99Ms)}`,
 		`hitches ${formatCount(stats.hitches)} / ${formatCount(stats.frames)} frames`
 	].join(" · ");
+	const timing = [`CPU ${ms(sample.cpu)}`, `GPU ${sample.gpu.available ? ms(sample.gpu.ms) : "unavailable"}`];
+	if (stats.refreshHz) {
+		const busiest = Math.max(sample.cpu, sample.gpu.available ? sample.gpu.ms : 0);
+		timing.push(`refresh ${stats.refreshHz} Hz`, `headroom ${ms(1e3 / stats.refreshHz - busiest)}`);
+	}
 	const lines = [
 		heading.join(" · "),
 		frames,
-		`CPU ${ms(sample.cpu)} · GPU ${sample.gpu.available ? ms(sample.gpu.ms) : "unavailable"}`,
+		timing.join(" · "),
 		[
 			`Calls ${formatCount(render.calls)}`,
 			`passes ${formatCount(render.passes)}`,
@@ -799,7 +856,15 @@ const COST_GROUPS = [{
 	group: "materials",
 	label: "materials"
 }];
-const COSTS_HELP = "The scene's biggest draw costs in the main render pass, estimated from the scene graph. Hidden and off-screen objects are left out; shadow and post-processing passes aren't counted. Click a row to log its objects to the console.";
+const COSTS_HELP = "The scene's biggest draw costs in the main render pass, estimated from the scene graph. Hidden and off-screen objects are left out; shadow and post-processing passes aren't counted. Click a row to log its objects to the console; use the eye to hide them and measure the time they cost.";
+/** Frames averaged on each side of hiding a row. */
+const MEASURE_FRAMES = 30;
+/** How long after hiding before the saving is read, so the average holds only frames without the row. */
+const MEASURE_SETTLE_MS = 700;
+const meanOfLast = (values, count) => {
+	const tail = values.slice(-count);
+	return tail.length === 0 ? 0 : tail.reduce((sum, value) => sum + value, 0) / tail.length;
+};
 /** `×2,000` for instances or copies; nothing for a single object. */
 const copiesOf = (entry) => entry.instances > 1 ? `×${formatCount(entry.instances)}` : "";
 const costTitle = (entry) => {
@@ -848,6 +913,22 @@ const NUMBERS = [
 		unit: "ms",
 		value: (sample) => sample.gpu.available ? sample.gpu.ms : null
 	},
+	{
+		format: tenths,
+		icon: "hourglass",
+		key: "headroom",
+		label: "Headroom",
+		unit: "ms",
+		value: (sample, _stats, frameMs) => sample.fps ? frameMs - Math.max(sample.cpu, sample.gpu.available ? sample.gpu.ms : 0) : null
+	},
+	{
+		format: (value) => `${Math.round(value)} Hz`,
+		icon: "monitor",
+		key: "refresh",
+		label: "Refresh",
+		unit: "Hz",
+		value: (_sample, stats) => stats.refreshHz
+	},
 	{
 		format: whole,
 		icon: "trendingDown",
@@ -971,6 +1052,10 @@ var PerformanceView = class {
 	hudGraphs = /* @__PURE__ */ new Map();
 	hudNumberEls = /* @__PURE__ */ new Map();
 	budgets;
+	budgetsInput;
+	detectedHz = null;
+	hider = new Hider();
+	hiddenRows = /* @__PURE__ */ new Map();
 	rafId = null;
 	lastPaintAt = 0;
 	resizeObserver;
@@ -991,6 +1076,7 @@ var PerformanceView = class {
 		this.theme.setOverride(this.settings.theme);
 		this.mode = options.mode ?? "full";
 		this.minIntervalMs = 1e3 / (options.refreshHz ?? 10);
+		this.budgetsInput = options.budgets;
 		this.budgets = resolveBudgets(options.budgets);
 		this.element = document.createElement("div");
 		this.element.className = "perf-monitor";
@@ -1023,11 +1109,13 @@ var PerformanceView = class {
 	}
 	/** Replace the budgets; `false` turns them all off. Applies on the next paint. */
 	setBudgets(budgets) {
-		this.budgets = resolveBudgets(budgets);
+		this.budgetsInput = budgets;
+		this.budgets = resolveBudgets(budgets, this.detectedHz);
 		this.applyBudgetTitles();
 	}
 	dispose() {
 		this.stop();
+		this.showAllHidden();
 		this.unsubscribe();
 		this.unsubscribeTheme();
 		if (this.ownsTheme) this.theme.dispose();
@@ -1042,13 +1130,14 @@ var PerformanceView = class {
 	};
 	render() {
 		const sample = this.monitor.getSample();
+		const stats = this.monitor.getFrameStats();
+		this.followRefresh(stats.refreshHz);
 		if (this.mode === "compact") {
-			this.renderHud(sample);
+			this.renderHud(sample, stats);
 			if (this.settings.info) this.renderFooter();
 			return;
 		}
 		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.paintNumber(config, this.statValueEls.get(config.key), sample, stats);
 		if (this.costsOpen && performance.now() - this.lastCostsAt >= COSTS_INTERVAL_MS) this.renderCosts();
 		this.renderFooter();
@@ -1056,44 +1145,102 @@ var PerformanceView = class {
 	renderCosts() {
 		this.lastCostsAt = performance.now();
 		const cost = this.monitor.getSceneCost();
+		const hidden = [...this.hiddenRows.values()].map((row) => this.hiddenCostRow(row));
 		if (!cost) {
-			this.costsListEl.replaceChildren(this.costsNote("No scene rendered yet."));
+			this.costsListEl.replaceChildren(...hidden, this.costsNote("No scene rendered yet."));
 			return;
 		}
-		const entries = [...this.costGroup === "meshes" ? cost.meshes : cost.materials];
+		const entries = (this.costGroup === "meshes" ? cost.meshes : cost.materials).filter((entry) => !this.hiddenRows.has(entry.key));
 		if (this.costSort === "triangles") entries.sort((a, b) => b.triangles - a.triangles || b.calls - a.calls);
-		if (entries.length === 0) {
+		if (entries.length === 0 && hidden.length === 0) {
 			this.costsListEl.replaceChildren(this.costsNote("Nothing drawn."));
 			return;
 		}
 		const rows = entries.slice(0, COSTS_ROWS).map((entry) => {
-			const row = document.createElement("button");
-			row.type = "button";
-			row.className = "perf-monitor__cost";
-			row.title = costTitle(entry);
-			const name = document.createElement("span");
-			name.className = "perf-monitor__cost-name";
-			name.textContent = entry.label;
-			const copies = copiesOf(entry);
-			if (copies) {
-				const suffix = document.createElement("span");
-				suffix.className = "perf-monitor__cost-copies";
-				suffix.textContent = ` ${copies}`;
-				name.append(suffix);
-			}
+			const row = this.costRowShell(entry);
 			const calls = document.createElement("span");
 			calls.className = "perf-monitor__cost-value";
 			calls.textContent = formatCount(entry.calls);
 			const triangles = document.createElement("span");
 			triangles.className = "perf-monitor__cost-value";
 			triangles.textContent = formatCount(entry.triangles);
-			row.append(name, calls, triangles);
-			row.addEventListener("click", () => {
-				console.log(`three-meter: ${entry.label}`, entry.objects);
-			});
+			row.append(calls, triangles, this.eyeButton(entry, false));
 			return row;
 		});
-		this.costsListEl.replaceChildren(...rows);
+		this.costsListEl.replaceChildren(...hidden, ...rows);
+	}
+	/** Name button (logs the objects) in a row; the caller appends the value cells and the eye. */
+	costRowShell(entry) {
+		const row = document.createElement("div");
+		row.className = "perf-monitor__cost";
+		const name = document.createElement("button");
+		name.type = "button";
+		name.className = "perf-monitor__cost-name";
+		name.title = costTitle(entry);
+		name.textContent = entry.label;
+		const copies = copiesOf(entry);
+		if (copies) {
+			const suffix = document.createElement("span");
+			suffix.className = "perf-monitor__cost-copies";
+			suffix.textContent = ` ${copies}`;
+			name.append(suffix);
+		}
+		name.addEventListener("click", () => {
+			console.log(`three-meter: ${entry.label}`, entry.objects);
+		});
+		row.append(name);
+		return row;
+	}
+	/** A hidden row: what hiding it saved, measured from the timing history. */
+	hiddenCostRow(hidden) {
+		const row = this.costRowShell(hidden.entry);
+		row.classList.add("is-hidden");
+		const saved = document.createElement("span");
+		saved.className = "perf-monitor__cost-saved";
+		const label = hidden.metric.toUpperCase();
+		if (performance.now() - hidden.hiddenAt < MEASURE_SETTLE_MS) saved.textContent = "measuring…";
+		else {
+			const now = meanOfLast(this.monitor.getHistory(hidden.metric), MEASURE_FRAMES);
+			const delta = hidden.baseline - now;
+			saved.textContent = `${delta >= 0 ? "−" : "+"}${Math.abs(delta).toFixed(1)} ms ${label}`;
+			saved.title = `${label} time went from ${hidden.baseline.toFixed(1)} ms to ${now.toFixed(1)} ms with this hidden, averaged over ${MEASURE_FRAMES} frames each side.`;
+		}
+		row.append(saved, this.eyeButton(hidden.entry, true));
+		return row;
+	}
+	eyeButton(entry, hidden) {
+		const eye = document.createElement("button");
+		eye.type = "button";
+		eye.className = "perf-monitor__cost-eye";
+		eye.setAttribute("aria-pressed", String(hidden));
+		const label = hidden ? `Show ${entry.label} again` : `Hide ${entry.label} to measure its cost`;
+		eye.title = label;
+		eye.setAttribute("aria-label", label);
+		eye.append(createIcon(hidden ? "eyeOff" : "eye", "perf-monitor__icon"));
+		eye.addEventListener("click", () => hidden ? this.showRow(entry.key) : this.hideRow(entry));
+		return eye;
+	}
+	hideRow(entry) {
+		const metric = this.monitor.getSample().gpu.available ? "gpu" : "cpu";
+		this.hiddenRows.set(entry.key, {
+			baseline: meanOfLast(this.monitor.getHistory(metric), MEASURE_FRAMES),
+			entry,
+			hiddenAt: performance.now(),
+			metric
+		});
+		const all = this.monitor.getObjectsForKey(entry.key);
+		this.hider.hide(entry.key, all.length > 0 ? all : entry.objects);
+		this.renderCosts();
+	}
+	showRow(key) {
+		this.hider.show(key);
+		this.hiddenRows.delete(key);
+		this.renderCosts();
+	}
+	/** Everything hidden goes back: on closing top costs and on dispose. */
+	showAllHidden() {
+		this.hider.restoreAll();
+		this.hiddenRows.clear();
 	}
 	costsNote(text) {
 		const note = document.createElement("div");
@@ -1119,11 +1266,17 @@ var PerformanceView = class {
 		this.footerGpuEl.title = gpu;
 		this.footerHardwareEl.hidden = backend === "" && gpu === "";
 	}
-	renderHud(sample) {
-		const stats = this.hudNumberEls.size > 0 ? this.monitor.getFrameStats() : null;
+	/** Budgets follow the detected refresh rate unless `targetFps` was given. */
+	followRefresh(hz) {
+		if (hz === this.detectedHz) return;
+		this.detectedHz = hz;
+		this.budgets = resolveBudgets(this.budgetsInput, hz);
+		this.applyBudgetTitles();
+	}
+	renderHud(sample, stats) {
 		for (const [key, element] of this.hudNumberEls) {
 			const config = NUMBER_BY_KEY.get(key);
-			if (config && stats) this.paintNumber(config, element, sample, stats);
+			if (config) this.paintNumber(config, element, sample, stats);
 		}
 		for (const [metric, graph] of this.hudGraphs) {
 			const config = TIMINGS.find((timing) => timing.metric === metric);
@@ -1131,7 +1284,7 @@ var PerformanceView = class {
 		}
 	}
 	paintNumber(config, element, sample, stats) {
-		const value = config.value(sample, stats);
+		const value = config.value(sample, stats, this.budgets.frameMs);
 		element.textContent = value === null ? "—" : config.format(value);
 		element.classList.toggle("is-over", isOverBudget(this.budgets, config.key, value));
 	}
@@ -1371,6 +1524,7 @@ var PerformanceView = class {
 		const checkbox = this.buildCheckbox(false, "Show the scene's biggest draw costs", (on) => {
 			this.costsOpen = on;
 			this.costsBodyEl.hidden = !on;
+			if (!on) this.showAllHidden();
 			if (on) this.renderCosts();
 		});
 		toggleRow.append(createIcon("flame", "perf-monitor__icon"), label, checkbox);
@@ -1414,6 +1568,7 @@ var PerformanceView = class {
 			this.costSortButtons.set(sort, button);
 			head.append(button);
 		}
+		head.append(document.createElement("span"));
 		this.costsListEl = document.createElement("div");
 		this.costsListEl.className = "perf-monitor__costs-list";
 		const hint = document.createElement("span");
@@ -1732,11 +1887,10 @@ const PERF_HUD_STYLES = `
 }
 
 .perf-monitor__cost {
-  /* Rows are buttons, which shrink to their content without a width. */
   box-sizing: border-box;
   width: 100%;
   display: grid;
-  grid-template-columns: minmax(0, 1fr) 5ch 6ch;
+  grid-template-columns: minmax(0, 1fr) 5ch 6ch 14px;
   gap: 6px;
   align-items: baseline;
   padding: 2px 6px;
@@ -1746,13 +1900,58 @@ const PERF_HUD_STYLES = `
   color: inherit;
   font: inherit;
   text-align: left;
-  cursor: pointer;
+  cursor: default;
 }
 
 .perf-monitor__cost:not(.perf-monitor__cost--head):hover {
   background: var(--perf-row);
 }
 
+.perf-monitor__cost.is-hidden .perf-monitor__cost-name {
+  opacity: 0.6;
+  text-decoration: line-through;
+}
+
+/* What hiding saved, across the calls and tris columns. */
+.perf-monitor__cost-saved {
+  grid-column: 2 / span 2;
+  color: var(--perf-accent);
+  font-variant-numeric: tabular-nums lining-nums;
+  text-align: right;
+  white-space: nowrap;
+}
+
+.perf-monitor__cost-eye {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 14px;
+  padding: 0;
+  border: 0;
+  border-radius: 3px;
+  background: transparent;
+  color: var(--perf-muted);
+  cursor: pointer;
+  align-self: center;
+}
+
+.perf-monitor__cost-eye .perf-monitor__icon {
+  width: 12px;
+  height: 12px;
+  color: inherit;
+}
+
+.perf-monitor__cost-eye:hover,
+.perf-monitor__cost-eye[aria-pressed="true"] {
+  color: var(--perf-fg);
+}
+
+.perf-monitor__cost-eye:focus-visible {
+  outline: 1px solid color-mix(in srgb, var(--perf-accent) 60%, transparent);
+  outline-offset: 1px;
+}
+
 .perf-monitor__cost:focus-visible {
   outline: 1px solid color-mix(in srgb, var(--perf-accent) 60%, transparent);
   outline-offset: -1px;
@@ -1763,13 +1962,30 @@ const PERF_HUD_STYLES = `
   cursor: default;
 }
 
+/* The name is a button: a click logs the row's objects. */
 .perf-monitor__cost-name {
+  min-width: 0;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
   color: var(--perf-fg-dim);
 }
 
+.perf-monitor__cost-name:hover {
+  color: var(--perf-fg);
+}
+
+.perf-monitor__cost-name:focus-visible {
+  outline: 1px solid color-mix(in srgb, var(--perf-accent) 60%, transparent);
+  outline-offset: 1px;
+}
+
 .perf-monitor__cost-copies {
   color: var(--perf-muted);
 }
@@ -2236,4 +2452,4 @@ const mountPerfHud = (monitor, options = {}) => {
 //#endregion
 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-BL84ddLm.js.map
+//# sourceMappingURL=mount-perf-hud-U_Xlj0Od.js.map