@madojs/mado 0.8.0 → 0.10.0

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/00-the-mado-way.md

@@ -2,7 +2,11 @@
 
 > Один правильный путь. Жёсткие контракты. Никакой магии.
 
-Mado — это не просто фреймворк, это **набор соглашений**. Если ты следуешь им, проект остаётся понятным даже когда в нём 200 экранов и 5 разработчиков. Если нарушаешь — типы и линтер скажут об этом сразу.
+Mado — фреймворк для команд, которые строят админки, внутренние инструменты
+и бизнес-SPA — приложения, которые должны быть просты в разработке и скучны
+в поддержке. Для этого он задаёт **набор соглашений**. Если ты следуешь им,
+проект остаётся понятным даже когда в нём 200 экранов и 5 разработчиков. Если
+нарушаешь — типы и линтер скажут об этом сразу.
 
 ## Принципы
 
@@ -32,13 +36,21 @@ src/
 
 ```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'` **регистрирует** компонент через `customElements.define`. Это side-effect. Где компонент нужен — там и импортируем.
@@ -52,7 +64,7 @@ component('x-user-card', () => {
 const user = resource(() => `/api/users/${id()}`, jsonFetcher());
 
 // запись → mutation
-const save = mutation(api.save, { invalidates: ['/api/users*'] });
+const save = mutation(api.save, { invalidates: ["/api/users*"] });
 ```
 
 Это даёт кеш, отмену, обработку ошибок, авто-инвалидацию.
@@ -61,11 +73,11 @@ const save = mutation(api.save, { invalidates: ['/api/users*'] });
 
 ```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 }) => `User #${id}`,
-  view:  ({ params }) => html`...`,
+  view: ({ params }) => html`...`,
 });
 ```
 
@@ -87,6 +99,7 @@ export default page({
 ## Когда сомневаешься
 
 Если ты задаёшься вопросом "а как тут лучше?" — это сигнал, что:
+
 1. Либо есть встроенный хелпер, который ты не знаешь (загляни в `docs/`).
 2. Либо это новая ситуация — её надо обсудить и **зафиксировать** в этом документе как ещё одно соглашение.
 

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

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

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

@@ -618,5 +618,7 @@ component("x-input", ({ host, attr }) => {
 | `@customElement('x')`                 | `component('x-name', setup)`                |
 | `host.getAttribute('x')` в render     | `ctx.attr('x', default)` (реактивно)        |
 | `jsonFetcher()` с авторизацией        | `apiFetcher()` (прикрепляет Bearer токен)   |
+| `setInterval` в page view             | `onDispose(() => clearInterval(id))`        |
+| чтение сигнала в async init view()    | `untracked(() => cursor())`                 |
 
 Если что-то не подходит из этого списка — открой `src/` и **прочитай 500 строк**. Это серьёзно. Mado специально маленький, чтобы быть читаемым.

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

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

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

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

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

@@ -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/00-the-mado-way.md

@@ -2,7 +2,9 @@
 
 > Один зрозумілий шлях. Жорсткі контракти. Мінімум магії.
 
-Mado — це не лише набір API, а набір домовленостей. Якщо їх дотримуватись,
+Mado — фреймворк для команд, що будують адмін-панелі, внутрішні інструменти
+та бізнес-SPA — застосунки, які мають бути простими у розробці та нудними в
+підтримці. Для цього він задає **набір домовленостей**. Якщо їх дотримуватись,
 проєкт залишається читабельним навіть тоді, коли в ньому десятки сторінок і
 кілька розробників.
 

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

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

@@ -141,3 +141,5 @@ Object.defineProperty(host, "value", {
 | `class extends HTMLElement` | `component('x-name', setup)` |
 | `host.getAttribute('x')`    | `ctx.attr('x', default)`     |
 | `jsonFetcher()` з auth      | `apiFetcher()`               |
+| `setInterval` в page view   | `onDispose(() => clearInterval(id))` |
+| читання сигналу в async init | `untracked(() => cursor())`  |

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

@@ -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.

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

@@ -0,0 +1,61 @@
+# Карта замороження 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 parser/binding: `html/parser.js`, `html/bindings.js`,
+  `ChildState`, `EachEntry`.
+- Internals router: `router/match.js`, `router/navigation.js`,
+  `router/manifest.js`.
+- Diagnostics internals і всі `_testHooks`.
+- Точний текст bundle, назви chunks і внутрішня структура файлів.
+
+Тести репозиторію можуть імпортувати internal files через відносні шляхи
+`dist/`. Код застосунків не повинен цього робити.
+
+## Що може змінюватися
+
+Patch і minor releases можуть додавати root exports, options, diagnostics, docs
+або starter files. Вони також можуть змінювати internals, форму bundle і деталі
+реалізації, якщо stable API та задокументована поведінка лишаються сумісними.
+
+Breaking changes стабільного API потребують major version.