@zkmake/three-meter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zubin Khavarian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# @zkmake/three-meter
+
+Frame metrics for a three.js renderer: FPS, CPU ms, GPU ms, draw calls, render passes, triangles,
+geometries, textures and programs, with a small dockable HUD. Zero dependencies. Works with
+`WebGLRenderer` and `WebGPURenderer`, with or without React.
+
+```sh
+bun add -d @zkmake/three-meter   # or npm i -D / pnpm add -D
+```
+
+The sampler and the card are separate components, so toggling the HUD never remounts your canvas.
+GPU time is measured on WebGPU as well as WebGL. The counters are draw calls, render passes and
+resource counts, which is what you watch when a scene is instanced. The card docks to a screen edge,
+remembers where you put it, and hides its controls until the pointer comes near.
+
+## 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. |
+
+## Vanilla three
+
+```ts
+import { PerformanceMonitor, wrapAnimationLoop } from "@zkmake/three-meter";
+import { mountPerfHud } from "@zkmake/three-meter/ui";
+
+const monitor = new PerformanceMonitor({ renderer });
+const hud = mountPerfHud(monitor); // appends to document.body, docks left-centre
+
+renderer.setAnimationLoop(
+  wrapAnimationLoop(monitor, () => {
+    update();
+    renderer.render(scene, camera);
+  }),
+);
+
+// later
+hud.dispose();
+monitor.dispose();
+```
+
+If you run your own loop, call `monitor.begin()` before the frame's work and `monitor.end()` after
+the render.
+
+## React Three Fiber
+
+```tsx
+import { Canvas } from "@react-three/fiber";
+import { PerfHud, PerfSampler } from "@zkmake/three-meter/react";
+
+<>
+  <Canvas>
+    <PerfSampler />
+    {/* scene */}
+  </Canvas>
+  <PerfHud />
+</>;
+```
+
+`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.
+
+## Options
+
+`mountPerfHud` and `PerfHud` take:
+
+| Option             | Default            | Meaning                                                                                      |
+| ------------------ | ------------------ | -------------------------------------------------------------------------------------------- |
+| `mode`             | `"compact"`        | `compact` is the card. `full` is the checkbox list that configures it.                       |
+| `defaultPlacement` | `{ edge: "left" }` | First-visit dock, as `edge` plus `align` of `start`, `center` or `end`. A drag overrides it. |
+| `storageKey`       | `three-meter`      | localStorage key for the selection and the dock. `null` disables persistence.                |
+| `parent`           | `document.body`    | Where the host element is appended.                                                          |
+| `injectStyles`     | `true`             | Append the stylesheet once per document.                                                     |
+| `refreshHz`        | `10`               | Repaint rate.                                                                                |
+
+`PerformanceMonitor` and `PerfSampler` take `trackGPU` (default true), `gpuQueryPoolSize` (default 5)
+and `historySize` (default 120).
+
+## GPU timing
+
+On WebGL2 the monitor uses `EXT_disjoint_timer_query_webgl2`, which Chrome and Edge expose. Safari
+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.
+
+## Examples
+
+[`examples/vanilla`](examples/vanilla) is plain three. Add `?webgpu` to use `WebGPURenderer` and
+`?count=` to scale the scene. [`examples/r3f`](examples/r3f) is the React Three Fiber version. Each
+is a Vite app. Run `bun run dev` inside it.
+
+## Shipping it
+
+Styles inject at runtime by default. To link them instead, pass `injectStyles: false` and import
+`@zkmake/three-meter/styles.css`.
+
+The package never reads `NODE_ENV` or `import.meta.env`. Whether the HUD exists in production is
+your call. Gate the import in the app with a `?debug=` query, a build flag or a dynamic `import()`.
+
+## Contract
+
+While a monitor is attached, `renderer.info.autoReset` is off and `begin()` resets `info`. One
+monitor per renderer. A second throws. `dispose()` restores everything. Theme with the `--perf-*`
+custom properties on `.perf-monitor`.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Changes ship with a changeset.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { a as RenderCounts, c as TimingMetric, i as PerformanceMonitorOptions, n as GpuTiming, o as ResourceCounts, r as PerfRenderer, s as Sample, t as PerformanceMonitor } from "./performance-monitor-WGLWbxOZ.js";
+//#region src/core/ring-buffer.d.ts
+/**
+ * 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
+ * chronological (oldest → newest) order.
+ */
+declare class RingBuffer {
+  private readonly data;
+  private readonly capacity;
+  private head;
+  private count;
+  constructor(capacity: number);
+  push(value: number): void;
+  /** Values oldest → newest. Length grows up to capacity as samples accumulate. */
+  toArray(): number[];
+  clear(): void;
+}
+//#endregion
+//#region src/core/wrap-animation-loop.d.ts
+type AnimationLoop<Args extends unknown[]> = (...args: Args) => void;
+/**
+ * Wrap a `renderer.setAnimationLoop` callback so each tick closes the previous
+ * frame and opens the next, the same bracketing the R3F sampler does. CPU time
+ * therefore spans the whole tick (your update code plus the render dispatch).
+ *
+ * ```ts
+ * renderer.setAnimationLoop(wrapAnimationLoop(monitor, (time) => { … renderer.render(scene, camera); }));
+ * ```
+ */
+declare function wrapAnimationLoop<Args extends unknown[]>(monitor: PerformanceMonitor, loop: AnimationLoop<Args>): AnimationLoop<Args>;
+//#endregion
+export { type GpuTiming, type PerfRenderer, PerformanceMonitor, type PerformanceMonitorOptions, type RenderCounts, type ResourceCounts, RingBuffer, type Sample, type TimingMetric, wrapAnimationLoop };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,24 @@
+import { n as RingBuffer, t as PerformanceMonitor } from "./performance-monitor-qswCj9Nl.js";
+//#region src/core/wrap-animation-loop.ts
+/**
+* Wrap a `renderer.setAnimationLoop` callback so each tick closes the previous
+* frame and opens the next, the same bracketing the R3F sampler does. CPU time
+* therefore spans the whole tick (your update code plus the render dispatch).
+*
+* ```ts
+* renderer.setAnimationLoop(wrapAnimationLoop(monitor, (time) => { … renderer.render(scene, camera); }));
+* ```
+*/
+function wrapAnimationLoop(monitor, loop) {
+	let started = false;
+	return (...args) => {
+		if (started) monitor.end();
+		started = true;
+		monitor.begin();
+		loop(...args);
+	};
+}
+//#endregion
+export { PerformanceMonitor, RingBuffer, wrapAnimationLoop };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/core/wrap-animation-loop.ts"],"sourcesContent":["import type { PerformanceMonitor } from \"./performance-monitor.ts\";\n\ntype AnimationLoop<Args extends unknown[]> = (...args: Args) => void;\n\n/**\n * Wrap a `renderer.setAnimationLoop` callback so each tick closes the previous\n * frame and opens the next, the same bracketing the R3F sampler does. CPU time\n * therefore spans the whole tick (your update code plus the render dispatch).\n *\n * ```ts\n * renderer.setAnimationLoop(wrapAnimationLoop(monitor, (time) => { … renderer.render(scene, camera); }));\n * ```\n */\nfunction wrapAnimationLoop<Args extends unknown[]>(\n  monitor: PerformanceMonitor,\n  loop: AnimationLoop<Args>,\n): AnimationLoop<Args> {\n  let started = false;\n\n  return (...args) => {\n    if (started) {\n      monitor.end();\n    }\n\n    started = true;\n    monitor.begin();\n    loop(...args);\n  };\n}\n\nexport { wrapAnimationLoop };\n"],"mappings":";;;;;;;;;;;AAaA,SAAS,kBACP,SACA,MACqB;CACrB,IAAI,UAAU;CAEd,QAAQ,GAAG,SAAS;EAClB,IAAI,SACF,QAAQ,IAAI;EAGd,UAAU;EACV,QAAQ,MAAM;EACd,KAAK,GAAG,IAAI;CACd;AACF"}