@zerotal/arch 1.7.2 → 1.7.4

package/docs/errors.md

@@ -77,6 +77,28 @@ The full set exported from `zerotal`:
 > and `ServiceUnavailableError(reason, retryAfter)` populate the `Allow` and
 > `Retry-After` response headers for you when you pass those arguments.
 
+## Errors the framework raises
+
+The errors above are the ones you throw. These the framework throws at you, and
+each is written to name the fix rather than only the symptom. Most surface at
+boot, before a request is ever served:
+
+| Class                        | `code`                       | Raised when                                                                                                                              |
+| ---------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `BootCheckError`             | `E_BOOT_CHECK_FAILED`        | The boot-time doctor found one or more wiring problems.                                                                                  |
+| `ConfigValidationError`      | `E_CONFIG_VALIDATION_FAILED` | Config validation refused a production boot, listing every fatal issue by namespace.                                                     |
+| `FacadeBindingMissingError`  | `E_FACADE_BEFORE_BOOT`       | A facade was used after boot but nothing provides its binding — almost always a `ServiceProvider` missing from `bootstrap/providers.ts`. |
+| `ContextOutsideRequestError` | `E_CONTEXT_OUTSIDE_REQUEST`  | `RequestContext` was read with no request in scope, such as from module-level code or a background task. Renders as a 500.               |
+
+`BootCheckError` carries the whole list rather than the first failure it hit. Its
+`failures` array holds one `BootCheckFailure` per culprit — the `token`, the
+`provider` that declared it in `static provides`, and the `reason` — so a single
+restart tells you everything there is to fix.
+
+These four are not re-exported from `zerotal`, because throwing them yourself is
+not the point. Catch one by class from `@zerotal/core/errors`, or match on `code`
+the way you would any other framework error.
+
 ## Custom exception classes
 
 Extend `ZerotalError` for domain errors, or `HttpError` for HTTP errors. The

package/docs/flow/components.md

@@ -489,25 +489,21 @@ A dropzone bound to an `@expose` property. Choosing a file POSTs the bytes to `/
 import { Component, expose, FileUpload, FileUploads, TemporaryUploadedFile } from "@zerotal/flow";
 
 export class AvatarPage extends Component.using(FileUploads) {
+  @locked user!: User; // /users/:user/avatar — the record, already found
   @expose photo: TemporaryUploadedFile | null = null;
-  @locked photoUrl: string = "";
-
-  override async onMount() {
-    const user = await User.find(this.userId);
-    this.photoUrl = user?.avatarUrl ?? "";
-  }
 
   @expose async save(): Promise<void> {
     if (!this.photo) return;
     const path = await this.photo.store("avatars"); // moves to permanent storage
-    await User.query().where("id", this.userId).update({ avatarUrl: path });
+    this.user.avatarUrl = path;
+    await this.user.save();
     this.flash("Avatar updated.", "success");
   }
 
   override async render() {
     return (
       <div class="space-y-4">
-        {this.photoUrl && <img src={this.photoUrl} class="h-24 w-24 rounded-full" />}
+        {this.user.avatarUrl && <img src={this.user.avatarUrl} class="h-24 w-24 rounded-full" />}
 
         <FileUpload bind={this.photo} accept="image/*" maxSize="5mb" />
 

package/docs/flow/decorators.md

@@ -42,18 +42,19 @@ Only `@expose` properties are two-way: the client can push updates back to the s
 
 Sent to the client for display, but the client cannot mutate it. Included in the snapshot so it survives WebSocket round-trips without re-loading from the database.
 
+An ORM model is the exception: only its id travels in the snapshot and the row is re-read on every round-trip, so what the page shows is always current. See [Models in Components](/docs/flow/models).
+
 A `value={this.x}` binding on a `@locked` property renders as a read-only display — not an editable field.
 
-Use `@locked` for data loaded in `onMount()` that the server controls: model results, user info, computed totals, child props from the parent:
+Use `@locked` for anything the server owns: a record the route resolved, results loaded in `onMount()`, computed totals, child props from the parent:
 
 ```tsx
 export class PostsPage extends Component {
+  @locked user!: User; // /users/:user — the record, already found
   @locked posts: Post[] = [];
-  @locked user: User | null = null;
   @locked total: number = 0;
 
   override async onMount() {
-    this.user = await User.findOrFail(this.userId);
     this.posts = await Post.query()
       .where("user_id", this.user.id)
       .where("status", "published")
@@ -65,7 +66,7 @@ export class PostsPage extends Component {
   override async render() {
     return (
       <div>
-        <h1>Posts by {this.user?.name}</h1>
+        <h1>Posts by {this.user.name}</h1>
         <p>{this.total} posts</p>
         <ul>
           {this.posts.map((p) => (
@@ -269,7 +270,8 @@ An `@expose`d method that runs on the server but **skips the re-render cycle**.
 }
 
 @expose @renderless async archivePost(): Promise<void> {
-  await Post.where("id", this.postId).update({ status: "archived" });
+  this.post.status = "archived"; // this.post came from the route
+  await this.post.save();
   this.redirect("/posts");
 }
 ```
@@ -307,6 +309,8 @@ async onOrderCancelled(payload: { id: number }): Promise<void> {
 }
 ```
 
+Both forms are a `ListenerName`: the event string itself, or a resolver handed the component instance that returns one.
+
 See [Events & Broadcasting](/docs/flow/events) for dispatch methods, targeting, broadcasting, and native event integration.
 
 ## The @reactive decorator
@@ -396,8 +400,8 @@ See [Layouts & Composition](/docs/flow/layouts#two-way-props) for the full `@mod
 | `@expose method`                                | Callable from the browser via WebSocket                               |
 | `@expose @renderless method`                    | Callable from browser; skips re-render cycle                          |
 | `@on("event") method`                           | Listens for cross-component events (auto-exposed)                     |
-| `@on("socket:channel,Event") method`              | Listens for real-time server broadcasts                               |
-| `@on((self) => "socket:…") method`                | Same, with the channel resolved per instance (record ids)             |
+| `@on("socket:channel,Event") method`            | Listens for real-time server broadcasts                               |
+| `@on((self) => "socket:…") method`              | Same, with the channel resolved per instance (record ids)             |
 | `@reactive prop`                                | Child prop; parent re-pushes on change, child re-renders              |
 | `@modelable prop`                               | Two-way child prop; writes from child flow back to parent             |
 
@@ -421,13 +425,13 @@ this.redirectIntended("/dashboard"); // back to where AuthMiddleware intercepted
 // Force onMount() to re-run this round-trip (useful for reloading stale data)
 this.refresh();
 
-// Update the document title in the browser tab
-this.title("Edit post — My App");
+// The document title is `static title` on the class, not an action — see Routing.
 
-// Run raw JavaScript in the browser after the DOM patch is applied
-this.client("$refs.titleInput.focus()");
-this.client("window.scrollTo({ top: 0, behavior: 'smooth' })");
-this.client(`$dispatch('toast', { message: 'Done!' })`);
+// Run JavaScript in the browser after the DOM patch is applied. `$` is a tagged
+// template, so interpolated values are encoded for you.
+this.$`$refs.titleInput.focus()`;
+this.$`window.scrollTo({ top: 0, behavior: 'smooth' })`;
+this.$`$dispatch('toast', { message: ${this.message} })`;
 
 // Trigger a file download in the browser
 this.download("report.csv", csvContent, "text/csv;charset=utf-8");

package/docs/flow/events.md

@@ -276,8 +276,8 @@ export class OrderDashboard extends Component {
 
 ### Channel name formats
 
-| Format                             | Channel type                            |
-| ---------------------------------- | --------------------------------------- |
+| Format                               | Channel type                            |
+| ------------------------------------ | --------------------------------------- |
 | `socket:channel,Event`               | Public channel                          |
 | `socket-private:channel,Event`       | Private channel (requires auth)         |
 | `socket-presence:room,joining`       | Presence channel — member joined        |
@@ -315,7 +315,7 @@ The resolver runs once per render, after `onMount()`, so it can read anything th
 loaded. If it throws — a field it reads is still null, say — that one listener is dropped and the
 page renders without it, rather than the render failing.
 
-Resolve the *narrowest* channel the reader is entitled to. A static `issues` channel with an
+Resolve the _narrowest_ channel the reader is entitled to. A static `issues` channel with an
 `if (payload.issueId !== this.issue.id) return` in the handler looks equivalent and is not: the
 broadcast still reaches every subscriber's browser, so every reader receives every issue's
 comment bodies and discards them after the fact.

package/docs/flow/icons.md

@@ -0,0 +1,199 @@
+---
+title: Icons
+description: 2,060 icons bundled with Flow's component library — typed by name, rendered on the server, nothing to install.
+---
+
+# Icons
+
+`<Icon>` draws an icon by name. The set ships inside `@zerotal/flow-ui`, so this
+works in a new app with nothing installed and nothing configured:
+
+```tsx
+import { Icon } from "@zerotal/flow-ui";
+
+<Icon name="inbox" />
+<Icon name="chevron-right" />
+<Icon name="trash-2" class="size-5 text-red-600" />
+```
+
+The name is a union of every bundled icon, so a typo is a compile error rather
+than a blank space nobody notices until it is in front of a user:
+
+```text
+Type '"inbxo"' is not assignable to type 'IconName'. Did you mean '"inbox"'?
+```
+
+That works on install — there is no generator to run first. The icons belong to
+the framework, so the names are known before your app exists.
+
+## Props
+
+`IconProps` — anything else you pass lands on the rendered `<svg>`.
+
+| Prop    | Type       | Description                                                                    |
+| ------- | ---------- | ------------------------------------------------------------------------------ |
+| `name`  | `IconName` | Which icon. Checked at compile time against the bundled and registered names.  |
+| `label` | `string`   | Accessible name. Omit for decoration — the icon is hidden from screen readers. |
+| `class` | `string`   | Merged with the defaults rather than replacing them.                           |
+
+## Sizing and colour
+
+An icon is `1em` square and painted in `currentColor`, so by default it matches
+the text it sits beside — size, weight of colour, and all. Override with classes
+rather than attributes:
+
+```tsx
+<p class="text-sm text-slate-600">
+  <Icon name="info" /> Saved a moment ago
+</p>
+
+<Icon name="triangle-alert" class="size-8 text-amber-500" />
+```
+
+Sizing through CSS is what lets an icon line up with a label without either being
+measured. `class="size-5"` sets both dimensions; `text-red-600` on the icon — or
+on anything above it — colours it.
+
+## Labelling
+
+An icon is decoration by default and hidden from screen readers, which is right
+when it sits next to text that already says the same thing. Announcing it there
+would read the meaning out twice.
+
+An icon that is the **only** content of a control is not decoration. Without a
+label, that button has no accessible name at all:
+
+```tsx
+<button onClick={this.remove}>
+  <Icon name="trash-2" label="Delete order" />
+</button>
+```
+
+## A name that isn't known until runtime
+
+A name from a database column or a URL segment is not a literal, so it does not
+satisfy the union. `isIconName()` narrows it:
+
+```tsx
+import { Icon, isIconName } from "@zerotal/flow-ui";
+
+override async render() {
+  const glyph = this.status.icon; // string, from a row
+  return isIconName(glyph) ? <Icon name={glyph} /> : <Icon name="circle-help" />;
+}
+```
+
+It is a shape check, not an existence check — it says the string could name an
+icon, not that anything answers to it. An icon that resolves to nothing renders
+nothing rather than throwing, because taking a page down over a missing glyph is
+the worse failure.
+
+## Drawn for the gaps
+
+Four names are drawn here rather than coming from the set, because the flows they
+label are ones Zerotal ships and the set has no icon for as a concept:
+
+| Name         | For                                                            |
+| ------------ | -------------------------------------------------------------- |
+| `passkey`    | WebAuthn sign-in — a fingerprint that ends in a key            |
+| `two-factor` | TOTP — a second device that has to agree                       |
+| `otp`        | An emailed one-time code — the separate slots it is typed into |
+| `magic-link` | Passwordless sign-in by link                                   |
+
+The set has `key-round`, `fingerprint` and `shield-check` — the parts — and a login
+page needs the whole. They are drawn on the same 24×24 stroke grid, so they sit
+beside the other 2,060 without announcing themselves.
+
+Nearly everything else that looked missing was there under a name that reads
+differently: `git-branch` not `branch`, `file-json` not `json`, `paperclip` not
+`attachment`, `venetian-mask` for impersonation. Search before you draw.
+
+## Brand marks
+
+Three sign-in providers ship as brand marks, because `@zerotal/auth` has a code
+path for each and a sign-in button wants the provider's actual logo:
+
+```tsx
+<button><Icon name="brand-google" /> Continue with Google</button>
+<button><Icon name="brand-github" /> Continue with GitHub</button>
+<button><Icon name="brand-apple" /> Continue with Apple</button>
+```
+
+They come from [Simple Icons](https://simpleicons.org) (**CC0-1.0**, public
+domain), so the paths are the real ones rather than approximations — an
+approximated logo reads as a forgery, not as an icon.
+
+The `brand-` prefix is deliberate: the bundled set has its own stroke-style
+`github` and `apple`, and prefixing means neither silently shadows the other, so a
+page picks a style rather than inheriting one. There is no plain `google` — the
+set never had one, which is what made this worth doing.
+
+Unlike the rest, brand marks are **solid**: each body carries its own
+`fill="currentColor"`, so it still takes its colour from the text around it.
+
+> **CC0 covers copyright, not trademark.** The marks belong to their owners.
+> Labelling a sign-in button with one is nominative use and what brand guidelines
+> contemplate; using one as your own logo is not. For a provider not listed here,
+> `registerIcons()` keeps that decision — and its licence — yours.
+
+## Your own icons
+
+A wordmark, a product glyph, a shape nobody has drawn: register it once, from a
+provider's `register()`, and it is available everywhere `<Icon>` is.
+
+```ts
+import { registerIcons } from "@zerotal/flow-ui";
+
+registerIcons({
+  "acme-wordmark": {
+    body: '<path fill="currentColor" d="M4 4h16v16H4z"/>',
+  },
+});
+```
+
+Each entry is an `IconBody` — the markup that goes **inside** the `<svg>`, plus an
+optional `width`/`height` when it was drawn against a box other than 24×24. A name
+you register shadows a bundled one, which is how you substitute your own drawing
+without renaming every call site.
+
+Registering supplies the body; the compiler needs telling separately. Declare the
+names on `CustomIconRegistry` and they join the same union as the bundled ones —
+`IconName` widens, and `CustomIconName` is the set you added:
+
+```ts
+declare module "@zerotal/flow-ui" {
+  interface CustomIconRegistry {
+    "acme-wordmark": true;
+  }
+}
+```
+
+> **The body is inserted as markup, not text.** Register only SVG you control.
+> A body built from user input is the same hole as any other unescaped HTML.
+
+### Matching the set
+
+Icons drawn to a different grid look wrong beside ones that aren't. The bundled
+set is 24×24 **stroke**: no fills, `stroke="currentColor"`, `stroke-width="2"`,
+round caps and joins. Copy the shape of an existing icon rather than exporting
+from a design tool, which will hand you absolute fills on a half-pixel grid.
+
+## What ships, and why it can
+
+The bundled set is [Lucide](https://lucide.dev), which is ISC-licensed — the
+reason it can be shipped inside the package at all. Redistributing it carries a
+notice (`LICENSE-ICONS.md` in `@zerotal/flow-ui`) and asks nothing of your
+application's UI.
+
+Most sets are not so simple. Font Awesome Free is CC BY 4.0 — usable, and only
+with attribution _you_ would have to display — and Font Awesome Pro may not be
+redistributed at any price. Bundling either would relicense someone else's artwork
+on behalf of every app that installed Flow. If you are entitled to a set we cannot
+ship, `registerIcons()` is how you bring it: your artwork, your licence.
+
+## Cost
+
+None on the client. Flow renders on the server, so an icon reaches the browser as
+markup that is already in the page — no icon font, no sprite sheet, no request per
+glyph, and nothing for a strict [Content Security Policy](/docs/flow/performance)
+to block. The set is read once per process and never sent.

package/docs/flow/index.md

@@ -139,7 +139,7 @@ component in the project is covered — the Flow scaffold already writes this:
 > is a type error rather than a wrong render. The two JSX runtimes produce different element
 > types: a view `FC` returns `SafeHtml` (`{ value }`) and Flow's JSX expects `HtmlNode`
 > (`{ html }`), so using one inside the other is `TS2786: 'Box' cannot be used as a JSX
-> component`. A shared component library has to target one runtime; share class-name constants
+component`. A shared component library has to target one runtime; share class-name constants
 > or plain strings across the two instead of components.
 
 ### Your first component
@@ -183,22 +183,26 @@ Router.flow("/counter", CounterPage);
 ### Reserved member names
 
 `Component` brings its own members, and a property of yours that collides with one is a
-type error. It is caught at compile time and the message is specific, but the name that
-trips people is `title` — an obvious field for a row representing a media item, a guide or
-a review, and taken by the page-title accessor.
+type error. It is caught at compile time and the message is specific, so the cost is the
+surprise rather than the failure — which is why the list is here.
+
+`title` used to be on it, and was the name that caught people most: an obvious field for a
+row representing a media item, a guide or a review. The document title is
+[`static title`](#the-page-title) now, so the instance name is yours.
 
 The names in use:
 
 | Group             | Names                                                                                                                 |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
 | Lifecycle         | `onBoot` `onMount` `onHydrate` `onDehydrate` `onRendering` `onRendered` `onUpdate` `onUpdating` `onUpdated` `onError` |
-| Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child` `title`                                                      |
+| Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child`                                                              |
 | Actions & state   | `bind` `validate` `resetValidation` `errors` `addError` `refresh` `$refresh` `$set` `cancelled` `signal`              |
 | Navigation        | `redirect` `redirectRoute` `redirectIntended` `currentUrl` `navigateCurrent`                                          |
-| Events & realtime | `dispatch` `dispatchSelf` `dispatchTo` `stream` `client`                                                              |
+| Events & realtime | `dispatch` `dispatchSelf` `dispatchTo` `stream` `client` `$`                                                          |
 | Misc              | `flash` `download` `clearDurable`                                                                                     |
 
-Anything beginning with `_` is also framework-internal, as is the static `durable`.
+Anything beginning with `_` is also framework-internal, as are the statics `durable`
+and `title`.
 
 If the natural name is taken, the usual fix is a more specific one — `headline`,
 `mediaTitle` — which often reads better than `title` did.

package/docs/flow/layouts.md

@@ -149,7 +149,7 @@ Flow assembles the outer document itself and emits `<html lang="en">`, and a `La
 change it. `head` injects into `<head>`; the `<html>` attributes are not reachable from a layout.
 
 For a localised app, put `lang` (and any locale-dependent class) on the layout's own wrapper element.
-Both are valid on a `div` and apply to every descendant, so the *content* is correctly marked up —
+Both are valid on a `div` and apply to every descendant, so the _content_ is correctly marked up —
 but the document still declares English to anything reading the root element, which is wrong for a
 screen reader announcing the page in the wrong voice:
 

package/docs/flow/lifecycle.md

@@ -94,11 +94,19 @@ Avoid expensive database queries in `onBoot()` — it fires on every round-trip,
 
 Runs once on the initial `GET` render, then is skipped on all subsequent WebSocket updates. It's the primary place to load data for the page.
 
-It receives the route `HttpContext` — the same argument a controller action gets — so a page on a dynamic segment reads its [route-model binding](/docs/routing#route-model-binding) straight off `ctx.params` instead of querying for it:
+A page on a dynamic segment needs no code here for the record it is about. A field of the model's type is [filled from the segment](/docs/flow/routing#path-parameters) before `onMount()` runs, so the query, the id field, and the 404 all belong to the route:
 
 ```typescript
-override async onMount({ params: { post } }: HttpContext<{ post: Post }>) {
-  this.post = post; // resolved by the router; a missing record 404s before this runs
+export class PostPage extends Component {
+  @locked post!: Post; // /posts/:post — nothing to load
+}
+```
+
+What `onMount()` is for is everything the URL does not carry. It receives the route `HttpContext` — the same argument a controller action gets — which is where the signed-in user lives, and `ctx.params` is still there for a segment no field claimed:
+
+```typescript
+override async onMount({ user }: HttpContext) {
+  this.canEdit = user?.id === this.post.authorId;
 }
 ```
 
@@ -106,21 +114,23 @@ The context is passed to `onBoot()` too, but only the initial `GET` populates `c
 
 ```typescript
 override async onMount() {
-  const [posts, user] = await Promise.all([
+  const [posts, drafts] = await Promise.all([
     Post.query()
       .where("status", "published")
       .orderBy("created_at", "desc")
       .limit(20)
       .get(),
-    User.findOrFail(this.currentUserId),
+    Post.query().where("status", "draft").count(),
   ]);
 
-  this.posts = posts;
-  this.user  = user;
-  this.total = posts.length;
+  this.posts  = posts;
+  this.drafts = drafts;
+  this.total  = posts.length;
 }
 ```
 
+Lists and counts are what belongs here — the things no route resolved and no parent passed down.
+
 To force `onMount()` to re-run during a WebSocket action — for example after creating a new record and wanting to reload the list — call `this.refresh()` inside the action:
 
 ```typescript
@@ -139,25 +149,30 @@ Runs on every WebSocket round-trip, immediately after state is restored from the
 
 ```typescript
 export class PostEditorPage extends Component {
-  @locked postId: number = 0; // persisted in snapshot
-  @transient post: Post | null = null; // NOT persisted — reset each round-trip
+  @expose post!: Post; // /posts/:post/edit — re-read from the row every round-trip
+  @transient wordCount = 0; // NOT persisted — derived again each time
 
   override async onHydrate() {
-    // Re-load the full Post model from the database using the persisted ID:
-    if (this.postId) {
-      this.post = await Post.findOrFail(this.postId);
-    }
+    await this.post.loadMissing(["author"]); // relations do not survive the round-trip
+    this.wordCount = this.post.body.split(/\s+/).length;
   }
 
   @expose async updateTitle(title: string): Promise<void> {
-    if (!this.post) return;
     await this.post.fill({ title }).save();
     this.flash("Title updated.");
   }
 }
 ```
 
-This is the correct pattern for holding live model instances on a component: persist only the ID in `@locked`, then re-query the model in `onHydrate()`. The model is always fresh from the database, never stale from a deserialized snapshot.
+> **This used to say to hold the id and re-query the model here.** A component could not hold a
+> model then, so `@locked postId` plus a `@transient post` re-fetched in `onHydrate()` was the
+> way to keep one fresh. It is no longer needed: a model held directly is [re-read from its row
+> on every round-trip](/docs/flow/models#freshness), which is the same guarantee with none of
+> the bookkeeping. The pattern still works — it is just two fields and a query doing what one
+> field now does.
+
+What is left for `onHydrate()` is the state a snapshot genuinely cannot carry: relations, which
+are not part of a re-read, and anything derived from them.
 
 ## Intercepting client writes