@zerotal/arch 1.7.4 → 1.8.0

package/docs/flow/decorators.md

@@ -16,7 +16,7 @@ Marks a property or method as part of the public contract with the browser.
 - **On a property** — the value is included in the signed snapshot and synced to the client on every patch. The client can update it via a bound `value`/`checked` attribute or a client expression like `onClick={() => this.count++}`.
 - **On a method** — makes it callable from the browser over the WebSocket via event bindings like `onClick={this.save}`.
 
-```typescript
+```typescript fragment
 import { expose } from "@zerotal/flow";
 
 export class CounterPage extends Component {
@@ -48,7 +48,7 @@ A `value={this.x}` binding on a `@locked` property renders as a read-only displa
 
 Use `@locked` for anything the server owns: a record the route resolved, results loaded in `onMount()`, computed totals, child props from the parent:
 
-```tsx
+```tsx fragment
 export class PostsPage extends Component {
   @locked user!: User; // /users/:user — the record, already found
   @locked posts: Post[] = [];
@@ -87,7 +87,7 @@ with no arguments, and used for [real-time validation](#real-time-validation) on
 
 Combine with `@expose` for a property that is both two-way bound and validated:
 
-```typescript
+```typescript fragment
 @expose @validate((rule) => rule.required().email())              email:    string = "";
 @expose @validate((rule) => rule.required().min(8))               password: string = "";
 @expose @validate((rule) => rule.required().min(2).max(50))       name:     string = "";
@@ -102,7 +102,7 @@ Combine with `@expose` for a property that is both two-way bound and validated:
 
 The validation runs when you call `this.validate()` inside an action:
 
-```typescript
+```typescript fragment
 @expose async register(): Promise<void> {
   await this.validate(); // reads all @validate rules on the class
 
@@ -120,7 +120,7 @@ The validation runs when you call `this.validate()` inside an action:
 
 You can also pass rules directly to `this.validate()` — they override the decorator-based rules:
 
-```typescript
+```typescript fragment
 @expose async update(): Promise<void> {
   await this.validate({
     email:    (rule) => rule.required().email(),
@@ -142,7 +142,7 @@ as the user edits, with no action call and without affecting any other field.
 > form is not writable in TSX: the `.` in an attribute name is a parse error (`TS1003`), so
 > copying it out of the emitted HTML into a component will not build.
 
-```tsx
+```tsx fragment
 @expose @validate((rule) => rule.required().email()) email = "";
 
 async render() {
@@ -165,7 +165,7 @@ See [Forms & Validation](/docs/flow/forms) for the full validation rules referen
 
 Syncs a property to the browser URL query string. Initialised from the query string on the initial page load; updated in the URL on every patch. The URL becomes shareable and bookmark-friendly automatically:
 
-```typescript
+```typescript fragment
 // Page and search stay in the URL: /posts?page=2&search=TypeScript
 @url page:   number = 1;
 @url search: string = "";
@@ -189,14 +189,14 @@ Binds a property to the HTTP session, so the value survives a browser refresh. R
 
 The field reads and writes the session key of the same name — the same value a controller or another component sees:
 
-```typescript
+```typescript fragment
 @session userId: string = "";           // the session's `userId`
 @session preferredTheme: string = "light";
 ```
 
 Pass options to change the key, or to keep it to this component:
 
-```typescript
+```typescript fragment
 // Read a differently-named key
 @session({ key: "s" }) whatever: number = 0;
 
@@ -216,7 +216,7 @@ A `@session` field is **not** in the WebSocket snapshot: it is read from and wri
 
 A getter derived from other state. Not stored in the snapshot — recomputed on every render pass. The result is **memoized for the duration of a single render**, so an expensive getter read multiple times in the same template runs only once:
 
-```typescript
+```typescript fragment
 @computed get fullName(): string {
   return `${this.firstName} ${this.lastName}`;
 }
@@ -241,7 +241,7 @@ Use them freely in a template as a text child — `{this.fullName}` — where th
 
 Excludes a property from the snapshot entirely. Reset to its class-level default on every WebSocket round-trip. Use for ephemeral UI state that shouldn't persist between server calls:
 
-```typescript
+```typescript fragment
 @transient isUploading:   boolean = false;
 @transient dropzoneActive: boolean = false;
 @transient tempMessage:    string  = "";
@@ -254,7 +254,7 @@ The pattern: start an upload, set `this.isUploading = true`, send a response. On
 
 An `@expose`d method that runs on the server but **skips the re-render cycle**. Use for side-effects that don't change the UI: file downloads, external API calls, jobs that just need to fire:
 
-```typescript
+```typescript fragment
 @expose @renderless async exportCsv(): Promise<void> {
   const rows = await Report.all();
   const csv  = rows.map((r) => `${r.id},${r.name},${r.email}`).join("\n");
@@ -282,7 +282,7 @@ Because the render cycle is skipped, `@renderless` actions are faster and cheape
 
 Registers a method as a listener for cross-component events dispatched via `this.dispatch()`. The method is implicitly exposed — no separate `@expose` needed:
 
-```typescript
+```typescript fragment
 @on("post-created")
 async handlePostCreated(data: { id: number; title: string }): Promise<void> {
   this.posts = await Post.query().orderBy("created_at", "desc").limit(10).get();
@@ -319,7 +319,7 @@ For child components — marks a prop the parent can re-push whenever its value
 
 Declare the reactive prop on the child:
 
-```tsx
+```tsx fragment
 export class PriceTag extends Component {
   @reactive currency = "USD";
   @reactive amount = 0;
@@ -339,7 +339,7 @@ export class PriceTag extends Component {
 
 Pass the prop from the parent:
 
-```tsx
+```tsx fragment
 // When this.currency changes, PriceTag re-renders automatically:
 <PriceTag currency={this.currency} amount={this.subtotal} />
 ```
@@ -350,7 +350,7 @@ Unlike `@locked`, `@reactive` props are **live** — the parent keeps them curre
 
 A reactive prop that **also syncs back to the parent** (two-way). The parent property and the child prop stay in lock-step. Use for reusable input/control components that need to write a value back to their parent:
 
-```tsx
+```tsx fragment
 export class StarRating extends Component {
   @modelable rating: number = 0; // two-way bound to parent
 
@@ -409,7 +409,7 @@ See [Layouts & Composition](/docs/flow/layouts#two-way-props) for the full `@mod
 
 These helpers are available inside any `@expose`d method:
 
-```typescript
+```typescript fragment
 // Flash a toast notification to the browser
 this.flash("Saved successfully!"); // level defaults to "success"
 this.flash("Could not connect.", "error");
@@ -442,7 +442,7 @@ this.download("export.json", JSON.stringify(data, null, 2), "application/json");
 
 `this.errors` is a typed proxy over the validation error bag. It is populated by `this.validate()` and `this.addError()`.
 
-```tsx
+```tsx fragment
 // Check if any validation errors exist
 if (this.errors.any()) {
   return; // stop processing

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

@@ -8,7 +8,7 @@ description: 2,060 icons bundled with Flow's component library — typed by name
 `<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
+```tsx fragment
 import { Icon } from "@zerotal/flow-ui";
 
 <Icon name="inbox" />
@@ -42,7 +42,7 @@ 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
+```tsx fragment
 <p class="text-sm text-slate-600">
   <Icon name="info" /> Saved a moment ago
 </p>
@@ -63,7 +63,7 @@ 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
+```tsx fragment
 <button onClick={this.remove}>
   <Icon name="trash-2" label="Delete order" />
 </button>
@@ -74,7 +74,7 @@ label, that button has no accessible name at all:
 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
+```tsx fragment
 import { Icon, isIconName } from "@zerotal/flow-ui";
 
 override async render() {
@@ -113,7 +113,7 @@ differently: `git-branch` not `branch`, `file-json` not `json`, `paperclip` not
 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
+```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>

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";
@@ -195,7 +195,7 @@ The names in use:
 | Group             | Names                                                                                                                 |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
 | Lifecycle         | `onBoot` `onMount` `onHydrate` `onDehydrate` `onRendering` `onRendered` `onUpdate` `onUpdating` `onUpdated` `onError` |
-| Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child`                                                              |
+| Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child` `isInteractive`                                              |
 | 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` `$`                                                          |
@@ -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.