@zkmake/three-meter 0.13.2 → 0.14.0

package/README.md

@@ -62,11 +62,16 @@ Three Fiber, on `WebGLRenderer` and `WebGPURenderer`.
 
 ## Entry points
 
-| Import                      | What it is                                                                   |
-| --------------------------- | ---------------------------------------------------------------------------- |
-| `@zkmake/three-meter`       | `PerformanceMonitor`. `begin()` and `end()` bracket a frame. No DOM.         |
-| `@zkmake/three-meter/ui`    | `mountPerfHud(monitor, options)`, the dockable card. Vanilla DOM.            |
-| `@zkmake/three-meter/react` | `PerfSampler` inside `<Canvas>`, `PerfHud` outside it. Peers: react and r3f. |
+| Import                      | What it is                                                                                            |
+| --------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `@zkmake/three-meter`       | `PerformanceMonitor`. `begin()` and `end()` bracket a frame. No DOM.                                  |
+| `@zkmake/three-meter/ui`    | `mountPerfHud(monitor, options)`, the dockable card. Vanilla DOM.                                     |
+| `@zkmake/three-meter/react` | `PerfSampler` inside `<Canvas>`, `PerfHud` outside it, and `frameworkVersions`. Peers: react and r3f. |
+
+`/ui` also exports the pieces under the HUD, for a host composing its own panel: `PerformanceView`
+(the card's body), `HudSettings`, `HudTheme`, `mountDevPanel`, `dockPanel`, `injectStyles` and
+`PERF_HUD_STYLES`, `resolveBudgets`, `formatReport` and `formatQuality`. The core also exports
+`RingBuffer`, and `/react` `createPerfMonitorStore`.
 
 ## Vanilla three
 
@@ -92,6 +97,10 @@ monitor.dispose();
 If you run your own loop, call `monitor.begin()` before the frame's work and `monitor.end()` after
 the render.
 
+Without the HUD, read the monitor: `monitor.getSample()` is the last frame (`fps`, `cpu`,
+`gpu: { ms, available }`, `render` counts, `resources`), and `monitor.getHistory("fps" | "cpu" |
+"gpu")` the last `historySize` values the graphs draw.
+
 ## React Three Fiber
 
 ```tsx
@@ -109,7 +118,11 @@ import { PerfHud, PerfSampler } from "@zkmake/three-meter/react";
 
 `PerfHud` must sit outside `<Canvas>`, because Fiber treats HTML under it as three objects. The two
 components find each other through a small shared store. A React context can't do this, since the
-Canvas is its own React root. To run two canvases on one page, pass the same `store` prop to both.
+Canvas is its own React root. To run two canvases on one page, give each canvas's `PerfSampler` and
+its `PerfHud` the same `store` prop, one `createPerfMonitorStore()` per pair.
+
+`theme`, `mode`, `label`, `budgets` (by value) and `quality` apply live. `defaultPlacement` (by
+value), `storageKey`, `parent`, `refreshHz`, `injectStyles` and `store` remount the HUD.
 
 ## Options
 
@@ -124,9 +137,10 @@ Canvas is its own React root. To run two canvases on one page, pass the same `st
 | `parent`           | `document.body`    | Where the host element is appended.                                                           |
 | `injectStyles`     | `true`             | Append the stylesheet once per document.                                                      |
 | `refreshHz`        | `10`               | Repaint rate.                                                                                 |
-| `budgets`          | timing defaults    | Limits past which a value turns amber. See [Budgets](#budgets).                               |
+| `budgets`          | timing defaults    | Limits past which a value turns amber; `false` for none. See [Budgets](#budgets).             |
 | `quality`          | none               | Adaptive quality to show. See [Adaptive quality](#adaptive-quality).                          |
 | `label`            | `"Performance"`    | Accessible name of the panel.                                                                 |
+| `settings`         | from `storageKey`  | Your own `HudSettings`, e.g. with `defaults` for what a first visit shows. Not on `PerfHud`.  |
 
 `PerformanceMonitor` and `PerfSampler` take `trackGPU` (default true), `gpuQueryPoolSize` (default 5),
 `historySize` (default 120) and `frameStatsSize` (default 1000).
@@ -177,10 +191,16 @@ they follow the detected refresh rate, so a 120 Hz display gets 8.3 ms budgets (
 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 } });
+const hud = mountPerfHud(monitor, {
+  budgets: { targetFps: 120, calls: 500, triangles: 2_000_000 },
+});
 hud.setBudgets({ gpu: null }); // null drops a default; false drops them all
 ```
 
+A budget goes on any row by its key: `fps`, `cpu`, `gpu`, `headroom`, `refresh`, `low` (1% low),
+`p99`, `hitches`, `calls`, `triangles`, `lines`, `points`, `passes`, `geometries`, `textures`,
+`shaders`. `fps`, `low` and `headroom` are floors (amber below); the rest are ceilings.
+
 `PerfHud` takes the same `budgets` prop and applies changes live.
 
 An app that keeps its budgets in one file with [three-audit](../three-audit)'s `defineBudgets`
@@ -261,7 +281,7 @@ 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.10.0 · three r186 · WebGL2 · Apple M4 Max
+three-meter v0.10.0 · three r186 · React 19.3.1 · R3F 9.8.2 · 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 · refresh 120 Hz · headroom 7.6 ms
 Calls 1 · passes 1 · triangles 24,000 · lines 0 · points 0
@@ -273,16 +293,22 @@ Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) …
 
 ## Environment
 
-The full view's footer has two rows: the three-meter version (linked to its release notes) and the
-three revision, then the backend and the GPU name. An amber `WebGL2 fallback` badge means
+The full view's footer has the three-meter version (linked to its release notes) and the three
+revision, then the React and React Three Fiber versions when the app has them, then the backend and
+the GPU name. An amber `WebGL2 fallback` badge means
 `WebGPURenderer` couldn't get WebGPU. Its checkbox (off by default) shows the footer in the compact
 HUD too. The same data is on the monitor:
 
 ```ts
 monitor.getEnvironment();
-// { three: "186", backend: "webgpu", fallback: false, gpu: "Apple metal-3" }
+// { three: "186", react: "19.3.1", r3f: "9.8.2", backend: "webgpu", fallback: false, gpu: "Apple metal-3" }
 ```
 
+`react` and `r3f` come from `PerfSampler`, which reads them from `frameworkVersions` in
+`@zkmake/three-meter/react`, and three-devtools' `<DevTools>` does the same. The core imports neither, so a
+monitor you make yourself takes them as an option, `new PerformanceMonitor({ renderer, frameworks })`, and
+otherwise reports what React DevTools can tell, or `null`: on a vanilla app, that's the right answer.
+
 `backend` is `null` until `WebGPURenderer.init()` settles. `gpu` comes from WebGPU's adapter info or
 WebGL's unmasked renderer string, and is `null` where the browser hides it. Chrome's WebGPU gives
 vendor and architecture, not the model.
@@ -293,6 +319,10 @@ On WebGL2 the monitor uses `EXT_disjoint_timer_query_webgl2`, which Chrome and E
 and Firefox don't, so the GPU row shows `—` and `sample.gpu.available` is `false`.
 
 On WebGPU, construct the renderer with `trackTimestamp: true`. Timings resolve a frame or two late.
+The number is how long the GPU was busy in the frame, with overlapping passes counted once. three's
+own `resolveTimestampsAsync` sums every pass, which on tile-based GPUs (Apple, most mobile) reads
+a post-processing stack at several times its cost; the meter falls back to that sum when three's
+timestamp pool isn't the shape it knows.
 
 ## Theme
 
@@ -325,7 +355,8 @@ palette, override the `--perf-*` custom properties (`bg`, `fg`, `fg-dim`, `muted
 
 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.
+(`@zkmake/three-textures`, `@zkmake/three-cameras`) mount through it too, so they all dock, wake,
+dim and theme the same way.
 A tool of your own can use it:
 
 ```ts

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-CrYmNIdv.js";
+import { a as FrameworkVersions, c as PerformanceMonitorOptions, d as ResourceCounts, f as Sample, i as FrameStats, l as RenderBackend, m as TimingMetric, n as CostEntry, o as GpuTiming, p as SceneCost, r as Environment, s as PerfRenderer, t as PerformanceMonitor, u as RenderCounts } from "./performance-monitor-CH3GOcIm.js";
 /**
  * Fixed-capacity numeric ring buffer. Backs the per-frame timing history the
  * view reads to draw sparklines. Push is O(1); `toArray()` returns values in
@@ -28,5 +28,5 @@ type AnimationLoop<Args extends unknown[]> = (...args: Args) => void;
  * ```
  */
 declare function wrapAnimationLoop<Args extends unknown[]>(monitor: PerformanceMonitor, loop: AnimationLoop<Args>): AnimationLoop<Args>;
-export { type CostEntry, type Environment, type FrameStats, type GpuTiming, type PerfRenderer, PerformanceMonitor, type PerformanceMonitorOptions, type RenderBackend, type RenderCounts, type ResourceCounts, RingBuffer, type Sample, type SceneCost, type TimingMetric, wrapAnimationLoop };
+export { type CostEntry, type Environment, type FrameStats, type FrameworkVersions, type GpuTiming, type PerfRenderer, PerformanceMonitor, type PerformanceMonitorOptions, type RenderBackend, type RenderCounts, type ResourceCounts, RingBuffer, type Sample, type SceneCost, 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-Dj5H2VXT.js";
+import { n as RingBuffer, t as PerformanceMonitor } from "./performance-monitor-Bz3ukv7t.js";
 // src/core/wrap-animation-loop.ts
 /**
 * Wrap a `renderer.setAnimationLoop` callback so each tick is one frame:

package/dist/{mount-perf-hud-C0yuW5JI.d.ts → mount-perf-hud-Be8DNtkg.d.ts}

@@ -1,4 +1,4 @@
-import { p as TimingMetric, t as PerformanceMonitor } from "./performance-monitor-CrYmNIdv.js";
+import { m as TimingMetric, t as PerformanceMonitor } from "./performance-monitor-CH3GOcIm.js";
 /**
  * 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
@@ -234,6 +234,7 @@ declare class PerformanceView {
   private infoCheckbox;
   private readonly themeRadios;
   private footerThreeEl;
+  private footerFrameworksEl;
   private footerHardwareEl;
   private footerBackendEl;
   private footerGpuEl;
@@ -375,4 +376,4 @@ type PerfHudHandle = {
 };
 declare const mountPerfHud: (monitor: PerformanceMonitor, options?: MountPerfHudOptions) => PerfHudHandle;
 export { BudgetsInput as A, DockPanelOptions as C, AppBudgets as D, dockPanel as E, resolveBudgets as M, BudgetKey as O, DockHandle as S, ScreenEdge as T, THEME_MODES as _, PerformanceViewMode as a, DefaultPlacement as b, QualitySource as c, HudDefaults as d, HudSelection as f, ResolvedTheme as g, HudTheme as h, PerformanceView as i, ResolvedBudgets as j, Budgets as k, formatQuality as l, HudSettingsOptions as m, PerfHudHandle as n, PerformanceViewOptions as o, HudSettings as p, mountPerfHud as r, QualityReading as s, MountPerfHudOptions as t, DEFAULT_STORAGE_KEY as u, ThemeMode as v, Placement as w, DockAlign as x, isThemeMode as y };
-//# sourceMappingURL=mount-perf-hud-C0yuW5JI.d.ts.map
+//# sourceMappingURL=mount-perf-hud-Be8DNtkg.d.ts.map

package/dist/{mount-perf-hud-s8ezVm_5.js → mount-perf-hud-BtucU7nZ.js}

@@ -1428,7 +1428,7 @@ const mountDevPanel = (options) => {
 };
 // package.json
 var name = "@zkmake/three-meter";
-var version = "0.13.2";
+var version = "0.14.0";
 // src/ui/clipboard.ts
 /**
 * Copy text from a click handler. The async Clipboard API needs a secure
@@ -1568,6 +1568,9 @@ const BACKEND_LABELS = {
 	webgpu: "WebGPU"
 };
 /** `WebGPU`, `WebGL2`, `WebGL2 fallback`, or `""` before the backend settles. */
+const threeLabel = ({ three }) => three ? `three r${three}` : "";
+/** `React 19.3.1 · R3F 9.8.2`, as far as the monitor can tell. */
+const frameworksLabel = ({ react, r3f }) => [react ? `React ${react}` : "", r3f ? `R3F ${r3f}` : ""].filter(Boolean).join(" · ");
 const backendLabel = (environment) => {
 	if (!environment.backend) return "";
 	const label = BACKEND_LABELS[environment.backend];
@@ -1584,7 +1587,8 @@ const renderReport = ({ cost, environment, page, sample, stats }) => {
 	const { render, resources } = sample;
 	const heading = [
 		`three-meter v${version}`,
-		environment.three ? `three r${environment.three}` : "",
+		threeLabel(environment),
+		frameworksLabel(environment),
 		backendLabel(environment),
 		environment.gpu ?? ""
 	].filter(Boolean);
@@ -1942,6 +1946,7 @@ var PerformanceView = class {
 	infoCheckbox;
 	themeRadios = /* @__PURE__ */ new Map();
 	footerThreeEl;
+	footerFrameworksEl;
 	footerHardwareEl;
 	footerBackendEl;
 	footerGpuEl;
@@ -2164,13 +2169,16 @@ var PerformanceView = class {
 	/** The monitor caches the environment once its backend settles; until then this re-reads. */
 	renderFooter() {
 		const environment = this.monitor.getEnvironment();
-		const three = environment.three ? `three r${environment.three}` : "";
+		const three = threeLabel(environment);
+		const frameworks = frameworksLabel(environment);
 		const backend = backendLabel(environment);
 		const gpu = environment.gpu ?? "";
-		const key = `${three}\n${backend}\n${gpu}`;
+		const key = `${three}\n${frameworks}\n${backend}\n${gpu}`;
 		if (key === this.lastEnvironmentKey) return;
 		this.lastEnvironmentKey = key;
 		this.footerThreeEl.textContent = three;
+		this.footerFrameworksEl.textContent = frameworks;
+		this.footerFrameworksEl.hidden = frameworks === "";
 		this.footerBackendEl.textContent = backend;
 		this.footerBackendEl.hidden = backend === "";
 		this.footerBackendEl.title = environment.fallback ? "WebGPURenderer couldn't get WebGPU and fell back to WebGL2" : "";
@@ -2375,6 +2383,9 @@ var PerformanceView = class {
 		release.textContent = `three-meter v${version}`;
 		this.footerThreeEl = document.createElement("span");
 		softwareRow.append(release, this.footerThreeEl);
+		this.footerFrameworksEl = document.createElement("div");
+		this.footerFrameworksEl.className = "perf-monitor__footer-row";
+		this.footerFrameworksEl.hidden = true;
 		this.footerHardwareEl = document.createElement("div");
 		this.footerHardwareEl.className = "perf-monitor__footer-row";
 		this.footerHardwareEl.hidden = true;
@@ -2383,7 +2394,7 @@ var PerformanceView = class {
 		this.footerGpuEl = document.createElement("span");
 		this.footerGpuEl.className = "perf-monitor__footer-gpu";
 		this.footerHardwareEl.append(this.footerBackendEl, this.footerGpuEl);
-		footerBody.append(softwareRow, this.footerHardwareEl);
+		footerBody.append(softwareRow, this.footerFrameworksEl, this.footerHardwareEl);
 		footer.append(createIcon("info", "perf-monitor__icon"), footerBody, this.infoCheckbox);
 		this.element.append(hud, options, graphs, stats, this.buildCosts(), footer);
 	}
@@ -2648,4 +2659,4 @@ const mountPerfHud = (monitor, options = {}) => {
 };
 export { mountDevPanel as a, dockPanel as c, HudTheme as d, THEME_MODES as f, formatQuality as i, DEFAULT_STORAGE_KEY as l, resolveBudgets as m, PerformanceView as n, PERF_HUD_STYLES as o, isThemeMode as p, formatReport as r, injectStyles as s, mountPerfHud as t, HudSettings as u };
 
-//# sourceMappingURL=mount-perf-hud-s8ezVm_5.js.map
+//# sourceMappingURL=mount-perf-hud-BtucU7nZ.js.map