@zkmake/three-meter 0.9.1 → 0.10.0

package/README.md

@@ -22,19 +22,19 @@ load the scene up past the demo's triangle budget.
   <tr>
     <th>Dark</th>
     <td valign="top">
-      <img src="https://raw.githubusercontent.com/zkmake/three-meter/main/docs/hud-full.png" width="318" alt="The HUD in full mode, dark theme. Option rows for theme (light, system, dark), explain metrics and a copy-report button; FPS, CPU and GPU sparklines with live values, the FPS graph showing a dashed budget line; 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), with the triangle count in amber for being over its budget; a top costs toggle; and a footer with the three-meter version, the three revision, a WebGL2 backend badge and the GPU name. Three discs beside it: a drag grip, the compact/full toggle and dim on leave." />
+      <img src="https://raw.githubusercontent.com/zkmake/three-kit/main/docs/hud-full.png" width="318" alt="The HUD in full mode, dark theme. Option rows for theme (light, system, dark), explain metrics and a copy-report button; FPS, CPU and GPU sparklines with live values, the FPS graph showing a dashed budget line; 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), with the triangle count in amber for being over its budget; a top costs toggle; and a footer with the three-meter version, the three revision, a WebGL2 backend badge and the GPU name. Three discs beside it: a drag grip, the compact/full toggle and dim on leave." />
     </td>
     <td valign="top">
-      <img src="https://raw.githubusercontent.com/zkmake/three-meter/main/docs/hud-compact.png" width="314" alt="The HUD collapsed, dark theme: FPS and GPU sparklines with a dashed budget line on the FPS graph, a two-column grid of metrics with icons (FPS, calls, CPU, GPU, 1% low, frame p99, triangles in amber for being over budget, geometries, textures, shaders), and the footer with versions, backend and GPU. Three discs beside it: drag, expand and dim on leave." />
+      <img src="https://raw.githubusercontent.com/zkmake/three-kit/main/docs/hud-compact.png" width="314" alt="The HUD collapsed, dark theme: FPS and GPU sparklines with a dashed budget line on the FPS graph, a two-column grid of metrics with icons (FPS, calls, CPU, GPU, 1% low, frame p99, triangles in amber for being over budget, geometries, textures, shaders), and the footer with versions, backend and GPU. Three discs beside it: drag, expand and dim on leave." />
     </td>
   </tr>
   <tr>
     <th>Light</th>
     <td valign="top">
-      <img src="https://raw.githubusercontent.com/zkmake/three-meter/main/docs/hud-full-light.png" width="318" alt="The HUD in full mode, light theme. Option rows for theme (light, system, dark), explain metrics and a copy-report button; FPS, CPU and GPU sparklines with live values, the FPS graph showing a dashed budget line; 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), with the triangle count in amber for being over its budget; a top costs toggle; and a footer with the three-meter version, the three revision, a WebGL2 backend badge and the GPU name. Three discs beside it: a drag grip, the compact/full toggle and dim on leave." />
+      <img src="https://raw.githubusercontent.com/zkmake/three-kit/main/docs/hud-full-light.png" width="318" alt="The HUD in full mode, light theme. Option rows for theme (light, system, dark), explain metrics and a copy-report button; FPS, CPU and GPU sparklines with live values, the FPS graph showing a dashed budget line; 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), with the triangle count in amber for being over its budget; a top costs toggle; and a footer with the three-meter version, the three revision, a WebGL2 backend badge and the GPU name. Three discs beside it: a drag grip, the compact/full toggle and dim on leave." />
     </td>
     <td valign="top">
-      <img src="https://raw.githubusercontent.com/zkmake/three-meter/main/docs/hud-compact-light.png" width="314" alt="The HUD collapsed, light theme: FPS and GPU sparklines with a dashed budget line on the FPS graph, a two-column grid of metrics with icons (FPS, calls, CPU, GPU, 1% low, frame p99, triangles in amber for being over budget, geometries, textures, shaders), and the footer with versions, backend and GPU. Three discs beside it: drag, expand and dim on leave." />
+      <img src="https://raw.githubusercontent.com/zkmake/three-kit/main/docs/hud-compact-light.png" width="314" alt="The HUD collapsed, light theme: FPS and GPU sparklines with a dashed budget line on the FPS graph, a two-column grid of metrics with icons (FPS, calls, CPU, GPU, 1% low, frame p99, triangles in amber for being over budget, geometries, textures, shaders), and the footer with versions, backend and GPU. Three discs beside it: drag, expand and dim on leave." />
     </td>
   </tr>
 </table>
@@ -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)
@@ -258,13 +279,13 @@ palette, override the `--perf-*` custom properties (`bg`, `fg`, `fg-dim`, `muted
 
 ## Examples
 
-[`examples/site`](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`](examples/site/src/demos/vanilla.ts) is plain three with `mountPerfHud`;
-[`src/demos/r3f.tsx`](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.
+inside the panel overrides the HUD alone. Run `bun run dev` inside it after a `bun install` at the repo root.
 
 ## Shipping it
 
@@ -282,7 +303,7 @@ custom properties on `.perf-hud` and `.perf-monitor`, or the `theme` option.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). Changes ship with a changeset.
+See [CONTRIBUTING.md](https://github.com/zkmake/three-kit/blob/main/CONTRIBUTING.md). Changes ship with a changeset.
 
 ## License
 

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:

package/dist/{mount-perf-hud-BKpk62Pp.d.ts → mount-perf-hud-MTPYNhG9.d.ts}

@@ -1,27 +1,32 @@
-import { p as TimingMetric, t as PerformanceMonitor } from "./performance-monitor-DgHxeQ2X.js";
+import { p as TimingMetric, t as PerformanceMonitor } from "./performance-monitor-BoY_-GTt.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).
+ * line once the series reaches it. `fps`, `low` and `headroom` 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.
+ * Timing budgets default from `targetFps`: FPS at least 95% of it, 1% low at
+ * least half, CPU and GPU within one frame, p99 within one and a half,
+ * headroom at least zero. Without a `targetFps`, the detected refresh rate is
+ * used, then 60 until one is detected.
  * 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 BudgetKey = "calls" | "cpu" | "fps" | "geometries" | "gpu" | "headroom" | "hitches" | "lines" | "low" | "p99" | "passes" | "points" | "refresh" | "shaders" | "textures" | "triangles";
 type Budgets = Partial<Record<BudgetKey, number | null>> & {
-  /** The frame rate the defaults are derived from. Default 60. */
+  /** The frame rate the defaults are derived from. Default: the detected refresh rate, else 60. */
   targetFps?: number;
 };
 type ResolvedBudgets = {
   /** Frame budget in ms, `1000 / targetFps`. */
   frameMs: number;
+  /** The rate the timing budgets came from: `targetFps`, the detected refresh, or 60. */
+  targetFps: number;
   limits: Partial<Record<BudgetKey, number>>;
 };
-declare const resolveBudgets: (budgets: Budgets | false | undefined) => ResolvedBudgets;
+/** `detectedHz` is the monitor's refresh reading; an explicit `targetFps` wins over it. */
+declare const resolveBudgets: (budgets: Budgets | false | undefined, detectedHz?: number | null) => ResolvedBudgets;
 //#endregion
 //#region src/ui/dock-panel.d.ts
 declare const EDGES: readonly ["left", "right", "top", "bottom"];
@@ -200,6 +205,10 @@ declare class PerformanceView {
   private readonly hudGraphs;
   private readonly hudNumberEls;
   private budgets;
+  private budgetsInput;
+  private detectedHz;
+  private readonly hider;
+  private readonly hiddenRows;
   private rafId;
   private lastPaintAt;
   private readonly resizeObserver;
@@ -223,9 +232,20 @@ declare class PerformanceView {
   private frame;
   private render;
   private renderCosts;
+  /** Name button (logs the objects) in a row; the caller appends the value cells and the eye. */
+  private costRowShell;
+  /** A hidden row: what hiding it saved, measured from the timing history. */
+  private hiddenCostRow;
+  private eyeButton;
+  private hideRow;
+  private showRow;
+  /** Everything hidden goes back: on closing top costs and on dispose. */
+  private showAllHidden;
   private costsNote;
   /** The monitor caches the environment once its backend settles; until then this re-reads. */
   private renderFooter;
+  /** Budgets follow the detected refresh rate unless `targetFps` was given. */
+  private followRefresh;
   private renderHud;
   private paintNumber;
   /** Value and sparkline, with the budget line drawn once the series reaches it. */
@@ -301,4 +321,4 @@ type PerfHudHandle = {
 declare const mountPerfHud: (monitor: PerformanceMonitor, options?: MountPerfHudOptions) => PerfHudHandle;
 //#endregion
 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-BKpk62Pp.d.ts.map
+//# sourceMappingURL=mount-perf-hud-MTPYNhG9.d.ts.map