Add VITE_API_BASE + HF Space and Vercel deploy configs

Split-deploy support so backend can live on a Hugging Face Space (Docker
SDK) and frontend on Vercel. All fetch/EventSource calls now go through
src/api.js which prepends VITE_API_BASE at build time; falls back to
relative URLs for dev (Vite proxy) and monolithic deploys (Express serves
dist/).

- README.md frontmatter for HF Space (sdk: docker, app_port: 8080)
- vercel.json for the Vite frontend (rewrite /controller to index.html)
- .env.example documents every env var

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.env.example

@@ -0,0 +1,11 @@
+# --- backend (server/server.js) ---
+MONGO_URI=mongodb+srv://<user>:<pass>@<cluster>/news?retryWrites=true&w=majority
+MONGO_DB=news
+MONGO_COLLECTION=egg_catcher_scores
+# PORT is set by the host (HF Space, Fly, etc.); defaults to 5174 locally.
+
+# --- frontend build (vite) ---
+# Empty in monolithic deploy (frontend served by same Express).
+# In split deploy, set to your backend URL (no trailing slash), e.g.:
+# VITE_API_BASE=https://abhinay-egg-catcher-api.hf.space
+VITE_API_BASE=

README.md

@@ -1,7 +1,20 @@
+---
+title: Egg Catcher
+emoji: 🥚
+colorFrom: yellow
+colorTo: red
+sdk: docker
+app_port: 8080
+pinned: false
+short_description: Pixel-art arcade with phone-as-controller and MongoDB leaderboard
+---
+
 # egg-catcher
 
 Pixel-art egg-catcher arcade. Laptop = main screen with a QR pop-up; phone = controller. MongoDB-backed global leaderboard.
 
+The frontmatter above is for [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-config-reference) — it's ignored on GitHub.
+
 ## Run locally
 
 ```bash
@@ -11,7 +24,7 @@ npm run dev
 
 `http://localhost:5173/` on the laptop. Phone scans the QR (same wifi).
 
-`.env` (already gitignored) needs:
+`.env` (gitignored) needs:
 
 ```
 MONGO_URI=mongodb+srv://...
@@ -19,26 +32,34 @@ MONGO_DB=news
 MONGO_COLLECTION=egg_catcher_scores
 ```
 
-## Deploy to Fly.io
+## Deploy — backend on HF Space, frontend on Vercel
 
-One-time:
+### 1. Backend on Hugging Face
 
-```bash
-flyctl auth login
-flyctl launch --no-deploy           # accept fly.toml, pick an app name
-flyctl secrets set MONGO_URI="mongodb+srv://abhinayabhi226_db_user:Od1IwrzfJbXybXap@cluster0.ctylbok.mongodb.net/news?retryWrites=true&w=majority"
-flyctl deploy
-```
+1. Go to https://huggingface.co/new-space
+2. **Owner**: your account · **Space name**: e.g. `egg-catcher-api` · **License**: MIT · **Space SDK**: pick **Docker** → **Blank**
+3. Hardware: **CPU basic — free**
+4. Create. Then in the Space, **Settings** → **Variables and secrets** → add a *Secret* named `MONGO_URI` with your full Mongo connection string
+5. **Settings** → **Repository** → **Connect to a GitHub repository** → pick `ABHINAY2025/egg-catcher`. Every push to `main` will rebuild the Space
+6. The Space will build and come up at `https://<username>-<spacename>.hf.space`
 
-Subsequent deploys:
+### 2. Frontend on Vercel
 
-```bash
-flyctl deploy
-```
+1. Go to https://vercel.com/new
+2. Import `ABHINAY2025/egg-catcher`
+3. **Framework Preset**: Vite (auto-detected)
+4. **Environment Variables**: add `VITE_API_BASE` = `https://<your-hf-space-url>` (no trailing slash, e.g. `https://abhinay-egg-catcher-api.hf.space`)
+5. Deploy. Your game lives at `https://<project>.vercel.app`
+
+### Why split?
+
+- Vercel gives CDN-fast static delivery + instant SPA routing.
+- HF Space stays warm with no card required and supports long-lived SSE for the phone-controller pairing.
+- Frontend and backend are decoupled — swap either independently.
 
 ## How it works
 
-- Single Express server: serves the built Vite frontend AND the API.
+- Single Express server: serves `/api/*` and (in monolithic deploy) the built Vite frontend.
 - Game rooms are in-memory; SSE relays controller events laptop ⇄ phone.
 - `/api/score`, `/api/leaderboard` write to MongoDB collection `egg_catcher_scores`.
-- In production the controller URL is `https://<your-app>.fly.dev/controller?room=XXXXXX`. In dev it's `http://<LAN-IP>:5173/controller?room=XXXXXX`.
+- Controller URL in prod = `${window.location.origin}/controller?room=XXXXXX` (the frontend's URL, not the API).

src/App.jsx

@@ -3,6 +3,7 @@ import UsernameGate from './UsernameGate.jsx';
 import Game from './Game.jsx';
 import MobileGame from './MobileGame.jsx';
 import Leaderboard from './Leaderboard.jsx';
+import { api } from './api.js';
 
 function detectMobile() {
   if (typeof window === 'undefined') return false;
@@ -37,12 +38,12 @@ export default function App() {
     let alive = true;
     (async () => {
       try {
-        const r1 = await fetch('/api/game/room', { method: 'POST' }).then((r) => r.json());
+        const r1 = await fetch(api('/api/game/room'), { method: 'POST' }).then((r) => r.json());
         if (!alive) return;
         setRoomId(r1.roomId);
         if (import.meta.env.PROD) return; // in prod, controller URL = window.location.origin
         try {
-          const r2 = await fetch('/api/game/local-ip').then((r) => r.json());
+          const r2 = await fetch(api('/api/game/local-ip')).then((r) => r.json());
           if (!alive) return;
           setLanIp(r2.ip);
           setIpCandidates(Array.isArray(r2.candidates) ? r2.candidates : []);

src/Controller.jsx

@@ -1,9 +1,10 @@
 import React from 'react';
+import { api } from './api.js';
 
 const ROUND_MS = 60_000;
 
 function send(roomId, action) {
-  fetch('/api/game/control', {
+  fetch(api('/api/game/control'), {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ roomId, action }),
@@ -28,7 +29,7 @@ export default function Controller() {
 
   React.useEffect(() => {
     if (!roomId) return;
-    const es = new EventSource(`/api/game/controller-events/${roomId}`);
+    const es = new EventSource(api(`/api/game/controller-events/${roomId}`));
     es.addEventListener('ready', (e) => {
       try { setPaired(JSON.parse(e.data).paired); } catch {}
     });

src/Game.jsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { api } from './api.js';
 
 const GAME_W = 640;
 const GAME_H = 380;
@@ -15,7 +16,7 @@ const OMELET_TTL = 5500;
 
 function postState(roomId, payload) {
   if (!roomId) return;
-  fetch('/api/game/state', {
+  fetch(api('/api/game/state'), {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ roomId, ...payload }),
@@ -57,7 +58,7 @@ export default function Game({ username, onGameOver, roomId, lanIp, ipCandidates
   // SSE — receive controller events (left/right/start)
   React.useEffect(() => {
     if (!roomId) return;
-    const es = new EventSource(`/api/game/events/${roomId}`);
+    const es = new EventSource(api(`/api/game/events/${roomId}`));
     es.addEventListener('ready', (e) => {
       try { setPaired(!!JSON.parse(e.data).paired); } catch {}
     });
@@ -111,7 +112,7 @@ export default function Game({ username, onGameOver, roomId, lanIp, ipCandidates
     stateRef.current.running = false;
     setRunning(false);
     try {
-      const res = await fetch('/api/score', {
+      const res = await fetch(api('/api/score'), {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ username, score: finalScore }),

src/Leaderboard.jsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { api } from './api.js';
 
 export default function Leaderboard({ username, lastResult, onPlayAgain, onChangeUser }) {
   const [data, setData] = React.useState(null);
@@ -9,7 +10,7 @@ export default function Leaderboard({ username, lastResult, onPlayAgain, onChang
     let alive = true;
     (async () => {
       try {
-        const r = await fetch(`/api/leaderboard?limit=25&username=${encodeURIComponent(username)}`)
+        const r = await fetch(api(`/api/leaderboard?limit=25&username=${encodeURIComponent(username)}`))
           .then((r) => r.json());
         if (!alive) return;
         if (!r.ok) throw new Error(r.error || 'failed');

src/MobileGame.jsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { api } from './api.js';
 
 const GAME_W = 640;
 const GAME_H = 380;
@@ -45,7 +46,7 @@ export default function MobileGame({ username, onGameOver }) {
     stateRef.current.running = false;
     setRunning(false);
     try {
-      const res = await fetch('/api/score', {
+      const res = await fetch(api('/api/score'), {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ username, score: finalScore }),

src/UsernameGate.jsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { api } from './api.js';
 
 export default function UsernameGate({ onPick, isMobile }) {
   const [value, setValue] = React.useState('');
@@ -21,7 +22,7 @@ export default function UsernameGate({ onPick, isMobile }) {
     setBusy(true);
     setError('');
     try {
-      const r = await fetch('/api/user/check', {
+      const r = await fetch(api('/api/user/check'), {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ username: name }),

src/api.js

@@ -0,0 +1,10 @@
+// Resolve API base URL.
+// - Dev: empty string → relative /api/* hits Vite's proxy to localhost:5174
+// - All-in-one prod: empty string → relative /api/* hits the same Express server that serves dist/
+// - Split prod (frontend on Vercel, backend on HF Space): set VITE_API_BASE=https://<space>.hf.space at build time
+const RAW = import.meta.env.VITE_API_BASE || '';
+export const API_BASE = RAW.replace(/\/+$/, '');
+
+export function api(path) {
+  return API_BASE + path;
+}

vercel.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "buildCommand": "npm run build",
+  "outputDirectory": "dist",
+  "framework": "vite",
+  "rewrites": [
+    { "source": "/controller", "destination": "/index.html" }
+  ]
+}