@aaqu/fromcubes-portal-react 0.1.0-alpha.15 → 0.1.0-alpha.17

package/README.md

@@ -1,41 +1,12 @@
 # @aaqu/fromcubes-portal-react
 
-> **⚠️ Alpha Module** — This project is in early development. Expect many breaking changes. Please test on a clean Node-RED instance.
+> **⚠️ Alpha Module** — This project is in early development. Expect breaking changes. Test on a clean Node-RED instance.
 
-React portal node for Node-RED. Server-side JSX transpilation via esbuild. Tailwind CSS 4. Zero runtime compilation in browser.
+A Node-RED node that turns any `/fromcubes/<sub-path>` URL into a React page. Write JSX in the editor, deploy, open the URL — your component talks to the flow over WebSocket. No build step, no browser compiler. All portal pages are served under the hardcoded `/fromcubes/` prefix so every node cleanly coexists under one URL tree.
 
-[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L4L01UOFRG)
-
-## How it works
+For internals, plugin authoring, and the deploy pipeline see [README-DEV.md](./README-DEV.md).
 
-```
-┌─ Deploy time (Node-RED server) ───────────────────────────┐
-│                                                           │
-│  npm packages  ──►  auto-installed at deploy              │
-│       (d3, three, @react-three/fiber…)                    │
-│       via dynamicModuleList                               │
-│                                                           │
-│  React + packages + JSX  ──►  single esbuild pass         │
-│       one IIFE, one React instance (alias)                │
-│       tree-shaking removes unused exports                 │
-│       React peer deps share same instance                 │
-│                                                           │
-│  Tailwind classes  ──►  server-side compile  ──►  CSS     │
-│       stored per-page in pageState                        │
-│                                                           │
-│  Unchanged JSX on redeploy = reuse CSS, 0ms               │
-│  Changed JSX = retranspile, ~5ms                          │
-└───────────────────────────────────────────────────────────┘
-
-┌─ Runtime (browser) ───────────────────────────────────────┐
-│                                                           │
-│  GET /endpoint  ──►  HTML + single inlined JS bundle      │
-│                      Tailwind CSS (server-compiled)       │
-│                      NO Babel, NO Sucrase, NO compiler    │
-│                                                           │
-│  WebSocket /endpoint/_ws  ◄──►  Node-RED msg I/O          │
-└───────────────────────────────────────────────────────────┘
-```
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L4L01UOFRG)
 
 ## Install
 
@@ -45,57 +16,92 @@ npm install @aaqu/fromcubes-portal-react@alpha
 # restart Node-RED
 ```
 
-Dependencies install automatically. No build step needed.
+That's it. No build step. Any npm packages you list in the node config (e.g. `d3, three`) are installed automatically on deploy.
+
+## Your first portal
+
+1. Drop a **portal-react** node onto a flow.
+2. Set **Sub-path** to e.g. `hello` (the node will serve at `/fromcubes/hello`; the `/fromcubes/` prefix is fixed).
+3. Open the code editor and paste:
+   ```jsx
+   function App() {
+     const { data, send } = useNodeRed();
+     return (
+       <div className="p-4">
+         <p>From flow: {JSON.stringify(data)}</p>
+         <button
+           className="px-3 py-1 bg-blue-500 text-white rounded"
+           onClick={() => send({ clicked: Date.now() })}
+         >
+           click me
+         </button>
+       </div>
+     );
+   }
+   ```
+4. Deploy. Open `http://localhost:1880/fromcubes/hello`.
+5. Wire an **inject** node into the portal-react input → see `data` update live. Wire its output → see button clicks arrive in your flow.
+
+## The `useNodeRed()` hook
+
+Everything your component needs from the flow lives in one hook:
 
-## npm scripts
+```jsx
+const {
+  data,          // last broadcast msg.payload from input wire (reactive)
+  send,          // send(payload, topic?) — emit msg on output wire
+  user,          // portal user object (when Portal Auth is enabled), or null
+  portalClient,  // unique session/tab ID assigned by server on connect
+} = useNodeRed();
+```
 
-| Script | Purpose |
-|---|---|
-| `npm start` | Start Node-RED |
+### Recovery on connect
 
-## Nodes
+A freshly-connected client receives the **last broadcast payload** the server has cached for this endpoint, sent as a distinct `recovery` frame. By default it's seeded straight into `data`, so the first render of a new tab shows the most recent value instead of waiting for the next broadcast — same idea as dashboard2's `lastMsg`.
 
-### portal-react
+Opt out per page:
 
-| Field | Purpose                                                          |
-|---|------------------------------------------------------------------|
-| Endpoint | HTTP path, e.g. `/fromcubes/page1`                               |
-| Page Title | Browser tab title                                                |
-| npm Packages | Comma-separated packages, e.g. `d3, three, @react-three/fiber` |
-| Portal Auth | Enable portal user header extraction                             |
-| Head HTML | Extra `<head>` tags (CDN, fonts, CSS)                            |
-| Code Editor | Monaco with JSX — must define `<App />`                          |
+```jsx
+// data stays undefined until a fresh broadcast arrives — no recovery seed
+const { data } = useNodeRed({ ignoreRecovery: true });
+```
 
-### fc-portal-component (config node)
+The opt-out is page-wide — the strictest call wins. If any component on the page asks to ignore recovery, recovery is dropped for all of them.
 
-Shared component store. Each component has name, code, input/output field definitions.
-Referenced components (with transitive dependencies) are selectively injected at transpile time.
+## Node configuration
+
+| Field | Purpose |
+|---|---|
+| Sub-path | Part after `/fromcubes/`, e.g. `page1` → served at `/fromcubes/page1`. Required. Nesting allowed (`team/alpha`). Reserved: `public`, `_ws`. |
+| Page Title | Browser tab title |
+| npm Packages | Comma-separated, e.g. `d3, three, @react-three/fiber` |
+| Portal Auth | Enable portal user header extraction (see Multi-user) |
+| Head HTML | Extra `<head>` tags (CDN, fonts, CSS) |
+| Code Editor | Monaco with JSX — must define `<App />` |
+
+There is also a config node, **fc-portal-component**, that lets you define reusable React components once and reference them by name from any portal-react node. Referenced components (and their transitive dependencies) are injected at transpile time, so unused ones add nothing to the bundle.
 
 ## Editor features
 
-- **Monaco editor** with full JSX support and `useNodeRed()` type declarations
-- **Tailwind CSS autocompletion** inside `className="..."` strings (~19k utility classes)
-- **JSX tag completion** — type tag name, Tab to expand (open+close and self-closing variants)
+- **Monaco** with full JSX support and `useNodeRed()` type declarations
+- **Tailwind CSS autocompletion** inside `className="..."` (~19k utility classes)
+- **JSX tag completion** — type tag name, Tab to expand
 - **Self-close collapse** — type `/` inside empty `<tag></tag>` to convert to `<tag />`
 - **Component completion** — registry components + any PascalCase word
-- **Portal Assets sidebar** — file manager for static assets (GLB models, textures, fonts, etc.)
+- **Portal Assets sidebar** — file manager for static assets (GLB, textures, fonts…)
 
-## Hook API
+## Multi-user / Multi-tenancy
 
-```jsx
-function App() {
-  const { data, send, user, portalClient } = useNodeRed();
-  // data         = last msg.payload from input wire (reactive)
-  // send(payload, topic?) = emit msg on output wire
-  // user         = portal user object (when Portal Auth enabled), or null
-  // portalClient = unique session/tab ID (assigned by server on WS connect)
-  return <div className="p-4 text-lg">{JSON.stringify(data)}</div>;
-}
-```
+Portal-react has three routing modes — broadcast, user-cast (every tab of one user), and unicast (one specific tab). Everything works without authentication too — user-cast just degrades gracefully when there is no user.
+
+### Identity
 
-## Portal Authentication
+| Identifier | Scope | Persistence | Source |
+|---|---|---|---|
+| `portalClient` | Single WS session (one tab) | Lost on reconnect — server assigns a new UUID | Generated server-side on connect |
+| `userId` / `username` | All sessions of a user | Survives reconnect and new tabs | `x-portal-user-*` headers (when **Portal Auth** is enabled) |
 
-When **Portal Auth** is checked, the node extracts user identity from incoming request headers:
+**Portal Auth header contract** — injected by an upstream reverse proxy such as `aaqu-portal-auth`:
 
 | Header | Field |
 |---|---|
@@ -106,66 +112,61 @@ When **Portal Auth** is checked, the node extracts user identity from incoming r
 | `x-portal-user-role` | `role` |
 | `x-portal-user-groups` | `groups` (JSON array) |
 
-- In the browser, `useNodeRed().user` returns the extracted user object (or `null` if auth is disabled or no headers present).
-- Every WebSocket message includes `msg._client = { portalClient, ...userFields }`. The `portalClient` is always present (unique per tab/session); user fields are added when Portal Auth is enabled.
-- To send a response to a specific tab, keep `msg._client` on the return message (or set `msg._client = { portalClient: "..." }`).
-- To send to all sessions of a user, set `msg._client = { userId: "..." }` (omit `portalClient`).
-- To broadcast to all clients, remove `msg._client` from the message.
+If Portal Auth is disabled or headers are absent, `user` is `null` and user-scoped features are silently skipped — broadcast and per-session features still work.
 
-## Portal Assets
+### Routing modes
 
-Static files (3D models, textures, fonts, etc.) can be uploaded and served from a public endpoint.
+Every inbound `msg` arrives in your flow with `msg._client` already filled in by the server. The flow then decides where the response should go by setting (or clearing) `msg._client` on the outgoing `msg`:
 
-- Open the **Portal Assets** tab in the Node-RED sidebar
-- Upload files via button or drag & drop
-- Organize in folders (create, rename, move between folders)
-- Copy public path with one click — use in JSX: `/fromcubes/public/models/scene.glb`
-- Download and delete files from the context menu
+```javascript
+// BROADCAST — everyone connected to this endpoint
+delete msg._client;
+return msg;
 
-All uploads require Node-RED admin authentication. Files are served publicly at `/fromcubes/public/`.
+// UNICAST — only the tab that sent the original msg (echo)
+// Keep msg._client as-is; it already carries portalClient.
+return msg;
 
-Limits: 100 MB per file, 500 MB total, 1000 files max.
+// UNICAST — a specific tab whose ID you know
+msg._client = { portalClient: "a1b2c3d4-..." };
+return msg;
 
-## Deploy lifecycle
+// USER-CAST — every tab of a specific user (even ones that just opened)
+msg._client = { userId: "alice" };
+return msg;
+```
 
-What happens on each deploy:
+**Anti-spoof guarantee.** On every inbound message the server overwrites `msg._client` from scratch using the socket's own `portalClient` and the user data captured at connect. A browser cannot forge `_client` — whatever it puts there is discarded.
 
-1. Node `close` fires on existing instance
-2. All WebSocket clients receive close code `1001` ("node redeployed")
-3. Browser auto-reconnects with exponential backoff (500ms → 1s → 2s → 4s → 8s cap)
-4. Stale HTTP route and WS upgrade handler removed
-5. New instance transpiles JSX:
-   - Content hash computed
-   - Cache hit → reuse (0ms)
-   - Cache miss → esbuild transpile (~5ms)
-6. New HTTP route and WS handler registered
-7. Reconnecting clients soft-reconnect (no page reload) and receive current `lastPayload`
+**User-cast uses an O(1) index** so a message to `{userId: "alice"}` reaches every tab of Alice with a single lookup, not a scan.
 
-Rapid deploys (user clicking deploy repeatedly) are safe:
-- `isClosing` flag prevents accepting new WS connections during teardown
-- Upgrade handlers are tracked per node ID, old ones removed before new ones register
-- No orphan listeners accumulate on `RED.server`
+### Without a user (anonymous mode)
 
-Transpile errors:
-- Node status shows red "transpile error"
-- Endpoint serves an error page with the error message
-- Fix code, redeploy — cache invalidates because hash changes
+If **Portal Auth** is off (or no proxy headers arrive), everything still works:
 
-## Browser payload
+- `broadcast` and `portalClient` unicast: unchanged
+- `user`-cast: gracefully skipped (no `userId` to target)
+- `useNodeRed().user` is `null`
 
-| Asset | Size (gzip) |
-|---|---|
-| Single JS bundle (React + packages + your code) | ~45 KB React only, grows with packages |
-| Tailwind CSS (server-compiled) | stored per-page, reused if JSX unchanged |
-| WebSocket bridge | <1 KB |
+Same model as dashboard 2 — no auth required to use the node.
 
-Single-pass esbuild bundle — React, npm packages, and your JSX compiled into one IIFE. Tree-shaking removes unused exports. React `alias` ensures packages with React peer deps (e.g. `@react-three/fiber`, `@pixi/react`) share the same React instance — no duplicate React, no hooks errors.
+## Portal Assets
 
-No Babel, no Sucrase, no runtime compiler in the browser.
+Static files (3D models, textures, fonts, etc.) can be uploaded and served from a public endpoint.
+
+- Open the **Portal Assets** tab in the Node-RED sidebar
+- Upload files via button or drag & drop
+- Organize in folders (create, rename, move between folders)
+- Copy public path with one click — use in JSX: `/fromcubes/public/models/scene.glb`
+- Download and delete files from the context menu
+
+All uploads require Node-RED admin authentication. Files are served publicly at `/fromcubes/public/`.
+
+Limits: 100 MB per file, 500 MB total, 1000 files max.
 
 ## Examples
 
-Import `001-shared-components-flow.json` first — it provides shared UI components (Page, Header, Stat, Button, ValueBadge) used by all examples.
+Import `001-shared-components-flow.json` first — it provides shared UI components (Page, Header, Stat, Button, ValueBadge) used by the others.
 
 | Flow | npm packages | Description |
 |---|---|---|
@@ -177,6 +178,18 @@ Import `001-shared-components-flow.json` first — it provides shared UI compone
 | `006-pixi-portal-flow.json` | `pixi.js`, `@pixi/react` | Clickable bunny sprites with PixiJS |
 | `007-webgpu-tsl-flow.json` | `three` | WebGPU renderer + TSL animated shaders |
 
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| Red status "transpile error" + error page on the endpoint | JSX syntax error — fix code, redeploy (cache invalidates automatically) |
+| Red status "legacy endpoint" on deploy | Flow was saved before the `/fromcubes/` prefix became hardcoded. Open the node, set **Sub-path**, redeploy. Automatic migration is disabled to avoid silent URL changes. |
+| Red status "bad sub-path" | Sub-path is empty or violates the rules (no leading `/`, no whitespace, no `..`, segments must start alphanumerically, `public`/`_ws` reserved). |
+| Page loads but `data` stays `undefined` | No input wire has fired yet — broadcast something into the node |
+| `user` is `null` even with Portal Auth on | Upstream proxy is not injecting `x-portal-user-*` headers |
+| New tab shows the previous broadcast value | Expected — that's the recovery frame. Use `useNodeRed({ ignoreRecovery: true })` to opt out |
+| Page reloads on every deploy | Expected for code changes; clients soft-reconnect with exponential backoff |
+
 ## License
 
 Apache-2.0

package/examples/002-sensor-portal-flow.json

@@ -47,7 +47,7 @@
     "type": "portal-react",
     "z": "fc-demo-flow",
     "name": "Sensor Portal",
-    "endpoint": "/fromcubes/sensors",
+    "subPath": "sensors",
     "pageTitle": "Sensors",
     "customHead": "",
     "inputSchema": "[{\"name\":\"temp\",\"type\":\"number\"},{\"name\":\"humidity\",\"type\":\"number\"},{\"name\":\"pressure\",\"type\":\"number\"},{\"name\":\"ts\",\"type\":\"number\"}]",

package/examples/003-chart-portal-flow.json

@@ -59,7 +59,7 @@
     "type": "portal-react",
     "z": "fc-chart-flow",
     "name": "Chart Portal",
-    "endpoint": "/fromcubes/chart",
+    "subPath": "chart",
     "pageTitle": "fromcubes charts",
     "customHead": "",
     "portalAuth": false,

package/examples/004-d3-poland-flow.json

@@ -46,7 +46,7 @@
     "type": "portal-react",
     "z": "fc-d3-flow",
     "name": "Poland Map",
-    "endpoint": "/fromcubes/poland",
+    "subPath": "poland",
     "pageTitle": "Poland Energy Grid",
     "customHead": "",
     "portalAuth": false,

package/examples/005-threejs-portal-flow.json

@@ -58,7 +58,7 @@
     "type": "portal-react",
     "z": "fc-three-flow",
     "name": "3D Portal",
-    "endpoint": "/fromcubes/3d",
+    "subPath": "threejs",
     "pageTitle": "fromcubes 3D",
     "customHead": "",
     "portalAuth": false,

package/examples/006-pixi-portal-flow.json

@@ -58,7 +58,7 @@
     "type": "portal-react",
     "z": "fc-pixi-flow",
     "name": "Pixi Portal",
-    "endpoint": "/fromcubes/pixi",
+    "subPath": "pixi",
     "pageTitle": "fromcubes Pixi",
     "customHead": "",
     "portalAuth": false,

package/examples/007-webgpu-tsl-flow.json

@@ -58,7 +58,7 @@
     "type": "portal-react",
     "z": "fc-webgpu-flow",
     "name": "WebGPU Portal",
-    "endpoint": "/fromcubes/webgpu",
+    "subPath": "webgpu",
     "pageTitle": "fromcubes WebGPU",
     "customHead": "",
     "portalAuth": false,

package/nodes/lib/helpers.js

@@ -50,6 +50,50 @@ function isSafeName(name) {
   );
 }
 
+const SUB_PATH_SEGMENT_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+const SUB_PATH_RESERVED = new Set(["public", "_ws"]);
+
+function validateSubPath(input) {
+  if (typeof input !== "string") {
+    return { ok: false, error: "Sub-path is required" };
+  }
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, error: "Sub-path is required" };
+  }
+  if (/\s/.test(trimmed)) {
+    return { ok: false, error: "Sub-path must not contain whitespace" };
+  }
+  if (trimmed.startsWith("/")) {
+    return { ok: false, error: "Sub-path must not start with /" };
+  }
+  if (trimmed.endsWith("/")) {
+    return { ok: false, error: "Sub-path must not end with /" };
+  }
+  const segments = trimmed.split("/");
+  for (const seg of segments) {
+    if (seg.length === 0) {
+      return { ok: false, error: "Sub-path must not contain empty segments" };
+    }
+    if (seg === "." || seg === "..") {
+      return { ok: false, error: "Path traversal not allowed in sub-path" };
+    }
+    if (SUB_PATH_RESERVED.has(seg.toLowerCase())) {
+      return {
+        ok: false,
+        error: `Sub-path segment "${seg}" is reserved`,
+      };
+    }
+    if (!SUB_PATH_SEGMENT_RE.test(seg)) {
+      return {
+        ok: false,
+        error: `Sub-path segment "${seg}" contains invalid characters`,
+      };
+    }
+  }
+  return { ok: true, value: trimmed };
+}
+
 function extractPortalUser(headers) {
   const user = {};
   if (headers["x-portal-user-id"]) user.userId = headers["x-portal-user-id"];
@@ -90,6 +134,13 @@ function escScript(s) {
 }
 
 module.exports = function (RED) {
+  return createHelpers(RED);
+};
+
+module.exports.validateSubPath = validateSubPath;
+module.exports.isSafeName = isSafeName;
+
+function createHelpers(RED) {
   // Package root — where react/react-dom live (this package's own node_modules)
   const pkgRoot = path.join(__dirname, "../..");
   // userDir — where dynamicModuleList installs user packages
@@ -255,6 +306,7 @@ module.exports = function (RED) {
     extractPortalUser,
     removeRoute,
     isSafeName,
+    validateSubPath,
     esc,
     escScript,
     pkgRoot,
@@ -267,4 +319,4 @@ module.exports = function (RED) {
     deleteCacheFiles,
     isHashInUse,
   };
-};
+}

package/nodes/lib/hooks.js

@@ -0,0 +1,82 @@
+/**
+ * Plugin hook system for @aaqu/fromcubes-portal-react.
+ *
+ * Plugins register with Node-RED via:
+ *   RED.plugins.registerPlugin("my-plugin", {
+ *     type: "fromcubes-portal-react",
+ *     hooks: {
+ *       onIsValidConnection(request)         { return true },
+ *       onCanSendTo(ws, msg)                 { return true },
+ *       onInbound(msg, ws)                   { return msg },
+ *     },
+ *   })
+ *
+ * Semantics:
+ * - allow(name, ...args): every registered hook must return !== false
+ *   (no hooks registered -> allowed). AND logic across plugins.
+ * - transform(name, msg, ...args): runs each hook sequentially, each
+ *   may return a new msg. Returning undefined keeps the current msg.
+ * - Any thrown exception is treated as `false` for allow hooks and
+ *   logged via RED.log.error. Transform hooks log and skip the step.
+ */
+
+const PLUGIN_TYPE = "fromcubes-portal-react";
+
+module.exports = function (RED) {
+  function getHooks(name) {
+    let plugins = [];
+    try {
+      plugins = RED.plugins.getByType(PLUGIN_TYPE) || [];
+    } catch (_) {
+      return [];
+    }
+    const out = [];
+    for (const p of plugins) {
+      const fn = p && p.hooks && p.hooks[name];
+      if (typeof fn === "function") out.push({ fn, id: p.id || p.name || "?" });
+    }
+    return out;
+  }
+
+  function allow(name, ...args) {
+    const hooks = getHooks(name);
+    if (hooks.length === 0) return true;
+    for (const h of hooks) {
+      let result;
+      try {
+        result = h.fn(...args);
+      } catch (e) {
+        RED.log.error(
+          `[portal-react] hook ${name} (${h.id}) threw: ${e.message}`,
+        );
+        return false;
+      }
+      if (result === false) return false;
+    }
+    return true;
+  }
+
+  function transform(name, msg, ...args) {
+    const hooks = getHooks(name);
+    let current = msg;
+    for (const h of hooks) {
+      try {
+        const next = h.fn(current, ...args);
+        if (next !== undefined) current = next;
+      } catch (e) {
+        RED.log.error(
+          `[portal-react] hook ${name} (${h.id}) threw: ${e.message}`,
+        );
+      }
+    }
+    return current;
+  }
+
+  function hasHook(name) {
+    return getHooks(name).length > 0;
+  }
+
+  return { allow, transform, hasHook, PLUGIN_TYPE };
+};
+
+module.exports.PLUGIN_TYPE = PLUGIN_TYPE;

package/nodes/lib/page-builder.js

@@ -43,6 +43,7 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
           _ws: null,
           _listeners: new Set(),
           _lastData: null,
+          _ignoreRecovery: false,
           _retries: 0,
           _wasConnected: false,
           _version: null,
@@ -108,6 +109,14 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
                   this._lastData = m.payload;
                   this._listeners.forEach(fn => fn(m.payload));
                 }
+                if (m.type === 'recovery') {
+                  // Cached last broadcast at connect time. Seeded into
+                  // _lastData unless the page opted out via
+                  // useNodeRed({ ignoreRecovery: true }).
+                  if (this._ignoreRecovery) return;
+                  this._lastData = m.payload;
+                  this._listeners.forEach(fn => fn(m.payload));
+                }
               } catch (err) { console.error('WS parse', err); }
             };
 

package/nodes/lib/router.js

@@ -0,0 +1,56 @@
+/**
+ * Pure routing function for portal-react WS outbound messages.
+ *
+ * Split out from portal-react.js so it can be unit-tested without a full
+ * Node-RED runtime.
+ *
+ * Routing modes, in priority order:
+ *   1. msg._client.portalClient → unicast to that one session
+ *   2. msg._client.userId        → user-cast (O(1) via userIndex)
+ *   3. msg._client.username      → user-cast fallback (O(N) scan)
+ *   4. otherwise                 → broadcast
+ *
+ * Returns a shallow summary { mode, delivered } for observability/tests.
+ * The caller is responsible for any side-effects keyed off the mode
+ * (e.g. caching the last broadcast payload for new-client recovery).
+ */
+
+function route(msg, ctx) {
+  const { clients, userIndex, sendTo } = ctx;
+  const target = msg && msg._client;
+  const frame = JSON.stringify({ type: "data", payload: msg.payload });
+
+  let delivered = 0;
+
+  if (target && target.portalClient) {
+    if (sendTo(clients.get(target.portalClient), frame, msg)) delivered++;
+    return { mode: "unicast", delivered };
+  }
+
+  if (target && target.userId) {
+    const set = userIndex.get(target.userId);
+    if (set) {
+      set.forEach((ws) => {
+        if (sendTo(ws, frame, msg)) delivered++;
+      });
+    }
+    return { mode: "user-cast", delivered };
+  }
+
+  if (target && target.username) {
+    clients.forEach((ws) => {
+      if (ws._portalUser && ws._portalUser.username === target.username) {
+        if (sendTo(ws, frame, msg)) delivered++;
+      }
+    });
+    return { mode: "user-cast", delivered };
+  }
+
+  // Broadcast.
+  clients.forEach((ws) => {
+    if (sendTo(ws, frame, msg)) delivered++;
+  });
+  return { mode: "broadcast", delivered };
+}
+
+module.exports = { route };

package/nodes/portal-react.html

@@ -56,7 +56,7 @@
       var libContent = [
         "declare var React: any;",
         "declare var ReactDOM: any;",
-        "declare function useNodeRed(): { data: any; send: (payload: any, topic?: string) => void; user: { userId?: string; userName?: string; username?: string; email?: string; role?: string; groups?: any[] } | null; portalClient: string | null };",
+        "declare function useNodeRed(opts?: { ignoreRecovery?: boolean }): { data: any; send: (payload: any, topic?: string) => void; user: { userId?: string; userName?: string; username?: string; email?: string; role?: string; groups?: any[] } | null; portalClient: string | null };",
       ].join("\n");
       console.log(PREFIX, "addExtraLib globals.d.ts");
       jsDef.addExtraLib(libContent, "file:///globals.d.ts");
@@ -813,10 +813,22 @@
         <input type="text" id="node-input-name" placeholder="My Portal" />
       </div>
       <div class="form-row">
-        <label for="node-input-endpoint"
-          ><i class="fa fa-globe"></i> Endpoint</label
+        <label for="node-input-subPath"
+          ><i class="fa fa-globe"></i> Sub-path</label
         >
-        <input type="text" id="node-input-endpoint" placeholder="/fromcubes" />
+        <div style="display:inline-flex;align-items:stretch;width:70%;">
+          <span
+            style="display:inline-flex;align-items:center;padding:0 8px;background:var(--red-ui-secondary-background,#f3f3f3);border:1px solid var(--red-ui-form-input-border-color,#ccc);border-right:none;border-radius:4px 0 0 4px;color:var(--red-ui-secondary-text-color,#888);font-family:monospace;user-select:none;"
+            >/fromcubes/</span
+          >
+          <input
+            type="text"
+            id="node-input-subPath"
+            placeholder="sensors"
+            style="flex:1;border-radius:0 4px 4px 0;"
+          />
+        </div>
+        <input type="hidden" id="node-input-endpoint" />
         <div
           style="font-size:11px;opacity:.5;margin-top:2px;margin-left:105px;"
           id="fc-url-hint"
@@ -929,7 +941,27 @@
       color: "#61dafb",
       defaults: {
         name: { value: "" },
-        endpoint: { value: "/fromcubes", required: true },
+        subPath: {
+          value: "",
+          required: true,
+          validate: function (v) {
+            if (typeof v !== "string") return false;
+            var t = v.trim();
+            if (t.length === 0) return false;
+            if (/\s/.test(t)) return false;
+            if (t.charAt(0) === "/" || t.charAt(t.length - 1) === "/") return false;
+            var segs = t.split("/");
+            for (var i = 0; i < segs.length; i++) {
+              var s = segs[i];
+              if (!s || s === "." || s === "..") return false;
+              var lower = s.toLowerCase();
+              if (lower === "public" || lower === "_ws") return false;
+              if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(s)) return false;
+            }
+            return true;
+          },
+        },
+        endpoint: { value: "" },
         pageTitle: { value: "fromcubes" },
         componentCode: { value: STARTER },
         customHead: { value: "" },
@@ -942,7 +974,7 @@
       icon: "font-awesome/fa-desktop",
       paletteLabel: "fromcubes portal",
       label: function () {
-        return this.name || this.endpoint || "portal react";
+        return this.name || ("/fromcubes/" + (this.subPath || "?"));
       },
 
       oneditprepare: function () {
@@ -984,13 +1016,45 @@
         fcTabs.addTab({ id: "fc-tab-head", label: "Head HTML" });
         fcTabs.activateTab("fc-tab-jsx");
 
+        // Legacy endpoint detection + convenience pre-fill
+        if (node.endpoint && typeof node.endpoint === "string") {
+          var legacy = node.endpoint;
+          var prefix = "/fromcubes/";
+          if (legacy.indexOf(prefix) === 0) {
+            if (!node.subPath) {
+              $("#node-input-subPath").val(legacy.slice(prefix.length));
+            }
+          } else if (legacy !== "" && legacy !== "/fromcubes") {
+            $("#fc-url-hint")
+              .css("color", "#c00")
+              .text(
+                "Legacy endpoint detected: '" +
+                  legacy +
+                  "'. Set a Sub-path and redeploy.",
+              );
+          }
+        }
+
         // URL hint
         function updateHint() {
-          var ep = $("#node-input-endpoint").val() || "/fromcubes";
+          var sp = ($("#node-input-subPath").val() || "").trim();
           var root = (RED.settings.httpNodeRoot || "/").replace(/\/$/, "");
-          $("#fc-url-hint").text("Page served at: http://<host>:1880" + root + ep);
+          if (sp) {
+            $("#fc-url-hint")
+              .css("color", "")
+              .text(
+                "Page served at: http://<host>:1880" +
+                  root +
+                  "/fromcubes/" +
+                  sp,
+              );
+          } else if (!node.endpoint || node.endpoint.indexOf("/fromcubes/") === 0) {
+            $("#fc-url-hint")
+              .css("color", "")
+              .text("Sub-path required (will be served under /fromcubes/<sub-path>)");
+          }
         }
-        $("#node-input-endpoint").on("input", updateHint);
+        $("#node-input-subPath").on("input", updateHint);
         updateHint();
 
         // Modules editableList (like function node's libs)
@@ -1117,9 +1181,9 @@
         });
 
         $("#fc-btn-preview").on("click", function () {
-          var ep = $("#node-input-endpoint").val();
+          var sp = ($("#node-input-subPath").val() || "").trim();
           var root = (RED.settings.httpNodeRoot || "/").replace(/\/$/, "");
-          if (ep) window.open(root + ep, "_blank");
+          if (sp) window.open(root + "/fromcubes/" + sp, "_blank");
         });
 
         $("#fc-btn-components").on("click", function () {
@@ -1239,6 +1303,11 @@
       oneditsave: function () {
         console.log("[FC-Monaco] PORTAL oneditsave");
 
+        // Clear legacy endpoint field + normalize subPath
+        $("#node-input-endpoint").val("");
+        this.endpoint = "";
+        this.subPath = ($("#node-input-subPath").val() || "").trim();
+
         // Collect libs from editableList
         var libs = [];
         var items = $("#node-input-libs-container").editableList("items");

package/nodes/portal-react.js

@@ -85,6 +85,7 @@ module.exports = function (RED) {
     extractPortalUser,
     removeRoute,
     isSafeName,
+    validateSubPath,
     userDir,
     readCachedJS,
     writeCachedJS,
@@ -94,6 +95,14 @@ module.exports = function (RED) {
     isHashInUse,
   } = helpers;
   const { buildPage, buildErrorPage } = require("./lib/page-builder");
+  const hooks = require("./lib/hooks")(RED);
+  const router = require("./lib/router");
+
+  // Per-process cache of the last broadcast payload per endpoint.
+  // Lets a freshly-connected client see the most recent broadcast value
+  // (similar to dashboard2's lastMsg recovery). Sent as a distinct
+  // `recovery` WS frame so React can opt out via useNodeRed({ ignoreRecovery: true }).
+  const lastBroadcastCache = new Map();
 
   // ── Canvas node: shared component ─────────────────────────────
 
@@ -153,7 +162,33 @@ module.exports = function (RED) {
     const nodeId = node.id;
 
     // Config
-    const endpoint = (config.endpoint || "/fromcubes").replace(/\/+$/, "");
+    const subPathResult = validateSubPath(config.subPath);
+    const legacyEndpoint =
+      typeof config.endpoint === "string" && config.endpoint.trim().length > 0
+        ? config.endpoint.trim()
+        : null;
+
+    if (!subPathResult.ok) {
+      // No valid subPath. If there's a legacy endpoint, hard-fail with a
+      // migration message; otherwise fail on the sub-path error.
+      if (legacyEndpoint) {
+        node.error(
+          `Legacy 'endpoint' field detected ("${legacyEndpoint}"). ` +
+            "Open the node, set a Sub-path (served under /fromcubes/<sub-path>), and redeploy.",
+        );
+        node.status({ fill: "red", shape: "ring", text: "legacy endpoint" });
+      } else {
+        node.error("Invalid sub-path: " + subPathResult.error);
+        node.status({ fill: "red", shape: "ring", text: "bad sub-path" });
+      }
+      node.on("close", function (_removed, done) {
+        if (done) done();
+      });
+      return;
+    }
+    const subPath = subPathResult.value;
+    const endpoint = "/fromcubes/" + subPath;
+
     const componentCode = config.componentCode || "";
     const pageTitle = config.pageTitle || "Portal";
     const customHead = config.customHead || "";
@@ -180,8 +215,8 @@ module.exports = function (RED) {
     endpointOwners[endpoint] = nodeId;
 
     // State
-    const clients = new Map(); // portalId → ws
-    let lastPayload = null;
+    const clients = new Map(); // portalClient → ws
+    const userIndex = new Map(); // userId → Set<ws>   (O(1) user-cast)
     let wsServer = null;
     let isClosing = false;
     let lastJsxHash = null;
@@ -293,11 +328,14 @@ module.exports = function (RED) {
           "",
           "// ── useNodeRed hook ──",
           [
-            "function useNodeRed() {",
+            "function useNodeRed(opts) {",
+            "  // opts.ignoreRecovery = true → ignore the cached last-broadcast",
+            "  // frame the server sends on connect; data stays undefined until",
+            "  // a fresh broadcast arrives. Latched once globally — strictest",
+            "  // call wins (any caller asking to ignore disables recovery for all).",
+            "  if (opts && opts.ignoreRecovery) window.__NR._ignoreRecovery = true;",
             "  const [data, setData] = React.useState(window.__NR._lastData);",
-            "  React.useEffect(() => {",
-            "    return window.__NR.subscribe(setData);",
-            "  }, []);",
+            "  React.useEffect(() => window.__NR.subscribe(setData), []);",
             "  const send = React.useCallback((payload, topic) => {",
             "    window.__NR.send(payload, topic);",
             "  }, []);",
@@ -566,6 +604,12 @@ module.exports = function (RED) {
             pathname = request.url;
           }
           if (pathname === wsPath) {
+            // Plugin hook: plugins may reject the connection before upgrade.
+            // Default (no plugins) = allowed, matches dashboard behavior.
+            if (!hooks.allow("onIsValidConnection", request)) {
+              try { socket.destroy(); } catch (_) {}
+              return;
+            }
             wsServer.handleUpgrade(request, socket, head, (ws) => {
               wsServer.emit("connection", ws, request);
             });
@@ -586,13 +630,20 @@ module.exports = function (RED) {
             ws._portalUser = extractPortalUser(request.headers);
           }
           clients.set(portalClient, ws);
-          updateStatus();
 
-          // Push current state to new client
-          if (lastPayload !== null) {
-            wsSend(ws, { type: "data", payload: lastPayload });
+          // Index by userId for O(1) user-cast routing
+          const userId = ws._portalUser && ws._portalUser.userId;
+          if (userId) {
+            let set = userIndex.get(userId);
+            if (!set) {
+              set = new Set();
+              userIndex.set(userId, set);
+            }
+            set.add(ws);
           }
 
+          updateStatus();
+
           // Send content version for deploy-reload detection
           const contentHash = pageState[endpoint]?.contentHash || "";
           wsSend(ws, { type: "version", hash: contentHash });
@@ -600,35 +651,55 @@ module.exports = function (RED) {
           // Send assigned portalClient to browser
           wsSend(ws, { type: "hello", portalClient });
 
+          // 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
+          // useNodeRed({ ignoreRecovery: true }).
+          if (lastBroadcastCache.has(endpoint)) {
+            wsSend(ws, { type: "recovery", payload: lastBroadcastCache.get(endpoint) });
+          }
+
           ws.on("message", (raw) => {
             try {
               const msg = JSON.parse(raw.toString());
               if (msg.type === "output") {
-                const out = {
+                let out = {
                   payload: msg.payload,
                   topic: msg.topic || "",
                 };
+                // Server-side identity injection — the client cannot forge
+                // _client because we build it from ws state, not from the
+                // inbound frame.
                 const client = { portalClient: ws._portalClient };
                 if (portalAuth && ws._portalUser) {
                   Object.assign(client, ws._portalUser);
                 }
                 out._client = client;
-                node.send(out);
+                // Transform hook — plugins may mutate / drop the msg.
+                // A hook returning null signals "drop this message".
+                out = hooks.transform("onInbound", out, ws);
+                if (out) node.send(out);
+                return;
               }
             } catch (e) {
               node.warn("Bad WS message: " + e.message);
             }
           });
 
-          ws.on("close", () => {
+          const detach = () => {
             clients.delete(portalClient);
+            if (userId) {
+              const set = userIndex.get(userId);
+              if (set) {
+                set.delete(ws);
+                if (set.size === 0) userIndex.delete(userId);
+              }
+            }
             updateStatus();
-          });
+          };
 
-          ws.on("error", () => {
-            clients.delete(portalClient);
-            updateStatus();
-          });
+          ws.on("close", detach);
+          ws.on("error", detach);
         });
       } catch (e) {
         node.error("WebSocket setup failed: " + e.message);
@@ -636,37 +707,27 @@ module.exports = function (RED) {
 
       // ── Input handler ─────────────────────────────────────────
 
-      node.on("input", (msg, send, done) => {
-        const target = msg._client;
-        const frame = JSON.stringify({ type: "data", payload: msg.payload });
-
-        if (target && target.portalClient) {
-          // Target specific client by portalClient
-          const ws = clients.get(target.portalClient);
-          if (ws && ws.readyState === 1) ws.send(frame);
-        } else if (target && (target.userId || target.username)) {
-          // Target all sessions of a specific user
-          const matchId = target.userId;
-          const matchName = target.username;
-          clients.forEach((ws) => {
-            if (ws.readyState !== 1) return;
-            const u = ws._portalUser;
-            if (!u) return;
-            if (
-              (matchId && u.userId === matchId) ||
-              (matchName && u.username === matchName)
-            ) {
-              ws.send(frame);
-            }
-          });
-        } else {
-          // Broadcast to all (default)
-          lastPayload = msg.payload;
-          clients.forEach((ws) => {
-            if (ws.readyState === 1) ws.send(frame);
-          });
+      // 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.
+      function sendTo(ws, frame, msg) {
+        if (!ws || ws.readyState !== 1) return false;
+        if (!hooks.allow("onCanSendTo", ws, msg)) return false;
+        try {
+          ws.send(frame);
+          return true;
+        } catch (_) {
+          return false;
         }
+      }
 
+      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);
+        }
         updateStatus();
         if (done) done();
       });
@@ -706,6 +767,16 @@ module.exports = function (RED) {
           delete endpointOwners[endpoint];
         }
 
+        // 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);
+        }
+
+        // Clear the userIndex — WS clients are already closed above, but
+        // the Map itself should not outlive the node instance.
+        userIndex.clear();
+
         // Clean up route only when node is fully removed (not redeployed)
         if (removed) {
           // Delete disk cache if no other endpoint uses this hash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaqu/fromcubes-portal-react",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.17",
   "description": "Fromcubes Portal - React for Node-RED with Tailwind CSS and auto complete",
   "keywords": [
     "node-red",
@@ -26,17 +26,17 @@
     "node": ">=18"
   },
   "dependencies": {
-    "esbuild": "^0.27.4",
+    "esbuild": "^0.28.0",
     "monaco-editor": "^0.55.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "tailwindcss": "^4.2.1"
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "tailwindcss": "^4.2.2"
   },
   "devDependencies": {
-    "node-red": "next",
-    "prettier": "^3.8.1",
+    "node-red": "5.0.0-beta.4",
+    "prettier": "^3.8.2",
     "supertest": "^7.2.2",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.4"
   },
   "scripts": {
     "start": "node-red",