@madojs/mado 0.11.1 → 0.13.0

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/24-devtools-and-diagnostics.md

@@ -0,0 +1,45 @@
+# Devtools and diagnostics
+
+Development instrumentation is opt-in and compiled out of production builds.
+Import the stable devtools subpath before application startup:
+
+```ts
+import { devtools } from "@madojs/mado/devtools.js";
+
+devtools.open();
+```
+
+`Alt+Shift+M` toggles the Shadow DOM overlay. Its Overview, Reactivity,
+Components, Router/Data and Timeline/Errors views are fed by a versioned
+internal hook. The controller also exposes `close()`, `toggle()`, `clear()`,
+`setLogLevel()` and `snapshot()`. Snapshots contain safe previews rather than
+live application objects.
+
+`localStorage.madoDebug = "1"` is accepted during 0.13 migration only and emits
+a deprecation warning.
+
+## Runtime diagnostics
+
+Every record has `level`, `scope`, `code`, `message`, optional `data`, and a
+timestamp. Set browser verbosity with:
+
+```js
+localStorage.setItem("mado:log-level", "debug");
+```
+
+Allowed levels are `debug`, `info`, `warn`, `error` and `silent`. Records are
+also dispatched as `mado:diagnostic` events and appear in devtools.
+
+## CLI diagnostics
+
+```bash
+mado release --log-level=debug --log-format=pretty
+mado release --log-format=plain
+mado release --log-format=json
+```
+
+The CLI honours `MADO_LOG_LEVEL`, `MADO_LOG_FORMAT` and `NO_COLOR`. Non-TTY
+output automatically becomes plain. JSON mode writes one structured record per
+line, suitable for CI ingestion.
+
+The logger is internal infrastructure, not a public logging API for apps.

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

@@ -9,11 +9,11 @@ package root:
 import { component, html, resource, routes, signal } from "@madojs/mado";
 ```
 
-The public package subpaths are the side-effect devtools module and the Vite
-tooling integration:
+The public package subpaths are the devtools controller and the Vite tooling
+integration:
 
 ```ts
-import "@madojs/mado/devtools.js";
+import { devtools } from "@madojs/mado/devtools.js";
 import { mado } from "@madojs/mado/vite";
 ```
 
@@ -26,18 +26,19 @@ These names are public and protected by SemVer once v1 ships:
 
 - Reactivity: `signal`, `computed`, `effect`, `untracked`, `batch`,
   `flushSync`.
-- Templates and directives: `html`, `render`, `each`, `list`, `unsafeHTML`,
+- Templates and directives: `html`, `render`, `unmount`, `each`, `unsafeHTML`,
   `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 `FormApi`,
+  `Resource`, `ComponentContext`, `StaticPageConfig` and `HeadMeta`.
 
 ## Internal or unstable
 
@@ -48,7 +49,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.
 
@@ -57,8 +65,8 @@ Application code should not.
 
 ## What can change
 
-Patch and minor releases may add new root exports, options, diagnostics, docs,
-or starter files. They may also change internals, emitted bundle shape, and
+Patch and minor releases may add compatible options, diagnostics, docs or
+starter files. New root exports require an explicit API review. Releases may change internals, emitted bundle shape, and
 implementation details as long as the stable API and documented behavior remain
 compatible.
 

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
 
@@ -17,7 +17,7 @@ After v1, Mado treats these as SemVer-protected:
 
 - Public exports from `@madojs/mado`.
 - Public TypeScript types exported from `@madojs/mado`.
-- The `@madojs/mado/devtools.js` side-effect subpath.
+- The `@madojs/mado/devtools.js` controller subpath and `@madojs/mado/vite`.
 - Template binding syntax: child `${}`, `@event`, `.prop`, `?boolean`,
   attribute bindings, directives and `each()`.
 - Signal semantics documented in the reactivity ordering guide.
@@ -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.
 
@@ -33,7 +33,7 @@ Breaking these requires a major version.
 
 Minor releases may add:
 
-- New root exports.
+- New root exports after explicit API review and golden-file update.
 - New options on existing APIs.
 - New diagnostics and warnings.
 - New starters, examples, docs and CLI flags.

package/docs/en/33-migration-0.12-0.13.md

@@ -0,0 +1,56 @@
+# Migrating from 0.12 to 0.13
+
+0.13 is the final planned pre-v1 breaking release. It narrows the root API and
+makes lifecycle, forms, resources and router behaviour explicit.
+
+## Forms
+
+<!-- docs-lint:allow-legacy-mention -->
+
+The 0.12 schema-shaped call:
+
+```ts
+useForm({ email: { required: true, type: "email" } });
+```
+
+becomes:
+
+```ts
+useForm({ initial: { email: "" } });
+```
+
+Move `required`, `type`, `min`, `max` and `pattern` to the native controls.
+Replace `setValue` with `setField`. The separate field-array helper was removed;
+use ordinary array values and `setField`. Custom/async validation now belongs
+to `validate(values, { signal, form })` in the options object.
+
+<!-- /docs-lint:allow-legacy-mention -->
+
+## Removed root exports
+
+`lazy`, `list`, `instantiate`, `isHtmlDirective`, `adopt`, `scopeStyles`,
+`isPage` and `isLayoutGroup` are no longer root exports. Use dynamic route
+imports, `each()`, `render()` and the documented high-level APIs instead.
+Only the package root, `/vite` and `/devtools.js` are public subpaths.
+
+## Behaviour changes
+
+- `render()` returns an idempotent disposer; `unmount(container)` explicitly
+  releases bindings, events, nested templates and child lifecycles.
+- `page.load` is synchronous. Return a value or a `Resource`; returning a
+  Promise throws a diagnostic error. Put async work in `resource()`.
+- `resource().refresh()` returns `Promise<T>`. `staleTime: 0` deduplicates only
+  an in-flight request and never reuses completed data.
+- Cache identity includes the fetcher, and `invalidate()` reaches cached and
+  uncached live resources.
+- Persisted signals separate `dispose()` from explicit storage deletion.
+- Context now uses the Web Components `context-request` protocol and cleans up
+  subscriptions with the current lifecycle.
+- Static capture blocks undeclared external requests and `mado build` writes
+  the `out/` artifact consumed by `mado static`.
+
+## Devtools and logging
+
+Import `@madojs/mado/devtools.js` in development and use `Alt+Shift+M`.
+`localStorage.madoDebug` is deprecated; use `mado:log-level` or the controller.
+CLI automation should prefer `--log-format=json`.