@madojs/mado 0.8.0 → 0.10.0

package/docs/en/07-llm-pitfalls.md

@@ -598,6 +598,105 @@ See [`17-shadow-dom-forms.md`](./17-shadow-dom-forms.md) for the full pattern.
 
 ---
 
+## Pitfall #23: signal reads in async functions called from `view()` create effect cycles
+
+**Symptom:** `[mado] effect cycle detected: subscriber re-ran more than 100 times in one flush.`
+
+The router calls `page.view()` inside a reactive effect. Any signal read
+**synchronously** during `view()` subscribes the router's render effect. If that
+signal is then written (e.g. `loading.set(true)`) — the router re-runs `view()`,
+which reads the signal again → infinite loop.
+
+```ts
+// ❌ INFINITE LOOP — loadMore reads signals inside the router's effect
+export default page({
+  view: () => {
+    const cursor = signal<string | null>("start");
+    const loading = signal(false);
+
+    const loadMore = async () => {
+      if (cursor() === null || loading()) return; // ← subscribes render effect!
+      loading.set(true); // ← re-triggers render → loadMore() → ∞
+      const res = await fetch(`/api/items?cursor=${cursor()}`);
+      // ...
+    };
+
+    loadMore(); // called synchronously during view()
+    return html`...`;
+  },
+});
+
+// ✅ CORRECT — wrap signal reads in untracked()
+import { untracked } from "@madojs/mado";
+
+export default page({
+  view: () => {
+    const cursor = signal<string | null>("start");
+    const loading = signal(false);
+
+    const loadMore = async () => {
+      const c = untracked(() => cursor());
+      if (c === null || untracked(() => loading())) return;
+      loading.set(true);
+      const res = await fetch(`/api/items?cursor=${c}`);
+      // ...
+    };
+
+    loadMore();
+    return html`...`;
+  },
+});
+```
+
+**Rule:** Any function that reads signals AND is called synchronously during
+`view()` initialization must use `untracked()` for those reads. This includes:
+
+- Data fetching / loadMore functions
+- IntersectionObserver callbacks set up during init
+- Timer/polling setup functions that check state
+
+Signals read inside the **returned template** (`html\`...\``) are fine — they are
+wrapped in a child-binding function `${() => ...}` which creates its own effect.
+
+---
+
+## Pitfall #24: `setInterval` / manual subscriptions in `page()` view without cleanup
+
+**Symptom:** After navigating away, timers/subscriptions keep running (zombie intervals,
+server logs show polling requests from pages the user already left).
+
+```ts
+// ❌ ZOMBIE — interval survives navigation
+export default page({
+  view: () => {
+    const tick = signal(0);
+    setInterval(() => tick.update((n) => n + 1), 3000); // never cleaned up!
+    return html`<div>${tick}</div>`;
+  },
+});
+
+// ✅ CORRECT — use onDispose for cleanup
+export default page({
+  view: ({ onDispose }) => {
+    const tick = signal(0);
+    const id = setInterval(() => tick.update((n) => n + 1), 3000);
+    onDispose(() => clearInterval(id));
+    return html`<div>${tick}</div>`;
+  },
+});
+```
+
+**Note:** `resource()` and `effect()` created inside `view()` are automatically
+cleaned up on navigation (they register with the page lifecycle). Only raw
+browser APIs need explicit `onDispose()`:
+
+- `setInterval` / `setTimeout`
+- `addEventListener` (on window/document)
+- `WebSocket` / `EventSource`
+- `IntersectionObserver` / `ResizeObserver`
+
+---
+
 ## Cheat-sheet for AI
 
 | If you want to do…                    | Correct in Mado                             |
@@ -619,5 +718,7 @@ See [`17-shadow-dom-forms.md`](./17-shadow-dom-forms.md) for the full pattern.
 | `@customElement('x')`                 | `component('x-name', setup)`                |
 | `host.getAttribute('x')` in render    | `ctx.attr('x', default)` (reactive)         |
 | `jsonFetcher()` with auth             | `apiFetcher()` (attaches Bearer token)      |
+| `setInterval` in page view            | `onDispose(() => clearInterval(id))`        |
+| signal read in view() async init      | `untracked(() => cursor())`                 |
 
 If something doesn't fit this list — open `src/` and **read 500 lines**. Seriously. Mado is intentionally small to be readable.

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

@@ -50,6 +50,11 @@ Look for these after implementation:
 The current `examples/tickets` implementation did not require new public APIs or
 runtime dependencies.
 
+CI runs `npm run llm:smoke` as a deterministic proxy for this task: it verifies
+that `llms.txt` still contains the key guidance, checks the committed
+`examples/tickets` artifact against the required Mado API surface and failure
+patterns, then builds and runs `test/tickets-smoke.test.mjs`.
+
 The main documentation pressure point remains lifecycle: older examples can make
 it look acceptable to create `resource()` directly in `page.view()`. The tickets
 example uses page-level wrapper components instead, so resources are registered

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

@@ -0,0 +1,63 @@
+# API freeze map
+
+> What is public, what is internal, and what SemVer will protect at v1.
+
+Mado's v1 contract is intentionally small. Import application code from the
+package root:
+
+```ts
+import { component, html, resource, routes, signal } from "@madojs/mado";
+```
+
+The only public package subpath is the side-effect devtools module:
+
+```ts
+import "@madojs/mado/devtools.js";
+```
+
+Everything else under `dist/src/` is an implementation detail, even when it is
+visible in the repository.
+
+## Stable public API
+
+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`,
+  `ref`, `classMap`, `styleMap`.
+- Components and CSS: `component`, `css`, `cssVars`.
+- Routing and pages: `routes`, `router`, `page`, `layout`, `nested`,
+  `navigate`, `queryParam`, `prefetchPath`.
+- Data: `resource`, `mutation`, `invalidate`, `jsonFetcher`, `HttpError`.
+- Forms: `useForm`.
+- Head and persistence: `applyHead`, `persisted`.
+- Context: `createContext`, `provide`, `inject`.
+- Advanced lifecycle helpers: `createLifecycle`, `runInLifecycle`,
+  `getCurrentLifecycle`.
+- Public TypeScript types exported from `@madojs/mado`.
+
+## Internal or unstable
+
+These are not public API:
+
+- Package subpaths other than `@madojs/mado` and
+  `@madojs/mado/devtools.js`.
+- Template parser/binding internals such as `html/parser.js`,
+  `html/bindings.js`, `ChildState`, and `EachEntry`.
+- Router implementation modules such as `router/match.js`,
+  `router/navigation.js`, and `router/manifest.js`.
+- Diagnostics internals and all `_testHooks`.
+- Exact generated bundle text, chunk names, and internal file layout.
+
+The repository's tests may import internal files through relative `dist/` paths.
+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
+implementation details as long as the stable API and documented behavior remain
+compatible.
+
+Breaking changes to the stable API require a major version.

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

@@ -0,0 +1,93 @@
+# Reactivity ordering
+
+> The small set of ordering guarantees Mado treats as public behaviour.
+
+Mado's reactivity is synchronous for reads and scheduled for side effects. The
+goal is boring, predictable UI updates rather than a large scheduling model.
+
+## Signals
+
+`signal(value)` returns a getter function. Calling `set(next)` changes the value
+immediately unless `Object.is(previous, next)` is true.
+
+```ts
+const count = signal(0);
+count.set(1);
+count(); // 1, immediately
+```
+
+Computed values are marked before effects run, so an effect that reads a
+computed value observes the current dependencies, not stale cached data.
+
+## Effects
+
+`effect(fn)` runs once immediately. Later dependency changes schedule one effect
+run in a microtask. Tests can call `flushSync()` to drain that queue
+synchronously.
+
+If an effect returns a cleanup function, Mado runs that cleanup before the next
+effect run and again when the effect disposer is called.
+
+```ts
+const stop = effect(() => {
+  const id = setInterval(tick, 1000);
+  return () => clearInterval(id);
+});
+
+stop();
+```
+
+In components and pages, prefer `ctx.onDispose()` / page `onDispose()` for
+unmount cleanup. Effect cleanup is per-run cleanup.
+
+## Batch
+
+`batch(fn)` groups signal writes into one subscriber pass. Effects do not run
+until the outermost batch exits, including nested batches.
+
+```ts
+batch(() => {
+  first.set("Ada");
+  batch(() => last.set("Lovelace"));
+});
+// effects see only the final pair
+```
+
+Observed `computed({ equals })` values also preserve batch atomicity: they
+recompute once after the outermost batch, on the fully applied state. They must
+not observe a half-applied batch such as `(new x, old y)`.
+
+## DOM updates
+
+`render(result, container)` reuses the existing template instance when the next
+render has the same template strings. For child bindings that return a nested
+`html```, Mado applies the same rule: same template strings update in place,
+different template strings rebuild that branch.
+
+This means unrelated signal changes do not recreate an `<input>` inside a
+stable nested template, so focus, DOM state and listeners survive.
+
+Lists should use `each(items, key, renderItem)`. Keys define DOM identity.
+Duplicate keys warn in development and fall back to a positional suffix so every
+item still renders, but duplicate keys are a data bug.
+
+## Component teardown
+
+Custom elements may receive `disconnectedCallback()` followed by
+`connectedCallback()` during a same-tick move. Mado defers component teardown to
+a microtask and cancels it when the element is reconnected, so keyed reorders
+preserve component state. A genuine removal still runs lifecycle cleanup on the
+next microtask.
+
+## Not guaranteed
+
+Mado does not guarantee the exact number of internal scheduler microtasks, the
+order of independent effects that do not share dependencies, generated bundle
+shape, or internal module layout. Those are implementation details.
+
+The invariant tests for this contract live in:
+
+- `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/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/00-the-mado-way.md

@@ -2,9 +2,12 @@
 
 > Une seule bonne façon. Des contrats stricts. Pas de magie.
 
-Mado n'est pas seulement un framework — c'est un **ensemble de conventions**. Si vous les
-respectez, le projet reste compréhensible même avec 200 écrans et 5 développeurs. Si vous
-les enfreignez — les types et le linter vous le diront immédiatement.
+Mado est un framework pour les équipes qui construisent des panneaux d'admin,
+des outils internes et des SPA métier — des apps qui doivent être simples à
+créer et ennuyeuses à maintenir. Pour cela, il impose un **ensemble de
+conventions**. Si vous les respectez, le projet reste compréhensible même avec
+200 écrans et 5 développeurs. Si vous les enfreignez — les types et le linter
+vous le diront immédiatement.
 
 ## Principes
 
@@ -42,13 +45,21 @@ tous écrire de la même manière.
 
 ```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 { 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'` **enregistre** le composant via
@@ -63,7 +74,7 @@ component('x-user-card', () => {
 const user = resource(() => `/api/users/${id()}`, jsonFetcher());
 
 // écriture → mutation
-const save = mutation(api.save, { invalidates: ['/api/users*'] });
+const save = mutation(api.save, { invalidates: ["/api/users*"] });
 ```
 
 Cela fournit la mise en cache, l'annulation, la gestion des erreurs et l'invalidation automatique.
@@ -72,11 +83,11 @@ Cela fournit la mise en cache, l'annulation, la gestion des erreurs et l'invalid
 
 ```ts
 // src/pages/user-profile.ts
-import { page, html, resource, jsonFetcher } from '@madojs/mado';
+import { page, html, resource, jsonFetcher } from "@madojs/mado";
 
 export default page({
   title: ({ id }) => `Utilisateur #${id}`,
-  view:  ({ params }) => html`...`,
+  view: ({ params }) => html`...`,
 });
 ```
 
@@ -101,6 +112,7 @@ Voir [`01-routing.md`](./01-routing.md).
 ## En cas de doute
 
 Si vous vous demandez "quelle est la meilleure façon ici ?" — c'est un signal que :
+
 1. Soit il existe un helper intégré que vous ne connaissez pas (consultez `docs/`).
 2. Soit c'est une nouvelle situation — discutez-en et **consignez-la** dans ce document
    comme une convention supplémentaire.

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/07-llm-pitfalls.md

@@ -619,5 +619,7 @@ Plus de détails : [`17-shadow-dom-forms.md`](./17-shadow-dom-forms.md).
 | `@customElement('x')`                 | `component('x-name', setup)`                |
 | `host.getAttribute('x')` dans render  | `ctx.attr('x', default)` (réactif)          |
 | `jsonFetcher()` avec auth             | `apiFetcher()` (attache le Bearer token)    |
+| `setInterval` dans page view          | `onDispose(() => clearInterval(id))`        |
+| lecture signal dans async init view()  | `untracked(() => cursor())`                 |
 
 Si quelque chose ne rentre pas dans cette liste — ouvrez `src/` et **lisez 500 lignes**. Sérieusement. Mado est intentionnellement petit pour être lisible.

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/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`