@zkmake/three-meter 0.5.0 → 0.7.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, then 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."
+    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>
 
@@ -89,6 +89,7 @@ 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).                               |
 
 `PerformanceMonitor` and `PerfSampler` take `trackGPU` (default true), `gpuQueryPoolSize` (default 5),
 `historySize` (default 120) and `frameStatsSize` (default 1000).
@@ -118,7 +119,7 @@ hud.theme.subscribe(() => syncMyPageWith(hud.theme.resolved));
 
 The resolved theme lands on `data-theme` of `.perf-hud` and `.perf-monitor`. To restyle either
 palette, override the `--perf-*` custom properties (`bg`, `fg`, `fg-dim`, `muted`, `row`,
-`border`, `accent`, `shadow`) on those selectors.
+`border`, `accent`, `warn`, `shadow`) on those selectors. `warn` is the over-budget amber.
 
 ## GPU timing
 
@@ -143,6 +144,29 @@ 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).
+
+## 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:
+
+```ts
+mountPerfHud(monitor, { budgets: { targetFps: 120, calls: 500, triangles: 2_000_000 } });
+hud.setBudgets({ gpu: null }); // null drops a default; false drops them all
+```
+
+`PerfHud` takes the same `budgets` prop and applies changes live.
+
 ## Stutter
 
 Average FPS hides a hitch every few seconds. Three rows in the full view catch it, and any of them

package/dist/{mount-perf-hud-CmINOH3T.d.ts → mount-perf-hud-6LeJ93Jg.d.ts}

@@ -1,4 +1,28 @@
 import { d as TimingMetric, t as PerformanceMonitor } from "./performance-monitor-CBN05_BC.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).
+ *
+ * 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.
+ * 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 Budgets = Partial<Record<BudgetKey, number | null>> & {
+  /** The frame rate the defaults are derived from. Default 60. */
+  targetFps?: number;
+};
+type ResolvedBudgets = {
+  /** Frame budget in ms, `1000 / targetFps`. */
+  frameMs: number;
+  limits: Partial<Record<BudgetKey, number>>;
+};
+declare const resolveBudgets: (budgets: Budgets | false | undefined) => ResolvedBudgets;
+//#endregion
 //#region src/ui/dock-panel.d.ts
 declare const EDGES: readonly ["left", "right", "top", "bottom"];
 type ScreenEdge = (typeof EDGES)[number];
@@ -131,6 +155,11 @@ type PerformanceViewOptions = {
   mode?: PerformanceViewMode;
   /** Repaint rate. Default 10. */
   refreshHz?: number;
+  /**
+   * Limits past which a value turns amber. Timing budgets default from
+   * `targetFps` (60); `false` turns them all off. See {@link Budgets}.
+   */
+  budgets?: Budgets | false;
   /** Share one between views to keep them in sync; a fresh instance otherwise. */
   settings?: HudSettings;
   /**
@@ -171,6 +200,7 @@ declare class PerformanceView {
   private hudGridEl;
   private readonly hudGraphs;
   private readonly hudNumberEls;
+  private budgets;
   private rafId;
   private lastPaintAt;
   private readonly resizeObserver;
@@ -180,12 +210,19 @@ declare class PerformanceView {
   stop(): void;
   setMode(mode: PerformanceViewMode): void;
   getMode(): PerformanceViewMode;
+  /** Replace the budgets; `false` turns them all off. Applies on the next paint. */
+  setBudgets(budgets: Budgets | false | undefined): void;
   dispose(): void;
   private frame;
   private render;
   /** The monitor caches the environment once its backend settles; until then this re-reads. */
   private renderFooter;
   private renderHud;
+  private paintNumber;
+  /** Value and sparkline, with the budget line drawn once the series reaches it. */
+  private paintGraph;
+  /** Each value's tooltip names its budget, so amber explains itself. */
+  private applyBudgetTitles;
   private formatTiming;
   private build;
   private rebuildHud;
@@ -221,6 +258,12 @@ type MountPerfHudOptions = {
   injectStyles?: boolean;
   /** Repaint rate. Default 10. */
   refreshHz?: number;
+  /**
+   * Limits past which a value turns amber, e.g. `{ calls: 500, targetFps: 120 }`.
+   * Timing budgets default from `targetFps` (60); `false` turns them all off.
+   * Change later with the handle's `setBudgets`.
+   */
+  budgets?: Budgets | false;
   /** Accessible name of the panel. Default `Performance`. */
   label?: string;
 };
@@ -240,9 +283,11 @@ type PerfHudHandle = {
   getTheme: () => ThemeMode;
   /** Sets the consumer layer; a pick made in the panel still wins until `settings.setTheme(null)`. */
   setTheme: (mode: ThemeMode) => void;
+  /** Replace the budgets; `false` turns them all off. */
+  setBudgets: (budgets: Budgets | false | undefined) => void;
   dispose: () => void;
 };
 declare const mountPerfHud: (monitor: PerformanceMonitor, options?: MountPerfHudOptions) => PerfHudHandle;
 //#endregion
-export { dockPanel as C, ScreenEdge as S, 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, Placement as x, DockHandle as y };
-//# sourceMappingURL=mount-perf-hud-CmINOH3T.d.ts.map
+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-6LeJ93Jg.d.ts.map