@madojs/mado 0.11.1 → 0.13.0

package/docs/en/14-forms.md

@@ -0,0 +1,91 @@
+# Forms
+
+`useForm()` adds reactive state to the browser's form and constraint-validation
+model. HTML remains the source of truth for `required`, `type`, `min`, `max`,
+`minlength`, `maxlength` and `pattern`.
+
+```ts
+import { html, useForm } from "@madojs/mado";
+
+const form = useForm({
+  initial: { email: "", age: "" as number | "", newsletter: false },
+  validate: async (values, { signal }) => {
+    const available = await api.emailAvailable(values.email, { signal });
+    return available ? null : { email: "Email is already registered" };
+  },
+});
+
+html`
+  <form @submit=${form.onSubmit(async (values, event) => {
+    await api.save(values, new FormData(event.currentTarget as HTMLFormElement));
+  })}>
+    <label>
+      Email
+      <input name="email" type="email" required
+        @input=${form.onInput} @blur=${form.onBlur} />
+    </label>
+    ${() => form.touched().email && form.errors().email
+      ? html`<small role="alert">${form.errors().email}</small>`
+      : null}
+
+    <input name="age" type="number" min="18" max="120" @input=${form.onInput} />
+    <label><input name="newsletter" type="checkbox" @input=${form.onInput} /> Subscribe</label>
+    <button type="submit" ?disabled=${() => form.submitting() || form.validating()}>
+      Save
+    </button>
+  </form>
+`;
+```
+
+## API
+
+`useForm<T>({ initial, validate? })` returns:
+
+| Member | Meaning |
+| --- | --- |
+| `values()` | current typed values |
+| `errors()` | native and custom errors by field; `$form` is available for form-wide errors |
+| `touched()` | fields that have blurred or participated in submit |
+| `dirty()` | whether values differ from the current initial values |
+| `isValid()` | whether the merged error map is empty |
+| `submitting()` / `validating()` | current async activity |
+| `setField(name, value)` | update one field programmatically |
+| `validate(form?)` | run native and custom validation; returns `Promise<boolean>` |
+| `reset(nextInitial?)` | abort validation, clear state and reset native controls |
+| `onInput`, `onBlur`, `onSubmit(handler)` | DOM event handlers |
+
+Custom validation receives `{ signal, form }`. Starting another validation or
+calling `reset()` aborts the previous run. Treat abort as normal cancellation.
+
+## Native controls
+
+- Checkbox groups produce an array when the initial field value is an array;
+  a single checkbox produces a boolean.
+- Radio groups produce the checked value.
+- `<select multiple>` produces a string array.
+- Number/range inputs produce a number, or `""` when empty.
+- File inputs produce `File | null`, or `File[]` when `multiple` is present.
+- The submit callback receives the native `SubmitEvent`; construct `FormData`
+  from its form when the backend expects multipart or repeated fields.
+
+Use a native `<button type="submit">`. A button inside another element's
+Shadow DOM is not a submit control for the outer form and keyboard submission
+will not discover it.
+
+## Mutations
+
+```ts
+const save = mutation((values: Profile) => api.save(values), {
+  invalidates: ["/api/profile"],
+});
+const form = useForm({ initial: { displayName: "" } });
+
+html`<form @submit=${form.onSubmit((values) => save.run(values))}>
+  <input name="displayName" required minlength="2" @input=${form.onInput} />
+  <button type="submit" ?disabled=${() => form.submitting()}>Save</button>
+</form>`;
+```
+
+Write failures belong to the mutation; field and cross-field validation belong
+to the form. See the [0.12 → 0.13 migration guide](./33-migration-0.12-0.13.md)
+for the removed schema and field-array APIs.

package/docs/en/15-static-snapshots.md

@@ -0,0 +1,181 @@
+# Static snapshots (`mado static`)
+
+> Browser-rendered static HTML for SEO and first paint. No SSR, no
+> hydration, no template-language bake.
+
+`mado static` is a *snapshot capture*: at release time Mado runs your
+app in a real headless Chromium, lets the page render to the DOM
+(including any Shadow DOM), then serialises the result — Declarative
+Shadow DOM and all — to one HTML file per route. On first paint the
+live SPA atomically replaces the static tree; there is no hydration
+protocol and no node reconciliation.
+
+It is the right tool for content that is the same for every visitor:
+public landing pages, product / catalogue pages, documentation, blog
+posts. It is intentionally **not** an SSR runtime for personalised
+data.
+
+## When `static` is suitable
+
+- Public pages with a single canonical representation per URL.
+- Pages whose data is known at build time (CMS dump, file system,
+  Markdown, JSON, build-time API call).
+- Pages that need to appear fully rendered in `view-source:`, in
+  social preview crawlers, and to JS-disabled clients.
+- First paint of a page that *later* upgrades into a live SPA route.
+
+## When `static` is **not** suitable
+
+- Personalised content per visitor (auth, geo, A/B). The capture sees
+  one DOM and would ship it to everyone.
+- Real-time data (chat, dashboards, prices). The snapshot is frozen
+  the moment of capture.
+- Routes behind guards. Static pages are public by definition; the
+  discovery pipeline refuses to capture guarded routes.
+
+For those cases keep the route SPA-only — Mado still serves a clean
+`_mado/spa.html` fallback for them.
+
+## Declaring a static page
+
+A page opts in through the `static` field on `page({ ... })`. Two
+shapes are accepted:
+
+```ts
+// Single static page (no params)
+import { html, page } from "@madojs/mado";
+
+export default page({
+  static: true,
+  title: "Pricing",
+  head: () => ({ description: "Plans and pricing." }),
+  view: () => html`<main><h1>Pricing</h1></main>`,
+});
+```
+
+```ts
+// Dynamic static route — one capture per `paths()` entry
+import { html, page } from "@madojs/mado";
+
+export default page<{ slug: string }, Guide>({
+  static: {
+    paths: async () => guides.map((g) => ({ slug: g.slug })),
+    initialData: async ({ slug }) => loadGuide(slug),
+  },
+  title: ({ slug }) => guides.find((g) => g.slug === slug)?.title ?? slug,
+  head: ({ slug }, seed) => ({
+    description: seed?.summary ?? "",
+  }),
+  view: (ctx) => html`<article>${ctx.data.body}</article>`,
+});
+```
+
+The seed produced by `initialData()` is JSON-serialised into the
+captured HTML as `<script type="application/json" data-mado-static-data="…">`.
+On first client boot Mado consumes it once so `page.load()` and
+`page.head()` see the same data the snapshot saw — no extra fetch.
+
+## Running
+
+In normal use `mado static` is invoked through `mado release`:
+
+```bash
+mado release          # vite build + mado static + deployment files
+mado preview          # serve out/ like a real static host
+```
+
+You can also invoke `mado static` on its own (for tighter loops in
+CI), but it operates on the existing `out/` artefact produced by
+`vite build`, so the canonical command is `release`.
+
+A public origin is required so static documents carry absolute
+canonical URLs. Set it in `vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  plugins: [mado({ site: "https://your-app.example" })],
+});
+```
+
+…or override per run:
+
+```bash
+mado release --base-url https://staging.example
+MADO_SITE=https://staging.example mado release
+```
+
+## What the generated HTML contains
+
+For every captured route:
+
+- The full rendered light DOM.
+- Every open shadow root serialised through Declarative Shadow DOM
+  (`<template shadowrootmode="open">`).
+- Adopted stylesheets materialised into `<style>` tags inside the
+  shadow root.
+- A `<link rel="canonical">` and `<meta property="og:url">` derived
+  from `site + base + pathname` (if the page did not declare its own).
+  Both are marked `data-mado-head="static"` so the runtime `applyHead`
+  removes them on SPA navigation into a page without explicit head
+  metadata.
+- The seed `<script type="application/json" data-mado-static-data="…">`
+  for routes that declared `initialData()`.
+- Vite assets resolved through the active `base`.
+
+`<form>`, `<input>`, `<select>`, `<textarea>` and `<details>` state
+is serialised through attributes so a JS-disabled browser sees the
+same shape the snapshot captured.
+
+## Constraints and gotchas
+
+- **`paths()` and `initialData()` run during discovery AND ship in the
+  client bundle.** Keep them browser-safe. Never read secrets, never
+  call private services.
+- **Static pages cannot use guards** — route-level or layout-level.
+- **Wildcard routes (`*`) cannot be static.** They are the SPA
+  fallback.
+- **A compatible Chromium is required.** CI should install it through
+  Playwright:
+  ```bash
+  npx playwright install --with-deps chromium
+  ```
+  …or via the framework's installed `playwright-core` for revision
+  parity:
+  ```bash
+  node node_modules/playwright-core/cli.js install --with-deps chromium
+  ```
+- **Capture is strict by default.** Any failed fetch (script, style,
+  resource(), custom element definition) fails the snapshot. A small
+  allow-list covers `/favicon.ico`, `/favicon.svg`, `/robots.txt`
+  and `data:` URLs.
+- **All network calls must target the internal capture origin** serving the
+  freshly built `out/` tree. Undeclared external HTTP(S) requests are blocked;
+  provide deterministic `static.initialData()` instead.
+
+## Comparison
+
+| Approach                              | Mado static snapshot |
+| ------------------------------------- | -------------------- |
+| Next-style SSR + hydration            | not used             |
+| Astro-style island runtime            | not used             |
+| Build-time HTML from templates only   | not used             |
+| Browser-rendered DOM + DSD + takeover | **used**             |
+
+The result is a plain HTML file. Search engines, social preview
+crawlers and `curl` see exactly what your app renders on first paint;
+no JavaScript step is required to make the document meaningful.
+
+## Cookbook
+
+Concrete recipes for blog, product catalogue, documentation site and
+multi-locale builds live in [23-cookbook.md](./23-cookbook.md).
+
+## TL;DR
+
+- Declare `static: true | { paths, initialData }` on `page({ ... })`.
+- Run `mado release`.
+- Ship `out/` to any static host.
+- The live SPA takes over atomically on first paint.

package/docs/en/{10-app-architecture.md → 16-app-architecture.md}

@@ -4,7 +4,58 @@ The official starter is the canonical production shape for Mado apps. It is
 not a demo architecture and not a framework inside the framework: it is plain
 files, imports, Mado primitives, and ESLint boundaries.
 
-## File Tree
+## Project layout (universal starter)
+
+Both starters share the same top-level shape. The universal starter is the
+minimum:
+
+```
+my-app/
+├── package.json              # exactly one runtime dep: @madojs/mado
+├── tsconfig.json             # strict TS, ES2022, Bundler resolution
+├── vite.config.ts            # mado() from @madojs/mado/vite
+├── index.html                # Vite entry + SPA shell
+├── public/                   # static assets (favicons, images, robots.txt)
+└── src/
+    ├── main.ts               # entry: mount router into #app
+    ├── app.routes.ts         # one app map (default + named `manifest`)
+    ├── pages/                # *.page.ts files
+    ├── components/           # reusable <x-tag> components
+    └── shared/               # http/, lib/, styles/, ui/
+```
+
+`index.html` belongs at the project root because Vite treats it as an entry
+template, not a static public file. Put only copy-as-is files in `public/`.
+
+### The three artifact states
+
+| Folder    | What it is                                                  | Who writes      | Who reads               | Deploy?       |
+| --------- | ----------------------------------------------------------- | --------------- | ----------------------- | ------------- |
+| `src/`    | your TypeScript source                                      | you             | Vite, `tsc --noEmit`    | ❌ no          |
+| `public/` | static assets copied as-is                                  | you             | Vite build              | ✅ via `out/` |
+| `out/`    | **the deploy artifact**: SPA shell + assets + snapshots     | `mado release`  | nginx / CDN / CF Pages  | ✅ **yes**    |
+
+One-liner: develop with `mado dev`, ship with `mado release`, upload `out/`.
+
+### Naming rules
+
+| What                       | Style              | Example                |
+| -------------------------- | ------------------ | ---------------------- |
+| File                       | kebab-case         | `user-profile.ts`      |
+| Component tag              | `x-` + kebab       | `<x-user-profile>`     |
+| Context                    | PascalCase + `Ctx` | `ThemeCtx`, `AuthCtx`  |
+| Signal                     | camelCase          | `userId`, `isLoggedIn` |
+| Page-internal element      | `x-<route>-page`   | `<x-posts-page>`       |
+
+### What does NOT belong in `src/`
+
+- ❌ Build-tool configs beyond `vite.config.ts` with `mado()`.
+- ❌ `.env` files — read env in `src/shared/lib/config.ts` from
+  `import.meta.env` and import that one module everywhere.
+- ❌ Tests mixed with code — put them in `test/`.
+- ❌ `examples/` folder — keep large demos outside the app repo.
+
+## File tree (modular reference starter)
 
 ```txt
 src/
@@ -68,7 +119,7 @@ export default routes(manifest);
 
 Rules:
 
-- Export `manifest` so `mado bake` can discover bakeable pages.
+- Export `manifest` so `mado static` can discover bakeable pages.
 - Modules never call `layout()`.
 - Layouts describe app zones, not domains.
 - Do not hide the router inside a custom element or a second shell in
@@ -139,8 +190,9 @@ Reusable leaf components keep their own styles in ``css`...` `` inside
 `component()` options. They should depend on tokens (`var(--color-text)`)
 rather than global classes.
 
-`vite.config.ts` opts into Vite's Lightning CSS transformer. Mado does not own
-prefixing, CSS lowering or minification.
+Vite 8's standard CSS pipeline owns transforms and minification. Mado adds no
+CSS transformer; applications can configure Vite directly when they have a
+measured need.
 
 ## Growth
 

package/docs/en/{13-deployment.md → 20-deployment.md}

@@ -8,11 +8,12 @@
 
 ```
 out/
-├── index.html              ← SPA shell or baked HTML for /
+├── index.html              ← captured snapshot for / (or SPA shell)
 ├── assets/                 ← Vite hashed assets
 │   ├── *.gz                ← precompressed gzip (gzip_static / Accept-Encoding)
 │   └── *.br                ← precompressed brotli (brotli_static / Accept-Encoding)
-├── <route>/index.html      ← prerendered SEO HTML for baked routes
+├── <route>/index.html      ← captured snapshot per static route
+├── _mado/spa.html          ← SPA fallback shell (noindex)
 ├── sitemap.xml             ← generated sitemap
 ├── favicon.svg             ← your public/ assets copied verbatim
 ├── _redirects              ← Cloudflare Pages / Netlify SPA fallback
@@ -61,7 +62,7 @@ Key lines of the recipe `nginx.conf`:
 - `gzip_static on;` — serves the precompressed `.gz` files written by
   `mado release`. Zero CPU at request time.
 - `/assets/*` should be cached immutable; Vite filenames are content hashed.
-- `try_files $uri $uri/ /index.html;` — SPA fallback so deep links work
+- `try_files $uri $uri/ /_mado/spa.html;` — SPA fallback so deep links work
   after a hard refresh.
 
 Enable HTTPS with Let's Encrypt / Certbot. Add HSTS once you have it.
@@ -75,7 +76,7 @@ mado release
 npx wrangler pages deploy out --project-name=myapp
 ```
 
-- The generated `_redirects` (`/* /index.html 200`) gives you SPA fallback.
+- The generated `_redirects` (`/* /_mado/spa.html 200`) gives you SPA fallback.
 - The generated `_headers` (immutable cache for `/assets/*`, `no-cache` for
   HTML) is honored by CF Pages.
 - Baked routes are promoted to real route files (`out/<route>/index.html`),
@@ -89,8 +90,9 @@ Build command:    npm ci && npx mado release
 Output directory: out
 ```
 
-For catalogs too big to bake at build time, keep edge prerender experiments in
-the external examples workspace rather than in the core package.
+For catalogs too big to snapshot at release time, keep on-demand snapshot
+experiments in the external examples workspace rather than in the core
+package.
 
 ---
 
@@ -114,16 +116,15 @@ aws s3 sync out/ s3://my-bucket/ \
   --cache-control "no-cache, must-revalidate" --include '*.html'
 ```
 Configure CloudFront's "Default root object" to `index.html` and add a custom
-error response: 403/404 → `/index.html` with status 200 (SPA fallback).
+error response: 403/404 → `/_mado/spa.html` with status 200 (SPA fallback).
 
 **GitHub Pages**
 ```bash
 mado release
 # Push out/ into the gh-pages branch (or use actions/upload-pages-artifact)
 ```
-Pages handles `index.html` automatically. There is no native SPA fallback;
-add a `404.html` that loads the SPA, or use the
-[`spa-github-pages`](https://github.com/rafgraph/spa-github-pages) trick.
+Pages handles route `index.html` files automatically. `mado release` also writes
+`404.html` from the noindex SPA shell for client-only routes.
 
 ---
 
@@ -175,17 +176,78 @@ jobs:
 
 - **404 on hard refresh of a deep link.** Your host did not pick up SPA
   fallback. nginx: check `try_files`. CF/Netlify: `_redirects` is present?
-  S3+CloudFront: configure the 404 → `/index.html` (200) error response.
+  S3+CloudFront: configure the 404 → `/_mado/spa.html` (200) error response.
 - **HTML is cached forever.** Either your host sent a default
   `Cache-Control: public, max-age=...` or you are sitting behind a CDN that
   ignores `no-cache`. Add an explicit rule mirroring the matrix above.
 - **`/assets/*` files change but the browser keeps the old one.** They
   should not — the filename is hashed by Vite during `mado release`. If you bypassed
   build and shipped your own unhashed JS, give it a hash or short cache.
-- **Baked SEO page shows `[object Object]`.** Should never happen after the
-  v1 bake update — bake now raises a loud error in that case. If you see it,
-  upgrade `@madojs/mado` and re-run `mado bake`.
+- **Captured snapshot shows `[object Object]`.** `mado static` rejects
+  non-JSON-serialisable seeds at build time and points at the bad
+  field. If you still see it, upgrade `@madojs/mado` and re-run
+  `mado release`.
+
+## CSP and trusted content
+
+Mado serialises JSON-LD and static seed JSON with `<`, U+2028 and U+2029
+escaped, so data cannot close its script element. `unsafeHTML()` is different:
+it is an explicit trust boundary and must receive only audited or sanitised
+markup.
+
+Start with a restrictive policy such as `default-src 'self'; script-src
+'self'; style-src 'self' 'unsafe-inline'; object-src 'none'; base-uri 'self'`
+and tighten styles with nonces/hashes when your deployment supports them.
+Trusted Types can enforce the same application boundary around any code that
+produces trusted HTML. The devtools overlay is development-only and should not
+be imported in production entrypoints.
+
+## Sub-path deployments and `base`
+
+A deployment under a sub-path (`https://your.site/docs/`, GitHub
+Pages project URL, an admin panel mounted under `/admin/`, …) only
+requires two changes:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  base: "/docs/",                       // ← active prefix
+  plugins: [mado({ site: "https://your.site" })],
+});
+```
+
+Then make every internal anchor go through `routeUrl()` + `data-link`
+so the URL is correct under any base:
+
+```ts
+import { html, routeUrl } from "@madojs/mado";
+
+html`<a data-link href=${routeUrl("/")}>Home</a>`;     // → "/docs/"
+html`<a data-link href=${routeUrl("/guides/intro")}>Intro</a>`;
+```
+
+`mado release` honours `base` end-to-end:
+
+- captured snapshots load assets through `/docs/assets/...`;
+- sitemap URLs are `https://your.site/docs/...`;
+- canonicals and `og:url` include the prefix;
+- `mado preview` redirects bare `/` to `/docs/` and serves SPA
+  fallback under `/docs/<anything>`.
+
+On the production host:
+
+- **nginx** — keep `try_files $uri $uri/ /_mado/spa.html;` but mount the
+  app under the matching prefix (`location /docs/ { ... }`).
+- **Cloudflare Pages / Netlify** — `_redirects` is generated with the
+  base prefix already baked in.
+- **GitHub Pages (project site)** — set `base: "/<repo>/"` and use
+  the `gh-pages` deploy path; canonical URLs land at
+  `https://<user>.github.io/<repo>/...`.
 
-See also: [`02-project-layout.md`](./02-project-layout.md) for the
-`src/`/`public/`/`out/` model and [`03-static-bake.md`](./03-static-bake.md)
-for the SEO bake mechanics.
+See also: [`16-app-architecture.md`](./16-app-architecture.md) for the
+`src/` / `public/` / `out/` model and
+[`15-static-snapshots.md`](./15-static-snapshots.md) for the static
+snapshot mechanics.

package/docs/en/{15-error-handling.md → 21-error-handling.md}

@@ -24,7 +24,7 @@ For a specific page, `page({ errorView })` wins over the global route boundary.
 
 ```ts
 export default page({
-  load: async () => api.get("/reports"),
+  load: () => resource(() => "/reports", jsonFetcher<Report[]>()),
   errorView: (err) => html`<x-report-error .error=${err}></x-report-error>`,
   view: ({ data }) => html`<x-report .data=${data}></x-report>`,
 });
@@ -53,10 +53,10 @@ Validation errors belong in `useForm()`. Server errors from writes belong near
 the submit button.
 
 ```ts
-const form = useForm(
-  { email: { required: true, type: "email" } },
-  { validateAsync: (values) => api.validateUser(values) },
-);
+const form = useForm({
+  initial: { email: "" },
+  validate: (values, { signal }) => api.validateUser(values, { signal }),
+});
 
 const save = mutation((values) => api.post("/users", values), {
   invalidates: ["/api/users*"],
@@ -66,6 +66,7 @@ html`
   <form @submit=${form.onSubmit(async values => {
     await save.run(values);
   })}>
+    <input name="email" type="email" required @input=${form.onInput} />
     <button ?disabled=${() => form.validating() || form.submitting()}>
       Save
     </button>
@@ -97,4 +98,6 @@ component("x-online", (ctx) => {
 
 Log once at the boundary that owns recovery. Avoid logging the same failure in
 the API client, resource, page and component. The user should get one visible
-message and developers should get one useful console error.
+message and developers should get one structured diagnostic. Runtime records
+are visible in the devtools Timeline/Errors panel and as `mado:diagnostic`
+events; CLI automation can select `--log-format=json`.

package/docs/en/{14-testing.md → 22-testing.md}

@@ -48,7 +48,7 @@ Test behavior, not internal implementation details:
 - route guards, redirects, scroll/focus behavior, error boundaries;
 - forms: validation, async validation races, field arrays;
 - resources/mutations: cache keys, invalidation, lifecycle cleanup;
-- CLI flows: `mado release`, `mado bake`, `mado preview`.
+- CLI flows: `mado release`, `mado static`, `mado preview`.
 
 ## Browser smoke tests
 
@@ -74,9 +74,10 @@ services from framework tests. For app tests, make the API client injectable via
 npm run typecheck
 npm run build
 npm test
-npm run bake
+npm run release
 ```
 
-`mado release` runs the production path for an app: typecheck, Vite build,
-bake, compression and deploy helper files. In the framework repository,
-`npm run build` still emits `dist/src` for package tests and publishing.
+`mado release` runs the production path for an app: typecheck, Vite
+build, static-snapshot capture, compression and deploy helper files.
+In the framework repository, `npm run build` still emits `dist/src`
+for package tests and publishing.