@madojs/mado 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+## 0.10.1 - 2026-06-12
+
+Patch release for the production bake/preview path.
+
+### Fixed
+
+- **Baked pages now use the production bundle during `mado release`.** Release
+  now bakes from the already bundled `out/index.html`, so baked HTML references
+  `/assets/main-*.js` instead of the dev-only `/dist/main.js`.
+
+- **Client boot no longer appends pages below baked HTML.** `mado bake` marks
+  the app container with `data-mado-baked`, and runtime `render()` replaces
+  that marked static DOM with live bindings on startup. This keeps bake as a
+  static first-paint/SEO shell, not SSR hydration, while avoiding duplicate
+  landing + route content after navigation.
+
+- **`mado preview` now serves the final `out/` artifact exactly.** Release
+  promotes baked HTML into real route paths inside `out/`, and preview no
+  longer applies a preview-only virtual mapping from `out/baked/`.
+
+- **`sitemap.xml` is promoted to the site root during release.** Standalone
+  `mado bake` still writes `out/baked/sitemap.xml`; `mado release` also copies
+  it to `out/sitemap.xml`, where static hosts and crawlers expect it.
+
+### Docs
+
+- Updated EN/RU/FR bake, deployment and project-layout docs to describe the
+  production release artifact, promoted baked routes, root sitemap and
+  `data-mado-baked` client boot behavior.
+
 ## 0.10.0 - 2026-06-12
 
 Surface-cleanup and API-lock release from the v1 tracker Phase B: legacy public

package/README.md

@@ -272,7 +272,7 @@ PoC in [`examples/cloudflare`](./examples/cloudflare/).
 ## Production
 
 ```bash
-mado release    # typecheck + build + bundle + bake + copy public -> out/
+mado release    # typecheck + build + bundle + bake + promote baked HTML + copy public -> out/
 mado preview    # serve out/ like a static host
 ```
 

package/dist/src/html/template.js

@@ -109,6 +109,16 @@ export function render(result, container) {
         }
         existing.dispose();
     }
+    // `mado bake` writes static first-paint markup into #app and marks the
+    // container. That markup is not hydrated: once the client app starts, Mado
+    // owns the container again and replaces the baked DOM with live bindings.
+    const isBakedContainer = !existing &&
+        "hasAttribute" in container &&
+        container.hasAttribute("data-mado-baked");
+    if (isBakedContainer) {
+        container.replaceChildren();
+        container.removeAttribute("data-mado-baked");
+    }
     if (!existing && container.childNodes.length > 0) {
         warnOnce("render-unmanaged-dom", "render() called on a container with existing DOM that was not created by Mado. It will remain alongside the new render output.");
     }

package/dist/src/html/template.js.map

@@ -1 +1 @@
-{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/html/template.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/html/template.ts"],"names":[],"mappings":"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"}

package/docs/en/02-project-layout.md

@@ -36,7 +36,8 @@ One-liner to remember:
 > Develop with `mado dev`. To ship: run `mado release`, then upload `out/`.
 
 `mado release` = `typecheck` + `build` (tsc → `dist/`) + `bundle` (esbuild
-→ `out/assets/`) + `bake` (HTML → `out/baked/`) + copy `public/*` → `out/`.
+→ `out/assets/`) + `bake` (HTML → `out/baked/`) + promote baked HTML and
+`sitemap.xml` into deployable `out/` paths + copy `public/*` → `out/`.
 
 You almost never need to look inside `dist/`. It exists so the dev browser can
 load native ESM modules without a bundler during development. In production
@@ -114,4 +115,4 @@ Precedence: built-in defaults < `mado.config.json` < CLI flags
   `process.env` and import that one module everywhere.
 - ❌ Tests mixed with code — put them in `test/`.
 - ❌ `examples/` folder — the framework repository has examples, your app
-  does not need one.
+  does not need one.

package/docs/en/13-deployment.md

@@ -12,9 +12,11 @@ out/
 ├── assets/                 ← hashed bundles (main-ABC.js, chunk-XYZ.js, …)
 │   ├── *.gz                ← precompressed gzip (gzip_static / Accept-Encoding)
 │   └── *.br                ← precompressed brotli (brotli_static / Accept-Encoding)
-├── baked/                  ← prerendered SEO HTML (mado bake)
+├── baked/                  ← bake output copy for inspection/debugging
 │   ├── <route>/index.html
 │   └── sitemap.xml
+├── <route>/index.html      ← prerendered SEO HTML promoted for static hosts
+├── sitemap.xml             ← sitemap promoted to the site root
 ├── favicon.svg             ← your public/ assets copied verbatim
 ├── _redirects              ← Cloudflare Pages / Netlify SPA fallback
 └── _headers                ← Cloudflare Pages / Netlify cache rules
@@ -31,9 +33,9 @@ mado release
 mado preview      # http://localhost:4173 — serves out/ exactly as a static host would
 ```
 
-`mado preview` mirrors the behavior described below: it picks `.br` over
-`.gz` over raw, prefers baked HTML at `/<route>/`, and falls back to
-`index.html` for unknown paths.
+`mado preview` serves the final `out/` directory like a static host: it picks
+`.br` over `.gz` over raw, serves promoted baked HTML when a route has an
+`index.html`, and falls back to `index.html` for unknown SPA paths.
 
 ---
 
@@ -79,8 +81,9 @@ npx wrangler pages deploy out --project-name=myapp
 - The generated `_redirects` (`/* /index.html 200`) gives you SPA fallback.
 - The generated `_headers` (immutable cache for `/assets/*`, `no-cache` for
   HTML) is honored by CF Pages.
-- Baked routes (`out/baked/<route>/index.html`) take priority over the SPA
-  fallback because CF Pages matches static files first.
+- Baked routes are promoted to real route files (`out/<route>/index.html`),
+  so they take priority over the SPA fallback because CF Pages matches static
+  files first.
 
 For preview branches, set the same build command in the CF Pages project:
 
@@ -189,4 +192,4 @@ jobs:
 
 See also: [`02-project-layout.md`](./02-project-layout.md) for the
 `src/`/`dist/`/`public/`/`out/` model and [`03-static-bake.md`](./03-static-bake.md)
-for the SEO bake mechanics.
+for the SEO bake mechanics.

package/docs/en/16-bake-cookbook.md

@@ -55,8 +55,10 @@ export default routes(manifest);
 
 ## Output
 
-By default app-mode writes baked pages under `out/baked/`. `mado release`
-produces the final deploy artifact:
+By default standalone `mado bake` writes baked pages under `out/baked/`.
+`mado release` uses the bundled production shell, keeps that `out/baked/` copy
+for inspection, promotes baked HTML into real route paths inside `out/`, and
+copies the generated sitemap to `out/sitemap.xml`:
 
 ```bash
 mado release
@@ -65,6 +67,12 @@ tree out
 
 The deployable folder is `out/`, not `dist/`.
 
+## Client boot
+
+Baked HTML marks `#app` with `data-mado-baked`. This is not hydration: when the
+client app starts, `render()` replaces the baked DOM with live bindings. The
+first response contains SEO/first-paint HTML, then the SPA takes over normally.
+
 ## Unsupported values
 
 Bake intentionally fails loudly instead of writing `[object Object]`. If a baked

package/docs/fr/02-project-layout.md

@@ -4,20 +4,14 @@ Chaque nouveau projet Mado a la même structure. C'est une convention **obligato
 
 ```
 my-app/
-├── package.json              # exactement 1 dép : typescript (esbuild optionnel)
-├── tsconfig.json             # avec paths "@madojs/mado" → import sans chemins relatifs
-├── Dockerfile + nginx.conf   # copiés depuis Mado/ lors du scaffold
-├── .gitlab-ci.yml | .github/workflows/ci.yml
-├── server/serve.mjs          # dev-server de Mado, sans dépendances
-├── scripts/
-│   ├── bundle.mjs            # bundle de production esbuild
-│   └── new.mjs               # générateur de pages
-├── templates/                # templates pour new.mjs
-├── docs/                     # documentation du projet (vous pouvez copier nos guides)
-├── public/                   # assets statiques (favicon, manifests)
+├── package.json              # runtime dep: @madojs/mado
+├── tsconfig.json             # strict TS, ES2022, Bundler resolution
+├── mado.config.json          # configuration dev/build/bake/bundle
+├── index.html                # shell SPA et template pour bake
+├── public/                   # assets statiques (favicon, images, robots.txt)
 └── src/
-    ├── main.ts               # entrée : providers + montage de <x-app>
-    ├── routes.ts             # manifeste de routes
+    ├── main.ts               # entrée : mount router dans #app
+    ├── routes.ts             # route manifest (default + named manifest)
     ├── pages/                # une page = un fichier = `export default page({...})`
     ├── components/           # composants réutilisables (x-*)
     ├── layouts/              # pages de layout (pour nested)
@@ -28,6 +22,19 @@ my-app/
         └── ...               # utilitaires, types, règles métier
 ```
 
+## États Des Artefacts
+
+| Dossier | Ce que c'est | Écrit par | Déployer ? |
+|---|---|---|---|
+| `src/` | sources TypeScript | vous | non |
+| `dist/` | output `tsc`, native ESM pour dev | `mado build` | non |
+| `public/` | assets statiques écrits par vous | vous | via `out/` |
+| `out/` | artefact déployable : shell SPA + bundles + HTML baked promu | `mado release` | oui |
+
+`mado release` = `typecheck` + `build` (`dist/`) + `bundle`
+(`out/assets/`) + `bake` (`out/baked/`) + promotion du HTML baked et de
+`sitemap.xml` dans les chemins déployables de `out/` + copie de `public/*`.
+
 ## Où mettre un nouveau fichier ?
 
 | Quoi | Où |

package/docs/fr/13-deployment.md

@@ -1,6 +1,6 @@
 # Déploiement
 
-Une commande, un artefact :
+Une commande, un artefact déployable :
 
 ```bash
 mado release
@@ -10,30 +10,51 @@ Résultat :
 
 ```txt
 out/
-├── index.html
-├── assets/
-├── baked/
-├── _redirects
-└── _headers
+├── index.html              ← shell SPA ou HTML baked promu pour /
+├── assets/                 ← bundles hashés (main-ABC.js, chunk-XYZ.js, ...)
+│   ├── *.gz                ← gzip précompressé
+│   └── *.br                ← brotli précompressé
+├── baked/                  ← copie de bake pour inspection/debugging
+│   ├── <route>/index.html
+│   └── sitemap.xml
+├── <route>/index.html      ← HTML baked promu pour les hébergeurs statiques
+├── sitemap.xml             ← sitemap à la racine du site
+├── _redirects              ← fallback SPA Cloudflare Pages / Netlify
+└── _headers                ← règles de cache
 ```
 
 Déploie `out/` sur nginx, Cloudflare Pages, Netlify, S3/CloudFront ou GitHub
-Pages.
+Pages. Ne déploie pas `dist/` : c'est un output interne.
+
+## Preview
 
 ```bash
 mado release
 mado preview
 ```
 
-`mado preview` sert `out/` comme un hébergeur statique : HTML baked d'abord,
-fallback SPA ensuite.
+`mado preview` sert le `out/` final comme un hébergeur statique : fichiers réels
+d'abord (`/<route>/index.html` si la route est baked), fallback SPA ensuite.
+Preview ne fait plus de mapping virtuel depuis `out/baked/`, donc il vérifie
+exactement ce qui sera déployé.
 
-Pour VPS + nginx :
+## VPS + nginx
 
 ```bash
 mado release
 rsync -avz --delete out/ user@server:/var/www/myapp/
 ```
 
-Le `nginx.conf` fourni gère cache immutable pour les bundles hashés, no-cache
-pour HTML, et fallback SPA pour les deep links.
+Le `nginx.conf` fourni gère le cache immutable pour les bundles hashés, no-cache
+pour HTML, et le fallback SPA pour les deep links.
+
+## Cloudflare / Netlify
+
+```bash
+mado release
+npx wrangler pages deploy out --project-name=myapp
+```
+
+`_redirects` et `_headers` sont générés automatiquement si tu n'en fournis pas.
+Les routes baked sont promues en vrais fichiers (`out/<route>/index.html`), donc
+l'hébergeur statique les sert avant le fallback SPA.

package/docs/fr/16-bake-cookbook.md

@@ -1,8 +1,10 @@
-# Bake cookbook
+# Bake Cookbook
 
 `mado bake` rend certaines routes en HTML statique. C'est pour le SEO et un
 premier rendu rapide, pas pour SSR + hydration.
 
+## Page Minimale
+
 ```ts
 export default page({
   head: () => ({ title: "Products", description: "Catalog" }),
@@ -21,15 +23,66 @@ export default page({
 ```
 
 Dans les vues baked, préfère les tableaux simples (`items.map(...)`). Les
-directives runtime comme `each()` sont pour le navigateur.
+directives runtime comme keyed `each()` sont pour le navigateur.
+
+## Routes Dynamiques
+
+```ts
+export default page<{ slug: string }>({
+  head: ({ slug }, data) => ({ title: data.title, canonical: `/blog/${slug}` }),
+  view: ({ data }) => html`<article>${unsafeHTML(data.html)}</article>`,
+  bake: {
+    paths: async () => (await api.posts()).map((p) => ({ slug: p.slug })),
+    data: ({ slug }) => api.post(slug),
+  },
+});
+```
+
+Utilise `unsafeHTML()` seulement pour du HTML fiable ou déjà nettoyé.
+
+## Route Manifest
+
+`mado bake` a besoin du manifest source :
 
 ```ts
 export const manifest = {
   "/": () => import("./pages/home.js"),
   "/blog/:slug": () => import("./pages/blog-post.js"),
 };
+
 export default routes(manifest);
 ```
 
-`mado release` produit l'artefact déployable dans `out/`. Si bake signale une
-valeur non supportée, remplace la partie runtime-only ou rends-la côté client.
+## Output
+
+Standalone `mado bake` écrit les pages baked dans `out/baked/` par défaut.
+`mado release` utilise le shell de production bundlé, garde cette copie
+`out/baked/` pour inspection, promeut le HTML dans les vrais chemins de route
+dans `out/`, et copie le sitemap vers `out/sitemap.xml`.
+
+```bash
+mado release
+tree out
+```
+
+Le dossier déployable est `out/`, pas `dist/`.
+
+## Client Boot
+
+Le HTML baked marque `#app` avec `data-mado-baked`. Ce n'est pas de
+l'hydration : au démarrage, `render()` remplace le DOM baked par les bindings
+vivants de l'application.
+
+## Valeurs Non Supportées
+
+Bake échoue volontairement au lieu d'écrire `[object Object]`. Si une vue baked
+signale une directive non supportée :
+
+- remplace `each()` par `items.map(...)` dans le markup baked ;
+- garde les widgets interactifs dans des routes client-only ;
+- assure-toi que chaque valeur peut être sérialisée en HTML statique.
+
+## Canonical Links
+
+Passe `--base-url` ou configure `bake.baseUrl` dans `mado.config.json` pour que
+les liens canonical et le sitemap pointent vers la production.

package/docs/ru/02-project-layout.md

@@ -1,23 +1,17 @@
-# Project layout
+# Project Layout
 
 Каждый new-проект на Mado имеет одинаковую структуру. Это **обязательное** соглашение.
 
 ```
 my-app/
-├── package.json              # ровно 1 dep: typescript (esbuild опц.)
-├── tsconfig.json             # с paths "@madojs/mado" → импорт без относительных путей
-├── Dockerfile + nginx.conf   # копируем из Mado/ при scaffold
-├── .gitlab-ci.yml | .github/workflows/ci.yml
-├── server/serve.mjs          # dev-сервер из Mado, без deps
-├── scripts/
-│   ├── bundle.mjs            # esbuild прод-бандл
-│   └── new.mjs               # скаффолд страницы
-├── templates/                # шаблоны для new.mjs
-├── docs/                     # проектные доки (можно копировать наши гайды)
-├── public/                   # статика (favicon, манифесты)
+├── package.json              # runtime dep: @madojs/mado
+├── tsconfig.json             # strict TS, ES2022, Bundler resolution
+├── mado.config.json          # dev/build/bake/bundle config
+├── index.html                # SPA shell и template для bake
+├── public/                   # статика (favicon, images, robots.txt)
 └── src/
-    ├── main.ts               # точка входа: провайдеры + монтаж <x-app>
-    ├── routes.ts             # манифест роутов
+    ├── main.ts               # точка входа: mount router в #app
+    ├── routes.ts             # route manifest (default + named manifest)
     ├── pages/                # одна страница = один файл = `export default page({...})`
     ├── components/           # переиспользуемые компоненты (x-*)
     ├── layouts/              # layout-страницы (для nested)
@@ -28,6 +22,19 @@ my-app/
         └── ...               # утилиты, типы, бизнес-правила
 ```
 
+## Artifact States
+
+| Folder | Что это | Кто пишет | Deploy? |
+|---|---|---|---|
+| `src/` | исходники TypeScript | ты | no |
+| `dist/` | output `tsc`, native ESM для dev | `mado build` | no |
+| `public/` | авторская статика | ты | через `out/` |
+| `out/` | deploy artifact: SPA shell + bundles + promoted baked HTML | `mado release` | yes |
+
+`mado release` = `typecheck` + `build` (`dist/`) + `bundle`
+(`out/assets/`) + `bake` (`out/baked/`) + promote baked HTML и
+`sitemap.xml` в deployable `out/` paths + copy `public/*`.
+
 ## Куда положить новый файл?
 
 | Что | Куда |
@@ -54,4 +61,4 @@ my-app/
 
 - ❌ Конфиги билдеров (webpack, rollup, vite) — у нас их нет.
 - ❌ `.env`-файлы — env читается из `process.env`/`import.meta.env` в `lib/config.ts`.
-- ❌ Тесты вперемешку с кодом — все в `test/`.
+- ❌ Тесты вперемешку с кодом — все в `test/`.

package/docs/ru/13-deployment.md

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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madojs/mado",
-  "version": "0.10.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",

package/scripts/bake.mjs

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

@@ -241,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}`);
@@ -276,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)) {
@@ -288,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"),
@@ -319,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);

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.

package/starters/admin/README.md

@@ -28,7 +28,7 @@ npm run build      # tsc → dist/
 npm run typecheck  # tsc --noEmit
 npm run bundle     # esbuild → out/assets/
 npm run bake       # prerender baked routes → out/baked/
-npm run release    # typecheck + build + bundle + bake + copy public/ → out/
+npm run release    # typecheck + build + bundle + bake + promote baked HTML + copy public/ → out/
 npm run preview    # serve out/ locally (production rehearsal)
 ```
 
@@ -60,4 +60,4 @@ Change `mado.config.json#dev.proxy` to point at your backend in development.
 See the framework docs:
 [`docs/en/11-layouts.md`](https://github.com/madojs/mado/blob/main/docs/en/11-layouts.md),
 [`docs/en/12-auth-and-api.md`](https://github.com/madojs/mado/blob/main/docs/en/12-auth-and-api.md),
-[`docs/en/13-deployment.md`](https://github.com/madojs/mado/blob/main/docs/en/13-deployment.md).
+[`docs/en/13-deployment.md`](https://github.com/madojs/mado/blob/main/docs/en/13-deployment.md).