@zerotal/flow 1.7.0 → 1.7.3

package/CHANGELOG.md

@@ -9,6 +9,182 @@ follows SemVer strictly: anything importable without an `@internal` marker keeps
 shape for the rest of the 1.x line, and `api-surface.md` is diffed by CI on every
 change.
 
+## [Unreleased]
+
+### Added
+
+- **`@on` can name a channel per instance.** A listener's channel is read off the _class_, so
+  a channel containing a record id could not be written at all. The guide showed
+  `@on("echo-private:issues.${this.issueId},CommentPosted")`, which is not interpolation —
+  it is a plain string, and the eleven characters `${this.issueId}` reached the browser
+  intact, subscribed to a channel nobody broadcasts to, and delivered nothing. No error, no
+  warning, no subscription: a live feature with this bug looks exactly like a live feature
+  that was never built.
+
+  `@on` now also accepts a resolver, the same shape `@presence` and `@shared` have always
+  taken and are resolved with four lines away in the same file:
+
+  ```ts
+  @on((self) => `echo-private:issues.${self.issue.id},CommentPosted`)
+  async onCommentPosted(payload: { comment: Comment }) { … }
+  ```
+
+  It is called with the component as the snapshot is built — after `onMount()`, so it can
+  read anything the component has loaded. A resolver that throws drops that one listener and
+  leaves the page rendering, because a page missing its live updates is degraded while a page
+  that 500s over an unnameable channel is gone. Static names are untouched.
+
+  Reach for the **narrowest** channel a reader is entitled to. A shared channel plus an
+  `if (payload.id !== this.id) return` in the handler looks equivalent and is not: the
+  broadcast still lands in every subscriber's browser, to be discarded after the fact.
+
+- **`<Link down>` — prefetch on pointer-down.** The choice was between prefetching on hover
+  and not prefetching at all, and on a dense list neither is right. Hover prefetch is free
+  speed on a handful of stable links — a navigation rail, a breadcrumb — but 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` with no dwell: once, on the link the reader has committed to,
+  and still ahead of the click by however long the button is held. `pointerdown` rather than
+  `mousedown` so a touch lands there too, and it is passive — the click that follows is
+  handled as usual and finds the page already cached. `flow:navigate.down` as an attribute;
+  both may be set.
+
+### Fixed
+
+- **A bound password field silently discarded every keystroke.** The client-writable set was
+  `fillable` minus `hidden`, which conflates two allow-lists that answer different questions:
+  `fillable`/`guarded` govern what may be _written_, `visible`/`hidden` govern what may be
+  _shown_. A password is in both — fillable because a user sets it, hidden because the stored
+  hash must never reach a page — so subtracting made it unwritable, and
+  `<input type="password" value={this.user.password} blur />` accepted typing and dropped it
+  on arrival. `hidden` is no longer subtracted. It is still never _sent_: the hash does not
+  leave the server, and the field arrives empty as it should. A hidden value the client
+  supplied now survives until save, and one the _server_ produced is never echoed back.
+
+  A half-typed secret is also stripped from the [durable snapshot](/docs/flow/lifecycle)
+  before it is persisted — that store is written server-side after every request and may be
+  backed by Redis, which is no place for a password in progress.
+
+- **`<FileUpload>` never stopped saying "Uploading… 100%".** A successful upload left the
+  dropzone reporting progress forever. The bytes had gone up, the signed reference had come
+  back, and the bound property had been set — the only thing that failed was the component
+  admitting it, which meant the feature read as broken while working perfectly.
+
+  The bridge dispatches `flow:upload-finish` on success and the guide documents that name.
+  The component listened for `flow:upload-done`, which appeared nowhere else in the codebase
+  and has never been dispatched by anything. So `uploading` was set true on start and had no
+  path back to false. The component's own test covered start, progress and error, and skipped
+  success — which is how a one-word mismatch survived. It now covers it.
+
+- **Signing out in another tab left the first tab looking broken.** The server has always
+  handled this: `hydrate()` refuses a snapshot whose subject no longer matches the session, and
+  the provider answers with an error frame carrying `reload: true` and "Your session changed —
+  reload the page." The client never read the flag. It reloaded for a dev soft-refresh and for
+  the literal message `"Unknown component"`, then fell through to `console.error` — so the
+  instruction reached a console nobody had open.
+
+  What the reader saw was a button that did nothing. The page stayed on screen, still looking
+  signed in, the action silently rejected, and no way to discover otherwise but to reload by
+  hand. The frame is now honoured, guarded by the same one-shot that protects the other reload
+  paths, and the decision is a pure `_reloadReasonFor()` so it can be tested without a DOM.
+  Matching on the flag rather than the sentence, so rewording or translating the message cannot
+  turn the recovery off.
+
+- **Sibling subclasses of one decorated base stole each other's fields.** Field decorators buffer
+  their registration and the buffer is matched to a class lazily, on the first read of that class's
+  registry. Matching took the longest run across **every** buffered group, so a class could claim —
+  and splice away — an entry belonging to a sibling whose group merely shared a name.
+
+  Given `NewPage { project }` and `EditPage { project, issue }` over a shared base, draining
+  `NewPage` first found `project` at the head of `EditPage`'s group, tied on length against its own
+  single entry, and — ties going to the newest group — took it. `EditPage` then drained to `issue`
+  alone; its `project` was never registered, route-param seeding skipped the field, and `render()`
+  died on `this.project.slug`. Whether the page worked depended on which sibling had been rendered
+  first in that process, which is what made it look flaky rather than broken.
+
+  Matching is now restricted to groups whose every name is a field the class declares, falling back
+  to the old behaviour when nothing is fully contained. A sibling's group is rejected by the names
+  it has that this class does not.
+
+- **The real-time validation example did not compile.** `docs/flow/decorators.md` showed
+  `<input value={this.email} flow:model.live />`. That is the _emitted_ directive, not the prop:
+  the `.` in an attribute name is a parse error in TSX (`TS1003`), so anyone copying it got a
+  build failure on a line the guide had just handed them. The prop is `live`; the note now says
+  so, and says why the compiled form cannot be written by hand.
+
+### Documented
+
+Four behaviours that were true but written down nowhere, each found by hitting it:
+
+- **AOT compilation and `__()` are mutually exclusive** — a function call in a text child forces
+  the runtime fallback, so a translated app compiles no pages at all. Normally that is a speed
+  cost; under `cspSafe`, where every page must compile, it is a build failure. `performance.md`
+  now lists what blocks compilation and what to do about it.
+- **`FlowTest` opens no request scope**, so `Auth.user()` and `Auth.attempt()` throw and no
+  action behind a sign-in can be driven without wrapping it. `testing.md` carries the wrapper.
+- **A layout cannot set the document's `lang`** — Flow emits `<html lang="en">` and offers no
+  hook, so a localised app marks up its wrapper instead and the root element stays wrong.
+- **`<Tabs>` selection is client-only and its strip is not themeable** — no bindable prop, so no
+  `?tab=`, no back button, and hardcoded gray/indigo that is invisible on a light surface.
+- **Flow and `zerotal/view` components do not interoperate** — the two JSX runtimes produce
+  different element types (`HtmlNode` vs `SafeHtml`), so a view `FC` in a Flow page is `TS2786`.
+- **`onSort` does not say which container took the drop** — the destination is encoded in which
+  method runs, so dragging between containers needs one action per container.
+
+Also: `sortGroupId` is annotated as inert. It is declared, mapped to `flow:sort:group-id`, and
+read by neither the runtime nor the compiler.
+
+## [1.7.1] — 2026-08-16
+
+### Changed
+
+- **An action opens into its own tabs.** A frame's detail was a stack — Sent, then State,
+  then Server with the SQL buried under it. They are alternatives, not a sequence: you are
+  reading the arguments the click sent, _or_ the state it moved, _or_ the queries it ran. Now
+  a strip, matching the request rows: `Sent · State 2 · Server · Queries 3 · Logs 1`.
+
+  Queries and Logs are panes of their own, counted, so what an action cost the database is
+  one click from the frame rather than a list appended beneath a duration. Only the panes a
+  frame has appear, so the strip doubles as the summary, and which one you were reading is
+  kept as you step down the list — comparing the SQL of one action against the next should
+  not return you to the arguments each time.
+
+- **One Flow tab in DevTools, and its rows open.** The time-travel timeline registered itself
+  as a tab called "Timeline", colliding with the panel's own Timeline tab, and sat apart from
+  the Flow tab even though the frames and the actions are the same clicks seen from the two
+  ends. They are now one tab, titled `Flow`.
+
+  Each frame expands to what that action actually did — the call and its arguments, the
+  fields it changed as `before → after`, and the server's own half: duration, status, client
+  IP, the queries it ran and the lines it logged, read off that action's devtools trace. A
+  frame that never left the browser says so rather than showing an empty server section.
+  Rewinding is unchanged: the row still time-travels, and the disclosure has its own hit area
+  so reading what happened does not also rewind the page you are reading it from.
+
+  Flow's action entries are recorded on the trace as before, now `hidden` so they no longer
+  claim a tab that repeated what the trace header already said.
+
+### Fixed
+
+- **The DevTools Flow tab shows Flow actions.** It could not show any, ever: the tab
+  reported "No flow activity during this request" on every page of an app whose every
+  interaction is a Flow action.
+
+  An action arrives over the WebSocket and runs against its own `HttpContext`, and the
+  bridge recorded its entry against that context — correctly. But DevTools builds a trace
+  from core's `RequestHandled` / `RequestFailed`, and a socket action fires neither, so
+  that context became no trace and everything buffered against it was dropped unread. Not
+  only the Flow entry: the queries an action ran, its logs, its N+1 warnings. For a Flow
+  app that is the entire interactive half of the application, invisible in the one tool
+  built to see it.
+
+  The bridge now finalises the action's context itself, through the new
+  `TraceSink.finalise` in `@zerotal/devtools`. An action appears in the request list
+  labelled `FLOW` rather than as a second `GET` of the page it ran on, carrying the same
+  queries, logs and timings any request does. Found by wiring DevTools into this repo's
+  own `apps/docs` and driving a real action in a browser.
+
 ## [1.7.0] — 2026-08-16
 
 ### Fixed

package/README.md

@@ -114,7 +114,7 @@ All imported from `@zerotal/flow`.
 | `@reactive`                      | A child prop the parent re-pushes whenever it changes, re-rendering the child.                                             |
 | `@modelable`                     | A two-way child prop — writes from the child flow back up to the parent.                                                   |
 
-Action helpers available inside any exposed method include `this.flash()`, `this.redirect()`, `this.refresh()`, `this.title()`, `this.client()`, `this.download()`, `this.dispatch()`, `this.stream()`, and the `this.errors` proxy (`has`, `any`, `addError`, `resetValidation`). Lifecycle hooks: `setup`, `onBoot`, `onMount`, `onHydrate`, `onUpdating`/`onUpdated`, `onUpdate`, `onRendering`, `onRendered`, `onDehydrate`, `onError`.
+Action helpers available inside any exposed method include `this.flash()`, `this.redirect()`, `this.refresh()`, ``this.$`…` ``, `this.download()`, `this.dispatch()`, `this.stream()`, and the `this.errors` proxy (`has`, `any`, `addError`, `resetValidation`). Lifecycle hooks: `setup`, `onBoot`, `onMount`, `onHydrate`, `onUpdating`/`onUpdated`, `onUpdate`, `onRendering`, `onRendered`, `onDehydrate`, `onError`.
 
 ## Built-in components
 

package/api-surface.md

@@ -9,7 +9,9 @@ class Component = {
   new (): Component
   static durable?: boolean | {    ttl?: string;    scope?: 'user' | 'session';}
   static readonly __isFlowPage: true
+  static title?: string | ((component: never) => string)
   static using: Compose
+  $: (strings: TemplateStringsArray, ...values: unknown[]) => void
   $refresh: () => void
   $set: (key: string, value: unknown) => void
   _applyClientUpdate: (key: string, value: unknown, arrayKey?: string) => Promise<void>
@@ -31,10 +33,10 @@ class Component = {
   _prevChildIds: string[]
   _redirectStatus: number | null
   _redirectUrl: string | null
+  _resolveTitle: () => string | null
   _shouldRefresh: boolean
   _streamSender: ((ref: string, content: string, replace: boolean) => void) | null
   _taskSignal: AbortSignal | null
-  _titleValue: string | null
   _validateField: (field: string) => Promise<void>
   addError: (field: string, message: string) => void
   bind: (key: string, optionValue?: string) => Record<string, unknown>
@@ -42,7 +44,7 @@ class Component = {
   child: <C extends Component>(ChildClass: new () => C, opts?: {    key?: string | number;    props?: Partial<C>;    lazy?: boolean;    defer?: boolean;    stream?: boolean;    slots?: Record<string, string>;}) => Promise<HtmlNode>
   clearDurable: () => void
   client: (script: string) => void
-  currentUrl: (_options?: CurrentUrlOptions) => string
+  currentUrl: (options?: CurrentUrlOptions) => string
   dispatch: <K extends string>(name: K, ...args: K extends EventName ? EventArgs<FlowEvents[K]> : [payload?: Record<string, unknown>]) => void
   dispatchSelf: <K extends string>(name: K, ...args: K extends EventName ? EventArgs<FlowEvents[K]> : [payload?: Record<string, unknown>]) => void
   dispatchTo: <K extends string>(component: string, name: K, ...args: K extends EventName ? EventArgs<FlowEvents[K]> : [payload?: Record<string, unknown>]) => void
@@ -51,7 +53,7 @@ class Component = {
   flash: (message: string, optionsOrLevel?: FlashLevel | FlashOptions) => FlashBuilder
   hasSlot: (name?: string) => boolean
   layout: (page: HtmlNode) => HtmlNode | Promise<HtmlNode>
-  navigateCurrent: (_options?: CurrentUrlOptions) => Promise<void>
+  navigateCurrent: (options?: CurrentUrlOptions) => Promise<void>
   onBoot: (_ctx?: HttpContext) => Promise<void>
   onDehydrate: () => Promise<void>
   onError: (error: Error) => Promise<void>
@@ -72,7 +74,6 @@ class Component = {
   signal: AbortSignal
   slot: (name?: string) => HtmlNode
   stream: (ref: string, content: string, opts?: {    replace?: boolean;}) => void
-  title: {    (): string;    (value: string): void;}
   validate: (rulesOrForm?: ValidationRules | {    __isFlowForm: true;    _validateToErrors(): Record<string, string[]>;}) => Promise<void>
 }
 
@@ -258,7 +259,7 @@ function Loading = (props: LoadingProps) => HtmlNode
 
 function Modal = (props: ModalProps) => HtmlNode
 
-function on = (eventName: LooseEventName) => (fn: unknown, context: ClassMethodDecoratorContext) => void
+function on = (eventName: ListenerName) => (fn: unknown, context: ClassMethodDecoratorContext) => void
 
 function Pager = (props: PagerProps) => HtmlNode
 
@@ -709,6 +710,7 @@ interface LegendProps = {
 interface LinkProps = {
   [key: string]: unknown
   current?: boolean
+  down?: boolean
   exact?: boolean
   hover?: boolean
   href: string
@@ -760,7 +762,7 @@ interface PageClassWithMeta = {
   layout?: new () => Layout
   models?: Record<string, typeof BaseModel>
   name: string
-  title?: string
+  title?: string | ((component: never) => string)
 }
 
 interface PagerProps = {
@@ -1038,6 +1040,8 @@ type FlashPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' |
 
 type HtmlNode = {    html: string;}
 
+type ListenerName = (string & {}) | ((self: Record<string, any>) => string)
+
 type Mixin = (Base: TIn) => TOut
 
 type PresenceChannel = string | ((self: Record<string, any>) => string)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/flow",
-  "version": "1.7.0",
+  "version": "1.7.3",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -47,14 +47,15 @@
     "@alpinejs/morph": "^3.14.9",
     "@alpinejs/persist": "^3.14.9",
     "@alpinejs/resize": "^3.14.9",
-    "@zerotal/core": "1.7.0",
-    "@zerotal/orm": "1.7.0",
-    "@zerotal/validator": "1.7.0",
+    "@zerotal/client": "1.7.3",
+    "@zerotal/core": "1.7.3",
+    "@zerotal/orm": "1.7.3",
+    "@zerotal/validator": "1.7.3",
     "alpinejs": "^3.14.9",
     "typescript": "^5.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.7.0",
+    "@zerotal/broadcasting": "1.7.3",
     "@types/alpinejs": "^3.13.10",
     "@types/alpinejs__anchor": "^3.13.1",
     "@types/alpinejs__collapse": "^3.13.4",

package/src/Component.ts

@@ -7,7 +7,7 @@ import type {
   FlashActionStyle,
   FlashCallback,
 } from "./types.ts";
-import type { CurrentUrlOptions } from "./client/url.ts";
+import { buildUrlWithQuery, type CurrentUrlOptions } from "./client/url.ts";
 import {
   getExposedProps,
   getLockedProps,
@@ -22,6 +22,7 @@ import type { Schema, FieldRuleDefinition } from "@zerotal/validator";
 import type { ValidateBuilder } from "./decorators.ts";
 import { ValidationError } from "./validation.ts";
 import type { ValidationRules } from "./validation.ts";
+import { _applyWireValues, _isRegisteredModel } from "./synths/ModelSynth.ts";
 import { resolveUploadValue } from "./uploads/TemporaryUploadedFile.ts";
 import { toScriptJson } from "./utils.ts";
 import { _compose } from "./mixins.ts";
@@ -174,6 +175,31 @@ function _isProduction(): boolean {
 }
 
 /** Classes already warned about, so a hundred-row list logs once. */
+/**
+ * Encode one interpolated value as a JS literal for a client expression.
+ *
+ * The scripts are evaluated with `Alpine.evaluate(rootEl, script)`, so each value has to
+ * arrive as source text. JSON is a subset of JS expression syntax for every shape that
+ * survives `JSON.stringify`, which is what makes this exact rather than approximate — and it
+ * is what removes the old `@security` note from `client()`, where the caller built the string
+ * and owned the escaping.
+ *
+ * The cases JSON alone gets wrong are handled explicitly: `undefined` and functions stringify
+ * to nothing, `NaN` / `Infinity` become `null`, and `BigInt` throws.
+ */
+function _encodeClientValue(value: unknown): string {
+  if (value === undefined) return "undefined";
+  if (typeof value === "bigint") return `${value}n`;
+  if (typeof value === "number" && !Number.isFinite(value)) return String(value);
+
+  const json = JSON.stringify(value);
+  if (json === undefined) return "undefined"; // functions, symbols
+
+  // U+2028/U+2029 are legal inside a JSON string and legal in a JS string literal only since
+  // ES2019. Escaping them costs nothing and keeps the output safe in any JS context.
+  return json.replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+
 const _warnedKeyless = new Set<string>();
 
 function _warnKeylessChild(className: string): void {
@@ -348,19 +374,6 @@ export interface FlashBuilder {
 
 // ── Component ──────────────────────────────────────────────────────────────────────
 
-/**
- * Client-only URL helpers compile to `$flow.*` client expressions and never run on the
- * server. Reaching this means the call executed server-side — i.e. on a page the compiler
- * couldn't statically compile (so it fell back to the runtime renderer), or in a server action.
- */
-function _clientOnlyUrlHelper(method: string): never {
-  throw new Error(
-    `[Flow] this.${method}() is client-only — the compiler rewrites it to \`$flow.${method}\`. ` +
-      `It ran on the server, which means this page couldn't be statically compiled (e.g. it ` +
-      `uses a construct the AOT compiler bails on) or you called it from a server action.`,
-  );
-}
-
 /**
  * Base class for Flow pages — reactive server-side components rendered over a WebSocket.
  *
@@ -555,9 +568,6 @@ export abstract class Component {
   /** File downloads queued by download(). Sent as DownloadFrames. @internal */
   _downloads: Array<{ filename: string; content: string; mime: string }> = [];
 
-  /** Dynamic document.title set by title(). Included in the patch frame. @internal */
-  _titleValue: string | null = null;
-
   /** This component's id — set by the route handler (SSR) or the WS dispatcher. @internal */
   _flowId = "";
 
@@ -623,6 +633,26 @@ export abstract class Component {
    *
    * @category State & exposure
    */
+  /**
+   * The page's document title — a string, or a function of the component.
+   *
+   * ```ts
+   * static title = "Search";
+   * static title = (c: SearchPage) => (c.query ? `Search: ${c.query}` : "Search");
+   * ```
+   *
+   * Resolved on the server for every render and every patch, so the function form tracks
+   * state without the page doing anything: change `query` in an action and the tab title
+   * follows. Only the resolved string is ever sent to the browser.
+   *
+   * Declared here rather than left to convention. It was read structurally off the
+   * constructor, which meant no type, no autocomplete, and no entry in the API surface for
+   * something the docs already told people to write.
+   *
+   * @category Rendering
+   */
+  static title?: string | ((component: never) => string);
+
   static durable?: boolean | { ttl?: string; scope?: "user" | "session" };
 
   /** Set by {@link clearDurable}; the dispatcher deletes the durable entry after the request. @internal */
@@ -1039,7 +1069,9 @@ export abstract class Component {
    * this.client(`$refs.titleInput.focus()`);
    * this.client(`$el.querySelector('.toast').classList.add('visible')`);
    *
-   * @security Never interpolate unescaped user input into the expression string.
+   * @security Never interpolate unescaped user input into the expression string. Prefer the
+   *           {@link $} tagged template, which encodes interpolated values for you.
+   * @deprecated Use the `$` tagged template: ``this.$`$refs.titleInput.focus()` ``.
    * @category Actions
    */
   client(script: string): void {
@@ -1047,27 +1079,33 @@ export abstract class Component {
   }
 
   /**
-   * Gets the current title value.
-   * @category Actions
-   */
-  title(): string;
-
-  /**
-   * Update `document.title` in the browser after this action completes.
+   * Run a client-side expression from a server action, interpolating values safely.
    *
-   * @example
-   * this.title(`Search: ${this.query}`);
+   * A tagged template, so each `${…}` is encoded as a JS literal rather than concatenated
+   * into the source by the caller:
+   *
+   * ```ts
+   * this.$`console.log(${this.search})`;
+   * this.$`$refs.title.focus()`;
+   * this.$`$el.dataset.count = ${this.items.length}`;
+   * ```
+   *
+   * That is the whole reason it replaces {@link client}. Building the expression by hand meant
+   * the caller owned the escaping, and a value containing a quote — a name, a search term —
+   * produced either a syntax error or something worse.
+   *
+   * Runs in the component root's Alpine context after the action's DOM patch, exactly as
+   * {@link client} does: `$el`, `$refs` and the `$flow` magics are all in scope, and multiple
+   * calls execute in order after the single round trip.
    *
    * @category Actions
    */
-  title(value: string): void;
-
-  // Implementation signature (hidden from the public API)
-  title(value?: string): void | string {
-    if (value === undefined) {
-      return this._titleValue ?? (this.constructor as { title?: string }).title ?? "";
+  $(strings: TemplateStringsArray, ...values: unknown[]): void {
+    let script = strings[0] ?? "";
+    for (let i = 0; i < values.length; i++) {
+      script += _encodeClientValue(values[i]) + (strings[i + 1] ?? "");
     }
-    this._titleValue = value;
+    this._clientScripts.push(script);
   }
 
   // ── Validation ────────────────────────────────────────────────────────────
@@ -1286,29 +1324,39 @@ export abstract class Component {
   // `$flow` is typed globally (see augment.ts); `$flow.store` is typed by `FlowStore`.
 
   /**
-   * Build a URL from the current one with merged query params — client-only. Use it in a
-   * JSX expression: `href={this.currentUrl({ query: this.q })}`, `class={this.currentUrl() === "/" ? "on" : ""}`,
-   * or `{this.currentUrl(...)}`. The compiler rewrites `this.currentUrl` → `$flow.currentUrl`
-   * so it runs on the client. It never runs on the server — hitting this throw means the call
-   * reached server code (e.g. a page the compiler couldn't statically compile, or a server action).
+   * Build a URL from the current one with merged query params. Listed params are added or
+   * updated, unlisted ones are preserved, and a `null` / `undefined` / `""` value removes one.
+   *
+   * Works on both render paths, which is the point. Written in JSX —
+   * `href={this.currentUrl({ query: { page: 2 } })}` — the compiler rewrites it to
+   * `$flow.currentUrl` and it runs in the browser against `location.href`. Reached from server
+   * code it does the same work against the current request's URL, through the same pure
+   * {@link buildUrlWithQuery} helper, so the two paths cannot drift.
+   *
+   * It used to throw on the server, on the reasoning that the compiler always rewrote it. The
+   * compiler bails for reasons that have nothing to do with this call — one `__()` anywhere in
+   * the page is enough — and the page then renders through the runtime renderer, where this
+   * executes server-side. A translated page with a paginated link crashed.
    *
-   * @throws {Error} when executed on the server (it is meant to be compiled to `$flow.currentUrl`).
    * @category Navigation & redirects
    */
-  currentUrl(_options?: CurrentUrlOptions): string {
-    return _clientOnlyUrlHelper("currentUrl");
+  currentUrl(options: CurrentUrlOptions = {}): string {
+    return buildUrlWithQuery(request().url.href, options);
   }
 
   /**
-   * Build the URL as {@link currentUrl} does, then SPA-navigate to it — client-only. Use it in a
-   * client handler: `onClick={() => this.navigateCurrent({ query: { page: 2 } })}`. The compiler
-   * rewrites it to `$flow.navigateCurrent`. To navigate from server code, return a `redirect()`.
+   * Build the URL as {@link currentUrl} does, then go to it.
+   *
+   * In a JSX handler — `onClick={() => this.navigateCurrent({ query: { page: 2 } })}` — the
+   * compiler rewrites it to `$flow.navigateCurrent` and the browser SPA-navigates. Reached from
+   * server code it queues a redirect to the same URL: a different mechanism for the same
+   * intent, and the one the server has. See {@link currentUrl} for why both paths must work.
    *
-   * @throws {Error} when executed on the server (it is meant to be compiled to `$flow.navigateCurrent`).
    * @category Navigation & redirects
    */
-  navigateCurrent(_options?: CurrentUrlOptions): Promise<void> {
-    return _clientOnlyUrlHelper("navigateCurrent");
+  navigateCurrent(options: CurrentUrlOptions = {}): Promise<void> {
+    this.redirect(buildUrlWithQuery(request().url.href, options));
+    return Promise.resolve();
   }
 
   // ── File downloads ────────────────────────────────────────────────────────
@@ -1685,6 +1733,21 @@ export abstract class Component {
       (cur as { fill(v: Record<string, unknown>): void }).fill(value as Record<string, unknown>);
       return;
     }
+    // Model: same reasoning as the form above — fill the hydrated instance rather than
+    // replacing it with the plain object the client sent, so its class, methods and dirty
+    // tracking survive a `value={this.user.name}` edit. `_applyWireValues` keeps only
+    // `fillable` minus `hidden`, so a field the model never offered is ignored rather than
+    // written or thrown over.
+    if (
+      cur &&
+      typeof cur === "object" &&
+      _isRegisteredModel(cur) &&
+      value &&
+      typeof value === "object"
+    ) {
+      _applyWireValues(cur, value);
+      return;
+    }
     // Signed upload references become TemporaryUploadedFile instances (signature verified);
     // all other values pass through unchanged.
     (this as Record<string, unknown>)[key] = resolveUploadValue(value);
@@ -1737,6 +1800,22 @@ export abstract class Component {
 
   // ── Effect draining (called by WS handler after action) ──────────────────
 
+  /**
+   * The title to send with this frame — `static title` resolved against this component.
+   *
+   * Resolved per frame rather than once, which is what lets the function form track state:
+   * change what it reads and the next patch carries the new title.
+   *
+   * @internal
+   */
+  _resolveTitle(): string | null {
+    const declared = (this.constructor as { title?: unknown }).title;
+    if (typeof declared === "function") {
+      return String((declared as (c: unknown) => unknown)(this));
+    }
+    return typeof declared === "string" ? declared : null;
+  }
+
   /** @internal — read by the WS handler after action execution. */
   _drainEffects(): FlowEffects {
     const effects: FlowEffects = {
@@ -1747,12 +1826,11 @@ export abstract class Component {
       errors: this._errors,
       events: this._events.splice(0),
       downloads: this._downloads.splice(0),
-      title: this._titleValue,
+      title: this._resolveTitle(),
     };
     this._redirectUrl = null;
     this._redirectStatus = null;
     this._shouldRefresh = false;
-    this._titleValue = null;
     // _errors intentionally NOT reset here: errors persist across actions so the
     // client continues showing field messages after e.g. a failed save that then
     // dispatches a flash. Call resetValidation() or a passing validate() to clear.

package/src/browser/FlowBrowser.ts

@@ -76,8 +76,13 @@ export class FlowBrowser {
       // than on a sleep is what makes these tests deterministic: a slow boot
       // waits longer, and a bridge that never connects fails with a clear reason
       // instead of a mystery assertion further down.
+      //
+      // Guarded on `document.body` existing: the poll can land between a
+      // navigation committing and the body being parsed, and `null.getAttribute`
+      // throws out of `evaluate` rather than returning false — so the wait died
+      // with a TypeError instead of polling once more.
       await page.waitUntil(
-        `document.body.getAttribute("data-flow-connection") === "online"`,
+        `!!document.body && document.body.getAttribute("data-flow-connection") === "online"`,
         "Flow to connect its WebSocket",
         timeout,
       );
@@ -125,7 +130,7 @@ export class FlowBrowser {
 
     if (options.waitForConnection !== false) {
       await this.waitUntil(
-        `document.body.getAttribute("data-flow-connection") === "online"`,
+        `!!document.body && document.body.getAttribute("data-flow-connection") === "online"`,
         "Flow to connect its WebSocket",
         timeout,
       );