@zerotal/arch 1.7.3 → 1.7.5

package/docs/flow/events.md

@@ -11,7 +11,7 @@ Flow components communicate by dispatching named events. Listeners registered wi
 
 Call `this.dispatch()` inside any `@expose`d action. The event is delivered to all matching `@on` listeners on the page after the action completes:
 
-```typescript
+```typescript fragment
 @expose async save(): Promise<void> {
   const post = await Post.create({
     title:  this.title,
@@ -27,7 +27,7 @@ Call `this.dispatch()` inside any `@expose`d action. The event is delivered to a
 
 The second argument is the payload — any JSON-serialisable value. Omit it for events that carry no data:
 
-```typescript
+```typescript fragment
 this.dispatch("cart-cleared");
 ```
 
@@ -35,7 +35,7 @@ this.dispatch("cart-cleared");
 
 By default, `dispatch()` notifies every `@on` listener on the page. Use `dispatchTo` or `dispatchSelf` to narrow the target:
 
-```typescript
+```typescript fragment
 // Default: all @on("post-created") listeners on the page
 this.dispatch("post-created", { id });
 
@@ -52,7 +52,7 @@ this.dispatchSelf("refresh");
 
 Register a method as an event listener with `@on`. The method is **implicitly exposed** — no `@expose` needed:
 
-```typescript
+```typescript fragment
 import { on } from "@zerotal/flow";
 
 export class PostList extends Component {
@@ -95,7 +95,7 @@ A component can have as many `@on` listeners as it needs. Each fires independent
 
 Several components on the same page can all listen for the same event. Each component is updated independently — Flow sends a separate patch frame to each listener:
 
-```typescript
+```typescript fragment
 // PostList.tsx
 @on("post-created")
 async onPostCreated(data: { id: number }) {
@@ -121,7 +121,7 @@ All three components update after a single `this.dispatch("post-created", ...)`
 
 The same `dispatch`, `dispatchTo`, and `dispatchSelf` methods work inside **client expressions** — no server round-trip needed to start the dispatch. The `@on` listeners still run server-side when they're notified:
 
-```tsx
+```tsx fragment
 {
   /* Notify all listeners without a preceding server action */
 }
@@ -158,7 +158,7 @@ declare module "@zerotal/flow" {
 
 Every `dispatch` / `dispatchTo` / `dispatchSelf` site is now checked against it — in server actions **and** client expressions, since they call the same typed method:
 
-```ts
+```ts fragment
 this.dispatch("post-created", { id: post.id, title: post.title }); // ✓
 this.dispatch("post-created", { id: post.id }); // ✗ missing `title`
 this.dispatch("post-created"); // ✗ payload required
@@ -168,7 +168,7 @@ this.dispatch("cart-cleared", { anything: 1 }); // ✗ void takes no payload
 
 On the listener side, `@on` autocompletes to the known event names, and you annotate the handler's parameter with `EventPayload<K>` to type the payload against the same contract:
 
-```ts
+```ts fragment
 import { on } from "@zerotal/flow";
 import type { EventPayload } from "@zerotal/flow";
 
@@ -235,7 +235,7 @@ Listen for server-broadcast events over WebSockets with `@on("socket:…")`. Whe
 
 The socket client is bundled into the Flow runtime and created the first time a page declares one of these listeners, so there is no script to add and nothing to publish on `window`. An app that needs a configured client — a different host, its own auth endpoint — assigns `window.Socket` before the runtime loads and that one is used instead. Pages with no such listener open no broadcast connection at all.
 
-```typescript
+```typescript fragment
 export class OrderDashboard extends Component {
   @locked orderCount: number = 0;
   @locked recentOrders: Order[] = [];
@@ -299,7 +299,7 @@ Pass a resolver instead. It is called with the component when the snapshot is bu
 [`@presence`](#presence--whos-here-multiplayer) and [`@shared`](#shared-state--everyone-converges-multiplayer)
 resolve theirs:
 
-```typescript
+```typescript fragment
 export class IssuePage extends Component {
   @locked issue!: Issue;
   @locked comments: Comment[] = [];
@@ -326,7 +326,7 @@ Broadcasting requires a global `window.Socket` client configured by your applica
 
 If `window.Socket` is not present, all `socket:` listeners are silently inert — no errors, no subscriptions attempted.
 
-```typescript
+```typescript fragment
 // In your frontend bootstrap (app.ts or similar):
 import { Socket } from "@zerotal/client";
 
@@ -339,7 +339,7 @@ window.Socket = new Socket();
 
 `@presence` binds a property to a broadcast **presence channel** and keeps it filled with the live member list — the framework joins the channel, seeds the list, and refreshes it as people join and leave. No event classes, no manual `@on` wiring:
 
-```tsx
+```tsx fragment
 import { Component, presence } from "@zerotal/flow";
 import type { PresenceMember } from "@zerotal/flow";
 
@@ -362,7 +362,7 @@ export class Board extends Component {
 
 The channel is resolved on the server from the component (so it can't be forged from the client) and carried, signed, in the snapshot. `who` is server-controlled (like `@locked`): it lives in the snapshot and the client can't write it. Authorize the channel — and shape the member data — in `routes/channels.ts`:
 
-```ts
+```ts fragment
 Broadcast.channel("board.[boardId]", (user, boardId) =>
   user.canView(boardId) ? { id: user.id, name: user.name } : null,
 );
@@ -385,7 +385,7 @@ Like all `socket:` features, presence needs a `window.Socket` client configured
 
 Where `@presence` answers _who's here_, `@shared` answers _what do we all see_. It binds a property to convergent, **server-authoritative** state on a channel: mutate it in an action and the framework writes it to a per-channel **room store** and broadcasts to the channel, so every other subscriber re-reads and converges. No store to wire, no events, no dispatch:
 
-```tsx
+```tsx fragment
 import { Component, presence, shared, expose } from "@zerotal/flow";
 
 export class Board extends Component {
@@ -416,7 +416,7 @@ Broadcasting is an **optional peer**. With `window.Socket` and `BroadcastProvide
 
 Calling `this.refresh()` inside an action inserts `onMount()` back into the WebSocket round-trip cycle:
 
-```typescript
+```typescript fragment
 @expose async syncOrders(): Promise<void> {
   await OrderSync.run();
   this.refresh(); // onMount() re-runs → this.orders is freshly loaded
@@ -434,7 +434,7 @@ Calling `this.refresh()` inside an action inserts `onMount()` back into the WebS
 
 In the browser, `this.refresh()` sends a lightweight re-render request with no data change — useful for polling or a manual reload button:
 
-```tsx
+```tsx fragment
 {
   /* Manual reload button */
 }

package/docs/flow/forms.md

@@ -11,7 +11,7 @@ Validate input, bind form fields to component state with two-way binding, encaps
 
 Attach rules with `@validate` on individual fields, or pass them explicitly to `this.validate()`:
 
-```typescript
+```typescript fragment
 import { expose, validate } from "@zerotal/flow";
 
 @expose @validate((rule) => rule.required().email())              email:    string = "";
@@ -29,7 +29,7 @@ builder (`rule.number()`, …). The same `@validate` rule also powers
 
 Call `this.validate()` at the start of your action. It reads the `@validate` rules and throws a `ValidationError` if any fail — Flow catches it, populates `this.errors`, and re-renders:
 
-```typescript
+```typescript fragment
 @expose async register(): Promise<void> {
   await this.validate(); // uses @validate rules declared on the class
 
@@ -46,7 +46,7 @@ Call `this.validate()` at the start of your action. It reads the `@validate` rul
 
 Pass explicit rules to override or extend `@validate`:
 
-```typescript
+```typescript fragment
 @expose async update(): Promise<void> {
   await this.validate({
     email:    (rule) => rule.required().email(),
@@ -83,7 +83,7 @@ Pass explicit rules to override or extend `@validate`:
 
 Pass a field off `this.errors` to the `error` prop. It renders the first message for that field and hides itself when the field is valid — no manual show/hide logic:
 
-```tsx
+```tsx fragment
 <input value={this.email} />
 <span error={this.errors.email} class="text-sm text-red-500" />
 
@@ -93,7 +93,7 @@ Pass a field off `this.errors` to the `error` prop. It renders the first message
 
 Use the `<Field>` component for accessible label + error wiring:
 
-```tsx
+```tsx fragment
 import { Field } from "@zerotal/flow";
 
 <Field label="Email" error={this.errors.email}>
@@ -107,7 +107,7 @@ import { Field } from "@zerotal/flow";
 
 Show all errors at once with `<Errors>`:
 
-```tsx
+```tsx fragment
 import { Errors } from "@zerotal/flow";
 
 <Errors />                          {/* all current errors */}
@@ -116,7 +116,7 @@ import { Errors } from "@zerotal/flow";
 
 ### Checking errors in server code
 
-```typescript
+```typescript fragment
 // Check if any errors exist
 if (this.errors.any()) {
   return;
@@ -131,7 +131,7 @@ if (this.errors.has("email")) {
 
 ### Manual errors
 
-```typescript
+```typescript fragment
 this.addError("email", "That email address is already taken.");
 this.addError("username", "Username must be unique.");
 
@@ -143,7 +143,7 @@ this.resetValidation("email"); // clear one field
 
 Pass state to `value` (or `checked`). Flow makes it two-way for `@expose` properties and read-only for `@locked` ones — no helper needed:
 
-```tsx
+```tsx fragment
 {/* Text inputs */}
 <input value={this.name} />
 <input value={this.email} />
@@ -194,7 +194,7 @@ export class LoginForm extends Form {
 
 Mount the form on a component:
 
-```typescript
+```typescript fragment
 export class LoginPage extends Component {
   @expose form = new LoginForm();
 
@@ -219,7 +219,7 @@ export class LoginPage extends Component {
 
 Bind fields with nested `value={this.form.email}`:
 
-```tsx
+```tsx fragment
 <form onSubmit={this.login} class="space-y-4">
   <Field label="Email" error={this.errors.email}>
     <input value={this.form.email} type="email" live class="input" />
@@ -242,7 +242,7 @@ Bind fields with nested `value={this.form.email}`:
 
 ### Form helpers
 
-```typescript
+```typescript fragment
 // Get all field values as a plain object
 const data = this.form.data();
 // { email: "alice@example.com", password: "…", remember: true }
@@ -273,7 +273,7 @@ See [Pagination](/docs/flow/pagination) for the full guide — `paginate()`, `Pa
 
 Quick reference for in-memory pagination:
 
-```typescript
+```typescript fragment
 import { paginate } from "@zerotal/flow";
 
 export class PostsPage extends Component {
@@ -342,7 +342,7 @@ export class PostsPage extends Component {
 
 Compose `Pagination` to get the page state and navigation methods automatically — no boilerplate:
 
-```tsx
+```tsx fragment
 import { Component, Pagination } from "@zerotal/flow";
 
 export class PostsPage extends Component.using(Pagination) {
@@ -404,7 +404,7 @@ export class PostsPage extends Component.using(Pagination) {
 
 Reset the page when a filter changes to avoid showing an empty page:
 
-```typescript
+```typescript fragment
 @expose async applyFilter(status: string): Promise<void> {
   this.filter = status;
   this.resetPage(); // go back to page 1
@@ -413,7 +413,7 @@ Reset the page when a filter changes to avoid showing an empty page:
 
 Compose with other mixins:
 
-```typescript
+```typescript fragment
 // `Sorting` here is a mixin you author yourself (see Layouts & Composition);
 // `Pagination` is the one shipped by Flow.
 export class PostsPage extends Component.using(Sorting, Pagination) {
@@ -425,7 +425,7 @@ export class PostsPage extends Component.using(Sorting, Pagination) {
 
 For database queries, skip the in-memory `paginate()` and use the ORM query builder directly. Combine with `@url page`:
 
-```typescript
+```typescript fragment
 export class PostsPage extends Component {
   @url page = 1;
   @locked posts: Post[] = [];

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 fragment
+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 fragment
+<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 fragment
+<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 fragment
+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 fragment
+<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

@@ -93,7 +93,7 @@ middleware is a `_middleware.ts` in the page tree. It stacks from the root down,
 covers every page beneath it, and — being route middleware — re-runs on every
 action with nothing else to configure:
 
-```typescript
+```typescript fragment
 // app/flow/pages/_middleware.ts
 import { TenantMiddleware } from "../../middleware/TenantMiddleware.ts";
 
@@ -107,7 +107,7 @@ guards the pages inside it without changing their URLs. See
 Reach for `persistentMiddleware` only when the middleware is genuinely **global** —
 registered app-wide with `Application.use()` because non-Flow routes need it too:
 
-```typescript
+```typescript fragment
 // app/providers/AppServiceProvider.ts — inside onRegister():
 FlowProvider.persistMiddleware(TenantMiddleware);
 ```
@@ -172,7 +172,7 @@ The distinction is the syntax: a named method reference is always a server actio
 
 Register the route:
 
-```typescript
+```typescript fragment
 // routes/web.ts
 import { Router } from "zerotal";
 import { CounterPage } from "./components/CounterPage.tsx";
@@ -239,7 +239,7 @@ State that the server should never see — a hover flag, which accordion section
 
 A list with per-row actions needs to tell the server _which_ row. Write the call as you would expect, and Flow compiles the arguments into the markup:
 
-```tsx
+```tsx fragment
 {
   this.enquiries.map((row) => (
     <tr>
@@ -254,7 +254,7 @@ A list with per-row actions needs to tell the server _which_ row. Write the call
 
 The arguments are evaluated **on the server, during the render** — where `row` exists — and travel with the action as `data-args`. Your action receives them as ordinary parameters:
 
-```ts
+```ts fragment
 @expose async archive(id: number) {
   await Enquiry.findOrFail(id).archive();
 }
@@ -262,7 +262,7 @@ The arguments are evaluated **on the server, during the render** — where `row`
 
 You can also write `data-args` yourself, which is useful when the handler is built dynamically:
 
-```tsx
+```tsx fragment
 <button onClick={this.archive} data-args={JSON.stringify([row.id])}>
   Archive
 </button>
@@ -280,7 +280,7 @@ By contrast, a handler pointing at a method you forgot to `@expose` **is** a har
 
 Bind an input by passing state straight to `value` (or `checked`). Flow wires up two-way binding when the property is `@expose`, and read-only reflection when it's `@locked`:
 
-```tsx
+```tsx fragment
 <input value={this.name} />                          {/* @expose → two-way    */}
 <input type="checkbox" checked={this.agree} />        {/* @expose → two-way    */}
 <input value={this.ownerName} />                      {/* @locked → read-only  */}
@@ -288,7 +288,7 @@ Bind an input by passing state straight to `value` (or `checked`). Flow wires up
 
 A **radio group** is bound as a unit rather than per input, because every option writes the same property. Pass the option's own value as a second argument to `bind()`:
 
-```tsx
+```tsx fragment
 {
   ["CUSTOM", "ROUTE", "TEAMS"].map((t) => (
     <label>
@@ -302,7 +302,7 @@ Each option renders with the shared `flow:model="type"`, its own `value`, and `c
 
 By default the value stays **local** — it updates the DOM instantly and is flushed to the server with your next action. Add `live` to sync to the server as you type, or `blur` to sync when the input loses focus:
 
-```tsx
+```tsx fragment
 <input value={this.draft} />            {/* local; flushed with the next action */}
 <input value={this.search} live />      {/* syncs to the server as you type      */}
 <input value={this.title}  blur />      {/* syncs to the server on blur          */}
@@ -312,20 +312,20 @@ By default the value stays **local** — it updates the DOM instantly and is flu
 
 Two more modifiers clean the value at the edge, so the server never sees a numeric string or stray whitespace and you write no coercion in `onUpdated`:
 
-```tsx
+```tsx fragment
 <input type="number" value={this.age} number />   {/* the bound value is a real number, not "42" */}
 <input value={this.name} trim />                   {/* whitespace stripped before it syncs */}
 ```
 
 Add `draft="key"` to keep an unsubmitted value across a reload or crash — it mirrors to `localStorage` and restores on mount (only when the field is empty, so server content always wins), then clears itself once the server empties the field after a successful submit. It's a client-side safety net; the server snapshot stays the authority:
 
-```tsx
+```tsx fragment
 <textarea value={this.body} draft="post-body" />   {/* survives a refresh until you submit */}
 ```
 
 And two focus helpers close the loop after a re-render, where focus is easily lost:
 
-```tsx
+```tsx fragment
 <input value={this.email} autoFocus />      {/* focus on mount (won't steal focus you've placed) */}
 <input value={this.email} focusOnError />   {/* after a failed submit, focus jumps to the first invalid field */}
 ```
@@ -336,7 +336,7 @@ And two focus helpers close the loop after a re-render, where focus is easily lo
 
 Pass a field off `this.errors` to the `error` prop and Flow renders that field's first validation message reactively — it appears when the field is invalid and clears when it's fixed:
 
-```tsx
+```tsx fragment
 <input value={this.email} />
 <span error={this.errors.email} class="text-red-500" />
 ```
@@ -347,7 +347,7 @@ No `errors.has(...)` checks, no manual show/hide.
 
 A `className`/`class` (or `style`, `href`, …) that depends on `@expose` or `@locked` state compiles to a reactive client binding, so it updates without a round-trip:
 
-```tsx
+```tsx fragment
 <span className={this.count > 10 ? "text-emerald-400" : "text-white"}>
   {this.count}
 </span>
@@ -361,7 +361,7 @@ A `className`/`class` (or `style`, `href`, …) that depends on `@expose` or `@l
 
 Use normal TypeScript control flow in `render()` — `.map()`, ternaries, and `&&` are all supported:
 
-```tsx
+```tsx fragment
 override async render() {
   return (
     <div>
@@ -389,7 +389,7 @@ Always provide a `key` when mapping over items — the morph algorithm uses it t
 
 Common interaction states are first-class props:
 
-```tsx
+```tsx fragment
 {/* Disable the button while the action is in flight */}
 <button onClick={this.save} loadingAttr="disabled">Save</button>
 
@@ -420,7 +420,7 @@ Common interaction states are first-class props:
 
 Add `transition` to animate the show/hide instead of an instant flip — a single prop covers **both** enter and leave (the leave half plain `show=` can't do, since the element would otherwise vanish before any animation runs):
 
-```tsx
+```tsx fragment
 <div show={this.modal} transition class="modal">…</div>                {/* default: fade */}
 <div show={this.menu}  transition="scale">…</div>                     {/* preset */}
 <aside show={this.drawer} transition="slide-right">…</aside>          {/* directional */}
@@ -446,7 +446,7 @@ The `flow:*` directives (`flow:click`, `flow:model`, `flow:show`, …) that the
 
 A handful of client-only helpers — writing a prop and syncing it, toggling a boolean, calling a parent action, optimistic list mutations — don't belong to any one component and never run on the server. Rather than crowd the component class (and reserve common names like `set`, `on`, `watch`, `parent` that you might want for your own methods), they all live on a single global object, `$flow`. Framework helpers wear a `$`; the bare names stay yours.
 
-```tsx
+```tsx fragment
 <button onClick={() => $flow.set("open", true)}>Open</button>     {/* write + sync an @expose prop */}
 <button onClick={() => $flow.toggle("open")}>Toggle</button>
 <button onClick={() => $flow.parent.save()}>Save</button>          {/* call a parent action */}
@@ -508,7 +508,7 @@ A page that _reads_ `$flow.store` in a binding must be AOT-compilable — the co
 
 ### Full page example
 
-```tsx
+```tsx fragment
 import { Component, expose, locked, validate, url } from "@zerotal/flow";
 import type { Post } from "#app/models/Post.ts";
 
@@ -576,4 +576,4 @@ Flow is a large surface. Each section below is its own page.
 - [Session](/docs/session) — the store behind `@session` and `SessionMiddleware`.
 - [Broadcasting](/docs/broadcasting) — drive `@on("socket:…")` real-time updates from the server.
 - [Storage](/docs/storage) — configure the disks that file uploads write to.
-- [Testing](/docs/testing/index) — patterns for the `FlowTest` harness and the rest of the suite.
+- [Testing](/docs/testing) — patterns for the `FlowTest` harness and the rest of the suite.