@madojs/mado 0.11.0 → 0.12.0

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

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
@@ -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.
 
 ---
 
@@ -182,10 +184,57 @@ jobs:
 - **`/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`.
+
+## 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/ /index.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/{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.

package/docs/en/23-cookbook.md

@@ -0,0 +1,292 @@
+# Static snapshots cookbook
+
+> Concrete recipes for `mado static`. Concept and API in
+> [15-static-snapshots.md](./15-static-snapshots.md); failure modes and CI
+> guidance at the end of this file.
+
+Every recipe assumes:
+
+- Vite is the build transport (`@madojs/mado/vite` plugin).
+- A public origin is configured (`mado({ site })` or
+  `MADO_SITE=https://your.site mado release`).
+- `mado release` is the release command (it runs `vite build` →
+  `mado static` → writes deployment files into `out/`).
+
+## 1. Single static landing page
+
+```ts
+// src/pages/home.page.ts
+import { html, page } from "@madojs/mado";
+
+export default page({
+  static: true,
+  title: "Home",
+  head: () => ({
+    description: "Welcome to the Mado App.",
+  }),
+  view: () => html`
+    <main>
+      <h1>Mado App</h1>
+      <p>One component model. One page model. One release command.</p>
+    </main>
+  `,
+});
+```
+
+After `mado release`:
+
+```
+out/
+  index.html               ← captured snapshot
+  assets/...
+  _mado/spa.html           ← SPA fallback for other routes
+  sitemap.xml
+  _headers / _redirects
+```
+
+## 2. Blog with file-system content
+
+```ts
+// src/content/posts.ts
+import { readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export interface Post {
+  slug: string;
+  title: string;
+  date: string;
+  html: string;
+}
+
+const dir = resolve(process.cwd(), "content/posts");
+
+export function listPosts(): Post[] {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .map((file) => loadPost(file));
+}
+
+export function loadPost(file: string): Post {
+  // Replace with your real Markdown pipeline.
+  return JSON.parse(readFileSync(resolve(dir, file), "utf8"));
+}
+```
+
+```ts
+// src/pages/post.page.ts
+import { html, page } from "@madojs/mado";
+import { listPosts, loadPost, type Post } from "../content/posts";
+
+export default page<{ slug: string }, Post>({
+  static: {
+    paths: async () =>
+      listPosts().map((p) => ({ slug: p.slug })),
+    initialData: async ({ slug }) =>
+      loadPost(`${slug}.json`),
+  },
+  title: (_, seed) => seed?.title ?? "Post",
+  head: (_, seed) => ({
+    description: seed?.title,
+  }),
+  view: (ctx) => html`
+    <article>
+      <h1>${ctx.data.title}</h1>
+      <time>${ctx.data.date}</time>
+      ${html([ctx.data.html] as unknown as TemplateStringsArray)}
+    </article>
+  `,
+});
+```
+
+Output: one `out/posts/<slug>/index.html` per post, each carrying its
+own canonical and `og:url`.
+
+> File-system reads happen during *discovery* (Node side). They never
+> ship in the client bundle. The captured *initial data* does ship —
+> keep it free of secrets.
+
+## 3. Product catalogue from JSON
+
+```ts
+import { html, page } from "@madojs/mado";
+import products from "../content/products.json" with { type: "json" };
+
+interface Product {
+  slug: string;
+  name: string;
+  price: number;
+}
+
+export default page<{ slug: string }, Product>({
+  static: {
+    paths: async () => products.map((p) => ({ slug: p.slug })),
+    initialData: async ({ slug }) =>
+      products.find((p) => p.slug === slug)!,
+  },
+  title: (_, seed) => seed?.name ?? "Product",
+  view: (ctx) => html`
+    <main>
+      <h1>${ctx.data.name}</h1>
+      <p>$${ctx.data.price.toFixed(2)}</p>
+    </main>
+  `,
+});
+```
+
+## 4. Documentation site
+
+A docs site is typically:
+
+- Many static guides keyed by `slug`.
+- A few hand-written landing pages.
+- One SPA route for the search modal (kept dynamic).
+
+```ts
+// src/app.routes.ts
+import { routes } from "@madojs/mado";
+import home from "./pages/home.page";
+import guide from "./pages/guide.page";
+import search from "./pages/search.page";
+
+export const manifest = {
+  "/":             home,                 // static
+  "/guides/:slug": guide,                // dynamic static
+  "/search":       search,               // SPA-only (no `static` field)
+  "*":             () => import("./pages/not-found.page"),
+};
+
+export default routes(manifest);
+```
+
+Only `home` and `guide` are captured. `/search` is served from the
+SPA fallback (`_mado/spa.html`).
+
+## 5. Build-time API call
+
+```ts
+import { html, page } from "@madojs/mado";
+
+interface Release { tag: string; date: string }
+
+export default page<{ tag: string }, Release>({
+  static: {
+    paths: async () => {
+      const res = await fetch("https://api.github.com/repos/madojs/mado/releases");
+      const list = (await res.json()) as Release[];
+      return list.map((r) => ({ tag: r.tag }));
+    },
+    initialData: async ({ tag }) => {
+      const res = await fetch(
+        `https://api.github.com/repos/madojs/mado/releases/tags/${tag}`,
+      );
+      return (await res.json()) as Release;
+    },
+  },
+  title: (_, seed) => `Release ${seed?.tag ?? ""}`,
+  view: (ctx) => html`
+    <article>
+      <h1>${ctx.data.tag}</h1>
+      <time>${ctx.data.date}</time>
+    </article>
+  `,
+});
+```
+
+Network calls in `paths()` / `initialData()` are perfectly fine — they
+run in the discovery Node process, not in the browser at capture.
+
+## 6. Sub-path deployment
+
+`mado release` honours Vite's `base`. Configure it once:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  base: "/docs/",
+  plugins: [mado({ site: "https://your.site" })],
+});
+```
+
+Every link in your app must go through `routeUrl()` so it picks up
+the prefix:
+
+```ts
+import { html, routeUrl } from "@madojs/mado";
+
+html`<a data-link href=${routeUrl("/guides/intro")}>Intro</a>`;
+html`<a data-link href=${routeUrl("/")}>Home</a>`;     // → "/docs/"
+```
+
+Captured canonicals and `og:url` will be `https://your.site/docs/...`.
+
+## 7. SPA-only fallback
+
+Any route that does NOT declare `static` is served from
+`out/_mado/spa.html`. That is the right place for authenticated
+zones, search, dashboards, admin tools.
+
+```ts
+// src/pages/app.page.ts
+import { html, page } from "@madojs/mado";
+
+// No `static` field — SPA only.
+export default page({
+  title: "App",
+  view: () => html`<x-app-shell></x-app-shell>`,
+});
+```
+
+The fallback is automatically marked `noindex` so search engines do
+not capture the SPA shell.
+
+## 8. Failure modes
+
+`mado static` fails the snapshot (non-zero exit) when:
+
+- A script, stylesheet, custom element or tracked `resource()` fetch
+  fails.
+- A custom element is referenced in the rendered DOM but never
+  defined.
+- A page declares `static: true` on a route with `:params` but no
+  `paths()`.
+- Two pages produce the same generated URL.
+- Any guard runs on a static route or its layout chain.
+- `initialData()` returns a value that is not strictly JSON-serialisable
+  (Date, Map, Set, class instance, `undefined` field, NaN, Infinity,
+  cycles, non-plain prototypes). The validator points at the bad
+  field by path.
+
+A failed snapshot leaves the previous `out/` untouched: capture
+writes to a temp tree and only promotes once every route survived.
+
+## 9. CI guidance
+
+```yaml
+# .github/workflows/ci.yml — extract
+- name: Install Playwright Chromium
+  run: node node_modules/playwright-core/cli.js install --with-deps chromium
+
+- name: Release smoke
+  env:
+    MADO_REQUIRE_BROWSER: "1"
+    MADO_SITE: "https://your.site"
+  run: npm run release
+```
+
+`MADO_REQUIRE_BROWSER=1` forces `mado static` to fail loudly if no
+Chromium is resolvable (instead of silently producing a SPA-only
+build).
+
+## 10. Quick checklist before pushing
+
+- [ ] `mado({ site })` set (or `MADO_SITE` / `--base-url`).
+- [ ] Every static page declares `static: true | { paths, initialData }`.
+- [ ] No `paths()` / `initialData()` reads secrets.
+- [ ] No static page is behind a guard.
+- [ ] Internal links go through `routeUrl()` + `data-link`.
+- [ ] `mado release` succeeds locally with Playwright Chromium
+      installed.
+- [ ] `mado preview` serves the artefact correctly.

package/docs/en/{18-api-freeze-map.md → 30-api-freeze-map.md}

@@ -30,14 +30,16 @@ These names are public and protected by SemVer once v1 ships:
   `ref`, `classMap`, `styleMap`.
 - Components and CSS: `component`, `css`, `cssVars`.
 - Routing and pages: `routes`, `router`, `page`, `layout`,
-  `navigate`, `queryParam`, `prefetchPath`.
+  `navigate`, `queryParam`, `prefetchPath`, `routeUrl`, `appBase`.
 - Data: `resource`, `mutation`, `invalidate`, `jsonFetcher`, `HttpError`.
 - Forms: `useForm`.
 - Head and persistence: `applyHead`, `persisted`.
 - Context: `createContext`, `provide`, `inject`.
 - Advanced lifecycle helpers: `createLifecycle`, `runInLifecycle`,
   `getCurrentLifecycle`.
-- Public TypeScript types exported from `@madojs/mado`.
+- Public TypeScript types exported from `@madojs/mado`, including
+  `StaticPageConfig` (the `static: true | { ... }` option on `page()`)
+  and `HeadMeta` (the head metadata shape returned by pages).
 
 ## Internal or unstable
 
@@ -48,7 +50,14 @@ These are not public API:
 - Template parser/binding internals such as `html/parser.js`,
   `html/bindings.js`, `ChildState`, and `EachEntry`.
 - Router implementation modules such as `router/match.js`,
-  `router/navigation.js`, and `router/manifest.js`.
+  `router/navigation.js`, `router/manifest.js`, and `router/base.js`.
+- Base-path helpers other than `routeUrl` / `appBase`: `normalizeBase`,
+  `stripBase` and `withBase` are intentionally not exported from
+  `@madojs/mado`. Use `routeUrl()` for `<a href>` values and `appBase`
+  if you need the raw active prefix.
+- The static snapshot pipeline (`scripts/static.mjs`, the
+  `_mado/build.json` bridge, the temp capture server). `mado static` is
+  a CLI command; its internals can change between minor versions.
 - Diagnostics internals and all `_testHooks`.
 - Exact generated bundle text, chunk names, and internal file layout.
 

package/docs/en/{20-v1-stability.md → 32-v1-stability.md}

@@ -8,8 +8,8 @@ copy, or diagnostic string is frozen forever.
 
 Read this together with:
 
-- [API freeze map](./18-api-freeze-map.md)
-- [Reactivity ordering](./19-reactivity-ordering.md)
+- [API freeze map](./30-api-freeze-map.md)
+- [Reactivity ordering](./31-reactivity-ordering.md)
 
 ## Stable under SemVer
 
@@ -25,7 +25,7 @@ After v1, Mado treats these as SemVer-protected:
   teardown for same-tick moves, cleanup via `ctx.onDispose`.
 - Router/page/resource/form contracts documented in the English docs.
 - CLI command names and broad command intent (`build`, `dev`, `release`,
-  `bake`, `preview`, `init`, `new`).
+  `static`, `preview`, `init`, `new`).
 
 Breaking these requires a major version.