npm - @zerotal/arch - Versions diffs - 1.7.3 → 1.7.5 - Mend

@zerotal/arch 1.7.3 → 1.7.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (127) hide show

package/CHANGELOG.md +34 -2
package/README.md +4 -2
package/api-surface.md +4 -4
package/docs/about.md +16 -16
package/docs/admin/actions.md +9 -9
package/docs/admin/auth.md +2 -2
package/docs/admin/dashboard.md +5 -5
package/docs/admin/extending-ui.md +12 -12
package/docs/admin/extending.md +16 -7
package/docs/admin/forms.md +4 -4
package/docs/admin/index.md +2 -2
package/docs/admin/operations.md +9 -9
package/docs/admin/resources.md +3 -3
package/docs/admin/structure.md +6 -6
package/docs/admin/tables.md +8 -8
package/docs/admin/testing.md +4 -4
package/docs/ai.md +118 -11
package/docs/application.md +12 -12
package/docs/arch.md +25 -3
package/docs/assets.md +11 -11
package/docs/audit.md +13 -13
package/docs/authentication.md +39 -39
package/docs/authorization.md +13 -13
package/docs/broadcasting/channels.md +2 -2
package/docs/broadcasting/client.md +2 -2
package/docs/broadcasting/events.md +9 -10
package/docs/broadcasting/index.md +1 -1
package/docs/broadcasting/testing.md +5 -5
package/docs/cache.md +15 -13
package/docs/carbon.md +35 -35
package/docs/changelog.md +165 -1
package/docs/client/index.md +277 -70
package/docs/commands.md +4 -4
package/docs/components.md +116 -115
package/docs/config-system.md +4 -4
package/docs/container.md +27 -27
package/docs/context.md +27 -27
package/docs/contributing.md +46 -0
package/docs/controllers.md +10 -10
package/docs/conventions.md +23 -15
package/docs/cookies.md +3 -3
package/docs/csrf.md +6 -6
package/docs/database.md +22 -17
package/docs/deployment.md +2 -2
package/docs/devtools.md +16 -16
package/docs/email-verification.md +8 -8
package/docs/encryption.md +7 -7
package/docs/errors.md +6 -6
package/docs/events.md +12 -11
package/docs/flow/components.md +32 -32
package/docs/flow/decorators.md +18 -18
package/docs/flow/events.md +16 -16
package/docs/flow/forms.md +17 -17
package/docs/flow/icons.md +199 -0
package/docs/flow/index.md +20 -20
package/docs/flow/layouts.md +35 -35
package/docs/flow/lifecycle.md +16 -16
package/docs/flow/models.md +9 -9
package/docs/flow/pagination.md +8 -8
package/docs/flow/performance.md +7 -7
package/docs/flow/references.md +3 -3
package/docs/flow/routing.md +26 -26
package/docs/flow/testing.md +20 -20
package/docs/getting-started.md +18 -13
package/docs/health.md +17 -8
package/docs/helpers.md +17 -17
package/docs/i18n.md +10 -10
package/docs/inertia/devtools.md +4 -4
package/docs/inertia/index.md +12 -7
package/docs/inertia/props.md +22 -22
package/docs/inertia/rendering.md +86 -7
package/docs/inertia/ssr.md +2 -2
package/docs/lifecycle.md +2 -2
package/docs/lock.md +11 -11
package/docs/logger.md +12 -12
package/docs/media.md +22 -22
package/docs/middleware.md +17 -17
package/docs/migrations.md +13 -13
package/docs/monitor.md +6 -6
package/docs/notifications.md +24 -24
package/docs/orm/casts.md +14 -14
package/docs/orm/factories.md +8 -8
package/docs/orm/index.md +22 -20
package/docs/orm/lifecycle.md +13 -13
package/docs/orm/queries.md +28 -28
package/docs/orm/relationships.md +16 -16
package/docs/orm/serialization.md +11 -11
package/docs/package-development.md +10 -10
package/docs/pagination.md +14 -14
package/docs/password-reset.md +6 -6
package/docs/providers.md +11 -11
package/docs/query-builder.md +18 -18
package/docs/queue.md +14 -12
package/docs/rate-limiting.md +6 -6
package/docs/responses.md +14 -14
package/docs/roles-and-2fa.md +9 -9
package/docs/routing.md +44 -44
package/docs/scaffolding.md +1 -1
package/docs/scheduler.md +10 -10
package/docs/seeding.md +6 -6
package/docs/session.md +16 -14
package/docs/social.md +14 -14
package/docs/storage.md +25 -13
package/docs/structure.md +2 -2
package/docs/support-policy.md +36 -8
package/docs/telemetry.md +12 -12
package/docs/tenancy.md +34 -40
package/docs/testing/browser.md +6 -6
package/docs/testing/console.md +3 -3
package/docs/testing/database.md +10 -10
package/docs/testing/flow-browser.md +6 -6
package/docs/testing/http.md +12 -12
package/docs/testing/index.md +3 -3
package/docs/testing/mocking.md +8 -8
package/docs/upgrade.md +1 -1
package/docs/validator.md +19 -19
package/docs/view.md +14 -14
package/package.json +4 -4
package/src/index.ts +25 -1
package/src/tools/searchDocs.ts +7 -0
package/docs/client/auth.md +0 -113
package/docs/client/errors.md +0 -139
package/docs/client/files.md +0 -118
package/docs/client/references.md +0 -58
package/docs/client/requests.md +0 -131
package/docs/client/resilience.md +0 -141
package/docs/client/testing.md +0 -146

package/docs/flow/layouts.md CHANGED Viewed

@@ -49,7 +49,7 @@ export class AppLayout extends Layout {
 Attach the layout to a page:
-```tsx
+```tsx fragment
 export class DashboardPage extends Component {
   static layout = AppLayout;
@@ -69,7 +69,7 @@ The layout's `render(slot)` receives the page's HTML as `slot`. Multiple pages c
 `static layout = SomeLayout` is the class form. The JSX-native alternative — and the same convention the framework's React/Inertia pages use — is to override the `layout(page)` method and wrap the rendered page in **any JSX** you like. There is no separate `Layout` base class and no named-slot mechanism: a layout is just a component you wrap the page in, and its regions are ordinary **props**.
-```tsx
+```tsx fragment
 import { Component } from "@zerotal/flow";
 import type { HtmlNode } from "@zerotal/flow";
 import { AppLayout } from "#app/layouts/AppLayout.tsx";
@@ -102,7 +102,7 @@ export class DashboardPage extends Component {
 `AppLayout` is an ordinary function component — nothing framework-specific:
-```tsx
+```tsx fragment
 export function AppLayout(props: { title?: string; actions?: HtmlNode; children?: unknown }) {
   return (
     <div data-flow-layout="app" class="min-h-screen bg-gray-50">
@@ -127,7 +127,7 @@ Two things to know:
 `static head` injects content into the `<head>` element on the initial render. For per-page head content (title, meta), use `<Head>` inside the page's `render()` — it's hoisted into `<head>` on load and on every `navigate` visit:
-```tsx
+```tsx fragment
 import { Head } from "@zerotal/flow";
 override async render() {
@@ -153,7 +153,7 @@ Both are valid on a `div` and apply to every descendant, so the _content_ is cor
 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:
-```tsx
+```tsx fragment
 override render(slot: HtmlNode) {
   return <div lang={activeLocale()}>{slot}</div>;
 }
@@ -176,7 +176,7 @@ import { SectionOutlet } from "@zerotal/flow";
 </header>;
 ```
-```tsx
+```tsx fragment
 // In any page — fill it
 import { SectionContent } from "@zerotal/flow";
@@ -188,7 +188,7 @@ import { SectionContent } from "@zerotal/flow";
 `<SectionContent>` renders nothing where it appears. Children of `<SectionOutlet>` are the default,
 used when no page published anything:
-```tsx
+```tsx fragment
 <SectionOutlet name="toolbar">
   <span class="text-sm text-gray-500">No actions</span>
 </SectionOutlet>
@@ -259,7 +259,7 @@ export function Sorting<T extends Constructor<Component>>(Base: T) {
 }
 ```
-```tsx
+```tsx fragment
 export class UsersPage extends Component.using(Sorting, Pagination) {}
 ```
@@ -269,7 +269,7 @@ export class UsersPage extends Component.using(Sorting, Pagination) {}
 an app-level base carry its own state and actions and still take mixins, without being flattened
 out of the prototype chain:
-```tsx
+```tsx fragment
 abstract class AdminPage extends Component {
   @expose breadcrumb = "admin";
@@ -297,7 +297,7 @@ live on it.
 The composed class carries `using` itself, so composition can be built up in stages — useful when
 a shared base is defined in one file and extended in another:
-```tsx
+```tsx fragment
 const AdminBase = Component.using(Pagination).using(Sorting);
 export class ReportsPage extends AdminBase.using(FileUploads) {}
 ```
@@ -311,7 +311,7 @@ export class ReportsPage extends AdminBase.using(FileUploads) {}
 Embed other `Component` subclasses as child components. Each child has its own isolated state, its own snapshot, and its own WebSocket update cycle. A parent re-render does not re-render existing children — their DOM and state are preserved (island architecture).
-```tsx
+```tsx fragment
 import { StatsWidget } from "./StatsWidget.tsx";
 import { ActivityFeed } from "./ActivityFeed.tsx";
@@ -340,7 +340,7 @@ export class DashboardPage extends Component {
 Each prop the parent passes is assigned onto the same-named field before any lifecycle hook runs — the field's initialiser is the default:
-```tsx
+```tsx fragment
 export class CounterWidget extends Component {
   @locked step: number = 1;
   @locked label: string = "Count";
@@ -369,7 +369,7 @@ Props that need to survive WebSocket round-trips must be `@locked` so they are i
 Where props pass **data** into a child, slots pass **markup**. A child component's plain children become its **default slot**; a `slots={{ … }}` prop supplies **named slots**. Inside the child, place each with `this.slot(name)` (or `this.slot()` for the default), and branch on `this.hasSlot(name)` to drop an optional wrapper entirely. This is the pattern for reusable shells — cards, modals, panels, page headers — where the container is fixed but the contents vary per use.
-```tsx
+```tsx fragment
 // The reusable shell — header and footer are optional.
 export class Card extends Component {
   override async render() {
@@ -415,7 +415,7 @@ Two consequences worth knowing:
 Give every child rendered inside a `.map()` a `key` tied to the row's own identity:
-```tsx
+```tsx fragment
 {
   this.settings.map((s) => <SettingRow key={`setting-${s.id}`} settingKey={s.key} />);
 }
@@ -433,7 +433,7 @@ Keys are sanitised to `[a-zA-Z0-9_-]`, so dots are stripped and `a.b` collides w
 ### Lazy, deferred, and streamed loading
-```tsx
+```tsx fragment
 // Defer mount until the placeholder enters the viewport (intersection observer)
 <HeavyChart key="chart" lazy />
@@ -454,7 +454,7 @@ works before and without Alpine). See [Streaming the initial render](#streaming-
 Override `placeholder()` to customise the skeleton shown while a lazy component loads:
-```tsx
+```tsx fragment
 export class HeavyChart extends Component {
   override placeholder() {
     return <div class="h-64 w-full rounded-xl bg-gray-200 animate-pulse" />;
@@ -472,7 +472,7 @@ export class HeavyChart extends Component {
 A `@locked` prop is frozen after mount. Mark a prop `@reactive` instead and the parent re-pushes its value whenever it changes, re-rendering the child — while the child keeps the rest of its own state intact:
-```tsx
+```tsx fragment
 export class PriceTag extends Component {
   @reactive currency = "USD";
   @reactive amount = 0;
@@ -497,7 +497,7 @@ export class PriceTag extends Component {
 `@modelable` is a reactive prop that also syncs **back** to the parent. The parent property and the child prop stay in lock-step, so you can build reusable input/control components:
-```tsx
+```tsx fragment
 export class StarRating extends Component {
   @modelable rating: number = 0; // two-way bound to parent
@@ -537,7 +537,7 @@ finishes. They solve different problems and do not interact.
 Mark a child `stream` and the page paints immediately with that child's placeholder; its real markup
 is appended to the same response as soon as it finishes rendering:
-```tsx
+```tsx fragment
 override async render() {
   return (
     <div>
@@ -569,13 +569,13 @@ so `stream` degrades to an ordinary inline child render.
 Push content to the client mid-action — before the final patch — using `this.stream()`. Useful for LLM token streaming, long-running progress updates, or any content that takes time:
-```tsx
+```tsx fragment
 {/* In the template: declare the stream target */}
 <div stream="answer" class="prose" />
 <div stream="status" class="text-sm text-gray-500" />
 ```
-```typescript
+```typescript fragment
 @expose async generate(): Promise<void> {
   this.stream("status", "Generating…");
@@ -596,7 +596,7 @@ this.stream("output", freshContent, { replace: true });
 `this.stream()` is the low-level primitive: it pushes raw HTML into a `flow:stream` target, but that content isn't part of the snapshot, so you must _also_ write the accumulated result to a field for the final render, and there's no built-in cancellation. `@task` handles both. Mark an async method `@task` and just **write the field** — the framework streams it:
-```tsx
+```tsx fragment
 import { Component, task, expose } from "@zerotal/flow";
 export class Chat extends Component {
@@ -612,7 +612,7 @@ export class Chat extends Component {
 }
 ```
-```tsx
+```tsx fragment
 {/* Bind the streamed field REACTIVELY (text={…} → flow:text, or x-text) so each write updates
     this element live off the client store — no flow:stream element, no re-render per chunk. */}
 <button onClick={this.generate} loadingAttr="disabled">Generate</button>
@@ -632,7 +632,7 @@ This is the primitive for AI answers, build/deploy logs, and progress feeds —
 Middleware attached to a `Router.flow()` call runs on the initial HTTP `GET` **and** on every WebSocket update for that page. This keeps auth gates active across the entire session, not just at page load:
-```typescript
+```typescript fragment
 import { Router } from "zerotal";
 import { RequireAuthMiddleware } from "#app/middleware/RequireAuth.ts";
 import { RequireAdminMiddleware } from "#app/middleware/RequireAdmin.ts";
@@ -657,7 +657,7 @@ See [Testing](/docs/flow/testing) for the full guide — mounting, calling actio
 ### Mounting a composed component
-```typescript
+```typescript fragment
 import { FlowTest } from "@zerotal/flow/testing";
 import { CounterPage } from "../app/flow/CounterPage.tsx";
@@ -672,14 +672,14 @@ t.assertDontSee("Count: 1");
 Mount with initial props (seed state before `onMount`):
-```typescript
+```typescript fragment
 const t = await FlowTest.mount(PostsPage, { page: 2, search: "TypeScript" });
 expect(t.page().search).toBe("TypeScript");
 ```
 ### Calling composed actions
-```typescript
+```typescript fragment
 // call() drives: onBoot → onHydrate → action() → onUpdate → render → onDehydrate
 await t.call("increment");
 expect(t.page().count).toBe(1);
@@ -694,7 +694,7 @@ expect(t.page().count).toBe(42);
 Two ways to change a property between calls:
-```typescript
+```typescript fragment
 // set() — direct assignment, no hooks fire
 await t.set("draft", "Hello world");
@@ -708,14 +708,14 @@ Use `set()` to seed state for a specific scenario. Use `update()` to test that y
 **HTML assertions:**
-```typescript
+```typescript fragment
 t.assertSee("Published post"); // HTML contains this string
 t.assertDontSee("Error"); // HTML does NOT contain this string
 ```
 **Validation assertions:**
-```typescript
+```typescript fragment
 await t.call("save");
 t.assertHasErrors("email"); // field has at least one error
 t.assertHasErrors("email", "required"); // error message contains "required"
@@ -724,14 +724,14 @@ t.assertNoErrors(); // no errors at all
 **Redirect assertions:**
-```typescript
+```typescript fragment
 t.assertRedirectedTo("/dashboard");
 t.assertNotRedirected();
 ```
 **Flash assertions:**
-```typescript
+```typescript fragment
 t.assertFlashed("success", "Saved."); // level + message substring
 t.assertFlashed("error"); // just check the level
 t.assertFlashed(undefined, "Something went"); // just check the message substring
@@ -739,13 +739,13 @@ t.assertFlashed(undefined, "Something went"); // just check the message substrin
 **Event assertions:**
-```typescript
+```typescript fragment
 t.assertDispatched("post-created");
 ```
 ### Composed accessors
-```typescript
+```typescript fragment
 t.page(); // the Component instance — inspect properties directly
 t.html(); // the rendered HTML string
 t.errors(); // current validation error bag: Record<string, string[]>
@@ -755,7 +755,7 @@ t.snapshot(); // the serialised snapshot
 ### Full test example
-```typescript
+```typescript fragment
 import { describe, test, expect, beforeEach } from "bun:test";
 import { FlowTest } from "@zerotal/flow/testing";
 import { LoginPage } from "#app/flow/LoginPage.tsx";

package/docs/flow/lifecycle.md CHANGED Viewed

@@ -46,7 +46,7 @@ GET /page  (initial render)            WebSocket action frame (subsequent)
 A child gets its data from its parent, not from the URL. Each prop lands on the field of the same name before `onBoot()` and `onMount()` run, so the field's initialiser is its default and a hook can use the value straight away:
-```typescript
+```typescript fragment
 export class CounterWidget extends Component {
   @locked label: string = "Count"; // ← <CounterWidget label="Views" />
   @locked step:  number = 1;       // ← defaults to 1 when the parent omits it
@@ -76,7 +76,7 @@ A child receives the request `HttpContext` in `onBoot(ctx)` / `onMount(ctx)` lik
 Runs on **every** request: the initial `GET` and every WebSocket update. Use it for setup that must be fresh on every round-trip — resolving the authenticated user from context, initialising i18n, wiring up per-request services:
-```typescript
+```typescript fragment
 import { request } from "zerotal";
 override async onBoot() {
@@ -96,7 +96,7 @@ Runs once on the initial `GET` render, then is skipped on all subsequent WebSock
 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
+```typescript fragment
 export class PostPage extends Component {
   @locked post!: Post; // /posts/:post — nothing to load
 }
@@ -104,7 +104,7 @@ export class PostPage extends Component {
 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
+```typescript fragment
 override async onMount({ user }: HttpContext) {
   this.canEdit = user?.id === this.post.authorId;
 }
@@ -112,7 +112,7 @@ override async onMount({ user }: HttpContext) {
 The context is passed to `onBoot()` too, but only the initial `GET` populates `ctx.params` — see the [warning in Routing](/docs/flow/routing#path-parameters). The argument is optional because a component can also be mounted outside a request (in a test, for example).
-```typescript
+```typescript fragment
 override async onMount() {
   const [posts, drafts] = await Promise.all([
     Post.query()
@@ -133,7 +133,7 @@ Lists and counts are what belongs here — the things no route resolved and no p
 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
+```typescript fragment
 @expose async createPost(): Promise<void> {
   await Post.create({ title: this.title, body: this.body });
   this.title = "";
@@ -147,7 +147,7 @@ To force `onMount()` to re-run during a WebSocket action — for example after c
 Runs on every WebSocket round-trip, immediately after state is restored from the snapshot. Use it to re-derive transient or protected state that wasn't persisted in the snapshot:
-```typescript
+```typescript fragment
 export class PostEditorPage extends Component {
   @expose post!: Post; // /posts/:post/edit — re-read from the row every round-trip
   @transient wordCount = 0; // NOT persisted — derived again each time
@@ -178,7 +178,7 @@ are not part of a re-read, and anything derived from them.
 Fires **before** a client-written property value is applied to the component. Throw to reject the write — the value is discarded, an error is added, and the component re-renders:
-```typescript
+```typescript fragment
 override async onUpdating(prop: string, value: unknown, key?: string) {
   // Prevent role escalation
   if (prop === "role" && value === "super_admin") {
@@ -198,7 +198,7 @@ override async onUpdating(prop: string, value: unknown, key?: string) {
 Fires **after** a client-written property is applied. Use it to normalise values, enforce computed side-effects, or trigger cascading updates:
-```typescript
+```typescript fragment
 override async onUpdated(prop: string, value: unknown) {
   if (prop === "categoryId") {
     // When the category changes, reload the subcategories
@@ -212,7 +212,7 @@ override async onUpdated(prop: string, value: unknown) {
 Instead of branching on `prop` inside `onUpdating`/`onUpdated`, define a per-property method named `onUpdating<PropName>` or `onUpdated<PropName>` (Pascal-cased). Flow calls it automatically and keeps the generic fallback as a catch-all:
-```typescript
+```typescript fragment
 @expose username = "";
 @expose email    = "";
 @expose tags:    string[] = [];
@@ -243,7 +243,7 @@ The per-property form is cleaner and TypeScript-friendly: the parameter type mat
 Runs once after the invoked action completes, before the render cycle. Use it to apply cross-cutting logic that should happen after any action:
-```typescript
+```typescript fragment
 override async onUpdate() {
   // Always log the current state to the audit trail after any action:
   await AuditLog.create({
@@ -260,7 +260,7 @@ Unlike `onUpdated` (which fires per property, before the action), `onUpdate()` f
 Runs immediately before `render()` on every request (initial and WebSocket). Use it for template-level setup that shouldn't be in `render()` itself — resolving shared view data, picking a layout variant, etc.:
-```typescript
+```typescript fragment
 override async onRendering() {
   // Decide which layout variant to use based on the user's subscription
   if (this.user?.isPro) {
@@ -275,7 +275,7 @@ Avoid async database calls here unless truly necessary — `onMount()` and `onHy
 Receives the rendered HTML string. Use it to post-process the output, measure render time, or send the HTML to a cache:
-```typescript
+```typescript fragment
 override async onRendered(html: string) {
   // Log very long renders for investigation
   if (html.length > 100_000) {
@@ -293,7 +293,7 @@ The `html` parameter is the raw HTML of this component only — not the full pag
 Runs just before the component state is serialised into the snapshot at the end of every request. Use it to strip sensitive or ephemeral state that shouldn't be persisted:
-```typescript
+```typescript fragment
 override async onDehydrate() {
   // Never persist raw upload paths between round-trips
   this.tempUploadPath = null;
@@ -314,7 +314,7 @@ After `onDehydrate()`, the snapshot is signed and sent to the browser as an encr
 Called when an `@expose`d action throws an unhandled error. The default behaviour flashes the error message with level `"error"`. Override to log to an error tracker or display a custom message:
-```typescript
+```typescript fragment
 override async onError(error: Error) {
   // Log to your error tracker
   await Sentry.captureException(error, {
@@ -331,7 +331,7 @@ override async onError(error: Error) {
 If you want some errors to propagate normally and only handle specific types:
-```typescript
+```typescript fragment
 override async onError(error: Error) {
   if (error instanceof DatabaseConnectionError) {
     this.flash("Database is temporarily unavailable. Please try again.", "error");

package/docs/flow/models.md CHANGED Viewed

@@ -28,7 +28,7 @@ binds to and how a model resolves by something other than its primary key.
 The other way a model arrives is from a parent that already has it, as a prop:
-```tsx
+```tsx fragment
 <PostCard post={this.post} />
 ```
@@ -53,7 +53,7 @@ one it edits.** Both put the model on the client; only `@expose` accepts anythin
 The snapshot carries the model's **id** and the result of its `toJSON()` — the same
 serialisation your API responses use, honouring `visible`, `hidden` and `appends`.
-```ts
+```ts fragment
 @table("users")
 export class User extends BaseModel {
   static fillable = ["name", "email", "password"];
@@ -98,7 +98,7 @@ server error. To refuse a value loudly instead, or to vet one before it lands, t
 Bind to a field of an `@expose`d model and it is two-way:
-```tsx
+```tsx fragment
 export class EditProfile extends Component {
   @expose user!: User;
@@ -149,7 +149,7 @@ and fails whatever the field actually holds. Two ways round it:
 the difference: fillable because a user sets it, hidden because the stored hash must never
 reach the page.
-```tsx
+```tsx fragment
 <input type="password" value={this.user.password} blur />
 ```
@@ -166,7 +166,7 @@ listed in the model's `hashable` — see [Password hashing](/docs/orm#password-h
 A relation that is loaded when the page renders travels with the model, through its own
 `toJSON()`. It does not survive the round-trip:
-```tsx
+```tsx fragment
 override async onMount(): Promise<void> {
   await this.post.loadMissing(["author"]); // this.post came from the route
 }
@@ -178,7 +178,7 @@ throws the ORM's guard: `Relation "author" was accessed on Post without eager lo
 Load what an action needs, where it needs it:
-```ts
+```ts fragment
 @expose async approve(): Promise<void> {
   await this.post.loadMissing(["author"]);
   this.post.approved = true;
@@ -192,7 +192,7 @@ When the page _displays_ the relation, load it once per round-trip in
 the case worth watching: a template reading `this.post.author.name` works on the first paint
 and throws on every interaction after it.
-```ts
+```ts fragment
 override async onHydrate(): Promise<void> {
   await this.post.loadMissing(["author"]);
 }
@@ -221,7 +221,7 @@ deleted — or soft-deleted — while a page holds it makes the next interaction
 patched, and the browser console carries the error. So follow a delete with a navigation
 rather than leaving the prop pointing at a row that is gone:
-```ts
+```ts fragment
 @expose async destroy(): Promise<void> {
   await this.post.delete();
   this.redirect("/posts");
@@ -232,7 +232,7 @@ rather than leaving the prop pointing at a row that is gone:
 An array of models is sent as ids and re-read with a single `whereIn` query:
-```tsx
+```tsx fragment
 @locked posts: Post[] = [];
 ```

package/docs/flow/pagination.md CHANGED Viewed

@@ -11,7 +11,7 @@ Paginate in the database with `Model.paginate(perPage)` — it returns the page
 For arrays already held in memory, `paginate(items, page, perPage)` slices the data and returns a rich paginator object with metadata and a windowed page list:
-```typescript
+```typescript fragment
 import { paginate } from "@zerotal/flow";
 export class PostsPage extends Component {
@@ -89,7 +89,7 @@ export class PostsPage extends Component {
 `Pagination` is a class mixin that adds page state, URL sync, and navigation methods automatically. Compose it with [`Component.using(...)`](/docs/flow/layouts#composing-behaviour-with-mixins).
-```tsx
+```tsx fragment
 import { Component, Pagination, Pager } from "@zerotal/flow";
 export class PostsPage extends Component.using(Pagination) {
@@ -137,7 +137,7 @@ Optional update hooks fire around a page change: define any of `updatingPage(pag
 Always call `this.resetPage()` when a filter changes — otherwise the current page may exceed the new total and return an empty result set:
-```typescript
+```typescript fragment
 @url search = "";
 @url status = "all";
@@ -187,7 +187,7 @@ For large datasets, avoid loading all rows in `onMount()`. Paginate in the datab
 `Model.paginate(perPage)` returns the page the request is on. Compose the mixin, query in `render()`, and there is no page to pass, no state to hold, and nothing to refresh — a page change re-renders, and the re-render re-queries:
-```tsx
+```tsx fragment
 export class PostsPage extends Component.using(Pagination) {
   override async render() {
     const posts = await Post.paginate(10); // this component's page
@@ -223,14 +223,14 @@ Outside a component, `paginate()` reads `?page=` from the query string — what
 Pass the page explicitly when it isn't the request's — a report job, a fixed first page, a second paginator driven by something other than the mixin:
-```typescript
+```typescript fragment
 const first = await Post.paginate(10, 1); // always page 1
 const invoices = await Invoice.paginate(10, undefined, "invoices"); // a named paginator
 ```
 The query builder takes the same arguments when you need to build the query up first. Keep the **result** on the component — it already carries the page, the total, the last page, and the URL helpers, so there is nothing to copy out of it:
-```typescript
+```typescript fragment
 export class PostsPage extends Component.using(Pagination) {
   @url search = "";
   @url status = "all";
@@ -291,7 +291,7 @@ The ORM's `.paginate()` issues two queries — a `COUNT(*)` for the total and a
 Use the `<InfiniteScroll>` component to load more pages as the user scrolls down, without explicit page navigation:
-```tsx
+```tsx fragment
 import { InfiniteScroll } from "@zerotal/flow";
 export class FeedPage extends Component {
@@ -345,7 +345,7 @@ export class FeedPage extends Component {
 For very large tables where `OFFSET` pagination is slow, use cursor-based pagination via the ORM. The cursor encodes the last-seen row's sort key and is more efficient for deep pages:
-```typescript
+```typescript fragment
 export class ActivityPage extends Component {
   @url cursor: string | null = null;
   @locked items:    Activity[] = [];

package/docs/flow/performance.md CHANGED Viewed

@@ -74,7 +74,7 @@ paying for a navigation you could have paid for during the hover. Flow has a sma
 `<Skeleton>` is a pulsing placeholder block — pure markup plus a bundled animation, so it needs no app CSS. Use it for the shape of content that hasn't loaded yet:
-```tsx
+```tsx fragment
 import { Skeleton } from "@zerotal/flow";
 <Skeleton height="1.5rem" width="60%" />     {/* one bar */}
@@ -84,7 +84,7 @@ import { Skeleton } from "@zerotal/flow";
 The most useful place is a lazy child's `placeholder()` — what shows while the component mounts on viewport entry — and inside a `<Loading>` region (`<Loading skeleton />` renders one for you):
-```tsx
+```tsx fragment
 export class ChartWidget extends Component {
   override placeholder() {
     return <Skeleton height="12rem" rounded="0.75rem" />;
@@ -101,7 +101,7 @@ Tune the tone with the `--flow-skeleton-color` CSS variable; the pulse respects
 Because state is a server-authoritative snapshot, optimistic UI and its rollback are already built in. A client expression that changes a prop and then calls an action applies the change **instantly**; when the server responds, the authoritative snapshot reconciles the prop — so if the server **rejects** the change, it snaps back on its own. There is no separate optimistic library and no compensation code to write:
-```tsx
+```tsx fragment
 @expose liked = false;
 @expose confirmLike(): void { /* … persist … */ }
@@ -124,7 +124,7 @@ Optimistic UI for a scalar is easy (flip a bool, reconcile on the patch). A **li
 **`<For>` — a reactive list.** Render the list with `<For>` and it compiles to an Alpine `x-for`, so any client change to the array re-renders it instantly (server patches still keep it authoritative):
-```tsx
+```tsx fragment
 import { For } from "@zerotal/flow";
 <For each={this.todos} keyBy="id">
@@ -141,7 +141,7 @@ The item template supports element structure, static attributes, `class`/`classN
 **`appendOptimistic` / `removeOptimistic` — instant add/remove with rollback.** Mutate the array optimistically, then dispatch the action that persists it:
-```tsx
+```tsx fragment
 <button
   onClick={() => {
     $flow.appendOptimistic("todos", { id: `tmp-${Date.now()}`, text: this.draft });
@@ -170,7 +170,7 @@ mirror image for deletes.
 Add `hover` to a `navigate` link and Flow fetches the target after a brief hover dwell (and on first touch on mobile), caching the HTML so the click swaps instantly instead of waiting on a cold request:
-```tsx
+```tsx fragment
 <a href="/posts" navigate hover>
   Posts
 </a>;
@@ -251,7 +251,7 @@ A multi-step form, a long editor, or any in-progress flow then resumes
 **exactly** — whether the user reloads the page, closes and reopens the tab, or
 switches device. Nothing is stored in the browser:
-```tsx
+```tsx fragment
 export class Wizard extends Component {
   static durable = true; // or { ttl: "1h", scope: "user" | "session" }

package/docs/flow/references.md CHANGED Viewed

@@ -129,7 +129,7 @@ So Flow re-derives instead. Any component left mid-action is refreshed from the
 The refresh is announced first, so you can say something rather than have the UI change under the user:
-```ts
+```ts fragment
 document.addEventListener("flow:desync", (e) => {
   const { components } = (e as CustomEvent<{ components: string[] }>).detail;
   toast(`Reconnected — refreshing ${components.length} component(s).`);
@@ -156,7 +156,7 @@ Mark a container with `onSort` (the reorder action) and each child with `sortIte
 | `sortIgnore`            | Exclude this child from dragging/reordering              | `flow:sort:ignore` |
 | `sortGroup="tasks"`     | Allow dragging between containers sharing the group name | `flow:sort:group`  |
-```tsx
+```tsx fragment
 @expose async reorder(key: string, index: number) {
   const moved = this.items.find((i) => String(i.id) === key);
   if (!moved) return;
@@ -272,7 +272,7 @@ A write syncs to the server after the expression finishes, unless the same expre
 `$flow.store` is app-wide UI state that shouldn't round-trip to the server — side-panel visibility, colour scheme, notification drawer, etc. Declare its shape with `defineStore(...)` at app start and type it by augmenting `FlowStore` (see [The global client store](/docs/flow#the-global-client-store)):
-```tsx
+```tsx fragment
 <button onClick={() => ($flow.store.ui.sidebarOpen = true)}>Open sidebar</button>
 <aside show={$flow.store.ui.sidebarOpen}>Sidebar content</aside>
 ```