@madojs/mado 0.11.1 → 0.13.0

package/AGENTS.md

@@ -3,14 +3,20 @@
 > This file is read by AI agents in IDEs (Cursor, Cline, Copilot, Continue, etc.).
 > Goal: prevent them from generating React-like code where Mado should be used.
 >
-> / `TODO.md` unless the user explicitly resumes that tracker.
+> Skip `TODO.md` unless the user explicitly resumes that tracker.
 
 ## Project at a glance
 
-- **Mado** — a calm browser-native SPA framework for internal tools, admin panels and business apps.
+- **Mado** — a calm native-first web framework for both static sites
+  and live SPAs. One Web Component model, one page model, one release
+  command.
+- Current development release: **0.13.0**.
 - Built on Web Components + signals + tagged-template `html`.
-- Zero runtime dependencies. Generated apps use dev tooling (`typescript`,
-`vite`, `linkedom`) for dev/build/bake/release.
+- **Vite is the canonical transport** for development, build and the
+  static snapshot pipeline. Generated apps depend on `typescript`,
+  `vite` and `playwright-core` (the last only for `mado release`,
+  which captures real Chromium-rendered HTML).
+- Zero runtime dependencies (Vite is dev/build tooling, not bundled).
 - Small TypeScript core in `src/`; production size budgets are enforced in CI.
 
 ## HARD RULES — violation = bug
@@ -295,8 +301,9 @@ const { register, handleSubmit } = useForm({ resolver: yupResolver(schema) });
 import { useForm } from "@madojs/mado";
 
 const f = useForm({
-  email: { required: true, type: "email" },
-  age: { required: true, type: "number", min: 18 },
+  initial: { email: "", age: "" as number | "" },
+  validate: async (values, { signal }) =>
+    await api.valid(values, { signal }) ? null : { email: "Unavailable" },
 });
 
 html`
@@ -305,7 +312,8 @@ html`
       await api.save(v);
     })}
   >
-    <input name="email" @input=${f.onInput} @blur=${f.onBlur} />
+    <input name="email" type="email" required @input=${f.onInput} @blur=${f.onBlur} />
+    <input name="age" type="number" min="18" @input=${f.onInput} />
     ${() =>
       f.touched().email && f.errors().email
         ? html`<small>${f.errors().email}</small>`
@@ -315,7 +323,8 @@ html`
 `;
 ```
 
-Custom validation — `validate: (values) => ({ field: 'error message' } | null)`.
+HTML owns native constraints. Custom validation receives an `AbortSignal`.
+Use `setField`, not a schema/field-array abstraction.
 
 ### 11. Styles — `css\`\`` + Shadow DOM by default
 
@@ -362,6 +371,10 @@ component("x-child", ({ host }) => {
 });
 ```
 
+This interoperates through the Web Components `context-request` protocol.
+Providers may expose function values; only real Mado Signals are treated as
+reactive sources. Subscriptions are removed with the active lifecycle.
+
 ### 13. Component registration imports
 
 Custom elements are global after registration, but the browser never imports a
@@ -384,16 +397,54 @@ Rules:
 - Tiny leaf components used everywhere → importing in `main.ts` is acceptable.
 - Do **not** bulk-import every component "just in case".
 
-### 14. Bake — meta shell, not SSR/SSG runtime
+### 14. Static snapshots — browser-rendered, not SSR/SSG
+
+`mado static` (normally invoked through `mado release`) captures real
+HTML by navigating each page in a headless Chromium and serialising
+the resulting DOM, including the Shadow DOM through Declarative Shadow
+DOM (DSD). On first paint the live SPA **atomically replaces** the
+static tree — there is no hydration protocol, no node reconciliation
+and no per-attribute diffing.
+
+A page opts in by declaring `static` on `page({ ... })`:
+
+```ts
+// Static landing page
+export default page({
+  static: true,
+  title: "Home",
+  head: () => ({ description: "Public landing" }),
+  view: () => html`<main><h1>Hello</h1></main>`,
+});
+
+// Dynamic static route
+export default page({
+  static: {
+    paths: async () => [{ slug: "alpha" }, { slug: "beta" }],
+    initialData: async ({ slug }) => loadGuide(slug),
+  },
+  title: ({ slug }) => `Guide: ${slug}`,
+  view: (ctx) => html`<article>${ctx.data}</article>`,
+});
+```
 
-`mado bake` is a static meta-shell/prerender pass for SEO and first paint. It is
-not SSR with hydration and not a Next-style SSG runtime.
+Important constraints:
 
-- Baked HTML must be deterministic from `params`, `bake.data`, and plain values.
-- Do not rely on browser-only effects, timers, relative `fetch`, or keyed
-  runtime directives such as `each()` during bake.
-- Use `page({ head, bake })` for meta/JSON-LD/sitemap data; render dynamic,
-  personalized, real-time, or auth-dependent content in the client SPA.
+- Static pages cannot use guards (route- or layout-level) — they are
+  public by definition.
+- `paths()` and `initialData()` run at discovery AND ship in the
+  client bundle. Keep them browser-safe; never read secrets.
+- Wildcard routes (`*`) cannot be static.
+- The `static` discovery uses Vite SSR as a control plane only;
+  nothing is rendered in Node. The actual capture happens in
+  headless Chromium.
+
+<!-- docs-lint:allow-legacy-mention -->
+There is no `bake`, no `bake.paths`, no `bake.data`, no
+`bake.revalidate`, no `npm run bake`, no `linkedom` renderer, no
+"meta-shell". Those names refer to a removed system; do not generate
+them. If you see them in older docs, treat them as obsolete.
+<!-- /docs-lint:allow-legacy-mention -->
 
 ## SOFT GUIDELINES — recommended, but not critical
 
@@ -409,19 +460,52 @@ not SSR with hydration and not a Next-style SSG runtime.
 
 ## Project structure
 
+Two official starters target the same Mado runtime:
+
 ```
+# universal starter (default — `mado init my-app`)
+src/
+├── main.ts
+├── app.routes.ts
+├── pages/         ← one *.page.ts per route, light DOM
+├── components/    ← reusable Web Components (Shadow DOM)
+├── content/       ← static content (guides, etc.)
+└── styles/
+
+# modular starter (`mado init my-app --starter modular`)
 src/
-├── main.ts           ← entry: mount to #app
-├── app.routes.ts     ← app map, exports `manifest` + default routes(...)
-├── layouts/          ← app-zone layout modules (`page({ child })`)
-├── shared/           ← ui, http, lib, styles
-└── modules/          ← bounded contexts with pages/data/api/services
+├── main.ts
+├── app.routes.ts
+├── layouts/       ← stateless app-zone shells (`page({ child })`)
+├── shared/        ← ui, http, lib, styles
+└── modules/       ← bounded contexts with pages/data/api/services
 ```
 
+The modular starter ships a dev-only mock API in `vite.config.ts`
+(`/api/auth/*`, `/api/billing/*`). Disable with `MADO_MOCK_API=0`
+or remove the `devApiMock()` plugin before pointing at a real backend.
+
+## Internal links — always `routeUrl()`
+
+Vite's `base` flows automatically into `appBase` and `routeUrl()`. App
+code MUST use `routeUrl()` for every internal anchor so the URL stays
+correct under `/`, `/mado/` or any sub-path deployment, and MUST opt
+in with `data-link` for SPA navigation:
+
+```ts
+import { routeUrl } from "@madojs/mado";
+
+html`<a data-link href=${routeUrl("/users/42")}>User</a>`;
+html`<a data-link href=${routeUrl("/")}>Home</a>`;        // → "/mado/" under base
+```
+
+`navigate("/users/42")` for programmatic navigation. Both accept route
+paths (no base) and apply the active base internally.
+
 ## App architecture for LLM
 
 When generating an app, prefer the blessed production shape from
-`docs/en/10-app-architecture.md` and the `starters/default/` example:
+`docs/en/16-app-architecture.md` and the `starters/default/` example:
 
 - `src/main.ts` mounts `routesApi.view` and imports only global styles,
   providers, and tiny shared components.
@@ -440,18 +524,18 @@ When generating an app, prefer the blessed production shape from
 
 | Question                         | File                             |
 | -------------------------------- | -------------------------------- |
-| How does reactivity work?        | `src/signal.ts` (283 lines)      |
+| How does reactivity work?        | `src/signal.ts`                  |
 | How are templates parsed?        | `src/html/`                      |
 | How does the router work?        | `src/router/`                    |
-| How does resource + cache work?  | `src/resource.ts` (297 lines)    |
-| How do forms work?               | `src/forms.ts` (212 lines)       |
-| How should an app be structured? | `docs/en/10-app-architecture.md` |
-| How should errors be handled?    | `docs/en/15-error-handling.md`   |
-| How should bake be used?         | `docs/en/16-bake-cookbook.md`    |
-| What API is stable?              | `docs/en/18-api-freeze-map.md`   |
-| What ordering is guaranteed?     | `docs/en/19-reactivity-ordering.md` |
-| What does v1 stability mean?     | `docs/en/20-v1-stability.md`     |
-| When something goes wrong        | `docs/en/07-llm-pitfalls.md`     |
+| How does resource + cache work?  | `src/resource.ts`                |
+| How do forms work?               | `src/forms.ts`                   |
+| How should an app be structured? | `docs/en/16-app-architecture.md` |
+| How should errors be handled?    | `docs/en/21-error-handling.md`   |
+| How should static snapshots be used? | `docs/en/15-static-snapshots.md` / `docs/en/23-cookbook.md` |
+| What API is stable?              | `docs/en/30-api-freeze-map.md`   |
+| What ordering is guaranteed?     | `docs/en/31-reactivity-ordering.md` |
+| What does v1 stability mean?     | `docs/en/32-v1-stability.md`     |
+| When something goes wrong        | `docs/en/40-llm-guide.md`        |
 
 ## Before committing
 

package/CHANGELOG.md

@@ -1,6 +1,221 @@
 # Changelog
 
-## Unreleased
+## 0.13.0 - 2026-07-11
+
+The final planned pre-v1 breaking release hardens ownership and freezes the
+small platform-first API.
+
+### Breaking
+
+- Forms now use `useForm({ initial, validate? })`; native controls and
+  `ValidityState` own constraints. The schema and field-array APIs are removed.
+- The root surface drops `lazy`, `list` and accidental low-level exports. The
+  only public subpaths are the package root, `/vite` and `/devtools.js`.
+- `page.load` is synchronous and returns a value or `Resource`; Promises are
+  rejected with a targeted diagnostic.
+
+### Added
+
+- `render()` returns a disposer and public `unmount(container)` releases owned
+  bindings, events, effects and nested templates.
+- Structured browser and CLI diagnostics, including JSON CLI output, log-level
+  controls and `NO_COLOR` support.
+- A development-only Shadow DOM devtools overlay with reactivity, component,
+  router/data and timeline/error views, plus an exported controller.
+- The Web Components `context-request` protocol with subscriptions and
+  lifecycle cleanup.
+
+### Fixed
+
+- Destructive output paths are realpath-checked and cleaned only when owned by
+  a `.mado-output` sentinel.
+- JSON-LD/static seed serialization escapes script-breaking input.
+- Effect, component, render and navigation teardown is transactional and
+  idempotent, including initial failures and same-tick DOM moves.
+- Route literals are escaped, template markers are opaque and deterministic,
+  unsupported self-closing/template-child shapes fail early.
+- Resource cache identity includes the fetcher; `staleTime: 0`, expiry,
+  invalidation, refresh and concurrent mutation generations have defined
+  semantics. Persisted signal disposal no longer deletes storage implicitly.
+- Static capture blocks undeclared external requests, preserves form/focus
+  takeover state, runs bounded route capture and emits portable build metadata.
+- `mado build` and published route discovery now feed the standalone static
+  pipeline correctly.
+
+### Tooling and release
+
+- Framework/default starter use TypeScript 7; the ESLint modular starter stays
+  on TypeScript 6. Node 22.12+ and Vite 8 are the supported baseline.
+- Lightning CSS was removed from starters in favour of Vite's standard CSS
+  pipeline.
+- Reproducible tarballs, inline source maps, API golden files, compiled docs
+  snippets and a single `verify:release` gate were added.
+- CI covers Node 22/24, Chromium/Firefox/WebKit modular flows and Windows
+  package smoke. Runtime and devtools bundles have separate size budgets.
+- Windows package smoke invokes `npm-cli.js` through the active `node.exe`
+  instead of relying on `npm`/`npx` command shims, and launches preview
+  directly so CI does not leak a nested process tree.
+
+See [the migration guide](./docs/en/33-migration-0.12-0.13.md).
+
+## 0.12.0 - 2026-06-24
+
+### Stable polish
+
+Two rounds of post-rc polish for the 0.12.0 cut:
+
+#### Pre-merge fixes (carried over from the rc.1 review)
+
+- **Router base/prefetch.** `routeUrl()` on `"/"` and hover-prefetch
+  on Vite `base` deployments now resolve correctly under any sub-path
+  (`/`, `/mado/`, `/admin/`).
+- **`mado static` cleanup.** No more race between `process.exit` and
+  capture; canonical `<link>` is stripped on SPA navigation into pages
+  that don't declare their own head metadata.
+- **Discovery.** `mado static` no longer bypasses `fatal()` when
+  Vite SSR import fails; failures abort the snapshot.
+- **Modular starter.** All internal anchors flow through
+  `routeUrl()` + `data-link`; generators are context-aware and
+  refuse to overwrite existing files.
+- **`package:smoke`.** Now exercises both the default and modular
+  starters end to end.
+- **Release publishing.** `next` versions stay on the `next`
+  dist-tag; `latest` is reserved for stable cuts. The release and
+  weekly workflows install a pinned Playwright Chromium so static
+  snapshots never silently skip on CI.
+- **`mado preview`.** Prints the active base URL so users browsing
+  under a sub-path see the right entrypoint.
+- **`TODO.md` / `CONTRIBUTING.md` / `package.json#files`** trimmed
+  to match the post-rc reality.
+
+#### Documentation reorganisation
+
+`docs/en/` was rewritten so users (and LLMs) get one happy path:
+**"don't think `shadow: true` vs `shadow: false`; pick `page()` for
+URLs and `component()` for reusable widgets."**
+
+- **New flagship doc** `docs/en/10-pages-and-components.md` —
+  "the one rule": `page()` for routes, `component()` for reusable
+  `<x-tag>`s. Anti-patterns + decision table + `{ shadow: false }`
+  escape hatch.
+- **New numbering** groups docs into Start here / Concepts /
+  Production / Reference / Meta. Migration map for stale links is in
+  `docs/en/README.md`.
+- **Consolidated pages** —
+  `11-templates-and-signals.md` (NEW), `12-routing.md` (merges old
+  routing + layouts), `13-data.md` (merges old data + auth/api),
+  `14-forms.md` (merges old forms + Shadow-DOM forms),
+  `15-static-snapshots.md`, `16-app-architecture.md` (merges old
+  project-layout), `01-quickstart.md` (merges old IDE-setup),
+  `40-llm-guide.md` (merges old pitfalls + zero-history test).
+- **Deleted** `docs/fr`, `docs/uk`, `docs/ru` — English-only since
+  v0.12. Several legacy `docs/en/*` files were removed; their
+  content lives in the consolidated pages.
+- **Truth pass on retained prose.** Killed obsolete claims:
+  no more "tsc-only", "no bundler", "SSE reload", "tsc → browser",
+  "edge prerender", "import maps". Vite is consistently named as
+  the canonical transport.
+- **`scripts/docs-lint.mjs`** now also blocks the obsolete vocabulary
+  above and any links to renamed `docs/en/*` filenames in active
+  docs; the migration table in `docs/en/README.md` is wrapped in a
+  `docs-lint:allow-legacy-mention` block.
+
+## 0.12.0-rc.1 - 2026-06-22
+
+The unified pre-merge release. Mado is no longer "a calm browser-native
+SPA framework for internal tools"; it becomes **"a calm native-first
+web framework for sites and apps"** with one component model end to end.
+The full plan is preserved as
+[ADR 0001 — Browser-rendered static snapshots](./docs/architecture/adr/0001-browser-static-snapshots.md).
+
+### Positioning
+
+- New tagline: **One component model. One page model. One release command.**
+- README, `package.json` (description + keywords), CLI help and starter
+  READMEs all updated to the sites-and-apps positioning.
+- `MADO_UNIFIED_PRE_MERGE_PLAN.MD` moved to
+  `docs/architecture/adr/0001-browser-static-snapshots.md`.
+
+### Added
+
+- **`src/router/base.ts`** — single source of truth for the Vite base.
+  Exports `appBase`, `normalizeBase`, `stripBase`, `withBase` and the
+  new public `routeUrl()` helper. The runtime reads
+  `import.meta.env.BASE_URL` once and exposes it through these helpers
+  so every internal link is base-aware without any application
+  configuration.
+- **Production-served snapshot → live takeover E2E gate.**
+  `test/static/dsd-takeover.test.mjs` now scaffolds a real app, runs
+  `mado release`, hosts it through `mado preview` and asserts the
+  takeover contract through headless Chromium with strict
+  no-`.catch()` assertions.
+- **Base-path fixture.** `test/static/base-path.test.mjs` proves the
+  whole `/mado/` deployment shape end to end: build, sitemap, capture,
+  preview redirects, SPA fallback, runtime stripBase/withBase.
+- **Canonical / `og:url` auto-fallback.** When a page does not declare
+  either, the snapshot pipeline derives an absolute
+  `site + base + pathname` URL, deduplicates duplicates and rejects
+  localhost / capture-origin values.
+- **Strict `JsonValue` validator** with path-aware errors. Date / Map /
+  Set / class instances / undefined / NaN / Infinity / cycles all fail
+  the build with the exact JSON path that broke
+  (`[mado:static] /products/keyboard: seed.product.createdAt is Date`).
+- **Universal default starter** (`mado init my-app`). ~15 source
+  files, no backend required, demonstrates one Shadow Component shared
+  between a static landing page and a live SPA route.
+- **Modular starter preserved** (`mado init my-app --starter modular`)
+  as the long-lived business-application reference architecture.
+- **HTTP policy documented** in `scripts/static/browser.mjs`: fatal
+  vs ignored vs quality-hint classes are explicit, with bounded
+  timeouts for fonts and paint frames.
+- **`scripts/docs-lint.mjs`** refuses the old vocabulary in current
+  docs (page.bake, mado bake, out/baked, "No Vite required",
+  "internal tools only") while still allowing it in migration guides
+  and ADRs.
+- **Required CI gate** `.github/workflows/ci.yml → static-snapshot`
+  installs Playwright-managed Chromium with
+  `npx playwright install --with-deps chromium` and runs the static
+  tests under `MADO_REQUIRE_BROWSER=1` so they cannot silently skip.
+
+### Changed (breaking)
+
+- **`mado build`** in app contexts now performs a Vite production
+  build of the deployable SPA (`vite build`). Inside the framework
+  repository it still calls `tsc`. The internal tsc compile is
+  exposed via `npm run build` in the repo. Use `mado typecheck` if
+  you only wanted `tsc --noEmit`.
+- **`out/_mado/build.json`** is dropped from the final release
+  artifact. It is internal CLI plumbing emitted by the
+  `@madojs/mado/vite` plugin so `mado static` and `mado preview` can
+  read the resolved Vite base/site without parsing `vite.config.ts`.
+  `mado preview` now derives the base from the build bridge OR from
+  the asset prefix in `out/index.html`, so the preview works on the
+  shipped artifact.
+- **Static output staging.** `out/_mado/spa.html` is no longer touched
+  until every static route captures cleanly; a failure mid-pipeline
+  leaves the previous deployment intact. `cleanupTemp()` always runs
+  in `finally`.
+- **`whenStable()` phase-bounded.** The runtime now waits for
+  routeReady (cap: 15s) and tracked resources (cap: 15s) separately
+  so timeout diagnostics name the failing phase. Fonts and paint
+  frames are best-effort with bounded timeouts (5s / 1s); on timeout
+  the snapshot proceeds with a diagnostic instead of failing.
+- **Browser launch order.** `chromium.launch()` (Playwright-managed)
+  is tried *before* `channel: "chrome"` so CI determinism does not
+  depend on whatever branded Chrome happens to be installed.
+
+### Migration
+
+| Before | After |
+|---|---|
+| `page.bake` | `page.static` |
+| `mado bake` | `mado static` |
+| `out/baked/...` | `out/<route>/index.html` |
+| `#bake` data | `data-mado-static-data` script |
+| `shadow: false` for SEO | open Shadow DOM (snapshotted as DSD) |
+| `site` was optional | required for any `static` route |
+| Vite plugin optional | canonical transport |
+| `mado build` ≈ `tsc` | `mado build` ≈ `vite build` |
 
 ## 0.11.1 - 2026-06-21