npm - @madojs/mado - Versions diffs - 0.9.0 → 0.10.0 - Mend

@madojs/mado 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/AGENTS.md +58 -7
package/CHANGELOG.md +91 -1
package/README.md +20 -4
package/dist/src/component.d.ts +2 -12
package/dist/src/component.js +2 -29
package/dist/src/component.js.map +1 -1
package/dist/src/diagnostics.d.ts +0 -4
package/dist/src/diagnostics.js +1 -0
package/dist/src/diagnostics.js.map +1 -1
package/dist/src/html/bindings.js +3 -0
package/dist/src/html/bindings.js.map +1 -1
package/dist/src/resource.d.ts +3 -6
package/dist/src/resource.js +59 -10
package/dist/src/resource.js.map +1 -1
package/dist/src/router/manifest.d.ts +0 -3
package/dist/src/router/manifest.js +1 -0
package/dist/src/router/manifest.js.map +1 -1
package/dist/src/router.d.ts +1 -1
package/dist/src/router.js +1 -1
package/dist/src/router.js.map +1 -1
package/dist/src/signal.d.ts +0 -4
package/dist/src/signal.js +1 -0
package/dist/src/signal.js.map +1 -1
package/docs/en/03-static-bake.md +1 -2
package/docs/en/06-for-backenders.md +5 -0
package/docs/en/08-llm-zero-history-test.md +5 -0
package/docs/en/18-api-freeze-map.md +63 -0
package/docs/en/19-reactivity-ordering.md +93 -0
package/docs/en/20-v1-stability.md +83 -0
package/docs/en/README.md +3 -0
package/docs/fr/03-static-bake.md +1 -2
package/docs/fr/06-for-backenders.md +6 -0
package/docs/fr/08-llm-zero-history-test.md +5 -0
package/docs/fr/18-api-freeze-map.md +63 -0
package/docs/fr/19-reactivity-ordering.md +97 -0
package/docs/fr/20-v1-stability.md +88 -0
package/docs/fr/README.md +3 -0
package/docs/ru/03-static-bake.md +2 -3
package/docs/ru/06-for-backenders.md +6 -0
package/docs/ru/08-llm-zero-history-test.md +5 -0
package/docs/ru/18-api-freeze-map.md +62 -0
package/docs/ru/19-reactivity-ordering.md +95 -0
package/docs/ru/20-v1-stability.md +82 -0
package/docs/ru/README.md +3 -0
package/docs/uk/06-for-backenders.md +5 -0
package/docs/uk/08-llm-zero-history-test.md +5 -0
package/docs/uk/18-api-freeze-map.md +61 -0
package/docs/uk/19-reactivity-ordering.md +95 -0
package/docs/uk/20-v1-stability.md +83 -0
package/docs/uk/README.md +3 -0
package/llms.txt +59 -5
package/package.json +8 -3
package/scripts/bake.mjs +0 -1
package/scripts/cli.mjs +17 -0
package/scripts/llm-zero-history-smoke.mjs +93 -0
package/scripts/new.mjs +1 -1
package/scripts/package-smoke.mjs +74 -0
package/scripts/size-budget.mjs +88 -0
package/starters/admin/package.json +2 -2
package/starters/crud/package.json +2 -2
package/starters/minimal/package.json +2 -2

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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/03-static-bake.md CHANGED Viewed

@@ -129,7 +129,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">
@@ -212,7 +211,7 @@ export default page<{ slug: string }>({
 ## Revalidate / CDN
-`bake.revalidate: 3600` пишет в HTML `<meta name="bake-revalidate" content="3600">` и `bake-stamp`. Это **метаданные** — фреймворк сам ничего не перевыпекает. Стратегии:
+`bake.revalidate: 3600` пишет в HTML `<meta name="bake-revalidate" content="3600">`. Это **метаданные** — фреймворк сам ничего не перевыпекает. Стратегии:
 1. **Простейший вариант**: cron в CI — `npm run bake && rsync out/ origin:/var/www/`.
 2. **Через CDN** (Cloudflare/Fastly): кладёте HTML с `Cache-Control: max-age=3600`. CDN сам инвалидирует.
@@ -248,4 +247,4 @@ export default page<{ slug: string }>({
 Если страница **общая для всех пользователей**, имеет **относительно стабильный набор URL'ов** и важен **SEO + первый paint** — добавьте `bake: { paths, data }` и получите статический HTML с meta/JSON-LD/sitemap за миллисекунды. Без node-сервера, без Chrome, без магии.
-Если страница персонализирована, или URL'ов миллион, или контент меняется в реальном времени — `bake` не ваш инструмент. Оставляйте SPA или подключайте отдельный SSR-фреймворк.
+Если страница персонализирована, или URL'ов миллион, или контент меняется в реальном времени — `bake` не ваш инструмент. Оставляйте SPA или подключайте отдельный SSR-фреймворк.

package/docs/ru/06-for-backenders.md CHANGED Viewed

@@ -150,6 +150,12 @@ await save.run(newUser);
 // автоматически: user.data() обновится, если совпал glob
 ```
+Ключи `resource()` — это identity кеша. Включайте endpoint, query params и
+форму данных в ключ: два живых `resource()` с одинаковым ключом разделяют кеш
+и in-flight request. Если один и тот же ключ используется с другим fetcher,
+Mado предупреждает, потому что обычно это значит, что ключ кеша слишком
+широкий.
 Если бы такая абстракция была в Go-мире для серверных кешей — мы бы все плакали от счастья.
 ---

package/docs/ru/08-llm-zero-history-test.md CHANGED Viewed

@@ -51,6 +51,11 @@
 Текущая реализация `examples/tickets` не потребовала новых публичных API или
 runtime-зависимостей.
+CI запускает `npm run llm:smoke` как детерминированный proxy для этой задачи:
+проверяет, что `llms.txt` всё ещё содержит ключевые правила, сверяет
+зафиксированный артефакт `examples/tickets` с нужной Mado API surface и
+failure patterns, затем собирает проект и запускает `test/tickets-smoke.test.mjs`.
 Основная болевая точка в документации остается lifecycle: старые примеры могут
 создать впечатление, что создание `resource()` прямо в `page.view()` допустимо.
 Пример tickets использует page-level wrapper-компоненты вместо этого, поэтому

package/docs/ru/18-api-freeze-map.md ADDED Viewed

@@ -0,0 +1,62 @@
+# Карта заморозки API
+> Что публично, что внутреннее, и что SemVer будет защищать в v1.
+Контракт Mado v1 намеренно небольшой. Код приложения импортирует API из корня
+пакета:
+```ts
+import { component, html, resource, routes, signal } from "@madojs/mado";
+```
+Единственный публичный subpath — side-effect модуль devtools:
+```ts
+import "@madojs/mado/devtools.js";
+```
+Все остальное под `dist/src/` — деталь реализации, даже если файл виден в
+репозитории.
+## Стабильный публичный API
+Эти имена публичны и будут защищены SemVer после v1:
+- Reactivity: `signal`, `computed`, `effect`, `untracked`, `batch`,
+  `flushSync`.
+- Templates и directives: `html`, `render`, `each`, `list`, `unsafeHTML`,
+  `ref`, `classMap`, `styleMap`.
+- Components и CSS: `component`, `css`, `cssVars`.
+- Routing и pages: `routes`, `router`, `page`, `layout`, `nested`,
+  `navigate`, `queryParam`, `prefetchPath`.
+- Data: `resource`, `mutation`, `invalidate`, `jsonFetcher`, `HttpError`.
+- Forms: `useForm`.
+- Head и persistence: `applyHead`, `persisted`.
+- Context: `createContext`, `provide`, `inject`.
+- Advanced lifecycle helpers: `createLifecycle`, `runInLifecycle`,
+  `getCurrentLifecycle`.
+- Публичные TypeScript-типы, экспортируемые из `@madojs/mado`.
+## Внутреннее или нестабильное
+Это не публичный API:
+- Package subpaths кроме `@madojs/mado` и `@madojs/mado/devtools.js`.
+- Internals парсера/биндингов: `html/parser.js`, `html/bindings.js`,
+  `ChildState`, `EachEntry`.
+- Internals роутера: `router/match.js`, `router/navigation.js`,
+  `router/manifest.js`.
+- Diagnostics internals и все `_testHooks`.
+- Точный текст bundle, имена chunks и внутренняя структура файлов.
+Тесты репозитория могут импортировать внутренние файлы через относительные
+пути `dist/`. Код приложений так делать не должен.
+## Что может меняться
+Patch и minor релизы могут добавлять root exports, опции, diagnostics, docs или
+starter files. Они также могут менять internals, форму bundle и детали
+реализации, если стабильный API и задокументированное поведение остаются
+совместимыми.
+Ломающие изменения стабильного API требуют major version.

package/docs/ru/19-reactivity-ordering.md ADDED Viewed

@@ -0,0 +1,95 @@
+# Порядок reactivity
+> Небольшой набор ordering-гарантий, которые Mado считает публичным поведением.
+Reactivity в Mado синхронна для чтения и планирует side effects. Цель —
+предсказуемые UI-обновления без большой scheduling-модели.
+## Signals
+`signal(value)` возвращает getter-функцию. `set(next)` меняет значение сразу,
+если `Object.is(previous, next)` не вернул `true`.
+```ts
+const count = signal(0);
+count.set(1);
+count(); // 1, сразу
+```
+`computed` помечается до запуска effects, поэтому effect, читающий computed,
+видит актуальные dependencies, а не старый кеш.
+## Effects
+`effect(fn)` запускается один раз сразу. Последующие изменения dependencies
+планируют один запуск effect в microtask. В тестах можно вызвать `flushSync()`,
+чтобы синхронно очистить очередь.
+Если effect возвращает cleanup-функцию, Mado запускает ее перед следующим
+запуском effect и еще раз при вызове disposer.
+```ts
+const stop = effect(() => {
+  const id = setInterval(tick, 1000);
+  return () => clearInterval(id);
+});
+stop();
+```
+В компонентах и pages для unmount cleanup предпочитайте `ctx.onDispose()` /
+page `onDispose()`. Cleanup effect — это cleanup между запусками.
+## Batch
+`batch(fn)` группирует записи signals в один subscriber pass. Effects не
+запускаются до выхода из внешнего batch, включая вложенные batches.
+```ts
+batch(() => {
+  first.set("Ada");
+  batch(() => last.set("Lovelace"));
+});
+// effects увидят только финальную пару
+```
+Наблюдаемые `computed({ equals })` также сохраняют batch atomicity: они
+пересчитываются один раз после внешнего batch на полностью примененном state.
+Они не должны видеть половинчатый batch вроде `(new x, old y)`.
+## DOM updates
+`render(result, container)` переиспользует существующий template instance, когда
+следующий render имеет те же template strings. Для child bindings, возвращающих
+вложенный `html```, действует то же правило: те же strings обновляются на
+месте, другие strings пересобирают ветку.
+Это значит, что несвязанные изменения signals не пересоздают `<input>` внутри
+стабильного вложенного template, поэтому focus, DOM state и listeners
+сохраняются.
+Списки должны использовать `each(items, key, renderItem)`. Keys задают DOM
+identity. Duplicate keys предупреждают в development и получают positional
+suffix, чтобы все элементы все равно отрендерились, но duplicate keys — это
+ошибка данных.
+## Teardown компонентов
+Custom elements могут получить `disconnectedCallback()`, а затем
+`connectedCallback()` во время same-tick move. Mado откладывает teardown
+компонента до microtask и отменяет его при reconnect, поэтому keyed reorders
+сохраняют state компонента. Настоящее удаление все равно запускает cleanup на
+следующей microtask.
+## Не гарантируется
+Mado не гарантирует точное число внутренних scheduler microtasks, порядок
+независимых effects без общих dependencies, форму generated bundle или
+внутреннюю структуру modules. Это детали реализации.
+Invariant tests для этого контракта:
+- `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/ru/20-v1-stability.md ADDED Viewed

@@ -0,0 +1,82 @@
+# Стабильность v1
+> Что Mado обещает после v1, и что остается свободным для развития.
+Mado v1 означает, что публичный app-facing contract достаточно стабилен для
+реальных business apps. Это не значит, что каждый внутренний файл, generated
+byte, starter copy или diagnostic string заморожены навсегда.
+Читайте вместе с:
+- [Карта заморозки API](./18-api-freeze-map.md)
+- [Порядок reactivity](./19-reactivity-ordering.md)
+## Стабильно под SemVer
+После v1 Mado считает SemVer-protected:
+- Public exports из `@madojs/mado`.
+- Public TypeScript types из `@madojs/mado`.
+- Side-effect subpath `@madojs/mado/devtools.js`.
+- Template binding syntax: child `${}`, `@event`, `.prop`, `?boolean`,
+  attribute bindings, directives и `each()`.
+- Signal semantics, описанные в reactivity ordering guide.
+- Component lifecycle semantics: setup один раз за connection lifetime,
+  deferred teardown для same-tick moves, cleanup через `ctx.onDispose`.
+- Router/page/resource/form contracts, описанные в English docs.
+- Имена CLI commands и широкий смысл команд (`build`, `dev`, `release`,
+  `bake`, `bundle`, `preview`, `init`, `new`).
+Ломать это можно только в major version.
+## Разрешено в minor releases
+Minor releases могут добавлять:
+- New root exports.
+- New options на существующих API.
+- New diagnostics и warnings.
+- New starters, examples, docs и CLI flags.
+- Performance improvements и внутренние rewrites.
+Minor release не должен требовать изменений в уже корректных apps.
+## Разрешено в patch releases
+Patch releases могут исправлять bugs, ужесточать diagnostics, улучшать docs и
+делать совместимые implementation changes. Patch может изменить timing только
+когда старый timing был незадокументированным bug и новое поведение сохраняет
+reactivity ordering contract.
+## Нестабильно
+Это намеренно не защищено SemVer:
+- Internal package subpaths кроме `@madojs/mado/devtools.js`.
+- Файлы под `src/`, `dist/src/` и implementation module boundaries.
+- `_testHooks`, diagnostics internals и warning codes.
+- Точный JavaScript output, chunk names, sourcemap content и bundle byte layout.
+- Internal parser, binding, router и resource cache data structures.
+- Visual copy и demo data в starters.
+Apps не должны импортировать internal files или проверять точный bundle output.
+## Bundle и release output
+Mado держит size budget и deterministic release tests, но v1 stability не
+замораживает byte-for-byte bundler output. Hashes, chunk boundaries и asset
+names могут меняться, если задокументированный deployment contract продолжает
+работать.
+## Если релиз вас сломал
+Если update ломает код, который использует только public exports и
+задокументированное поведение, считайте это bug. Откройте issue и укажите:
+- версию Mado до и после;
+- задействованный public API;
+- минимальную репродукцию;
+- это runtime behaviour, TypeScript types, CLI output или docs.
+Если поломка зависит от internal subpath или точного generated output, ее все
+равно можно зарепортить, но это не считается SemVer break.

package/docs/ru/README.md CHANGED Viewed

@@ -20,3 +20,6 @@
 | Обработка ошибок            | [15-error-handling.md](./15-error-handling.md)               |
 | Рецепты bake                | [16-bake-cookbook.md](./16-bake-cookbook.md)                 |
 | Shadow DOM + формы          | [17-shadow-dom-forms.md](./17-shadow-dom-forms.md)           |
+| Карта заморозки API         | [18-api-freeze-map.md](./18-api-freeze-map.md)               |
+| Порядок reactivity          | [19-reactivity-ordering.md](./19-reactivity-ordering.md)     |
+| Стабильность v1             | [20-v1-stability.md](./20-v1-stability.md)                   |

package/docs/uk/06-for-backenders.md CHANGED Viewed

@@ -26,6 +26,11 @@ const save = mutation(api.saveUser, {
 });
 ```
+Ключі `resource()` — це identity кешу. Додавайте endpoint, query params і форму
+даних у ключ: два живі `resource()` з однаковим ключем ділять cache та
+in-flight request. Якщо той самий ключ використано з іншим fetcher, Mado
+попереджає, бо зазвичай це означає, що ключ кешу занадто широкий.
 ## Форми
 ```ts

package/docs/uk/08-llm-zero-history-test.md CHANGED Viewed

@@ -27,5 +27,10 @@ Mado CRUD, не перетворюючи його на React у tagged templates
 resources, mutations, invalidation, `queryParam`, `computed`, `signal` і
 keyed lists.
+CI запускає `npm run llm:smoke` як детермінований proxy для цієї задачі:
+перевіряє, що `llms.txt` містить ключові правила, звіряє закомічений артефакт
+`examples/tickets` з потрібною Mado API surface та failure patterns, потім
+збирає проєкт і запускає `test/tickets-smoke.test.mjs`.
 Критерій успіху: код виглядає як Mado, а не як React/Vue, переодягнений у
 template strings.