fluxy-bot 0.9.6 → 0.9.8

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "fluxy-bot",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "releaseNotes": [
-    "Another test for self update",
+    "Moving away from POST to use websockets instead",
     "2. ",
     "3. ",
     "4. "

package/supervisor/app-ws.js

@@ -0,0 +1,200 @@
+(function () {
+  if (window.__appWs) return;
+
+  var RECONNECT_BASE = 1000;
+  var RECONNECT_MAX = 8000;
+  var HEARTBEAT_MS = 25000;
+  var REQUEST_TIMEOUT = 30000;
+
+  var ws = null;
+  var connected = false;
+  var reconnectDelay = RECONNECT_BASE;
+  var reconnectTimer = null;
+  var heartbeatTimer = null;
+  var pendingRequests = {};
+  var requestCounter = 0;
+  var intentionalClose = false;
+  var originalFetch = window.fetch;
+
+  function buildWsUrl() {
+    var proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    return proto + '//' + location.host + '/app/ws';
+  }
+
+  function startHeartbeat() {
+    stopHeartbeat();
+    heartbeatTimer = setInterval(function () {
+      if (ws && ws.readyState === WebSocket.OPEN) ws.send('ping');
+    }, HEARTBEAT_MS);
+  }
+
+  function stopHeartbeat() {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  }
+
+  function failoverPending() {
+    var ids = Object.keys(pendingRequests);
+    for (var i = 0; i < ids.length; i++) {
+      var p = pendingRequests[ids[i]];
+      clearTimeout(p.timer);
+      console.log('[app-ws] WS dropped, falling back to fetch: ' + p.method + ' ' + p.path);
+      p.resolve(originalFetch(p.input, p.init));
+    }
+    pendingRequests = {};
+  }
+
+  function connect() {
+    intentionalClose = false;
+    var url = buildWsUrl();
+    ws = new WebSocket(url);
+
+    ws.onopen = function () {
+      connected = true;
+      reconnectDelay = RECONNECT_BASE;
+      startHeartbeat();
+      console.log('[app-ws] Connected to /app/ws');
+    };
+
+    ws.onmessage = function (e) {
+      if (e.data === 'pong') return;
+
+      var msg;
+      try {
+        msg = JSON.parse(e.data);
+      } catch (err) {
+        return;
+      }
+
+      if (msg.type === 'app:api:response' && msg.data && msg.data.id) {
+        var pending = pendingRequests[msg.data.id];
+        if (pending) {
+          clearTimeout(pending.timer);
+          delete pendingRequests[msg.data.id];
+
+          console.log('[app-ws] Response via WS: ' + msg.data.status + ' ' + pending.method + ' ' + pending.path);
+
+          var responseBody = msg.data.body;
+          if (responseBody === null || responseBody === undefined) responseBody = '';
+
+          var responseInit = {
+            status: msg.data.status,
+            headers: msg.data.headers || {},
+          };
+
+          pending.resolve(new Response(responseBody, responseInit));
+        }
+      }
+    };
+
+    ws.onclose = function () {
+      connected = false;
+      stopHeartbeat();
+      failoverPending();
+
+      if (!intentionalClose) {
+        console.log('[app-ws] Disconnected, reconnecting in ' + reconnectDelay + 'ms');
+        reconnectTimer = setTimeout(function () {
+          reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX);
+          connect();
+        }, reconnectDelay);
+      }
+    };
+
+    ws.onerror = function () {
+      if (ws) ws.close();
+    };
+  }
+
+  // Override window.fetch to intercept /app/api/* calls
+  window.fetch = function (input, init) {
+    var url = input instanceof Request ? input.url : String(input);
+    var method = (init && init.method) || (input instanceof Request ? input.method : 'GET');
+
+    // Only intercept /app/api/* calls
+    if (url.indexOf('/app/api') === -1) {
+      return originalFetch.apply(this, arguments);
+    }
+
+    // Fallback: WS not connected
+    if (!connected || !ws || ws.readyState !== WebSocket.OPEN) {
+      console.log('[app-ws] WS not connected, falling back to fetch: ' + method + ' ' + url);
+      return originalFetch.apply(this, arguments);
+    }
+
+    // Fallback: non-serializable body (FormData, Blob, ArrayBuffer)
+    var body = init && init.body;
+    if (body && (body instanceof FormData || body instanceof Blob || body instanceof ArrayBuffer)) {
+      console.log('[app-ws] Non-serializable body, falling back to fetch: ' + method + ' ' + url);
+      return originalFetch.apply(this, arguments);
+    }
+
+    // Build request
+    var id = 'r' + ++requestCounter + '-' + Date.now().toString(36);
+
+    var reqPath = url;
+    try {
+      var parsed = new URL(url, location.origin);
+      reqPath = parsed.pathname + parsed.search;
+    } catch (e) {}
+
+    var headers = {};
+    if (init && init.headers) {
+      if (init.headers instanceof Headers) {
+        init.headers.forEach(function (v, k) {
+          headers[k] = v;
+        });
+      } else if (typeof init.headers === 'object') {
+        var h = init.headers;
+        for (var k in h) {
+          if (Object.prototype.hasOwnProperty.call(h, k)) headers[k] = h[k];
+        }
+      }
+    }
+
+    var bodyStr = null;
+    if (body !== undefined && body !== null) {
+      bodyStr = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+
+    console.log('[app-ws] Proxying via WS: ' + method + ' ' + reqPath);
+
+    ws.send(
+      JSON.stringify({
+        type: 'app:api',
+        data: { id: id, method: method.toUpperCase(), path: reqPath, headers: headers, body: bodyStr },
+      })
+    );
+
+    var savedInput = input;
+    var savedInit = init;
+
+    return new Promise(function (resolve, reject) {
+      var timer = setTimeout(function () {
+        delete pendingRequests[id];
+        console.log('[app-ws] Request timed out, falling back to fetch: ' + method + ' ' + reqPath);
+        resolve(originalFetch(savedInput, savedInit));
+      }, REQUEST_TIMEOUT);
+
+      pendingRequests[id] = {
+        resolve: resolve,
+        reject: reject,
+        timer: timer,
+        input: savedInput,
+        init: savedInit,
+        method: method,
+        path: reqPath,
+      };
+    });
+  };
+
+  window.__appWs = {
+    connected: function () {
+      return connected;
+    },
+  };
+
+  connect();
+})();

package/supervisor/index.ts

@@ -154,11 +154,12 @@ self.addEventListener('notificationclick', function(event) {
 });
 `;
 
-const RECOVERING_HTML = `<!DOCTYPE html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Recovering</title>
-<style>body{background:#0a0a0f;color:#94a3b8;font-family:system-ui;display:flex;align-items:center;justify-content:center;height:100vh;margin:0}
-div{text-align:center}h1{font-size:18px;margin-bottom:8px;color:#e2e8f0}p{font-size:14px}a{color:#60a5fa}</style></head>
-<body><div><h1>Dashboard is restarting...</h1><p>Refreshing automatically.</p></div>
-<script>console.error('[refresh-diag] RECOVERING_HTML loaded — will auto-reload in 3s');setTimeout(()=>{console.error('[refresh-diag] RECOVERING_HTML 3s timer fired — reloading');location.reload()},3000)</script>
+const RECOVERING_HTML = `<!DOCTYPE html><html style="background:#222122"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Fluxy</title>
+<style>@keyframes _fs{to{transform:rotate(360deg)}}body{background:#222122;margin:0}</style></head>
+<body><div style="background:#222122;color:#fff;display:flex;flex-direction:column;align-items:center;justify-content:center;height:100dvh;width:100vw;font-family:system-ui,-apple-system,sans-serif">
+<img src="/fluxy-icon-192.png" width="56" height="56" style="border-radius:14px;margin-bottom:20px" alt="" />
+<div style="width:18px;height:18px;border:2px solid rgba(255,255,255,0.12);border-top-color:rgba(255,255,255,0.7);border-radius:50%;animation:_fs .6s linear infinite"></div>
+</div><script>setTimeout(function(){location.reload()},3000)</script>
 <script src="/fluxy/widget.js"></script></body></html>`;
 
 export async function startSupervisor() {
@@ -294,6 +295,14 @@ export async function startSupervisor() {
       return;
     }
 
+    // App WS client — served directly (proxies /app/api calls through WebSocket)
+    if (req.url === '/fluxy/app-ws.js') {
+      console.log('[supervisor] Serving /fluxy/app-ws.js directly');
+      res.writeHead(200, { 'Content-Type': 'application/javascript', 'Cache-Control': 'no-cache' });
+      res.end(fs.readFileSync(path.join(PKG_DIR, 'supervisor', 'app-ws.js')));
+      return;
+    }
+
     // Service worker — served from embedded constant (supervisor/ is always updated)
     if (req.url === '/sw.js' || req.url === '/fluxy/sw.js') {
       res.writeHead(200, { 'Content-Type': 'application/javascript', 'Cache-Control': 'no-cache' });
@@ -426,6 +435,94 @@ export async function startSupervisor() {
   // WebSocket: Fluxy chat + proxy worker WS
   const fluxyWss = new WebSocketServer({ noServer: true });
 
+  // WebSocket: App API proxy (routes /app/api calls through WS to avoid tunnel POST issues)
+  const appWss = new WebSocketServer({ noServer: true });
+
+  appWss.on('connection', (ws) => {
+    console.log('[supervisor] App API WS client connected');
+
+    ws.on('message', (raw) => {
+      const rawStr = raw.toString();
+
+      if (rawStr === 'ping') {
+        if (ws.readyState === WebSocket.OPEN) ws.send('pong');
+        return;
+      }
+
+      let msg: any;
+      try {
+        msg = JSON.parse(rawStr);
+      } catch {
+        return;
+      }
+
+      if (msg.type !== 'app:api' || !msg.data) return;
+
+      const { id, method, path: reqPath, headers: reqHeaders, body } = msg.data;
+      const backendPath = (reqPath || '').replace(/^\/app\/api/, '') || '/';
+
+      console.log(`[supervisor] App WS → backend :${backendPort} | ${method} ${backendPath} (${id})`);
+
+      if (!isBackendAlive()) {
+        console.log('[supervisor] App WS: Backend down — returning 503');
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({
+            type: 'app:api:response',
+            data: { id, status: 503, headers: { 'content-type': 'application/json' }, body: JSON.stringify({ error: 'Backend is starting...' }) },
+          }));
+        }
+        return;
+      }
+
+      const proxyHeaders: Record<string, string> = { ...(reqHeaders || {}) };
+      if (body && !proxyHeaders['content-type']) {
+        proxyHeaders['content-type'] = 'application/json';
+      }
+
+      const proxyReq = http.request(
+        { host: '127.0.0.1', port: backendPort, path: backendPath, method, headers: proxyHeaders },
+        (proxyRes) => {
+          const chunks: Buffer[] = [];
+          proxyRes.on('data', (chunk: Buffer) => chunks.push(chunk));
+          proxyRes.on('end', () => {
+            const responseBody = Buffer.concat(chunks).toString('utf-8');
+            const resHeaders: Record<string, string> = {};
+            for (const [k, v] of Object.entries(proxyRes.headers)) {
+              if (typeof v === 'string') resHeaders[k] = v;
+              else if (Array.isArray(v)) resHeaders[k] = v.join(', ');
+            }
+
+            console.log(`[supervisor] App WS ← backend: ${proxyRes.statusCode} (${id})`);
+
+            if (ws.readyState === WebSocket.OPEN) {
+              ws.send(JSON.stringify({
+                type: 'app:api:response',
+                data: { id, status: proxyRes.statusCode, headers: resHeaders, body: responseBody },
+              }));
+            }
+          });
+        },
+      );
+
+      proxyReq.on('error', (e) => {
+        console.error(`[supervisor] App WS backend error: ${backendPath}`, e.message);
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({
+            type: 'app:api:response',
+            data: { id, status: 503, headers: { 'content-type': 'application/json' }, body: JSON.stringify({ error: 'Backend unavailable' }) },
+          }));
+        }
+      });
+
+      if (body) proxyReq.write(body);
+      proxyReq.end();
+    });
+
+    ws.on('close', () => {
+      console.log('[supervisor] App API WS client disconnected');
+    });
+  });
+
   /** Send a message to all connected fluxy WS clients */
   function broadcastFluxy(type: string, data: any = {}) {
     const msg = JSON.stringify({ type, data });
@@ -805,6 +902,13 @@ export async function startSupervisor() {
   server.on('upgrade', async (req, socket: net.Socket, head) => {
     console.log(`[supervisor] WebSocket upgrade: ${req.url} | protocol=${req.headers['sec-websocket-protocol'] || 'none'}`);
 
+    // App API WebSocket — no auth (backend handles its own auth)
+    if (req.url?.startsWith('/app/ws')) {
+      console.log('[supervisor] → App API WebSocket');
+      appWss.handleUpgrade(req, socket, head, (ws) => appWss.emit('connection', ws, req));
+      return;
+    }
+
     if (!req.url?.startsWith('/fluxy/ws')) {
       console.log('[supervisor] → Letting Vite handle this upgrade');
       return;

package/supervisor/widget.js

@@ -139,4 +139,10 @@
       })
       .catch(function () {});
   } catch (e) {}
+
+  // Inject app-ws.js — proxies /app/api/* fetch calls through WebSocket
+  // (works around POST request failures through Cloudflare tunnel)
+  var awsScript = document.createElement('script');
+  awsScript.src = '/fluxy/app-ws.js';
+  document.head.appendChild(awsScript);
 })();

package/worker/prompts/fluxy-system-prompt.txt

@@ -265,9 +265,16 @@ Browser: GET /app/api/tasks → Supervisor strips prefix → Backend receives: G
 - **Backend** Express routes: register as `/tasks`, `/health` — NO `/app/api` prefix
 - No exceptions
 
+**Tunnel reliability:** All `/app/api/*` fetch calls from the dashboard are automatically proxied through WebSocket when available. This is transparent — just use `fetch('/app/api/...')` normally. The WebSocket proxy activates automatically and falls back to regular HTTP if unavailable. You don't need to handle this in your code.
+
 ## Build Rules
 NEVER run `npm run build`, `vite build`, or any build commands. Vite HMR handles frontend changes automatically. The backend auto-restarts when you edit files. Never look in `dist/` or `dist-fluxy/`.
 
+## Installing Packages
+You can install npm packages when a feature requires one that isn't already available. Run `npm install <package>` from the **project root** (`$PKG_DIR` / the parent of `workspace/`). Do NOT create a `package.json` inside `workspace/` — all dependencies live at the root level.
+
+Before installing, check if a suitable package is already in `node_modules/`. Prefer well-known, maintained packages. After installing, the backend picks up new imports on the next auto-restart and Vite resolves new frontend imports via HMR — no build step needed.
+
 ## Backend Lifecycle (Critical)
 
 The supervisor manages the backend process. You don't need to manage it yourself.
@@ -318,6 +325,53 @@ When an MCP server is configured, its tools appear alongside your built-in tools
 - `shared/` — shared utilities
 - `bin/` — CLI entry point
 
+## Workspace Security — CRITICAL: Two Password Systems
+
+There are TWO completely separate password systems in Fluxy. Understanding the difference is essential — confusing them WILL cause problems.
+
+### 1. Chat Password (Portal Password) — DO NOT TOUCH
+
+- **Set during onboarding** — it is MANDATORY. Every Fluxy has one.
+- **Protects the chat interface** (fluxy.bot/your_name) where your human talks to you.
+- Stored as `portal_pass` in the **worker** database (scrypt-hashed). You cannot and should not access or modify this.
+- **This is the MOST CRITICAL credential** — if compromised, an attacker gets chat access, and through you, they get terminal access, file access, and potentially root access to the entire machine.
+- Optional 2FA (TOTP) can be layered on top for extra protection.
+- **YOU DO NOT SET OR CHANGE THIS.** It was configured during onboarding. If your human mentions their "chat password" or "portal password", it refers to this. Never try to look it up, reset it, or modify it. If they need to change it, they re-run onboarding.
+
+### 2. Workspace Password (Dashboard Password) — YOU CAN SET THIS
+
+- **OPTIONAL — not set by default.**
+- Protects the **dashboard/workspace** (the `/app/` path) where your human's mini-apps, modules, data, and tools live.
+- **Without this password, ANYONE who knows the URL can view the entire workspace** — all pages, all data displayed in the UI.
+- Your human sets this **through you** — when they say "add a password", "protect the workspace", "lock the dashboard", or just "set a password", they mean THIS one. They already have a chat password.
+
+**How to set the workspace password:**
+```
+POST /app/api/workspace/set-password
+Body: { "password": "the_password" }
+```
+
+**How to remove it:**
+```
+POST /app/api/workspace/remove-password
+```
+
+**How it works under the hood:**
+- Password is hashed (scrypt with random salt) and stored in the workspace `app.db` database (`workspace_settings` table).
+- When someone visits the dashboard, a lock screen appears asking for the password.
+- On correct entry, a 7-day session token is created and stored in the browser's localStorage.
+- The session persists across page reloads until it expires or the password is changed.
+- Changing the password invalidates all existing sessions.
+
+### Default State — BE AWARE
+
+The workspace is **NOT secured by default**. If your human's Fluxy is accessible via the internet (relay, Cloudflare tunnel, etc.) and they haven't set a workspace password, their workspace data is visible to anyone who knows or guesses the URL. Be aware of this and **proactively suggest setting a workspace password** when appropriate — especially if sensitive data is in the workspace.
+
+### The Cardinal Rule
+
+**When your human says "add a password" or "set a password" → they mean the WORKSPACE password.**
+They already have a chat password from onboarding. Don't confuse the two. Don't go looking in the worker database for `portal_pass`. Don't tell them "you already have a password set." Set the workspace password using the route above.
+
 ## Modular Philosophy
 When your human asks for something new, don't rebuild the app — add a module. A sidebar icon, a dashboard card, a new page. Yesterday it was a CRM, today a finance tracker, tomorrow a diet log. They all coexist. Keep it organized.
 

package/workspace/client/index.html

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en">
+<html lang="en" style="background:#222122">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, interactive-widget=resizes-content" />
@@ -10,9 +10,21 @@
     <link rel="apple-touch-icon" href="/fluxy-icon-192.png" />
     <link rel="manifest" href="/manifest.json" />
     <title>Fluxy</title>
+    <style>
+      @keyframes _fs{to{transform:rotate(360deg)}}
+    </style>
   </head>
-  <body class="bg-background text-foreground">
+  <body class="bg-background text-foreground" style="background:#222122">
+    <!-- App shell splash — visible instantly, no JS needed.
+         Covers the screen during reload/restore so there's never a white flash.
+         React hides it on mount; shown again before any reload. -->
+    <div id="splash" style="background:#222122;color:#fff;display:flex;flex-direction:column;align-items:center;justify-content:center;height:100dvh;width:100vw;position:fixed;inset:0;z-index:9999;font-family:system-ui,-apple-system,sans-serif;transition:opacity .25s ease-out">
+      <img src="/fluxy-icon-192.png" width="56" height="56" style="border-radius:14px;margin-bottom:20px" alt="" />
+      <div style="width:18px;height:18px;border:2px solid rgba(255,255,255,0.12);border-top-color:rgba(255,255,255,0.7);border-radius:50%;animation:_fs .6s linear infinite"></div>
+    </div>
+
     <div id="root"></div>
+
     <script>
       // Global error handler — catches errors outside React's Error Boundary
       // (e.g., Vite compilation errors, module loading failures)
@@ -33,21 +45,12 @@
     <script>
     if('serviceWorker' in navigator){
       navigator.serviceWorker.register('/sw.js').then(function(r){
-        console.warn('[refresh-diag] SW registered, state:', r.active?.state, 'waiting:', !!r.waiting);
         r.update();
-        if(r.waiting){
-          console.warn('[refresh-diag] SW: found waiting worker — sending SKIP_WAITING');
-          r.waiting.postMessage({type:'SKIP_WAITING'});
-        }
+        if(r.waiting){r.waiting.postMessage({type:'SKIP_WAITING'})}
         r.addEventListener('updatefound',function(){
-          console.warn('[refresh-diag] SW: updatefound — new version installing');
           var w=r.installing;
           if(w)w.addEventListener('statechange',function(){
-            console.warn('[refresh-diag] SW installing statechange:', w.state);
-            if(w.state==='installed'&&navigator.serviceWorker.controller){
-              console.warn('[refresh-diag] SW: new version installed while controller exists — sending SKIP_WAITING');
-              w.postMessage({type:'SKIP_WAITING'});
-            }
+            if(w.state==='installed'&&navigator.serviceWorker.controller)w.postMessage({type:'SKIP_WAITING'});
           });
         });
       });

package/workspace/client/src/App.tsx

@@ -27,76 +27,69 @@ export default function App() {
   const [rebuildState, setRebuildState] = useState<'idle' | 'rebuilding' | 'error'>('idle');
   const [buildError, setBuildError] = useState('');
 
-  // ── Refresh diagnostics ──────────────────────────────────────────
-  // Logs every possible reload trigger so we can trace phantom refreshes.
-  // Safe to remove once the mystery is solved.
+  // ── Seamless reload: splash screen + freeze-thaw ──────────────────
+  // Prevents the "white flash" and "delayed reload" jank that plagues PWAs.
+  //
+  // How it works:
+  // 1. Any location.reload() shows the HTML splash BEFORE reloading
+  //    so the user sees: app → splash → splash → app (no white gap).
+  // 2. When returning from background (> 30s hidden), the splash shows
+  //    IMMEDIATELY — before Vite's delayed reconnect-reload can fire.
+  //    If no reload comes within 3s, the splash fades away.
+  // 3. Vite full-reloads trigger the splash too (same mechanism).
   useEffect(() => {
-    const t0 = Date.now();
-    const tag = `[refresh-diag ${new Date().toISOString()}]`;
+    const splash = document.getElementById('splash');
+    let hiddenAt = 0;
 
-    // 1. Log page load reason
-    const navEntries = performance.getEntriesByType('navigation') as PerformanceNavigationTiming[];
-    const navType = navEntries[0]?.type ?? 'unknown'; // 'navigate' | 'reload' | 'back_forward' | 'prerender'
-    console.warn(`${tag} Page loaded — navType="${navType}", wasDiscarded=${document.wasDiscarded ?? 'N/A'}, visState="${document.visibilityState}"`);
+    // Show the splash screen (used before reloads and on resume)
+    function showSplash() {
+      if (!splash) return;
+      splash.style.display = 'flex';
+      splash.style.opacity = '1';
+    }
+
+    // Hide the splash screen with a fade
+    function hideSplash() {
+      if (!splash || splash.style.display === 'none') return;
+      splash.style.opacity = '0';
+      splash.addEventListener('transitionend', () => { splash.style.display = 'none'; }, { once: true });
+    }
 
-    // 2. Intercept location.reload to capture stack trace
+    // Wrap location.reload: show splash, wait for paint, then reload.
+    // This ensures the dark splash is visible during the brief unload→load gap.
     const origReload = location.reload.bind(location);
     location.reload = () => {
-      console.error(`${tag} ⚠ location.reload() called! Stack trace:`);
-      console.trace();
-      origReload();
+      showSplash();
+      requestAnimationFrame(() => requestAnimationFrame(() => origReload()));
     };
 
-    // 3. Service Worker controller changes
-    if (navigator.serviceWorker) {
-      navigator.serviceWorker.addEventListener('controllerchange', () => {
-        console.warn(`${tag} SW controllerchange — new SW took control (can cause reload in some browsers)`);
-      });
-    }
-
-    // 4. Vite HMR events (Vite injects import.meta.hot on the client)
+    // Vite HMR: show splash before a full-reload
     if (import.meta.hot) {
-      // Vite fires 'vite:beforeFullReload' before a full page reload
-      import.meta.hot.on('vite:beforeFullReload', (payload: unknown) => {
-        console.error(`${tag} ⚠ Vite HMR: full-reload triggered!`, payload);
-        console.trace();
-      });
-      import.meta.hot.on('vite:beforeUpdate', (payload: unknown) => {
-        console.warn(`${tag} Vite HMR: beforeUpdate`, payload);
-      });
-      import.meta.hot.on('vite:error', (payload: unknown) => {
-        console.error(`${tag} Vite HMR: error`, payload);
-      });
-      import.meta.hot.on('vite:ws:disconnect', () => {
-        console.warn(`${tag} Vite HMR: WebSocket disconnected`);
-      });
-      import.meta.hot.on('vite:ws:connect', () => {
-        console.warn(`${tag} Vite HMR: WebSocket reconnected (may trigger full-reload if stale)`);
-      });
+      import.meta.hot.on('vite:beforeFullReload', () => showSplash());
     }
 
-    // 5. Visibility + focus changes (iOS kills PWA processes in background)
-    const onVisChange = () => console.warn(`${tag} visibilitychange → "${document.visibilityState}" (uptime: ${((Date.now() - t0) / 1000).toFixed(1)}s)`);
-    const onPageShow = (e: PageTransitionEvent) => console.warn(`${tag} pageshow — persisted=${e.persisted} (bfcache restore)`);
-    const onFreeze = () => console.warn(`${tag} freeze — page is being frozen by OS`);
-    const onResume = () => console.warn(`${tag} resume — page resumed from frozen state`);
-    document.addEventListener('visibilitychange', onVisChange);
-    window.addEventListener('pageshow', onPageShow);
-    document.addEventListener('freeze', onFreeze);
-    document.addEventListener('resume', onResume);
+    // Freeze-thaw: when returning from background after > 30s,
+    // show splash proactively so the user never sees the "working app
+    // suddenly yank away" pattern. If Vite decides to full-reload,
+    // the splash is already visible. If not, we fade it away after 3s.
+    let thawTimer: ReturnType<typeof setTimeout>;
+    const BACKGROUND_THRESHOLD = 30_000; // 30 seconds
 
-    // 6. beforeunload — last chance to log before the page goes away
-    const onBeforeUnload = () => {
-      console.warn(`${tag} beforeunload — page is about to unload (uptime: ${((Date.now() - t0) / 1000).toFixed(1)}s)`);
+    const onVisChange = () => {
+      if (document.visibilityState === 'hidden') {
+        hiddenAt = Date.now();
+      } else if (hiddenAt && Date.now() - hiddenAt > BACKGROUND_THRESHOLD) {
+        showSplash();
+        // Give Vite 3s to trigger a reload; if it doesn't, hide splash
+        clearTimeout(thawTimer);
+        thawTimer = setTimeout(hideSplash, 3_000);
+      }
     };
-    window.addEventListener('beforeunload', onBeforeUnload);
+    document.addEventListener('visibilitychange', onVisChange);
 
     return () => {
       document.removeEventListener('visibilitychange', onVisChange);
-      window.removeEventListener('pageshow', onPageShow);
-      document.removeEventListener('freeze', onFreeze);
-      document.removeEventListener('resume', onResume);
-      window.removeEventListener('beforeunload', onBeforeUnload);
+      clearTimeout(thawTimer);
     };
   }, []);
 
@@ -114,22 +107,16 @@ export default function App() {
     let safetyTimer: ReturnType<typeof setTimeout>;
     const handler = (e: MessageEvent) => {
       if (e.data?.type === 'fluxy:rebuilding') {
-        console.warn('[refresh-diag] fluxy:rebuilding received — starting 60s safety timer');
         setRebuildState('rebuilding');
         setBuildError('');
         // Safety: auto-reload after 60s in case app:rebuilt message is lost
         clearTimeout(safetyTimer);
-        safetyTimer = setTimeout(() => {
-          console.error('[refresh-diag] ⚠ 60s safety timer fired — forcing reload');
-          location.reload();
-        }, 60_000);
+        safetyTimer = setTimeout(() => location.reload(), 60_000);
       } else if (e.data?.type === 'fluxy:rebuilt') {
-        console.warn('[refresh-diag] fluxy:rebuilt received — reloading now');
         clearTimeout(safetyTimer);
         setRebuildState('idle');
         location.reload();
       } else if (e.data?.type === 'fluxy:build-error') {
-        console.warn('[refresh-diag] fluxy:build-error received:', e.data.error);
         clearTimeout(safetyTimer);
         setRebuildState('error');
         setBuildError(e.data.error || 'Build failed');

package/workspace/client/src/main.tsx

@@ -8,3 +8,10 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
     <App />
   </React.StrictMode>,
 );
+
+// Fade out the HTML splash screen now that React has mounted
+const splash = document.getElementById('splash');
+if (splash) {
+  splash.style.opacity = '0';
+  splash.addEventListener('transitionend', () => { splash.style.display = 'none'; }, { once: true });
+}