mates 0.1.0-beta.2 → 0.1.0-beta.3

package/README.md

@@ -2,6 +2,9 @@
 
 **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. 
 
+Try out Here on Stackblitz 
+Check the Full **Docs** Here  
+
 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. 
@@ -10,47 +13,6 @@ Mates is about 50Kb gzipped, but it comes with a Router, really good state manag
 
 ---
 
-## 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)
 
 ---
 
@@ -155,1588 +117,6 @@ const App = () => () => html`
 
 ---
 
-### 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
-import { setter, html } from "mates";
-import type { Props } from "mates";
-
-const Counter = (propsFn: Props<{ label: string }>) => {
-  let count = 0;
-  const incr = setter(()=>count++);
-  // ── Inner: runs every time the incr is called or parent component is re-rendered.
-  return () => html`
-    <p>${propsFn().label}: ${count}</p>
-    <button @click=${incr}>Increment</button>
-  `;
-};
-```
-
-### 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>
-  `;
-};
-```
-
-> ⚠️ Never destructure props in the outer function (`const { name } = propsFn()`). The value would be captured at mount time and never update.
-
----
-
-### Children / Slots
-
-Pass children using the `<x-view>` element and render them inside the component with a standard `<slot>` element:
-
-```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>
-`;
-```
-
----
-
-## State Management
-
-### `atom` — reactive primitive
-
-`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.
-
-```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
-```
-
-**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.
-
-**Atoms created at module level** are global — they persist for the lifetime of the application and can be shared between any component.
-
-```typescript
-// Global state — shared across all components
-export const currentUser = atom<User | null>(null);
-export const cartCount   = atom(0);
-```
-
----
-
-### `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
-import { iAtom } from "mates";
-
-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
-```
-
----
-
-### `effect` — reactive side effect
-
-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 { atom, effect } from "mates";
-
-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
-```
-
-When used inside a component's outer function, effects are automatically disposed when the component unmounts.
-
----
-
-### `memo` — derived / computed value
-
-`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, memo } from "mates";
-
-const firstName = atom("Alice");
-const lastName  = atom("Smith");
-
-const fullName = memo(() => `${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
-
-`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.
-
-```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; },
-});
-
-// Consume in any component
-const Counter = () => {
-  const [state, update] = counterStore();
-
-  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>
-  `;
-};
-```
-
-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 { setAtom } from "mates";
-
-const selectedIds = setAtom<number>([1, 2]);
-
-// Mutations — trigger re-renders
-selectedIds.add(3);
-selectedIds.delete(1);
-selectedIds.clear();
-
-// Reads — track as reactive dependencies
-selectedIds.size;               // 2
-selectedIds.has(2);             // true
-selectedIds.values();           // IterableIterator
-selectedIds.forEach((v) => {}); // iterate
-```
-
----
-
-### `mapAtom` — reactive Map
-
-A reactive wrapper around JavaScript's `Map`. All mutations trigger component updates.
-
-```typescript
-import { mapAtom } from "mates";
-
-const cache = mapAtom<string, number>([["apples", 3]]);
-
-// Mutations
-cache.set("bananas", 5);
-cache.delete("apples");
-cache.clear();
-
-// Reads
-cache.size;                      // 1
-cache.get("bananas");            // 5
-cache.has("bananas");            // true
-cache.entries();                 // IterableIterator<[string, number]>
-```
-
----
-
-### `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 { lsAtom, ssAtom } from "mates";
-
-// Persisted across page reloads
-const theme   = lsAtom<"light" | "dark">("light");
-const sidebar = lsAtom<boolean>(true);
-
-// Session-only — cleared when the tab closes
-const draftText = ssAtom<string>("");
-
-theme.set("dark");   // saved to localStorage["mates"]
-theme();             // "dark" — even after a page reload
-```
-
-`lsAtom` also syncs across browser tabs via the `storage` event.
-
----
-
-## Scopes — Shared State Without Prop Drilling
-
-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`.
-
-```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);
-
-  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);
-    });
-  }
-
-  // setup() runs before the component mounts
-  setup() {
-    effect(() => {
-      console.log("Cart has", this.items().length, "items");
-    });
-  }
-}
-
-// 2. Parent creates the scope
-const Cart = () => {
-  const { items } = useScope(CartScope);
-
-  return () => html`
-    <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`;
-    });
-  }
-}
-```
-
----
-
-## Lifecycle Hooks
-
-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 { atom, html, onMount, onCleanup, onPaint } from "mates";
-
-const Timer = () => {
-  const seconds = atom(0);
-
-  // Runs after the component's first render
-  onMount(() => {
-    const id = setInterval(() => seconds.set((n) => n + 1), 1000);
-
-    // Return a cleanup function — called on unmount
-    return () => clearInterval(id);
-  });
-
-  // Runs after every browser paint (double-RAF)
-  onPaint(() => {
-    console.log("painted");
-  });
-
-  // Explicit cleanup — equivalent to returning a fn from onMount
-  onCleanup(() => {
-    console.log("component removed");
-  });
-
-  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
-
-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();
-    }
-  });
-
-  // Fires when the browser window is resized
-  onWindowResize((e) => {
-    console.log("resized", window.innerWidth);
-  });
-
-  // Fires when the tab is hidden or shown
-  onVisibilityChange((hidden) => {
-    if (hidden) pauseSearch();
-  });
-
-  // setInterval — auto-cleared on unmount
-  onInterval(() => {
-    refreshResults();
-  }, 30_000);
-
-  // setTimeout — auto-cleared on unmount
-  onTimeout(() => {
-    showTip();
-  }, 2_000);
-
-  // Fires on every pathAtom change (client-side navigation)
-  onNavigate((path) => {
-    console.log("navigated to", path);
-  });
-
-  // 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);
-  });
-
-  // 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";
-
-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 }>;
-});
-
-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)
-});
-```
-
-**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`.
-
----
-
-### `action` — synchronous action
-
-`action` wraps a synchronous function with subscriber notifications, `interceptBefore`/`interceptAfter` middleware, and hot-swappable implementation.
-
-```typescript
-import { action } from "mates";
-
-const addToCart = action((productId: string, quantity: number) => {
-  cart.update((c) => { c[productId] = (c[productId] ?? 0) + quantity; });
-  return { productId, quantity };
-});
-
-// Subscribe to every call
-addToCart.__subscribe((result) => {
-  console.log("Added:", result);
-  analytics.track("add_to_cart", result);
-});
-
-// 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("");
-  };
-
-  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 |
-
----
-
-## 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) => { /* ... */ },
-  });
-}
-```
-
----
-
-## TypeScript
-
-All APIs are fully typed. The most common types you'll import:
-
-```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;
-}
-
-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>
-    `;
-  };
-};
-```
-
----
-
-## 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