@zerotal/flow 1.4.0 → 1.5.0

package/src/client/bridge.ts

@@ -277,7 +277,7 @@ const _loadingTimers = new Map<string, ReturnType<typeof setTimeout>>();
 const LOADING_DELAY_MS = 200;
 
 // A `live` text input debounces its per-keystroke sync by default, so fast typing doesn't fire
-// a WebSocket $set on every character (matching Livewire's `wire:model.live` default). Discrete
+// a WebSocket $set on every character. Discrete
 // controls — checkbox, radio, select, range, date, colour — send immediately (a deliberate pick,
 // not a stream of keystrokes). The default binding (no `live`) is deferred and never affected.
 const MODEL_DEBOUNCE_MS = 150;
@@ -452,9 +452,16 @@ function _updateDirty(comp: FlowComponent): void {
 let _isOnline = true;
 
 function _setConnectionState(online: boolean): void {
+  // The attribute mirrors the *current* state, so it is stamped even when that
+  // state hasn't changed. The bridge starts optimistic (`_isOnline = true`), so
+  // a page whose socket connects on the first attempt — the normal case — would
+  // otherwise never carry the attribute at all, and a stylesheet or a readiness
+  // check keyed on `[data-flow-connection="online"]` would wait forever for a
+  // page that is in fact perfectly connected.
+  document.body.setAttribute("data-flow-connection", online ? "online" : "offline");
+
   if (_isOnline === online) return;
   _isOnline = online;
-  document.body.setAttribute("data-flow-connection", online ? "online" : "offline");
   document.dispatchEvent(new CustomEvent(online ? "flow:online" : "flow:offline"));
 
   const offline = !online;
@@ -495,10 +502,37 @@ let _httpMode = false;
 let _wsFailures = 0;
 const HTTP_FALLBACK_AFTER = 3; // consecutive failed WS handshakes before switching to HTTP
 
+/**
+ * The origin guard refused this page, and no retry will change that.
+ *
+ * Reported once, in full, because the alternative is the worst failure this app has: the
+ * HTML renders, the console shows a generic "action failed", and the only symptom is that
+ * nothing a user clicks does anything. The connection state drops to offline too — the app
+ * genuinely cannot act, so actions queue behind `flow:offline` directives instead of being
+ * fired at an endpoint that will refuse every one of them.
+ */
+let _originRefused = false;
+function _reportOriginRefused(body: string): void {
+  if (_originRefused) return;
+  _originRefused = true;
+  console.error(
+    `[Flow] Actions refused: the server rejected this page's origin (${location.origin}).\n` +
+      `Behind a reverse proxy the app's own origin is the loopback address it bound to, so ` +
+      `the public origin has to be configured for it to accept browser-initiated actions.\n` +
+      `Fix: set \`url\` in config/app.ts to ${location.origin} — AppConfig fills ` +
+      `app.allowedOrigins from it.` +
+      (body ? `\nServer said: ${body}` : ""),
+  );
+  _setConnectionState(false);
+}
+
 function _enableHttpMode(): void {
   if (_httpMode) return;
   _httpMode = true;
-  console.warn("[Flow] WebSocket unavailable — falling back to HTTP requests.");
+  console.warn(
+    "[Flow] WebSocket unavailable — falling back to HTTP requests. If actions also fail, " +
+      "check that the proxy forwards /__flow/* over HTTP/1.1 and does not gate it behind auth.",
+  );
   _setConnectionState(true); // HTTP works, so we're "online" for offline directives
   // The socket that dropped may never come back, so this is the reconnect for anything it
   // left mid-action — resync over HTTP before replaying, same order as the WS path.
@@ -517,12 +551,25 @@ function _httpSend(frame: unknown, compId: string): void {
     credentials: "include",
     body: JSON.stringify(frame),
   })
-    .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`HTTP ${r.status}`))))
+    .then(async (r) => {
+      if (r.ok) return r.json();
+      // The status is the diagnosis, and the body carries the server's own words for it.
+      // Both are dropped by a bare `HTTP 403`, which is what made this failure so quiet.
+      const body = await r.text().catch(() => "");
+      const err = new Error(`HTTP ${r.status}${body ? `: ${body}` : ""}`) as Error & {
+        status?: number;
+        body?: string;
+      };
+      err.status = r.status;
+      err.body = body;
+      throw err;
+    })
     .then((frames: unknown) => {
       if (Array.isArray(frames)) for (const f of frames) void _handleServerFrame(f as ServerFrame);
     })
-    .catch((e) => {
-      console.error("[Flow] HTTP action failed:", e);
+    .catch((e: Error & { status?: number; body?: string }) => {
+      if (e.status === 403) _reportOriginRefused(e.body ?? "");
+      else console.error("[Flow] HTTP action failed:", e);
       _resolveAck(compId); // never wedge the per-component queue
     });
 }
@@ -1206,16 +1253,37 @@ function _renderTimelineInto(el: HTMLElement): void {
   };
 }
 
-// A compact, dev-only scrubbing panel docked bottom-left. The console API above is the primary
-// interface; this is a convenience over it.
+/** The four corners the timeline pill can dock to. */
+const _TL_CORNERS = ["bottom-left", "bottom-right", "top-left", "top-right"] as const;
+type _TlCorner = (typeof _TL_CORNERS)[number];
+
+/**
+ * Which corner the fallback pill docks to. `data-flow-tl-corner` on <html> or <body>
+ * overrides; the default is bottom-left, where it stays clear of an app's own left-rail
+ * navigation (a top-docked panel at max z-index sat exactly on a sidebar's first item).
+ */
+function _timelineCorner(): _TlCorner {
+  const raw =
+    document.documentElement.dataset["flowTlCorner"] ?? document.body.dataset["flowTlCorner"];
+  return (_TL_CORNERS as readonly string[]).includes(raw ?? "")
+    ? (raw as _TlCorner)
+    : "bottom-left";
+}
+
+// A compact, dev-only scrubbing panel docked bottom-left by default (see _timelineCorner).
+// The console API above is the primary interface; this is a convenience over it.
 function _setupTimelinePanel(): void {
   if (document.getElementById("flow-tl-panel")) return;
   const style = document.createElement("style");
   style.textContent = `
-    #flow-tl-panel{position:fixed;left:10px;top:88px;z-index:2147483647;font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace;color:#e5e7eb}
+    #flow-tl-panel{position:fixed;z-index:2147483647;display:flex;flex-direction:column;gap:6px;font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace;color:#e5e7eb}
+    #flow-tl-panel[data-corner="bottom-left"]{left:10px;bottom:10px;flex-direction:column-reverse}
+    #flow-tl-panel[data-corner="bottom-right"]{right:10px;bottom:10px;flex-direction:column-reverse;align-items:flex-end}
+    #flow-tl-panel[data-corner="top-left"]{left:10px;top:10px}
+    #flow-tl-panel[data-corner="top-right"]{right:10px;top:10px;align-items:flex-end}
     #flow-tl-panel *{box-sizing:border-box}
-    .flow-tl-toggle{background:#111827;color:#e5e7eb;border:1px solid #374151;border-radius:9999px;padding:5px 10px;cursor:pointer;box-shadow:0 4px 12px rgba(0,0,0,.3)}
-    .flow-tl-body{margin-top:6px;width:320px;max-height:50vh;display:flex;flex-direction:column;background:#0b1220;border:1px solid #374151;border-radius:10px;overflow:hidden;box-shadow:0 8px 28px rgba(0,0,0,.45)}
+    .flow-tl-toggle{background:#111827;color:#e5e7eb;border:1px solid #374151;border-radius:9999px;padding:5px 10px;cursor:pointer;box-shadow:0 4px 12px rgba(0,0,0,.3);align-self:inherit}
+    .flow-tl-body{width:320px;max-height:50vh;display:flex;flex-direction:column;background:#0b1220;border:1px solid #374151;border-radius:10px;overflow:hidden;box-shadow:0 8px 28px rgba(0,0,0,.45)}
     .flow-tl-head{display:flex;align-items:center;gap:8px;padding:8px 10px;border-bottom:1px solid #1f2937;font-weight:600}
     .flow-tl-head .sp{flex:1}
     .flow-tl-live{background:#059669;color:#fff;border:0;border-radius:6px;padding:3px 8px;cursor:pointer}
@@ -1233,6 +1301,7 @@ function _setupTimelinePanel(): void {
 
   const root = document.createElement("div");
   root.id = "flow-tl-panel";
+  root.dataset["corner"] = _timelineCorner();
   root.innerHTML =
     `<button class="flow-tl-toggle" type="button">⏱ <b class="flow-tl-count">0</b></button>` +
     `<div class="flow-tl-body" hidden>` +
@@ -1846,16 +1915,6 @@ function _focusFirstError(comp: FlowComponent): void {
   if (invalid) (invalid as HTMLElement).focus();
 }
 
-// Local copy by design: this file ships to browsers as part of the client
-// bundle and cannot import server-side @zerotal/core helpers.
-function debounce<T extends unknown[]>(fn: (...args: T) => void, ms: number): (...args: T) => void {
-  let timer: ReturnType<typeof setTimeout>;
-  return (...args: T) => {
-    clearTimeout(timer);
-    timer = setTimeout(() => fn(...args), ms);
-  };
-}
-
 /**
  * Find the nearest ancestor carrying `flow:<event>`, with or without modifiers.
  *
@@ -2005,12 +2064,75 @@ function _takeLastAction(compId: string): string {
 }
 
 function _callAction(comp: FlowComponent, method: string, args: unknown[]): void {
+  _countActionDispatch(comp);
   _setActionError(comp, false); // retrying clears any prior failed state
   _setLoading(comp, true, method);
   if (isTimelineEnabled()) _pendingActionByComp.set(comp.id, method);
   _dispatchFrame(comp, method, args);
 }
 
+// ── Client-expression writes sync to the server ───────────────────────────────
+// `onClick={() => (this.selected = row.id)}` writes the reactive store, but render()
+// runs on the server — without a round-trip the page never reflects the write, and
+// nothing errors. (It *looked* reactive whenever a later action happened to flush it,
+// which is the worst kind of sometimes.) So: while a client expression evaluates,
+// every write to an exposed prop is recorded; if the expression wrote state and did
+// not itself dispatch an action on that component (an action's frame already carries
+// all pending writes), one `$rerender` is sent — state applied through the same
+// allowlist + updating()/updated() hooks, re-rendered, patched. No loading state:
+// it is a sync, not a user action. Client-only UI state belongs in `this.store()`,
+// which never round-trips.
+
+/** Writes recorded during the currently-evaluating client expression (null: none active). */
+let _exprWrites: Set<string> | null = null;
+/** Actions dispatched per component, to detect "the expression already sent one". */
+const _actionSeq = new Map<string, number>();
+
+/** @internal Count an action dispatch on `comp` (called by _callAction; exported for tests). */
+export function _countActionDispatch(comp: { id: string }): void {
+  _actionSeq.set(comp.id, (_actionSeq.get(comp.id) ?? 0) + 1);
+}
+
+/** @internal Record a write to an exposed prop; no-op outside an expression evaluation. */
+export function _noteExprWrite(key: string): void {
+  _exprWrites?.add(key);
+}
+
+/** @internal Opaque state carried from {@link _beginExprEval} to {@link _endExprEval}. */
+export interface ExprEvalToken {
+  writes: Set<string>;
+  prev: Set<string> | null;
+  seqBefore: number;
+}
+
+/** @internal Start recording exposed-prop writes for one expression evaluation. */
+export function _beginExprEval(comp: { id: string }): ExprEvalToken {
+  const token: ExprEvalToken = {
+    writes: new Set(),
+    prev: _exprWrites,
+    seqBefore: _actionSeq.get(comp.id) ?? 0,
+  };
+  _exprWrites = token.writes;
+  return token;
+}
+
+/**
+ * @internal Stop recording and decide whether the component needs a sync round-trip:
+ * it does when the expression wrote at least one exposed prop, dispatched no action on
+ * this component itself, and the writes left actual pending changes (a toggle-back to
+ * the canonical value needs nothing).
+ */
+export function _endExprEval(
+  comp: { id: string },
+  token: ExprEvalToken,
+  pendingCount: number,
+): boolean {
+  _exprWrites = token.prev;
+  if (token.writes.size === 0) return false;
+  if ((_actionSeq.get(comp.id) ?? 0) !== token.seqBefore) return false;
+  return pendingCount > 0;
+}
+
 /**
  * Execute a flow:click / flow:submit value that contains $flow references.
  * Emitted from inline arrow handlers in JSX — `onClick={(e) => this.x = 0}` — where
@@ -2020,15 +2142,24 @@ function _callAction(comp: FlowComponent, method: string, args: unknown[]): void
  * Mirrors Alpine's own `x-on` semantics: if the expression evaluates to a function
  * (the author wrote an arrow), call it with the DOM event. A bare statement
  * (`$flow.x = 0`) evaluates directly and returns a non-function, so nothing is called.
+ *
+ * A write to an exposed prop syncs to the server afterwards (see _beginExprEval) —
+ * a partial write before a throw still syncs, since the client state did change.
  */
 function _evalClientExpr(comp: FlowComponent, el: Element, expr: string, event?: Event): void {
   const A = Alpine as unknown as { evaluate(el: Element, expr: string): unknown };
+  const token = _beginExprEval(comp);
+  let needsSync = false;
   try {
     const result = A.evaluate(el, expr);
     if (typeof result === "function") (result as (e?: Event) => unknown)(event);
   } catch (e) {
     console.error("[Flow] client expression error:", e, "\nExpr:", expr);
+  } finally {
+    needsSync = _endExprEval(comp, token, Object.keys(_pendingUpdates(comp)).length);
   }
+  // Serialised like any action; carries every pending write as the frame's `updates`.
+  if (needsSync) _dispatchFrame(comp, "$rerender", []);
 }
 
 /**
@@ -2293,7 +2424,7 @@ function _linkActive(href: string, path: string, exact = false): boolean {
 function _updateCurrentLinks(): void {
   const path = window.location.pathname;
 
-  // Auto data-current on every navigate link matching the URL (Livewire behavior).
+  // Auto data-current on every navigate link matching the URL.
   // Style with `class="data-current:font-bold"` or `[data-current] {}`. Opt out
   // per-link with `flow:current.ignore` (the <Link current={false}> prop), or force it
   // always-on with `flow:current.force` (the <Link current={true}> prop) so the link stays
@@ -3404,11 +3535,13 @@ function _isWritable(comp: FlowComponent, key: string): boolean {
  * Register $flow and $errors Alpine magic helpers.
  * Called from index.ts with the Alpine instance before Alpine.start().
  *
- * $flow mirrors Livewire's $wire API:
+ * The $flow client API:
  *
  *   $flow.method(args)         — call an @expose method
  *   $flow.prop                 — read a reactive property
- *   $flow.prop = value         — write locally (sent with next action)
+ *   $flow.prop = value         — write; inside a client expression that dispatches no
+ *                                action, the write syncs to the server afterwards so
+ *                                render() reflects it (client-only state → $store)
  *
  *   $flow.$refresh()           — re-render the component
  *   $flow.$commit()            — alias for $refresh
@@ -3618,6 +3751,9 @@ export function registerFlowMagic(alpine: AlpineType): void {
         _syncDeclarative(comp);
         // flow:model inputs aren't Alpine-bound, so push the new value into them explicitly.
         _syncModelInputs(comp);
+        // Inside a client expression, the write syncs to the server when the
+        // expression dispatches no action of its own (see _beginExprEval).
+        _noteExprWrite(key);
         return true;
       },
     });

package/src/client/headless.ts

@@ -901,7 +901,8 @@ export function flowCommand(config: { items: FlowCommandItem[]; hotkey?: string
       this.open = false;
     },
     toggle(this: AlpineCtx & CommandState) {
-      this.open ? this.hide() : this.show();
+      if (this.open) this.hide();
+      else this.show();
     },
     move(this: AlpineCtx & CommandState, by: number) {
       const total = this.results().length;

package/src/components.ts

@@ -11,8 +11,16 @@
  * ```
  */
 
-import { jsx, _resolveReactiveName, _resolveBindName, _injectedBindKey } from "./jsx-runtime.ts";
+import {
+  jsx,
+  _resolveReactiveName,
+  _resolveBindName,
+  _injectedBindKey,
+  _renderChild,
+  _protectThunks,
+} from "./jsx-runtime.ts";
 import type { HtmlNode } from "./jsx-runtime.ts";
+import { publishSection, reserveSection } from "./sections.ts";
 import { jsLiteral } from "./utils.ts";
 
 // ── <Link> ────────────────────────────────────────────────────────────────
@@ -936,8 +944,7 @@ export interface PagerProps {
  * @remarks
  * Pass `params` to preserve other query state (search term, per-page, …). `hover`
  * prefetches each page; `prevLabel`/`nextLabel` and the class props override the
- * defaults. This is the links UI — the Flow equivalent of Livewire's
- * `$paginator->links()` view.
+ * defaults. This is the links UI for a paginator.
  *
  * @example
  * ```tsx
@@ -1472,3 +1479,269 @@ export function Drawer(props: DrawerProps): HtmlNode {
   // and nothing intercepts clicks when closed (both are display:none via x-show).
   return jsx("div", { ...rest, class: "contents", children: [backdrop, jsx("div", panelOut)] });
 }
+
+// ── <ErrorBoundary> ───────────────────────────────────────────────────────────
+/** Props for {@link ErrorBoundary}: the protected `children` and what to show instead on failure. */
+export interface ErrorBoundaryProps {
+  /** Markup to render when a child fails. A function receives the thrown error. */
+  fallback?: HtmlNode | ((error: unknown) => HtmlNode);
+  /** Called server-side when a child fails, for logging or reporting. */
+  onError?: (error: unknown) => void;
+  /** Wrapper element. Defaults to `"div"`. */
+  tag?: string;
+  class?: string;
+  children?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Contains a failure in a nested `<Component />` so it costs that component
+ * rather than the page.
+ *
+ * @remarks
+ * Without a boundary, a child component that throws while mounting or rendering
+ * takes the whole response with it — one broken widget blanks the dashboard.
+ * Wrapped, the child is replaced by `fallback` and everything around it renders.
+ *
+ * What it covers is child *components*. Inline JSX in the same `render()` is evaluated before
+ * this component is ever called, so a throw there cannot be intercepted here —
+ * move the risky work into a child component, which is where it belongs anyway.
+ * Boundaries nest, and the innermost one wins.
+ *
+ * The failure is reported through `onError` and logged; it is contained, not
+ * hidden.
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary fallback={<p class="text-sm text-red-600">Sales data unavailable.</p>}>
+ *   <SalesReport />
+ * </ErrorBoundary>
+ * ```
+ *
+ * @category Feedback
+ */
+export function ErrorBoundary(props: ErrorBoundaryProps): HtmlNode {
+  const { fallback, onError, tag, class: cls, children, ...rest } = props;
+
+  // Children are already rendered, and their child-component thunks already
+  // queued but not yet run, so the tokens sitting in this string are exactly the
+  // pending children this boundary is responsible for.
+  const inner = _renderChild(children);
+
+  _protectThunks(inner, (error) => {
+    try {
+      onError?.(error);
+    } catch {
+      // A reporting hook that throws must not replace the original failure with
+      // a less useful one.
+    }
+    console.error("[Flow] A component inside <ErrorBoundary> failed to render:", error);
+
+    if (typeof fallback === "function") return fallback(error).html;
+    if (fallback) return fallback.html;
+    return (
+      '<div data-flow-boundary-error role="alert" class="rounded border border-red-300 ' +
+      'bg-red-50 p-3 text-sm text-red-700">Something went wrong loading this section.</div>'
+    );
+  });
+
+  const out: Record<string, unknown> = { ...rest, children: { html: inner } };
+  out["data-flow-boundary"] = true;
+  if (cls) out["class"] = cls;
+  return jsx(tag ?? "div", out);
+}
+
+// ── <SectionContent> / <SectionOutlet> ────────────────────────────────────────
+/** Props for {@link SectionContent}: the `name` to publish under, and the markup. */
+export interface SectionContentProps {
+  /** Section name. Must match a {@link SectionOutlet}. */
+  name: string;
+  children?: unknown;
+}
+
+/**
+ * Publish markup to a named section, rendered wherever the matching
+ * {@link SectionOutlet} sits — typically in the layout.
+ *
+ * @remarks
+ * This renders nothing where it appears. It is how a page reaches a region it
+ * does not own: a page-specific toolbar button, a breadcrumb trail, a title. The
+ * alternative is threading content through every component in between as props,
+ * or the layout knowing about every page that might contribute.
+ *
+ * Two components may publish to one name; their content accumulates in render
+ * order rather than one replacing the other.
+ *
+ * Sections resolve once per document render. A WebSocket patch re-renders a
+ * component, not the layout, so content published during one does not reach an
+ * outlet outside the component being patched.
+ *
+ * @example
+ * ```tsx
+ * <SectionContent name="toolbar">
+ *   <button onClick={this.publish}>Publish</button>
+ * </SectionContent>
+ * ```
+ *
+ * @category Layout
+ */
+export function SectionContent(props: SectionContentProps): HtmlNode {
+  publishSection(props.name, _renderChild(props.children));
+  return { html: "" };
+}
+
+/** Props for {@link SectionOutlet}: the `name` to render, plus optional default content. */
+export interface SectionOutletProps {
+  /** Section name. Must match a {@link SectionContent}. */
+  name: string;
+  /** Rendered when nothing was published to this section. */
+  children?: unknown;
+}
+
+/**
+ * Render whatever was published to a named section.
+ *
+ * @remarks
+ * Place it in a layout to give pages a hole to fill. Children are the default,
+ * used when no page published anything.
+ *
+ * Order does not matter: the outlet reserves its place and is filled after the
+ * page *and* the layout have rendered. That is what makes the usual arrangement
+ * work — outlet in the layout, content in the page it wraps — where reading a
+ * store at render time would always be too early.
+ *
+ * @example
+ * ```tsx
+ * <header class="flex gap-2">
+ *   <SectionOutlet name="toolbar" />
+ * </header>
+ * ```
+ *
+ * @category Layout
+ */
+export function SectionOutlet(props: SectionOutletProps): HtmlNode {
+  return { html: reserveSection(props.name, _renderChild(props.children)) };
+}
+
+// ── <Virtualize> ──────────────────────────────────────────────────────────────
+/** Props for {@link Virtualize}: the current window of rows and how to ask for another. */
+export interface VirtualizeProps<T> {
+  /** The rows to render — the current window, not the whole collection. */
+  items: readonly T[];
+  /** Height of one row in pixels. Every row must be this tall. */
+  itemHeight: number;
+  /** Total rows in the full collection. Defaults to `items.length`. */
+  total?: number;
+  /** Index of `items[0]` within the full collection. Defaults to 0. */
+  start?: number;
+  /** Height of the scroll viewport in pixels. Defaults to 400. */
+  height?: number;
+  /**
+   * Server action requesting a different window, called as `(start, count)`.
+   * Omit when the collection is small enough to render whole.
+   */
+  onWindow?: unknown;
+  /** Rows rendered beyond the viewport on each side, to hide fetch latency. Defaults to 6. */
+  overscan?: number;
+  class?: string;
+  /** The row template: `(item, index) => <div>…</div>`, where `index` is absolute. */
+  children: (item: T, index: number) => HtmlNode;
+}
+
+/**
+ * A scrolling window over a collection too large to put in the DOM.
+ *
+ * @remarks
+ * Only the visible rows exist as elements; spacers above and below hold the
+ * scrollbar at the size the full collection implies. As the viewport moves, the
+ * component asks the server for the window it now needs via `onWindow` — a
+ * server-authoritative arrangement, which means the collection never has to
+ * reach the client in full.
+ *
+ * Rows must be a known, uniform `itemHeight`. That is what lets a scroll offset
+ * be turned into an index without measuring anything.
+ *
+ * Distinct from {@link InfiniteScroll}, which appends and grows the DOM without
+ * bound. Reach for this when *keeping* every rendered row is the problem.
+ *
+ * @example
+ * ```tsx
+ * <Virtualize
+ *   items={this.window}
+ *   start={this.windowStart}
+ *   total={this.total}
+ *   itemHeight={36}
+ *   height={480}
+ *   onWindow={this.loadWindow}
+ * >
+ *   {(row) => <div class="h-9 px-3 leading-9">{row.name}</div>}
+ * </Virtualize>
+ * ```
+ *
+ * @category Navigation & data
+ */
+export function Virtualize<T>(props: VirtualizeProps<T>): HtmlNode {
+  const {
+    items,
+    itemHeight,
+    total,
+    start = 0,
+    height = 400,
+    onWindow,
+    overscan = 6,
+    class: cls,
+    children,
+  } = props;
+
+  const rows = items ?? [];
+  const count = total ?? rows.length;
+  const visible = Math.max(1, Math.ceil(height / itemHeight));
+
+  let body = "";
+  for (let i = 0; i < rows.length; i++) {
+    const node = children(rows[i]!, start + i);
+    body += node && typeof node === "object" && "html" in node ? node.html : "";
+  }
+
+  // Spacers rather than absolutely-positioned rows: the browser keeps the
+  // scrollbar honest without every row needing a computed `top`, and the row
+  // template stays ordinary markup the caller can style however they like.
+  const above = start * itemHeight;
+  const below = Math.max(0, (count - start - rows.length) * itemHeight);
+
+  const state =
+    `{ h: ${itemHeight}, v: ${visible}, o: ${overscan}, at: ${start}, ` +
+    `win() { const s = Math.max(0, Math.floor($el.scrollTop / this.h) - this.o); ` +
+    `const c = this.v + this.o * 2; ` +
+    // Only ask when the window actually moved: scroll fires far more often than
+    // the set of needed rows changes, and every request is a round trip.
+    `if (s === this.at) return; this.at = s; ${_virtualizeRequest(onWindow)} } }`;
+
+  return jsx("div", {
+    ...(cls ? { class: cls } : {}),
+    "x-data": state,
+    "x-on:scroll.passive.throttle.100ms": "win()",
+    style: `height:${height}px;overflow-y:auto`,
+    "data-flow-virtualize": true,
+    children: {
+      html:
+        `<div style="height:${above}px" data-flow-virtualize-spacer></div>` +
+        body +
+        `<div style="height:${below}px" data-flow-virtualize-spacer></div>`,
+    },
+  });
+}
+
+/**
+ * The client expression that asks for a new window.
+ *
+ * A method reference arrives as a function whose `name` is the server action to
+ * call. Anything else means no provider was supplied, in which case scrolling
+ * just moves over rows that are already present.
+ */
+function _virtualizeRequest(onWindow: unknown): string {
+  if (typeof onWindow !== "function") return "";
+  const method = (onWindow as { name?: string }).name;
+  if (!method) return "";
+  return `$flow.${method}(s, c);`;
+}

package/src/config.ts

@@ -12,8 +12,8 @@ export interface FlowConfigShape {
    */
   cspSafe: boolean;
   /**
-   * Global middleware re-applied on every WebSocket update (Livewire-style
-   * persistent middleware). Entries are matched against the app's global
+   * Global middleware re-applied on every WebSocket update (persistent
+   * middleware). Entries are matched against the app's global
    * pipeline by class reference or by class name.
    *
    * Route middleware always re-runs and does not need to be listed here.