@aaqu/fromcubes-react 0.2.0 → 0.2.2

package/nodes/portal-react.html

@@ -1,12 +1,27 @@
 <!-- ============================================================
      Portal Code Workspace — sidebar tab + full-screen editor overlay.
-     Served from nodes/editor/ via the /fromcubes-react/editor admin route.
+     Served from nodes/editor/ via the /fromcubes-react/<version>/editor admin route.
      ============================================================ -->
-<link rel="stylesheet" href="fromcubes-react/editor/workspace.css" />
-<script type="text/javascript" src="fromcubes-react/editor/file-tree.js"></script>
-<script type="text/javascript" src="fromcubes-react/editor/workspace.js"></script>
-<script type="text/javascript" src="fromcubes-react/editor/format.js"></script>
-<script type="text/javascript" src="fromcubes-react/editor/provider-settings.js"></script>
+<script type="text/javascript">
+  // Loaded from the versioned asset path the runtime exports (ASSET_BASE in
+  // lib/admin-api.js), so no cache — browser, CDN or proxy — can serve this
+  // template an older file, or a 404 it remembered. Execution order follows
+  // insertion order (async = false); every script waits for what it needs.
+  (function () {
+    const base = (RED.settings && RED.settings.portalReactAssetBase) || "fromcubes-react/";
+    window.__fcAssetBase = base;
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = base + "editor/workspace.css";
+    document.head.appendChild(link);
+    ["file-tree.js", "class-completion.js", "workspace.js", "format.js", "provider-settings.js"].forEach(function (file) {
+      const s = document.createElement("script");
+      s.src = base + "editor/" + file;
+      s.async = false;
+      document.head.appendChild(s);
+    });
+  })();
+</script>
 
 <!-- ============================================================
      Shared: Monaco loader (used by both node editors)
@@ -29,12 +44,13 @@
       quickSuggestions: { strings: true },
     };
 
-    // className="…" completion list, from the CSS engine in force (Settings →
-    // Fromcubes). Refetched every time a dialog or the React Editor opens and
+    // className="…" completion data, from the CSS engine in force (Settings →
+    // Fromcubes): classes with their swatch colours and modifiers, and the
+    // variants. Refetched every time a dialog or the React Editor opens and
     // after the engine changes — the engine can change while the editor is
     // open, so "load once" would keep offering the old engine's classes.
     window.__fcCssClasses = null;
-    window.__fcCssClassSet = null;
+    window.__fcCssData = null;
     window.__fcCssEngine = null;
     let cssClassesPending = false;
     window.__fcRefreshCssClasses = function () {
@@ -42,9 +58,26 @@
       cssClassesPending = true;
       $.getJSON("fromcubes-react/css-classes", function (data) {
         if (!data || !Array.isArray(data.classes)) return;
+        const prev = window.__fcCssData;
         window.__fcCssEngine = data.engine;
         window.__fcCssClasses = data.classes;
-        window.__fcCssClassSet = null;
+        window.__fcCssData = {
+          engine: data.engine,
+          classes: data.classes,
+          colors: data.colors || [],
+          modifiers: data.modifiers || [],
+          classModifiers: data.classModifiers || [],
+          variants: data.variants || [],
+          describe: data.describe === true,
+          canonical: data.canonical === true,
+        };
+        // What the engine said about classes stays true while it is the same
+        // engine; a refetch on every dialog open must not ask again.
+        if (prev && prev.engine === data.engine && prev._described) {
+          Object.defineProperty(window.__fcCssData, "_described", { value: prev._described });
+          Object.defineProperty(window.__fcCssData, "_canonical", { value: prev._canonical });
+        }
+        if (window.__fcRevalidateCss) window.__fcRevalidateCss();
       })
         .fail(function (xhr) {
           console.error("[FC-Monaco] css-classes FAILED:", xhr.status, xhr.statusText);
@@ -102,102 +135,398 @@
       console.log(PREFIX, "addExtraLib globals.d.ts");
       jsDef.addExtraLib(libContent, "file:///globals.d.ts");
 
-      // className completion provider — classes from the CSS engine in force
-      // Triggers in: className="...", className={`...`}, and any string literal
-      // containing at least one known TW class (e.g. "bg-red-500 text-white")
-      console.log(PREFIX, "registering Tailwind completion provider");
-      monaco.languages.registerCompletionItemProvider("javascript", {
-        triggerCharacters: ['"', "'", "`", " "],
-        provideCompletionItems: function (model, position) {
-          const line = model.getLineContent(position.lineNumber);
-          const before = line.substring(0, position.column - 1);
+      // className completion, hover and CSS preview — Tailwind CSS
+      // IntelliSense's logic (editor/class-completion.js) over the data of the
+      // CSS engine in force. Inside className="…" / className={…} it offers
+      // what IntelliSense offers: variants first (`hover:` reopens the list),
+      // then every class in the engine's order with colour swatches, and after
+      // `/` the class's modifiers. Strings elsewhere complete too once they
+      // hold a known class — this editor's addition.
+      console.log(PREFIX, "registering CSS class completion provider");
+      const cssKinds = {
+        variant: monaco.languages.CompletionItemKind.Module,
+        color: monaco.languages.CompletionItemKind.Color,
+        constant: monaco.languages.CompletionItemKind.Constant,
+      };
+
+      function cssData() {
+        const cc = window.__fcClassCompletion;
+        const data = window.__fcCssData;
+        if (!cc || !data || !data.classes.length) return null;
+        return cc.prepare(data);
+      }
 
-          // 1) className="..." or className={`...`}
-          const isClassName =
-            before.match(/className\s*=\s*["'][^"']*$/) ||
-            before.match(/className\s*=\s*\{`[^`]*$/);
+      // What the engine says about each candidate (CSS, summary, colour,
+      // conflict rules), or null — one request per batch, answers kept for
+      // the data's lifetime. Fast: hovers and the detail pane wait for it.
+      function describeCss(data, candidates) {
+        return askCssEngine(data, data.describe, "css-describe", data._described, candidates, 5000);
+      }
 
-          // 2) Any open string literal: "..., '..., or `...
-          const inString = !isClassName && before.match(/["'`][^"'`]*$/);
+      // Canonical spellings, for the diagnostic only: the engine may take its
+      // time (the Tailwind add-on's worker builds an index on its first
+      // answer), so nothing else waits for these.
+      function canonicalCss(data, candidates) {
+        return askCssEngine(data, data.canonical, "css-canonical", data._canonical, candidates, 30000);
+      }
 
-          if (!isClassName && !inString) return { suggestions: [] };
+      const cssInflight = new WeakMap(); // answer cache → candidate → pending request
 
-          // Extract text inside the string
-          const raw = (isClassName || inString)[0];
-          let inside;
-          if (isClassName) {
-            inside = raw.replace(/^className\s*=\s*(?:\{`|["'])/, "");
-          } else {
-            inside = raw.substring(1); // skip opening quote
+      function askCssEngine(data, supported, route, cache, candidates, timeout) {
+        const cc = window.__fcClassCompletion;
+        const nulls = candidates.map(function () {
+          return null;
+        });
+        if (!supported) return Promise.resolve(nulls);
+        // Classes already asked about and not answered yet are waited for,
+        // not asked again — typing while the first answer is slow would
+        // otherwise queue the same classes over and over.
+        let inflight = cssInflight.get(cache);
+        if (!inflight) cssInflight.set(cache, (inflight = new Map()));
+        const waiting = [];
+        const missing = candidates.filter(function (c, i) {
+          if (cache.has(c) || candidates.indexOf(c) !== i) return false;
+          if (inflight.has(c)) {
+            waiting.push(inflight.get(c));
+            return false;
           }
-          inside = inside.replace(/\$\{[^}]*\}/g, " ");
-          const parts = inside.split(/\s+/);
-          const word = parts[parts.length - 1] || "";
-
-          // For non-className strings, only activate if at least one existing
-          // token in the string looks like a TW class (avoid noise in random strings)
-          if (!isClassName && parts.length > 0) {
-            const classes = window.__fcCssClasses || [];
-            let twSet = window.__fcCssClassSet;
-            if (!twSet && classes.length) {
-              twSet = new Set(classes);
-              window.__fcCssClassSet = twSet;
-              console.log(PREFIX, "CSS: built class lookup Set, size=" + twSet.size);
-            }
-            if (twSet) {
-              let hasTwToken = false;
-              for (let p = 0; p < parts.length; p++) {
-                if (parts[p] && twSet.has(parts[p])) {
-                  hasTwToken = true;
-                  break;
-                }
-              }
-              // If typing the very first word, accept if it looks like a prefix
-              if (!hasTwToken && parts.length === 1 && word.length >= 2) {
-                for (let j = 0; j < classes.length; j++) {
-                  if (classes[j].indexOf(word) === 0) {
-                    hasTwToken = true;
-                    break;
-                  }
+          return true;
+        });
+        const batches = [];
+        for (let i = 0; i < missing.length; i += cc.MAX_DESCRIBE) {
+          batches.push(missing.slice(i, i + cc.MAX_DESCRIBE));
+        }
+        const asked = batches.map(function (batch) {
+          const request = new Promise(function (resolve) {
+            $.ajax({
+              url: "fromcubes-react/" + route,
+              data: { c: batch.join("\n") },
+              dataType: "json",
+              timeout: timeout,
+            })
+              .done(function (res) {
+                if (res && Array.isArray(res.results) && res.engine === data.engine) {
+                  batch.forEach(function (c, i) {
+                    cache.set(c, res.results[i] || null);
+                  });
                 }
-              }
-              if (!hasTwToken) return { suggestions: [] };
-            }
-          }
+              })
+              .fail(function (xhr) {
+                console.error(PREFIX, route + " FAILED:", xhr.status, xhr.statusText);
+              })
+              .always(function () {
+                batch.forEach(function (c) {
+                  inflight.delete(c);
+                });
+                resolve();
+              });
+          });
+          batch.forEach(function (c) {
+            inflight.set(c, request);
+          });
+          return request;
+        });
+        return Promise.all(asked.concat(waiting)).then(function () {
+          return candidates.map(function (c) {
+            return cache.has(c) ? cache.get(c) : null;
+          });
+        });
+      }
 
-          const range = {
-            startLineNumber: position.lineNumber,
+      // A variant the data does not list by name (`group-hover/item`,
+      // `data-[open]`) is valid when the engine compiles it — IntelliSense's
+      // test, `<part>:[color:red]`.
+      function isValidVariant(data, part) {
+        if (!window.__fcClassCompletion.mayBeVariant(data, part)) return false;
+        return describeCss(data, [part + ":[color:red]"]).then(function (r) {
+          return !!r[0];
+        });
+      }
+
+      // Text the class-list scan needs: up to SEARCH_RANGE before the cursor,
+      // and the cursor's line split at the cursor.
+      function cssScanText(model, position) {
+        const cc = window.__fcClassCompletion;
+        const offset = model.getOffsetAt(position);
+        const from = model.getPositionAt(Math.max(0, offset - cc.SEARCH_RANGE));
+        const line = model.getLineContent(position.lineNumber);
+        return {
+          before: model.getValueInRange({
+            startLineNumber: from.lineNumber,
+            startColumn: from.column,
             endLineNumber: position.lineNumber,
-            startColumn: position.column - word.length,
             endColumn: position.column,
-          };
+          }),
+          lineBefore: line.substring(0, position.column - 1),
+          lineAfter: line.substring(position.column - 1),
+        };
+      }
 
-          const classes = window.__fcCssClasses || [];
-          const suggestions = [];
-          for (let i = 0; i < classes.length; i++) {
-            const cls = classes[i];
-            if (!word.length || cls.indexOf(word) === 0) {
-              suggestions.push({
-                label: cls,
-                kind: monaco.languages.CompletionItemKind.Value,
-                insertText: cls,
-                range: range,
-                sortText: cls.padStart(60, "0"),
+      function cssFence(css) {
+        return { value: "```css\n" + css + "\n```" };
+      }
+
+      monaco.languages.registerCompletionItemProvider("javascript", {
+        triggerCharacters: window.__fcClassCompletion
+          ? window.__fcClassCompletion.TRIGGER_CHARACTERS
+          : ['"', "'", "`", " ", ".", "(", "[", "]", "!", "/", "-", ":"],
+        provideCompletionItems: function (model, position, context) {
+          const data = cssData();
+          if (!data) return { suggestions: [] };
+          const cc = window.__fcClassCompletion;
+          const text = cssScanText(model, position);
+          const at = cc.classListAt(data, text.before, text.lineBefore);
+          if (!at) return { suggestions: [] };
+          const kinds = monaco.languages.CompletionTriggerKind;
+          const ctx = {
+            triggerKind:
+              context.triggerKind === kinds.Invoke
+                ? "invoke"
+                : context.triggerKind === kinds.TriggerCharacter
+                  ? "character"
+                  : "incomplete",
+            triggerCharacter: context.triggerCharacter,
+          };
+          return cc
+            .completionsFromClassList(data, at.classList, ctx, function (part) {
+              return isValidVariant(data, part);
+            })
+            .then(function (list) {
+              if (!list.modifiers) return list;
+              return describeCss(
+                data,
+                list.items.map(function (item) {
+                  return item.label;
+                }),
+              ).then(function (described) {
+                cc.applyModifierColors(list.items, described);
+                return list;
+              });
+            })
+            .then(function (list) {
+              const range = {
+                startLineNumber: position.lineNumber,
+                endLineNumber: position.lineNumber,
+                startColumn: position.column + list.range.start,
+                endColumn: position.column + list.range.end,
+              };
+              const owner = { variants: list.variants, important: list.important };
+              const suggestions = list.items.map(function (item) {
+                const s = {
+                  label: item.label,
+                  kind: cssKinds[item.kind],
+                  insertText: item.insertText || item.label,
+                  sortText: item.sortText,
+                  range: range,
+                };
+                if (item.filterText) s.filterText = item.filterText;
+                if (item.detail) s.detail = item.detail;
+                if (item.documentation) s.documentation = item.documentation;
+                if (item.snippet) {
+                  s.insertTextRules = monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet;
+                }
+                if (item.retrigger) s.command = { id: "editor.action.triggerSuggest", title: "" };
+                if (item.kind !== "variant") s.fcClassOwner = owner;
+                return s;
               });
+              console.log(
+                PREFIX,
+                "CSS class completion: ctx=" +
+                  (at.attribute ? "attribute" : "string") +
+                  " items=" +
+                  suggestions.length,
+              );
+              return { suggestions: suggestions };
+            });
+        },
+        // The detail pane: the declarations on one line, and the CSS the
+        // class generates under the variants typed before it.
+        resolveCompletionItem: function (item) {
+          const data = cssData();
+          if (!data || !item.fcClassOwner || (item.detail && item.documentation)) return item;
+          const className = item.fcClassOwner.important ? "!" + item.label : item.label;
+          const full = item.fcClassOwner.variants.concat([className]).join(":");
+          return describeCss(data, [full, className]).then(function (r) {
+            const whole = r[0];
+            const base = r[1];
+            if (!whole) return item;
+            if (!item.detail) {
+              item.detail = /^\d+ rules$/.test(whole.detail || "") ? whole.detail : (base || whole).detail || undefined;
             }
-          }
-          console.log(
-            PREFIX,
-            "CSS class completion: ctx=" +
-              (isClassName ? "className" : "string") +
-              " word='" +
-              word +
-              "', matched=" +
-              suggestions.length +
-              "/" +
-              classes.length,
-          );
-          return { suggestions: suggestions };
+            if (!item.documentation && whole.documentation) item.documentation = cssFence(whole.documentation);
+            return item;
+          });
+        },
+      });
+
+      monaco.languages.registerHoverProvider("javascript", {
+        provideHover: function (model, position) {
+          const data = cssData();
+          if (!data || !data.describe) return null;
+          const text = cssScanText(model, position);
+          const hit = window.__fcClassCompletion.classNameAt(data, text.before, text.lineBefore, text.lineAfter);
+          if (!hit) return null;
+          return describeCss(data, [hit.className]).then(function (r) {
+            if (!r[0] || !r[0].hover) return null;
+            return {
+              range: {
+                startLineNumber: position.lineNumber,
+                endLineNumber: position.lineNumber,
+                startColumn: position.column + hit.start,
+                endColumn: position.column + hit.end,
+              },
+              contents: [cssFence(r[0].hover)],
+            };
+          });
+        },
+      });
+
+      // Diagnostics, quick fixes and colour squares — IntelliSense's
+      // cssConflict and suggestCanonicalClasses warnings and its document
+      // colours, over every class attribute of every javascript model (node
+      // dialogs and the React Editor alike), rechecked as the code changes.
+      function cssRange(model, start, end) {
+        const a = model.getPositionAt(start);
+        const b = model.getPositionAt(end);
+        return { startLineNumber: a.lineNumber, startColumn: a.column, endLineNumber: b.lineNumber, endColumn: b.column };
+      }
+
+      function cssClassLists(model) {
+        const cc = window.__fcClassCompletion;
+        return cc.findClassListsInText(cc.jsWithoutComments(model.getValue()));
+      }
+
+      const CSS_MARKER_OWNER = "tailwindcss";
+      const cssDiagnostics = new WeakMap(); // model → diagnostics, for their quick fixes
+      const cssTimers = new WeakMap();
+
+      function validateCss(model) {
+        if (model.isDisposed() || model.getLanguageId() !== "javascript") return;
+        const data = cssData();
+        if (!data || !data.describe) {
+          cssDiagnostics.delete(model);
+          monaco.editor.setModelMarkers(model, CSS_MARKER_OWNER, []);
+          return;
+        }
+        const cc = window.__fcClassCompletion;
+        const version = model.getVersionId();
+        const lists = cssClassLists(model);
+        const names = cc.uniqueClassNames(lists);
+        // Conflicts as soon as the classes are described; canonical
+        // suggestions join when the engine has them — a slow first answer
+        // never holds back the rest.
+        describeCss(data, names).then(function () {
+          publishCssMarkers(model, version, data, lists);
+          canonicalCss(data, names).then(function () {
+            publishCssMarkers(model, version, data, lists);
+          });
+        });
+      }
+
+      function publishCssMarkers(model, version, data, lists) {
+        if (model.isDisposed() || model.getVersionId() !== version || cssData() !== data) return;
+        const diagnostics = window.__fcClassCompletion.diagnose(lists, data._described, data._canonical);
+        cssDiagnostics.set(model, diagnostics);
+        monaco.editor.setModelMarkers(
+          model,
+          CSS_MARKER_OWNER,
+          diagnostics.map(function (d) {
+            return Object.assign(cssRange(model, d.start, d.end), {
+              severity: d.severity === "error" ? monaco.MarkerSeverity.Error : monaco.MarkerSeverity.Warning,
+              message: d.message,
+              source: "tailwindcss",
+              code: d.code,
+              relatedInformation: d.related.map(function (r) {
+                return Object.assign(cssRange(model, r.start, r.end), { resource: model.uri, message: r.message });
+              }),
+            });
+          }),
+        );
+      }
+
+      function scheduleCssValidation(model) {
+        clearTimeout(cssTimers.get(model));
+        cssTimers.set(
+          model,
+          setTimeout(function () {
+            validateCss(model);
+          }, 400),
+        );
+      }
+
+      function watchCssModel(model) {
+        const changed = model.onDidChangeContent(function () {
+          scheduleCssValidation(model);
+        });
+        const language = model.onDidChangeLanguage(function () {
+          scheduleCssValidation(model);
+        });
+        model.onWillDispose(function () {
+          changed.dispose();
+          language.dispose();
+          clearTimeout(cssTimers.get(model));
+        });
+        scheduleCssValidation(model);
+      }
+
+      monaco.editor.getModels().forEach(watchCssModel);
+      monaco.editor.onDidCreateModel(watchCssModel);
+      // New engine data (a dialog opened, the engine switched): check again.
+      window.__fcRevalidateCss = function () {
+        monaco.editor.getModels().forEach(scheduleCssValidation);
+      };
+
+      monaco.languages.registerCodeActionProvider("javascript", {
+        provideCodeActions: function (model, _range, context) {
+          const diagnostics = cssDiagnostics.get(model) || [];
+          const actions = [];
+          context.markers.forEach(function (marker) {
+            if (marker.source !== "tailwindcss") return;
+            const start = model.getOffsetAt({ lineNumber: marker.startLineNumber, column: marker.startColumn });
+            const end = model.getOffsetAt({ lineNumber: marker.endLineNumber, column: marker.endColumn });
+            diagnostics.forEach(function (d) {
+              if (d.start !== start || d.end !== end || d.code !== marker.code || d.message !== marker.message) return;
+              d.fixes.forEach(function (fix) {
+                actions.push({
+                  title: fix.title,
+                  kind: "quickfix",
+                  diagnostics: [marker],
+                  edit: {
+                    edits: [
+                      {
+                        resource: model.uri,
+                        versionId: model.getVersionId(),
+                        textEdit: { range: cssRange(model, fix.start, fix.end), text: fix.text },
+                      },
+                    ],
+                  },
+                });
+              });
+            });
+          });
+          return { actions: actions, dispose: function () {} };
+        },
+      });
+
+      monaco.languages.registerColorProvider("javascript", {
+        provideDocumentColors: function (model) {
+          const data = cssData();
+          if (!data) return [];
+          const cc = window.__fcClassCompletion;
+          const lists = cssClassLists(model);
+          return describeCss(data, cc.classesNeedingColor(data, lists)).then(function () {
+            if (model.isDisposed()) return [];
+            return cc.documentColors(data, lists, data._described).map(function (c) {
+              return { color: c.color, range: cssRange(model, c.start, c.end) };
+            });
+          });
+        },
+        // Only an arbitrary colour (`bg-[#f00]`) takes one back from the picker.
+        provideColorPresentations: function (model, info) {
+          const className = model.getValueInRange(info.range);
+          return window.__fcClassCompletion.colorPresentations(className, info.color).map(function (label) {
+            return { label: label, textEdit: { range: info.range, text: label } };
+          });
         },
       });
 
@@ -1041,10 +1370,11 @@
         return;
       }
       const s = document.createElement("script");
-      s.src = "fromcubes-react/vs/loader.js";
+      const base = window.__fcAssetBase || "fromcubes-react/";
+      s.src = base + "vs/loader.js";
       s.onload = function () {
         console.log(PREFIX, "loader.js loaded, configuring require paths");
-        require.config({ paths: { vs: "fromcubes-react/vs" } });
+        require.config({ paths: { vs: base + "vs" } });
         require(["vs/editor/editor.main"], function () {
           console.log(PREFIX, "editor.main loaded");
           ensureJsxSetup();
@@ -1312,32 +1642,26 @@
 </script>
 
 <script type="text/html" data-help-name="fc-portal-component">
+  <p>A React component every portal can use as a tag.</p>
+
+  <h3>Details</h3>
   <p>
-    Defines a shared JSX component available to all
-    <strong>portal-react</strong> nodes.
+    Write the component in <b>JSX Code</b> and give its name in
+    <b>JSX Tag</b>. After deploy, any <b>React Portal</b> uses it as
+    <code>&lt;Name /&gt;</code>, without imports. Components can use each
+    other and <code>useNodeRed()</code>.
   </p>
+  <pre>function Badge({ label }) {
+  return &lt;span className="badge"&gt;{label}&lt;/span&gt;;
+}</pre>
+
   <h3>Properties</h3>
   <dl>
     <dt>JSX Tag</dt>
-    <dd>
-      The name used as a JSX tag in portal-react pages (e.g.
-      <code>&lt;MyComponent /&gt;</code>).
-    </dd>
-    <dt>Input fields</dt>
-    <dd>Comma-separated list of expected input props (documentation only).</dd>
-    <dt>Output fields</dt>
-    <dd>Comma-separated list of output props (documentation only).</dd>
+    <dd>The component's name, starting with a capital letter (<code>Badge</code>).</dd>
     <dt>JSX Code</dt>
-    <dd>
-      The component function. Use <code>useNodeRed()</code> for data binding.
-    </dd>
+    <dd>The component function.</dd>
   </dl>
-  <h3>Usage</h3>
-  <p>
-    Place this node on the canvas, set the JSX tag name and code, then deploy.
-    All <strong>portal-react</strong> nodes will automatically have access to
-    this component.
-  </p>
 </script>
 
 <!-- ============================================================
@@ -1558,57 +1882,28 @@
 </script>
 
 <script type="text/html" data-help-name="fc-portal-utility">
+  <p>Shared JavaScript — helpers, hooks, constants — for every portal.</p>
+
+  <h3>Details</h3>
   <p>
-    Defines shared <strong>helpers</strong>, <strong>custom hooks</strong> and
-    <strong>constants</strong> available to all <strong>portal-react</strong>
-    nodes. Unlike <code>fc-portal-component</code>, the code is injected raw at
-    top level (no IIFE wrapper) — a single utility node may declare many symbols.
+    Declare any number of functions, constants or classes in <b>Code</b>.
+    Portals and components use them by name, without imports. A portal only
+    includes this node if it uses something from it.
   </p>
+  <pre>function clamp(n, min, max) {
+  return Math.max(min, Math.min(max, n));
+}</pre>
+
   <h3>Properties</h3>
   <dl>
     <dt>Module name</dt>
     <dd>
-      Identifier for this utility node. Shares a namespace with
-      <code>fc-portal-component</code> names — must be unique across all
-      components and utilities.
+      A name for this node; it must not repeat a component's or another
+      utility's name.
     </dd>
     <dt>Code</dt>
-    <dd>
-      Top-level JavaScript: <code>const</code>, <code>let</code>,
-      <code>function</code>, <code>class</code> declarations. <code>import</code>
-      statements at the top are auto-hoisted into the bundle.
-    </dd>
+    <dd>Top-level declarations; <code>import</code> lines are allowed.</dd>
   </dl>
-  <h3>Selective inclusion</h3>
-  <p>
-    A utility node is bundled into a portal only when the portal's JSX (or any
-    of its referenced library components) mentions at least one of the symbols
-    declared in the utility. Unused utility nodes are skipped.
-  </p>
-  <p>
-    Group related symbols in one node — referencing any one symbol pulls in the
-    whole node's code. Split unrelated helpers across multiple nodes for finer
-    granularity.
-  </p>
-  <h3>Example</h3>
-  <pre>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;
-}</pre>
-  <p>
-    Then in any <strong>portal-react</strong> node:
-  </p>
-  <pre>function App() {
-  const { data } = useNodeRed();
-  const slow = useDebounce(data?.value);
-  return &lt;div&gt;{clamp(slow ?? 0, 0, 100)}&lt;/div&gt;;
-}</pre>
 </script>
 
 <!-- ============================================================
@@ -2415,125 +2710,86 @@ function useDebounce(value, ms = 300) {
      Help
      ============================================================ -->
 <script type="text/html" data-help-name="portal-react">
-  <h3>Quick Reference</h3>
-  <ul>
-    <li><code>useNodeRed()</code> &rarr; <code>{ data, send, user, portalClient }</code></li>
-    <li>Components from <code>fc-portal-component</code> nodes are auto-imported</li>
-    <li>Must export <code>&lt;App /&gt;</code></li>
-    <li>JSX is transpiled server-side at deploy</li>
-  </ul>
-
   <p>
-    Renders a React 19 application on a configurable HTTP endpoint with live
-    WebSocket data binding. JSX is transpiled <strong>server-side at deploy
-    time</strong> using esbuild — browsers receive pre-compiled JS with zero
-    runtime compilation. Tailwind CSS 4 utility classes are generated
-    server-side and served as static CSS.
+    A React page served at <code>/fromcubes/&lt;sub-path&gt;</code>, kept live
+    with data from the flow.
   </p>
 
   <h3>Inputs</h3>
-  <p>
-    <code>msg.payload</code> is pushed via WebSocket. Set <code>msg._client</code>
-    to target specific clients, or omit it to broadcast to all.
-  </p>
-  <pre>
-const { data, send, user, portalClient } = useNodeRed();
-// data         = last msg.payload (reactive)
-// send(payload, topic?) — emit msg on output wire
-// user         = portal auth data or null
-// portalClient = unique session/tab ID (assigned by server)</pre
-  >
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">any</span></dt>
+    <dd>Sent to the open pages; read it with <code>useNodeRed().data</code>.</dd>
+    <dt class="optional">_client <span class="property-type">object</span></dt>
+    <dd>
+      Who gets it: <code>{ portalClient }</code> one browser tab,
+      <code>{ userId }</code> every tab of one user,
+      <code>{ authenticated: true }</code> every logged-in visitor.
+      Without it, every open page.
+    </dd>
+  </dl>
 
   <h3>Outputs</h3>
-  <p>
-    <code>send(payload, topic?)</code> emits a <code>msg</code> on the node's
-    output wire via WebSocket.
-  </p>
-
-  <h3>npm Packages</h3>
-  <p>
-    Add npm packages in the <strong>Modules</strong> list (e.g.
-    <code>chart.js/auto@^4.4.0</code>, <code>d3</code>, <code>three</code>).
-    Node-RED auto-installs them at deploy time. All packages are bundled with
-    React into a single vendor IIFE via esbuild, cached by hash of installed
-    versions. Use them in JSX via standard imports.
-  </p>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">any</span></dt>
+    <dd>What the page passed to <code>send(payload, topic)</code>.</dd>
+    <dt>_client <span class="property-type">object</span></dt>
+    <dd>The tab and user it came from — send a reply back with it.</dd>
+  </dl>
 
-  <h3>Deploy behavior</h3>
-  <ul>
-    <li>
-      Each deploy re-transpiles JSX via esbuild and rebuilds Tailwind CSS
-      (both cached by content hash — unchanged code is instant)
-    </li>
-    <li>
-      Vendor bundle (React + npm packages) rebuilt only when package versions
-      change
-    </li>
-    <li>
-      Active WebSocket clients receive close code 1001 and auto-reconnect
-      (exponential backoff)
-    </li>
-    <li>
-      Stale HTTP routes and WS handlers are cleaned up before new ones register
-    </li>
-    <li>
-      Transpile errors show in node status and as an error page on the endpoint
-    </li>
-  </ul>
-
-  <h3>Shared Components</h3>
+  <h3>Details</h3>
   <p>
-    Components defined in <strong>fc-portal-component</strong> nodes on the
-    canvas are auto-injected into every portal-react page. Use them as JSX tags
-    by their component name — no imports needed.
+    Write a <code>function App()</code> in the <b>JSX</b> tab. It is compiled
+    when you deploy, so the browser gets ready-made JavaScript.
   </p>
-
-  <h3>Portal Auth</h3>
+  <pre>function App() {
+  const { data, send } = useNodeRed();
+  return &lt;button onClick={() =&gt; send("hi")}&gt;{data}&lt;/button&gt;;
+}</pre>
   <p>
-    When enabled in the Auth tab, reads <code>X-Portal-*</code> headers set by
-    a reverse proxy (e.g. Nginx) and exposes user data:
+    <code>useNodeRed()</code> gives <code>data</code> (the last payload,
+    <code>null</code> until one arrives), <code>send</code>, <code>user</code>
+    (the visitor, or <code>null</code>) and <code>portalClient</code> (this
+    tab's id).
   </p>
-  <ul>
-    <li><code>useNodeRed()</code> returns <code>{ data, send, user, portalClient }</code></li>
-    <li>
-      All WebSocket messages include <code>msg._client</code> with
-      <code>{ portalClient, ...userFields }</code>
-    </li>
-    <li>
-      To target a specific tab: keep <code>msg._client</code> (or set
-      <code>msg._client = { portalClient: "..." }</code>)
-    </li>
-    <li>
-      To target all tabs of a user: set
-      <code>msg._client = { userId: "..." }</code> (no portalClient)
-    </li>
-    <li>
-      To target every authenticated session (skips anonymous):
-      <code>msg._client = { authenticated: true }</code>
-    </li>
-    <li>
-      To broadcast to all: remove <code>msg._client</code>. With
-      <b>Authenticated-only delivery</b> enabled this defaults to the
-      authenticated sessions instead; force a true broadcast with
-      <code>msg._client = { authenticated: false }</code>
-    </li>
-  </ul>
-
-  <h3>Custom Head HTML</h3>
   <p>
-    Inject CDN links, fonts, or extra stylesheets into
-    <code>&lt;head&gt;</code>. This is raw trusted-author HTML; scripts and
-    event handlers run in the public portal page. Example:
+    <b>React Component</b> and <b>React Utility</b> nodes can be used here by
+    name, without imports.
   </p>
-  <pre>
-&lt;link href="https://fonts.googleapis.com/css2?family=Inter&amp;display=swap" rel="stylesheet"&gt;</pre
-  >
 
-  <h3>WebSocket Status</h3>
+  <h3>Properties</h3>
+  <dl>
+    <dt>Sub-path</dt>
+    <dd>Where the page lives: <code>sensors</code> → <code>/fromcubes/sensors</code>.</dd>
+    <dt>Title</dt>
+    <dd>The browser tab's title.</dd>
+    <dt>Modules</dt>
+    <dd>
+      npm packages to use in the code (<code>chart.js/auto</code>,
+      <code>d3</code>, <code>three</code>); installed on deploy, then
+      <code>import</code> them.
+    </dd>
+    <dt>Enable Portal Auth headers</dt>
+    <dd>
+      Identify visitors with the identity provider chosen in
+      <b>Settings → Fromcubes</b>. Off: everyone is anonymous.
+    </dd>
+    <dt>Authenticated-only delivery</dt>
+    <dd>
+      Messages without <code>_client</code> go to logged-in visitors only;
+      <code>_client = { authenticated: false }</code> still reaches everyone.
+    </dd>
+    <dt>Show WebSocket status indicator</dt>
+    <dd>A small connected/disconnected badge in the page's corner.</dd>
+    <dt>Head HTML</dt>
+    <dd>Extra tags for the page's <code>&lt;head&gt;</code>, such as fonts or stylesheets.</dd>
+  </dl>
+
+  <h3>Styling</h3>
   <p>
-    Optional <em>fromcubes</em> badge in the bottom-right corner showing
-    connection state. Enable via the <strong>Show WebSocket status
-    indicator</strong> checkbox (off by default).
+    The page's stylesheet comes from the CSS engine chosen in
+    <b>Settings → Fromcubes</b>. Install <code>@aaqu/fromcubes-tailwind</code>
+    to style with Tailwind CSS classes; without a CSS engine the page has no
+    generated stylesheet.
   </p>
 </script>