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

README.md

@@ -8,6 +8,11 @@ a WebAssembly build of the real [Visual Pinball](https://github.com/vpinball/vpi
 ## Features
 
 - **Play any self-contained `.vpx` table** — drag a file onto the landing page, or click to browse.
+- **ROM support for real-hardware ("SS") tables** — attach the table's PinMAME ROM `.zip` alongside
+  the `.vpx` upload; most tables don't need this.
+- **A local table library** — uploads are saved in the browser (IndexedDB) so you don't have to
+  re-upload the same table (and its ROM) on your next visit. Nothing leaves your browser; there's
+  no server-side storage.
 - **Demo mode** — a bundled table plays instantly with no upload required.
 - **Fullscreen**, a live **FPS/stats** readout, and a **game info** panel (table name, size, load
   time) in an in-game HUD styled after a pinball cabinet's coin door.
@@ -88,10 +93,11 @@ pnpm run sw:bump
 
 | Key            | Action        |
 | -------------- | ------------- |
+| 4              | Insert coin   |
+| 1              | Start game    |
+| Enter          | Launch ball   |
 | Left Shift     | Left flipper  |
 | Right Shift    | Right flipper |
-| Enter          | Plunger       |
-| 1              | Start game    |
 
 On touch devices, an on-screen control overlay appears automatically once a table is running.
 
@@ -101,12 +107,19 @@ Inherited from the underlying engine:
 
 - Only self-contained `.vpx` tables are supported — tables that reference an external `.vbs`
   script override or a `Music/` folder won't load correctly.
-- No PinMAME, DOF, or FlexDMD plugin support.
+- PinMAME (`VPinMAME.Controller`) ROM-driven emulation runs, but on-screen DMD/backglass output
+  and hands-on switch/solenoid/scoring behavior aren't yet confirmed end-to-end — see the engine's
+  own README for the current state. No DOF, FlexDMD, or backglass (`.directb2s`) plugin support.
+  ROM files are copyrighted; only supply ones you're legally entitled to use.
+- The ROM `gameName` PinMAME needs is derived from the uploaded zip's filename (e.g.
+  `hvymetal.zip` → `hvymetal`) — rename the zip to match if a table doesn't recognize its ROM.
 - Single-threaded (no `SharedArrayBuffer`) — performance depends on your device's single-core
   WebGL2 throughput.
 - Initial engine download is ~34 MB (cached after the first visit).
 - Gamepad input and DMD rendering are implemented but not yet confirmed on real hardware/tables.
 - Raw cabinet hardware input (real nudge/plunger boards) has no browser equivalent.
+- The table library lives in the browser's IndexedDB storage — clearing site data removes it, and
+  it doesn't sync across browsers/devices.
 
 ## License
 

app/globals.css

@@ -9,7 +9,7 @@
   --color-arc: #4ce0d2; /* fluorescent-tube cyan — focus rings, secondary */
   --color-paper: #f3efe6; /* aged-backglass cream — high-contrast body text */
 
-  --font-display: var(--font-big-shoulders), "Arial Narrow", sans-serif;
+  --font-display: var(--font-display-face), "Arial Narrow", sans-serif;
   --font-body: var(--font-space-grotesk), system-ui, sans-serif;
   --font-mono: var(--font-plex-mono), "IBM Plex Mono", ui-monospace, monospace;
 }

app/layout.tsx

@@ -1,17 +1,12 @@
 import type { Metadata, Viewport } from "next";
-import { Big_Shoulders, Space_Grotesk, IBM_Plex_Mono } from "next/font/google";
+import { Barlow_Condensed, Space_Grotesk, IBM_Plex_Mono } from "next/font/google";
 import RegisterServiceWorker from "@/components/RegisterServiceWorker";
 import "./globals.css";
 
-const bigShoulders = Big_Shoulders({
+const displayFont = Barlow_Condensed({
-  variable: "--font-big-shoulders",
+  variable: "--font-display-face",
   weight: ["700", "900"],
   subsets: ["latin"],
-  // Next's fallback-metrics table has no entry for this (newer, merged
-  // variable-font) family name, so the automatic CLS-reducing fallback
-  // override it would otherwise generate always fails with a build
-  // warning — opt out instead of leaving that warning unresolved.
-  adjustFontFallback: false,
 });
 
 const spaceGrotesk = Space_Grotesk({
@@ -39,7 +34,7 @@ export default function RootLayout({ children }: LayoutProps<"/">) {
   return (
     <html
       lang="en"
-      className={`${bigShoulders.variable} ${spaceGrotesk.variable} ${plexMono.variable} h-full antialiased`}
+      className={`${displayFont.variable} ${spaceGrotesk.variable} ${plexMono.variable} h-full antialiased`}
     >
       <body className="min-h-full flex flex-col bg-ink text-paper font-body">
         {children}

app/page.tsx

@@ -1,12 +1,11 @@
 import AttractHero from "@/components/landing/AttractHero";
+import TableLibrary from "@/components/landing/TableLibrary";
 
 export default function Home() {
   return (
     <main className="flex flex-1 flex-col items-center justify-center gap-8 px-4 py-16">
       <AttractHero />
-      <p className="max-w-lg text-center font-mono text-xs text-chrome sm:hidden">
+      <TableLibrary />
-        Pinball plays best in landscape or fullscreen — rotate your device once a table loads.
-      </p>
       <footer className="font-mono text-xs text-chrome/70">
         Powered by{" "}
         <a

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">
+        <div className="flex min-w-0 items-center gap-2">
-          <span className="font-display text-lg tracking-wide text-marquee">VPINBALL</span>
+          <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">
+        <div className="flex shrink-0 items-center gap-1.5 sm: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"}
+            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();
+      const selection = takePendingTable();
-      if (file) {
+
-        const tableData = await file.arrayBuffer();
+      if (selection?.kind === "upload") {
-        if (cancelled) return;
+        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}
+    />
   );
 }

lib/pinball/keyBindings.ts

@@ -4,8 +4,9 @@ export interface KeyBinding {
 }
 
 export const KEY_BINDINGS: KeyBinding[] = [
+  { keys: "4", action: "Insert coin" },
+  { keys: "1", action: "Start game" },
+  { keys: "Enter", action: "Launch ball" },
   { keys: "Left Shift", action: "Left flipper" },
   { keys: "Right Shift", action: "Right flipper" },
-  { keys: "Enter", action: "Plunger" },
-  { keys: "1", action: "Start game" },
 ];

lib/pinball/rom.ts

@@ -0,0 +1,7 @@
+// PinMAME identifies a ROM by its short "game name" (e.g. "hvymetal"), not
+// the table's display title — see loadRom() in @valknar/vpinball-wasm. ROM
+// zips are conventionally distributed named after that game name, so it's
+// derived from the uploaded zip's filename rather than asked for separately.
+export function romGameNameFromFileName(fileName: string): string {
+  return fileName.replace(/\.zip$/i, "").trim().toLowerCase();
+}

lib/pinball/tableLibrary.ts

@@ -0,0 +1,72 @@
+// Persists uploaded tables (and their optional ROM zip) in the browser via
+// IndexedDB, so a returning visitor can replay a table without re-uploading
+// it. Blobs are stored as-is (File objects are Blobs) rather than converted
+// to ArrayBuffer up front — IndexedDB clones Blobs without loading their
+// bytes into JS memory, so a large library doesn't sit resident until a
+// specific entry is actually played.
+
+const DB_NAME = "vpinball-library";
+const DB_VERSION = 1;
+const STORE = "tables";
+
+export interface LibraryEntry {
+  id: string;
+  name: string;
+  sizeBytes: number;
+  addedAt: number;
+  vpxBlob: Blob;
+  romFileName?: string;
+  romBlob?: Blob;
+}
+
+export type LibraryEntryMeta = Omit<LibraryEntry, "vpxBlob" | "romBlob">;
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      request.result.createObjectStore(STORE, { keyPath: "id" });
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+async function withStore<T>(mode: IDBTransactionMode, fn: (store: IDBObjectStore) => IDBRequest<T>): Promise<T> {
+  const db = await openDb();
+  try {
+    return await new Promise<T>((resolve, reject) => {
+      const tx = db.transaction(STORE, mode);
+      const request = fn(tx.objectStore(STORE));
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  } finally {
+    db.close();
+  }
+}
+
+export async function saveToLibrary(entry: LibraryEntry): Promise<void> {
+  await withStore("readwrite", (store) => store.put(entry));
+}
+
+export async function listLibrary(): Promise<LibraryEntryMeta[]> {
+  const entries = await withStore<LibraryEntry[]>("readonly", (store) => store.getAll());
+  return entries
+    .map((entry): LibraryEntryMeta => ({
+      id: entry.id,
+      name: entry.name,
+      sizeBytes: entry.sizeBytes,
+      addedAt: entry.addedAt,
+      romFileName: entry.romFileName,
+    }))
+    .sort((a, b) => b.addedAt - a.addedAt);
+}
+
+export async function getLibraryEntry(id: string): Promise<LibraryEntry | undefined> {
+  return withStore<LibraryEntry | undefined>("readonly", (store) => store.get(id));
+}
+
+export async function deleteFromLibrary(id: string): Promise<void> {
+  await withStore("readwrite", (store) => store.delete(id));
+}

lib/pinball/tableSelectionStore.ts

@@ -1,15 +1,19 @@
-// In-memory handoff for a user-selected .vpx File between the landing page
+// In-memory handoff for the user's table choice between the landing page
 // and /play — a File can't survive a URL-based navigation, and this is a
 // single-shot value read once on mount, so module-level state is sufficient
 // (no need for anything heavier than a plain variable).
-let pendingFile: File | null = null;
+export type PendingSelection =
+  | { kind: "upload"; vpxFile: File; romFile?: File; saveToLibrary: boolean }
+  | { kind: "library"; id: string };
 
-export function setPendingTable(file: File): void {
+let pendingSelection: PendingSelection | null = null;
-  pendingFile = file;
+
+export function setPendingTable(selection: PendingSelection): void {
+  pendingSelection = selection;
 }
 
-export function takePendingTable(): File | null {
+export function takePendingTable(): PendingSelection | null {
-  const file = pendingFile;
+  const selection = pendingSelection;
-  pendingFile = null;
+  pendingSelection = null;
-  return file;
+  return selection;
 }

lib/pinball/types.ts

@@ -2,4 +2,6 @@ export interface TableInfo {
   name: string;
   sizeBytes: number;
   isDemo: boolean;
+  /** Filename of the attached PinMAME ROM zip, if any. */
+  romFileName?: string;
 }

lib/pinball/usePinballInstance.ts

@@ -33,9 +33,15 @@ export interface UsePinballInstanceResult {
   start: () => void;
 }
 
+export interface RomSelection {
+  gameName: string;
+  romData: ArrayBuffer;
+}
+
 export function usePinballInstance(
   canvasRef: React.RefObject<HTMLCanvasElement | null>,
   tableData: ArrayBuffer | undefined,
+  rom: RomSelection | undefined,
 ): UsePinballInstanceResult {
   // Computed once at mount (not inside the effect below) so the WebGL2-
   // unsupported case is derived initial state rather than a setState call
@@ -73,6 +79,18 @@ export function usePinballInstance(
           instance.dispose();
           return;
         }
+        if (rom) {
+          try {
+            // Must run before start() — Controller.Run() reads the ROM
+            // file synchronously at table-init time. A bad/mismatched ROM
+            // zip fails cleanly inside the engine rather than here, so this
+            // is defensive against loadRom() itself throwing (e.g. a
+            // corrupt zip), not something expected to fire routinely.
+            instance.loadRom(rom.gameName, rom.romData);
+          } catch (err) {
+            console.error("Failed to load ROM:", err);
+          }
+        }
         instanceRef.current = instance;
         setLoadTimeMs(performance.now() - startedAt);
         setStatus("ready");

package.json

@@ -12,7 +12,7 @@
     "lint": "eslint"
   },
   "dependencies": {
-    "@valknar/vpinball-wasm": "0.2.0",
+    "@valknar/vpinball-wasm": "0.3.2",
     "next": "16.3.2",
     "react": "19.2.8",
     "react-dom": "19.2.8"

pnpm-lock.yaml

@@ -9,8 +9,8 @@ importers:
   .:
     dependencies:
       '@valknar/vpinball-wasm':
-        specifier: 0.2.0
+        specifier: 0.3.2
-        version: 0.2.0
+        version: 0.3.2
       next:
         specifier: 16.3.2
         version: 16.3.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@20.19.43)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
@@ -754,8 +754,8 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@valknar/vpinball-wasm@0.2.0':
+  '@valknar/vpinball-wasm@0.3.2':
-    resolution: {integrity: sha512-KZ/TxQzO8V+km67Yq4YgPCpAbuTTjqii9I6wBVWgKb5vsbiSBbvgTucY8288tpsWoA+/j4Bsp3pe0USiG1xJAQ==, tarball: https://dev.pivoine.art/api/packages/valknar/npm/%40valknar%2Fvpinball-wasm/-/0.2.0/vpinball-wasm-0.2.0.tgz}
+    resolution: {integrity: sha512-52vkjVzev92khiO8a50N2afYIviX1hHCMzTilN24Pe/7pu5m9LlSQVS3o11rRdItSF5h1RVmTLpoh1ENYrLQJw==, tarball: https://dev.pivoine.art/api/packages/valknar/npm/%40valknar%2Fvpinball-wasm/-/0.3.2/vpinball-wasm-0.3.2.tgz}
 
   acorn-jsx@5.3.2:
     resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
@@ -2645,7 +2645,7 @@ snapshots:
   '@unrs/resolver-binding-win32-x64-msvc@1.12.2':
     optional: true
 
-  '@valknar/vpinball-wasm@0.2.0': {}
+  '@valknar/vpinball-wasm@0.3.2': {}
 
   acorn-jsx@5.3.2(acorn@8.18.0):
     dependencies:

pnpm-workspace.yaml

@@ -2,5 +2,5 @@ allowBuilds:
   sharp: false
   unrs-resolver: false
 minimumReleaseAgeExclude:
-  - '@valknar/vpinball-wasm@0.2.0'
+  - '@valknar/vpinball-wasm@0.2.0 || 0.3.1 || 0.3.2'
 updateNotifier: false