@madojs/mado 0.10.1 → 0.11.1

package/MADO_V1_PLAN.md

@@ -1,179 +0,0 @@
-# MadoJS — Road to v1 (completed v0.6 tracker)
-
-> Completed tracker for the v0.6 product-surface push. The work agreed during
-> the v1 audit is now closed and squash-merged into `main` as
-> `feat: add v1 product surface`.
->
-> Convention: every commit/PR that advances v1 references task IDs in its message,
-> e.g. `[v1 F1.2] bake.mjs: app-mode defaults + --entry/--template/--out flags`.
-> When a task is completed, tick its box here in the same commit.
-
----
-
-## 0. Mental model (write this into docs first)
-
-Three artifact states. One deploy artifact. End of story.
-
-| Folder      | What it is                                                     | Who writes        | Who reads                  | Deployed?         |
-|-------------|----------------------------------------------------------------|-------------------|----------------------------|-------------------|
-| `src/`      | your source (TS)                                               | you               | `tsc`, `esbuild`           | no                |
-| `dist/`     | `tsc` output (native ESM JS for the browser)                   | `mado build`      | `mado dev`, dev browser    | no (internal)     |
-| `public/`   | static assets (favicons, images, robots.txt)                   | you               | `mado bundle` copies it    | as part of `out/` |
-| `out/`      | **the only deploy artifact**: SPA shell + bundles + baked HTML | `mado release`    | nginx / CDN / CF / VPS     | ✅ yes            |
-
-One-liner for users:
-> Develop with `mado dev`. To deploy: run `mado release`, then upload `out/` anywhere.
-
-`mado release` = `typecheck` + `build` + `bundle` + `bake` + copy `public/*` → `out/`.
-One command. One artifact. Zero questions about where things live.
-
----
-
-## 1. Problem map (consolidated)
-
-### Layer A — Core (from the audit)
-- **A1** Computed leaks: no refcount/owner; once read, computed stays subscribed to deps forever.
-- **A2** No cycle-detection in `effect` (e.g. `effect(() => x.set(x()+1))` runs forever).
-- **A3** No `equals` option on `computed`.
-- **A4** No template directives: `unsafeHTML`, `ref`, `classMap`, `styleMap`.
-- **A5** `useForm`: no async validators, no field-arrays.
-- **A6** `resource`/`invalidate`: no typed key relationship; pattern miss is silent.
-- **A7** Router: no scroll restoration / focus management / error boundary.
-- **A8** `head()`: not obvious how dedup/cleanup happens across navigation.
-
-### Layer B — DX, tooling, product surface (from dogfooding)
-- **B1** CLI/bake hardcoded to `examples/` and alias `@madojs/mado → src/index.ts` — repo-mode leaks into user apps.
-- **B2** No single blessed way for **layouts** (LLM and humans both guess).
-- **B3** No blessed way for **auth + API client + dev-proxy**.
-- **B4** No single config file (`mado.config.json`); everything is env vars.
-- **B5** Unclear model for `dist/` vs `out/` vs `public/`.
-- **B6** No `mado release` (one deploy artifact).
-- **B7** Bake silently renders `[object Object]` for `each()`.
-- **B8** Bake lives "next to" the app instead of inside `mado dev`.
-- **B9** No route guard API.
-- **B10** `crud` starter looks like raw scaffold; no admin-template.
-- **B11** Docs missing: app-architecture, layouts, auth-and-api, deployment, testing, error-handling, bake-cookbook.
-- **B12** Starter scaffolds contain `examples/` legacy.
-
----
-
-## 2. Phases (deliver in order; phase 5 runs in parallel)
-
-### 🟦 Phase 1 — Repo-vs-app split (P0)
-
-Goal: kill `examples/` leakage; make app-mode the default.
-
-### 🟩 Phase 2 — One blessed way (P0)
-
-Goal: conventions over flexibility. Layouts, guards, auth, api — one recipe each.
-
-### 🟨 Phase 3 — Bake first-class + Release pipeline (P0)
-
-Goal: pragmatic path from `mado dev` to production on VPS / Cloudflare / static CDN.
-
-### 🟪 Phase 4 — Core hardening (P1)
-
-Goal: long-term correctness of signals, html, router, forms, head.
-
-### 🟫 Phase 5 — Documentation (P0/P1, in parallel)
-
-Goal: a backender can ship an admin app reading only the docs.
-
----
-
-## 3. Acceptance scenario for v1
-
-```bash
-npm exec --package @madojs/mado@latest -- mado init dashboard --starter admin
-cd dashboard
-npm install
-mado dev
-# / → public landing
-# /admin → redirected to /login (guard works)
-# log in → admin shell with sidebar / topbar / dashboard / orders table
-
-mado release
-rsync -avz out/ user@vps:/var/www/dashboard/
-# done
-```
-
-If a backend developer reaches production **without reading `bake.mjs`,
-without setting env vars, without asking "where does layout live?",
-and without an `examples/` folder in their app** — v1 is done.
-
----
-
-## 4. Tracker
-
-### Phase 1 — Repo-vs-app split ✅
-- [x] **F1.1** `mado.config.json` schema + loader (`scripts/_config.mjs`)
-- [x] **F1.2** `scripts/bake.mjs`: flags `--entry/--template/--out/--base-url`, app-mode defaults, no `examples/` alias in app-mode, loud errors instead of silent `[object Object]`
-- [x] **F1.3** `scripts/cli.mjs`: detect repo vs app, read `mado.config.json`, redesigned help, new `mado release` command
-- [x] **F1.4** Starters cleanup: `mado.config.json` and blessed CLI scripts in `starters/minimal` and `starters/crud`; no `examples/` references
-- [x] **F1.5** `docs/en/02-project-layout.md` rewritten around the canonical `src/`/`dist/`/`public/`/`out/` model and `mado.config.json`
-- [x] **F1.6** `test/config-loader.test.mjs` + `test/bake-cli.test.mjs`.
-
-### Phase 2 — One blessed way ✅
-- [x] **F2.1** `layout()` factory (alias of `nested()`) exported from `src/page.ts`; flatten propagates layouts outer → inner.
-- [x] **F2.2** `Guard` type + guard chain in `src/router/manifest.ts`. Verdicts: void / `{ halt: true }` / `{ redirect, replace? }`. Async-aware with sync fast path; throwing guard is treated as `halt` with a `console.error`.
-- [x] **F2.3** `layout`, `Guard`, `GuardResult`, `nested`, `navigate` exported from `src/index.ts`.
-- [x] **F2.4** New starter `starters/admin/` with `layouts/{app,auth}.ts`, `lib/{api,auth}.ts`, `components/{x-button,x-input}.ts`, `pages/{home,login,not-found,admin/{dashboard,orders,order-detail}}.ts`, `styles/global.ts`, `mado.config.json`, `public/favicon.svg`. End-to-end scaffold + typecheck + build verified locally.
-- [x] **F2.5** CLI advertises `--starter admin` (`mado init my-app --starter admin`) and adds it to the help screen.
-- [x] **F2.6** Doc `docs/en/11-layouts.md` (one path + 2 alternatives with caveats).
-- [x] **F2.7** Doc `docs/en/12-auth-and-api.md` (blessed `api`/`auth` recipes, backend contract, dev-proxy hint).
-- [x] **F2.8** `test/guards-layouts.test.mjs` covers the public `layout()` alias, sync pass/halt/redirect verdicts, async guards, parent→page guard order, and throwing-guard fallback (7 tests, all green).
-
-### Phase 3 — Bake first-class + Release pipeline ✅ (core)
-- [x] **F3.1** `mado release` command: typecheck + build + bundle + bake + copy `public/` → `out/` + write `_headers` / `_redirects` (`scripts/cli.mjs`).
-- [x] **F3.2** Deferred to v0.7: `mado dev` serves baked routes inline. Current v1 path is `mado release && mado preview`.
-- [x] **F3.3** `mado preview` reads `mado.config.json`, refuses to auto-build in app-mode (opt in with `PREVIEW_AUTOBUILD=1`), and emulates nginx fallback (`scripts/preview.mjs`).
-- [x] **F3.4** Bake raises a loud, file/route-targeted error on unsupported render values (e.g. `each()` directive objects). Covered by `test/bake-cli.test.mjs`.
-- [x] **F3.5** Deferred to v0.7: `mado check` runs bake-safety scan on `bake:` routes. Current v1 coverage is the loud-error contract from F3.4.
-- [x] **F3.6** Dev-proxy in `server/serve.mjs`: reads `dev.proxy` from `mado.config.json` and forwards matching prefixes to the upstream backend without external deps.
-- [x] **F3.7** `mado release` generates `out/_redirects` (`/* /index.html 200`) and `out/_headers` (immutable for `/assets/*`, no-cache for `/*.html`) when those files do not exist.
-- [x] **F3.8** Doc `docs/en/13-deployment.md` (VPS + nginx, Cloudflare Pages, S3/CloudFront, Netlify, GitHub Pages, CI sketch, cache matrix, troubleshooting).
-- [x] **F3.9** Production `nginx.conf` next to the docs (already shipped, with `gzip_static`, immutable hashed bundles, SPA fallback). Verified referenced from the deployment doc.
-- [x] **F3.10** `test/release-pipeline.test.mjs`: end-to-end CLI test scaffolds an app, runs `mado release`, and asserts `out/index.html`, `out/baked/index.html`, `out/_headers`, `out/_redirects`, public-asset copy, and sitemap. Also `scripts/bundle.mjs` is app-mode aware (no `examples/`-leak when run from a user app).
-
-### Phase 4 — Core hardening
-- [x] **F4.1** Refcount/GC for `computed` in `src/signal.ts` + tests (`computed` releases dep subscriptions after unobserved reads and after the last subscriber is disposed).
-- [x] **F4.2** Cycle-detection in `effect` + `test/signal-cycle.test.mjs`
-- [x] **F4.3** `equals` option on `computed`
-- [x] **F4.4** Directives: `unsafeHTML`, `ref`, `classMap`, `styleMap` in `src/html/bindings.ts` + public exports + `test/html-directives.test.mjs`.
-- [x] **F4.5** `useForm`: async validators (`validateAsync`, field-level `validateAsync`, `validating`) + field arrays (`form.array()`, dotted paths, wildcard schema) + tests.
-- [x] **F4.6** Router: scroll restoration + focus management
-- [x] **F4.7** Router: `errorPage:` in manifest + error boundary
-- [x] **F4.8** `src/head.ts`: guaranteed cleanup on navigation (`data-mado-head` removed before re-applying)
-- [x] **F4.9** Tests for everything above: `test/computed-lazy.test.mjs` (F4.1/F4.3), `test/signal-cycle.test.mjs` (F4.2), `test/html-directives.test.mjs` (F4.4), `test/forms.test.mjs` (F4.5), `test/router-isolation.test.mjs` (F4.6), `test/router-error-boundary.test.mjs` (F4.7), `test/head.test.mjs` (F4.8). Final `typecheck + build + test` pass verified.
-
-### Phase 5 — Documentation (parallel to phases 2-4)
-English docs for project layout, layouts, auth/API and deployment exist now.
-The remaining work is deeper recipes plus translation sync.
-
-- [x] **F5.1** `docs/en/10-app-architecture.md` (end-to-end admin)
-- [x] **F5.2** `docs/en/14-testing.md`
-- [x] **F5.3** `docs/en/15-error-handling.md`
-- [x] **F5.4** `docs/en/16-bake-cookbook.md`
-- [x] **F5.5** `AGENTS.md`: section "App architecture for LLM"
-- [x] **F5.6** `llms.txt`: new anchors
-- [x] **F5.7** ru/fr/uk translations for new docs (`10` through `16`)
-
----
-
-## 5. Working loop
-
-1. Pick the first unchecked box.
-2. Implement it (small, focused change).
-3. Run `npm test` (and `npm run typecheck` when touching `src/`).
-4. Tick the box in this file in the same commit.
-5. Add a one-line entry under "Unreleased" in `CHANGELOG.md`.
-6. After each phase finishes, pause and review.
-
-## 6. Context-loss safety
-
-- This file = ground truth on disk.
-- `task_progress` in chat = current phase/task.
-- Git commits tagged `[v1 Fx.y]` = time machine.
-
-If future work resumes from this plan, treat it as archive context. New tasks
-belong in `ROADMAP.md`, `TODO.md`, or a fresh tracker.

package/ROADMAP.md

@@ -1,178 +0,0 @@
-# Roadmap to v1
-
-Mado is a calm frontend stack for internal tools, admin panels and business
-SPA. The path to v1 is not about adding features — it is about proving the
-framework works reliably for its intended use case and earning trust through
-demonstrated quality.
-
-## Positioning
-
-**For:** small teams and solo developers building admin panels, internal tools,
-backoffice apps and CRUD-heavy SPA.
-
-**Promise:** easy to build, boring to maintain. Complete app stack (routing,
-forms, state, data, prerender) without frontend infrastructure overhead.
-
-**Not for:** SEO-heavy sites, large teams optimizing for hiring, projects
-needing SSR hydration or mature plugin ecosystems.
-
-## Current state: v0.8
-
-The core API is feature-complete for the target use case:
-- Signals, computed, effects with GC and cycle detection
-- Tagged-template `html` with directives (ref, classMap, styleMap, unsafeHTML)
-- Web Components with Shadow DOM
-- Router with nested routes, guards, lazy loading, error boundary, scroll restoration
-- Resource + mutation with cache, invalidation, abort, optimistic updates
-- Forms with schema validation, async validators, field arrays
-- Persisted state, context/DI, head management
-- Static prerender (bake) for SEO without hydration
-- CLI: init, dev, build, release, preview
-- Starters: minimal, crud, admin
-
-The API surface is feature-complete — but a line-by-line audit
-([`FABLE_REPORT.md`](./FABLE_REPORT.md)) found correctness defects that break
-three central promises (*keyed `each` preserves state*, *glitch-free signals*,
-*cross-tab sync works*) plus one re-bind model that is cheaper to fix before
-the API freeze than after. So what is missing is, in order: **correctness,
-then surface lockdown, then proof and polish.**
-
-## Milestone 0: Correctness & surface lockdown (gate to v1)
-
-Before any of the product-surface milestones below mean anything, the
-foundation must be correct and the public surface must be freezable. This work
-is tracked task-by-task (TDD: reproducing test → fix) in
-[`MADO_V1_TRACKER.md`](./MADO_V1_TRACKER.md):
-
-- [ ] **v0.9 — Correctness release:** fix audit findings C1–C8 (each-reorder
-  teardown, persisted cross-tab loop, `update()` nested re-bind, `equals` +
-  `batch` atomicity, stale form async validation, `mutation` abort semantics,
-  silent parser drops, lifecycle/router defect pack). Fixes only, zero features,
-  each with a regression test that was red first.
-- [ ] **v0.10 — Surface & cleanup:** remove legacy attribute→property reflection
-  and `observedAttributes`, replace `exports "./*"` with an explicit subpath map,
-  close `_testHooks`, publish the API freeze map, add CI size budgets and a
-  package-level export test, sync `llms.txt`/`AGENTS.md` with the real API.
-
-The milestones below (live demo, reliability, recipes, docs) execute **after**
-Milestone 0, during the `v1.0-rc` dogfooding phase.
-
-## V1 milestones (in priority order)
-
-
-### 1. Live demo — prove it works
-
-**Goal:** a deployed, publicly accessible app that looks like real work.
-
-The showcase already has: auth, tables with filters/sort/pagination, record
-details, forms, nested routes, context services, role guards, loading/error
-states. What it needs:
-
-- [ ] Deploy to a public URL (Cloudflare Pages or similar)
-- [ ] Add responsive sidebar + mobile breakpoints
-- [ ] Add toast/feedback system
-- [ ] Add optimistic update example
-- [ ] Add persisted filters example
-- [ ] Polish visual quality to "not embarrassing" level
-- [ ] Add a comparison section: bundle size, file count, cold start vs React+Vite equivalent
-
-This is the single most important deliverable. A working app proves more than
-any README.
-
-### 2. Boring reliability — earn trust
-
-**Goal:** no surprises in production.
-
-- [ ] Browser compatibility pass: Chrome, Edge, Firefox, Safari (current)
-- [ ] Accessibility pass: focus management, ARIA, keyboard navigation in examples
-- [ ] Public API audit: names, warnings, lifecycle rules, docs coverage
-- [ ] Public exports audit: lock the root import; decide on subpaths
-- [ ] Error messages audit: every runtime error should point to a fix
-- [ ] Long session stability test: memory leaks, listener cleanup, route churn
-- [ ] Migration notes template: document how to upgrade between versions
-
-### 3. Release hygiene — look professional
-
-**Goal:** signal stability and care.
-
-- [ ] npm provenance / Trusted Publishing
-- [ ] GitHub repo metadata: description, topics, social preview
-- [ ] Semantic versioning discipline with changelog
-- [ ] Size reporting in CI (ESM + bundled + gzip + brotli)
-- [ ] Compatibility matrix in docs (browsers, TS versions)
-- [ ] Issue labels and triage process
-
-### 4. Business-app recipes — solve real problems
-
-**Goal:** answer "how do I..." for common admin/internal app patterns.
-
-- [ ] Auth recipe: login, token refresh, route guards, logout
-- [ ] Table recipe: pagination, sort, filters, empty state, loading skeleton
-- [ ] Form recipe: create/edit, validation, async submit, error display
-- [ ] CRUD recipe: list → detail → edit → delete with optimistic updates
-- [ ] API integration recipe: typed client, error handling, retry
-- [ ] Deployment recipe: VPS, Cloudflare Pages, static CDN, Docker
-
-### 5. External validation — prove others can use it
-
-**Goal:** at least 3 people outside the author build real apps.
-
-- [ ] Invite 2-3 developers to build internal tools with Mado
-- [ ] Collect friction reports and fix blockers
-- [ ] Get at least 1 public case study or blog post
-- [ ] Address real issues that emerge from pressure testing
-
-### 6. Documentation rewrite — job-to-be-done first
-
-**Goal:** docs answer "how to build X" not "how API Y works".
-
-- [ ] Getting started guide focused on building an admin panel
-- [ ] "Build a backoffice app" tutorial (30 min, end-to-end)
-- [ ] Troubleshooting guide for common mistakes
-- [ ] API reference (generated or manually curated)
-- [ ] Remove or archive docs that don't serve the target audience
-
-## Explicitly out of scope
-
-These will not happen before v1. They are not weaknesses — they are focus.
-
-- Runtime dependencies
-- UI component library / design system
-- SSR with hydration
-- Plugin ecosystem
-- Framework-specific build tool
-- Broad general-purpose narrative
-- Synthetic benchmark marketing
-
-## After v1
-
-Ideas live in `TODO.md`. They become commitments only when a real app or
-user issue proves the need. The general direction:
-
-- Optimistic mutation primitives
-- Live data (SSE/WebSocket) resource
-- i18n helper
-- Accessibility utilities (focus trap, live region)
-- Optional tiny utility stylesheet
-- PWA scaffold
-- eslint-plugin-mado
-
-## Success criteria for v1
-
-Not stars or hype. Instead:
-
-1. **3+ people** have built real internal/admin apps with Mado
-2. **1 polished live demo** is deployed and maintained
-3. **Zero known browser bugs** in Chrome/Edge/Firefox/Safari current
-4. **API is stable** — no breaking changes needed for known use cases
-5. **Docs answer 90% of questions** without asking the author
-
-## Release History
-
-| Date | Version | Notes |
-|---|---|---|
-| 2026-06-03 | v0.1-v0.3 | Core stabilization, docs foundation, publish readiness, Cloudflare PoC |
-| 2026-06-05 | v0.4 | Showcase CRM pressure app, browser regression suite |
-| 2026-06-06 | v0.5 | Unified CLI, rebrand to @madojs/mado, first npm release |
-| 2026-06-07 | v0.6 | App-mode CLI/config, admin starter, release pipeline, core hardening |
-| 2026-06-09 | v0.8 | Product surface complete, positioning pivot to internal tools focus |

package/dist/src/html.d.ts

@@ -1,18 +0,0 @@
-/**
- * html module entry point. The implementation lives in `./html/`:
- *
- *   ./html/parser.ts          — state-machine tokenizer + ParsedTemplate cache
- *   ./html/bindings.ts        — bindChild / bindAttr + keyed each
- *   ./html/template.ts        — html`` tag, instantiate(), render()
- *   ./html/template-types.ts  — shared types (TemplateResult, InstantiatedTemplate)
- *
- * This file keeps compatibility for internal imports from `"./html.js"`.
- * The public barrel (`src/index.ts`) also goes through this file.
- *
- * If the shell is ever removed, switch imports to `./html/template.js`.
- * For now it has no runtime cost.
- */
-export { html, render, instantiate } from "./html/template.js";
-export { unsafeHTML, ref, classMap, styleMap, isHtmlDirective, } from "./html/bindings.js";
-export type { TemplateResult } from "./html/template-types.js";
-export type { HtmlDirective, UnsafeHTMLDirective, RefCallback, RefDirective, ClassMap, ClassMapDirective, StyleMap, StyleMapDirective, } from "./html/bindings.js";

package/dist/src/html.js

@@ -1,17 +0,0 @@
-/**
- * html module entry point. The implementation lives in `./html/`:
- *
- *   ./html/parser.ts          — state-machine tokenizer + ParsedTemplate cache
- *   ./html/bindings.ts        — bindChild / bindAttr + keyed each
- *   ./html/template.ts        — html`` tag, instantiate(), render()
- *   ./html/template-types.ts  — shared types (TemplateResult, InstantiatedTemplate)
- *
- * This file keeps compatibility for internal imports from `"./html.js"`.
- * The public barrel (`src/index.ts`) also goes through this file.
- *
- * If the shell is ever removed, switch imports to `./html/template.js`.
- * For now it has no runtime cost.
- */
-export { html, render, instantiate } from "./html/template.js";
-export { unsafeHTML, ref, classMap, styleMap, isHtmlDirective, } from "./html/bindings.js";
-//# sourceMappingURL=html.js.map

package/dist/src/html.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"html.js","sourceRoot":"","sources":["../../src/html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EACL,UAAU,EACV,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,eAAe,GAChB,MAAM,oBAAoB,CAAC"}

package/dist/src/router.d.ts

@@ -1,13 +0,0 @@
-/**
- * Router module entry point. The implementation lives in `./router/`:
- *
- *   ./router/match.ts        — pure pattern matching (compile/flatten/normalize)
- *   ./router/navigation.ts   — router() + navigate() + queryParam (touches window/history)
- *   ./router/manifest.ts     — routes() + prefetchPath + lazy loading + sync-fast-path
- *
- * This file keeps compatibility for internal imports from `"./router.js"`.
- * The public barrel (`src/index.ts`) also goes through this file.
- */
-export { router, navigate, queryParam, type RouterApi, type RouterOptions, type QueryParam, type QuerySignal, } from "./router/navigation.js";
-export type { RouteHandler, RouteParams, Routes, RoutesMap, } from "./router/match.js";
-export { routes, prefetchPath, type RoutesOptions, } from "./router/manifest.js";

package/dist/src/router.js

@@ -1,13 +0,0 @@
-/**
- * Router module entry point. The implementation lives in `./router/`:
- *
- *   ./router/match.ts        — pure pattern matching (compile/flatten/normalize)
- *   ./router/navigation.ts   — router() + navigate() + queryParam (touches window/history)
- *   ./router/manifest.ts     — routes() + prefetchPath + lazy loading + sync-fast-path
- *
- * This file keeps compatibility for internal imports from `"./router.js"`.
- * The public barrel (`src/index.ts`) also goes through this file.
- */
-export { router, navigate, queryParam, } from "./router/navigation.js";
-export { routes, prefetchPath, } from "./router/manifest.js";
-//# sourceMappingURL=router.js.map

package/dist/src/router.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,MAAM,EACN,QAAQ,EACR,UAAU,GAKX,MAAM,wBAAwB,CAAC;AAShC,OAAO,EACL,MAAM,EACN,YAAY,GAEb,MAAM,sBAAsB,CAAC"}

package/scripts/bundle.mjs

@@ -1,212 +0,0 @@
-// Production bundle through esbuild. No build config files.
-//
-// Usage:
-//   mado bundle
-//   mado bundle --entry src/main.ts --html index.html --out out
-//
-// Configuration precedence: built-in defaults < mado.config.json < CLI flags
-// < legacy env vars (ENTRY, HTML, OUT_DIR).
-//
-// What it does:
-//   1. Bundles `entry` with code splitting (each dynamic import → chunk),
-//      writing hashed `main-<hash>.js` and `chunk-<hash>.js` into <out>/assets/.
-//   2. Computes SRI for the entry bundle.
-//   3. Rewrites `html` so its <script type=module> points at the hashed entry,
-//      removes the dev importmap, and adds <link rel=modulepreload> for the
-//      entry and all chunks. Writes the result to <out>/index.html.
-//   4. Pre-compresses every .js into .gz and .br for nginx_gzip_static and
-//      Cloudflare/Netlify Accept-Encoding.
-//   5. Copies optional `favicon.ico`/`favicon.svg`/`assets/` from the project
-//      root if they exist (kept for backwards compatibility; new apps should
-//      put public assets in `public/` so `mado release` copies them).
-//
-// In repo-mode (the framework repo itself) the defaults still point at
-// examples/showcase so the framework can dogfood its bundle pipeline against
-// its biggest example.
-
-import { build } from "esbuild";
-import { readFile, writeFile, mkdir, cp, stat, readdir, rm } from "node:fs/promises";
-import { createHash } from "node:crypto";
-import { gzipSync, brotliCompressSync, constants as zlibConst } from "node:zlib";
-import { join, basename, resolve, dirname } from "node:path";
-import { existsSync } from "node:fs";
-
-import { loadConfig, parseFlags, resolveProjectPath } from "./_config.mjs";
-
-const { flags } = parseFlags(process.argv.slice(2));
-const cfg = loadConfig({});
-
-// Defaults are context-aware: in repo-mode they continue to bundle the
-// showcase example; in app-mode they assume the canonical layout.
-const defaultEntry = cfg.context === "repo"
-  ? "examples/showcase/main.ts"
-  : "src/main.ts";
-const defaultHtml = cfg.context === "repo"
-  ? "examples/showcase/index.html"
-  : "index.html";
-
-const ENTRY = resolveProjectPath(
-  cfg,
-  typeof flags.entry === "string" ? flags.entry : process.env.ENTRY ?? defaultEntry,
-);
-const HTML = resolveProjectPath(
-  cfg,
-  typeof flags.html === "string" ? flags.html : process.env.HTML ?? defaultHtml,
-);
-const OUT_DIR = resolveProjectPath(
-  cfg,
-  typeof flags.out === "string" ? flags.out : process.env.OUT_DIR ?? cfg.build.out ?? "out",
-);
-// Where the hashed bundles land. Apps want them under /assets/* to match
-// nginx.conf and _headers; in repo-mode we keep the historical out/main-*.js
-// layout so existing showcase pages continue to work.
-const ASSETS_REL = cfg.context === "repo" ? "" : "assets";
-const ASSETS_DIR = ASSETS_REL ? join(OUT_DIR, ASSETS_REL) : OUT_DIR;
-
-if (!existsSync(ENTRY)) {
-  console.error(`[bundle] entry not found: ${ENTRY}`);
-  console.error("[bundle] set bundle entry in mado.config.json or pass --entry <file>");
-  process.exit(1);
-}
-if (!existsSync(HTML)) {
-  console.error(`[bundle] html template not found: ${HTML}`);
-  console.error("[bundle] pass --html <file> or place index.html at the project root");
-  process.exit(1);
-}
-
-// Clean stale assets from previous bundles.
-//
-// Without this step, hashed chunks from prior runs (main-<oldhash>.js,
-// chunk-<oldhash>.js) accumulate in ASSETS_DIR. We later list ASSETS_DIR
-// (via readdir below) and emit <link rel="modulepreload"> for every
-// .js file we find — so stale chunks would be preloaded as if they were
-// still part of the app, polluting the production HTML and shipping dead
-// code over the wire. SRI is also only computed for the fresh entry, so
-// stale preloads would lack integrity checks.
-//
-// In app-mode the entire <out>/assets/ folder is owned by the bundler,
-// so wiping it is safe. In repo-mode the historical layout drops assets
-// directly into <out>/ alongside non-bundle artifacts, so we only remove
-// the recognisable hashed files there.
-if (ASSETS_REL) {
-  await rm(ASSETS_DIR, { recursive: true, force: true });
-} else if (existsSync(ASSETS_DIR)) {
-  for (const f of await readdir(ASSETS_DIR)) {
-    if (/^(main|chunk|asset)-[A-Z0-9]+\.(js|css)(\.map|\.gz|\.br)?$/i.test(f)) {
-      await rm(join(ASSETS_DIR, f), { force: true });
-    }
-  }
-}
-await mkdir(ASSETS_DIR, { recursive: true });
-
-console.log(`[bundle] entry:    ${ENTRY}`);
-console.log(`[bundle] html:     ${HTML}`);
-console.log(`[bundle] out:      ${OUT_DIR}`);
-if (ASSETS_REL) console.log(`[bundle] assets:   ${ASSETS_DIR}`);
-
-const result = await build({
-  entryPoints: [ENTRY],
-  bundle: true,
-  minify: true,
-  sourcemap: true,
-  format: "esm",
-  target: "es2022",
-  splitting: true,
-  outdir: ASSETS_DIR,
-  entryNames: "main-[hash]",
-  chunkNames: "chunk-[hash]",
-  assetNames: "asset-[hash]",
-  metafile: true,
-  legalComments: "none",
-});
-
-// 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);
-}
-
-// Collect all js chunks in the assets dir.
-const allJs = (await readdir(ASSETS_DIR)).filter((f) => f.endsWith(".js"));
-
-// Pre-compress every .js into .gz and .br.
-let totalRaw = 0;
-let totalGz = 0;
-let totalBr = 0;
-for (const f of allJs) {
-  const p = join(ASSETS_DIR, f);
-  const buf = await readFile(p);
-  totalRaw += buf.length;
-  const gz = gzipSync(buf, { level: 9 });
-  await writeFile(`${p}.gz`, gz);
-  totalGz += gz.length;
-  const br = brotliCompressSync(buf, { params: { [zlibConst.BROTLI_PARAM_QUALITY]: 11 } });
-  await writeFile(`${p}.br`, br);
-  totalBr += br.length;
-}
-
-// SRI for the main bundle.
-const mainBuf = await readFile(join(ASSETS_DIR, mainBundle));
-const sri = "sha384-" + createHash("sha384").update(mainBuf).digest("base64");
-
-// Rewrite HTML: drop dev importmap, swap the <script src>, add preloads.
-const urlPrefix = ASSETS_REL ? `/${ASSETS_REL}/` : "/";
-let html = await readFile(HTML, "utf8");
-
-html = html.replace(/<script type="importmap">[\s\S]*?<\/script>/, "");
-
-const preloads = allJs
-  .map(
-    (f) =>
-      `    <link rel="modulepreload" href="${urlPrefix}${f}"${
-        f === mainBundle ? ` integrity="${sri}" crossorigin="anonymous"` : ""
-      } />`,
-  )
-  .join("\n");
-
-const scriptTag = `<script type="module" src="${urlPrefix}${mainBundle}" integrity="${sri}" crossorigin="anonymous"></script>`;
-if (/<script\s+type="module"\s+src="[^"]+"[^>]*><\/script>/.test(html)) {
-  html = html.replace(
-    /<script\s+type="module"\s+src="[^"]+"[^>]*><\/script>/,
-    scriptTag,
-  );
-} else {
-  // No matching dev <script> in the template: inject one before </body>.
-  html = html.replace(/<\/body>/i, `  ${scriptTag}\n  </body>`);
-}
-
-html = html.replace(/<\/head>/, `${preloads}\n  </head>`);
-
-await mkdir(OUT_DIR, { recursive: true });
-await writeFile(join(OUT_DIR, "index.html"), html);
-
-// Backwards-compatible asset copy (repo-mode only). In app-mode the
-// `mado release` command copies the entire `public/` tree, which is the
-// recommended path for new apps.
-if (cfg.context === "repo") {
-  for (const name of ["favicon.ico", "favicon.svg", "assets"]) {
-    const src = join(cfg.projectRoot, "examples", name);
-    if (!existsSync(src)) continue;
-    const s = await stat(src);
-    if (s.isDirectory()) {
-      await cp(src, join(OUT_DIR, name), { recursive: true });
-    } else {
-      await cp(src, join(OUT_DIR, name));
-    }
-  }
-}
-
-// Stats
-const kib = (n) => (n / 1024).toFixed(1);
-console.log(`[bundle] chunks: ${allJs.length}`);
-for (const f of allJs.sort()) {
-  const sz = (await stat(join(ASSETS_DIR, f))).size;
-  const gz = (await stat(join(ASSETS_DIR, `${f}.gz`))).size;
-  const star = f === mainBundle ? " *" : "";
-  console.log(`  ${f.padEnd(24)} ${kib(sz).padStart(6)} KB raw, ${kib(gz).padStart(5)} KB gz${star}`);
-}
-console.log(`[bundle] total: ${kib(totalRaw)} KB raw / ${kib(totalGz)} KB gz / ${kib(totalBr)} KB br`);
-console.log(`[bundle] entry SRI: ${sri}`);