@aaqu/fromcubes-react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Mazur Albert Fromcubes
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,406 @@
-# Temporary Holding Version
+# @aaqu/fromcubes-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/%40aaqu%2Ffromcubes-react.svg)](https://www.npmjs.com/package/@aaqu/fromcubes-react)
+[![npm downloads](https://img.shields.io/npm/dm/%40aaqu%2Ffromcubes-react.svg)](https://www.npmjs.com/package/@aaqu/fromcubes-react)
+[![node](https://img.shields.io/node/v/%40aaqu%2Ffromcubes-react.svg)](https://www.npmjs.com/package/@aaqu/fromcubes-react)
+[![Node-RED](https://img.shields.io/badge/Node--RED-%E2%89%A5%204.0-8f0000.svg)](https://nodered.org)
+[![license](https://img.shields.io/npm/l/%40aaqu%2Ffromcubes-react.svg)](./LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-join%20chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/KYzsfKkYxX)
+
+**📖 Documentation — step-by-step guide with screenshots:** [aaqu.github.io/fromcubes-modules](https://aaqu.github.io/fromcubes-modules/) — install → import → edit JSX → live dashboard, on one example.
+
+[![Documentation walkthrough](https://aaqu.github.io/fromcubes-modules/img/docs-scroll.gif)](https://aaqu.github.io/fromcubes-modules/)
+
+> **⚠️ Alpha Module** — This project is in early development. Expect breaking changes. Test on a clean Node-RED instance.
+
+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.
+
+For internals, plugin authoring, and the deploy pipeline see [README-DEV.md](./README-DEV.md).
+
+**💬 Questions, feedback, showcase?** Join the [fromcubes Discord](https://discord.gg/KYzsfKkYxX).
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L4L01UOFRG)
+
+## Prerequisites
+
+- **Node-RED ≥ 4.0** — declared in `package.json`'s `node-red.version` and
+  enforced by the editor's Palette Manager.
+- **Node.js ≥ 18.5** — Node-RED 4.x's effective minimum.
+- **npm** — only required when you use the `libs` config field to install
+  user packages at deploy time. The portal itself does not need `npm`
+  available at runtime.
+- A WebSocket-capable reverse proxy or direct connection — the portal
+  upgrades `/fromcubes/<sub-path>/_ws`. If you front Node-RED with nginx /
+  Traefik / Caddy, enable `Upgrade: websocket` headers on that path.
+
+## Install
+
+```bash
+cd ~/.node-red
+npm install @aaqu/fromcubes-react
+# restart Node-RED
+```
+
+That's it. No build step. Any npm packages you list in the node config (e.g. `d3, three`) are installed automatically on deploy.
+
+### Add-ons
+
+Three parts ship as their own packages, and for now installing the core
+installs them too:
+
+| Package | What it adds |
+|---|---|
+| [`@aaqu/fromcubes-tailwind`](https://www.npmjs.com/package/@aaqu/fromcubes-tailwind) | Tailwind CSS 4 for portals, plus class completion in the editor |
+| [`@aaqu/fromcubes-auth-headers`](https://www.npmjs.com/package/@aaqu/fromcubes-auth-headers) | Users from `x-portal-user-*` headers set by a reverse proxy (Portal Auth) |
+| [`@aaqu/fromcubes-assets`](https://www.npmjs.com/package/@aaqu/fromcubes-assets) | Static files for portals, managed from a sidebar tab |
+
+Each is a Node-RED plugin built on the same API anyone can use — see
+[Plugins](#plugins-identity-providers-and-css-engines). Coming from
+`@aaqu/fromcubes-portal-react`? Uninstall it first, then install this
+package: both register the same nodes. Your flows keep working unchanged.
+
+## 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:
+
+```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
+  authRequired,  // true when this session is anonymous on an authenticated-only portal
+} = useNodeRed();
+```
+
+### Initial data on connect
+
+The server does **not** cache payloads — a freshly-loaded page has `data === null` until the flow pushes the next message. For periodic streams that's at most one interval of blankness. For event-driven or per-user data, request the initial state from the component:
+
+```jsx
+const { data, send } = useNodeRed();
+useEffect(() => { send({}, "init"); }, []);
+```
+
+In the flow, catch `topic === "init"`, look up the state (per-user via `msg._client.userId` if needed) and reply — `msg._client` is already set on the inbound message, so the response returns as a unicast to exactly that tab.
+
+## 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) |
+| Authenticated-only delivery | Untargeted msgs (no `msg._client`) go only to sessions with portal identity headers; anonymous sessions get an `auth_required` frame on connect (see Multi-user). Off by default. |
+| Show WS status | Small "fromcubes • connected/disconnected" badge in the page's bottom-right corner (off by default) |
+| Head HTML | Extra trusted-author `<head>` tags (CDN, fonts, CSS, scripts). Runs in the public portal page. |
+| 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.
+
+For shared **non-component** code (helpers, custom hooks, constants), use **fc-portal-utility** — a sibling config node. Unlike component nodes (which export exactly one symbol via an IIFE wrapper), a utility node is injected raw at top level so it can declare any number of `function` / `const` / `let` / `class` symbols. Selective inclusion: a utility node lands in a portal's bundle only when the portal's JSX or any of its referenced library components mentions at least one of the symbols declared in that utility.
+
+```jsx
+// fc-portal-utility, Module name = mathHelpers
+const PI2 = Math.PI * 2;
+function clamp(n, min, max) { return Math.max(min, Math.min(max, n)); }
+function useDebounce(value, ms = 300) {
+  const [v, setV] = React.useState(value);
+  React.useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}
+
+// portal-react, JSX tab
+function App() {
+  const { data } = useNodeRed();
+  const slow = useDebounce(data?.value);
+  return <div>{clamp(slow ?? 0, 0, 100)}</div>;
+}
+```
+
+## Editor features
+
+- **Monaco** with full JSX support and `useNodeRed()` type declarations
+- **Tailwind CSS autocompletion** inside `className="..."` (~19k utility classes). Classes must be complete literals in a string — dynamic `bg-${tone}-500` generates no CSS (use a map of full classes). Arbitrary values incl. `w-[calc(100%-2rem)]`, `grid-cols-[repeat(2,1fr)]`, `mt-0!` and `@md:flex` are supported.
+- **JSX tag completion** — type tag name, Tab to expand
+- **Self-close collapse** — type `/` inside empty `<tag></tag>` to convert to `<tag />`
+- **Ctrl+D / Cmd+D** — duplicate the current line or selection (in every Monaco editor of the package)
+- **Ctrl+/ / Cmd+/** — JSX-aware comment toggle. Style follows the first selected line (VS Code behavior): selecting a whole `return ( … )` block gives plain `//` on every line, while lines between live JSX tags are wrapped in `{/* … */}` (a plain `//` there is literal text — JSX renders it on the page)
+- **Component completion** — registry components + any PascalCase word
+- **Utility-symbol completion** — top-level identifiers from any `fc-portal-utility` node, suggested in JS context
+- **Components / Utilities dialogs** — buttons in the JSX tab; Components inserts `<Tag></Tag>`, Utilities expands to the symbols declared in each node and inserts the bare identifier on click
+- **Portal Assets sidebar** — file manager for static assets (GLB, textures, fonts…)
+
+## Multi-user / Multi-tenancy
+
+Portal-react has four routing modes — broadcast, auth-cast (every authenticated session), user-cast (every tab of one user), and unicast (one specific tab). Everything works without authentication too — user-cast and auth-cast just degrade gracefully when there is no user.
+
+### Identity
+
+| Identifier | Scope | Persistence | Source |
+|---|---|---|---|
+| `portalClient` | Single WS session (one tab) | Lost on reconnect — server assigns a new UUID | Generated server-side on connect |
+| `userId` / `login` | All sessions of a user | Survives reconnect and new tabs | `x-portal-user-*` headers (when **Portal Auth** is enabled) |
+
+**Portal Auth header contract** — injected by an upstream reverse proxy (the [fromcubes-portal](https://github.com/Aaqu/fromcubes-portal) platform sets them from Traefik forward-auth). Every value is percent-encoded UTF-8 (`%C5%81ukasz` → `Łukasz`); the same field names appear in `useNodeRed().user` and `msg._client`:
+
+| Header | Field |
+|---|---|
+| `x-portal-user-id` | `userId` — required; without it the session is anonymous |
+| `x-portal-user-login` | `login` |
+| `x-portal-user-display-name` | `displayName` |
+| `x-portal-user-email` | `email` |
+| `x-portal-user-role` | `role` (single value) |
+| `x-portal-user-groups` | `groups` — comma-separated, each element encoded on its own (`a%2Cb` is one group `a,b`); always an array, `[]` when absent |
+
+A value with a malformed escape is skipped (in `groups`, only that element). Without `x-portal-user-id` the session is anonymous and `user` is `null`, whatever other headers arrive. The pre-contract `x-portal-user-username` / `x-portal-user-name` headers are ignored.
+
+**The proxy must strip all six headers from the client's request** before injecting its own. The package trusts them as they arrive; one header let through is enough to impersonate any user.
+
+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.
+
+### Routing modes
+
+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`:
+
+```javascript
+// BROADCAST — everyone connected to this endpoint
+delete msg._client;
+return msg;
+
+// UNICAST — only the tab that sent the original msg (echo)
+// Keep msg._client as-is; it already carries portalClient.
+return msg;
+
+// UNICAST — a specific tab whose ID you know
+msg._client = { portalClient: "a1b2c3d4-..." };
+return msg;
+
+// USER-CAST — every tab of a specific user (even ones that just opened)
+msg._client = { userId: "alice" };
+return msg;
+
+// AUTH-CAST — every session that arrived with x-portal-user-* identity;
+// anonymous sessions (no proxy headers) are skipped
+msg._client = { authenticated: true };
+return msg;
+```
+
+**Auth-cast vs broadcast.** Broadcast reaches every connected client, including anonymous ones. Auth-cast reaches only sessions that arrived with `x-portal-user-*` identity headers. Use auth-cast for data that any logged-in user may see; use broadcast only for data that is genuinely public. Nothing is cached server-side — each mode delivers to the clients connected at send time.
+
+### Authenticated-only delivery (fail-safe default)
+
+With the **Authenticated-only delivery** checkbox enabled on the node, an untargeted `msg` (no `msg._client`) is delivered as an **auth-cast** instead of a broadcast — a forgotten `_client` then narrows delivery to logged-in sessions rather than leaking to anonymous ones. A true broadcast stays available explicitly:
+
+```javascript
+msg._client = { authenticated: false };  // deliberate broadcast, anonymous included
+return msg;
+```
+
+Anonymous sessions are told up front: right after `hello` the server sends a single `auth_required` frame (once per connection — never per skipped message, so unauthenticated clients learn nothing about traffic volume or timing). The hook exposes it so the page can render a login hint instead of staying silently empty:
+
+```jsx
+const { data, authRequired } = useNodeRed();
+if (authRequired) return <p className="p-4 text-zinc-500">Log in to see this data.</p>;
+```
+
+**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.
+
+**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.
+
+### Without a user (anonymous mode)
+
+If **Portal Auth** is off (or no proxy headers arrive), everything still works:
+
+- `broadcast` and `portalClient` unicast: unchanged
+- `user`-cast: gracefully skipped (no `userId` to target)
+- `auth`-cast: delivers to nobody (no session has identity headers)
+- `useNodeRed().user` is `null`
+
+Same model as dashboard 2 — no auth required to use the node.
+
+## Plugins: identity providers and CSS engines
+
+Who the user is and how CSS is generated are both pluggable. The defaults,
+`headers` (the contract above) and `tailwind`, are themselves plugins shipped
+in this package and use exactly this API. A separate npm package can register its own, e.g. for a different
+auth proxy or a different CSS tool:
+
+```js
+// package.json: "node-red": { "plugins": { "my-providers": "plugin.js" } }
+module.exports = function (RED) {
+  RED.plugins.registerPlugin("my-sso", {
+    type: "fromcubes-identity",
+    apiVersion: 1,
+    async resolveUser(req) {          // HTTP request or WS upgrade request
+      const claims = await verify(req.headers.authorization);
+      return claims ? { userId: claims.sub, login: claims.preferred_username, groups: claims.groups } : null;
+    },
+  });
+  RED.plugins.registerPlugin("my-css", {
+    type: "fromcubes-css",
+    apiVersion: 1,
+    async generate(source) {          // the portal's full source, components included
+      return { css: await compileMyCss(source) };
+    },
+    editor: {                         // optional: className="…" completion
+      classes() { return ["card", "btn", "btn-primary"]; },
+    },
+  });
+};
+```
+
+Installing a plugin does not activate it. Choose one per kind in the editor,
+**Menu → Settings → Fromcubes**: every installed provider is listed with the
+package it comes from, and exactly one is selected. The choice is saved in
+`<userDir>/fromcubes/providers.json` and applies at once — a new CSS engine
+rebuilds every portal; a new identity provider asks for confirmation, then
+reloads every open portal tab so page and connection both use it.
+
+An administrator can pin either choice in `settings.js`; the editor then shows
+it locked:
+
+```js
+portalReact: {
+  identityProvider: "my-sso",   // default "headers"; "none" = everyone anonymous
+  cssEngine: "my-css",          // default "tailwind"; "none" serves no stylesheet
+},
+```
+
+- `resolveUser` returns a user or `null`. Only the known fields
+  (`userId`, `login`, `displayName`, `email`, `role`, `groups`) are kept; a
+  throw, a rejection or 5 s without an answer means anonymous.
+- `generate` returns `{ css }`. A failure shows the yellow `css-fail` status
+  and the page is served unstyled.
+- `editor.classes()` (optional, may be async) feeds the class completion in
+  every code editor; it is asked once per installed plugin. Without it the
+  engine just gets no completion. Strings only, no whitespace, ≤ 200 chars,
+  at most 50 000.
+- An unknown provider name is logged once; for identity every session is then
+  anonymous. The settings pane flags a selected provider whose package is gone.
+- Optional `label: "…"` on the plugin is shown next to its id in the settings
+  pane.
+- `require("@aaqu/fromcubes-react/api")` gives the type names and
+  `API_VERSION`, plus `createAdminSecurity(RED)` — the permission, CSRF and
+  rate-limit gates the core puts on its own admin routes — for a plugin that
+  adds routes. Declare `@aaqu/fromcubes-react` as a peer dependency. The
+  three add-ons above are complete examples.
+
+## Portal Assets
+
+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
+
+Available via **Menu → Import → Examples → @aaqu/fromcubes-react**.
+Each flow includes a comment node with what to expect and the URL to open.
+
+Import **Shared Components** first — it provides the UI building blocks (Page, Header, Stat, Button, ValueBadge) referenced by the others.
+
+| Example | npm packages | Description |
+|---|---|---|
+| **Shared Components** | — | Reusable components: Page, Header, Stat, Button, ValueBadge |
+| **Sensor Portal** | — | Sensor gauge with live WebSocket data |
+| **Live Chart** | `chart.js/auto` | Live updating Chart.js charts |
+| **D3 Poland Map** | `d3` | Interactive SVG map of Poland (simulated data) |
+| **Three.js Scene** | `three`, `@react-three/fiber`, `@react-three/drei` | 3D scene with Three.js |
+| **PixiJS Sprites** | `pixi.js`, `@pixi/react` | Clickable bunny sprites with PixiJS |
+| **WebGPU Shader** | `three` | WebGPU renderer + TSL animated shaders |
+| **Utility Hooks** | — | `fc-portal-utility` demo: `useDebounce` custom hook + `clamp` helper |
+
+## 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). |
+| Yellow status "css-fail" | Tailwind generation failed (usually an invalid class in JSX). Page still loads but unstyled. Fix the class, redeploy — the status clears on the next successful build. |
+| Code editor stays blank / `fromcubes-react/vs/loader.js` 404s | Monaco is served live from the package's own `node_modules` at `/fromcubes-react/vs` (no postinstall copy step). The 404 means `RED.httpAdmin` is mounted under a non-root `httpAdminRoot` the editor didn't account for, or `monaco-editor` failed to install. Reinstall the package and hard-refresh the editor (`Cmd/Ctrl-Shift-R`). |
+| `npm install @aaqu/fromcubes-react` ends with `EACCES` | The Node-RED `userDir/node_modules` install path is not writable by the user running Node-RED. Re-run `npm install` from a shell with the right ownership. |
+| Browser request `/fromcubes/css/<hash>.css` returns 404 | The portal's deploy hasn't produced a CSS bundle yet — open the editor, redeploy. If the URL is bookmarked from before a deploy, the hash is stale; reload the portal page itself. With a custom `httpNodeRoot`, prepend it to this path. |
+| WebSocket reconnects in an endless loop | Reverse-proxy is not forwarding `Upgrade: websocket` on `/fromcubes/<sub-path>/_ws`. Check the proxy config — nginx needs `proxy_set_header Upgrade $http_upgrade`, Traefik needs the `websocket` middleware. |
+| `libs` packages fail to install on deploy | The user-installed npm packages declared in **Libs** install via Node-RED's `dynamicModuleList` mechanism, which needs network access from `userDir` and a writable `node_modules`. Behind a corporate proxy set `npm config set proxy …` for the Node-RED user. |
+| Page loads but `data` stays `null` | Nothing has been pushed since the page connected — payloads are not cached server-side. Push periodically, or request initial state from the component (`send({}, "init")` → flow replies) |
+| `user` is `null` even with Portal Auth on | Upstream proxy is not injecting `x-portal-user-id` (required — the other headers alone count as anonymous), or sends a malformed percent-escape in it |
+| Page reloads on every deploy | Expected for code changes; clients soft-reconnect with exponential backoff |
+
+## Architecture: source AND sink
+
+The Node-RED guidelines suggest a node should "sit at the beginning, middle
+or end of a flow — not all at once". `portal-react` intentionally violates
+this: every node is both a **sink** (`msg → render`) and a **source** (UI
+event → outbound `msg`). Trade-offs:
+
+- **Pro**: one wire per portal is conceptually simpler — the same node owns
+  the page lifecycle, its WebSocket, and the routing rules.
+- **Con**: flow-error tracking only follows the `input → output` path.
+  Errors originating in the browser (e.g. a runtime exception inside a UI
+  handler) cross the WebSocket as a source-event and are **not** routed to
+  a Catch node on the same tab — they surface as a red node status and a
+  log line. This matches the Node-RED guidance for source nodes: "produces
+  messages in response to external events".
+
+If you need explicit Catch-node visibility for UI-originated errors, wire
+the portal's output through a Switch / Catch chain — a UI event landing on
+`msg.payload` is then a regular wire-level message that Catch can observe.
+
+## Security
+
+This module is meant to run behind a trusted Node-RED instance, ideally
+behind a reverse proxy. Highlights:
+
+- Admin write endpoints require the `Node-RED-API-Version` header (CSRF
+  protection) and a `portal-react.write` permission when `adminAuth` is
+  configured.
+- Token-bucket rate-limit (default 60 burst / 1 req/s steady) on every
+  write endpoint, tunable via `RED.settings.portalReact.rateLimit`.
+- JSON bodies capped by Node-RED's own `apiMaxLength` (settings.js, default
+  5 MB), 100 MB asset-upload cap, 500 MB / 1000 files total
+  assets quota, 1 MB WebSocket frame cap.
+- `x-portal-user-*` identity headers are trusted unconditionally — production
+  deployments **must** terminate auth at a reverse proxy that strips all six
+  inbound identity headers before injecting verified ones, and Node-RED must
+  not be reachable except through that proxy.
+
+## License
+
+Apache-2.0