bloby-bot 0.63.0 → 0.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.63.0",
+  "version": "0.64.0",
   "releaseNotes": [
     "1. Fix: image (and audio) attachments now render in chat again — /api/files is fetched with the auth token instead of a raw <img> src that 401'd after the endpoint hardening",
     "2. Affects chat thumbnails, the image lightbox, voice-note playback, and agent image cards",

package/supervisor/index.ts

@@ -27,6 +27,7 @@ import { startScheduler, stopScheduler, readPulseConfig, readCronsConfig, nextRu
 import { execSync, spawn as cpSpawn } from 'child_process';
 import crypto from 'crypto';
 import { ChannelManager } from './channels/manager.js';
+import { SHELL_HTML } from './shell.js';
 
 // Last-resort process-level safety nets. The supervisor is the SINGLE process that keeps
 // chat alive (G1) and heals the backend (G3); a stray throw inside an emitter callback
@@ -120,7 +121,7 @@ const SW_JS = `// Service worker — app-shell caching + push notifications
 // cached shell that masks a broken (or just-fixed) frontend and produces the confusing
 // "normal refresh is broken but hard refresh works" split. Cache is a pure offline fallback.
 
-var CACHE = 'bloby-v23';
+var CACHE = 'bloby-v24';
 var HASHED_RE = new RegExp('/assets/.+-[a-zA-Z0-9]{6,}[.](js|css)$');
 
 // Precache the HTML shell on install so the cache is never empty.
@@ -184,6 +185,10 @@ self.addEventListener('fetch', function(event) {
   // caching the wrong HTML under the / key.
   if (request.mode === 'navigate') {
     console.log('[SW] navigate →', url.pathname);
+    // Workspace iframe documents (?__bloby_frame=1) share pathname '/' with the shell.
+    // Network-only: never c.put() them (would overwrite the precached shell under the '/'
+    // key) and never fall back to c.match('/') (would serve the shell INTO the iframe).
+    if (url.searchParams.has('__bloby_frame')) return;
     if (url.pathname === '/' || url.pathname === '/index.html') {
       // Network-first: always fetch the live dashboard; only fall back to cache when offline.
       event.respondWith(caches.open(CACHE).then(function(c) {
@@ -2560,6 +2565,47 @@ ${alreadyLinked ? '' : `
       } catch { /* fall through to Vite */ }
     }
 
+    // Document-ish request? Used by the backend-down interstitial (NOT the shell branch,
+    // which needs top-level-only gating). sec-fetch-dest 'document' covers top-level
+    // navigations; sec-fetch-mode 'navigate' also matches iframe documents (dest 'iframe',
+    // wanted here — the interstitial must show inside the workspace frame too); the accept
+    // fallback covers old clients that send no sec-fetch headers at all.
+    const wantsHtml = req.method === 'GET' && (
+      req.headers['sec-fetch-dest'] === 'document' ||
+      req.headers['sec-fetch-mode'] === 'navigate' ||
+      (!req.headers['sec-fetch-dest'] && String(req.headers['accept'] || '').includes('text/html'))
+    );
+
+    // SHELL INVERSION: TOP-LEVEL document navigations get the immortal shell (bubble +
+    // chat + a same-origin iframe that hosts the actual workspace app). The iframe
+    // re-requests the same URL with ?__bloby_frame=1, which skips this branch and falls
+    // through to the interstitials / Vite proxy below — so Vite reloads, rebuilds, and
+    // crash pages all happen INSIDE the iframe while the chat chrome survives. (The
+    // Lovable/Bolt pattern.) The __bloby_frame param is lost on real in-frame navigations
+    // (<a href> links, location.href redirects, 302s), so the frame is also excluded by
+    // sec-fetch-dest — those requests carry dest 'iframe' and must fall through to Vite,
+    // never get a nested shell. wantsHtml is intentionally NOT reused here: its
+    // mode === 'navigate' arm matches iframe documents (fine for the interstitial below,
+    // wrong for the shell). pathname === '/' is special-cased because the service worker's
+    // install-time precache fetch of '/' may carry no sec-fetch/accept headers yet must
+    // still cache the shell.
+    // Kill switch: BLOBY_NO_SHELL=1 restores legacy behavior (workspace served top-level;
+    // widget.js injects the bubble into the workspace document as before).
+    const fetchDest = req.headers['sec-fetch-dest'];
+    const isSubframe = fetchDest === 'iframe' || fetchDest === 'frame' || fetchDest === 'embed' || fetchDest === 'object';
+    if (
+      req.method === 'GET' &&
+      process.env.BLOBY_NO_SHELL !== '1' &&
+      !(req.url || '').includes('__bloby_frame=1') &&
+      !isSubframe &&
+      (cleanUrl === '/' || fetchDest === 'document' ||
+        (!fetchDest && String(req.headers['accept'] || '').includes('text/html')))
+    ) {
+      res.writeHead(200, { 'Content-Type': 'text/html', 'Cache-Control': 'no-cache', 'X-Bloby-Origin': 'supervisor' });
+      res.end(SHELL_HTML);
+      return;
+    }
+
     // Workspace backend has crash-looped and given up → serve the "backend down" interstitial
     // for dashboard DOCUMENT navigations, instead of proxying to Vite (which serves the user's
     // SPA that then 503s on every /app/api call and, for the common workspace-lock template,
@@ -2567,11 +2613,6 @@ ${alreadyLinked ? '' : `
     // top-level navigations only (not assets/HMR/XHR) and only when the backend has truly given
     // up — never during a normal 1–2s restart. The chat PWA (/bloby/*) is served earlier and is
     // unaffected.
-    const wantsHtml = req.method === 'GET' && (
-      req.headers['sec-fetch-dest'] === 'document' ||
-      req.headers['sec-fetch-mode'] === 'navigate' ||
-      (!req.headers['sec-fetch-dest'] && String(req.headers['accept'] || '').includes('text/html'))
-    );
     if (wantsHtml && isBackendDead()) {
       // X-Bloby-Origin marks this as the agent's OWN branded page so the relay passes it through
       // (and never mistakes it for a Cloudflare tunnel error to be replaced).

package/supervisor/shell.ts

@@ -0,0 +1,120 @@
+// The immortal shell — served by the supervisor at top-level '/' (and document navigations).
+// It contains ONLY the bubble + chat chrome (widget.js) and a same-origin iframe hosting the
+// user's workspace app. There is NO Vite client here, NO HMR, no service-worker auto-reload —
+// nothing that can reload this page. All workspace reloads, rebuilds, and interstitials
+// (RECOVERING_HTML / backend-down) happen INSIDE the iframe, so the chat — the user's lifeline
+// to the agent — never dies. The iframe src carries ?__bloby_frame=1 so the supervisor routes
+// it past the shell branch to the real workspace (Vite proxy / interstitials).
+// Kill switch: BLOBY_NO_SHELL=1 makes the supervisor skip this entirely (legacy top-level
+// workspace). Static string by design — no server-side templating.
+
+export const SHELL_HTML = `<!DOCTYPE html>
+<html lang="en" style="background-color:#0A0A0A;margin:0;overflow:hidden">
+  <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" />
+    <meta name="theme-color" content="#212121" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+    <meta name="apple-mobile-web-app-title" content="Bloby" />
+    <link rel="icon" type="image/png" href="/morphy-favicon.png" />
+    <link rel="apple-touch-icon" href="/morphy-icon-192.png" />
+    <link rel="manifest" href="/manifest.json" />
+    <title>Bloby</title>
+  </head>
+  <body style="background-color:#0A0A0A;margin:0;overflow:hidden">
+    <!-- Dark background fallback — visible instantly while widget.js loads.
+         The canvas animation (in widget.js) takes over as the actual splash. -->
+    <div id="splash" style="background:#0A0A0A;position:fixed;inset:0;z-index:9998;transition:opacity .25s ease-out"></div>
+
+    <iframe
+      id="bloby-workspace"
+      style="position:fixed;inset:0;width:100vw;height:100dvh;border:none;background:#0A0A0A"
+      allow="camera; microphone; geolocation; clipboard-read; clipboard-write; fullscreen; autoplay; display-capture"
+      allowfullscreen
+    ></iframe>
+
+    <script>
+    (function () {
+      var frame = document.getElementById('bloby-workspace');
+
+      // Preserve deep links: the iframe loads the SAME url the shell was opened with, plus
+      // __bloby_frame=1 so the supervisor serves the workspace instead of the shell again.
+      // Collapse leading slashes first — a pathname like '//evil.com' would otherwise be a
+      // protocol-relative URL and point the iframe off-origin under our trusted domain.
+      var path = location.pathname.replace(/^\\/+/, '/');
+      var target = new URL(path + location.search + location.hash, location.origin);
+      if (target.origin !== location.origin) target = new URL('/', location.origin);
+      target.searchParams.set('__bloby_frame', '1');
+
+      // Framed shell self-check: browsers without Fetch Metadata (older Safari/WebViews) can
+      // get a shell served INTO the workspace iframe when an in-frame navigation loses the
+      // __bloby_frame param (the supervisor's sec-fetch-dest exclusion can't see those).
+      // A nested shell replaces itself with the workspace document it should have been.
+      try {
+        if (window.top !== window) {
+          location.replace(target.pathname + target.search + target.hash);
+          return;
+        }
+      } catch (e) { /* cross-origin top — not our nesting case; carry on */ }
+
+      frame.src = target.pathname + target.search + target.hash;
+
+      // widget.js (loaded below, in THIS document) waits for window.__blobyAppReady / the
+      // 'bloby:app-ready' window event before transitioning splash → bubble. The workspace
+      // posts 'bloby:app-ready' up to us; we re-dispatch it locally. Idempotent.
+      var appReadyFired = false;
+      function fireAppReady() {
+        if (appReadyFired) return;
+        appReadyFired = true;
+        window.__blobyAppReady = true;
+        window.dispatchEvent(new Event('bloby:app-ready'));
+      }
+
+      window.addEventListener('message', function (e) {
+        // Same-origin iframe only — drop anything else (extensions, third-party embeds).
+        if (e.origin !== location.origin) return;
+        var d = e.data;
+        if (!d || typeof d.type !== 'string') return;
+        if (d.type === 'bloby:app-ready') {
+          fireAppReady();
+        } else if (d.type === 'bloby:title') {
+          document.title = String(d.title || '').slice(0, 200) || 'Bloby';
+        }
+      });
+
+      // Interstitials and broken workspaces never post 'bloby:app-ready' — the bubble must
+      // still appear (it IS the recovery path). Fire on iframe load, with a timer backstop
+      // for the case where the iframe never finishes loading at all.
+      frame.addEventListener('load', fireAppReady);
+      setTimeout(fireAppReady, 8000);
+
+      // Last-resort splash backstop: only widget.js ever hides #splash (it does so as soon
+      // as its sprite loads, ~1s). If widget.js fails to load, throws, or its sprite fetch
+      // fails, the shell — the user's lifeline — must not sit as a permanent black screen
+      // over the workspace iframe.
+      setTimeout(function () {
+        var s = document.getElementById('splash');
+        if (s && s.style.display !== 'none') s.style.display = 'none';
+      }, 10000);
+    })();
+    </script>
+
+    <script>
+    // Register the SW but DO NOT auto-reload on controllerchange.
+    // The old pattern (skipWaiting + claim + controllerchange → location.reload)
+    // caused surprise reloads on mobile PWAs: iOS aggressively re-checks sw.js
+    // and any byte-level variation in the response (esp. via Vite dev) trips a
+    // new SW activation → controllerchange → unwanted reload. The new SW
+    // silently takes over for future fetches; the user gets the new build on
+    // their next natural refresh.
+    if ('serviceWorker' in navigator) {
+      navigator.serviceWorker.register('/sw.js').catch(function (err) {
+        console.error('[sw-reg] registration failed:', err);
+      });
+    }
+    </script>
+    <script src="/bloby/widget.js"></script>
+  </body>
+</html>
+`;

package/supervisor/widget.js

@@ -1,4 +1,19 @@
 (function () {
+  // app-ws.js (the /app/api → /app/ws fetch proxy) must load in EVERY document
+  // that includes widget.js — in shell mode the workspace runs inside the
+  // iframe, where the early return below would skip it, leaving the user's
+  // /app/api calls as raw tunnel POSTs. app-ws.js guards itself
+  // (window.__appWs), so duplicate loads are no-ops.
+  var awsScript = document.createElement('script');
+  awsScript.src = '/bloby/app-ws.js';
+  document.head.appendChild(awsScript);
+
+  // Shell mode: the immortal shell loads this script at top level, but legacy
+  // workspace index.html + the interstitial pages still reference it too, and
+  // those now render inside the shell's iframe — inside any iframe this must
+  // no-op so exactly one bubble exists. Cross-origin window.top access throws,
+  // which also means we're not the top window.
+  try { if (window.top !== window) return; } catch (e) { return; }
   if (document.getElementById('bloby-widget')) return;
 
   var PANEL_WIDTH = '480px';
@@ -571,7 +586,7 @@
           var reader = new FileReader();
           reader.onloadend = function() {
             var base64 = reader.result.split(',')[1];
-            if (base64 && iframe.contentWindow) iframe.contentWindow.postMessage({ type: 'bloby:voice-record', audio: base64 }, '*');
+            if (base64 && iframe.contentWindow) iframe.contentWindow.postMessage({ type: 'bloby:voice-record', audio: base64 }, location.origin);
           };
           reader.readAsDataURL(blob);
         };
@@ -583,7 +598,7 @@
           if (sent) return; sent = true;
           var text = hpSpeechTranscript.trim();
           hpSpeechTranscript = '';
-          if (text && iframe.contentWindow) iframe.contentWindow.postMessage({ type: 'bloby:voice-record', transcript: text }, '*');
+          if (text && iframe.contentWindow) iframe.contentWindow.postMessage({ type: 'bloby:voice-record', transcript: text }, location.origin);
         };
         instance.onend = function() { hpSpeechInstance = null; sendTranscript(); };
         try { instance.stop(); } catch(e) { hpSpeechInstance = null; sendTranscript(); }
@@ -760,21 +775,25 @@
 
   // Handle messages from iframe
   window.addEventListener('message', function (e) {
+    // Chat iframe + workspace iframe are same-origin; hardens against any third-party frame.
+    if (e.origin !== location.origin) return;
     if (!e.data || !e.data.type) return;
     if (e.data.type === 'bloby:close' && isOpen) toggle();
+    // Workspace iframe forwards Escape keypresses so ESC still closes the chat
+    // when focus is inside the user's app.
+    if (e.data.type === 'bloby:esc' && isOpen) toggle();
+    // Shell mode: the workspace app's same-document 'bloby:app-ready' window
+    // event fires inside the iframe, so the guard forwards it as a postMessage.
+    if (e.data.type === 'bloby:app-ready') { appReady = true; maybeTransition(); }
     if (e.data.type === 'bloby:new-message' && !isOpen) { unreadCount++; updateBadge(); }
     if (e.data.type === 'bloby:install-app') {
       if (deferredInstallPrompt) {
         deferredInstallPrompt.prompt();
         deferredInstallPrompt.userChoice.then(function (r) { if (r.outcome === 'accepted') deferredInstallPrompt = null; });
-      } else { iframe.contentWindow.postMessage({ type: 'bloby:show-ios-install' }, '*'); }
+      } else { iframe.contentWindow.postMessage({ type: 'bloby:show-ios-install' }, location.origin); }
     }
     if (e.data.type === 'bloby:onboard-complete') { onboardActive = false; hideAfterTransition = false; canvas.style.display = 'block'; }
   });
 
   try { if (sessionStorage.getItem('bloby_widget_open') === '1') { sessionStorage.removeItem('bloby_widget_open'); if (canvasPhase === 'bubble') toggle(); } } catch (e) {}
-
-  var awsScript = document.createElement('script');
-  awsScript.src = '/bloby/app-ws.js';
-  document.head.appendChild(awsScript);
 })();

package/supervisor/workspace-guard.js

@@ -1,6 +1,6 @@
 (function () {
   // Injected by the supervisor into the workspace dashboard HTML (and ONLY there — never the
-  // chat PWA or the supervisor's own interstitials). Two jobs, both aimed at non-technical users:
+  // chat PWA or the supervisor's own interstitials). Five jobs, all aimed at non-technical users:
   //
   //   1. Backend-down auto-detect — when the workspace backend crash-loops and gives up, the
   //      supervisor serves a full "backend down" interstitial on the next navigation. Poll for
@@ -19,6 +19,22 @@
   //      console AND to a sessionStorage ring buffer that survives the reload, so the page that
   //      comes back can print exactly what killed its predecessor. Look for the
   //      "[bloby-forensics]" banner in the console after a mystery refresh.
+  //
+  //   4. Shell relay — under shell inversion the workspace renders inside the immortal shell's
+  //      same-origin iframe and the chat bubble lives in the shell, so signals that used to be
+  //      same-window must cross the frame boundary: app readiness ({type:'bloby:app-ready'}),
+  //      document title ({type:'bloby:title'}), Escape keydowns ({type:'bloby:esc'}), and the
+  //      nested onboard wizard's {type:'bloby:onboard-complete'} are posted up to the parent.
+  //      No-ops when this document IS the top window (legacy mode / BLOBY_NO_SHELL=1).
+  //
+  //   5. Vite reconnect-reload suppression + staleness check — Vite's HMR client hard-reloads
+  //      the page whenever its WebSocket drops. With an immortal dev server behind a fragile
+  //      tunnel (and mobile backgrounding), that reload is almost always pointless. A
+  //      synchronously-throwing 'vite:ws:disconnect' listener cancels it — but Vite 8 has NO
+  //      reconnect loop (the suppressed reload IS its reconnection strategy), so the same
+  //      handler starts a recovery poll against a server-side change counter
+  //      (/__bloby/fe-stamp) and reloads ONLY when frontend files actually changed while the
+  //      socket was dead.
   if (window.__blobyWorkspaceGuard) return;
   window.__blobyWorkspaceGuard = true;
 
@@ -98,14 +114,122 @@
     }
   } catch (e) {}
 
-  // Vite HMR client events — THE prime suspect. 'vite:ws:disconnect' followed by
-  // 'location.reload' with a client.mjs stack = Vite's reload-on-reconnect fired.
+  // Vite HMR client events — forensics (job 3) + reconnect-reload suppression and staleness
+  // check (job 5), all on one hot context.
+  //
+  // The suppression throw below is dispatched from the transport's socket 'close' handler
+  // without an await/catch (client.mjs), so it surfaces as a window 'unhandledrejection'.
+  // The error-overlay handler further down recognizes this marker and ignores it.
+  var VITE_SUPPRESS_MARK = '[bloby] suppressing vite reload-on-reconnect';
   try {
     import('/@vite/client').then(function (m) {
       var hot = m.createHotContext('/__bloby_forensics.js');
-      hot.on('vite:ws:disconnect', function () { flog('vite:ws:disconnect', 'visible=' + document.visibilityState); });
-      hot.on('vite:ws:connect', function () { flog('vite:ws:connect'); });
-      hot.on('vite:beforeFullReload', function (p) { flog('vite:beforeFullReload', p && p.path ? 'path=' + p.path : ''); });
+
+      // Staleness stamp: a Vite-plugin middleware (reached through the supervisor's dashboard
+      // proxy) serves /__bloby/fe-stamp as {stamp:N}, bumped on every frontend hot update.
+      // Comparing the stamp across a disconnect tells us whether anything actually changed
+      // while we were gone. When Vite is down the supervisor answers 503 HTML — json() rejects
+      // and we treat it as "not back yet", never as "changed".
+      var lastStamp = null;
+      function fetchStamp() {
+        return fetch('/__bloby/fe-stamp', { cache: 'no-store' })
+          .then(function (r) { return r.json(); })
+          .then(function (j) { return (j && typeof j.stamp === 'number') ? j.stamp : null; });
+      }
+      function refreshStamp(reason) {
+        fetchStamp().then(function (s) {
+          if (s !== null) lastStamp = s;
+        }).catch(function (err) { flog('fe-stamp', reason + ' fetch failed: ' + err); });
+      }
+      // Baseline with retry: a transient blip right at page load must not leave us without a
+      // baseline — the recovery poll would then adopt a possibly-already-moved stamp as truth.
+      (function initStamp(attempt) {
+        fetchStamp().then(function (s) {
+          if (s !== null) { lastStamp = s; return; }
+          throw new Error('bad payload');
+        }).catch(function (err) {
+          if (attempt >= 5) { flog('fe-stamp', 'init gave up: ' + err); return; }
+          setTimeout(function () { initStamp(attempt + 1); }, 2000 * (attempt + 1));
+        });
+      })(0);
+
+      // Recovery poll — the ONLY change signal after a disconnect. Vite 8 never reconnects a
+      // dropped socket: transport.connect() runs once at module init, and the reload we
+      // suppress below is what would have re-run it. So once disconnected, HMR messages and
+      // 'vite:ws:connect' are gone for good; we poll the stamp instead. Stamp moved → reload
+      // (restores both freshness and HMR). Stamp unchanged → page content is current, keep
+      // polling (HMR stays dead until the next agent edit bumps the stamp). A failed fetch
+      // (supervisor's 503 HTML while Vite is down → json() rejects) means "not back yet".
+      // Single instance so rapid disconnects don't stack timers; paused while hidden
+      // (mirrors Vite's own visibility-aware ping) and kicked on visibility/online.
+      var recoveryTimer = null;
+      function recoveryTick() {
+        if (document.visibilityState === 'hidden') return;
+        fetchStamp().then(function (s) {
+          if (s === null || recoveryTimer === null) return;
+          if (lastStamp === null) { lastStamp = s; return; } // no baseline — adopt and watch
+          if (s !== lastStamp) {
+            flog('stale-after-disconnect', 'stamp ' + lastStamp + '→' + s);
+            stopRecoveryPoll();
+            location.reload(); // goes through the forensics wrapper: logged + splash
+          }
+        }).catch(function () {});
+      }
+      function startRecoveryPoll() {
+        if (recoveryTimer !== null) return;
+        flog('recovery-poll', 'started');
+        recoveryTimer = setInterval(recoveryTick, 3000);
+        recoveryTick();
+      }
+      function stopRecoveryPoll() {
+        if (recoveryTimer === null) return;
+        clearInterval(recoveryTimer);
+        recoveryTimer = null;
+        flog('recovery-poll', 'stopped');
+      }
+      document.addEventListener('visibilitychange', function () {
+        if (document.visibilityState === 'visible' && recoveryTimer !== null) recoveryTick();
+      });
+      window.addEventListener('online', function () {
+        if (recoveryTimer !== null) recoveryTick();
+      });
+
+      hot.on('vite:ws:disconnect', function () {
+        flog('vite:ws:disconnect', 'visible=' + document.visibilityState);
+        // The poll must start BEFORE the suppressing throw aborts this handler.
+        startRecoveryPoll();
+        // Cancel Vite's reload-on-reconnect: client.mjs handleMessage awaits
+        // notifyListeners('vite:ws:disconnect') BEFORE waitForSuccessfulPing() +
+        // location.reload(). notifyListeners runs cbs.map((cb) => cb(data)) synchronously, so
+        // a SYNCHRONOUS throw here rejects that awaited promise and the reload never runs.
+        // (An async listener would NOT work — Promise.allSettled swallows rejections.) We
+        // suppress because the dev server is immortal while the tunnel/mobile connection is
+        // fragile: every blip would otherwise hard-reload a perfectly-current page. Net
+        // effect with the recovery poll above: connection blips no longer reload the page;
+        // we reload ONLY when edits actually happened while disconnected.
+        throw new Error(VITE_SUPPRESS_MARK + ' — staleness is handled by the recovery poll instead');
+      });
+      // Dead code on Vite 8 after the first disconnect (the event is emitted only inside
+      // transport.connect(), which never re-runs) — kept as a fast path for a future Vite
+      // that reconnects in place.
+      hot.on('vite:ws:connect', function () {
+        flog('vite:ws:connect');
+        stopRecoveryPoll();
+        if (lastStamp === null) { refreshStamp('connect'); return; }
+        fetchStamp().then(function (s) {
+          if (s === null) return;
+          if (s !== lastStamp) {
+            flog('stale-after-reconnect', 'stamp ' + lastStamp + '→' + s);
+            location.reload(); // goes through the forensics wrapper: logged + splash
+          }
+        }).catch(function (err) { flog('fe-stamp', 'connect fetch failed: ' + err); });
+      });
+      // We just received these updates over the live socket, so we're current — resync.
+      hot.on('vite:afterUpdate', function () { refreshStamp('after-update'); });
+      hot.on('vite:beforeFullReload', function (p) {
+        flog('vite:beforeFullReload', p && p.path ? 'path=' + p.path : '');
+        refreshStamp('before-full-reload');
+      });
       hot.on('vite:invalidate', function (p) { flog('vite:invalidate', (p && p.path) || ''); });
       hot.on('vite:error', function (p) { flog('vite:error', p && p.err && p.err.message || ''); });
       flog('vite-hooks', 'installed');
@@ -114,6 +238,80 @@
     flog('vite-hooks', 'unavailable: ' + e);
   }
 
+  /* ── 4. Shell relay ───────────────────────────────────────────────────── */
+  // The shell (parent) hosts the bubble + chat; this document is its same-origin iframe.
+  // Everything here no-ops when we ARE the top window (legacy mode / BLOBY_NO_SHELL=1).
+  (function () {
+    var framed = false;
+    try { framed = !!window.parent && window.parent !== window; } catch (e) {}
+    if (!framed) return;
+
+    function post(msg) {
+      try { window.parent.postMessage(msg, location.origin); } catch (e) {}
+    }
+
+    // a. App readiness. The workspace's main.tsx dispatches the same-window DOM Event
+    // 'bloby:app-ready' and sets window.__blobyAppReady after first paint. The event may have
+    // fired before this script ran (or a custom workspace may never dispatch it), so also
+    // check the flag now and poll it; give up after 20s. Send at most once.
+    //
+    // Readiness also hides the workspace's own opaque #splash (index.html, z-index 9998):
+    // widget.js — the only thing that ever hid it — no-ops inside frames, so without this
+    // every shell-mode load (including onboarding, whose iframe sits at z-index 200) stays
+    // black forever. Timeout backstop (~8s, matching the shell's own) keeps broken apps
+    // visible too. Framed-only, so legacy mode still gets widget.js's splash animation.
+    var readySent = false;
+    function hideSplash() {
+      try {
+        var s = document.getElementById('splash');
+        if (s) s.style.display = 'none';
+      } catch (e) {}
+    }
+    setTimeout(hideSplash, 8000);
+    function sendReady() {
+      if (readySent) return;
+      readySent = true;
+      hideSplash();
+      post({ type: 'bloby:app-ready' });
+    }
+    window.addEventListener('bloby:app-ready', sendReady);
+    if (window.__blobyAppReady) sendReady();
+    var readyPolls = 0;
+    var readyTimer = setInterval(function () {
+      if (window.__blobyAppReady) sendReady();
+      if (readySent || ++readyPolls >= 80) clearInterval(readyTimer); // 80 × 250ms = 20s
+    }, 250);
+
+    // b. Title sync — the shell mirrors the iframe's title into the real tab title.
+    function postTitle() {
+      if (document.title) post({ type: 'bloby:title', title: document.title });
+    }
+    postTitle();
+    try {
+      var titleEl = document.querySelector('title');
+      if (titleEl) {
+        new MutationObserver(postTitle).observe(titleEl, { childList: true, characterData: true, subtree: true });
+      }
+    } catch (e) {}
+
+    // c. Escape — keydown inside the iframe never reaches the shell document, so the shell's
+    // widget would miss its close-the-chat-panel shortcut.
+    window.addEventListener('keydown', function (e) {
+      if (e.key === 'Escape') post({ type: 'bloby:esc' });
+    });
+
+    // d. Onboard relay — the onboarding wizard iframe is nested INSIDE this workspace app and
+    // posts {type:'bloby:onboard-complete'} to ITS parent (= this window); the widget that
+    // must un-hide the bubble now lives in the shell. Re-post upward. Loop-safe by direction:
+    // only messages from below (never from the parent shell) are relayed.
+    window.addEventListener('message', function (e) {
+      if (e.source === window.parent) return;
+      if (e.origin === location.origin && e.data && e.data.type === 'bloby:onboard-complete') {
+        post(e.data);
+      }
+    });
+  })();
+
   /* ── 1. Backend-down auto-detect ──────────────────────────────────────── */
   var reloading = false;
   function pollBackend() {
@@ -217,6 +415,14 @@
   new MutationObserver(evaluate).observe(document.body, { childList: true });
   setInterval(evaluate, 1500);
   window.addEventListener('error', function () { sawError = true; evaluate(); });
-  window.addEventListener('unhandledrejection', function () { sawError = true; evaluate(); });
+  window.addEventListener('unhandledrejection', function (e) {
+    // The reconnect-reload suppressor (job 5) throws a marker error inside Vite's HMR
+    // dispatch; it surfaces here on every tunnel blip. Not an app error — swallow it.
+    try {
+      var msg = e && e.reason && e.reason.message;
+      if (msg && String(msg).indexOf(VITE_SUPPRESS_MARK) !== -1) { e.preventDefault(); return; }
+    } catch (err) {}
+    sawError = true; evaluate();
+  });
   evaluate();
 })();

package/vite.config.ts

@@ -1,8 +1,39 @@
-import { defineConfig } from 'vite';
+import { defineConfig, type Plugin } from 'vite';
 import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
 import path from 'path';
 
+// Backs workspace-guard.js's reconnect staleness check: Vite's reload-on-reconnect
+// is suppressed client-side, and on reconnect the client fetches this stamp and
+// reloads ONLY if frontend code actually changed while it was disconnected.
+// Seeded with Date.now() (not 0) so a Vite/supervisor restart — which resets this
+// module — always reads as "changed" → clients reload after restarts, which is
+// exactly right (in-memory HMR state is gone).
+function blobyFeStamp(): Plugin {
+  let stamp = Date.now();
+  return {
+    name: 'bloby-fe-stamp',
+    // hotUpdate (not legacy handleHotUpdate): fires on create/update/delete and
+    // for .html edits that trigger full-reload. It runs once per environment, so
+    // only count the client one.
+    hotUpdate() {
+      if (this.environment.name !== 'client') return;
+      stamp++;
+    },
+    configureServer(server) {
+      // Reached through the supervisor's catch-all proxy to Vite. connect mounts
+      // by prefix, so reject subpaths to keep this an exact match.
+      server.middlewares.use('/__bloby/fe-stamp', (req, res, next) => {
+        const rest = (req.url || '').split('?')[0];
+        if (rest !== '' && rest !== '/') return next();
+        res.setHeader('Content-Type', 'application/json');
+        res.setHeader('Cache-Control', 'no-store');
+        res.end(JSON.stringify({ stamp }));
+      });
+    },
+  };
+}
+
 export default defineConfig({
   root: process.env.BLOBY_WORKSPACE
     ? path.join(process.env.BLOBY_WORKSPACE, 'client')
@@ -64,5 +95,5 @@ export default defineConfig({
       'use-sync-external-store/shim',
     ],
   },
-  plugins: [react(), tailwindcss()],
+  plugins: [react(), tailwindcss(), blobyFeStamp()],
 });

package/worker/prompts/prompt-conditions.ts

@@ -19,6 +19,15 @@ export type ConditionResult = false | true | Record<string, string>;
 
 export const conditions: Record<string, () => Promise<ConditionResult>> = {
 
+  /**
+   * Shell mode: the workspace renders inside a same-origin iframe under the
+   * supervisor's shell page. BLOBY_NO_SHELL=1 is the kill switch back to
+   * legacy top-level serving — the iframe note must disappear with it.
+   */
+  'workspace-iframe-shell': async () => {
+    return process.env.BLOBY_NO_SHELL !== '1';
+  },
+
   /**
    * Official Workspace Lock is active.
    * Calls GET http://localhost:{backendPort}/api/lock/status

package/worker/prompts/prompt-fragments.json

@@ -1,4 +1,12 @@
 [
+  {
+    "id": "workspace-iframe-shell",
+    "description": "Shell mode active (BLOBY_NO_SHELL != 1): workspace renders inside a same-origin iframe under Bloby's shell. Priority 0 is load-bearing — must run before the workspace-lock replace fragments consume the workspace-security marker this append anchors on.",
+    "target": "workspace-security",
+    "action": "append",
+    "priority": 0,
+    "content": "## Iframe Shell\n\nThe dashboard your human sees renders inside a same-origin iframe under Bloby's shell page — the workspace app is never the top-level browsing context. This is transparent for normal code, with a few hard rules:\n\n- **Redirect-based auth (Google/GitHub OAuth, Stripe Checkout, etc.):** never navigate the current window to a third-party page — providers refuse to render inside iframes. Open a popup (`window.open`) or put `target=\"_top\"` on the redirect link. Prefer popup-based SDK flows when the provider offers one.\n- **`window.top` and `window.parent` belong to Bloby's shell.** Never navigate, reload, or postMessage them from workspace code.\n- **Browser permissions work normally** — camera, microphone, geolocation, clipboard, fullscreen, autoplay, and display-capture are all granted to the iframe by the shell.\n- **The browser tab title syncs automatically** from `document.title`. Nothing to do."
+  },
   {
     "id": "workspace-lock-official",
     "description": "Official marketplace Workspace Lock is active (PIN or password)",

package/workspace/client/public/sw.js

@@ -8,7 +8,7 @@
 // build errors, never a stale cached shell. Cache is a pure offline fallback. (Mirror of the
 // supervisor's SW_JS in supervisor/index.ts — keep in sync.)
 
-const CACHE = 'bloby-v17';
+const CACHE = 'bloby-v24';
 
 // Precache the HTML shell on install so the cache is never empty.
 // Without this, the first navigation isn't intercepted (SW wasn't

package/workspace/client/src/App.tsx

@@ -28,80 +28,27 @@ export default function App() {
   const [showOnboard, setShowOnboard] = useState(false);
   const [userName, setUserName] = useState('');
   const [botName, setBotName] = useState('Bloby');
-  const [rebuildState, setRebuildState] = useState<'idle' | 'rebuilding' | 'error'>('idle');
-  const [buildError, setBuildError] = useState('');
 
-  // ── 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).
+  // ── Seamless reload: splash before full-reloads ───────────────────
+  // Vite's reload-on-reconnect is suppressed by the supervisor-injected
+  // workspace-guard (which also owns location.reload wrapping), so the
+  // only reloads left are real ones: Vite full-reloads after frontend
+  // changes. Show the HTML splash before those so the user sees
+  // app → splash → app instead of a white flash.
   useEffect(() => {
     const splash = document.getElementById('splash');
-    let hiddenAt = 0;
 
-    // Show the dark background (used before reloads and on resume)
+    // Show the dark background before the reload unloads the page
     function showSplash() {
       if (!splash) return;
       splash.style.display = 'block';
       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 });
-    }
-
-    // Wrap location.reload: show splash, wait for paint, then reload.
-    // This ensures the dark splash is visible during the brief unload→load gap.
-    try {
-      const origReload = location.reload.bind(location);
-      Object.defineProperty(location, 'reload', {
-        configurable: true,
-        value: () => {
-          showSplash();
-          requestAnimationFrame(() => requestAnimationFrame(() => origReload()));
-        },
-      });
-    } catch {
-      // location.reload is non-configurable in some browsers — skip override
-    }
-
     // Vite HMR: show splash before a full-reload
     if (import.meta.hot) {
       import.meta.hot.on('vite:beforeFullReload', () => showSplash());
     }
-
-    // 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
-
-    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);
-      }
-    };
-    document.addEventListener('visibilitychange', onVisChange);
-
-    return () => {
-      document.removeEventListener('visibilitychange', onVisChange);
-      clearTimeout(thawTimer);
-    };
   }, []);
 
   useEffect(() => {
@@ -119,39 +66,18 @@ export default function App() {
       .catch(() => {});
   }, []);
 
-  // Listen for rebuild events from Bloby iframe via postMessage
+  // Listen for events from Bloby iframes via postMessage.
+  // 'bloby:hmr-update' is intentionally ignored: Vite HMR handles hot
+  // updates natively, and a manual location.reload() here would kill the
+  // chat iframe's WebSocket connection for nothing.
   useEffect(() => {
-    let safetyTimer: ReturnType<typeof setTimeout>;
     const handler = (e: MessageEvent) => {
-      if (e.data?.type === 'bloby:rebuilding') {
-        setRebuildState('rebuilding');
-        setBuildError('');
-        // Safety: auto-reload after 60s in case app:rebuilt message is lost
-        clearTimeout(safetyTimer);
-        safetyTimer = setTimeout(() => location.reload(), 60_000);
-      } else if (e.data?.type === 'bloby:rebuilt') {
-        clearTimeout(safetyTimer);
-        setRebuildState('idle');
-        location.reload();
-      } else if (e.data?.type === 'bloby:build-error') {
-        clearTimeout(safetyTimer);
-        setRebuildState('error');
-        setBuildError(e.data.error || 'Build failed');
-        setTimeout(() => setRebuildState('idle'), 5000);
-      } else if (e.data?.type === 'bloby:onboard-complete') {
+      if (e.data?.type === 'bloby:onboard-complete') {
         setShowOnboard(false);
-      } else if (e.data?.type === 'bloby:hmr-update') {
-        // Vite HMR handles hot updates natively — no manual reload needed.
-        // Manual location.reload() here was causing unnecessary full-page refreshes
-        // that killed the chat iframe's WebSocket connection.
-
       }
     };
     window.addEventListener('message', handler);
-    return () => {
-      window.removeEventListener('message', handler);
-      clearTimeout(safetyTimer);
-    };
+    return () => window.removeEventListener('message', handler);
   }, []);
 
   return (
@@ -172,22 +98,6 @@ export default function App() {
           style={{ position: 'fixed', inset: 0, width: '100vw', height: '100dvh', border: 'none', zIndex: 200 }}
         />
       )}
-
-      {rebuildState !== 'idle' && (
-        <div className="fixed inset-0 z-[49] flex flex-col items-center justify-center bg-background/90">
-          <video
-            src="/bloby_tilts.webm"
-            autoPlay
-            loop
-            muted
-            playsInline
-            className="h-24 w-24 rounded-full object-cover"
-          />
-          <p className="mt-4 text-sm text-muted-foreground">
-            {rebuildState === 'rebuilding' ? 'Rebuilding app...' : buildError}
-          </p>
-        </div>
-      )}
     </>
   );
 }