@madojs/mado 0.9.0 → 0.10.1

package/docs/en/20-v1-stability.md

@@ -0,0 +1,83 @@
+# v1 stability
+
+> What Mado promises after v1, and what remains free to evolve.
+
+Mado v1 means the public app-facing contract is stable enough for real
+business apps. It does not mean every internal file, generated byte, starter
+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)
+
+## Stable under SemVer
+
+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.
+- Template binding syntax: child `${}`, `@event`, `.prop`, `?boolean`,
+  attribute bindings, directives and `each()`.
+- Signal semantics documented in the reactivity ordering guide.
+- Component lifecycle semantics: setup once per connection lifetime, deferred
+  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`, `bundle`, `preview`, `init`, `new`).
+
+Breaking these requires a major version.
+
+## Allowed in minor releases
+
+Minor releases may add:
+
+- New root exports.
+- New options on existing APIs.
+- New diagnostics and warnings.
+- New starters, examples, docs and CLI flags.
+- Performance improvements and internal implementation rewrites.
+
+Minor releases should not require existing correct apps to change code.
+
+## Allowed in patch releases
+
+Patch releases may fix bugs, tighten diagnostics, improve docs, and make
+compatible implementation changes. A patch may change timing only when the old
+timing was an undocumented bug and the change preserves the documented
+reactivity ordering contract.
+
+## Not stable
+
+These are intentionally not SemVer-protected:
+
+- Internal package subpaths other than `@madojs/mado/devtools.js`.
+- Files under `src/`, `dist/src/`, and implementation module boundaries.
+- `_testHooks`, diagnostics internals and warning codes.
+- Exact generated JavaScript text, chunk names, sourcemap content and bundle
+  byte layout.
+- Internal parser, binding, router and resource cache data structures.
+- Starter app visual copy and demo data.
+
+Apps should not import internal files or assert exact bundle output.
+
+## Bundle and release output
+
+Mado will keep a size budget and deterministic release tests, but v1 stability
+does not freeze byte-for-byte bundler output. Hashes, chunk boundaries and
+generated asset names may change as long as the documented deployment contract
+continues to work.
+
+## If a release breaks you
+
+If an update breaks code that uses only public exports and documented behaviour,
+treat it as a bug. Open an issue with:
+
+- the Mado version before and after;
+- the public API involved;
+- a minimal reproduction;
+- whether the break is runtime behaviour, TypeScript types, CLI output or docs.
+
+If the break depends on an internal subpath or exact generated output, it may
+still be worth reporting, but it is not considered a SemVer break.

package/docs/en/README.md

@@ -22,3 +22,6 @@ English documentation set.
 | 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)                   |

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

@@ -4,20 +4,14 @@ Chaque nouveau projet Mado a la même structure. C'est une convention **obligato
 
 ```
 my-app/
-├── package.json              # exactement 1 dép : typescript (esbuild optionnel)
-├── tsconfig.json             # avec paths "@madojs/mado" → import sans chemins relatifs
-├── Dockerfile + nginx.conf   # copiés depuis Mado/ lors du scaffold
-├── .gitlab-ci.yml | .github/workflows/ci.yml
-├── server/serve.mjs          # dev-server de Mado, sans dépendances
-├── scripts/
-│   ├── bundle.mjs            # bundle de production esbuild
-│   └── new.mjs               # générateur de pages
-├── templates/                # templates pour new.mjs
-├── docs/                     # documentation du projet (vous pouvez copier nos guides)
-├── public/                   # assets statiques (favicon, manifests)
+├── package.json              # runtime dep: @madojs/mado
+├── tsconfig.json             # strict TS, ES2022, Bundler resolution
+├── mado.config.json          # configuration dev/build/bake/bundle
+├── index.html                # shell SPA et template pour bake
+├── public/                   # assets statiques (favicon, images, robots.txt)
 └── src/
-    ├── main.ts               # entrée : providers + montage de <x-app>
-    ├── routes.ts             # manifeste de routes
+    ├── main.ts               # entrée : mount router dans #app
+    ├── routes.ts             # route manifest (default + named manifest)
     ├── pages/                # une page = un fichier = `export default page({...})`
     ├── components/           # composants réutilisables (x-*)
     ├── layouts/              # pages de layout (pour nested)
@@ -28,6 +22,19 @@ my-app/
         └── ...               # utilitaires, types, règles métier
 ```
 
+## États Des Artefacts
+
+| Dossier | Ce que c'est | Écrit par | Déployer ? |
+|---|---|---|---|
+| `src/` | sources TypeScript | vous | non |
+| `dist/` | output `tsc`, native ESM pour dev | `mado build` | non |
+| `public/` | assets statiques écrits par vous | vous | via `out/` |
+| `out/` | artefact déployable : shell SPA + bundles + HTML baked promu | `mado release` | oui |
+
+`mado release` = `typecheck` + `build` (`dist/`) + `bundle`
+(`out/assets/`) + `bake` (`out/baked/`) + promotion du HTML baked et de
+`sitemap.xml` dans les chemins déployables de `out/` + copie de `public/*`.
+
 ## Où mettre un nouveau fichier ?
 
 | Quoi | Où |

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

@@ -148,7 +148,6 @@ out/
     {"@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">
@@ -231,7 +230,7 @@ export default page<{ slug: string }>({
 
 ## Revalidate / CDN
 
-`bake.revalidate: 3600` écrit `<meta name="bake-revalidate" content="3600">` et `bake-stamp`
+`bake.revalidate: 3600` écrit `<meta name="bake-revalidate" content="3600">`
 dans le HTML. C'est des **métadonnées** — le framework ne re-bake rien lui-même. Stratégies :
 
 1. **Option la plus simple** : cron dans CI — `npm run bake && rsync out/ origin:/var/www/`.

package/docs/fr/06-for-backenders.md

@@ -154,6 +154,12 @@ await save.run(newUser);
 // automatiquement : user.data() se mettra à jour si le glob correspond
 ```
 
+Les clés de `resource()` sont l'identité du cache. Incluez l'endpoint, les query
+params et la forme des données dans la clé : deux `resource()` vivants avec la
+même clé partagent le cache et la requête in-flight. Si la même clé est utilisée
+avec un fetcher différent, Mado avertit, car cela signifie généralement que la
+clé de cache est trop large.
+
 Si une telle abstraction existait dans le monde Go pour les caches côté serveur — on
 pleurerait tous de joie.
 

package/docs/fr/08-llm-zero-history-test.md

@@ -53,6 +53,11 @@ Cherchez ces éléments après l'implémentation :
 L'implémentation actuelle de `examples/tickets` n'a pas nécessité de nouvelles API publiques ni
 de dépendances runtime.
 
+CI exécute `npm run llm:smoke` comme proxy déterministe pour cette tâche :
+il vérifie que `llms.txt` contient toujours les règles clés, compare l'artefact
+commité `examples/tickets` à la surface API Mado requise et aux failure
+patterns, puis build le projet et lance `test/tickets-smoke.test.mjs`.
+
 Le principal point de pression dans la documentation reste le lifecycle : les anciens exemples
 peuvent donner l'impression qu'il est acceptable de créer `resource()` directement dans
 `page.view()`. L'exemple tickets utilise plutôt des composants wrapper au niveau page, de sorte

package/docs/fr/13-deployment.md

@@ -1,6 +1,6 @@
 # Déploiement
 
-Une commande, un artefact :
+Une commande, un artefact déployable :
 
 ```bash
 mado release
@@ -10,30 +10,51 @@ Résultat :
 
 ```txt
 out/
-├── index.html
-├── assets/
-├── baked/
-├── _redirects
-└── _headers
+├── index.html              ← shell SPA ou HTML baked promu pour /
+├── assets/                 ← bundles hashés (main-ABC.js, chunk-XYZ.js, ...)
+│   ├── *.gz                ← gzip précompressé
+│   └── *.br                ← brotli précompressé
+├── baked/                  ← copie de bake pour inspection/debugging
+│   ├── <route>/index.html
+│   └── sitemap.xml
+├── <route>/index.html      ← HTML baked promu pour les hébergeurs statiques
+├── sitemap.xml             ← sitemap à la racine du site
+├── _redirects              ← fallback SPA Cloudflare Pages / Netlify
+└── _headers                ← règles de cache
 ```
 
 Déploie `out/` sur nginx, Cloudflare Pages, Netlify, S3/CloudFront ou GitHub
-Pages.
+Pages. Ne déploie pas `dist/` : c'est un output interne.
+
+## Preview
 
 ```bash
 mado release
 mado preview
 ```
 
-`mado preview` sert `out/` comme un hébergeur statique : HTML baked d'abord,
-fallback SPA ensuite.
+`mado preview` sert le `out/` final comme un hébergeur statique : fichiers réels
+d'abord (`/<route>/index.html` si la route est baked), fallback SPA ensuite.
+Preview ne fait plus de mapping virtuel depuis `out/baked/`, donc il vérifie
+exactement ce qui sera déployé.
 
-Pour VPS + nginx :
+## VPS + nginx
 
 ```bash
 mado release
 rsync -avz --delete out/ user@server:/var/www/myapp/
 ```
 
-Le `nginx.conf` fourni gère cache immutable pour les bundles hashés, no-cache
-pour HTML, et fallback SPA pour les deep links.
+Le `nginx.conf` fourni gère le cache immutable pour les bundles hashés, no-cache
+pour HTML, et le fallback SPA pour les deep links.
+
+## Cloudflare / Netlify
+
+```bash
+mado release
+npx wrangler pages deploy out --project-name=myapp
+```
+
+`_redirects` et `_headers` sont générés automatiquement si tu n'en fournis pas.
+Les routes baked sont promues en vrais fichiers (`out/<route>/index.html`), donc
+l'hébergeur statique les sert avant le fallback SPA.

package/docs/fr/16-bake-cookbook.md

@@ -1,8 +1,10 @@
-# Bake cookbook
+# Bake Cookbook
 
 `mado bake` rend certaines routes en HTML statique. C'est pour le SEO et un
 premier rendu rapide, pas pour SSR + hydration.
 
+## Page Minimale
+
 ```ts
 export default page({
   head: () => ({ title: "Products", description: "Catalog" }),
@@ -21,15 +23,66 @@ export default page({
 ```
 
 Dans les vues baked, préfère les tableaux simples (`items.map(...)`). Les
-directives runtime comme `each()` sont pour le navigateur.
+directives runtime comme keyed `each()` sont pour le navigateur.
+
+## Routes Dynamiques
+
+```ts
+export default page<{ slug: string }>({
+  head: ({ slug }, data) => ({ title: data.title, canonical: `/blog/${slug}` }),
+  view: ({ data }) => html`<article>${unsafeHTML(data.html)}</article>`,
+  bake: {
+    paths: async () => (await api.posts()).map((p) => ({ slug: p.slug })),
+    data: ({ slug }) => api.post(slug),
+  },
+});
+```
+
+Utilise `unsafeHTML()` seulement pour du HTML fiable ou déjà nettoyé.
+
+## Route Manifest
+
+`mado bake` a besoin du manifest source :
 
 ```ts
 export const manifest = {
   "/": () => import("./pages/home.js"),
   "/blog/:slug": () => import("./pages/blog-post.js"),
 };
+
 export default routes(manifest);
 ```
 
-`mado release` produit l'artefact déployable dans `out/`. Si bake signale une
-valeur non supportée, remplace la partie runtime-only ou rends-la côté client.
+## Output
+
+Standalone `mado bake` écrit les pages baked dans `out/baked/` par défaut.
+`mado release` utilise le shell de production bundlé, garde cette copie
+`out/baked/` pour inspection, promeut le HTML dans les vrais chemins de route
+dans `out/`, et copie le sitemap vers `out/sitemap.xml`.
+
+```bash
+mado release
+tree out
+```
+
+Le dossier déployable est `out/`, pas `dist/`.
+
+## Client Boot
+
+Le HTML baked marque `#app` avec `data-mado-baked`. Ce n'est pas de
+l'hydration : au démarrage, `render()` remplace le DOM baked par les bindings
+vivants de l'application.
+
+## Valeurs Non Supportées
+
+Bake échoue volontairement au lieu d'écrire `[object Object]`. Si une vue baked
+signale une directive non supportée :
+
+- remplace `each()` par `items.map(...)` dans le markup baked ;
+- garde les widgets interactifs dans des routes client-only ;
+- assure-toi que chaque valeur peut être sérialisée en HTML statique.
+
+## Canonical Links
+
+Passe `--base-url` ou configure `bake.baseUrl` dans `mado.config.json` pour que
+les liens canonical et le sitemap pointent vers la production.

package/docs/fr/18-api-freeze-map.md

@@ -0,0 +1,63 @@
+# Carte de gel de l'API
+
+> Ce qui est public, ce qui est interne, et ce que SemVer protégera en v1.
+
+Le contrat v1 de Mado est volontairement petit. Le code applicatif importe
+depuis la racine du package :
+
+```ts
+import { component, html, resource, routes, signal } from "@madojs/mado";
+```
+
+Le seul subpath public est le module side-effect devtools :
+
+```ts
+import "@madojs/mado/devtools.js";
+```
+
+Tout le reste sous `dist/src/` est un détail d'implémentation, même si le
+fichier est visible dans le dépôt.
+
+## API publique stable
+
+Ces noms sont publics et protégés par SemVer une fois v1 publiée :
+
+- Réactivité : `signal`, `computed`, `effect`, `untracked`, `batch`,
+  `flushSync`.
+- Templates et directives : `html`, `render`, `each`, `list`, `unsafeHTML`,
+  `ref`, `classMap`, `styleMap`.
+- Composants et CSS : `component`, `css`, `cssVars`.
+- Routage et pages : `routes`, `router`, `page`, `layout`, `nested`,
+  `navigate`, `queryParam`, `prefetchPath`.
+- Data : `resource`, `mutation`, `invalidate`, `jsonFetcher`, `HttpError`.
+- Formulaires : `useForm`.
+- Head et persistence : `applyHead`, `persisted`.
+- Context : `createContext`, `provide`, `inject`.
+- Helpers lifecycle avancés : `createLifecycle`, `runInLifecycle`,
+  `getCurrentLifecycle`.
+- Types TypeScript publics exportés depuis `@madojs/mado`.
+
+## Interne ou instable
+
+Ce n'est pas de l'API publique :
+
+- Subpaths du package autres que `@madojs/mado` et
+  `@madojs/mado/devtools.js`.
+- Internals du parser/binding comme `html/parser.js`, `html/bindings.js`,
+  `ChildState` et `EachEntry`.
+- Internals du routeur comme `router/match.js`, `router/navigation.js` et
+  `router/manifest.js`.
+- Internals de diagnostics et tous les `_testHooks`.
+- Texte exact du bundle généré, noms des chunks et layout interne des fichiers.
+
+Les tests du dépôt peuvent importer des fichiers internes via des chemins
+relatifs `dist/`. Le code applicatif ne doit pas le faire.
+
+## Ce qui peut changer
+
+Les patch et minor releases peuvent ajouter des root exports, options,
+diagnostics, docs ou starters. Elles peuvent aussi changer les internals, la
+forme du bundle et les détails d'implémentation tant que l'API stable et le
+comportement documenté restent compatibles.
+
+Les changements cassants de l'API stable nécessitent une version majeure.

package/docs/fr/19-reactivity-ordering.md

@@ -0,0 +1,97 @@
+# Ordre de la réactivité
+
+> Le petit ensemble de garanties d'ordre que Mado traite comme comportement public.
+
+La réactivité de Mado est synchrone pour les lectures et planifiée pour les
+side effects. Le but est une mise à jour UI prévisible plutôt qu'un grand modèle
+de scheduling.
+
+## Signals
+
+`signal(value)` renvoie une fonction getter. `set(next)` change la valeur
+immédiatement sauf si `Object.is(previous, next)` vaut `true`.
+
+```ts
+const count = signal(0);
+count.set(1);
+count(); // 1, immédiatement
+```
+
+Les computed values sont marquées avant l'exécution des effects : un effect qui
+lit un computed observe les dépendances courantes, pas un cache obsolète.
+
+## Effects
+
+`effect(fn)` s'exécute une première fois immédiatement. Les changements
+ultérieurs de dépendances planifient une seule exécution en microtask. Les tests
+peuvent appeler `flushSync()` pour vider cette file de façon synchrone.
+
+Si un effect retourne une fonction de cleanup, Mado l'exécute avant l'exécution
+suivante de l'effect et à nouveau quand le disposer est appelé.
+
+```ts
+const stop = effect(() => {
+  const id = setInterval(tick, 1000);
+  return () => clearInterval(id);
+});
+
+stop();
+```
+
+Dans les composants et pages, préférez `ctx.onDispose()` / page `onDispose()`
+pour le cleanup à l'unmount. Le cleanup d'un effect est un cleanup par run.
+
+## Batch
+
+`batch(fn)` regroupe les écritures de signals en un seul passage des
+subscribers. Les effects ne s'exécutent pas avant la sortie du batch le plus
+extérieur, y compris avec des batches imbriqués.
+
+```ts
+batch(() => {
+  first.set("Ada");
+  batch(() => last.set("Lovelace"));
+});
+// les effects ne voient que la paire finale
+```
+
+Les `computed({ equals })` observés préservent aussi l'atomicité du batch : ils
+se recalculent une fois après le batch extérieur, sur l'état entièrement
+appliqué. Ils ne doivent pas observer un batch à moitié appliqué comme
+`(new x, old y)`.
+
+## Mises à jour DOM
+
+`render(result, container)` réutilise l'instance de template existante quand le
+render suivant a les mêmes template strings. Pour les child bindings qui
+retournent un `html``` imbriqué, la même règle s'applique : mêmes strings =
+mise à jour sur place, autres strings = reconstruction de cette branche.
+
+Ainsi, des changements de signals sans rapport ne recréent pas un `<input>`
+dans un template imbriqué stable : focus, état DOM et listeners survivent.
+
+Les listes doivent utiliser `each(items, key, renderItem)`. Les keys définissent
+l'identité DOM. Les duplicate keys avertissent en development et retombent sur
+un suffixe positionnel pour que chaque item soit rendu, mais les duplicate keys
+sont un bug de données.
+
+## Teardown des composants
+
+Les custom elements peuvent recevoir `disconnectedCallback()` puis
+`connectedCallback()` pendant un déplacement dans le même tick. Mado diffère le
+teardown du composant jusqu'à une microtask et l'annule si l'élément est
+reconnecté, donc les reorders keyed préservent l'état du composant. Une vraie
+suppression lance tout de même le cleanup lifecycle à la microtask suivante.
+
+## Non garanti
+
+Mado ne garantit pas le nombre exact de microtasks internes du scheduler,
+l'ordre des effects indépendants sans dépendances communes, la forme du bundle
+généré ni le layout interne des modules. Ce sont des détails d'implémentation.
+
+Les tests invariants de ce contrat vivent dans :
+
+- `test/reactivity-ordering.test.mjs`
+- `test/signal-batch-equals.test.mjs`
+- `test/update-nested-reuse.test.mjs`
+- `test/each-component-state.test.mjs`

package/docs/fr/20-v1-stability.md

@@ -0,0 +1,88 @@
+# Stabilité v1
+
+> Ce que Mado promet après v1, et ce qui reste libre d'évoluer.
+
+Mado v1 signifie que le contrat public côté application est assez stable pour
+de vraies applications métier. Cela ne veut pas dire que chaque fichier interne,
+octet généré, starter copy ou diagnostic string est gelé pour toujours.
+
+À lire avec :
+
+- [Carte de gel de l'API](./18-api-freeze-map.md)
+- [Ordre de la réactivité](./19-reactivity-ordering.md)
+
+## Stable sous SemVer
+
+Après v1, Mado considère comme protégés par SemVer :
+
+- Les exports publics de `@madojs/mado`.
+- Les types TypeScript publics exportés depuis `@madojs/mado`.
+- Le subpath side-effect `@madojs/mado/devtools.js`.
+- La syntaxe de template binding : child `${}`, `@event`, `.prop`,
+  `?boolean`, attribute bindings, directives et `each()`.
+- Les semantics des signals documentées dans le guide d'ordre de réactivité.
+- Les semantics du lifecycle composant : setup une fois par connection
+  lifetime, teardown différé pour les same-tick moves, cleanup via
+  `ctx.onDispose`.
+- Les contrats router/page/resource/form documentés dans les docs anglaises.
+- Les noms de commandes CLI et leur intention générale (`build`, `dev`,
+  `release`, `bake`, `bundle`, `preview`, `init`, `new`).
+
+Casser cela nécessite une version majeure.
+
+## Autorisé en minor releases
+
+Les minor releases peuvent ajouter :
+
+- De nouveaux root exports.
+- De nouvelles options sur des API existantes.
+- De nouveaux diagnostics et warnings.
+- De nouveaux starters, examples, docs et flags CLI.
+- Des améliorations de performance et des rewrites internes.
+
+Une minor release ne devrait pas forcer les apps correctes existantes à changer
+leur code.
+
+## Autorisé en patch releases
+
+Les patch releases peuvent corriger des bugs, durcir les diagnostics, améliorer
+les docs et faire des changements d'implémentation compatibles. Un patch peut
+changer le timing seulement si l'ancien timing était un bug non documenté et
+que le changement conserve le contrat d'ordre de réactivité.
+
+## Non stable
+
+Ne sont volontairement pas protégés par SemVer :
+
+- Les subpaths internes du package autres que `@madojs/mado/devtools.js`.
+- Les fichiers sous `src/`, `dist/src/` et les frontières de modules
+  d'implémentation.
+- `_testHooks`, internals de diagnostics et warning codes.
+- Le JavaScript exact généré, les noms de chunks, le contenu sourcemap et le
+  byte layout du bundle.
+- Les structures internes du parser, des bindings, du routeur et du cache
+  resource.
+- Le texte visuel et les données de démonstration des starters.
+
+Les apps ne doivent pas importer de fichiers internes ni vérifier l'output exact
+du bundle.
+
+## Bundle et output de release
+
+Mado gardera un size budget et des tests de release déterministe, mais la
+stabilité v1 ne fige pas l'output du bundler octet par octet. Les hashes,
+frontières de chunks et noms d'assets générés peuvent changer tant que le
+contrat de déploiement documenté continue de fonctionner.
+
+## Si une release vous casse
+
+Si une mise à jour casse du code qui utilise seulement les exports publics et le
+comportement documenté, traitez-le comme un bug. Ouvrez une issue avec :
+
+- la version de Mado avant et après ;
+- l'API publique impliquée ;
+- une reproduction minimale ;
+- si la casse concerne le runtime, les types TypeScript, l'output CLI ou les docs.
+
+Si la casse dépend d'un subpath interne ou de l'output généré exact, cela peut
+quand même valoir un rapport, mais ce n'est pas considéré comme une casse SemVer.

package/docs/fr/README.md

@@ -22,3 +22,6 @@ Documentation française.
 | Gestion des erreurs           | [15-error-handling.md](./15-error-handling.md)               |
 | Guide de recettes bake        | [16-bake-cookbook.md](./16-bake-cookbook.md)                 |
 | Shadow DOM + formulaires      | [17-shadow-dom-forms.md](./17-shadow-dom-forms.md)           |
+| Carte de gel de l'API         | [18-api-freeze-map.md](./18-api-freeze-map.md)               |
+| Ordre de la réactivité        | [19-reactivity-ordering.md](./19-reactivity-ordering.md)     |
+| Stabilité v1                  | [20-v1-stability.md](./20-v1-stability.md)                   |

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

@@ -1,23 +1,17 @@
-# Project layout
+# Project Layout
 
 Каждый new-проект на Mado имеет одинаковую структуру. Это **обязательное** соглашение.
 
 ```
 my-app/
-├── package.json              # ровно 1 dep: typescript (esbuild опц.)
-├── tsconfig.json             # с paths "@madojs/mado" → импорт без относительных путей
-├── Dockerfile + nginx.conf   # копируем из Mado/ при scaffold
-├── .gitlab-ci.yml | .github/workflows/ci.yml
-├── server/serve.mjs          # dev-сервер из Mado, без deps
-├── scripts/
-│   ├── bundle.mjs            # esbuild прод-бандл
-│   └── new.mjs               # скаффолд страницы
-├── templates/                # шаблоны для new.mjs
-├── docs/                     # проектные доки (можно копировать наши гайды)
-├── public/                   # статика (favicon, манифесты)
+├── package.json              # runtime dep: @madojs/mado
+├── tsconfig.json             # strict TS, ES2022, Bundler resolution
+├── mado.config.json          # dev/build/bake/bundle config
+├── index.html                # SPA shell и template для bake
+├── public/                   # статика (favicon, images, robots.txt)
 └── src/
-    ├── main.ts               # точка входа: провайдеры + монтаж <x-app>
-    ├── routes.ts             # манифест роутов
+    ├── main.ts               # точка входа: mount router в #app
+    ├── routes.ts             # route manifest (default + named manifest)
     ├── pages/                # одна страница = один файл = `export default page({...})`
     ├── components/           # переиспользуемые компоненты (x-*)
     ├── layouts/              # layout-страницы (для nested)
@@ -28,6 +22,19 @@ my-app/
         └── ...               # утилиты, типы, бизнес-правила
 ```
 
+## Artifact States
+
+| Folder | Что это | Кто пишет | Deploy? |
+|---|---|---|---|
+| `src/` | исходники TypeScript | ты | no |
+| `dist/` | output `tsc`, native ESM для dev | `mado build` | no |
+| `public/` | авторская статика | ты | через `out/` |
+| `out/` | deploy artifact: SPA shell + bundles + promoted baked HTML | `mado release` | yes |
+
+`mado release` = `typecheck` + `build` (`dist/`) + `bundle`
+(`out/assets/`) + `bake` (`out/baked/`) + promote baked HTML и
+`sitemap.xml` в deployable `out/` paths + copy `public/*`.
+
 ## Куда положить новый файл?
 
 | Что | Куда |
@@ -54,4 +61,4 @@ my-app/
 
 - ❌ Конфиги билдеров (webpack, rollup, vite) — у нас их нет.
 - ❌ `.env`-файлы — env читается из `process.env`/`import.meta.env` в `lib/config.ts`.
-- ❌ Тесты вперемешку с кодом — все в `test/`.
+- ❌ Тесты вперемешку с кодом — все в `test/`.