@madojs/mado 0.8.0 → 0.10.0

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

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

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

@@ -0,0 +1,83 @@
+# Стабільність v1
+
+> Що Mado обіцяє після v1, і що лишається вільним для розвитку.
+
+Mado v1 означає, що публічний app-facing contract достатньо стабільний для
+реальних business apps. Це не означає, що кожен internal file, 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 і internal implementation 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.
+- Точний generated JavaScript text, chunk names, sourcemap content і bundle
+  byte layout.
+- Internal parser, binding, router і resource cache data structures.
+- Starter app visual copy і demo data.
+
+Apps не повинні імпортувати internal files або перевіряти точний bundle output.
+
+## Bundle і release output
+
+Mado триматиме size budget і deterministic release tests, але v1 stability не
+заморожує byte-for-byte bundler output. Hashes, chunk boundaries і generated
+asset names можуть змінюватися, якщо задокументований deployment contract
+продовжує працювати.
+
+## Якщо release вас зламав
+
+Якщо update ламає код, який використовує тільки public exports і
+задокументовану поведінку, вважайте це bug. Відкрийте issue з:
+
+- версією Mado до і після;
+- задіяним public API;
+- мінімальною репродукцією;
+- чи це runtime behaviour, TypeScript types, CLI output або docs.
+
+Якщо поломка залежить від internal subpath або точного generated output, про це
+все одно варто повідомити, але це не вважається SemVer break.

package/docs/uk/README.md

@@ -22,3 +22,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/llms.txt

@@ -1,9 +1,9 @@
 # Mado
 
-> Small native-web SPA framework on the platform (Web Components + signals + tagged-template `html`).  
-> No build step (only `tsc`), no runtime dependencies, readable in an evening.
+> A calm browser-native SPA framework for internal tools, admin panels and business apps.  
+> Routing, forms, state, data fetching and prerendering. Zero runtime dependencies; generated apps use `typescript`, `esbuild` and `linkedom` as dev tooling.
 
-Mado is a narrowly-focused frontend framework that deliberately avoids React patterns (no JSX, no hooks, no VDOM, no Vite). Target audience: backend developers and senior frontend engineers who are tired of the infrastructure complexity of React/Next.
+Mado is a focused frontend framework for admin panels, internal tools and CRUD-heavy SPA. It deliberately avoids React patterns (no JSX, no hooks, no VDOM, no Vite). Target audience: backend developers and small teams who want a complete app stack without frontend infrastructure overhead.
 
 ## Key things an AI assistant needs to know
 
@@ -13,7 +13,12 @@ Mado is a narrowly-focused frontend framework that deliberately avoids React pat
 - **Components are Web Components.** Registered via `component('x-name', setupFn, options)`. Names must include a hyphen (`x-foo`, `my-button`).
 - **Component files register tags as side effects.** The browser does not auto-import files by tag name. If `<x-card>` works, some imported module already ran `customElements.define("x-card", ...)`.
 - **Cleanup via `ctx.onDispose(fn)`** in setup, not via return from effect.
-- **Reactive attributes via `ctx.attr(name, default?)`** — returns a Signal<string> that auto-updates when the attribute changes. No MutationObserver needed.
+- **Page cleanup via `onDispose`** in view: `view: ({ onDispose }) => { ... onDispose(() => cleanup()); }`. Only needed for raw APIs (setInterval, WebSocket). `resource()`/`effect()` auto-cleanup.
+- **`untracked()` in page view async** — functions called synchronously in `view()` that read signals must wrap reads in `untracked()` to avoid effect cycles with the router.
+- **Reactive attributes via `ctx.attr(name, default?)`** — returns a Signal<string> that auto-updates when the attribute changes via a per-instance `MutationObserver`. No `observedAttributes` option, no boilerplate.
+- **Public imports only.** App code imports from `@madojs/mado` and optionally side-effect `@madojs/mado/devtools.js`. Other package subpaths and `dist/src/*` are internal.
+- **Layouts are stateless wrappers.** Use route-manifest `layout()` and render `${child}` inside shared chrome. Put per-page state in pages/components/resources, not in layout view locals keyed by route identity.
+- **Bake is a static meta-shell/prerender pass.** It is not SSR with hydration and not a Next-style SSG runtime.
 
 ## Critical template rules
 
@@ -45,6 +50,24 @@ Mado is a narrowly-focused frontend framework that deliberately avoids React pat
    html`<ul>${() => each(users(), u => u.id, u => html`<li>${u.name}</li>`)}</ul>`
    ```
 
+4. **Parser hard errors:**
+   - no dynamic `${...}` child slots inside `<script>`, `<style>`, `<textarea>`, or `<title>`;
+   - no nested SVG-only `html` templates inside an outer `<svg>`.
+
+   ```ts
+   // ❌ throws: RAW_TEXT elements cannot host child slots
+   html`<textarea>${draft}</textarea>`;
+
+   // ✅ bind the DOM property instead
+   html`<textarea .value=${draft}></textarea>`;
+
+   // ❌ throws: nested SVG template loses namespace context
+   html`<svg>${html`<circle r="5"></circle>`}</svg>`;
+
+   // ✅ keep SVG internals in one template
+   html`<svg viewBox="0 0 10 10"><circle r="5"></circle></svg>`;
+   ```
+
 ## Canonical imports
 
 ```ts
@@ -112,6 +135,35 @@ const stats = resource(() => "/api/admin/stats", apiFetcher<Stats>());
 Unlike `jsonFetcher()`, `apiFetcher()` attaches the Bearer token from memory.
 Use `jsonFetcher()` for public endpoints, `apiFetcher()` for anything behind auth.
 
+## Resource and mutation semantics
+
+- A `resource()` key is the cache identity. Same key means shared cache and
+  deduped in-flight request; use distinct keys for distinct data or auth scope.
+- `mutation().run()` is concurrent by default. `loading()` stays true while any
+  run is in flight. Use `{ abortPrevious: true }` only for search-as-you-type or
+  "latest request wins" flows.
+- `invalidates` runs after a successful mutation and is best-effort: errors are
+  logged, but the mutation result stays successful.
+
+## Layouts and bake
+
+Use `layout()` in `routes.ts` for shared shells. A layout view should be a pure
+wrapper around `${child}` and shared chrome:
+
+```ts
+export default page({
+  view: ({ child }) => html`<x-app-shell>${child}</x-app-shell>`,
+});
+```
+
+Do not create route-specific state in layout view locals. Put it in pages,
+components, resources, or app-level contexts.
+
+`mado bake` renders selected routes to static HTML for SEO and first paint. It
+does not hydrate server-rendered code. Baked views must be deterministic from
+`params`, `bake.data`, and plain values. Avoid browser-only effects, timers,
+relative `fetch`, and runtime directives like keyed `each()` during bake.
+
 ## Canonical "Hello world"
 
 ```ts
@@ -199,6 +251,9 @@ export default page({
 - docs/en/15-error-handling.md — route/data/action error boundaries
 - docs/en/16-bake-cookbook.md — static bake recipes and failure modes
 - docs/en/17-shadow-dom-forms.md — Shadow DOM + useForm() patterns (proxy properties, form submit bridge)
+- docs/en/18-api-freeze-map.md — stable public API vs internal implementation details
+- docs/en/19-reactivity-ordering.md — signal ordering, batching and teardown guarantees
+- docs/en/20-v1-stability.md — v1 SemVer contract and what remains internal
 - examples/basic/ — minimal API tour
 - examples/tickets/ — LLM zero-history CRUD validation
 - examples/showcase/ — flagship CRM pressure app (auth, nested routes, forms, mutations)
@@ -208,7 +263,7 @@ export default page({
 
 - ❌ JSX → tagged templates instead
 - ❌ Virtual DOM → fine-grained signal updates
-- ❌ SSR with hydration → `bake` (static build) or edge-prerender for SEO
+- ❌ SSR with hydration → `bake` static meta-shell or edge-prerender for SEO
 - ❌ Hooks and rules of hooks → signals
 - ❌ Mandatory Webpack/Vite → only `tsc`
 - ❌ React-Router / TanStack → built-in 500-line `routes()`
@@ -219,8 +274,9 @@ export default page({
 
 ## Version
 
-`0.8.0` — pre-1.0 product-surface release. API may still change before 1.0.
-Semver is not guaranteed on minor versions before 1.0.
+`0.10.0` — pre-1.0 API-lock release. Phase B closed the public surface,
+package exports, docs and CI gates. SemVer is not guaranteed on minor versions
+before 1.0.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@madojs/mado",
-  "version": "0.8.0",
-  "description": "Mado — a small native-web SPA framework with Web Components, signals, tagged-template html, router, resources, and forms. TypeScript-only build, zero runtime dependencies.",
+  "version": "0.10.0",
+  "description": "Mado — a calm browser-native SPA framework for internal tools, admin panels and business apps. Routing, forms, state and data fetching without frontend infrastructure overhead.",
   "type": "module",
   "license": "MIT",
   "keywords": [
@@ -36,8 +36,10 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     },
-    "./devtools.js": "./dist/src/devtools.js",
-    "./*": "./dist/src/*"
+    "./devtools.js": {
+      "types": "./dist/src/devtools.d.ts",
+      "import": "./dist/src/devtools.js"
+    }
   },
   "files": [
     "dist/src",
@@ -66,6 +68,9 @@
     "test:browser": "node scripts/cli.mjs test browser",
     "new": "node scripts/cli.mjs new",
     "examples": "node scripts/cli.mjs examples",
+    "size": "node scripts/size-budget.mjs",
+    "package:smoke": "node scripts/package-smoke.mjs",
+    "llm:smoke": "node scripts/llm-zero-history-smoke.mjs",
     "test": "node scripts/cli.mjs test",
     "typecheck": "node scripts/cli.mjs typecheck",
     "clean": "rm -rf dist out",
@@ -80,4 +85,4 @@
   "engines": {
     "node": ">=20"
   }
-}
+}

package/scripts/bake.mjs

@@ -522,7 +522,6 @@ function buildHtml({ template, bodyHtml, head, bakedData, revalidate, canonical
 
   if (revalidate) {
     setMeta(document, { name: "bake-revalidate", content: String(revalidate) });
-    setMeta(document, { name: "bake-stamp", content: String(Date.now()) });
   }
 
   if (bakedData !== undefined) {

package/scripts/bundle.mjs

@@ -120,14 +120,14 @@ const result = await build({
   legalComments: "none",
 });
 
-const entryOutput = Object.entries(result.metafile.outputs).find(
-  ([name, info]) => info.entryPoint && name.endsWith(".js"),
-);
-if (!entryOutput) {
-  console.error("[bundle] entry not found in outputs");
+// With splitting: true, esbuild marks all dynamic-import chunks as having
+// entryPoint. We identify the real app entry by the `entryNames` prefix "main-".
+const mainBundle = (await readdir(ASSETS_DIR))
+  .find((f) => f.startsWith("main-") && f.endsWith(".js") && !f.endsWith(".js.map"));
+if (!mainBundle) {
+  console.error("[bundle] entry not found in outputs (no main-*.js in assets dir)");
   process.exit(1);
 }
-const mainBundle = basename(entryOutput[0]);
 
 // Collect all js chunks in the assets dir.
 const allJs = (await readdir(ASSETS_DIR)).filter((f) => f.endsWith(".js"));

package/scripts/cli.mjs

@@ -144,6 +144,7 @@ async function runInit(rawArgs) {
   await cp(source, target, { recursive: true, force: true });
   await copyCanonicalAgentFiles(target);
   await ensureStarterGitignore(target);
+  await ensureStarterPackageJson(target);
 
   const packageName = packageNameFromDir(target);
   if (!isValidPackageName(packageName)) {
@@ -331,6 +332,22 @@ async function ensureStarterGitignore(target) {
   await writeFile(file, "node_modules\ndist\nout\n.DS_Store\n*.log\n");
 }
 
+async function ensureStarterPackageJson(target) {
+  const file = join(target, "package.json");
+  if (!existsSync(file)) return;
+
+  const pkg = JSON.parse(await readFile(file, "utf8"));
+  const rootDev = PACKAGE_JSON.devDependencies ?? {};
+  pkg.devDependencies = {
+    ...(pkg.devDependencies ?? {}),
+    typescript: rootDev.typescript ?? "^6.0.3",
+    esbuild: rootDev.esbuild ?? "^0.28.0",
+    linkedom: rootDev.linkedom ?? "^0.18.12",
+  };
+
+  await writeFile(file, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
 async function runNodeBin(bin, args) {
   await run(process.execPath, [resolveBin(bin), ...args]);
 }

package/scripts/llm-zero-history-smoke.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+const root = process.cwd();
+const ticketsDir = join(root, "examples", "tickets");
+
+const llms = await read("llms.txt");
+assertIncludes(llms, "This is NOT React", "llms.txt must keep the React warning");
+assertIncludes(llms, "Canonical CRUD pattern", "llms.txt must keep the CRUD recipe");
+assertIncludes(llms, "resource()", "llms.txt must document resource()");
+assertIncludes(llms, "mutation", "llms.txt must document mutation()");
+assertIncludes(llms, "useForm", "llms.txt must document useForm()");
+
+const files = await collectTs(ticketsDir);
+const code = (await Promise.all(files.map((file) => read(file)))).join("\n");
+const routes = await read(join(ticketsDir, "routes.ts"));
+
+for (const route of ['"/"', '"/tickets"', '"/tickets/new"', '"/tickets/:id"', '"*"']) {
+  assertIncludes(routes, route, `tickets routes must include ${route}`);
+}
+
+for (const api of [
+  "component(",
+  "html`",
+  "signal(",
+  "computed(",
+  "resource(",
+  "mutation(",
+  "invalidates",
+  "queryParam(",
+  "each(",
+  "useForm(",
+]) {
+  assertIncludes(code, api, `tickets example must exercise ${api}`);
+}
+
+const forbidden = [
+  /\buseState\s*\(/,
+  /\buseEffect\s*\(/,
+  /\$state\b/,
+  /\bref\s*\(/,
+  /from\s+["']react["']/,
+  /class\s+\w+\s+extends\s+HTMLElement/,
+  /<>\s*$/,
+  /(^|[^?.\w-])disabled=\$\{/,
+  /(^|[^?.\w-])checked=\$\{/,
+];
+
+for (const pattern of forbidden) {
+  if (pattern.test(code)) {
+    throw new Error(`[llm-smoke] forbidden generated pattern: ${pattern}`);
+  }
+}
+
+await run(process.execPath, ["scripts/cli.mjs", "build"]);
+await run(process.execPath, ["--test", "test/tickets-smoke.test.mjs"]);
+
+console.log("[llm-smoke] ok examples/tickets follows llms.txt and passes smoke");
+
+async function collectTs(dir) {
+  const out = [];
+  for (const entry of await readdir(dir)) {
+    const file = join(dir, entry);
+    const s = await stat(file);
+    if (s.isDirectory()) out.push(...await collectTs(file));
+    else if (file.endsWith(".ts")) out.push(file);
+  }
+  return out.sort();
+}
+
+async function read(file) {
+  return readFile(file, "utf8");
+}
+
+function assertIncludes(text, needle, message) {
+  if (!text.includes(needle)) throw new Error(`[llm-smoke] ${message}`);
+}
+
+async function run(cmd, args) {
+  console.log(`[llm-smoke] ${cmd} ${args.join(" ")}`);
+  try {
+    await exec(cmd, args, { cwd: root, maxBuffer: 20 * 1024 * 1024 });
+  } catch (err) {
+    if (err.stdout) process.stdout.write(err.stdout);
+    if (err.stderr) process.stderr.write(err.stderr);
+    throw err;
+  }
+}

package/scripts/new.mjs

@@ -7,7 +7,7 @@
 // Result: examples/pages/<name>.ts (or src/pages/, when present)
 // with __name__ / __Name__ placeholders replaced.
 //
-// Zero dependencies.
+// Zero runtime dependencies; generated apps use dev tooling only.
 
 import { readFile, writeFile, mkdir, access } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";

package/scripts/package-smoke.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+const repoRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const tempRoot = await mkdtemp(join(tmpdir(), "mado-package-smoke-"));
+let tarball = "";
+
+try {
+  const packed = await exec("npm", ["pack", "--silent"], { cwd: repoRoot });
+  tarball = resolve(repoRoot, packed.stdout.trim().split(/\s+/).at(-1) ?? "");
+  if (!tarball) throw new Error("[package-smoke] npm pack did not return a tarball");
+
+  const installRoot = join(tempRoot, "installed");
+  await mkdir(installRoot, { recursive: true });
+  await run("npm", ["install", tarball], { cwd: installRoot });
+
+  await run(
+    process.execPath,
+    [
+      "--input-type=module",
+      "--eval",
+      `
+        import { html, signal } from "@madojs/mado";
+        import "@madojs/mado/devtools.js";
+        if (typeof html !== "function" || typeof signal !== "function") {
+          throw new Error("public root import failed");
+        }
+        try {
+          await import("@madojs/mado/lifecycle.js");
+          throw new Error("internal lifecycle subpath unexpectedly resolved");
+        } catch (err) {
+          if (err?.code !== "ERR_PACKAGE_PATH_NOT_EXPORTED") throw err;
+        }
+      `,
+    ],
+    { cwd: installRoot },
+  );
+
+  await run("npx", ["mado", "init", "smoke-app", "--starter", "minimal"], {
+    cwd: installRoot,
+    env: { ...process.env, MADO_PACKAGE_SPEC: tarball },
+  });
+
+  const appRoot = join(installRoot, "smoke-app");
+  await run("npm", ["install"], { cwd: appRoot });
+  await run("npm", ["run", "release"], { cwd: appRoot });
+
+  console.log(`[package-smoke] ok ${basename(tarball)}`);
+} finally {
+  await rm(tempRoot, { recursive: true, force: true });
+  if (tarball) await rm(tarball, { force: true });
+}
+
+async function run(cmd, args, options) {
+  console.log(`[package-smoke] ${cmd} ${args.join(" ")}`);
+  try {
+    await exec(cmd, args, {
+      cwd: options.cwd,
+      env: options.env ?? process.env,
+      maxBuffer: 20 * 1024 * 1024,
+    });
+  } catch (err) {
+    if (err.stdout) process.stdout.write(err.stdout);
+    if (err.stderr) process.stderr.write(err.stderr);
+    throw err;
+  }
+}

package/scripts/size-budget.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { build } from "esbuild";
+import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
+
+const API_ENTRY = "src/index.ts";
+const SAMPLE_ENTRY = "examples/showcase/main.ts";
+const API_GZIP_LIMIT = readLimit("MADO_SIZE_API_GZIP_LIMIT", 16 * 1024);
+const SAMPLE_GZIP_LIMIT = readLimit("MADO_SIZE_SAMPLE_GZIP_LIMIT", 42 * 1024);
+
+let failed = false;
+
+const api = await bundlePublicApi();
+report("public API", api.gzip, API_GZIP_LIMIT);
+
+const sample = await bundleSampleApp();
+report("showcase app", sample.gzip, SAMPLE_GZIP_LIMIT);
+
+if (failed) process.exit(1);
+
+async function bundlePublicApi() {
+  const result = await build({
+    entryPoints: [API_ENTRY],
+    bundle: true,
+    minify: true,
+    format: "esm",
+    target: "es2022",
+    platform: "browser",
+    legalComments: "none",
+    write: false,
+  });
+  const js = result.outputFiles[0]?.contents;
+  if (!js) throw new Error("[size] esbuild produced no public API output");
+  return { gzip: gzipSync(js, { level: 9 }).length };
+}
+
+async function bundleSampleApp() {
+  const outdir = await mkdtemp(join(tmpdir(), "mado-size-"));
+  try {
+    await build({
+      entryPoints: [SAMPLE_ENTRY],
+      bundle: true,
+      minify: true,
+      format: "esm",
+      target: "es2022",
+      platform: "browser",
+      splitting: true,
+      outdir,
+      legalComments: "none",
+    });
+
+    let gzip = 0;
+    for (const file of await readdir(outdir)) {
+      if (!file.endsWith(".js")) continue;
+      const js = await readFile(join(outdir, file));
+      gzip += gzipSync(js, { level: 9 }).length;
+    }
+    return { gzip };
+  } finally {
+    await rm(outdir, { recursive: true, force: true });
+  }
+}
+
+function report(label, actual, limit) {
+  const ok = actual < limit;
+  const mark = ok ? "ok" : "FAIL";
+  console.log(
+    `[size] ${label.padEnd(12)} ${mark} ${kib(actual)} KiB gzip < ${kib(limit)} KiB`,
+  );
+  if (!ok) failed = true;
+}
+
+function readLimit(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error(`[size] ${name} must be a positive byte count`);
+  }
+  return n;
+}
+
+function kib(bytes) {
+  return (bytes / 1024).toFixed(2);
+}