@madojs/mado 0.5.1 → 0.6.0

package/dist/src/signal.js

@@ -23,7 +23,48 @@
  *
  *   batch(() => { a.set(1); b.set(2); });
  */
+const MAX_FLUSH_RUNS_PER_SUBSCRIBER = 100;
 let activeTracker = null;
+class SubscriberSet extends Set {
+    onEmpty;
+    emptyScheduled = false;
+    constructor(onEmpty) {
+        super();
+        this.onEmpty = onEmpty;
+    }
+    add(entry) {
+        super.add(entry);
+        this.emptyScheduled = false;
+        return this;
+    }
+    delete(entry) {
+        const deleted = super.delete(entry);
+        if (deleted)
+            this.queueEmpty();
+        return deleted;
+    }
+    clear() {
+        const hadEntries = this.size > 0;
+        super.clear();
+        if (hadEntries)
+            this.queueEmpty();
+    }
+    queueEmpty() {
+        if (!this.onEmpty || this.size > 0 || this.emptyScheduled)
+            return;
+        this.emptyScheduled = true;
+        queueMicrotask(() => {
+            this.emptyScheduled = false;
+            if (this.size === 0)
+                this.onEmpty?.();
+        });
+    }
+}
+function cleanupTracker(tracker) {
+    for (const dep of tracker.deps)
+        dep.delete(tracker.entry);
+    tracker.deps.clear();
+}
 // ---------- Scheduler ----------
 const pending = new Set();
 let batchDepth = 0;
@@ -39,11 +80,20 @@ function schedule(sub) {
 }
 function flush() {
     flushScheduled = false;
+    const runCounts = new Map();
     // guard against Set modification during iteration
     while (pending.size > 0) {
         const subs = [...pending];
         pending.clear();
         for (const sub of subs) {
+            const runs = (runCounts.get(sub) ?? 0) + 1;
+            runCounts.set(sub, runs);
+            if (runs > MAX_FLUSH_RUNS_PER_SUBSCRIBER) {
+                // eslint-disable-next-line no-console
+                console.error("[mado] effect cycle detected: subscriber re-ran more than " +
+                    `${MAX_FLUSH_RUNS_PER_SUBSCRIBER} times in one flush.`);
+                continue;
+            }
             try {
                 sub();
             }
@@ -81,7 +131,7 @@ export function flushSync() {
 }
 export function signal(initial) {
     let value = initial;
-    const subscribers = new Set();
+    const subscribers = new SubscriberSet();
     const read = (() => {
         if (activeTracker) {
             subscribers.add(activeTracker.entry);
@@ -115,6 +165,7 @@ export function signal(initial) {
     };
     read.update = (fn) => read.set(fn(value));
     read.peek = () => value;
+    debugInfo.set(read, { subscribers });
     return read;
 }
 /**
@@ -131,17 +182,55 @@ export function signal(initial) {
  * instead of actually recomputing we mark ourselves dirty and
  * propagate to subscribers.
  */
-export function computed(fn) {
-    const subscribers = new Set();
+export function computed(fn, options = {}) {
     let value = undefined;
     let dirty = true;
+    let hasValue = false;
+    let computing = false;
     const onInvalidate = () => {
         // dep changed → mark dirty synchronously and cascade.
         // Sync subscribers (other computed) are triggered immediately — they also
         // set dirty without delay. Async (effects) go through the scheduler.
         if (dirty)
             return;
+        if (subscribers.size === 0) {
+            dirty = true;
+            suspend();
+            return;
+        }
+        if (options.equals && hasValue) {
+            const prevValue = value;
+            recompute();
+            if (options.equals(prevValue, value))
+                return;
+            notifySubscribers();
+            return;
+        }
         dirty = true;
+        notifySubscribers();
+    };
+    const tracker = {
+        deps: new Set(),
+        entry: { run: onInvalidate, sync: true },
+    };
+    const subscribers = new SubscriberSet(() => {
+        suspend();
+    });
+    const suspend = () => {
+        if (subscribers.size > 0)
+            return;
+        cleanupTracker(tracker);
+        dirty = true;
+    };
+    const queueSuspendIfUnobserved = () => {
+        if (subscribers.size > 0)
+            return;
+        queueMicrotask(() => {
+            if (subscribers.size === 0)
+                suspend();
+        });
+    };
+    const notifySubscribers = () => {
         const snapshot = [...subscribers];
         for (const e of snapshot) {
             if (e.sync) {
@@ -158,23 +247,24 @@ export function computed(fn) {
             }
         }
     };
-    const tracker = {
-        deps: new Set(),
-        entry: { run: onInvalidate, sync: true },
-    };
     const recompute = () => {
-        for (const dep of tracker.deps)
-            dep.delete(tracker.entry);
-        tracker.deps.clear();
+        if (computing) {
+            throw new Error("[mado] computed cycle detected");
+        }
+        cleanupTracker(tracker);
         const prev = activeTracker;
         activeTracker = tracker;
+        computing = true;
         try {
             value = fn();
         }
         finally {
+            computing = false;
             activeTracker = prev;
         }
         dirty = false;
+        hasValue = true;
+        queueSuspendIfUnobserved();
     };
     const read = (() => {
         if (activeTracker) {
@@ -190,14 +280,13 @@ export function computed(fn) {
             recompute();
         return value;
     };
+    debugInfo.set(read, { subscribers, tracker });
     return read;
 }
 export function effect(fn) {
     let cleanup;
     const run = () => {
-        for (const dep of tracker.deps)
-            dep.delete(tracker.entry);
-        tracker.deps.clear();
+        cleanupTracker(tracker);
         if (typeof cleanup === "function")
             cleanup();
         const prev = activeTracker;
@@ -215,9 +304,7 @@ export function effect(fn) {
     };
     run();
     return () => {
-        for (const dep of tracker.deps)
-            dep.delete(tracker.entry);
-        tracker.deps.clear();
+        cleanupTracker(tracker);
         if (typeof cleanup === "function")
             cleanup();
     };
@@ -235,4 +322,13 @@ export function untracked(fn) {
         activeTracker = prev;
     }
 }
+const debugInfo = new WeakMap();
+export const _testHooks = {
+    subscriberCount(source) {
+        return debugInfo.get(source)?.subscribers.size ?? 0;
+    },
+    dependencyCount(source) {
+        return debugInfo.get(source)?.tracker?.deps.size ?? 0;
+    },
+};
 //# sourceMappingURL=signal.js.map

package/dist/src/signal.js.map

@@ -1 +1 @@
-{"version":3,"file":"signal.js","sourceRoot":"","sources":["../../src/signal.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"signal.js","sourceRoot":"","sources":["../../src/signal.ts"],"names":[],"mappings":"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"}

package/docs/en/02-project-layout.md

@@ -1,58 +1,117 @@
 # Project layout
 
-Every new Mado project has the same structure. This is a **mandatory** convention.
+Every Mado app uses the same shape. This is a **mandatory** convention — it
+exists so that you, your teammates, and any LLM assistant always know where
+things live.
 
 ```
 my-app/
-├── package.json              # exactly 1 dep: typescript (esbuild optional)
-├── tsconfig.json             # with paths "@madojs/mado" → import without relative paths
-├── Dockerfile + nginx.conf   # copied from Mado/ on scaffold
-├── .gitlab-ci.yml | .github/workflows/ci.yml
-├── server/serve.mjs          # dev-server from Mado, no deps
-├── scripts/
-│   ├── bundle.mjs            # esbuild prod bundle
-│   └── new.mjs               # page scaffolder
-├── templates/                # templates for new.mjs
-├── docs/                     # project docs (can copy our guides)
-├── public/                   # static assets (favicon, manifests)
+├── package.json              # exactly one runtime dep: @madojs/mado
+├── tsconfig.json             # strict TS, ES2022, Bundler resolution
+├── mado.config.json          # single config file (dev/build/bake/bundle)
+├── index.html                # SPA shell (also the template for `mado bake`)
+├── public/                   # static assets (favicons, images, robots.txt)
 └── src/
-    ├── main.ts               # entry: providers + mount <x-app>
-    ├── routes.ts             # route manifest
-    ├── pages/                # one page = one file = `export default page({...})`
-    ├── components/           # reusable components (x-*)
-    ├── layouts/              # layout pages (for nested)
+    ├── main.ts               # entry: mount router into #app
+    ├── routes.ts             # route manifest (default + named `manifest`)
+    ├── layouts/              # `page({ child })` layouts for nested routes
+    ├── pages/                # one page = one file
+    ├── components/           # reusable x-* Web Components
     └── lib/
-        ├── api.ts            # all fetch wrappers
-        ├── contexts.ts       # createContext(...)
-        ├── theme.ts          # themes
-        └── ...               # utilities, types, business rules
+        ├── api.ts            # API client + error type
+        ├── auth.ts           # auth recipe (token + guard)
+        └── ...               # contexts, helpers, business rules
 ```
 
+## The three artifact states (read this once, never wonder again)
+
+| Folder      | What it is                                                     | Who writes        | Who reads                  | Deploy?           |
+|-------------|----------------------------------------------------------------|-------------------|----------------------------|-------------------|
+| `src/`      | your source (TypeScript)                                       | you               | `tsc`, `esbuild`           | ❌ no             |
+| `dist/`     | `tsc` output — native ESM `.js` for the browser                | `mado build`      | `mado dev` (during dev)    | ❌ no (internal)  |
+| `public/`   | static assets you authored (favicon, images, robots.txt)       | you               | `mado release` copies it   | ✅ via `out/`     |
+| `out/`      | **the deploy artifact**: SPA shell + bundles + baked HTML      | `mado release`    | nginx / CDN / Cloudflare   | ✅ **yes**        |
+
+One-liner to remember:
+> Develop with `mado dev`. To ship: run `mado release`, then upload `out/`.
+
+`mado release` = `typecheck` + `build` (tsc → `dist/`) + `bundle` (esbuild
+→ `out/assets/`) + `bake` (HTML → `out/baked/`) + copy `public/*` → `out/`.
+
+You almost never need to look inside `dist/`. It exists so the dev browser can
+load native ESM modules without a bundler during development. In production
+the equivalent code is bundled and hashed into `out/assets/`.
+
+### Quick deployment matrix
+
+| Target                | Command                              | Where it goes              |
+|-----------------------|--------------------------------------|----------------------------|
+| VPS + nginx           | `mado release && rsync -avz out/ …`  | `/var/www/<app>/`          |
+| Cloudflare Pages      | `mado release && wrangler pages deploy out` | CF Pages                 |
+| Netlify / S3 / GH Pages | `mado release && upload out/*`     | any static host            |
+
+See `docs/en/13-deployment.md` for full recipes.
+
 ## Where to put a new file?
 
-| What | Where |
-|---|---|
-| Page for a new URL | `src/pages/foo.ts` + add to `src/routes.ts` |
-| Reusable UI widget | `src/components/foo-bar.ts` |
-| API wrapper | `src/lib/api.ts` (add a method) |
-| Global context (theme, user, i18n) | `src/lib/<name>.ts` |
-| Pure function without UI | `src/lib/util/<name>.ts` |
+| What                                | Where                                                |
+|-------------------------------------|------------------------------------------------------|
+| Page for a new URL                  | `src/pages/<name>.ts` + add to `src/routes.ts`       |
+| Layout for a group of routes        | `src/layouts/<name>.ts` (referenced from `routes.ts`)|
+| Reusable UI widget                  | `src/components/<x-name>.ts`                         |
+| API call                            | `src/lib/api.ts` (add a method)                      |
+| Auth/session                        | `src/lib/auth.ts`                                    |
+| Global context (theme, user, i18n)  | `src/lib/<name>.ts`                                  |
+| Pure function with no UI            | `src/lib/util/<name>.ts`                             |
+| Static image / favicon              | `public/<file>`                                      |
 
-If you don't know where — that is a signal that **the architecture is suffering**.
-Ask the team, **record** the answer in `docs/`.
+If you don't know where — that is a signal that **the architecture is
+suffering**. Ask the team and **record** the answer in `docs/`. Don't invent a
+new top-level folder.
 
 ## Naming rules
 
-| What | Style | Example |
-|---|---|---|
-| File | kebab-case | `user-profile.ts` |
-| Component tag | `x-` + kebab | `<x-user-profile>` |
-| Context | PascalCase + `Ctx` | `ThemeCtx`, `AuthCtx` |
-| Signal | camelCase | `userId`, `isLoggedIn` |
-| Page function (internal component) | `x-<route>-page` | `<x-posts-page>` |
+| What                                | Style                | Example                |
+|-------------------------------------|----------------------|------------------------|
+| File                                | kebab-case           | `user-profile.ts`      |
+| Component tag                       | `x-` + kebab         | `<x-user-profile>`     |
+| Context                             | PascalCase + `Ctx`   | `ThemeCtx`, `AuthCtx`  |
+| Signal                              | camelCase            | `userId`, `isLoggedIn` |
+| Page-internal element               | `x-<route>-page`     | `<x-posts-page>`       |
+
+## `mado.config.json` in one screen
+
+```jsonc
+{
+  "dev": {
+    "port": 5173,
+    "proxy": { "/api": "http://localhost:3000" }   // dev → backend
+  },
+  "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"]
+  }
+}
+```
+
+Precedence: built-in defaults < `mado.config.json` < CLI flags
+(< legacy env vars). All keys are optional.
 
-## What does NOT go in src/
+## What does NOT go in `src/`
 
 - ❌ Build tool configs (webpack, rollup, vite) — we don't have any.
-- ❌ `.env` files — env is read from `process.env`/`import.meta.env` in `lib/config.ts`.
-- ❌ Tests mixed with code — all in `test/`.
+- ❌ `.env` files — read env in `src/lib/config.ts` from `import.meta.env` /
+  `process.env` and import that one module everywhere.
+- ❌ Tests mixed with code — put them in `test/`.
+- ❌ `examples/` folder — the framework repository has examples, your app
+  does not need one.

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

@@ -0,0 +1,141 @@
+# App architecture
+
+This is the default shape for a production Mado app. It is intentionally boring:
+one route manifest, one shell, one API client, one auth module, and page files
+that own their feature components.
+
+## File tree
+
+```txt
+src/
+├── main.ts
+├── routes.ts
+├── layouts/
+│   ├── app.ts
+│   └── auth.ts
+├── pages/
+│   ├── home.ts
+│   ├── login.ts
+│   ├── not-found.ts
+│   └── admin/
+│       ├── dashboard.ts
+│       ├── orders.ts
+│       └── order-detail.ts
+├── components/
+│   ├── x-button.ts
+│   └── x-input.ts
+├── lib/
+│   ├── api.ts
+│   └── auth.ts
+└── styles/
+    └── global.ts
+```
+
+Keep business logic in `lib/`, route wrapping in `layouts/`, and UI leaves in
+`components/`. A page should import the components it renders.
+
+## Entry point
+
+```ts
+// src/main.ts
+import { html, render } from "@madojs/mado";
+import "./styles/global.js";
+import "./components/x-button.js";
+import routesApi from "./routes.js";
+
+render(html`${routesApi.view}`, document.getElementById("app")!);
+```
+
+Import global providers and tiny shared components here. Do not bulk-import
+every feature component.
+
+## Routes
+
+```ts
+// src/routes.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"),
+      "/orders": () => import("./pages/admin/orders.js"),
+      "/orders/:id": () => import("./pages/admin/order-detail.js"),
+    },
+  }),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest, {
+  errorPage: (err) => html`<main><h1>Something went wrong</h1><pre>${err.message}</pre></main>`,
+});
+```
+
+Exporting `manifest` lets `mado bake` inspect the same route table.
+
+## API and auth
+
+Use one API client and one auth module. The admin starter ships a complete
+version with token storage, a single-flight refresh request, and a route guard.
+
+```ts
+// pages/admin/orders.ts
+import { each, html, page, resource } from "@madojs/mado";
+import { api } from "../../lib/api.js";
+
+const orders = resource(() => "/api/orders", () => api.get("/orders"));
+
+export default page({
+  title: "Orders",
+  view: () => html`
+    <main>
+      <h1>Orders</h1>
+      <ul>
+        ${() => each(orders.data() ?? [], o => o.id, o => html`<li>${o.number}</li>`)}
+      </ul>
+    </main>
+  `,
+});
+```
+
+Mutations should declare invalidation near the write:
+
+```ts
+const save = mutation((payload) => api.post("/orders", payload), {
+  invalidates: ["/api/orders*"],
+});
+```
+
+## Forms
+
+Prefer one `useForm()` per user workflow.
+
+```ts
+const form = useForm({
+  email: { required: true, type: "email" },
+  "items.*.title": { required: true },
+});
+const items = form.array("items");
+```
+
+Use dotted paths for arrays (`items.0.title`) and keep async validation in
+`validateAsync` when it talks to the backend.
+
+## Release
+
+Local development uses `mado dev`. Production uses exactly one artifact:
+
+```bash
+mado release
+rsync -avz out/ user@server:/var/www/app/
+```
+
+`out/` is the deploy folder. `dist/` is internal build output.

package/docs/en/11-layouts.md

@@ -0,0 +1,115 @@
+# Layouts
+
+> **One blessed path.** Layouts in Mado are nested-route groups with a shared
+> shell. There is exactly one canonical place to declare a layout — your
+> `routes.ts` manifest. Putting layout code anywhere else (in `main.ts`, in a
+> page view, in a global custom-element wrapper) is a bug pattern: the LLM and
+> the human both produce visually broken UI when they guess differently.
+
+## The canonical recipe
+
+```ts
+// src/routes.ts
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./lib/auth.js";
+
+export const manifest = {
+  "/":       () => import("./pages/home.js"),       // no layout
+  "/login": layout({
+    layout:  () => import("./layouts/auth.js"),     // centered card
+    routes:  { "/": () => import("./pages/login.js") },
+  }),
+  "/admin": layout({
+    layout:  () => import("./layouts/app.js"),      // admin shell
+    guard:   requireAuth,                           // ← see 12-auth-and-api.md
+    routes: {
+      "/":           () => import("./pages/admin/dashboard.js"),
+      "/orders":     () => import("./pages/admin/orders.js"),
+      "/orders/:id": () => import("./pages/admin/order-detail.js"),
+    },
+  }),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest);
+```
+
+A layout is just a `page({ view })` that renders `${ctx.child}` somewhere:
+
+```ts
+// src/layouts/app.ts
+import { html, page } from "@madojs/mado";
+import "../components/app-shell.js";   // <x-app-shell> (sidebar + topbar + slot)
+
+export default page({
+  view: ({ child }) => html`
+    <x-app-shell>${child}</x-app-shell>
+  `,
+});
+```
+
+That is the whole API.
+
+- **Order of layouts** matters: outer groups wrap inner groups. The order in
+  the manifest is exactly the order of rendering.
+- **One shell per group**, not one shell per page. If you want a different
+  shell for a subtree, create a new group with its own `layout`.
+- **Layouts can be lazy** (`() => import(...)`). They are loaded together
+  with the page.
+
+## Why "one blessed path"
+
+Without this convention, every page accumulates `<x-app-shell>${...}</x-app-shell>`
+boilerplate, the LLM eventually puts the shell wrapper into `main.ts` "to make
+it consistent", and the next refactor produces the classic
+*"navigation appears below the page content"* screenshot. The nested-routes
+recipe makes the shell the **outer frame** structurally; there is no way to
+re-order it by accident.
+
+## Two acceptable alternatives (with caveats)
+
+These exist for completeness. Reach for them only if you cannot use nested
+routes.
+
+### a) A single shell with the router slot in `main.ts`
+
+```ts
+import { html, render } from "@madojs/mado";
+import "./components/app-shell.js";
+import router from "./routes.js";
+
+render(html`<x-app-shell>${router.view}</x-app-shell>`, app);
+```
+
+Caveat: every route now lives inside one shell. You cannot have a centered
+login page or a marketing landing page without the admin chrome around it.
+Use this only for single-shell apps.
+
+### b) Per-page wrapping inside `view`
+
+```ts
+export default page({
+  view: () => html`
+    <x-app-shell>
+      <h1>Orders</h1>
+      ...
+    </x-app-shell>
+  `,
+});
+```
+
+Caveat: repetition. Every new page must remember the wrapper. The first time
+someone forgets it, the layout disappears and the LLM "fixes" it in the wrong
+place. **Do not start with this.**
+
+## Where to find more
+
+- `src/page.ts` defines `layout()`, `page()`, `Guard` and `NestedRoutes`.
+- `src/router/manifest.ts` flattens the nested manifest and applies guards
+  outer → inner before the page renders.
+- The `admin` starter (`mado init my-app --starter admin`) ships with three
+  groups (`/`, `/login`, `/admin`) and is the reference implementation.
+
+If you ever feel tempted to invent a fourth pattern, write it down in your
+project `docs/` first and discuss it with the team. The cost of inconsistency
+in this exact spot is higher than the cost of a slightly awkward layout.