webgpu-profiler 0.1.0

package/src/react/MemoryHUD.tsx

@@ -0,0 +1,438 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import {
+  profileMemory,
+  reportToText,
+  type MemoryReport,
+  type TextureEntry,
+  type BufferEntry,
+} from "../profiler.js";
+import {
+  getActiveInstrumentation,
+  subscribeActiveInstrumentation,
+  type DeviceInstrumentation,
+} from "../instrument.js";
+
+/**
+ * Viewport-pinned overlay that polls {@link profileMemory} on a timer and
+ * renders a copyable breakdown of all GPU memory the page has allocated
+ * through `device.createBuffer` / `device.createTexture`.
+ *
+ * Self-contained (no external CSS, no design-token dependency). Default
+ * styling is a dark transparent panel. Re-skin via `style` / `className`.
+ *
+ * Each section (Textures / Render targets / Buffers) is independently
+ * scrollable, so the HUD never overflows the viewport.
+ */
+
+export interface MemoryHUDProps {
+  /**
+   * Optional. When omitted, the HUD reads the active instrumentation set
+   * by `instrumentDevice()` or `autoInstrument()` via subscription. Pass
+   * explicitly if you're managing multiple devices.
+   */
+  instrumentation?: DeviceInstrumentation | null;
+  refreshMs?: number;
+  corner?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * React hook that subscribes to the active instrumentation. Re-renders
+ * the calling component when `instrumentDevice` or `autoInstrument` sets
+ * (or clears) the global handle.
+ */
+function useActiveInstrumentation(): DeviceInstrumentation | null {
+  return useSyncExternalStore(
+    subscribeActiveInstrumentation,
+    getActiveInstrumentation,
+    () => null,
+  );
+}
+
+const DEFAULT_REFRESH_MS = 1000;
+const SECTION_MAX_HEIGHT = 240;
+const MIN_WIDTH = 360;
+const NAME_MAX_CHARS = 26;
+
+const CORNERS: Record<NonNullable<MemoryHUDProps["corner"]>, CSSProperties> = {
+  "top-right": { top: 8, right: 8 },
+  "top-left": { top: 8, left: 8 },
+  "bottom-right": { bottom: 8, right: 8 },
+  "bottom-left": { bottom: 8, left: 8 },
+};
+
+function mb(bytes: number): string {
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+/** Pre-truncate names that would otherwise blow the layout; the CSS
+ *  ellipsis is a safety net for edges this helper misses. */
+function shortName(name: string, maxLen = NAME_MAX_CHARS): string {
+  if (name.length <= maxLen) return name;
+  return name.slice(0, maxLen - 1) + "…";
+}
+
+// Default theme. Override via `style` prop or className.
+const C = {
+  bg: "rgba(8, 12, 16, 0.92)",
+  border: "rgba(255, 255, 255, 0.1)",
+  hover: "rgba(255, 255, 255, 0.06)",
+  textPrimary: "rgba(255, 255, 255, 0.9)",
+  textSecondary: "rgba(255, 255, 255, 0.65)",
+  textMuted: "rgba(255, 255, 255, 0.4)",
+} as const;
+
+const monoFont =
+  'ui-monospace, "SF Mono", Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace';
+
+// One-time global style injection for focus-visible. The HUD otherwise
+// uses inline styles only, so consumers can override via `style` / `className`
+// without specificity wars. SSR-safe via the `document` guard.
+const FOCUS_STYLE_ID = "webgpu-profiler-focus";
+function ensureFocusStyle(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(FOCUS_STYLE_ID)) return;
+  const el = document.createElement("style");
+  el.id = FOCUS_STYLE_ID;
+  el.textContent = `
+    [data-webgpu-profiler-btn]:focus-visible {
+      outline: 2px solid rgba(255, 255, 255, 0.5);
+      outline-offset: -2px;
+      border-radius: 4px;
+    }
+  `;
+  document.head.appendChild(el);
+}
+
+export function MemoryHUD({
+  instrumentation: explicit,
+  refreshMs = DEFAULT_REFRESH_MS,
+  corner = "top-right",
+  className,
+  style,
+}: MemoryHUDProps = {}) {
+  const active = useActiveInstrumentation();
+  const instrumentation = explicit !== undefined ? explicit : active;
+
+  const [report, setReport] = useState<MemoryReport | null>(null);
+  const [open, setOpen] = useState(true);
+  const [copied, setCopied] = useState(false);
+  const [headerHover, setHeaderHover] = useState(false);
+  const [copyHover, setCopyHover] = useState(false);
+  const timerRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    ensureFocusStyle();
+  }, []);
+
+  useEffect(() => {
+    if (!instrumentation) return;
+    const tick = () => {
+      try {
+        setReport(profileMemory(instrumentation));
+      } catch {
+        // Device may not yet be ready; ignore until next tick.
+      }
+    };
+    tick();
+    timerRef.current = window.setInterval(tick, refreshMs);
+    return () => {
+      if (timerRef.current !== null) window.clearInterval(timerRef.current);
+    };
+  }, [instrumentation, refreshMs]);
+
+  if (!report) return null;
+
+  const [copyFailed, setCopyFailed] = useState(false);
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(reportToText(report));
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1200);
+    } catch (err) {
+      // Insecure context, sandboxed iframe, permission denied, etc.
+      // Surface the failure so the user knows to fall back to manual select.
+      console.warn("[webgpu-profiler] clipboard write failed:", err);
+      setCopyFailed(true);
+      window.setTimeout(() => setCopyFailed(false), 1500);
+    }
+  };
+
+  const containerStyle: CSSProperties = {
+    position: "fixed",
+    zIndex: 9999,
+    pointerEvents: "auto",
+    minWidth: open ? MIN_WIDTH : undefined,
+    maxHeight: "calc(100vh - 16px)",
+    display: "flex",
+    flexDirection: "column",
+    background: C.bg,
+    border: `1px solid ${C.border}`,
+    borderRadius: 6,
+    fontFamily: monoFont,
+    fontSize: 11,
+    color: C.textSecondary,
+    backdropFilter: "blur(8px)",
+    WebkitBackdropFilter: "blur(8px)",
+    ...CORNERS[corner],
+    ...style,
+  };
+
+  return (
+    <div className={className} style={containerStyle}>
+      <button
+        type="button"
+        data-webgpu-profiler-btn=""
+        onClick={() => setOpen((v) => !v)}
+        onMouseEnter={() => setHeaderHover(true)}
+        onMouseLeave={() => setHeaderHover(false)}
+        style={{
+          all: "unset",
+          cursor: "pointer",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: 12,
+          padding: "6px 10px",
+          color: C.textPrimary,
+          borderBottom: open ? `1px solid ${C.border}` : undefined,
+          background: headerHover ? C.hover : "transparent",
+          flexShrink: 0,
+          transition: "background 100ms ease",
+        }}
+      >
+        <span>VRAM</span>
+        <span style={{ fontVariantNumeric: "tabular-nums" }}>
+          {mb(report.totals.all)}
+        </span>
+        <span style={{ color: C.textMuted }}>{open ? "▾" : "▸"}</span>
+      </button>
+
+      {open && (
+        <div
+          style={{
+            padding: "8px 10px 0",
+            display: "flex",
+            flexDirection: "column",
+            gap: 6,
+            minHeight: 0,
+            flex: "1 1 auto",
+          }}
+        >
+          {report.sampledTextures.length > 0 && (
+            <Section
+              label="Sampled textures"
+              total={report.totals.sampledTextures}
+            >
+              {report.sampledTextures.map((t, i) => (
+                <TextureRow key={i} entry={t} />
+              ))}
+            </Section>
+          )}
+
+          {report.renderTargets.length > 0 && (
+            <Section
+              label="Render targets"
+              total={report.totals.renderTargets}
+              topBorder
+            >
+              {report.renderTargets.map((t, i) => (
+                <TextureRow key={i} entry={t} />
+              ))}
+            </Section>
+          )}
+
+          {report.buffers.length > 0 && (
+            <Section label="Buffers" total={report.totals.buffers} topBorder>
+              {report.buffers.map((b, i) => (
+                <BufferRow key={i} entry={b} />
+              ))}
+            </Section>
+          )}
+        </div>
+      )}
+
+      {open && (
+        <div
+          style={{
+            display: "flex",
+            justifyContent: "flex-end",
+            borderTop: `1px solid ${C.border}`,
+            padding: "6px 10px",
+            flexShrink: 0,
+          }}
+        >
+          <button
+            type="button"
+            data-webgpu-profiler-btn=""
+            onClick={handleCopy}
+            onMouseEnter={() => setCopyHover(true)}
+            onMouseLeave={() => setCopyHover(false)}
+            title="Copy report to clipboard"
+            style={{
+              all: "unset",
+              cursor: "pointer",
+              fontSize: 10,
+              color: copyHover ? C.textPrimary : C.textMuted,
+              transition: "color 100ms ease",
+            }}
+          >
+            {copyFailed ? "copy failed" : copied ? "copied" : "copy report"}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ── Rows ────────────────────────────────────────────────────────────────────
+//
+// Table rows with `width: 100%` and `table-layout: auto`. Names are
+// pre-truncated to NAME_MAX_CHARS in JS so column widths stay reasonable;
+// CSS overflow/ellipsis is the safety net.
+
+function TextureRow({ entry }: { entry: TextureEntry }) {
+  return (
+    <tr style={{ lineHeight: 1.4 }}>
+      <td
+        style={{
+          paddingRight: 8,
+          color: C.textPrimary,
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+          whiteSpace: "nowrap",
+        }}
+        title={entry.name}
+      >
+        {shortName(entry.name)}
+      </td>
+      <td style={{ paddingRight: 8, color: C.textMuted, whiteSpace: "nowrap" }}>
+        {entry.width}x{entry.height}
+        {entry.depth > 1 ? `x${entry.depth}` : ""}
+      </td>
+      <td style={{ paddingRight: 8, color: C.textMuted, whiteSpace: "nowrap" }}>
+        {entry.format}
+      </td>
+      <td
+        style={{
+          textAlign: "right",
+          fontVariantNumeric: "tabular-nums",
+          color: C.textSecondary,
+          whiteSpace: "nowrap",
+        }}
+      >
+        {mb(entry.bytes)}
+      </td>
+    </tr>
+  );
+}
+
+function BufferRow({ entry }: { entry: BufferEntry }) {
+  return (
+    <tr style={{ lineHeight: 1.4 }}>
+      <td
+        style={{
+          paddingRight: 8,
+          color: C.textPrimary,
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+          whiteSpace: "nowrap",
+        }}
+        title={entry.name}
+      >
+        {shortName(entry.name)}
+      </td>
+      <td
+        style={{
+          paddingRight: 8,
+          color: C.textMuted,
+          fontSize: 10,
+          whiteSpace: "nowrap",
+        }}
+        title={entry.usage}
+      >
+        {shortName(entry.usage, 18)}
+      </td>
+      <td
+        style={{
+          textAlign: "right",
+          fontVariantNumeric: "tabular-nums",
+          color: C.textSecondary,
+          whiteSpace: "nowrap",
+        }}
+      >
+        {mb(entry.bytes)}
+      </td>
+    </tr>
+  );
+}
+
+function Section({
+  label,
+  total,
+  topBorder,
+  children,
+}: {
+  label: string;
+  total: number;
+  topBorder?: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        minHeight: 0,
+        flex: "0 1 auto",
+        marginTop: topBorder ? 6 : 0,
+        paddingTop: topBorder ? 6 : 0,
+        borderTop: topBorder ? `1px solid ${C.border}` : undefined,
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          justifyContent: "space-between",
+          color: C.textMuted,
+          marginBottom: 4,
+          flexShrink: 0,
+        }}
+      >
+        <span>{label}</span>
+        <span style={{ fontVariantNumeric: "tabular-nums" }}>{mb(total)}</span>
+      </div>
+      <div
+        style={{
+          overflowY: "auto",
+          overflowX: "hidden",
+          maxHeight: SECTION_MAX_HEIGHT,
+          minHeight: 0,
+          // `thin` shrinks the scrollbar; `stable` reserves space for it
+          // even when it's not visible, so the rightmost column never gets
+          // overlapped by an overlay scrollbar (macOS, mobile).
+          scrollbarWidth: "thin",
+          scrollbarGutter: "stable",
+        }}
+      >
+        <table
+          style={{
+            width: "100%",
+            tableLayout: "auto",
+            borderCollapse: "collapse",
+          }}
+        >
+          <tbody>{children}</tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

package/src/react/index.ts

@@ -0,0 +1 @@
+export { MemoryHUD, type MemoryHUDProps } from "./MemoryHUD.js";