Add ROM upload, local table library, engine bump, and UX/responsiveness fixes

- Bump @valknar/vpinball-wasm to 0.3.2 (PinMAME ROM support, MsgBox fix)
- Add optional PinMAME ROM .zip upload alongside .vpx tables
- Persist uploaded tables/ROMs in IndexedDB so users don't have to
  re-upload on later visits, with a library list on the landing page
- Fix Insert Coin key mismatch with the engine's real coin-door gating
  (now bound to 4, matching the shared table scripts) and surface it
  in the controls legend and "Tap to Start" hint
- Make the landing page, staging panel, and in-game HUD responsive for
  portrait phone widths; drop the landscape hint since portrait plays fine
- Replace the separate STATS HUD toggle with an FPS row in the info panel

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

components/GameInfoPanel.tsx

@@ -1,3 +1,6 @@
+"use client";
+
+import { useEffect, useState } from "react";
 import { formatBytes, formatDuration } from "@/lib/format";
 import { KEY_BINDINGS } from "@/lib/pinball/keyBindings";
 import type { TableInfo } from "@/lib/pinball/types";
@@ -7,20 +10,53 @@ export interface GameInfoPanelProps {
   loadTimeMs: number | null;
 }
 
+/** Self-contained rAF-based FPS counter — the engine exposes no perf API of its own. */
+function useFps(): number | null {
+  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 fps;
+}
+
 export default function GameInfoPanel({ tableInfo, loadTimeMs }: GameInfoPanelProps) {
+  const fps = useFps();
+
   return (
-    <div className="w-72 space-y-4 rounded border border-chrome/30 bg-ash/95 p-4 font-mono text-sm text-paper shadow-xl">
+    <div className="w-full space-y-4 rounded border border-chrome/30 bg-ash/95 p-4 font-mono text-sm text-paper shadow-xl sm:w-72">
       <div>
         <div className="text-xs tracking-widest text-chrome">TABLE</div>
         <div className="truncate text-arc">{tableInfo.name}</div>
       </div>
       <dl className="grid grid-cols-2 gap-x-2 gap-y-1 text-xs">
+        <dt className="text-chrome">FPS</dt>
+        <dd className="tabular-nums text-arc">{fps ?? "—"}</dd>
         <dt className="text-chrome">Source</dt>
         <dd>{tableInfo.isDemo ? "Bundled demo" : "Your upload"}</dd>
         <dt className="text-chrome">Size</dt>
         <dd>{tableInfo.isDemo ? "—" : formatBytes(tableInfo.sizeBytes)}</dd>
         <dt className="text-chrome">Load time</dt>
         <dd>{loadTimeMs !== null ? formatDuration(loadTimeMs) : "—"}</dd>
+        <dt className="text-chrome">ROM</dt>
+        <dd className="truncate">{tableInfo.romFileName ?? "—"}</dd>
       </dl>
       <div>
         <div className="mb-1 text-xs tracking-widest text-chrome">CONTROLS</div>

components/hud/CoinDoorHud.tsx

@@ -4,7 +4,6 @@ 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";
 
@@ -16,10 +15,12 @@ export interface CoinDoorHudProps {
 
 function HudButton({
   label,
+  shortLabel,
   active,
   onClick,
 }: {
   label: string;
+  shortLabel?: string;
   active?: boolean;
   onClick: () => void;
 }) {
@@ -28,13 +29,20 @@ function HudButton({
       type="button"
       onClick={onClick}
       aria-pressed={active}
-      className={`rounded-sm border px-3 py-1.5 font-mono text-xs tracking-widest transition ${
+      className={`rounded-sm border px-2 py-1 font-mono text-xs tracking-widest transition sm:px-3 sm:py-1.5 ${
         active
           ? "border-marquee bg-marquee/20 text-marquee"
           : "border-chrome/40 bg-black/30 text-chrome hover:border-arc hover:text-arc"
       }`}
     >
-      {label}
+      {shortLabel ? (
+        <>
+          <span className="sm:hidden">{shortLabel}</span>
+          <span className="hidden sm:inline">{label}</span>
+        </>
+      ) : (
+        label
+      )}
     </button>
   );
 }
@@ -42,7 +50,6 @@ function HudButton({
 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);
 
@@ -69,22 +76,21 @@ export default function CoinDoorHud({ instanceRef, tableInfo, loadTimeMs }: Coin
     <>
       <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 ${
+        className={`absolute inset-x-0 top-0 z-10 flex items-center justify-between gap-1.5 border-b border-chrome/30 bg-ash/90 px-2 py-2 backdrop-blur transition-opacity duration-300 sm:gap-3 sm:px-4 ${
           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>
+        <div className="flex min-w-0 items-center gap-2">
+          <span className="shrink-0 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 />}
+        <div className="flex shrink-0 items-center gap-1.5 sm:gap-2">
           <HudButton label="INFO" active={showInfo} onClick={() => setShowInfo((v) => !v)} />
-          <HudButton label="STATS" active={showStats} onClick={() => setShowStats((v) => !v)} />
           <HudButton
             label={isFullscreen ? "EXIT FS" : "FULLSCREEN"}
+            shortLabel={isFullscreen ? "EXIT" : "FS"}
             active={isFullscreen}
             onClick={handleFullscreen}
           />
@@ -93,7 +99,7 @@ export default function CoinDoorHud({ instanceRef, tableInfo, loadTimeMs }: Coin
       </div>
 
       {showInfo && (
-        <div className="absolute right-4 top-16 z-10">
+        <div className="absolute inset-x-2 top-14 z-10 sm:inset-x-auto sm:right-4 sm:top-16">
           <GameInfoPanel tableInfo={tableInfo} loadTimeMs={loadTimeMs} />
         </div>
       )}

components/hud/StatsReadout.tsx

@@ -1,35 +0,0 @@
-"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/landing/AttractHero.tsx

@@ -4,18 +4,33 @@ import { useRouter } from "next/navigation";
 import { useState } from "react";
 import Button, { buttonClassName } from "@/components/ui/Button";
 import FileDropZone, { VPX_FILE_INPUT_ID } from "@/components/FileDropZone";
+import TableStaging from "./TableStaging";
 import { setPendingTable } from "@/lib/pinball/tableSelectionStore";
 
 export default function AttractHero() {
   const router = useRouter();
   const [error, setError] = useState<string | null>(null);
+  const [stagedFile, setStagedFile] = useState<File | null>(null);
 
   const handleFile = (file: File) => {
     setError(null);
-    setPendingTable(file);
+    setStagedFile(file);
+  };
+
+  const handlePlay = (romFile: File | undefined, saveToLibrary: boolean) => {
+    if (!stagedFile) return;
+    setPendingTable({ kind: "upload", vpxFile: stagedFile, romFile, saveToLibrary });
     router.push("/play");
   };
 
+  if (stagedFile) {
+    return (
+      <div className="w-full max-w-4xl">
+        <TableStaging vpxFile={stagedFile} onPlay={handlePlay} onCancel={() => setStagedFile(null)} />
+      </div>
+    );
+  }
+
   return (
     <FileDropZone onFile={handleFile} onError={setError} className="w-full max-w-4xl">
       <div className="relative overflow-hidden rounded-t-3xl rounded-b-lg border-2 border-chrome/40 bg-ash shadow-2xl">
@@ -37,9 +52,9 @@ export default function AttractHero() {
           }}
         />
 
-        <div className="relative flex flex-col items-center gap-6 px-8 py-20 text-center sm:py-28">
+        <div className="relative flex flex-col items-center gap-6 px-4 py-14 text-center sm:px-8 sm:py-28">
           <p className="font-mono text-xs tracking-[0.3em] text-arc">WEBASSEMBLY · WEBGL2 · REAL .VPX TABLES</p>
-          <h1 className="font-display text-6xl font-black leading-none tracking-wide text-paper sm:text-8xl">
+          <h1 className="font-display text-5xl font-black leading-none tracking-wide text-paper sm:text-8xl">
             VPINBALL
           </h1>
           <p className="max-w-md font-body text-chrome">

components/landing/TableLibrary.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { formatBytes } from "@/lib/format";
+import { deleteFromLibrary, listLibrary, type LibraryEntryMeta } from "@/lib/pinball/tableLibrary";
+import { setPendingTable } from "@/lib/pinball/tableSelectionStore";
+
+export default function TableLibrary() {
+  const router = useRouter();
+  const [entries, setEntries] = useState<LibraryEntryMeta[] | null>(null);
+
+  useEffect(() => {
+    listLibrary()
+      .then(setEntries)
+      .catch((err) => {
+        console.error("Failed to read table library:", err);
+        setEntries([]);
+      });
+  }, []);
+
+  if (!entries || entries.length === 0) return null;
+
+  const handlePlay = (id: string) => {
+    setPendingTable({ kind: "library", id });
+    router.push("/play");
+  };
+
+  const handleDelete = async (id: string) => {
+    await deleteFromLibrary(id);
+    setEntries((prev) => prev?.filter((entry) => entry.id !== id) ?? null);
+  };
+
+  return (
+    <div className="w-full max-w-4xl">
+      <h2 className="mb-3 font-display text-xl tracking-wide text-paper">Your Library</h2>
+      <ul className="divide-y divide-chrome/20 rounded-lg border border-chrome/30 bg-ash">
+        {entries.map((entry) => (
+          <li key={entry.id} className="flex items-center justify-between gap-3 px-4 py-3">
+            <div className="min-w-0">
+              <div className="truncate font-mono text-sm text-paper">{entry.name}</div>
+              <div className="font-mono text-xs text-chrome">
+                {formatBytes(entry.sizeBytes)}
+                {entry.romFileName ? ` · ROM: ${entry.romFileName}` : ""}
+              </div>
+            </div>
+            <div className="flex shrink-0 items-center gap-2">
+              <button
+                type="button"
+                onClick={() => handlePlay(entry.id)}
+                className="rounded-full border-2 border-marquee bg-marquee/10 px-4 py-1.5 font-display text-sm tracking-wide text-marquee transition hover:bg-marquee/20"
+              >
+                Play
+              </button>
+              <button
+                type="button"
+                onClick={() => handleDelete(entry.id)}
+                className="rounded-full border border-chrome/40 px-4 py-1.5 font-display text-sm tracking-wide text-chrome transition hover:border-marquee hover:text-marquee"
+              >
+                Delete
+              </button>
+            </div>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

components/landing/TableStaging.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { useState, type ChangeEvent } from "react";
+import Button, { buttonClassName } from "@/components/ui/Button";
+import { formatBytes } from "@/lib/format";
+
+const ROM_FILE_INPUT_ID = "rom-file-input";
+
+export interface TableStagingProps {
+  vpxFile: File;
+  onPlay: (romFile: File | undefined, saveToLibrary: boolean) => void;
+  onCancel: () => void;
+}
+
+export default function TableStaging({ vpxFile, onPlay, onCancel }: TableStagingProps) {
+  const [romFile, setRomFile] = useState<File | null>(null);
+  const [saveToLibrary, setSaveToLibrary] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleRomChange = (e: ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    e.target.value = "";
+    if (!file) return;
+    if (!file.name.toLowerCase().endsWith(".zip")) {
+      setError(`"${file.name}" isn't a .zip file.`);
+      return;
+    }
+    setError(null);
+    setRomFile(file);
+  };
+
+  return (
+    <div className="relative overflow-hidden rounded-t-3xl rounded-b-lg border-2 border-chrome/40 bg-ash shadow-2xl">
+      <div className="relative flex flex-col items-center gap-5 px-4 py-14 text-center sm:px-8">
+        <p className="font-mono text-xs tracking-[0.3em] text-arc">TABLE SELECTED</p>
+        <h2 className="max-w-lg truncate font-display text-3xl font-black tracking-wide text-paper sm:text-4xl">
+          {vpxFile.name}
+        </h2>
+        <p className="font-mono text-xs text-chrome">{formatBytes(vpxFile.size)}</p>
+
+        <div className="mt-2 flex flex-col items-center gap-2">
+          <p className="max-w-sm font-body text-sm text-chrome">
+            Real-hardware (&quot;SS&quot;) tables need a matching PinMAME ROM. Attach its zip if you have one
+            — most tables don&apos;t need this.
+          </p>
+          <label htmlFor={ROM_FILE_INPUT_ID} className={buttonClassName("outline", "cursor-pointer text-sm")}>
+            {romFile ? `ROM: ${romFile.name}` : "Attach ROM (.zip) — optional"}
+          </label>
+          <input
+            id={ROM_FILE_INPUT_ID}
+            type="file"
+            accept=".zip"
+            className="sr-only"
+            onChange={handleRomChange}
+          />
+          {romFile && (
+            <button
+              type="button"
+              onClick={() => setRomFile(null)}
+              className="font-mono text-xs text-chrome underline decoration-dotted underline-offset-2 hover:text-arc"
+            >
+              Remove ROM
+            </button>
+          )}
+        </div>
+
+        <label className="flex items-center gap-2 font-mono text-xs text-chrome">
+          <input
+            type="checkbox"
+            checked={saveToLibrary}
+            onChange={(e) => setSaveToLibrary(e.target.checked)}
+            className="accent-marquee"
+          />
+          Save to my library, so I don&apos;t need to re-upload it later
+        </label>
+
+        {error && (
+          <p role="alert" className="font-mono text-sm text-marquee">
+            {error}
+          </p>
+        )}
+
+        <div className="mt-2 flex items-center gap-3">
+          <Button type="button" variant="primary" onClick={() => onPlay(romFile ?? undefined, saveToLibrary)}>
+            Play
+          </Button>
+          <Button type="button" variant="quiet" onClick={onCancel}>
+            Cancel
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

components/pinball/PinballCanvasImpl.tsx

@@ -1,22 +1,24 @@
 "use client";
 
 import { useRef } from "react";
-import { usePinballInstance } from "@/lib/pinball/usePinballInstance";
+import { usePinballInstance, type RomSelection } 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;
+  rom?: RomSelection;
   tableInfo: TableInfo;
 }
 
-export default function PinballCanvasImpl({ tableData, tableInfo }: PinballCanvasImplProps) {
+export default function PinballCanvasImpl({ tableData, rom, tableInfo }: PinballCanvasImplProps) {
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
   const containerRef = useRef<HTMLDivElement | null>(null);
   const { status, progress, error, loadTimeMs, instanceRef, start } = usePinballInstance(
     canvasRef,
     tableData,
+    rom,
   );
   useTouchControls(containerRef, status === "running");
 
@@ -54,7 +56,7 @@ export default function PinballCanvasImpl({ tableData, tableInfo }: PinballCanva
       )}
 
       {status === "ready" && (
-        <div className="absolute inset-0 flex items-center justify-center bg-ink/80">
+        <div className="absolute inset-0 flex flex-col items-center justify-center gap-3 bg-ink/80">
           <button
             type="button"
             onClick={start}
@@ -62,6 +64,14 @@ export default function PinballCanvasImpl({ tableData, tableInfo }: PinballCanva
           >
             TAP TO START
           </button>
+          {/* Most tables gate Start Game behind having a credit, same as a
+              real coin-op cabinet — pressing 1 alone does nothing until a
+              credit is added. Surfaced here since it's the first thing
+              anyone hits and easy to mistake for the app not responding. */}
+          <p className="font-mono text-xs text-chrome">
+            If Start doesn&apos;t respond: press <span className="text-arc">4</span> to insert a coin, then{" "}
+            <span className="text-arc">1</span> to start.
+          </p>
         </div>
       )}
     </div>

components/pinball/PlayView.tsx

@@ -1,40 +1,103 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import PinballCanvas from "./PinballCanvas";
 import { takePendingTable } from "@/lib/pinball/tableSelectionStore";
+import { getLibraryEntry, saveToLibrary } from "@/lib/pinball/tableLibrary";
+import { romGameNameFromFileName } from "@/lib/pinball/rom";
+import type { RomSelection } from "@/lib/pinball/usePinballInstance";
 import type { TableInfo } from "@/lib/pinball/types";
 
 interface ResolvedTable {
   tableData?: ArrayBuffer;
+  rom?: RomSelection;
   tableInfo: TableInfo;
 }
 
+async function toRomSelection(romFile: File): Promise<RomSelection> {
+  return { gameName: romGameNameFromFileName(romFile.name), romData: await romFile.arrayBuffer() };
+}
+
 export default function PlayView() {
   const [resolved, setResolved] = useState<ResolvedTable | null>(null);
+  // takePendingTable() pops the store on read, so it must run at most once
+  // per real mount — React's dev-mode double-invoke of effects would
+  // otherwise have the second call see an already-emptied store (the first
+  // call already popped the selection) and silently fall back to the demo
+  // table. No unmount-cancellation guard here: this ref makes the
+  // double-invoke's second pass a full no-op, so the async work below only
+  // ever runs once for a given component instance — a cleanup-driven cancel
+  // flag would incorrectly cancel that one real run's own result, since the
+  // phantom unmount's cleanup fires for whichever pass actually started it.
+  const hasResolvedRef = useRef(false);
 
   useEffect(() => {
-    let cancelled = false;
+    if (hasResolvedRef.current) return;
+    hasResolvedRef.current = true;
+
     (async () => {
-      const file = takePendingTable();
-      if (file) {
-        const tableData = await file.arrayBuffer();
-        if (cancelled) return;
+      const selection = takePendingTable();
+
+      if (selection?.kind === "upload") {
+        const { vpxFile, romFile, saveToLibrary: shouldSave } = selection;
+        const [tableData, rom] = await Promise.all([
+          vpxFile.arrayBuffer(),
+          romFile ? toRomSelection(romFile) : Promise.resolve(undefined),
+        ]);
+        if (shouldSave) {
+          saveToLibrary({
+            id: crypto.randomUUID(),
+            name: vpxFile.name,
+            sizeBytes: vpxFile.size,
+            addedAt: Date.now(),
+            vpxBlob: vpxFile,
+            romFileName: romFile?.name,
+            romBlob: romFile,
+          }).catch((err) => console.error("Failed to save table to library:", err));
+        }
         setResolved({
           tableData,
-          tableInfo: { name: file.name, sizeBytes: file.size, isDemo: false },
+          rom,
+          tableInfo: { name: vpxFile.name, sizeBytes: vpxFile.size, isDemo: false, romFileName: romFile?.name },
         });
         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.
+
+      if (selection?.kind === "library") {
+        const entry = await getLibraryEntry(selection.id);
+        if (entry) {
+          const [tableData, rom] = await Promise.all([
+            entry.vpxBlob.arrayBuffer(),
+            entry.romBlob
+              ? entry.romBlob.arrayBuffer().then((romData) => ({
+                  gameName: romGameNameFromFileName(entry.romFileName ?? ""),
+                  romData,
+                }))
+              : Promise.resolve(undefined),
+          ]);
+          setResolved({
+            tableData,
+            rom,
+            tableInfo: {
+              name: entry.name,
+              sizeBytes: entry.sizeBytes,
+              isDemo: false,
+              romFileName: entry.romFileName,
+            },
+          });
+          return;
+        }
+        // Fall through to the demo table if the library entry was removed
+        // (e.g. deleted in another tab) between selecting it and arriving here.
+      }
+
+      // No pending upload/library selection (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) {
@@ -46,6 +109,11 @@ export default function PlayView() {
   }
 
   return (
-    <PinballCanvas tableData={resolved.tableData} tableInfo={resolved.tableInfo} key={resolved.tableInfo.name} />
+    <PinballCanvas
+      tableData={resolved.tableData}
+      rom={resolved.rom}
+      tableInfo={resolved.tableInfo}
+      key={resolved.tableInfo.name}
+    />
   );
 }