@zerotal/flow 1.7.0 → 1.7.3

package/src/client/bridge.ts

@@ -34,6 +34,11 @@ import { confirmDialog, type ConfirmDialogOptions } from "./confirm.ts";
 import { showErrorOverlay } from "./errorOverlay.ts";
 import { applyAppend, applyRemove, type OptOp } from "./optimistic.ts";
 import { clientStore } from "../store.ts";
+// The `/Socket` subpath, not the package root: the root also exports
+// `ClientProvider`, which reaches @zerotal/core's CLI modules — one of which
+// does `await import("bun")`, a hard error in a browser bundle before
+// tree-shaking can drop it.
+import { Socket as BundledSocket } from "@zerotal/client/Socket";
 import { route } from "@zerotal/core/routes";
 import { URL_ATTRIBUTES, sanitizeUrl } from "../urlSafety.ts";
 import {
@@ -43,6 +48,11 @@ import {
   setTimelineApplier,
 } from "./timeline.ts";
 import * as _timeline from "./timeline.ts";
+import {
+  framePanes as _framePanes,
+  renderFramePanes as _renderFramePanes,
+  type FrameServerCost as _ServerCost,
+} from "./framePanes.ts";
 
 // CSP-safe mode: set by the CSP client entry. When on, bridge-managed bindings
 // use the eval-free evaluateCsp() instead of `new Function`.
@@ -712,14 +722,19 @@ function _sendCall(
       .then(
         () =>
           new Promise<void>((resolve) => {
+            const updates = fixedUpdates ?? _pendingUpdates(comp);
             const frame = {
               type: "call",
               component: compId,
               method,
               args,
-              updates: fixedUpdates ?? _pendingUpdates(comp),
+              updates,
               snapshot: comp.snapshot,
             };
+            // Here is where the client writes riding along with this call are
+            // finally resolved, so it is the only place the panel can learn them.
+            const pending = _pendingActionByComp.get(compId);
+            if (pending && pending.method === method) pending.updates = updates;
             // Safety net: never wedge the queue if a patch is dropped (server crash / HTTP error).
             const armSafetyNet = (): void => {
               setTimeout(() => {
@@ -1049,6 +1064,32 @@ function _dispatchFlash(detail: Record<string, unknown>): void {
 // episode triggers at most one reload, while a later, genuine restart can recover again.
 const _EXPIRY_RELOAD_KEY = "flow:reloaded-for-expired-component";
 
+/**
+ * Why an error frame should be recovered by a reload, if it should.
+ *
+ * Pure and exported so the policy is testable without a DOM — the handler that
+ * calls it needs `window`, `sessionStorage` and a live component map.
+ *
+ * `reload` is set by the server when the snapshot no longer belongs to the
+ * session that is asking, which is what signing out in another tab looks like
+ * from here. The page's state belongs to who you *were*, so no patch can
+ * succeed and reloading is the only honest recovery — the fresh request meets
+ * auth middleware and lands wherever a signed-out visitor belongs.
+ *
+ * Both cases share the one-shot guard: a reload that does not fix the problem
+ * must not reload again.
+ */
+export function _reloadReasonFor(
+  frame: { message?: string; reload?: boolean },
+  alreadyReloaded: boolean,
+): "session-changed" | "unknown-component" | null {
+  if (alreadyReloaded) return null;
+  // The server's explicit instruction outranks any inference from the message.
+  if (frame.reload) return "session-changed";
+  if (frame.message === "Unknown component") return "unknown-component";
+  return null;
+}
+
 function _reloadedForExpiry(): boolean {
   try {
     return sessionStorage.getItem(_EXPIRY_RELOAD_KEY) === "1";
@@ -1186,9 +1227,10 @@ function _enableTimeline(): void {
   if (dt && typeof dt.register === "function") {
     dt.register({
       id: "flow-timeline",
-      title: "Timeline",
+      title: "Flow",
       badge: () => _timeline.getFrames().length || undefined,
-      render: (el: HTMLElement) => _renderTimelineInto(el),
+      render: (el: HTMLElement, context?: { trace?: _TraceLike | null }) =>
+        _renderTimelineInto(el, context?.trace ?? null),
     });
     _timeline.onTimelineChange(() => dt.refresh("flow-timeline"));
   } else {
@@ -1207,9 +1249,90 @@ interface _DevtoolsRegistryLike {
   refresh(id?: string): void;
 }
 
+/**
+ * The half of a devtools trace this panel reads.
+ *
+ * Structural rather than imported: Flow depends on no observer package, and an
+ * app without devtools installed simply never passes one. Every field is optional
+ * for the same reason — this is a shape read from another package's data.
+ */
+interface _TraceLike {
+  statusCode?: number;
+  durationMs?: number;
+  channels?: Record<string, Array<Record<string, unknown>>>;
+  queries?: Array<{ sql?: unknown; durationMs?: unknown; rowCount?: unknown }>;
+  logs?: Array<{ level?: unknown; args?: unknown }>;
+  exception?: { message?: unknown } | null;
+}
+
+/**
+ * Server cost per frame, accumulated as traces arrive.
+ *
+ * A trace carries one action, and the panel follows the newest — so each render
+ * can bind at most the frame that just happened. Keeping what earlier renders
+ * bound is what lets a frame from four clicks ago still show what it cost, rather
+ * than only ever the selected one being annotated.
+ */
+const _frameCost = new Map<number, _ServerCost>();
+
+/** Attach the selected trace's action to the frame it produced, once. */
+function _bindServerCost(
+  trace: _TraceLike | null,
+  frames: readonly _timeline.TimelineFrame[],
+): void {
+  for (const entry of trace?.channels?.["flow"] ?? []) {
+    const component = entry["component"];
+    const action = entry["action"];
+    const durationMs = entry["durationMs"];
+    if (typeof component !== "string" || typeof action !== "string") continue;
+    if (typeof durationMs !== "number") continue;
+
+    // The newest matching frame that has no cost yet: an action produces its
+    // frame before the trace reaches the panel, and re-rendering the same trace
+    // must not walk the binding back through older frames of the same name.
+    for (let i = frames.length - 1; i >= 0; i--) {
+      const frame = frames[i]!;
+      if (frame.compId !== component || frame.action !== action) continue;
+      if (_frameCost.has(frame.seq)) break;
+      const ip = entry["ip"];
+      _frameCost.set(frame.seq, {
+        durationMs,
+        ip: typeof ip === "string" ? ip : null,
+        statusCode: typeof trace?.statusCode === "number" ? trace.statusCode : null,
+        // One action is one trace, so the whole trace is this action's server half.
+        queries: (trace?.queries ?? []).map((q) => ({
+          sql: String(q.sql ?? ""),
+          durationMs: typeof q.durationMs === "number" ? q.durationMs : null,
+          rowCount: typeof q.rowCount === "number" ? q.rowCount : null,
+        })),
+        logs: (trace?.logs ?? []).map((l) => ({
+          level: String(l.level ?? "log"),
+          text: Array.isArray(l.args) ? l.args.map((a) => String(a)).join(" ") : "",
+        })),
+        error:
+          trace?.exception && typeof trace.exception.message === "string"
+            ? trace.exception.message
+            : null,
+      });
+      break;
+    }
+  }
+}
+
+/** Which frames are expanded. Module state so a redraw does not collapse them. */
+const _expanded = new Set<number>();
+
+/** The trace of the last draw, so toggling a row can redraw without waiting for one. */
+let _lastTrace: _TraceLike | null = null;
+
+/** Which pane of a frame the reader last picked. See `activePane`. */
+let _framePref = "";
+
 /** Render the timeline into the Zerotal devtools content area (themed with its CSS vars/classes). */
-function _renderTimelineInto(el: HTMLElement): void {
+function _renderTimelineInto(el: HTMLElement, trace: _TraceLike | null = null): void {
   const frames = _timeline.getFrames();
+  _lastTrace = trace;
+  _bindServerCost(trace, frames);
   const compIds = [...new Set(frames.map((f) => f.compId))];
   const curSeqs = new Set(compIds.map((id) => _timeline.currentSeq(id)));
   const rewound = compIds.some((id) => !_timeline.isLive(id));
@@ -1228,13 +1351,30 @@ function _renderTimelineInto(el: HTMLElement): void {
           const cur = curSeqs.has(f.seq);
           const changed = f.changed.length ? f.changed.join(", ") : "—";
           const time = new Date(f.ts).toLocaleTimeString();
+          // A frame with no cost ran entirely in the browser — a client expression
+          // never reached the server, and saying nothing is the honest rendering.
+          const cost = _frameCost.get(f.seq);
+          const server = cost
+            ? `<span class="dim" style="font-size:10px">server ${cost.durationMs}ms${cost.queries.length ? ` · ${cost.queries.length}q` : ""}</span>`
+            : "";
+          const open = _expanded.has(f.seq);
+          const detail = open
+            ? `<div class="hdetail" style="margin-left:26px">` +
+              _renderFramePanes(_framePanes(f, frames, _frameCost.get(f.seq) ?? null), _framePref) +
+              `</div>`
+            : "";
           return (
             `<div class="qrow" data-tl-seq="${f.seq}" style="cursor:pointer;display:flex;gap:8px;align-items:baseline${cur ? ";background:var(--card)" : ""}">` +
+            // Its own hit area: the row time-travels, and expanding to read what
+            // happened must not also rewind the page you are reading it from.
+            `<span data-tl-exp="${f.seq}" title="${open ? "Collapse" : "What this action did"}" style="min-width:12px;cursor:pointer;user-select:none">${open ? "▾" : "▸"}</span>` +
             `<span class="dim" style="min-width:30px">#${f.seq}</span>` +
             `<span style="color:var(--purple);font-weight:700">${_escapeHtml(f.action)}</span>` +
             `<span class="dim" style="flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">${_escapeHtml(f.compName)} · ${_escapeHtml(changed)}</span>` +
+            server +
             `<span class="dim" style="font-size:10px">${time}</span>` +
-            `</div>`
+            `</div>` +
+            detail
           );
         })
         .join("")
@@ -1249,6 +1389,24 @@ function _renderTimelineInto(el: HTMLElement): void {
         _timeline.resumeLive(id);
       return;
     }
+    // A pane of the frame being read. First, since the strip sits inside the
+    // detail the row opened and a click there must not also rewind the page.
+    const pane = target.closest<HTMLElement>("[data-fsec]");
+    if (pane?.dataset["fsec"]) {
+      _framePref = pane.dataset["fsec"];
+      _renderTimelineInto(el, _lastTrace);
+      return;
+    }
+
+    // Checked before the row, since the toggle sits inside it.
+    const toggle = target.closest<HTMLElement>("[data-tl-exp]");
+    if (toggle?.dataset["tlExp"]) {
+      const seq = Number(toggle.dataset["tlExp"]);
+      if (_expanded.has(seq)) _expanded.delete(seq);
+      else _expanded.add(seq);
+      _renderTimelineInto(el, _lastTrace);
+      return;
+    }
     const row = target.closest<HTMLElement>("[data-tl-seq]");
     if (row?.dataset["tlSeq"]) _timeline.jumpTo(Number(row.dataset["tlSeq"]));
   };
@@ -1436,6 +1594,7 @@ async function _handleServerFrame(
     dataRemoved?: string[];
     actionError?: boolean;
     dev?: boolean;
+    reload?: boolean;
   },
 ): Promise<void> {
   if (frame.type === "ready") {
@@ -1515,12 +1674,21 @@ async function _handleServerFrame(
     // Time-travel: record this applied patch as a timeline frame (final patches only — mid-@task
     // partials would flood the timeline). No-op unless recording is enabled (dev).
     if (!frame.partial && isTimelineEnabled()) {
+      const dispatched = _takeLastDispatch(component);
       _recordTimelineFrame({
         compId: component,
         compName: comp.name,
-        action: _takeLastAction(component),
+        action: dispatched.action,
         snapshot: comp.snapshot,
         html: comp.rootEl.outerHTML,
+        ...(dispatched.sent
+          ? {
+              sent: {
+                args: dispatched.sent.args,
+                ...(dispatched.sent.updates ? { updates: dispatched.sent.updates } : {}),
+              },
+            }
+          : {}),
       });
     }
 
@@ -1594,11 +1762,14 @@ async function _handleServerFrame(
     // fresh document re-renders and re-registers every component server-side, then
     // re-hydrates the client. A one-shot guard (cleared once patches flow again, below)
     // prevents a reload loop if the reload doesn't resolve it.
-    if (frame.message === "Unknown component" && !_reloadedForExpiry()) {
+    const reloadReason = _reloadReasonFor(frame, _reloadedForExpiry());
+    if (reloadReason) {
       _markReloadedForExpiry();
       console.warn(
-        `[Flow] Component "${frame.component}" is no longer registered on the server ` +
-          `(likely a server restart) — reloading the page to recover.`,
+        reloadReason === "session-changed"
+          ? `[Flow] ${frame.message ?? "The session changed"} — reloading the page.`
+          : `[Flow] Component "${frame.component}" is no longer registered on the server ` +
+              `(likely a server restart) — reloading the page to recover.`,
       );
       window.location.reload();
       return;
@@ -1687,6 +1858,16 @@ function _syncModelInputs(comp: FlowComponent): void {
       el.checked = el.value === String(serverVal ?? "");
       return;
     }
+    // A file input's value belongs to the user agent: assigning anything but "" throws
+    // InvalidStateError, and that throw escapes the frame handler — the morph never runs
+    // and the action's ack never resolves, wedging the component's queue for good. The
+    // server side of the binding is an upload reference, not a filename, so there is
+    // nothing to write back; only the server *clearing* it is worth mirroring, so the
+    // same file can be picked again after a remove.
+    if (el instanceof HTMLInputElement && el.type === "file") {
+      if (serverVal === null || serverVal === undefined) el.value = "";
+      return;
+    }
     const str = String(serverVal ?? "");
     if (el.value !== str) el.value = str;
     // A draft-backed field the server just emptied (e.g. after a successful submit) → drop the draft.
@@ -2055,20 +2236,29 @@ function _reapplyOptOps(comp: FlowComponent): void {
   }
 }
 
-// Time-travel: remember the method a component last dispatched, so the patch it produces is
-// labelled with that action name in the timeline. Consumed (and cleared) when the patch lands.
-const _pendingActionByComp = new Map<string, string>();
-function _takeLastAction(compId: string): string {
-  const a = _pendingActionByComp.get(compId);
+// Time-travel: remember what a component last dispatched, so the patch it produces is labelled
+// with that action name in the timeline — and so the panel can show the call that caused it.
+// Consumed (and cleared) when the patch lands.
+interface _PendingDispatch {
+  method: string;
+  args: unknown[];
+  /** Filled in by `_sendCall`, which is where the batch of client writes is resolved. */
+  updates?: Record<string, unknown>;
+}
+const _pendingActionByComp = new Map<string, _PendingDispatch>();
+
+function _takeLastDispatch(compId: string): { action: string; sent?: _PendingDispatch } {
+  const d = _pendingActionByComp.get(compId);
   _pendingActionByComp.delete(compId);
-  return a ?? "action";
+  if (!d) return { action: "action" };
+  return { action: d.method, sent: d };
 }
 
 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);
+  if (isTimelineEnabled()) _pendingActionByComp.set(comp.id, { method, args });
   _dispatchFrame(comp, method, args);
 }
 
@@ -2710,12 +2900,32 @@ async function _navigateTo(href: string, options: NavigateOptions = {}): Promise
     // 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;
+  // The return value is typed here rather than cast at the call site, so reading
+  // the transition's promises below costs no new assertion.
+  const _startVT = (
+    document as unknown as {
+      startViewTransition?: (cb: () => void) => {
+        ready?: Promise<unknown>;
+        finished?: Promise<unknown>;
+      };
+    }
+  ).startViewTransition;
   const _reduceMotion =
     typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
-  if (typeof _startVT === "function" && !_reduceMotion) _startVT.call(document, _swap);
-  else _swap(); // reduced-motion (or unsupported): swap instantly, no cross-page animation
+  if (typeof _startVT === "function" && !_reduceMotion) {
+    const _vt = _startVT.call(document, _swap);
+    // A navigation that starts while a transition is still running makes the
+    // browser skip the older one and reject its `ready` and `finished` promises
+    // with an AbortError. Nothing has gone wrong — the swap itself already ran
+    // inside the callback — but an unhandled rejection reaches `window.onerror`
+    // and whatever error tracker the app has wired to it. Clicking through links
+    // faster than the animation reported a stream of errors describing an
+    // animation the browser skipped on purpose.
+    void _vt?.ready?.catch(() => {});
+    void _vt?.finished?.catch(() => {});
+  } else {
+    _swap(); // reduced-motion (or unsupported): swap instantly, no cross-page animation
+  }
 
   if (push) _pushHistoryEntry(href);
   const incomingTitle = doc.querySelector("title");
@@ -2819,6 +3029,32 @@ function _setupPrefetch(): void {
     },
     { passive: true },
   );
+
+  // `flow:navigate.down` — prefetch on pointer-down, with no dwell.
+  //
+  // The middle setting between "never" and "every link the pointer crosses".
+  // Hover prefetch is free speed on a handful of stable links and the opposite
+  // on a dense list: moving the pointer down a table of a hundred rows asks the
+  // server for a hundred pages, none of which anyone chose. Pointer-down fires
+  // once, on the link the reader has committed to, and still beats the click by
+  // however long the button stays held — around 100ms of ordinary human timing,
+  // which is most of a fast page render.
+  //
+  // `pointerdown` rather than `mousedown` so a touch lands here too, and it is
+  // passive because this never calls preventDefault — the click that follows is
+  // handled by the navigation listener as usual, and finds the page waiting in
+  // the cache.
+  document.addEventListener(
+    "pointerdown",
+    (e) => {
+      const a = (e.target as Element).closest?.(
+        "a[flow\\:navigate\\.down]",
+      ) as HTMLAnchorElement | null;
+      const href = a ? sameOrigin(a) : null;
+      if (href) _prefetch(href);
+    },
+    { passive: true },
+  );
 }
 
 function _setupNavigationLinks(): void {
@@ -3252,7 +3488,7 @@ function _scanComponents(): void {
     _setupPolling(comp);
     _setupIntersect(comp);
     _setupSort(comp);
-    _setupEchoListeners(comp);
+    _setupSocketListeners(comp);
     _setupPresence(comp);
     _setupShared(comp);
 
@@ -3318,7 +3554,7 @@ function _cleanupDisconnected(): void {
         obs.disconnect();
         _lazyObservers.delete(id);
       }
-      _teardownEchoListeners(id);
+      _teardownSocketListeners(id);
       _teardownPresence(id);
       _teardownShared(id);
       _optOps.delete(id);
@@ -3327,61 +3563,95 @@ function _cleanupDisconnected(): void {
   }
 }
 
-// ── Real-time @on('echo:…') listeners ─────────────────────────────────────────
+// ── Real-time @on('socket:…') listeners ───────────────────────────────────────
 //
-// A listener whose event name is `echo:CHANNEL,EVENT` (or echo-private: /
-// echo-presence:) subscribes to a broadcast channel via the global `window.Echo`
-// (the standard broadcast client the app configures). When the broadcast
+// A listener whose event name is `socket:CHANNEL,EVENT` (or socket-private: /
+// socket-presence:) subscribes to a broadcast channel. When the broadcast
 // arrives, the component's @on method runs server-side via a normal action frame —
-// so a broadcast updates the component exactly like any other event. No-op when
-// `window.Echo` is absent.
+// so a broadcast updates the component exactly like any other event.
+//
+// The client is bundled into this runtime and created on first use, so a page
+// that declares a listener is live without the app shipping any script. That is
+// not a convenience: these subscriptions used to be *silently inert* when the
+// global was missing — no error, no warning — so a live feature with no script
+// looked exactly like a live feature that was never written. An app that needs a
+// configured client (a different host, its own auth endpoint) still sets
+// `window.Socket` itself before the runtime loads, and that one wins.
+
+/**
+ * The broadcast client: whatever the app published, or one made on demand.
+ *
+ * Constructed on first use rather than at load, so an app with no realtime
+ * feature never opens a second connection. `new Socket()` needs no arguments in
+ * a browser — it derives its URL from `location` and posts to
+ * `/broadcasting/auth` — which is exactly the wiring every app was writing by
+ * hand.
+ */
+function _socketClient(): SocketClient {
+  const w = window as unknown as { Socket?: SocketClient };
+  return (w.Socket ??= new BundledSocket() as unknown as SocketClient);
+}
+
+/**
+ * The client, but only if one already exists.
+ *
+ * Teardown and whisper paths use this: creating a connection in order to leave a
+ * channel, or to whisper on a page that never joined one, would open a socket to
+ * do nothing with it.
+ */
+function _existingSocketClient(): SocketClient | undefined {
+  return (window as unknown as { Socket?: SocketClient }).Socket;
+}
 
-type EchoSub = { channel: string; kind: "" | "-private" | "-presence" };
-const _echoSubs = new Map<string, EchoSub[]>();
+type SocketSub = { channel: string; kind: "" | "-private" | "-presence" };
+const _socketSubs = new Map<string, SocketSub[]>();
 
-/** Parse `echo[-private|-presence]:channel,event` → parts, or null if not an echo listener. @internal */
-export function _parseEchoListener(
+/** Parse `socket[-private|-presence]:channel,event` → parts, or null if not a socket listener. @internal */
+export function _parseSocketListener(
   name: string,
-): { kind: EchoSub["kind"]; channel: string; event: string } | null {
-  const m = /^echo(-private|-presence)?:/.exec(name);
+): { kind: SocketSub["kind"]; channel: string; event: string } | null {
+  const m = /^socket(-private|-presence)?:/.exec(name);
   if (!m) return null;
-  const kind = (m[1] ?? "") as EchoSub["kind"];
+  const kind = (m[1] ?? "") as SocketSub["kind"];
   const rest = name.slice(m[0].length);
   const ci = rest.lastIndexOf(","); // split on the LAST comma (channels may contain dots, not commas)
   if (ci === -1) return null;
   return { kind, channel: rest.slice(0, ci), event: rest.slice(ci + 1) };
 }
 
-interface EchoChannel {
-  listen(event: string, cb: (payload: unknown) => void): EchoChannel;
-  here?(cb: (payload: unknown) => void): EchoChannel;
-  joining?(cb: (payload: unknown) => void): EchoChannel;
-  leaving?(cb: (payload: unknown) => void): EchoChannel;
+interface SocketChannel {
+  listen(event: string, cb: (payload: unknown) => void): SocketChannel;
+  here?(cb: (payload: unknown) => void): SocketChannel;
+  joining?(cb: (payload: unknown) => void): SocketChannel;
+  leaving?(cb: (payload: unknown) => void): SocketChannel;
 }
-interface EchoClient {
-  channel(name: string): EchoChannel;
-  private(name: string): EchoChannel;
-  join(name: string): EchoChannel;
+interface SocketClient {
+  channel(name: string): SocketChannel;
+  private(name: string): SocketChannel;
+  join(name: string): SocketChannel;
   leave(name: string): void;
 }
 
-function _setupEchoListeners(comp: FlowComponent): void {
-  const Echo = (window as unknown as { Echo?: EchoClient }).Echo;
+function _setupSocketListeners(comp: FlowComponent): void {
+  // The snapshot decides whether this page needs a connection at all — asking
+  // for the client first would open one on every page, including the ones with
+  // nothing to subscribe to.
   const listeners = comp.snapshot.memo.listeners;
-  if (!Echo || !listeners) return;
+  if (!listeners) return;
+  const client = _socketClient();
 
-  const subs: EchoSub[] = [];
+  const subs: SocketSub[] = [];
   for (const [name, method] of Object.entries(listeners)) {
-    const parsed = _parseEchoListener(name);
+    const parsed = _parseSocketListener(name);
     if (!parsed) continue;
     const { kind, channel, event } = parsed;
 
     const ch =
       kind === "-private"
-        ? Echo.private(channel)
+        ? client.private(channel)
         : kind === "-presence"
-          ? Echo.join(channel)
-          : Echo.channel(channel);
+          ? client.join(channel)
+          : client.channel(channel);
 
     const cb = (payload: unknown) => _callAction(comp, method, [payload]);
     // Presence sub-events (here/joining/leaving) use their own methods; everything
@@ -3393,43 +3663,43 @@ function _setupEchoListeners(comp: FlowComponent): void {
     }
     subs.push({ channel, kind });
   }
-  if (subs.length) _echoSubs.set(comp.id, subs);
+  if (subs.length) _socketSubs.set(comp.id, subs);
 }
 
-function _teardownEchoListeners(id: string): void {
-  const Echo = (window as unknown as { Echo?: EchoClient }).Echo;
-  const subs = _echoSubs.get(id);
-  if (Echo && subs)
+function _teardownSocketListeners(id: string): void {
+  const client = _existingSocketClient();
+  const subs = _socketSubs.get(id);
+  if (client && subs)
     for (const s of subs) {
       try {
-        Echo.leave(s.channel);
+        client.leave(s.channel);
       } catch {
         /* ignore */
       }
     }
-  _echoSubs.delete(id);
+  _socketSubs.delete(id);
 }
 
 // ── @presence channels ────────────────────────────────────────────────────────
 // A component with @presence props carries its resolved channel(s) in memo.presence.
 // Join each presence channel and, on here/joining/leaving, dispatch `$presence` so the
 // server refills the member list and re-renders. Cursors/ephemeral state ride the same
-// channel via Echo whispers (see _presenceChannelFor / whisper helpers below).
+// channel via client whispers (see _presenceChannelFor / whisper helpers below).
 
-interface PresenceEchoChannel extends EchoChannel {
-  whisper?(event: string, data: unknown): PresenceEchoChannel;
-  listenForWhisper?(event: string, cb: (data: unknown) => void): PresenceEchoChannel;
+interface PresenceSocketChannel extends SocketChannel {
+  whisper?(event: string, data: unknown): PresenceSocketChannel;
+  listenForWhisper?(event: string, cb: (data: unknown) => void): PresenceSocketChannel;
 }
 const _presenceChannels = new Map<string, string[]>(); // componentId → joined channels
 
 function _setupPresence(comp: FlowComponent): void {
-  const Echo = (window as unknown as { Echo?: EchoClient }).Echo;
   const presence = comp.snapshot.memo.presence;
-  if (!Echo || !presence || presence.length === 0) return;
+  if (!presence || presence.length === 0) return;
+  const client = _socketClient();
 
   const channels: string[] = [];
   for (const { channel } of presence) {
-    const ch = Echo.join(channel);
+    const ch = client.join(channel);
     const refresh = (): void => _callAction(comp, "$presence", []);
     ch.here?.(refresh);
     ch.joining?.(refresh);
@@ -3440,12 +3710,12 @@ function _setupPresence(comp: FlowComponent): void {
 }
 
 function _teardownPresence(id: string): void {
-  const Echo = (window as unknown as { Echo?: EchoClient }).Echo;
+  const client = _existingSocketClient();
   const channels = _presenceChannels.get(id);
-  if (Echo && channels)
+  if (client && channels)
     for (const c of channels) {
       try {
-        Echo.leave(c);
+        client.leave(c);
       } catch {
         /* ignore */
       }
@@ -3461,21 +3731,21 @@ function _presenceChannelFor(comp: FlowComponent): string | null {
 /**
  * Broadcast ephemeral state (e.g. a cursor position) to the other members of the
  * component's presence channel — client-only, never hits the server or the DB. Pair with
- * `onWhisper`. No-op without `window.Echo` or a presence channel.
+ * `onWhisper`. No-op without `window.client` or a presence channel.
  */
 function _whisper(comp: FlowComponent, event: string, data: unknown): void {
-  const Echo = (window as unknown as { Echo?: EchoClient }).Echo;
+  const client = _existingSocketClient();
   const channel = _presenceChannelFor(comp);
-  if (!Echo || !channel) return;
-  (Echo.join(channel) as PresenceEchoChannel).whisper?.(event, data);
+  if (!client || !channel) return;
+  (client.join(channel) as PresenceSocketChannel).whisper?.(event, data);
 }
 
 /** Listen for peers' whispers on the component's presence channel (e.g. cursor moves). */
 function _onWhisper(comp: FlowComponent, event: string, cb: (data: unknown) => void): void {
-  const Echo = (window as unknown as { Echo?: EchoClient }).Echo;
+  const client = _existingSocketClient();
   const channel = _presenceChannelFor(comp);
-  if (!Echo || !channel) return;
-  (Echo.join(channel) as PresenceEchoChannel).listenForWhisper?.(event, cb);
+  if (!client || !channel) return;
+  (client.join(channel) as PresenceSocketChannel).listenForWhisper?.(event, cb);
 }
 
 // ── @task cancellation ─────────────────────────────────────────────────────────
@@ -3503,32 +3773,32 @@ function _cancelTask(comp: FlowComponent): void {
 // A component with @shared props carries its resolved channel(s) in memo.shared. Join each
 // channel and, on the `flow:shared` broadcast, dispatch `$shared` so the server re-reads
 // the room store and re-renders — every subscriber converges to the same state. Shared and
-// presence channels are joined the same way (Echo.join), so one room channel can carry both.
+// presence channels are joined the same way (client.join), so one room channel can carry both.
 
 const SHARED_EVENT = "flow:shared";
 const _sharedChannels = new Map<string, string[]>(); // componentId → joined channels
 
 function _setupShared(comp: FlowComponent): void {
-  const Echo = (window as unknown as { Echo?: EchoClient }).Echo;
   const shared = comp.snapshot.memo.shared;
-  if (!Echo || !shared || shared.length === 0) return;
+  if (!shared || shared.length === 0) return;
+  const client = _socketClient();
 
   const channels: string[] = [];
   for (const { channel } of shared) {
     const converge = (): void => _callAction(comp, "$shared", []);
-    Echo.join(channel).listen(SHARED_EVENT, converge);
+    client.join(channel).listen(SHARED_EVENT, converge);
     channels.push(channel);
   }
   if (channels.length) _sharedChannels.set(comp.id, channels);
 }
 
 function _teardownShared(id: string): void {
-  const Echo = (window as unknown as { Echo?: EchoClient }).Echo;
+  const client = _existingSocketClient();
   const channels = _sharedChannels.get(id);
-  if (Echo && channels)
+  if (client && channels)
     for (const c of channels) {
       try {
-        Echo.leave(c);
+        client.leave(c);
       } catch {
         /* ignore */
       }