@zerotal/flow 1.6.3 → 1.7.2

package/CHANGELOG.md

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