@madojs/mado 0.5.0

package/scripts/showcase-regression.mjs

@@ -0,0 +1,392 @@
+// Browser regression for examples/showcase.
+//
+// Optional by design: regular `npm test` stays Node/linkedom-only. Run this
+// when you want real browser confidence for routing, forms and Shadow DOM.
+
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as wait } from "node:timers/promises";
+
+const PORT = Number(process.env.PORT ?? 5181);
+const BASE = `http://localhost:${PORT}`;
+
+async function loadPlaywright() {
+  try {
+    return await import("playwright-core");
+  } catch {
+    console.warn("[showcase-regression] playwright-core is not installed; skipped.");
+    return null;
+  }
+}
+
+async function waitForServer() {
+  for (let i = 0; i < 60; i++) {
+    try {
+      const res = await fetch(BASE);
+      if (res.ok) return;
+    } catch {
+      /* server not ready */
+    }
+    await wait(100);
+  }
+  throw new Error(`Server did not start at ${BASE}`);
+}
+
+const server = spawn("node", ["server/serve.mjs"], {
+  env: {
+    ...process.env,
+    PORT: String(PORT),
+    EXAMPLE: "showcase",
+    NO_HMR: "1",
+  },
+  stdio: "pipe",
+});
+
+let browser;
+let chrome;
+let tmpProfile;
+try {
+  await waitForServer();
+  const pw = await loadPlaywright();
+  if (pw) {
+    try {
+      browser = await pw.chromium.launch();
+      const page = await browser.newPage();
+      await runWithPage(page);
+      await page.close();
+    } catch (error) {
+      console.warn(
+        `[showcase-regression] Playwright Chromium could not start; falling back to system Chrome. ${error.message}`,
+      );
+      if (browser) await browser.close();
+      browser = undefined;
+      const result = await runWithChromeCdp();
+      chrome = result.chrome;
+      tmpProfile = result.tmpProfile;
+    }
+  } else {
+    const result = await runWithChromeCdp();
+    chrome = result.chrome;
+    tmpProfile = result.tmpProfile;
+  }
+  console.log("[showcase-regression] passed");
+} finally {
+  if (browser) await browser.close();
+  if (chrome) {
+    chrome.kill("SIGTERM");
+    await wait(300);
+  }
+  if (tmpProfile) {
+    try {
+      await rm(tmpProfile, { recursive: true, force: true, maxRetries: 3, retryDelay: 120 });
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
+  server.kill("SIGTERM");
+}
+
+async function expectSingle(page, selector) {
+  const count = await page.locator(`#app ${selector}`).count();
+  assert.equal(count, 1, `${selector} should be the only active page host`);
+}
+
+async function runWithPage(page) {
+  await page.goto(BASE);
+  await page.waitForSelector("x-hero");
+  assert.equal(await page.locator("#app x-hero").count(), 1);
+
+  await page.click("x-nav >>> a[href='/app/login']");
+  await page.waitForSelector("x-login");
+  await page.fill("x-login >>> input[name='email']", "anna@example.com");
+  await page.fill("x-login >>> input[name='password']", "demo");
+  await page.click("x-login >>> button[type='submit']");
+  await page.waitForSelector("x-dashboard");
+  await expectSingle(page, "x-dashboard");
+
+  await page.click("x-app-layout a[href='/app/accounts']");
+  await page.waitForSelector("x-accounts-list");
+  await page.fill("x-accounts-list >>> input[type='search']", "Northwind");
+  await page.waitForTimeout(350);
+  await expectSingle(page, "x-accounts-list");
+
+  await page.click("x-accounts-list >>> a[href='/app/accounts/new']");
+  await page.waitForSelector("x-account-new");
+  await page.fill("x-account-new >>> input[name='name']", "Browser Test Co");
+  await page.fill("x-account-new >>> input[name='domain']", "browser.example");
+  await page.fill("x-account-new >>> input[name='mrr']", "6200");
+  await page.fill("x-account-new >>> textarea[name='notes']", "Created by browser regression.");
+  await page.click("x-account-new >>> button[type='submit']");
+  await page.waitForSelector("x-account-detail");
+  await expectSingle(page, "x-account-detail");
+
+  await page.click("x-account-detail >>> button:has-text('New deal')");
+  await page.fill("x-account-detail >>> input[name='title']", "Browser pipeline");
+  await page.fill("x-account-detail >>> input[name='value']", "88000");
+  await page.fill("x-account-detail >>> textarea[name='notes']", "Created through modal regression.");
+  await page.click("x-account-detail >>> button:has-text('Create deal')");
+  await page.waitForTimeout(500);
+  await expectSingle(page, "x-account-detail");
+
+  await page.click("x-app-layout a[href='/app/deals']");
+  await page.waitForSelector("x-deals-list");
+  await expectSingle(page, "x-deals-list");
+
+  const activeAppHosts = await page.locator(
+    "#app x-dashboard,#app x-accounts-list,#app x-account-new,#app x-account-detail,#app x-deals-list,#app x-deal-detail,#app x-settings,#app x-login",
+  ).count();
+  assert.equal(activeAppHosts, 1);
+}
+
+async function runWithChromeCdp() {
+  if (typeof WebSocket === "undefined") {
+    console.warn("[showcase-regression] no WebSocket for CDP fallback; skipped.");
+    process.exit(0);
+  }
+  const debugPort = Number(process.env.CHROME_DEBUG_PORT ?? 9228);
+  const chromeBin = process.env.CHROME_BIN ?? "google-chrome";
+  const profile = await mkdtemp(join(tmpdir(), "mado-showcase-chrome-"));
+  const chromeProc = spawn(
+    chromeBin,
+    [
+      "--headless=new",
+      "--disable-gpu",
+      "--no-sandbox",
+      "--disable-dev-shm-usage",
+      `--remote-debugging-port=${debugPort}`,
+      `--user-data-dir=${profile}`,
+      BASE,
+    ],
+    { stdio: "ignore" },
+  );
+  chromeProc.on("error", () => {
+    console.warn("[showcase-regression] google-chrome is not available; skipped.");
+  });
+
+  const wsUrl = await waitForCdp(debugPort);
+  if (!wsUrl) {
+    chromeProc.kill("SIGTERM");
+    await rm(profile, { recursive: true, force: true });
+    console.warn("[showcase-regression] Chrome CDP did not start; skipped.");
+    process.exit(0);
+  }
+
+  const cdp = await connectCdp(wsUrl);
+  await cdp.send("Runtime.enable");
+  await cdp.send("Page.enable");
+  await cdp.send("Page.navigate", { url: BASE });
+  await waitForCdpSelector(cdp, "x-hero");
+  assert.equal(await cdpCount(cdp, "x-hero"), 1);
+
+  await cdpClick(cdp, "x-nav >>> a[href='/app/login']");
+  await waitForCdpSelector(cdp, "x-login");
+  await cdpFill(cdp, "x-login >>> input[name='email']", "anna@example.com");
+  await cdpFill(cdp, "x-login >>> input[name='password']", "demo");
+  await cdpClick(cdp, "x-login >>> button[type='submit']");
+  await waitForCdpSelector(cdp, "x-dashboard");
+  assert.equal(await cdpCount(cdp, "x-dashboard"), 1);
+
+  await cdpClick(cdp, "x-app-layout >>> a[href='/app/accounts']");
+  await waitForCdpSelector(cdp, "x-accounts-list");
+  await cdpFill(cdp, "x-accounts-list >>> input[type='search']", "Northwind");
+  await wait(350);
+  assert.equal(await cdpCount(cdp, "x-accounts-list"), 1);
+
+  await cdpClick(cdp, "x-accounts-list >>> a[href='/app/accounts/new']");
+  await waitForCdpSelector(cdp, "x-account-new");
+  await cdpFill(cdp, "x-account-new >>> input[name='name']", "Browser Test Co");
+  await cdpFill(cdp, "x-account-new >>> input[name='domain']", "browser.example");
+  await cdpFill(cdp, "x-account-new >>> input[name='mrr']", "6200");
+  await cdpFill(cdp, "x-account-new >>> textarea[name='notes']", "Created by browser regression.");
+  await cdpClick(cdp, "x-account-new >>> button[type='submit']");
+  await waitForCdpSelector(cdp, "x-account-detail");
+  assert.equal(await cdpCount(cdp, "x-account-detail"), 1);
+
+  await cdpClickText(cdp, "x-account-detail >>> button", "New deal");
+  await cdpFill(cdp, "x-account-detail >>> input[name='title']", "Browser pipeline");
+  await cdpFill(cdp, "x-account-detail >>> input[name='value']", "88000");
+  await cdpFill(cdp, "x-account-detail >>> textarea[name='notes']", "Created through modal regression.");
+  await cdpClickText(cdp, "x-account-detail >>> button", "Create deal");
+  await wait(500);
+  assert.equal(await cdpCount(cdp, "x-account-detail"), 1);
+
+  await cdpClick(cdp, "x-app-layout >>> a[href='/app/deals']");
+  await waitForCdpSelector(cdp, "x-deals-list");
+  assert.equal(await cdpCount(cdp, "x-deals-list"), 1);
+  const active = await cdpCount(
+    cdp,
+    "x-dashboard,x-accounts-list,x-account-new,x-account-detail,x-deals-list,x-deal-detail,x-settings,x-login",
+  );
+  assert.equal(active, 1);
+  cdp.close();
+  return { chrome: chromeProc, tmpProfile: profile };
+}
+
+async function waitForCdp(debugPort) {
+  for (let i = 0; i < 50; i++) {
+    try {
+      const list = await fetch(`http://127.0.0.1:${debugPort}/json/list`).then((r) => r.json());
+      for (const item of list) {
+        if (item.type === "page" && item.webSocketDebuggerUrl) return item.webSocketDebuggerUrl;
+      }
+    } catch {
+      /* not ready */
+    }
+    await wait(100);
+  }
+  return "";
+}
+
+function connectCdp(url) {
+  const ws = new WebSocket(url);
+  let seq = 1;
+  const pending = new Map();
+  ws.onmessage = (event) => {
+    const msg = JSON.parse(event.data);
+    if (!msg.id) return;
+    const entry = pending.get(msg.id);
+    if (!entry) return;
+    pending.delete(msg.id);
+    if (msg.error) entry.reject(new Error(msg.error.message));
+    else entry.resolve(msg.result);
+  };
+  return new Promise((resolve, reject) => {
+    ws.onerror = () => reject(new Error("CDP websocket failed"));
+    ws.onopen = () => {
+      resolve({
+        send(method, params = {}) {
+          const id = seq++;
+          ws.send(JSON.stringify({ id, method, params }));
+          return new Promise((res, rej) => pending.set(id, { resolve: res, reject: rej }));
+        },
+        close() {
+          ws.close();
+        },
+      });
+    };
+  });
+}
+
+function helperScript() {
+  return `
+(() => {
+  window.__deepFind = (selector, root = document) => {
+    const direct = root.querySelector(selector);
+    if (direct) return direct;
+    for (const el of root.querySelectorAll('*')) {
+      if (!el.shadowRoot) continue;
+      const found = window.__deepFind(selector, el.shadowRoot);
+      if (found) return found;
+    }
+    return null;
+  };
+  window.__deepCount = (selector, root = document) => {
+    let count = root.querySelectorAll(selector).length;
+    for (const el of root.querySelectorAll('*')) {
+      if (el.shadowRoot) count += window.__deepCount(selector, el.shadowRoot);
+    }
+    return count;
+  };
+  window.__pq = (path) => {
+    let root = document;
+    let node = null;
+    for (const raw of path.split('>>>')) {
+      const part = raw.trim();
+      node = root === document ? window.__deepFind(part, root) : root.querySelector(part);
+      if (!node) return null;
+      root = node.shadowRoot || node;
+    }
+    return node;
+  };
+  window.__pqAllCount = (selector) => window.__deepCount(selector);
+})();
+`;
+}
+
+async function cdpEval(cdp, expression) {
+  const result = await cdp.send("Runtime.evaluate", {
+    expression,
+    awaitPromise: true,
+    returnByValue: true,
+  });
+  if (result.exceptionDetails) {
+    const detail =
+      result.exceptionDetails.exception?.description ??
+      result.exceptionDetails.text ??
+      "Runtime.evaluate failed";
+    throw new Error(detail);
+  }
+  return result.result?.value;
+}
+
+async function installHelper(cdp) {
+  await cdpEval(cdp, helperScript());
+}
+
+async function waitForCdpSelector(cdp, selector) {
+  await installHelper(cdp);
+  for (let i = 0; i < 80; i++) {
+    if (await cdpEval(cdp, `Boolean(window.__pq(${JSON.stringify(selector)}))`)) return;
+    await wait(100);
+  }
+  const snapshot = await cdpEval(
+    cdp,
+    `JSON.stringify({ href: location.href, title: document.title, body: document.body.innerHTML.slice(0, 500) })`,
+  );
+  throw new Error(`Selector not found: ${selector}; page=${snapshot}`);
+}
+
+async function cdpClick(cdp, selector) {
+  await installHelper(cdp);
+  await cdpEval(cdp, `(() => {
+    const el = window.__pq(${JSON.stringify(selector)});
+    if (!el) throw new Error("missing ${selector}");
+    el.click();
+    return true;
+  })()`);
+}
+
+async function cdpClickText(cdp, selector, text) {
+  await installHelper(cdp);
+  for (let i = 0; i < 80; i++) {
+    const clicked = await cdpEval(cdp, `(() => {
+      const rootPath = ${JSON.stringify(selector)};
+      const parts = rootPath.split('>>>');
+      let root = document;
+      const last = parts.pop().trim();
+      for (const raw of parts) {
+        const part = raw.trim();
+        const node = root === document ? window.__deepFind(part, root) : root.querySelector(part);
+        if (!node) return false;
+        root = node.shadowRoot || node;
+      }
+      const el = Array.from(root.querySelectorAll(last)).find((x) => x.textContent.includes(${JSON.stringify(text)}));
+      if (!el) return false;
+      el.click();
+      return true;
+    })()`);
+    if (clicked) return;
+    await wait(100);
+  }
+  throw new Error(`Text button not found: ${selector} ${text}`);
+}
+
+async function cdpFill(cdp, selector, value) {
+  await installHelper(cdp);
+  await cdpEval(cdp, `(() => {
+    const el = window.__pq(${JSON.stringify(selector)});
+    if (!el) throw new Error("missing ${selector}");
+    el.value = ${JSON.stringify(value)};
+    el.dispatchEvent(new Event("input", { bubbles: true, composed: true }));
+    el.dispatchEvent(new Event("change", { bubbles: true, composed: true }));
+    return true;
+  })()`);
+}
+
+async function cdpCount(cdp, selector) {
+  await installHelper(cdp);
+  return cdpEval(cdp, `window.__pqAllCount(${JSON.stringify(selector)})`);
+}

package/server/serve.mjs

@@ -0,0 +1,292 @@
+// Tiny static server on node:http with dev features (ETag + HMR through SSE).
+// No dependencies.
+//
+//   PORT=5173 node server/serve.mjs
+//   NO_HMR=1 node server/serve.mjs                # disable HMR
+//   node server/serve.mjs basic                   # mount examples/basic/ at /
+//   EXAMPLE=showcase node server/serve.mjs        # mount examples/showcase/ at /
+//
+// Without EXAMPLE, / serves examples/index.html (example index).
+// With EXAMPLE, all extensionless and /index.html requests fall back to
+// examples/<EXAMPLE>/index.html so the client router works from root, just
+// like a production SPA deploy.
+
+import { createServer } from "node:http";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { watch, existsSync } from "node:fs";
+import { extname, join, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+
+const ROOT = resolve(process.cwd());
+const PORT = Number(process.env.PORT ?? 5173);
+const HMR = process.env.NO_HMR !== "1";
+
+const EXAMPLE = process.argv[2] ?? process.env.MADO_EXAMPLE ?? process.env.EXAMPLE ?? "";
+const EXAMPLE_DIR = EXAMPLE
+  ? resolve(join(ROOT, "examples", EXAMPLE))
+  : "";
+const EXAMPLE_INDEX = EXAMPLE ? join(EXAMPLE_DIR, "index.html") : "";
+
+if (EXAMPLE) {
+  if (!existsSync(EXAMPLE_INDEX)) {
+    console.error(
+      `[serve] EXAMPLE=${EXAMPLE}: file not found: ${EXAMPLE_INDEX}`,
+    );
+    process.exit(1);
+  }
+}
+
+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",
+  ".map": "application/json; charset=utf-8",
+};
+
+// ---------- HMR through Server-Sent Events ----------
+//
+// Open SSE connections live in a Set. Any file change broadcasts "reload".
+// The client reloads the page. This is deliberately full reload rather than
+// true HMR: we do not need preserved state, and the behavior stays simple.
+
+const sseClients = new Set();
+
+function broadcast(event, data) {
+  for (const res of sseClients) {
+    res.write(`event: ${event}\ndata: ${data}\n\n`);
+  }
+}
+
+if (HMR) {
+  // Debounce reload: tsc -w often changes several files in a row.
+  let timer = null;
+  const trigger = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      console.log(`[hmr] reload ${sseClients.size} client(s)`);
+      broadcast("reload", Date.now());
+    }, 80);
+  };
+
+  for (const dir of ["dist", "examples"]) {
+    try {
+      watch(join(ROOT, dir), { recursive: true }, trigger);
+    } catch {
+      /* dir may not exist on startup */
+    }
+  }
+}
+
+const HMR_CLIENT = `
+// Mado HMR client (auto-injected by serve.mjs)
+(() => {
+  if (window.__madoHmr) return;
+  window.__madoHmr = true;
+  const es = new EventSource('/__hmr');
+  es.addEventListener('reload', () => location.reload());
+  es.addEventListener('error', () => {
+    // The server may be gone; try reconnecting after 1s.
+    setTimeout(() => location.reload(), 1000);
+  });
+})();
+`.trim();
+
+// ---------- Server ----------
+
+const server = createServer(async (req, res) => {
+  const started = Date.now();
+  let pathname = "/";
+  let reason = "";
+  res.on("finish", () => {
+    const ms = Date.now() - started;
+    const type = res.getHeader("content-type") ?? "-";
+    const suffix = reason ? ` ${reason}` : "";
+    console.log(
+      `[serve] ${req.method ?? "GET"} ${pathname} ${res.statusCode} ${ms}ms ${type}${suffix}`,
+    );
+  });
+
+  try {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    pathname = decodeURIComponent(url.pathname);
+
+    // SSE endpoint for HMR.
+    if (pathname === "/__hmr") {
+      res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+      });
+      res.write("retry: 1000\n\n");
+      sseClients.add(res);
+      console.log(`[hmr] client connected (${sseClients.size})`);
+      req.on("close", () => {
+        sseClients.delete(res);
+        console.log(`[hmr] client disconnected (${sseClients.size})`);
+      });
+      return;
+    }
+
+    // A mounted example owns root and SPA fallback. Otherwise serve the
+    // examples index page.
+    const fallbackIndex = EXAMPLE
+      ? EXAMPLE_INDEX
+      : join(ROOT, "examples", "index.html");
+
+    if (pathname === "/") {
+      // Resolved through fallback below.
+    }
+
+    const filePath =
+      pathname === "/" ? fallbackIndex : resolve(join(ROOT, pathname));
+
+    if (filePath !== fallbackIndex) {
+      if (!filePath.startsWith(ROOT + sep) && filePath !== ROOT) {
+        reason = "forbidden path";
+        res.writeHead(403).end("forbidden");
+        return;
+      }
+    }
+
+    let target = filePath;
+    try {
+      const s = await stat(target);
+      if (s.isDirectory()) target = join(target, "index.html");
+    } catch {
+      if (!extname(pathname)) {
+        target = fallbackIndex;
+      } else {
+        reason = "file not found";
+        res.writeHead(404).end("not found");
+        return;
+      }
+    }
+
+    let data = await readFile(target);
+
+    // ETag: content hash. If-None-Match → 304.
+    const etag = `"${createHash("sha1").update(data).digest("base64url")}"`;
+    if (req.headers["if-none-match"] === etag) {
+      res.writeHead(304, { etag });
+      res.end();
+      return;
+    }
+
+    // HMR injector: add the client script before </body>.
+    const type =
+      MIME[extname(target).toLowerCase()] ?? "application/octet-stream";
+
+    if (type.startsWith("text/html")) {
+      let text = data.toString("utf8");
+      // modulepreload hints: tell the browser to fetch the framework core and
+      // the mounted example's pages while HTML is still being parsed.
+      const preload = await buildPreloadHints();
+      if (preload) {
+        text = text.replace(/<\/head>/i, `${preload}\n  </head>`);
+      }
+      if (HMR) {
+        text = text.replace(
+          /<\/body>/i,
+          `<script>${HMR_CLIENT}</script>\n  </body>`,
+        );
+      }
+      data = Buffer.from(text);
+    }
+
+    res.writeHead(200, {
+      "content-type": type,
+      etag,
+      "cache-control": "no-cache",
+    });
+    res.end(data);
+  } catch (err) {
+    reason = "unhandled error";
+    console.error("[serve] error:", err);
+    res.writeHead(500).end(String(err));
+  }
+});
+
+// ---------- modulepreload hints ----------
+//
+// Simple heuristic, no AST parsing:
+//   1. /dist/src/index.js — framework core, always needed
+//   2. /dist/examples/<EXAMPLE>/main.js — app entry
+//   3. /dist/examples/<EXAMPLE>/routes.js — route manifest
+//   4. /dist/examples/<EXAMPLE>/pages/*.js — all pages
+//      (without them the first router click waterfalls)
+//
+// Disable with PRELOAD=0. Limit to the core with PRELOAD=core.
+// Default is full (all pages).
+
+const PRELOAD = process.env.PRELOAD ?? "full";
+
+let cachedPreloadHints = null;
+let cachedPreloadAt = 0;
+const PRELOAD_CACHE_MS = HMR ? 1000 : 60_000;
+
+async function buildPreloadHints() {
+  if (PRELOAD === "0" || PRELOAD === "off" || PRELOAD === "false") return "";
+  const now = Date.now();
+  if (cachedPreloadHints !== null && now - cachedPreloadAt < PRELOAD_CACHE_MS) {
+    return cachedPreloadHints;
+  }
+  const hrefs = [];
+  // core
+  if (existsSync(join(ROOT, "dist/src/index.js"))) {
+    hrefs.push("/dist/src/index.js");
+  }
+  if (EXAMPLE) {
+    const exampleDist = join(ROOT, "dist", "examples", EXAMPLE);
+    for (const f of ["main.js", "routes.js"]) {
+      if (existsSync(join(exampleDist, f))) {
+        hrefs.push(`/dist/examples/${EXAMPLE}/${f}`);
+      }
+    }
+    if (PRELOAD === "full") {
+      const pagesDir = join(exampleDist, "pages");
+      if (existsSync(pagesDir)) {
+        try {
+          for (const file of await readdir(pagesDir)) {
+            if (file.endsWith(".js")) {
+              hrefs.push(`/dist/examples/${EXAMPLE}/pages/${file}`);
+            }
+          }
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  }
+  cachedPreloadHints = hrefs
+    .map((h) => `  <link rel="modulepreload" href="${h}">`)
+    .join("\n");
+  cachedPreloadAt = now;
+  return cachedPreloadHints;
+}
+
+server.on("error", (err) => {
+  console.error(`[serve] failed to listen on port ${PORT}: ${err.message}`);
+  process.exit(1);
+});
+
+server.listen(PORT, () => {
+  const distReady = existsSync(join(ROOT, "dist/src/index.js"));
+  console.log("");
+  console.log("Mado dev server");
+  console.log(`  url:      http://localhost:${PORT}/`);
+  console.log(`  root:     ${ROOT}`);
+  console.log(`  example:  ${EXAMPLE ? `examples/${EXAMPLE}/ -> /` : "examples/index.html landing"}`);
+  console.log(`  hmr:      ${HMR ? "on" : "off"}`);
+  console.log(`  preload:  ${PRELOAD}`);
+  console.log(`  dist:     ${distReady ? "ready" : "missing (run mado build)"}`);
+  if (!EXAMPLE) {
+    console.log("  try:      mado serve basic");
+    console.log("            mado serve showcase");
+    console.log("            mado serve tickets");
+  }
+  console.log("");
+});

package/starters/crud/README.md

@@ -0,0 +1,21 @@
+# __APP_NAME__
+
+Generated with the Mado CRUD starter.
+
+```bash
+npm install
+npm run build
+npm run serve
+```
+
+Open http://localhost:5173.
+
+This starter demonstrates:
+
+- lazy routes;
+- Web Components through `component()`;
+- query params through `queryParam()`;
+- async data through `resource()`;
+- mutations with invalidation;
+- forms through `useForm()`;
+- keyed tables through `each()`.