@madojs/mado 0.11.1 → 0.13.0

package/docs/en/{06-for-backenders.md → 41-for-backenders.md}

@@ -195,14 +195,13 @@ We register the `<x-counter>` tag in the browser — it becomes a "function" tha
 
 ## Forms — like `form.Validate()` on the backend
 
-Mado uses **schema-based validation close to native HTML constraints**, plus adds state tracking.
+Mado uses the browser's **constraint validation** and adds reactive state tracking.
 
 ```ts
 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 | "" },
 });
 
 // in the template:
@@ -215,6 +214,8 @@ html`
   >
     <input
       name="email"
+      type="email"
+      required
       .value=${() => f.values().email ?? ""}
       @input=${f.onInput}
       @blur=${f.onBlur}
@@ -225,12 +226,13 @@ html`
         ? html`<small>${f.errors().email}</small>`
         : null}
 
-    <button ?disabled=${() => !f.isValid() || f.submitting()}>Save</button>
+    <input name="age" type="number" min="18" @input=${f.onInput} />
+    <button type="submit" ?disabled=${() => !f.isValid() || f.submitting()}>Save</button>
   </form>
 `;
 ```
 
-Custom validation — `validate: (values) => errors | null`. No Yup schemas or dependencies.
+Custom validation — `validate: (values, { signal }) => errors | null`. No Yup schemas or dependencies.
 
 ---
 
@@ -258,24 +260,25 @@ component("x-page", ({ host }) => {
 ```
 
 This is like `context.WithValue` / `ctx.Value` in Go, but reactive.
+The transport is the interoperable Web Components `context-request` event, so
+providers and consumers can cross library boundaries.
 
 ---
 
-## SEO — not SSR, but `bake` (like `templ generate` in Go)
+## SEO — not SSR, but static snapshots (like `templ generate` in Go)
 
-If you're used to server-side rendering for SEO, in Mado this is solved differently: **prerender at build time**.
+If you're used to server-side rendering for SEO, in Mado this is solved differently: **browser-rendered prerender at build time**.
 
 ```ts
 // src/modules/<module>/pages/product.ts
 export default page({
-  bake: {
-    paths: () => api.allProductSlugs(), // build-time fetch
-    data: ({ slug }) => api.getProduct(slug),
-    revalidate: 3600,
+  static: {
+    paths: () => api.allProductSlugs(),       // build-time fetch
+    initialData: ({ slug }) => api.getProduct(slug),
   },
-  head: ({ slug }, data) => ({
+  head: (_, data) => ({
     description: data.description,
-    canonical: `/product/${slug}`,
+    canonical: `/product/${data.slug}`,
     og: { title: data.name, image: data.image },
   }),
   view: ({ params }) => html`<x-product data-slug=${params.slug} />`,
@@ -283,12 +286,12 @@ export default page({
 ```
 
 ```bash
-npm run bake   # → out/product/iphone-15/index.html (+ sitemap)
+npm run release   # → out/product/iphone-15/index.html (+ sitemap)
 ```
 
 The crawler sees ready-made HTML with meta tags. The user sees the same thing + interactivity after JS loads.
 
-More details: [`03-static-bake.md`](./03-static-bake.md).
+More details: [`15-static-snapshots.md`](./15-static-snapshots.md).
 
 ---
 
@@ -336,7 +339,7 @@ const createUser = mutation<NewUser, User>(
 );
 
 // in page.view:
-const f = useForm({ name: { required: true } });
+const f = useForm({ initial: { name: "" } });
 
 html`
   <form
@@ -345,8 +348,8 @@ html`
       navigate("/users");
     })}
   >
-    <input name="name" @input=${f.onInput} />
-    <button>Create</button>
+    <input name="name" required @input=${f.onInput} />
+    <button type="submit">Create</button>
   </form>
 `;
 ```
@@ -403,7 +406,8 @@ Module connectors build on this transport and map DTOs to domain types.
 
 - **Hooks and hook rules.** Not in Mado. Signals are ordinary functions.
 - **VDOM and reconciliation.** None. Signals update the DOM directly, surgically.
-- **Webpack/Vite configs.** No build. `tsc → browser`.
+- **Webpack/Babel configs.** Vite is the transport; the starter ships one
+  three-line `vite.config.ts` with `mado()`.
 - **`useEffect` dependency arrays.** `effect()` sees what you read on its own.
 - **State management libraries** (Redux/Zustand). Signals + context.
 - **CSS-in-JS transformations.** Shadow DOM + `css\`\`` + cssVars.
@@ -418,7 +422,7 @@ These are new concepts. Not scary, but they are additions to your React/Vue base
 1. **Custom Elements / Shadow DOM.** `<x-foo>` is not a div, it is a full-fledged element with its own DOM. Slots, scoped CSS. One evening of MDN reading.
 2. **`attribute` vs `property`.** Attribute is a string in HTML (`data-id="5"`), property is a JS property (`el.id = 5`). `?attr=${flag}` and `.prop=${value}` in templates refer to different things. Main rule: **numbers/objects/arrays — via `.prop`, flags — via `?attr`, strings — via `attr`**.
 3. **Signals.** If it's your first time — you'll get stuck for 10 minutes, then it's easier than hooks.
-4. **`html\`\``-templates.** It's just a JS function with highlighting via [lit-plugin](./04-ide-setup.md). Not magic.
+4. **`html\`\``-templates.** It's just a JS function with highlighting via [lit-plugin](./01-quickstart.md#4-ide-setup). Not magic.
 
 Everything else — standard browser + TypeScript.
 
@@ -426,8 +430,7 @@ Everything else — standard browser + TypeScript.
 
 ## What's missing (honestly)
 
-- No hot reload, only full reload via SSE. Sufficient for most cases, but not like Vite.
-- No browser extension dev-tools. Use `localStorage.madoDebug = '1'` + console.
+- The built-in overlay covers runtime inspection; a browser extension remains post-v1 work.
 - No StackBlitz starters (yet).
 - No AI assistant that knows Mado as well as React. When in doubt — read `src/`, it's not scary.
 
@@ -435,9 +438,9 @@ Everything else — standard browser + TypeScript.
 
 ## Further reading
 
-- **[`01-routing.md`](./01-routing.md)** — the router in detail.
-- **[`02-project-layout.md`](./02-project-layout.md)** — project structure.
-- **[`03-static-bake.md`](./03-static-bake.md)** — SEO without SSR.
+- **[`12-routing.md`](./12-routing.md)** — the router in detail.
+- **[`16-app-architecture.md`](./16-app-architecture.md)** — project structure.
+- **[`15-static-snapshots.md`](./15-static-snapshots.md)** — SEO without SSR.
 - **External `madojs-examples` workspace** — full demos (landing + admin).
 
 If something is unclear — open an issue, or just open the source. It really is readable in an evening.

package/docs/en/{05-why-mado.md → 42-why-mado.md}

@@ -39,7 +39,7 @@ If your case does not fall into the last point — Mado is most likely not the b
 | Router         | none, you need to find one (`@lit-labs/router`, etc)           | included: `routes()` + layout groups + prefetch        |
 | Data fetching  | none, you need to assemble it                                  | `resource()` + `mutation()` + glob invalidation        |
 | Forms          | none                                                           | `useForm()` with HTML-like constraints                 |
-| SEO / static   | complex (`@lit-labs/ssr`)                                      | `bake` (linkedom) + edge-prerender                     |
+| SEO / static   | complex (`@lit-labs/ssr`)                                      | `mado static` (real Chromium snapshot + DSD)           |
 | Build          | needs framework-specific build plugins                         | Vite transport + native runtime                         |
 | Code style     | classes + decorators                                           | functions + tagged templates                           |
 | Ecosystem      | real (Shoelace, Material Web, etc.)                            | none                                                   |
@@ -138,7 +138,7 @@ I won't dwell on this for long, because React is in a **different weight class**
 **Mado wins:**
 
 - bundle size dozens of times smaller;
-- zero infrastructure (no Vite, no Babel, no 200 packages);
+- one conventional Vite transport without a framework compiler or Babel layer;
 - readable in an evening — if something breaks, open `src/`;
 - signals instead of hooks (no "can't use in an if" rules, no stale-closure traps);
 - no need to migrate between major versions.
@@ -194,7 +194,7 @@ This is sufficient for most applications. If you're building Excel in the browse
 Mado is a **narrow** tool with honest positioning. It is strongest where:
 
 1. You want to **own** the code and read it in its entirety.
-2. **Infrastructure simplicity** is critical (no Vite/Webpack/Babel).
+2. **Infrastructure simplicity** is critical (one Vite transport, no custom compiler).
 3. You need **batteries in one box** (router + data + forms + SEO).
 4. You are not a junior and are not afraid of Web Components.
 

package/docs/en/README.md

@@ -1,27 +1,99 @@
-# Mado docs — English
-
-English documentation set.
-
-| Section                 | Source                                                       |
-| ----------------------- | ------------------------------------------------------------ |
-| The Mado way            | [00-the-mado-way.md](./00-the-mado-way.md)                   |
-| Routing                 | [01-routing.md](./01-routing.md)                             |
-| Project layout          | [02-project-layout.md](./02-project-layout.md)               |
-| Static bake & SEO       | [03-static-bake.md](./03-static-bake.md)                     |
-| IDE setup               | [04-ide-setup.md](./04-ide-setup.md)                         |
-| Why Mado                | [05-why-mado.md](./05-why-mado.md)                           |
-| For backenders          | [06-for-backenders.md](./06-for-backenders.md)               |
-| LLM pitfalls            | [07-llm-pitfalls.md](./07-llm-pitfalls.md)                   |
-| LLM zero-history test   | [08-llm-zero-history-test.md](./08-llm-zero-history-test.md) |
-| Shadow DOM vs Light DOM | [09-shadow-vs-light-dom.md](./09-shadow-vs-light-dom.md)     |
-| App architecture        | [10-app-architecture.md](./10-app-architecture.md)           |
-| Layouts                 | [11-layouts.md](./11-layouts.md)                             |
-| Auth and API            | [12-auth-and-api.md](./12-auth-and-api.md)                   |
-| Deployment              | [13-deployment.md](./13-deployment.md)                       |
-| Testing                 | [14-testing.md](./14-testing.md)                             |
-| Error handling          | [15-error-handling.md](./15-error-handling.md)               |
-| Bake cookbook           | [16-bake-cookbook.md](./16-bake-cookbook.md)                 |
-| Shadow DOM + Forms      | [17-shadow-dom-forms.md](./17-shadow-dom-forms.md)           |
-| API freeze map          | [18-api-freeze-map.md](./18-api-freeze-map.md)               |
-| Reactivity ordering     | [19-reactivity-ordering.md](./19-reactivity-ordering.md)     |
-| v1 stability            | [20-v1-stability.md](./20-v1-stability.md)                   |
+# Mado documentation
+
+> Canonical project documentation. English-only since v0.12.
+
+Read top-to-bottom for a complete mental model, or jump to the
+section you need from the matrix below.
+
+## Reading paths
+
+- **First time here?** Start with [00 — The Mado way](./00-the-mado-way.md)
+  and then [01 — Quickstart](./01-quickstart.md).
+- **Already shipped one Mado app?** Skim
+  [10 — Pages and components](./10-pages-and-components.md) and
+  [30 — API freeze map](./30-api-freeze-map.md).
+- **Coming from React / Vue / Next?**
+  [42 — Why Mado](./42-why-mado.md) and
+  [40 — LLM guide](./40-llm-guide.md) cover the mental shifts.
+- **Backend developer?** [41 — For backenders](./41-for-backenders.md)
+  is the express lane.
+
+## Map
+
+### Start here
+
+| Section                       | File                                       |
+| ----------------------------- | ------------------------------------------ |
+| The Mado way (philosophy)     | [00-the-mado-way.md](./00-the-mado-way.md) |
+| Quickstart                    | [01-quickstart.md](./01-quickstart.md)     |
+
+### Concepts (read once)
+
+| Section                            | File                                                       |
+| ---------------------------------- | ---------------------------------------------------------- |
+| Pages and components               | [10-pages-and-components.md](./10-pages-and-components.md) |
+| Templates and signals              | [11-templates-and-signals.md](./11-templates-and-signals.md) |
+| Routing                            | [12-routing.md](./12-routing.md)                           |
+| Data — `resource()` / `mutation()` | [13-data.md](./13-data.md)                                 |
+| Forms                              | [14-forms.md](./14-forms.md)                               |
+| Static snapshots                   | [15-static-snapshots.md](./15-static-snapshots.md)         |
+| App architecture                   | [16-app-architecture.md](./16-app-architecture.md)         |
+
+### Production
+
+| Section            | File                                           |
+| ------------------ | ---------------------------------------------- |
+| Deployment         | [20-deployment.md](./20-deployment.md)         |
+| Error handling     | [21-error-handling.md](./21-error-handling.md) |
+| Testing            | [22-testing.md](./22-testing.md)               |
+| Cookbook           | [23-cookbook.md](./23-cookbook.md)             |
+| Devtools and diagnostics | [24-devtools-and-diagnostics.md](./24-devtools-and-diagnostics.md) |
+
+### Reference
+
+| Section                | File                                                       |
+| ---------------------- | ---------------------------------------------------------- |
+| API freeze map         | [30-api-freeze-map.md](./30-api-freeze-map.md)             |
+| Reactivity ordering    | [31-reactivity-ordering.md](./31-reactivity-ordering.md)   |
+| v1 stability contract  | [32-v1-stability.md](./32-v1-stability.md)                 |
+| Migration 0.12 → 0.13  | [33-migration-0.12-0.13.md](./33-migration-0.12-0.13.md)   |
+
+### Meta
+
+| Section                                                | File                                       |
+| ------------------------------------------------------ | ------------------------------------------ |
+| LLM guide (pitfalls + zero-history test)               | [40-llm-guide.md](./40-llm-guide.md)       |
+| For backenders                                         | [41-for-backenders.md](./41-for-backenders.md) |
+| Why Mado vs Lit / Solid / Svelte / htmx / React        | [42-why-mado.md](./42-why-mado.md)         |
+
+## Migrating from v0.11.x doc layout
+
+The 0.12 release reorganised `docs/en/` into the groups above and
+collapsed several overlapping files. Old → new map:
+
+<!-- docs-lint:allow-legacy-mention -->
+
+| Old (v0.11.x)                       | New (v0.12)                                                |
+| ----------------------------------- | ---------------------------------------------------------- |
+| `01-routing.md`                     | `12-routing.md`                                            |
+| `02-project-layout.md`              | merged into `16-app-architecture.md`                       |
+| `03-static-bake.md`                 | `15-static-snapshots.md`                                   |
+| `04-ide-setup.md`                   | merged into `01-quickstart.md`                             |
+| `05-why-mado.md`                    | `42-why-mado.md`                                           |
+| `06-for-backenders.md`              | `41-for-backenders.md`                                     |
+| `07-llm-pitfalls.md`                | merged into `40-llm-guide.md`                              |
+| `08-llm-zero-history-test.md`       | merged into `40-llm-guide.md`                              |
+| `09-shadow-vs-light-dom.md`         | replaced by `10-pages-and-components.md`                   |
+| `10-app-architecture.md`            | `16-app-architecture.md`                                   |
+| `11-layouts.md`                     | merged into `12-routing.md`                                |
+| `12-auth-and-api.md`                | merged into `13-data.md`                                   |
+| `13-deployment.md`                  | `20-deployment.md`                                         |
+| `14-testing.md`                     | `22-testing.md`                                            |
+| `15-error-handling.md`              | `21-error-handling.md`                                     |
+| `16-bake-cookbook.md`               | `23-cookbook.md`                                           |
+| `17-shadow-dom-forms.md`            | merged into `14-forms.md`                                  |
+| `18-api-freeze-map.md`              | `30-api-freeze-map.md`                                     |
+| `19-reactivity-ordering.md`         | `31-reactivity-ordering.md`                                |
+| `20-v1-stability.md`                | `32-v1-stability.md`                                       |
+
+<!-- /docs-lint:allow-legacy-mention -->

package/docs/recipes/nginx/Containerfile

@@ -0,0 +1,26 @@
+# Optional generated-app container recipe.
+#
+# Usage from your app root after copying this directory to ./docker:
+#   docker build -f docker/Containerfile -t myapp .
+
+FROM node:24-alpine AS builder
+WORKDIR /app
+
+COPY package.json package-lock.json* pnpm-lock.yaml* ./
+RUN if [ -f pnpm-lock.yaml ]; then \
+      corepack enable && pnpm install --frozen-lockfile; \
+    elif [ -f package-lock.json ]; then \
+      npm ci; \
+    else \
+      npm install; \
+    fi
+
+COPY . .
+RUN npm run release
+
+FROM nginx:alpine AS runtime
+COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=builder /app/out /usr/share/nginx/html
+
+EXPOSE 80
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost/ >/dev/null || exit 1

package/docs/recipes/nginx/nginx.conf

@@ -0,0 +1,42 @@
+# Static nginx config for a Mado app released with `mado release`.
+#
+# Serves:
+#   - Vite hashed assets from /assets/ with immutable caching;
+#   - precompressed .gz files written by `mado release`;
+#   - baked route HTML when present;
+#   - _mado/spa.html as the noindex SPA fallback for client-only routes.
+
+server {
+    listen 80;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    gzip_static on;
+    # brotli_static on;  # requires ngx_brotli module
+
+    gzip on;
+    gzip_types text/plain text/css application/javascript application/json image/svg+xml;
+    gzip_min_length 1024;
+    gzip_comp_level 6;
+
+    location ^~ /assets/ {
+        add_header Cache-Control "public, max-age=31536000, immutable";
+        try_files $uri =404;
+    }
+
+    location ~* \.html$ {
+        add_header Cache-Control "no-cache, must-revalidate";
+        try_files $uri =404;
+    }
+
+    location ~* \.(svg|png|jpe?g|gif|ico|webp|avif|woff2?)$ {
+        add_header Cache-Control "public, max-age=86400";
+        try_files $uri =404;
+    }
+
+    location / {
+        add_header Cache-Control "no-cache, must-revalidate";
+        try_files $uri $uri/ /_mado/spa.html;
+    }
+}