@madojs/mado 0.5.0

package/docs/en/00-the-mado-way.md

@@ -0,0 +1,106 @@
+# The Mado Way
+
+> One right way. Strict contracts. No magic.
+
+Mado is not just a framework — it is a **set of conventions**. If you follow them,
+the project stays understandable even with 200 screens and 5 developers. If you
+break them — types and the linter will tell you immediately.
+
+## Principles
+
+1. **One way.** For every task there is one right path, not five. If you write
+   something unusual — ask yourself whether an idiomatic helper already exists.
+2. **Explicitness over magic.** No file-system scanners, no implicit globals, no
+   hidden side-effects. Everything the framework does can be read in a single file.
+3. **Platform first.** If the browser already has a feature — use it directly.
+   No custom abstractions over `fetch`, `<form>`, the History API, or Shadow DOM.
+4. **Strict types.** `tsc --strict --noUncheckedIndexedAccess` always. If
+   something cannot be typed — that is a signal the API is wrong.
+5. **No runtime dependencies.** Every dependency is a years-long commitment; the
+   Web Components ecosystem does not require it.
+
+## Conventions
+
+### Project structure
+
+```
+src/
+├── routes.ts         ← route manifest, one file per project
+├── main.ts           ← entry point: providers + mount <x-app>
+├── pages/            ← one page = one file = `export default page({...})`
+├── components/       ← reusable components, side-effect registration
+├── lib/              ← contexts, API clients, business logic without UI
+└── styles/           ← shared styles (if needed), .ts files with css``
+```
+
+This is **mandatory**, not optional. If a project has 10 developers — they must
+all write the same way.
+
+### One component = one file
+
+```ts
+// src/components/user-card.ts
+import { component, html, css } from '@madojs/mado';
+
+component('x-user-card', () => {
+  return () => html`<div class="card"><slot/></div>`;
+}, {
+  styles: css`.card { padding: 1rem; }`,
+});
+```
+
+`import './components/user-card.js'` **registers** the component via
+`customElements.define`. This is a side effect. Import where the component is needed.
+
+### One way to load data
+
+❌ Do not call `fetch()` directly from a component. Always use:
+
+```ts
+// reading → resource
+const user = resource(() => `/api/users/${id()}`, jsonFetcher());
+
+// writing → mutation
+const save = mutation(api.save, { invalidates: ['/api/users*'] });
+```
+
+This provides caching, cancellation, error handling, and auto-invalidation.
+
+### One way to describe a page
+
+```ts
+// src/pages/user-profile.ts
+import { page, html, resource, jsonFetcher } from '@madojs/mado';
+
+export default page({
+  title: ({ id }) => `User #${id}`,
+  view:  ({ params }) => html`...`,
+});
+```
+
+Three slots — `title`, `load`, `view`. No others. Want something else — that is
+a component or a helper.
+
+### One way to declare routes
+
+See [`01-routing.md`](./01-routing.md).
+
+## What we do NOT do
+
+- ❌ Do not write components without a hyphen. This is the browser rule for
+  custom elements: `user-card` is ok, `usercard` is not.
+- `x-*` is only a convention for Mado examples and tests, not a brand standard.
+  In production use a domain prefix: `app-*`, `crm-*`, `ticket-*`, `admin-*`.
+- ❌ Do not use `innerHTML` directly. Only via `html\`\``.
+- ❌ Do not call `setTimeout`/`setInterval` without cleanup. Only inside `effect()`.
+- ❌ Do not store global mutable state. Use signals and `context`.
+- ❌ Do not add packages without discussion. Every dependency is a commitment.
+
+## When in doubt
+
+If you are asking "what's the best way here?" — that is a signal that:
+1. Either there is a built-in helper you don't know about (check `docs/`).
+2. Or this is a new situation — discuss it and **record** it in this document
+   as one more convention.
+
+"A consistent okay beats a varied ideal."

package/docs/en/01-routing.md

@@ -0,0 +1,204 @@
+# Routing
+
+> One manifest file. No folder scanners. No special characters.
+
+## Why not file-based
+
+In Next/SvelteKit/SolidStart routes appear "magically" from file names. This has
+advantages (URL structure visible in `pages/`), but in production it means:
+
+- An invisible plugin-scanner in the build. Without it the files are just files.
+- Special characters in paths: `[id]`, `(group)`, `_layout`, `+page.svelte`, `...slug`.
+- Server-routes and client-routes get confused.
+- Testing routing is a pain: you need a build-tool emulator.
+
+Mado considers this **too much magic**. We do it differently.
+
+## Manifest
+
+One file — `src/routes.ts`. One object. Read top to bottom.
+
+```ts
+// src/routes.ts
+import { routes } from '@madojs/mado';
+
+export default routes({
+  '/':              () => import('./pages/home.js'),
+  '/about':         () => import('./pages/about.js'),
+  '/users/:id':     () => import('./pages/user-profile.js'),
+  '/users/:id/edit':() => import('./pages/user-edit.js'),
+  '*':              () => import('./pages/not-found.js'),
+});
+```
+
+Want to see all routes? Open `routes.ts`. No surprises.
+
+## What goes on the right side of a path
+
+Every entry is **one of three things**:
+
+### 1. Lazy import (recommended)
+
+```ts
+'/posts': () => import('./pages/posts.js'),
+```
+
+- The browser makes its own chunk when bundling (esbuild --bundle --splitting).
+- The module is loaded only when the user visits the route.
+- Subsequent navigations use the cached result.
+
+### 2. Ready Page (eager)
+
+```ts
+import about from './pages/about.js';
+
+'/about': about,
+```
+
+In the bundle immediately, no delay. Use for critical pages (home, login).
+
+### 3. Nested with layout
+
+```ts
+import { routes, nested } from '@madojs/mado';
+
+export default routes({
+  '/': () => import('./pages/home.js'),
+
+  '/admin/*': nested({
+    layout: () => import('./layouts/admin.js'),
+    routes: {
+      '':       () => import('./pages/admin/dashboard.js'),
+      'users':  () => import('./pages/admin/users.js'),
+      'logs':   () => import('./pages/admin/logs.js'),
+    },
+  }),
+});
+```
+
+A layout is just a regular `page({...})` that renders `ctx.child` wherever it wants:
+
+```ts
+// src/layouts/admin.ts
+import { page, html, css, component } from '@madojs/mado';
+
+export default page({
+  view: ({ child }) => html`
+    <div class="admin">
+      <aside><nav>...</nav></aside>
+      <main>${child}</main>
+    </div>
+  `,
+});
+```
+
+## Page contract
+
+```ts
+import { page, html, resource, jsonFetcher } from '@madojs/mado';
+
+export default page({
+  title: ({ id }) => `User #${id}`,        // string | (params) => string
+  load:  ({ id }) => resource(...),         // optional, returns Resource or data
+  view:  ({ params, data, path, child }) => html`...`,  // REQUIRED
+});
+```
+
+Three slots, that's all. If you export something other than `page({...})`, a plain
+function for instance — `routes()` throws a clear error:
+
+```
+[Mado] Lazy route did not return page({...}) as the default export.
+```
+
+## URL parameters
+
+```ts
+'/users/:id': () => import('./pages/user.js'),
+```
+
+```ts
+export default page<{ id: string }>({
+  title: ({ id }) => `User ${id}`,
+  view:  ({ params }) => html`<h1>${params.id}</h1>`,
+});
+```
+
+Types are passed in `page<Params>` — `tsc` verifies that you don't access
+`params.foo` which doesn't exist in the route.
+
+## Global options
+
+```ts
+export default routes(
+  { '/': home, '/about': about, '*': nf },
+  {
+    titleSuffix: ' · MyApp',                       // → "Home · MyApp"
+    loading: () => html`<x-spinner/>`,             // while module loads
+    error:   (err) => html`<x-fatal-error .err=${err}/>`,
+  },
+);
+```
+
+## Programmatic navigation
+
+```ts
+import route from './routes.js';
+
+route.navigate('/posts');
+route.navigate('/posts?page=2');
+route.navigate('/posts', { replace: true });
+```
+
+Clicks on `<a href="/foo" data-link>` are intercepted globally (without the
+attribute — the browser does a full reload, as expected for external links).
+
+## Query parameters
+
+```ts
+import { queryParam } from '@madojs/mado';
+
+const page = queryParam('page', '1');
+page();              // '1'
+page.set('2');       // history.replaceState + re-render
+page.set(null);      // delete the parameter
+page.set('3', { push: true });   // history.pushState
+```
+
+`queryParam` is a normal signal. Use it anywhere: in pages, components, computed.
+
+## What is intentionally absent
+
+- ❌ Auto-scan of `pages/`. **One explicit manifest file**.
+- ❌ Special characters in paths (`[id]`, `(group)`, `_layout`). **Parameters are
+  `:name` only, nothing else**.
+- ❌ Server-side routing in the same manifest. Mado is a client-side framework.
+- ❌ Auto-prefetch on hover. If you really need it — do it manually:
+  `link.addEventListener('mouseenter', loader)`. Usually unnecessary.
+
+## FAQ
+
+**What if I have 100 routes? Won't the file get huge?**
+It will grow to ~150 lines. That is still **one source of truth** versus a hundred
+files in `pages/` with magic names. In practice even large projects (1000+ pages)
+can split into feature manifests:
+
+```ts
+import { routes } from '@madojs/mado';
+import adminRoutes from './features/admin/routes.js';
+import billingRoutes from './features/billing/routes.js';
+
+export default routes({
+  ...adminRoutes,
+  ...billingRoutes,
+  '*': () => import('./pages/not-found.js'),
+});
+```
+
+**How do I test routing?**
+Import `routes.ts` — it is just an object. Substitute your mock router. No build
+tool emulation needed.
+
+**Does code splitting work?**
+Yes. With `esbuild --bundle --splitting --format=esm` every
+`() => import('./pages/x.js')` becomes its own chunk.

package/docs/en/02-project-layout.md

@@ -0,0 +1,58 @@
+# Project layout
+
+Every new Mado project has the same structure. This is a **mandatory** convention.
+
+```
+my-app/
+├── package.json              # exactly 1 dep: typescript (esbuild optional)
+├── tsconfig.json             # with paths "@madojs/mado" → import without relative paths
+├── Dockerfile + nginx.conf   # copied from Mado/ on scaffold
+├── .gitlab-ci.yml | .github/workflows/ci.yml
+├── server/serve.mjs          # dev-server from Mado, no deps
+├── scripts/
+│   ├── bundle.mjs            # esbuild prod bundle
+│   └── new.mjs               # page scaffolder
+├── templates/                # templates for new.mjs
+├── docs/                     # project docs (can copy our guides)
+├── public/                   # static assets (favicon, manifests)
+└── src/
+    ├── main.ts               # entry: providers + mount <x-app>
+    ├── routes.ts             # route manifest
+    ├── pages/                # one page = one file = `export default page({...})`
+    ├── components/           # reusable components (x-*)
+    ├── layouts/              # layout pages (for nested)
+    └── lib/
+        ├── api.ts            # all fetch wrappers
+        ├── contexts.ts       # createContext(...)
+        ├── theme.ts          # themes
+        └── ...               # utilities, types, business rules
+```
+
+## Where to put a new file?
+
+| What | Where |
+|---|---|
+| Page for a new URL | `src/pages/foo.ts` + add to `src/routes.ts` |
+| Reusable UI widget | `src/components/foo-bar.ts` |
+| API wrapper | `src/lib/api.ts` (add a method) |
+| Global context (theme, user, i18n) | `src/lib/<name>.ts` |
+| Pure function without UI | `src/lib/util/<name>.ts` |
+
+If you don't know where — that is a signal that **the architecture is suffering**.
+Ask the team, **record** the answer in `docs/`.
+
+## Naming rules
+
+| What | Style | Example |
+|---|---|---|
+| File | kebab-case | `user-profile.ts` |
+| Component tag | `x-` + kebab | `<x-user-profile>` |
+| Context | PascalCase + `Ctx` | `ThemeCtx`, `AuthCtx` |
+| Signal | camelCase | `userId`, `isLoggedIn` |
+| Page function (internal component) | `x-<route>-page` | `<x-posts-page>` |
+
+## What does NOT go in src/
+
+- ❌ Build tool configs (webpack, rollup, vite) — we don't have any.
+- ❌ `.env` files — env is read from `process.env`/`import.meta.env` in `lib/config.ts`.
+- ❌ Tests mixed with code — all in `test/`.

package/docs/en/03-static-bake.md

@@ -0,0 +1,251 @@
+# Smart Static (`bake`)
+
+> Baking HTML for SEO without runtime SSR. **Idea: data and view in one file, static output.**
+
+`bake` is a **build-time prerender**, not SSR. The output is static `*.html` files that any nginx/Cloudflare serves as regular static content. On the client, Web Components come alive and SPA navigation continues to work.
+
+---
+
+## When `bake` is suitable
+
+- **Marketing pages**: landing pages, sub-landings for advertising campaigns, product pages.
+- **Catalog with a relatively stable set of pages**: blog, documentation, portfolio, e-commerce up to **~10k SKUs** with updates less than once an hour.
+- **Content that is the same for all users**: the entire page is identical for a guest and an authenticated user (or authentication is rendered on the client via `effect()`).
+- You need **good SEO** (rich snippets, OG, JSON-LD) and **fast first paint** without running node servers in production.
+
+## When `bake` is **not** suitable
+
+- **Hundreds of thousands of pages with frequent changes**. `bake` traverses all `paths` synchronously in one run. For 100k+ pages this means minutes of rebuild, and invalidating one page either requires a full rebake or separate CI logic (see below on targeted revalidation).
+- **Personalized content in HTML**. If the page should show "Hello, Ivan" in the `<title>` or in meta — that's not for `bake`. Authenticated dashboards, personal feeds, a cart with real prices for the user — keep these as SPA.
+- **Server-only APIs are needed in render**: cookies, headers, real network requests to private APIs. On the bake side only `linkedom` is available, no Node environment for components.
+- **A/B tests and flags that change markup on the first paint**. `bake` will lock in one variant. Handle dynamic behavior on the client via `effect()`.
+- **Real-time / frequently changing data** (stock quotes, warehouse stock by the minute). `bake.revalidate` is metadata, not runtime: the framework does not re-bake anything itself.
+- **Content behind authentication** (admin, internal tools). No need; use SPA mode.
+
+---
+
+## Concept
+
+`page({...})` has four optional slots related to `bake`:
+
+- `head` — meta, OG, JSON-LD.
+- `bake.paths` — list of URL parameters for generation (build-time, can be `async`).
+- `bake.data` — data for a specific URL (build-time, can be `async`).
+- `bake.revalidate` — after how many seconds the cache is stale (written to `<meta>`, real invalidation is handled by your CI/CDN).
+
+The `npm run bake` command traverses all `page` entries with `bake`, generates HTML via `linkedom`, and places it in `out/<path>/index.html`. **No Chromium needed** — `linkedom` is ~50 KB.
+
+---
+
+## Example
+
+```ts
+// src/pages/product.ts
+import { page, component, html } from "@madojs/mado";
+import { findProduct, products, type Product } from "../lib/products.js";
+
+component("x-product-page", ({ host }) => {
+  return () => {
+    const p = findProduct(host.dataset.slug);
+    return p
+      ? html`<h1>${p.name}</h1><p>${p.description}</p>`
+      : html`<p>Not found.</p>`;
+  };
+});
+
+export default page<{ slug: string }, Product | undefined>({
+  title: ({ slug }) => `${findProduct(slug)?.name} — MyShop`,
+
+  head: ({ slug }, baked) => {
+    const p = baked ?? findProduct(slug);
+    if (!p) return {};
+    return {
+      description: p.description,
+      canonical: `/product/${p.slug}`,
+      og: { title: p.name, image: p.image, type: "product" },
+      jsonLd: {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        name: p.name,
+        offers: { "@type": "Offer", price: p.price, priceCurrency: p.currency },
+      },
+    };
+  },
+
+  bake: {
+    paths: () => products.map((p) => ({ slug: p.slug })),
+    data: ({ slug }) => findProduct(slug),
+    revalidate: 3600,
+  },
+
+  view: ({ params }) =>
+    html`<x-product-page data-slug=${params.slug}></x-product-page>`,
+});
+```
+
+```ts
+// src/routes.ts
+import { routes, type RoutesMap } from "@madojs/mado";
+
+// Export BOTH default (RouterApi for runtime) AND manifest (for the bake script).
+export const manifest: RoutesMap = {
+  "/": () => import("./pages/home.js"),
+  "/product/:slug": () => import("./pages/product.js"),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest, { titleSuffix: " · MyShop" });
+```
+
+## Running
+
+```bash
+npm install -D linkedom esbuild
+npm run build
+npm run bake
+```
+
+You get:
+
+```
+out/
+├── product/
+│   ├── mado-mug/index.html        ← HTML with meta + JSON-LD
+│   ├── raw-bundler/index.html
+│   └── shadow-dom/index.html
+└── sitemap.xml
+```
+
+## What's Inside the Generated HTML
+
+```html
+<head>
+  <title>Mado Mug — MyShop</title>
+  <meta name="description" content="..." data-mado-head="baked">
+  <link rel="canonical" href="/product/mado-mug" data-mado-head="baked">
+  <meta property="og:title" content="Mado Mug" data-mado-head="baked">
+  <meta property="og:image" content="..." data-mado-head="baked">
+  <script type="application/ld+json" data-mado-head="baked">
+    {"@context":"https://schema.org","@type":"Product","..."}
+  </script>
+  <meta name="bake-revalidate" content="3600" data-mado-head="baked">
+  <meta name="bake-stamp" content="1234567890" data-mado-head="baked">
+</head>
+<body>
+  <div id="app">
+    <x-product-page data-slug="mado-mug">
+      <h1>Mado Mug</h1>
+      <p>A mug with the inscription "zero dependencies".</p>
+      <strong>12 EUR</strong>
+    </x-product-page>
+  </div>
+
+  <!-- preloaded data for hydration -->
+  <script id="bake" type="application/json">
+    {"slug":"mado-mug","name":"Mado Mug","price":12,"..."}
+  </script>
+
+  <script type="module" src="/dist/examples/main.js"></script>
+</body>
+```
+
+After JS loads:
+
+1. Web Components `<x-product-page>` come alive (the browser already knows the custom elements).
+2. `page.load()` receives `baked` as initialData — no unnecessary `fetch` calls.
+3. SPA navigation continues to work as normal.
+
+---
+
+## Cookbook: Typical Scenarios
+
+### Blog (Markdown → bake)
+
+```ts
+// src/lib/posts.ts
+import { readdirSync, readFileSync } from "node:fs";
+// (this module is imported only from the bake script,
+// it must not end up in the browser graph — put it in lib/server/ or ifdef it out)
+
+export const allPosts = () =>
+  readdirSync("content/blog").map((file) => ({
+    slug: file.replace(/\.md$/, ""),
+    ...parseFrontmatter(readFileSync(`content/blog/${file}`, "utf-8")),
+  }));
+```
+
+```ts
+// src/pages/blog-post.ts
+import { page, html } from "@madojs/mado";
+import { allPosts } from "../lib/posts.js";
+
+export default page<{ slug: string }>({
+  title: ({ slug }) => allPosts().find((p) => p.slug === slug)?.title ?? slug,
+  head: ({ slug }, post) => ({
+    description: post?.excerpt,
+    canonical: `/blog/${slug}`,
+    og: { title: post?.title, type: "article" },
+  }),
+  bake: {
+    paths: () => allPosts().map(({ slug }) => ({ slug })),
+    data: ({ slug }) => allPosts().find((p) => p.slug === slug),
+  },
+  view: ({ params }) =>
+    html`<x-blog-post data-slug=${params.slug}></x-blog-post>`,
+});
+```
+
+### Product Catalog (e-commerce, ≤ 10k SKUs)
+
+- `bake.paths` → SELECT slug FROM products
+- `bake.data` → SELECT * FROM products WHERE slug=?
+- Full invalidation every N hours via cron + `npm run bake`
+- Targeted invalidation of a single product: webhook → rebuild only that `paths` entry
+
+### Documentation
+
+- `bake.paths` — traversal of the file system `docs/**/*.md`
+- `bake.data` — Markdown parsing
+- `head.jsonLd` — `TechArticle`
+
+---
+
+## Revalidate / CDN
+
+`bake.revalidate: 3600` writes `<meta name="bake-revalidate" content="3600">` and `bake-stamp` to the HTML. This is **metadata** — the framework does not re-bake anything itself. Strategies:
+
+1. **Simplest option**: cron in CI — `npm run bake && rsync out/ origin:/var/www/`.
+2. **Via CDN** (Cloudflare/Fastly): serve HTML with `Cache-Control: max-age=3600`. CDN invalidates itself.
+3. **Webhook trigger**: shop API → POST `/_revalidate?path=/product/mado-mug` → CI re-bakes only that page (you can implement `bake.paths` to return a targeted list based on an env parameter).
+
+---
+
+## Comparison with Alternatives
+
+|                          | Next.js SSG/ISR    | playwright-prerender | **mado bake** |
+|--------------------------|--------------------|----------------------|-----------------|
+| Chrome required in CI    | no                 | **yes** (~300 MB)    | **no**          |
+| Node required in production | for ISR         | no                   | **no**          |
+| Time for 1000 pages      | minutes            | minutes              | **seconds**     |
+| Magic level              | high               | low                  | **zero**        |
+| HTML parser              | React renderer     | browser              | linkedom (~50 KB) |
+| Configuration            | next.config.js + … | single script        | single script   |
+| Source of truth view+data | separate          | page                 | **one page**    |
+
+---
+
+## Limitations and Gotchas
+
+- **There is no browser on the bake side.** The following do not work: `setTimeout` (technically it works, but bake finishes before it fires), `fetch` to relative URLs, any `effect()`/`signal()` side effects, real `requestAnimationFrame`. The render function must be deterministic based on `params` / `data`.
+- **`linkedom` ≠ browser.** Not all DOM APIs are supported (for example, `HTMLElement.click()` behaves more simply). Heavy logic in Web Components will only execute in the browser after `connectedCallback`; only what rendered synchronously on the first pass will end up in the baked HTML.
+- **Render dynamic content on the client.** Current time, A/B tests, geo-banners, the user's cart — these must not be in the baked HTML. Use `effect()` for client-side rendering.
+- **Server-side imports must not end up in the client graph.** If `lib/posts.ts` imports `node:fs`, it cannot be imported from `view`. Keep such modules in a separate folder (`lib/build/`) and use them only from `bake.paths`/`bake.data`.
+- **`paths` and `data` are executed on every bake run.** If they involve a heavy database query — cache at the script level.
+
+---
+
+## TL;DR
+
+If a page is **the same for all users**, has **a relatively stable set of URLs**, and **SEO + first paint** matter — add `bake: { paths, data }` and get static HTML with meta/JSON-LD/sitemap in milliseconds. No node server, no Chrome, no magic.
+
+If the page is personalized, or there are millions of URLs, or content changes in real time — `bake` is not your tool. Keep it as SPA or bring in a separate SSR framework.