@zkmake/three-meter 0.1.1 → 0.3.0

package/README.md

@@ -8,6 +8,10 @@ geometries, textures and programs, with a small dockable HUD. Zero dependencies.
 bun add -d @zkmake/three-meter   # or npm i -D / pnpm add -D
 ```
 
+Live demo: [three-meter.pages.dev](https://three-meter.pages.dev/), with a vanilla three and a
+React Three Fiber take on the same scene. Add `?webgpu` for the WebGPU renderer and `?count=5000` to
+load the scene up.
+
 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,
@@ -68,18 +72,46 @@ Canvas is its own React root. To run two canvases on one page, pass the same `st
 
 `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.                                                                                |
+| Option             | Default            | Meaning                                                                                       |
+| ------------------ | ------------------ | --------------------------------------------------------------------------------------------- |
+| `mode`             | `"compact"`        | `compact` is the card. `full` is the checkbox list that configures it.                        |
+| `theme`            | `"system"`         | `dark`, `light`, or `system` to follow `prefers-color-scheme` live. A pick in the panel wins. |
+| `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).
 
+## Theme
+
+The HUD ships a dark and a light palette. Two layers decide which shows:
+
+1. **The panel's own pick.** The full view has a light / system / dark row. A pick there is kept
+   with the other settings under `storageKey` and wins while set.
+2. **Your `theme` option.** `dark`, `light`, or `system` (the default), which follows the OS and
+   switches when it does. Applies whenever the person using the HUD hasn't picked anything.
+
+Change your layer later from the handle, or from the `PerfHud` prop in React, which applies without
+remounting:
+
+```ts
+const hud = mountPerfHud(monitor, { theme: "system" });
+hud.setTheme("light"); // your layer: "dark" | "light" | "system"
+hud.getTheme(); // your layer, as asked for
+hud.settings.theme; // the panel's pick, or null
+hud.settings.setTheme(null); // clear the pick so your layer applies again
+hud.theme.effective; // whichever layer is in force
+hud.theme.resolved; // "dark" | "light", what is on screen right now
+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.
+
 ## GPU timing
 
 On WebGL2 the monitor uses `EXT_disjoint_timer_query_webgl2`, which Chrome and Edge expose. Safari
@@ -89,9 +121,13 @@ On WebGPU, construct the renderer with `trackTimestamp: true`. Timings resolve a
 
 ## 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.
+[`examples/site`](examples/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
+`PerfHud`. `?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.
 
 ## Shipping it
 
@@ -105,7 +141,7 @@ your call. Gate the import in the app with a `?debug=` query, a build flag or a
 
 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`.
+custom properties on `.perf-hud` and `.perf-monitor`, or the `theme` option.
 
 ## Contributing
 

package/dist/{mount-perf-hud-Dw8KNQTt.d.ts → mount-perf-hud-B3wBLrcu.d.ts}

@@ -32,11 +32,58 @@ type DockHandle = {
  */
 declare const dockPanel: (element: HTMLElement, options?: DockPanelOptions) => DockHandle;
 //#endregion
+//#region src/ui/theme.d.ts
+/**
+ * Dark, light, or follow the OS. One instance per HUD: the floating host and
+ * the card inside it both paint `resolved` onto `data-theme`, and the
+ * stylesheet picks the palette from that attribute.
+ *
+ * Two layers. `mode` is what the consumer asked for (the `theme` option,
+ * `setTheme`). `override` is what the person using the HUD picked in the
+ * panel, kept in `HudSettings`; it wins while set. `effective` is whichever
+ * applies, and `system` there tracks `prefers-color-scheme` for as long as
+ * the instance lives.
+ */
+type ThemeMode = "dark" | "light" | "system";
+type ResolvedTheme = Exclude<ThemeMode, "system">;
+declare const THEME_MODES: readonly ThemeMode[];
+declare const isThemeMode: (value: unknown) => value is ThemeMode;
+declare class HudTheme {
+  private current;
+  private userPick;
+  private readonly listeners;
+  private media;
+  private readonly onSchemeChange;
+  constructor(mode?: ThemeMode);
+  /** What the consumer asked for. */
+  get mode(): ThemeMode;
+  /** What the person using the HUD picked in the panel, or `null` for no pick. */
+  get override(): ThemeMode | null;
+  /** The layer that applies: the user's pick if there is one, else the consumer's mode. */
+  get effective(): ThemeMode;
+  /**
+   * `dark` or `light`, with `system` resolved against the OS preference.
+   * Where `matchMedia` is missing, `system` falls back to `dark`, the HUD's
+   * original palette.
+   */
+  get resolved(): ResolvedTheme;
+  setMode(mode: ThemeMode): void;
+  setOverride(mode: ThemeMode | null): void;
+  /** Fires on `setMode`, `setOverride` and, in `system`, whenever the OS preference flips. */
+  subscribe(listener: () => void): () => void;
+  /** Stop tracking the OS preference and drop every subscriber. */
+  dispose(): void;
+  private watch;
+  private unwatch;
+  private notify;
+}
+//#endregion
 //#region src/ui/hud-settings.d.ts
 type HudSelection = {
   dim: boolean;
   graphs: ReadonlySet<TimingMetric>;
   numbers: ReadonlySet<string>;
+  theme: ThemeMode | null;
 };
 type HudDefaults = {
   dim?: boolean;
@@ -59,6 +106,9 @@ declare class HudSettings {
   get selection(): HudSelection;
   get dim(): boolean;
   setDim(enabled: boolean): void;
+  /** The user's pick in the panel; `null` means none, so the consumer's option applies. */
+  get theme(): ThemeMode | null;
+  setTheme(mode: ThemeMode | null): void;
   isNumberEnabled(key: string): boolean;
   isGraphEnabled(metric: TimingMetric): boolean;
   setNumberEnabled(key: string, enabled: boolean): void;
@@ -78,6 +128,11 @@ type PerformanceViewOptions = {
   refreshHz?: number;
   /** Share one between views to keep them in sync; a fresh instance otherwise. */
   settings?: HudSettings;
+  /**
+   * Share the host's so the card and its chrome switch together. Otherwise a
+   * fresh `system` instance is created and disposed with the view.
+   */
+  theme?: HudTheme;
 };
 /**
  * Host-agnostic widget that paints {@link Sample}s. Mount {@link element}
@@ -88,6 +143,9 @@ type PerformanceViewOptions = {
 declare class PerformanceView {
   readonly element: HTMLDivElement;
   readonly settings: HudSettings;
+  readonly theme: HudTheme;
+  private readonly ownsTheme;
+  private readonly unsubscribeTheme;
   private readonly monitor;
   private readonly minIntervalMs;
   private mode;
@@ -97,6 +155,7 @@ declare class PerformanceView {
   private readonly statValueEls;
   private readonly statCheckboxes;
   private dimCheckbox;
+  private readonly themeRadios;
   private hudGraphsEl;
   private hudGridEl;
   private readonly hudGraphs;
@@ -118,6 +177,8 @@ declare class PerformanceView {
   private build;
   private rebuildHud;
   private onSelectionChanged;
+  /** Repaint the palette and mark the radio matching what applies (pick, else consumer mode). */
+  private onThemeChanged;
   private buildCheckbox;
   private applyModeClass;
   private resizeCanvases;
@@ -127,6 +188,12 @@ declare class PerformanceView {
 type MountPerfHudOptions = {
   /** Start compact (the card) or full (the checkbox list). Default `compact`. */
   mode?: PerformanceViewMode;
+  /**
+   * `dark`, `light`, or `system` to follow the OS preference. Default
+   * `system`. Change it later with the handle's `setTheme`. A pick made in
+   * the panel's own theme row (kept in `settings`) sits on top of this.
+   */
+  theme?: ThemeMode;
   /** localStorage key for the selection and the dock. `null` disables persistence. */
   storageKey?: string | null;
   /** Bring your own; otherwise one is created from `storageKey`. */
@@ -146,11 +213,21 @@ type PerfHudHandle = {
   element: HTMLDivElement;
   view: PerformanceView;
   settings: HudSettings;
+  /**
+   * `mode` is the consumer layer, `override` the panel's pick, `effective`
+   * whichever applies, `resolved` the `dark` / `light` on screen. Subscribe
+   * for changes, including the OS preference moving under `system`.
+   */
+  theme: HudTheme;
   getMode: () => PerformanceViewMode;
   setMode: (mode: PerformanceViewMode) => void;
+  /** The consumer layer. The panel's pick, if any, is `settings.theme`. */
+  getTheme: () => ThemeMode;
+  /** Sets the consumer layer; a pick made in the panel still wins until `settings.setTheme(null)`. */
+  setTheme: (mode: ThemeMode) => void;
   dispose: () => void;
 };
 declare const mountPerfHud: (monitor: PerformanceMonitor, options?: MountPerfHudOptions) => PerfHudHandle;
 //#endregion
-export { ScreenEdge as _, PerformanceViewMode as a, HudDefaults as c, HudSettingsOptions as d, DefaultPlacement as f, Placement as g, DockPanelOptions as h, PerformanceView as i, HudSelection as l, DockHandle as m, PerfHudHandle as n, PerformanceViewOptions as o, DockAlign as p, mountPerfHud as r, DEFAULT_STORAGE_KEY as s, MountPerfHudOptions as t, HudSettings as u, dockPanel as v };
-//# sourceMappingURL=mount-perf-hud-Dw8KNQTt.d.ts.map
+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-B3wBLrcu.d.ts.map