From eb083d39374456fc92c487ba2cd8a6e1faa1006f Mon Sep 17 00:00:00 2001
From: Alexander Whitestone <alexpaynex@gmail.com>
Date: Sun, 22 Mar 2026 19:01:09 -0400
Subject: [PATCH] fix: add error state fallback for perpetual INITIALIZING
 screen

When main.js fails to load (network error, CORS, etc.), users were
stuck on "INITIALIZING" forever with no error or recovery option.

Changes:
- Add inline 8s timeout that shows error state if main.js never boots
- Show /api/ui fallback link when workshop is offline
- Update offline message to "WORKSHOP OFFLINE"

Fixes #7

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 world/index.html | 19 +++++++++++++++++++
 world/main.js    | 10 ++++++++--
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/world/index.html b/world/index.html
index 460d09a..af50645 100644
--- a/world/index.html
+++ b/world/index.html
@@ -88,6 +88,7 @@
     </div>
     <div class="status-line">AGENTS: <span id="agent-count">0</span></div>
     <button id="retry-btn">Retry connection</button>
+    <a id="fallback-link" href="/api/ui" style="display:none; margin-top:6px; color:#8a7f6a; font-size:0.7rem;">Open API dashboard →</a>
   </div>
 
   <!-- Reject unknown sub-paths: only /world/ is valid -->
@@ -99,6 +100,24 @@
       }
     })();
   </script>
+  <!-- Fallback: if main.js fails to load, don't leave user on INITIALIZING forever -->
+  <script>
+    (function() {
+      var INIT_TIMEOUT_MS = 8000;
+      window.__workshopBooted = false;
+      setTimeout(function() {
+        if (window.__workshopBooted) return;
+        var dot = document.getElementById('status-dot');
+        var text = document.getElementById('status-text');
+        var btn = document.getElementById('retry-btn');
+        var fallback = document.getElementById('fallback-link');
+        if (dot) { dot.className = 'dot offline'; }
+        if (text) { text.textContent = 'WORKSHOP UNREACHABLE'; }
+        if (btn) { btn.style.display = 'block'; }
+        if (fallback) { fallback.style.display = 'block'; }
+      }, INIT_TIMEOUT_MS);
+    })();
+  </script>
   <!-- Three.js scene will mount to #scene -->
   <script type="module" src="main.js"></script>
 </body>
diff --git a/world/main.js b/world/main.js
index f63cfd3..cb96b6e 100644
--- a/world/main.js
+++ b/world/main.js
@@ -23,8 +23,12 @@ const dom = {
   text: document.getElementById('status-text'),
   agents: document.getElementById('agent-count'),
   retryBtn: document.getElementById('retry-btn'),
+  fallback: document.getElementById('fallback-link'),
 };
 
+// Signal to inline fallback script that main.js loaded successfully
+window.__workshopBooted = true;
+
 let ws = null;
 let autoRetries = 0;
 let connectTimer = null;
@@ -32,7 +36,9 @@ let connectTimer = null;
 function setStatus(state, message) {
   dom.dot.className = 'dot ' + state;
   dom.text.textContent = message;
-  dom.retryBtn.style.display = state === Status.OFFLINE ? 'block' : 'none';
+  var isOffline = state === Status.OFFLINE;
+  dom.retryBtn.style.display = isOffline ? 'block' : 'none';
+  if (dom.fallback) dom.fallback.style.display = isOffline ? 'block' : 'none';
 }
 
 function setAgentCount(n) {
@@ -105,7 +111,7 @@ function onFail() {
     setStatus(Status.CONNECTING, 'RETRYING (' + autoRetries + '/' + MAX_AUTO_RETRIES + ')\u2026');
     setTimeout(connect, RETRY_DELAY_MS);
   } else {
-    setStatus(Status.OFFLINE, 'OFFLINE \u2014 backend unreachable');
+    setStatus(Status.OFFLINE, 'WORKSHOP OFFLINE');
   }
 }
 
-- 
2.43.0