@madojs/mado 0.5.1 → 0.6.0

package/docs/ru/16-bake-cookbook.md

@@ -0,0 +1,55 @@
+# Bake cookbook
+
+`mado bake` рендерит выбранные роуты в статический HTML. Это для SEO и быстрого
+первого ответа, не SSR с hydration.
+
+## Минимальная страница
+
+```ts
+export default page({
+  head: () => ({ title: "Products", description: "Catalog" }),
+  view: ({ data }) => html`
+    <main>
+      <h1>Products</h1>
+      ${data.products.map((p) => html`<article><h2>${p.name}</h2></article>`)}
+    </main>
+  `,
+  bake: {
+    paths: () => [{}],
+    data: async () => ({ products: await api.products() }),
+    revalidate: 3600,
+  },
+});
+```
+
+В baked views лучше использовать обычные массивы (`items.map(...)`). Runtime
+директивы вроде `each()` нужны браузеру.
+
+## Dynamic routes
+
+```ts
+export default page<{ slug: string }>({
+  head: ({ slug }, data) => ({ title: data.title, canonical: `/blog/${slug}` }),
+  view: ({ data }) => html`<article>${unsafeHTML(data.html)}</article>`,
+  bake: {
+    paths: async () => (await api.posts()).map((p) => ({ slug: p.slug })),
+    data: ({ slug }) => api.post(slug),
+  },
+});
+```
+
+`unsafeHTML()` используй только для доверенного или заранее очищенного HTML.
+
+## Manifest и output
+
+```ts
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/blog/:slug": () => import("./pages/blog-post.js"),
+};
+export default routes(manifest);
+```
+
+`mado release` создает deploy artifact в `out/`. Если bake ругается на
+unsupported value, значит в статическую страницу попало runtime-only значение:
+замени `each()` на `items.map(...)` или вынеси интерактивный кусок в клиент.

package/docs/ru/README.md

@@ -12,3 +12,10 @@
 | LLM pitfalls | [07-llm-pitfalls.md](./07-llm-pitfalls.md) |
 | LLM zero-history test | [08-llm-zero-history-test.md](./08-llm-zero-history-test.md) |
 | Shadow DOM vs Light DOM | [09-shadow-vs-light-dom.md](./09-shadow-vs-light-dom.md) |
+| Архитектура приложения | [10-app-architecture.md](./10-app-architecture.md) |
+| Layouts | [11-layouts.md](./11-layouts.md) |
+| Auth and API | [12-auth-and-api.md](./12-auth-and-api.md) |
+| Deployment | [13-deployment.md](./13-deployment.md) |
+| Тестирование | [14-testing.md](./14-testing.md) |
+| Обработка ошибок | [15-error-handling.md](./15-error-handling.md) |
+| Bake cookbook | [16-bake-cookbook.md](./16-bake-cookbook.md) |

package/docs/uk/10-app-architecture.md

@@ -0,0 +1,56 @@
+# Архітектура застосунку
+
+Production-застосунок на Mado має бути простим: один manifest маршрутів, один
+shell, один API-клієнт, один auth-модуль і сторінки, які імпортують власні
+компоненти.
+
+```txt
+src/
+├── main.ts
+├── routes.ts
+├── layouts/
+├── pages/
+├── components/
+├── lib/
+└── styles/
+```
+
+`lib/` — бізнес-логіка, `layouts/` — обгортки груп маршрутів, `components/` —
+повторні UI-теги, `pages/` — один файл на сторінку.
+
+```ts
+import { html, render } from "@madojs/mado";
+import "./styles/global.js";
+import routesApi from "./routes.js";
+
+render(html`${routesApi.view}`, document.getElementById("app")!);
+```
+
+Feature-компоненти імпортує сторінка, яка їх рендерить.
+
+```ts
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./lib/auth.js";
+
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/admin": layout({
+    layout: () => import("./layouts/app.js"),
+    guard: requireAuth,
+    routes: { "/": () => import("./pages/admin/dashboard.js") },
+  }),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest);
+```
+
+`manifest` потрібен для `mado bake`. Для читання використовуй `resource()`, для
+запису `mutation(..., { invalidates })`, для форм `useForm()`.
+
+```bash
+mado dev
+mado release
+```
+
+Деплоїться `out/`, а не `dist/`.

package/docs/uk/11-layouts.md

@@ -0,0 +1,34 @@
+# Layouts
+
+Рекомендований спосіб layout у Mado — вкладена група маршрутів у `routes.ts`.
+
+```ts
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./lib/auth.js";
+
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/login": layout({
+    layout: () => import("./layouts/auth.js"),
+    routes: { "/": () => import("./pages/login.js") },
+  }),
+  "/admin": layout({
+    layout: () => import("./layouts/app.js"),
+    guard: requireAuth,
+    routes: { "/": () => import("./pages/admin/dashboard.js") },
+  }),
+};
+
+export default routes(manifest);
+```
+
+Layout — це `page({ view })`, яка рендерить `child`:
+
+```ts
+export default page({
+  view: ({ child }) => html`<x-app-shell>${child}</x-app-shell>`,
+});
+```
+
+Один shell на групу, не на кожну сторінку. Guard на групі захищає все
+піддерево.

package/docs/uk/12-auth-and-api.md

@@ -0,0 +1,34 @@
+# Auth та API
+
+Starter `admin` містить рекомендований рецепт:
+
+- `src/lib/api.ts` — один HTTP-клієнт, `ApiError`, refresh після 401;
+- `src/lib/auth.ts` — `accessToken`, `restoreSession()`, `login()`,
+  `logout()`, `requireAuth`.
+
+Модель:
+
+- access token у пам'яті через `signal`, не в `localStorage`;
+- HttpOnly refresh cookie відновлює сесію;
+- усі запити проходять через API-клієнт;
+- захищені routes використовують group guard.
+
+```ts
+export const requireAuth: Guard = async ({ path }) => {
+  if (accessToken()) return;
+  if (await restoreSession()) return;
+  return { redirect: `/login?return=${encodeURIComponent(path)}`, replace: true };
+};
+```
+
+Dev proxy:
+
+```jsonc
+{
+  "dev": {
+    "proxy": { "/api": "http://localhost:3000" }
+  }
+}
+```
+
+Якщо backend має іншу auth-схему, змінюй `api.ts`/`auth.ts`, а не сторінки.

package/docs/uk/13-deployment.md

@@ -0,0 +1,39 @@
+# Deployment
+
+Одна команда, один artifact:
+
+```bash
+mado release
+```
+
+Результат:
+
+```txt
+out/
+├── index.html
+├── assets/
+├── baked/
+├── _redirects
+└── _headers
+```
+
+`out/` можна деплоїти на nginx, Cloudflare Pages, Netlify, S3/CloudFront або
+GitHub Pages.
+
+```bash
+mado release
+mado preview
+```
+
+`mado preview` показує `out/` як статичний хост: baked HTML має пріоритет,
+потім SPA fallback.
+
+Для VPS + nginx:
+
+```bash
+mado release
+rsync -avz --delete out/ user@server:/var/www/myapp/
+```
+
+Наданий `nginx.conf` налаштовує immutable cache для hash bundles, no-cache для
+HTML та fallback для deep links.

package/docs/uk/14-testing.md

@@ -0,0 +1,34 @@
+# Тестування
+
+Mado — це TypeScript і browser APIs. У репозиторії фреймворка тести йдуть через
+Node test runner та `linkedom`.
+
+```bash
+npm run typecheck
+npm run build
+npm test
+```
+
+DOM-тест:
+
+```js
+import test from "node:test";
+import assert from "node:assert/strict";
+
+const { parseHTML } = await import("linkedom");
+const { window } = parseHTML("<!doctype html><html><body></body></html>");
+globalThis.window = window;
+globalThis.document = window.document;
+
+const { html, render } = await import("../dist/src/html.js");
+
+test("renders", () => {
+  const root = document.createElement("div");
+  render(html`<p>${"hello"}</p>`, root);
+  assert.equal(root.querySelector("p").textContent, "hello");
+});
+```
+
+Покривай signals/computed/effect, HTML bindings, guards/redirects, scroll/focus,
+error boundaries, forms, resources/mutations і CLI-команди `mado release`,
+`mado bake`, `mado preview`.

package/docs/uk/15-error-handling.md

@@ -0,0 +1,32 @@
+# Обробка помилок
+
+Обробляй помилки там, де користувач може відновитися: маршрути, дані, дії
+користувача.
+
+```ts
+export default routes(manifest, {
+  errorPage: (err) => html`
+    <main>
+      <h1>Щось пішло не так</h1>
+      <pre>${err.message}</pre>
+      <a data-link href="/">На головну</a>
+    </main>
+  `,
+});
+```
+
+`page({ errorView })` має пріоритет над глобальною boundary.
+
+```ts
+const users = resource(() => "/api/users", jsonFetcher<User[]>());
+
+html`
+  ${() => users.error()
+    ? html`<p role="alert">${users.error()!.message}</p>
+         <button @click=${users.refresh}>Повторити</button>`
+    : null}
+`;
+```
+
+Валідація належить `useForm()`, помилки запису — поруч із submit-кнопкою.
+Зовнішні browser subscriptions очищай через `ctx.onDispose()`.

package/docs/uk/16-bake-cookbook.md

@@ -0,0 +1,36 @@
+# Bake cookbook
+
+`mado bake` рендерить вибрані маршрути у статичний HTML. Це для SEO та швидкого
+першого рендеру, не SSR з hydration.
+
+```ts
+export default page({
+  head: () => ({ title: "Products", description: "Catalog" }),
+  view: ({ data }) => html`
+    <main>
+      <h1>Products</h1>
+      ${data.products.map((p) => html`<article><h2>${p.name}</h2></article>`)}
+    </main>
+  `,
+  bake: {
+    paths: () => [{}],
+    data: async () => ({ products: await api.products() }),
+    revalidate: 3600,
+  },
+});
+```
+
+У baked views краще використовувати звичайні масиви (`items.map(...)`).
+Runtime-директиви на кшталт `each()` потрібні браузеру.
+
+```ts
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/blog/:slug": () => import("./pages/blog-post.js"),
+};
+export default routes(manifest);
+```
+
+`mado release` створює deploy artifact у `out/`. Якщо bake повідомляє про
+unsupported value, винеси runtime-only частину в клієнт або заміни її на
+серіалізований HTML.

package/docs/uk/README.md

@@ -14,3 +14,10 @@
 | Типові помилки LLM | [07-llm-pitfalls.md](./07-llm-pitfalls.md) |
 | LLM zero-history тест | [08-llm-zero-history-test.md](./08-llm-zero-history-test.md) |
 | Shadow DOM vs Light DOM | [09-shadow-vs-light-dom.md](./09-shadow-vs-light-dom.md) |
+| Архітектура застосунку | [10-app-architecture.md](./10-app-architecture.md) |
+| Layouts | [11-layouts.md](./11-layouts.md) |
+| Auth та API | [12-auth-and-api.md](./12-auth-and-api.md) |
+| Deployment | [13-deployment.md](./13-deployment.md) |
+| Тестування | [14-testing.md](./14-testing.md) |
+| Обробка помилок | [15-error-handling.md](./15-error-handling.md) |
+| Bake cookbook | [16-bake-cookbook.md](./16-bake-cookbook.md) |

package/llms.txt

@@ -143,6 +143,13 @@ export default page({
 - docs/en/05-why-mado.md — honest comparison with Lit / Solid / Svelte / htmx / Alpine / React
 - docs/en/06-for-backenders.md — mental model in 10 minutes for Go/Rust/.NET/Java developers
 - docs/en/07-llm-pitfalls.md — common mistakes when generating Mado code
+- docs/en/10-app-architecture.md — canonical app file layout, routes, auth/API and release shape
+- docs/en/11-layouts.md — blessed layout recipe
+- docs/en/12-auth-and-api.md — blessed auth/API client recipe
+- docs/en/13-deployment.md — deployment recipes and cache rules
+- docs/en/14-testing.md — testing strategy and commands
+- docs/en/15-error-handling.md — route/data/action error boundaries
+- docs/en/16-bake-cookbook.md — static bake recipes and failure modes
 - examples/basic/ — minimal API tour
 - examples/tickets/ — LLM zero-history CRUD validation
 - examples/showcase/ — flagship CRM pressure app (auth, nested routes, forms, mutations)
@@ -163,7 +170,8 @@ export default page({
 
 ## Version
 
-`0.5.0` — early, API may change before 1.0. Semver is not guaranteed on minor versions before 1.0.
+`0.6.0` — pre-1.0 product-surface release. API may still change before 1.0.
+Semver is not guaranteed on minor versions before 1.0.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madojs/mado",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Mado — a small native-web SPA framework with Web Components, signals, tagged-template html, router, resources, and forms. TypeScript-only build, zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
@@ -48,7 +48,9 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
+    "MADO_V1_PLAN.md",
     "ROADMAP.md",
+    "TODO.md",
     "AGENTS.md",
     "llms.txt",
     "docs/**/*.md"

package/scripts/_config.mjs

@@ -0,0 +1,224 @@
+// Mado configuration loader.
+//
+// Single source of project configuration for `mado dev`, `mado build`,
+// `mado bundle`, `mado bake`, `mado preview`, `mado release`.
+//
+// Lookup order (first hit wins):
+//   1. `mado.config.json`  in PROJECT_ROOT (recommended)
+//   2. built-in defaults
+//
+// CLI flags always override file values, file values override defaults.
+//
+// Context detection:
+//   - "app"  : a user project that depends on `@madojs/mado`
+//   - "repo" : the framework repository itself (has src/index.ts and examples/)
+//
+// In app-mode, defaults assume the canonical layout from MADO_V1_PLAN.md:
+//   src/routes.ts  index.html  public/  dist/  out/
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * @typedef {Object} MadoDevConfig
+ * @property {number} [port]
+ * @property {Record<string,string>} [proxy]   // path → upstream base URL
+ *
+ * @typedef {Object} MadoBuildConfig
+ * @property {string} [out]                    // deploy artifact dir (default: "out")
+ * @property {string} [dist]                   // tsc output dir (default: "dist")
+ * @property {string} [publicDir]              // static assets dir (default: "public")
+ *
+ * @typedef {Object} MadoBakeConfig
+ * @property {string} [entry]                  // routes module (default: "src/routes.ts")
+ * @property {string} [template]               // SPA shell html (default: "index.html")
+ * @property {string} [baseUrl]                // canonical/sitemap base
+ * @property {string} [outDir]                 // override (default: build.out + "/baked")
+ *
+ * @typedef {Object} MadoBundleConfig
+ * @property {boolean} [splitting]
+ * @property {Array<"gz"|"br">} [compress]
+ *
+ * @typedef {Object} MadoConfig
+ * @property {"app"|"repo"} context
+ * @property {string} projectRoot
+ * @property {MadoDevConfig}    dev
+ * @property {MadoBuildConfig}  build
+ * @property {MadoBakeConfig}   bake
+ * @property {MadoBundleConfig} bundle
+ */
+
+/**
+ * Detect whether we are inside the framework repository or inside a user app.
+ *
+ * Heuristic: the framework repo has both `src/index.ts` and an `examples/`
+ * directory at PROJECT_ROOT. Anything else is treated as an app.
+ *
+ * @param {string} projectRoot
+ * @returns {"app"|"repo"}
+ */
+export function detectContext(projectRoot) {
+  const looksLikeRepo =
+    existsSync(join(projectRoot, "src/index.ts")) &&
+    existsSync(join(projectRoot, "examples")) &&
+    existsSync(join(projectRoot, "package.json")) &&
+    safeReadJson(join(projectRoot, "package.json"))?.name === "@madojs/mado";
+  return looksLikeRepo ? "repo" : "app";
+}
+
+/**
+ * Built-in defaults per context.
+ *
+ * @param {"app"|"repo"} context
+ * @returns {MadoConfig}
+ */
+function defaults(context) {
+  if (context === "repo") {
+    return {
+      context,
+      projectRoot: "",
+      dev:    { port: 5173, proxy: {} },
+      build:  { out: "out", dist: "dist", publicDir: "public" },
+      bake:   {
+        entry: "examples/basic/routes.ts",
+        template: "examples/index.html",
+        baseUrl: "https://example.com",
+      },
+      bundle: { splitting: true, compress: ["gz", "br"] },
+    };
+  }
+  return {
+    context,
+    projectRoot: "",
+    dev:    { port: 5173, proxy: {} },
+    build:  { out: "out", dist: "dist", publicDir: "public" },
+    bake:   {
+      entry: "src/routes.ts",
+      template: "index.html",
+      baseUrl: "https://example.com",
+    },
+    bundle: { splitting: true, compress: ["gz", "br"] },
+  };
+}
+
+/**
+ * Load and merge configuration for the given project root.
+ *
+ * Precedence (low → high): defaults, mado.config.json, CLI overrides.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.projectRoot=process.cwd()]
+ * @param {Partial<MadoConfig>} [opts.overrides]
+ * @returns {MadoConfig}
+ */
+export function loadConfig(opts = {}) {
+  const projectRoot = resolve(opts.projectRoot ?? process.cwd());
+  const context = detectContext(projectRoot);
+  const base = defaults(context);
+  base.projectRoot = projectRoot;
+
+  const file = join(projectRoot, "mado.config.json");
+  const fromFile = existsSync(file) ? safeReadJson(file) ?? {} : {};
+
+  const merged = deepMerge(base, fromFile);
+  if (opts.overrides) deepMerge(merged, opts.overrides);
+
+  merged.context = context;
+  merged.projectRoot = projectRoot;
+  return merged;
+}
+
+/**
+ * Resolve a project-relative path against `projectRoot`. Absolute paths are
+ * returned unchanged.
+ *
+ * @param {MadoConfig} cfg
+ * @param {string} p
+ * @returns {string}
+ */
+export function resolveProjectPath(cfg, p) {
+  if (!p) return cfg.projectRoot;
+  return resolve(cfg.projectRoot, p);
+}
+
+/**
+ * @param {MadoConfig} cfg
+ * @returns {string}
+ */
+export function getPackageRoot() {
+  return PACKAGE_ROOT;
+}
+
+// ---------- helpers ----------
+
+function safeReadJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    console.warn(`[mado] failed to parse ${path}: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Shallow-deep merge: objects are merged recursively, arrays and primitives
+ * are replaced. Mutates `target` and returns it.
+ */
+function deepMerge(target, source) {
+  if (!source || typeof source !== "object") return target;
+  for (const [k, v] of Object.entries(source)) {
+    if (v === undefined) continue;
+    if (
+      v !== null &&
+      typeof v === "object" &&
+      !Array.isArray(v) &&
+      target[k] &&
+      typeof target[k] === "object" &&
+      !Array.isArray(target[k])
+    ) {
+      deepMerge(target[k], v);
+    } else {
+      target[k] = v;
+    }
+  }
+  return target;
+}
+
+/**
+ * Tiny argv parser shared by CLI subcommands.
+ *
+ * Recognises `--key=value`, `--key value`, and `--flag` (boolean).
+ * Unknown leading positionals are returned in `positional`.
+ *
+ * @param {string[]} argv
+ * @returns {{ flags: Record<string, string|boolean>, positional: string[] }}
+ */
+export function parseFlags(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 > -1) {
+        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 };
+}