@madojs/mado 0.7.0 → 0.9.0

package/docs/en/05-why-mado.md

@@ -1,22 +1,27 @@
 # Why Mado (and why not Lit / Solid / Alpine / htmx)
 
-> If you are choosing a frontend stack for a new project, this page is for you.  
-> If you already have something working — **don't migrate for the sake of migration**, it always costs more than it seems.
+> If you are choosing a frontend stack for an admin panel, internal tool or
+> business SPA, this page is for you.  
+> If you already have something working — **don't migrate for the sake of
+> migration**, it always costs more than it seems.
 
-Mado is not a "killer" of React/Vue/Svelte. It is a narrowly specialized tool. Here I honestly explain **in which cases Mado is genuinely better than the alternatives**, and in which it is not.
+Mado is not a "killer" of React/Vue/Svelte. It is a focused tool for teams that
+want a complete app stack (routing, forms, data, state, prerender) without
+frontend infrastructure overhead. Here is an honest comparison of **when Mado is
+genuinely better than the alternatives**, and when it is not.
 
 ---
 
 ## TL;DR — one table
 
-| If you care about… | Choose |
-|---|---|
-| Best learning infrastructure / huge ecosystem | **React** or **Vue** |
-| Component design system for embedding into any framework | **Lit** |
-| Top performance on large lists, "close to vanilla" with JSX | **Solid** or **Svelte 5** |
-| Progressive enhancement of classic server-rendered apps | **htmx** + your backend |
-| "Sprinkling" reactivity onto a static site | **Alpine.js** |
-| Minimal tooling, maximum platform, everything in one box (router + data + forms + SEO), readable in an evening | **Mado** ✓ |
+| If you care about…                                                                                             | Choose                    |
+| -------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| Best learning infrastructure / huge ecosystem                                                                  | **React** or **Vue**      |
+| Component design system for embedding into any framework                                                       | **Lit**                   |
+| Top performance on large lists, "close to vanilla" with JSX                                                    | **Solid** or **Svelte 5** |
+| Progressive enhancement of classic server-rendered apps                                                        | **htmx** + your backend   |
+| "Sprinkling" reactivity onto a static site                                                                     | **Alpine.js**             |
+| Minimal tooling, maximum platform, everything in one box (router + data + forms + SEO), readable in an evening | **Mado** ✓                |
 
 If your case does not fall into the last point — Mado is most likely not the best choice. That's fine.
 
@@ -26,21 +31,21 @@ If your case does not fall into the last point — Mado is most likely not the b
 
 **Lit** is the closest alternative in spirit. Same approach: Web Components + tagged templates + minimal magic.
 
-| | Lit | Mado |
-|---|---|---|
-| Size | ~6 KB | ~16 KB |
-| Age / support | ~10 years, Google | 6 months, single author |
-| Reactivity | `@property` decorators + manual `requestUpdate` | signals (`signal`/`computed`/`effect`) out of the box |
-| Router | none, you need to find one (`@lit-labs/router`, etc) | included: `routes()` + nested + prefetch + sync-cache |
-| Data fetching | none, you need to assemble it | `resource()` + `mutation()` + glob invalidation |
-| Forms | none | `useForm()` with HTML-like constraints |
-| SEO / static | complex (`@lit-labs/ssr`) | `bake` (linkedom) + edge-prerender |
-| Build | needs esbuild/rollup/webpack | `tsc` is enough |
-| Code style | classes + decorators | functions + tagged templates |
-| Ecosystem | real (Shoelace, Material Web, etc.) | none |
+|                | Lit                                                            | Mado                                                   |
+| -------------- | -------------------------------------------------------------- | ------------------------------------------------------ |
+| Size           | ~6 KB                                                          | ~16 KB                                                 |
+| Age / support  | ~10 years, Google                                              | 6 months, single author                                |
+| Reactivity     | `@property` decorators + manual `requestUpdate`                | signals (`signal`/`computed`/`effect`) out of the box  |
+| Router         | none, you need to find one (`@lit-labs/router`, etc)           | included: `routes()` + nested + prefetch + sync-cache  |
+| Data fetching  | none, you need to assemble it                                  | `resource()` + `mutation()` + glob invalidation        |
+| Forms          | none                                                           | `useForm()` with HTML-like constraints                 |
+| SEO / static   | complex (`@lit-labs/ssr`)                                      | `bake` (linkedom) + edge-prerender                     |
+| Build          | needs esbuild/rollup/webpack                                   | `tsc` is enough                                        |
+| Code style     | classes + decorators                                           | functions + tagged templates                           |
+| Ecosystem      | real (Shoelace, Material Web, etc.)                            | none                                                   |
 | When to choose | writing a design system / Web Components library for embedding | writing a full application, want everything in one box |
 
-**Honest pitch:** *"Lit is better if you're writing a component design system. Mado is better if you're writing an application and want batteries included without assembling 8 packages."*
+**Honest pitch:** _"Lit is better if you're writing a component design system. Mado is better if you're writing an application and want batteries included without assembling 8 packages."_
 
 ---
 
@@ -48,21 +53,21 @@ If your case does not fall into the last point — Mado is most likely not the b
 
 **Solid** is a top-tier reactive library built on signals. Technically very impressive.
 
-| | Solid | Mado |
-|---|---|---|
-| Size | ~7 KB | ~16 KB |
-| Performance | top-3 on js-framework-benchmark | good, but not top |
-| Reactivity | signals (same class of ideas) | signals |
-| Templates | JSX (compiled to reactive expressions) | tagged template `html\`\`` |
-| Component model | functions, Solid virtual nodes | Web Components |
-| Build | Vite + babel-plugin-solid required | `tsc` only |
-| Router | `@solidjs/router` | included |
-| Data | `createResource` | `resource()` |
-| SSR | seriously supported (SolidStart) | intentionally none |
-| Ecosystem | growing, ~50 packages | none |
-| When to choose | need top performance + JSX + willing to configure the build | want to run without a build / minimal infrastructure |
-
-**Honest pitch:** *"Solid is technically faster and more mature. But Solid requires Vite + a babel plugin. Mado requires nothing but `tsc` — it's 'open VS Code, F5, and work'. If that difference isn't critical — go with Solid."*
+|                 | Solid                                                       | Mado                                                 |
+| --------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
+| Size            | ~7 KB                                                       | ~16 KB                                               |
+| Performance     | top-3 on js-framework-benchmark                             | good, but not top                                    |
+| Reactivity      | signals (same class of ideas)                               | signals                                              |
+| Templates       | JSX (compiled to reactive expressions)                      | tagged template `html\`\``                           |
+| Component model | functions, Solid virtual nodes                              | Web Components                                       |
+| Build           | Vite + babel-plugin-solid required                          | `tsc` only                                           |
+| Router          | `@solidjs/router`                                           | included                                             |
+| Data            | `createResource`                                            | `resource()`                                         |
+| SSR             | seriously supported (SolidStart)                            | intentionally none                                   |
+| Ecosystem       | growing, ~50 packages                                       | none                                                 |
+| When to choose  | need top performance + JSX + willing to configure the build | want to run without a build / minimal infrastructure |
+
+**Honest pitch:** _"Solid is technically faster and more mature. But Solid requires Vite + a babel plugin. Mado requires nothing but `tsc` — it's 'open VS Code, F5, and work'. If that difference isn't critical — go with Solid."_
 
 ---
 
@@ -70,17 +75,17 @@ If your case does not fall into the last point — Mado is most likely not the b
 
 **Svelte 5** with runes — also a signal model, also minimalist.
 
-| | Svelte 5 | Mado |
-|---|---|---|
-| Runtime size | ~3 KB | ~16 KB |
-| Compiler | required (.svelte → JS) | none |
-| Syntax | custom .svelte format | TS + tagged templates |
-| Reactivity | `$state`/`$derived` (runes) | `signal`/`computed` |
-| SSR / SvelteKit | full-featured, mature | intentionally none |
-| Ecosystem | large, excellent dev-tools | none |
-| When to choose | new production project with a team | private/internal tool, need simplicity |
+|                 | Svelte 5                           | Mado                                   |
+| --------------- | ---------------------------------- | -------------------------------------- |
+| Runtime size    | ~3 KB                              | ~16 KB                                 |
+| Compiler        | required (.svelte → JS)            | none                                   |
+| Syntax          | custom .svelte format              | TS + tagged templates                  |
+| Reactivity      | `$state`/`$derived` (runes)        | `signal`/`computed`                    |
+| SSR / SvelteKit | full-featured, mature              | intentionally none                     |
+| Ecosystem       | large, excellent dev-tools         | none                                   |
+| When to choose  | new production project with a team | private/internal tool, need simplicity |
 
-**Honest pitch:** *"Svelte is a product choice. Mado is an engineering one. If you have a team and a production app — Svelte. If you're alone and want control — Mado."*
+**Honest pitch:** _"Svelte is a product choice. Mado is an engineering one. If you have a team and a production app — Svelte. If you're alone and want control — Mado."_
 
 ---
 
@@ -88,17 +93,17 @@ If your case does not fall into the last point — Mado is most likely not the b
 
 **htmx** is a different school: HTML-fragments over the wire.
 
-| | htmx | Mado |
-|---|---|---|
-| Architecture | HTML from server, updated via fragments | SPA: JS loads data, renders itself |
-| Backend dependency | strong (backend must be able to serve HTML) | weak (backend is a JSON API) |
-| Client state | minimal (cookies, localStorage) | full (signal, persisted) |
-| Optimistic updates | difficult | easy (mutation + invalidates) |
-| Offline / PWA | poor | decent |
-| Size | ~14 KB | ~16 KB |
-| When to choose | classic server-rendered app (Rails, Django, Phoenix), need to "liven up" | SPA experience is required, backend is REST/GraphQL |
+|                    | htmx                                                                     | Mado                                                |
+| ------------------ | ------------------------------------------------------------------------ | --------------------------------------------------- |
+| Architecture       | HTML from server, updated via fragments                                  | SPA: JS loads data, renders itself                  |
+| Backend dependency | strong (backend must be able to serve HTML)                              | weak (backend is a JSON API)                        |
+| Client state       | minimal (cookies, localStorage)                                          | full (signal, persisted)                            |
+| Optimistic updates | difficult                                                                | easy (mutation + invalidates)                       |
+| Offline / PWA      | poor                                                                     | decent                                              |
+| Size               | ~14 KB                                                                   | ~16 KB                                              |
+| When to choose     | classic server-rendered app (Rails, Django, Phoenix), need to "liven up" | SPA experience is required, backend is REST/GraphQL |
 
-**Honest pitch:** *"htmx — if the backend is solid and can serve HTML. Mado — if the backend serves JSON and you need a full SPA experience."*
+**Honest pitch:** _"htmx — if the backend is solid and can serve HTML. Mado — if the backend serves JSON and you need a full SPA experience."_
 
 ---
 
@@ -106,16 +111,16 @@ If your case does not fall into the last point — Mado is most likely not the b
 
 **Alpine** — reactive attributes directly in HTML.
 
-| | Alpine | Mado |
-|---|---|---|
-| Purpose | enhancing static HTML | full SPA |
-| Size | ~7 KB | ~16 KB |
-| State management | `x-data` locally | signals + context + persisted |
-| Routing | none | included |
-| TypeScript | poor | first-class |
-| When to choose | static sites, landing pages, need 5 interactive buttons | full app: pages, navigation, forms, data |
+|                  | Alpine                                                  | Mado                                     |
+| ---------------- | ------------------------------------------------------- | ---------------------------------------- |
+| Purpose          | enhancing static HTML                                   | full SPA                                 |
+| Size             | ~7 KB                                                   | ~16 KB                                   |
+| State management | `x-data` locally                                        | signals + context + persisted            |
+| Routing          | none                                                    | included                                 |
+| TypeScript       | poor                                                    | first-class                              |
+| When to choose   | static sites, landing pages, need 5 interactive buttons | full app: pages, navigation, forms, data |
 
-**Honest pitch:** *"Alpine — for interactivity on static sites. Mado — for a full application."*
+**Honest pitch:** _"Alpine — for interactivity on static sites. Mado — for a full application."_
 
 ---
 
@@ -124,12 +129,14 @@ If your case does not fall into the last point — Mado is most likely not the b
 I won't dwell on this for long, because React is in a **different weight class** in terms of ecosystem and maturity. But if you're seriously comparing:
 
 **React wins:**
+
 - massive ecosystem: thousands of UI kits, thousands of articles, endless tutorials;
 - AI assistants (ChatGPT, Copilot) know React better than anything;
 - better job market;
 - better SSR support (Next.js).
 
 **Mado wins:**
+
 - bundle size dozens of times smaller;
 - zero infrastructure (no Vite, no Babel, no 200 packages);
 - readable in an evening — if something breaks, open `src/`;
@@ -137,11 +144,13 @@ I won't dwell on this for long, because React is in a **different weight class**
 - no need to migrate between major versions.
 
 **When to choose Mado over React:**
+
 - 1–3 person project, for years to come;
 - bundle size is critical;
 - you're tired of React fatigue and are ready to sacrifice the ecosystem for simplicity.
 
 **When to choose React:**
+
 - team of 5 or more people;
 - you need UI kits, you need the ecosystem;
 - a project that will be hiring new people from the market;
@@ -166,6 +175,7 @@ For backend developers who are used to small, understandable libraries (chi in G
 Honestly: **Mado is not the fastest**. The top-3 on js-framework-benchmark are Solid, Inferno, and Svelte. Mado is closer to Lit / Preact in characteristics.
 
 What Mado does for performance out of the box:
+
 - **lazy `computed`** (dirty-flag, not eager);
 - **batch microtask scheduler** for `signal.set`;
 - **keyed reconciliation** in `each()` with real DOM reuse;

package/docs/en/06-for-backenders.md

@@ -1,6 +1,7 @@
 # Mado for Backend Developers
 
-> You write in Go / Rust / .NET / Java / Python and you need to build a web UI.  
+> You write in Go / Rust / .NET / Java / Python and you need to build a web UI
+> for an admin panel, internal tool or dashboard.  
 > This page is the mental model of Mado in 10 minutes, in your language.
 
 ---
@@ -9,17 +10,17 @@
 
 Mado is structured **like an HTTP server**. Seriously:
 
-| Server world | Mado |
-|---|---|
-| HTTP router (chi, axum, mux) | `routes()` — path manifest |
-| Handler `func(req, resp)` | `page({ view: (ctx) => html\`...\` })` |
-| Middleware | `layout` in `nested()` (wraps the handler) |
-| Template engine (Jinja, Handlebars) | `html\`\`` tagged template |
-| HTTP client with cache | `resource()` — fetch + cache + invalidation |
-| Reactive variable / atom | `signal()` — reactive getter |
-| Background goroutine / task | `effect()` — auto-reruns when a signal changes |
-| `defer cleanup()` | `ctx.onDispose(fn)` in component setup |
-| ENV variables | `createContext()` + `provide()`/`inject()` |
+| Server world                        | Mado                                           |
+| ----------------------------------- | ---------------------------------------------- |
+| HTTP router (chi, axum, mux)        | `routes()` — path manifest                     |
+| Handler `func(req, resp)`           | `page({ view: (ctx) => html\`...\` })`         |
+| Middleware                          | `layout` in `nested()` (wraps the handler)     |
+| Template engine (Jinja, Handlebars) | `html\`\`` tagged template                     |
+| HTTP client with cache              | `resource()` — fetch + cache + invalidation    |
+| Reactive variable / atom            | `signal()` — reactive getter                   |
+| Background goroutine / task         | `effect()` — auto-reruns when a signal changes |
+| `defer cleanup()`                   | `ctx.onDispose(fn)` in component setup         |
+| ENV variables                       | `createContext()` + `provide()`/`inject()`     |
 
 If you understand an HTTP server, you understand Mado.
 
@@ -130,20 +131,23 @@ import { resource, mutation, jsonFetcher, invalidate } from "@madojs/mado";
 const userId = signal(1);
 
 const user = resource(
-  () => `/api/users/${userId()}`,         // cache key (reactive!)
-  jsonFetcher<User>(),                    // how to load
-  { staleTime: 60_000 },                  // 60-second cache
+  () => `/api/users/${userId()}`, // cache key (reactive!)
+  jsonFetcher<User>(), // how to load
+  { staleTime: 60_000 }, // 60-second cache
 );
 
 // in the component:
-user.data();     // User | undefined
-user.error();    // Error | null
-user.loading();  // boolean
+user.data(); // User | undefined
+user.error(); // Error | null
+user.loading(); // boolean
 
 // mutation (like POST/PUT)
 const save = mutation<User, User>(
-  (u) => fetch("/api/users", { method: "POST", body: JSON.stringify(u) }).then(r => r.json()),
-  { invalidates: ["/api/users*"] },  // glob invalidation — like `cache.Drop("users:*")`
+  (u) =>
+    fetch("/api/users", { method: "POST", body: JSON.stringify(u) }).then((r) =>
+      r.json(),
+    ),
+  { invalidates: ["/api/users*"] }, // glob invalidation — like `cache.Drop("users:*")`
 );
 
 await save.run(newUser);
@@ -169,9 +173,7 @@ component("x-counter", () => {
   const count = signal(0);
 
   return () => html`
-    <button @click=${() => count.update(n => n + 1)}>
-      Clicks: ${count}
-    </button>
+    <button @click=${() => count.update((n) => n + 1)}>Clicks: ${count}</button>
   `;
 });
 ```
@@ -179,7 +181,7 @@ component("x-counter", () => {
 Usage:
 
 ```ts
-html`<x-counter></x-counter>`
+html`<x-counter></x-counter>`;
 ```
 
 We register the `<x-counter>` tag in the browser — it becomes a "function" that can be inserted into HTML. This is a **native** browser mechanism (Web Components), Mado only glues it together with signals.
@@ -195,22 +197,29 @@ import { useForm } from "@madojs/mado";
 
 const f = useForm({
   email: { required: true, type: "email" },
-  age:   { required: true, type: "number", min: 18 },
+  age: { required: true, type: "number", min: 18 },
 });
 
 // in the template:
 html`
-  <form @submit=${f.onSubmit(async (v) => {
-    await api.save(v);
-    f.reset();
-  })}>
-    <input name="email" .value=${() => f.values().email ?? ""}
-           @input=${f.onInput} @blur=${f.onBlur} />
-    
-    ${() => f.errors().email && f.touched().email
-      ? html`<small>${f.errors().email}</small>`
-      : null}
-    
+  <form
+    @submit=${f.onSubmit(async (v) => {
+      await api.save(v);
+      f.reset();
+    })}
+  >
+    <input
+      name="email"
+      .value=${() => f.values().email ?? ""}
+      @input=${f.onInput}
+      @blur=${f.onBlur}
+    />
+
+    ${() =>
+      f.errors().email && f.touched().email
+        ? html`<small>${f.errors().email}</small>`
+        : null}
+
     <button ?disabled=${() => !f.isValid() || f.submitting()}>Save</button>
   </form>
 `;
@@ -233,12 +242,12 @@ const ApiCtx = createContext<ApiClient>(defaultApiClient);
 // in the root component — provide
 component("x-app", ({ host }) => {
   provide(host, ApiCtx, new ApiClient("https://api.example.com"));
-  return () => html`<x-page/>`;
+  return () => html`<x-page />`;
 });
 
 // in any child — consume
 component("x-page", ({ host }) => {
-  const api = inject(host, ApiCtx);  // signal<ApiClient>
+  const api = inject(host, ApiCtx); // signal<ApiClient>
   return () => html`<div>API version: ${() => api().version}</div>`;
 });
 ```
@@ -255,7 +264,7 @@ If you're used to server-side rendering for SEO, in Mado this is solved differen
 // src/pages/product.ts
 export default page({
   bake: {
-    paths: () => api.allProductSlugs(),   // build-time fetch
+    paths: () => api.allProductSlugs(), // build-time fetch
     data: ({ slug }) => api.getProduct(slug),
     revalidate: 3600,
   },
@@ -264,7 +273,7 @@ export default page({
     canonical: `/product/${slug}`,
     og: { title: data.name, image: data.image },
   }),
-  view: ({ params }) => html`<x-product data-slug=${params.slug}/>`,
+  view: ({ params }) => html`<x-product data-slug=${params.slug} />`,
 });
 ```
 
@@ -288,14 +297,20 @@ import { page, html, resource, each, signal } from "@madojs/mado";
 export default page({
   view: () => {
     const users = resource(() => "/api/users", jsonFetcher<User[]>());
-    
+
     return html`
-      ${() => users.loading() ? html`<p>Loading…</p>` : null}
-      ${() => users.error() ? html`<p>Error: ${users.error()!.message}</p>` : null}
+      ${() => (users.loading() ? html`<p>Loading…</p>` : null)}
+      ${() =>
+        users.error() ? html`<p>Error: ${users.error()!.message}</p>` : null}
       <ul>
-        ${() => each(users.data() ?? [], u => u.id, u => html`
-          <li><a href="/users/${u.id}" data-link>${u.name}</a></li>
-        `)}
+        ${() =>
+          each(
+            users.data() ?? [],
+            (u) => u.id,
+            (u) => html`
+              <li><a href="/users/${u.id}" data-link>${u.name}</a></li>
+            `,
+          )}
       </ul>
     `;
   },
@@ -308,7 +323,10 @@ export default page({
 import { useForm, mutation } from "@madojs/mado";
 
 const createUser = mutation<NewUser, User>(
-  (u) => fetch("/api/users", { method: "POST", body: JSON.stringify(u) }).then(r => r.json()),
+  (u) =>
+    fetch("/api/users", { method: "POST", body: JSON.stringify(u) }).then((r) =>
+      r.json(),
+    ),
   { invalidates: ["/api/users*"] },
 );
 
@@ -316,11 +334,13 @@ const createUser = mutation<NewUser, User>(
 const f = useForm({ name: { required: true } });
 
 html`
-  <form @submit=${f.onSubmit(async (v) => {
-    await createUser.run(v);
-    navigate("/users");
-  })}>
-    <input name="name" @input=${f.onInput}>
+  <form
+    @submit=${f.onSubmit(async (v) => {
+      await createUser.run(v);
+      navigate("/users");
+    })}
+  >
+    <input name="name" @input=${f.onInput} />
     <button>Create</button>
   </form>
 `;
@@ -353,8 +373,8 @@ export default routes({
   "/app/*": nested({
     layout: () => import("./layouts/auth-layout.js"),
     routes: {
-      "dashboard": () => import("./pages/dashboard.js"),
-      "users": () => import("./pages/users.js"),
+      dashboard: () => import("./pages/dashboard.js"),
+      users: () => import("./pages/users.js"),
     },
   }),
 });
@@ -367,7 +387,7 @@ export default routes({
 export class ApiClient {
   constructor(private base: string) {}
   get<T>(path: string): Promise<T> {
-    return fetch(this.base + path).then(r => r.json());
+    return fetch(this.base + path).then((r) => r.json());
   }
 }
 

package/docs/en/07-llm-pitfalls.md

@@ -598,6 +598,105 @@ See [`17-shadow-dom-forms.md`](./17-shadow-dom-forms.md) for the full pattern.
 
 ---
 
+## Pitfall #23: signal reads in async functions called from `view()` create effect cycles
+
+**Symptom:** `[mado] effect cycle detected: subscriber re-ran more than 100 times in one flush.`
+
+The router calls `page.view()` inside a reactive effect. Any signal read
+**synchronously** during `view()` subscribes the router's render effect. If that
+signal is then written (e.g. `loading.set(true)`) — the router re-runs `view()`,
+which reads the signal again → infinite loop.
+
+```ts
+// ❌ INFINITE LOOP — loadMore reads signals inside the router's effect
+export default page({
+  view: () => {
+    const cursor = signal<string | null>("start");
+    const loading = signal(false);
+
+    const loadMore = async () => {
+      if (cursor() === null || loading()) return; // ← subscribes render effect!
+      loading.set(true); // ← re-triggers render → loadMore() → ∞
+      const res = await fetch(`/api/items?cursor=${cursor()}`);
+      // ...
+    };
+
+    loadMore(); // called synchronously during view()
+    return html`...`;
+  },
+});
+
+// ✅ CORRECT — wrap signal reads in untracked()
+import { untracked } from "@madojs/mado";
+
+export default page({
+  view: () => {
+    const cursor = signal<string | null>("start");
+    const loading = signal(false);
+
+    const loadMore = async () => {
+      const c = untracked(() => cursor());
+      if (c === null || untracked(() => loading())) return;
+      loading.set(true);
+      const res = await fetch(`/api/items?cursor=${c}`);
+      // ...
+    };
+
+    loadMore();
+    return html`...`;
+  },
+});
+```
+
+**Rule:** Any function that reads signals AND is called synchronously during
+`view()` initialization must use `untracked()` for those reads. This includes:
+
+- Data fetching / loadMore functions
+- IntersectionObserver callbacks set up during init
+- Timer/polling setup functions that check state
+
+Signals read inside the **returned template** (`html\`...\``) are fine — they are
+wrapped in a child-binding function `${() => ...}` which creates its own effect.
+
+---
+
+## Pitfall #24: `setInterval` / manual subscriptions in `page()` view without cleanup
+
+**Symptom:** After navigating away, timers/subscriptions keep running (zombie intervals,
+server logs show polling requests from pages the user already left).
+
+```ts
+// ❌ ZOMBIE — interval survives navigation
+export default page({
+  view: () => {
+    const tick = signal(0);
+    setInterval(() => tick.update((n) => n + 1), 3000); // never cleaned up!
+    return html`<div>${tick}</div>`;
+  },
+});
+
+// ✅ CORRECT — use onDispose for cleanup
+export default page({
+  view: ({ onDispose }) => {
+    const tick = signal(0);
+    const id = setInterval(() => tick.update((n) => n + 1), 3000);
+    onDispose(() => clearInterval(id));
+    return html`<div>${tick}</div>`;
+  },
+});
+```
+
+**Note:** `resource()` and `effect()` created inside `view()` are automatically
+cleaned up on navigation (they register with the page lifecycle). Only raw
+browser APIs need explicit `onDispose()`:
+
+- `setInterval` / `setTimeout`
+- `addEventListener` (on window/document)
+- `WebSocket` / `EventSource`
+- `IntersectionObserver` / `ResizeObserver`
+
+---
+
 ## Cheat-sheet for AI
 
 | If you want to do…                    | Correct in Mado                             |
@@ -619,5 +718,7 @@ See [`17-shadow-dom-forms.md`](./17-shadow-dom-forms.md) for the full pattern.
 | `@customElement('x')`                 | `component('x-name', setup)`                |
 | `host.getAttribute('x')` in render    | `ctx.attr('x', default)` (reactive)         |
 | `jsonFetcher()` with auth             | `apiFetcher()` (attaches Bearer token)      |
+| `setInterval` in page view            | `onDispose(() => clearInterval(id))`        |
+| signal read in view() async init      | `untracked(() => cursor())`                 |
 
 If something doesn't fit this list — open `src/` and **read 500 lines**. Seriously. Mado is intentionally small to be readable.