@zerotal/arch 1.7.0

package/docs/inertia/rendering.md

@@ -0,0 +1,189 @@
+---
+title: Inertia Rendering Pages
+description: Return a page from a controller, choose a component, and control the response.
+---
+
+# Rendering pages
+
+Every Inertia response goes through one helper: `inertia()`. This section covers how it
+resolves components, what it returns for each request type, controller-less page
+routes, and how redirects behave.
+
+## The inertia helper
+
+```ts
+function inertia(component: PageName, props?: RenderProps): Promise<void>;
+```
+
+Call `inertia()` from any controller action. It reads the active request from
+`RequestContext` (via AsyncLocalStorage), so there is **no context argument** — and
+it sets `ctx.response` as a side effect. It is **async** (it resolves lazy/deferred props), so it
+returns `Promise<void>` — always `return inertia(...)` (or `await` it):
+
+```ts
+// app/controllers/PostController.ts
+import type { HttpContext } from "zerotal";
+import { inertia } from "@zerotal/inertia";
+import { Post } from "../models/Post.ts";
+
+export class PostController {
+  async index(ctx: HttpContext): Promise<void> {
+    const posts = await Post.query()
+      .withScopes((s) => s.published())
+      .with("author")
+      .orderBy("published_at", "desc")
+      .paginate(10, Number(ctx.query("page", "1")));
+
+    return inertia("Posts/Index", { posts });
+  }
+
+  async show(ctx: HttpContext): Promise<void> {
+    const post = await Post.query()
+      .where("slug", ctx.params["slug"]!)
+      .with("author")
+      .with("comments")
+      .firstOrFail();
+
+    return inertia("Posts/Show", { post });
+  }
+}
+```
+
+`return inertia(...)` is idiomatic: the helper returns `Promise<void>`, so returning it ends the
+action.
+
+> **Warning** — `inertia()` takes `(component, props)` — _not_
+> `inertia(ctx, component, props)`. The request is resolved from context
+> automatically.
+
+### Controlling which props are sent, and when
+
+Props can be more than plain values. Wrap them to make them lazy, optional, deferred, or mergeable —
+the foundation for partial reloads, "load more" lists, and deferred content:
+
+```ts
+// in a controller
+import { inertia, optional, defer, merge } from "@zerotal/inertia";
+
+return inertia("Users/Index", {
+  users: () => User.all(), // lazy — only evaluated when sent
+  roles: optional(() => Role.all()), // only on a partial reload that asks for it
+  stats: defer(() => computeStats()), // loaded after first paint
+  feed: merge(() => Post.paginate(15, page)), // appended on "load more"
+});
+```
+
+A unified `Inertia` facade exposes the full protocol API (`Inertia.render`, `Inertia.optional`,
+`Inertia.defer`, `Inertia.merge`, `Inertia.share`, `Inertia.location`, …). See
+[Data Props](/docs/inertia/props) for the full v3 feature set.
+
+## Component resolution
+
+The component string maps to a file under your pages directory (`resources/js/pages/`
+by default, configurable via `pagesDir`), with the framework extension appended
+(`.tsx` for React, `.vue` for Vue):
+
+| `inertia(...)` call           | Component file                            |
+| ----------------------------- | ----------------------------------------- |
+| `inertia("Dashboard")`        | `resources/js/pages/Dashboard.tsx`        |
+| `inertia("Posts/Index")`      | `resources/js/pages/Posts/Index.tsx`      |
+| `inertia("Admin/Users/Edit")` | `resources/js/pages/Admin/Users/Edit.tsx` |
+
+Component names are validated — a name containing `..` or a leading `/` is rejected
+to prevent path traversal.
+
+### The name is checked at compile time
+
+`inertia("Posts/Shwo", …)` does not compile: the name has to be a page in the
+generated registry (`resources/js/pages.generated.ts`, rebuilt by
+`bun zt inertia:build` and by `zt dev`). A renamed or misspelled page was a
+runtime 500 before — the kind that reaches production because the route it lives
+on is the one nobody clicked.
+
+For a name that genuinely isn't known until runtime, `inertia.dynamic(name, props)`
+takes any string and skips the check.
+
+The props are checked too — see [Typed props](/docs/inertia/props#typed-props).
+
+### Props serialization
+
+Props are JSON-serialized into the page object. **Pass plain data, not live ORM
+models with unloaded relations** — eager-load what the page needs (`.with("author")`)
+or map to a plain shape. Shared props (`auth.user`) are already reduced to scalars
+for you; see [Shared Props](/docs/inertia/props).
+
+## First load vs. navigation
+
+`inertia()` branches on the `X-Inertia` request header:
+
+| Request                            | Response                                                 |
+| ---------------------------------- | -------------------------------------------------------- |
+| First load (no `X-Inertia` header) | Full HTML document with the page object JSON embedded    |
+| XHR navigation (`X-Inertia: true`) | JSON page object only (`Content-Type: application/json`) |
+
+Both responses carry `Vary: X-Inertia` so browsers and CDNs cache the HTML and JSON
+variants separately. The page object always includes the current `url` and asset
+`version`.
+
+## Controller-less routes
+
+For pages that need no controller logic (marketing pages, static dashboards), render
+straight from the route with the `Router.inertia()` macro (added by the package):
+
+```ts
+// routes/web.ts
+import { Router } from "zerotal";
+
+Router.inertia("/about", "About/Index"); // no props
+Router.inertia("/home", "Home/Index", { greeting: "Hello" }); // static props
+Router.inertia("/admin", "Admin/Dashboard", [AuthMiddleware]); // middleware shorthand
+```
+
+The third argument is polymorphic: pass a **props object**, or pass a **middleware
+array** directly as a shorthand. To use both, pass props third and middleware fourth:
+
+```ts
+// routes/web.ts
+Router.inertia("/admin", "Admin/Dashboard", { title: "Admin" }, [AuthMiddleware]);
+```
+
+## Redirects
+
+After a non-GET action (a form POST/PUT/DELETE), redirect as usual — return a 302 and
+[`InertiaMiddleware`](/docs/inertia/middleware) upgrades it to a **303** so the
+browser issues a GET on the target instead of replaying the form:
+
+```ts
+// in a controller
+async store(ctx: HttpContext): Promise<void> {
+  const post = await Post.create(await ctx.body());
+  ctx.flash("success", "Post created.");
+  return ctx.redirect(`/posts/${post.slug}`); // 302 → 303, then renders Posts/Show
+}
+```
+
+Validation failures redirect back with errors in the session, which surface as the
+`errors` shared prop on the re-rendered page — again, see
+[Shared Props](/docs/inertia/props).
+
+### External redirects — Inertia.location
+
+To send the browser to an external URL (or force a full-page visit), use `Inertia.location(url)`. On
+an Inertia request it returns a `409` + `X-Inertia-Location` so the client does a `window.location`
+visit; on a normal request it's a plain `302`:
+
+```ts
+// in a controller
+import { Inertia } from "@zerotal/inertia";
+
+return Inertia.location("https://billing.stripe.com/session/abc");
+```
+
+Redirects to a target with a URL fragment (`/page#section`) are automatically converted to a `409` +
+`X-Inertia-Redirect` on Inertia requests so the fragment is preserved across the visit. See
+[External & fragment redirects](/docs/inertia/props#external-fragment-redirects).
+
+## 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.

package/docs/inertia/ssr.md

@@ -0,0 +1,102 @@
+---
+title: Inertia Server-Side Rendering
+description: Render the first paint on the server, and what changes when you do.
+---
+
+# Server-side rendering
+
+By default Inertia renders the first page on the client. Server-side rendering (SSR)
+renders the initial HTML on the server instead — better Time-to-First-Byte and
+crawlable content — while subsequent navigations keep using the fast JSON path.
+
+Zerotal offers two approaches: the **`/__ssr` endpoint** (standard Inertia SSR) and
+**streaming SSR** via `inertiaStream()`.
+
+## Which should I use?
+
+- **Endpoint SSR** (`ssr: true`) — the standard Inertia SSR contract. Turn it on
+  globally and the Inertia client renders the first page through `POST /__ssr`. Use
+  this when you want crawlable, server-rendered HTML across the whole app with no
+  per-controller change.
+- **Streaming SSR** (`inertiaStream()`) — swap `inertia()` for `inertiaStream()` in
+  the controllers whose initial document you want streamed for the fastest TTFB. Use
+  it selectively on heavy landing pages; everything else stays on `inertia()`.
+
+## Endpoint SSR
+
+Enable the SSR endpoint in config:
+
+```ts
+// config/inertia.ts
+import { InertiaConfig } from "@zerotal/inertia";
+import { env } from "zerotal";
+
+export default InertiaConfig({
+  htmlTemplate: "./resources/app.html",
+  version: env("ASSET_VERSION", "1"),
+  ssr: true, // registers POST /__ssr — requires a server renderer
+});
+```
+
+When `ssr: true`, `InertiaProvider` registers `POST /__ssr`, which accepts
+`{ component, props, url }` and returns `{ body, head }` — the same contract as the
+Inertia Node SSR server. On a first-page load the server renders the component into
+the template instead of shipping an empty root `<div>`; subsequent navigations use
+the normal JSON path. Pages render with the framework they're authored in: React
+`.tsx` via `react-dom/server`, or Vue `.vue` via `@inertiajs/vue3` +
+`vue/server-renderer` — install the server renderer for the framework(s) your app uses.
+
+## Streaming SSR
+
+`inertiaStream()` is a drop-in async alternative to `inertia()` that uses React 18's
+`renderToReadableStream` to improve TTFB. Instead of buffering the whole render, it
+streams the React output between the template's HTML prefix and suffix:
+
+```
+│ HTML prefix (everything before <!-- @inertia -->) │ → browser starts parsing <head>
+│ React component stream                             │ → above-the-fold content arrives early
+│ <div> close + page JSON + HTML suffix              │
+```
+
+Swap `inertia()` → `inertiaStream()` and `await` it — nothing else changes:
+
+```ts
+// app/controllers/PostController.ts
+import { inertiaStream } from "@zerotal/inertia";
+
+export class PostController {
+  async show(ctx: HttpContext): Promise<void> {
+    const post = await Post.findOrFail(ctx.params["id"]);
+    return inertiaStream("Posts/Show", { post });
+  }
+}
+```
+
+### Requirements
+
+- `react-dom/server` ≥ 18 (for `renderToReadableStream`)
+- The HTML template must contain `<!-- @inertia -->`
+- The page component must exist under your pages directory (`resources/js/pages/<component>.tsx`)
+
+It throws if the template hasn't loaded, or if the component name contains path
+traversal (`..` or a leading `/`).
+
+### inertia vs. inertiaStream
+
+|                | `inertia()`            | `inertiaStream()`                  |
+| -------------- | ---------------------- | ---------------------------------- |
+| Return type    | `Promise<void>`        | `Promise<void>`                    |
+| Rendering      | Buffered HTML string   | Streaming `renderToReadableStream` |
+| Response body  | Fully buffered string  | Streaming `ReadableStream`         |
+| TTFB           | After full render      | After the prefix is flushed        |
+| XHR navigation | JSON (the normal path) | N/A — only the first-page document |
+
+For XHR navigations (`X-Inertia: true`), keep using `inertia()` — streaming only
+benefits the initial HTML document load.
+
+> **Tip** — Stream the heaviest landing pages and leave everything else on `inertia()`.
+
+## 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.

package/docs/inspirations.md

@@ -0,0 +1,257 @@
+---
+title: Inspirations & Attributions
+description: The frameworks, runtimes, and tools that shaped Zerotal's design — what it borrowed, adapted, and where it diverged.
+---
+
+# Inspirations & Attributions
+
+Zerotal is built on the shoulders of giants. This page acknowledges the frameworks,
+runtimes, and tools that shaped its design — what we borrowed, what we adapted, and
+where we intentionally diverged.
+
+Zerotal is a full-stack TypeScript framework built natively for the [Bun](https://bun.sh)
+runtime, and to get there we drew on the best patterns from across the industry. The
+influences below are grouped by the part of the stack they shaped.
+
+## The Runtime & Foundation
+
+### Bun
+
+Bun is not just a runtime dependency — it is the reason Zerotal exists in the form it
+does. Without Bun's native primitives there would be no coherent single-package story:
+
+- **`Bun.SQL`** — the native SQLite/PostgreSQL client is the foundation of the ORM.
+  No `pg`, no `better-sqlite3`, no driver-abstraction overhead.
+- **`Bun.serve`** — the HTTP server. No `http.createServer`, no Express under the hood.
+- **`Bun.file` / `Bun.write`** — power the local storage driver and asset pipeline.
+- **`Bun.markdown`** — renders this documentation site straight from the `docs/*.md`
+  source files.
+- **`bun:test`** — the testing helpers (`TestApp`, `TestResponse`, factories) are built
+  directly on `bun:test`'s `describe` / `it` / `expect` primitives.
+- **Bun plugin API** — `bun-plugin-tailwind` and the JS bundler used by `FlowProvider`
+  run inside Bun's native plugin lifecycle.
+
+Where we diverged: Zerotal makes no attempt to also run on Node. Committing fully to one
+runtime is what keeps the stack small — one SQL client, one server, one test runner —
+instead of abstracting over several.
+
+### Temporal
+
+The TC39 `Temporal` proposal directly underpins `Carbon`, Zerotal's date library. All
+date arithmetic uses `Temporal.PlainDate`, `Temporal.ZonedDateTime`, and friends — never
+the legacy `Date` object — and `Carbon` is built on Bun's bundled `Temporal`
+implementation rather than wrapping `Date`.
+
+Where we diverged: `Carbon` is a thin ergonomic layer over `Temporal`, not a Moment/Day.js
+clone — it tracks the proposal toward stable rather than inventing its own date model.
+
+## Architectural Titans
+
+### Laravel
+
+Laravel is the gold standard for developer-friendly full-stack frameworks. Its
+influence on Zerotal is pervasive:
+
+- **Active Record ORM** — `Model`, attribute decorators (`@column`, `@belongsTo`,
+  `@hasMany`, `@hasOne`), and the query builder API mirror Eloquent's ergonomics.
+- **Service providers** — the `onRegister` / `onBooting` / `onBooted` lifecycle
+  (through to `onStarting` / `onStarted` / `onStopping` / `onStopped`) maps directly
+  to Laravel's provider boot cycle.
+- **Artisan-style CLI** — the `zt` command runner and generator scaffolding
+  (`make:model`, `make:controller`, `migrate`, …) take heavy cues from Artisan.
+- **Mail notifications** — `Notify.send(user, new WelcomeNotification())`, with the
+  email built fluently inside `toMail()` (`new MailMessage().subject(...).line(...)`),
+  is a conscious homage to Laravel's mail/notification API.
+- **Facades** — `Notify`, `Cache`, `Storage`, `Queue`, `Auth`, and `Log` follow the
+  static-proxy pattern, resolving a container singleton on each call.
+- **Gate / Policy authorization, password broker, and the `validate()` request flow**
+  all follow Laravel's shapes.
+
+Where we diverged: Zerotal drops PHP's runtime magic (no dynamic proxies, no
+`__get`/`__set` trickery) in favour of explicit TypeScript decorators and genuine
+static typing throughout.
+
+### Rails
+
+Before Laravel, Ruby on Rails established the patterns both frameworks inherit: the
+**Active Record** model pattern itself, **convention over configuration**, and
+**versioned, runnable migrations**. Zerotal's `Model.create()` / `Model.find()` surface
+and its migration runner trace their lineage here.
+
+Where we diverged: the same convention-over-configuration spirit, expressed through
+explicit TypeScript types and decorators rather than Ruby metaprogramming — conventions
+you can follow by reading types, not by memorising magic.
+
+## The TypeScript & Node Ecosystem
+
+### NestJS
+
+NestJS demonstrated that a decorator-driven IoC container could feel natural in
+TypeScript. Zerotal's dependency-injection story echoes it:
+
+- **Container + decorators** — `@inject(...)` marks a class for auto-wiring,
+  declaring its constructor dependencies as explicit tokens the container
+  resolves in order.
+- **Provider modules** — grouping bindings and boot logic into provider classes
+  parallels Nest's module/provider model.
+
+Where we diverged: Zerotal uses standard **TC39 decorators** with no `reflect-metadata`
+dependency — dependencies are declared explicitly as `@inject(...)` tokens rather than
+inferred from constructor parameter types.
+
+### AdonisJS
+
+AdonisJS proved that a Laravel-flavoured framework could thrive in the JavaScript
+ecosystem. Several Zerotal conventions trace back to Adonis:
+
+- **`HttpContext` as the single per-request object** — passing one rich context object
+  through the entire pipeline (rather than `req`/`res` pairs) was validated by Adonis.
+- **IoC container token conventions** — string-keyed bindings (`'db'`, `'cache'`,
+  `'queue'`, `'events'`, `'log'`) alongside class and Symbol tokens follow the pattern
+  Adonis popularised.
+- **Lucid-inspired query scopes** — named scopes (`Model.scope(...)`,
+  `Model.query().withScopes(...)`) and global scopes parallel Lucid's model scopes.
+
+Where we diverged: Zerotal keeps views as typed TypeScript (template literals / JSX)
+rather than adopting a dedicated template engine like Adonis's Edge — one less language
+to learn, and views type-check against the data you pass them.
+
+### Koa
+
+Zerotal's middleware pipeline is a Koa-style **onion model**, not a Laravel-style
+before/after/terminate kernel:
+
+- **`handle(ctx, next)`** — each middleware is a `Pipe` with a single `handle` method
+  that receives the `HttpContext` and a `next()` continuation, awaits downstream
+  middleware, and can run logic on the way out — exactly Koa's cascading model.
+- **Short-circuiting** — a middleware that returns without calling `next()` stops the
+  chain, the same way Koa middleware can decline to continue.
+
+Where we diverged: Koa is deliberately minimal — middleware and little else. Zerotal keeps
+the onion model but ships a batteries-included stack on top of it, and the context is a
+richly-typed `HttpContext` rather than a bare object. Post-response work (Laravel's
+`terminate`) is handled via `ctx.afterResponse(...)` callbacks rather than a third phase.
+
+## Reactivity & The Frontend
+
+### Next.js
+
+Next.js normalised several patterns that Zerotal adopted for its front-end story:
+
+- **File-based routing** — a `routes/` directory with `GET`, `POST`, etc. named exports
+  mirrors the Next.js App Router file convention.
+- **Co-located route handlers** — keeping data-fetching logic next to the route that
+  uses it (rather than in a separate controllers directory) is a Next.js-influenced
+  option.
+- **`_layout.ts`** — a persistent shell that wraps every page in a section of the app
+  comes directly from Next.js layouts.
+
+Where we diverged: file-based routing is _one option_, not the whole story — routes can
+equally be registered explicitly with `Router.get(...)` — and everything runs
+server-side on Bun, with no client bundler or React Server Components coupling.
+
+### Livewire / Alpine.js
+
+Flow — Zerotal's first-party, server-driven reactive component system — draws from the
+Livewire mental model:
+
+- **Server-driven reactivity** — component state lives on the server; only diffs are
+  sent to the client.
+- **`@locked` / `@expose` decorators** — the distinction between server-private and
+  client-accessible properties mirrors Livewire's `#[Locked]` and `wire:model` boundary.
+- **SPA `navigate` transitions** — Livewire's `livewire:navigate` was the direct
+  reference point for Flow's fetch-and-swap page navigation.
+
+Where we diverged: Flow is pure TypeScript with no PHP/Blade runtime — components are
+typed classes, and the diffing/transport protocol is Zerotal's own.
+
+### Inertia.js
+
+Zerotal's first-party Inertia adapter (`@zerotal/inertia`) is built on Inertia.js
+itself. The adapter layer follows the same server-side adapter conventions established
+by the official Laravel and Rails adapters.
+
+Where we diverged: the adapter ships first-party and is versioned with the framework,
+rather than living as a separately-maintained community package.
+
+### shadcn/ui
+
+`@zerotal/flow-ui` follows the model shadcn/ui established, and the debt is worth naming
+plainly:
+
+- **You own the code** — `bun zt flow:add button` copies the source into your app rather
+  than adding a dependency you can only configure from the outside. `flow:add` is the
+  same idea as `npx shadcn add`, down to the registry manifest behind it.
+- **Tokens over props** — re-theming happens by overriding CSS variables, not by
+  threading a theme object through every component. The default token names
+  (`background`, `card`, `primary`, `muted`, `accent`, `destructive`, `border`, `input`,
+  `ring`) are shadcn's, so a palette written for one drops into the other.
+- **Styled wrappers over headless primitives** — shadcn styles Radix; flow-ui styles
+  Flow's own headless layer, which fills the same role.
+- **The catalogue** — the component list was chosen by working through shadcn's and
+  asking which entries a Zerotal application would actually reach for.
+
+Where we diverged: components render on the server and return HTML rather than React
+elements, so there is no client component tree; the `Chart` component draws SVG on the
+server instead of wrapping a charting library; and the AI-chat components have no
+equivalent here.
+
+## Tooling, Data & Telemetry
+
+### Zod
+
+The validator's API is shaped by Zod's fluent, inferable schemas:
+
+- **Chained rule builders** — `r.string().min(3).max(255)`, `r.number().integer()`,
+  `r.array(r.string()).optional()` read like Zod schemas.
+- **Type inference** — `Infer<>` derives the fully-typed result of a schema, so
+  validated data needs no manual casts — the same payoff as Zod's `z.infer`.
+
+Where we diverged: Zerotal's validator is wired into the HTTP request lifecycle
+(`FormRequest`, the `validate(ctx, …)` helper, automatic 422/redirect handling) rather
+than being a standalone parsing library.
+
+### Monolog
+
+Zerotal's logger borrows Monolog's channel architecture (by way of Laravel's logging):
+
+- **Named channels with per-channel level thresholds** — `console`, `single`, `daily`,
+  `stack`, `null`, each filtering below its configured minimum level.
+- **Stack channels** — fan a single entry out to several channels at once.
+- **Daily rotation with retention** — date-stamped files pruned after `days`.
+
+Where we diverged: the logger is a lean, five-driver reimplementation — there is no PHP
+handler/processor ecosystem to port, just the channel model that earns its keep.
+
+### Laravel Telescope / Pulse
+
+Zerotal's devtools (`@zerotal/devtools`) take their cue from Telescope and Pulse:
+
+- **Per-request traces** — queries, cache operations, mail, jobs, and logs captured for
+  each request and streamed live to an in-browser dashboard.
+- **Slow-query and N+1 detection** — surfaced automatically, the way Telescope flags
+  slow queries.
+
+Where we diverged: rather than each domain package depending on devtools, everything is
+captured through the synchronous **`FrameworkEvents`** instrumentation bus in
+`@zerotal/core` — devtools (and the logger, and any metrics layer) simply subscribe, so
+the domain packages never import their observers. See [Events](/docs/events).
+
+### Prisma / Drizzle
+
+The class-based migration format (`export default class extends Migration` with `up()`
+and `down()` methods) and the `migrate` / `migrate:fresh` CLI commands were shaped by
+observing what Prisma and Drizzle got right.
+
+Where we diverged: migrations stay as ordinary TypeScript you can read and run — no
+schema DSL, no generated client step — keeping the database layer transparent rather
+than hidden behind a code-generation pipeline.
+
+If you see your work reflected here and feel it is misrepresented or missing, please
+open an issue or pull request — attribution matters.
+
+## Next steps
+
+- [Getting started](/docs/getting-started) — scaffold your first Zerotal app.
+- [Application](/docs/application) — how the framework is wired together.
+- [Contributing](/docs/contributing) — help shape the framework.