mates 0.0.21 → 0.1.0-beta.0

package/README.md

@@ -1,412 +1,1753 @@
-# Mates
+# MATES
+
+**MATES** is a lightweight, TypeScript-first front-end framework built on [lit-html](https://lit.dev/docs/libraries/standalone-templates/) to help you build large scale complex web applications that focuses on Developer Experience. 
+
+What if we had a framework that is just perfect? A framework that's faster than react and without the need of a compiler. A Framework that's super type safe. A framework that cherishes capabilities of Javascript. Mates a Beautiful, simple, Perfect Javascript Framework with **no virtual DOM**, **no compiler step**, but with lots of **goodness**. You can install Mates and run using a build tool like Vite or Bun or just use CDN to load Mates at runtime.
+
+MATES is based on an architecture: **M**utable State, **A**ctions, **T**emplates, **E**vents and **S**etups. State is mutable, Actions are trackable functions, Templates are functions that return html template strings, setups are run once before the component is mounted to set up some state or some business logic or effects. 
+
+Mates is about 50Kb gzipped, but it comes with a Router, really good state management system (you will not need anything else), Date Utils with timezone support (no need for extra library), Fetch and web socket Utils (no axios or socket.io needed), Animation Utils, Form Validation Utils, Virtualisation for lists or tables, built in CSS-in-Js library, portals, tooltips, snackbars, popups (so it'll help you create popups with no effort), UUID utils to generate random ID, Actions, Events, custom hook support, Memoisation, Zero promises (cancellable and reusable promises), built in support for pagination and lazy loading, with tons of built in hooks that are very useful, utilites to handle local storage across all tabs, a Task Manager to handle lots of async tasks in parallel or one by one and many more. 
+
+---
+
+## Table of Contents
+
+- [Why Mates?](#why-mates)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Components](#components)
+  - [The Two-Layer Model](#the-two-layer-model)
+  - [Rendering Components](#rendering-components)
+  - [Props](#props)
+  - [Children / Slots](#children--slots)
+- [State Management](#state-management)
+  - [atom — reactive primitive](#atom--reactive-primitive)
+  - [iAtom — immutable signal](#iatom--immutable-signal)
+  - [effect — reactive side effect](#effect--reactive-side-effect)
+  - [memo — derived / computed value](#memo--derived--computed-value)
+  - [useState — local object state](#usestate--local-object-state)
+  - [store — module-level shared state](#store--module-level-shared-state)
+  - [setAtom — reactive Set](#setatom--reactive-set)
+  - [mapAtom — reactive Map](#mapatom--reactive-map)
+  - [lsAtom / ssAtom — persistent state](#lsatom--ssatom--persistent-state)
+- [Scopes — Shared State Without Prop Drilling](#scopes--shared-state-without-prop-drilling)
+- [Lifecycle Hooks](#lifecycle-hooks)
+- [DOM & Window Hooks](#dom--window-hooks)
+- [Async Actions](#async-actions)
+  - [asyncAction](#asyncaction)
+  - [action — synchronous action](#action--synchronous-action)
+  - [paginatedAsyncAction](#paginatedasyncaction)
+  - [taskAction](#taskaction)
+- [HTTP Client](#http-client)
+- [Routing](#routing)
+- [CSS-in-JS & Theming](#css-in-js--theming)
+- [Directives](#directives)
+- [Portals, Dialogs & Tooltips](#portals-dialogs--tooltips)
+- [Animations](#animations)
+- [WebSocket](#websocket)
+- [Virtualization](#virtualization)
+- [DevTools](#devtools)
+- [TypeScript](#typescript)
+- [Features at a Glance](#features-at-a-glance)
+- [How Mates Compares](#how-mates-compares)
+- [License](#license)
+
+---
+
+## Why Mates?
+
+Most frameworks ask you to learn a new mental model — JSX compilers, reactive transforms, or a shadow DOM abstraction. Mates takes a different approach:
+
+- **No compiler, no JSX** — just tagged template literals from `lit-html`. Works in any TypeScript project out of the box.
+- **No virtual DOM** — `lit-html` patches only the parts of the DOM that actually changed. Updates are surgical, not diffed from scratch.]
+- **Predictable two-layer components** — the outer function (setup) runs once. The inner function (render) runs on every update. Clear separation between initialization and rendering.
+- **Batteries included** — routing, async state machines, CSS-in-JS, WebSocket, virtualization, portals, and animations are all first-party and designed to work together.
+- **Very Capable** it's shipped with lots of utitlies to help you avoid installing a third party library just for few of it's functions.
+- **TypeScript-first** — every API is fully typed from the ground up.
+
+---
+
+## Installation
 
-**Mates** is a lightweight framework that focuses on developer experience. It lets you build great web applications easily with it's awesome state management system. It's typescript First Framework. supports typescript all the way.
+```bash
+npm install mates
+```
 
-## 🚀 Features (MATES)
+Mates requires `lit-html` as a peer dependency (automatically installed):
 
-- **M**utable State: Mutate state directly through setters to update components (views)
-- **A**ctions: Function utilities to help with business logic
-- **T**emplates: Template functions that return **lit-html** result
-- **E**vents: Event Utilites for event-driven development
-- **S**etup functions: These are functions to intialise state needed for the view
+```bash
+npm install mates lit-html
+```
 
-## 📦 Installation
+---
 
-```bash
+## Quick Start
 
-npm  install  mates
+```typescript
+import { atom, html, renderX, x } from "mates";
 
-# or
+// A simple counter component
+const Counter = () => {
+  const count = atom(0);
 
-yarn  add  mates
+  return () => html`
+    <button @click=${() => count.set((n) => n - 1)}>−</button>
+    <span>${count()}</span>
+    <button @click=${() => count.set((n) => n + 1)}>+</button>
+  `;
+};
 
+// Mount to the DOM
+renderX(Counter, document.getElementById("app")!);
 ```
 
-## 🧠 Core Concepts
+---
+
+## Components
 
-### 👁 Views: Components of Mates
+### The Two-Layer Model
 
-Views are similar to components in react. They are closure functions with outer function aka **Setup** function (the S from the MATES), and inner function is called **Template** function (the T from MATES) which returns html template string.
+Every Mates component is a **closure** with two layers:
+
+| Layer | Runs | Purpose |
+|-------|------|---------|
+| **Outer function** | Once on mount | Create atoms, set up subscriptions, register lifecycle hooks |
+| **Inner function** | Every render | Read reactive values and return a `TemplateResult` |
 
 ```typescript
-import { renderView, setter, html } from "mates";
+import { atom, html } from "mates";
+import type { Props } from "mates";
 
-const CounterView = (props) => {
-  // setup function: initialise state
-  let count = 0;
-  const incr = setter(() => count++);
+const Counter = (propsFn: Props<{ label: string }>) => {
+  // ── Outer: runs once ────────────────────────────────────
+  const count = atom(0);
 
-  // template function: returns html template strings.
-  return () => html` <div>
-    <h1>Count: ${count}</h1>
-    <button @click=${incr}>Increment</button>
-  </div>`;
+  // ── Inner: runs on every re-render ──────────────────────
+  return () => html`
+    <p>${propsFn().label}: ${count()}</p>
+    <button @click=${() => count.set((n) => n + 1)}>Increment</button>
+  `;
 };
-
-// Render the view in any html element by passing it's id
-renderView(CounterView, "app");
 ```
 
-**count** is a **local let variable** that holds value. which can only be changed froma  setter function. 
-**incr** is a **setter** function, that when called, updates the view. it has to be non-async.
+> **Rule of thumb:** atoms, effects, hooks, and subscriptions always go in the **outer** function, you can also make api calls..etc you can be assumed that this code is only executed once. template function always returns html temlate strings. Modern IDEs have a built in formatting support for the html template strings.
 
-### Scopes
+---
 
-Mates introduces a new feature called Scopes. an amazing way to share state with child views (components). using Scopes, child components can access parent's state directly without using props.
+### Rendering Components
 
-#### Formatting Support:
+Use `x()` (also exported as `view`) to embed a component inside a template. Use `renderX()` to mount a component into a real DOM element.
 
-you can install lit-html plugin on your IDE like vs code or cursor for proper formatting for your template strings.
+**x** function lets you mount components in another component. you can also use **view** for the same puprose. **x** takes in a component.
 
-### props()
+```typescript
+import { html, renderX, x } from "mates";
+
+// Embed in another component's template
+const App = () => () => html`
+  <main>
+    <h1>My App</h1>
+    ${x(Counter, { label: "Clicks" })}
+  </main>
+`;
 
-In Mates, props can be passed to child views as object. props is a funciton and not an object but it's passed as object to child component. the view will have to call props() to get the projects object.
+```
+
+---
+
+### plain state and settter
+
+You don't need to create atoms to handle state for your application. The state can be anything, it can be a plain primitives or objects or sets or maps or something else, the reason we use atoms because they are trackable and you can derive computed values from them. But you can also use plain JS objects as state and you can setter functions to notify the component that something is changed and that it needs to update itself. Here is an example of the same counter without using atoms. 
 
 ```typescript
-const CounterView = () => {
+import { setter, html } from "mates";
+import type { Props } from "mates";
+
+const Counter = (propsFn: Props<{ label: string }>) => {
   let count = 0;
-  let incr = setter(() => count++);
+  const incr = setter(()=>count++);
+  // ── Inner: runs every time the incr is called or parent component is re-rendered.
   return () => html`
-    <div>count is: ${count}</div>
-    <div>${view(ChildView, { count })}</div>
+    <p>${propsFn().label}: ${count}</p>
+    <button @click=${incr}>Increment</button>
   `;
 };
-const ChildView = (props: Props<{ count: number }>) => {
-  return html`parent count is : ${props().count}`;
+```
+
+### PropsFn
+
+Props are passed as the second argument to `x()` and arrive inside the component as a **function** — `propsFn()`. Calling it inside the **inner** function ensures you always get the latest values when the parent re-renders.
+
+```typescript
+import { html, x, renderX } from "mates";
+import type { Props } from "mates";
+
+const Greeting = (propsFn: Props<{ name: string; color?: string }>) => {
+  // ✅ Read props in the inner function — always up-to-date
+  return () => html`
+    <p style="color: ${propsFn().color ?? "black"}">
+      Hello, ${propsFn().name}!
+    </p>
+  `;
+};
+
+// Props update automatically when the parent re-renders
+const App = () => {
+  const name = atom("World");
+  return () => html`
+    ${x(Greeting, { name: name(), color: "royalblue" })}
+    <button @click=${() => name.set("Mates")}>Change Name</button>
+  `;
 };
 ```
 
-**note** please don't destructure props into local variables in the outer function, as it breaks connection from the parent object. but you can do this in the inner function as inner function gets executed everytime the parent view is updated. so you will have always the latest value. 
+> ⚠️ Never destructure props in the outer function (`const { name } = propsFn()`). The value would be captured at mount time and never update.
 
-### ⚛️ Atoms: Simple Reactive State
+---
 
-Atoms hold mutable values. they can hold any Javascript value like primitive or objects or maps or sets.etc They store a single value that can be read, set (replaced with new value), or updated (if it's an object). They support typescript fully.
+### Children / Slots
 
-```typescript
+Pass children using the `<x-view>` element and render them inside the component with a standard `<slot>` element:
 
-import  {  atom  }  from  "mates";
+```typescript
+// Parent passes children
+const App = () => () => html`
+  <x-view .view=${Card} .props=${{title: "Hello"}}>
+    <p>This is child content</p>
+  </x-view>
+`;
+
+// Component renders children via <slot>
+const Card = (propsFn: Props<{ title: string }>) => () => html`
+  <div class="card">
+    <h2>${propsFn().title}</h2>
+    <slot></slot>
+  </div>
+`;
+```
 
-// Create an atom with initial value
-const username  =  atom("guest");
+---
 
-// Read the value
-console.log(username());  // "guest"
-// or
-console.log(username.get()); // "guest"
+## State Management
 
-// set the value
-username.set("alice");
+### `atom` — reactive primitive
 
-// you can also Use setter function
-username.set((val)  => val.toUpperCase());
+`atom` is the core reactive primitive. It holds any JavaScript value. Reading an atom inside the **inner** function (or an `effect`) registers a dependency — that subscriber re-runs whenever the atom changes.
 
-// you can also update the value if it's of object type
-const address  =  atom({  street:  ""  });
+```typescript
+import { atom } from "mates";
+
+// Create
+const username = atom("guest");
+const count    = atom(0);
+const user     = atom<{ name: string; age: number } | null>(null);
+
+// Read
+username();        // "guest" — registers reactive dependency
+username.get();    // "guest" — alias, same behavior
+username.val;      // "guest" — non-reactive (snapshot, no tracking)
+
+// Write
+username.set("alice");                     // replace
+count.set((n) => n + 1);                  // updater function
+user.set({ name: "Alice", age: 30 });
+
+// Mutate objects in-place
+const profile = atom({ name: "Alice", score: 0 });
+profile.update((p) => { p.score++; });    // mutation, triggers update
+```
 
-// you are updating just the street value in an object.
-address.update((s)  =>  (s.street  =  "newstreet"));
+**Atoms created inside a component's outer function** are scoped to that component — they are created on mount and automatically garbage-collected when the component unmounts.
 
-// supports maps or sets:
-const nums = atom(new Map());
-// modify the map through update.
-nums.update(m=>m.set(1, "one"));
+**Atoms created at module level** are global — they persist for the lifetime of the application and can be shared between any component.
 
-const nums = atom(new Set([1,2,3]);
-nums.update(s=>s.add(4));
-// get the value
-nums(); // Set(4) [1,2,3,4]
+```typescript
+// Global state — shared across all components
+export const currentUser = atom<User | null>(null);
+export const cartCount   = atom(0);
 ```
 
-### Counter app using atoms
+---
+
+### `iAtom` — immutable signal
+
+`iAtom` (also exported as `signal`) behaves like `atom` but **deep-freezes every value** after each `set()`. Accidental mutations throw in strict mode, making state flows easier to reason about. There is no `.update()` method — you always replace the whole value.
 
 ```typescript
-const CounterView = (props) => {
-  // setup function: initialise state
-  const count = atom(0);
-  const incr = count.set(count() + 1);
+import { iAtom } from "mates";
 
-  // template function: returns html template strings.
-  return () => html` <div>
-    <h1>Count: ${count}</h1>
-    <button @click=${incr}>Increment</button>
-  </div>`;
-};
+const theme = iAtom<"light" | "dark">("light");
+
+theme.set("dark");
+theme();  // "dark"
+
+const config = iAtom({ debug: false, version: 1 });
+config.set({ debug: true, version: 2 });  // must replace entirely
 ```
 
-### Units: Independent Object-Based State
+---
 
-Units are perfect for managing object-based state with methods and building store utilities.
-Units have the following pieces
+### `effect` — reactive side effect
 
-- Data: any type of javascript value
-- Setters: methods whose name start with (\_)
-- Getters: methods that returns data without changing it
-- Actions: async or non-async methods that call getters or setters for getting, setting data.
+An effect runs **immediately** and automatically re-runs whenever any atom it reads during execution changes. Return a cleanup function to run before the next execution and on disposal.
 
 ```typescript
-import { unit } from "mates";
+import { atom, effect } from "mates";
 
-// Create a users unit
-const todoList = unit({
-  users: [],
-  isLoading = false,
-  // setter
-  _setIsLoading(value) {
-    this.isLoading = value;
-  },
-  // setter
-  _setUsers(newUsers) {
-    this.users = newUsers;
-  },
-  // async action that calls setters to set state
-  async loadUsers() {
-    this._setIsLoading(true);
-    this._setUsers(await fetch("/users").then((d) => d.json()));
-    this._setIsLoading(false);
-  },
-  getUsersCount() {
-    return this.users.length;
-  },
+const count = atom(0);
+const label = atom("counter");
+
+// Runs immediately, then again whenever count or label changes
+const stop = effect(() => {
+  document.title = `${label()}: ${count()}`;
+
+  // Optional: return a cleanup function
+  return () => {
+    document.title = "App";
+  };
 });
+
+count.set(5);   // document.title → "counter: 5"
+label.set("score"); // document.title → "score: 5"
+
+stop(); // dispose — cleanup runs, no more re-runs
 ```
 
-### 📊 Getters: Computed Values
+When used inside a component's outer function, effects are automatically disposed when the component unmounts.
+
+---
+
+### `memo` — derived / computed value
 
-Getters create computed values that only recalculate when their dependencies change.
+`memo` creates a derived atom that stays in sync with its dependencies. It only recomputes when a dependency changes. The result is itself a readable atom.
 
 ```typescript
-import { atom, getter } from "mates";
+import { atom, memo } from "mates";
 
-const firstName = atom("John");
+const firstName = atom("Alice");
+const lastName  = atom("Smith");
 
-const lastName = atom("Doe");
+const fullName = memo(() => `${firstName()} ${lastName()}`);
 
-const fullName = getter(() => {
-  return `${firstName()}  ${lastName()}`;
-});
+fullName();         // "Alice Smith"
+firstName.set("Bob");
+fullName();         // "Bob Smith" — recomputed automatically
+```
+
+---
+
+### `useState` — local object state
+
+`useState` is designed for local component state expressed as a plain object with data properties and setter methods. Every method call triggers a re-render.
+
+```typescript
+import { html, renderX, useState } from "mates";
+
+const Counter = () => {
+  const [state] = useState({
+    count: 0,
+    step: 1,
+    incr() { this.count += this.step; },
+    decr() { this.count -= this.step; },
+    reset() { this.count = 0; },
+    setStep(n: number) { this.step = n; },
+  });
+
+  return () => html`
+    <div>
+      <button @click=${state.decr}>−</button>
+      <span>${state.count}</span>
+      <button @click=${state.incr}>+</button>
+      <button @click=${state.reset}>Reset</button>
+      <label>
+        Step:
+        <input
+          type="number"
+          .value=${String(state.step)}
+          @input=${(e: InputEvent) =>
+            state.setStep(Number((e.target as HTMLInputElement).value))}
+        />
+      </label>
+    </div>
+  `;
+};
+```
+
+> Async methods inside `useState` are automatically wrapped with `asyncAction`, giving you `.data`, `.isLoading`, `.error`, and `.status` atoms for free on async operations.
+
+---
+
+### `store` — module-level shared state
 
-console.log(fullName()); // "John Doe"
+`store` creates a **global reactive container** from a plain object. Define it at module level and share it across the entire application. Inside a component, call the store to get a `[state, update]` tuple.
 
-// Only recalculates when dependencies change
+```typescript
+import { store, html, x, renderX } from "mates";
+
+// Define once at module level
+const counterStore = store({
+  count: 0,
+  step: 1,
+  incr() { this.count += this.step; },
+  decr() { this.count -= this.step; },
+  get doubled() { return this.count * 2; },
+});
 
-firstName.set("Jane");
+// Consume in any component
+const Counter = () => {
+  const [state, update] = counterStore();
 
-console.log(fullName()); // "Jane Doe"
+  return () => html`
+    <button @click=${state.decr}>−</button>
+    <span>${state.count} (doubled: ${state.doubled})</span>
+    <button @click=${state.incr}>+</button>
+    <button @click=${() => update((s) => { s.count = 0; })}>Reset</button>
+  `;
+};
 ```
 
-### 🧬 Molecules: group atoms or units or getters into one molecule
+The `update` function is for direct external mutations. State methods (`incr`, `decr`) trigger re-renders automatically.
+
+---
+
+### `setAtom` — reactive Set
+
+A reactive wrapper around JavaScript's `Set`. All mutations trigger component updates.
 
 ```typescript
-import { molecule, atom } from "mates";
+import { setAtom } from "mates";
 
-class UserStore {
-  name = atom("Guest");
+const selectedIds = setAtom<number>([1, 2]);
 
-  isLoggedIn = atom(false);
+// Mutations — trigger re-renders
+selectedIds.add(3);
+selectedIds.delete(1);
+selectedIds.clear();
 
-  login(username) {
-    this.name.set(username);
-    this.isLoggedIn.set(true);
-  }
+// Reads — track as reactive dependencies
+selectedIds.size;               // 2
+selectedIds.has(2);             // true
+selectedIds.values();           // IterableIterator
+selectedIds.forEach((v) => {}); // iterate
+```
 
-  logout() {
-    this.name.set("Guest");
-    this.isLoggedIn.set(false);
-  }
-}
+---
 
-// Create a molecule from the class
+### `mapAtom` — reactive Map
 
-const userStore = molecule(UserStore);
+A reactive wrapper around JavaScript's `Map`. All mutations trigger component updates.
 
-// Use the molecule
+```typescript
+import { mapAtom } from "mates";
 
-console.log(userStore().name()); // "Guest"
+const cache = mapAtom<string, number>([["apples", 3]]);
 
-userStore().login("Alice");
+// Mutations
+cache.set("bananas", 5);
+cache.delete("apples");
+cache.clear();
 
-console.log(userStore().isLoggedIn()); // true
+// Reads
+cache.size;                      // 1
+cache.get("bananas");            // 5
+cache.has("bananas");            // true
+cache.entries();                 // IterableIterator<[string, number]>
 ```
 
-### 🔄 XProvider: Context Management
+---
 
-XProvider allows you to provide and consume context across your application.
+### `lsAtom` / `ssAtom` — persistent state
+
+`lsAtom` persists to `localStorage`; `ssAtom` persists to `sessionStorage`. Both auto-hydrate from storage on first read and automatically sync writes back.
 
 ```typescript
-import { html } from "lit-html";
+import { lsAtom, ssAtom } from "mates";
 
-import { view, useContext } from "mates";
+// Persisted across page reloads
+const theme   = lsAtom<"light" | "dark">("light");
+const sidebar = lsAtom<boolean>(true);
 
-// Create a context class
+// Session-only — cleared when the tab closes
+const draftText = ssAtom<string>("");
 
-class ThemeContext {
-  theme = "light";
+theme.set("dark");   // saved to localStorage["mates"]
+theme();             // "dark" — even after a page reload
+```
 
-  toggleTheme() {
-    this.theme = this.theme === "light" ? "dark" : "light";
-  }
-}
+`lsAtom` also syncs across browser tabs via the `storage` event.
 
-// Provider component
+---
 
-const ThemeProvider = view(
-  (props) => {
-    const themeContext = new ThemeContext();
+## Scopes — Shared State Without Prop Drilling
 
-    return () => html`
-      <x-provider .value=${themeContext}> ${props().children} </x-provider>
-    `;
-  },
+Scopes let any **descendant** component access state from a parent without threading props through every layer in between. Define a scope as a class, initialize it in the parent with `useScope`, and read it anywhere below with `getParentScope`.
 
-  { children: [] }
-);
+```typescript
+import { atom, effect, getParentScope, html, onMount, repeat, useScope, x } from "mates";
+import type { Props } from "mates";
+
+// 1. Define the scope as a class
+class CartScope {
+  items    = atom<string[]>([]);
+  loading  = atom(false);
 
-// Consumer component
+  add(item: string) {
+    this.items.update((list) => { list.push(item); });
+  }
+  remove(item: string) {
+    this.items.update((list) => {
+      const i = list.indexOf(item);
+      if (i !== -1) list.splice(i, 1);
+    });
+  }
 
-const ThemedButton = view(() => {
-  // Get context instance
+  // setup() runs before the component mounts
+  setup() {
+    effect(() => {
+      console.log("Cart has", this.items().length, "items");
+    });
+  }
+}
 
-  const theme = useContext(ThemeContext);
+// 2. Parent creates the scope
+const Cart = () => {
+  const { items } = useScope(CartScope);
 
   return () => html`
-    <button class="${theme.theme}-theme" @click=${() => theme.toggleTheme()}>
-      Toggle Theme (Current: ${theme.theme})
-    </button>
+    <div>
+      <p>${items().length} item(s) in cart</p>
+      ${x(ProductList)}
+      ${x(CartSummary)}
+    </div>
   `;
-}, {});
+};
+
+// 3. Any descendant reads the scope — no props needed
+const ProductList = () => {
+  const { add } = getParentScope(CartScope);
+
+  return () => html`
+    <ul>
+      <li><button @click=${() => add("Apple")}>Add Apple</button></li>
+      <li><button @click=${() => add("Banana")}>Add Banana</button></li>
+    </ul>
+  `;
+};
+
+const CartSummary = () => {
+  const { items, remove } = getParentScope(CartScope);
+
+  return () => html`
+    <ul>
+      ${repeat(
+        items(),
+        (item) => item,
+        (item) => html`
+          <li>${item} <button @click=${() => remove(item)}>✕</button></li>
+        `,
+      )}
+    </ul>
+  `;
+};
+```
+
+### `setup()` — scope initialization
+
+Add a `setup()` method to a scope class to run initialization logic (effects, timers, subscriptions, lifecycle hooks) before the host component mounts:
+
+```typescript
+class TimerScope {
+  seconds = atom(0);
+
+  setup() {
+    // Lifecycle hooks work inside setup()
+    onMount(() => {
+      console.log("timer started");
+    });
+
+    onInterval(() => {
+      this.seconds.set((n) => n + 1);
+    }, 1000);
+
+    onCleanup(() => {
+      console.log("timer stopped");
+    });
+
+    // Effects are auto-disposed with the component
+    effect(() => {
+      document.title = `${this.seconds()}s elapsed`;
+    });
+  }
+}
 ```
 
-## 🎮 Complete Example
+---
+
+## Lifecycle Hooks
 
-Here's a complete todo list example that showcases Mates' features:
+Lifecycle hooks must be called in the component's **outer function** (or in a scope's `setup()` method). They are automatically cleaned up when the component unmounts.
 
 ```typescript
-import { html } from "lit-html";
+import { atom, html, onMount, onCleanup, onPaint } from "mates";
 
-import { view, bubble, atom } from "mates";
+const Timer = () => {
+  const seconds = atom(0);
 
-// Create state with a bubble
+  // Runs after the component's first render
+  onMount(() => {
+    const id = setInterval(() => seconds.set((n) => n + 1), 1000);
 
-const todos = bubble((setter) => {
-  let items = [];
+    // Return a cleanup function — called on unmount
+    return () => clearInterval(id);
+  });
 
-  let newTodoText = "";
+  // Runs after every browser paint (double-RAF)
+  onPaint(() => {
+    console.log("painted");
+  });
 
-  const setNewTodoText = setter((text) => {
-    newTodoText = text;
+  // Explicit cleanup — equivalent to returning a fn from onMount
+  onCleanup(() => {
+    console.log("component removed");
   });
 
-  const addTodo = setter(() => {
-    if (newTodoText.trim()) {
-      items.push({ text: newTodoText, completed: false });
+  return () => html`<p>Elapsed: ${seconds()}s</p>`;
+};
+```
+
+| Hook | Timing | Notes |
+|------|--------|-------|
+| `onMount(fn)` | After first render | Return a fn to run on cleanup |
+| `onCleanup(fn)` | On unmount | Equivalent to `onMount` cleanup return |
+| `onPaint(fn)` | After browser paint | Double RAF — element is measured |
+| `onAllMount(fn)` | After all children mount | Safe for cross-component reads |
+| `onError(fn)` | On component error | Receives the Error object |
+
+---
+
+## DOM & Window Hooks
 
-      newTodoText = "";
+These hooks attach listeners **scoped to the component**. They automatically detach when the component unmounts.
+
+```typescript
+import {
+  onDOMReady,
+  onKeyDown,
+  onWindowResize,
+  onVisibilityChange,
+  onInterval,
+  onTimeout,
+  onNavigate,
+  onClickAway,
+  onFileDrop,
+  onScroll,
+  onResize,
+  onStorageChange,
+  onOnline,
+  onOffline,
+} from "mates";
+
+const SearchBar = () => {
+  const query = atom("");
+
+  // Fires on every keydown anywhere on the page
+  onKeyDown((e) => {
+    if (e.key === "/" && !e.target.matches("input")) {
+      e.preventDefault();
+      inputRef.el?.focus();
     }
   });
 
-  const toggleTodo = setter((index) => {
-    items[index].completed = !items[index].completed;
+  // Fires when the browser window is resized
+  onWindowResize((e) => {
+    console.log("resized", window.innerWidth);
   });
 
-  const deleteTodo = setter((index) => {
-    items.splice(index, 1);
+  // Fires when the tab is hidden or shown
+  onVisibilityChange((hidden) => {
+    if (hidden) pauseSearch();
   });
 
-  return () => ({
-    items,
+  // setInterval — auto-cleared on unmount
+  onInterval(() => {
+    refreshResults();
+  }, 30_000);
 
-    newTodoText,
+  // setTimeout — auto-cleared on unmount
+  onTimeout(() => {
+    showTip();
+  }, 2_000);
+
+  // Fires on every pathAtom change (client-side navigation)
+  onNavigate((path) => {
+    console.log("navigated to", path);
+  });
 
-    setNewTodoText,
+  // Fires when a click happens outside the component's host element
+  onClickAway(() => {
+    closeDropdown();
+  });
+
+  // Fires when files are dragged + dropped onto the window
+  onFileDrop((files) => {
+    handleUpload(files);
+  });
 
-    addTodo,
+  // Network status
+  onOnline(() => syncPendingChanges());
+  onOffline(() => showOfflineBanner());
+
+  return () => html`...`;
+};
+```
+
+| Hook | Trigger |
+|------|---------|
+| `onWindow(event, fn)` | Any `window` event |
+| `onWindowScroll(fn)` | Window scroll |
+| `onWindowResize(fn)` | Window resize |
+| `onKeyDown(fn)` | Global `keydown` |
+| `onKeyUp(fn)` | Global `keyup` |
+| `onVisibilityChange(fn)` | Tab show/hide, receives `hidden: boolean` |
+| `onClickAway(fn)` | Click outside host element |
+| `onFileDrop(fn)` | Window file drop |
+| `onScroll(fn, target?)` | Scroll on window or a specific element |
+| `onResize(fn, target?)` | `ResizeObserver` on host element or a specific element |
+| `onNavigate(fn)` | Path changes |
+| `onInterval(fn, ms)` | Repeating timer |
+| `onTimeout(fn, ms)` | One-shot timer |
+| `onOnline(fn)` | Browser goes online |
+| `onOffline(fn)` | Browser goes offline |
+| `onStorageChange(fn)` | Cross-tab `localStorage` changes |
+| `onPaste(fn)` | Clipboard paste |
+| `onCopy(fn)` | Clipboard copy |
+| `onCut(fn)` | Clipboard cut |
+| `onSelectionChange(fn)` | Text selection changes |
+| `onSocket(fn, sockets)` | WebSocket messages (see WebSocket section) |
+| `onUpdate(fn)` | Every re-render of the component |
+
+---
+
+## Async Actions
+
+### `asyncAction`
+
+`asyncAction` wraps an async function and gives it a complete **loading / error / data state machine** with atoms, automatic cancellation of stale calls, caching, polling, and interceptors — all built in.
+
+```typescript
+import { asyncAction, html, x, renderX } from "mates";
+import type { Props } from "mates";
 
-    toggleTodo,
+const fetchUser = asyncAction(async (id: number) => {
+  const res = await fetch(`/api/users/${id}`);
+  if (!res.ok) throw new Error("Not found");
+  return res.json() as Promise<{ id: number; name: string; email: string }>;
+});
 
-    deleteTodo,
+const UserCard = (propsFn: Props<{ userId: number }>) => {
+  // Load data when the component mounts
+  onMount(() => {
+    fetchUser(propsFn().userId);
   });
+
+  return () => html`
+    <div class="card">
+      ${fetchUser.isLoading()
+        ? html`<p>Loading…</p>`
+        : fetchUser.error()
+          ? html`<p class="error">${fetchUser.error()!.message}</p>`
+          : fetchUser.data()
+            ? html`
+                <h2>${fetchUser.data()!.name}</h2>
+                <p>${fetchUser.data()!.email}</p>
+              `
+            : html`<p>No user loaded</p>`}
+      <button @click=${() => fetchUser(propsFn().userId)}>Reload</button>
+    </div>
+  `;
+};
+```
+
+**State atoms on every `asyncAction`:**
+
+| Atom | Type | Description |
+|------|------|-------------|
+| `.data` | `AtomType<T \| null>` | The resolved value |
+| `.error` | `AtomType<Error \| null>` | The rejection error |
+| `.isLoading` | `AtomType<boolean>` | `true` while in flight |
+| `.status` | `AtomType<"init" \| "loading" \| "success" \| "error">` | Full state machine status |
+
+**Methods on every `asyncAction`:**
+
+| Method | Description |
+|--------|-------------|
+| `.cancel()` | Abort the current in-flight call |
+| `.cache(...args)` | Call and cache result by args (LRU, configurable size + TTL) |
+| `.clearCache(...args)` | Evict specific cached entries |
+| `.startPolling(...args)` | Begin polling the function on a fixed interval |
+| `.stopPolling()` | Stop polling |
+| `.subscribe(fn)` | Subscribe to completion events |
+| `.interceptBefore(fn)` | Middleware — transform args before the function runs |
+| `.interceptAfter(fn)` | Transform the resolved value before it hits `.data` |
+
+**Options:**
+
+```typescript
+const fetchData = asyncAction(myFn, {
+  cacheLimit: 20,          // Max LRU entries (default: 10)
+  cacheDuration: 60_000,   // Cache TTL in ms (default: infinite)
+  pollInterval: 5_000,     // Polling interval in ms (default: 5000)
 });
+```
 
-// Create a view for the todo app
+**Stale-call cancellation is automatic.** If you call the action a second time before the first resolves, the first call is aborted and its result is discarded. Only the latest call's data is ever written to `.data`.
 
-const TodoApp = view(() => {
-  return () => {
-    const {
-      items,
+---
 
-      newTodoText,
+### `action` — synchronous action
 
-      setNewTodoText,
+`action` wraps a synchronous function with subscriber notifications, `interceptBefore`/`interceptAfter` middleware, and hot-swappable implementation.
 
-      addTodo,
+```typescript
+import { action } from "mates";
 
-      toggleTodo,
+const addToCart = action((productId: string, quantity: number) => {
+  cart.update((c) => { c[productId] = (c[productId] ?? 0) + quantity; });
+  return { productId, quantity };
+});
 
-      deleteTodo,
-    } = todos();
+// Subscribe to every call
+addToCart.__subscribe((result) => {
+  console.log("Added:", result);
+  analytics.track("add_to_cart", result);
+});
 
-    return html`
-      <div class="todo-app">
-        <h1>Todo List</h1>
-
-        <div class="add-todo">
-          <input
-            value=${newTodoText}
-            @input=${(e) => setNewTodoText(e.target.value)}
-            @keypress=${(e) => e.key === "Enter" && addTodo()}
-            placeholder="Add new todo"
-          />
-
-          <button @click=${addTodo}>Add</button>
-        </div>
-
-        <ul class="todo-list">
-          ${items.map(
-            (item, index) => html`
-              <li class=${item.completed ? "completed" : ""}>
-                <input
-                  type="checkbox"
-                  .checked=${item.completed}
-                  @change=${() => toggleTodo(index)}
-                />
-
-                <span>${item.text}</span>
-
-                <button @click=${() => deleteTodo(index)}>Delete</button>
-              </li>
-            `
-          )}
-        </ul>
-
-        <div class="todo-stats">
-          <p>${items.filter((item) => !item.completed).length} items left</p>
-        </div>
+// Add middleware
+addToCart.interceptBefore((next, productId, quantity) => {
+  if (quantity < 1) throw new Error("Quantity must be positive");
+  return next(productId, quantity);
+});
+
+addToCart("prod_123", 2);
+```
+
+---
+
+### `paginatedAsyncAction`
+
+`paginatedAsyncAction` extends `asyncAction` with a built-in `page` atom and a `next()` helper.
+
+```typescript
+import { paginatedAsyncAction } from "mates";
+
+const fetchPosts = paginatedAsyncAction(async () => {
+  const page = fetchPosts.page();
+  const res = await fetch(`/api/posts?page=${page}&limit=10`);
+  return res.json() as Promise<Post[]>;
+});
+
+// Load first page
+fetchPosts();
+
+// Load next page
+fetchPosts.next();
+
+// Jump to page
+fetchPosts.page.set(3);
+fetchPosts();
+```
+
+Extra atoms: `fetchPosts.page` (`AtomType<number>`), `fetchPosts.totalPages` (`AtomType<number>`).
+
+---
+
+### `taskAction`
+
+`taskAction` queues async tasks and runs them one at a time, tracking the running status of each individual task.
+
+```typescript
+import { taskAction } from "mates";
+
+const processFile = taskAction(async (file: File) => {
+  const result = await uploadFile(file);
+  return result.url;
+});
+
+// Queue multiple files — they run serially
+processFile(file1);
+processFile(file2);
+processFile(file3);
+
+// Check overall status
+processFile.status();      // "loading" | "success" | "error" | "init"
+processFile.data();        // result of the last completed task
+```
+
+---
+
+## HTTP Client
+
+Mates includes a first-party HTTP client with interceptors, URL template substitution, automatic JSON serialization, SSR support, and `asyncAction` integration.
+
+### Basic usage
+
+```typescript
+import { Fetch, Get, Post, Put, Patch, Delete } from "mates";
+
+// GET with query params
+const users = await Get({ url: "/api/users", params: { page: 1, limit: 10 } });
+
+// POST with a JSON body
+const created = await Post({
+  url: "/api/users",
+  body: { name: "Alice", email: "alice@example.com" },
+});
+
+// URL template substitution — :id is replaced, extra params become query string
+const user = await Get({ url: "/api/users/:id", params: { id: 42, include: "posts" } });
+// → GET /api/users/42?include=posts
+
+// Shorthand — pass just a URL string
+const data = await Fetch("/api/health");
+```
+
+### FetchClient — per-instance configuration
+
+Create a dedicated client for each API with a shared base config and per-instance interceptors:
+
+```typescript
+import { FetchClient } from "mates";
+
+const api = new FetchClient({
+  host: "https://api.example.com",
+  headers: { "Accept": "application/json" },
+});
+
+// Add auth to every request
+api.interceptBefore((url, opts) => ({
+  url,
+  options: {
+    ...opts,
+    headers: { ...opts.headers, Authorization: `Bearer ${getToken()}` },
+  },
+}));
+
+// Log every error
+api.interceptError((error) => {
+  logger.error(error);
+});
+
+const users = await api.Get({ url: "/users" });
+const me    = await api.Get({ url: "/users/me" });
+```
+
+### `fetchAction` / HTTP action shortcuts
+
+Combine the HTTP client with `asyncAction` in one line:
+
+```typescript
+import { getAction, postAction, deleteAction } from "mates";
+
+// getAction creates an asyncAction that calls GET
+const loadUsers = getAction({ url: "/api/users" });
+loadUsers();
+
+// postAction with dynamic body
+const createUser = postAction<User>();
+createUser.interceptBefore((next) => next({ url: "/api/users", body: form() }));
+createUser();
+
+// Per-client action
+const api = new FetchClient({ host: "https://api.example.com" });
+const loadProfile = api.getAction({ url: "/users/me" });
+loadProfile();
+```
+
+---
+
+## Routing
+
+### Navigation
+
+```typescript
+import { navigateTo, pathAtom, qsAtom, hashAtom, location } from "mates";
+
+// Push a new history entry
+navigateTo("/about");
+
+// Replace current history entry (no back button entry)
+navigateTo("/login", true);
+
+// With history state data
+navigateTo("/checkout", false, { step: 2 });
+
+// Read current location reactively
+pathAtom();          // "/about"
+qsAtom();            // { q: "search term" } — parsed query string
+hashAtom();          // "#section-2"
+location.pathname;   // "/about"
+
+// Update query string (replaces history state)
+qsAtom.set({ q: "mates framework", page: 2 });
+
+// Navigation lock — prevents navigation (e.g. unsaved changes)
+lockNavigation();
+unlockNavigation();
+navigationLocked();  // true/false — reactive
+```
+
+### `Router` — declarative route table
+
+```typescript
+import { Router, navigateTo, html, renderX } from "mates";
+
+// Define components
+const HomePage    = () => () => html`<h1>Home</h1>`;
+const AboutPage   = () => () => html`<h1>About</h1>`;
+const UserPage    = (p: Props<{}>) => () => html`<h1>User</h1>`;
+const NotFound    = () => () => html`<h1>404 — Not Found</h1>`;
+
+// Create the router
+const appRouter = Router([
+  { path: "/",           component: HomePage },
+  { path: "/about",      component: AboutPage },
+  { path: "/users/:id",  component: UserPage },
+  // Lazy-loaded route — code-split automatically
+  { path: "/dashboard",  component: async () => import("./Dashboard") },
+], NotFound);
+
+// Mount
+const App = () => () => html`
+  <nav>
+    <a @click=${() => navigateTo("/")}>Home</a>
+    <a @click=${() => navigateTo("/about")}>About</a>
+  </nav>
+  <main>${appRouter()}</main>
+`;
+
+renderX(App, document.getElementById("app")!);
+```
+
+### `route` — inline conditional routing
+
+For simpler scenarios, use `route` directly in a template:
+
+```typescript
+import { route, navigateTo, html } from "mates";
+
+const App = () => () => html`
+  ${route("/",           { view: HomePage })}
+  ${route("/about",      { view: AboutPage })}
+  ${route("/users/:id",  { view: UserPage })}
+`;
+```
+
+### `animatedRouter` — page transitions
+
+```typescript
+import { animatedRouter, fadeInPreset, fadeOutPreset } from "mates";
+
+const router = animatedRouter(routes, {
+  enter: fadeInPreset,
+  exit:  fadeOutPreset,
+  scrollToTop: true,
+});
+```
+
+### `isPathMatching` — pattern testing
+
+```typescript
+import { isPathMatching } from "mates";
+
+isPathMatching("/");            // true when path is exactly "/"
+isPathMatching("/users/:id");   // true for "/users/42", "/users/abc", etc.
+isPathMatching("/posts/:id");   // false when on "/users/42"
+```
+
+### `buildPath` — fill URL templates
+
+```typescript
+import { buildPath } from "mates";
+
+buildPath("/users/:id/posts/:postId", { id: 42, postId: 7, highlight: true });
+// → "/users/42/posts/7?highlight=true"
+```
+
+---
+
+## CSS-in-JS & Theming
+
+### Scoped stylesheets with `stylesheet`
+
+`stylesheet()` creates a **scoped** CSS-in-JS instance. Each call generates unique class names so styles from different components never collide. Call it at module level, then call `mount()` inside the component.
+
+```typescript
+import { stylesheet, html, renderX } from "mates";
+
+// Module-level — created once
+const { css, mount, keyframes } = stylesheet();
+
+// Define an animation
+const spin = keyframes("spin", {
+  from: { transform: "rotate(0deg)" },
+  to:   { transform: "rotate(360deg)" },
+});
+
+// Define styles
+const cl = css({
+  card: {
+    display: "flex",
+    flexDirection: "column",
+    padding: "1.5rem",
+    borderRadius: "12px",
+    boxShadow: "0 2px 8px rgba(0,0,0,0.1)",
+    "&:hover": { boxShadow: "0 4px 16px rgba(0,0,0,0.15)" },
+    "md": { padding: "2rem" },           // breakpoint shorthand
+  },
+  title: { fontSize: "1.25rem", fontWeight: "600" },
+  loader: { animation: `${spin} 1s linear infinite` },
+});
+
+const Card = () => {
+  mount(); // injects styles when component mounts, removes on unmount
+
+  return () => html`
+    <div class="${cl.card}">
+      <h2 class="${cl.title}">Hello</h2>
+    </div>
+  `;
+};
+```
+
+**Supported nested keys inside a block:**
+
+| Key pattern | Compiled to |
+|-------------|-------------|
+| `"&:hover"` | `.block:hover { … }` |
+| `"&::before"` | `.block::before { … }` |
+| `"&[disabled]"` | `.block[disabled] { … }` |
+| `"sm"`, `"md"`, `"lg"`, `"xl"`, `"2xl"` | `@media (min-width: …) { … }` |
+| `"@media (…)"` | `@media (…) { … }` |
+
+Configure custom breakpoints globally:
+
+```typescript
+import { configureCSS } from "mates";
+
+configureCSS({ breakpoints: { tablet: "900px", desktop: "1200px" } });
+```
+
+### Global styles with `globalCSS`
+
+```typescript
+import { globalCSS } from "mates";
+
+// Singleton — injected once into <head>
+const g = globalCSS({
+  body:  { margin: "0", fontFamily: "'Inter', sans-serif" },
+  "*, *::before, *::after": { boxSizing: "border-box" },
+  a:     { color: "inherit", textDecoration: "none" },
+});
+```
+
+### Design tokens and theming with `globalTheme`
+
+```typescript
+import { globalTheme } from "mates";
+
+const { cssVars, themeAtom } = globalTheme({
+  light: {
+    primary:    "#3b82f6",
+    background: "#ffffff",
+    surface:    "#f8fafc",
+    text:       "#111827",
+    border:     "#e5e7eb",
+  },
+  dark: {
+    primary:    "#60a5fa",
+    background: "#0f172a",
+    surface:    "#1e293b",
+    text:       "#f1f5f9",
+    border:     "#334155",
+  },
+});
+
+// cssVars maps token names to CSS custom property strings
+// cssVars.primary → "--primary"  cssVars.background → "--background"
+
+// Use in stylesheet
+const cl = css({
+  button: {
+    backgroundColor: `var(${cssVars.primary})`,
+    color: `var(${cssVars.background})`,
+  },
+});
+
+// Switch theme reactively
+themeAtom.set("dark");    // adds data-theme="dark" to <html>
+themeAtom.set("auto");    // uses OS preference via prefers-color-scheme
+themeAtom.set("light");   // explicit light
+```
+
+`globalTheme` injects:
+- `:root { ... }` — first theme as base variables
+- `[data-theme="name"] { ... }` — each theme explicitly
+- `@media (prefers-color-scheme: dark) { :root:not([data-theme]) { ... } }` — OS auto mode
+
+### `cl` helper — conditional class names
+
+```typescript
+import { cl } from "mates";
+
+// Merge conditional class names into a single string
+const classes = cl(
+  styles.btn,
+  isActive  && styles.active,
+  isLoading && styles.loading,
+);
+```
+
+---
+
+## Directives
+
+Directives are attribute and child-position bindings for `lit-html` templates.
+
+### DOM manipulation directives
+
+```typescript
+import { attr, style, classes } from "mates";
+
+html`
+  <!-- Set / remove attributes declaratively -->
+  <div ${attr({ id: "main", "aria-label": "content", disabled: isDisabled })}>
+
+  <!-- Apply inline styles -->
+  <div ${style({ color: "red", display: isVisible ? "block" : "none" })}>
+
+  <!-- Conditional class management -->
+  <button ${classes([
+    "btn",
+    [isPrimary, "btn-primary", "btn-secondary"],  // ternary tuple
+    [isLoading, "btn-loading"],                    // conditional tuple
+    isDisabled && "btn-disabled",                  // falsy-safe expression
+  ])}>
+`
+```
+
+### Lifecycle directives
+
+```typescript
+import { onConnect, onDisconnect, onUpdate, onIntersect, onVisible, lazyLoad } from "mates";
+
+html`
+  <!-- React to element entering/leaving the DOM -->
+  <div ${onConnect((el) => console.log("connected", el))}>
+  <div ${onDisconnect(() => cleanup())}>
+
+  <!-- Re-run on every re-render of this node -->
+  <canvas ${onUpdate((el) => drawChart(el))}>
+
+  <!-- IntersectionObserver -->
+  <section ${onIntersect({
+    onVisible: (el) => el.classList.add("visible"),
+    onHidden:  (el) => el.classList.remove("visible"),
+    rootMargin: "0px 0px -100px 0px",
+  })}>
+
+  <!-- Lazy load when scrolled into view -->
+  <img ${lazyLoad((el) => {
+    (el as HTMLImageElement).src = el.dataset.src!;
+  })} data-src="/images/photo.jpg" />
+`
+```
+
+### Rendering helpers
+
+```typescript
+import { renderSwitch, animatedIf } from "mates";
+
+// Render first matching case
+html`${renderSwitch([
+  [status() === "loading",  html`<spinner-el></spinner-el>`],
+  [status() === "error",    html`<error-msg .msg=${error()}></error-msg>`],
+  [status() === "success",  html`<user-card .user=${data()}></user-card>`],
+  html`<p>Idle</p>`,   // default fallback
+])}`
+
+// Conditional rendering with animated transitions
+html`${animatedIf(
+  isOpen(),
+  () => html`<div class="panel">...</div>`,
+  undefined,
+  { enter: fadeInPreset, exit: fadeOutPreset },
+)}`
+```
+
+### Event directives
+
+```typescript
+import { on } from "mates";
+
+html`
+  <!-- Declarative event map — cleaned up automatically -->
+  <div ${on({ click: handleClick, mouseover: handleHover })}>
+`
+```
+
+### `eleHook` / `htmlHook` — custom directives
+
+Build your own reusable directives using the low-level hooks:
+
+```typescript
+import { eleHook, htmlHook } from "mates";
+
+// eleHook — bound to a real element
+const autoFocus = eleHook(($) => {
+  ($.el as HTMLElement).focus();
+
+  return {
+    onCleanup() { /* cleanup */ },
+  };
+});
+
+html`<input ${autoFocus()} />`
+
+// htmlHook — for inline content slots (no element required)
+const liveTime = htmlHook((render) => {
+  const tick = () => render(html`<span>${new Date().toLocaleTimeString()}</span>`);
+  tick();
+  const id = setInterval(tick, 1000);
+  return { onCleanup: () => clearInterval(id) };
+});
+
+html`<p>Current time: ${liveTime()}</p>`
+```
+
+### `$` — fluent DOM chain
+
+Imperatively manipulate elements inside hooks and lifecycle callbacks:
+
+```typescript
+import { $ } from "mates";
+
+$(el)
+  .attr({ "data-active": "true", "aria-expanded": "false" })
+  .style({ color: "red", transform: `translateX(${offset}px)` })
+  .classes(["base", [isActive, "active"], [isError, "error", "ok"]])
+  .on("click", handleClick)
+  .focus()
+  .scroll({ top: 0, behavior: "smooth" });
+```
+
+---
+
+## Portals, Dialogs & Tooltips
+
+Render content **outside** the normal DOM tree — useful for modals, toasts, context menus, and tooltips that must escape `overflow: hidden` or `transform` stacking contexts.
+
+### `portal` — fixed-position overlay
+
+```typescript
+import { portal, html } from "mates";
+
+html`
+  ${isToastVisible() && portal(
+    html`<div class="toast">Saved ✓</div>`,
+    { style: { bottom: "16px", right: "16px", position: "fixed" } },
+  )}
+`
+```
+
+### `dialog` — modal with backdrop
+
+```typescript
+import { dialog, html } from "mates";
+
+html`
+  ${isOpen() && dialog(
+    html`
+      <div class="modal">
+        <h2>Confirm Delete</h2>
+        <p>This action cannot be undone.</p>
+        <button @click=${() => isOpen.set(false)}>Cancel</button>
+        <button @click=${doDelete}>Delete</button>
       </div>
-    `;
+    `,
+    {
+      onBackdropClick: () => isOpen.set(false),
+      style:       { backdropColor: "rgba(0,0,0,0.6)" },
+      dialogStyle: { borderRadius: "16px", padding: "2rem", maxWidth: "480px" },
+    },
+  )}
+`
+```
+
+`dialog` automatically prevents body scroll while open and restores it exactly on close, even with nested dialogs.
+
+### `tooltip` / `tip`
+
+```typescript
+import { tooltip, html } from "mates";
+
+html`
+  <!-- Plain string tip -->
+  <button ${tooltip("Save changes (Ctrl+S)")}>Save</button>
+
+  <!-- Rich HTML tip -->
+  <button ${tooltip(html`Press <kbd>Ctrl</kbd> + <kbd>S</kbd>`)}>Save</button>
+
+  <!-- Custom style -->
+  <span ${tooltip("Long description", { maxWidth: "280px", placement: "bottom" })}>
+    Hover me
+  </span>
+`
+```
+
+Tooltips auto-position above/below based on available viewport space. They use a singleton overlay element on `<body>` — no portal proliferation.
+
+---
+
+## Animations
+
+Mates provides a first-party animation system built on the Web Animations API (WAAPI).
+
+```typescript
+import {
+  animate,
+  animateDirective,
+  fadeInPreset,
+  fadeOutPreset,
+  slideInPreset,
+  slideOutPreset,
+  scaleInPreset,
+  bouncePreset,
+  springInPreset,
+  withStaggerPreset,
+} from "mates";
+
+// Imperative — animate an element directly
+animate(el, fadeInPreset);
+animate(el, { keyframes: [{ opacity: 0 }, { opacity: 1 }], duration: 300 });
+
+// Directive — declaratively apply to a template element
+html`
+  <div ${animateDirective({ enter: fadeInPreset, exit: fadeOutPreset })}>
+    Content
+  </div>
+`
+
+// Stagger children
+html`
+  <ul ${animateDirective(withStaggerPreset(fadeInPreset, { stagger: 50 }))}>
+    ${items.map((i) => html`<li>${i}</li>`)}
+  </ul>
+`
+```
+
+**Built-in animation presets:**
+
+| Preset | Effect |
+|--------|--------|
+| `fadeInPreset` / `fadeOutPreset` | Opacity fade |
+| `slideInPreset` / `slideOutPreset` | Slide from edge |
+| `scaleInPreset` / `scaleOutPreset` | Scale from center |
+| `blurInPreset` / `blurOutPreset` | Blur + fade |
+| `flipInPreset` / `flipOutPreset` | 3D flip |
+| `bouncePreset` | Elastic bounce |
+| `pulsePreset` | Heartbeat pulse |
+| `shakePreset` | Horizontal shake |
+| `spinPreset` | Full rotation |
+| `springInPreset` | Spring physics enter |
+| `withStaggerPreset` | Wrap any preset with stagger |
+
+---
+
+## WebSocket
+
+```typescript
+import { ws, onSocket, html } from "mates";
+
+type ChatMessage = { user: string; text: string; ts: number };
+
+const Chat = () => {
+  const messages = atom<ChatMessage[]>([]);
+  const input    = atom("");
+
+  // Create connection — auto-reconnects, auto-cleanup on unmount
+  const socket = ws<ChatMessage>("wss://api.example.com/chat", {
+    reconnect: true,
+    reconnectDelay: 1_000,
+    reconnectMaxDelay: 30_000,
+    auth: () => ({ token: authToken() }),   // refreshed on every reconnect
+  });
+
+  // Subscribe to incoming messages
+  onSocket((msg) => {
+    messages.update((list) => { list.push(msg); });
+  }, [socket]);
+
+  const send = () => {
+    socket.send({ user: "me", text: input(), ts: Date.now() });
+    input.set("");
   };
-}, {});
 
-// Mount the app
+  return () => html`
+    <div class="chat">
+      <p>Status: ${socket.status()}</p>
+      <ul>
+        ${messages().map((m) => html`<li><b>${m.user}:</b> ${m.text}</li>`)}
+      </ul>
+      <input .value=${input()} @input=${(e: InputEvent) =>
+        input.set((e.target as HTMLInputElement).value)} />
+      <button @click=${send}>Send</button>
+    </div>
+  `;
+};
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `reconnect` | `true` | Auto-reconnect on close/error |
+| `reconnectDelay` | `1000` | Initial delay in ms (doubles each attempt) |
+| `reconnectMaxDelay` | `30000` | Exponential backoff cap |
+| `reconnectMaxAttempts` | `Infinity` | Max attempts before giving up |
+| `auth` | — | `() => Record<string, string>` — query params added on connect |
+| `autoConnect` | `true` | Set to `false` to defer until `.connect()` is called manually |
+
+---
 
-document.body.appendChild(TodoApp);
+## Virtualization
+
+Render large lists and grids efficiently by only mounting visible items:
+
+```typescript
+import { virtualList, virtualGrid, virtualMasonry, masonryGrid } from "mates";
+
+// Virtualized list — only renders visible rows
+html`${virtualList({
+  items: bigArray,
+  itemHeight: 60,
+  renderItem: (item, index) => html`
+    <div class="row">${index}: ${item.name}</div>
+  `,
+})}`
+
+// Virtualized grid — only renders visible cells
+html`${virtualGrid({
+  items: products,
+  columns: 4,
+  rowHeight: 240,
+  renderItem: (product) => html`
+    <div class="product-card">
+      <img src=${product.image} />
+      <p>${product.name}</p>
+    </div>
+  `,
+})}`
+
+// Masonry layout (non-virtualized)
+html`${masonryGrid({
+  items: photos,
+  columns: 3,
+  gap: 16,
+  renderItem: (photo) => html`<img src=${photo.url} />`,
+})}`
+```
+
+---
+
+## DevTools
+
+Mates DevTools is a companion browser extension. When installed, it provides component tree inspection, atom state history, time-travel debugging, and re-render tracking — all without any code changes.
+
+To wire up custom DevTools integration at runtime:
+
+```typescript
+import { installDevToolsHooks, isDevToolsInstalled } from "mates";
+
+if (!isDevToolsInstalled()) {
+  installDevToolsHooks({
+    onAtomCreate: (atom) => { /* ... */ },
+    onAtomSet:    (atom, prev, next) => { /* ... */ },
+    onRender:     (component) => { /* ... */ },
+  });
+}
 ```
 
-## 🔄 Why Mates?
+---
 
-Mates gives you the power and simplicity of React hooks without the React! As a complete framework, it's perfect for:
+## TypeScript
 
-- Building lightweight web apps without other heavy frameworks
+All APIs are fully typed. The most common types you'll import:
 
-- Adding reactivity to existing applications
+```typescript
+import type {
+  Props,              // propsFn type: () => T
+  Component,          // outer fn → inner fn (closure component)
+  TemplateFn,         // fn → TemplateResult
+  AtomType,           // atom return type: AtomType<T>
+  IAtomType,          // iAtom return type
+  AsyncActionReturnType, // asyncAction return type
+  ActionReturnType,      // action return type
+  CSSBlock,           // css-in-js block type
+  CSSRulesInput,      // full css() rules object type
+  WsConfig,           // WebSocket config
+  WsConnection,       // WebSocket connection handle
+} from "mates";
+```
+
+**Typed component example:**
+
+```typescript
+import type { Props, Component } from "mates";
+
+interface ButtonProps {
+  label: string;
+  onClick: () => void;
+  variant?: "primary" | "ghost" | "danger";
+  disabled?: boolean;
+}
 
-- Creating reusable, reactive components
+const Button: Component<ButtonProps> = (propsFn) => {
+  return () => {
+    const { label, onClick, variant = "primary", disabled = false } = propsFn();
+    return html`
+      <button
+        class="btn btn--${variant}"
+        ?disabled=${disabled}
+        @click=${onClick}
+      >${label}</button>
+    `;
+  };
+};
+```
 
-- Prototyping ideas quickly
+---
+
+## Features at a Glance
+
+| Category | Feature |
+|----------|---------|
+| **Components** | Two-layer closure model, props as function, slot/children support |
+| **Reactivity** | `atom`, `iAtom`, `effect`, `memo`, `store`, reactive Map/Set |
+| **Local state** | `useState` with auto-async wrapping |
+| **Shared state** | Scope classes with `useScope` / `getParentScope` — no prop drilling |
+| **Persistence** | `lsAtom` (localStorage), `ssAtom` (sessionStorage), cross-tab sync |
+| **Async** | `asyncAction` with loading/error/data atoms, cancellation, polling, LRU cache |
+| **Pagination** | `paginatedAsyncAction` with built-in page atom and `next()` |
+| **Task queue** | `taskAction` for serial async work |
+| **HTTP** | `FetchClient` with interceptors, URL templates, JSON auto-serialization, SSR support |
+| **Routing** | `Router`, `route`, `navigateTo`, `pathAtom`, `qsAtom`, animated transitions |
+| **Navigation lock** | Built-in unsaved-changes guard |
+| **CSS-in-JS** | Scoped `stylesheet`, `globalCSS`, `keyframes` — zero runtime for static styles |
+| **Theming** | `globalTheme` with CSS custom properties, dark mode, OS auto-mode |
+| **Directives** | `attr`, `style`, `classes`, `on`, `onIntersect`, `lazyLoad`, `animatedIf`, etc. |
+| **Hooks** | `onMount`, `onPaint`, `onCleanup`, `onKeyDown`, `onInterval`, `onNavigate`, … |
+| **Portals** | `portal`, `dialog`, `tooltip` — escape DOM stacking contexts |
+| **Animations** | WAAPI wrapper, `animateDirective`, 15+ presets, stagger |
+| **WebSocket** | `ws()` with reconnect, exponential backoff, auth refresh, `onSocket` hook |
+| **Virtualization** | `virtualList`, `virtualGrid`, `virtualMasonry`, `masonryGrid` |
+| **DevTools** | Installable hook bridge for browser extension integration |
+| **SSR** | `isSSR`, `setSSRMode`, handler registry for zero-network server rendering |
+| **TypeScript** | Full type coverage, generics throughout, strict-mode safe |
+| **lit-html** | Full re-export of `html`, `svg`, `render`, `repeat`, `classMap`, `styleMap`, `when`, `cache`, `live`, `keyed`, `guard`, `until`, and more |
+
+---
+
+## How Mates Compares
+
+### vs React
+
+| | Mates | React |
+|---|---|---|
+| **Rendering** | `lit-html` patches the real DOM directly — no virtual DOM, no diffing tree | VDOM diff on every render, reconciler determines what to patch |
+| **Component model** | Two-layer closure — outer (setup) runs once, inner (render) runs on change | Function components re-run entirely on every render |
+| **Reactivity** | Fine-grained atoms — only components that read a changed atom re-run | Renders propagate top-down via props and context unless `memo`/`useMemo` are used |
+| **State** | `atom` (module or component-scoped), `useState`, `store` | `useState`, `useReducer`, `useContext`, external libraries |
+| **Side effects** | `effect(fn)` is reactive — re-runs when dependencies change | `useEffect` with manual dependency arrays |
+| **Computed values** | `memo(fn)` — auto-tracked dependencies | `useMemo(fn, deps)` — manual dependency arrays |
+| **Shared state** | Scopes (class-based, `useScope`/`getParentScope`) | Context API + `useContext` or external store (Zustand, Redux) |
+| **Compiler** | None — plain TypeScript, standard ESM | JSX transform required |
+| **Bundle size** | ~50 KB gzipped (framework + lit-html) | ~45 KB gzipped (React + ReactDOM) |
+| **HTTP** | Built-in `FetchClient` + `asyncAction` | Third-party (Axios, TanStack Query, SWR) |
+| **Routing** | Built-in `Router` | Third-party (React Router, TanStack Router) |
+| **CSS** | Built-in `stylesheet` + `globalTheme` | Third-party (Emotion, styled-components, CSS Modules) |
+| **Animation** | Built-in WAAPI presets + `animateDirective` | Third-party (Framer Motion, react-spring) |
+| **WebSocket** | Built-in `ws()` with reconnect | Third-party |
+| **Virtualization** | Built-in `virtualList`, `virtualGrid`, `virtualMasonry` | Third-party (react-window, TanStack Virtual) |
+
+**Key difference:** In React, calling `setState` schedules a re-render of the whole component tree from that node down. In Mates, changing an atom only re-runs the specific inner functions and effects that read that atom — everything else stays untouched.
+
+---
+
+### vs Vue 3
+
+| | Mates | Vue 3 |
+|---|---|---|
+| **Templates** | Tagged template literals — standard JavaScript, no compiler | `.vue` SFC files or JSX with Vite compiler |
+| **Reactivity** | `atom` — explicit, function-call reads | `ref`/`reactive` — Proxy-based, transparent reads |
+| **Components** | Plain closure functions | Options API or `setup()` function + `<template>` |
+| **Scoped styles** | `stylesheet()` — scoped class names | `<style scoped>` — attribute-based scoping |
+| **Router** | Built-in | Official but separate (`vue-router`) |
+| **State management** | `atom`, `store`, `scope` built-in | Official but separate (`pinia`) |
+| **Compiler** | None required | Required for SFC and template directives |
+
+---
+
+### vs Svelte
+
+| | Mates | Svelte |
+|---|---|---|
+| **Build step** | None — TypeScript only | Required Svelte compiler |
+| **Reactivity** | Explicit `atom` calls | Compile-time `$:` labels / `$state` runes |
+| **Component files** | Plain `.ts` files | `.svelte` files with `<script>`, `<template>`, `<style>` sections |
+| **Bundle size** | Consistent ~50 KB | Per-component compiled output — small for tiny apps, grows with app size |
+| **TypeScript** | Native — no extra config | Requires `lang="ts"` + type-checking config |
+| **Animation** | Built-in WAAPI presets | Built-in `transition:`, `animate:` directives (compile-time) |
+
+---
+
+### vs SolidJS
+
+| | Mates | SolidJS |
+|---|---|---|
+| **Rendering** | `lit-html` patches — no VDOM | Compiled fine-grained DOM updates |
+| **Reactivity** | `atom` — explicit function call to read | `createSignal`, `createEffect` — runs at compile time |
+| **Compiler** | None | JSX transform + reactivity transform required |
+| **Component re-runs** | Inner function re-runs on change | Components run once — JSX expressions are reactive subscriptions |
+| **Ecosystem** | Self-contained (router, HTTP, CSS, WS all built-in) | Growing ecosystem, mostly third-party |
+| **Learning curve** | Low — plain TypeScript + tagged templates | Moderate — must understand compiled reactive graph |
+
+---
+
+### vs Preact / Inferno
+
+Both are drop-in React replacements with VDOM. Mates takes a fundamentally different approach (lit-html + fine-grained atoms) and ships a complete feature set out of the box rather than relying on the React ecosystem for routing, state, animations, and HTTP.
+
+---
+
+### Summary: When to choose Mates
+
+✅ You want **no compiler magic** — just TypeScript and a build tool you already use  
+✅ You want **everything in one package** — HTTP, routing, CSS, WS, animations, virtualization  
+✅ You want **fine-grained reactivity** without a framework-specific compiler  
+✅ You're building a **single-page application** with complex state and async flows  
+✅ You want **predictable performance** — only what changed is ever re-rendered  
+✅ You prefer **explicit over implicit** — reads and writes are always function calls  
+
+---
+
+## IDE Support
+
+Install the **Lit** extension for VS Code / Cursor ([marketplace](https://marketplace.visualstudio.com/items?itemName=lit.lit-plugin)) to get:
 
-## 📚 Learn More
+- Syntax highlighting inside `html\`...\`` template literals
+- Attribute and property completions on HTML elements
+- Inline TypeScript errors in templates
 
-Check out our [examples](https://github.com/yourusername/mates/tree/main/examples) to see more usage patterns and advanced framework features.
+---
 
-## 📄 License
+## License
 
-MIT
+MIT