@zerotal/flow 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -4,12 +4,325 @@ 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: `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.
+**Maturity: `stable`** — matching this package's `maturity` field. The public API
+follows SemVer strictly: anything importable without an `@internal` marker keeps its
+shape for the rest of the 1.x line, and `api-surface.md` is diffed by CI on every
+change.
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-08-15
+
+### Changed — BREAKING
+
+- **`redirectRoute(name, params)` takes route params only.** Extra keys used to become
+  query-string entries; core's `route()` now treats a key that matches no `:segment` as
+  the mistake it usually is and throws, naming it. Route names and params are checked at
+  compile time once the app has run `bun zt route:types`. For a redirect that needs a
+  query string, build the URL: `this.redirect(route("posts.show", { slug }, { ref }))`.
+
+### Changed
+
+- **The client now says which transport failure it hit.** `[Flow] WebSocket unavailable —
+falling back to HTTP requests` was the same line whether the handshake was blocked by a
+  proxy, refused by the origin guard, or genuinely unreachable, and the HTTP fallback then
+  logged a bare `HTTP 403` that dropped both the status and the server's own explanation.
+
+  A `403` from `/__flow/http` is now reported once, in full, naming the page's origin and
+  the config that fixes it — and the connection state drops to **offline**. That is the
+  honest state: the origin guard will refuse every retry, so actions queue behind
+  `flow:offline` directives instead of being fired at an endpoint that cannot accept them.
+  A refused origin was the one failure the fallback could see and was reporting as a
+  transient degrade.
+
+- **Flow no longer rebuilds its CSS/JS bundles at boot in production when `public/` is
+  read-only.** Same policy as `serve`; see `@zerotal/core`. Build them with
+  `bun zt assets:build` as a release step and the service needs no write access to its own
+  output tree.
+
+- **`/__flow/ws` is declared at registration**, so a CLI process can name it. That is what
+  lets `bun zt doctor --url=…` probe the socket through the real proxy — the check that
+  catches an origin guard or an auth gate over the transport before a user does.
+
+### Fixed
+
+- **A decorator could be registered against the wrong component.** Field decorators
+  cannot see their own class, so each registration is buffered in the decorator body
+  and matched to a class later. The match searched the whole buffer by field name, and
+  a component that declares a field and is never rendered leaves its entry buffered for
+  the life of the process — so an unrelated component with a field of the same name
+  could claim it, receive a decorator it never asked for, and never receive its own.
+  `page`, `count` and `open` are declared in a lot of files.
+
+  Two things were wrong. The search now runs per declaring class rather than across
+  one flat buffer, and a class is matched on the fields it **declares** rather than
+  every field on an instance — a subclass inherits its mixin's fields, so a leftover
+  block from another application of that mixin used to out-score the subclass's own.
+
+  It surfaced as `@reactive` failing to register: the prop was then folded into the
+  child's id, so every parent-pushed change remounted the child instead of updating it
+  in place — the exact thing `@reactive` exists to prevent. Whether it happened
+  depended on which modules had loaded first, which is why it reproduced on one machine
+  and not another.
+
+- **A keyless child in a list is no longer identified by its position.** The id was
+  `<parentId>-<name>-<occurrence index>`, and an index is _position_, not identity:
+  remove an item from a list and every row below it inherits the id its neighbour had.
+  Because a hydrated parent emits an already-known child as an **empty stub** — on the
+  understanding that the client morph will recognise the pairing — every row then
+  adopted the previous row's live DOM and the last was left blank. Nothing warned, and
+  nothing server-side could see it: SSR, snapshot assertions and `FlowTest` all render
+  the full child every time, because they never take the already-mounted branch.
+
+  The id is now derived from the child's **seed props** plus an occurrence counter, so
+  the pairing is content-addressed and a shifted row is rendered in full rather than
+  crossed with its neighbour. `@reactive` and `@modelable` props are deliberately
+  excluded — those exist to change _without_ remounting the child, and hashing them
+  would trade this bug for a child that resets on every parent update.
+
+  Two siblings whose props are identical are still, as far as the framework can see,
+  the same child. Flow now logs a warning the first time it sees that in development,
+  naming the class and the fix. `key` remains the answer, and the docs say so where
+  `child()` is documented.
+
+### Added
+
+- **`<ErrorBoundary>` — a failing child costs that child, not the page.** A nested
+  component that threw while mounting or rendering took the whole response with it: one
+  broken widget blanked the dashboard, and the only defence was to make every child
+  defensive from the inside. Wrapped, the child is replaced and everything around it
+  renders:
+
+  ```tsx
+  <ErrorBoundary fallback={<p class="text-sm text-red-600">Sales data unavailable.</p>}>
+    <SalesReport />
+  </ErrorBoundary>
+  ```
+
+  `fallback` may be a function, which receives the thrown error; `onError` reports it to a
+  log or a tracker without changing what renders. Boundaries nest and the innermost one
+  wins, and siblings are independent — one failing widget does not affect the other.
+
+  What it covers is child _components_.
+  Inline JSX in the same `render()` is evaluated before the boundary is ever called, so a
+  throw there cannot be intercepted here — move the risky work into a child component,
+  which is where it belongs anyway. Containment is opt-in for the same reason: a child
+  outside every boundary still fails the page, so a real bug surfaces instead of rendering
+  as blank space forever.
+
+- **`stream` — a slow child no longer holds up the shell.** Mark a child
+  `<SalesReport stream />` and the page paints immediately with that child's placeholder;
+  the real markup is appended to the _same_ response as it finishes rendering. The browser
+  receives a `<template>` carrying the finished markup and a one-line script that swaps it
+  in, which runs during parse — so the content appears without a second request, without
+  the socket, and without waiting for (or even having) the runtime.
+
+  This is the missing third option next to `lazy` and `defer`. Both of those also paint a
+  placeholder first, but the real render happens on a second round trip over the socket,
+  which is right for content that may never be needed — a widget below the fold, a tab
+  nobody opens. `stream` is for content that is definitely needed and merely slow, where
+  the only thing a round trip buys is latency.
+
+  A child that fails mid-stream is replaced with a notice rather than failing the
+  response: the shell is already on the wire by then, so there is nothing left to fail.
+  Streaming applies to the initial `GET` only — over the socket there is no open response
+  to append to, so `stream` degrades to an ordinary inline child. Flow sets
+  `X-Accel-Buffering: no`; behind a proxy that buffers anyway the browser simply receives
+  the whole document at once, which is correct but not progressive.
+
+- **`<SectionContent>` / `<SectionOutlet>` — a page can fill a region the layout owns.**
+  Putting a page-specific button in the layout's toolbar meant threading it through every
+  component in between as props, or the layout knowing about every page that might
+  contribute. Sections invert that: the component that owns the content declares it, and
+  the layout declares a hole.
+
+  ```tsx
+  // In the layout
+  <SectionOutlet name="toolbar" />
+
+  // In any page — renders nothing here
+  <SectionContent name="toolbar">
+    <button onClick={this.publish}>Publish</button>
+  </SectionContent>
+  ```
+
+  Order does not matter. An outlet emits a token and is filled in a final pass over the
+  finished document rather than reading a store when it renders — which is what makes the
+  usual arrangement work at all, since the layout wraps a page that has already rendered.
+  Two components may publish to one name and their content accumulates in render order.
+  Outlet children are the default, used when nothing was published.
+
+  Sections resolve once per document render: a WebSocket patch re-renders a component, not
+  the layout, so content published during one does not reach an outlet outside the
+  component being patched.
+
+- **`<Virtualize>` — a scrolling window over a collection too large for the DOM.** Only
+  the visible rows exist as elements; spacers above and below hold the scrollbar at the
+  size the full collection implies. As the viewport moves, `onWindow(start, count)` asks
+  the server for the window it now needs, so the collection never has to reach the client
+  in full — the server-authoritative arrangement, with an
+  `ItemsProvider`.
+
+  ```tsx
+  <Virtualize
+    items={this.rows}
+    start={this.windowStart}
+    total={this.total}
+    itemHeight={36}
+    height={480}
+    onWindow={this.loadWindow}
+  >
+    {(row) => <div class="h-9 px-3 leading-9">{row.name}</div>}
+  </Virtualize>
+  ```
+
+  Rows must be a uniform `itemHeight` — that is what lets a scroll offset become an index
+  without measuring anything. `overscan` (default 6) renders extra rows on each side to
+  hide fetch latency, and a window request is only made when the needed window actually
+  changes, since scroll fires far more often than that. Distinct from `<InfiniteScroll>`,
+  which appends and grows the DOM without bound; reach for this when _keeping_ every
+  rendered row is the problem.
+
+- **`@zerotal/flow/browser` — drive a real browser against a running app.** The suite
+  had 568 tests and could not fail the way production fails: `FlowTest` calls actions
+  directly, so it never renders an attribute the client must find, never dispatches a
+  DOM event, and never opens the socket. Every silent failure Flow has shipped lived in
+  exactly that gap — a `<select>` that lost its binding, a click cancelled by
+  `preventDefault`, an action the server refused and mentioned only to `console.error`.
+  Depth was never the problem; shape was.
+
+  `FlowBrowser` drives headless Chrome over the DevTools Protocol, so a click is a real
+  click travelling through the page's own delegated listener, over a real socket, to the
+  real dispatcher, and back as a real patch:
+
+  ```ts
+  const page = await FlowBrowser.open(`http://localhost:${port}/counter`);
+  await page.click("#increment");
+  await page.waitForText("#count", "1");
+  expect(page.consoleErrors()).toEqual([]);
+  ```
+
+  Console output is captured deliberately rather than incidentally: a refused action is
+  reported _only_ there, so a harness that cannot see the console cannot see the
+  failure. Waits are polls with timeouts that name what they were waiting for and what
+  the console said, so a break reads as a diagnosis instead of a mystery.
+
+  No Puppeteer, no Playwright — it speaks CDP over Bun's own WebSocket and drives a
+  browser the machine already has, matching the zero-dependency posture of the telemetry
+  tracer and the media image driver. `FlowBrowser.available()` lets a suite skip where no
+  browser is installed rather than fail; `CHROME_PATH` pins a binary for CI.
+
+- **A compiled-versus-runtime parity suite.** Flow renders a page one of two ways, and
+  when the AOT compiler bails the runtime renderer infers bindings by observing property
+  reads instead of reading intent from the AST — necessarily weaker, and the gap between
+  them is where the field reports kept finding silent failures. "Weaker mechanism" is not
+  the same claim as "different output", so the output is now pinned: each case is written
+  once, compiled _and_ imported as a real class, and both paths must emit the same
+  bindings. They agree across the corpus, including the two shapes that were reported as
+  broken. A case the compiler bails on still has to carry its binding through the
+  fallback.
+
+### Fixed
+
+- **`data-flow-connection` is stamped on a page that connects normally.** The attribute
+  was only written when the connection state _changed_, and the bridge starts optimistic
+  (`_isOnline = true`), so a socket that connected on the first attempt — the normal case
+  — left the attribute absent entirely. A stylesheet or a readiness check keyed on
+  `[data-flow-connection="online"]` would wait forever on a page that was in fact
+  perfectly connected. Found by the browser harness on its first run, which is a fair
+  summary of why the harness exists.
+
+### Changed
+
+- **Maturity is now `stable`** — the public API follows SemVer strictly for the rest of
+  the 1.x line. Both gates that stood in the way are closed in this release, and neither
+  was closed by relabelling:
+
+  - The **bridge is covered by a real browser**, so the layer that produced every silent
+    failure Flow has shipped is now exercised by tests that fail when it breaks. The gap
+    was never depth — it was that 568 tests all stopped short of the socket.
+  - The **two render paths are pinned to the same output**, so the "compiled is stronger
+    than runtime" caveat is now a statement about mechanism rather than an unmeasured
+    behavioural risk.
+
+  The supporting evidence: the deepest test coverage in the monorepo, correct
+  `@internal` discipline across 61 markers, thirteen documentation pages, dependencies
+  only on stable packages, and an API surface snapshotted and CI-diffed on every change.
+  The one breaking change Flow has ever made was 1.3.0's mixin-composition rename; 1.4.0
+  and this release both followed it without one.
+
+  Being honest about what the label does not claim: Flow has less production exposure
+  than the core and ORM layers, and the parity suite characterises a corpus of binding
+  shapes rather than proving the two renderers identical for every program. What
+  `stable` commits to is that the API will not move under you, and that is a promise
+  this release can keep.
+
+- **A client expression that writes an `@expose` prop now syncs to the server.**
+  `onClick={() => (this.selected = row.id)}` updated the reactive store and nothing
+  else — `render()` runs on the server, so a template branch keyed on the write
+  (`this.selected === row.id ? <RowDetail /> : null`) never appeared, with no error
+  anywhere. Worse, it _worked_ whenever some later action happened to flush the
+  pending write, so the mental model "`@expose` state is reactive" was true for
+  `flow:model` inputs and intermittently false for expression writes.
+
+  Writes made during a client-expression evaluation are now recorded; when the
+  expression dispatches no action on that component itself, one `$rerender` follows —
+  the frame's `updates` carry every pending write through the same allowlist and
+  `updating()`/`updated()` hooks as any action, and the re-render is patched back.
+  No loading state is shown (it is a sync, not a user action), an expression that
+  also calls a server action syncs nothing extra (the action's frame already carries
+  the writes), and a write that lands back on the canonical value sends nothing.
+  State the server should never see belongs in `this.store()`, which stays
+  client-only. `$flow.$refresh()` remains for forcing a full `onMount` re-run.
+
+### Fixed
+
+- **The dev timeline pill docks bottom-left, as its own comment always said.** The CSS
+  put it at `top: 88px` at maximum z-index — exactly where a left-rail's first
+  navigation item lives, which it then covered and swallowed clicks for. It now sits at
+  bottom-left with the frame list opening upward, and the corner is configurable via
+  `data-flow-tl-corner="top-right"` (any corner) on `<html>` or `<body>`. Only affects
+  the standalone fallback pill; the devtools-panel Timeline tab is unchanged.
+
+## [1.4.0] — 2026-08-10
+
+### Fixed
+
+- **`focusOnError` did nothing on a page that rendered through the runtime.** The
+  JSX runtime rewrites `-` to `.` inside a `flow:` attribute — right for a
+  hand-written `flow:loading-class`, wrong for a name the directive map already
+  spells out. `focusOnError` reached the DOM as `flow:focus.error` while the
+  bridge only ever queries `[flow\:focus-error]`, so focus-on-error worked on a
+  compiled page and silently did not on one the compiler bailed out of (a
+  branching `render()`, say). Mapped names now go out verbatim; the kebab→dot
+  rewrite still applies to attributes written by hand. `sortGroupId` was affected
+  the same way.
+
+- **`flow:navigate` now scrolls, instead of leaving you wherever the last page
+  was.** The SPA swap replaced the page under a stationary viewport and never
+  touched the scroll offset, so following a link from near the bottom of a long
+  list landed you halfway down the next page. Nothing visible changed, which
+  reads as the page having failed to load rather than as a scroll problem.
+
+  A navigation now lands at the top of the new page, or at the fragment when the
+  href names one (`/docs#install`) — which is what the same link does without the
+  SPA swap. Back and Forward restore the position the entry was left at.
+
+  The scroll happens inside the swap, after the root is replaced: the document
+  only has its new height (and its fragment targets) at that point, and inside a
+  View Transition it is also what the "after" snapshot captures, so the animation
+  ends at the right offset rather than sliding to it. It is issued with
+  `behavior: "instant"`, so a page whose CSS sets `scroll-behavior: smooth` does
+  not animate the whole way up on every visit.
+
+### Added
+
+- **`preserveScroll`** — `<Link href="…" preserveScroll>` and
+  `this.navigateCurrent({ query: …, preserveScroll: true })` leave the viewport
+  where it is. For a control partway down a page — a sort header, a filter, a tab
+  strip — going to the top loses the thing the user was just looking at. Compiles
+  to `flow:navigate.preserve` on the anchor.
+
 ## [1.3.0] — 2026-08-09
 
 ### Fixed
@@ -127,7 +440,7 @@ _First public release._
 ### 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).
+- **`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, 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

package/README.md

@@ -2,7 +2,7 @@
 
 > 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.
+**Maturity: stable.** Flow's public API follows SemVer strictly: anything importable without an `@internal` marker keeps its shape for the rest of the 1.x line, and its surface is snapshotted in `api-surface.md`, which CI diffs on every change. The WebSocket bridge is covered end to end by a real browser (`@zerotal/flow/browser`), and the compiled and runtime render paths are pinned to the same binding output. It carries less production exposure than the core and ORM layers, so read the release notes — but the API will not move under you.
 
 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.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zerotal/flow",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "license": "MIT",
-  "maturity": "experimental",
+  "maturity": "stable",
   "private": false,
   "type": "module",
   "main": "./src/index.ts",
@@ -13,7 +13,8 @@
     "./jsx-dev-runtime": "./src/jsx-dev-runtime.ts",
     "./compiler-helpers": "./src/compiler/helpers.ts",
     "./store": "./src/store.ts",
-    "./testing": "./src/testing.ts"
+    "./testing": "./src/testing.ts",
+    "./browser": "./src/browser/index.ts"
   },
   "files": [
     "CHANGELOG.md",
@@ -45,14 +46,14 @@
     "@alpinejs/morph": "^3.14.9",
     "@alpinejs/persist": "^3.14.9",
     "@alpinejs/resize": "^3.14.9",
-    "@zerotal/core": "1.3.0",
-    "@zerotal/orm": "1.3.0",
-    "@zerotal/validator": "1.3.0",
+    "@zerotal/core": "1.5.0",
+    "@zerotal/orm": "1.5.0",
+    "@zerotal/validator": "1.5.0",
     "alpinejs": "^3.14.9",
     "typescript": "^5.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.3.0",
+    "@zerotal/broadcasting": "1.5.0",
     "@types/alpinejs": "^3.13.10",
     "@types/alpinejs__anchor": "^3.13.1",
     "@types/alpinejs__collapse": "^3.13.4",
@@ -64,7 +65,6 @@
   },
   "description": "Flow (experimental) — server-driven reactive UI for Zerotal with signed snapshots, delta transport, and real-time primitives.",
   "keywords": [
-    "experimental",
     "zerotal",
     "bun",
     "typescript",
@@ -72,7 +72,6 @@
     "reactive",
     "ssr",
     "websocket",
-    "livewire",
     "server-driven"
   ],
   "repository": {