npm - @aaqu/fromcubes-portal-react - Versions diffs - 0.1.0-alpha.22 → 0.1.0-alpha.23 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/README.md +66 -10
package/examples/D3 Poland Map.json +90 -0
package/examples/Live Chart.json +103 -0
package/examples/PixiJS Sprites.json +118 -0
package/examples/Sensor Portal.json +97 -0
package/examples/Shared Components.json +78 -0
package/examples/Three.js Scene.json +122 -0
package/examples/Utility Hooks.json +96 -0
package/examples/WebGPU Shader.json +114 -0
package/nodes/lib/assets.js +141 -11
package/nodes/lib/helpers.js +308 -12
package/nodes/lib/hooks.js +38 -0
package/nodes/lib/page-builder.js +121 -8
package/nodes/lib/router.js +25 -1
package/nodes/portal-react.html +248 -9
package/nodes/portal-react.js +849 -192
package/package.json +20 -5
package/examples/001-shared-components-flow.json +0 -68
package/examples/002-sensor-portal-flow.json +0 -71
package/examples/003-chart-portal-flow.json +0 -93
package/examples/004-d3-poland-flow.json +0 -80
package/examples/005-threejs-portal-flow.json +0 -87
package/examples/006-pixi-portal-flow.json +0 -86
package/examples/007-webgpu-tsl-flow.json +0 -85
package/examples/008-utility-debounce-flow.json +0 -72

package/nodes/portal-react.js CHANGED Viewed

@@ -1,9 +1,97 @@
+/** @module @aaqu/fromcubes-portal-react */
 /**
- * @aaqu/fromcubes-portal-react
- *
  * Node-RED node that serves React apps from configurable HTTP endpoints
  * with live WebSocket data binding. JSX is transpiled server-side via esbuild
  * at deploy time — browsers receive pre-compiled JS.
+ *
+ * Module-global state lives on `RED.settings.portalReact*` so it survives
+ * Full deploys (Node-RED closes and re-opens every node on a Full deploy;
+ * the `RED.settings` namespace persists across that cycle).
+ */
+/**
+ * @typedef {Object} LibSpec
+ * @property {string} module          npm package name (auto-installed at deploy).
+ * @property {string} [var]           Optional global var name when bundled.
+ */
+/**
+ * @typedef {Object} PortalConfig
+ * @property {string}  subPath           URL segment served under `/fromcubes/<subPath>`.
+ * @property {string}  [endpoint]        Legacy field — hard-fails on deploy if subPath empty.
+ * @property {string}  componentCode     User JSX entrypoint (must declare `function App`).
+ * @property {string}  [pageTitle]       `<title>` for the served HTML page.
+ * @property {string}  [customHead]      Raw HTML injected into `<head>` (trusted-author content).
+ * @property {boolean} [portalAuth]      Read `x-portal-user-*` headers from incoming HTTP requests.
+ * @property {boolean} [showWsStatus]    Render the in-page `#__cs` connection badge.
+ * @property {Array<LibSpec>} [libs]    npm packages auto-installed at deploy via `dynamicModuleList`.
+ */
+/**
+ * @typedef {Object} ClientInfo
+ * @property {string}                  portalClient  Server-assigned per-tab UUID.
+ * @property {string}                  [userId]
+ * @property {string}                  [userName]
+ * @property {string}                  [username]
+ * @property {string}                  [email]
+ * @property {string}                  [role]
+ * @property {string|Array<string>}    [groups]
+ */
+/**
+ * @typedef {Object} MessagePayload
+ * @property {*}            payload
+ * @property {string}       [topic]
+ * @property {ClientInfo}   [_client]    Server-side identity (set on outbound WS msgs).
+ */
+/**
+ * @typedef {Object} RouteResult
+ * @property {"unicast"|"user-cast"|"broadcast"} mode
+ * @property {number} delivered
+ */
+/**
+ * @typedef {Object} CompiledBundle
+ * @property {?string}  js
+ * @property {?string}  error
+ * @property {Object}   [metafile]      esbuild metafile (size analysis).
+ */
+/**
+ * @typedef {Object} ComponentNodeConfig
+ * @property {string}  [name]
+ * @property {string}  compName
+ * @property {string}  compCode
+ */
+/**
+ * @typedef {Object} UtilityNodeConfig
+ * @property {string}  [name]
+ * @property {string}  utilName
+ * @property {string}  utilCode
+ */
+/**
+ * @typedef {Object} PageState
+ * @property {CompiledBundle} compiled
+ * @property {string}  contentHash       sha256-16 of the compiled JS.
+ * @property {string}  jsxHash
+ * @property {Promise<{css: string, cssHash: string}>} cssReady
+ * @property {?string} css
+ * @property {string}  cssHash
+ * @property {string}  pageTitle
+ * @property {string}  wsPath
+ * @property {string}  customHead
+ * @property {boolean} portalAuth
+ * @property {boolean} showWsStatus
+ * @property {?string} errorSource       Component / utility name responsible for the build error.
+ * @property {?string} errorKind         'component' | 'utility' | 'missing-component' | 'missing-return' | 'transpile' | 'rebuild'
+ * @property {?Object} lastGood          Snapshot of the previous successful build (degraded-mode fallback).
+ * @property {boolean} [cssError]        Tailwind generation failed on the last attempt.
+ * @property {boolean} [building]
+ * @property {?string} [runtimeError]    Browser-reported exception (truncated).
  */
 const crypto = require("crypto");
@@ -14,97 +102,312 @@ module.exports = function (RED) {
   const adminRoot = (RED.settings.httpAdminRoot || "/").replace(/\/$/, "");
   const nodeRoot = (RED.settings.httpNodeRoot || "/").replace(/\/$/, "");
+  // ── Admin auth gate (Node-RED 4.x adminAuth) ─────────────────
+  // When the user configures `adminAuth` in settings.js, RED.auth.needsPermission
+  // returns an Express middleware that enforces the named permission scope.
+  // Without this gate, any endpoint mounted on RED.httpAdmin is reachable
+  // without auth and can read/modify the registry, utilities, and assets.
+  // Fallback no-op for runtimes that do not expose RED.auth.
+  /**
+   * Resolve a Node-RED permission middleware. Returns a no-op when the runtime
+   * does not expose `RED.auth.needsPermission` (test harnesses, Node-RED <1.0)
+   * so unit tests don't have to mock auth.
+   *
+   * @param {string} scope  Permission scope (e.g. `"portal-react.write"`).
+   * @returns {import("express").RequestHandler}
+   * @private
+   */
+  function needsPerm(scope) {
+    if (RED.auth && typeof RED.auth.needsPermission === "function") {
+      return RED.auth.needsPermission(scope);
+    }
+    return function (_req, _res, next) { next(); };
+  }
+  const PERM_READ = needsPerm("portal-react.read");
+  const PERM_WRITE = needsPerm("portal-react.write");
+  // ── CSRF guard for admin write endpoints ──────────────────────
+  // The Node-RED editor sends `Node-RED-API-Version` on every XHR. Browsers
+  // refuse to attach custom headers on cross-origin form/fetch submissions
+  // without a CORS preflight, so requiring this header on write endpoints is
+  // sufficient CSRF protection without per-session tokens. Same trick the
+  // Node-RED core admin API uses for its own POST/PUT/DELETE routes.
+  /**
+   * Express middleware enforcing the `Node-RED-API-Version` header on write
+   * endpoints. The header is sent by the Node-RED editor XHR layer on every
+   * request; browser cross-origin form/fetch POSTs cannot attach custom
+   * headers without a CORS preflight, so requiring this header gives CSRF
+   * protection without per-session tokens.
+   *
+   * @param {import("express").Request}  req
+   * @param {import("express").Response} res
+   * @param {Function}                   next
+   * @returns {void}
+   * @private
+   */
+  function csrfGuard(req, res, next) {
+    if (!req.get("Node-RED-API-Version")) {
+      return res.status(403).json({ error: "missing Node-RED-API-Version header" });
+    }
+    next();
+  }
+  // ── Token-bucket rate limiter keyed by req.ip ─────────────────
+  // Steady-state: RATE_LIMIT_TOKENS tokens refilled over RATE_LIMIT_WINDOW_MS.
+  // Default = 60 tokens / 60 s → 1 req/s sustained, 60 burst. Tunable via
+  // RED.settings.portalReact.rateLimit = { tokens, windowMs }. The buckets
+  // are pruned every 5 minutes to bound memory usage.
+  const rateLimitCfg = (RED.settings.portalReact &&
+    RED.settings.portalReact.rateLimit) || {};
+  const RATE_LIMIT_TOKENS = Number.isFinite(rateLimitCfg.tokens)
+    ? rateLimitCfg.tokens
+    : 60;
+  const RATE_LIMIT_WINDOW_MS = Number.isFinite(rateLimitCfg.windowMs)
+    ? rateLimitCfg.windowMs
+    : 60_000;
+  if (!RED.settings.portalReactRateBuckets) RED.settings.portalReactRateBuckets = new Map();
+  const rateBuckets = RED.settings.portalReactRateBuckets;
+  /**
+   * Token-bucket rate limit middleware keyed by `req.ip`. Each bucket refills
+   * `RATE_LIMIT_TOKENS` over `RATE_LIMIT_WINDOW_MS`. Steady-state default is
+   * 1 request/second with a 60-token burst. On exhaustion: HTTP 429 with
+   * `Retry-After`. Buckets idle > 10 minutes get pruned by a separate
+   * interval (see below).
+   *
+   * @param {import("express").Request}  req
+   * @param {import("express").Response} res
+   * @param {Function}                   next
+   * @returns {void}
+   * @private
+   */
+  function rateLimit(req, res, next) {
+    const ip = req.ip || req.socket?.remoteAddress || "unknown";
+    const now = Date.now();
+    let b = rateBuckets.get(ip);
+    if (!b) {
+      b = { tokens: RATE_LIMIT_TOKENS, last: now };
+      rateBuckets.set(ip, b);
+    }
+    const elapsed = now - b.last;
+    b.tokens = Math.min(
+      RATE_LIMIT_TOKENS,
+      b.tokens + (elapsed * RATE_LIMIT_TOKENS) / RATE_LIMIT_WINDOW_MS,
+    );
+    b.last = now;
+    if (b.tokens < 1) {
+      res.set("Retry-After", Math.ceil(RATE_LIMIT_WINDOW_MS / 1000));
+      return res.status(429).json({ error: "rate limit exceeded" });
+    }
+    b.tokens -= 1;
+    next();
+  }
+  if (!RED.settings.portalReactRateBucketPruneIv) {
+    RED.settings.portalReactRateBucketPruneIv = setInterval(() => {
+      const now = Date.now();
+      for (const [ip, b] of rateBuckets) {
+        if (now - b.last > 10 * 60_000) rateBuckets.delete(ip);
+      }
+    }, 5 * 60_000);
+    RED.settings.portalReactRateBucketPruneIv.unref?.();
+  }
+  // ── Standard JSON parser with 1 MB limit ──────────────────────
+  // Applied per-route on POSTs that read req.body. 1 MB easily fits even
+  // large component files, and protects the registry endpoints from being
+  // used as a denial-of-service vector.
+  const JSON_BODY_LIMIT = "1mb";
+  // ── Status text helper ───────────────────────────────────────
+  // Node-RED appearance docs recommend status text "around 20 characters".
+  // Truncate with an ellipsis so long error fragments, component names, or
+  // endpoint paths don't spill past the node tile.
+  const STATUS_MAX = 20;
+  /**
+   * Truncate a status text to at most `STATUS_MAX` characters, replacing the
+   * final character with an ellipsis when truncation occurs. Keeps node tile
+   * width predictable per the Node-RED appearance guidelines.
+   *
+   * @param {*} s
+   * @returns {string}
+   */
+  function shortStatus(s) {
+    s = String(s == null ? "" : s);
+    return s.length <= STATUS_MAX ? s : s.slice(0, STATUS_MAX - 1) + "…";
+  }
   // ── Shared state ──────────────────────────────────────────────
   // Component registry: populated by fc-portal-component canvas nodes at deploy time
-  if (!RED.settings.fcPortalRegistry) {
-    RED.settings.fcPortalRegistry = {};
+  if (!RED.settings.portalReactComponentRegistry) {
+    RED.settings.portalReactComponentRegistry = {};
   }
-  const registry = RED.settings.fcPortalRegistry;
+  const registry = RED.settings.portalReactComponentRegistry;
   // Active upgrade handlers per node id (for cleanup on redeploy)
-  if (!RED.settings.fcUpgradeHandlers) {
-    RED.settings.fcUpgradeHandlers = {};
+  if (!RED.settings.portalReactUpgradeHandlers) {
+    RED.settings.portalReactUpgradeHandlers = {};
   }
-  const upgradeHandlers = RED.settings.fcUpgradeHandlers;
+  const upgradeHandlers = RED.settings.portalReactUpgradeHandlers;
   // Live page state per endpoint — route handlers read from this on each request
-  if (!RED.settings.fcPageState) {
-    RED.settings.fcPageState = {};
+  if (!RED.settings.portalReactPageState) {
+    RED.settings.portalReactPageState = {};
   }
-  const pageState = RED.settings.fcPageState;
+  const pageState = RED.settings.portalReactPageState;
   // Track which endpoints already have a registered Express route
-  if (!RED.settings.fcRegisteredRoutes) {
-    RED.settings.fcRegisteredRoutes = {};
+  if (!RED.settings.portalReactRegisteredRoutes) {
+    RED.settings.portalReactRegisteredRoutes = {};
   }
-  const registeredRoutes = RED.settings.fcRegisteredRoutes;
+  const registeredRoutes = RED.settings.portalReactRegisteredRoutes;
   // Rebuild callbacks: portal-react nodes register here so components can trigger re-transpile
-  if (!RED.settings.fcRebuildCallbacks) {
-    RED.settings.fcRebuildCallbacks = {};
+  if (!RED.settings.portalReactRebuildCallbacks) {
+    RED.settings.portalReactRebuildCallbacks = {};
   }
-  const rebuildCallbacks = RED.settings.fcRebuildCallbacks;
+  const rebuildCallbacks = RED.settings.portalReactRebuildCallbacks;
   // Per-portal set of component names the portal depends on (needed set from last rebuild,
   // including transitive deps). Lets component changes target only portals that use them.
-  if (!RED.settings.fcPortalNeeded) {
-    RED.settings.fcPortalNeeded = {};
+  if (!RED.settings.portalReactPortalNeeded) {
+    RED.settings.portalReactPortalNeeded = {};
   }
-  const portalNeeded = RED.settings.fcPortalNeeded;
+  const portalNeeded = RED.settings.portalReactPortalNeeded;
   // Per-portal raw user JSX code string. Used as fallback to detect references to
   // newly-added components that haven't been in a `needed` set yet.
-  if (!RED.settings.fcPortalCode) {
-    RED.settings.fcPortalCode = {};
+  if (!RED.settings.portalReactPortalCode) {
+    RED.settings.portalReactPortalCode = {};
   }
-  const portalCode = RED.settings.fcPortalCode;
+  const portalCode = RED.settings.portalReactPortalCode;
   // Track endpoint ownership: { endpoint: nodeId } — prevents duplicate endpoints
-  if (!RED.settings.fcEndpointOwners) {
-    RED.settings.fcEndpointOwners = {};
+  if (!RED.settings.portalReactEndpointOwners) {
+    RED.settings.portalReactEndpointOwners = {};
   }
-  const endpointOwners = RED.settings.fcEndpointOwners;
+  const endpointOwners = RED.settings.portalReactEndpointOwners;
   // 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 = {};
+  if (!RED.settings.portalReactCompNameOwners) {
+    RED.settings.portalReactCompNameOwners = {};
   }
-  const compNameOwners = RED.settings.fcCompNameOwners;
+  const compNameOwners = RED.settings.portalReactCompNameOwners;
   // 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 = {};
+  if (!RED.settings.portalReactUtilities) {
+    RED.settings.portalReactUtilities = {};
   }
-  const utilities = RED.settings.fcPortalUtilities;
+  const utilities = RED.settings.portalReactUtilities;
   // 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 = {};
+  if (!RED.settings.portalReactNeededUtilities) {
+    RED.settings.portalReactNeededUtilities = {};
   }
-  const portalNeededUtilities = RED.settings.fcPortalNeededUtilities;
+  const portalNeededUtilities = RED.settings.portalReactNeededUtilities;
   // 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 = {};
+  if (!RED.settings.portalReactUtilSymbolOwners) {
+    RED.settings.portalReactUtilSymbolOwners = {};
   }
-  const utilSymbolOwners = RED.settings.fcUtilSymbolOwners;
+  const utilSymbolOwners = RED.settings.portalReactUtilSymbolOwners;
   // 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) {
-    RED.settings.fcPortalSig = {};
+  if (!RED.settings.portalReactSig) {
+    RED.settings.portalReactSig = {};
+  }
+  const portalSig = RED.settings.portalReactSig;
+  /**
+   * Shared WebSocket heartbeat tick.
+   *
+   * Replaces the previous per-client `setInterval(ping, 30 s)` pattern: with
+   * N connected browsers the old code held N intervals; this module-level
+   * tick walks every registered `WebSocket.Server` once every 30 s and pings
+   * every alive client. Result: 1 interval regardless of fan-out.
+   *
+   * The tick auto-starts when the first portal node registers its
+   * `WebSocket.Server` via `registerPingedServer()` and clears itself when
+   * the last server unregisters. `unref()` ensures it never blocks process
+   * exit.
+   *
+   * @description N→1 interval count; bounded liveness latency 30 s.
+   * @private
+   */
+  const PING_INTERVAL_MS = 30_000;
+  if (!RED.settings.portalReactPingedServers) {
+    RED.settings.portalReactPingedServers = new Set();
+  }
+  const pingedServers = RED.settings.portalReactPingedServers;
+  if (!RED.settings.portalReactPingTick) {
+    RED.settings.portalReactPingTick = { iv: null };
+  }
+  const pingTick = RED.settings.portalReactPingTick;
+  /**
+   * Single tick of the WS keep-alive sweep. For each registered ws.Server, drop
+   * sockets whose previous ping went unanswered (they are dead) and ping the
+   * survivors. The pong handler resets `_isAlive` back to true. Runs on a
+   * shared interval so multiple portals share one timer.
+   *
+   * @returns {void}
+   * @private
+   */
+  function _pingSweep() {
+    for (const srv of pingedServers) {
+      try {
+        srv.clients.forEach((ws) => {
+          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); }
+        });
+      } catch (e) {
+        RED.log.trace("[portal-react] ping sweep: " + e.message);
+      }
+    }
+  }
+  /**
+   * Add a `WebSocket.Server` to the shared ping-tick rotation. Idempotent.
+   * Starts the global interval the first time the set is non-empty.
+   * @param {WebSocket.Server} wsServer
+   */
+  function registerPingedServer(wsServer) {
+    if (pingedServers.has(wsServer)) return;
+    pingedServers.add(wsServer);
+    if (!pingTick.iv) {
+      pingTick.iv = setInterval(_pingSweep, PING_INTERVAL_MS);
+      pingTick.iv.unref?.();
+    }
+  }
+  /**
+   * Remove a `WebSocket.Server` from the shared rotation. Clears the
+   * interval automatically when the last server unregisters.
+   * @param {WebSocket.Server} wsServer
+   */
+  function unregisterPingedServer(wsServer) {
+    if (!pingedServers.delete(wsServer)) return;
+    if (pingedServers.size === 0 && pingTick.iv) {
+      clearInterval(pingTick.iv);
+      pingTick.iv = null;
+    }
   }
-  const portalSig = RED.settings.fcPortalSig;
   // Debounced selective rebuild: coalesces multiple component changes into one pass.
   // Yields event loop between builds so HTTP server stays responsive.
@@ -118,6 +421,13 @@ module.exports = function (RED) {
   // rebuild. Hold all flushes until `flows:started` (or a 2s failsafe) so startup
   // collapses to exactly one rebuild pass.
   let _startupPhase = true;
+  /**
+   * Lift the startup gate and flush any pending rebuild work. Called once
+   * from `flows:started` and once again from a 2 s failsafe `setTimeout`;
+   * idempotent.
+   * @returns {void}
+   * @private
+   */
   function _endStartupPhase() {
     if (!_startupPhase) return;
     _startupPhase = false;
@@ -127,6 +437,11 @@ module.exports = function (RED) {
     }
   }
   try {
+    // Subscribed ONCE per process (not per deploy).
+    // Component registry is module-global state that persists across deploys.
+    // Re-running this handler on every deploy would duplicate work without
+    // benefit. For per-deploy hooks use RED.events.on('flows:started', ...)
+    // with dedup.
     if (RED.events && typeof RED.events.once === "function") {
       RED.events.once("flows:started", _endStartupPhase);
     }
@@ -134,22 +449,49 @@ module.exports = function (RED) {
   // Failsafe: if flows:started never arrives (module loaded mid-run, test harness, etc.)
   setTimeout(_endStartupPhase, 2000).unref?.();
+  /**
+   * Debounce arm — defer the next rebuild flush by 50 ms. During the
+   * startup phase the arm is a no-op; `_endStartupPhase` flushes directly.
+   * @returns {void}
+   * @private
+   */
   function _armRebuild() {
     if (_startupPhase) return; // gated — _endStartupPhase will flush
     if (_rebuildTimer) clearTimeout(_rebuildTimer);
     _rebuildTimer = setTimeout(_flushRebuild, 50);
     _rebuildTimer.unref?.();
   }
+  /**
+   * Mark a portal node id as needing rebuild on the next flush. Used by
+   * the portal constructor when its own config signature changed.
+   * @param {string} nodeId
+   */
   function scheduleRebuildSelf(nodeId) {
     if (!nodeId) return;
     _dirtyPortals.add(nodeId);
     _armRebuild();
   }
+  /**
+   * Mark a component / utility symbol as dirty. The next flush re-builds
+   * every portal that references the symbol (via `portalNeeded`,
+   * `portalNeededUtilities` or a raw-code regex scan in `portalCode`).
+   * @param {string} compName
+   */
   function scheduleRebuildUsing(compName) {
     if (!compName) return;
     _dirtyComps.add(compName);
     _armRebuild();
   }
+  /**
+   * Run pending rebuild callbacks. Resolves the union of:
+   *  - portal ids in `_dirtyPortals` (self-trigger), AND
+   *  - every portal whose `portalNeeded` / `portalNeededUtilities` / raw
+   *    code references any name in `_dirtyComps`.
+   * Each callback runs through `setImmediate` chaining so the event loop
+   * stays responsive between heavy esbuild passes.
+   * @returns {void}
+   * @private
+   */
   function _flushRebuild() {
     _rebuildTimer = null;
     const dirty = new Set(_dirtyComps);
@@ -179,6 +521,12 @@ module.exports = function (RED) {
     const fns = [...targetIds].map((id) => rebuildCallbacks[id]).filter(Boolean);
     let i = 0;
+    /**
+     * Trampoline over the rebuild list — yields to the event loop between
+     * iterations so a heavy queue does not block the HTTP server.
+     * @returns {void}
+     * @private
+     */
     function next() {
       if (i >= fns.length) return;
       try { fns[i](); } catch (e) { RED.log.error("[portal-react] rebuild failed: " + e.message); }
@@ -199,6 +547,7 @@ module.exports = function (RED) {
     removeRoute,
     isSafeName,
     validateSubPath,
+    findMissingComponentRefs,
     userDir,
     readCachedJS,
     writeCachedJS,
@@ -219,6 +568,22 @@ module.exports = function (RED) {
   // ── Canvas node: shared component ─────────────────────────────
+  /**
+   * Canvas node that registers a named React component into the shared
+   * component registry. One node = one named identifier; multiple
+   * components require multiple `fc-portal-component` nodes.
+   *
+   * Constructor side-effects:
+   *   - validates `compName` (JS identifier + length + prototype blacklist)
+   *   - checks duplicates against the cross-namespace owner table
+   *   - syntax-checks the JSX via `quickCheckSyntax`
+   *   - schedules a selective rebuild of every portal that references this name
+   *
+   * @param {ComponentNodeConfig} config
+   * @returns {void}
+   * @fires Node-RED#close  via node.on("close", …) — removes registration on disable / delete.
+   * @private
+   */
   function PortalComponentNode(config) {
     RED.nodes.createNode(this, config);
     const node = this;
@@ -239,10 +604,10 @@ module.exports = function (RED) {
       node.status({
         fill: "red",
         shape: "ring",
-        text: "duplicate: " + compName,
+        text: shortStatus("dup: " + compName),
       });
       node.on("close", function (_removed, done) {
-        if (done) done();
+        done();
       });
       return;
     }
@@ -258,10 +623,10 @@ module.exports = function (RED) {
       node.status({
         fill: "red",
         shape: "ring",
-        text: "duplicate symbol: " + compName,
+        text: shortStatus("dup sym: " + compName),
       });
       node.on("close", function (_removed, done) {
-        if (done) done();
+        done();
       });
       return;
     }
@@ -274,10 +639,10 @@ module.exports = function (RED) {
     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 });
+      const short = syntaxErr.split("\n")[0];
+      node.status({ fill: "red", shape: "dot", text: shortStatus("syntax: " + short) });
     } else {
-      node.status({ fill: "green", shape: "dot", text: compName });
+      node.status({ fill: "green", shape: "dot", text: shortStatus(compName) });
     }
     // Only rebuild portals that reference this component, and only if the code actually changed.
@@ -292,7 +657,7 @@ module.exports = function (RED) {
       delete registry[compName];
       // Portals depending on this component must rebuild (topology changed or name resolution breaks).
       scheduleRebuildUsing(compName);
-      if (done) done();
+      done();
     });
   }
   RED.nodes.registerType("fc-portal-component", PortalComponentNode);
@@ -302,14 +667,44 @@ module.exports = function (RED) {
   // 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).
+  // Code is rejected silently when oversize so the regex cannot be weaponized
+  // (ReDoS) by feeding multi-MB code into a sticky regex with `\s+` runs.
+  const MAX_UTIL_CODE_BYTES = 1_000_000;
+  /**
+   * Scan utility code for top-level `function`/`const`/`let`/`var`/`class`
+   * names. Used to populate the symbol-ownership table (collision checks)
+   * and the editor's Utilities dialog. Oversize input is rejected silently
+   * (ReDoS guard — the regex has multiple `\s+` runs that could regress
+   * to near-linear on multi-MB payloads).
+   *
+   * @param {string} code
+   * @returns {Set<string>}  set of declared top-level identifiers
+   * @example
+   *   extractUtilitySymbols("const PI = 3.14;\nfunction add(a,b) { return a+b }");
+   *   // → Set(2) { "PI", "add" }
+   */
   function extractUtilitySymbols(code) {
     const names = new Set();
+    if (!code || code.length > MAX_UTIL_CODE_BYTES) return names;
     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]);
+    while ((m = re.exec(code))) names.add(m[1]);
     return names;
   }
+  /**
+   * Canvas node that contributes raw top-level JavaScript (helpers / custom
+   * hooks / constants) to the bundle. Unlike `fc-portal-component`, the code
+   * is injected *without* an IIFE wrapper — one node can declare many
+   * top-level symbols. Each symbol is registered with the cross-namespace
+   * owner table so identifiers don't collide with component names or other
+   * utility nodes.
+   *
+   * @param {UtilityNodeConfig} config
+   * @returns {void}
+   * @fires Node-RED#close  on disable / delete — frees registry + owned symbols.
+   * @private
+   */
   function PortalUtilityNode(config) {
     RED.nodes.createNode(this, config);
     const node = this;
@@ -330,10 +725,10 @@ module.exports = function (RED) {
       node.status({
         fill: "red",
         shape: "ring",
-        text: "duplicate: " + utilName,
+        text: shortStatus("dup: " + utilName),
       });
       node.on("close", function (_removed, done) {
-        if (done) done();
+        done();
       });
       return;
     }
@@ -382,14 +777,14 @@ module.exports = function (RED) {
       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 });
+        const short = syntaxErr.split("\n")[0];
+        node.status({ fill: "red", shape: "dot", text: shortStatus("syntax: " + short) });
       } else {
         const firstSym = conflicts[0].split(" ")[0];
         node.status({
           fill: "red",
           shape: "ring",
-          text: "duplicate symbol: " + firstSym,
+          text: shortStatus("dup sym: " + firstSym),
         });
       }
       // Don't register symbols on conflict — leave the namespace clean for
@@ -401,7 +796,7 @@ module.exports = function (RED) {
       node.status({
         fill: "green",
         shape: "dot",
-        text: "utility: " + utilName,
+        text: shortStatus(utilName),
       });
     }
@@ -431,13 +826,36 @@ module.exports = function (RED) {
       delete utilities[utilName];
       scheduleRebuildUsing(utilName);
       for (const s of removedSyms) scheduleRebuildUsing(s);
-      if (done) done();
+      done();
     });
   }
   RED.nodes.registerType("fc-portal-utility", PortalUtilityNode);
   // ── Main node: portal-react ───────────────────────────────────
+  /**
+   * Main canvas node: serves a React app at `/fromcubes/<subPath>` and
+   * bridges its WebSocket to Node-RED wires.
+   *
+   * Lifecycle (per deploy):
+   *   1. Validate subPath / legacy endpoint migration.
+   *   2. Take ownership of the endpoint (one portal per URL).
+   *   3. Compute the config signature — skip rebuild if unchanged.
+   *   4. Register rebuild callback in `rebuildCallbacks`.
+   *   5. Inside `setImmediate`: mount HTTP route, attach WS upgrade handler,
+   *      wire `input` + `close` events.
+   *
+   * Input handler routes incoming `msg` through `lib/router.js` and caches
+   * the payload (deep-cloned) when broadcasting so freshly-connected clients
+   * recover the last value.
+   *
+   * @param {PortalConfig} config
+   * @returns {void}
+   * @fires Node-RED#close
+   * @listens Node-RED#input
+   * @listens ws#connection
+   * @private
+   */
   function PortalReactNode(config) {
     RED.nodes.createNode(this, config);
     const node = this;
@@ -464,7 +882,7 @@ module.exports = function (RED) {
         node.status({ fill: "red", shape: "ring", text: "bad sub-path" });
       }
       node.on("close", function (_removed, done) {
-        if (done) done();
+        done();
       });
       return;
     }
@@ -487,10 +905,10 @@ module.exports = function (RED) {
       node.status({
         fill: "red",
         shape: "ring",
-        text: "duplicate: " + endpoint,
+        text: shortStatus("dup: " + subPath),
       });
       node.on("close", function (_removed, done) {
-        if (done) done();
+        done();
       });
       return;
     }
@@ -511,56 +929,96 @@ module.exports = function (RED) {
     const wsPath = nodeRoot + endpoint + "/_ws";
+    /**
+     * Refresh the canvas-node status indicator. Priority of states (highest
+     * first): build error > building > runtime error > CSS-fail >
+     * connected/0-clients. Returns early when the node is closing so a late
+     * rebuild promise can't flash a stale state on a torn-down node.
+     * @returns {void}
+     * @private
+     */
     function updateStatus() {
       if (isClosing) return;
       const st = pageState[endpoint];
       const n = clients.size;
-      const clientTail = n > 0 ? ` [${n} client${n !== 1 ? "s" : ""}]` : "";
+      // Compact tail keeps within the 20-char status budget. Shape (ring vs
+      // dot) and fill carry the "0 clients" + "degraded" signals; we no
+      // longer pack them into the text.
+      const tail = n > 0 ? ` [${n}]` : "";
-      // 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 });
-        }
+        if (st.errorKind === "missing-component") base = "missing: " + st.errorSource;
+        else if (st.errorSource) base = "broken: " + st.errorSource;
+        else if (st.errorKind === "missing-return") base = "no return";
+        else if (st.errorKind === "rebuild") base = "rebuild err";
+        else base = "transpile err";
+        // Degraded mode = ring shape (already conveys "serving last good");
+        // hard failure = dot. Text stays ≤20.
+        node.status({
+          fill: "red",
+          shape: st.lastGood ? "ring" : "dot",
+          text: shortStatus(base + tail),
+        });
         return;
       }
-      // Preserve building state — same reason.
       if (st && st.building) {
-        node.status({ fill: "yellow", shape: "dot", text: "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,
+          text: shortStatus("runtime err" + tail),
+        });
+        return;
+      }
+      // CSS generation failed but JS is fine — the portal still works,
+      // just unstyled. Yellow ring distinguishes from green-OK without
+      // claiming "broken". Cleared on the next successful CSS pass.
+      if (st && st.cssError) {
+        node.status({
+          fill: "yellow",
+          shape: "ring",
+          text: shortStatus("css-fail" + tail),
         });
         return;
       }
+      // All status text stays as English literals for now. A full i18n
+      // catalog migration is tracked separately — until then, mixing one
+      // RED._(...) call with ~10 hardcoded strings would just confuse the
+      // reader without giving any locale coverage.
       node.status({
         fill: n > 0 ? "green" : "grey",
         shape: n > 0 ? "dot" : "ring",
-        text: `${endpoint}${clientTail || " [0 clients]"}`,
+        text: n > 0 ? "connected" + tail : "0 clients",
       });
     }
     // ── Rebuild: transpile JSX + update page state ────────────
+    /**
+     * Transpile and bundle the portal's JSX into a fresh PageState entry.
+     *
+     * Pipeline (per call):
+     *   1. Resolve needed components (transitive deps from registry)
+     *   2. Resolve needed utility nodes (any symbol referenced anywhere)
+     *   3. Hoist imports, dedupe across sources
+     *   4. Pre-flight: syntax errors in components / utilities, missing
+     *      `return` in `function App`
+     *   5. Read disk cache; on miss run `transpile()` (esbuild buildSync)
+     *   6. Generate Tailwind CSS (cssReady promise)
+     *   7. Snapshot lastGood for degraded-mode serving
+     *   8. Broadcast `version` / `error` / `building` frames to live WS
+     *
+     * Errors set `pageState[endpoint].compiled.error` and the route handler
+     * serves an error page (or the previous lastGood build with a banner).
+     *
+     * @returns {void}
+     * @throws never — internal exceptions are caught and stored in pageState.
+     * @private
+     */
     function rebuild() {
       try {
         // ── Pre-build: clear cache, set building state, notify browsers ──
@@ -579,20 +1037,45 @@ module.exports = function (RED) {
         const allEntries = Object.entries(registry);
         const needed = new Set();
+        // Word-boundary identifier match. Avoids prefix collisions (e.g. a
+        // `Button` rebuild marking `ButtonGroup` users as needing rebuild)
+        // and matches identifiers, not substrings inside other words.
+        // Regexes are cached per name so we don't pay the constructor cost
+        // on every recursion of addWithDeps.
+        const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const nameReCache = new Map();
+        const refRe = (n) => {
+          let r = nameReCache.get(n);
+          if (!r) {
+            r = new RegExp(`\\b${escapeRe(n)}\\b`);
+            nameReCache.set(n, r);
+          }
+          return r;
+        };
+        /**
+         * Depth-first walk that pulls a component and every transitively
+         * referenced sibling into `needed`. Matching uses `\b<name>\b`
+         * (cached) so a component named `Button` does not pull in
+         * `ButtonGroup`.
+         * @param {string} name
+         * @returns {void}
+         * @private
+         */
         function addWithDeps(name) {
           if (needed.has(name)) return;
           const entry = registry[name];
           if (!entry) return;
           needed.add(name);
           for (const [other] of allEntries) {
-            if (other !== name && entry.code.includes(other)) {
+            if (other !== name && refRe(other).test(entry.code)) {
               addWithDeps(other);
             }
           }
         }
         for (const [name] of allEntries) {
-          if (componentCode.includes(name)) {
+          if (refRe(name).test(componentCode)) {
             addWithDeps(name);
           }
         }
@@ -621,6 +1104,14 @@ module.exports = function (RED) {
           return false;
         };
         const neededUtils = new Set();
+        /**
+         * Same walk as `addWithDeps` but over utility nodes — a utility is
+         * included as soon as any of its top-level symbols is referenced.
+         * Transitive: pulled-in utilities can in turn reference others.
+         * @param {string} name
+         * @returns {void}
+         * @private
+         */
         function addUtilWithDeps(name) {
           if (neededUtils.has(name)) return;
           const u = utilities[name];
@@ -671,6 +1162,24 @@ module.exports = function (RED) {
         const cleanCompCode = componentCode.replace(importRe, "").trim();
         const cleanUtilJsx = utilityJsx.replace(importRe, "").trim();
+        // ── Check: JSX references a PascalCase tag with no definition ──
+        // Catches the common foot-gun where a portal references a shared
+        // component (e.g. <Header/>) without the example flow that defines
+        // it being imported. Without this check the bundler silently skips
+        // the missing name and the browser crashes with ReferenceError.
+        let missingComps = null;
+        {
+          const knownNames = new Set(Object.keys(registry));
+          for (const [, syms] of utilSymbols) {
+            for (const s of syms) knownNames.add(s);
+          }
+          // Use raw componentCode (with imports intact) so the helper can see
+          // `import {Canvas} from '@react-three/fiber'` and not flag Canvas
+          // as a missing fc-portal-component.
+          const miss = findMissingComponentRefs(componentCode, knownNames);
+          if (miss.size > 0) missingComps = [...miss].sort();
+        }
         // Dedupe imports across all sources (libs may already pull React; user
         // and utility may import the same package).
         const seenImports = new Set();
@@ -794,8 +1303,23 @@ module.exports = function (RED) {
         // ── Resolve compiled (success or unified error) ──
         let compiled;
         let cacheHit = false;
-        let errorKind = null; // 'component' | 'missing-return' | 'transpile'
-        if (errorSource) {
+        let errorKind = null; // 'component' | 'utility' | 'missing-component' | 'missing-return' | 'transpile'
+        if (missingComps) {
+          const list = missingComps.join(", ");
+          const plural = missingComps.length > 1;
+          const hint = plural
+            ? `Make sure these fc-portal-components exist (e.g. import the "Shared Components" example flow): ${list}.`
+            : `Make sure a fc-portal-component named "${missingComps[0]}" exists (e.g. import the "Shared Components" example flow), then redeploy.`;
+          compiled = {
+            js: null,
+            error: `Missing component${plural ? "s" : ""}: ${list}\n\n${hint}`,
+          };
+          errorKind = "missing-component";
+          // Re-use errorSource for status/text — first missing name + count tail.
+          errorSource = plural
+            ? `${missingComps[0]} +${missingComps.length - 1}`
+            : missingComps[0];
+        } else if (errorSource) {
           const srcErr =
             errorSourceKind === "utility"
               ? utilities[errorSource].error
@@ -827,7 +1351,9 @@ module.exports = function (RED) {
         if (compiled.error) {
           node.error(
-            (errorKind === "component"
+            (errorKind === "missing-component"
+              ? "Missing component(s) in JSX: "
+              : errorKind === "component"
               ? `Component "${errorSource}" syntax error: `
               : errorKind === "utility"
               ? `Utility "${errorSource}" syntax error: `
@@ -879,7 +1405,15 @@ module.exports = function (RED) {
                 return { css, cssHash };
               });
             })().catch((err) => {
+              // CSS generation failed (Tailwind compile error, missing
+              // entrypoint, etc.). Surface as warn + flag pageState so
+              // updateStatus() shows a yellow ring "css-fail" — the portal
+              // page still loads (empty CSS), just unstyled. Cleared on
+              // the next successful build.
               node.warn("Tailwind CSS generation failed: " + err.message);
+              const st = pageState[endpoint];
+              if (st) st.cssError = true;
+              updateStatus();
               return { css: "", cssHash: "" };
             })
           : Promise.resolve({ css: "", cssHash: "" });
@@ -930,24 +1464,36 @@ module.exports = function (RED) {
           });
         }
-        cssReady.then(({ css, cssHash }) => {
-          const state = pageState[endpoint];
-          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,
-              };
+        cssReady
+          .then(({ css, cssHash }) => {
+            const state = pageState[endpoint];
+            if (state && state.jsxHash === jsxHash) {
+              state.css = css;
+              state.cssHash = cssHash;
+              // Clear css-fail flag on a successful generation. Only the
+              // outer .catch above sets it, so we don't risk wiping a
+              // freshly-set error mid-flight.
+              if (cssHash) state.cssError = false;
+              // 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();
             }
-            updateStatus();
-          }
-        });
+          })
+          .catch((e) => {
+            // Tail-handler — generateCSS already has its own .catch upstream
+            // that yields { css: "", cssHash: "" }. This guards against
+            // exceptions thrown inside the state-update block above so the
+            // process doesn't see an UnhandledPromiseRejection.
+            RED.log.warn("[portal-react] cssReady tail: " + e.message);
+          });
       } catch (e) {
         node.error("Rebuild failed: " + e.message);
         // Surface as a regular build error so the lastGood/degraded path,
@@ -1109,7 +1655,11 @@ module.exports = function (RED) {
       try {
         const WebSocket = require("ws");
-        wsServer = new WebSocket.Server({ noServer: true });
+        // 1 MB hard cap on incoming WS frames — far above typical msg.output
+        // sizes (a few KB of JSON) and well below the 100 MB default. Blocks
+        // a hostile client from spamming oversized frames.
+        wsServer = new WebSocket.Server({ noServer: true, maxPayload: 1024 * 1024 });
+        registerPingedServer(wsServer);
         // Remove previous upgrade handler for this node (dirty deploy)
         if (upgradeHandlers[nodeId]) {
@@ -1198,17 +1748,11 @@ module.exports = function (RED) {
           }
           // Heartbeat — detect dead sockets via WS ping/pong. Browser
-          // auto-replies to ping frames, no client JS needed.
+          // auto-replies to ping frames, no client JS needed. The actual
+          // ping interval lives in the module-level `_pingSweep` tick;
+          // each client only needs the alive flag and pong listener here.
           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 {
@@ -1238,6 +1782,9 @@ module.exports = function (RED) {
                 // inbound frame.
                 const client = { portalClient: ws._portalClient };
                 if (portalAuth && ws._portalUser) {
+                  // Source is extractPortalUser() — whitelist of named
+                  // header reads. No untrusted key can land here, so this
+                  // Object.assign cannot be turned into prototype pollution.
                   Object.assign(client, ws._portalUser);
                 }
                 out._client = client;
@@ -1253,7 +1800,8 @@ module.exports = function (RED) {
           });
           const detach = () => {
-            if (ws._pingIv) { clearInterval(ws._pingIv); ws._pingIv = null; }
+            // No per-client interval to clear — heartbeat is centralised in
+            // the shared `_pingSweep` tick (see registerPingedServer).
             clients.delete(portalClient);
             if (userId) {
               const set = userIndex.get(userId);
@@ -1277,6 +1825,15 @@ module.exports = function (RED) {
       // sendTo: single point where every outbound frame passes through
       // the onCanSendTo hook. Strict-by-default — no opt-in per widget
       // type like dashboard's acceptsClientConfig.
+      /**
+       * Send a pre-serialised frame to one WS client, gated by the
+       * `onCanSendTo` plugin hook. Returns true on successful send.
+       * @param {import("ws").WebSocket} ws
+       * @param {string} frame                JSON-encoded payload.
+       * @param {MessagePayload} msg          Inspected by plugin hooks.
+       * @returns {boolean}
+       * @private
+       */
       function sendTo(ws, frame, msg) {
         if (!ws || ws.readyState !== 1) return false;
         if (!hooks.allow("onCanSendTo", ws, msg)) return false;
@@ -1290,94 +1847,156 @@ module.exports = function (RED) {
       }
       node.on("input", (msg, send, done) => {
-        const result = router.route(msg, { clients, userIndex, sendTo });
-        // Cache the latest broadcast payload so freshly-connected clients
-        // can recover it via the `recovery` frame on connect.
-        if (result.mode === "broadcast") {
-          lastBroadcastCache.set(endpoint, msg.payload);
+        // Target Node-RED ≥4.0: `done` is always present. No defensive guard.
+        try {
+          const result = router.route(msg, { clients, userIndex, sendTo });
+          // Cache the latest broadcast payload so freshly-connected clients
+          // can recover it via the `recovery` frame on connect. Deep-clone via
+          // RED.util.cloneMessage so a downstream mutation cannot retroactively
+          // change what a fresh client sees on connect.
+          if (result.mode === "broadcast") {
+            let cached;
+            try {
+              cached = RED.util.cloneMessage({ p: msg.payload }).p;
+            } catch (_) {
+              cached = msg.payload;
+            }
+            lastBroadcastCache.set(endpoint, cached);
+          }
+          updateStatus();
+          done();
+        } catch (err) {
+          // Catch-node propagation: done(err) lets the runtime route the
+          // error to a Catch node on the same tab (Node-RED docs: "this will
+          // trigger any Catch nodes present on the same tab").
+          done(err);
         }
-        updateStatus();
-        if (done) done();
       });
       // ── Cleanup on redeploy / shutdown ────────────────────────
+      //
+      // Teardown order (Node-RED gives us a 15 s budget before forcibly
+      // killing the close handler):
+      //   1. mark isClosing = true (refuse new WS upgrades)
+      //   2. close all WS clients with 1001
+      //   3. remove the upgrade listener from RED.server
+      //   4. close the ws.Server
+      //   5. clear timers / interval handles
+      //   6. drop route & shared state (only when fully removed)
+      //   7. done()
+      //
+      // `removed` is true when the node is deleted *or* disabled in the
+      // editor (Node-RED docs). For both we drop persistent route + cache;
+      // for redeploy (removed=false) we keep pageState[endpoint] so
+      // reconnecting clients hit the same build with a smaller delay.
       node.on("close", (removed, done) => {
-        isClosing = true;
+        let doneCalled = false;
+        const callDone = (err) => {
+          if (doneCalled) return;
+          doneCalled = true;
+          done(err);
+        };
+        // Safety net — runtime force-kills at 15 s. Resolve at 14 s if
+        // teardown is somehow blocked so we don't get a hard timeout log.
+        const safety = setTimeout(() => callDone(), 14_000);
+        safety.unref?.();
-        // Remove upgrade handler
-        if (upgradeHandlers[nodeId]) {
-          RED.server.removeListener("upgrade", upgradeHandlers[nodeId]);
-          delete upgradeHandlers[nodeId];
-        }
+        try {
+          isClosing = true;
-        // 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); }
-        });
-        clients.clear();
+          // Close all WS clients. Heartbeat lives in the shared module-level
+          // sweep tick — no per-client cleanup needed here. ws.close() is
+          // non-blocking; we don't await drain.
+          clients.forEach((ws) => {
+            try {
+              ws.close(1001, "node redeployed");
+            } catch (e) { RED.log.trace("[portal-react] ws close client: " + e.message); }
+          });
+          clients.clear();
-        // Close WS server
-        if (wsServer) {
-          try {
-            wsServer.close();
-          } catch (e) { RED.log.trace("[portal-react] wsServer close: " + e.message); }
-          wsServer = null;
-        }
+          // Remove upgrade handler before tearing down the WS server so a
+          // late upgrade request doesn't race into a half-closed wsServer.
+          if (upgradeHandlers[nodeId]) {
+            RED.server.removeListener("upgrade", upgradeHandlers[nodeId]);
+            delete upgradeHandlers[nodeId];
+          }
-        // Unregister rebuild callback + selective-rebuild metadata
-        delete rebuildCallbacks[nodeId];
-        delete portalNeeded[nodeId];
-        delete portalNeededUtilities[nodeId];
-        delete portalCode[nodeId];
+          // Close WS server — also drop it from the shared heartbeat tick.
+          // When the last portal node tears down its server, the shared
+          // interval auto-clears (see unregisterPingedServer).
+          if (wsServer) {
+            unregisterPingedServer(wsServer);
+            try {
+              wsServer.close();
+            } catch (e) { RED.log.trace("[portal-react] wsServer close: " + e.message); }
+            wsServer = null;
+          }
-        // Release endpoint ownership
-        if (endpointOwners[endpoint] === nodeId) {
-          delete endpointOwners[endpoint];
-        }
+          // Unregister rebuild callback + selective-rebuild metadata
+          delete rebuildCallbacks[nodeId];
+          delete portalNeeded[nodeId];
+          delete portalNeededUtilities[nodeId];
+          delete portalCode[nodeId];
-        // Drop the recovery cache only on full node removal — on a
-        // redeploy we keep it so reconnecting clients still recover.
-        if (removed) {
-          lastBroadcastCache.delete(endpoint);
-          delete portalSig[nodeId];
-        }
+          // Release endpoint ownership
+          if (endpointOwners[endpoint] === nodeId) {
+            delete endpointOwners[endpoint];
+          }
-        // Clear the userIndex — WS clients are already closed above, but
-        // 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;
-        }
+          // Drop the recovery cache on full removal/disable; on a plain
+          // redeploy keep it so reconnecting clients still recover.
+          if (removed) {
+            lastBroadcastCache.delete(endpoint);
+            delete portalSig[nodeId];
+          }
-        // Clean up route only when node is fully removed (not redeployed)
-        if (removed) {
-          // Delete disk cache if no other endpoint uses this hash
-          if (lastJsxHash && !isHashInUse(lastJsxHash, pageState, endpoint)) {
-            deleteCacheFiles(lastJsxHash);
+          // Clear the userIndex — WS clients are already closed above, but
+          // 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;
           }
-          delete pageState[endpoint];
-          removeRoute(RED.httpNode._router, endpoint);
-          delete registeredRoutes[endpoint];
-        }
-        if (done) done();
+          // Clean up route only on full removal/disable (not on redeploy).
+          if (removed) {
+            // Delete disk cache if no other endpoint uses this hash
+            if (lastJsxHash && !isHashInUse(lastJsxHash, pageState, endpoint)) {
+              deleteCacheFiles(lastJsxHash);
+            }
+            delete pageState[endpoint];
+            removeRoute(RED.httpNode._router, endpoint);
+            delete registeredRoutes[endpoint];
+          }
+          clearTimeout(safety);
+          callDone();
+        } catch (err) {
+          clearTimeout(safety);
+          callDone(err);
+        }
       });
       // ── Utilities ─────────────────────────────────────────────
+      /**
+       * Best-effort `JSON.stringify` + `ws.send`. Swallows write errors at
+       * trace level — used for status/control frames where dropping a
+       * single packet has no semantic impact (the next deploy or heartbeat
+       * will reconcile state).
+       * @param {import("ws").WebSocket} ws
+       * @param {Object} obj
+       * @returns {void}
+       * @private
+       */
       function wsSend(ws, obj) {
         try {
           if (ws.readyState === 1) ws.send(JSON.stringify(obj));
@@ -1398,13 +2017,14 @@ module.exports = function (RED) {
   );
   RED.httpAdmin.use(
     "/portal-react/vs",
+    PERM_READ,
     express.static(path.join(monacoPath, "min", "vs")),
   );
   // ── Tailwind class list endpoint ────────────────────────────
   const { generateCandidates } = require("./tw-candidates");
   let twClassesCache = null;
-  RED.httpAdmin.get("/portal-react/tw-classes", (_req, res) => {
+  RED.httpAdmin.get("/portal-react/tw-classes", PERM_READ, (_req, res) => {
     if (!twClassesCache) {
       twClassesCache = generateCandidates();
     }
@@ -1412,8 +2032,41 @@ module.exports = function (RED) {
   });
   // ── Vendor CSS endpoint (per page, looked up from pageState) ─────────
+  // Public (httpNode) — served to browsers loading the portal page, not the
+  // editor. Hash is constrained to short hex so a hostile client cannot probe
+  // for arbitrary pageState keys.
+  const CSS_HASH_RE = /^[a-f0-9]{1,64}$/;
+  RED.httpNode.get("/fromcubes/css/:hash.css", (req, res) => {
+    const reqHash = req.params.hash;
+    if (!CSS_HASH_RE.test(reqHash)) {
+      res.status(400).send("Bad request");
+      return;
+    }
+    let css = null;
+    for (const ep in pageState) {
+      if (pageState[ep]?.cssHash === reqHash) {
+        css = pageState[ep].css;
+        break;
+      }
+    }
+    if (!css) {
+      res.status(404).send("Not found");
+      return;
+    }
+    res.set({
+      "Content-Type": "text/css",
+      "Cache-Control": "public, max-age=31536000, immutable",
+    });
+    res.send(css);
+  });
+  // Back-compat: legacy admin URL still works (page-builder may emit it for
+  // existing builds). Apply the same hash whitelist.
   RED.httpAdmin.get("/portal-react/css/:hash.css", (req, res) => {
     const reqHash = req.params.hash;
+    if (!CSS_HASH_RE.test(reqHash)) {
+      res.status(400).send("Bad request");
+      return;
+    }
     let css = null;
     for (const ep in pageState) {
       if (pageState[ep]?.cssHash === reqHash) {
@@ -1434,15 +2087,19 @@ module.exports = function (RED) {
   // ── Public assets folder ─────────────────────────────────────
   const { registerAssets } = require("./lib/assets");
-  registerAssets(RED, express, path.join(userDir, "fromcubes", "public"));
+  registerAssets(RED, express, path.join(userDir, "fromcubes", "public"), {
+    csrfGuard,
+    rateLimit,
+    jsonLimit: JSON_BODY_LIMIT,
+  });
   // ── Admin API for component registry ──────────────────────────
-  RED.httpAdmin.get("/portal-react/registry", (_req, res) => {
+  RED.httpAdmin.get("/portal-react/registry", PERM_READ, (_req, res) => {
     res.json(registry);
   });
-  RED.httpAdmin.post("/portal-react/registry", (req, res) => {
+  RED.httpAdmin.post("/portal-react/registry", PERM_WRITE, csrfGuard, rateLimit, express.json({ limit: JSON_BODY_LIMIT }), (req, res) => {
     const { name, code } = req.body || {};
     if (!isSafeName(name))
       return res.status(400).json({ error: "invalid name" });
@@ -1455,7 +2112,7 @@ module.exports = function (RED) {
     res.json({ ok: true });
   });
-  RED.httpAdmin.delete("/portal-react/registry/:name", (req, res) => {
+  RED.httpAdmin.delete("/portal-react/registry/:name", PERM_WRITE, csrfGuard, rateLimit, (req, res) => {
     const name = req.params.name;
     if (!isSafeName(name))
       return res.status(400).json({ error: "invalid name" });
@@ -1469,7 +2126,7 @@ module.exports = function (RED) {
   // ── Admin API for utility registry ────────────────────────────
-  RED.httpAdmin.get("/portal-react/utilities", (_req, res) => {
+  RED.httpAdmin.get("/portal-react/utilities", PERM_READ, (_req, res) => {
     // Include parsed top-level symbols so the editor "Utilities" dialog can
     // list which identifiers each node exports.
     const out = {};
@@ -1483,7 +2140,7 @@ module.exports = function (RED) {
     res.json(out);
   });
-  RED.httpAdmin.post("/portal-react/utilities", (req, res) => {
+  RED.httpAdmin.post("/portal-react/utilities", PERM_WRITE, csrfGuard, rateLimit, express.json({ limit: JSON_BODY_LIMIT }), (req, res) => {
     const { name, code } = req.body || {};
     if (!isSafeName(name))
       return res.status(400).json({ error: "invalid name" });
@@ -1530,7 +2187,7 @@ module.exports = function (RED) {
     res.json({ ok: true, error: combinedErr || null });
   });
-  RED.httpAdmin.delete("/portal-react/utilities/:name", (req, res) => {
+  RED.httpAdmin.delete("/portal-react/utilities/:name", PERM_WRITE, csrfGuard, rateLimit, (req, res) => {
     const name = req.params.name;
     if (!isSafeName(name))
       return res.status(400).json({ error: "invalid name" });