Add vpinball: a browser Visual Pinball player

Next.js app that plays real .vpx tables via @valknar/vpinball-wasm
(WebAssembly Visual Pinball). Demo mode with the bundled default
table, drag-and-drop custom table upload, a cabinet-styled UI with a
coin-door HUD (fullscreen/stats/info/eject), a custom 404 page, PWA
support (hand-rolled service worker), and a static Docker Compose
deployment behind nginx.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012hQoM3jJT1Lx7CMTciMzvD

components/hud/CoinDoorHud.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import type { PinballInstance } from "@valknar/vpinball-wasm";
+import { useIdleTimer } from "./useIdleTimer";
+import StatsReadout from "./StatsReadout";
+import GameInfoPanel from "@/components/GameInfoPanel";
+import type { TableInfo } from "@/lib/pinball/types";
+
+export interface CoinDoorHudProps {
+  instanceRef: React.RefObject<PinballInstance | null>;
+  tableInfo: TableInfo;
+  loadTimeMs: number | null;
+}
+
+function HudButton({
+  label,
+  active,
+  onClick,
+}: {
+  label: string;
+  active?: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-pressed={active}
+      className={`rounded-sm border px-3 py-1.5 font-mono text-xs tracking-widest transition ${
+        active
+          ? "border-marquee bg-marquee/20 text-marquee"
+          : "border-chrome/40 bg-black/30 text-chrome hover:border-arc hover:text-arc"
+      }`}
+    >
+      {label}
+    </button>
+  );
+}
+
+export default function CoinDoorHud({ instanceRef, tableInfo, loadTimeMs }: CoinDoorHudProps) {
+  const router = useRouter();
+  const isIdle = useIdleTimer(3000);
+  const [showStats, setShowStats] = useState(false);
+  const [showInfo, setShowInfo] = useState(false);
+  const [isFullscreen, setIsFullscreen] = useState(false);
+
+  useEffect(() => {
+    const onChange = () => setIsFullscreen(Boolean(document.fullscreenElement));
+    document.addEventListener("fullscreenchange", onChange);
+    return () => document.removeEventListener("fullscreenchange", onChange);
+  }, []);
+
+  const handleFullscreen = () => {
+    instanceRef.current?.requestFullscreen();
+  };
+
+  const handleEject = () => {
+    // dispose() (called by usePinballInstance's unmount cleanup, triggered by
+    // this navigation) tears the instance down immediately. Calling stop()
+    // here too raced it — stop() defers teardown to the engine's next
+    // internal step, and dispose() freeing WASM memory before that step runs
+    // hung the tab.
+    router.push("/");
+  };
+
+  return (
+    <>
+      <div
+        data-hud
+        className={`absolute inset-x-0 top-0 z-10 flex items-center justify-between gap-3 border-b border-chrome/30 bg-ash/90 px-4 py-2 backdrop-blur transition-opacity duration-300 ${
+          isIdle ? "pointer-events-none opacity-0" : "opacity-100"
+        }`}
+      >
+        <div className="flex items-center gap-2">
+          <span className="font-display text-lg tracking-wide text-marquee">VPINBALL</span>
+          <span className="hidden truncate font-mono text-xs text-chrome sm:inline">
+            {tableInfo.name}
+          </span>
+        </div>
+        <div className="flex items-center gap-2">
+          {showStats && <StatsReadout />}
+          <HudButton label="INFO" active={showInfo} onClick={() => setShowInfo((v) => !v)} />
+          <HudButton label="STATS" active={showStats} onClick={() => setShowStats((v) => !v)} />
+          <HudButton
+            label={isFullscreen ? "EXIT FS" : "FULLSCREEN"}
+            active={isFullscreen}
+            onClick={handleFullscreen}
+          />
+          <HudButton label="EJECT" onClick={handleEject} />
+        </div>
+      </div>
+
+      {showInfo && (
+        <div className="absolute right-4 top-16 z-10">
+          <GameInfoPanel tableInfo={tableInfo} loadTimeMs={loadTimeMs} />
+        </div>
+      )}
+    </>
+  );
+}

components/hud/StatsReadout.tsx

@@ -0,0 +1,35 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** Self-contained rAF-based FPS counter — the engine exposes no perf API of its own. */
+export default function StatsReadout() {
+  const [fps, setFps] = useState<number | null>(null);
+
+  useEffect(() => {
+    let frameCount = 0;
+    let windowStart = performance.now();
+    let raf = 0;
+
+    const tick = (now: number) => {
+      frameCount += 1;
+      const elapsed = now - windowStart;
+      if (elapsed >= 500) {
+        setFps(Math.round((frameCount * 1000) / elapsed));
+        frameCount = 0;
+        windowStart = now;
+      }
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+
+    return () => cancelAnimationFrame(raf);
+  }, []);
+
+  return (
+    <div className="flex items-baseline gap-2 rounded border border-chrome/30 bg-black/40 px-3 py-1.5 font-mono">
+      <span className="text-xs tracking-widest text-chrome">FPS</span>
+      <span className="text-lg tabular-nums text-arc">{fps ?? "--"}</span>
+    </div>
+  );
+}

components/hud/useIdleTimer.ts

@@ -0,0 +1,33 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+
+/** True once no pointer/keyboard activity has been seen for `timeoutMs`. */
+export function useIdleTimer(timeoutMs = 3000): boolean {
+  const [isIdle, setIsIdle] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    const reset = () => {
+      setIsIdle(false);
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => setIsIdle(true), timeoutMs);
+    };
+
+    reset();
+    const events: Array<keyof WindowEventMap> = [
+      "mousemove",
+      "pointerdown",
+      "touchstart",
+      "keydown",
+    ];
+    events.forEach((event) => window.addEventListener(event, reset, { passive: true }));
+
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      events.forEach((event) => window.removeEventListener(event, reset));
+    };
+  }, [timeoutMs]);
+
+  return isIdle;
+}