feat(hybrid): route /launch to a local backend from the deployed site

- api.js: launch() uses VITE_LAUNCH_BASE (falls back to the main API base).
  Set VITE_LAUNCH_BASE=http://localhost:8000 on the cloud build so the deployed
  site generates on the cloud but launches the real game on the user's PC.
- app.py: respond to Chrome's Private Network Access preflight so an HTTPS page
  may call the http://localhost backend.
- App.jsx: friendlier launch error pointing to start_local.bat.

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

Author: rlafurud

backend/app.py

@@ -55,6 +55,18 @@
 )
 
 
+# A deployed HTTPS page (e.g. the Vercel site) calling this local backend at
+# http://localhost:8000 triggers Chrome's Private Network Access check, which
+# needs this header on the preflight response. Added after CORS so it wraps the
+# CORS preflight reply. Harmless on the cloud backend (header just unused).
+@app.middleware("http")
+async def allow_private_network(request, call_next):
+    response = await call_next(request)
+    if request.headers.get("access-control-request-private-network"):
+        response.headers["Access-Control-Allow-Private-Network"] = "true"
+    return response
+
+
 class GenerateRequest(BaseModel):
     query: str
     seed: int | None = None

frontend/src/App.jsx

@@ -47,7 +47,12 @@ export default function App() {
         setLaunchMsg({ ok: false, text: `실행 실패: ${res.error || '알 수 없는 오류'}` })
       }
     } catch (e) {
-      setLaunchMsg({ ok: false, text: `백엔드에 연결하지 못했어요 (${e.message}).` })
+      // Most common cause on the deployed site: launch is routed to the user's
+      // local backend, which isn't running.
+      setLaunchMsg({
+        ok: false,
+        text: `로컬 백엔드에 연결하지 못했어요. 내 PC에서 start_local.bat을 실행해 켜두세요. (${e.message})`,
+      })
     } finally {
       setLaunching(false)
     }

frontend/src/api.js

@@ -5,6 +5,13 @@
 // double slash ("//generate") that the backend 404s on.
 const BASE = (import.meta.env.VITE_API_BASE ?? '/api').replace(/\/+$/, '')
 
+// /launch opens the real game on the machine running the backend, so it must
+// hit a backend with BAR installed. Defaults to the same backend as everything
+// else (local single-process). On a cloud deploy set
+// VITE_LAUNCH_BASE=http://localhost:8000 to route launch to the user's own
+// local backend while generation stays on the cloud.
+const LAUNCH_BASE = (import.meta.env.VITE_LAUNCH_BASE ?? BASE).replace(/\/+$/, '')
+
 export async function getCatalog() {
   const res = await fetch(`${BASE}/catalog`)
   if (!res.ok) throw new Error(`catalog failed: ${res.status}`)
@@ -23,7 +30,7 @@ export async function generate(query, seed) {
 
 // Launch the generated config in the actual BAR client (via the v4 simulator).
 export async function launch(config, mode = 'gadget') {
-  const res = await fetch(`${BASE}/launch`, {
+  const res = await fetch(`${LAUNCH_BASE}/launch`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ config, mode }),