@madojs/mado 0.6.0 → 0.7.0

package/scripts/cli.mjs

@@ -53,10 +53,10 @@ switch (command) {
     }
     break;
   case "serve":
-    await runServe(args[0] ?? "");
+    await runServe(args);
     break;
   case "dev":
-    await runDev(args[0] ?? "");
+    await runDev(args);
     break;
   case "bake":
     await runNodeScript("scripts/bake.mjs", args);
@@ -87,15 +87,26 @@ switch (command) {
     process.exit(1);
 }
 
-async function runServe(example) {
-  if (!example && PROJECT_ROOT !== PACKAGE_ROOT) {
-    await serveStaticProject(PROJECT_ROOT);
-    return;
-  }
+async function runServe(rawArgs) {
+  // Split args into [example?, ...flags]. The first non-flag positional is the
+  // example name; everything else (including `--host`, `--port`, etc.) is
+  // forwarded verbatim to server/serve.mjs.
+  const { example, forwarded } = splitDevArgs(rawArgs);
   if (example) assertExample(example, { serveable: true });
-  await run(process.execPath, [join(PACKAGE_ROOT, "server/serve.mjs"), example].filter(Boolean), {
-    env: { ...process.env, EXAMPLE: example || process.env.EXAMPLE || "" },
-  });
+
+  // In app-mode (generated project, no example argument) we also go through
+  // server/serve.mjs to get config support (--host, --port, mado.config.json
+  // dev.proxy, HMR, etc.) — previously this fell back to serveStaticProject()
+  // which only read PORT from env and had no proxy/config/HMR.
+  await run(
+    process.execPath,
+    [join(PACKAGE_ROOT, "server/serve.mjs"), example, ...forwarded].filter(
+      Boolean,
+    ),
+    {
+      env: { ...process.env, EXAMPLE: example || process.env.EXAMPLE || "" },
+    },
+  );
 }
 
 async function runInit(rawArgs) {
@@ -168,15 +179,25 @@ async function runInit(rawArgs) {
   console.log("");
 }
 
-async function runDev(example) {
+async function runDev(rawArgs) {
+  // Forward unknown flags (e.g. --host, --port) to server/serve.mjs so callers
+  // can write `mado dev --host 127.0.0.1` without the CLI mistaking `--host`
+  // for an example name.
+  const { example, forwarded } = splitDevArgs(rawArgs);
   if (example) assertExample(example, { serveable: true });
 
   const env = { ...process.env, EXAMPLE: example || process.env.EXAMPLE || "" };
-  const server = spawn(process.execPath, [join(PACKAGE_ROOT, "server/serve.mjs"), example].filter(Boolean), {
-    cwd: PROJECT_ROOT,
-    env,
-    stdio: "inherit",
-  });
+  const server = spawn(
+    process.execPath,
+    [join(PACKAGE_ROOT, "server/serve.mjs"), example, ...forwarded].filter(
+      Boolean,
+    ),
+    {
+      cwd: PROJECT_ROOT,
+      env,
+      stdio: "inherit",
+    },
+  );
   const tsc = spawn(process.execPath, [resolveBin("typescript/bin/tsc"), "-w"], {
     cwd: PROJECT_ROOT,
     stdio: "inherit",
@@ -215,7 +236,8 @@ async function runRelease(rawArgs) {
   // have to remember the order, and so the deploy artifact (out/) is always
   // assembled the same way.
   //
-  //   mado release
+  //   mado release [--no-clean]
+  //     → rm -rf out/        (unless --no-clean)
   //     → mado typecheck
   //     → mado build       (tsc → dist/)
   //     → mado bundle      (esbuild → out/assets/, also copies index.html)
@@ -223,6 +245,7 @@ async function runRelease(rawArgs) {
   //     → copy public/* → out/
   //
   // 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 publicDir = resolve(cfg.projectRoot, cfg.build.publicDir ?? "public");
@@ -231,6 +254,18 @@ async function runRelease(rawArgs) {
   console.log(`[release] artifact: ${outDir}`);
   console.log("");
 
+  // Deterministic builds: remove the entire output directory so stale assets,
+  // removed bake routes, and deleted public files don't linger in the deploy
+  // artifact. Use --no-clean to opt out (e.g. incremental CI workflows).
+  if (!releaseFlags["no-clean"]) {
+    if (existsSync(outDir)) {
+      await rm(outDir, { recursive: true, force: true });
+      console.log(`[release] cleaned ${outDir}`);
+    }
+  } else {
+    console.log("[release] --no-clean: keeping existing out/");
+  }
+
   console.log("[release] step 1/5  typecheck");
   await runNodeBin("typescript/bin/tsc", ["--noEmit"]);
 
@@ -411,6 +446,50 @@ function parseFlags(raw) {
   return { flags, positional };
 }
 
+/**
+ * Split args for `mado dev` / `mado serve` into:
+ *   - example: the first non-flag positional (or undefined)
+ *   - forwarded: every remaining token (flags, their values, leftover
+ *     positionals), preserved in order so server/serve.mjs sees them
+ *     unchanged.
+ *
+ * This is what lets `mado dev -- --host 127.0.0.1` and
+ * `mado dev showcase --port 6000` both work without the CLI confusing
+ * `--host` for an example name.
+ */
+function splitDevArgs(raw) {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return { example: "", forwarded: [] };
+  }
+  let example = "";
+  const forwarded = [];
+  let pickedExample = false;
+  for (let i = 0; i < raw.length; i++) {
+    const a = raw[i];
+    if (a === "--") {
+      forwarded.push(...raw.slice(i + 1));
+      break;
+    }
+    if (a.startsWith("-")) {
+      forwarded.push(a);
+      // Lookahead: if the next token is the flag's VALUE (does not start with
+      // "-"), forward it too — but only when the flag is in inline form
+      // (--flag value), not --flag=value.
+      if (!a.includes("=") && raw[i + 1] !== undefined && !raw[i + 1].startsWith("-")) {
+        forwarded.push(raw[++i]);
+      }
+      continue;
+    }
+    if (!pickedExample) {
+      example = a;
+      pickedExample = true;
+    } else {
+      forwarded.push(a);
+    }
+  }
+  return { example, forwarded };
+}
+
 function packageNameFromDir(target) {
   return target
     .split(/[\\/]/)
@@ -463,31 +542,5 @@ function contentType(file) {
   }[ext] ?? "application/octet-stream";
 }
 
-async function serveStaticProject(rootDir) {
-  const port = Number(process.env.PORT || 5173);
-  const server = http.createServer((req, res) => {
-    const url = new URL(req.url || "/", `http://localhost:${port}`);
-    const pathname = decodeURIComponent(url.pathname);
-    const normalized = pathname.replace(/^\/+/, "");
-    let file = resolve(rootDir, normalized);
-    if (pathname === "/" || !normalized.includes(".")) file = join(rootDir, "index.html");
-    if (!file.startsWith(rootDir) || !existsSync(file) || statSync(file).isDirectory()) {
-      file = join(rootDir, "index.html");
-    }
-
-    if (!existsSync(file)) {
-      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
-      res.end("Not found");
-      return;
-    }
-
-    res.writeHead(200, { "content-type": contentType(file) });
-    res.end(readFileSync(file));
-  });
-
-  await new Promise((resolveListen) => {
-    server.listen(port, resolveListen);
-  });
-  console.log(`[mado] serving ${rootDir}`);
-  console.log(`[mado] http://localhost:${port}`);
-}
+// serveStaticProject removed in v0.7 — mado serve now always goes through
+// server/serve.mjs to get --host, --port, dev.proxy, and HMR support.

package/scripts/preview.mjs

@@ -24,13 +24,49 @@ import { spawnSync } from "node:child_process";
 
 import { loadConfig } from "./_config.mjs";
 
+// Tiny argv parser. Supports --flag, --flag=value, --flag value.
+function parsePreviewArgs(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") continue;
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq >= 0) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const name = a.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("-")) {
+          flags[name] = next;
+          i++;
+        } else {
+          flags[name] = true;
+        }
+      }
+    }
+  }
+  return flags;
+}
+
+const PREVIEW_FLAGS = parsePreviewArgs(process.argv.slice(2));
+
 const cfg = loadConfig({});
 const ROOT = cfg.projectRoot;
 const OUT = resolve(
   ROOT,
   process.env.OUT_DIR ?? cfg.build.out ?? "out",
 );
-const PORT = Number(process.env.PORT ?? cfg.dev?.port ?? 4173);
+// 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>.
+const BAKED = resolve(
+  ROOT,
+  process.env.BAKED_DIR ?? cfg.bake?.outDir ?? join(cfg.build.out ?? "out", "baked"),
+);
+const PORT = Number(PREVIEW_FLAGS.port ?? process.env.PORT ?? cfg.dev?.port ?? 4173);
+const HOST = String(PREVIEW_FLAGS.host ?? process.env.HOST ?? cfg.dev?.host ?? "localhost");
 const AUTOBUILD = process.env.PREVIEW_AUTOBUILD === "1";
 const SKIP_BUILD = process.env.SKIP_BUILD === "1" || !AUTOBUILD;
 
@@ -66,7 +102,18 @@ if (!SKIP_BUILD) {
 }
 
 if (!(await exists(OUT))) {
-  console.error(`[preview] missing ${OUT}/ — check the steps above`);
+  console.error(
+    `[preview] missing ${OUT}/ — run \`mado release\` (or \`mado bundle\`) first.`,
+  );
+  process.exit(1);
+}
+
+const spaShell = join(OUT, "index.html");
+if (!(await exists(spaShell))) {
+  console.error(
+    `[preview] missing ${spaShell} — \`mado bundle\` did not produce an HTML entry.\n` +
+      `[preview] Without it any non-baked route will 404 instead of falling back to the SPA.`,
+  );
   process.exit(1);
 }
 
@@ -114,8 +161,31 @@ const server = createServer(async (req, res) => {
   }
 });
 
-server.listen(PORT, () => {
-  console.log(`\n[preview] http://localhost:${PORT}/  (Ctrl-C — stop)\n`);
+server.on("error", (err) => {
+  if (err.code === "EPERM" || err.code === "EACCES") {
+    console.error(
+      `[preview] failed to bind ${HOST}:${PORT}: ${err.message}\n` +
+        `[preview] tip: this sandbox may disallow binding "${HOST}".\n` +
+        `[preview] try:  mado preview --host 127.0.0.1`,
+    );
+  } else {
+    console.error(
+      `[preview] failed to listen on ${HOST}:${PORT}: ${err.message}`,
+    );
+  }
+  process.exit(1);
+});
+
+server.listen(PORT, HOST, async () => {
+  const urlHost = HOST === "0.0.0.0" || HOST === "::" ? "localhost" : HOST;
+  const bakedReady = await exists(BAKED);
+  console.log("");
+  console.log("Mado preview (production-like)");
+  console.log(`  url:    http://${urlHost}:${PORT}/`);
+  console.log(`  out:    ${OUT}`);
+  console.log(`  baked:  ${bakedReady ? BAKED : "(none — SPA-only)"}`);
+  console.log("  (Ctrl-C to stop)");
+  console.log("");
 });
 
 // ---------- helpers ----------
@@ -145,14 +215,33 @@ 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;
 
-  // 1) Exact match
+  // 2) Exact match inside out/.
   if (await exists(candidate)) {
     const s = await stat(candidate);
     if (s.isDirectory()) {
-      // Baked priority: /product/foo/ → /product/foo/index.html
       const idx = join(candidate, "index.html");
       if (await exists(idx)) return idx;
     } else {
@@ -160,15 +249,20 @@ async function resolveTarget(pathname) {
     }
   }
 
-  // 2) /foo → /foo/index.html (for baked pages without trailing slash)
+  // 3) /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;
   }
 
-  // 3) SPA-fallback
-  const spa = join(OUT, "index.html");
-  if (await exists(spa)) return spa;
+  // 4) 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.
+  if (!extname(pathname)) {
+    const spa = join(OUT, "index.html");
+    if (await exists(spa)) return spa;
+  }
 
   return null;
 }

package/server/serve.mjs

@@ -35,10 +35,49 @@ const CONFIG = (() => {
 })();
 const PROXY_RULES = Object.entries(CONFIG.dev?.proxy ?? {}); // [["/api", "http://localhost:3000"], ...]
 
-const PORT = Number(process.env.PORT ?? CONFIG.dev?.port ?? 5173);
-const HMR = process.env.NO_HMR !== "1";
+// Tiny argv parser. Supports --flag, --flag=value, --flag value. The first
+// non-flag positional is the EXAMPLE name (legacy behavior). Anything that
+// looks like a flag is consumed before we pick the positional, so calls like
+// `mado dev -- --host 127.0.0.1` work as documented.
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") continue;
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq >= 0) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const name = a.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("-")) {
+          flags[name] = next;
+          i++;
+        } else {
+          flags[name] = true;
+        }
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { flags, positional };
+}
+
+const { flags: CLI_FLAGS, positional: CLI_POSITIONAL } = parseArgs(
+  process.argv.slice(2),
+);
 
-const EXAMPLE = process.argv[2] ?? process.env.MADO_EXAMPLE ?? process.env.EXAMPLE ?? "";
+const PORT = Number(CLI_FLAGS.port ?? process.env.PORT ?? CONFIG.dev?.port ?? 5173);
+// HOST is opt-in. Default to "localhost" (loopback) which is friendlier in
+// sandboxes that disallow binding 0.0.0.0 (EPERM on listen). Users can opt
+// into LAN exposure with `mado dev --host 0.0.0.0` or HOST=0.0.0.0.
+const HOST = String(CLI_FLAGS.host ?? process.env.HOST ?? CONFIG.dev?.host ?? "localhost");
+const HMR = CLI_FLAGS.hmr !== false && process.env.NO_HMR !== "1";
+
+const EXAMPLE = CLI_POSITIONAL[0] ?? process.env.MADO_EXAMPLE ?? process.env.EXAMPLE ?? "";
 const EXAMPLE_DIR = EXAMPLE
   ? resolve(join(ROOT, "examples", EXAMPLE))
   : "";
@@ -185,7 +224,30 @@ const server = createServer(async (req, res) => {
       const s = await stat(target);
       if (s.isDirectory()) target = join(target, "index.html");
     } catch {
-      if (!extname(pathname)) {
+      // Public assets: in production `mado release` copies public/* into out/.
+      // In dev we surface them from public/ directly so favicon.svg, robots.txt,
+      // og-image.png, etc. don't 404 (and so dev/prod behavior matches).
+      const publicCandidate = resolve(join(ROOT, "public", pathname));
+      if (
+        publicCandidate.startsWith(resolve(join(ROOT, "public")) + sep) &&
+        existsSync(publicCandidate)
+      ) {
+        try {
+          const ps = await stat(publicCandidate);
+          if (!ps.isDirectory()) {
+            target = publicCandidate;
+            reason = "public/";
+          } else if (!extname(pathname)) {
+            target = fallbackIndex;
+          } else {
+            reason = "file not found";
+            res.writeHead(404).end("not found");
+            return;
+          }
+        } catch {
+          target = fallbackIndex;
+        }
+      } else if (!extname(pathname)) {
         target = fallbackIndex;
       } else {
         reason = "file not found";
@@ -301,7 +363,15 @@ async function buildPreloadHints() {
 }
 
 server.on("error", (err) => {
-  console.error(`[serve] failed to listen on port ${PORT}: ${err.message}`);
+  if (err.code === "EPERM" || err.code === "EACCES") {
+    console.error(
+      `[serve] failed to bind ${HOST}:${PORT}: ${err.message}\n` +
+        `[serve] tip: this sandbox may disallow binding "${HOST}".\n` +
+        `[serve] try:  mado dev --host 127.0.0.1   (or HOST=127.0.0.1)`,
+    );
+  } else {
+    console.error(`[serve] failed to listen on ${HOST}:${PORT}: ${err.message}`);
+  }
   process.exit(1);
 });
 
@@ -351,7 +421,7 @@ async function proxyForward({ req, res, prefix, upstream, pathname, search }) {
   void prefix;
 }
 
-server.listen(PORT, () => {
+server.listen(PORT, HOST, () => {
   const distReady = existsSync(join(ROOT, "dist/src/index.js"))
     || existsSync(join(ROOT, "dist/main.js"));
   const mount = EXAMPLE
@@ -359,9 +429,12 @@ server.listen(PORT, () => {
     : existsSync(EXAMPLES_INDEX)
       ? "examples/index.html landing"
       : "index.html app";
+  // Show "localhost" in the URL when bound to 0.0.0.0 — easier to click.
+  const urlHost = HOST === "0.0.0.0" || HOST === "::" ? "localhost" : HOST;
   console.log("");
   console.log("Mado dev server");
-  console.log(`  url:      http://localhost:${PORT}/`);
+  console.log(`  url:      http://${urlHost}:${PORT}/`);
+  console.log(`  host:     ${HOST}`);
   console.log(`  root:     ${ROOT}`);
   console.log(`  mount:    ${mount}`);
   console.log(`  hmr:      ${HMR ? "on" : "off"}`);

package/starters/admin/index.html

@@ -5,17 +5,24 @@
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>__APP_NAME__</title>
     <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+    <!--
+      Paths below MUST be root-absolute (start with "/"), not "./...".
+      Mado is an SPA: hard-refreshing /admin/orders/42 still serves this same
+      index.html, and the browser resolves "./dist/main.js" against the
+      current URL → /admin/orders/dist/main.js → 404 → blank page.
+      Root-absolute paths always resolve to /dist/main.js regardless of route.
+    -->
     <script type="importmap">
       {
         "imports": {
-          "@madojs/mado": "./node_modules/@madojs/mado/dist/src/index.js",
-          "@madojs/mado/": "./node_modules/@madojs/mado/dist/src/"
+          "@madojs/mado": "/node_modules/@madojs/mado/dist/src/index.js",
+          "@madojs/mado/": "/node_modules/@madojs/mado/dist/src/"
         }
       }
     </script>
   </head>
   <body>
     <div id="app"></div>
-    <script type="module" src="./dist/main.js"></script>
+    <script type="module" src="/dist/main.js"></script>
   </body>
 </html>

package/starters/admin/package.json

@@ -17,6 +17,8 @@
     "@madojs/mado": "__MADOJS_VERSION__"
   },
   "devDependencies": {
+    "esbuild": "^0.24.0",
+    "linkedom": "^0.18.0",
     "typescript": "^6.0.3"
   }
-}
+}

package/starters/admin/src/components/x-button.ts

@@ -1,25 +1,45 @@
 // <x-button variant="primary|ghost|danger" ?disabled>
 //
 // Wraps a native <button> so it can be slotted with text/icon and styled
-// consistently across the app. Click events bubble naturally because Shadow
-// DOM is `mode: open` and composed: true is the default for `click`.
+// consistently across the app.
+//
+// Handles two Shadow DOM gotchas out of the box:
+//   1. Reactive attributes via ctx.attr() — external ?disabled changes
+//      re-render the inner button automatically.
+//   2. Form submit — a <button type="submit"> inside Shadow DOM cannot
+//      trigger <form> submit in Light DOM (spec limitation). We call
+//      form.requestSubmit() from a click handler to bridge this gap.
 
 import { component, css, html } from "@madojs/mado";
 
 component(
   "x-button",
-  ({ host }) => () => {
-    const variant = host.getAttribute("variant") ?? "primary";
-    const disabled = host.hasAttribute("disabled");
-    return html`
-      <button data-variant=${variant} ?disabled=${disabled}>
+  ({ host, attr }) => {
+    const variant = attr("variant", "primary");
+    const disabled = attr("disabled");
+
+    const handleClick = () => {
+      const typeAttr = host.getAttribute("type");
+      if (typeAttr === "button" || typeAttr === "reset") return;
+      const form = host.closest("form");
+      if (form && !host.hasAttribute("disabled")) form.requestSubmit();
+    };
+
+    return () => html`
+      <button
+        data-variant=${variant()}
+        ?disabled=${() => disabled() !== ""}
+        @click=${handleClick}
+      >
         <slot></slot>
       </button>
     `;
   },
   {
     styles: css`
-      :host { display: inline-flex; }
+      :host {
+        display: inline-flex;
+      }
       button {
         display: inline-flex;
         align-items: center;
@@ -31,11 +51,18 @@ component(
         cursor: pointer;
         background: var(--accent);
         color: var(--accent-fg);
-        transition: filter .12s ease;
+        transition: filter 0.12s ease;
+      }
+      button:hover:not(:disabled) {
+        filter: brightness(1.07);
+      }
+      button:active:not(:disabled) {
+        filter: brightness(0.95);
+      }
+      button:disabled {
+        opacity: 0.55;
+        cursor: not-allowed;
       }
-      button:hover:not(:disabled) { filter: brightness(1.07); }
-      button:active:not(:disabled) { filter: brightness(.95); }
-      button:disabled { opacity: .55; cursor: not-allowed; }
 
       button[data-variant="ghost"] {
         background: transparent;
@@ -52,4 +79,4 @@ component(
       }
     `,
   },
-);
+);