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

@madojs/mado 0.9.0 → 0.10.1

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 (74) hide show

package/AGENTS.md +58 -7
package/CHANGELOG.md +121 -1
package/README.md +21 -5
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/html/template.js +10 -0
package/dist/src/html/template.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/02-project-layout.md +3 -2
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/13-deployment.md +10 -7
package/docs/en/16-bake-cookbook.md +10 -2
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/02-project-layout.md +20 -13
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/13-deployment.md +33 -12
package/docs/fr/16-bake-cookbook.md +57 -4
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/02-project-layout.md +22 -15
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/13-deployment.md +23 -13
package/docs/ru/16-bake-cookbook.md +42 -8
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 +4 -2
package/scripts/cli.mjs +83 -5
package/scripts/llm-zero-history-smoke.mjs +93 -0
package/scripts/new.mjs +1 -1
package/scripts/package-smoke.mjs +74 -0
package/scripts/preview.mjs +7 -27
package/scripts/size-budget.mjs +88 -0
package/starters/admin/README.md +2 -2
package/starters/admin/package.json +2 -2
package/starters/crud/package.json +2 -2
package/starters/minimal/package.json +2 -2

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/13-deployment.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Deployment
-Один command, один artifact:
+Одна команда, один deploy artifact:
 ```bash
 mado release
@@ -10,15 +10,21 @@ mado release
 ```txt
 out/
-├── index.html
-├── assets/
-├── baked/
-├── _redirects
-└── _headers
+├── index.html              ← SPA shell или promoted baked HTML для /
+├── assets/                 ← hashed bundles (main-ABC.js, chunk-XYZ.js, ...)
+│   ├── *.gz                ← precompressed gzip
+│   └── *.br                ← precompressed brotli
+├── baked/                  ← копия результата bake для inspection/debugging
+│   ├── <route>/index.html
+│   └── sitemap.xml
+├── <route>/index.html      ← promoted baked HTML для static hosts
+├── sitemap.xml             ← sitemap в root сайта
+├── _redirects              ← Cloudflare Pages / Netlify SPA fallback
+└── _headers                ← cache rules
 ```
 `out/` можно деплоить на nginx, Cloudflare Pages, Netlify, S3/CloudFront или
-GitHub Pages.
+GitHub Pages. Не деплой `dist/`: это внутренний output для dev/build.
 ## Preview
@@ -27,8 +33,10 @@ mado release
 mado preview
 ```
-`mado preview` сервит `out/` как статический хост: baked HTML имеет приоритет,
-а неизвестные пути падают в SPA fallback.
+`mado preview` сервит финальный `out/` как обычный static host: сначала реальные
+файлы (`/<route>/index.html`, если route был baked), потом SPA fallback в
+`index.html`. Preview больше не делает отдельную виртуальную подстановку из
+`out/baked/`, поэтому он проверяет ровно то, что будет загружено на хостинг.
 ## VPS + nginx
@@ -37,8 +45,8 @@ mado release
 rsync -avz --delete out/ user@server:/var/www/myapp/
 ```
-В репозитории есть production `nginx.conf`: hashed bundles кешируются
-immutably, HTML идет с `no-cache`, deep links работают через SPA fallback.
+В репозитории есть production `nginx.conf`: hashed bundles кешируются immutable,
+HTML идет с `no-cache`, deep links работают через SPA fallback.
 ## Cloudflare / Netlify
@@ -47,9 +55,11 @@ mado release
 npx wrangler pages deploy out --project-name=myapp
 ```
-`_redirects` и `_headers` генерируются автоматически.
+`_redirects` и `_headers` генерируются автоматически, если ты не положил свои.
+Baked routes промотируются в реальные файлы (`out/<route>/index.html`), поэтому
+static host отдаст их до SPA fallback.
-## Cache rules
+## Cache Rules
 | Path | Cache-Control |
 |---|---|

package/docs/ru/16-bake-cookbook.md CHANGED Viewed

@@ -1,9 +1,9 @@
-# Bake cookbook
+# Bake Cookbook
 `mado bake` рендерит выбранные роуты в статический HTML. Это для SEO и быстрого
 первого ответа, не SSR с hydration.
-## Минимальная страница
+## Минимальная Страница
 ```ts
 export default page({
@@ -23,9 +23,9 @@ export default page({
 ```
 В baked views лучше использовать обычные массивы (`items.map(...)`). Runtime
-директивы вроде `each()` нужны браузеру.
+директивы вроде keyed `each()` нужны браузеру.
-## Dynamic routes
+## Dynamic Routes
 ```ts
 export default page<{ slug: string }>({
@@ -40,16 +40,50 @@ export default page<{ slug: string }>({
 `unsafeHTML()` используй только для доверенного или заранее очищенного HTML.
-## Manifest и output
+## Route Manifest
+`mado bake` нужен source manifest:
 ```ts
 export const manifest = {
   "/": () => import("./pages/home.js"),
   "/blog/:slug": () => import("./pages/blog-post.js"),
 };
 export default routes(manifest);
 ```
-`mado release` создает deploy artifact в `out/`. Если bake ругается на
-unsupported value, значит в статическую страницу попало runtime-only значение:
-замени `each()` на `items.map(...)` или вынеси интерактивный кусок в клиент.
+## Output
+Standalone `mado bake` по умолчанию пишет baked pages в `out/baked/`.
+`mado release` использует bundled production shell, оставляет копию в
+`out/baked/` для inspection, промотирует HTML в реальные route paths внутри
+`out/` и копирует sitemap в `out/sitemap.xml`.
+```bash
+mado release
+tree out
+```
+Deployable folder — `out/`, не `dist/`.
+## Client Boot
+Baked HTML помечает `#app` атрибутом `data-mado-baked`. Это не hydration:
+клиентский `render()` заменяет baked DOM живыми bindings при старте приложения.
+Так первый ответ содержит SEO/first-paint HTML, а SPA после загрузки работает
+как обычно.
+## Unsupported Values
+Bake намеренно падает громко вместо записи `[object Object]`. Если baked view
+ругается на unsupported directive:
+- замени `each()` на `items.map(...)` в baked markup;
+- интерактивные виджеты оставь в client-only routes;
+- убедись, что все значения сериализуются в статический HTML.
+## Canonical Links
+Передай `--base-url` или задай `bake.baseUrl` в `mado.config.json`, чтобы
+canonical links и sitemap указывали на production.

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.

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

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

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

@@ -0,0 +1,95 @@
+# Порядок reactivity
+> Малий набір ordering-гарантій, які Mado вважає публічною поведінкою.
+Reactivity у Mado синхронна для читання і планована для side effects. Мета —
+передбачувані UI updates без великої scheduling-моделі.
+## Signals
+`signal(value)` повертає getter-функцію. `set(next)` змінює значення одразу,
+якщо `Object.is(previous, next)` не дорівнює `true`.
+```ts
+const count = signal(0);
+count.set(1);
+count(); // 1, одразу
+```
+Computed values позначаються до запуску effects, тому effect, який читає
+computed, бачить актуальні dependencies, а не застарілий cache.
+## 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 між runs.
+## 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, щоб кожен item все одно рендерився, але duplicate keys — це data bug.
+## Teardown компонентів
+Custom elements можуть отримати `disconnectedCallback()`, а потім
+`connectedCallback()` під час same-tick move. Mado відкладає teardown компонента
+до microtask і скасовує його при reconnect, тому keyed reorders зберігають
+state компонента. Справжнє видалення все одно запускає lifecycle cleanup на
+наступній microtask.
+## Не гарантується
+Mado не гарантує точну кількість internal scheduler microtasks, порядок
+незалежних effects без спільних dependencies, форму generated bundle або
+внутрішній module layout. Це implementation details.
+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`