@zerotal/arch 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -7,6 +7,63 @@ All notable changes to this package are documented here. The format is
 **Maturity: beta.** The API is close to final and breaking changes are rare, called out
 here with migration steps — but a minor release may still contain one.
 
+## [Unreleased]
+
+## [1.7.1] — 2026-08-16
+
+### Fixed
+
+Faults that only appear once the surface is installed into a real app, found by installing
+it into this repo's own `apps/docs` and calling every tool.
+
+- **`search_docs` ranked a generated page above the right answer.** Scoring was raw term
+  frequency weighted by field, with no length normalisation — so `components.md`, one
+  generated page covering 53 components and long enough to mention nearly everything, came
+  first for both "send an email" and "how do I write a test for a controller". Now BM25 over
+  a small inverted index built when the corpus is read: length normalisation, inverse
+  document frequency and term saturation, with title/description/heading matches scored as
+  separate fields _outside_ the saturation, since folded in BM25 flattens a title hit to
+  about twice a passing mention. Plus light stemming, so "test" meets "testing", and
+  hyphenated terms indexed whole and in parts, so "soft deletes" finds `soft-delete`.
+
+  Measured on fourteen questions an agent would actually ask, top-1 relevance went from
+  roughly three in ten to twelve in fourteen. The remaining two return related pages rather
+  than the best one; tuning further against a list that size fits the list, not the corpus.
+
+- **`last_error` dropped the error.** The framework logs an exception's class in `error`,
+  its trace in `stack` and the request it belongs to in `requestId`. The parser named the
+  six fields it knew about and discarded the rest, so the tool whose entire job is saying
+  _why_ something failed returned the generic `"Unhandled error"` that wraps the real one —
+  a line that says nothing. Entries now carry every field the logger wrote, and
+  `last_error` renders the exception, the request id and the trace. `logs` shows the first
+  two but not the trace: a stack on each of two hundred entries buries the sequence the
+  caller asked for.
+
+- **`baselines` reported a ceiling smaller than the command's count, without saying so.**
+  The cast baseline ratchets per file and exempts designated boundary modules, so it reads
+  455 where `cast:check` prints 466. A reader comparing the two saw debt that had appeared
+  between them. The reading now carries a `note` naming the exempt modules.
+
+- **Packages in a workspace were invisible.** `node_modules/@zerotal/*` is a symlink in
+  every workspace — this monorepo, `bun link`, any app developed against a checkout — and
+  `Bun.Glob` will not descend into one, `followSymlinks` or not. `installedPackages()`
+  returned nothing for an app with seventeen packages, so `app_info` reported an empty list
+  and `arch:install` wrote generic guidance with none of the per-package sections that are
+  the reason it is composed rather than canned. Listed with `readdir` now, which sees the
+  link, and read through `Bun.file`, which follows it.
+
+- **The generated Markdown failed the formatter.** `arch:install` wrote files that did not
+  pass the `prettier --check .` the project it had just installed into already runs. The
+  markers now sit on their own lines with blank lines around them — which is correctness
+  before it is formatting, since Markdown parses text pressed against an HTML comment as
+  part of that raw-HTML block.
+
+- **`arch:update` fought the formatter over `.mcp.json`.** `JSON.stringify(…, 2)` expands a
+  one-element array where a formatter collapses it, so the command rewrote a file it had no
+  change to make to, and the next `prettier --write` put it back. Idempotence is now
+  measured on the parsed data: when the config already says what it should, the file is
+  returned exactly as it was found, in whatever shape its owner keeps it.
+
 ## [1.7.0] — 2026-08-16
 
 ### Added

package/docs/broadcasting/channels.md

@@ -122,7 +122,7 @@ the wire; a Pusher-protocol client surfaces them to your code under the `pusher:
 
 > **Note** — The native `ws`/`redis` drivers use the equivalent
 > `subscription_succeeded` / `presence:member_added` / `presence:member_removed` events; the
-> first-party `Socket` client maps them to Echo's `here`/`joining`/`leaving` callbacks for you.
+> first-party `Socket` client maps them to Socket's `here`/`joining`/`leaving` callbacks for you.
 
 ## Typed channels
 

package/docs/broadcasting/client.md

@@ -9,8 +9,20 @@ description: Subscribe from the browser and react to events as they arrive.
 
 `@zerotal/client` ships a small, dependency-free `Socket` that speaks the native broadcast
 protocol and exposes a familiar realtime-client API — no external client library, and it works
-with the lightweight `ws` and `redis` drivers (no Pusher credentials needed). It's also a drop-in
-for `window.Echo`, so Flow's [`@on('echo:…')`](/docs/flow/events) listeners work against it.
+with the lightweight `ws` and `redis` drivers (no Pusher credentials needed).
+
+**Flow apps need none of this.** The client is bundled into `/__flow/runtime.js` and created the
+first time a page declares a [`@on('socket:…')`](/docs/flow/events) listener, so those listeners
+are live with no script of your own. Read on only if you want a configured client — a different
+host, your own auth endpoint — or if you are subscribing from code that is not a Flow component.
+
+> **The package root is fine to import in browser code.** It used to be a bundle error: the root
+> also exports `ClientProvider`, which reaches the CLI commands and `await import("bun")`, and a
+> browser bundler rejects that during resolution — before tree-shaking can discard the half you
+> did not want. `@zerotal/client` now resolves to a browser-safe entry under the `browser`
+> condition, so a bundler gets `Socket`, `ApiClient` and `CircuitBreaker` and none of the
+> server-side exports. `@zerotal/client/Socket` still works and is still the leanest import if
+> `Socket` is all you need.
 
 ```ts
 // in your client code
@@ -34,8 +46,9 @@ socket
   .leaving((m) => removeOnline(m))
   .listen("Message", (e) => append(e));
 
-// Use it as Echo for Flow @on('echo:…') listeners:
-window.Echo = socket;
+// Only if you need Flow's listeners to use *this* client rather than the bundled
+// one — assign before the runtime loads and it is used as-is:
+window.Socket = socket;
 ```
 
 Private and presence channels are authorized with a **per-subscription HMAC signature** (the same

package/docs/broadcasting/events.md

@@ -64,7 +64,7 @@ Broadcast.send(new OrderShipmentStatusUpdated(order));
 ```
 
 `broadcast(event).toOthers()` excludes the connection that triggered the request (read from the
-`X-Socket-ID` header your Echo client sends), so the user who just made an optimistic UI update
+`X-Socket-ID` header your Socket client sends), so the user who just made an optimistic UI update
 doesn't receive a duplicate.
 
 `broadcast()` returns a `PendingBroadcast` — a thenable that sends itself on the next
@@ -181,7 +181,7 @@ The wire event name defaults to `${ModelName}${Event}` (e.g. `OrderUpdated`) and
 
 ```ts
 // in your client code
-Echo.private(`orders.${id}`).listen("OrderUpdated", (e) => render(e.order));
+Socket.private(`orders.${id}`).listen("OrderUpdated", (e) => render(e.order));
 ```
 
 ## Next steps

package/docs/broadcasting/index.md

@@ -50,7 +50,7 @@ The provider exposes one HTTP route and one WebSocket upgrade path:
 
 - `POST /broadcasting/auth` — the private/presence channel auth endpoint (a real `Router` route).
 - The WebSocket upgrade is served at the configured `path` (default `/app/ws`) via Bun's
-  WebSocket handler — it is _not_ a separate `Router` route. Pusher/Echo clients connect to
+  WebSocket handler — it is _not_ a separate `Router` route. Pusher/Socket clients connect to
   `ws://host/app/{appKey}`.
 
 ## Configuration

package/docs/changelog.md

@@ -24,6 +24,52 @@ Each version lists changes under three headings:
 Patch and minor releases are backward compatible. Before taking a **major** release,
 read its section here and apply each migration note.
 
+## 1.7.2 — 2026-08-18
+
+Realtime that works without being wired up, and three ways a socket could go quiet without
+saying so.
+
+### Changed
+
+- **BREAKING — Flow's `@on` broadcast listeners use a `socket:` prefix.** `echo:`,
+  `echo-private:` and `echo-presence:` are now `socket:`, `socket-private:` and
+  `socket-presence:`; the browser global is `window.Socket`, not `window.Echo`. There is no
+  alias — an unrenamed listener never matches, and never subscribes.
+
+  ```diff
+  - @on("echo-private:issues.5,CommentPosted")
+  + @on("socket-private:issues.5,CommentPosted")
+  ```
+
+  Shipped in a patch release deliberately, on the judgement that the old prefix has no
+  meaningful use in the wild. If you are on it, the upgrade is a find-and-replace of `echo:`
+  → `socket:` in your `@on` listeners and `window.Echo` → `window.Socket` in any client code.
+
+### Added
+
+- **Flow bundles the socket client into its runtime.** A page that declares a `socket:`
+  listener is live with no script of your own. Flow apps own no bundle entry, so the contract
+  used to be "publish `window.Socket` yourself" — and when you didn't, the listeners were
+  *silently inert*: no error, no warning, no subscription, so a live feature with no script
+  looked exactly like a live feature that was never written. An app that needs a configured
+  client still assigns `window.Socket` before the runtime loads and that one is used as-is; a
+  page with no listeners opens no connection at all.
+
+### Fixed
+
+- **A patch no longer writes back into a file input.** A file input's `value` belongs to the
+  user agent, and assigning anything but `""` throws `InvalidStateError`. The write was legal
+  while the bound property was empty and threw on the very patch carrying an upload's result
+  — and the throw escaped the frame handler, so the DOM never updated *and* the action's ack
+  never resolved. Since frames are chained per component, every later action queued behind a
+  promise that would never settle: the page rendered correctly and ignored every click for
+  the rest of its life.
+
+- **WebSocket connections get an explicit 120s `idleTimeout`.** Bun closes an idle socket
+  after 10 seconds; the client pings every 30. A connection that was merely quiet got cut
+  before it had reason to speak, taking its channel subscriptions with it — so anyone who had
+  been reading a page for more than ten seconds silently stopped receiving broadcasts.
+
 ## 1.7.0 — 2026-08-16
 
 The agent surface, a DevTools panel that shows the framework and not just the last request,

package/docs/commands.md

@@ -210,23 +210,32 @@ running, restarting, or has given up:
 ─────────────────────────────────────────────────
  GET / 200 4ms
  GET /posts 200 11ms
- 1-9 tab · ←/→ cycle · r restart · c clear · / search · t time · s stream · q quit
+ 1-9 tab · ←/→ cycle · ↑/↓ scroll · r restart · c clear · / search · t time · s stream · q quit
 ```
 
-| Key           | Does                                                             |
-| ------------- | ---------------------------------------------------------------- |
-| `1`–`9`       | Select that tab                                                  |
-| `←` `→` `Tab` | Cycle through tabs                                               |
-| `r`           | Restart the focused process                                      |
-| `c`           | Clear the focused tab's output                                   |
-| `/`           | Search within the focused tab (`Enter` keeps it, `Esc` drops it) |
-| `t`           | Toggle per-line timestamps                                       |
-| `s`           | Switch to stream mode                                            |
-| `PgUp` `PgDn` | Scroll the focused tab                                           |
-| `q`           | Quit — stops every process and restores your shell               |
+| Key           | Does                                                              |
+| ------------- | ----------------------------------------------------------------- |
+| `1`–`9`       | Select that tab                                                   |
+| `←` `→` `Tab` | Cycle through tabs                                                |
+| `↑` `↓`       | Scroll the focused tab a line at a time — as does the mouse wheel |
+| `PgUp` `PgDn` | Scroll it a screen at a time                                      |
+| `Home` `End`  | Jump to the oldest line, or back to the newest                    |
+| `r`           | Restart the focused process                                       |
+| `c`           | Clear the focused tab's output                                    |
+| `/`           | Search within the focused tab (`Enter` keeps it, `Esc` drops it)  |
+| `t`           | Toggle per-line timestamps                                        |
+| `s`           | Switch to stream mode                                             |
+| `q`           | Quit — stops every process and restores your shell                |
 
 Scrollback belongs to the deck rather than to your terminal, which is what makes
 per-tab history and search possible. It keeps the last 5,000 lines per process.
+Your terminal's own scrollbar does nothing while the deck is up — it has no
+history to move, because the deck holds it all. Use the keys above (or the
+wheel, which the terminal sends the deck as `↑`/`↓`).
+
+Scrolling up parks the view where you left it: the process behind the tab keeps
+printing, but what you stopped to read stays on screen until you scroll back
+down to the newest line.
 
 **A process that dies never takes the server with it.** It restarts on its own —
 three times, backing off between attempts — and if it still will not start, that

package/docs/flow/components.md

@@ -29,6 +29,13 @@ import { Link } from "@zerotal/flow";
   Posts
 </Link>;
 
+{
+  /* Prefetch on pointer-down instead — for a row in a long list */
+}
+<Link href="/posts/42" down>
+  One post
+</Link>;
+
 {
   /* Disable automatic data-current (e.g. always-active home links) */
 }
@@ -37,6 +44,14 @@ import { Link } from "@zerotal/flow";
 </Link>;
 ```
 
+Choose between `hover` and `down` by how many of the link there are. `hover` prefetches after a
+short dwell, which is free speed on a handful of stable links — a navigation rail, a breadcrumb.
+On a dense list it inverts: the pointer crosses every row between where it is and where it is
+going, so scrolling a hundred-row table asks the server for a hundred pages nobody chose. `down`
+fires on `pointerdown` instead — once, on the link the reader has committed to, and still ahead
+of the click by however long the button is held. Both may be set; the target is fetched once and
+cached either way.
+
 `data-current` matches by **prefix** — a link to `/posts` stays active on `/posts/42` — which is what you want for a section parent. For an index link that should be active only on its own exact URL (an "Overview" tab that shouldn't light up on the section's sub-pages), add `exact`:
 
 ```tsx
@@ -456,6 +471,14 @@ import { Tabs } from "@zerotal/flow";
 
 `<Tabs>` emits `role="tablist"` / `"tab"` / `"tabpanel"` with roving arrow-key navigation.
 
+> **Note** — selection is client-only and not addressable. The active tab lives in Alpine state,
+> always starts on the first item, and there is no prop to bind or read it, so `?tab=settings`
+> cannot be made to work and the back button does not step between panels. The tab strip's own
+> classes are fixed (`border-gray-800`, `text-white`, `border-indigo-500`); only the outer wrapper
+> takes `class`, so on a light surface the selected tab is white on white. For a tab set that has
+> to be linkable or has to match a design system, drive the panels from a `@url` property and
+> write the strip out — it is a dozen lines, and you keep both.
+
 ## File upload component
 
 ### FileUpload + FileUploads mixin

package/docs/flow/decorators.md

@@ -133,9 +133,13 @@ You can also pass rules directly to `this.validate()` — they override the deco
 
 ### Real-time validation
 
-When a `@validate` field is bound with `flow:model.live` (or `.blur`), each change is validated on
+When a `@validate` field is bound `live` (or `blur`), each change is validated on
 the server as it arrives. The field's error appears (and clears)
-as the user edits, with no action call and without affecting any other field:
+as the user edits, with no action call and without affecting any other field.
+
+> **Note** — `live` is the prop you write; `flow:model.live` is what it compiles to. The compiled
+> form is not writable in TSX: the `.` in an attribute name is a parse error (`TS1003`), so
+> copying it out of the emitted HTML into a component will not build.
 
 ```tsx
 @expose @validate((rule) => rule.required().email()) email = "";
@@ -143,7 +147,7 @@ as the user edits, with no action call and without affecting any other field:
 async render() {
   return (
     <div>
-      <input type="email" value={this.email} flow:model.live />
+      <input type="email" value={this.email} live />
       <span error={this.errors.email} />
     </div>
   );
@@ -289,11 +293,18 @@ async refreshUser(data: { userId: number }): Promise<void> {
 }
 
 // Listen for real-time WebSocket broadcasts (see Events doc for channel formats)
-@on("echo:orders,OrderPlaced")
+@on("socket:orders,OrderPlaced")
 async onOrderPlaced(payload: { id: number }): Promise<void> {
   this.orderCount++;
   this.flash("New order received!", "success");
 }
+
+// A channel naming a record needs a resolver — the string form is read off the
+// class, so `"socket:orders.${this.id},…"` would subscribe to that literal text.
+@on((self) => `socket-private:orders.${self.orderId},OrderCancelled`)
+async onOrderCancelled(payload: { id: number }): Promise<void> {
+  this.orderCount--;
+}
 ```
 
 See [Events & Broadcasting](/docs/flow/events) for dispatch methods, targeting, broadcasting, and native event integration.
@@ -385,7 +396,8 @@ See [Layouts & Composition](/docs/flow/layouts#two-way-props) for the full `@mod
 | `@expose method`                                | Callable from the browser via WebSocket                               |
 | `@expose @renderless method`                    | Callable from browser; skips re-render cycle                          |
 | `@on("event") method`                           | Listens for cross-component events (auto-exposed)                     |
-| `@on("echo:channel,Event") method`              | Listens for real-time server broadcasts                               |
+| `@on("socket:channel,Event") method`              | Listens for real-time server broadcasts                               |
+| `@on((self) => "socket:…") method`                | Same, with the channel resolved per instance (record ids)             |
 | `@reactive prop`                                | Child prop; parent re-pushes on change, child re-renders              |
 | `@modelable prop`                               | Two-way child prop; writes from child flow back to parent             |
 

package/docs/flow/events.md

@@ -178,7 +178,7 @@ async onPostCreated(data: EventPayload<"post-created">) {
 }
 ```
 
-Adoption is gradual and non-breaking: any event name **not** in the contract stays untyped (a plain optional-payload call), so existing events and `@on("echo:…")` broadcasts keep compiling — you type the ones you care about, when you care about them.
+Adoption is gradual and non-breaking: any event name **not** in the contract stays untyped (a plain optional-payload call), so existing events and `@on("socket:…")` broadcasts keep compiling — you type the ones you care about, when you care about them.
 
 **Runtime guard (optional).** The types cover your own dispatch sites at compile time. For a payload that arrives from an untrusted source — a client-originated dispatch — register a runtime guard; a violating payload then throws from `dispatch` instead of reaching listeners:
 
@@ -231,7 +231,9 @@ When a child component just needs to invoke a parent action, use `$flow.parent`
 
 ## Real-time broadcasting
 
-Listen for server-broadcast events over WebSockets with `@on("echo:…")`. When a matching broadcast arrives, the listener method runs server-side exactly like any other action — the component re-renders live.
+Listen for server-broadcast events over WebSockets with `@on("socket:…")`. When a matching broadcast arrives, the listener method runs server-side exactly like any other action — the component re-renders live.
+
+The socket client is bundled into the Flow runtime and created the first time a page declares one of these listeners, so there is no script to add and nothing to publish on `window`. An app that needs a configured client — a different host, its own auth endpoint — assigns `window.Socket` before the runtime loads and that one is used instead. Pages with no such listener open no broadcast connection at all.
 
 ```typescript
 export class OrderDashboard extends Component {
@@ -243,7 +245,7 @@ export class OrderDashboard extends Component {
     this.recentOrders = await Order.query().orderBy("created_at", "desc").limit(5).get();
   }
 
-  @on("echo:orders,OrderPlaced")
+  @on("socket:orders,OrderPlaced")
   async onOrderPlaced(payload: { id: number; total: number }): Promise<void> {
     this.orderCount++;
     const order = await Order.findOrFail(payload.id);
@@ -251,7 +253,7 @@ export class OrderDashboard extends Component {
     this.flash(`New order — $${payload.total}`, "success");
   }
 
-  @on("echo-private:orders.${this.branchId},OrderCancelled")
+  @on((self) => `socket-private:orders.${self.branchId},OrderCancelled`)
   async onOrderCancelled(payload: { id: number }): Promise<void> {
     this.recentOrders = this.recentOrders.filter((o) => o.id !== payload.id);
     this.orderCount   = Math.max(0, this.orderCount - 1);
@@ -276,29 +278,61 @@ export class OrderDashboard extends Component {
 
 | Format                             | Channel type                            |
 | ---------------------------------- | --------------------------------------- |
-| `echo:channel,Event`               | Public channel                          |
-| `echo-private:channel,Event`       | Private channel (requires auth)         |
-| `echo-presence:room,joining`       | Presence channel — member joined        |
-| `echo-presence:room,leaving`       | Presence channel — member left          |
-| `echo-presence:room,here`          | Presence channel — initial member list  |
-| `echo:teams.1.threads,MessageSent` | Dot-separated dynamic/nested channel    |
-| `echo:scores,.score.submitted`     | Custom `broadcastAs` name (leading dot) |
+| `socket:channel,Event`               | Public channel                          |
+| `socket-private:channel,Event`       | Private channel (requires auth)         |
+| `socket-presence:room,joining`       | Presence channel — member joined        |
+| `socket-presence:room,leaving`       | Presence channel — member left          |
+| `socket-presence:room,here`          | Presence channel — initial member list  |
+| `socket:teams.1.threads,MessageSent` | Dot-separated dynamic/nested channel    |
+| `socket:scores,.score.submitted`     | Custom `broadcastAs` name (leading dot) |
 
 The part before the comma is the channel name; the part after is the event name. For presence channels, `joining`, `leaving`, and `here` are the built-in presence event names.
 
+### Per-instance channels
+
+A channel that names a record — `issues.417`, `orders.8` — cannot be written as a string. The
+decorator's argument is read off the **class**, before any instance exists, so a template literal
+inside a plain string is not interpolated: `@on("socket-private:issues.${this.issueId},CommentPosted")`
+subscribes to a channel whose name contains those characters, and receives nothing.
+
+Pass a resolver instead. It is called with the component when the snapshot is built, exactly as
+[`@presence`](#presence--whos-here-multiplayer) and [`@shared`](#shared-state--everyone-converges-multiplayer)
+resolve theirs:
+
+```typescript
+export class IssuePage extends Component {
+  @locked issue!: Issue;
+  @locked comments: Comment[] = [];
+
+  @on((self) => `socket-private:issues.${self.issue.id},CommentPosted`)
+  async onCommentPosted(payload: { comment: Comment }): Promise<void> {
+    this.comments = [...this.comments, payload.comment];
+  }
+}
+```
+
+The resolver runs once per render, after `onMount()`, so it can read anything the component has
+loaded. If it throws — a field it reads is still null, say — that one listener is dropped and the
+page renders without it, rather than the render failing.
+
+Resolve the *narrowest* channel the reader is entitled to. A static `issues` channel with an
+`if (payload.issueId !== this.issue.id) return` in the handler looks equivalent and is not: the
+broadcast still reaches every subscriber's browser, so every reader receives every issue's
+comment bodies and discards them after the fact.
+
 ### Requirements
 
-Broadcasting requires a global `window.Echo` client configured by your application — the first-party `@zerotal/client` `Socket`, or any compatible realtime client. Flow subscribes through it on component mount and unsubscribes on teardown.
+Broadcasting requires a global `window.Socket` client configured by your application — the first-party `@zerotal/client` `Socket`, or any compatible realtime client. Flow subscribes through it on component mount and unsubscribes on teardown.
 
-If `window.Echo` is not present, all `echo:` listeners are silently inert — no errors, no subscriptions attempted.
+If `window.Socket` is not present, all `socket:` listeners are silently inert — no errors, no subscriptions attempted.
 
 ```typescript
 // In your frontend bootstrap (app.ts or similar):
 import { Socket } from "@zerotal/client";
 
 // The first-party Socket speaks Zerotal's native broadcast protocol and is a
-// drop-in for `window.Echo` — no external client library or Pusher credentials.
-window.Echo = new Socket();
+// drop-in for `window.Socket` — no external client library or Pusher credentials.
+window.Socket = new Socket();
 ```
 
 ## Presence — who's here (multiplayer)
@@ -345,7 +379,7 @@ Broadcast.channel("board.[boardId]", (user, boardId) =>
 
 Whispers are client-only (they ride the presence channel directly), so they're instant and don't count as component round-trips.
 
-Like all `echo:` features, presence needs a `window.Echo` client configured (above). Without it, `@presence` props stay empty and whispers are inert — no errors.
+Like all `socket:` features, presence needs a `window.Socket` client configured (above). Without it, `@presence` props stay empty and whispers are inert — no errors.
 
 ## Shared state — everyone converges (multiplayer)
 
@@ -370,7 +404,7 @@ The mental model: a `@shared` prop is a **cache of a server-side room value**, n
 
 Like `@presence`, the channel is resolved on the server (signed in the snapshot, unforgeable) and the prop is server-controlled (`@locked`): clients render it but change it only through `@expose` actions. Authorize the channel in `routes/channels.ts` exactly as for presence.
 
-Broadcasting is an **optional peer**. With `window.Echo` and `BroadcastProvider` configured, changes fan out to every open window; without them, `@shared` still converges within a single window's own round-trips, because the room store is server-side either way. For multi-instance deployments, swap the in-process store for a shared backend with `setSharedStore(store)` (any `{ get, set, has }`), e.g. Redis-backed — the convergence logic is unchanged.
+Broadcasting is an **optional peer**. With `window.Socket` and `BroadcastProvider` configured, changes fan out to every open window; without them, `@shared` still converges within a single window's own round-trips, because the room store is server-side either way. For multi-instance deployments, swap the in-process store for a shared backend with `setSharedStore(store)` (any `{ get, set, has }`), e.g. Redis-backed — the convergence logic is unchanged.
 
 > v1 semantics are last-write-wins and server-authoritative; `@shared` props should hold plain, serializable data (arrays/objects), like snapshot state generally. The originating window also receives its own change broadcast as an idempotent no-op re-read (self-exclusion is a planned refinement).
 

package/docs/flow/index.md

@@ -135,6 +135,13 @@ component in the project is covered — the Flow scaffold already writes this:
 > runtime need a `/** @jsxImportSource … */` comment of their own — which is why
 > `make:flow` writes one into every class it generates.
 
+> **Note** — Flow components and `zerotal/view` components do not interoperate, and the failure
+> is a type error rather than a wrong render. The two JSX runtimes produce different element
+> types: a view `FC` returns `SafeHtml` (`{ value }`) and Flow's JSX expects `HtmlNode`
+> (`{ html }`), so using one inside the other is `TS2786: 'Box' cannot be used as a JSX
+> component`. A shared component library has to target one runtime; share class-name constants
+> or plain strings across the two instead of components.
+
 ### Your first component
 
 ```tsx
@@ -563,6 +570,6 @@ Flow is a large surface. Each section below is its own page.
 - [Validator](/docs/validator) — the full rule chain behind `@validate` and `this.validate()`.
 - [Middleware](/docs/middleware) — write the guards you attach to Flow routes.
 - [Session](/docs/session) — the store behind `@session` and `SessionMiddleware`.
-- [Broadcasting](/docs/broadcasting) — drive `@on("echo:…")` real-time updates from the server.
+- [Broadcasting](/docs/broadcasting) — drive `@on("socket:…")` real-time updates from the server.
 - [Storage](/docs/storage) — configure the disks that file uploads write to.
 - [Testing](/docs/testing/index) — patterns for the `FlowTest` harness and the rest of the suite.

package/docs/flow/layouts.md

@@ -143,6 +143,22 @@ override async render() {
 }
 ```
 
+### The document's `lang` is fixed
+
+Flow assembles the outer document itself and emits `<html lang="en">`, and a `Layout` has no hook to
+change it. `head` injects into `<head>`; the `<html>` attributes are not reachable from a layout.
+
+For a localised app, put `lang` (and any locale-dependent class) on the layout's own wrapper element.
+Both are valid on a `div` and apply to every descendant, so the *content* is correctly marked up —
+but the document still declares English to anything reading the root element, which is wrong for a
+screen reader announcing the page in the wrong voice:
+
+```tsx
+override render(slot: HtmlNode) {
+  return <div lang={activeLocale()}>{slot}</div>;
+}
+```
+
 ## Sections
 
 A layout owns regions a page cannot reach. When a page needs to put something _there_ — a toolbar

package/docs/flow/performance.md

@@ -33,11 +33,37 @@ It's a graceful degrade, not a mode you configure. WebSocket reconnection keeps
 
 - Each action is a request/response, with no server-pushed frames — so `@task`
   streaming arrives as one batched update rather than token by token.
-- Real-time `@on("echo:…")`, `@presence`, and `@shared` broadcasts are not
+- Real-time `@on("socket:…")`, `@presence`, and `@shared` broadcasts are not
   delivered, because those ride the separate broadcasting socket.
 
 Everything driven by your own actions still works. Nothing is sent over HTTP until the socket has actually failed; the happy path is unchanged.
 
+## What forces the runtime fallback
+
+Every page is AOT-compiled at boot where it can be. A page the compiler cannot handle still works —
+it renders through the standard runtime instead — and Flow logs a count at startup:
+
+```
+N of M Flow pages (75%) render through the runtime fallback instead of compiled output.
+```
+
+Set `ZT_FLOW_COMPILE_LOG=1` to print what blocks each page. The common causes:
+
+| Blocker | Fix |
+| --- | --- |
+| `render()` with more than one `return` | Build the branches into a variable and return once |
+| A function call in a text child — including **`__()`** | See below |
+| An imported child component in `render()` (`<Header/>`) | Inline it, or accept the fallback |
+| `class={someLocalConst}` or a numeric-literal attribute (`rows={3}`) | Use a literal string |
+
+**`__()` is the one that matters most.** A translated template is a function call in a text child,
+so a page that translates a single string falls off the fast path — which in an app where `__()`
+is the house style means every page. The cost is normally just speed, but it is not only speed
+under [`cspSafe`](/docs/flow/components#csp-safe-mode): there, every page **must** compile or the
+build fails, so an app using `__()` in its templates cannot run in CSP-safe mode today. If you need
+`cspSafe`, keep translation out of the template — resolve strings in the action or `onMount()` into
+`@locked` properties and render those.
+
 ## Interaction polish
 
 The perceived speed of a server-driven app comes from three things: never showing

package/docs/flow/references.md

@@ -87,6 +87,7 @@ Visual loading indicators (`showOnLoading`, `hideOnLoading`, `loadingClass`) wai
 | ----------------- | --------------------------------------------------------- | ----------------------------------- |
 | `navigate`        | SPA navigation to `href`, layout stays mounted            | `flow:navigate`                     |
 | `navigate hover`  | Prefetch page on hover (~60ms debounce)                   | `flow:navigate flow:navigate.hover` |
+| `navigate down`   | Prefetch page on pointer-down (no dwell; dense lists)     | `flow:navigate flow:navigate.down`  |
 | `current={false}` | Disable automatic `data-current` attribute                | —                                   |
 | `exact`           | `data-current` only on an exact URL match (not sub-pages) | `flow:current.exact`                |
 
@@ -177,6 +178,20 @@ override async render() {
 
 > A dynamic `sortItem={String(it.id)}` inside a `.map()` renders through the standard runtime (not the AOT fast path) — the drag behaviour is identical either way.
 
+> **The payload does not say which container took the drop.** The client reads `flow:sort` off the
+> container a child was dropped **into** and calls it `(key, index)` — so the destination is
+> encoded in *which method runs*, and nowhere else. For a single sortable list that is invisible.
+> For dragging **between** containers under one `sortGroup` it means one action per container:
+>
+> ```tsx
+> <ul onSort={this.dropInTodo} sortGroup="tasks">…</ul>
+> <ul onSort={this.dropInDone} sortGroup="tasks">…</ul>
+> ```
+>
+> An arrow (`onSort={(k, i) => this.move("todo", k, i)}`) cannot stand in, because the attribute's
+> value is used as a method *name* rather than evaluated. `onSort` accepts the name as a string,
+> so the handlers can come from a lookup table keyed by column, but they must be declared members.
+
 ### DOM utilities
 
 | You write         | Behaviour                                                    | Compiles to     |

package/docs/flow/testing.md

@@ -177,6 +177,38 @@ expect(page.user?.email).toBe("alice@example.com");
 expect(page.totalRevenue).toBe(450.0);
 ```
 
+## No request scope
+
+`FlowTest` drives the server-side pipeline but does **not** open a request context. There is no
+`RequestContext.run` inside it, so anything reaching for the request throws rather than
+returning empty:
+
+- `Auth.user()` → `E_UNAUTHORIZED`
+- `Auth.attempt()` / `Auth.login()` → `E_CONTEXT_OUTSIDE_REQUEST`
+- request-scoped pagination, and any facade that reads `RequestContext`
+
+That covers most actions on any page behind a sign-in, so open the scope yourself. `HttpContext.fake()`
+rather than an object literal cast to the type — it carries a real `Request`, which matters as soon
+as anything downstream reads a header (an audited model records the actor's IP, for one):
+
+```typescript
+import { RequestContext, HttpContext } from "@zerotal/core";
+
+function asUser<T>(user: User | null, fn: () => Promise<T>): Promise<T> {
+  const ctx = HttpContext.fake("http://localhost/");
+  if (user) ctx.user = user;
+  return RequestContext.run(ctx, fn);
+}
+
+await asUser(alice, async () => {
+  const t = await FlowTest.mount(IssuePage, { issue });
+  await t.call("postComment");
+});
+```
+
+`app.actingAs()` does not help here: it encodes a session cookie for `app.get()`, and `FlowTest`
+never makes a request to send it on.
+
 ## Testing with a database
 
 `FlowTest` does not set up or tear down a database — use your test suite's standard database helpers. With Bun, wrap tests in a transaction that rolls back after each test for full isolation: