@zerotal/arch 1.7.0

package/docs/inertia/devtools.md

@@ -0,0 +1,197 @@
+---
+title: Inertia DevTools
+description: Record every Inertia request — component, props, timing, and headers — and read it in the Inertia DevTools browser extension.
+---
+
+# Inertia DevTools
+
+The [Inertia DevTools](https://inertiajs.com/docs/v3/advanced/devtools) browser
+extension shows a timeline of every Inertia request: which component rendered,
+which props it received, which of those were deferred or shared, and how long the
+server took. Zerotal implements the server half of that — the recorder and the
+read API the extension talks to.
+
+It is on by default in development and off everywhere else, so there is normally
+nothing to configure.
+
+## What you get
+
+Install the extension, run `bun zt dev`, and open the Inertia panel. Each request
+becomes one entry carrying:
+
+- The **component** that rendered and the **route** that matched, by name.
+- Every **prop**, tagged with the wrapper that produced it — `defer` (and its
+  group), `optional`, `always`, `merge` (and its direction), `once`, `scroll` —
+  plus which props came from `share()`.
+- The **resolved values**, with sensitive keys removed.
+- **Request and response headers**, with sensitive ones removed.
+- **Status, method, URL, and server time**.
+
+Follow-up requests are grouped with the navigation that caused them, so a page
+whose deferred props arrive in three later requests reads as one batch rather
+than four unrelated rows.
+
+### The same data, without the extension
+
+The recorder also feeds Zerotal's own [DevTools](/docs/devtools) panel, on an
+**Inertia** tab, whenever that package is installed. Nothing to configure and no
+extension to add — the entry is recorded against the same request as everything
+else, so one row shows the component and its prop tree _and_ the SQL that
+produced them. A visit and the deferred loads it triggers fold into one entry on
+that panel's All tab, keyed on the same batch the extension groups by.
+
+This is a fan-out, not a replacement: the read API below is a published contract
+and keeps serving the extension either way. Neither package depends on the other
+— the panel is found through the container, and its absence is the ordinary case.
+
+### The client half needs Inertia 3
+
+Two independent halves feed the panel. The **server recorder** is this package,
+and it works on any supported Inertia version. The **client hooks** — visit
+options, prefetch-cache entries, and the grouping that tells a poll apart from a
+navigation — live in the Inertia adapter, and only in **version 3 or later**.
+
+On an older adapter the panel still fills with requests, but reports that the app
+is not running in dev mode and suggests starting a Vite dev server. That advice
+does not apply here — there is no Vite in a Zerotal app — and the fix is the
+adapter version:
+
+```bash
+# in your project root
+bun add @inertiajs/react@^3   # or @inertiajs/vue3@^3
+```
+
+Apps scaffolded from Zerotal 1.6.1 onwards already pin it. The React adapter
+requires React 19, which the template has always pinned.
+
+Nothing else is needed. The adapter's `dev` option defaults to `import.meta.env.DEV`,
+a Vite convention that Bun's bundler does not define on its own — so Zerotal
+defines it for every Inertia build, development and production alike. You do not
+set `dev` yourself, and there is no Vite server to run.
+
+## Turning it on and off
+
+The recorder follows the same gate as the stack-trace error page: on when this
+process is a development process, off otherwise. A production deploy records
+nothing and registers no endpoints — there is nothing there to probe.
+
+To override, set the environment variable:
+
+```bash
+INERTIA_DEVTOOLS_ENABLED=false   # off, even in dev
+INERTIA_DEVTOOLS_ENABLED=true    # on — see the warning below
+```
+
+Or configure it:
+
+```typescript
+// config/inertia.ts
+import { InertiaConfig } from "zerotal/inertia";
+
+export default InertiaConfig({
+  devtools: {
+    enabled: null, // null = follow the dev-surface gate (default)
+    maxEntries: 200,
+  },
+});
+```
+
+> **Running it outside development.** Entries contain request headers and
+> resolved props for real users' requests. If you enable the recorder on a shared
+> environment, set a `gate` — without one the read API refuses every request
+> rather than defaulting to open.
+
+## Configuration
+
+All keys live under `devtools` in `config/inertia.ts`, typed as
+`InertiaDevtoolsConfig`.
+
+| Key             | Default | What it does                                                                   |
+| --------------- | ------- | ------------------------------------------------------------------------------ |
+| `enabled`       | `null`  | `null` follows the dev-surface gate; `true`/`false` decides explicitly.        |
+| `maxEntries`    | `200`   | How many entries to keep before the oldest is dropped.                         |
+| `redact`        | `[]`    | Extra prop/body key patterns to withhold, on top of the built-in list.         |
+| `redactHeaders` | `[]`    | Extra header names to withhold, on top of the built-in list.                   |
+| `except`        | `[]`    | Path prefixes never recorded.                                                  |
+| `gate`          | `null`  | `(request) => boolean` authorising the read API outside a development process. |
+
+### Redaction
+
+Values are redacted **before** an entry is stored, so a withheld value is never
+written down in the first place.
+
+Redacted out of the box: any key containing `password`, `secret`, `token`,
+`authorization`, `api_key`, `apikey`, `credit_card`, `card_number`, `cvv`, `ssn`,
+or `private_key`, and the `authorization`, `cookie`, `set-cookie`,
+`proxy-authorization`, `x-api-key`, `x-csrf-token`, and `x-xsrf-token` headers.
+Matching is a case-insensitive substring, so `password` also covers
+`password_confirmation` and `currentPassword`.
+
+Add your own:
+
+```typescript
+// config/inertia.ts
+export default InertiaConfig({
+  devtools: {
+    redact: ["national_id", "account_number"],
+    redactHeaders: ["x-internal-signature"],
+  },
+});
+```
+
+Uploaded files are summarised rather than inlined, and a prop graph containing a
+cycle is recorded with `[Circular]` in place of the loop instead of failing the
+request.
+
+### Keeping noise out
+
+The read API never records itself. Add anything else that would bury the
+timeline:
+
+```typescript
+// config/inertia.ts
+export default InertiaConfig({
+  devtools: { except: ["/health", "/metrics"] },
+});
+```
+
+### Gating a shared environment
+
+```typescript
+// config/inertia.ts
+export default InertiaConfig({
+  devtools: {
+    enabled: true,
+    gate: (request) => request.headers.get("X-Debug-Key") === Bun.env["DEBUG_KEY"],
+  },
+});
+```
+
+The gate is never consulted on a development machine — a gate that can lock you
+out of your own laptop is a gate that gets switched off.
+
+## How it works
+
+`InertiaProvider` registers `InertiaDevtoolsMiddleware` and the read API when the
+recorder is enabled, so an app adds nothing to its middleware stack.
+
+Each response carries the id of the entry it produced, and the first full-page
+load also embeds it in a script tag so the extension can find the entry before
+any XHR happens. The extension then reads the entry from
+`/_inertia/devtools/entries` (`DEVTOOLS_API_PREFIX`), which serves
+`DevtoolsEntry` objects newest-first and accepts `component`, `type`, `exclude`,
+`offset`, and `limit` filters.
+
+Entries are kept in memory in the process that recorded them, capped at
+`maxEntries`. They do not survive a restart — which under `bun zt dev` happens on
+every save anyway, and which keeps recording off the disk and out of the request
+path.
+
+`devtoolsEnabled()` reports whether the recorder is currently active, if you need
+to branch on it yourself.
+
+## Next steps
+
+- [Props](/docs/inertia/props) — the wrappers the panel reports on.
+- [Middleware & Versioning](/docs/inertia/middleware) — the rest of the Inertia middleware stack.
+- [DevTools](/docs/devtools) — Zerotal's own in-browser panel for SQL, logs, mail, and jobs.

package/docs/inertia/index.md

@@ -0,0 +1,267 @@
+---
+title: Inertia
+description: Build a single-page app with server-side routing and controllers — no separate API layer or client-side router.
+---
+
+# Inertia
+
+[Inertia.js](https://inertiajs.com) lets you build a single-page app using
+server-side routing and controllers — no separate API layer, no client-side router.
+Your controllers return Inertia **page responses**; Inertia renders the matching
+React (or Vue) component client-side on navigation, and returns a full HTML document
+on the first load.
+
+Zerotal's `@zerotal/inertia` package is a native, Bun-powered Inertia server adapter with full
+**Inertia v3** protocol support: controller-less page routes, automatic shared props, asset
+versioning, the complete data-props layer (partial reloads, `optional`/`defer`/`merge`/`once` props,
+history encryption, precognition), a `make:page` generator, a `Bun.build`-based bundler, and optional
+streaming SSR — all wired by a single provider. The stock `@inertiajs/react` / `@inertiajs/vue3`
+clients work against it unchanged.
+
+## How it works
+
+1. **First load** — a `GET` request hits a controller, which calls `inertia()`. The
+   server renders the full HTML document with the page object (component name +
+   props) embedded as JSON.
+2. **Client boot** — the Inertia client reads that page object and mounts the named
+   component.
+3. **Navigation** — subsequent links/visits send an `X-Inertia: true` request. The
+   same controller runs, but `inertia()` returns **only the JSON page object** — the
+   client swaps the page component without a full reload.
+
+The server stays the source of truth for routing and data; the client is just a thin
+renderer that morphs between pages.
+
+## Getting Started
+
+The framework adapter (React or Vue) is a peer dependency you install in your app —
+the server package works against whichever you choose:
+
+```bash
+# in your project root
+bun add @inertiajs/react react react-dom   # React
+# or
+bun add @inertiajs/vue3 vue                # Vue
+```
+
+`@zerotal/inertia` itself ships with the framework. If you're adding it to an
+existing app, `bun add @zerotal/inertia`.
+
+## Register the provider
+
+Add `InertiaProvider` to the providers array in `bootstrap/providers.ts`:
+
+```ts
+// bootstrap/providers.ts
+import { InertiaProvider } from "@zerotal/inertia";
+
+const providers = [
+  // …your other providers
+  InertiaProvider,
+];
+
+export default providers;
+```
+
+That's the only wiring you need. Registering the provider switches on the following (in lifecycle order):
+
+- `onRegister` — registers the `Router.inertia()` route macro so it's available before routes load.
+- `onBooting` — auto-registers `InertiaMiddleware` via `app.useOnce()`, loads the HTML template and asset version into memory, resolves the pages directory, applies the history-encryption default, and (when `ssr: true`) registers `POST /__ssr`.
+- `onBooted` — registers Inertia's dev build routine (alongside any other view layer's, so both keep rebuilding) and lazily registers the `make:page` and `inertia:build` CLI commands when running in console mode.
+
+You do **not** add `InertiaMiddleware` to `.use()` manually (see [Middleware & Versioning](/docs/inertia/middleware)).
+
+## Configuration
+
+Create `config/inertia.ts` with the `InertiaConfig()` helper (or `satisfies
+InertiaConfigShape`). Every field has a default, so an empty `InertiaConfig({})` is valid:
+
+```ts
+// config/inertia.ts
+import { InertiaConfig } from "@zerotal/inertia";
+import { env } from "zerotal";
+
+export default InertiaConfig({
+  htmlTemplate: "./resources/app.html", // root template — must contain <!-- @inertia -->
+  version: env("ASSET_VERSION", "1"), // cache-bust string; bump on each deploy
+  assetsUrl: "/", // public URL prefix for built assets
+  pagesDir: "resources/js/pages", // where page components live
+  ssr: false, // set true to enable POST /__ssr (see SSR)
+});
+```
+
+| Field            | Required | Default                  | Description                                                                                          |
+| ---------------- | -------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `htmlTemplate`   | no       | `"./resources/app.html"` | Path to the root HTML template (must contain `<!-- @inertia -->`); falls back to a built-in default. |
+| `version`        | no       | `"1"`                    | Asset version string embedded in every page object; bump on each deploy.                             |
+| `assetsUrl`      | no       | `"/"`                    | Public URL prefix for built assets.                                                                  |
+| `pagesDir`       | no       | `"resources/js/pages"`   | Directory (relative to the project root) where Inertia page components live.                         |
+| `ssr`            | no       | `false`                  | Register `POST /__ssr` for endpoint SSR (requires a server renderer).                                |
+| `encryptHistory` | no       | `false`                  | Encrypt browser history state globally; per-page overrides via `Inertia.encryptHistory()`.           |
+
+### HTML template
+
+The template is loaded **once at boot**; `<!-- @inertia -->` is where the page
+object and root `<div>` are injected on every response:
+
+```html
+<!-- resources/app.html -->
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>My App</title>
+    <script type="module" src="/assets/app.js" defer></script>
+  </head>
+  <body>
+    <!-- @inertia -->
+  </body>
+</html>
+```
+
+> **Note** — If `htmlTemplate` is missing, `InertiaProvider` falls back to a built-in default
+> template in development so the app still boots — but in production a missing template
+> throws. Provide your own for real projects.
+
+## Your first page
+
+A controller action calls `inertia(component, props)`:
+
+```ts
+// app/controllers/DashboardController.ts
+import type { HttpContext } from "zerotal";
+import { inertia } from "@zerotal/inertia";
+import { Post } from "../models/Post.ts";
+
+export class DashboardController {
+  async index(ctx: HttpContext): Promise<void> {
+    const posts = await Post.query().latest().limit(5).get();
+    return inertia("Dashboard", { posts });
+  }
+}
+```
+
+`inertia()` reads the current request from context — it takes **no context
+argument** — and sets the response as a side effect, so the action returns
+`Promise<void>`. The component name (`"Dashboard"`) maps to
+`resources/js/pages/Dashboard.tsx`.
+
+```tsx
+// resources/js/pages/Dashboard.tsx
+import { Link } from "@inertiajs/react";
+
+interface Props {
+  posts: { id: number; slug: string; title: string }[];
+  auth: { user: { name: string } | null }; // from shared props
+}
+
+export default function Dashboard({ posts, auth }: Props) {
+  return (
+    <main>
+      <h1>Dashboard</h1>
+      {auth.user && <p>Welcome back, {auth.user.name}</p>}
+      {posts.map((post) => (
+        <Link key={post.id} href={`/posts/${post.slug}`}>
+          {post.title}
+        </Link>
+      ))}
+    </main>
+  );
+}
+```
+
+Note `auth` is available without the controller passing it — see
+[Shared Props](/docs/inertia/props). Generate new pages with
+[`make:page`](/docs/inertia/build#generating-a-page) and bundle them with
+[`inertia:build`](/docs/inertia/build#building-assets).
+
+## Testing
+
+Set your suite up once as described in [Testing](/docs/testing). An Inertia route
+serves two different things depending on one header, so a test has to say which
+one it wants.
+
+**Send `X-Inertia: true` to get the page object** instead of the HTML shell. This
+is the assertion you want in almost every route test — it checks the component
+and its props without parsing markup:
+
+```typescript
+// tests/http/dashboard.test.ts
+import { test } from "bun:test";
+import { createApp } from "../helpers.ts";
+
+test("the dashboard renders with its stats", async () => {
+  const app = await createApp();
+
+  const res = await app.actingAs(user).get("/dashboard", { "X-Inertia": "true" });
+
+  res.assertJsonPath("component", "Dashboard");
+  res.assertJsonPath("props.stats.orders", 12);
+  await app.close();
+});
+```
+
+**Without that header you get the full HTML document** with the page object
+embedded in a `data-page` attribute — right for asserting the first paint, wrong
+for asserting props:
+
+```typescript
+// tests/http/dashboard.test.ts
+const res = await app.actingAs(user).get("/dashboard");
+
+res.assertSee('<div id="app"');
+res.assertHeader("Vary", "X-Inertia"); // the response varies by that header
+```
+
+**Test partial reloads by the props they omit.** A partial reload that quietly
+returns everything is a performance bug no page-level assertion catches:
+
+```typescript
+// tests/http/dashboard.test.ts
+const res = await app.actingAs(user).get("/dashboard", {
+  "X-Inertia": "true",
+  "X-Inertia-Partial-Data": "stats",
+  "X-Inertia-Partial-Component": "Dashboard",
+});
+
+res.assertJsonPath("props.stats.orders", 12);
+const page = res.json<{ props: Record<string, unknown> }>();
+expect(page.props.notifications).toBeUndefined(); // excluded, as asked
+```
+
+**A version mismatch is a `409`, not an error.** It tells the client to reload so
+it picks up new assets — worth a test if you set `ASSET_VERSION` on deploy:
+
+```typescript
+// tests/http/dashboard.test.ts
+const res = await app.get("/dashboard", { "X-Inertia": "true", "X-Inertia-Version": "stale" });
+
+res.assertStatus(409);
+res.assertHeader("X-Inertia-Location");
+```
+
+> **Note** — For the client half — a component rendering, a form submitting, a
+> deferred prop arriving — use [Browser Tests](/docs/testing/browser). These
+> assertions stop at the boundary your server owns.
+
+## The rest of the guide
+
+| Page                                                | What it covers                                                                                            |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| [Rendering Pages](/docs/inertia/rendering)          | Return a page from a controller, choose a component, and control the response.                            |
+| [Props](/docs/inertia/props)                        | Pass data to a page — eager, lazy, deferred, and merged props, plus the shared props every page receives. |
+| [Middleware & Versioning](/docs/inertia/middleware) | The Inertia middleware, asset versioning, and forcing a full reload after a deploy.                       |
+| [Server-Side Rendering](/docs/inertia/ssr)          | Render the first paint on the server, and what changes when you do.                                       |
+| [DevTools](/docs/inertia/devtools)                  | Record each request's component, props, and timing for the Inertia DevTools extension.                    |
+| [CLI & Build](/docs/inertia/build)                  | The page registry, the bundler pipeline, and building for production.                                     |
+| [Reference](/docs/inertia/references)               | Every helper, prop type, and config key in one table.                                                     |
+
+## Next steps
+
+- [Controllers](/docs/controllers) — where most `inertia()` calls live.
+- [Routing](/docs/routing) — declare routes and the `Router.inertia()` macro targets.
+- [Middleware](/docs/middleware) — how `InertiaMiddleware` slots into the pipeline.
+- [Validator](/docs/validator) — the validation that feeds the `errors` shared prop and precognition.
+- [Providers](/docs/providers) — the lifecycle hooks `InertiaProvider` builds on.
+- [Pagination](/docs/pagination) — the paginators `merge()` and `scroll()` consume.

package/docs/inertia/middleware.md

@@ -0,0 +1,81 @@
+---
+title: Inertia Middleware & Versioning
+description: The Inertia middleware, asset versioning, and forcing a full reload after a deploy.
+---
+
+# Middleware & versioning
+
+`InertiaMiddleware` implements the parts of the Inertia protocol that have to happen
+at the HTTP layer. You don't register it manually — `InertiaProvider` adds it for you
+via `useOnce()` during boot.
+
+## What the middleware does
+
+`InertiaMiddleware` handles three protocol requirements on every response:
+
+1. **302 → 303 for non-GET redirects.** Inertia requires a 303 after a
+   POST/PUT/DELETE so the browser issues a `GET` on the redirect target instead of
+   replaying the form submission. Without this, redirect-after-submit flows break.
+
+2. **Asset-version mismatch → 409.** When the client's `X-Inertia-Version` header
+   differs from the server's current [asset version](#asset-versioning), the
+   middleware responds **409** with an `X-Inertia-Location` header. The Inertia
+   client reacts by doing a full page reload to pull the new assets — this is how
+   zero-downtime deploys avoid stale-bundle errors.
+
+3. **`Vary: X-Inertia` on every response.** Prevents a browser/CDN cache from serving
+   a JSON navigation response where an HTML document is expected (or vice versa) on
+   Back/Refresh.
+
+## Automatic registration
+
+`InertiaProvider.onBooting()` calls `this.app.useOnce(InertiaMiddleware)`, so simply
+registering the provider is enough:
+
+```ts
+// bootstrap/providers.ts — this is all you need
+import { InertiaProvider } from "@zerotal/inertia";
+
+export default [
+  // …auth, session providers…
+  InertiaProvider,
+];
+```
+
+You do **not** add `InertiaMiddleware` to `Application.create().use([...])` — doing so
+would just register it twice (and `useOnce` guards against that anyway).
+
+> **Note** — Ordering & `ctx.user`. Shared props read `ctx.user` at the moment `inertia()`
+> runs _inside your controller_ — which is after the entire middleware pipeline. So
+> the authenticated user is always populated by the time props are built; you don't
+> need to hand-order `InertiaMiddleware` relative to auth.
+
+## Asset versioning
+
+The asset version is a string sent as part of every page object. When it changes, the
+client knows its cached bundle is stale and triggers a reload (the 409 flow above).
+
+Set a baseline in [config](/docs/inertia#configuration) (`version`), or compute one at boot
+from the actual bundle so it changes automatically on every deploy:
+
+```ts
+// in a ServiceProvider.onBooting()
+import { setAssetVersion } from "@zerotal/inertia";
+
+const hash = Bun.hash(await Bun.file("public/assets/app.js").text()).toString(16);
+setAssetVersion(hash);
+```
+
+| Function             | Purpose                                            |
+| -------------------- | -------------------------------------------------- |
+| `setAssetVersion(v)` | Set the current version (called by the provider).  |
+| `assetVersion()`     | Read the current version (embedded in every page). |
+
+Hashing the built bundle is the most robust option: the version is guaranteed to
+change exactly when the client code changes, so users always reload onto matching
+assets after a deploy.
+
+## Next steps
+
+- [Inertia overview](/docs/inertia) — the guide's front page and the rest of the sections.
+- [Reference](/docs/inertia/references) — the full API surface in one table.