@madojs/mado 0.12.0 → 0.13.1

package/docs/en/14-forms.md

@@ -1,244 +1,91 @@
 # Forms
 
-> `useForm()` is a thin signal-wrapper around native HTML5 form
-> validation. For 90% of cases you write a `<form>`, attach
-> `onInput / onBlur / onSubmit` and you are done.
+`useForm()` adds reactive state to the browser's form and constraint-validation
+model. HTML remains the source of truth for `required`, `type`, `min`, `max`,
+`minlength`, `maxlength` and `pattern`.
 
 ```ts
-import { html, page, useForm } from "@madojs/mado";
-
-export default page({
-  view: () => {
-    const f = useForm({
-      email: { required: true, type: "email" },
-      age:   { required: true, type: "number", min: 18 },
-    });
-
-    return html`
-      <form @submit=${f.onSubmit(async (v) => { await api.save(v); f.reset(); })}>
-        <input name="email" type="email"
-               @input=${f.onInput} @blur=${f.onBlur} />
-        ${() =>
-          f.touched().email && f.errors().email
-            ? html`<small class="err">${f.errors().email}</small>`
-            : null}
-
-        <input name="age" type="number" @input=${f.onInput} />
-
-        <button ?disabled=${() => !f.isValid() || f.submitting()}>Save</button>
-      </form>
-    `;
-  },
-});
-```
-
-## The signals it exposes
-
-| Reader                 | Value                                                            |
-| ---------------------- | ---------------------------------------------------------------- |
-| `f.values()`           | object of current field values                                   |
-| `f.errors()`           | object of `field → error string` (validators + HTML5 constraints)|
-| `f.touched()`          | object of `field → boolean` (true after first blur)              |
-| `f.isValid()`          | true when `errors()` is empty                                    |
-| `f.submitting()`       | true while the `onSubmit` async handler is running               |
-| `f.dirty()`            | true when any value differs from initial                         |
-
-Writers: `f.setValue(name, v)`, `f.setError(name, msg)`,
-`f.reset(values?)`, `f.touch(name)`.
-
-## Schema
-
-The schema mirrors HTML5 constraints, with a few extras:
-
-```ts
-useForm({
-  email:    { required: true, type: "email" },
-  age:      { type: "number", min: 18, max: 120 },
-  name:     { required: true, minLength: 2, maxLength: 80 },
-  website:  { type: "url" },
-  tags:     { custom: (v) => Array.isArray(v) && v.length > 0 ? null : "pick at least one" },
-});
-```
-
-For cross-field or async rules use `validate`:
-
-```ts
-useForm({
-  password: { required: true, minLength: 8 },
-  confirm:  { required: true },
-}, {
-  validate: (values) =>
-    values.password !== values.confirm
-      ? { confirm: "passwords do not match" }
-      : null,
-});
-```
-
-Return `null` (everything is valid) or a partial `field → error`
-object.
-
-## Field arrays
-
-```ts
-const f = useForm({ tags: { custom: (v) => v.length > 0 ? null : "required" } });
-const tags = f.fieldArray<string>("tags");
-
-tags.append("rust");
-tags.remove(0);
-tags.move(0, 2);
-tags.items();   // current array (signal)
-```
-
-## With `mutation()`
+import { html, useForm } from "@madojs/mado";
 
-Forms compose with `mutation()` for typed write-paths:
-
-```ts
-import { mutation, navigate } from "@madojs/mado";
-
-const save = mutation((u: User) => api.save(u), {
-  invalidates: ["/api/users*"],
+const form = useForm({
+  initial: { email: "", age: "" as number | "", newsletter: false },
+  validate: async (values, { signal }) => {
+    const available = await api.emailAvailable(values.email, { signal });
+    return available ? null : { email: "Email is already registered" };
+  },
 });
 
-// inside view()
-const f = useForm({ name: { required: true } });
-return html`
-  <form @submit=${f.onSubmit(async (v) => {
-    await save.run(v);
-    navigate("/users");
+html`
+  <form @submit=${form.onSubmit(async (values, event) => {
+    await api.save(values, new FormData(event.currentTarget as HTMLFormElement));
   })}>
-    <input name="name" @input=${f.onInput} />
-    <button ?disabled=${() => !f.isValid() || save.loading()}>Create</button>
-    ${() => save.error() ? html`<p class="err">${save.error()!.message}</p>` : null}
+    <label>
+      Email
+      <input name="email" type="email" required
+        @input=${form.onInput} @blur=${form.onBlur} />
+    </label>
+    ${() => form.touched().email && form.errors().email
+      ? html`<small role="alert">${form.errors().email}</small>`
+      : null}
+
+    <input name="age" type="number" min="18" max="120" @input=${form.onInput} />
+    <label><input name="newsletter" type="checkbox" @input=${form.onInput} /> Subscribe</label>
+    <button type="submit" ?disabled=${() => form.submitting() || form.validating()}>
+      Save
+    </button>
   </form>
 `;
 ```
 
-`save.loading()` reflects the request; `f.submitting()` reflects the
-`onSubmit` handler runtime. Usually only one of them is interesting.
-
-## Shadow DOM inputs — when you need them
+## API
 
-Most apps build forms from native `<input>` / `<select>` /
-`<textarea>` directly inside the `<form>`. `useForm()` reads
-`e.target.name` and `e.target.value` on the events, which works
-out-of-the-box for native controls.
+`useForm<T>({ initial, validate? })` returns:
 
-You only need a custom Web Component when the input has its own
-shadow tree (a date picker, a tag editor, a rich text field, …). Two
-browser-level facts make that path slightly different:
+| Member | Meaning |
+| --- | --- |
+| `values()` | current typed values |
+| `errors()` | native and custom errors by field; `$form` is available for form-wide errors |
+| `touched()` | fields that have blurred or participated in submit |
+| `dirty()` | whether values differ from the current initial values |
+| `isValid()` | whether the merged error map is empty |
+| `submitting()` / `validating()` | current async activity |
+| `setField(name, value)` | update one field programmatically |
+| `validate(form?)` | run native and custom validation; returns `Promise<boolean>` |
+| `reset(nextInitial?)` | abort validation, clear state and reset native controls |
+| `onInput`, `onBlur`, `onSubmit(handler)` | DOM event handlers |
 
-1. **Event retargeting** — events that bubble out of an open shadow
-   root have their `target` retargeted to the host. `useForm()` reads
-   `e.target.name` and `e.target.value` — the host element must
-   expose both.
-2. **Form association** — a `<button type="submit">` inside a shadow
-   root is NOT part of the form-owner algorithm. Clicking it does
-   not submit the surrounding `<form>`.
+Custom validation receives `{ signal, form }`. Starting another validation or
+calling `reset()` aborts the previous run. Treat abort as normal cancellation.
 
-The two patterns below cover both. Reach for them **only** if a real
-custom input forces you to. For everything else, see "Light-DOM
-inputs" further down.
+## Native controls
 
-### Custom input — proxy `name` / `value`
+- Checkbox groups produce an array when the initial field value is an array;
+  a single checkbox produces a boolean.
+- Radio groups produce the checked value.
+- `<select multiple>` produces a string array.
+- Number/range inputs produce a number, or `""` when empty.
+- File inputs produce `File | null`, or `File[]` when `multiple` is present.
+- The submit callback receives the native `SubmitEvent`; construct `FormData`
+  from its form when the backend expects multipart or repeated fields.
 
-```ts
-import { component, html } from "@madojs/mado";
-
-component("x-input", ({ host, attr }) => {
-  const type = attr("type", "text");
-
-  // After Shadow DOM retargets e.target from the inner <input> to
-  // <x-input>, useForm reads e.target.name / e.target.value. These
-  // getters bridge the gap.
-  Object.defineProperty(host, "name", {
-    get: () => host.getAttribute("name") ?? "",
-    configurable: true,
-  });
-  Object.defineProperty(host, "value", {
-    get: () => host.shadowRoot?.querySelector("input")?.value ?? "",
-    set: (v: string) => {
-      const input = host.shadowRoot?.querySelector("input");
-      if (input) input.value = v;
-    },
-    configurable: true,
-  });
-
-  return () => html`<input type=${type} />`;
-});
-```
+Use a native `<button type="submit">`. A button inside another element's
+Shadow DOM is not a submit control for the outer form and keyboard submission
+will not discover it.
 
-The inner `input` event already bubbles through the shadow boundary
-(`composed: true` by default), so `<form @input=${f.onInput}>` keeps
-working.
-
-### Custom submit button — `requestSubmit()`
+## Mutations
 
 ```ts
-import { component, html } from "@madojs/mado";
-
-component("x-button", ({ host, attr }) => {
-  const disabled = attr("disabled");
-
-  const onClick = () => {
-    const t = host.getAttribute("type");
-    if (t === "button" || t === "reset") return;
-    if (host.hasAttribute("disabled")) return;
-    host.closest("form")?.requestSubmit();
-  };
-
-  return () => html`
-    <button ?disabled=${() => disabled() !== ""} @click=${onClick}>
-      <slot></slot>
-    </button>
-  `;
+const save = mutation((values: Profile) => api.save(values), {
+  invalidates: ["/api/profile"],
 });
-```
-
-`host.closest("form")` works because the host itself lives in the
-light DOM. `requestSubmit()` triggers HTML5 validation and the
-`submit` event exactly like a native click.
-
-### Light-DOM input — the simpler alternative
-
-If a custom element is just a styled wrapper around a native control
-and does not need style encapsulation, use `{ shadow: false }`. The
-native `<input>` is then part of the document; no retargeting, no
-proxy properties, no submit bridge.
+const form = useForm({ initial: { displayName: "" } });
 
-```ts
-component(
-  "x-field",
-  ({ attr }) => {
-    const label = attr("label", "");
-    return () => html`
-      <label>
-        <span>${label}</span>
-        <slot></slot>
-      </label>
-    `;
-  },
-  { shadow: false },
-);
+html`<form @submit=${form.onSubmit((values) => save.run(values))}>
+  <input name="displayName" required minlength="2" @input=${form.onInput} />
+  <button type="submit" ?disabled=${() => form.submitting()}>Save</button>
+</form>`;
 ```
 
-This is the only situation where `shadow: false` is the recommended
-default — and even then a `page()` is usually a better fit if the
-wrapper is layout-shaped rather than reusable.
-
-## Summary
-
-| Concern                    | Native form                          | Custom component with Shadow DOM         |
-| -------------------------- | ------------------------------------ | ----------------------------------------- |
-| `useForm` integration      | works out of the box                 | proxy `name` / `value` on the host        |
-| Submit button              | `<button type="submit">` works       | `host.closest("form")?.requestSubmit()`   |
-| Reactive attributes        | not needed                           | `ctx.attr(name)` returns a Signal         |
-| Style encapsulation        | global CSS                           | Shadow DOM CSS via `css\`\``              |
-
-## Further reading
-
-- [10-pages-and-components.md](./10-pages-and-components.md) — when
-  to reach for `component({ shadow: false })`.
-- [13-data.md](./13-data.md) — `mutation()` for typed writes.
-- [21-error-handling.md](./21-error-handling.md) — surfacing form
-  errors from network failures.
+Write failures belong to the mutation; field and cross-field validation belong
+to the form. See the [0.12 → 0.13 migration guide](./33-migration-0.12-0.13.md)
+for the removed schema and field-array APIs.

package/docs/en/15-static-snapshots.md

@@ -151,9 +151,9 @@ same shape the snapshot captured.
   resource(), custom element definition) fails the snapshot. A small
   allow-list covers `/favicon.ico`, `/favicon.svg`, `/robots.txt`
   and `data:` URLs.
-- **All network calls happen against an internal capture server** that
-  serves the freshly built `out/` tree. There is no real network at
-  capture time.
+- **All network calls must target the internal capture origin** serving the
+  freshly built `out/` tree. Undeclared external HTTP(S) requests are blocked;
+  provide deterministic `static.initialData()` instead.
 
 ## Comparison
 
@@ -178,4 +178,4 @@ multi-locale builds live in [23-cookbook.md](./23-cookbook.md).
 - Declare `static: true | { paths, initialData }` on `page({ ... })`.
 - Run `mado release`.
 - Ship `out/` to any static host.
-- The live SPA takes over atomically on first paint.
+- The live SPA takes over atomically on first paint.

package/docs/en/16-app-architecture.md

@@ -190,8 +190,9 @@ Reusable leaf components keep their own styles in ``css`...` `` inside
 `component()` options. They should depend on tokens (`var(--color-text)`)
 rather than global classes.
 
-`vite.config.ts` opts into Vite's Lightning CSS transformer. Mado does not own
-prefixing, CSS lowering or minification.
+Vite 8's standard CSS pipeline owns transforms and minification. Mado adds no
+CSS transformer; applications can configure Vite directly when they have a
+measured need.
 
 ## Growth
 

package/docs/en/20-deployment.md

@@ -62,7 +62,7 @@ Key lines of the recipe `nginx.conf`:
 - `gzip_static on;` — serves the precompressed `.gz` files written by
   `mado release`. Zero CPU at request time.
 - `/assets/*` should be cached immutable; Vite filenames are content hashed.
-- `try_files $uri $uri/ /index.html;` — SPA fallback so deep links work
+- `try_files $uri $uri/ /_mado/spa.html;` — SPA fallback so deep links work
   after a hard refresh.
 
 Enable HTTPS with Let's Encrypt / Certbot. Add HSTS once you have it.
@@ -76,7 +76,7 @@ mado release
 npx wrangler pages deploy out --project-name=myapp
 ```
 
-- The generated `_redirects` (`/* /index.html 200`) gives you SPA fallback.
+- The generated `_redirects` (`/* /_mado/spa.html 200`) gives you SPA fallback.
 - The generated `_headers` (immutable cache for `/assets/*`, `no-cache` for
   HTML) is honored by CF Pages.
 - Baked routes are promoted to real route files (`out/<route>/index.html`),
@@ -116,16 +116,15 @@ aws s3 sync out/ s3://my-bucket/ \
   --cache-control "no-cache, must-revalidate" --include '*.html'
 ```
 Configure CloudFront's "Default root object" to `index.html` and add a custom
-error response: 403/404 → `/index.html` with status 200 (SPA fallback).
+error response: 403/404 → `/_mado/spa.html` with status 200 (SPA fallback).
 
 **GitHub Pages**
 ```bash
 mado release
 # Push out/ into the gh-pages branch (or use actions/upload-pages-artifact)
 ```
-Pages handles `index.html` automatically. There is no native SPA fallback;
-add a `404.html` that loads the SPA, or use the
-[`spa-github-pages`](https://github.com/rafgraph/spa-github-pages) trick.
+Pages handles route `index.html` files automatically. `mado release` also writes
+`404.html` from the noindex SPA shell for client-only routes.
 
 ---
 
@@ -177,7 +176,7 @@ jobs:
 
 - **404 on hard refresh of a deep link.** Your host did not pick up SPA
   fallback. nginx: check `try_files`. CF/Netlify: `_redirects` is present?
-  S3+CloudFront: configure the 404 → `/index.html` (200) error response.
+  S3+CloudFront: configure the 404 → `/_mado/spa.html` (200) error response.
 - **HTML is cached forever.** Either your host sent a default
   `Cache-Control: public, max-age=...` or you are sitting behind a CDN that
   ignores `no-cache`. Add an explicit rule mirroring the matrix above.
@@ -189,6 +188,20 @@ jobs:
   field. If you still see it, upgrade `@madojs/mado` and re-run
   `mado release`.
 
+## CSP and trusted content
+
+Mado serialises JSON-LD and static seed JSON with `<`, U+2028 and U+2029
+escaped, so data cannot close its script element. `unsafeHTML()` is different:
+it is an explicit trust boundary and must receive only audited or sanitised
+markup.
+
+Start with a restrictive policy such as `default-src 'self'; script-src
+'self'; style-src 'self' 'unsafe-inline'; object-src 'none'; base-uri 'self'`
+and tighten styles with nonces/hashes when your deployment supports them.
+Trusted Types can enforce the same application boundary around any code that
+produces trusted HTML. The devtools overlay is development-only and should not
+be imported in production entrypoints.
+
 ## Sub-path deployments and `base`
 
 A deployment under a sub-path (`https://your.site/docs/`, GitHub
@@ -226,7 +239,7 @@ html`<a data-link href=${routeUrl("/guides/intro")}>Intro</a>`;
 
 On the production host:
 
-- **nginx** — keep `try_files $uri $uri/ /index.html;` but mount the
+- **nginx** — keep `try_files $uri $uri/ /_mado/spa.html;` but mount the
   app under the matching prefix (`location /docs/ { ... }`).
 - **Cloudflare Pages / Netlify** — `_redirects` is generated with the
   base prefix already baked in.

package/docs/en/21-error-handling.md

@@ -24,7 +24,7 @@ For a specific page, `page({ errorView })` wins over the global route boundary.
 
 ```ts
 export default page({
-  load: async () => api.get("/reports"),
+  load: () => resource(() => "/reports", jsonFetcher<Report[]>()),
   errorView: (err) => html`<x-report-error .error=${err}></x-report-error>`,
   view: ({ data }) => html`<x-report .data=${data}></x-report>`,
 });
@@ -53,10 +53,10 @@ Validation errors belong in `useForm()`. Server errors from writes belong near
 the submit button.
 
 ```ts
-const form = useForm(
-  { email: { required: true, type: "email" } },
-  { validateAsync: (values) => api.validateUser(values) },
-);
+const form = useForm({
+  initial: { email: "" },
+  validate: (values, { signal }) => api.validateUser(values, { signal }),
+});
 
 const save = mutation((values) => api.post("/users", values), {
   invalidates: ["/api/users*"],
@@ -66,6 +66,7 @@ html`
   <form @submit=${form.onSubmit(async values => {
     await save.run(values);
   })}>
+    <input name="email" type="email" required @input=${form.onInput} />
     <button ?disabled=${() => form.validating() || form.submitting()}>
       Save
     </button>
@@ -97,4 +98,6 @@ component("x-online", (ctx) => {
 
 Log once at the boundary that owns recovery. Avoid logging the same failure in
 the API client, resource, page and component. The user should get one visible
-message and developers should get one useful console error.
+message and developers should get one structured diagnostic. Runtime records
+are visible in the devtools Timeline/Errors panel and as `mado:diagnostic`
+events; CLI automation can select `--log-format=json`.

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/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,7 +26,7 @@ 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`,
@@ -37,9 +37,8 @@ These names are public and protected by SemVer once v1 ships:
 - Context: `createContext`, `provide`, `inject`.
 - Advanced lifecycle helpers: `createLifecycle`, `runInLifecycle`,
   `getCurrentLifecycle`.
-- Public TypeScript types exported from `@madojs/mado`, including
-  `StaticPageConfig` (the `static: true | { ... }` option on `page()`)
-  and `HeadMeta` (the head metadata shape returned by pages).
+- Public TypeScript types exported from `@madojs/mado`, including `FormApi`,
+  `Resource`, `ComponentContext`, `StaticPageConfig` and `HeadMeta`.
 
 ## Internal or unstable
 
@@ -66,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/32-v1-stability.md

@@ -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.
@@ -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`.