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

package/README.md

@@ -81,6 +81,29 @@ The opt-out is page-wide — the strictest call wins. If any component on the pa
 
 There is also a config node, **fc-portal-component**, that lets you define reusable React components once and reference them by name from any portal-react node. Referenced components (and their transitive dependencies) are injected at transpile time, so unused ones add nothing to the bundle.
 
+For shared **non-component** code (helpers, custom hooks, constants), use **fc-portal-utility** — a sibling config node. Unlike component nodes (which export exactly one symbol via an IIFE wrapper), a utility node is injected raw at top level so it can declare any number of `function` / `const` / `let` / `class` symbols. Selective inclusion: a utility node lands in a portal's bundle only when the portal's JSX or any of its referenced library components mentions at least one of the symbols declared in that utility.
+
+```jsx
+// fc-portal-utility, Module name = mathHelpers
+const PI2 = Math.PI * 2;
+function clamp(n, min, max) { return Math.max(min, Math.min(max, n)); }
+function useDebounce(value, ms = 300) {
+  const [v, setV] = React.useState(value);
+  React.useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}
+
+// portal-react, JSX tab
+function App() {
+  const { data } = useNodeRed();
+  const slow = useDebounce(data?.value);
+  return <div>{clamp(slow ?? 0, 0, 100)}</div>;
+}
+```
+
 ## Editor features
 
 - **Monaco** with full JSX support and `useNodeRed()` type declarations
@@ -88,6 +111,8 @@ There is also a config node, **fc-portal-component**, that lets you define reusa
 - **JSX tag completion** — type tag name, Tab to expand
 - **Self-close collapse** — type `/` inside empty `<tag></tag>` to convert to `<tag />`
 - **Component completion** — registry components + any PascalCase word
+- **Utility-symbol completion** — top-level identifiers from any `fc-portal-utility` node, suggested in JS context
+- **Components / Utilities dialogs** — buttons in the JSX tab; Components inserts `<Tag></Tag>`, Utilities expands to the symbols declared in each node and inserts the bare identifier on click
 - **Portal Assets sidebar** — file manager for static assets (GLB, textures, fonts…)
 
 ## Multi-user / Multi-tenancy
@@ -177,6 +202,7 @@ Import `001-shared-components-flow.json` first — it provides shared UI compone
 | `005-threejs-portal-flow.json` | `three` | 3D scene with Three.js |
 | `006-pixi-portal-flow.json` | `pixi.js`, `@pixi/react` | Clickable bunny sprites with PixiJS |
 | `007-webgpu-tsl-flow.json` | `three` | WebGPU renderer + TSL animated shaders |
+| `008-utility-debounce-flow.json` | — | `fc-portal-utility` demo: `useDebounce` custom hook + `clamp` helper |
 
 ## Troubleshooting
 

package/examples/008-utility-debounce-flow.json

@@ -0,0 +1,72 @@
+[
+  {
+    "id": "fc-util-flow",
+    "type": "tab",
+    "label": "Utility: useDebounce",
+    "disabled": false
+  },
+  {
+    "id": "fc-util-tick",
+    "type": "inject",
+    "z": "fc-util-flow",
+    "name": "Fast tick (10Hz)",
+    "props": [{ "p": "payload" }],
+    "repeat": "0.1",
+    "payload": "",
+    "payloadType": "date",
+    "x": 160,
+    "y": 160,
+    "wires": [["fc-util-noisy"]]
+  },
+  {
+    "id": "fc-util-noisy",
+    "type": "function",
+    "z": "fc-util-flow",
+    "name": "Noisy signal",
+    "func": "// Random walk between 0..120 with bursts of noise — exactly the sort of\n// fast-changing input where a debounced display is much more readable\n// than the raw value.\nconst prev = context.get('v') ?? 50;\nconst drift = (Math.random() - 0.5) * 8;\nconst noise = Math.random() < 0.15 ? (Math.random() - 0.5) * 30 : 0;\nconst v = Math.max(0, Math.min(120, prev + drift + noise));\ncontext.set('v', v);\nmsg.payload = { value: +v.toFixed(2), ts: Date.now() };\nreturn msg;",
+    "outputs": 1,
+    "x": 360,
+    "y": 160,
+    "wires": [["fc-util-portal"]]
+  },
+  {
+    "id": "fc-util-helpers",
+    "type": "fc-portal-utility",
+    "z": "fc-util-flow",
+    "name": "math helpers + useDebounce",
+    "utilName": "mathHelpers",
+    "utilCode": "// Constants — bundled once, shared across portals that reference them.\nconst CLAMP_MIN = 0;\nconst CLAMP_MAX = 100;\n\n// Pure helper.\nfunction clamp(n, min, max) {\n  return Math.max(min, Math.min(max, n));\n}\n\n// Custom React hook — name MUST start with `use` for React's rules of hooks.\n// This node groups a constant + a helper + a hook in one block; portals that\n// reference any of `clamp`, `useDebounce`, `CLAMP_MIN`, `CLAMP_MAX` pull in\n// the whole node.\nfunction useDebounce(value, ms = 300) {\n  const [v, setV] = React.useState(value);\n  React.useEffect(() => {\n    const t = setTimeout(() => setV(value), ms);\n    return () => clearTimeout(t);\n  }, [value, ms]);\n  return v;\n}",
+    "x": 160,
+    "y": 280,
+    "wires": []
+  },
+  {
+    "id": "fc-util-bar",
+    "type": "fc-portal-component",
+    "z": "fc-util-flow",
+    "name": "Bar",
+    "compName": "Bar",
+    "compCode": "function Bar({ value = 0, label = '' }) {\n  // Component uses `clamp` from the utility node — selective inclusion picks\n  // up the dependency through the components' code, not just the user JSX.\n  const pct = clamp(value, CLAMP_MIN, CLAMP_MAX);\n  const color = pct > 80 ? 'bg-red-500' : pct > 50 ? 'bg-amber-500' : 'bg-emerald-500';\n  return (\n    <div className=\"flex items-center gap-3\">\n      <div className=\"w-24 text-xs text-zinc-400 uppercase tracking-wider\">{label}</div>\n      <div className=\"flex-1 h-3 bg-zinc-800 rounded-full overflow-hidden\">\n        <div className={`h-full ${color} transition-all duration-150`} style={{ width: pct + '%' }} />\n      </div>\n      <div className=\"w-14 text-right font-mono text-sm tabular-nums text-zinc-200\">\n        {value.toFixed(1)}\n      </div>\n    </div>\n  );\n}",
+    "compInputs": "value,label",
+    "compOutputs": "",
+    "x": 360,
+    "y": 280,
+    "wires": []
+  },
+  {
+    "id": "fc-util-portal",
+    "type": "portal-react",
+    "z": "fc-util-flow",
+    "name": "Debounce demo",
+    "subPath": "debounce",
+    "pageTitle": "useDebounce demo",
+    "customHead": "",
+    "componentCode": "function App() {\n  const { data } = useNodeRed();\n  const raw = data?.value ?? 0;\n\n  // Live raw signal vs debounced views at three different windows.\n  // `useDebounce` is declared in the fc-portal-utility node — no import.\n  const slow100 = useDebounce(raw, 100);\n  const slow400 = useDebounce(raw, 400);\n  const slow1500 = useDebounce(raw, 1500);\n\n  return (\n    <div className=\"min-h-screen bg-zinc-950 text-zinc-100 p-8 font-sans\">\n      <h1 className=\"text-2xl font-light text-amber-400 mb-2\">useDebounce</h1>\n      <p className=\"text-sm text-zinc-500 mb-8\">\n        Custom hook from <code className=\"text-amber-300\">fc-portal-utility</code>. Same noisy 10 Hz input fed through different debounce windows.\n      </p>\n      <div className=\"max-w-xl space-y-4\">\n        <Bar value={raw} label=\"raw\" />\n        <Bar value={slow100} label=\"100 ms\" />\n        <Bar value={slow400} label=\"400 ms\" />\n        <Bar value={slow1500} label=\"1500 ms\" />\n      </div>\n    </div>\n  );\n}",
+    "libs": [],
+    "portalAuth": false,
+    "showWsStatus": false,
+    "x": 580,
+    "y": 160,
+    "wires": [[]]
+  }
+]

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) {
+          const root = document.getElementById('root');
+          if (root) root.style.display = 'none';
+          const bo = document.getElementById('__building_overlay');
+          if (bo) bo.remove();
+          const bn = document.getElementById('__error_banner');
+          if (bn) bn.remove();
+          let 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) {
+          const ov = document.getElementById('__error_overlay');
+          if (ov) ov.remove();
+          const bo = document.getElementById('__building_overlay');
+          if (bo) bo.remove();
+          const root = document.getElementById('root');
+          if (root) root.style.display = '';
+          let 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() {
+          const ov = document.getElementById('__error_overlay');
+          if (ov) ov.remove();
+          const bn = document.getElementById('__error_banner');
+          if (bn) bn.remove();
+          const 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;
+              const 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,16 +185,26 @@ 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');
+                  const eo = document.getElementById('__error_overlay');
                   if (eo) eo.remove();
                   if (!document.getElementById('__building_overlay')) {
-                    var ov = document.createElement('div');
+                    const ov = document.createElement('div');
                     ov.id = '__building_overlay';
                     ov.style.cssText = 'position:fixed;inset:0;z-index:99999;background:#111;color:#888;display:flex;flex-direction:column;align-items:center;justify-content:center;font-family:monospace';
                     ov.innerHTML = '<div style="font-size:24px;margin-bottom:16px">Building\\u2026</div>'
@@ -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)});
+                    const 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;
+              const 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>';
+          const __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,40 +290,43 @@ 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 retries = 0;
+          const st = document.getElementById('__err_status');
+          const pre = document.querySelector('#__error_overlay pre');
+          let 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}');
+            const p = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const 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);
+                const 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'; }
-              var delay = Math.min(500 * Math.pow(2, retries), 8000);
+              setStatus('Disconnected \\u2014 reconnecting\\u2026', false);
+              const delay = Math.min(500 * Math.pow(2, retries), 8000);
               retries++;
               setTimeout(connect, delay);
             };