@madojs/mado 0.11.0 → 0.12.0

package/scripts/static/server.mjs

@@ -0,0 +1,167 @@
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, resolve, sep } from "node:path";
+
+import { injectSnapshotMode } from "./serialize.mjs";
+
+/**
+ * Normalise a Vite-style base into the canonical Mado form: `"/"` for the
+ * root, otherwise `"/prefix/"` (leading and trailing slash, no doubles).
+ * Mirrors src/router/base.ts.normalizeBase so the capture pipeline never
+ * disagrees with the runtime router.
+ */
+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, "/");
+}
+
+/**
+ * Strip the active base prefix off a request pathname so the capture
+ * server can look it up against route records (which are always
+ * registered without a base).
+ */
+function stripBase(pathname, base) {
+  const b = normalizeBase(base);
+  if (!pathname) return "/";
+  if (b === "/") return pathname.startsWith("/") ? pathname : "/" + pathname;
+  if (pathname === b || pathname === b.slice(0, -1)) return "/";
+  if (pathname.startsWith(b)) {
+    const rest = pathname.slice(b.length - 1);
+    return rest || "/";
+  }
+  return pathname;
+}
+
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".woff2": "font/woff2",
+  ".xml": "application/xml; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+};
+
+/**
+ * Internal HTTP server that hosts the Vite build output during snapshot
+ * capture. It speaks the real deployment URL shape (the active Vite
+ * `base` is honoured for both static routes and asset lookups), so the
+ * runtime router sees the same `location.pathname` as production.
+ */
+export async function createStaticCaptureServer({ outDir, shellHtml, records, base = "/" }) {
+  const normalizedBase = normalizeBase(base);
+  const routeRecords = new Map(records.map((record) => [record.pathname, record]));
+
+  const server = createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      const browserPath = normalizePathname(url.pathname);
+      // The router uses BASE-FREE route pathnames, but assets in
+      // `out/assets/...` are served from the same base-relative URLs the
+      // production CDN exposes. Strip the active base before any record
+      // lookup or file resolution so both halves use one consistent
+      // pathname space.
+      const routePath = stripBase(browserPath, normalizedBase);
+
+      const record = routeRecords.get(routePath);
+      if (record) {
+        sendHtml(res, injectSnapshotMode(shellHtml, record));
+        return;
+      }
+
+      const file = await resolveStaticFile(outDir, routePath);
+      if (file) {
+        const data = await readFile(file);
+        res.writeHead(200, {
+          "content-type": MIME[extname(file).toLowerCase()] ?? "application/octet-stream",
+          "cache-control": "no-store",
+        });
+        res.end(data);
+        return;
+      }
+
+      // SPA fallback: any non-asset path falls back to the snapshot shell
+      // so client-side routing handles it. We use the original browser
+      // pathname (not the stripped one) inside `injectSnapshotMode` so
+      // that the runtime `location.pathname` matches production.
+      if (!extname(routePath)) {
+        sendHtml(
+          res,
+          injectSnapshotMode(shellHtml, { pathname: routePath, params: {} }),
+        );
+        return;
+      }
+
+      res.writeHead(404, { "cache-control": "no-store" });
+      res.end("not found");
+    } catch (err) {
+      res.writeHead(500, {
+        "content-type": "text/plain; charset=utf-8",
+        "cache-control": "no-store",
+      });
+      res.end(String(err?.stack ?? err));
+    }
+  });
+
+  await new Promise((resolveListen, rejectListen) => {
+    server.once("error", rejectListen);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", rejectListen);
+      resolveListen();
+    });
+  });
+
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new Error("[mado:static] failed to bind internal capture server.");
+  }
+
+  return {
+    origin: `http://127.0.0.1:${address.port}`,
+    close: () => new Promise((resolveClose) => server.close(resolveClose)),
+  };
+}
+
+function sendHtml(res, html) {
+  res.writeHead(200, {
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  res.end(html);
+}
+
+async function resolveStaticFile(outDir, pathname) {
+  const raw = pathname === "/" ? "/index.html" : pathname;
+  const candidate = resolve(join(outDir, decodeURIComponent(raw)));
+  if (!candidate.startsWith(resolve(outDir) + sep) && candidate !== resolve(outDir)) {
+    return null;
+  }
+  try {
+    const s = await stat(candidate);
+    if (s.isFile()) return candidate;
+    if (s.isDirectory()) {
+      const index = join(candidate, "index.html");
+      if ((await stat(index)).isFile()) return index;
+    }
+  } catch {
+    /* not found */
+  }
+  return null;
+}
+
+function normalizePathname(pathname) {
+  if (!pathname.startsWith("/")) return `/${pathname}`;
+  if (pathname.length > 1 && pathname.endsWith("/")) return pathname.slice(0, -1);
+  return pathname;
+}

package/scripts/static.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, writeSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { parseFlags } from "./_config.mjs";
+import { discoverStaticRoutes } from "./static/discover.mjs";
+import { createStaticCaptureServer } from "./static/server.mjs";
+import { captureStaticRoutes } from "./static/browser.mjs";
+import {
+  cleanupTemp,
+  dropBuildBridge,
+  prepareStaticOutput,
+  promoteCapturedRoutes,
+  promoteSpaShell,
+  writeCapturedRoutes,
+  writeStaticDeploymentFiles,
+} from "./static/output.mjs";
+
+const { flags } = parseFlags(process.argv.slice(2));
+const projectRoot = resolve(process.cwd());
+const outDir = resolve(
+  projectRoot,
+  typeof flags.out === "string" ? flags.out : "out",
+);
+const timeout = Number(flags.timeout ?? 30_000);
+
+let tempRootForCleanup = null;
+try {
+  console.log(`[static] artifact: ${outDir}`);
+
+  // Source the public origin and Vite base from (in order):
+  //   --base-url, --base / MADO_SITE env, _mado/build.json (the bridge
+  //   emitted by the @madojs/mado/vite plugin). Static routes REQUIRE
+  //   a non-localhost public origin; we never invent one.
+  const buildMeta = readBuildMeta(outDir);
+  const site = pickSite({ flags, buildMeta });
+  const base = pickBase({ flags, buildMeta });
+  validateSite(site, "site");
+
+  // Ordering matters: discover and validate the manifest BEFORE we
+  // touch the deployed artefact. A manifest that throws (missing
+  // params, duplicate URL, ...) used to leave a half-prepared
+  // staging directory behind because we provisioned the temp tree
+  // before discovery; now the temp tree is created only after we know
+  // the inputs are sound.
+  const { records } = await discoverStaticRoutes({
+    projectRoot,
+    entry: typeof flags.entry === "string" ? flags.entry : undefined,
+  });
+
+  console.log(`[static] discovered ${records.length} static route(s)`);
+
+  if (records.length > 0 && !site) {
+    throw new Error(
+      "[mado:static] missing public origin for static routes.\n" +
+        "Provide one of:\n" +
+        "  mado static --base-url https://your.site\n" +
+        "  MADO_SITE=https://your.site mado static\n" +
+        "  mado({ site: \"https://your.site\" }) in vite.config.ts",
+    );
+  }
+
+  const { shellHtml, tempRoot, routesDir, stagedSpaPath } =
+    await prepareStaticOutput(outDir);
+  tempRootForCleanup = tempRoot;
+
+  const publicOrigin = site ?? "";
+  const baseUrl = publicOrigin
+    ? joinSite(publicOrigin, base)
+    : "/";
+
+  if (records.length > 0) {
+    const server = await createStaticCaptureServer({
+      outDir,
+      shellHtml,
+      records,
+      base,
+    });
+    try {
+      const captured = await captureStaticRoutes({
+        records,
+        serverOrigin: server.origin,
+        baseUrl,
+        base,
+        site: publicOrigin,
+        timeout,
+        browserChannel:
+          typeof flags["browser-channel"] === "string"
+            ? flags["browser-channel"]
+            : undefined,
+        browserPath:
+          typeof flags["browser-path"] === "string"
+            ? flags["browser-path"]
+            : undefined,
+      });
+      // First write everything to the temp staging tree, only then
+      // promote into `out/`. A capture failure aborts before any of the
+      // existing deployment files are touched.
+      await writeCapturedRoutes(routesDir, captured);
+      await promoteCapturedRoutes({ outDir, routesDir, captured });
+      console.log(`[static] captured ${captured.length} route snapshot(s)`);
+    } finally {
+      await server.close();
+    }
+  }
+
+  // SPA shell is promoted only after every route survived capture and
+  // promotion. On a re-run with broken pages this guarantees that the
+  // previous (working) `_mado/spa.html` is preserved.
+  await promoteSpaShell({ outDir, stagedSpaPath });
+
+  await writeStaticDeploymentFiles({
+    outDir,
+    records,
+    baseUrl,
+    site: publicOrigin,
+    base,
+  });
+
+  // Drop the internal build bridge so the production artifact does not
+  // ship Vite's resolved view of the project (site, base, assetsDir).
+  await dropBuildBridge(outDir);
+  console.log(`[static] done`);
+} catch (err) {
+  // Defer the actual termination: `process.exit()` is synchronous and
+  // would race the awaited cleanup in the `finally` block, leaving the
+  // OS to garbage-collect a half-promoted staging directory. Setting
+  // `exitCode` lets Node finish the microtask queue (including the
+  // cleanup below) and then exit with the failure status.
+  writeSync(2, `${err?.stack ?? err}\n`);
+  process.exitCode = 1;
+} finally {
+  if (tempRootForCleanup) {
+    try {
+      await cleanupTemp(tempRootForCleanup);
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+function readBuildMeta(outDir) {
+  const file = join(outDir, "_mado/build.json");
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function pickSite({ flags, buildMeta }) {
+  const fromFlag = flags["base-url"] ?? flags.site;
+  if (typeof fromFlag === "string" && fromFlag.length > 0) return fromFlag;
+  if (typeof process.env.MADO_SITE === "string" && process.env.MADO_SITE.length > 0) {
+    return process.env.MADO_SITE;
+  }
+  if (buildMeta?.site) return buildMeta.site;
+  return null;
+}
+
+function pickBase({ flags, buildMeta }) {
+  const fromFlag = flags.base;
+  if (typeof fromFlag === "string" && fromFlag.length > 0) return fromFlag;
+  if (buildMeta?.base) return buildMeta.base;
+  return "/";
+}
+
+function validateSite(site, label) {
+  if (!site) return;
+  let u;
+  try {
+    u = new URL(site);
+  } catch {
+    throw new Error(`[mado:static] ${label} is not a valid URL: ${site}`);
+  }
+  if (u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "::1") {
+    throw new Error(
+      `[mado:static] ${label} cannot point at localhost (${site}). ` +
+        "Set the public origin via --base-url or mado({ site }) in vite.config.ts.",
+    );
+  }
+}
+
+function joinSite(site, base) {
+  const left = site.replace(/\/+$/, "");
+  const right = (base ?? "/").startsWith("/") ? base : `/${base ?? "/"}`;
+  const merged = `${left}${right}`;
+  return merged.endsWith("/") ? merged.slice(0, -1) : merged;
+}

package/starters/default/README.md

@@ -1,74 +1,76 @@
-# Mado Starter
+# Mado universal starter
 
-Canonical starter for Mado business apps: admin panels, internal tools and
-long-lived SPAs.
+A calm native-first web framework for sites and apps. This starter
+proves the whole promise in ~15 files:
 
-## Commands
+- one Shadow Component (`feature-card`) shared by the static landing
+  and the live SPA,
+- one component model end-to-end,
+- a build-time seed for a dynamic static route (`/guide/:slug`),
+- a private SPA route (`/app`) that falls back through `_mado/spa.html`,
+- per-route head metadata, sitemap, canonical and `og:url`
+  auto-fallback.
+
+## Run it
 
 ```bash
 npm install
-npm run dev
-npm run release
+npm run dev          # Vite dev server
+npm run build        # Vite production SPA build
+npm run release      # vite build + browser-rendered snapshots → out/
+npm run preview      # serve out/ like a real static host
 ```
 
-`npm run release` writes the deploy artifact to `out/`.
+`mado release` requires a public origin so it can build absolute
+canonical URLs. Set it once in `vite.config.ts`:
 
-## Shape
+```ts
+mado({ site: "https://your-app.example" })
+```
 
-```txt
-public/                  static assets copied by Vite
-src/
-  main.ts                imports global CSS and mounts the router
-  app.routes.ts          app map: zones, layouts, guards and modules
-  layouts/               app-zone shells
-  shared/
-    http/                HTTP client and interceptors
-    lib/                 pure utilities
-    styles/              tokens, reset, shell and content CSS
-    ui/                  reusable x-* components
-  modules/               business modules
-    <name>/
-      <name>.routes.ts
-      <name>.public.ts
-      <name>.types.ts
-      pages/
-      data/
-      api/
-      components/
-      _contracts/
+…or override per environment:
+
+```bash
+mado release --base-url https://staging.example
+MADO_SITE=https://staging.example mado release
 ```
 
-## CSS Contract
+## File map
+
+```
+src/
+  main.ts                       # mounts the router into #app
+  app.routes.ts                 # the URL → page table
 
-- `tokens.css` defines CSS custom properties and is safe for Shadow DOM
-  components through `var(...)`.
-- `reset.css` normalizes the document/light DOM surface.
-- `shell.css` styles app-zone layouts from `src/layouts/`.
-- `content.css` styles page-level light DOM: forms, tables, prose and simple
-  states.
-- Reusable leaf components keep their own styles in ``css`...` `` inside
-  `component()` options.
+  pages/
+    home.page.ts                # public, static
+    guide.page.ts               # dynamic static (/guide/:slug)
+    app.page.ts                 # SPA-only interactive route
+    not-found.page.ts           # 404 (SPA fallback)
 
-Vite uses Lightning CSS for CSS transforms/minification in this starter.
+  components/
+    feature-card.component.ts   # shared by landing + app
+    live-counter.component.ts   # reactivity demo
 
-## Generate Files
+  content/
+    guides.ts                   # browser-safe content module
 
-```bash
-npm run new -- module billing
-npm run new -- page billing/pages/invoices-list
-npm run new -- connector billing/api/stripe
-npm run new -- resource billing/data/invoices
-npm run new -- service billing/cart
-npm run new -- form billing/invoice
-npm run new -- component billing/components/invoice-status-badge
-npm run new -- guard billing/billing
-npm run new -- layout admin-shell
+  styles/
+    tokens.css                  # design tokens (custom properties)
+    reset.css                   # tiny modern reset
+    document.css                # light-DOM document layout
 ```
 
-The generator writes files only. Wire new routes in `src/app.routes.ts` or the
-module route map by hand.
+## Going further
 
-## More
+If you need module boundaries, layouts, guards, an auth shell, an HTTP
+client and a Stripe-style billing example, scaffold the modular
+starter instead:
+
+```bash
+mado init my-app --starter modular
+```
 
-The full architecture guide lives in the framework docs:
-https://github.com/madojs/mado/tree/main/docs/en
+The modular starter is the reference architecture for long-lived
+business apps. Both starters target the same Mado runtime — they only
+differ in how much structure they pre-create for you.

package/starters/default/package.json

@@ -5,25 +5,19 @@
   "type": "module",
   "scripts": {
     "dev": "mado dev",
-    "build": "mado release",
+    "build": "mado build",
     "typecheck": "mado typecheck",
-    "test": "npm run typecheck && npm run lint",
+    "test": "mado typecheck",
     "release": "mado release",
     "preview": "mado preview",
-    "lint": "eslint \"src/**/*.ts\"",
-    "lint:fix": "eslint \"src/**/*.ts\" --fix",
     "new": "mado new"
   },
   "dependencies": {
     "@madojs/mado": "__MADOJS_VERSION__"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "eslint": "^9.0.0",
-    "eslint-plugin-boundaries": "^5.0.0",
-    "linkedom": "^0.18.12",
     "lightningcss": "^1.32.0",
+    "playwright-core": "^1.47.0",
     "typescript": "^5.5.0",
     "vite": "^8.0.16"
   }

package/starters/default/src/app.routes.ts

@@ -1,39 +1,26 @@
-// Single source of truth for the application route table.
+// Single source of truth for the app's URL → page mapping.
 //
-// This file is the APP MAP. Reading it = understanding the app.
-//
-// One rule:
-//   Modules export plain `routes` maps. The choice of SHELL and GUARD for
-//   each zone of the app is made HERE, by wrapping a module's routes with
-//   a `layout({...})` block.
-//
-// `manifest` is exported separately so `mado bake` can discover pages that
-// declare `bake: { paths, data }`.
-
-import { layout, routes } from "@madojs/mado";
-
-import { requireAuth } from "./modules/auth/auth.public";
-import { authRoutes } from "./modules/auth/auth.routes";
-import { billingRoutes } from "./modules/billing/billing.routes";
+// Mado has no "file-based routes". You list pages explicitly, in order
+// of specificity, and the router takes care of code-splitting via the
+// dynamic imports below.
+import { routes } from "@madojs/mado";
 
 export const manifest = {
-  // Public landing (no shell, no guard).
-  "/": () => import("./modules/home/home.page"),
-
-  // AUTH ZONE — centered card, no guard.
-  "/login": layout({
-    layout: () => import("./layouts/auth-shell.layout"),
-    routes: authRoutes,
-  }),
-
-  // APP ZONE — header + nav, guarded by requireAuth.
-  "/billing": layout({
-    layout: () => import("./layouts/app-shell.layout"),
-    guard: requireAuth,
-    routes: billingRoutes,
-  }),
-
-  "*": () => import("./modules/home/not-found.page"),
+  // Public landing — `static: true` makes `mado release` snapshot this
+  // route into `out/index.html` so search engines see a fully rendered
+  // document without running JS.
+  "/": () => import("./pages/home.page"),
+  // Dynamic static route: `mado static` calls `paths()` at build time,
+  // captures one HTML file per slug, and seeds `initialData` so the
+  // first client render does not re-fetch what the snapshot already
+  // shows.
+  "/guide/:slug": () => import("./pages/guide.page"),
+  // SPA-only route: deliberately non-static. Lives in `_mado/spa.html`
+  // at deploy time and is served whenever the CDN cannot find a static
+  // document.
+  "/app": () => import("./pages/app.page"),
+  // 404 — matched after every literal pattern.
+  "*": () => import("./pages/not-found.page"),
 };
 
 export default routes(manifest);

package/starters/default/src/components/feature-card.component.ts

@@ -0,0 +1,40 @@
+// `feature-card` is a leaf component shared by the home page (in the
+// static snapshot) and by `app.page.ts` (in the live SPA). The same
+// open-shadow custom element runs in both contexts — that is the core
+// promise of the universal model.
+import { component, css, html } from "@madojs/mado";
+
+component(
+  "feature-card",
+  (ctx) => {
+    const title = ctx.attr("title", "");
+    return () => html`
+      <article class="card">
+        <h3>${() => title()}</h3>
+        <p><slot></slot></p>
+      </article>
+    `;
+  },
+  {
+    styles: css`
+      :host {
+        display: block;
+      }
+      .card {
+        padding: 1.25rem 1.5rem;
+        border: 1px solid var(--mado-border);
+        border-radius: var(--mado-radius);
+        background: var(--mado-surface);
+      }
+      h3 {
+        margin: 0 0 0.5rem;
+        font-size: 1.1rem;
+        font-weight: 600;
+      }
+      p {
+        margin: 0;
+        color: var(--mado-fg-muted);
+      }
+    `,
+  },
+);

package/starters/default/src/components/live-counter.component.ts

@@ -0,0 +1,57 @@
+// `live-counter` showcases reactivity: signal-driven text, a click
+// handler that mutates the signal, and an open shadow root that
+// participates in the static snapshot via Declarative Shadow DOM.
+import { component, css, html, signal } from "@madojs/mado";
+
+component(
+  "live-counter",
+  () => {
+    const count = signal(0);
+    return () => html`
+      <div class="counter">
+        <button
+          class="bump"
+          @click=${() => count.update((n) => n + 1)}
+          aria-label="Increment"
+        >
+          +
+        </button>
+        <span class="value">${() => count()}</span>
+      </div>
+    `;
+  },
+  {
+    styles: css`
+      :host {
+        display: inline-block;
+      }
+      .counter {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.75rem;
+        padding: 0.5rem 0.75rem;
+        border: 1px solid var(--mado-border);
+        border-radius: var(--mado-radius);
+        background: var(--mado-surface);
+      }
+      .bump {
+        font: inherit;
+        width: 2rem;
+        height: 2rem;
+        border-radius: 999px;
+        border: 1px solid var(--mado-border);
+        background: var(--mado-bg);
+        cursor: pointer;
+      }
+      .bump:hover {
+        background: var(--mado-surface-hover);
+      }
+      .value {
+        font-variant-numeric: tabular-nums;
+        font-weight: 600;
+        min-width: 2ch;
+        text-align: right;
+      }
+    `,
+  },
+);