@zerotal/flow 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -1,13 +1,42 @@
-# Changelog — @zerotal/flow
+# Changelog — @zerotal/flow
 
 All notable changes to this package are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/); this package
 follows the Zerotal monorepo's unified versioning.
 
-**Maturity: `stable`**
+**Maturity: `experimental`** — matching this package's `maturity` field. Flow shares the
+monorepo's version line but not the stable packages' API guarantees; it may change
+between minor versions.
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-08-08
+
+### Fixed
+
+- **A radio group can be bound again.** `_readModelValue` special-cased checkboxes but not radios, so every radio in a group contributed its `value` whether or not it was checked and the last one in DOM order won — a leisure enquiry silently became a corporate one, with no error anywhere. A radio now reports a value only when checked, and the flush, `input` and `flow:model.blur` paths all skip the `undefined` an unchecked radio returns. The blur path was additionally reading `.value` raw, so it sent `"on"` for checkboxes. Server-to-client sync no longer assigns `el.value` on a radio either, which was rewriting every option in a group to the group's current value and destroying the choices.
+- **A reactive sibling attribute no longer suppresses a `value` binding.** The getter capture is a single slot and JSX evaluates every prop before `jsx()` runs, so `value={this.destination} disabled={this.notSure}` left the capture on `notSure`, the freshness check failed, and the element rendered with no `flow:model` at all — the field accepted typing and nothing reached the server. The capture now retains the element's reads, so a binding finds the key matching its own value. Only keys genuinely read through a `this.` getter qualify, so a literal that happens to equal state still binds nothing.
+- **A radio no longer acquires a binding by coincidence.** Value-identity inference matched whichever single option currently equalled the bound property, so that one radio claimed the whole group's model. Radios are now excluded from binding inference, as `<option>` already was; bind a group explicitly with `{...this.bind('type', optionValue)}`.
+- **`flow:click` no longer breaks the control it sits on.** `preventDefault()` was unconditional, which cancels the element's activation behaviour — a radio or checkbox carrying `onClick` never became checked, and no handler could compensate, because the browser restores the pre-click checkedness after listeners run. The default is now cancelled only where it is in the way (anchors, submit buttons and submit inputs), with `.prevent` to force it and `.passive` to opt out.
+- **Click handlers carrying a modifier are no longer dead.** Modifiers are emitted into the attribute name (`flow:click.stop`), but the listener looked handlers up with an exact attribute selector — which cannot match that name — so `onClick={flow(this.save).stop}` did nothing at all, silently. Handler lookup now reads both forms and applies `.stop`.
+- **`request().ip()` answers inside an action.** The WebSocket dispatcher builds its own `HttpContext`, which has no Bun `Server` behind it, so `ip()` resolved to `null` for every action even though the peer address was captured at upgrade. It is now supplied.
+
+### Added
+
+- **A server action can take arguments from a loop.** `() => this.archive(row.id)` compiles to `flow:click="archive"` plus `data-args`, with the arguments evaluated server-side during the render where `row` exists. Previously the arrow was emitted verbatim, so `row` was undefined in the browser and the click threw a `ReferenceError` into the console and nothing else. An argument that reads `this` still stays a live client expression so it re-evaluates against reactive state.
+- `Component.bind(key, optionValue)` — the explicit way to bind one member of a radio group.
+- `FlowTest.tolerateErrors()`, `assertErrored()`, `lastError()`, `seed()` and `render()`.
+
+### Changed
+
+- The members `Component` reserves are documented, and pinned by a test so the list cannot drift. A page property colliding with one is a compile error with a clear message, but `title` — taken by the page-title accessor — is an obvious name for a field on a row representing a media item or a review, and there was no list to check.
+- **`FlowTest.call()` rethrows.** A `ValidationError` is still an expected outcome, but any other error is routed to `onError()` (as in production) and then rethrown, so a broken action fails its test instead of looking like one that ran and did nothing. Previously it was swallowed — and a throwing `onError` was swallowed too. Call `tolerateErrors()` when the error path is what you are testing.
+- **`FlowTest.set()` re-renders.** A test that set a property and then read `html()` was silently asserting against the previous render. `seed()` is the batching form that does not render.
+- **A handler pointing at an un-`@expose`d method is a build error.** The allowlist is the exposed methods, so an undecorated method was absent from it — the compiler emitted `flow:click="submit"`, the button rendered enabled, and the click sent a frame the server refused, reporting the refusal only over the WebSocket to `console.error`. Nothing reached the server log and the page did not change. The member table needed to catch this was already built; it is now used.
+- **A client expression referencing a name the browser will not have is reported at boot**, naming the identifier and pointing at `data-args`. The page falls back to the runtime renderer rather than failing the build: the check works from a hand-maintained list of globals, and a false positive should not stop a server starting. In CSP-safe mode, where there is no runtime fallback, it is fatal.
+- The compiler warns when more than half of a page set falls back to the runtime renderer, naming `ZT_FLOW_COMPILE_LOG=1`. Falling back for a page or two is normal; an entire app doing it silently is not.
+- Maturity is stated in the README and npm metadata. It was only ever a `package.json` field npm does not render, and this changelog said `stable` while the manifest said `experimental`.
+
 ## [1.0.3] — 2026-08-07
 
 ### Changed
@@ -27,40 +56,40 @@ _First public release._
 
 ### Added
 
-- **`make:flow` scaffolding command.** The flagship server-driven layer previously had no generator — every `Component` was hand-written (the audit's #1 DX gap). `bun zt make:flow Name` emits a ready-to-run class with the JSX pragma, imports, and an `@expose`/`render` skeleton: `--child` scaffolds a child component (with `setup(props)`), `--crud` a resourceful page (list + create/edit/delete + `@validate` + a form), and `--layout Foo` wraps a page in a layout (with the correct relative import depth for nested names like `Users/Index`). The target directory is auto-detected (`app/flow/pages` for pages, `app/flow/components` for children) or set with `--dir`; since Flow uses file-based routing the page is served automatically, and the command also prints the explicit `Router.flow(...)` line. Registered lazily by `FlowProvider` in console mode, so it's available in any app that registers the provider.
-- **HTTP fallback for WebSocket-blocked networks (Tier 1).** A client circuit breaker: after `HTTP_FALLBACK_AFTER` (3) failed socket handshakes the bridge stops waiting on the WebSocket and sends action frames as plain `POST /__flow/http` requests, which run the _exact same_ server pipeline (hydrate → dispatch → render → patch) over a collecting fake connection and return the frames as a JSON array the client applies — so actions, validation, flashes, redirects, events, and offline-queue replay all keep working behind strict proxies/firewalls that drop WS upgrades, with no component change. It's a graceful degrade, not a configured mode: WS reconnection keeps running and the client upgrades back automatically the moment the socket succeeds (`onopen` resets the failure count and exits HTTP mode). `this.cancel()` POSTs an out-of-band `$cancel` in HTTP mode too. Trade-offs while degraded: no server-pushed frames (so `@task` arrives as one batched update, not token-by-token) and no broadcast-driven `@presence`/`@shared`/`@on("echo:…")` (those ride the separate broadcasting socket); everything driven by the user's own actions still works. Nothing is sent over HTTP until the socket has actually failed.
-- **Reactive lists (`<For>`) + optimistic collections.** `<For each={this.items} keyBy="id">{(item) => …}</For>` compiles to an Alpine `<template x-for>`, so any client change to the array re-renders the list instantly (server patches still keep it authoritative) — the missing piece that made optimistic list ops impossible while `.map()` renders to static HTML. The item template supports element structure, static attrs, `class`/`className` (→ `:class`), reactive attrs, `on*` arrow handlers (→ Alpine `@event`, `this.`→`$flow.`), and `{item.field}` text (→ `x-text`); anything else is a clear compile error pointing at a raw `x-for` escape hatch. On top of it, `this.appendOptimistic(prop, item)` / `this.removeOptimistic(prop, match)` mutate the array before the server confirms: the change shows at once, **survives interim (broadcast/event) patches** (pending ops are re-applied over each server merge), and is **reconciled when the owning action's patch resolves** — server list on success, automatic rollback on failure. Pure reconciliation core in `client/optimistic.ts`; new `For`/`ForProps` exports.
-- **Dev error overlay.** Under `serve --dev`, an unexpected throw — in a server action **or** the initial `GET` render (`onMount`/`render`) — pops a full-screen overlay (Vite/Next style) with the error class, message, and stack, naming the action + component and dimming framework/`node_modules` frames so app frames stand out. Dismiss with Esc or a backdrop click; after an action error the patch still reconciles underneath, so you return to a live page (pairs with the time-travel timeline). The detail is attached **only under the dev worker** — production sends none (an action flashes; an initial-render error returns a normal 500). Only unexpected throws overlay: validation errors and **intended HTTP errors** (auth `401`/`403`, `404`, redirects — anything carrying a numeric `status`) pass straight through to their normal handling. New module `client/errorOverlay.ts`; the error frame gained optional dev-only `name`/`stack`/`action` fields; the initial-render error rides an embedded `flow-boot-error` script the bridge reads on load.
-- **Type-safe real-time events (Tier 1).** An app-augmentable `FlowEvents` contract maps event names to payload types; `dispatch`/`dispatchTo`/`dispatchSelf` are now generic over it, so a known event's payload is type-checked at every dispatch site (server actions and client expressions alike) — wrong shape, missing payload, or a payload on a `void` event all fail to compile — while unknown names stay untyped (a `string` fallback keeps `echo:…` and gradual adoption compiling, no breakage). `@on` autocompletes to known names; annotate handlers with `EventPayload<K>`. No codegen. An optional runtime guard (`registerFlowEvent(name, guard)`) throws from `dispatch` on a malformed payload — for the untrusted client-originated path the types can't cover. New module `events.ts`; exports `registerFlowEvent`, `FlowEvents`, `EventName`, `EventPayload`.
-
-- **`@presence` — multiplayer "who's here" (Tier 1).** Binds a property to a broadcast presence channel (static or a `(self) => string` resolver) and keeps it filled with the live member list, refreshed on join/leave via a new `$presence` built-in. The resolved channel is server-derived and carried signed in the snapshot; the prop is server-controlled (locked). Client-only cursor/typing whispers ride the same channel via `this.whisper(event, data)` / `this.onWhisper(event, cb)`. Broadcasting is an optional peer — resolved through a dynamic import, a no-op when absent — so flow takes no new hard dependency.
-- **Time-travel devtools (Tier 1).** Under `serve --dev`, the client records the signed snapshot stream it already receives — one frame per applied patch plus the initial mount — into a capped ring buffer, and can scrub back to any frame: a jump re-applies that frame's snapshot + HTML to the live component (client-only, no server round-trip), restoring state and DOM exactly. It surfaces as a **Timeline tab in the `@zerotal/devtools` panel** (registered via that package's new `window.__zerotalDevtools` extension API) so all the framework's tooling is unified; when devtools isn't present it falls back to a standalone ⏱ panel. Frames list by action + changed fields + time with click-to-jump and a ⏵ Resume-live button; a `window.__flow.timeline` console API (`frames`/`framesFor`/`jump`/`live`) mirrors it. Dev-gated via the `dev` flag on the WS `ready` frame — production ships none of it. The recording core is a DOM-free module (`client/timeline.ts`); the DOM apply step is injected from the bridge, and the patch morph was extracted to a shared `_morphComponent` reused by both a patch and a jump.
-- **Durable / resumable snapshots (Tier 1).** Opt a component in with `static durable = true` (or `{ ttl, scope }`) and its signed snapshot is persisted server-side after every request, keyed by user (or session) + route. On a fresh GET a valid stored snapshot is restored and `onHydrate()` runs instead of `onMount()`, so an in-progress flow resumes exactly across a full reload, tab close/reopen, device switch, or reconnect after the held client snapshot is gone — nothing stored in the browser. HMAC verification + identity keying isolate users and reject tampered/rotated-key entries (graceful fresh mount). `this.clearDurable()` forgets the entry on flow completion. The store is pluggable via `setDurableStore()` (default in-process TTL store; swap a `@zerotal/cache`/Redis-backed `{ get, set, delete }` for redeploy survival). `scope: "user"` keys by the authenticated user (session fallback when anonymous); `scope: "session"` keys per-device.
-- **`@task` — streaming, cancellable actions (Tier 1).** Mark an async method `@task` (implicitly `@expose`) and write a field in a loop — while the action runs the framework flushes throttled **field-level** snapshot diffs (the changed fields only, no HTML, no per-chunk re-render), so a reactive binding of the field (`text={this.answer}`, `x-text`, a reactive `:attr`) streams to the browser live as `this.answer += token` runs. The field stays the source of truth (no `flow:stream` element, no double-write); the final patch re-renders once to reconcile any static template positions. The triggering control keeps its loading state for the whole run (partial patches don't clear it; only the final patch does). `this.signal` (a standard `AbortSignal`) + `this.cancelled` give cooperative cancellation; the client's `this.cancel()` sends an out-of-band `$cancel` frame (bypassing the per-component send queue the running task occupies), which the server handles before dispatch to abort the task's controller. Implemented via a `partial` patch flag and a chained delta base (each streaming patch is delta-encoded against the previous one the client received).
-- **`@shared` — convergent multiplayer state (Tier 1).** Binds a property to server-authoritative shared state on a channel: mutating it in an action writes to a per-channel **room store** and broadcasts to the channel, so every other subscriber re-reads and converges via a new `$shared` built-in. Before each action the prop is refilled from the store (read-latest); after, changed props are written back and broadcast (`toOthers`). The resolved channel is signed in the snapshot (`SnapshotMemo.shared`) and the prop is server-controlled (locked). The store is pluggable via `setSharedStore()` (default in-process; swap a Redis-backed `{ get, set, has }` for multi-instance). Same optional-peer broadcasting as `@presence` — without it, state still converges within a single window's round-trips. v1 semantics: last-write-wins.
+- **`make:flow` scaffolding command.** The flagship server-driven layer previously had no generator — every `Component` was hand-written (the audit's #1 DX gap). `bun zt make:flow Name` emits a ready-to-run class with the JSX pragma, imports, and an `@expose`/`render` skeleton: `--child` scaffolds a child component (with `setup(props)`), `--crud` a resourceful page (list + create/edit/delete + `@validate` + a form), and `--layout Foo` wraps a page in a layout (with the correct relative import depth for nested names like `Users/Index`). The target directory is auto-detected (`app/flow/pages` for pages, `app/flow/components` for children) or set with `--dir`; since Flow uses file-based routing the page is served automatically, and the command also prints the explicit `Router.flow(...)` line. Registered lazily by `FlowProvider` in console mode, so it's available in any app that registers the provider.
+- **HTTP fallback for WebSocket-blocked networks (Tier 1).** A client circuit breaker: after `HTTP_FALLBACK_AFTER` (3) failed socket handshakes the bridge stops waiting on the WebSocket and sends action frames as plain `POST /__flow/http` requests, which run the _exact same_ server pipeline (hydrate → dispatch → render → patch) over a collecting fake connection and return the frames as a JSON array the client applies — so actions, validation, flashes, redirects, events, and offline-queue replay all keep working behind strict proxies/firewalls that drop WS upgrades, with no component change. It's a graceful degrade, not a configured mode: WS reconnection keeps running and the client upgrades back automatically the moment the socket succeeds (`onopen` resets the failure count and exits HTTP mode). `this.cancel()` POSTs an out-of-band `$cancel` in HTTP mode too. Trade-offs while degraded: no server-pushed frames (so `@task` arrives as one batched update, not token-by-token) and no broadcast-driven `@presence`/`@shared`/`@on("echo:…")` (those ride the separate broadcasting socket); everything driven by the user's own actions still works. Nothing is sent over HTTP until the socket has actually failed.
+- **Reactive lists (`<For>`) + optimistic collections.** `<For each={this.items} keyBy="id">{(item) => …}</For>` compiles to an Alpine `<template x-for>`, so any client change to the array re-renders the list instantly (server patches still keep it authoritative) — the missing piece that made optimistic list ops impossible while `.map()` renders to static HTML. The item template supports element structure, static attrs, `class`/`className` (→ `:class`), reactive attrs, `on*` arrow handlers (→ Alpine `@event`, `this.`→`$flow.`), and `{item.field}` text (→ `x-text`); anything else is a clear compile error pointing at a raw `x-for` escape hatch. On top of it, `this.appendOptimistic(prop, item)` / `this.removeOptimistic(prop, match)` mutate the array before the server confirms: the change shows at once, **survives interim (broadcast/event) patches** (pending ops are re-applied over each server merge), and is **reconciled when the owning action's patch resolves** — server list on success, automatic rollback on failure. Pure reconciliation core in `client/optimistic.ts`; new `For`/`ForProps` exports.
+- **Dev error overlay.** Under `serve --dev`, an unexpected throw — in a server action **or** the initial `GET` render (`onMount`/`render`) — pops a full-screen overlay (Vite/Next style) with the error class, message, and stack, naming the action + component and dimming framework/`node_modules` frames so app frames stand out. Dismiss with Esc or a backdrop click; after an action error the patch still reconciles underneath, so you return to a live page (pairs with the time-travel timeline). The detail is attached **only under the dev worker** — production sends none (an action flashes; an initial-render error returns a normal 500). Only unexpected throws overlay: validation errors and **intended HTTP errors** (auth `401`/`403`, `404`, redirects — anything carrying a numeric `status`) pass straight through to their normal handling. New module `client/errorOverlay.ts`; the error frame gained optional dev-only `name`/`stack`/`action` fields; the initial-render error rides an embedded `flow-boot-error` script the bridge reads on load.
+- **Type-safe real-time events (Tier 1).** An app-augmentable `FlowEvents` contract maps event names to payload types; `dispatch`/`dispatchTo`/`dispatchSelf` are now generic over it, so a known event's payload is type-checked at every dispatch site (server actions and client expressions alike) — wrong shape, missing payload, or a payload on a `void` event all fail to compile — while unknown names stay untyped (a `string` fallback keeps `echo:…` and gradual adoption compiling, no breakage). `@on` autocompletes to known names; annotate handlers with `EventPayload<K>`. No codegen. An optional runtime guard (`registerFlowEvent(name, guard)`) throws from `dispatch` on a malformed payload — for the untrusted client-originated path the types can't cover. New module `events.ts`; exports `registerFlowEvent`, `FlowEvents`, `EventName`, `EventPayload`.
+
+- **`@presence` — multiplayer "who's here" (Tier 1).** Binds a property to a broadcast presence channel (static or a `(self) => string` resolver) and keeps it filled with the live member list, refreshed on join/leave via a new `$presence` built-in. The resolved channel is server-derived and carried signed in the snapshot; the prop is server-controlled (locked). Client-only cursor/typing whispers ride the same channel via `this.whisper(event, data)` / `this.onWhisper(event, cb)`. Broadcasting is an optional peer — resolved through a dynamic import, a no-op when absent — so flow takes no new hard dependency.
+- **Time-travel devtools (Tier 1).** Under `serve --dev`, the client records the signed snapshot stream it already receives — one frame per applied patch plus the initial mount — into a capped ring buffer, and can scrub back to any frame: a jump re-applies that frame's snapshot + HTML to the live component (client-only, no server round-trip), restoring state and DOM exactly. It surfaces as a **Timeline tab in the `@zerotal/devtools` panel** (registered via that package's new `window.__zerotalDevtools` extension API) so all the framework's tooling is unified; when devtools isn't present it falls back to a standalone ⏱ panel. Frames list by action + changed fields + time with click-to-jump and a ⏵ Resume-live button; a `window.__flow.timeline` console API (`frames`/`framesFor`/`jump`/`live`) mirrors it. Dev-gated via the `dev` flag on the WS `ready` frame — production ships none of it. The recording core is a DOM-free module (`client/timeline.ts`); the DOM apply step is injected from the bridge, and the patch morph was extracted to a shared `_morphComponent` reused by both a patch and a jump.
+- **Durable / resumable snapshots (Tier 1).** Opt a component in with `static durable = true` (or `{ ttl, scope }`) and its signed snapshot is persisted server-side after every request, keyed by user (or session) + route. On a fresh GET a valid stored snapshot is restored and `onHydrate()` runs instead of `onMount()`, so an in-progress flow resumes exactly across a full reload, tab close/reopen, device switch, or reconnect after the held client snapshot is gone — nothing stored in the browser. HMAC verification + identity keying isolate users and reject tampered/rotated-key entries (graceful fresh mount). `this.clearDurable()` forgets the entry on flow completion. The store is pluggable via `setDurableStore()` (default in-process TTL store; swap a `@zerotal/cache`/Redis-backed `{ get, set, delete }` for redeploy survival). `scope: "user"` keys by the authenticated user (session fallback when anonymous); `scope: "session"` keys per-device.
+- **`@task` — streaming, cancellable actions (Tier 1).** Mark an async method `@task` (implicitly `@expose`) and write a field in a loop — while the action runs the framework flushes throttled **field-level** snapshot diffs (the changed fields only, no HTML, no per-chunk re-render), so a reactive binding of the field (`text={this.answer}`, `x-text`, a reactive `:attr`) streams to the browser live as `this.answer += token` runs. The field stays the source of truth (no `flow:stream` element, no double-write); the final patch re-renders once to reconcile any static template positions. The triggering control keeps its loading state for the whole run (partial patches don't clear it; only the final patch does). `this.signal` (a standard `AbortSignal`) + `this.cancelled` give cooperative cancellation; the client's `this.cancel()` sends an out-of-band `$cancel` frame (bypassing the per-component send queue the running task occupies), which the server handles before dispatch to abort the task's controller. Implemented via a `partial` patch flag and a chained delta base (each streaming patch is delta-encoded against the previous one the client received).
+- **`@shared` — convergent multiplayer state (Tier 1).** Binds a property to server-authoritative shared state on a channel: mutating it in an action writes to a per-channel **room store** and broadcasts to the channel, so every other subscriber re-reads and converges via a new `$shared` built-in. Before each action the prop is refilled from the store (read-latest); after, changed props are written back and broadcast (`toOthers`). The resolved channel is signed in the snapshot (`SnapshotMemo.shared`) and the prop is server-controlled (locked). The store is pluggable via `setSharedStore()` (default in-process; swap a Redis-backed `{ get, set, has }` for multi-instance). Same optional-peer broadcasting as `@presence` — without it, state still converges within a single window's round-trips. v1 semantics: last-write-wins.
 - **Delta transport.** WebSocket patches carry only the changed snapshot fields (rebuilt client-side against the copy it holds, still HMAC-verified) via `encodeSnapshotDelta`/`applySnapshotDelta`, and omit `html` when the re-render is byte-identical to the last patch on that connection. `ZT_FLOW_TRANSPORT_LOG=1` logs delta-vs-full sizes.
-- **JSX-native layouts.** Override `Component.layout(page)` to wrap the rendered root in any component — named regions are plain props. `static layout` still works; the method wins when both are present. Nav-persistence uses a `data-flow-layout` marker (declared on the shell, else derived from the wrapper source).
-- **Named slots on child components.** `slots={{ … }}` + `this.slot(name)` / `this.hasSlot(name)`; slot HTML is carried, signed, in the child snapshot (`SnapshotMemo.slots`).
+- **JSX-native layouts.** Override `Component.layout(page)` to wrap the rendered root in any component — named regions are plain props. `static layout` still works; the method wins when both are present. Nav-persistence uses a `data-flow-layout` marker (declared on the shell, else derived from the wrapper source).
+- **Named slots on child components.** `slots={{ … }}` + `this.slot(name)` / `this.hasSlot(name)`; slot HTML is carried, signed, in the child snapshot (`SnapshotMemo.slots`).
 - **Compiler prop parity.** `transition`, the `flow:offline` family (`showOnOffline`/`hideOnOffline`/`offlineClass`/`offlineAttr`), `sortItem`, and `loadingTarget`/`dirtyTarget` (`flow:target`) now compile to their directives; the AOT `directives.ts` map and the runtime `PULSE_PROP_MAP` were reconciled.
-- **Stateful fast refresh in dev.** Editing a component under `serve --dev` now re-renders each mounted component from its held, still-valid snapshot with the newly-compiled code — **preserving state** — instead of a full reload, and refetches the stylesheet so new classes apply. Implemented as a `$rerender` built-in (a no-op re-render that skips `onMount`), gated to the dev worker via a `dev` flag on the WS `ready` frame, triggered by the flow WS reconnect; falls back to a one-shot full reload if the held snapshot is incompatible with the new code.
-- **Tier 2 interaction polish.** `<Skeleton>` pulsing placeholder (+ `<Loading skeleton>` and lazy `placeholder()` use); **hover-prefetch** for `navigate hover` links (fetch-on-hover cache so the click swaps instantly — the prop existed but was unimplemented); and **optimistic-UI failed state** via `showOnError`/`hideOnError` (driven by an `actionError` flag the server sets when an action or a rejected `onUpdating` write throws). Rollback itself was already a property of snapshot reconciliation. `lazy`/`defer` are now typed on component JSX props.
+- **Stateful fast refresh in dev.** Editing a component under `serve --dev` now re-renders each mounted component from its held, still-valid snapshot with the newly-compiled code — **preserving state** — instead of a full reload, and refetches the stylesheet so new classes apply. Implemented as a `$rerender` built-in (a no-op re-render that skips `onMount`), gated to the dev worker via a `dev` flag on the WS `ready` frame, triggered by the flow WS reconnect; falls back to a one-shot full reload if the held snapshot is incompatible with the new code.
+- **Tier 2 interaction polish.** `<Skeleton>` pulsing placeholder (+ `<Loading skeleton>` and lazy `placeholder()` use); **hover-prefetch** for `navigate hover` links (fetch-on-hover cache so the click swaps instantly — the prop existed but was unimplemented); and **optimistic-UI failed state** via `showOnError`/`hideOnError` (driven by an `actionError` flag the server sets when an action or a rejected `onUpdating` write throws). Rollback itself was already a property of snapshot reconciliation. `lazy`/`defer` are now typed on component JSX props.
 
 ### Changed
 
-- **Loading indicators wait out a short delay by default (no flash on fast actions).** `showOnLoading`, `hideOnLoading`, `loadingClass`, and `<Loading>` now reveal only after ~200ms in flight, so an action that finishes inside that window shows nothing — no spinner flash. `loadingAttr` (e.g. `loadingAttr="disabled"`) stays **immediate**, so a submit button still guards against a double-click even on a sub-100ms action. Previously only the opt-in `<Loading delay>` / `flow:loading.delay` was delayed; `delay` is now the default and kept for back-compat. Cleared instantly on resolve, so a just-over-threshold action barely blips.
-- **`live` text inputs debounce their server sync (~150ms) by default.** A `live` text/textarea input no longer fires a WebSocket `$set` on every keystroke — it debounces ~150ms (matching Livewire's `wire:model.live`), so real-time validation and reactive server state update when you pause, not per character. Discrete controls (checkbox, radio, `<select>`, range) still sync immediately. The DOM and client-reactive bindings update on every keystroke regardless; only the server round-trip waits, and no value is ever lost (local state is current and any action flushes the full snapshot).
-- **WebSocket actions serialize per component.** At most one action per component is in flight; the next waits for the previous patch to apply. Required by delta transport (deltas are order-dependent — a pipelined patch computed against a stale base would corrupt the client snapshot and trip the invalid-request rate limit). Offline replay runs through the same serial queue; a 15s ack timeout prevents wedging.
+- **Loading indicators wait out a short delay by default (no flash on fast actions).** `showOnLoading`, `hideOnLoading`, `loadingClass`, and `<Loading>` now reveal only after ~200ms in flight, so an action that finishes inside that window shows nothing — no spinner flash. `loadingAttr` (e.g. `loadingAttr="disabled"`) stays **immediate**, so a submit button still guards against a double-click even on a sub-100ms action. Previously only the opt-in `<Loading delay>` / `flow:loading.delay` was delayed; `delay` is now the default and kept for back-compat. Cleared instantly on resolve, so a just-over-threshold action barely blips.
+- **`live` text inputs debounce their server sync (~150ms) by default.** A `live` text/textarea input no longer fires a WebSocket `$set` on every keystroke — it debounces ~150ms (matching Livewire's `wire:model.live`), so real-time validation and reactive server state update when you pause, not per character. Discrete controls (checkbox, radio, `<select>`, range) still sync immediately. The DOM and client-reactive bindings update on every keystroke regardless; only the server round-trip waits, and no value is ever lost (local state is current and any action flushes the full snapshot).
+- **WebSocket actions serialize per component.** At most one action per component is in flight; the next waits for the previous patch to apply. Required by delta transport (deltas are order-dependent — a pipelined patch computed against a stale base would corrupt the client snapshot and trip the invalid-request rate limit). Offline replay runs through the same serial queue; a 15s ack timeout prevents wedging.
 
 ### Fixed
 
-- **`@expose`/`@locked` on a getter now fails loudly.** A getter (a `@computed`, or any accessor) has no writable snapshot storage, so exposing or locking one would serialize a value the framework then tries to write back on the next update — clobbering the getter. TypeScript already rejects it (the decorators' Stage 3 context types exclude getters), but Bun transpiles without typechecking, so the decorator would still run and silently misregister. The `@expose`/`@locked`/`@url`/`@session`/`@transient`/`@reactive`/`@modelable` decorators now throw at class definition on a getter/setter/accessor, with a message pointing to `@computed` (for a derived value) or an `@expose` field (for client-writable state).
-- **`@computed` getters compile in a text child.** The AOT compiler only knew about `@expose`/`@locked`, so `{this.uptime}` for a `@computed` getter failed validation and the whole page silently fell back to the runtime renderer. The compiler now recognises `@computed` (it sits on a getter, which the member scan previously skipped) and allows it wherever a text child emits a **static** value (`{this.x}`, `{String(this.x)}`) — matching how `@expose`/`@locked` text children already render (static, updates on the next server patch). Reactive sites still reject it correctly (a `@computed` isn't in the snapshot, so `text={this.x}` / reactive `:class` can't bind to it) — now with a message that says so and points to `{this.x}` or `@expose`. Also corrected the docs claim that `@computed` is "reactive on the client": it renders a static server-evaluated value, not a client-reactive binding.
-- **Removed two dead binding-resolution defences.** The runtime resolver's "brute-force own-property scan" and the twin `hasOwnProperty(hint)` fallback existed to recover `@locked` props "whose decorator registration failed to land" — but `getExposedProps`/`getLockedProps` now drain the prototype chain first, so every decorated prop is reliably registered before the value-scan. Verified across the full suite + the showcase that the brute-force branch never fired; it could only ever match a _non-decorated_ field (a false positive), so removing it also removes that footgun.
-- **Component bindings resolve statically (compile-time bind-name injection).** The AOT string compiler bails on any function component, so component-heavy pages render through the runtime `jsx()` path, where TSC's jsx transform has already discarded the `show`→`sheetOpen` prop→key mapping. That made value-based bind resolution fragile: a bound child clobbered the getter capture, and props sharing a value (two `false`s) couldn't be told apart, so an overlay-with-a-bound-form could render **unbound** (with only a `console.warn`). A new pass (`buildBindInjectedRender`) reprints a bailed page's `render()` with `__flowBinds={{ show: "sheetOpen" }}` added to every component that binds `show`/`bind`/`query` to `this.<key>`; the component reads it via `_injectedBindKey(props, attr)` (before `name=`/value resolution), so the bound prop is resolved from the source **statically and unambiguously**. The reprint is otherwise identical to the source (behaviour unchanged apart from robust binding), runs through the existing cache as a `.tsx` entry, and falls back to the untouched runtime render on any failure. Wired for every overlay (`Modal`/`Drawer`/`Dialog`/`Sheet`), form control (`Switch`/`Checkbox`/`Select`/`RadioGroup`/`Listbox`), and `Combobox` (`bind` + `query`). `__flowBinds` is stripped by `jsx()` and never emitted as an HTML attribute. (Applies to pages the compiler sees — file-based routes automatically; `Router.flow` pages once their `__sourceFile` is set.) Audit of the other seams: `_resolveValueBind` (`value=`/`checked=`) is already value-identity-guarded and only applies to leaf inputs (no children to clobber the capture); `error=`/`<ErrorMessage>` carries a self-describing sentinel — neither is ambiguous.
-- **`text={this.x}` binds to its own property, not a sibling binding's.** On the runtime (non-AOT) render path, `_resolveBindName` trusted a single-slot getter capture — but every prop of a JSX element is evaluated before `jsx()` runs, so a later binding like `class={"row " + this.accent}` overwrote the capture that `text={this.count}` had set. The element then emitted `flow:text="accent"` and rendered the accent string in place of the count. The resolver now value-guards the capture (only trusts it when the captured property's current value is the one being resolved) and falls back to value-identity + the hint, so `text` (and `show`) always resolve to their own property regardless of other bindings on the same element. `value=`/`checked=` were already value-checked and unaffected.
-- **`<Head>` content survives SPA navigation.** On a same-layout `navigate`, `_processHead` only ever re-read the live `document` — but the initial hoist removes each `<template data-flow-head>` from the DOM, and a persistent-layout swap carries only the page root (not the shell's `<Head>`). So the managed head was cleared and never restored: a stylesheet or fonts declared in a JSX-native layout's `<Head>` vanished on the first navigation (the page rendered unstyled), and page-level `<title>`/`<meta>` were dropped too. `navigate` now re-applies head from the **incoming** parsed document (which still carries every head template — shell stylesheet and page meta alike), deduping by identity so an unchanged stylesheet is left in place rather than removed-and-re-added (no unstyled flash between visits).
+- **`@expose`/`@locked` on a getter now fails loudly.** A getter (a `@computed`, or any accessor) has no writable snapshot storage, so exposing or locking one would serialize a value the framework then tries to write back on the next update — clobbering the getter. TypeScript already rejects it (the decorators' Stage 3 context types exclude getters), but Bun transpiles without typechecking, so the decorator would still run and silently misregister. The `@expose`/`@locked`/`@url`/`@session`/`@transient`/`@reactive`/`@modelable` decorators now throw at class definition on a getter/setter/accessor, with a message pointing to `@computed` (for a derived value) or an `@expose` field (for client-writable state).
+- **`@computed` getters compile in a text child.** The AOT compiler only knew about `@expose`/`@locked`, so `{this.uptime}` for a `@computed` getter failed validation and the whole page silently fell back to the runtime renderer. The compiler now recognises `@computed` (it sits on a getter, which the member scan previously skipped) and allows it wherever a text child emits a **static** value (`{this.x}`, `{String(this.x)}`) — matching how `@expose`/`@locked` text children already render (static, updates on the next server patch). Reactive sites still reject it correctly (a `@computed` isn't in the snapshot, so `text={this.x}` / reactive `:class` can't bind to it) — now with a message that says so and points to `{this.x}` or `@expose`. Also corrected the docs claim that `@computed` is "reactive on the client": it renders a static server-evaluated value, not a client-reactive binding.
+- **Removed two dead binding-resolution defences.** The runtime resolver's "brute-force own-property scan" and the twin `hasOwnProperty(hint)` fallback existed to recover `@locked` props "whose decorator registration failed to land" — but `getExposedProps`/`getLockedProps` now drain the prototype chain first, so every decorated prop is reliably registered before the value-scan. Verified across the full suite + the showcase that the brute-force branch never fired; it could only ever match a _non-decorated_ field (a false positive), so removing it also removes that footgun.
+- **Component bindings resolve statically (compile-time bind-name injection).** The AOT string compiler bails on any function component, so component-heavy pages render through the runtime `jsx()` path, where TSC's jsx transform has already discarded the `show`→`sheetOpen` prop→key mapping. That made value-based bind resolution fragile: a bound child clobbered the getter capture, and props sharing a value (two `false`s) couldn't be told apart, so an overlay-with-a-bound-form could render **unbound** (with only a `console.warn`). A new pass (`buildBindInjectedRender`) reprints a bailed page's `render()` with `__flowBinds={{ show: "sheetOpen" }}` added to every component that binds `show`/`bind`/`query` to `this.<key>`; the component reads it via `_injectedBindKey(props, attr)` (before `name=`/value resolution), so the bound prop is resolved from the source **statically and unambiguously**. The reprint is otherwise identical to the source (behaviour unchanged apart from robust binding), runs through the existing cache as a `.tsx` entry, and falls back to the untouched runtime render on any failure. Wired for every overlay (`Modal`/`Drawer`/`Dialog`/`Sheet`), form control (`Switch`/`Checkbox`/`Select`/`RadioGroup`/`Listbox`), and `Combobox` (`bind` + `query`). `__flowBinds` is stripped by `jsx()` and never emitted as an HTML attribute. (Applies to pages the compiler sees — file-based routes automatically; `Router.flow` pages once their `__sourceFile` is set.) Audit of the other seams: `_resolveValueBind` (`value=`/`checked=`) is already value-identity-guarded and only applies to leaf inputs (no children to clobber the capture); `error=`/`<ErrorMessage>` carries a self-describing sentinel — neither is ambiguous.
+- **`text={this.x}` binds to its own property, not a sibling binding's.** On the runtime (non-AOT) render path, `_resolveBindName` trusted a single-slot getter capture — but every prop of a JSX element is evaluated before `jsx()` runs, so a later binding like `class={"row " + this.accent}` overwrote the capture that `text={this.count}` had set. The element then emitted `flow:text="accent"` and rendered the accent string in place of the count. The resolver now value-guards the capture (only trusts it when the captured property's current value is the one being resolved) and falls back to value-identity + the hint, so `text` (and `show`) always resolve to their own property regardless of other bindings on the same element. `value=`/`checked=` were already value-checked and unaffected.
+- **`<Head>` content survives SPA navigation.** On a same-layout `navigate`, `_processHead` only ever re-read the live `document` — but the initial hoist removes each `<template data-flow-head>` from the DOM, and a persistent-layout swap carries only the page root (not the shell's `<Head>`). So the managed head was cleared and never restored: a stylesheet or fonts declared in a JSX-native layout's `<Head>` vanished on the first navigation (the page rendered unstyled), and page-level `<title>`/`<meta>` were dropped too. `navigate` now re-applies head from the **incoming** parsed document (which still carries every head template — shell stylesheet and page meta alike), deduping by identity so an unchanged stylesheet is left in place rather than removed-and-re-added (no unstyled flash between visits).
 - **`lazy`/`defer` on a child component in JSX now actually defer.** `<Widget lazy />` passed `lazy` through as a component _prop_ instead of a `child()` option, so the child mounted eagerly (blocking on its `onMount`) and never showed its placeholder. The JSX runtime now routes `lazy`/`defer` to the child-loading options.
-- **Browser Back to the first page did nothing.** SPA `navigate` only re-rendered on `popstate` when the history entry carried the `flowNavigate` marker, which a fresh page load's initial entry lacked — so pressing Back to the first visited page changed the URL but left the page in place. The initial entry is now stamped at startup.
+- **Browser Back to the first page did nothing.** SPA `navigate` only re-rendered on `popstate` when the history entry carried the `flowNavigate` marker, which a fresh page load's initial entry lacked — so pressing Back to the first visited page changed the URL but left the page in place. The initial entry is now stamped at startup.
 - **`transition` prop.** Was typed but absent from `PULSE_PROP_MAP`, so it emitted an inert `transition` attribute instead of `flow:transition`.
 - **`children`/`slots` on components type-check.** Added to `JSX.IntrinsicAttributes` so passing children or a `slots` prop to a `Component` no longer errors.
 

package/README.md

@@ -2,6 +2,8 @@
 
 > Reactive server-side rendering for Zerotal — server-rendered components, streamed over WebSocket, morphed into the DOM by Alpine.
 
+**Maturity: experimental.** Flow ships on the same version line as the rest of Zerotal, but it is not at the same maturity as the stable packages. Its API may change between minor versions, and it has had far less production exposure than the core, ORM, and HTTP layers. The version number alone doesn't tell you that, which is why it is said here — build on it deliberately.
+
 Flow is Zerotal's server-driven UI layer. Each page is a TypeScript `Component` class whose state lives on the server. You write plain JSX and bind handlers like `onClick={this.save}`; on each interaction the server hydrates the component from a signed snapshot, runs the method, re-renders, and streams only the changed HTML back, which Alpine.js morphs into the page. There is no API layer, no client-side store, and no hand-written client reactivity — the server is the single source of truth.
 
 Flow began life as **Geleza** — isiZulu for _"to flow"_ — and the name turned out to describe the architecture better than anything we could invent. Settling on English package names, we translated it rather than replaced it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/flow",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "license": "MIT",
   "maturity": "experimental",
   "private": false,
@@ -45,14 +45,14 @@
     "@alpinejs/morph": "^3.14.9",
     "@alpinejs/persist": "^3.14.9",
     "@alpinejs/resize": "^3.14.9",
-    "@zerotal/core": "1.0.3",
-    "@zerotal/orm": "1.0.3",
-    "@zerotal/validator": "1.0.3",
+    "@zerotal/core": "1.1.0",
+    "@zerotal/orm": "1.1.0",
+    "@zerotal/validator": "1.1.0",
     "alpinejs": "^3.14.9",
     "typescript": "^5.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.0.3",
+    "@zerotal/broadcasting": "1.1.0",
     "@types/alpinejs": "^3.13.10",
     "@types/alpinejs__anchor": "^3.13.1",
     "@types/alpinejs__collapse": "^3.13.4",
@@ -62,8 +62,9 @@
     "@types/alpinejs__resize": "^3.14.0",
     "bun-types": "^1.3.14"
   },
-  "description": "Flow — server-driven reactive UI for Zerotal with signed snapshots, delta transport, and real-time primitives.",
+  "description": "Flow (experimental) — server-driven reactive UI for Zerotal with signed snapshots, delta transport, and real-time primitives.",
   "keywords": [
+    "experimental",
     "zerotal",
     "bun",
     "typescript",

package/src/Component.ts

@@ -1181,18 +1181,44 @@ export abstract class Component {
   /**
    * Emit the HTML attributes needed for `flow:model` two-way binding.
    *
+   * Pass `optionValue` for one member of a radio group: the radio carries that
+   * fixed value and is `checked` only when the bound property currently equals it.
+   * A radio group is addressed as a unit — every option binds the same property —
+   * so `value={…}`/`checked={…}` on a radio never infers a binding by itself and
+   * this is the way to bind one.
+   *
    * @example
    * <input {...this.bind('name')} />
    * // → <input flow:model="name" value="Alice" />
    *
+   * @example
+   * // A radio group over a `type` property:
+   * {['CUSTOM', 'ROUTE', 'TEAMS'].map((t) => (
+   *   <label>
+   *     <input type="radio" name="type" {...this.bind('type', t)} /> {t}
+   *   </label>
+   * ))}
+   * // → <input type="radio" name="type" flow:model="type" value="ROUTE" checked>
+   *
    * @param key  the `@expose` property to two-way bind.
-   * @returns the `flow:model` + `value` attributes to spread onto an input.
+   * @param optionValue  this radio's own value; omit for text/checkbox/select inputs.
+   * @returns the `flow:model` + `value` (+ `checked`) attributes to spread onto an input.
    * @category State & exposure
    */
-  bind(key: string): Record<string, unknown> {
+  bind(key: string, optionValue?: string): Record<string, unknown> {
+    const current = (this as Record<string, unknown>)[key];
+    if (optionValue !== undefined) {
+      return {
+        "flow:model": key,
+        value: optionValue,
+        // String-compare so a numeric property still matches its string option value —
+        // the DOM only ever gives a radio's value back as a string.
+        checked: String(current ?? "") === optionValue,
+      };
+    }
     return {
       "flow:model": key,
-      value: (this as Record<string, unknown>)[key] ?? "",
+      value: current ?? "",
     };
   }
 

package/src/client/bridge.ts

@@ -1605,6 +1605,14 @@ function _syncModelInputs(comp: FlowComponent): void {
       el.checked = Boolean(serverVal);
       return;
     }
+    // A radio's `value` is its immutable option identifier — the group's state selects
+    // among those, it does not replace them. Assigning `el.value` here (as the generic
+    // path below does) would rewrite every option in the group to the current value and
+    // destroy the choices.
+    if (el instanceof HTMLInputElement && el.type === "radio") {
+      el.checked = el.value === String(serverVal ?? "");
+      return;
+    }
     const str = String(serverVal ?? "");
     if (el.value !== str) el.value = str;
     // A draft-backed field the server just emptied (e.g. after a successful submit) → drop the draft.
@@ -1844,6 +1852,62 @@ function debounce<T extends unknown[]>(fn: (...args: T) => void, ms: number): (.
   };
 }
 
+/**
+ * Find the nearest ancestor carrying `flow:<event>`, with or without modifiers.
+ *
+ * The compiler emits modifiers into the attribute *name* (`onClick={flow(this.save).stop}`
+ * → `flow:click.stop="save"`), but a `[flow\:click]` attribute selector matches that name
+ * exactly — so every handler that carried a modifier was invisible to the bridge and did
+ * nothing at all, silently. Walking the ancestors and reading the attribute list finds
+ * both forms.
+ */
+export function _findHandler(
+  target: Element | null,
+  event: string,
+): { el: Element; value: string; modifiers: Set<string> } | null {
+  const prefix = `flow:${event}`;
+  for (let el = target; el; el = el.parentElement) {
+    for (const attr of Array.from(el.attributes)) {
+      if (attr.name !== prefix && !attr.name.startsWith(`${prefix}.`)) continue;
+      if (!attr.value) continue;
+      const modifiers = new Set(
+        attr.name.length > prefix.length ? attr.name.slice(prefix.length + 1).split(".") : [],
+      );
+      return { el, value: attr.value, modifiers };
+    }
+  }
+  return null;
+}
+
+/**
+ * Whether a click handler should cancel the element's default action.
+ *
+ * `preventDefault()` used to be unconditional, which cancels the *activation behaviour*
+ * of whatever it is placed on — so a radio or checkbox carrying `onClick` never became
+ * checked, and no handler could fix it: the browser restores the control's pre-click
+ * checkedness after listeners run, so assigning `.checked` inside the handler is reverted
+ * a moment later. `onClick` and a form control were effectively mutually exclusive.
+ *
+ * Default only where the default action is the thing in the way — following a link, or
+ * submitting a form. `.prevent` forces it anywhere; `.passive` opts out anywhere.
+ */
+export function _shouldPreventClickDefault(el: Element, modifiers: Set<string>): boolean {
+  if (modifiers.has("passive")) return false;
+  if (modifiers.has("prevent")) return true;
+  // tagName rather than instanceof: an element adopted from another document (an iframe,
+  // a template) fails `instanceof HTMLAnchorElement` against this window's constructors,
+  // and silently taking the wrong branch here is the whole class of bug being fixed.
+  const tag = el.tagName?.toUpperCase();
+  if (tag === "A") return true;
+  const type = (el.getAttribute?.("type") ?? "").toLowerCase();
+  // A <button> with no type attribute is type="submit" per the HTML spec.
+  if (tag === "BUTTON") return type === "" || type === "submit";
+  // Inputs of type submit/image submit a form; every other control (checkbox, radio,
+  // file, …) needs its activation behaviour left alone.
+  if (tag === "INPUT") return type === "submit" || type === "image";
+  return false;
+}
+
 function _parseArgs(el: Element): unknown[] {
   const raw = el.getAttribute("data-args") ?? el.getAttribute("flow:args");
   if (!raw) return [];
@@ -1989,9 +2053,18 @@ function _modelKey(el: Element): string | null {
  * coercion for `type="number"` inputs whose canonical value is already numeric. A checkbox
  * returns its boolean `checked`. `existing` (the current canonical value) guards the implicit
  * number coercion so a string-typed field isn't turned into a number behind the author's back.
+ *
+ * A radio returns its value only when it is the checked member of its group, and
+ * `undefined` otherwise — callers must skip `undefined` rather than write it. Every
+ * radio in a group carries the same `flow:model`, so returning a bare `.value` would
+ * let each unchecked option overwrite the group's state in turn and leave whichever
+ * one happens to be last in DOM order as the winner.
  */
 function _readModelValue(el: ModelEl, existing?: unknown): unknown {
   if (el instanceof HTMLInputElement && el.type === "checkbox") return el.checked;
+  if (el instanceof HTMLInputElement && el.type === "radio") {
+    return el.checked ? el.value : undefined;
+  }
   let v = (el as HTMLInputElement).value;
   if (el.hasAttribute("data-flow-trim")) v = v.trim();
   const wantNumber =
@@ -2010,6 +2083,9 @@ function _flushModelInputs(comp: FlowComponent): void {
       if (!key) return;
       // Coerce (see _readModelValue) so a number field doesn't send "0" as a string, etc.
       const value = _readModelValue(el, _getPath(comp.reactive as Record<string, unknown>, key));
+      // An unchecked radio reports undefined — skip it, or iterating the group would
+      // clear the value its checked sibling just contributed.
+      if (value === undefined) return;
       // reactive first (see set-trap note): ephemeral is the proxy's raw target.
       _setPath(comp.reactive, key, value);
       _setPath(comp.ephemeral, key, value);
@@ -2072,13 +2148,14 @@ function _setupEventDelegation(): void {
   });
 
   document.addEventListener("click", async (e) => {
-    const el = (e.target as Element).closest("[flow\\:click]") as Element | null;
-    if (!el) return;
-    const method = el.getAttribute("flow:click");
-    if (!method) return;
+    const found = _findHandler(e.target as Element, "click");
+    if (!found) return;
+    const { el, value: method, modifiers } = found;
     const comp = findComponentByEl(el);
     if (!comp) return;
-    e.preventDefault();
+
+    if (modifiers.has("stop")) e.stopPropagation();
+    if (_shouldPreventClickDefault(el, modifiers)) e.preventDefault();
 
     // Async: a confirm prompt shows the styled dialog and resolves on Confirm/Cancel.
     if (!(await _requireConfirm(el))) return;
@@ -2130,6 +2207,9 @@ function _setupEventDelegation(): void {
     // Apply the trim/number modifiers on the way in, so client-reactive bindings see the coerced
     // value immediately (not just the server on the next action).
     const value = _readModelValue(el, _getPath(comp.reactive as Record<string, unknown>, key));
+    // Only the newly-checked radio in a group reports a value; the input event that
+    // deselects its sibling carries nothing to write.
+    if (value === undefined) return;
 
     // reactive first (see set-trap note): ephemeral is the proxy's raw target, so writing it
     // first would suppress the reactive trigger and leave x-text/:class bindings stale.
@@ -2168,7 +2248,16 @@ function _setupEventDelegation(): void {
       if (!comp) return;
 
       const key = el.getAttribute("flow:model.blur");
-      if (key) _callAction(comp, "$set", [key, (el as HTMLInputElement).value]);
+      if (key) {
+        // Go through _readModelValue so the blur path applies the same coercions and
+        // the same radio/checkbox rules as input and flush do — a raw `.value` here
+        // sends "on" for a checkbox and an unchecked radio's value for a radio.
+        const blurValue = _readModelValue(
+          el as ModelEl,
+          _getPath(comp.reactive as Record<string, unknown>, key),
+        );
+        if (blurValue !== undefined) _callAction(comp, "$set", [key, blurValue]);
+      }
 
       // `onBlur={this.method}` — the JSX runtime emits `flow:blur` for it like any
       // other `on*` prop, so without this the attribute renders and nothing ever

package/src/compiler/index.ts

@@ -169,4 +169,35 @@ export async function compileRegisteredPages(appRoot: string, cspSafe = false):
       { compiled, cached, injected, runtime: skipped, ms },
     );
   }
+
+  _warnIfMostlyRuntime(compiled + cached + injected + skipped, skipped);
 }
+
+/**
+ * Falling back to the runtime renderer for a page or two is normal and correct.
+ * A whole app doing it is not: the runtime path resolves `value=`/`checked=`
+ * bindings by observing property reads at render time, which is necessarily
+ * weaker than the compiler reading the same intent out of the AST. An app that
+ * never compiles is relying on that weaker path everywhere without being told.
+ *
+ * So the per-page reasons stay behind ZT_FLOW_COMPILE_LOG (they are noise at a
+ * handful of pages), but the *rate* is reported unconditionally once it passes
+ * half. The message names the flag, because knowing which construct blocks each
+ * page is the only actionable next step.
+ */
+function _warnIfMostlyRuntime(total: number, runtime: number): void {
+  if (total < MIN_PAGES_FOR_FALLBACK_WARNING) return;
+  if (runtime * 2 <= total) return;
+  if (_explainFallbacks()) return; // already printing a reason per page
+
+  const pct = Math.round((runtime / total) * 100);
+  frameworkLog("flow").warn(
+    `${runtime} of ${total} Flow pages (${pct}%) render through the runtime fallback ` +
+      `instead of compiled output.\n` +
+      `  Set ZT_FLOW_COMPILE_LOG=1 to print what blocks each page.`,
+    { total, runtime, pct },
+  );
+}
+
+/** Below this, a high percentage is not yet evidence of anything. */
+const MIN_PAGES_FOR_FALLBACK_WARNING = 4;

package/src/compiler/transform.ts

@@ -448,14 +448,39 @@ interface MemberInfo {
   locked: Set<string>; // @locked only — readable from client, not writable
   computed: Set<string>; // @computed getters — derived, NOT in the snapshot
   readable: Set<string>; // exposed ∪ locked — any prop in the snapshot (client-reactive)
+  /** Every method declared on this class, decorated or not — see `_assertActionExposed`. */
+  declaredMethods: Set<string>;
+  /**
+   * Methods the client may call. `@expose` is the usual one, but `@task` and `@on` both
+   * register into the same allowlist (`_exposedMethods`) — a `@task` streams field writes
+   * and is dispatched exactly like any other action. Checking only for `@expose` rejected
+   * perfectly good pages.
+   */
+  callableMethods: Set<string>;
 }
 
+/** Decorators that put a method in the client-callable allowlist. */
+const ACTION_DECORATORS = new Set(["expose", "task", "on"]);
+
 /** Collect @expose, @locked, and @computed decorated members from the Component class AST. */
 function _getMemberInfo(cls: ts.ClassDeclaration): MemberInfo {
   const exposed = new Set<string>();
   const locked = new Set<string>();
   const computed = new Set<string>();
+  const declaredMethods = new Set<string>();
+  const callableMethods = new Set<string>();
   for (const member of cls.members) {
+    if (ts.isMethodDeclaration(member) && ts.isIdentifier(member.name)) {
+      declaredMethods.add(member.name.text);
+      for (const m of member.modifiers ?? []) {
+        if (!ts.isDecorator(m)) continue;
+        // `@on("evt")` is a call; `@expose` is a bare identifier.
+        const e = ts.isCallExpression(m.expression) ? m.expression.expression : m.expression;
+        if (ts.isIdentifier(e) && ACTION_DECORATORS.has(e.text)) {
+          callableMethods.add(member.name.text);
+        }
+      }
+    }
     // @computed sits on a getter (GetAccessorDeclaration); @expose/@locked on fields/methods.
     if (
       !ts.isPropertyDeclaration(member) &&
@@ -475,7 +500,55 @@ function _getMemberInfo(cls: ts.ClassDeclaration): MemberInfo {
     if (has("locked")) locked.add(name);
     if (has("computed")) computed.add(name);
   }
-  return { exposed, locked, computed, readable: new Set([...exposed, ...locked]) };
+  return {
+    exposed,
+    locked,
+    computed,
+    readable: new Set([...exposed, ...locked]),
+    declaredMethods,
+    callableMethods,
+  };
+}
+
+/**
+ * Reject `onClick={this.method}` when `method` is declared on the page but not `@expose`d.
+ *
+ * `getAllowedMethods()` is `getExposedMethods()`, so an undecorated method is simply absent
+ * from the allowlist. Everything else about the page passes — `tsc` is clean, the compiler
+ * emits `flow:click="submit"`, the button renders enabled — and the click sends a frame the
+ * server refuses, reporting it *only* over the WebSocket to `console.error`:
+ *
+ *     [Flow] Server error on …: Method "submit" is not allowed
+ *
+ * Nothing reaches the server log, nothing throws, the page does not change. To a developer,
+ * and to every test that is not a real browser with the console open, the button simply does
+ * nothing — indistinguishable from the binding bugs, so the instinct is to go hunting for one.
+ *
+ * The member table needed to catch this is already built, so catch it here.
+ *
+ * Only fires for a method *declared on this class*: an inherited handler (a base-class action,
+ * a mixin) is invisible to this AST and must not be second-guessed.
+ */
+function _assertActionExposed(
+  method: string,
+  members: MemberInfo,
+  filename: string,
+  node: ts.Node,
+): void {
+  if (!members.declaredMethods.has(method)) return; // inherited or a magic — not ours to judge
+  if (members.callableMethods.has(method)) return;
+  if (CLIENT_CALLBACK_MAGICS.has(method) || CLIENT_MAGICS.has(method)) return;
+
+  const sf = node.getSourceFile();
+  const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+  throw new FlowValidationError(
+    `[Flow] \`${method}\` is used as a server action but is not @expose'd.\n` +
+      `  ${_at(filename, line + 1, character + 1)}\n` +
+      `      → Add @expose to ${method}() (or @task / @on, which also make it callable). ` +
+      `Without it the method is not in the action ` +
+      `allowlist, so the click sends a frame the server refuses — and the refusal is ` +
+      `reported only to the browser console, which makes the button look inert.`,
+  );
 }
 
 // ── this.xxx reference extraction (read vs write) ─────────────────────────────
@@ -685,6 +758,18 @@ function _validateFlowCallbacks(sf: ts.SourceFile, members: MemberInfo, filename
         // its this.xxx refs must be @expose (writes) / @expose|@locked (reads).
         _validateArrowRefs(expr, members, filename);
       }
+
+      // onClick={this.method} / onSubmit={flow(this.method)} — the method must be
+      // @expose'd or it is not in the action allowlist. Checked here, in the pass that
+      // runs unconditionally and whose errors are fatal, rather than during transform:
+      // a transform error is caught and downgraded to a runtime fallback, which would
+      // leave the page rendering and the button still silently dead.
+      if (attrName.startsWith("on") || attrName === "submit") {
+        const ref = _isThisProp(expr)
+          ? (expr as ts.PropertyAccessExpression)
+          : _extractFlowProp(expr);
+        if (ref) _assertActionExposed(ref.name.text, members, filename, ref);
+      }
     }
     ts.forEachChild(node, scan);
   }
@@ -1671,7 +1756,8 @@ function _compileRenderMethod(
         const event = eventName;
         // onClick={this.method} — server action (named method reference).
         if (_isThisProp(expr)) {
-          emitStatic(` flow:${event}="${(expr as ts.PropertyAccessExpression).name.text}"`);
+          const method = (expr as ts.PropertyAccessExpression).name.text;
+          emitStatic(` flow:${event}="${method}"`);
           continue;
         }
         // onClick={(e) => this.x = 0} — bare arrow → client expression, emitted verbatim
@@ -1680,6 +1766,20 @@ function _compileRenderMethod(
         // key off it). The <For> path below is the one exception — a loop handler must be an
         // Alpine `@event`, because the loop variable only exists in Alpine's x-for scope.
         if (ts.isArrowFunction(expr)) {
+          // `() => this.method(row.id)` — a server action that wants an argument. The
+          // arrow itself cannot ship: it would be emitted verbatim and `row` does not
+          // exist in the browser. But this render function DOES have `row` in scope at
+          // request time, so emit the action by name and serialise the arguments beside
+          // it as data-args, which the bridge already reads and forwards. Matches what
+          // the runtime renderer achieves by invoking the arrow with a recorder.
+          const argCall = _asServerActionCall(expr, members);
+          if (argCall) {
+            emitStatic(` flow:${event}="${argCall.method}"`);
+            emitStatic(` data-args="`);
+            emitDynamic(`__escAttr(JSON.stringify([${argCall.argsSrc}]))`);
+            emitStatic(`"`);
+            continue;
+          }
           if (_cspSafe) {
             // CSP-safe: emit the bare expression body (no arrow wrapper). An event
             // param or a block body has no CSP-safe inline form → compile error.
@@ -1695,11 +1795,13 @@ function _compileRenderMethod(
                   `  Use a single expression or an @expose action.\n  File: ${filename}`,
               );
             }
+            _assertClientExprScope(expr, members, filename);
             const body = _rewriteClientExpr(expr.body.getText());
             _assertCspExpr(body, filename);
             emitStatic(` flow:${event}="${_escAttr(body)}"`);
             continue;
           }
+          _assertClientExprScope(expr, members, filename);
           const src = _rewriteClientExpr(expr.getText());
           emitStatic(` flow:${event}="${_escAttr(src)}"`);
           continue;
@@ -2047,9 +2149,246 @@ function _clientMagicSrc(expr: ts.Expression, members: MemberInfo, filename: str
       );
     }
   }
+  // Same verbatim-emission hazard as an arrow handler: this expression re-evaluates in
+  // the browser, so a captured server-side name would silently evaluate to undefined.
+  _assertClientExprScope(expr, members, filename);
   return _rewriteClientExpr(expr.getText());
 }
 
+/**
+ * Recognise `() => this.method(a, b)` — a no-parameter arrow whose whole body is one
+ * call to a component action with arguments — and return the pieces needed to emit it
+ * as `flow:<event>="method"` + `data-args`.
+ *
+ * Returns null (leaving the caller on the verbatim client-expression path) when:
+ *  - the arrow takes parameters (it wants the DOM event; that's genuinely client-side);
+ *  - the body isn't a single call, or isn't a call to `this.something`;
+ *  - the callee isn't an @expose action (a client magic like `this.refresh()` must stay
+ *    a client expression);
+ *  - **any argument reads `this`** — `this.count + 1` must re-evaluate on the client
+ *    against live reactive state, not be frozen into the markup at render time.
+ */
+function _asServerActionCall(
+  arrow: ts.ArrowFunction,
+  members: MemberInfo,
+): { method: string; argsSrc: string } | null {
+  if (arrow.parameters.length > 0) return null;
+
+  const body = ts.isBlock(arrow.body)
+    ? arrow.body.statements.length === 1 && ts.isExpressionStatement(arrow.body.statements[0]!)
+      ? (arrow.body.statements[0] as ts.ExpressionStatement).expression
+      : null
+    : arrow.body;
+  if (!body || !ts.isCallExpression(body)) return null;
+  if (!ts.isPropertyAccessExpression(body.expression)) return null;
+  if (body.expression.expression.kind !== ts.SyntaxKind.ThisKeyword) return null;
+
+  const method = body.expression.name.text;
+  if (CLIENT_CALLBACK_MAGICS.has(method) || CLIENT_MAGICS.has(method)) return null;
+  // Actions are @expose methods, so `exposed` is the whole allowlist.
+  if (!members.exposed.has(method)) return null;
+  if (body.arguments.length === 0) return null; // no args → plain flow:click="method"
+
+  for (const arg of body.arguments) {
+    if (_referencesThis(arg)) return null;
+  }
+
+  return { method, argsSrc: body.arguments.map((a) => a.getText()).join(", ") };
+}
+
+/** True when `node` reads `this` anywhere (so it must stay a live client expression). */
+function _referencesThis(node: ts.Node): boolean {
+  if (node.kind === ts.SyntaxKind.ThisKeyword) return true;
+  let found = false;
+  ts.forEachChild(node, (child) => {
+    if (!found && _referencesThis(child)) found = true;
+  });
+  return found;
+}
+
+// ── Client-expression scope validation ────────────────────────────────────────
+
+/**
+ * Names a client expression may reference besides `$flow`, its own parameters, and
+ * its own locals: Alpine's magics (the expression is evaluated by Alpine) and the
+ * browser globals it is reasonable to reach for inline.
+ */
+const CLIENT_EXPR_GLOBALS = new Set([
+  // Alpine magics
+  "$el",
+  "$event",
+  "$refs",
+  "$store",
+  "$dispatch",
+  "$watch",
+  "$nextTick",
+  "$id",
+  "$root",
+  "$data",
+  "$flow",
+  // Language / literals
+  "undefined",
+  "NaN",
+  "Infinity",
+  "globalThis",
+  "arguments",
+  // Standard built-ins
+  "Object",
+  "Array",
+  "String",
+  "Number",
+  "Boolean",
+  "Math",
+  "JSON",
+  "Date",
+  "RegExp",
+  "Map",
+  "Set",
+  "Promise",
+  "Error",
+  "Symbol",
+  "BigInt",
+  "Intl",
+  "parseInt",
+  "parseFloat",
+  "isNaN",
+  "isFinite",
+  "encodeURIComponent",
+  "decodeURIComponent",
+  "encodeURI",
+  "decodeURI",
+  "structuredClone",
+  // Browser
+  "window",
+  "document",
+  "console",
+  "navigator",
+  "location",
+  "history",
+  "localStorage",
+  "sessionStorage",
+  "fetch",
+  "URL",
+  "URLSearchParams",
+  "FormData",
+  "Event",
+  "CustomEvent",
+  "alert",
+  "confirm",
+  "prompt",
+  "setTimeout",
+  "clearTimeout",
+  "setInterval",
+  "clearInterval",
+  "requestAnimationFrame",
+  "cancelAnimationFrame",
+  "matchMedia",
+  "getComputedStyle",
+]);
+
+/** Collect every name a binding pattern introduces (`{a, b: [c]}`, `...rest`). */
+function _collectBoundNames(name: ts.BindingName, into: Set<string>): void {
+  if (ts.isIdentifier(name)) {
+    into.add(name.text);
+    return;
+  }
+  for (const element of name.elements) {
+    if (ts.isOmittedExpression(element)) continue;
+    _collectBoundNames(element.name, into);
+  }
+}
+
+/**
+ * Reject a client expression that references a name the browser will not have.
+ *
+ * Client expressions are emitted as source text with `this.` rewritten to `$flow.`;
+ * every other identifier is emitted verbatim. So a handler that closes over an
+ * enclosing scope — the loop variable in
+ * `{items.map((item) => <button onClick={() => this.select(item.id)}>)}` — compiles
+ * to `$flow.select(item.id)`, where `item` does not exist. At runtime that throws a
+ * ReferenceError inside the bridge's evaluator, which logs to the browser console
+ * and returns: the click does nothing, the server never hears about it, and the page
+ * looks perfect. Catching it here turns a silent dead button into a build error that
+ * names the identifier.
+ *
+ * Server actions that need a row id take arguments instead — `onClick={this.remove}`
+ * with `data-args={JSON.stringify([row.id])}`.
+ */
+function _assertClientExprScope(expr: ts.Expression, members: MemberInfo, filename: string): void {
+  // Names bound *within* the expression (arrow params, block locals, catch bindings).
+  const scoped = new Set<string>();
+
+  const collectScope = (node: ts.Node): void => {
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+      for (const param of node.parameters) _collectBoundNames(param.name, scoped);
+    } else if (ts.isVariableDeclaration(node)) {
+      _collectBoundNames(node.name, scoped);
+    } else if (ts.isCatchClause(node) && node.variableDeclaration) {
+      _collectBoundNames(node.variableDeclaration.name, scoped);
+    }
+    ts.forEachChild(node, collectScope);
+  };
+  collectScope(expr);
+
+  const check = (node: ts.Node): void => {
+    // `a.b` — only `a` is a free identifier; `b` is a property name.
+    if (ts.isPropertyAccessExpression(node)) {
+      check(node.expression);
+      return;
+    }
+    // `{ key: value }` — `key` is not a reference.
+    if (ts.isPropertyAssignment(node)) {
+      check(node.initializer);
+      return;
+    }
+    if (ts.isShorthandPropertyAssignment(node)) {
+      // `{ x }` — `x` IS a reference.
+      _checkIdentifier(node.name, scoped, members, filename, expr);
+      return;
+    }
+    if (ts.isIdentifier(node)) {
+      _checkIdentifier(node, scoped, members, filename, expr);
+      return;
+    }
+    ts.forEachChild(node, check);
+  };
+  // Enter through `check`, not forEachChild: when the whole expression IS a property
+  // access (`$flow.store.ui.open`), forEachChild would hand us its trailing name as a
+  // bare identifier and we would reject the root of the chain's own property.
+  check(expr);
+}
+
+function _checkIdentifier(
+  id: ts.Identifier,
+  scoped: Set<string>,
+  members: MemberInfo,
+  filename: string,
+  expr: ts.Expression,
+): void {
+  const name = id.text;
+  if (scoped.has(name)) return;
+  if (CLIENT_EXPR_GLOBALS.has(name)) return;
+  if (name.startsWith("$")) return; // an Alpine plugin magic we don't know about
+
+  const sf = id.getSourceFile();
+  const { line, character } = sf.getLineAndCharacterOfPosition(id.getStart(sf));
+
+  // A member of the component is the most likely intent, and has a precise fix.
+  const isMember = members.readable.has(name) || members.exposed.has(name);
+  const hint = isMember
+    ? `Did you mean this.${name}? A bare \`${name}\` is not in scope in the browser.`
+    : `\`${name}\` comes from an enclosing server-side scope, and client expressions ` +
+      `are emitted verbatim — it will not exist in the browser.\n` +
+      `      To pass a value to a server action, use data-args:\n` +
+      `        <button onClick={this.method} data-args={JSON.stringify([${name}])}>`;
+
+  throw new FlowValidationError(
+    `[Flow] client expression references \`${name}\`, which will be undefined in the browser.\n` +
+      `  ${_at(filename, line + 1, character + 1)}  in \`${_snippet(expr, 60)}\`\n` +
+      `      → ${hint}`,
+  );
+}
+
 function _isComponent(tag: string): boolean {
   const c = tag.charCodeAt(0);
   return c >= 65 && c <= 90; // A–Z

package/src/jsx-runtime.ts

@@ -10,7 +10,11 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { escapeHtml } from "@zerotal/core/helpers";
 import { getExposedProps, getLockedProps } from "./decorators.ts";
-import { _setExposedKeyCapture, _consumeExposedKeyCapture } from "./utils.ts";
+import {
+  _setExposedKeyCapture,
+  _consumeExposedKeyCapture,
+  _consumeExposedKeyReads,
+} from "./utils.ts";
 import { URL_ATTRIBUTES, sanitizeUrl } from "./urlSafety.ts";
 
 /** The rendered output of a JSX element: an object carrying its serialized HTML string. */
@@ -557,18 +561,27 @@ export function _resolveBindName(
  * capture AND a value-identity match, so a literal or server value never false-positives),
  * or null when the attribute is just an ordinary server-rendered value.
  * `locked` distinguishes @locked (read-only, reactive) from @expose (two-way).
+ *
+ * @remarks
+ * The getter capture is a single slot and *all* of an element's props are evaluated
+ * before `jsx()` runs, so any later prop that reads an exposed property clobbers it —
+ * `value={this.destination} disabled={this.notSure}` leaves the capture pointing at
+ * `notSure`. The freshness check then fails and the element renders with no
+ * `flow:model` at all: the field accepts typing and nothing ever reaches the server.
+ * When the capture is unusable we therefore fall back to a value-identity scan over
+ * the exposed props, exactly as `_resolveBindName` does — binding correctly whenever
+ * the answer is unambiguous, rather than silently dropping the binding.
  */
 function _resolveValueBind(value: unknown): { name: string; locked: boolean } | null {
   const page = _getRenderCtx()?.page ?? null;
   if (!page) return null;
   const cap = _consumeExposedKeyCapture();
-  if (!cap) return null;
   const exposed = getExposedProps(page); // includes @locked
 
   // Dotted capture (e.g. "form.email") — a Form field. The root must be an exposed
   // prop and the nested value must identity-match (freshness guard). Form fields
   // are always writable (two-way), so locked is false.
-  if (cap.includes(".")) {
+  if (cap && cap.includes(".")) {
     const root = cap.slice(0, cap.indexOf("."));
     if (!exposed.has(root)) return null;
     const nested = cap
@@ -578,11 +591,29 @@ function _resolveValueBind(value: unknown): { name: string; locked: boolean } |
     return { name: cap, locked: false };
   }
 
-  if (!exposed.has(cap)) return null;
-  // Confirm the capture is fresh for THIS value (guards against a stale capture
-  // lingering from a previous element that didn't consume it).
-  if (!Object.is((page as Record<string, unknown>)[cap], value)) return null;
-  return { name: cap, locked: getLockedProps(page).has(cap) };
+  // Capture fast path: trust it only when it is fresh for THIS value (guards against
+  // a stale capture lingering from a previous element that didn't consume it).
+  if (cap && exposed.has(cap) && Object.is((page as Record<string, unknown>)[cap], value)) {
+    _consumeExposedKeyReads(); // this element is resolved; don't leak reads to the next
+    return { name: cap, locked: getLockedProps(page).has(cap) };
+  }
+
+  // The single slot was clobbered by a later prop on the same element (the B2 case:
+  // `value={this.destination} disabled={this.notSure}`). Fall back to the keys actually
+  // read while this element's props were evaluated, most recent first, and take the one
+  // whose current value IS this value.
+  //
+  // Crucially this is NOT a scan of every exposed prop: a key only qualifies if it was
+  // genuinely read through a `this.` getter, so a literal `value="CUSTOM"` that happens
+  // to equal some property's current value still binds nothing.
+  const reads = _consumeExposedKeyReads();
+  for (const key of reads) {
+    if (key === cap) continue; // already rejected above
+    if (!exposed.has(key)) continue;
+    if (!Object.is((page as Record<string, unknown>)[key], value)) continue;
+    return { name: key, locked: getLockedProps(page).has(key) };
+  }
+  return null;
 }
 
 /**
@@ -1061,6 +1092,18 @@ export function jsx(
         attrs.push(`value="${escapeAttr(String(v ?? ""))}"`);
         continue;
       }
+      // A radio's `value` is the option's identifier and its `checked` is a per-option
+      // boolean — neither is a two-way binding target, and inferring one is actively
+      // wrong. In a group rendered from a .map() the inference lands on whichever single
+      // option currently equals the bound property, so that one radio claims the whole
+      // group's model and overwrites the user's pick on every flush. Bind a radio group
+      // explicitly with {...this.bind('prop', 'optionValue')}, which knows the group is
+      // addressed as a unit.
+      if (type === "input" && String(p["type"] ?? "") === "radio") {
+        if (k === "value") attrs.push(`value="${escapeAttr(String(v ?? ""))}"`);
+        else if (v) attrs.push("checked");
+        continue;
+      }
       const bound = _resolveValueBind(v);
       if (bound) {
         if (bound.locked) {

package/src/provider/FlowProvider.ts

@@ -274,6 +274,22 @@ async function _handleFlowMessage(ws: FlowBunWs, raw: string, deps: FlowWsDeps):
   await deps.container.runScoped(async (scoped) => {
     const ctx = new HttpContext(request, scoped);
 
+    // A WebSocket action has no Bun `Server` behind it, so `ctx.ip()` — which resolves
+    // through `server.requestIP(request)` — would return null for every action even
+    // though the socket's peer address is known here and was captured at upgrade. Supply
+    // a minimal provider so `request().ip()` answers the same inside an action as it does
+    // during the initial HTTP render, instead of silently degrading to null.
+    const socketIp = ws.data.remoteIp;
+    if (socketIp && socketIp !== "unknown") {
+      ctx._server = {
+        requestIP: () => ({
+          address: socketIp,
+          family: socketIp.includes(":") ? "IPv6" : "IPv4",
+          port: 0, // not carried across the upgrade; nothing reads it
+        }),
+      };
+    }
+
     await RequestContext.run(ctx, async () => {
       let passed = false;
       let redirectUrl: string | undefined;

package/src/testing.ts

@@ -54,6 +54,10 @@ export class FlowTest<T extends Component> {
   private _effects: FlowEffects | null = null;
   private _snapshot: Snapshot | null = null;
   private _name: string;
+  /** Set by {@link tolerateErrors}: capture action errors instead of rethrowing them. */
+  private _tolerateErrors = false;
+  /** The last non-validation error an action threw, when {@link tolerateErrors} is on. */
+  private _lastError: Error | null = null;
 
   private constructor(page: T, name: string) {
     this._page = page;
@@ -97,13 +101,43 @@ export class FlowTest<T extends Component> {
   // ── Actions ────────────────────────────────────────────────────────────────
 
   /**
-   * Set a property value directly (state seeding), then return for chaining.
-   * Does NOT fire the updating/updated hooks — use `update()` to simulate a
-   * client-driven property change.
+   * Set a property value directly (state seeding) and re-render, then return for
+   * chaining. Does NOT fire the updating/updated hooks — use `update()` to
+   * simulate a client-driven property change.
+   *
+   * The re-render is the point: without it `html()` and every assertion that reads
+   * it would still describe the render from *before* the assignment, so a test
+   * would silently assert against stale markup. Use {@link seed} when you are
+   * assigning several properties and only want to pay for one render.
    * @category Actions
    */
   async set(prop: keyof T, value: unknown): Promise<this> {
     (this._page as Record<string, unknown>)[prop as string] = value;
+    await this._render();
+    return this;
+  }
+
+  /**
+   * Assign a property without re-rendering — the batching form of {@link set}.
+   * Nothing reads the new value until the next `set`/`update`/`call` (or an
+   * explicit {@link render}) produces a fresh render.
+   * @category Actions
+   *
+   * @example
+   * ```ts
+   * await t.seed('step', 3);
+   * await t.seed('mode', 'advanced');
+   * await t.render();          // one render for both
+   * ```
+   */
+  async seed(prop: keyof T, value: unknown): Promise<this> {
+    (this._page as Record<string, unknown>)[prop as string] = value;
+    return this;
+  }
+
+  /** Re-render the page without changing state (pairs with {@link seed}). @category Actions */
+  async render(): Promise<this> {
+    await this._render();
     return this;
   }
 
@@ -120,15 +154,71 @@ export class FlowTest<T extends Component> {
     return this;
   }
 
+  /**
+   * Opt out of the rethrow in {@link call}: a throwing action is captured on the
+   * harness instead of failing the test, so the error path itself can be asserted.
+   *
+   * Only for tests *about* error handling. Leaving it off is what makes a broken
+   * action fail its test rather than look like a no-op.
+   * @category Actions
+   *
+   * @example
+   * ```ts
+   * const t = (await FlowTest.mount(CheckoutPage)).tolerateErrors();
+   * await t.call('submit');
+   * t.assertErrored(/payment gateway/);
+   * ```
+   */
+  tolerateErrors(): this {
+    this._tolerateErrors = true;
+    return this;
+  }
+
+  /** The last non-validation error an action threw, or null. @category Actions */
+  lastError(): Error | null {
+    return this._lastError;
+  }
+
+  /**
+   * Assert the last action threw, optionally matching its message.
+   * Requires {@link tolerateErrors} — without it a throwing action fails the test outright.
+   * @category Assertions
+   */
+  assertErrored(match?: string | RegExp): this {
+    if (!this._lastError) {
+      throw new Error(
+        `[FlowTest] Expected the last action on ${this._name} to throw, but it did not.`,
+      );
+    }
+    if (match !== undefined) {
+      const message = this._lastError.message;
+      const ok = typeof match === "string" ? message.includes(match) : match.test(message);
+      if (!ok) {
+        throw new Error(
+          `[FlowTest] Expected the error message to match ${String(match)}, but got: ${message}`,
+        );
+      }
+    }
+    return this;
+  }
+
   /**
    * Call an action method and re-render. Simulates a subsequent (WebSocket) request:
    * runs `onBoot()` + `onHydrate()`, invokes the method, then `onUpdate()` and re-render.
-   * If the action throws ValidationError, the errors are stored and the page re-renders
-   * with the error bag populated; any other thrown error is routed to `onError()`.
+   *
+   * A `ValidationError` is an expected outcome: the errors are stored and the page
+   * re-renders with the error bag populated, exactly as in production.
+   *
+   * Any other error is routed to `onError()` (mirroring production) and then
+   * **rethrown**, so a broken action fails its test instead of silently rendering
+   * an unchanged page. Call {@link tolerateErrors} first when the error path is
+   * what you are testing.
    *
    * @param method - Name of the method to invoke on the page.
    * @param args - Arguments forwarded to the method.
    * @throws If `method` is not a function on the page instance.
+   * @throws Whatever the action threw, unless it was a `ValidationError` or
+   *   {@link tolerateErrors} is on.
    * @category Actions
    */
   async call(method: string, ...args: unknown[]): Promise<this> {
@@ -141,16 +231,25 @@ export class FlowTest<T extends Component> {
     await this._page.onBoot();
     await this._page.onHydrate();
 
+    this._lastError = null;
+    let thrown: Error | null = null;
+
     try {
       await (fn as (...a: unknown[]) => unknown).apply(this._page, args);
     } catch (error) {
       if (error instanceof ValidationError) {
-        // Errors already stored on page._errors
+        // Errors already stored on page._errors — a normal, assertable outcome.
       } else {
+        thrown = error instanceof Error ? error : new Error(String(error));
+        this._lastError = thrown;
+        // Run the production error hook so its side effects (the default flashes
+        // the message) are observable either way. An onError that itself throws
+        // replaces the original — surfacing the deeper bug rather than hiding it.
         try {
-          await this._page.onError(error instanceof Error ? error : new Error(String(error)));
-        } catch {
-          // ignore
+          await this._page.onError(thrown);
+        } catch (hookError) {
+          thrown = hookError instanceof Error ? hookError : new Error(String(hookError));
+          this._lastError = thrown;
         }
       }
     }
@@ -158,6 +257,10 @@ export class FlowTest<T extends Component> {
     await this._page.onUpdate();
     this._effects = this._page._drainEffects();
     await this._render();
+
+    // Rethrow after the re-render, so an opted-in test still sees the rendered
+    // error state and a non-opted-in test gets the real stack.
+    if (thrown && !this._tolerateErrors) throw thrown;
     return this;
   }
 

package/src/utils.ts

@@ -176,15 +176,46 @@ export interface FlowChain<T> {
 // Shared capture variable: set by instrumented @expose getters in jsx-runtime,
 // consumed immediately by flow() to embed __key in the chain.
 let _exposedKeyCapture: string | undefined;
+
+/**
+ * Every exposed key read since the last consume, in read order.
+ *
+ * `_exposedKeyCapture` is a single slot, but JSX evaluates *all* of an element's
+ * props before `jsx()` runs — so `value={this.destination} disabled={this.notSure}`
+ * leaves the slot pointing at `notSure` and the `value` binding resolves to nothing.
+ * Keeping the full read list lets a binding find the key that actually matches its
+ * own value, while still refusing to bind a literal that was never read through a
+ * `this.` getter at all. Bounded so a pathological render cannot grow it without limit.
+ */
+const _exposedKeyReads: string[] = [];
+const _MAX_KEY_READS = 64;
+
 export function _setExposedKeyCapture(k: string | undefined): void {
   _exposedKeyCapture = k;
+  if (k === undefined) return;
+  // Keep the most recent read last; drop an earlier duplicate so order stays meaningful.
+  const at = _exposedKeyReads.indexOf(k);
+  if (at !== -1) _exposedKeyReads.splice(at, 1);
+  _exposedKeyReads.push(k);
+  if (_exposedKeyReads.length > _MAX_KEY_READS) _exposedKeyReads.shift();
 }
+
 export function _consumeExposedKeyCapture(): string | undefined {
   const k = _exposedKeyCapture;
   _exposedKeyCapture = undefined;
   return k;
 }
 
+/**
+ * The keys read since the last call, most recent first, clearing the list.
+ * Used by the value/checked binding resolver to survive a clobbered single slot.
+ */
+export function _consumeExposedKeyReads(): string[] {
+  const reads = _exposedKeyReads.slice().reverse();
+  _exposedKeyReads.length = 0;
+  return reads;
+}
+
 export function flow<T>(target: T): FlowChain<T> {
   const modifiers: string[] = [];
   // Capture immediately so subsequent prop evaluations cannot clobber it.