@zerotal/flow 1.7.2 → 1.7.3

package/CHANGELOG.md

@@ -13,7 +13,7 @@ change.
 
 ### Added
 
-- **`@on` can name a channel per instance.** A listener's channel is read off the *class*, so
+- **`@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
@@ -52,6 +52,20 @@ change.
 
 ### 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
@@ -94,7 +108,7 @@ change.
   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:
+  `<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.

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.2",
+  "version": "1.7.3",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -47,15 +47,15 @@
     "@alpinejs/morph": "^3.14.9",
     "@alpinejs/persist": "^3.14.9",
     "@alpinejs/resize": "^3.14.9",
-    "@zerotal/client": "1.7.2",
-    "@zerotal/core": "1.7.2",
-    "@zerotal/orm": "1.7.2",
-    "@zerotal/validator": "1.7.2",
+    "@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.2",
+    "@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/client/bridge.ts

@@ -2900,12 +2900,32 @@ async function _navigateTo(href: string, options: NavigateOptions = {}): Promise
     // the animation ends at the right offset instead of sliding there.
     _applyScroll(scrollIntent, _hashOf(href));
   };
-  const _startVT = (document as unknown as { startViewTransition?: (cb: () => void) => unknown })
-    .startViewTransition;
+  // The return value is typed here rather than cast at the call site, so reading
+  // the transition's promises below costs no new assertion.
+  const _startVT = (
+    document as unknown as {
+      startViewTransition?: (cb: () => void) => {
+        ready?: Promise<unknown>;
+        finished?: Promise<unknown>;
+      };
+    }
+  ).startViewTransition;
   const _reduceMotion =
     typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
-  if (typeof _startVT === "function" && !_reduceMotion) _startVT.call(document, _swap);
-  else _swap(); // reduced-motion (or unsupported): swap instantly, no cross-page animation
+  if (typeof _startVT === "function" && !_reduceMotion) {
+    const _vt = _startVT.call(document, _swap);
+    // A navigation that starts while a transition is still running makes the
+    // browser skip the older one and reject its `ready` and `finished` promises
+    // with an AbortError. Nothing has gone wrong — the swap itself already ran
+    // inside the callback — but an unhandled rejection reaches `window.onerror`
+    // and whatever error tracker the app has wired to it. Clicking through links
+    // faster than the animation reported a stream of errors describing an
+    // animation the browser skipped on purpose.
+    void _vt?.ready?.catch(() => {});
+    void _vt?.finished?.catch(() => {});
+  } else {
+    _swap(); // reduced-motion (or unsupported): swap instantly, no cross-page animation
+  }
 
   if (push) _pushHistoryEntry(href);
   const incomingTitle = doc.querySelector("title");

package/src/decorators.ts

@@ -970,7 +970,7 @@ export function validate(
  *
  * @category Realtime
  */
-export type ListenerName = LooseEventName | ((self: Record<string, any>) => string);
+export type ListenerName = LooseEventName | ((self: Record<string, any>) => string); // eslint-disable-line @typescript-eslint/no-explicit-any -- `unknown` would break `self.issue.id`
 
 /**
  * Binds a method as a cross-component (realtime) event listener. Auto-exposes the method.

package/src/dehydrate.ts

@@ -222,6 +222,49 @@ export async function hydrate<T extends Component>(
   return page;
 }
 
+/**
+ * A copy of `snapshot` with client-supplied hidden values removed, re-signed.
+ *
+ * A hidden field the user typed — a new password — rides in the snapshot so it survives until
+ * they save. That is fine on the wire, where it goes back to the browser that produced it,
+ * and wrong in the durable store, which writes the whole snapshot server-side after every
+ * request and may be backed by Redis. A half-typed password should not be waiting there for
+ * anyone, and resuming into one is not what durable is for.
+ *
+ * Re-signed rather than edited in place: the checksum covers `data`, so a strip without a
+ * fresh signature would produce a snapshot that fails its own verification on restore.
+ *
+ * @internal
+ */
+export function stripPendingSecrets(snapshot: Snapshot): Snapshot {
+  let touched = false;
+  const data: SnapshotData = {};
+
+  for (const [prop, [value, meta]] of Object.entries(snapshot.data)) {
+    const pending = meta["p"];
+    if (
+      !Array.isArray(pending) ||
+      pending.length === 0 ||
+      value === null ||
+      typeof value !== "object"
+    ) {
+      data[prop] = [value, meta];
+      continue;
+    }
+    touched = true;
+    const cleanValue: Record<string, unknown> = { ...(value as Record<string, unknown>) };
+    for (const key of pending as string[]) delete cleanValue[key];
+    const cleanMeta = { ...meta };
+    delete cleanMeta["p"];
+    data[prop] = [cleanValue, cleanMeta];
+  }
+
+  if (!touched) return snapshot;
+
+  const stripped = { ...snapshot, data };
+  return { ...stripped, checksum: _sign(_signingPayload(stripped)) };
+}
+
 /** Verify a snapshot's HMAC against the current APP_KEY. Public so durable-snapshot
  *  restore can validate a stored snapshot before trusting it (a rotated key → false). */
 export function verifySnapshot(snapshot: Snapshot): boolean {

package/src/durable.ts

@@ -13,7 +13,7 @@
 import type { Component } from "./Component.ts";
 import type { Snapshot } from "./types.ts";
 import type { HttpContext } from "@zerotal/core";
-import { verifySnapshot, applySnapshotData } from "./dehydrate.ts";
+import { verifySnapshot, applySnapshotData, stripPendingSecrets } from "./dehydrate.ts";
 
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
 
@@ -221,7 +221,10 @@ export async function persistDurable(
     await _store.delete(key);
     return;
   }
-  await _store.set(key, snapshot, cfg.ttlMs);
+  // Never persist a hidden field the client is part-way through typing — see
+  // `stripPendingSecrets`. The wire may carry it back to the browser that produced it; a
+  // server-side store, possibly Redis, may not hold it.
+  await _store.set(key, stripPendingSecrets(snapshot), cfg.ttlMs);
 }
 
 /**

package/src/registry.ts

@@ -107,8 +107,12 @@ export { getRenderlessMethods };
 export interface PageClassWithMeta {
   new (): Component;
   name: string;
-  /** Sets the HTML <title> for this page. */
-  title?: string;
+  /**
+   * Sets the HTML `<title>` for this page — a string, or a function of the component
+   * instance. Resolve it with the component's `_resolveTitle()` rather than reading it
+   * directly, so both forms are handled in one place.
+   */
+  title?: string | ((component: never) => string);
   /** Raw HTML to inject into <head> for this page. */
   head?: string;
   /** Optional model associations for auto-registration. */

package/src/router.ts

@@ -9,6 +9,7 @@ import type { PageClassWithMeta } from "./registry.ts";
 import { registerPage } from "./registry.ts";
 import { dehydrate, warnIfLarge } from "./dehydrate.ts";
 import { _renderFlowPage } from "./jsx-runtime.ts";
+import { escapeHtml } from "@zerotal/core/helpers";
 import { populatePresence } from "./presence.ts";
 import { populateShared } from "./shared.ts";
 import { restoreDurable, persistDurable } from "./durable.ts";
@@ -220,7 +221,12 @@ export function _makeFlowHandler(path: string, PageClass: PageClassWithMeta) {
               bodyContent = flowRoot.html;
             }
 
-            const titleTag = PageClass.title ? `<title>${PageClass.title}</title>` : "";
+            // Through the component, not `PageClass.title` directly: `static title` may be a
+            // function of the component, and reading the raw static would render its source.
+            // Escaped because a resolved title can carry state — a search term reaching
+            // `<title>` unescaped is an injection, and the old direct interpolation had none.
+            const resolvedTitle = page._resolveTitle();
+            const titleTag = resolvedTitle ? `<title>${escapeHtml(resolvedTitle)}</title>` : "";
             // Component head takes precedence; layout head provides global resources.
             const headExtra = [PageClass.head ?? "", layoutHead].filter(Boolean).join("\n  ");
 

package/src/synths/CollectionSynth.ts

@@ -5,15 +5,10 @@
 // registered model, so plain arrays fall through to the recursive serializer.
 import type { BaseModel } from "@zerotal/orm";
 import { registerSynth } from "./index.ts";
-import { _modelRegistry, _modelClassToName } from "./ModelSynth.ts";
+import { _isModel, _modelKey, _resolveModel } from "./ModelSynth.ts";
 
 function isModelOf(value: unknown, ctor: typeof BaseModel): boolean {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    (value as object).constructor === ctor &&
-    typeof (value as Record<string, unknown>)["id"] !== "undefined"
-  );
+  return _isModel(value) && (value as object).constructor === ctor;
 }
 
 registerSynth({
@@ -22,11 +17,11 @@ registerSynth({
   match(value): value is BaseModel[] {
     if (!Array.isArray(value) || value.length === 0) return false;
     const first = value[0] as unknown;
-    if (typeof first !== "object" || first === null) return false;
-    // Key off the constructor, not constructor.name, so the match survives
-    // minification (same hardening as ModelSynth).
+    // Registration is not required: an unregistered model would fall through to the generic
+    // serializer, which never calls `toJSON()` and so publishes every column. Same reasoning
+    // as ModelSynth's `match`.
+    if (!_isModel(first)) return false;
     const ctor = (first as object).constructor as typeof BaseModel;
-    if (!_modelClassToName.has(ctor)) return false;
     // Only claim a homogeneous array. A mixed array would be dehydrated under a
     // single class tag and silently lose the odd-one-out on hydrate, so let it
     // fall through to the recursive serializer, which handles each model via
@@ -36,18 +31,25 @@ registerSynth({
 
   dehydrate(value: BaseModel[], meta) {
     const ctor = (value[0] as object).constructor as typeof BaseModel;
-    meta["class"] = _modelClassToName.get(ctor)!;
+    const key = _modelKey(ctor);
+    if (!key) {
+      throw new Error(
+        `[Flow] ${ctor.name} has no table name, so it cannot be sent across the wire. ` +
+          `Give it @table("…") — every model in app/models has one.`,
+      );
+    }
+    meta["class"] = key;
     return value.map((m) => (m as unknown as Record<string, unknown>)["id"]);
   },
 
   async hydrate(data, meta) {
     const cls = meta["class"] as string | undefined;
     if (!cls) throw new Error("[Flow] CollectionSynth: missing class in meta");
-    const Model = _modelRegistry.get(cls);
+    const Model = _resolveModel(cls);
     if (!Model) {
       throw new Error(
-        `[Flow] Model "${cls}" is not registered. ` +
-          `Add it to your Component's static models property.`,
+        `[Flow] No model maps to "${cls}". Models live in app/models, where they are ` +
+          `discovered automatically — check the class is there and its @table matches.`,
       );
     }
     const ids = data as unknown[];

package/src/synths/ModelSynth.ts

@@ -1,4 +1,5 @@
 import type { BaseModel } from "@zerotal/orm";
+import { modelsByName } from "@zerotal/orm";
 import { registerSynth } from "./index.ts";
 
 // Models register themselves here when their class is imported.
@@ -12,67 +13,366 @@ export const _modelRegistry = new Map<string, typeof BaseModel>();
 export const _modelClassToName = new Map<typeof BaseModel, string>();
 
 /**
- * Register an ORM model class under a stable name so the model synth can send it
- * across the wire: a model prop is dehydrated to its `id` (tagged with this name)
- * and hydrated back by re-fetching via `findOrFail`.
+ * Associate a model class with an explicit wire name, overriding its table name.
  *
  * @remarks
- * Registering by an explicit name (rather than `constructor.name`) keeps snapshots
- * valid under minification, where the class name may be mangled. You normally don't
- * call this directly — declare models in a component's `static models` map and the
- * framework registers them when the page is registered.
+ * **Not part of the normal path.** Models live in `app/models` and are discovered there, and
+ * a model travels under its table name — already declared, and immune to minification. There
+ * is nothing to register.
  *
- * @param name - Stable, developer-assigned name recorded in the snapshot's `meta.class`.
- * @param ModelClass - The `BaseModel` subclass to associate with `name`.
+ * This exists for the framework's own wiring: a component's `static models` map routes
+ * through it, and it takes precedence over the table name when both are present.
  *
- * @example
- * ```tsx
- * class ShowPost extends Component {
- *   static models = { Post }; // auto-calls registerFlowModel("Post", Post)
- *   @locked post!: Post;      // survives the round-trip as a rehydrated model
- * }
+ * @param name - The wire name recorded in the snapshot's `meta.class`.
+ * @param ModelClass - The `BaseModel` subclass to associate with `name`.
  *
- * // Or register manually (e.g. outside a page's static models):
- * registerFlowModel("Post", Post);
- * ```
+ * @internal
  */
 export function registerFlowModel(name: string, ModelClass: typeof BaseModel): void {
   _modelRegistry.set(name, ModelClass);
   _modelClassToName.set(ModelClass, name);
 }
 
+/**
+ * Is this value an ORM model?
+ *
+ * Duck-typed, because importing `BaseModel` as a value here would be circular. A model class
+ * always carries a `table` string (set by `@table("…")` or inflected from the class name) and
+ * every instance has `toJSON` — together specific enough to tell a model from a plain object.
+ *
+ * **This deliberately does not require registration.** It used to, and an unregistered model
+ * fell through to the generic serializer, which walks properties directly and never calls
+ * `toJSON()` — so `hidden` was bypassed and every column, password hashes included, was
+ * written into the page. It failed on the second interaction and never the first, and
+ * `FlowTest` does not round-trip through a synth, so only a browser ever saw it. A missing
+ * declaration must not be able to cause that.
+ *
+ * @internal
+ */
+export function _isModel(value: unknown): value is BaseModel {
+  if (typeof value !== "object" || value === null) return false;
+  const ctor = (value as object).constructor as { table?: unknown } | undefined;
+  if (typeof ctor !== "function") return false;
+  if (typeof (ctor as { table?: unknown }).table !== "string") return false;
+  return typeof Reflect.get(value, "toJSON") === "function";
+}
+
+/**
+ * The stable key a model travels under.
+ *
+ * The table name, which the app already declares and a minifier cannot touch — unlike
+ * `constructor.name`, which is exactly what `Post` becomes `n` in a production build. An
+ * explicit {@link registerFlowModel} name still wins, for a model that wants one.
+ *
+ * @internal
+ */
+export function _modelKey(ctor: typeof BaseModel): string | undefined {
+  const explicit = _modelClassToName.get(ctor);
+  if (explicit) return explicit;
+  const table: unknown = ctor.table;
+  return typeof table === "string" && table.length > 0 ? table : undefined;
+}
+
+/**
+ * Find the class a key names — an explicit registration first, then the ORM's own registry,
+ * which `app/models` auto-discovery populates for every model in the app.
+ *
+ * @internal
+ */
+export function _resolveModel(key: string): typeof BaseModel | undefined {
+  const explicit = _modelRegistry.get(key);
+  if (explicit) return explicit;
+
+  for (const ctor of modelsByName.values()) {
+    if (Reflect.get(ctor, "table") === key) return ctor as typeof BaseModel;
+  }
+  return undefined;
+}
+
+const _wireFieldCache = new WeakMap<typeof BaseModel, readonly string[]>();
+
+/**
+ * Convert a model's `toJSON()` output so any nested model in it is its own `toJSON()` too.
+ *
+ * `BaseModel.toJSON()` assigns relations by reference — `out[key] = this[key]` — so a loaded
+ * `post.author` comes out as a live `User`. In practice its `hidden` list still applied,
+ * because whatever stringified the snapshot honoured the `toJSON` contract. That is an
+ * implicit guarantee sitting under a security property, and it holds only for as long as
+ * every path to the wire goes through `JSON.stringify`.
+ *
+ * Doing it here makes it explicit: what leaves this synth is data, and every model in it has
+ * already answered for its own hidden columns.
+ *
+ * @internal
+ */
+export function _deepToJson(value: unknown, seen = new WeakSet<object>()): unknown {
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return undefined; // a relation cycle (post.author.posts)
+  seen.add(value);
+
+  if (Array.isArray(value)) return value.map((v) => _deepToJson(v, seen));
+
+  if (_isModel(value)) {
+    const json = Reflect.get(value, "toJSON") as () => Record<string, unknown>;
+    return _deepToJson(json.call(value), seen);
+  }
+
+  // A Date, a Carbon, anything with its own serialisation — leave it to the value's own
+  // contract rather than walking into its internals.
+  if (typeof Reflect.get(value, "toJSON") === "function") return value;
+
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = _deepToJson(v, seen);
+  }
+  return out;
+}
+
+/**
+ * The fields a client may **write back**: `fillable`.
+ *
+ * `hidden` is not subtracted, because the two allow-lists answer different questions.
+ * `fillable`/`guarded` govern writes; `visible`/`hidden` govern display. A password is the
+ * case that makes the difference concrete: it is fillable because a user sets it, and hidden
+ * because the stored hash must never be shown. Subtracting made it unwritable too, which
+ * meant a bound password field silently did nothing.
+ *
+ * What keeps that safe is that a hidden field is never *sent* — see the synth's `dehydrate`
+ * and {@link _pendingSecrets}.
+ *
+ * `fillable` on its own is the wrong set. It is the mass-assignment allow-list — what a user
+ * may *write* — and that is not the same as what may be *shown*. The ORM's own example is the
+ * counter-example:
+ *
+ * ```ts
+ * static fillable = ["name", "email", "password"];
+ * static hidden   = ["password"];
+ * ```
+ *
+ * A password is fillable and must never reach a browser. The subtraction lives here rather
+ * than in each model because the failure is silent: nothing goes wrong until someone reads
+ * the snapshot in dev tools.
+ *
+ * A model that declares no `fillable` accepts **no writes at all** — which is the ORM's own
+ * default, since it guards mass assignment until told otherwise. Such a model is still fully
+ * readable on the client; it simply cannot be edited there.
+ *
+ * @internal
+ */
+export function _writableFields(ModelClass: typeof BaseModel): readonly string[] {
+  const cached = _wireFieldCache.get(ModelClass);
+  if (cached) return cached;
+
+  const fields = Object.freeze([...(ModelClass.fillable ?? [])]);
+
+  _wireFieldCache.set(ModelClass, fields);
+  return fields;
+}
+
+/**
+ * Whether a value is an instance of a model registered with {@link registerFlowModel}.
+ *
+ * The same duck-typed check the synth's `match` uses, exported so `$set` can recognise a
+ * hydrated model without importing `BaseModel` (which would be circular).
+ *
+ * @internal
+ */
+export function _isRegisteredModel(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as Record<string, unknown>)["constructor"] === "function" &&
+    _modelClassToName.has((value as object).constructor as typeof BaseModel)
+  );
+}
+
+/**
+ * Hidden fields whose current value came from the client, per model instance.
+ *
+ * A hidden column is never sent — that is the point of `hidden`, and the stored password hash
+ * has no business in a page. But a hidden column can still be *written*: a user typing a new
+ * password needs that value to survive until they save, and dropping it would mean the field
+ * silently emptied itself on the next interaction.
+ *
+ * The distinction that makes this safe is **who produced the value**. Echoing back something
+ * the client just typed tells it nothing it does not already have. Echoing a value the server
+ * computed — a generated token, a rotated secret — would be a disclosure, which is why this
+ * tracks what {@link _applyWireValues} actually applied rather than asking `$dirty()`, which
+ * cannot tell the two apart.
+ *
+ * @internal
+ */
+const _pendingSecrets = new WeakMap<object, Set<string>>();
+
+/** The hidden fields on `model` currently holding a client-supplied value. @internal */
+export function _pendingSecretKeys(model: object): readonly string[] {
+  return [...(_pendingSecrets.get(model) ?? [])];
+}
+
+/** Mark hidden fields as client-supplied, so they survive the next round-trip. @internal */
+export function _markPendingSecrets(model: object, keys: readonly string[]): void {
+  if (keys.length === 0) return;
+  const set = _pendingSecrets.get(model) ?? new Set<string>();
+  for (const k of keys) set.add(k);
+  _pendingSecrets.set(model, set);
+}
+
+/**
+ * Restore a model to the state it was in when we last dehydrated it.
+ *
+ * The values come from the snapshot, which is HMAC-signed over `data` and `memo` — so they
+ * are the server's own last output, not anything a browser could author. A change an action
+ * made and did not save is part of that state, and restoring it is what stops the field
+ * reverting the moment anything else happens.
+ *
+ * **Only the writable fields.** Everything else — `role`, `createdAt`, anything the server
+ * owns — comes from the row that was just fetched, which is current by definition. Carrying
+ * those forward from a snapshot would replace fresh values with older ones for no gain,
+ * since nothing in the round-trip could have changed them. The editable subset is the only
+ * part that holds state worth preserving.
+ *
+ * (Hidden columns never appear here anyway: `toJSON()` leaves them out, so there is nothing
+ * to restore. The set is the same one {@link _applyWireValues} enforces.)
+ *
+ * Only properties the instance already carries are set, so an `appends` entry or a computed
+ * accessor in `toJSON()` output cannot be written over the real one. `id` is skipped — the
+ * identity is `meta.id` and the row was fetched by it.
+ *
+ * @internal
+ */
+export function _restoreSnapshotValues(model: object, data: unknown): void {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) return;
+
+  const writable = new Set(_writableFields(model.constructor as typeof BaseModel));
+
+  for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+    if (key === "id" || key.startsWith("_")) continue;
+    if (!writable.has(key)) continue;
+    if (!Object.prototype.hasOwnProperty.call(model, key)) continue;
+    Reflect.set(model, key, value);
+  }
+}
+
+/**
+ * Apply client-supplied values to a model, keeping only its wire fields.
+ *
+ * Filters rather than letting `fill()` reject: `fill()` throws `MassAssignmentError` off
+ * `fillable`, and this data comes from the browser, so a hostile payload would become a 500
+ * instead of being ignored. Everything that survives the filter is fillable by construction,
+ * so `fill()` runs its normal path — reactive accessors, casts and all.
+ *
+ * @internal
+ */
+export function _applyWireValues(model: object, data: unknown): void {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) return;
+
+  const allowed = new Set(_writableFields(model.constructor as typeof BaseModel));
+  const incoming: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+    if (allowed.has(key)) incoming[key] = value;
+  }
+
+  if (Object.keys(incoming).length === 0) return;
+
+  // `fill` is typed `UpdatePayload<this>`, which cannot be expressed for a model this
+  // function only knows as `BaseModel`. The values are already filtered to the class's own
+  // `fillable`, so the assertion is narrower than it looks.
+  (model as unknown as { fill(v: Record<string, unknown>): unknown }).fill(incoming);
+
+  // A hidden field the client just set has to travel back, or it empties itself on the next
+  // interaction. Recorded here, where we know the value came from the browser.
+  const hidden = new Set((model.constructor as typeof BaseModel).hidden ?? []);
+  _markPendingSecrets(
+    model,
+    Object.keys(incoming).filter((k) => hidden.has(k)),
+  );
+}
+
 registerSynth({
   key: "mdl",
 
-  match(value): value is BaseModel {
-    // Lazy check: duck-type for BaseModel (avoids circular import of BaseModel class)
-    return (
-      typeof value === "object" &&
-      value !== null &&
-      typeof (value as Record<string, unknown>)["id"] !== "undefined" &&
-      typeof (value as Record<string, unknown>)["constructor"] === "function" &&
-      _modelClassToName.has((value as object).constructor as typeof BaseModel)
-    );
-  },
+  match: _isModel,
 
   dehydrate(value: BaseModel, meta) {
     // Use the stable registered name rather than constructor.name, which is
     // mangled in minified production builds.
-    meta["class"] = _modelClassToName.get((value as object).constructor as typeof BaseModel)!;
-    return (value as unknown as Record<string, unknown>)["id"];
+    const ctor = (value as object).constructor as typeof BaseModel;
+    const key = _modelKey(ctor);
+    if (!key) {
+      throw new Error(
+        `[Flow] ${ctor.name} has no table name, so it cannot be sent across the wire. ` +
+          `Give it @table("…") — every model in app/models has one.`,
+      );
+    }
+    meta["class"] = key;
+
+    // The id goes in `meta`, never in `data`. `$set` replaces a prop's data and never
+    // touches its meta, so keeping the key out of the editable payload is what makes
+    // "the client cannot change which record this is" true rather than merely intended.
+    meta["id"] = Reflect.get(value, "id");
+
+    // What the client is *shown* is the model's own serialisation surface — `toJSON()`, which
+    // already honours `visible` / `hidden` / `appends` and any per-instance overrides. Using
+    // the writable set here instead would have made `@locked` pointless: a display model
+    // declares no `fillable`, so it would have arrived as a bare id, and a prop that puts
+    // nothing on the client is what `@transient` is for.
+    const toJson = Reflect.get(value, "toJSON");
+    const out: Record<string, unknown> =
+      typeof toJson === "function"
+        ? (_deepToJson(toJson.call(value)) as Record<string, unknown>)
+        : { id: Reflect.get(value, "id") };
+
+    // Hidden fields the client itself supplied ride along, and say so in `meta` so the next
+    // hydrate keeps treating them as pending rather than as a read of the row. Nothing the
+    // *server* put there is echoed — only what came back through `updates`.
+    const pending = _pendingSecretKeys(value);
+    if (pending.length > 0) {
+      for (const key of pending) out[key] = Reflect.get(value, key);
+      meta["p"] = pending;
+    }
+
+    return out;
   },
 
   async hydrate(data, meta) {
     const cls = meta["class"] as string | undefined;
     if (!cls) throw new Error("[Flow] ModelSynth: missing class in meta");
-    const Model = _modelRegistry.get(cls);
+    const Model = _resolveModel(cls);
     if (!Model) {
       throw new Error(
-        `[Flow] Model "${cls}" is not registered. ` +
-          `Add it to your Component's static models property.`,
+        `[Flow] No model maps to "${cls}". Models live in app/models, where they are ` +
+          `discovered automatically — check the class is there and its @table matches.`,
       );
     }
-    // BaseModel.findOrFail is a static method
-    return (Model as unknown as { findOrFail(id: unknown): Promise<BaseModel> }).findOrFail(data);
+
+    // `meta.id` is the identity; `data` is only ever field values. A snapshot written before
+    // wire fields existed carried the id as `data`, so fall back to it — those stay valid
+    // for their remaining lifetime rather than throwing.
+    const id = meta["id"] !== undefined ? meta["id"] : data;
+
+    // Fetch first, overlay second. The fresh row supplies everything the client did not
+    // touch; the client's values win where it typed. `_original` is therefore the row as it
+    // is *now*, so `$dirty()` — and the UPDATE `save()` builds from it — covers exactly the
+    // fields that genuinely differ from the database.
+    const model = await (
+      Model as unknown as { findOrFail(id: unknown): Promise<BaseModel> }
+    ).findOrFail(id);
+
+    // Fetch for identity — a live instance, its relations, and a 404 if the row is gone —
+    // then restore the state we last had. The snapshot is signed, so those values are ours,
+    // not the client's; an unsaved change an action made is part of the component's state and
+    // has to survive the round-trip or the field would revert the moment anything else
+    // happened.
+    //
+    // Client *intent* arrives separately, in the frame's `updates` map, and is applied after
+    // this through `_applyClientUpdate` — where `fillable` is enforced.
+    _restoreSnapshotValues(model, data);
+
+    // Keep the marks across the round-trip, so a pending password survives more than one
+    // interaction rather than only the next.
+    const pending = meta["p"];
+    if (Array.isArray(pending)) _markPendingSecrets(model, pending as string[]);
+
+    return model;
   },
 });