@aaqu/fromcubes-portal-react 0.1.0-alpha.20 → 0.1.0-alpha.21

package/nodes/lib/helpers.js

@@ -121,12 +121,42 @@ function removeRoute(router, path) {
   );
 }
 
+function formatEsbuildError(e) {
+  return e.errors?.length
+    ? e.errors
+        .map(
+          (err) =>
+            `${err.text}${err.location ? ` (line ${err.location.line})` : ""}`,
+        )
+        .join("\n")
+    : e.message;
+}
+
+// Fast JSX syntax validation (no bundling). Returns null on OK, error string on fail.
+function quickCheckSyntax(jsx) {
+  if (!jsx || !jsx.trim()) return null;
+  try {
+    esbuild.transformSync(jsx, {
+      loader: "jsx",
+      jsx: "transform",
+      jsxFactory: "React.createElement",
+      jsxFragment: "React.Fragment",
+      logLevel: "silent",
+    });
+    return null;
+  } catch (e) {
+    return formatEsbuildError(e);
+  }
+}
+
 module.exports = function (RED) {
   return createHelpers(RED);
 };
 
 module.exports.validateSubPath = validateSubPath;
 module.exports.isSafeName = isSafeName;
+module.exports.quickCheckSyntax = quickCheckSyntax;
+module.exports.formatEsbuildError = formatEsbuildError;
 
 function createHelpers(RED) {
   // Package root — where react/react-dom live (this package's own node_modules)
@@ -220,25 +250,8 @@ function createHelpers(RED) {
 
   function transpile(jsx) {
     // Pre-validate with transformSync (fast, no bundling) to avoid esbuild buildSync deadlock on syntax errors
-    try {
-      esbuild.transformSync(jsx, {
-        loader: "jsx",
-        jsx: "transform",
-        jsxFactory: "React.createElement",
-        jsxFragment: "React.Fragment",
-        logLevel: "silent",
-      });
-    } catch (e) {
-      const msg = e.errors?.length
-        ? e.errors
-            .map(
-              (err) =>
-                `${err.text}${err.location ? ` (line ${err.location.line})` : ""}`,
-            )
-            .join("\n")
-        : e.message;
-      return { js: null, error: msg };
-    }
+    const syntaxErr = quickCheckSyntax(jsx);
+    if (syntaxErr) return { js: null, error: syntaxErr };
     // Syntax OK — bundle with full resolution
     try {
       const buildResult = esbuild.buildSync({
@@ -275,21 +288,14 @@ function createHelpers(RED) {
         error: null,
       };
     } catch (e) {
-      const msg = e.errors?.length
-        ? e.errors
-            .map(
-              (err) =>
-                `${err.text}${err.location ? ` (line ${err.location.line})` : ""}`,
-            )
-            .join("\n")
-        : e.message;
-      return { js: null, error: msg };
+      return { js: null, error: formatEsbuildError(e) };
     }
   }
 
   return {
     hash,
     transpile,
+    quickCheckSyntax,
     generateCSS,
     extractPortalUser,
     removeRoute,

package/nodes/lib/page-builder.js

@@ -14,6 +14,63 @@ function escScript(s) {
   return String(s).replace(/<\/(script)/gi, "<\\/$1");
 }
 
+const ERROR_OVERLAY_CSS = `
+  #__error_overlay {
+    position: fixed; inset: 0; z-index: 99999;
+    background: #1a0000; color: #f87171;
+    font-family: monospace; padding: 40px;
+    overflow: auto;
+    display: flex; flex-direction: column; align-items: center; justify-content: flex-start;
+  }
+  #__error_overlay h1 { color: #ff4444; margin: 0 0 16px; font-size: 24px }
+  #__error_overlay p.__hint { color: #888; margin: 0 0 16px }
+  #__error_overlay pre {
+    background: #0a0a0a; border: 1px solid #ff4444; border-radius: 8px;
+    padding: 20px; color: #fca5a5;
+    max-width: 90vw; max-height: 60vh; overflow: auto;
+    white-space: pre-wrap; margin: 0;
+  }
+  #__error_overlay p.__status { color: #4ade80; font-size: 12px; margin: 24px 0 0 }
+  #__error_overlay p.__status.__off { color: #888 }
+  #__error_banner {
+    position: fixed; top: 8px; right: 8px; z-index: 99998;
+    max-width: 360px; padding: 8px 12px;
+    background: #1a0000; color: #fca5a5;
+    border: 1px solid #ff4444; border-radius: 6px;
+    font-family: monospace; font-size: 12px;
+    box-shadow: 0 4px 12px rgba(0,0,0,.4);
+    cursor: pointer; user-select: none;
+  }
+  #__error_banner b { color: #ff4444; display: block; margin-bottom: 2px }
+  #__error_banner.__expanded {
+    max-width: 70vw; max-height: 60vh; overflow: auto;
+    cursor: default;
+  }
+  #__error_banner pre {
+    margin: 8px 0 0; padding: 8px; background: #0a0a0a;
+    border-radius: 4px; white-space: pre-wrap; display: none;
+  }
+  #__error_banner.__expanded pre { display: block }
+  #__error_banner .__close {
+    float: right; padding: 0 4px; color: #888; cursor: pointer;
+  }
+`;
+
+// Shared error overlay markup (HTML inside #__error_overlay).
+// Used by buildPage (WS error frame, runtime try/catch) and buildErrorPage.
+function errorOverlayInnerHtml({ title, hint, message, statusLine, statusOk }) {
+  return (
+    `<h1>${esc(title)}</h1>` +
+    (hint ? `<p class="__hint">${esc(hint)}</p>` : "") +
+    `<pre>${esc(message)}</pre>` +
+    (statusLine
+      ? `<p class="__status${statusOk ? "" : " __off"}" id="__err_status">${esc(statusLine)}</p>`
+      : "")
+  );
+}
+
+const DEFAULT_HINT = "Fix the component code in Node-RED and deploy again.";
+
 function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showWsStatus, adminRoot) {
   return `<!DOCTYPE html>
     <html lang="en">
@@ -23,6 +80,7 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
       <title>${esc(title)}</title>
       ${cssHash ? `<link rel="stylesheet" href="${adminRoot}/portal-react/css/${cssHash}.css">` : ""}
       ${escScript(customHead)}
+      <style>${ERROR_OVERLAY_CSS}</style>
       ${showWsStatus ? `<style>
         #__cs {
           position: fixed; bottom: 6px; right: 6px;
@@ -39,6 +97,51 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
       <div id="root"></div>
       ${showWsStatus ? `<div id="__cs" class="err">fromcubes</div>` : ""}
       <script>
+        function __safe(s){return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');}
+        function __renderErrorOverlay(title, message, hint) {
+          var root = document.getElementById('root');
+          if (root) root.style.display = 'none';
+          var bo = document.getElementById('__building_overlay');
+          if (bo) bo.remove();
+          var bn = document.getElementById('__error_banner');
+          if (bn) bn.remove();
+          var ov = document.getElementById('__error_overlay');
+          if (!ov) { ov = document.createElement('div'); ov.id = '__error_overlay'; document.body.appendChild(ov); }
+          ov.innerHTML = '<h1>' + __safe(title) + '</h1>'
+            + (hint ? '<p class="__hint">' + __safe(hint) + '</p>' : '')
+            + '<pre>' + __safe(message) + '</pre>'
+            + '<p class="__status __off" id="__err_status">Waiting for redeploy\\u2026</p>';
+        }
+        function __renderErrorBanner(message) {
+          var ov = document.getElementById('__error_overlay');
+          if (ov) ov.remove();
+          var bo = document.getElementById('__building_overlay');
+          if (bo) bo.remove();
+          var root = document.getElementById('root');
+          if (root) root.style.display = '';
+          var bn = document.getElementById('__error_banner');
+          if (!bn) {
+            bn = document.createElement('div');
+            bn.id = '__error_banner';
+            document.body.appendChild(bn);
+            bn.addEventListener('click', function(e) {
+              if (e.target && e.target.className === '__close') { bn.remove(); return; }
+              bn.classList.toggle('__expanded');
+            });
+          }
+          bn.innerHTML = '<span class="__close" title="Dismiss">\\u00d7</span>'
+            + '<b>\\u26a0 Latest deploy failed</b>'
+            + '<span>Running previous version. Click for details.</span>'
+            + '<pre>' + __safe(message) + '</pre>';
+        }
+        function __clearErrorOverlay() {
+          var ov = document.getElementById('__error_overlay');
+          if (ov) ov.remove();
+          var bn = document.getElementById('__error_banner');
+          if (bn) bn.remove();
+          var root = document.getElementById('root');
+          if (root) root.style.display = '';
+        }
         window.__NR = {
           _ws: null,
           _listeners: new Set(),
@@ -48,6 +151,13 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
           _wasConnected: false,
           _version: null,
           _portalClient: null,
+          // Set on building/error WS frames. Next version with real hash reloads,
+          // independent of hash diff (build may produce same hash again).
+          _buildErrorActive: false,
+          // Pending runtime error message captured before WS opened.
+          // Flushed in onopen so node status can go red even when the
+          // exception fires synchronously during initial bundle execution.
+          _pendingRuntimeError: null,
           _user: ${user ? escScript(JSON.stringify(user)) : "null"},
 
           connect() {
@@ -57,9 +167,15 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
             const s = document.getElementById('__cs');
 
             ws.onopen = () => {
-              if (s) { s.textContent = 'fromcubes \u2022 connected'; s.className = 'ok'; }
+              if (s) { s.textContent = 'fromcubes • connected'; s.className = 'ok'; }
               this._retries = 0;
               this._wasConnected = true;
+              var es = document.getElementById('__err_status');
+              if (es) { es.textContent = 'Connected \\u2014 will reload on redeploy'; es.className = '__status'; }
+              if (this._pendingRuntimeError) {
+                try { ws.send(JSON.stringify({ type: 'runtime_error', message: this._pendingRuntimeError })); } catch(_) {}
+                this._pendingRuntimeError = null;
+              }
             };
 
             ws.onmessage = (e) => {
@@ -69,11 +185,21 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
                   this._portalClient = m.portalClient;
                 }
                 if (m.type === 'version') {
-                  var hasOverlay = document.getElementById('__building_overlay') || document.getElementById('__error_overlay');
-                  if (hasOverlay || (this._version && this._version !== m.hash)) { location.reload(); return; }
+                  // Empty hash = server still in building/error state, ignore (overlay stays).
+                  if (!m.hash) return;
+                  // Reload when server was in build-error/building (recover regardless of
+                  // hash) OR when hash differs from prior known hash (deploy detected).
+                  // Do NOT reload merely because an overlay is in the DOM: a runtime
+                  // exception caught locally renders the same overlay node and would
+                  // otherwise loop reload to runtime-error to reload forever.
+                  if (this._buildErrorActive || (this._version && this._version !== m.hash)) {
+                    location.reload();
+                    return;
+                  }
                   this._version = m.hash;
                 }
                 if (m.type === 'building') {
+                  this._buildErrorActive = true;
                   document.getElementById('root').style.display = 'none';
                   var eo = document.getElementById('__error_overlay');
                   if (eo) eo.remove();
@@ -88,22 +214,14 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
                   }
                 }
                 if (m.type === 'error') {
-                  document.getElementById('root').style.display = 'none';
-                  var bo = document.getElementById('__building_overlay');
-                  if (bo) bo.remove();
-                  var ov = document.getElementById('__error_overlay');
-                  if (!ov) {
-                    ov = document.createElement('div');
-                    ov.id = '__error_overlay';
-                    ov.style.cssText = 'position:fixed;inset:0;z-index:99999;background:#1a0000;color:#f87171;display:flex;flex-direction:column;align-items:center;justify-content:center;font-family:monospace;padding:40px';
-                    document.body.appendChild(ov);
+                  this._buildErrorActive = true;
+                  if (m.degraded) {
+                    __renderErrorBanner(m.message);
+                  } else {
+                    __renderErrorOverlay('Build Error', m.message, ${JSON.stringify(DEFAULT_HINT)});
+                    var es2 = document.getElementById('__err_status');
+                    if (es2) { es2.textContent = 'Connected \\u2014 will reload on redeploy'; es2.className = '__status'; }
                   }
-                  ov.innerHTML = '<h1 style="color:#ff4444;margin-bottom:16px;font-size:24px">JSX Transpile Error</h1>'
-                    + '<p style="color:#888;margin-bottom:16px">Fix the component code in Node-RED and deploy again.</p>'
-                    + '<pre style="background:#0a0a0a;border:1px solid #ff4444;border-radius:8px;padding:20px;overflow-x:auto;color:#fca5a5;max-width:90vw;max-height:60vh;overflow:auto;white-space:pre-wrap">'
-                    + m.message.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')
-                    + '</pre>'
-                    + '<p style="color:#4ade80;font-size:12px;margin-top:24px">Connected \\u2014 will reload on redeploy</p>';
                 }
                 if (m.type === 'data') {
                   this._lastData = m.payload;
@@ -121,8 +239,10 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
             };
 
             ws.onclose = () => {
-              if (s) { s.textContent = 'fromcubes \u2022 disconnected'; s.className = 'err'; }
+              if (s) { s.textContent = 'fromcubes • disconnected'; s.className = 'err'; }
               this._ws = null;
+              var es = document.getElementById('__err_status');
+              if (es) { es.textContent = 'Disconnected \\u2014 reconnecting\\u2026'; es.className = '__status __off'; }
               const delay = Math.min(500 * Math.pow(2, this._retries), 8000);
               this._retries++;
               setTimeout(() => this.connect(), delay);
@@ -147,12 +267,17 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
       <script>
         try { ${escScript(transpiledJs)}
         } catch(__e) {
-          var __r = document.getElementById('root');
-          __r.style.cssText = 'font-family:monospace;background:#1a0000;color:#f87171;padding:40px;min-height:100vh;margin:0';
-          __r.innerHTML = '<h1 style="color:#ff4444;margin-bottom:16px">Runtime Error</h1>'
-            + '<p style="color:#888">Fix the component code in Node-RED and deploy again.</p>'
-            + '<pre style="background:#0a0a0a;border:1px solid #ff4444;border-radius:8px;padding:20px;overflow-x:auto;color:#fca5a5;white-space:pre-wrap">'
-            + (__e.message || __e).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;') + '</pre>';
+          var __m = (__e && (__e.stack || __e.message)) || String(__e);
+          __renderErrorOverlay('Runtime Error', __m, ${JSON.stringify(DEFAULT_HINT)});
+          // Report back to server so node status goes red. WS may not be open
+          // yet (sync throw during initial bundle); queue until onopen.
+          try {
+            if (window.__NR && window.__NR._ws && window.__NR._ws.readyState === 1) {
+              window.__NR._ws.send(JSON.stringify({ type: 'runtime_error', message: __m }));
+            } else if (window.__NR) {
+              window.__NR._pendingRuntimeError = __m;
+            }
+          } catch(_) {}
         }
       <\/script>
     </body>
@@ -165,39 +290,42 @@ function buildErrorPage(title, error, wsPath) {
     <head>
       <meta charset="UTF-8">
       <title>${esc(title)} — Error</title>
-      <style>
-        body { font-family: monospace; background: #1a0000; color: #f87171; padding: 40px; line-height: 1.6 }
-        h1 { color: #ff4444; margin-bottom: 16px }
-        pre { background: #0a0a0a; border: 1px solid #ff4444; border-radius: 8px; padding: 20px; overflow-x: auto; color: #fca5a5 }
-        .status { color: #888; font-size: 12px; margin-top: 24px }
-        .status.ok { color: #4ade80 }
-      </style>
+      <style>${ERROR_OVERLAY_CSS}</style>
     </head>
     <body>
-      <h1>JSX Transpile Error</h1>
-      <p>Fix the component code in Node-RED and deploy again.</p>
-      <pre>${esc(error)}</pre>
-      <p class="status" id="st">Waiting for redeploy…</p>
+      <div id="__error_overlay">${errorOverlayInnerHtml({
+        title: "Build Error",
+        hint: DEFAULT_HINT,
+        message: error,
+        statusLine: "Waiting for redeploy…",
+        statusOk: false,
+      })}</div>
       <script>
         (function() {
-          var st = document.getElementById('st');
+          var st = document.getElementById('__err_status');
+          var pre = document.querySelector('#__error_overlay pre');
           var retries = 0;
+          function setStatus(text, ok) {
+            if (!st) return;
+            st.textContent = text;
+            st.className = '__status' + (ok ? '' : ' __off');
+          }
           function connect() {
             var p = location.protocol === 'https:' ? 'wss:' : 'ws:';
             var ws = new WebSocket(p + '//' + location.host + '${wsPath}');
             ws.onopen = function() {
               retries = 0;
-              if (st) { st.textContent = 'Connected \\u2014 will reload on redeploy'; st.className = 'status ok'; }
+              setStatus('Connected \\u2014 will reload on redeploy', true);
             };
             ws.onmessage = function(e) {
               try {
                 var m = JSON.parse(e.data);
                 if (m.type === 'version' && m.hash) location.reload();
-                if (m.type === 'error') { var pre = document.querySelector('pre'); if (pre) pre.textContent = m.message; }
+                if (m.type === 'error' && pre) pre.textContent = m.message;
               } catch(_) {}
             };
             ws.onclose = function() {
-              if (st) { st.textContent = 'Disconnected \\u2014 reconnecting\\u2026'; st.className = 'status'; }
+              setStatus('Disconnected \\u2014 reconnecting\\u2026', false);
               var delay = Math.min(500 * Math.pow(2, retries), 8000);
               retries++;
               setTimeout(connect, delay);

package/nodes/portal-react.html

@@ -499,7 +499,10 @@
 
       var diagOpts = {
         noSemanticValidation: true,
-        noSyntaxValidation: false,
+        // Server-side esbuild does the real syntax check at deploy time;
+        // Monaco's TS parser produces noisy false positives on raw JSX
+        // (1109, 1005, 1128 etc.), so we silence its squiggles entirely.
+        noSyntaxValidation: true,
         noSuggestionDiagnostics: true,
         diagnosticCodesToIgnore: [17004],
       };

package/nodes/portal-react.js

@@ -110,6 +110,7 @@ module.exports = function (RED) {
     if (_startupPhase) return; // gated — _endStartupPhase will flush
     if (_rebuildTimer) clearTimeout(_rebuildTimer);
     _rebuildTimer = setTimeout(_flushRebuild, 50);
+    _rebuildTimer.unref?.();
   }
   function scheduleRebuildSelf(nodeId) {
     if (!nodeId) return;
@@ -159,6 +160,7 @@ module.exports = function (RED) {
   const {
     hash,
     transpile,
+    quickCheckSyntax,
     generateCSS,
     extractPortalUser,
     removeRoute,
@@ -215,9 +217,16 @@ module.exports = function (RED) {
 
     const newCode = config.compCode || "";
     const prevCode = registry[compName]?.code;
-    registry[compName] = { code: newCode };
+    const syntaxErr = quickCheckSyntax(newCode);
+    registry[compName] = { code: newCode, error: syntaxErr };
 
-    node.status({ fill: "green", shape: "dot", text: compName });
+    if (syntaxErr) {
+      node.error(`Component "${compName}" syntax error: ${syntaxErr}`);
+      const short = syntaxErr.split("\n")[0].slice(0, 40);
+      node.status({ fill: "red", shape: "dot", text: "syntax: " + short });
+    } else {
+      node.status({ fill: "green", shape: "dot", text: compName });
+    }
 
     // Only rebuild portals that reference this component, and only if the code actually changed.
     if (prevCode !== newCode) {
@@ -313,11 +322,49 @@ module.exports = function (RED) {
 
     function updateStatus() {
       if (isClosing) return;
+      const st = pageState[endpoint];
       const n = clients.size;
+      const clientTail = n > 0 ? ` [${n} client${n !== 1 ? "s" : ""}]` : "";
+
+      // Preserve build-error state — don't clobber with client count until JSX is fixed.
+      // Show "(serving last good)" suffix in degraded mode (ring shape) so it is
+      // obvious the portal still works for connected clients despite the broken build.
+      if (st && st.compiled && st.compiled.error) {
+        let base;
+        if (st.errorSource) base = "broken: " + st.errorSource;
+        else if (st.errorKind === "missing-return") base = "missing return";
+        else if (st.errorKind === "rebuild") base = "rebuild error";
+        else base = "transpile error";
+        if (st.lastGood) {
+          node.status({
+            fill: "red",
+            shape: "ring",
+            text: base + " (serving last good)" + clientTail,
+          });
+        } else {
+          node.status({ fill: "red", shape: "dot", text: base + clientTail });
+        }
+        return;
+      }
+      // Preserve building state — same reason.
+      if (st && st.building) {
+        node.status({ fill: "yellow", shape: "dot", text: "building..." });
+        return;
+      }
+      // Build succeeded but a connected browser threw at runtime
+      // (e.g. ReferenceError to a missing component / undefined identifier).
+      if (st && st.runtimeError) {
+        node.status({
+          fill: "red",
+          shape: "ring",
+          text: "runtime error" + clientTail,
+        });
+        return;
+      }
       node.status({
         fill: n > 0 ? "green" : "grey",
         shape: n > 0 ? "dot" : "ring",
-        text: `${endpoint} [${n} client${n !== 1 ? "s" : ""}]`,
+        text: `${endpoint}${clientTail || " [0 clients]"}`,
       });
     }
 
@@ -325,8 +372,6 @@ module.exports = function (RED) {
 
     function rebuild() {
       try {
-        node.status({ fill: "yellow", shape: "dot", text: "building..." });
-
         // ── Pre-build: clear cache, set building state, notify browsers ──
         const prevState = pageState[endpoint];
         const prevHash = prevState?.jsxHash;
@@ -334,6 +379,7 @@ module.exports = function (RED) {
           deleteCacheFiles(prevHash);
         }
         pageState[endpoint] = { building: true, wsPath, pageTitle };
+        updateStatus();
         clients.forEach((ws) => {
           try { if (ws.readyState === 1) ws.send(JSON.stringify({ type: "building" })); } catch (e) { RED.log.trace("[portal-react] ws send building: " + e.message); }
         });
@@ -451,7 +497,19 @@ module.exports = function (RED) {
           "createRoot(document.getElementById('root')).render(React.createElement(App));",
         ].join("\n");
 
+        const jsxHash = hash(fullJsx);
+
+        // ── Check: any used component has its own syntax error ──
+        let errorSource = null;
+        for (const name of needed) {
+          if (registry[name]?.error) {
+            errorSource = name;
+            break;
+          }
+        }
+
         // ── Check: missing return in App ──
+        let missingReturn = false;
         const appFnMatch = cleanCompCode.match(/function\s+App\s*\([^)]*\)\s*\{/);
         if (appFnMatch) {
           let depth = 1, i = appFnMatch.index + appFnMatch[0].length;
@@ -463,54 +521,47 @@ module.exports = function (RED) {
             else if (cleanCompCode.slice(i, i + 7) === "return ") hasReturn = true;
             i++;
           }
-          if (!hasReturn) {
-            node.error("App component has no return statement");
-            node.status({ fill: "red", shape: "dot", text: "missing return" });
-            const missingReturnError = {
-              js: null,
-              error: "App component has no return statement.\n\nAdd a return with JSX, e.g.:\n\nfunction App() {\n  return <div>Hello</div>\n}",
-            };
-            pageState[endpoint] = {
-              compiled: missingReturnError,
-              contentHash: "",
-              cssReady: Promise.resolve({ css: "", cssHash: "" }),
-              jsxHash: "",
-              css: null,
-              cssHash: "",
-              pageTitle,
-              wsPath,
-              customHead,
-              portalAuth,
-              showWsStatus,
-            };
-            clients.forEach((ws) => {
-              try { if (ws.readyState === 1) ws.send(JSON.stringify({ type: "error", message: missingReturnError.error })); } catch (e) { RED.log.trace("[portal-react] ws send error frame: " + e.message); }
-            });
-            return;
-          }
+          missingReturn = !hasReturn;
         }
 
-        const jsxHash = hash(fullJsx);
-
-        // ── JS: disk cache → transpile ──
-        let compiled = readCachedJS(jsxHash);
-        let cacheHit = !!compiled;
-        if (!compiled) {
-          compiled = transpile(fullJsx);
-          if (!compiled.error) {
-            writeCachedJS(jsxHash, compiled.js, compiled.metafile);
+        // ── Resolve compiled (success or unified error) ──
+        let compiled;
+        let cacheHit = false;
+        let errorKind = null; // 'component' | 'missing-return' | 'transpile'
+        if (errorSource) {
+          compiled = {
+            js: null,
+            error: `Component "${errorSource}" has a syntax error:\n\n${registry[errorSource].error}`,
+          };
+          errorKind = "component";
+        } else if (missingReturn) {
+          compiled = {
+            js: null,
+            error:
+              "App component has no return statement.\n\nAdd a return with JSX, e.g.:\n\nfunction App() {\n  return <div>Hello</div>\n}",
+          };
+          errorKind = "missing-return";
+        } else {
+          compiled = readCachedJS(jsxHash);
+          cacheHit = !!compiled;
+          if (!compiled) {
+            compiled = transpile(fullJsx);
+            if (!compiled.error) {
+              writeCachedJS(jsxHash, compiled.js, compiled.metafile);
+            }
           }
+          if (compiled.error) errorKind = "transpile";
         }
 
         if (compiled.error) {
-          node.error("JSX transpile error: " + compiled.error);
-          RED.log.warn(
-            `[portal-react] ${endpoint} — JSX transpile error: ${compiled.error}`,
+          node.error(
+            (errorKind === "component"
+              ? `Component "${errorSource}" syntax error: `
+              : errorKind === "missing-return"
+              ? "App component has no return statement: "
+              : "JSX transpile error: ") + compiled.error,
           );
-          node.status({ fill: "red", shape: "dot", text: "transpile error" });
-          clients.forEach((ws) => {
-            try { if (ws.readyState === 1) ws.send(JSON.stringify({ type: "error", message: compiled.error })); } catch (e) { RED.log.trace("[portal-react] ws send transpile error: " + e.message); }
-          });
+          // Status + WS frames handled below (lastGood-aware).
         } else {
           updateStatus();
           if (compiled.metafile) {
@@ -561,6 +612,12 @@ module.exports = function (RED) {
 
         lastJsxHash = jsxHash;
 
+        // Preserve last successful build so that on transpile errors we keep
+        // serving the previous working JS instead of throwing clients to an error page.
+        const lastGood = compiled.error
+          ? prevState?.lastGood || null
+          : null; // will be populated after cssReady resolves on success
+
         pageState[endpoint] = {
           compiled,
           contentHash,
@@ -573,8 +630,24 @@ module.exports = function (RED) {
           customHead,
           portalAuth,
           showWsStatus,
+          errorSource,
+          errorKind,
+          lastGood,
         };
 
+        if (compiled.error) {
+          // Status text (red) handled centrally by updateStatus — it formats
+          // base + "(serving last good)" + client-count suffix consistently
+          // across build and connect/disconnect events.
+          updateStatus();
+          const frame = lastGood
+            ? JSON.stringify({ type: "error", message: compiled.error, degraded: true })
+            : JSON.stringify({ type: "error", message: compiled.error });
+          clients.forEach((ws) => {
+            try { if (ws.readyState === 1) ws.send(frame); } catch (e) { RED.log.trace("[portal-react] ws send error: " + e.message); }
+          });
+        }
+
         // Notify all connected browsers that build finished — triggers reload or overlay cleanup
         if (!compiled.error && contentHash) {
           const versionFrame = JSON.stringify({ type: "version", hash: contentHash });
@@ -588,12 +661,49 @@ module.exports = function (RED) {
           if (state && state.jsxHash === jsxHash) {
             state.css = css;
             state.cssHash = cssHash;
+            // Snapshot current good build so future failed builds can fall back.
+            if (!state.compiled.error && state.compiled.js) {
+              state.lastGood = {
+                compiledJs: state.compiled.js,
+                contentHash: state.contentHash,
+                cssHash,
+                pageTitle: state.pageTitle,
+                customHead: state.customHead,
+              };
+            }
             updateStatus();
           }
         });
       } catch (e) {
         node.error("Rebuild failed: " + e.message);
-        node.status({ fill: "red", shape: "dot", text: "rebuild error" });
+        // Surface as a regular build error so the lastGood/degraded path,
+        // status formatting and FE error frame all run uniformly.
+        const prev = pageState[endpoint];
+        pageState[endpoint] = {
+          compiled: { js: null, error: "Internal rebuild error: " + e.message },
+          contentHash: "",
+          cssReady: Promise.resolve({ css: "", cssHash: "" }),
+          jsxHash: "",
+          css: null,
+          cssHash: "",
+          pageTitle,
+          wsPath,
+          customHead,
+          portalAuth,
+          showWsStatus,
+          errorSource: null,
+          errorKind: "rebuild",
+          lastGood: prev?.lastGood || null,
+        };
+        updateStatus();
+        const frame = JSON.stringify({
+          type: "error",
+          message: "Internal rebuild error: " + e.message,
+          degraded: !!prev?.lastGood,
+        });
+        clients.forEach((ws) => {
+          try { if (ws.readyState === 1) ws.send(frame); } catch (err) { RED.log.trace("[portal-react] ws send rebuild err: " + err.message); }
+        });
       }
     }
 
@@ -626,7 +736,7 @@ module.exports = function (RED) {
       scheduleRebuildSelf(nodeId);
     } else {
       node.log(`[${nodeId}] unchanged — skipping rebuild`);
-      node.status({ fill: "grey", shape: "ring", text: `${endpoint} [0 clients]` });
+      updateStatus();
     }
     setImmediate(() => {
       // Register route only once per endpoint (persists across deploys)
@@ -638,15 +748,35 @@ module.exports = function (RED) {
               const bWsPath = state?.wsPath || wsPath;
               res
                 .set("Cache-Control", "no-store")
-                .set("Refresh", "3")
                 .type("text/html")
                 .send(
-                  `<!DOCTYPE html><html><head><meta charset="UTF-8"><title>Building\u2026</title><style>@keyframes __sp{to{transform:rotate(360deg)}}body{font-family:monospace;background:#111;color:#888;margin:0;min-height:100vh;display:flex;flex-direction:column;align-items:center;justify-content:center}</style></head><body><div style="font-size:24px;margin-bottom:16px">Building\u2026</div><div style="width:40px;height:40px;border:3px solid #333;border-top-color:#888;border-radius:50%;animation:__sp .8s linear infinite"></div><script>(function(){var r=0;function c(){var p=location.protocol==='https:'?'wss:':'ws:';var ws=new WebSocket(p+'//'+location.host+'${bWsPath}');ws.onmessage=function(e){try{var m=JSON.parse(e.data);if(m.type==='version'||m.type==='error')location.reload();}catch(_){}};ws.onclose=function(){var d=Math.min(500*Math.pow(2,r),8000);r++;setTimeout(c,d);};ws.onerror=function(){ws.close();};}c();})()</script></body></html>`,
+                  `<!DOCTYPE html><html><head><meta charset="UTF-8"><title>Building\u2026</title><style>@keyframes __sp{to{transform:rotate(360deg)}}body{font-family:monospace;background:#111;color:#888;margin:0;min-height:100vh;display:flex;flex-direction:column;align-items:center;justify-content:center}</style></head><body><div style="font-size:24px;margin-bottom:16px">Building\u2026</div><div style="width:40px;height:40px;border:3px solid #333;border-top-color:#888;border-radius:50%;animation:__sp .8s linear infinite"></div><script>(function(){var r=0;function c(){var p=location.protocol==='https:'?'wss:':'ws:';var ws=new WebSocket(p+'//'+location.host+'${bWsPath}');ws.onmessage=function(e){try{var m=JSON.parse(e.data);if((m.type==='version'&&m.hash)||m.type==='error')location.reload();}catch(_){}};ws.onclose=function(){var d=Math.min(500*Math.pow(2,r),8000);r++;setTimeout(c,d);};ws.onerror=function(){ws.close();};}c();})()</script></body></html>`,
                 );
               return;
             }
             res.set("Cache-Control", "no-store");
             if (state.compiled.error) {
+              if (state.lastGood) {
+                // Degraded: serve previous good build, banner-only error UI.
+                const user = state.portalAuth
+                  ? extractPortalUser(_req.headers)
+                  : null;
+                res
+                  .type("text/html")
+                  .send(
+                    buildPage(
+                      state.lastGood.pageTitle,
+                      state.lastGood.compiledJs,
+                      state.wsPath,
+                      state.lastGood.customHead,
+                      state.lastGood.cssHash,
+                      user,
+                      state.showWsStatus,
+                      adminRoot,
+                    ),
+                  );
+                return;
+              }
               res
                 .status(500)
                 .type("text/html")
@@ -763,13 +893,28 @@ module.exports = function (RED) {
 
           updateStatus();
 
-          // Send content version for deploy-reload detection
-          const contentHash = pageState[endpoint]?.contentHash || "";
+          // Send content version for deploy-reload detection.
+          // In degraded mode (current build failed but lastGood served), advertise
+          // the lastGood hash so the freshly reloaded client matches the JS we sent.
+          const cs = pageState[endpoint];
+          const contentHash =
+            cs?.compiled?.error && cs?.lastGood
+              ? cs.lastGood.contentHash
+              : cs?.contentHash || "";
           wsSend(ws, { type: "version", hash: contentHash });
 
           // Send assigned portalClient to browser
           wsSend(ws, { type: "hello", portalClient });
 
+          // Degraded warning — show banner, not full overlay.
+          if (cs?.compiled?.error && cs?.lastGood) {
+            wsSend(ws, {
+              type: "error",
+              message: cs.compiled.error,
+              degraded: true,
+            });
+          }
+
           // Send the cached last broadcast (if any) as a distinct
           // `recovery` frame. The browser uses this to seed `data` on a
           // fresh connection. React components can opt out via
@@ -778,9 +923,37 @@ module.exports = function (RED) {
             wsSend(ws, { type: "recovery", payload: lastBroadcastCache.get(endpoint) });
           }
 
+          // Heartbeat — detect dead sockets via WS ping/pong. Browser
+          // auto-replies to ping frames, no client JS needed.
+          ws._isAlive = true;
+          ws.on("pong", () => { ws._isAlive = true; });
+          ws._pingIv = setInterval(() => {
+            if (ws._isAlive === false) {
+              try { ws.terminate(); } catch (e) { RED.log.trace("[portal-react] ws terminate: " + e.message); }
+              return;
+            }
+            ws._isAlive = false;
+            try { ws.ping(); } catch (e) { RED.log.trace("[portal-react] ws ping: " + e.message); }
+          }, 30000);
+
           ws.on("message", (raw) => {
             try {
               const msg = JSON.parse(raw.toString());
+              if (msg.type === "runtime_error") {
+                // Browser caught an exception while running the bundle —
+                // surface it on node status so the editor shows red even
+                // when the build itself succeeded (e.g. ReferenceError to
+                // an undefined identifier or missing component).
+                const st = pageState[endpoint];
+                if (st && !(st.compiled && st.compiled.error)) {
+                  st.runtimeError = String(msg.message || "")
+                    .split("\n")[0]
+                    .slice(0, 200);
+                  node.error("Runtime error in browser: " + st.runtimeError);
+                  updateStatus();
+                }
+                return;
+              }
               if (msg.type === "output") {
                 let out = {
                   payload: msg.payload,
@@ -806,6 +979,7 @@ module.exports = function (RED) {
           });
 
           const detach = () => {
+            if (ws._pingIv) { clearInterval(ws._pingIv); ws._pingIv = null; }
             clients.delete(portalClient);
             if (userId) {
               const set = userIndex.get(userId);
@@ -863,8 +1037,10 @@ module.exports = function (RED) {
           delete upgradeHandlers[nodeId];
         }
 
-        // Close all WS clients
+        // Close all WS clients — clear heartbeat interval BEFORE ws.close()
+        // so pending pings do not leak if the 'close' event is delayed.
         clients.forEach((ws) => {
+          if (ws._pingIv) { clearInterval(ws._pingIv); ws._pingIv = null; }
           try {
             ws.close(1001, "node redeployed");
           } catch (e) { RED.log.trace("[portal-react] ws close client: " + e.message); }
@@ -900,6 +1076,17 @@ module.exports = function (RED) {
         // the Map itself should not outlive the node instance.
         userIndex.clear();
 
+        // Break references to large objects / Promises in pageState even on
+        // redeploy. Next rebuild overwrites pageState[endpoint] anyway, but
+        // between close and the new build these would retain closures over
+        // the old clients/userIndex/rebuild scope.
+        const st = pageState[endpoint];
+        if (st) {
+          st.cssReady = null;
+          st.compiled = null;
+          st.css = null;
+        }
+
         // Clean up route only when node is fully removed (not redeployed)
         if (removed) {
           // Delete disk cache if no other endpoint uses this hash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaqu/fromcubes-portal-react",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.21",
   "description": "Fromcubes Portal - React for Node-RED with Tailwind CSS and auto complete",
   "keywords": [
     "node-red",
@@ -30,13 +30,13 @@
     "monaco-editor": "^0.55.1",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "tailwindcss": "^4.2.2"
+    "tailwindcss": "^4.2.4"
   },
   "devDependencies": {
-    "node-red": "5.0.0-beta.4",
-    "prettier": "^3.8.2",
+    "node-red": "5.0.0-beta.5",
+    "prettier": "^3.8.3",
     "supertest": "^7.2.2",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.5"
   },
   "scripts": {
     "start": "node-red",