@zerotal/flow 1.3.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
     });
 }
@@ -865,7 +912,11 @@ function _syncUrlParams(comp: FlowComponent): void {
 
   if (newUrl !== location.pathname + location.search + location.hash) {
     if (pushed) {
-      history.pushState({ flowNavigate: true }, "", newUrl);
+      // Bank the scroll offset first: this entry is about to become a Back
+      // target, and the viewport has not moved, so where the user is now is
+      // where Back should return them.
+      _rememberScroll();
+      _pushHistoryEntry(newUrl);
     } else {
       history.replaceState(history.state, "", newUrl);
     }
@@ -1202,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}
@@ -1229,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>` +
@@ -1842,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.
  *
@@ -2001,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
@@ -2016,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", []);
 }
 
 /**
@@ -2289,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
@@ -2357,7 +2492,127 @@ function _takePrefetched(href: string): string | null {
   return Date.now() - cached.at < PREFETCH_TTL_MS ? cached.html : null;
 }
 
-async function _navigateTo(href: string, pushState = true): Promise<void> {
+// ── Scroll position across SPA navigations ────────────────────────────────────
+//
+// A real navigation puts you at the top of the new page, and Back puts you back
+// where you were. Swapping the DOM under a stationary viewport does neither: you
+// click a link near the bottom of a long list and land halfway down the next
+// page, which reads as the page having failed to load.
+//
+// Positions live in a map keyed by history entry rather than inside
+// `history.state`, because the entry you are *leaving* on a Back cannot be
+// stamped — by the time `popstate` fires, `history.state` is already the
+// destination's. A key per entry lets both directions be recorded.
+
+let _nextHistoryKey = 1;
+let _currentHistoryKey = 0;
+const _scrollByHistoryKey = new Map<number, [number, number]>();
+
+/**
+ * The live scroll offset, tracked passively.
+ *
+ * Read from here rather than from `window.scrollY` at navigation time: on a
+ * `popstate` the browser may already have applied its own scroll restoration
+ * before our handler runs, and by then the outgoing page's real position is gone.
+ */
+let _liveScroll: [number, number] = [0, 0];
+
+function _trackScroll(): void {
+  const update = (): void => {
+    _liveScroll = [window.scrollX, window.scrollY];
+  };
+  update();
+  window.addEventListener("scroll", update, { passive: true });
+}
+
+/** Record where the current history entry was left, so Back can return to it. */
+function _rememberScroll(): void {
+  _scrollByHistoryKey.set(_currentHistoryKey, _liveScroll);
+}
+
+/** Start a new history entry, keyed so its scroll position can be found again. */
+function _pushHistoryEntry(url: string): void {
+  _currentHistoryKey = _nextHistoryKey++;
+  history.pushState({ flowNavigate: true, flowKey: _currentHistoryKey }, "", url);
+}
+
+/** Where a navigation should leave the viewport. */
+export type ScrollIntent = "top" | "preserve" | readonly [number, number];
+
+/** The fragment of an href, without the `#`. Empty when it has none. */
+export function _hashOf(href: string): string {
+  const at = href.indexOf("#");
+  return at === -1 ? "" : href.slice(at + 1);
+}
+
+/**
+ * Resolve what a navigation should do to the viewport.
+ *
+ * A recorded position wins outright: on Back/Forward the whole point is to land
+ * where the user was, and `preserveScroll` is passed alongside it only as the
+ * fallback for an entry with nothing recorded.
+ */
+export function _scrollIntent(options: {
+  preserveScroll?: boolean;
+  restoreScroll?: readonly [number, number] | undefined;
+}): ScrollIntent {
+  return options.restoreScroll ?? (options.preserveScroll ? "preserve" : "top");
+}
+
+/** What {@link _applyScroll} will do, separated out so the decision is testable. */
+export type ScrollAction =
+  | { kind: "none" }
+  | { kind: "offset"; left: number; top: number }
+  | { kind: "fragment"; id: string };
+
+export function _scrollAction(intent: ScrollIntent, hash: string): ScrollAction {
+  if (intent === "preserve") return { kind: "none" };
+  if (intent !== "top") return { kind: "offset", left: intent[0], top: intent[1] };
+
+  // A fragment in the URL beats the top of the page — that is what the browser
+  // would have done for the same link without the SPA swap.
+  let id = hash;
+  if (id) {
+    try {
+      id = decodeURIComponent(id);
+    } catch {
+      /* malformed %-escape — take the fragment literally, as browsers do */
+    }
+  }
+  return id ? { kind: "fragment", id } : { kind: "offset", left: 0, top: 0 };
+}
+
+function _applyScroll(intent: ScrollIntent, hash: string): void {
+  const action = _scrollAction(intent, hash);
+  if (action.kind === "none") return;
+
+  // `behavior: "instant"` on purpose: a page with `scroll-behavior: smooth` in
+  // its CSS would otherwise animate the whole way up on every navigation, which
+  // on a long page is a visible scroll-back the user did not ask for.
+  if (action.kind === "offset") {
+    window.scrollTo({ left: action.left, top: action.top, behavior: "instant" });
+    return;
+  }
+
+  const target = document.getElementById(action.id);
+  // A fragment naming nothing on the page lands at the top, same as a real load.
+  if (target) target.scrollIntoView({ behavior: "instant", block: "start" });
+  else window.scrollTo({ left: 0, top: 0, behavior: "instant" });
+}
+
+/** Options for {@link _navigateTo}. */
+interface NavigateOptions {
+  /** Add a history entry. False on Back/Forward, where the entry already exists. */
+  push?: boolean;
+  /** Leave the viewport where it is instead of going to the top of the new page. */
+  preserveScroll?: boolean;
+  /** Offsets to restore, for Back/Forward. Takes precedence over `preserveScroll`. */
+  restoreScroll?: readonly [number, number] | undefined;
+}
+
+async function _navigateTo(href: string, options: NavigateOptions = {}): Promise<void> {
+  const { push = true } = options;
+  const scrollIntent = _scrollIntent(options);
   let html: string;
   const prefetched = _takePrefetched(href);
   if (prefetched !== null) {
@@ -2391,8 +2646,9 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
     // document.write() here would re-inject the classic runtime <script> into the
     // *current* realm and redeclare its top-level bindings (e.g. `class
     // FlowComponent` → "already declared"). A hard navigation also re-bootstraps
-    // the client cleanly for the new layout.
-    if (pushState) window.location.assign(href);
+    // the client cleanly for the new layout — including the scroll position,
+    // which the browser owns on a real document load.
+    if (push) window.location.assign(href);
     else window.location.reload();
     return;
   }
@@ -2417,6 +2673,12 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
   const incomingClone = incomingRoot.cloneNode(true) as HTMLElement;
   _carryPersisted(currentRoot, incomingClone);
 
+  // Where this page is sitting, banked before the swap. Replacing the root
+  // changes the document height, and the browser clamps the scroll offset
+  // against it — read afterwards, a position near the bottom of a long page
+  // comes back as somewhere near the bottom of the short one.
+  if (push) _rememberScroll();
+
   // Swap state script + component root. Wrapped in a View Transition when the
   // browser supports it, for a smooth cross-page animation; falls back to an
   // instant swap otherwise.
@@ -2427,6 +2689,11 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
     _cleanupDisconnected();
     _scanComponents();
     _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
+    // Transition callback this is also what the "after" snapshot captures, so
+    // the animation ends at the right offset instead of sliding there.
+    _applyScroll(scrollIntent, _hashOf(href));
   };
   const _startVT = (document as unknown as { startViewTransition?: (cb: () => void) => unknown })
     .startViewTransition;
@@ -2435,7 +2702,7 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
   if (typeof _startVT === "function" && !_reduceMotion) _startVT.call(document, _swap);
   else _swap(); // reduced-motion (or unsupported): swap instantly, no cross-page animation
 
-  if (pushState) history.pushState({ flowNavigate: true }, "", href);
+  if (push) _pushHistoryEntry(href);
   const incomingTitle = doc.querySelector("title");
   if (incomingTitle) document.title = incomingTitle.textContent ?? "";
   _updateCurrentLinks();
@@ -2542,14 +2809,22 @@ function _setupPrefetch(): void {
 function _setupNavigationLinks(): void {
   _updateCurrentLinks();
   _setupPrefetch();
+  _trackScroll();
 
   // Stamp the initial history entry as ours. A fresh page load has `history.state === null`,
   // so without this, pressing Back to the first page fires `popstate` with a null state — the
   // handler below ignores it and the URL changes while the page stays put. Replacing (not
-  // pushing) keeps the entry in place; it just gains the flowNavigate marker.
-  if (!(history.state as { flowNavigate?: boolean } | null)?.flowNavigate) {
+  // pushing) keeps the entry in place; it just gains the flowNavigate marker and its scroll key.
+  const initial = history.state as { flowNavigate?: boolean; flowKey?: number } | null;
+  if (typeof initial?.flowKey === "number") {
+    // Restored from bfcache or a reload — keep the key so the entry's recorded
+    // position still matches, and mint above it so a new entry can't collide.
+    _currentHistoryKey = initial.flowKey;
+    _nextHistoryKey = Math.max(_nextHistoryKey, initial.flowKey + 1);
+  } else {
+    _currentHistoryKey = _nextHistoryKey++;
     history.replaceState(
-      { ...(history.state as object | null), flowNavigate: true },
+      { ...(initial as object | null), flowNavigate: true, flowKey: _currentHistoryKey },
       "",
       location.href,
     );
@@ -2566,13 +2841,31 @@ function _setupNavigationLinks(): void {
       return;
     }
     e.preventDefault();
-    void _navigateTo(href);
+    void _navigateTo(href, {
+      preserveScroll: anchor.hasAttribute("flow:navigate.preserve"),
+    });
   });
 
   window.addEventListener("popstate", (e) => {
-    if ((e.state as { flowNavigate?: boolean } | null)?.flowNavigate) {
-      void _navigateTo(window.location.pathname + window.location.search, false);
-    }
+    const state = e.state as { flowNavigate?: boolean; flowKey?: number } | null;
+    if (!state?.flowNavigate) return;
+
+    // Bank the outgoing entry before the key moves on, so Forward lands correctly
+    // too — not just Back. This is the half that cannot be done from
+    // `history.state`, which by now already describes the destination.
+    _rememberScroll();
+    const destination = state.flowKey;
+    const restore = destination === undefined ? undefined : _scrollByHistoryKey.get(destination);
+    if (destination !== undefined) _currentHistoryKey = destination;
+
+    void _navigateTo(location.pathname + location.search + location.hash, {
+      push: false,
+      restoreScroll: restore,
+      // Nothing recorded for this entry — it predates the runtime, or a reload
+      // cleared the map. Leave the viewport alone rather than jumping to the
+      // top, which is not what Back does.
+      preserveScroll: restore === undefined,
+    });
   });
 }
 
@@ -2584,12 +2877,21 @@ function _setupNavigationLinks(): void {
  * Both read the live URL from window.location (kept in sync by flow:navigate).
  * Ideal for instant filters, e.g.:
  *   <select @change="$flow.navigateCurrent({ query: { status: $event.target.value || null } })">
+ *
+ * Like any navigation this lands at the top of the page. For a control sitting
+ * partway down — a filter row the user is looking at while they change it —
+ * pass `preserveScroll: true` to leave the viewport alone:
+ *   $flow.navigateCurrent({ query: { status: … }, preserveScroll: true })
  */
 function _currentUrl(options: CurrentUrlOptions = {}): string {
   return buildUrlWithQuery(window.location.href, options);
 }
-function _navigateCurrent(options: CurrentUrlOptions = {}): Promise<void> {
-  return _navigateTo(buildUrlWithQuery(window.location.href, options));
+function _navigateCurrent(
+  options: CurrentUrlOptions & { preserveScroll?: boolean } = {},
+): Promise<void> {
+  return _navigateTo(buildUrlWithQuery(window.location.href, options), {
+    preserveScroll: options.preserveScroll ?? false,
+  });
 }
 
 const _debouncedModelSend = (() => {
@@ -3233,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
@@ -3447,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/compiler/directives.ts

@@ -22,6 +22,7 @@ export const BOOLEAN_DIRECTIVES: Record<string, string> = {
   hideOnDirty: "flow:dirty.remove",
   navigate: "flow:navigate",
   navigateHover: "flow:navigate.hover",
+  navigatePreserveScroll: "flow:navigate.preserve",
   currentExact: "flow:current.exact",
   currentStrict: "flow:current.strict",
   cloak: "flow:cloak",

package/src/compiler/transform.ts

@@ -1634,6 +1634,10 @@ function _compileRenderMethod(
           emitStatic(" flow:navigate.hover");
           continue;
         }
+        if (ln === "preserveScroll" && attr.initializer === undefined) {
+          emitStatic(" flow:navigate.preserve");
+          continue;
+        }
         if (ln === "current") {
           const ci = attr.initializer;
           // current={false} → opt out of the auto active class; current={true} → default (skip).