@madojs/mado 0.11.0 → 0.12.0

package/dist/src/vite/index.js

@@ -1,32 +1,63 @@
-import { resolve } from "node:path";
 /**
  * Vite integration for Mado apps.
  *
- * The plugin is intentionally small: Vite owns dev serving, HTML processing,
- * assets and bundling; Mado keeps its runtime and static bake semantics.
+ * Intentionally minimal: Vite owns dev serving, HTML processing, assets
+ * and bundling. This plugin is the bridge that hands the snapshot CLI the
+ * three pieces of resolved Vite config it needs and asks Vite for a
+ * Mado-flavoured full reload on TypeScript/JavaScript changes.
+ *
+ * What it owns:
+ *   1. a small `build.target` default (matches what the runtime relies on);
+ *   2. forcing a full page reload when a `.ts` / `.js` module updates,
+ *      so signals / components do not have to track HMR state;
+ *   3. emitting `_mado/build.json` into the output so
+ *      `scripts/static.mjs` can read the resolved Vite `base`, `assetsDir`
+ *      and the user-declared `site` without parsing `vite.config.ts`.
+ *
+ * What it does NOT own:
+ *   - HTML ownership (Vite keeps that),
+ *   - publicDir / outDir / assetsDir defaults (Vite already supplies them),
+ *   - snapshot orchestration (CLI keeps that),
+ *   - SSR or hydration.
  */
-export function mado(_options = {}) {
-    let root = process.cwd();
+export function mado(options = {}) {
+    let resolved = null;
     return {
         name: "mado",
-        config(userConfig) {
-            root = resolve(process.cwd(), userConfig.root ?? ".");
+        config() {
             return {
-                appType: "spa",
-                publicDir: "public",
-                build: {
-                    outDir: "out",
-                    assetsDir: "assets",
-                    target: "es2022",
-                },
+                build: { target: "es2022" },
             };
         },
+        configResolved(config) {
+            resolved = config;
+        },
         handleHotUpdate(ctx) {
-            if (/\.(ts|js)$/.test(ctx.file)) {
-                ctx.server.ws.send({ type: "full-reload" });
-                return [];
+            if (!/\.[cm]?[jt]s$/.test(ctx.file))
+                return;
+            // Invalidate the module graph first; otherwise the reload would
+            // serve cached modules and miss the change. Mirrors the canonical
+            // Vite "force full reload" recipe.
+            const invalidated = new Set();
+            for (const mod of ctx.modules) {
+                ctx.server.moduleGraph.invalidateModule(mod, invalidated, ctx.timestamp, true);
             }
-            return undefined;
+            ctx.server.ws.send({ type: "full-reload" });
+            return [];
+        },
+        generateBundle() {
+            if (!resolved)
+                return;
+            this.emitFile({
+                type: "asset",
+                fileName: "_mado/build.json",
+                source: JSON.stringify({
+                    site: options.site ?? null,
+                    base: resolved.base,
+                    assetsDir: resolved.build.assetsDir,
+                    outDir: resolved.build.outDir,
+                }),
+            });
         },
     };
 }

package/dist/src/vite/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,WAAkC,EAAE;IACvD,IAAI,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAEzB,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,MAAM,CAAC,UAAU;YACf,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC;YAEtD,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,SAAS,EAAE,QAAQ;gBACnB,KAAK,EAAE;oBACL,MAAM,EAAE,KAAK;oBACb,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,QAAQ;iBACjB;aACF,CAAC;QACJ,CAAC;QACD,eAAe,CAAC,GAAG;YACjB,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC5C,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/vite/index.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,IAAI,CAAC,UAAiC,EAAE;IACtD,IAAI,QAAQ,GAA0B,IAAI,CAAC;IAE3C,OAAO;QACL,IAAI,EAAE,MAAM;QAEZ,MAAM;YACJ,OAAO;gBACL,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;aAC5B,CAAC;QACJ,CAAC;QAED,cAAc,CAAC,MAAM;YACnB,QAAQ,GAAG,MAAM,CAAC;QACpB,CAAC;QAED,eAAe,CAAC,GAAG;YACjB,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO;YAC5C,gEAAgE;YAChE,kEAAkE;YAClE,mCAAmC;YACnC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAW,CAAC;YACvC,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAC9B,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,gBAAgB,CACrC,GAAG,EACH,WAAyB,EACzB,GAAG,CAAC,SAAS,EACb,IAAI,CACL,CAAC;YACJ,CAAC;YACD,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;YAC5C,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,cAAc;YACZ,IAAI,CAAC,QAAQ;gBAAE,OAAO;YACtB,IAAI,CAAC,QAAQ,CAAC;gBACZ,IAAI,EAAE,OAAO;gBACb,QAAQ,EAAE,kBAAkB;gBAC5B,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC;oBACrB,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI;oBAC1B,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS;oBACnC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM;iBAC9B,CAAC;aACH,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/docs/README.md

@@ -1,12 +1,9 @@
 # Mado docs
 
-Documentation is organized by language.
+Canonical project documentation is maintained in English only.
 
-| Language | Status |
-|---|---|
-| [Français](./fr/README.md) | translated |
-| [English](./en/README.md) | translated |
-| [Ukrainian](./uk/README.md) | translated |
-| [Russian](./ru/README.md) | translated |
+- [English documentation](./en/README.md)
 
-Translations and comment localization are tracked separately from core work.
+Older translations (`fr/`, `uk/`, `ru/`) were removed at v0.12. They
+remain available in git history and the `v0.11.1` tag for any
+external links that still need them.

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.