@zerotal/arch 1.7.0 → 1.7.3

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);
@@ -274,31 +276,63 @@ export class OrderDashboard extends Component {
 
 ### Channel name formats
 
-| 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) |
+| Format                               | Channel type                            |
+| ------------------------------------ | --------------------------------------- |
+| `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
@@ -176,22 +183,26 @@ Router.flow("/counter", CounterPage);
 ### Reserved member names
 
 `Component` brings its own members, and a property of yours that collides with one is a
-type error. It is caught at compile time and the message is specific, but the name that
-trips people is `title` — an obvious field for a row representing a media item, a guide or
-a review, and taken by the page-title accessor.
+type error. It is caught at compile time and the message is specific, so the cost is the
+surprise rather than the failure — which is why the list is here.
+
+`title` used to be on it, and was the name that caught people most: an obvious field for a
+row representing a media item, a guide or a review. The document title is
+[`static title`](#the-page-title) now, so the instance name is yours.
 
 The names in use:
 
 | Group             | Names                                                                                                                 |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
 | Lifecycle         | `onBoot` `onMount` `onHydrate` `onDehydrate` `onRendering` `onRendered` `onUpdate` `onUpdating` `onUpdated` `onError` |
-| Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child` `title`                                                      |
+| Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child`                                                              |
 | Actions & state   | `bind` `validate` `resetValidation` `errors` `addError` `refresh` `$refresh` `$set` `cancelled` `signal`              |
 | Navigation        | `redirect` `redirectRoute` `redirectIntended` `currentUrl` `navigateCurrent`                                          |
-| Events & realtime | `dispatch` `dispatchSelf` `dispatchTo` `stream` `client`                                                              |
+| Events & realtime | `dispatch` `dispatchSelf` `dispatchTo` `stream` `client` `$`                                                          |
 | Misc              | `flash` `download` `clearDurable`                                                                                     |
 
-Anything beginning with `_` is also framework-internal, as is the static `durable`.
+Anything beginning with `_` is also framework-internal, as are the statics `durable`
+and `title`.
 
 If the natural name is taken, the usual fix is a more specific one — `headline`,
 `mediaTitle` — which often reads better than `title` did.
@@ -563,6 +574,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/lifecycle.md

@@ -94,11 +94,19 @@ Avoid expensive database queries in `onBoot()` — it fires on every round-trip,
 
 Runs once on the initial `GET` render, then is skipped on all subsequent WebSocket updates. It's the primary place to load data for the page.
 
-It receives the route `HttpContext` — the same argument a controller action gets — so a page on a dynamic segment reads its [route-model binding](/docs/routing#route-model-binding) straight off `ctx.params` instead of querying for it:
+A page on a dynamic segment needs no code here for the record it is about. A field of the model's type is [filled from the segment](/docs/flow/routing#path-parameters) before `onMount()` runs, so the query, the id field, and the 404 all belong to the route:
 
 ```typescript
-override async onMount({ params: { post } }: HttpContext<{ post: Post }>) {
-  this.post = post; // resolved by the router; a missing record 404s before this runs
+export class PostPage extends Component {
+  @locked post!: Post; // /posts/:post — nothing to load
+}
+```
+
+What `onMount()` is for is everything the URL does not carry. It receives the route `HttpContext` — the same argument a controller action gets — which is where the signed-in user lives, and `ctx.params` is still there for a segment no field claimed:
+
+```typescript
+override async onMount({ user }: HttpContext) {
+  this.canEdit = user?.id === this.post.authorId;
 }
 ```
 
@@ -106,21 +114,23 @@ The context is passed to `onBoot()` too, but only the initial `GET` populates `c
 
 ```typescript
 override async onMount() {
-  const [posts, user] = await Promise.all([
+  const [posts, drafts] = await Promise.all([
     Post.query()
       .where("status", "published")
       .orderBy("created_at", "desc")
       .limit(20)
       .get(),
-    User.findOrFail(this.currentUserId),
+    Post.query().where("status", "draft").count(),
   ]);
 
-  this.posts = posts;
-  this.user  = user;
-  this.total = posts.length;
+  this.posts  = posts;
+  this.drafts = drafts;
+  this.total  = posts.length;
 }
 ```
 
+Lists and counts are what belongs here — the things no route resolved and no parent passed down.
+
 To force `onMount()` to re-run during a WebSocket action — for example after creating a new record and wanting to reload the list — call `this.refresh()` inside the action:
 
 ```typescript
@@ -139,25 +149,30 @@ Runs on every WebSocket round-trip, immediately after state is restored from the
 
 ```typescript
 export class PostEditorPage extends Component {
-  @locked postId: number = 0; // persisted in snapshot
-  @transient post: Post | null = null; // NOT persisted — reset each round-trip
+  @expose post!: Post; // /posts/:post/edit — re-read from the row every round-trip
+  @transient wordCount = 0; // NOT persisted — derived again each time
 
   override async onHydrate() {
-    // Re-load the full Post model from the database using the persisted ID:
-    if (this.postId) {
-      this.post = await Post.findOrFail(this.postId);
-    }
+    await this.post.loadMissing(["author"]); // relations do not survive the round-trip
+    this.wordCount = this.post.body.split(/\s+/).length;
   }
 
   @expose async updateTitle(title: string): Promise<void> {
-    if (!this.post) return;
     await this.post.fill({ title }).save();
     this.flash("Title updated.");
   }
 }
 ```
 
-This is the correct pattern for holding live model instances on a component: persist only the ID in `@locked`, then re-query the model in `onHydrate()`. The model is always fresh from the database, never stale from a deserialized snapshot.
+> **This used to say to hold the id and re-query the model here.** A component could not hold a
+> model then, so `@locked postId` plus a `@transient post` re-fetched in `onHydrate()` was the
+> way to keep one fresh. It is no longer needed: a model held directly is [re-read from its row
+> on every round-trip](/docs/flow/models#freshness), which is the same guarantee with none of
+> the bookkeeping. The pattern still works — it is just two fields and a query doing what one
+> field now does.
+
+What is left for `onHydrate()` is the state a snapshot genuinely cannot carry: relations, which
+are not part of a re-read, and anything derived from them.
 
 ## Intercepting client writes
 

package/docs/flow/models.md

@@ -0,0 +1,284 @@
+---
+title: Models in Components
+description: Put an ORM model on a Flow component — what crosses the wire, what the client may change, and what stays on the server.
+---
+
+# Models in Components
+
+A Flow component can hold an ORM model directly. On a route that names one, it arrives loaded:
+
+```tsx
+import { Component, locked } from "@zerotal/flow";
+import { Post } from "@app/models/Post.ts";
+
+export class ShowPost extends Component {
+  @locked post!: Post; // /posts/:post — the record, already found
+
+  override async render() {
+    return <article>{this.post.title}</article>;
+  }
+}
+```
+
+There is no `onMount()`, because there is nothing to fetch. The router resolved `:post` before
+the component was built, and a field of that type receives the result — so the query, the
+`postId` field it would have needed, and the 404 handling all belong to the route rather than
+to this page. [Path parameters](/docs/flow/routing#path-parameters) covers what a segment
+binds to and how a model resolves by something other than its primary key.
+
+The other way a model arrives is from a parent that already has it, as a prop:
+
+```tsx
+<PostCard post={this.post} />
+```
+
+Either way the model is a model on the other side — not a plain object shaped like one — and
+everything below applies the same to both.
+
+Nothing has to be declared. A model travels under its table name — the one `@table("…")`
+sets, or the inflected default — which the app already declares and a minifier cannot mangle.
+On the way back it is found through the registry that `app/models` discovery populates, which
+is every model in the app.
+
+> **Fetching a model in `onMount()` is the older way of doing this**, from before a component
+> could hold one. It still runs, and it is still right for a record no route names and no
+> parent has — a list, a lookup keyed off something the URL does not carry. It is the wrong
+> shape for the record the page is _about_: that one the route already found.
+
+The decorator is the whole decision: **`@locked` for a model the page displays, `@expose` for
+one it edits.** Both put the model on the client; only `@expose` accepts anything back.
+
+## What crosses the wire
+
+The snapshot carries the model's **id** and the result of its `toJSON()` — the same
+serialisation your API responses use, honouring `visible`, `hidden` and `appends`.
+
+```ts
+@table("users")
+export class User extends BaseModel {
+  static fillable = ["name", "email", "password"];
+  static hidden = ["password"];
+}
+```
+
+`password` is never sent. Nothing else has to be configured for that: the model already
+declares its serialisation surface, and Flow uses it.
+
+> **`hidden` is a security control here.** On an API response an omitted column is a matter of
+> shape. On a component it is the only thing keeping a value out of the page. A snapshot is
+> signed, not encrypted — the browser can read every byte of it. Declare `hidden` (or
+> `visible`) on any model a component holds.
+
+A loaded relation is resolved the same way, through its own `toJSON()` — every model hides
+its own columns, however deep it sits.
+
+The id travels separately from the values, in the part of the snapshot a client write cannot
+reach. **Which record a component points at is not something the browser can change** — only
+the values on it, and only the ones below.
+
+## What the client may change
+
+Only `fillable`. Everything else is server-owned, whatever the browser sends:
+
+| Column                               | Sent to the client | Client may write |
+| ------------------------------------ | ------------------ | ---------------- |
+| `id` — the identity                  | yes                | no               |
+| `name` — fillable, not hidden        | yes                | **yes**          |
+| `role` — not fillable                | yes                | no               |
+| `password` — fillable **and** hidden | no                 | **yes**          |
+
+A model that declares no `fillable` is read-only in the browser. That is the ORM's default:
+it guards mass assignment until told otherwise, and a component does not widen it.
+
+A field outside that set is **ignored**, not rejected — a crafted payload does not become a
+server error. To refuse a value loudly instead, or to vet one before it lands, throw from
+[`onUpdating()`](/docs/flow/lifecycle#intercepting-client-writes).
+
+### Editing
+
+Bind to a field of an `@expose`d model and it is two-way:
+
+```tsx
+export class EditProfile extends Component {
+  @expose user!: User;
+
+  @expose async save(): Promise<void> {
+    if (this.user.name.trim().length < 2) {
+      this.addError("name", "Your name needs at least two characters.");
+      return;
+    }
+    await this.user.save();
+    this.flash("Saved");
+  }
+
+  override async render() {
+    return (
+      <form onSubmit={this.save}>
+        <input value={this.user.name} blur />
+        <span error={this.errors.name} />
+        <button>Save</button>
+      </form>
+    );
+  }
+}
+```
+
+`save()` writes only the columns that actually differ. The row was re-read a moment earlier
+(see [Freshness](#freshness)), so the model's idea of "unchanged" is the row as it is now, not
+the one the page was built from.
+
+A `@locked` model is display-only, and its fields are not bound: render them as text —
+`<p>{this.post.title}</p>` — rather than as an input. An input pointed at one accepts typing
+and sends nothing.
+
+### Validating a model's fields
+
+`this.validate()` rules are keyed by the component's **own** exposed properties, and a model's
+columns are not among them: `"user.name"` looks for a property with that name, finds nothing,
+and fails whatever the field actually holds. Two ways round it:
+
+- **Check in the action**, then `this.addError(field, message)` — as above. Right for a field
+  or two.
+- **Use a [form object](/docs/flow/forms)** for anything larger. It is the shape built for
+  validated multi-field editing, and it can carry values no column has: a confirmation field,
+  a current-password check, an upload.
+
+### Hidden fields are writable
+
+`hidden` governs what is _shown_, not what may be written. A password is the case that makes
+the difference: fillable because a user sets it, hidden because the stored hash must never
+reach the page.
+
+```tsx
+<input type="password" value={this.user.password} blur />
+```
+
+The stored hash is never sent, so the field starts empty. What the user types is held until
+they save — it travels back to the browser that produced it, and nowhere else. A value the
+_server_ set is never echoed, and a half-typed one is never written to the
+[durable store](/docs/flow/lifecycle).
+
+What reaches the database is a hash rather than what was typed, as long as the column is
+listed in the model's `hashable` — see [Password hashing](/docs/orm#password-hashing).
+
+## Relations
+
+A relation that is loaded when the page renders travels with the model, through its own
+`toJSON()`. It does not survive the round-trip:
+
+```tsx
+override async onMount(): Promise<void> {
+  await this.post.loadMissing(["author"]); // this.post came from the route
+}
+```
+
+That renders. **The next interaction has no `author`** — the re-read is a find by id, which
+fetches the row and not the relations that happened to be loaded around it. Reading it then
+throws the ORM's guard: `Relation "author" was accessed on Post without eager loading`.
+
+Load what an action needs, where it needs it:
+
+```ts
+@expose async approve(): Promise<void> {
+  await this.post.loadMissing(["author"]);
+  this.post.approved = true;
+  await this.post.save();
+  this.flash(`Approved — ${this.post.author.name} has been credited.`);
+}
+```
+
+When the page _displays_ the relation, load it once per round-trip in
+[`onHydrate()`](/docs/flow/lifecycle#re-deriving-state-after-hydration) instead. Rendering is
+the case worth watching: a template reading `this.post.author.name` works on the first paint
+and throws on every interaction after it.
+
+```ts
+override async onHydrate(): Promise<void> {
+  await this.post.loadMissing(["author"]);
+}
+```
+
+## Freshness
+
+The model is **re-read from the database on every round-trip**, by id. What the client holds
+is a rendering of a row, not the row.
+
+Two consequences worth knowing:
+
+- **Server-owned columns are always current.** If someone else changes `role`, the next
+  interaction shows the new value.
+- **Unsaved changes survive.** A change an action made without calling `save()` is restored
+  from the snapshot, so a half-filled field does not revert the moment something else happens.
+  Only the writable fields are restored; everything else comes from the fresh row.
+
+If two people edit the same record, the one who saves last wins. Flow does not add optimistic
+locking — add a version column and check it in `save()` if a record needs it.
+
+### A row that disappears
+
+The re-read is a `findOrFail`, and it applies the same scopes your own queries do. A record
+deleted — or soft-deleted — while a page holds it makes the next interaction fail: nothing is
+patched, and the browser console carries the error. So follow a delete with a navigation
+rather than leaving the prop pointing at a row that is gone:
+
+```ts
+@expose async destroy(): Promise<void> {
+  await this.post.delete();
+  this.redirect("/posts");
+}
+```
+
+## Collections
+
+An array of models is sent as ids and re-read with a single `whereIn` query:
+
+```tsx
+@locked posts: Post[] = [];
+```
+
+Collections are read-only on the client. Bind to a single model when you need to edit one.
+
+Two things follow from ids and one `whereIn`:
+
+- **Order does not travel.** The re-read carries no `order by`, so the order you loaded them
+  in is not guaranteed to come back. Sort where you render, or re-run the real query in
+  `onHydrate()`.
+- **Rows that vanish drop out quietly.** A `whereIn` returns what it finds, so a deleted
+  record leaves the array one shorter — unlike a single model, whose disappearance fails the
+  interaction.
+
+## What a round-trip costs
+
+Each model prop is one query per interaction, and each collection one more. That is the price
+of never showing a stale row, and for most pages it is the right trade. When it is not:
+
+- **[`@transient`](/docs/flow/decorators#the-transient-decorator)** keeps a value off the
+  client and out of the snapshot entirely — nothing is sent, and nothing is re-read.
+- **Hold an id and query it yourself** in `onHydrate()` when the query needs shaping the
+  re-read cannot do: eager loads, ordering, a scope. `@locked postId: number` plus one query
+  is the whole pattern.
+- **A [form object](/docs/flow/forms)** when the page is editing many fields — it edits a
+  plain object, and touches the database once, in your action.
+
+## Troubleshooting
+
+| What you see                            | What it means                                                        |
+| --------------------------------------- | -------------------------------------------------------------------- |
+| `No model maps to "posts"`              | The class is not in `app/models`, or its `@table` no longer matches. |
+| `Post has no table name`                | Give the class `@table("…")`.                                        |
+| `Relation "author" was accessed`        | It was loaded in `onMount()`, and this is a later round-trip.        |
+| An edited field never saves             | It is not in `fillable`, so the write was ignored.                   |
+| A field snaps back after an interaction | The same cause, seen from the page: the fresh row won the re-render. |
+| A password field empties itself         | The column is `hidden` but not `fillable`, so nothing was applied.   |
+
+## Next steps
+
+- [Decorators](/docs/flow/decorators) — `@expose`, `@locked` and the rest of the property
+  contract.
+- [Lifecycle](/docs/flow/lifecycle) — `onHydrate()`, `onUpdating()` and where per-round-trip
+  work belongs.
+- [Forms & Uploads](/docs/flow/forms) — form objects, which are the right shape for
+  multi-field editing and for anything a model cannot carry.
+- [Mass assignment](/docs/orm#mass-assignment) — `fillable`, `guarded`, `hidden` and
+  `visible`, which this page builds on.
+- [Relationships](/docs/orm/relationships) — eager loading, `load()` and `loadMissing()`.

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