@zkmake/three-meter 0.9.2 → 0.11.0

package/README.md

@@ -142,18 +142,30 @@ 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 }
+// { frames: 1000, lowFps: 97.6, p99Ms: 10.2, hitches: 3, refreshHz: 120 }
 ```
 
+## Refresh rate and headroom
+
+**Refresh** is the rate the loop runs at when it keeps up: the display's refresh rate, or the app's
+own cap if it throttles itself. It comes from the fastest tenth of recent frames, with each interval
+averaged against the next so a late frame and the early one after it don't read as a faster display,
+then snapped to a common rate (60, 120, 144, …). It needs 60 frames.
+
+**Headroom** is the spare time in each frame: the frame budget minus whichever of CPU and GPU took
+longer. At 120 Hz with 3 ms of GPU work that's 5.3 ms. Below zero, frames miss the display's refresh,
+and the row turns amber.
+
 ## 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:
+Timing budgets come from `targetFps`: FPS at least 95% of it, 1% low at least half, CPU and GPU
+within one frame, frame p99 within one and a half, headroom at least zero. Leave `targetFps` out and
+they follow the detected refresh rate, so a 120 Hz display gets 8.3 ms budgets (60 until it's
+detected). 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 } });
@@ -166,7 +178,7 @@ hud.setBudgets({ gpu: null }); // null drops a default; false drops them all
 
 The HUD tells you there are 400 draw calls; **top costs** tells you which objects they come from.
 Tick it in the full view for the five biggest costs in the main render pass, grouped by **meshes** or
-**materials**, sorted by draw calls or triangles. Click a row to log its three objects to the
+**materials**, sorted by draw calls or triangles. Click a row's name to log its three objects to the
 console.
 
 ```text
@@ -186,9 +198,18 @@ walks the scene only while open, twice a second.
 
 ```ts
 monitor.getSceneCost();
-// { calls: 309, triangles: 57548, meshes: [{ label: "tree", calls: 300, … }, …], materials: […] }
+// { calls: 309, triangles: 57548, meshes: [{ key: "mesh:tree…", label: "tree", calls: 300, … }, …], materials: […] }
 ```
 
+### Test a cost by hiding it
+
+Calls and triangles aren't time. The eye on each row hides its objects, every copy in the scene
+including ones off screen, and the row then shows what that saved: GPU time averaged over 30 frames
+before and after hiding (CPU time where there's no GPU timer), like `−4.3 ms GPU`. Hidden rows stay
+listed so you can show them again. Everything comes back when you untick top costs or the HUD is
+disposed, and objects that were already invisible stay that way. `monitor.getObjectsForKey(key)`
+returns the same objects for a row's `key`.
+
 ## Bug reports
 
 The **report** row's copy button puts a Markdown snapshot on the clipboard: versions, backend, GPU,
@@ -196,9 +217,9 @@ the current metrics, the stutter stats, the top three meshes, the viewport and t
 `formatReport(monitor)` from `@zkmake/three-meter/ui` returns the same text.
 
 ```text
-three-meter v0.7.0 · three r186 · WebGL2 · Apple M4 Max
+three-meter v0.10.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
+CPU 0.2 ms · GPU 0.7 ms · refresh 120 Hz · headroom 7.6 ms
 Calls 1 · passes 1 · triangles 24,000 · lines 0 · points 0
 Geometries 1 · textures 1 · shaders 1
 Top: tree ×300 (300 calls, 9,600 tris) · house (6 calls, 12 tris) · dome (2 calls, 7,936 tris)
@@ -256,12 +277,35 @@ The resolved theme lands on `data-theme` of `.perf-hud` and `.perf-monitor`. To
 palette, override the `--perf-*` custom properties (`bg`, `fg`, `fg-dim`, `muted`, `row`,
 `border`, `accent`, `warn`, `shadow`) on those selectors. `warn` is the over-budget amber.
 
+## The dev-panel frame
+
+The HUD's frame is `mountDevPanel` from `@zkmake/three-meter/ui`: the docked host, a card with a
+brand label on top, and the drag / expand-compact / dim-on-leave discs. Other zkmake dev panels
+(`@zkmake/three-textures`) mount through it too, so they all dock, wake, dim and theme the same way.
+A tool of your own can use it:
+
+```ts
+const panel = mountDevPanel({
+  brand: "my-tool",
+  label: "My tool",
+  content: myElement,
+  theme: new HudTheme("system"),
+  storageKey: "my-tool",
+  onToggle: () => myElement.classList.toggle("is-compact"),
+});
+
+panel.detail.textContent = "3 items"; // the brand row's right-hand slot
+```
+
+The card is `.perf-hud__card`, holding `.perf-hud__brand` and your content (the HUD's is
+`.perf-monitor`).
+
 ## Examples
 
-[`examples/site`](https://github.com/zkmake/three-kit/tree/main/examples/site) is what runs at [three-meter.pages.dev](https://three-meter.pages.dev/):
+[`apps/three-meter-site`](https://github.com/zkmake/three-kit/tree/main/apps/three-meter-site) is what runs at [three-meter.pages.dev](https://three-meter.pages.dev/):
 one Vite app with both integrations of the same scene, swapped from the header.
-[`src/demos/vanilla.ts`](https://github.com/zkmake/three-kit/blob/main/examples/site/src/demos/vanilla.ts) is plain three with `mountPerfHud`;
-[`src/demos/r3f.tsx`](https://github.com/zkmake/three-kit/blob/main/examples/site/src/demos/r3f.tsx) is React Three Fiber with `PerfSampler` and
+[`src/demos/vanilla.ts`](https://github.com/zkmake/three-kit/blob/main/apps/three-meter-site/src/demos/vanilla.ts) is plain three with `mountPerfHud`;
+[`src/demos/r3f.tsx`](https://github.com/zkmake/three-kit/blob/main/apps/three-meter-site/src/demos/r3f.tsx) is React Three Fiber with `PerfSampler` and
 `PerfHud`. Both set a 250K triangle budget on top of the timing defaults. `?r3f` opens on Fiber,
 `?webgpu` uses `WebGPURenderer` in either, `?count=` scales the scene. The header's theme toggle sets the page theme and the HUD's `theme` layer together; the row
 inside the panel overrides the HUD alone. Run `bun run dev` inside it after a `bun install` at the repo root.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as GpuTiming, c as RenderBackend, d as Sample, f as SceneCost, i as FrameStats, l as RenderCounts, n as CostEntry, o as PerfRenderer, p as TimingMetric, r as Environment, s as PerformanceMonitorOptions, t as PerformanceMonitor, u as ResourceCounts } from "./performance-monitor-DgHxeQ2X.js";
+import { a as GpuTiming, c as RenderBackend, d as Sample, f as SceneCost, i as FrameStats, l as RenderCounts, n as CostEntry, o as PerfRenderer, p as TimingMetric, r as Environment, s as PerformanceMonitorOptions, t as PerformanceMonitor, u as ResourceCounts } from "./performance-monitor-BoY_-GTt.js";
 //#region src/core/ring-buffer.d.ts
 /**
  * Fixed-capacity numeric ring buffer. Backs the per-frame timing history the

package/dist/index.js

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