@madojs/mado 0.9.0 → 0.10.1

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,7 +1,7 @@
 # Mado
 
 > A calm browser-native SPA framework for internal tools, admin panels and business apps.  
-> Routing, forms, state, data fetching and prerendering. TypeScript-only build (`tsc`), zero runtime dependencies.
+> Routing, forms, state, data fetching and prerendering. Zero runtime dependencies; generated apps use `typescript`, `esbuild` and `linkedom` as dev tooling.
 
 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.
 
@@ -15,7 +15,10 @@ Mado is a focused frontend framework for admin panels, internal tools and CRUD-h
 - **Cleanup via `ctx.onDispose(fn)`** in setup, not via return from effect.
 - **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. Uses `observedAttributes` when available, falls back to a per-instance `MutationObserver` for attrs registered during setup. No boilerplate needed.
+- **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
 
@@ -47,6 +50,24 @@ Mado is a focused frontend framework for admin panels, internal tools and CRUD-h
    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
@@ -114,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
@@ -201,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)
@@ -210,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()`
@@ -221,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,6 +1,6 @@
 {
   "name": "@madojs/mado",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "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",
@@ -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",

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) {
@@ -534,7 +533,10 @@ function buildHtml({ template, bodyHtml, head, bakedData, revalidate, canonical
   }
 
   const app = document.getElementById("app");
-  if (app) app.innerHTML = bodyHtml;
+  if (app) {
+    app.setAttribute("data-mado-baked", "");
+    app.innerHTML = bodyHtml;
+  }
 
   return "<!doctype html>\n" + document.documentElement.outerHTML;
 }

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)) {
@@ -240,15 +241,28 @@ async function runRelease(rawArgs) {
   //     → rm -rf out/        (unless --no-clean)
   //     → mado typecheck
   //     → mado build       (tsc → dist/)
-  //     → mado bundle      (esbuild → out/assets/, also copies index.html)
-  //     → mado bake        (HTML  → out/baked/)
+  //     → mado bundle      (esbuild → out/assets/, also writes out/index.html)
+  //     → mado bake        (HTML → out/baked/, using bundled out/index.html)
   //     → copy public/* → out/
+  //     → promote baked HTML + sitemap into out/ route paths
   //
   // Flags are forwarded to bake/bundle.
   const { flags: releaseFlags } = parseFlags(rawArgs);
   const cfg = loadConfig({ projectRoot: PROJECT_ROOT });
-  const outDir = resolve(cfg.projectRoot, cfg.build.out ?? "out");
+  const outDir = resolve(
+    cfg.projectRoot,
+    typeof releaseFlags.out === "string" ? releaseFlags.out : cfg.build.out ?? "out",
+  );
   const publicDir = resolve(cfg.projectRoot, cfg.build.publicDir ?? "public");
+  const bundledHtml = join(outDir, "index.html");
+  const bakedDir = resolve(
+    cfg.projectRoot,
+    cfg.bake.outDir ??
+      join(
+        typeof releaseFlags.out === "string" ? releaseFlags.out : cfg.build.out ?? "out",
+        "baked",
+      ),
+  );
 
   console.log(`[release] context: ${cfg.context}`);
   console.log(`[release] artifact: ${outDir}`);
@@ -275,8 +289,14 @@ async function runRelease(rawArgs) {
   console.log("[release] step 3/5  bundle (esbuild → out/assets/)");
   await runNodeScript("scripts/bundle.mjs", rawArgs);
 
-  console.log("[release] step 4/5  bake (out/baked/)");
-  await runNodeScript("scripts/bake.mjs", rawArgs);
+  console.log("[release] step 4/5  bake (out/baked/, bundled shell)");
+  await runNodeScript("scripts/bake.mjs", [
+    ...rawArgs,
+    "--template",
+    bundledHtml,
+    "--out",
+    bakedDir,
+  ]);
 
   console.log("[release] step 5/5  copy public/ → out/");
   if (existsSync(publicDir)) {
@@ -287,6 +307,14 @@ async function runRelease(rawArgs) {
     console.log(`[release]   no ${publicDir}, skipping`);
   }
 
+  const promoted = await promoteBakedHtml(bakedDir, outDir);
+  if (promoted.html > 0) {
+    console.log(`[release]   promoted ${promoted.html} baked HTML page(s) into out/`);
+  }
+  if (promoted.sitemap) {
+    console.log(`[release]   copied sitemap.xml → ${join(outDir, "sitemap.xml")}`);
+  }
+
   // Optional CDN config files. Generated only when not already provided.
   await writeIfMissing(
     join(outDir, "_redirects"),
@@ -318,6 +346,40 @@ async function writeIfMissing(path, content) {
   console.log(`[release]   wrote ${path}`);
 }
 
+async function promoteBakedHtml(bakedDir, outDir) {
+  if (!existsSync(bakedDir)) return { html: 0, sitemap: false };
+
+  let html = 0;
+
+  async function walk(dir, rel = "") {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const nextRel = rel ? `${rel}/${entry.name}` : entry.name;
+      const source = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(source, nextRel);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith(".html")) continue;
+      const target = join(outDir, nextRel);
+      await mkdir(dirname(target), { recursive: true });
+      await copyFile(source, target);
+      html++;
+    }
+  }
+
+  await walk(bakedDir);
+
+  const bakedSitemap = join(bakedDir, "sitemap.xml");
+  const rootSitemap = join(outDir, "sitemap.xml");
+  let sitemap = false;
+  if (existsSync(bakedSitemap)) {
+    await copyFile(bakedSitemap, rootSitemap);
+    sitemap = true;
+  }
+
+  return { html, sitemap };
+}
+
 async function copyCanonicalAgentFiles(target) {
   for (const file of ["AGENTS.md", "llms.txt"]) {
     const source = join(PACKAGE_ROOT, file);
@@ -331,6 +393,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/preview.mjs

@@ -11,7 +11,7 @@
 //   3. Starts a static server with:
 //        - immutable cache for hashed bundles;
 //        - SPA fallback to index.html;
-//        - baked HTML priority over the SPA shell;
+//        - exact `out/` route files before SPA fallback;
 //        - precompressed .gz / .br serving via Accept-Encoding.
 //
 // Goal: see production-like output locally without Docker/nginx, identical to
@@ -58,9 +58,9 @@ const OUT = resolve(
   process.env.OUT_DIR ?? cfg.build.out ?? "out",
 );
 // Baked HTML lives in <out>/baked/ by default (see scripts/bake.mjs and
-// mado.config.json bake.outDir). Preview serves it with priority over the
-// SPA shell so URLs that have a prerendered HTML page render real markup
-// instead of an empty <div id="app"></div>.
+// mado.config.json bake.outDir). `mado release` promotes those HTML files into
+// real route paths inside <out>/, so preview can serve exactly what a static
+// host sees instead of applying a preview-only virtual mapping.
 const BAKED = resolve(
   ROOT,
   process.env.BAKED_DIR ?? cfg.bake?.outDir ?? join(cfg.build.out ?? "out", "baked"),
@@ -215,30 +215,10 @@ function basenameSafe(p) {
 async function resolveTarget(pathname) {
   if (pathname === "/") pathname = "/index.html";
 
-  // 1) Baked HTML wins. `mado bake` writes prerendered pages into
-  //    <out>/baked/<path>/index.html. Serve them with priority over the
-  //    SPA shell so search engines AND human users hitting a prerendered
-  //    URL see real content immediately. Without this branch preview
-  //    served the empty SPA shell for every URL, which looked like a
-  //    "blank page" bug even when bake had succeeded.
-  if (await exists(BAKED)) {
-    if (!extname(pathname) || pathname.endsWith("/index.html")) {
-      const bakedDir = join(BAKED, pathname.replace(/\/index\.html$/, ""));
-      const bakedIdx = join(bakedDir, "index.html");
-      if (await exists(bakedIdx)) return bakedIdx;
-    }
-    // Direct file (sitemap.xml etc.) from the baked dir.
-    const bakedFile = resolve(join(BAKED, pathname));
-    if (bakedFile.startsWith(BAKED + sep) && (await exists(bakedFile))) {
-      const s = await stat(bakedFile);
-      if (!s.isDirectory()) return bakedFile;
-    }
-  }
-
   const candidate = resolve(join(OUT, pathname));
   if (!candidate.startsWith(OUT + sep) && candidate !== OUT) return null;
 
-  // 2) Exact match inside out/.
+  // 1) Exact match inside out/.
   if (await exists(candidate)) {
     const s = await stat(candidate);
     if (s.isDirectory()) {
@@ -249,13 +229,13 @@ async function resolveTarget(pathname) {
     }
   }
 
-  // 3) /foo → /foo/index.html (for sub-folders without trailing slash).
+  // 2) /foo → /foo/index.html (for sub-folders without trailing slash).
   if (!extname(pathname)) {
     const asDir = join(OUT, pathname, "index.html");
     if (await exists(asDir)) return asDir;
   }
 
-  // 4) SPA-fallback: any non-asset path falls back to the SPA shell so
+  // 3) SPA-fallback: any non-asset path falls back to the SPA shell so
   //    client-side routing handles it. Asset-looking paths (with an
   //    extension) deliberately 404 instead — otherwise a 200 on
   //    /missing.png would mask real bugs.