@madojs/mado 0.11.0 → 0.12.0

package/scripts/cli/index.mjs

@@ -31,10 +31,21 @@ export async function main(argv) {
       await runInit(ctx, args);
       break;
     case "build":
-      await runNodeBin(ctx, "typescript/bin/tsc", args);
+      // Framework repo bootstraps via `tsc` (so the published package
+      // ships compiled .js). Every other context — user apps, the
+      // starter — gets a production Vite build of the deployable SPA.
+      if (ctx.isRepo) {
+        await runNodeBin(ctx, "typescript/bin/tsc", args);
+      } else {
+        await runVite(ctx, ["build", ...args], { defaultConfig: true });
+      }
       break;
     case "watch":
-      await runNodeBin(ctx, "typescript/bin/tsc", ["-w", ...args]);
+      if (ctx.isRepo) {
+        await runNodeBin(ctx, "typescript/bin/tsc", ["-w", ...args]);
+      } else {
+        await runVite(ctx, ["build", "--watch", ...args], { defaultConfig: true });
+      }
       break;
     case "typecheck":
       await runNodeBin(ctx, "typescript/bin/tsc", ["--noEmit", ...args]);
@@ -42,7 +53,7 @@ export async function main(argv) {
     case "test": {
       await runNodeBin(ctx, "typescript/bin/tsc", []);
       const files = await listTestFiles(projectRoot);
-      await run(process.execPath, ["--test", "--test-timeout=30000", ...files, ...args], {
+      await run(process.execPath, ["--test", "--test-timeout=120000", ...files, ...args], {
         cwd: projectRoot,
       });
       break;
@@ -55,7 +66,12 @@ export async function main(argv) {
       );
       break;
     case "bake":
-      await runNodeScript(ctx, "scripts/bake.mjs", args);
+      console.error("[mado] `mado bake` was removed.");
+      console.error("Use `mado static`, or run the complete pipeline with `mado release`.");
+      process.exit(1);
+      break;
+    case "static":
+      await runNodeScript(ctx, "scripts/static.mjs", args);
       break;
     case "preview":
       await runNodeScript(ctx, "scripts/preview.mjs", args);

package/scripts/cli/init.mjs

@@ -4,7 +4,12 @@ import { join, resolve } from "node:path";
 
 import { parseFlags } from "../_config.mjs";
 
-const STARTERS = ["default"];
+// `default` is the universal starter: minimal, runnable, zero backend.
+// `modular` is the long-lived business-app reference architecture:
+//   auth, billing, guards, layouts, services, connectors, contracts.
+// Both target the same Mado runtime — they only differ in how much
+// structure they pre-create.
+const STARTERS = ["default", "modular"];
 
 export async function runInit(ctx, rawArgs) {
   const { flags, positional } = parseFlags(rawArgs);
@@ -109,8 +114,8 @@ async function ensureStarterPackageJson(ctx, target) {
   pkg.devDependencies = {
     ...(pkg.devDependencies ?? {}),
     typescript: rootDev.typescript ?? "^6.0.3",
-    linkedom: rootDev.linkedom ?? "^0.18.12",
     lightningcss: rootDev.lightningcss ?? "^1.32.0",
+    "playwright-core": rootDev["playwright-core"] ?? "^1.47.0",
     vite: rootDev.vite ?? "^8.0.16",
   };
 

package/scripts/cli/release.mjs

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
-import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { brotliCompressSync, constants as zlibConst, gzipSync } from "node:zlib";
 
 import { parseFlags } from "../_config.mjs";
@@ -12,8 +12,6 @@ export async function runRelease(ctx, rawArgs) {
     ctx.projectRoot,
     typeof releaseFlags.out === "string" ? releaseFlags.out : "out",
   );
-  const bundledHtml = join(outDir, "index.html");
-  const bakedDir = join(outDir, "baked");
 
   console.log(`[release] context: ${ctx.context}`);
   console.log(`[release] artifact: ${outDir}`);
@@ -34,37 +32,22 @@ export async function runRelease(ctx, rawArgs) {
   console.log("[release] step 2/5  vite build");
   await runVite(ctx, ["build", "--outDir", outDir], { defaultConfig: true });
 
-  console.log("[release] step 3/5  bake");
-  if (releaseFlags["keep-bake-dir"]) {
-    await runNodeScript(ctx, "scripts/bake.mjs", [
-      ...rawArgs.filter((a) => a !== "--keep-bake-dir"),
-      "--template",
-      bundledHtml,
-      "--out",
-      bakedDir,
-    ]);
-    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")}`);
-    }
-  } else {
-    await runNodeScript(ctx, "scripts/bake.mjs", [
-      ...rawArgs,
-      "--template",
-      bundledHtml,
-      "--out",
-      outDir,
-    ]);
+  console.log("[release] step 3/5  static snapshots");
+  await runNodeScript(ctx, "scripts/static.mjs", [
+    ...rawArgs.filter((a) => a !== "--no-clean"),
+    "--out",
+    outDir,
+  ]);
+
+  console.log("[release] step 4/5  deployment files");
+  // GitHub Pages / Netlify / Cloudflare Pages fallback. SPA fallback shell
+  // is written by `mado static`; here we only register the deployment
+  // bindings, and respect user-supplied files (writeIfMissing).
+  const spaShell = join(outDir, "_mado/spa.html");
+  if (existsSync(spaShell)) {
+    await writeIfMissing(join(outDir, "404.html"), await readFile(spaShell, "utf8"), "[release]  ");
   }
-
-  console.log("[release] step 4/5  precompress assets");
-  await precompressOut(outDir);
-
-  console.log("[release] step 5/5  CDN config");
-  await writeIfMissing(join(outDir, "_redirects"), "/* /index.html 200\n", "[release]  ");
+  await writeIfMissing(join(outDir, "_redirects"), "/* /_mado/spa.html 200\n", "[release]  ");
   await writeIfMissing(
     join(outDir, "_headers"),
     [
@@ -78,45 +61,14 @@ export async function runRelease(ctx, rawArgs) {
     "[release]  ",
   );
 
+  console.log("[release] step 5/5  precompress assets");
+  await precompressOut(outDir);
+
   console.log("");
   console.log(`[release] done. Deploy artifact: ${outDir}`);
   console.log("[release] try:  mado preview");
 }
 
-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 precompressOut(outDir) {
   if (!existsSync(outDir)) return;
   const files = await listCompressibleFiles(outDir);

package/scripts/docs-lint.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// Docs lint: refuses to ship documentation that still uses the legacy
+// vocabulary the 0.12 release replaced. Active reference docs, README,
+// llms.txt, AGENTS.md, CONTRIBUTING.md, TODO.md and the starter READMEs
+// must use the new terms; migration guides, CHANGELOG, release notes
+// and ADRs are allowed to mention the old names by name so users can
+// find them.
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, "..");
+
+// Phrases that MUST disappear from current docs/README/llms/AGENTS. They
+// remain legal inside the allow-listed contexts below.
+const FORBIDDEN = [
+  // Page API renamed from `bake` to `static`.
+  { pattern: /\bpage\.bake\b/, replacement: "page.static" },
+  { pattern: /\bbake\.paths\b/, replacement: "static.paths" },
+  { pattern: /\bbake\.data\b/, replacement: "static.initialData" },
+  { pattern: /\bbake\.revalidate\b/, replacement: "drop; no revalidate API" },
+
+  // CLI renamed from `bake` to `static`.
+  { pattern: /\bmado bake\b/, replacement: "mado static" },
+  { pattern: /\bnpm run bake\b/, replacement: "npm run release" },
+
+  // Output / marker shape changed.
+  { pattern: /\bout\/baked\b/, replacement: "out/<route>/index.html" },
+  { pattern: /#bake\b/, replacement: "data-mado-static-data" },
+
+  // Old "Smart Static (`bake`)" headline.
+  { pattern: /Smart Static \(`bake`\)/, replacement: "Static snapshots (`mado static`)" },
+
+  // Old transport / renderer claims.
+  { pattern: /No Vite required/i, replacement: "drop the phrase; Vite is the canonical transport" },
+  { pattern: /\bNo Chromium needed\b/i, replacement: "drop the phrase; mado static REQUIRES Chromium" },
+  // `linkedom` is also a legitimate Node-side test helper (the framework
+  // uses it in test/router/* for DOM unit tests). We only flag the
+  // phrases that mis-described the snapshot pipeline as a linkedom
+  // renderer.
+  { pattern: /linkedom (?:as|is) (?:the |a )?(?:static|snapshot|production) renderer/i,
+    replacement: "drop the claim; capture uses Playwright/Chromium" },
+  { pattern: /linkedom-?based renderer/i,
+    replacement: "drop the claim; capture uses Playwright/Chromium" },
+  { pattern: /server-rendered snapshot/i, replacement: "browser-rendered snapshot" },
+  { pattern: /\bmeta[- ]shell\b/i, replacement: "static snapshot" },
+
+  // Old positioning.
+  {
+    pattern: /SEO-heavy public sites are not supported/i,
+    replacement: "drop the phrase — Mado now snapshots public sites",
+  },
+  {
+    pattern: /\binternal tools only\b/i,
+    replacement: "drop the phrase — Mado is for sites and apps",
+  },
+  {
+    pattern: /SPA framework for internal tools/i,
+    replacement: "drop the phrase — Mado is for sites and apps",
+  },
+  {
+    pattern: /shadow:\s*false[^.\n]*SEO/i,
+    replacement: "drop the recommendation; SEO is handled by snapshots",
+  },
+
+  // Old pre-Vite transport language.
+  { pattern: /\btsc[- ]only\b/i, replacement: "drop the phrase — Vite is the canonical transport" },
+  { pattern: /\bno bundler\b/i, replacement: "drop the phrase — Vite is the canonical bundler" },
+  { pattern: /\btsc\s*(?:→|->)+\s*browser\b/i,
+    replacement: "drop the phrase — generated apps go through Vite" },
+  { pattern: /\bimport[\s-]?map(?:s)?\b/i, replacement: "drop the phrase — apps use Vite, not import maps" },
+
+  // Old dev / static / edge claims.
+  { pattern: /SSE[- ]?reload/i, replacement: "drop the phrase — dev uses Vite HMR" },
+  { pattern: /\bedge[- ]prerender\b/i, replacement: "drop the phrase — capture is `mado static` only" },
+
+  // Old doc filenames in active docs (the migration table in
+  // docs/en/README.md is allow-listed via docs-lint:allow-legacy-mention
+  // markers around it if needed).
+  { pattern: /\b03-static-bake\.md\b/, replacement: "15-static-snapshots.md" },
+  { pattern: /\b09-shadow-vs-light-dom\.md\b/, replacement: "10-pages-and-components.md" },
+  { pattern: /\b10-app-architecture\.md\b/, replacement: "16-app-architecture.md" },
+  { pattern: /\b13-deployment\.md\b/, replacement: "20-deployment.md" },
+  { pattern: /\b16-bake-cookbook\.md\b/, replacement: "23-cookbook.md" },
+  { pattern: /\b18-api-freeze-map\.md\b/, replacement: "30-api-freeze-map.md" },
+  { pattern: /\b19-reactivity-ordering\.md\b/, replacement: "31-reactivity-ordering.md" },
+  { pattern: /\b20-v1-stability\.md\b/, replacement: "32-v1-stability.md" },
+  { pattern: /\b07-llm-pitfalls\.md\b/, replacement: "40-llm-guide.md" },
+  { pattern: /\b08-llm-zero-history-test\.md\b/, replacement: "40-llm-guide.md" },
+];
+
+const ALLOW_LISTED = [
+  /(^|\/)CHANGELOG\.md$/,
+  /(^|\/)docs\/architecture\/adr\//,
+  /(^|\/)docs\/.+migration/i,
+  /(^|\/)docs\/.+v1-stability/i,
+  /(^|\/)scripts\/docs-lint\.mjs$/,
+];
+
+// Files / trees that must stay on-message about the post-0.12 API. New
+// roots must be added here AND covered by the CI step.
+const ROOTS = [
+  "README.md",
+  "AGENTS.md",
+  "llms.txt",
+  "CONTRIBUTING.md",
+  "TODO.md",
+  "docs/README.md",
+  "docs/en",
+  "starters/default/README.md",
+  "starters/modular/README.md",
+];
+
+let errors = 0;
+
+for (const root of ROOTS) {
+  const full = join(REPO_ROOT, root);
+  try {
+    statSync(full);
+  } catch {
+    continue;
+  }
+  scan(full);
+}
+
+if (errors > 0) {
+  console.error(`\n[docs-lint] ${errors} forbidden term(s) in current docs.`);
+  process.exit(1);
+}
+console.log("[docs-lint] OK");
+
+function scan(path) {
+  const stat = statSync(path);
+  if (stat.isDirectory()) {
+    for (const entry of readdirSync(path)) scan(join(path, entry));
+    return;
+  }
+  if (!path.endsWith(".md") && !path.endsWith(".txt")) return;
+  const rel = path.slice(REPO_ROOT.length + 1);
+  if (ALLOW_LISTED.some((rx) => rx.test(rel))) return;
+
+  const body = readFileSync(path, "utf8");
+  const lines = body.split("\n");
+  let inIgnoreBlock = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Block-scoped allowance: paragraphs that teach LLMs which names
+    // are obsolete must be free to mention those names verbatim.
+    //   <!-- docs-lint:allow-legacy-mention -->
+    //   ...legacy terms...
+    //   <!-- /docs-lint:allow-legacy-mention -->
+    if (line.includes("docs-lint:allow-legacy-mention")) {
+      inIgnoreBlock = !line.includes("/docs-lint:allow-legacy-mention");
+      continue;
+    }
+    if (inIgnoreBlock) continue;
+
+    for (const rule of FORBIDDEN) {
+      if (rule.pattern.test(line)) {
+        errors++;
+        console.error(
+          `${rel}:${i + 1}: forbidden term matches /${rule.pattern.source}/. ` +
+            `Replace with: ${rule.replacement}`,
+        );
+      }
+    }
+  }
+}

package/scripts/package-smoke.mjs

@@ -21,18 +21,24 @@ try {
   await mkdir(installRoot, { recursive: true });
   await run("npm", ["install", tarball], { cwd: installRoot });
 
+  // Public-API surface smoke: prove the published tarball exposes the
+  // root entry, the devtools side-effect import and the Vite plugin,
+  // while still hiding internal subpaths behind `exports`.
   await run(
     process.execPath,
     [
       "--input-type=module",
       "--eval",
       `
-        import { html, signal } from "@madojs/mado";
+        import { html, signal, routeUrl, appBase } from "@madojs/mado";
         import "@madojs/mado/devtools.js";
         import { mado } from "@madojs/mado/vite";
         if (typeof html !== "function" || typeof signal !== "function") {
           throw new Error("public root import failed");
         }
+        if (typeof routeUrl !== "function" || typeof appBase !== "string") {
+          throw new Error("routing helpers missing from public root");
+        }
         if (typeof mado !== "function") throw new Error("vite plugin import failed");
         try {
           await import("@madojs/mado/lifecycle.js");
@@ -45,15 +51,56 @@ try {
     { cwd: installRoot },
   );
 
-  await run("npx", ["mado", "init", "smoke-app"], {
-    cwd: installRoot,
-    env: { ...process.env, MADO_PACKAGE_SPEC: tarball },
+  // We exercise BOTH published starters end-to-end:
+  //
+  //   smoke-universal — `mado init` (default), npm install, typecheck,
+  //                     release. This is the path the README quick-start
+  //                     points new users to; if it ever breaks for a
+  //                     published tarball the first-run experience is
+  //                     broken.
+  //
+  //   smoke-modular   — `mado init --starter modular`, npm install,
+  //                     `mado new module`, release. Long-lived apps
+  //                     deploy this shape; the `mado new` generator
+  //                     also lives here.
+  //
+  // Each run uses MADO_SITE so static routes resolve canonical URLs,
+  // and points the starter at the freshly packed tarball through
+  // MADO_PACKAGE_SPEC so package.json doesn't reference an unpublished
+  // version.
+
+  await smokeStarter({
+    label: "universal",
+    appName: "smoke-universal",
+    initArgs: ["mado", "init", "smoke-universal"],
+    after: async (appRoot) => {
+      await run("npm", ["run", "typecheck"], { cwd: appRoot });
+      await run("npm", ["run", "release"], {
+        cwd: appRoot,
+        env: { ...process.env, MADO_SITE: "https://package-smoke.test" },
+      });
+    },
+    installRoot,
+    tarball,
   });
 
-  const appRoot = join(installRoot, "smoke-app");
-  await run("npm", ["install"], { cwd: appRoot });
-  await run("npm", ["run", "new", "--", "module", "smoke"], { cwd: appRoot });
-  await run("npm", ["run", "release"], { cwd: appRoot });
+  await smokeStarter({
+    label: "modular",
+    appName: "smoke-modular",
+    initArgs: ["mado", "init", "smoke-modular", "--starter", "modular"],
+    after: async (appRoot) => {
+      await run("npm", ["run", "new", "--", "module", "smoke"], {
+        cwd: appRoot,
+      });
+      await run("npm", ["run", "typecheck"], { cwd: appRoot });
+      await run("npm", ["run", "release"], {
+        cwd: appRoot,
+        env: { ...process.env, MADO_SITE: "https://package-smoke.test" },
+      });
+    },
+    installRoot,
+    tarball,
+  });
 
   console.log(`[package-smoke] ok ${basename(tarball)}`);
 } finally {
@@ -61,6 +108,17 @@ try {
   if (tarball) await rm(tarball, { force: true });
 }
 
+async function smokeStarter({ label, appName, initArgs, after, installRoot, tarball }) {
+  console.log(`[package-smoke] === ${label} starter ===`);
+  await run("npx", initArgs, {
+    cwd: installRoot,
+    env: { ...process.env, MADO_PACKAGE_SPEC: tarball },
+  });
+  const appRoot = join(installRoot, appName);
+  await run("npm", ["install"], { cwd: appRoot });
+  await after(appRoot);
+}
+
 async function run(cmd, args, options) {
   console.log(`[package-smoke] ${cmd} ${args.join(" ")}`);
   try {
@@ -74,4 +132,4 @@ async function run(cmd, args, options) {
     if (err.stderr) process.stderr.write(err.stderr);
     throw err;
   }
-}
+}

package/scripts/preview.mjs

@@ -9,7 +9,7 @@
 //      PREVIEW_AUTOBUILD=1.
 //   3. Starts a static server with:
 //        - immutable cache for hashed bundles;
-//        - SPA fallback to index.html;
+//        - SPA fallback to _mado/spa.html when present, else index.html;
 //        - exact `out/` route files before SPA fallback;
 //        - precompressed .gz / .br serving via Accept-Encoding.
 //
@@ -17,6 +17,7 @@
 // what a static host (nginx / Cloudflare Pages / S3) would serve.
 
 import { createServer } from "node:http";
+import { existsSync, readFileSync } from "node:fs";
 import { readFile, stat, access } from "node:fs/promises";
 import { extname, join, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -55,6 +56,68 @@ const HOST = String(PREVIEW_FLAGS.host ?? process.env.HOST ?? "localhost");
 const AUTOBUILD = process.env.PREVIEW_AUTOBUILD === "1";
 const SKIP_BUILD = process.env.SKIP_BUILD === "1" || !AUTOBUILD;
 
+// Active Vite base. We try the internal build bridge first (the
+// `@madojs/mado/vite` plugin writes `_mado/build.json` during `vite
+// build`); if `mado static` has already dropped that file before
+// shipping the production artifact, we fall back to parsing the asset
+// prefix out of `out/index.html`. Both paths converge on the same
+// canonical "/" or "/prefix/" form so the preview server replays the
+// real deployment URL shape regardless of pipeline stage.
+const BASE = detectDeployedBase(OUT);
+
+function detectDeployedBase(out) {
+  const fromBridge = readBridgeBase(out);
+  if (fromBridge != null) return fromBridge;
+  const fromHtml = readHtmlBase(out);
+  if (fromHtml != null) return fromHtml;
+  return "/";
+}
+
+function readBridgeBase(out) {
+  try {
+    const meta = JSON.parse(
+      readFileSync(join(out, "_mado/build.json"), "utf8"),
+    );
+    return meta?.base ? normalizeBase(meta.base) : null;
+  } catch {
+    return null;
+  }
+}
+
+function readHtmlBase(out) {
+  try {
+    const html = readFileSync(join(out, "index.html"), "utf8");
+    // Look at the first hashed asset; Vite always prefixes it with
+    // the deployed base.
+    const match = /(?:href|src)="(\/[^"]*?\/)assets\//.exec(html);
+    if (match && match[1]) return normalizeBase(match[1]);
+    // No prefix means root-deployed.
+    if (/(?:href|src)="\/assets\//.test(html)) return "/";
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeBase(raw) {
+  if (!raw) return "/";
+  let s = String(raw).trim();
+  if (!s || s === "/") return "/";
+  if (!s.startsWith("/")) s = "/" + s;
+  if (!s.endsWith("/")) s = s + "/";
+  return s.replace(/\/+/g, "/");
+}
+
+function stripBase(pathname) {
+  if (BASE === "/") return pathname.startsWith("/") ? pathname : "/" + pathname;
+  if (pathname === BASE || pathname === BASE.slice(0, -1)) return "/";
+  if (pathname.startsWith(BASE)) {
+    const rest = pathname.slice(BASE.length - 1);
+    return rest || "/";
+  }
+  return pathname;
+}
+
 const MIME = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -86,11 +149,13 @@ if (!(await exists(OUT))) {
   process.exit(1);
 }
 
-const spaShell = join(OUT, "index.html");
+const spaShell = existsSync(join(OUT, "_mado", "spa.html"))
+  ? join(OUT, "_mado", "spa.html")
+  : join(OUT, "index.html");
 if (!(await exists(spaShell))) {
   console.error(
     `[preview] missing ${spaShell} — \`mado release\` did not produce an HTML entry.\n` +
-      `[preview] Without it any non-baked route will 404 instead of falling back to the SPA.`,
+      `[preview] Without it any non-static route will 404 instead of falling back to the SPA.`,
   );
   process.exit(1);
 }
@@ -103,7 +168,24 @@ const isImmutable = (filename) =>
 const server = createServer(async (req, res) => {
   try {
     const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
-    const pathname = decodeURIComponent(url.pathname);
+    const fullPathname = decodeURIComponent(url.pathname);
+    // Honour the deployed Vite base: redirect bare `/` to `/${base}/` and
+    // strip the prefix before any lookup, so `out/index.html`,
+    // `out/assets/...` and `out/docs/index.html` are reachable through
+    // the same URL shape the CDN serves.
+    if (BASE !== "/") {
+      const bareBase = BASE.slice(0, -1);
+      if (fullPathname === "/" || fullPathname === bareBase) {
+        res.writeHead(302, { location: BASE });
+        res.end();
+        return;
+      }
+      if (!fullPathname.startsWith(BASE) && fullPathname !== bareBase) {
+        res.writeHead(404).end("not found");
+        return;
+      }
+    }
+    const pathname = stripBase(fullPathname);
     const accepts = (req.headers["accept-encoding"] ?? "").toString();
 
     const target = await resolveTarget(pathname);
@@ -158,7 +240,12 @@ server.listen(PORT, HOST, async () => {
   const urlHost = HOST === "0.0.0.0" || HOST === "::" ? "localhost" : HOST;
   console.log("");
   console.log("Mado preview (production-like)");
-  console.log(`  url:    http://${urlHost}:${PORT}/`);
+  // Print the URL the server actually serves the app at. When the
+  // deployment uses a non-trivial Vite `base`, the bare root just
+  // 302-redirects to the base prefix, which surprises users who copy
+  // the logged URL into a browser and land on "Not Found".
+  console.log(`  url:    http://${urlHost}:${PORT}${BASE}`);
+  console.log(`  base:   ${BASE}`);
   console.log(`  out:    ${OUT}`);
   console.log("  (Ctrl-C to stop)");
   console.log("");
@@ -216,7 +303,9 @@ async function resolveTarget(pathname) {
   //    extension) deliberately 404 instead — otherwise a 200 on
   //    /missing.png would mask real bugs.
   if (!extname(pathname)) {
-    const spa = join(OUT, "index.html");
+    const spa = existsSync(join(OUT, "_mado", "spa.html"))
+      ? join(OUT, "_mado", "spa.html")
+      : join(OUT, "index.html");
     if (await exists(spa)) return spa;
   }
 

package/scripts/size-budget.mjs

@@ -8,7 +8,11 @@ import { gzipSync } from "node:zlib";
 
 const API_ENTRY = "src/index.ts";
 const SAMPLE_ENTRY = "starters/default/src/main.ts";
-const API_GZIP_LIMIT = readLimit("MADO_SIZE_API_GZIP_LIMIT", 16 * 1024);
+// Public API budget bumped from 16 KiB → 17 KiB to accommodate the
+// base-aware router/navigation pack added in 0.12.0 (`src/router/base.ts`,
+// stripBase/withBase wiring in navigation, manifest and static-runtime).
+// Override per-environment via MADO_SIZE_API_GZIP_LIMIT.
+const API_GZIP_LIMIT = readLimit("MADO_SIZE_API_GZIP_LIMIT", 17 * 1024);
 const SAMPLE_GZIP_LIMIT = readLimit("MADO_SIZE_SAMPLE_GZIP_LIMIT", 42 * 1024);
 
 let failed = false;