@zerotal/arch 1.7.0

package/docs/flow/pagination.md

@@ -0,0 +1,402 @@
+---
+title: Flow Pagination
+description: The Pagination mixin, URL-synced pages, and named paginators.
+---
+
+# Pagination
+
+Paginate in the database with `Model.paginate(perPage)` — it returns the page the request is on, so the component holds the result and nothing else. Compose the `Pagination` mixin (`Component.using(Pagination)`) for the page state and navigation actions. The standalone `paginate()` helper is for arrays you already hold in memory.
+
+## In-memory pagination
+
+For arrays already held in memory, `paginate(items, page, perPage)` slices the data and returns a rich paginator object with metadata and a windowed page list:
+
+```typescript
+import { paginate } from "@zerotal/flow";
+
+export class PostsPage extends Component {
+  @url page = 1;
+  @locked all: Post[] = [];
+
+  override async onMount() {
+    this.all = await Post.query().orderBy("created_at", "desc").get();
+  }
+
+  @expose goTo(n: number): void {
+    this.page = n;
+  }
+
+  override async render() {
+    const p = paginate(this.all, this.page, 10);
+
+    return (
+      <div>
+        <ul>
+          {p.data.map((post) => (
+            <li key={String(post.id)}>{post.title}</li>
+          ))}
+        </ul>
+
+        <div class="flex items-center gap-2 mt-4 text-sm">
+          <span class="text-gray-500">
+            Showing {p.from}–{p.to} of {p.total}
+          </span>
+
+          <nav class="flex gap-1 ml-auto">
+            {p.elements().map((el) =>
+              el === "..." ? (
+                <span class="px-2 py-1 text-gray-400">…</span>
+              ) : (
+                <button
+                  key={String(el)}
+                  onClick={() => this.goTo(el as number)}
+                  class={
+                    el === p.page
+                      ? "px-3 py-1 rounded bg-orange-500 text-white font-semibold"
+                      : "px-3 py-1 rounded hover:bg-gray-100"
+                  }
+                >
+                  {el}
+                </button>
+              ),
+            )}
+          </nav>
+        </div>
+      </div>
+    );
+  }
+}
+```
+
+### Paginator properties
+
+| Property          | Type                  | Description                                       |
+| ----------------- | --------------------- | ------------------------------------------------- |
+| `data`            | `T[]`                 | Items on the current page                         |
+| `total`           | `number`              | Total item count across all pages                 |
+| `page`            | `number`              | Current page number (1-based)                     |
+| `perPage`         | `number`              | Items per page                                    |
+| `lastPage`        | `number`              | Number of the last page                           |
+| `from`            | `number`              | 1-based index of the first item on this page      |
+| `to`              | `number`              | 1-based index of the last item on this page       |
+| `onFirstPage`     | `boolean`             | `true` if `page === 1`                            |
+| `hasMorePages`    | `boolean`             | `true` if there are pages after the current one   |
+| `elements(each?)` | `(number \| "...")[]` | Windowed page list with ellipsis for large ranges |
+
+`elements()` produces a compact list like `[1, 2, "...", 8, 9, 10]` — always showing the first page, last page, and a window around the current page. Pass a window size to `elements(window)` to control how many adjacent pages are shown on each side of the current one (default: 1).
+
+## The Pagination mixin
+
+`Pagination` is a class mixin that adds page state, URL sync, and navigation methods automatically. Compose it with [`Component.using(...)`](/docs/flow/layouts#composing-behaviour-with-mixins).
+
+```tsx
+import { Component, Pagination, Pager } from "@zerotal/flow";
+
+export class PostsPage extends Component.using(Pagination) {
+  override async render() {
+    const posts = await Post.paginate(10); // uses this component's page
+
+    return (
+      <div>
+        <ul>
+          {posts.data.map((post) => (
+            <li key={String(post.id)}>{post.title}</li>
+          ))}
+        </ul>
+
+        <Pager paginator={posts} />
+
+        <p class="text-sm text-gray-500 mt-2">
+          Showing {posts.from}–{posts.to} of {posts.total}
+        </p>
+      </div>
+    );
+  }
+}
+```
+
+`<Pager>` renders the Prev / numbered / Next links and takes either paginator — the ORM's result or the in-memory one.
+
+### Pagination members
+
+Every navigation method accepts an optional `pageName` (default `"page"`) so one component can drive several **independent** paginators — `this.nextPage("invoices")` alongside `Invoice.paginate(10, undefined, "invoices")`. The default paginator is URL-synced (`?page=`); named paginators live in the snapshot.
+
+| Member                    | Type             | Description                                               |
+| ------------------------- | ---------------- | --------------------------------------------------------- |
+| `page`                    | `@url number`    | Current page of the default paginator, synced to `?page=` |
+| `paginators`              | `@expose record` | Current page of each named paginator, keyed by name       |
+| `gotoPage(n, pageName?)`  | `@expose method` | Jump to a specific page                                   |
+| `resetPage(pageName?)`    | `@expose method` | Reset to page 1 (call when filters change)                |
+| `nextPage(pageName?)`     | `@expose method` | Advance to the next page                                  |
+| `previousPage(pageName?)` | `@expose method` | Go back to the previous page                              |
+| `pageFor(pageName?)`      | method           | Read the current page of a paginator                      |
+
+Optional update hooks fire around a page change: define any of `updatingPage(page, name)` / `updatedPage(page, name)` (default paginator) or the generic `updatingPaginators(page, name)` / `updatedPaginators(page, name)`.
+
+### Resetting page on filter change
+
+Always call `this.resetPage()` when a filter changes — otherwise the current page may exceed the new total and return an empty result set:
+
+```typescript
+@url search = "";
+@url status = "all";
+
+@expose async applySearch(q: string): Promise<void> {
+  this.search = q;
+  this.resetPage();
+}
+
+@expose async setStatus(s: string): Promise<void> {
+  this.status = s;
+  this.resetPage();
+}
+
+override async render() {
+  const posts = await Post.query()
+    .when(this.search, (q) => q.where("title", "like", `%${this.search}%`))
+    .when(this.status !== "all", (q) => q.where("status", this.status))
+    .paginate(15);
+  // …
+}
+```
+
+### Composing mixins
+
+`Pagination` composes cleanly with other mixins via `Component.using(...)`:
+
+```typescript
+// Sorting + pagination — `Sorting` is your own mixin, `Pagination` is shipped:
+export class PostsPage extends Component.using(Sorting, Pagination) {
+  // has this.page and the nav actions, plus whatever your Sorting mixin adds
+}
+
+// A per-page preference of your own — pass it to the query:
+export class PostsPage extends Component.using(Pagination) {
+  readonly perPage = 25;
+
+  override async render() {
+    const posts = await Post.paginate(this.perPage);
+    // …
+  }
+}
+```
+
+## Database pagination
+
+For large datasets, avoid loading all rows in `onMount()`. Paginate in the database instead.
+
+`Model.paginate(perPage)` returns the page the request is on. Compose the mixin, query in `render()`, and there is no page to pass, no state to hold, and nothing to refresh — a page change re-renders, and the re-render re-queries:
+
+```tsx
+export class PostsPage extends Component.using(Pagination) {
+  override async render() {
+    const posts = await Post.paginate(10); // this component's page
+
+    return (
+      <div>
+        <ul>
+          {posts.data.map((p) => (
+            <li key={String(p.id)}>{p.title}</li>
+          ))}
+        </ul>
+
+        <nav>
+          <button onClick={this.previousPage} disabled={posts.page <= 1}>
+            ‹ Prev
+          </button>
+          <span>
+            Page {posts.page} of {posts.lastPage}
+          </span>
+          <button onClick={this.nextPage} disabled={posts.page >= posts.lastPage}>
+            Next ›
+          </button>
+        </nav>
+      </div>
+    );
+  }
+}
+```
+
+That is the whole component. `render()` is `async`, so the query runs there and re-runs on every round-trip, with the trade-off that implies: one query per render. Hold the result in a `@locked` field and load it in `onMount()` instead when the query is expensive and you'd rather re-run it only on demand (`this.refresh()`).
+
+Outside a component, `paginate()` reads `?page=` from the query string — what a controller wants. The mixin points it at the component's own page instead, which is what makes it work over WebSocket, where there is no URL to read.
+
+Pass the page explicitly when it isn't the request's — a report job, a fixed first page, a second paginator driven by something other than the mixin:
+
+```typescript
+const first = await Post.paginate(10, 1); // always page 1
+const invoices = await Invoice.paginate(10, undefined, "invoices"); // a named paginator
+```
+
+The query builder takes the same arguments when you need to build the query up first. Keep the **result** on the component — it already carries the page, the total, the last page, and the URL helpers, so there is nothing to copy out of it:
+
+```typescript
+export class PostsPage extends Component.using(Pagination) {
+  @url search = "";
+  @url status = "all";
+
+  @locked posts!: PaginateResult<Post>;
+
+  override async onMount() {
+    this.posts = await Post.query()
+      .where("status", "!=", "deleted")
+      .when(this.status !== "all", (q) => q.where("status", this.status))
+      .when(this.search, (q) => q.where("title", "like", `%${this.search}%`))
+      .orderBy("created_at", "desc")
+      .paginate(15); // the component's page
+  }
+
+  @expose async applySearch(q: string): Promise<void> {
+    this.search = q;
+    this.resetPage(); // filters changed — back to page 1
+    this.refresh(); // re-run onMount on this round-trip
+  }
+
+  override async render() {
+    return (
+      <div>
+        <input value={this.search} live placeholder="Search posts…" class="input" />
+
+        <ul class="mt-4 space-y-2">
+          {this.posts.data.map((p) => (
+            <li key={String(p.id)} class="border rounded p-3">
+              <h3 class="font-semibold">{p.title}</h3>
+            </li>
+          ))}
+        </ul>
+
+        <nav class="flex items-center gap-1 mt-4">
+          <button onClick={this.previousPage} disabled={this.posts.page <= 1}>
+            ‹ Prev
+          </button>
+          <span class="px-3">
+            Page {this.posts.page} of {this.posts.lastPage}
+          </span>
+          <button onClick={this.nextPage} disabled={this.posts.page >= this.posts.lastPage}>
+            Next ›
+          </button>
+        </nav>
+        <p class="text-sm text-gray-500 mt-1">{this.posts.total} total posts</p>
+      </div>
+    );
+  }
+}
+```
+
+> **Warning** — Don't mirror the paginator onto the component. Fields like `@locked total`, `@locked lastPage`, `@locked perPage`, and a hand-rolled `@url page` restate what `PaginateResult` already holds, and each one is a value that can drift out of step with the query. The mixin owns the page; the result owns everything else.
+
+The ORM's `.paginate()` issues two queries — a `COUNT(*)` for the total and a `LIMIT/OFFSET` for the data — and returns `{ data, total, page, perPage, lastPage, from, to, meta }` plus `nextPageUrl()` / `prevPageUrl()` / `urlForPage()` for building links.
+
+## Infinite scroll
+
+Use the `<InfiniteScroll>` component to load more pages as the user scrolls down, without explicit page navigation:
+
+```tsx
+import { InfiniteScroll } from "@zerotal/flow";
+
+export class FeedPage extends Component {
+  @expose page = 1;
+  @locked posts: Post[] = [];
+  @locked hasMore = true;
+
+  override async onMount() {
+    const result = await Post.query().orderBy("created_at", "desc").paginate(20, 1);
+    this.posts = result.data;
+    this.hasMore = result.hasMorePages;
+  }
+
+  @expose async loadMore(): Promise<void> {
+    this.page++;
+    const result = await Post.query().orderBy("created_at", "desc").paginate(20, this.page);
+
+    this.posts = [...this.posts, ...result.data]; // append
+    this.hasMore = result.hasMorePages;
+  }
+
+  override async render() {
+    return (
+      <div>
+        <ul class="space-y-4">
+          {this.posts.map((p) => (
+            <li key={String(p.id)} class="border rounded p-4">
+              {p.title}
+            </li>
+          ))}
+        </ul>
+
+        <InfiniteScroll show={this.hasMore} onMore={this.loadMore}>
+          <div class="h-12 flex items-center justify-center text-gray-400 text-sm">
+            Loading more…
+          </div>
+        </InfiniteScroll>
+
+        {!this.hasMore && (
+          <p class="text-center text-gray-400 text-sm mt-4">You've reached the end.</p>
+        )}
+      </div>
+    );
+  }
+}
+```
+
+`<InfiniteScroll>` calls the `onMore` action when its sentinel enters the viewport (using an IntersectionObserver). Pass `show={this.hasMore}` to stop rendering the sentinel — and stop loading — once you reach the end.
+
+## Cursor pagination
+
+For very large tables where `OFFSET` pagination is slow, use cursor-based pagination via the ORM. The cursor encodes the last-seen row's sort key and is more efficient for deep pages:
+
+```typescript
+export class ActivityPage extends Component {
+  @url cursor: string | null = null;
+  @locked items:    Activity[] = [];
+  @locked nextCursor: string | null = null;
+  @locked prevCursor: string | null = null;
+
+  private async load() {
+    const result = await Activity.query()
+      .orderBy("id", "desc")
+      .cursorPaginate(20, this.cursor);
+
+    this.items      = result.data;
+    this.nextCursor = result.nextCursor;
+    this.prevCursor = result.prevCursor;
+  }
+
+  override async onMount() {
+    await this.load();
+  }
+
+  @expose async next(): Promise<void> {
+    this.cursor = this.nextCursor;
+    await this.load();
+  }
+
+  @expose async prev(): Promise<void> {
+    this.cursor = this.prevCursor;
+    await this.load();
+  }
+
+  override async render() {
+    return (
+      <div>
+        <ul>
+          {this.items.map((a) => (
+            <li key={String(a.id)}>{a.description}</li>
+          ))}
+        </ul>
+        <div class="flex gap-4 mt-4">
+          <button onClick={this.prev} disabled={!this.prevCursor}>← Previous</button>
+          <button onClick={this.next} disabled={!this.nextCursor}>Next →</button>
+        </div>
+      </div>
+    );
+  }
+}
+```
+
+Cursor pagination works best when you paginate by a monotonic column (`id`, `created_at`) in a consistent direction. It does not support random page access.
+
+## Next steps
+
+- [Flow overview](/docs/flow) — the guide's front page and the rest of the sections.
+- [Reference](/docs/flow/references) — every decorator, prop, and directive in one table.

package/docs/flow/performance.md

@@ -0,0 +1,262 @@
+---
+title: Flow Transport & Performance
+description: How updates reach the browser, what to do on hostile networks, and the polish that hides latency.
+---
+
+# Transport & performance
+
+Every WebSocket action returns a **patch**. To keep those patches small, Flow sends only what changed:
+
+- **Snapshot deltas.** Instead of re-sending the whole snapshot each round-trip, Flow transmits only the properties that changed (plus any that were removed) and the new signed checksum. The client rebuilds the full snapshot from the copy it already holds. This is exact — the server diffs against the client's own snapshot — and still HMAC-verified, so a large `@locked` collection that doesn't change on a given action isn't re-sent on every keystroke.
+- **HTML suppression.** When an action re-renders to markup byte-identical to
+  the last patch on that connection, the server omits the HTML entirely and the
+  client keeps its DOM — no morph at all. This covers a save that only flashed a
+  toast, or a change reflected purely through client-reactive bindings like
+  `:class` and `flow:text`.
+
+Both are automatic; there is nothing to configure. What you can still do to help:
+
+- Put display-only collections behind `@transient` (or store IDs and re-load inside the action that needs them) so they never enter the snapshot in the first place.
+- Prefer `@computed` for values derivable from other state.
+- Reach for client expressions / reactive bindings (`onClick={() => this.open = true}`, `class={…}`) for pure-UI state so those interactions don't round-trip at all.
+
+Set `ZT_FLOW_TRANSPORT_LOG=1` in development to log each patch's delta size versus the full snapshot size (and whether the HTML was suppressed), so you can see the payload of a given interaction while you build.
+
+## WebSocket-blocked networks (HTTP fallback)
+
+Some strict corporate proxies and firewalls block WebSocket upgrades outright — which would otherwise lock those users out of a socket-driven app. Flow has an automatic **circuit breaker**: after a few failed handshakes the client stops waiting on the socket and starts sending action frames over a plain **HTTP POST** to `/__flow/http`. That endpoint runs the _exact same_ server pipeline — hydrate → dispatch →
+render → patch — and returns the frames for the client to apply. Actions,
+validation, flashes, redirects, and events all keep working, with no code change
+in your components.
+
+It's a graceful degrade, not a mode you configure. WebSocket reconnection keeps running in the background, so the moment the socket becomes reachable again the client upgrades back to it automatically. The trade-offs while in fallback:
+
+- 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
+  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.
+
+## Interaction polish
+
+The perceived speed of a server-driven app comes from three things: never showing
+a blank box, never making a click wait to feel like it did something, and never
+paying for a navigation you could have paid for during the hover. Flow has a small primitive for each.
+
+### Skeletons
+
+`<Skeleton>` is a pulsing placeholder block — pure markup plus a bundled animation, so it needs no app CSS. Use it for the shape of content that hasn't loaded yet:
+
+```tsx
+import { Skeleton } from "@zerotal/flow";
+
+<Skeleton height="1.5rem" width="60%" />     {/* one bar */}
+<Skeleton lines={3} />                        {/* three stacked lines, last one short */}
+<Skeleton height="10rem" rounded="0.75rem" /> {/* a card-sized block */}
+```
+
+The most useful place is a lazy child's `placeholder()` — what shows while the component mounts on viewport entry — and inside a `<Loading>` region (`<Loading skeleton />` renders one for you):
+
+```tsx
+export class ChartWidget extends Component {
+  override placeholder() {
+    return <Skeleton height="12rem" rounded="0.75rem" />;
+  }
+}
+
+// Parent — the skeleton shows until the widget loads:
+<ChartWidget lazy />;
+```
+
+Tune the tone with the `--flow-skeleton-color` CSS variable; the pulse respects `prefers-reduced-motion`.
+
+### Optimistic UI with automatic rollback
+
+Because state is a server-authoritative snapshot, optimistic UI and its rollback are already built in. A client expression that changes a prop and then calls an action applies the change **instantly**; when the server responds, the authoritative snapshot reconciles the prop — so if the server **rejects** the change, it snaps back on its own. There is no separate optimistic library and no compensation code to write:
+
+```tsx
+@expose liked = false;
+@expose confirmLike(): void { /* … persist … */ }
+
+override async render() {
+  return (
+    <button onClick={() => { this.liked = true; $flow.call("confirmLike"); }}>
+      ♥ Like
+      <span show={this.liked} class="ml-1 text-rose-600">— saving…</span>
+      <span showOnError class="ml-1 text-red-600">— couldn't save</span>
+    </button>
+  );
+}
+```
+
+The `showOnError` (and `hideOnError`) directive reveals an element after an action **fails** — an unhandled throw in the action, or an `onUpdating` hook that rejected the optimistic write. It's the failed-state counterpart to `showOnLoading`, and it clears automatically when the next action for that component is dispatched. Rollback itself needs nothing extra: the reconciliation that keeps the client honest also reverts a rejected optimistic value. (Validation errors are not "failures" in this sense — they populate the error bag and drive `error={this.errors.field}` instead.)
+
+### Reactive lists & optimistic collections
+
+Optimistic UI for a scalar is easy (flip a bool, reconcile on the patch). A **list** add/remove is the hard case in server-driven UIs: `{this.items.map(…)}` renders to static server HTML, so pushing to the array client-side wouldn't show until the round-trip. Two pieces solve it.
+
+**`<For>` — a reactive list.** Render the list with `<For>` and it compiles to an Alpine `x-for`, so any client change to the array re-renders it instantly (server patches still keep it authoritative):
+
+```tsx
+import { For } from "@zerotal/flow";
+
+<For each={this.todos} keyBy="id">
+  {(todo) => (
+    <li class={todo.done ? "line-through" : ""}>
+      {todo.text}
+      <button onClick={() => $flow.call("removeTodo", todo.id)}>×</button>
+    </li>
+  )}
+</For>;
+```
+
+The item template supports element structure, static attributes, `class`/`className` (→ reactive `:class`), reactive attributes, `on*` arrow handlers (→ Alpine `@event`, with `this.` resolving to the component), and `{item.field}` text. Anything more exotic → a clear compile error pointing you at a raw Alpine `<template x-for="item in $flow.todos">` escape hatch.
+
+**`appendOptimistic` / `removeOptimistic` — instant add/remove with rollback.** Mutate the array optimistically, then dispatch the action that persists it:
+
+```tsx
+<button
+  onClick={() => {
+    $flow.appendOptimistic("todos", { id: `tmp-${Date.now()}`, text: this.draft });
+    $flow.call("addTodo"); // persists + reloads todos
+  }}
+>
+  Add
+</button>
+```
+
+The item appears the instant you click. Two things then happen to it.
+
+**It survives interim patches.** A broadcast or event landing mid-flight
+re-applies your pending change on top of the server state.
+
+**It is reconciled when the owning action's patch lands.** On success the
+authoritative server list stands — your persisted row, with its real id. On
+failure the server list is unchanged, so the optimistic change rolls back on its
+own. Pair it with `showOnError` for a failed-state hint.
+
+Persist the item in that action — push to the `@expose` array, or reload it — so
+it stays after reconciliation. `removeOptimistic(prop, (item) => …)` is the
+mirror image for deletes.
+
+### Hover-prefetch
+
+Add `hover` to a `navigate` link and Flow fetches the target after a brief hover dwell (and on first touch on mobile), caching the HTML so the click swaps instantly instead of waiting on a cold request:
+
+```tsx
+<a href="/posts" navigate hover>
+  Posts
+</a>;
+{
+  /* or */
+}
+<Link href="/posts" hover>
+  Posts
+</Link>;
+```
+
+The cache is small (a handful of recent pages) and short-lived, same-origin only, and never prefetches across a layout boundary. It's the difference between "snappy in dev" and "snappy on 4G."
+
+### Fast refresh in dev
+
+When you edit a component under `serve --dev`, the server restarts (quickly) and the client **re-renders each mounted component from its held snapshot with the new code — keeping its state**, instead of a full reload that would reset everything. Because component state is a signed snapshot and your `APP_KEY` doesn't change across a restart, that snapshot still verifies against the fresh server; the browser also refetches the stylesheet, so a newly-used Tailwind class shows up too. Increment a counter, tweak its template, save — the counter keeps its value and the change appears in place.
+
+Two things to know:
+
+- It deliberately does **not** re-run `onMount`. Editing your data-loading there
+  won't reflect until you reload manually — that is the price of preserving
+  state.
+- If an edit changes a component's shape in a way the held snapshot cannot
+  satisfy, Flow falls back to a one-shot full reload rather than showing a
+  broken page. Production is unaffected — this only runs under the dev worker.
+
+### Time-travel devtools
+
+Because the engine signs and delta-encodes the **full component state** on every round-trip, the client already holds an exact, verifiable history of everything each component has been. Under `serve --dev`, Flow records that stream: one frame per applied patch,
+plus the initial mount. You can then **scrub back to any frame**.
+
+Jumping re-applies that frame's snapshot _and_ its HTML to the live component, so
+both state and DOM restore exactly. No setup, no instrumentation in your components.
+
+It surfaces as a **Timeline** tab in the [Zerotal devtools panel](/docs/devtools) (`@zerotal/devtools`) — Flow registers it there so all the framework's tooling lives in one place. If devtools isn't installed, Flow falls back to a standalone ⏱ panel so time-travel still works on its own — docked bottom-left, or set `data-flow-tl-corner="bottom-right"` (any corner) on `<html>` or `<body>` if that clashes with your layout. Each frame shows the action that produced it (`increment`, `$set`, `mount`, …), which state fields changed, and the time. Click a frame to jump there; a **⏵ Resume live** button returns to the latest. It's the fastest way to see how a bug's state evolved — perform the actions, then step backward through them.
+
+There's also a console API for scripted inspection:
+
+```js
+__flow.timeline.frames(); // every recorded frame (seq, action, changed fields, snapshot, …)
+__flow.timeline.framesFor(id); // frames for one component (its data-flow-id)
+__flow.timeline.jump(seq); // restore the component to that frame (state + DOM)
+__flow.timeline.live(id); // return a rewound component to its latest frame
+```
+
+Two things to know: jumping is **client-only** — it re-applies a snapshot you already hold, with no server round-trip, so it's instant and side-effect-free. State is server-authoritative, though, so acting after a rewind has
+consequences: the action sends the rewound snapshot to the server, which
+continues authoritatively from there as a coherent new branch.
+
+Use time travel to inspect and replay, then hit **Live** before resuming normal
+use. Recording is capped to the most recent frames and runs **only** under the dev worker; production ships none of it.
+
+### Dev error overlay
+
+When an **unexpected** error is thrown, `serve --dev` shows a **full-screen
+overlay** carrying the error class, message, and stack. It covers both a server
+action and the initial `GET` render (`onMount` / `render`).
+
+That is the same immediacy a client-side bundler gives you, for server-driven
+components. The server attaches that detail **only under the dev worker**, so the overlay
+never appears in production. No stack is ever sent to a browser there: an action
+flashes its message, and an initial-render error returns a normal 500.
+
+The overlay names the **action** and **component** that threw, dims framework/`node_modules` stack frames so your app frames stand out, and dismisses on Esc or a backdrop click. For an action error the component's patch still reconciles underneath, so dismissing returns you to a live page with its state intact — pair it with the [time-travel timeline](#time-travel-devtools) to see exactly how the state got there.
+
+Only genuinely unexpected throws raise the overlay. The framework's own control-flow errors pass straight through to their normal
+handling. Validation errors populate the error bag
+(`error={this.errors.field}`), and **intended HTTP errors** — an auth `401` or
+`403`, a `404`, a redirect — resolve to their proper status instead of a spurious
+error screen.
+
+### Durable & resumable state
+
+Fast refresh keeps state across a _dev restart_; **`static durable`** keeps it across a _full client reload_. Opt a component in and its signed snapshot is persisted server-side after every
+request, keyed by user (or session) and route.
+
+A multi-step form, a long editor, or any in-progress flow then resumes
+**exactly** — whether the user reloads the page, closes and reopens the tab, or
+switches device. Nothing is stored in the browser:
+
+```tsx
+export class Wizard extends Component {
+  static durable = true; // or { ttl: "1h", scope: "user" | "session" }
+
+  @expose step = 1;
+  @expose name = "";
+  @expose next() {
+    this.step++;
+  }
+
+  @expose finish() {
+    // …persist the result…
+    this.clearDurable(); // flow complete — forget the stored snapshot so the next visit is fresh
+  }
+}
+```
+
+How it works: on a fresh `GET`, Flow looks for a valid stored snapshot for this
+user and route. Finding one, it restores the snapshot and runs `onHydrate()`
+**instead of `onMount()`**.
+
+The resume therefore behaves like a WebSocket round-trip rather than a fresh
+load — state comes back from the snapshot, so re-derive any `@transient` model in
+`onHydrate()`. If there's no entry — or the snapshot fails its HMAC check (tampered, or your `APP_KEY` rotated) — it mounts fresh. Every subsequent action re-persists the latest snapshot; `this.clearDurable()` drops it.
+
+A few things to know:
+
+- **Keying & isolation.** `scope: "user"` (the default) keys by the authenticated user, falling back to the session when anonymous; `scope: "session"` always keys per-session (per-device, even when logged in). The snapshot is HMAC-signed and keyed by identity, so one user can never resume another's state. A user-scoped component with no user and no session simply doesn't persist.
+- **Survives a redeploy — with a persistent store.** The default store is in-process (survives reconnect/tab-close/device-switch within the running process). To also survive a **server restart or redeploy**, swap in a persistent backend — `setDurableStore(store)` accepts any `{ get, set, delete }` (e.g. one backed by `@zerotal/cache`/Redis). Set a `ttl` (default 24h) to bound how long an abandoned flow lingers.
+- **The URL vs. the snapshot.** On resume the stored snapshot wins, so `@url` props reflect the saved value rather than re-seeding from the current query string — resume-exactly semantics. Use `clearDurable()` at the natural end of a flow so a returning user isn't dropped back into a finished form.
+
+## Next steps
+
+- [Flow overview](/docs/flow) — the guide's front page and the rest of the sections.
+- [Reference](/docs/flow/references) — every decorator, prop, and directive in one table.