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

package/nodes/portal-react.js

@@ -66,11 +66,39 @@ module.exports = function (RED) {
   const endpointOwners = RED.settings.fcEndpointOwners;
 
   // Track component name ownership: { compName: nodeId } — prevents duplicate component names
+  // Shared namespace with fc-portal-utility nodes so a component and a utility
+  // can never share the same name.
   if (!RED.settings.fcCompNameOwners) {
     RED.settings.fcCompNameOwners = {};
   }
   const compNameOwners = RED.settings.fcCompNameOwners;
 
+  // Utility registry: populated by fc-portal-utility canvas nodes at deploy time.
+  // Keyed by node-level utilName (e.g. "mathHelpers"), value { code, error }.
+  // Each utility node may declare multiple top-level symbols inside its code block.
+  if (!RED.settings.fcPortalUtilities) {
+    RED.settings.fcPortalUtilities = {};
+  }
+  const utilities = RED.settings.fcPortalUtilities;
+
+  // Per-portal set of utility node names this portal depends on (transitively).
+  // Lets utility code changes target only portals that reference at least one
+  // symbol declared by the changed utility node.
+  if (!RED.settings.fcPortalNeededUtilities) {
+    RED.settings.fcPortalNeededUtilities = {};
+  }
+  const portalNeededUtilities = RED.settings.fcPortalNeededUtilities;
+
+  // Track owner of each top-level symbol declared inside fc-portal-utility nodes:
+  // { symbol: utilName }. Lets us catch collisions upfront (component-name vs
+  // utility-symbol, utility-symbol vs utility-symbol from another node) before
+  // they reach esbuild, where the diagnostic would surface on the portal node
+  // as a confusing transpile error rather than on the offending utility node.
+  if (!RED.settings.fcUtilSymbolOwners) {
+    RED.settings.fcUtilSymbolOwners = {};
+  }
+  const utilSymbolOwners = RED.settings.fcUtilSymbolOwners;
+
   // Per-portal config signature — detects no-op Full-deploy reconstructions so unchanged
   // portals skip rebuild entirely (Node-RED closes/reopens every node on Full deploy).
   if (!RED.settings.fcPortalSig) {
@@ -110,6 +138,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;
@@ -132,10 +161,15 @@ module.exports = function (RED) {
     if (dirty.size > 0) {
       for (const nodeId of Object.keys(rebuildCallbacks)) {
         if (targetIds.has(nodeId)) continue;
-        const used = portalNeeded[nodeId];
+        const usedComps = portalNeeded[nodeId];
+        const usedUtils = portalNeededUtilities[nodeId];
         const raw = portalCode[nodeId] || "";
         for (const name of dirty) {
-          if ((used && used.has(name)) || raw.includes(name)) {
+          if (
+            (usedComps && usedComps.has(name)) ||
+            (usedUtils && usedUtils.has(name)) ||
+            raw.includes(name)
+          ) {
             targetIds.add(nodeId);
             break;
           }
@@ -159,6 +193,7 @@ module.exports = function (RED) {
   const {
     hash,
     transpile,
+    quickCheckSyntax,
     generateCSS,
     extractPortalUser,
     removeRoute,
@@ -211,13 +246,39 @@ module.exports = function (RED) {
       });
       return;
     }
+
+    // Cross-namespace collision: compName matches an existing utility's
+    // internal top-level symbol → bundle would have two declarations of the
+    // same identifier (component IIFE + utility raw decl).
+    const utilSymOwner = utilSymbolOwners[compName];
+    if (utilSymOwner) {
+      node.error(
+        `Component name "${compName}" conflicts with a top-level symbol declared in utility "${utilSymOwner}"`,
+      );
+      node.status({
+        fill: "red",
+        shape: "ring",
+        text: "duplicate symbol: " + compName,
+      });
+      node.on("close", function (_removed, done) {
+        if (done) done();
+      });
+      return;
+    }
     compNameOwners[compName] = node.id;
 
     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) {
@@ -236,6 +297,145 @@ module.exports = function (RED) {
   }
   RED.nodes.registerType("fc-portal-component", PortalComponentNode);
 
+  // ── Canvas node: shared utility (helpers / hooks / constants) ─
+
+  // Parse top-level symbols from utility code: function/const/let/class declarations.
+  // Used for selective inclusion (does user JSX reference any of these symbols?)
+  // and for the editor "Utilities" dialog (lists exported identifiers per node).
+  function extractUtilitySymbols(code) {
+    const names = new Set();
+    const re = /^(?:export\s+)?(?:async\s+)?(?:function\s*\*?|const|let|var|class)\s+([A-Za-z_$][\w$]*)/gm;
+    let m;
+    while ((m = re.exec(code || ""))) names.add(m[1]);
+    return names;
+  }
+
+  function PortalUtilityNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    const utilName = (config.utilName || "").trim();
+
+    if (!isSafeName(utilName)) {
+      node.error("Invalid utility name: " + utilName);
+      node.status({ fill: "red", shape: "dot", text: "invalid name" });
+      return;
+    }
+
+    // Duplicate name check across components AND utilities (shared namespace)
+    const existingOwner = compNameOwners[utilName];
+    if (existingOwner && existingOwner !== node.id) {
+      node.error(
+        `Name "${utilName}" is already used by another component or utility`,
+      );
+      node.status({
+        fill: "red",
+        shape: "ring",
+        text: "duplicate: " + utilName,
+      });
+      node.on("close", function (_removed, done) {
+        if (done) done();
+      });
+      return;
+    }
+    compNameOwners[utilName] = node.id;
+
+    const newCode = config.utilCode || "";
+    const prevCode = utilities[utilName]?.code;
+    const prevSyms = extractUtilitySymbols(prevCode || "");
+    const newSyms = extractUtilitySymbols(newCode);
+
+    // Free this node's previously-registered symbols before checking new ones,
+    // so a redeploy that simply renames an internal symbol doesn't see itself
+    // as a collision.
+    for (const s of prevSyms) {
+      if (utilSymbolOwners[s] === utilName) delete utilSymbolOwners[s];
+    }
+
+    // Cross-namespace symbol collision check:
+    //  - vs component names (a component declares `const Name = (() => ...)();`
+    //    at top level — a utility-internal `function Name` would clash)
+    //  - vs other utility nodes' internal symbols (raw top-level decls clash)
+    const conflicts = [];
+    for (const s of newSyms) {
+      if (Object.prototype.hasOwnProperty.call(registry, s)) {
+        conflicts.push(`${s} (component)`);
+        continue;
+      }
+      const symOwner = utilSymbolOwners[s];
+      if (symOwner && symOwner !== utilName) {
+        conflicts.push(`${s} (utility ${symOwner})`);
+      }
+    }
+
+    const syntaxErr = quickCheckSyntax(newCode);
+    const dupErr =
+      conflicts.length > 0
+        ? "duplicate symbols: " + conflicts.join(", ")
+        : null;
+    // Syntax error takes precedence (most actionable). If both, both are
+    // surfaced in the node.error message but status text shows syntax.
+    const combinedErr = syntaxErr || dupErr;
+
+    utilities[utilName] = { code: newCode, error: combinedErr };
+
+    if (combinedErr) {
+      const msgs = [syntaxErr, dupErr].filter(Boolean).join(" | ");
+      node.error(`Utility "${utilName}": ${msgs}`);
+      if (syntaxErr) {
+        const short = syntaxErr.split("\n")[0].slice(0, 40);
+        node.status({ fill: "red", shape: "dot", text: "syntax: " + short });
+      } else {
+        const firstSym = conflicts[0].split(" ")[0];
+        node.status({
+          fill: "red",
+          shape: "ring",
+          text: "duplicate symbol: " + firstSym,
+        });
+      }
+      // Don't register symbols on conflict — leave the namespace clean for
+      // whichever node actually owns them. Dependent portals will surface
+      // "broken: <utilName>" via the standard utility-error path.
+    } else {
+      // Register all new symbols as owned by this utility node
+      for (const s of newSyms) utilSymbolOwners[s] = utilName;
+      node.status({
+        fill: "green",
+        shape: "dot",
+        text: "utility: " + utilName,
+      });
+    }
+
+    // Trigger rebuild of portals using this utility (any of its inner symbols).
+    // Push BOTH the node-level utilName AND each top-level symbol into the
+    // dirty set so portals matching by either are caught by selective rebuild.
+    if (prevCode !== newCode) {
+      scheduleRebuildUsing(utilName);
+      for (const s of newSyms) scheduleRebuildUsing(s);
+      // Symbols removed in this edit must also force rebuild for portals that
+      // referenced them — those portals will fail to find the symbol and need
+      // to surface an error or recompile against the new utility code.
+      for (const s of prevSyms) if (!newSyms.has(s)) scheduleRebuildUsing(s);
+    }
+
+    node.on("close", function (removed, done) {
+      if (compNameOwners[utilName] === node.id) {
+        delete compNameOwners[utilName];
+      }
+      // Remove all symbols this node currently owns (none if it errored out
+      // on dup-check, all of newSyms otherwise — driven by the registration
+      // table, not by re-parsing the code).
+      for (const s of Object.keys(utilSymbolOwners)) {
+        if (utilSymbolOwners[s] === utilName) delete utilSymbolOwners[s];
+      }
+      const removedSyms = extractUtilitySymbols(utilities[utilName]?.code || "");
+      delete utilities[utilName];
+      scheduleRebuildUsing(utilName);
+      for (const s of removedSyms) scheduleRebuildUsing(s);
+      if (done) done();
+    });
+  }
+  RED.nodes.registerType("fc-portal-utility", PortalUtilityNode);
+
   // ── Main node: portal-react ───────────────────────────────────
 
   function PortalReactNode(config) {
@@ -313,11 +513,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 +563,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 +570,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); }
         });
@@ -364,6 +601,45 @@ module.exports = function (RED) {
         // can target only affected portals.
         portalNeeded[nodeId] = new Set(needed);
 
+        // ── Selective utility injection ──
+        // Each utility node contributes raw top-level code that may declare
+        // multiple symbols. Pull the whole node in if the user JSX OR any
+        // included library component references at least one of its symbols.
+        const allUtilEntries = Object.entries(utilities);
+        const utilSymbols = new Map(); // utilName -> Set of symbol names
+        for (const [n, u] of allUtilEntries) {
+          utilSymbols.set(n, extractUtilitySymbols(u.code || ""));
+        }
+        const includedLibraryCode = [...needed]
+          .map((n) => registry[n]?.code || "")
+          .join("\n");
+        const referencesAnySymbol = (text, syms) => {
+          for (const s of syms) {
+            const re = new RegExp(`\\b${s}\\b`);
+            if (re.test(text)) return true;
+          }
+          return false;
+        };
+        const neededUtils = new Set();
+        function addUtilWithDeps(name) {
+          if (neededUtils.has(name)) return;
+          const u = utilities[name];
+          if (!u) return;
+          neededUtils.add(name);
+          // Transitively include other utilities referenced by this utility's code
+          for (const [other, otherSyms] of utilSymbols) {
+            if (other === name) continue;
+            if (referencesAnySymbol(u.code || "", otherSyms)) {
+              addUtilWithDeps(other);
+            }
+          }
+        }
+        const userScanText = componentCode + "\n" + includedLibraryCode;
+        for (const [n, syms] of utilSymbols) {
+          if (referencesAnySymbol(userScanText, syms)) addUtilWithDeps(n);
+        }
+        portalNeededUtilities[nodeId] = new Set(neededUtils);
+
         // Topological sort only needed components
         const entries = allEntries.filter(([n]) => needed.has(n));
         entries.sort((a, b) => {
@@ -380,17 +656,39 @@ module.exports = function (RED) {
           )
           .join("\n\n");
 
-        // Extract import statements from library/user code so they appear at top level
+        // Build utility block — raw top-level concat of needed utility codes.
+        // No IIFE wrapper: a single utility node may declare many symbols.
+        const utilityJsx = [...neededUtils]
+          .map((n) => `// Utility: ${n}\n${utilities[n].code}`)
+          .join("\n\n");
+
+        // Extract import statements from library/utility/user code so they appear at top level
         const importRe = /^import\s+.+?from\s+['"].+?['"];?\s*$/gm;
         const libImports = libraryJsx.match(importRe) || [];
         const userImports = componentCode.match(importRe) || [];
+        const utilImports = utilityJsx.match(importRe) || [];
         const cleanLibJsx = libraryJsx.replace(importRe, "").trim();
         const cleanCompCode = componentCode.replace(importRe, "").trim();
+        const cleanUtilJsx = utilityJsx.replace(importRe, "").trim();
+
+        // Dedupe imports across all sources (libs may already pull React; user
+        // and utility may import the same package).
+        const seenImports = new Set();
+        const dedupImports = (arr) =>
+          arr.filter((s) => {
+            const k = s.trim();
+            if (seenImports.has(k)) return false;
+            seenImports.add(k);
+            return true;
+          });
+        const allLibImports = dedupImports(libImports);
+        const allUserImports = dedupImports(userImports);
+        const allUtilImports = dedupImports(utilImports);
 
         // Warn about import * (prevents tree-shaking)
         const starRe = /^import\s+\*\s+as\s+(\w+)\s+from\s+['"](.+?)['"];?\s*$/;
-        const allCode = cleanLibJsx + "\n" + cleanCompCode;
-        for (const imp of [...libImports, ...userImports]) {
+        const allCode = cleanLibJsx + "\n" + cleanUtilJsx + "\n" + cleanCompCode;
+        for (const imp of [...allLibImports, ...allUserImports, ...allUtilImports]) {
           const m = imp.match(starRe);
           if (!m) continue;
           const [, localName, modulePath] = m;
@@ -415,8 +713,9 @@ module.exports = function (RED) {
           'import React from "react";',
           'import ReactDOM from "react-dom";',
           'import { createRoot } from "react-dom/client";',
-          ...libImports,
-          ...userImports,
+          ...allLibImports,
+          ...allUtilImports,
+          ...allUserImports,
           "",
           "// ── React shorthand ──",
           "Object.keys(React).filter(k => /^use[A-Z]/.test(k)).forEach(k => { window[k] = React[k]; });",
@@ -441,6 +740,9 @@ module.exports = function (RED) {
             "}",
           ].join("\n"),
           "",
+          "// ── Utilities (helpers / hooks / constants) ──",
+          cleanUtilJsx,
+          "",
           "// ── Library components ──",
           cleanLibJsx,
           "",
@@ -451,7 +753,30 @@ module.exports = function (RED) {
           "createRoot(document.getElementById('root')).render(React.createElement(App));",
         ].join("\n");
 
+        const jsxHash = hash(fullJsx);
+
+        // ── Check: any used component or utility has its own syntax error ──
+        let errorSource = null;
+        let errorSourceKind = null; // 'component' | 'utility'
+        for (const name of needed) {
+          if (registry[name]?.error) {
+            errorSource = name;
+            errorSourceKind = "component";
+            break;
+          }
+        }
+        if (!errorSource) {
+          for (const name of neededUtils) {
+            if (utilities[name]?.error) {
+              errorSource = name;
+              errorSourceKind = "utility";
+              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 +788,54 @@ 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) {
+          const srcErr =
+            errorSourceKind === "utility"
+              ? utilities[errorSource].error
+              : registry[errorSource].error;
+          const label = errorSourceKind === "utility" ? "Utility" : "Component";
+          compiled = {
+            js: null,
+            error: `${label} "${errorSource}" has a syntax error:\n\n${srcErr}`,
+          };
+          errorKind = errorSourceKind;
+        } 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 === "utility"
+              ? `Utility "${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 +886,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 +904,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 +935,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 +1010,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 +1022,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(){let r=0;function c(){const p=location.protocol==='https:'?'wss:':'ws:';const ws=new WebSocket(p+'//'+location.host+'${bWsPath}');ws.onmessage=function(e){try{const m=JSON.parse(e.data);if((m.type==='version'&&m.hash)||m.type==='error')location.reload();}catch(_){}};ws.onclose=function(){const 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 +1167,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 +1197,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 +1253,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 +1311,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); }
@@ -882,6 +1332,7 @@ module.exports = function (RED) {
         // Unregister rebuild callback + selective-rebuild metadata
         delete rebuildCallbacks[nodeId];
         delete portalNeeded[nodeId];
+        delete portalNeededUtilities[nodeId];
         delete portalCode[nodeId];
 
         // Release endpoint ownership
@@ -900,6 +1351,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
@@ -1004,4 +1466,85 @@ module.exports = function (RED) {
     }
     res.json({ ok: true });
   });
+
+  // ── Admin API for utility registry ────────────────────────────
+
+  RED.httpAdmin.get("/portal-react/utilities", (_req, res) => {
+    // Include parsed top-level symbols so the editor "Utilities" dialog can
+    // list which identifiers each node exports.
+    const out = {};
+    for (const [name, u] of Object.entries(utilities)) {
+      out[name] = {
+        code: u.code,
+        error: u.error || null,
+        symbols: [...extractUtilitySymbols(u.code || "")],
+      };
+    }
+    res.json(out);
+  });
+
+  RED.httpAdmin.post("/portal-react/utilities", (req, res) => {
+    const { name, code } = req.body || {};
+    if (!isSafeName(name))
+      return res.status(400).json({ error: "invalid name" });
+    const newCode = code || "";
+    const prevCode = utilities[name]?.code;
+    const prevSyms = extractUtilitySymbols(prevCode || "");
+    const newSyms = extractUtilitySymbols(newCode);
+
+    // Free previously-owned symbols before conflict check (mirror node ctor)
+    for (const s of prevSyms) {
+      if (utilSymbolOwners[s] === name) delete utilSymbolOwners[s];
+    }
+
+    const conflicts = [];
+    for (const s of newSyms) {
+      if (Object.prototype.hasOwnProperty.call(registry, s)) {
+        conflicts.push(`${s} (component)`);
+        continue;
+      }
+      const symOwner = utilSymbolOwners[s];
+      if (symOwner && symOwner !== name) {
+        conflicts.push(`${s} (utility ${symOwner})`);
+      }
+    }
+
+    const syntaxErr = quickCheckSyntax(newCode);
+    const dupErr =
+      conflicts.length > 0
+        ? "duplicate symbols: " + conflicts.join(", ")
+        : null;
+    const combinedErr = syntaxErr || dupErr;
+
+    utilities[name] = { code: newCode, error: combinedErr };
+
+    if (!combinedErr) {
+      for (const s of newSyms) utilSymbolOwners[s] = name;
+    }
+
+    if (prevCode !== newCode) {
+      scheduleRebuildUsing(name);
+      for (const s of newSyms) scheduleRebuildUsing(s);
+      for (const s of prevSyms) if (!newSyms.has(s)) scheduleRebuildUsing(s);
+    }
+    res.json({ ok: true, error: combinedErr || null });
+  });
+
+  RED.httpAdmin.delete("/portal-react/utilities/:name", (req, res) => {
+    const name = req.params.name;
+    if (!isSafeName(name))
+      return res.status(400).json({ error: "invalid name" });
+    const prev = utilities[name];
+    delete utilities[name];
+    // Release all symbols owned by this utility
+    for (const s of Object.keys(utilSymbolOwners)) {
+      if (utilSymbolOwners[s] === name) delete utilSymbolOwners[s];
+    }
+    if (prev) {
+      const removedSyms = extractUtilitySymbols(prev.code || "");
+      scheduleRebuildUsing(name);
+      for (const s of removedSyms) scheduleRebuildUsing(s);
+    }
+    res.json({ ok: true });
+  });
 };