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/pinball/PinballCanvas.tsx

@@ -0,0 +1,14 @@
+"use client";
+
+import dynamic from "next/dynamic";
+import type { PinballCanvasImplProps } from "./PinballCanvasImpl";
+
+// The engine touches window/canvas/WebGL as soon as it mounts, so it's kept
+// out of the server render entirely rather than just deferring to an effect.
+const PinballCanvasImpl = dynamic<PinballCanvasImplProps>(() => import("./PinballCanvasImpl"), {
+  ssr: false,
+});
+
+export default function PinballCanvas(props: PinballCanvasImplProps) {
+  return <PinballCanvasImpl {...props} />;
+}

components/pinball/PinballCanvasImpl.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import { useRef } from "react";
+import { usePinballInstance } from "@/lib/pinball/usePinballInstance";
+import { useTouchControls } from "@/lib/pinball/useTouchControls";
+import CoinDoorHud from "@/components/hud/CoinDoorHud";
+import type { TableInfo } from "@/lib/pinball/types";
+
+export interface PinballCanvasImplProps {
+  tableData?: ArrayBuffer;
+  tableInfo: TableInfo;
+}
+
+export default function PinballCanvasImpl({ tableData, tableInfo }: PinballCanvasImplProps) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const { status, progress, error, loadTimeMs, instanceRef, start } = usePinballInstance(
+    canvasRef,
+    tableData,
+  );
+  useTouchControls(containerRef, status === "running");
+
+  return (
+    <div ref={containerRef} className="relative h-full w-full overflow-hidden bg-black">
+      {/* SDL3's Emscripten backend resolves its own window/GL-context target via
+          document.querySelector("#canvas") independently of Module.canvas — the
+          id is required or context creation silently no-ops (findCanvasEventTarget
+          returns null, emscripten_webgl_create_context returns handle 0, and the
+          engine crashes later reading an unset GL context). */}
+      <canvas id="canvas" ref={canvasRef} className="h-full w-full" />
+
+      {(status === "ready" || status === "running") && (
+        <CoinDoorHud instanceRef={instanceRef} tableInfo={tableInfo} loadTimeMs={loadTimeMs} />
+      )}
+
+      {status === "loading" && (
+        <div className="absolute inset-0 flex flex-col items-center justify-center gap-4 bg-ink/90 text-paper">
+          <div className="font-display text-2xl tracking-wide text-marquee">LOADING TABLE</div>
+          <div className="h-2 w-64 overflow-hidden rounded-full bg-ash">
+            <div
+              className="h-full bg-marquee transition-[width]"
+              style={{ width: `${Math.round(progress * 100)}%` }}
+            />
+          </div>
+          <div className="font-mono text-sm text-chrome">{Math.round(progress * 100)}%</div>
+        </div>
+      )}
+
+      {status === "error" && (
+        <div className="absolute inset-0 flex flex-col items-center justify-center gap-2 bg-ink px-8 text-center text-paper">
+          <div className="font-display text-2xl text-marquee">TABLE NOT LOADING</div>
+          <p className="max-w-md font-body text-chrome">{error}</p>
+        </div>
+      )}
+
+      {status === "ready" && (
+        <div className="absolute inset-0 flex items-center justify-center bg-ink/80">
+          <button
+            type="button"
+            onClick={start}
+            className="rounded-full border-2 border-marquee bg-marquee/10 px-8 py-4 font-display text-2xl tracking-wide text-marquee shadow-[0_0_24px_rgba(255,122,41,0.5)] transition hover:bg-marquee/20"
+          >
+            TAP TO START
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

components/pinball/PlayView.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import PinballCanvas from "./PinballCanvas";
+import { takePendingTable } from "@/lib/pinball/tableSelectionStore";
+import type { TableInfo } from "@/lib/pinball/types";
+
+interface ResolvedTable {
+  tableData?: ArrayBuffer;
+  tableInfo: TableInfo;
+}
+
+export default function PlayView() {
+  const [resolved, setResolved] = useState<ResolvedTable | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      const file = takePendingTable();
+      if (file) {
+        const tableData = await file.arrayBuffer();
+        if (cancelled) return;
+        setResolved({
+          tableData,
+          tableInfo: { name: file.name, sizeBytes: file.size, isDemo: false },
+        });
+        return;
+      }
+      // No pending upload (fresh visit, or a hard refresh of /play) — fall
+      // back to the bundled demo table rather than dead-ending the route.
+      setResolved({
+        tableInfo: { name: "Demo table", sizeBytes: 0, isDemo: true },
+      });
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  if (!resolved) {
+    return (
+      <div className="flex h-full w-full items-center justify-center bg-ink font-mono text-chrome">
+        Preparing table…
+      </div>
+    );
+  }
+
+  return (
+    <PinballCanvas tableData={resolved.tableData} tableInfo={resolved.tableInfo} key={resolved.tableInfo.name} />
+  );
+}