@zerotal/flow 1.7.5 → 1.8.0

package/CHANGELOG.md

@@ -11,6 +11,35 @@ change.
 
 ## [Unreleased]
 
+## [1.8.0] — 2026-08-24
+
+### Added
+
+- **`static interactive = false` — the first render mode.** Every component until now was
+  maximally interactive: server-rendered, dehydrated into a snapshot, tracked by the client,
+  reachable over a socket. Right for a counter, wasteful for a nav rail. A static component is
+  rendered in full by its parent and nothing else — no `onDehydrate`, no snapshot, no state
+  script, no entry in the client registry, and no `data-flow-root` (which would freeze it at
+  its first render, since its only route to an update is the parent re-rendering it). It takes
+  no place in `_childIds` and does not shift its interactive siblings' ids. `lazy`, `defer` and
+  `stream` throw rather than being ignored: each waits for the client to ask for the real
+  render, and a static child never registers to do the asking. Opt-in — nothing existing
+  changes.
+
+- **`this.isInteractive`** reports the mode from inside a component. A new public member, so
+  the name is no longer available to applications; it is on the documented reserved list.
+
+### Changed
+
+- **A page with nothing interactive on it opens no socket.** Every page connected at boot,
+  unconditionally — so a marketing page, a docs article or a rendered report held a WebSocket
+  open on both ends for the life of the visit to carry nothing, since both paths that write to
+  the socket take a `FlowComponent` and none was registered. The connection is now made when
+  something needs it: after the initial scan, after an SPA navigation, after a patch registers
+  a child. `<Link navigate>` fetches over HTTP, so a static page with links stays disconnected.
+  A routed page honours the same static, which is the half that matters — a page is a
+  component, and one whose children are static but which is interactive itself still connects.
+
 ## [1.7.3] — 2026-08-20
 
 ### Changed

package/api-surface.md

@@ -8,6 +8,7 @@
 class Component = {
   new (): Component
   static durable?: boolean | {    ttl?: string;    scope?: 'user' | 'session';}
+  static interactive?: boolean
   static readonly __isFlowPage: true
   static title?: string | ((component: never) => string)
   static using: Compose
@@ -33,6 +34,7 @@ class Component = {
   _prevChildIds: string[]
   _redirectStatus: number | null
   _redirectUrl: string | null
+  _renderStaticChild: <C extends Component>(ChildClass: new () => C, opts: {    props?: Partial<C>;    slots?: Record<string, string>;}) => Promise<string>
   _resolveTitle: () => string | null
   _shouldRefresh: boolean
   _streamSender: ((ref: string, content: string, replace: boolean) => void) | null
@@ -52,6 +54,7 @@ class Component = {
   errors: ErrorsProxy
   flash: (message: string, optionsOrLevel?: FlashLevel | FlashOptions) => FlashBuilder
   hasSlot: (name?: string) => boolean
+  isInteractive: boolean
   layout: (page: HtmlNode) => HtmlNode | Promise<HtmlNode>
   navigateCurrent: (options?: CurrentUrlOptions) => Promise<void>
   onBoot: (_ctx?: HttpContext) => Promise<void>
@@ -757,6 +760,7 @@ interface ModalProps = {
 interface PageClassWithMeta = {
   new (): Component
   head?: string
+  interactive?: boolean
   layout?: new () => Layout
   models?: Record<string, typeof BaseModel>
   name: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/flow",
-  "version": "1.7.5",
+  "version": "1.8.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -47,15 +47,15 @@
     "@alpinejs/morph": "^3.14.9",
     "@alpinejs/persist": "^3.14.9",
     "@alpinejs/resize": "^3.14.9",
-    "@zerotal/client": "1.7.5",
-    "@zerotal/core": "1.7.5",
-    "@zerotal/orm": "1.7.5",
-    "@zerotal/validator": "1.7.5",
+    "@zerotal/client": "1.8.0",
+    "@zerotal/core": "1.8.0",
+    "@zerotal/orm": "1.8.0",
+    "@zerotal/validator": "1.8.0",
     "alpinejs": "^3.14.9",
     "typescript": "^5.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.7.5",
+    "@zerotal/broadcasting": "1.8.0",
     "@types/alpinejs": "^3.13.10",
     "@types/alpinejs__anchor": "^3.13.1",
     "@types/alpinejs__collapse": "^3.13.4",

package/src/Component.ts

@@ -373,6 +373,24 @@ export interface FlashBuilder {
 }
 
 // ── Component ──────────────────────────────────────────────────────────────────────
+/**
+ * Copy a parent's `props` onto a freshly constructed child.
+ *
+ * Underscore-prefixed keys are skipped: those are the framework's own fields
+ * (`_flowId`, `_flowPath`, `_childIds`) and a parent overwriting one would
+ * detach the child from its own identity.
+ *
+ * The cast is the boundary. `Partial<C>` is a checked contract at the call site;
+ * inside, assignment is by string key and no index signature exists to express
+ * that. Written once here rather than at each of the four render paths, which is
+ * both less duplication and three fewer casts.
+ */
+function _assignChildProps(target: object, props: Record<string, unknown>): void {
+  const bag = target as Record<string, unknown>;
+  for (const [key, value] of Object.entries(props)) {
+    if (!key.startsWith("_")) bag[key] = value;
+  }
+}
 
 /**
  * Base class for Flow pages — reactive server-side components rendered over a WebSocket.
@@ -653,6 +671,53 @@ export abstract class Component {
    */
   static title?: string | ((component: never) => string);
 
+  /**
+   * Opt a component out of interactivity: `static interactive = false`.
+   *
+   * Every Flow component today is maximally interactive — rendered on the server,
+   * dehydrated into a state snapshot, tracked by the client, and re-rendered over
+   * a socket. That is right for a counter and wasteful for a page header, a nav
+   * rail or a marketing section, none of which will ever receive an action.
+   *
+   * A static child is rendered in full by its parent and nothing else: no
+   * snapshot, no `<script type="application/json">`, no entry in the client's
+   * component registry. It updates when its parent re-renders, the way ordinary
+   * markup does.
+   *
+   * ## Why it is not marked `data-flow-root`
+   *
+   * The client morph deliberately *skips* nested roots — that is what preserves a
+   * live child's DOM and state when its parent re-renders. A static child has no
+   * live DOM to preserve, so wearing that attribute would freeze its content at
+   * the first render and every later parent update would pass it by. So it is
+   * emitted as plain markup, which is also what makes "the parent re-renders it"
+   * true without any special case on the client.
+   *
+   * For the same reason a static child is kept out of `_childIds`: that list is
+   * what decides whether a hydrated parent emits a child as an empty stub, and a
+   * stub for something with no live DOM blanks the region.
+   *
+   * ## What it does not do yet
+   *
+   * The socket is still opened unconditionally, so a page whose every component
+   * is static still connects. That is the other half of render modes and it is
+   * separate work — see `_connect()` in the client bridge.
+   *
+   * @category Rendering
+   */
+  static interactive?: boolean;
+
+  /**
+   * Whether this component was rendered interactively.
+   *
+   * The instance-side reading of `static interactive`. Useful inside `render()`
+   * to leave out something that only makes sense with a client attached — a
+   * "Loading…" state, a control whose action can never fire.
+   */
+  get isInteractive(): boolean {
+    return (this.constructor as typeof Component).interactive !== false;
+  }
+
   static durable?: boolean | { ttl?: string; scope?: "user" | "session" };
 
   /** Set by {@link clearDurable}; the dispatcher deletes the durable entry after the request. @internal */
@@ -1523,6 +1588,31 @@ export abstract class Component {
     // excluded deliberately: those exist to change without remounting the child,
     // and hashing them would trade this bug for a child that resets on every
     // update. The counter still disambiguates genuinely identical siblings.
+    // A static child is markup, not an island: rendered in full by this parent
+    // every time, with no snapshot, no id, and no place in `_childIds`.
+    //
+    // Kept out of that list deliberately. `_childIds`/`_prevChildIds` is what
+    // decides whether a hydrated parent emits a child as an empty stub and lets
+    // the client morph preserve the live DOM underneath — and a static child has
+    // no live DOM, so a stub would blank the region on every parent update. That
+    // single interaction is the whole of what makes render modes delicate.
+    // `Reflect.get` rather than a cast to `typeof Component`, and rather than
+    // widening the parameter to name the static. Widening changes a public
+    // signature — and `C` is inferred from this parameter, which TypeScript does
+    // less reliably through an intersection than through a bare constructor. A
+    // subtly worse inference at every call site is a poor trade for reading one
+    // optional boolean.
+    if (Reflect.get(ChildClass, "interactive") === false) {
+      if (opts.lazy || opts.defer || opts.stream) {
+        throw new Error(
+          `<${name}> is \`static interactive = false\`, so it cannot also be lazy, deferred ` +
+            `or streamed — each of those needs a client to ask for the real render, and a ` +
+            `static child has none. Drop the option, or make the component interactive.`,
+        );
+      }
+      return { html: await this._renderStaticChild(ChildClass, opts) };
+    }
+
     const keyPart =
       opts.key !== undefined
         ? String(opts.key).replace(/[^a-zA-Z0-9_-]/g, "")
@@ -1581,9 +1671,7 @@ export abstract class Component {
       childPage._flowPath = this._flowPath;
       if (opts.slots) childPage._flowSlots = opts.slots;
       if (opts.props) {
-        for (const [k, v] of Object.entries(opts.props)) {
-          if (!k.startsWith("_")) (childPage as Record<string, unknown>)[k] = v;
-        }
+        _assignChildProps(childPage, opts.props as Record<string, unknown>);
       }
       // Don't call onMount() — placeholder only
 
@@ -1616,9 +1704,7 @@ export abstract class Component {
       childPage._flowPath = this._flowPath;
       if (opts.slots) childPage._flowSlots = opts.slots;
       if (opts.props) {
-        for (const [k, v] of Object.entries(opts.props)) {
-          if (!k.startsWith("_")) (childPage as Record<string, unknown>)[k] = v;
-        }
+        _assignChildProps(childPage, opts.props as Record<string, unknown>);
       }
 
       queueStream({
@@ -1651,9 +1737,7 @@ export abstract class Component {
     childPage._flowPath = this._flowPath;
     if (opts.slots) childPage._flowSlots = opts.slots;
     if (opts.props) {
-      for (const [k, v] of Object.entries(opts.props)) {
-        if (!k.startsWith("_")) (childPage as Record<string, unknown>)[k] = v;
-      }
+      _assignChildProps(childPage, opts.props as Record<string, unknown>);
     }
     // A child is populated from its parent's props (assigned above), not from route segments,
     // but it still gets the request context — the same object the routed page received.
@@ -1679,6 +1763,36 @@ export abstract class Component {
     };
   }
 
+  /**
+   * Render a `static interactive = false` child: markup, and nothing else.
+   *
+   * Same lifecycle as an interactive child up to the point where the client would
+   * be involved — `onBoot`, `onMount`, `render` — and then it stops. No
+   * `onDehydrate`, no snapshot, no state script, no wrapper.
+   *
+   * The absent wrapper is the load-bearing part. `data-flow-root` is what tells
+   * the client morph to leave a subtree alone, which is right for something with
+   * live state and exactly wrong here: this child's only route to an update is
+   * its parent re-rendering it, and a skipped subtree would never receive one.
+   */
+  /** @internal Called only by {@link child}. */
+  async _renderStaticChild<C extends Component>(
+    ChildClass: new () => C,
+    opts: { props?: Partial<C>; slots?: Record<string, string> },
+  ): Promise<string> {
+    const childPage = new ChildClass();
+    childPage._flowPath = this._flowPath;
+    if (opts.slots) childPage._flowSlots = opts.slots;
+    if (opts.props) {
+      _assignChildProps(childPage, opts.props as Record<string, unknown>);
+    }
+
+    const ctx = HttpContext.tryGet();
+    await childPage.onBoot(ctx);
+    await childPage.onMount(ctx);
+    return _renderFlowPage(childPage, () => childPage.render());
+  }
+
   // ── Streaming ─────────────────────────────────────────────────────────────
 
   /**

package/src/client/bridge.ts

@@ -501,6 +501,8 @@ function _setConnectionState(online: boolean): void {
 }
 
 let _ws: WebSocket | null = null;
+/** Whether this page has ever needed the socket. Latched, never cleared. @see _ensureConnected */
+let _socketWanted = false;
 let _reconnectDelay = 1_000;
 const MAX_DELAY = 30_000;
 
@@ -781,6 +783,37 @@ function _dispatchFrame(comp: FlowComponent, method: string, args: unknown[]): v
   _sendCall(comp, method, args);
 }
 
+/**
+ * Open the socket, but only if the page has anything that could use it.
+ *
+ * Every page used to connect. A page whose components are all
+ * `static interactive = false` — a marketing page, a docs article, a rendered
+ * report — has nothing that can dispatch an action, poll, or receive a patch,
+ * and it still opened `/__flow/ws` and held it. That is a connection per visitor
+ * per page, and a server holding all of them, for a page that will never send a
+ * frame.
+ *
+ * The test is `_components.size`, and it is exact rather than a heuristic: both
+ * paths that write to the socket — {@link _sendCall} and {@link _cancelTask} —
+ * take a `FlowComponent`, so with none registered nothing can send. Navigation
+ * does not need it either; `<Link navigate>` fetches the page over HTTP.
+ *
+ * Called again after anything that can register a component — the initial scan,
+ * an SPA navigation, a lazy child arriving — so a page that becomes interactive
+ * connects at that moment rather than never. Already-connected is a no-op, and
+ * reconnection after a drop stays with {@link _connect}, which does not re-ask
+ * the question: a page that has connected once has proved it needs a socket.
+ *
+ * The latch is a flag rather than `_ws !== null`, because `_ws` is nulled on
+ * close while a reconnect is pending — so a scan during that window would have
+ * opened a second socket beside the one already on its way back.
+ */
+function _ensureConnected(): void {
+  if (_socketWanted || _components.size === 0) return;
+  _socketWanted = true;
+  _connect();
+}
+
 function _connect(): void {
   const proto = location.protocol === "https:" ? "wss:" : "ws:";
   _ws = new WebSocket(`${proto}//${location.host}/__flow/ws`);
@@ -1173,6 +1206,7 @@ function _morphComponent(comp: FlowComponent, html: string): void {
   }
 
   _scanComponents();
+  _ensureConnected();
   _cleanupDisconnected();
   _refreshComponentFeatures(comp);
 }
@@ -2908,6 +2942,7 @@ async function _navigateTo(href: string, options: NavigateOptions = {}): Promise
     currentRoot.replaceWith(incomingClone);
     _cleanupDisconnected();
     _scanComponents();
+    _ensureConnected();
     _processHead(doc); // re-apply head from the incoming page (shell stylesheet + page meta)
     // Inside the swap, not after it: the document only has its new height (and
     // its fragment targets) once the root is in place. Inside the View
@@ -4158,7 +4193,7 @@ export function initBridge(): void {
   _checkBootError(); // dev-only: an initial-render throw is embedded on the page → show the overlay
   _scanComponents();
   _processHead(); // hoist any SSR <Head> content into document.head
-  _connect();
+  _ensureConnected();
   _setupEventDelegation();
   _setupNavigationLinks();
   _setupModalEscape();

package/src/registry.ts

@@ -115,6 +115,12 @@ export interface PageClassWithMeta {
   title?: string | ((component: never) => string);
   /** Raw HTML to inject into <head> for this page. */
   head?: string;
+  /**
+   * `false` renders this page as markup: no snapshot, no state script, no client
+   * registration — and, if nothing else on the page registers either, no
+   * WebSocket. See {@link Component.interactive}.
+   */
+  interactive?: boolean;
   /** Optional model associations for auto-registration. */
   models?: Record<string, typeof import("@zerotal/orm").BaseModel>;
   /** Optional layout class. */

package/src/router.ts

@@ -174,23 +174,36 @@ export function _makeFlowHandler(path: string, PageClass: PageClassWithMeta) {
 
             const innerHtml = await _renderFlowPage(page, () => page.render());
 
+            // A page can opt out of interactivity as a child can — and it is the page
+            // that matters most, because the client connects when it finds anything to
+            // register. A page that is static and whose children are static registers
+            // nothing, so no socket is opened at all.
+            const interactive = PageClass.interactive !== false;
+
             // dehydrate() hook runs at the end of the request, before serialisation.
-            await page.onDehydrate();
-            const snapshot = dehydrate(page, { id: compId, name: compName, path });
-            warnIfLarge(snapshot, compName);
+            if (interactive) await page.onDehydrate();
+            const snapshot = interactive
+              ? dehydrate(page, { id: compId, name: compName, path })
+              : undefined;
+            if (snapshot) warnIfLarge(snapshot, compName);
 
             // Persist the durable snapshot (or clear it if clearDurable() was called). No-op unless
             // the component opted into `static durable`.
-            await persistDurable(page, ctx, snapshot);
+            if (snapshot) await persistDurable(page, ctx, snapshot);
 
             // toScriptJson, not JSON.stringify: the snapshot carries @expose/@locked values and
             // @url props seeded from the query string, so it routinely holds attacker-controlled
             // strings that would otherwise close the <script> island. See toScriptJson's docblock.
-            const snapshotJson = toScriptJson(snapshot);
+            const snapshotJson = snapshot ? toScriptJson(snapshot) : "";
 
             // The flow component root — always the same wrapper regardless of layout.
+            // A static page is not marked as a flow root: the attribute is what makes
+            // the client morph skip a subtree, and it is also what `_scanComponents`
+            // looks for. Neither applies to markup that will never be patched.
             const flowRoot: HtmlNode = {
-              html: `<div data-flow-root x-data="{}" data-flow-id="${compId}" data-flow-name="${compName}">${innerHtml}</div>`,
+              html: interactive
+                ? `<div data-flow-root x-data="{}" data-flow-id="${compId}" data-flow-name="${compName}">${innerHtml}</div>`
+                : innerHtml,
             };
 
             // Layout resolution. The JSX-native `layout(page)` instance hook wins; otherwise
@@ -244,7 +257,7 @@ export function _makeFlowHandler(path: string, PageClass: PageClassWithMeta) {
 </head>
 <body>
   ${bodyContent}
-  <script type="application/json" id="flow-state-${compId}">${snapshotJson}</script>
+  ${snapshotJson ? `<script type="application/json" id="flow-state-${compId}">${snapshotJson}</script>` : ""}
   ${runtimeTag}
 </body>
 </html>`;