@madojs/mado 0.11.1 → 0.12.0

package/docs/architecture/adr/0001-browser-static-snapshots.md

@@ -0,0 +1,132 @@
+# ADR 0001 — Browser-rendered static snapshots
+
+**Status:** Accepted (0.12.0)
+**Date:** 2026-06-22
+
+## Context
+
+Mado started as a calm browser-native SPA framework for internal tools
+and admin panels. Two new product requirements made that scope too
+narrow:
+
+1. Public-facing surfaces (landing pages, docs sites, product pages)
+   need search engines and social preview bots to see a fully rendered
+   document on first request, without running JavaScript.
+2. The same component model that powers the live SPA must produce that
+   document — we do not want a second component runtime, a hydration
+   protocol, or a server renderer.
+
+The conventional answers (Next/Nuxt SSR, Astro, Eleventy, Lit SSR,
+Solid Start, …) each ship at least one of:
+
+- a separate component model for the server,
+- a hydration boundary that introduces a second source of truth,
+- a build-time JSX/Vue/Svelte compiler,
+- a Node runtime in production.
+
+Mado is positioned as "calm native-first": we cannot adopt any of
+those without breaking the positioning.
+
+## Decision
+
+Adopt **browser-rendered static snapshots with Declarative Shadow
+DOM** as the canonical SEO/static path:
+
+1. `mado release` runs `vite build`, then opens each declared static
+   route in a real headless Chromium pointed at the build output, and
+   serialises the rendered document — including the Shadow DOM as
+   Declarative Shadow DOM — into one HTML file per route under
+   `out/`.
+2. The client runtime treats the snapshot as an **atomic takeover**
+   target: a Mado component instance reattaches to the existing host
+   in place, with no second tree, no hydration, no diff.
+3. Routes that are not declared `static` stay SPA-only and are served
+   through the `_mado/spa.html` fallback the same way they were
+   before.
+4. Vite's `base` is the single source of truth for the public URL
+   prefix; the runtime reads it from `import.meta.env.BASE_URL`, the
+   CLI reads it from the build bridge (`_mado/build.json`) for
+   sitemap / canonical / preview, and the build bridge is dropped
+   before the artifact ships.
+5. Build-time seeds for static routes are strict `JsonValue` only,
+   validated by a path-aware walker so a `Date`, `Map`, `undefined`
+   field or cycle fails the build instead of silently corrupting the
+   first client render.
+
+## Alternatives rejected
+
+- **SSR (Next / Nuxt / Solid Start).** Ships a second component model
+  and a Node production runtime. Hydration boundary is the largest
+  source of recurring bug classes in the ecosystem. Mado's
+  positioning rejects both.
+
+- **Hydration via an island / partial hydration model (Astro,
+  Marko).** Splits the component graph into "static" and "interactive"
+  sub-graphs with framework-specific compilers. Adds a second mental
+  model for a public-site benefit that DSD already provides.
+
+- **Author-time prerendering with `linkedom`/`jsdom`.** Cannot run
+  Shadow DOM, adoptedStyleSheets, layout, or any browser API.
+  Snapshots would diverge from what the browser actually renders.
+
+- **External prerender service (Prerender.io and friends).** Adds an
+  external dependency, runs on each request, and Mado has no canonical
+  way to detect when to flush its cache.
+
+- **Embed a Node runtime that pretends to be a browser.** Same
+  divergence problem as `linkedom`, plus a custom DOM polyfill we
+  would have to maintain forever.
+
+## Consequences
+
+- A compatible Chromium is required at **release time** (not at
+  request time, not in production) for projects that declare any
+  static route. `mado release` documents how to install one
+  (Playwright-managed Chromium, system Chrome, or operator-provided
+  path) and CI gates the round-trip with `npx playwright install
+  --with-deps chromium` plus `MADO_REQUIRE_BROWSER=1`.
+
+- `page.static.paths()` and `page.static.initialData()` must be
+  **browser-safe and secret-free**: they execute during the discovery
+  pass AND remain in the client bundle. The strict `JsonValue`
+  validator catches the common shapes that would otherwise leak.
+
+- The framework now has a documented HTTP policy for snapshot capture:
+  documents, scripts, stylesheets and tracked resources are fatal;
+  favicon-class endpoints are ignored; fonts and paint frames are
+  quality hints with bounded timeouts.
+
+- The product surface widens from "internal tools / admin panels" to
+  "sites and apps". Marketing copy, package metadata, GitHub topics
+  and the default starter all change accordingly. The previous
+  modular reference architecture is preserved as
+  `mado init --starter modular` for long-lived business apps.
+
+## Known limits
+
+- Static routes cannot use `Date`, `Map`, `Set`, class instances,
+  `undefined` values, cycles, or non-finite numbers in their
+  `initialData`. The validator gives a path-aware error.
+
+- `mado release` snapshots are deterministic only in a pinned
+  environment (same Chromium revision, same source tree). We document
+  that determinism contract; reproducing it across CI vendors is the
+  operator's responsibility.
+
+- Static `paths()` runs at build time. We do not currently support
+  incremental re-snapshot from a webhook; a static-content change
+  requires a fresh release.
+
+- Public client-only state inside a static route (canvas, media
+  controllers, transient timers) survives takeover but is not part of
+  the snapshot — it materialises only after JS executes.
+
+---
+
+## Original implementation plan (for history)
+
+The remainder of this document is the original implementation plan
+that drove the work up to 0.12.0. It is preserved verbatim for
+historical context.
+
+---

package/docs/en/00-the-mado-way.md

@@ -106,7 +106,7 @@ belongs in `*.service.ts`.
 
 ### One way to declare routes
 
-See [`01-routing.md`](./01-routing.md).
+See [`12-routing.md`](./12-routing.md).
 
 ## What we do NOT do
 

package/docs/en/01-quickstart.md

@@ -0,0 +1,183 @@
+# Quickstart
+
+> Goal: have a Mado app running locally, edited from VS Code, and shipped to
+> a static host — in under 10 minutes.
+
+---
+
+## 1. Scaffold
+
+Mado 0.12 ships with two starters: the **universal** starter (default) and
+the **modular** reference architecture.
+
+```bash
+# Universal starter (default) — ~15 files, one shared component
+npm exec --package @madojs/mado -- mado init my-app
+
+# Modular reference starter — auth shell, guarded zones, billing module
+npm exec --package @madojs/mado -- mado init my-app --starter modular
+
+cd my-app
+npm install
+```
+
+What you get either way:
+
+- exactly one runtime dependency: `@madojs/mado`;
+- `vite.config.ts` with `mado()` from `@madojs/mado/vite`;
+- `src/main.ts` mounting the router into `#app`;
+- `src/app.routes.ts` (a default export + a named `manifest` export);
+- a `package.json` whose scripts wrap the Mado CLI.
+
+---
+
+## 2. The dev loop
+
+```bash
+npm run dev        # Vite dev server, fast HMR for templates/styles
+npm run typecheck  # tsc --noEmit
+npm run test       # node --test (if your project has tests)
+npm run build      # SPA build only (out/ without snapshots)
+npm run release    # typecheck + vite build + static snapshots + deploy files
+npm run preview    # serve out/ like a real static host
+```
+
+`mado release` is the single command you ship. It produces one folder,
+`out/`, that you can `rsync`/upload to any static host:
+
+```bash
+npm run release
+rsync -avz out/ user@server:/var/www/my-app/
+```
+
+See [20-deployment.md](./20-deployment.md) for nginx / Cloudflare Pages /
+GitHub Pages / S3 recipes.
+
+---
+
+## 3. Your first page
+
+Two primitives, that's it (see [10-pages-and-components.md](./10-pages-and-components.md)
+for the full mental model):
+
+- **`page()`** — a route. Lives at a URL. Renders in light DOM. Has
+  `title` / `head` / `load` / `view` / optional `static`.
+- **`component()`** — a reusable `<x-tag>`. Shadow DOM by default.
+
+```ts
+// src/pages/home.page.ts
+import { html, page } from "@madojs/mado";
+
+export default page({
+  title: "Home",
+  head: () => ({ description: "Hello from Mado" }),
+  view: () => html`<h1>Hello, Mado</h1>`,
+});
+```
+
+```ts
+// src/app.routes.ts
+import { routes } from "@madojs/mado";
+
+export const manifest = {
+  "/":  () => import("./pages/home.page"),
+  "*":  () => import("./pages/not-found.page"),
+};
+
+export default routes(manifest);
+```
+
+Always export both `default` (for the router) and `manifest` (so
+`mado static` can discover bakeable pages).
+
+Internal links must be base-aware:
+
+```ts
+import { routeUrl } from "@madojs/mado";
+
+html`<a data-link href=${routeUrl("/about")}>About</a>`;
+```
+
+`data-link` lets the router intercept the click — including across
+Shadow DOM. `routeUrl()` resolves against `import.meta.env.BASE_URL`,
+so the same code works whether your app is hosted at `/` or at
+`/docs/`.
+
+---
+
+## 4. IDE setup
+
+Out of the box `html` and `css` are tagged-template strings. TypeScript
+and most editors don't highlight them by default. The lit ecosystem's
+tools work because Mado uses the same tag names and binding shapes.
+
+### VS Code (recommended)
+
+1. **Extensions → install [lit-plugin](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin)** (by `runem`).
+2. Import `html` / `css` directly — no rename:
+
+   ```ts
+   import { html, css } from "@madojs/mado";
+   ```
+
+3. (Optional) Recommended settings for Mado in `.vscode/settings.json`:
+
+   ```json
+   {
+     "lit-plugin.rules": {
+       "no-unknown-attribute": "off",
+       "no-incompatible-type-binding": "off"
+     }
+   }
+   ```
+
+   `no-incompatible-type-binding: off` is needed because Mado bindings
+   accept signals (`Signal<T>`) where the plugin expects raw values.
+
+You get: HTML/CSS highlighting inside templates, attribute/event
+auto-complete, go-to-definition for custom elements, typo checking.
+
+### WebStorm / IntelliJ
+
+Native support for lit-style template literals since 2021. Nothing to
+install. If highlighting is missing, restart the TS server.
+
+### Neovim / Helix
+
+```bash
+npm install -g lit-html-server
+```
+
+Wire it into your LSP config (`lit_html` in `lspconfig`).
+
+### Optional extras
+
+- **Custom Elements Manifest** for auto-complete on your own
+  `<x-*>` components: `npx cem analyze --globs "src/**/*.ts"`.
+- **Prettier 3+** formats `html`/`css` template literals via
+  `embeddedLanguageFormatting: "auto"` (default).
+- **eslint-plugin-lit** + **eslint-plugin-wc** provide
+  template-aware lint rules. Not required.
+
+### What does NOT work today
+
+- Type-checking of signal bindings: `<input .value=${count}>` is
+  flagged because the plugin expects a string, not a `Signal<number>`.
+  Suppress with `// @ts-expect-error` or the settings override above.
+- The `each()` directive is recognised as a plain function — no
+  special-case checking inside.
+
+Mado works without any IDE plugin — the templates remain valid TS,
+they just won't be syntax-highlighted as HTML.
+
+---
+
+## 5. Where to go next
+
+- [10 — Pages and components](./10-pages-and-components.md) — the one rule.
+- [11 — Templates and signals](./11-templates-and-signals.md) — binding shapes.
+- [12 — Routing](./12-routing.md) — manifest, layouts, guards, prefetch.
+- [13 — Data](./13-data.md) — `resource()` / `mutation()` / auth.
+- [14 — Forms](./14-forms.md) — `useForm()` + Shadow DOM input recipes.
+- [15 — Static snapshots](./15-static-snapshots.md) — SEO without SSR.
+- [16 — App architecture](./16-app-architecture.md) — the modular starter, ESLint boundaries.

package/docs/en/10-pages-and-components.md

@@ -0,0 +1,271 @@
+# Pages and Components
+
+> Mado has exactly two primitives. You decide which one to use by
+> looking at the URL bar, not at the DOM tree.
+
+This is the document that removes the most common Mado design
+question. By the end of it you should never again have to think
+"should this be a page or a component?", "should this be Shadow DOM
+or Light DOM?", or "how do I share styles across components?". You
+just write the thing.
+
+---
+
+## The one rule
+
+| If the unit is…                                          | Use         |
+| -------------------------------------------------------- | ----------- |
+| Something the URL points to (a route, a layout, a 404)   | `page()`    |
+| Something you would copy-paste under multiple URLs       | `component()` |
+
+That's it. Pages are the URLs your app exposes. Components are
+re-usable Web Components.
+
+A page can render any number of components. A component can never
+participate in routing. Pages live in `src/pages/` (universal
+starter) or in `src/modules/<name>/pages/` (modular starter).
+Components live in `src/components/` or `src/modules/<name>/components/`.
+
+You **never** wrap a page in `component()` — that breaks form
+participation, shared CSS and the static snapshot capture. You
+**never** route to a `component()` — only `page()` shows up in the
+router manifest.
+
+---
+
+## You write the same TypeScript either way
+
+```ts
+import { html, page, signal } from "@madojs/mado";
+
+// PAGE — has a URL, owns route + load + head + view
+export default page({
+  title: "Counter",
+  view: () => {
+    const n = signal(0);
+    return html`
+      <main>
+        <h1>Counter</h1>
+        <button @click=${() => n.set(n() + 1)}>Clicks: ${n}</button>
+      </main>
+    `;
+  },
+});
+```
+
+```ts
+import { component, css, html, signal } from "@madojs/mado";
+
+// COMPONENT — reusable, has no URL
+component(
+  "x-counter",
+  () => {
+    const n = signal(0);
+    return () => html`
+      <button @click=${() => n.set(n() + 1)}>Clicks: ${n}</button>
+    `;
+  },
+  { styles: css`button { padding: .5rem 1rem; }` },
+);
+```
+
+Same signals. Same `html\`\`` templates. Same lifecycle. Same data
+model (`resource()`, `mutation()`, `useForm()`, `effect()`). The
+only thing that changes is *where* the DOM lives.
+
+---
+
+## What changes under the hood
+
+| Property                                       | `page()`     | `component()` (default)        |
+| ---------------------------------------------- | ------------ | ------------------------------ |
+| DOM location                                   | Light DOM    | Open Shadow DOM                |
+| Sees global CSS (`shell.css`, `content.css`)   | Yes          | No (Shadow boundary)           |
+| Can use `<slot>`                               | No (uses `child`) | Yes                       |
+| Participates in a parent `<form>`              | Yes          | Only via `attachInternals()` or `shadow:false` |
+| Is captured by `mado static`                   | If `static: true \| { ... }` | Yes (DSD serialised) |
+| Has a hyphenated custom-element tag            | No           | Yes (`x-foo`, `my-bar`)        |
+| Owns its own CSS isolation                    | No           | Yes (via `css\`\``)            |
+
+That is the entire decision matrix. Anything beyond it is detail.
+
+---
+
+## `{ shadow: false }` — the only escape hatch you need
+
+Sometimes a custom element MUST live in the light DOM. Two real
+cases:
+
+1. **Form participation without `attachInternals()`.** A custom
+   input that should be submitted as part of a regular `<form>` and
+   whose author does not want to wire up `ElementInternals`.
+2. **Host-level CSS that the document must address by tag name**
+   (rare; usually solved by passing class attributes instead).
+
+For both, declare `{ shadow: false }`:
+
+```ts
+component(
+  "x-custom-input",
+  () => () => html`<input name="email" />`,
+  { shadow: false, styles: css`x-custom-input input { width: 100%; }` },
+);
+```
+
+That is the *only* place this option is justified. If you reach for
+`shadow: false` because you want to share document-level CSS classes,
+**stop** — you wanted a `page()`, not a component.
+
+Page-shaped wrappers (layouts, route shells) are written with
+`page({ view: ({ child }) => ... })`. They are not components.
+
+---
+
+## Decision table
+
+| You are writing…                              | Reach for                                     |
+| --------------------------------------------- | --------------------------------------------- |
+| A landing page                                | `page({ static: true, view })`                |
+| A dynamic SEO page (`/product/:slug`)         | `page({ static: { paths, initialData } })`    |
+| An app screen behind auth                     | `page({ view })` (no `static`)                |
+| A shared shell that wraps several pages       | `page({ view: ({ child }) => html\`...\` })`  |
+| A reusable button / badge / card / modal     | `component("x-foo", setup, { styles })`       |
+| A custom form input                          | `component("x-input", setup, { shadow: false })` |
+| A small inline render helper (no state)       | a plain `(arg) => html\`...\`` function      |
+
+When in doubt, ask: **does this thing have a URL?** Yes → page.
+No → component.
+
+---
+
+## Anti-patterns
+
+These are the four mistakes Mado generators and AI assistants tend
+to produce. Avoid them.
+
+### 1. Page inside a `component()`
+
+```ts
+// ❌ Don't
+component(
+  "x-home-page",
+  () => () => html`<h1>Home</h1><p>...</p>`,
+);
+
+// ✅ Do
+export default page({
+  static: true,
+  title: "Home",
+  view: () => html`<h1>Home</h1><p>...</p>`,
+});
+```
+
+Why: the page becomes invisible to the router, the static snapshot
+pipeline cannot find it, and shared CSS (`content.css`) does not
+cross the Shadow boundary.
+
+### 2. Component used as a route
+
+```ts
+// ❌ Don't
+import "./components/billing-screen.component.js";
+const manifest = { "/billing": () => html`<x-billing-screen/>` };
+
+// ✅ Do
+import billing from "./pages/billing.page.js";
+const manifest = { "/billing": billing };
+```
+
+Why: the router gives you `page.head()`, `page.load()`, the static
+snapshot pipeline, the `data-mado-head` lifecycle and the seed
+contract. A component does not.
+
+### 3. `shadow: false` to "fix" CSS in a route layout
+
+```ts
+// ❌ Don't — this is a page wearing the wrong hat
+component(
+  "x-app-shell",
+  () => ({ child }) => html`<header>...</header><main>${child}</main>`,
+  { shadow: false, styles: css`...` },
+);
+
+// ✅ Do
+export default page({
+  view: ({ child }) => html`<header>...</header><main>${child}</main>`,
+});
+```
+
+Why: light-DOM components do not get the route `child`, are not
+recognised by `layout()`, and the manifest cannot wrap them.
+
+### 4. Route-id state in layout view locals
+
+```ts
+// ❌ Don't — `current` is shared across every page rendered by this layout
+const current = signal<User | null>(null);
+export default page({
+  view: ({ child }) => {
+    effect(() => loadUser(routePath()).then(current.set));
+    return html`<x-shell .user=${current}>${child}</x-shell>`;
+  },
+});
+
+// ✅ Do — put the resource in the page that needs it
+const user = resource(() => `/api/users/${userId()}`, jsonFetcher<User>());
+```
+
+Layouts are stateless wrappers. Per-page state belongs in the page
+itself or in a `resource()` whose key is the page's identity.
+
+---
+
+## What about styles?
+
+- `page()` lives in the light DOM. Use `content.css` / `shell.css`
+  from `src/styles/` (universal starter) or `src/shared/styles/`
+  (modular starter). Class selectors work normally.
+- `component()` carries its own `css\`\``. CSS custom properties
+  (`--accent`, `--bg`) cross the Shadow boundary; class selectors
+  from the document do not.
+- The shared design tokens (colours, spacing, type) live in
+  `tokens.css`. They are CSS custom properties and reach both pages
+  and components through `var(--...)`.
+
+For the long form on style boundaries, see
+[20-deployment.md](./20-deployment.md) (production tuning) and the
+starter README files.
+
+---
+
+## What about routing and links?
+
+Internal navigation is base-aware. Always use `routeUrl()` and
+`data-link`:
+
+```ts
+import { html, routeUrl } from "@madojs/mado";
+
+html`<a data-link href=${routeUrl("/billing/invoices")}>Invoices</a>`;
+html`<a data-link href=${routeUrl("/")}>Home</a>`;     // → "/mado/" under base
+```
+
+`data-link` opts the anchor into SPA navigation. A bare `<a href>`
+performs a full document load — that is intentional for foreign
+links and downloads. The router intercepts links inside Shadow DOM
+too (it uses `event.composedPath()`).
+
+Full router contract: [12-routing.md](./12-routing.md).
+
+---
+
+## Further reading
+
+- [11-templates-and-signals.md](./11-templates-and-signals.md) — the
+  `html\`\`` parser, signals, `each`, reactive bindings.
+- [12-routing.md](./12-routing.md) — `routes()`, layouts, guards,
+  `routeUrl`, `navigate`, prefetch.
+- [15-static-snapshots.md](./15-static-snapshots.md) — when to mark
+  a page `static: true`.
+- [14-forms.md](./14-forms.md) — `useForm()` + the only Shadow DOM
+  case where `shadow: false` is right.