@madojs/mado 0.12.0 → 0.13.0

package/docs/en/40-llm-guide.md

@@ -279,16 +279,15 @@ This means:
 // ❌ No such API
 const f = useForm({ resolver: zodResolver(schema) });
 
-// ✅ HTML-style schema validation
+// ✅ Native constraints in markup, reactive state in Mado
 const f = useForm({
-  email: { required: true, type: "email" },
-  age: { required: true, type: "number", min: 18 },
+  initial: { email: "", age: "" as number | "" },
 });
+html`<input name="email" type="email" required @input=${f.onInput} />`;
 
 // ✅ Or a custom function when HTML5 isn't enough
-const f = useForm(
-  { name: { required: true } },
-  {
+const f = useForm({
+    initial: { name: "" },
     validate: (values) => {
       const errors: Record<string, string> = {};
       if (values.name && /\d/.test(values.name as string)) {
@@ -296,8 +295,7 @@ const f = useForm(
       }
       return Object.keys(errors).length ? errors : null;
     },
-  },
-);
+});
 ```
 
 ---
@@ -705,7 +703,7 @@ automatically on navigation. Only raw browser APIs need explicit
 | `useRouter().query.q`                 | `queryParam('q')`                            |
 | `<input value={v} onChange={...}>`    | `<input .value=${v} @input=${...}>`          |
 | `{items.map(x => ...)}`               | `${() => each(items, x => x.id, x => ...)}`  |
-| `useForm({ resolver: zodResolver })`  | `useForm({...}, { validate: (v) => ... })`   |
+| `useForm({ resolver: zodResolver })`  | `useForm({ initial, validate })` + native constraints |
 | `class extends HTMLElement`           | `component('x-name', setup)`                 |
 | `@customElement('x')`                 | `component('x-name', setup)`                 |
 | `host.getAttribute('x')` in render    | `ctx.attr('x', default)` (reactive)          |

package/docs/en/41-for-backenders.md

@@ -195,14 +195,13 @@ We register the `<x-counter>` tag in the browser — it becomes a "function" tha
 
 ## Forms — like `form.Validate()` on the backend
 
-Mado uses **schema-based validation close to native HTML constraints**, plus adds state tracking.
+Mado uses the browser's **constraint validation** and adds reactive state tracking.
 
 ```ts
 import { useForm } from "@madojs/mado";
 
 const f = useForm({
-  email: { required: true, type: "email" },
-  age: { required: true, type: "number", min: 18 },
+  initial: { email: "", age: "" as number | "" },
 });
 
 // in the template:
@@ -215,6 +214,8 @@ html`
   >
     <input
       name="email"
+      type="email"
+      required
       .value=${() => f.values().email ?? ""}
       @input=${f.onInput}
       @blur=${f.onBlur}
@@ -225,12 +226,13 @@ html`
         ? html`<small>${f.errors().email}</small>`
         : null}
 
-    <button ?disabled=${() => !f.isValid() || f.submitting()}>Save</button>
+    <input name="age" type="number" min="18" @input=${f.onInput} />
+    <button type="submit" ?disabled=${() => !f.isValid() || f.submitting()}>Save</button>
   </form>
 `;
 ```
 
-Custom validation — `validate: (values) => errors | null`. No Yup schemas or dependencies.
+Custom validation — `validate: (values, { signal }) => errors | null`. No Yup schemas or dependencies.
 
 ---
 
@@ -258,6 +260,8 @@ component("x-page", ({ host }) => {
 ```
 
 This is like `context.WithValue` / `ctx.Value` in Go, but reactive.
+The transport is the interoperable Web Components `context-request` event, so
+providers and consumers can cross library boundaries.
 
 ---
 
@@ -335,7 +339,7 @@ const createUser = mutation<NewUser, User>(
 );
 
 // in page.view:
-const f = useForm({ name: { required: true } });
+const f = useForm({ initial: { name: "" } });
 
 html`
   <form
@@ -344,8 +348,8 @@ html`
       navigate("/users");
     })}
   >
-    <input name="name" @input=${f.onInput} />
-    <button>Create</button>
+    <input name="name" required @input=${f.onInput} />
+    <button type="submit">Create</button>
   </form>
 `;
 ```
@@ -426,7 +430,7 @@ Everything else — standard browser + TypeScript.
 
 ## What's missing (honestly)
 
-- No browser extension dev-tools. Use `localStorage.madoDebug = '1'` + console.
+- The built-in overlay covers runtime inspection; a browser extension remains post-v1 work.
 - No StackBlitz starters (yet).
 - No AI assistant that knows Mado as well as React. When in doubt — read `src/`, it's not scary.
 

package/docs/en/42-why-mado.md

@@ -138,7 +138,7 @@ I won't dwell on this for long, because React is in a **different weight class**
 **Mado wins:**
 
 - bundle size dozens of times smaller;
-- zero infrastructure (no Vite, no Babel, no 200 packages);
+- one conventional Vite transport without a framework compiler or Babel layer;
 - readable in an evening — if something breaks, open `src/`;
 - signals instead of hooks (no "can't use in an if" rules, no stale-closure traps);
 - no need to migrate between major versions.
@@ -194,7 +194,7 @@ This is sufficient for most applications. If you're building Excel in the browse
 Mado is a **narrow** tool with honest positioning. It is strongest where:
 
 1. You want to **own** the code and read it in its entirety.
-2. **Infrastructure simplicity** is critical (no Vite/Webpack/Babel).
+2. **Infrastructure simplicity** is critical (one Vite transport, no custom compiler).
 3. You need **batteries in one box** (router + data + forms + SEO).
 4. You are not a junior and are not afraid of Web Components.
 

package/docs/en/README.md

@@ -47,6 +47,7 @@ section you need from the matrix below.
 | Error handling     | [21-error-handling.md](./21-error-handling.md) |
 | Testing            | [22-testing.md](./22-testing.md)               |
 | Cookbook           | [23-cookbook.md](./23-cookbook.md)             |
+| Devtools and diagnostics | [24-devtools-and-diagnostics.md](./24-devtools-and-diagnostics.md) |
 
 ### Reference
 
@@ -55,6 +56,7 @@ section you need from the matrix below.
 | API freeze map         | [30-api-freeze-map.md](./30-api-freeze-map.md)             |
 | Reactivity ordering    | [31-reactivity-ordering.md](./31-reactivity-ordering.md)   |
 | v1 stability contract  | [32-v1-stability.md](./32-v1-stability.md)                 |
+| Migration 0.12 → 0.13  | [33-migration-0.12-0.13.md](./33-migration-0.12-0.13.md)   |
 
 ### Meta
 

package/docs/recipes/nginx/nginx.conf

@@ -4,7 +4,7 @@
 #   - Vite hashed assets from /assets/ with immutable caching;
 #   - precompressed .gz files written by `mado release`;
 #   - baked route HTML when present;
-#   - index.html as SPA fallback for client-only routes.
+#   - _mado/spa.html as the noindex SPA fallback for client-only routes.
 
 server {
     listen 80;
@@ -37,6 +37,6 @@ server {
 
     location / {
         add_header Cache-Control "no-cache, must-revalidate";
-        try_files $uri $uri/ /index.html;
+        try_files $uri $uri/ /_mado/spa.html;
     }
 }

package/llms.txt

@@ -84,7 +84,7 @@ import {
   // reactivity
   signal, computed, effect, untracked, batch, flushSync,
   // rendering + templates
-  html, render, each, list, unsafeHTML, ref, classMap, styleMap,
+  html, render, unmount, each, unsafeHTML, ref, classMap, styleMap,
   // components
   component, css, cssVars,
   // routing
@@ -94,14 +94,14 @@ import {
   page, layout, applyHead,
   // data
   resource, mutation, invalidate, jsonFetcher, HttpError,
-  // forms / context / persistence / lazy
+  // forms / context / persistence
   useForm,
   createContext, provide, inject,
-  persisted, lazy,
+  persisted,
 } from "@madojs/mado";
 
-// Side-effect-only:
-import "@madojs/mado/devtools.js";
+// Development overlay/controller:
+import { devtools } from "@madojs/mado/devtools.js";
 
 // Vite plugin:
 import { mado } from "@madojs/mado/vite";
@@ -110,6 +110,10 @@ import { mado } from "@madojs/mado/vite";
 Everything else under the package is internal and subject to change
 without notice (see `docs/en/30-api-freeze-map.md`).
 
+`page.load` is synchronous: return a plain value or `Resource`, never a
+Promise. Async work belongs in `resource()` so navigation can commit or roll
+back lifecycle ownership transactionally.
+
 ## Pages and the static snapshot pipeline
 
 A page declares its participation in static capture through the
@@ -219,11 +223,25 @@ const create = mutation((u) => api.create(u), {
 });
 ```
 
-The key is cache identity: same key → shared cache and de-duped
-in-flight request. `mutation().run()` is concurrent by default;
+Cache identity is the key plus fetcher. `staleTime: 0` only de-dupes an
+in-flight request; positive values expire automatically. `mutation().run()` is concurrent by default;
 `{ abortPrevious: true }` keeps only the latest in flight.
 `invalidates` runs after a successful mutation and is best-effort.
 
+## Forms
+
+```ts
+const form = useForm({ initial: { email: "" } });
+html`<form @submit=${form.onSubmit(save)}>
+  <input name="email" type="email" required @input=${form.onInput} />
+  <button type="submit">Save</button>
+</form>`;
+```
+
+Native constraints and `ValidityState` are authoritative. Custom async
+validation is `validate(values, { signal, form })`; reset aborts it. Use native
+controls for checkbox/radio groups, multiple select, files and keyboard submit.
+
 ## Static snapshot constraints
 
 - `paths()` and `initialData()` run during discovery AND ship in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madojs/mado",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "A calm native-first web framework for sites and apps. Web Components, signals, routing, data, forms and browser-rendered static snapshots. Zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
@@ -29,7 +29,6 @@
     "mado": "./scripts/cli.mjs"
   },
   "main": "./dist/src/index.js",
-  "module": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "exports": {
     ".": {
@@ -47,8 +46,16 @@
   },
   "files": [
     "dist/src",
-    "scripts",
-    "templates",
+    "scripts/cli.mjs",
+    "scripts/_config.mjs",
+    "scripts/clean.mjs",
+    "scripts/logger.mjs",
+    "scripts/output-guard.mjs",
+    "scripts/preview.mjs",
+    "scripts/static.mjs",
+    "scripts/vite.default.mjs",
+    "scripts/cli",
+    "scripts/static",
     "starters",
     "README.md",
     "LICENSE",
@@ -60,6 +67,14 @@
     "docs/architecture/**/*.md",
     "docs/recipes/**/*"
   ],
+  "sideEffects": [
+    "./dist/src/devtools.js"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "npm@11.16.0",
   "scripts": {
     "build": "node scripts/cli.mjs build",
     "watch": "node scripts/cli.mjs watch",
@@ -69,23 +84,26 @@
     "new": "node scripts/cli.mjs new",
     "size": "node scripts/size-budget.mjs",
     "package:smoke": "node scripts/package-smoke.mjs",
-    "docs:lint": "node scripts/docs-lint.mjs",
+    "docs:lint": "node scripts/docs-lint.mjs && node node_modules/typescript/bin/tsc --noEmit -p tsconfig.docs.json",
+    "api:check": "node scripts/api-check.mjs",
+    "benchmark:static": "node scripts/benchmark-static.mjs",
     "test": "node scripts/cli.mjs test",
     "typecheck": "node scripts/cli.mjs typecheck",
-    "clean": "rm -rf dist out",
-    "prepublishOnly": "npm run clean && npm run build && npm test"
+    "clean": "node scripts/clean.mjs",
+    "verify:release": "npm run clean && npm test && npm run docs:lint && npm run api:check && npm run size && npm run package:smoke && npm audit --audit-level=high",
+    "prepack": "node scripts/clean.mjs --dist-only && npm run build",
+    "prepublishOnly": "npm run verify:release"
   },
   "devDependencies": {
-    "@types/node": "^20.19.0",
-    "esbuild": "^0.28.0",
-    "lightningcss": "^1.32.0",
-    "linkedom": "^0.18.12",
-    "playwright-core": "^1.47.0",
-    "typescript": "^6.0.3",
-    "vite": "^8.0.16"
+    "@types/node": "^22.12.0",
+    "esbuild": "^0.28.1",
+    "linkedom": "^0.18.13",
+    "playwright-core": "^1.61.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.1.4"
   },
   "peerDependencies": {
-    "playwright-core": "^1.47.0",
+    "playwright-core": "^1.61.1",
     "vite": "^8.0.0"
   },
   "peerDependenciesMeta": {
@@ -97,6 +115,9 @@
     }
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12"
+  },
+  "allowScripts": {
+    "esbuild@0.28.1": true
   }
 }

package/scripts/clean.mjs

@@ -0,0 +1,8 @@
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const root = resolve(import.meta.dirname, "..");
+const targets = process.argv.includes("--dist-only") ? ["dist"] : ["dist", "out"];
+for (const target of targets) {
+  await rm(resolve(root, target), { recursive: true, force: true });
+}

package/scripts/cli/generate.mjs

@@ -2,6 +2,8 @@ import { existsSync } from "node:fs";
 import { access, mkdir, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 
+import { logger } from "../logger.mjs";
+
 const KINDS = [
   "module",
   "page",
@@ -52,15 +54,8 @@ export async function runNew(ctx, args) {
 
   const shape = detectStarterShape(ctx);
   if (shape === "universal" && MODULAR_ONLY.has(kind)) {
-    console.error(
-      `[mado] '${kind}' is a modular-starter generator and is not ` +
-        "available in the universal starter.",
-    );
-    console.error(
-      "[mado] Either move this project to the modular layout " +
-        "(create src/modules/<name>/) or scaffold a fresh modular " +
-        "project with: mado init my-app --starter modular",
-    );
+    logger.error("mado", "generator-shape", `'${kind}' is not available in the universal starter`);
+    logger.info("mado", "generator-hint", "Create src/modules/<name>/ or run: mado init my-app --starter modular");
     process.exit(1);
   }
 
@@ -78,8 +73,8 @@ export async function runNew(ctx, args) {
 
   const fn = generators[kind];
   if (!fn) {
-    console.error(`[mado] unknown generator: ${kind}`);
-    console.error(`[mado] available generators: ${KINDS.join(", ")}`);
+    logger.error("mado", "unknown-generator", `unknown generator: ${kind}`);
+    logger.info("mado", "available-generators", `available generators: ${KINDS.join(", ")}`);
     process.exit(1);
   }
 
@@ -266,7 +261,9 @@ async function scaffoldForm(ctx, target) {
 // Call inside a page view: const form = ${useName}();
 export const ${useName} = () =>
   useForm({
-    // name: { required: true },
+    initial: {
+      // name: "",
+    },
   });
 `,
   );
@@ -350,7 +347,7 @@ function moduleFile(ctx, target, suffix) {
 
 async function writeOnce(path, content) {
   if (await exists(path)) {
-    console.error(`[mado] file already exists: ${path}`);
+    logger.error("mado", "file-exists", `file already exists: ${path}`);
     process.exit(2);
   }
   await mkdir(dirname(path), { recursive: true });
@@ -383,7 +380,7 @@ function leafName(target) {
 
 function assertSingleSegment(label, name) {
   if (name.includes("/")) {
-    console.error(`[mado] ${label.toLowerCase()} name must be a single path segment`);
+    logger.error("mado", "invalid-name", `${label.toLowerCase()} name must be a single path segment`);
     process.exit(1);
   }
 }

package/scripts/cli/help.mjs

@@ -28,6 +28,8 @@ ${buildLine}
   Configuration:
     Put app/dev/build settings in vite.config.ts.
     Mado CLI flags are explicit per command.
+    --log-level debug|info|warn|error|silent
+    --log-format pretty|plain|json   --no-color
 
   Docs: README.md and docs/en/README.md.`);
 }

package/scripts/cli/index.mjs

@@ -1,8 +1,9 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { detectContext } from "../_config.mjs";
+import { configureLogger, logger } from "../logger.mjs";
 import { runInit } from "./init.mjs";
 import { runNew } from "./generate.mjs";
 import { printHelp } from "./help.mjs";
@@ -12,6 +13,7 @@ import { hasFlag, listTestFiles, run, runNodeBin, runNodeScript, runVite } from
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 
 export async function main(argv) {
+  argv = configureLogger(argv);
   const projectRoot = resolve(process.cwd());
   const context = detectContext(projectRoot);
   const packageJson = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
@@ -37,7 +39,8 @@ export async function main(argv) {
       if (ctx.isRepo) {
         await runNodeBin(ctx, "typescript/bin/tsc", args);
       } else {
-        await runVite(ctx, ["build", ...args], { defaultConfig: true });
+        const outputArgs = hasFlag(args, "--outDir") ? args : ["--outDir", "out", ...args];
+        await runVite(ctx, ["build", ...outputArgs], { defaultConfig: true });
       }
       break;
     case "watch":
@@ -47,9 +50,14 @@ export async function main(argv) {
         await runVite(ctx, ["build", "--watch", ...args], { defaultConfig: true });
       }
       break;
-    case "typecheck":
+    case "typecheck": {
       await runNodeBin(ctx, "typescript/bin/tsc", ["--noEmit", ...args]);
+      const nodeConfig = join(ctx.projectRoot, "tsconfig.node.json");
+      if (existsSync(nodeConfig) && !hasFlag(args, "--project", "-p")) {
+        await runNodeBin(ctx, "typescript/bin/tsc", ["--noEmit", "-p", nodeConfig]);
+      }
       break;
+    }
     case "test": {
       await runNodeBin(ctx, "typescript/bin/tsc", []);
       const files = await listTestFiles(projectRoot);
@@ -66,8 +74,8 @@ export async function main(argv) {
       );
       break;
     case "bake":
-      console.error("[mado] `mado bake` was removed.");
-      console.error("Use `mado static`, or run the complete pipeline with `mado release`.");
+      logger.error("mado", "command-removed", "`mado bake` was removed.");
+      logger.info("mado", "replacement", "Use `mado static`, or run the complete pipeline with `mado release`.");
       process.exit(1);
       break;
     case "static":
@@ -88,7 +96,7 @@ export async function main(argv) {
       printHelp(ctx);
       break;
     default:
-      console.error(`[mado] unknown command: ${command}`);
+      logger.error("mado", "unknown-command", `unknown command: ${command}`);
       printHelp(ctx);
       process.exit(1);
   }

package/scripts/cli/init.mjs

@@ -3,6 +3,7 @@ import { copyFile, cp, mkdir, readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 
 import { parseFlags } from "../_config.mjs";
+import { logger } from "../logger.mjs";
 
 // `default` is the universal starter: minimal, runnable, zero backend.
 // `modular` is the long-lived business-app reference architecture:
@@ -15,30 +16,30 @@ export async function runInit(ctx, rawArgs) {
   const { flags, positional } = parseFlags(rawArgs);
   const targetArg = positional[0];
   if (!targetArg) {
-    console.error("[mado] usage: mado init <name> [--starter default] [--force]");
+    logger.error("mado", "usage", "usage: mado init <name> [--starter default] [--force]");
     process.exit(1);
   }
 
   const starter = String(flags.starter ?? "default");
   if (!STARTERS.includes(starter)) {
-    console.error(`[mado] unknown starter: ${starter}`);
-    console.error(`[mado] available starters: ${STARTERS.join(", ")}`);
+    logger.error("mado", "unknown-starter", `unknown starter: ${starter}`);
+    logger.info("mado", "available-starters", `available starters: ${STARTERS.join(", ")}`);
     process.exit(1);
   }
 
   const target = resolve(ctx.projectRoot, targetArg);
   const source = join(ctx.packageRoot, "starters", starter);
   if (!existsSync(source)) {
-    console.error(`[mado] missing starter template: ${starter}`);
+    logger.error("mado", "missing-starter", `missing starter template: ${starter}`);
     process.exit(1);
   }
   if (existsSync(target) && statSync(target).isFile()) {
-    console.error(`[mado] target exists and is a file: ${target}`);
+    logger.error("mado", "target-is-file", `target exists and is a file: ${target}`);
     process.exit(1);
   }
   if (existsSync(target) && readdirSync(target).length > 0 && !flags.force) {
-    console.error(`[mado] target directory is not empty: ${target}`);
-    console.error("[mado] use --force to write into it");
+    logger.error("mado", "target-not-empty", `target directory is not empty: ${target}`);
+    logger.info("mado", "force-hint", "use --force to write into it");
     process.exit(1);
   }
 
@@ -50,7 +51,7 @@ export async function runInit(ctx, rawArgs) {
 
   const packageName = packageNameFromDir(target);
   if (!isValidPackageName(packageName)) {
-    console.error(`[mado] invalid package name derived from target: ${packageName}`);
+    logger.error("mado", "invalid-package-name", `invalid package name derived from target: ${packageName}`);
     process.exit(1);
   }
 
@@ -95,7 +96,10 @@ async function copyCanonicalLLMFiles(ctx, target) {
 async function ensureStarterGitignore(target) {
   const file = join(target, ".gitignore");
   if (existsSync(file)) return;
-  await writeFile(file, "node_modules\nout\n.DS_Store\n*.log\n");
+  await writeFile(
+    file,
+    "node_modules\ndist\nout\n.cache\n.env\n.env.*\n!.env.example\n.DS_Store\n*.log\n",
+  );
 }
 
 async function ensureStarterPackageJson(ctx, target) {
@@ -110,15 +114,6 @@ async function ensureStarterPackageJson(ctx, target) {
       process.env.MADOJS_PACKAGE_SPEC ||
       `^${ctx.packageJson.version}`,
   };
-  const rootDev = ctx.packageJson.devDependencies ?? {};
-  pkg.devDependencies = {
-    ...(pkg.devDependencies ?? {}),
-    typescript: rootDev.typescript ?? "^6.0.3",
-    lightningcss: rootDev.lightningcss ?? "^1.32.0",
-    "playwright-core": rootDev["playwright-core"] ?? "^1.47.0",
-    vite: rootDev.vite ?? "^8.0.16",
-  };
-
   await writeFile(file, `${JSON.stringify(pkg, null, 2)}\n`);
 }
 

package/scripts/cli/release.mjs

@@ -1,9 +1,11 @@
 import { existsSync } from "node:fs";
-import { readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { readdir, readFile, 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";
+import { logger } from "../logger.mjs";
+import { prepareOutputDirectory } from "../output-guard.mjs";
 import { runNodeBin, runNodeScript, runVite, writeIfMissing } from "./run.mjs";
 
 export async function runRelease(ctx, rawArgs) {
@@ -13,33 +15,35 @@ export async function runRelease(ctx, rawArgs) {
     typeof releaseFlags.out === "string" ? releaseFlags.out : "out",
   );
 
-  console.log(`[release] context: ${ctx.context}`);
-  console.log(`[release] artifact: ${outDir}`);
-  console.log("");
+  logger.info("release", "context", `context: ${ctx.context}`);
+  logger.info("release", "artifact", `artifact: ${outDir}`);
 
-  if (!releaseFlags["no-clean"]) {
-    if (existsSync(outDir)) {
-      await rm(outDir, { recursive: true, force: true });
-      console.log(`[release] cleaned ${outDir}`);
-    }
+  await prepareOutputDirectory({
+    projectRoot: ctx.projectRoot,
+    outDir,
+    clean: !releaseFlags["no-clean"],
+    force: releaseFlags["force-output"] === true,
+  });
+  if (releaseFlags["no-clean"]) {
+    logger.info("release", "clean-skip", "--no-clean: keeping existing out/");
   } else {
-    console.log("[release] --no-clean: keeping existing out/");
+    logger.info("release", "clean", `prepared ${outDir}`);
   }
 
-  console.log("[release] step 1/5  typecheck");
+  logger.info("release", "step", "step 1/5  typecheck");
   await runNodeBin(ctx, "typescript/bin/tsc", ["--noEmit"]);
 
-  console.log("[release] step 2/5  vite build");
+  logger.info("release", "step", "step 2/5  vite build");
   await runVite(ctx, ["build", "--outDir", outDir], { defaultConfig: true });
 
-  console.log("[release] step 3/5  static snapshots");
+  logger.info("release", "step", "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");
+  logger.info("release", "step", "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).
@@ -61,12 +65,11 @@ export async function runRelease(ctx, rawArgs) {
     "[release]  ",
   );
 
-  console.log("[release] step 5/5  precompress assets");
+  logger.info("release", "step", "step 5/5  precompress assets");
   await precompressOut(outDir);
 
-  console.log("");
-  console.log(`[release] done. Deploy artifact: ${outDir}`);
-  console.log("[release] try:  mado preview");
+  logger.info("release", "done", `done. Deploy artifact: ${outDir}`);
+  logger.info("release", "next", "try: mado preview");
 }
 
 async function precompressOut(outDir) {
@@ -84,7 +87,7 @@ async function precompressOut(outDir) {
     );
     count++;
   }
-  console.log(`[release]   compressed ${count} file(s)`);
+  logger.info("release", "compress", `compressed ${count} file(s)`);
 }
 
 async function listCompressibleFiles(dir) {