@vanijs/vani 0.3.0 → 0.5.0

package/DOCS.md

@@ -1,11 +1,12 @@
-# Vani Documentation
+# Vani Framework Documentation
 
 Vani is a small, dependency‑free UI runtime built around a simple idea:
 
 > Rendering should be explicit, local, and predictable.
 
-Vani is **not** a Virtual DOM, not reactive‑by‑default, and not compiler‑driven. Components own a
-DOM subtree delimited by anchors and only update when you explicitly ask them to.
+Vani is **not** a Virtual DOM, not reactive‑by‑default (signals are opt‑in), and not
+compiler‑driven. Components own a DOM subtree delimited by anchors and only update when you
+explicitly ask them to.
 
 ---
 
@@ -13,8 +14,29 @@ DOM subtree delimited by anchors and only update when you explicitly ask them to
 
 ```bash
 pnpm add @vanijs/vani
+# or
+npm install @vanijs/vani
+# or
+yarn add @vanijs/vani
+# or
+bun add @vanijs/vani
+# or
+deno add @vanijs/vani
 ```
 
+## Install skills (AI commands)
+
+Vani ships AI skills (commands) you can add to your agent tooling:
+
+```bash
+npx add-skill itsjavi/vani
+```
+
+## Use documentation as a context
+
+You can use the documentation as a context by feeding your agents the doc file directly, or by using
+[Context7](https://context7.com/itsjavi/vani) to feed your agents the doc file.
+
 ---
 
 ## Quick Start (SPA)
@@ -42,7 +64,7 @@ const Counter = component((_, handle: Handle) => {
 const appRoot = document.getElementById('app')
 if (!appRoot) throw new Error('#app not found')
 
-renderToDOM([Counter()], appRoot)
+renderToDOM(Counter(), appRoot)
 ```
 
 ---
@@ -52,6 +74,17 @@ renderToDOM([Counter()], appRoot)
 Vani is JS-first and transpiler-free, with an optional JSX adapter. JSX mode requires
 `jsxImportSource` to be set to `@vanijs/vani` and a `.tsx` file.
 
+TypeScript config example:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@vanijs/vani"
+  }
+}
+```
+
 ### 1) JSX counter button
 
 ```tsx
@@ -72,7 +105,7 @@ const Counter = component((_, handle: Handle) => {
   )
 })
 
-renderToDOM([Counter()], document.getElementById('app')!)
+renderToDOM(Counter(), document.getElementById('app')!)
 ```
 
 ### 2) JSX component inside JS-first components
@@ -143,7 +176,7 @@ export function MyReactComponent() {
     if (!containerRef.current) return
 
     // Mount Vani into a React-managed DOM element (the mounting point)
-    vaniHandlesRef.current = renderToDOM([VaniCounter()], containerRef.current)
+    vaniHandlesRef.current = renderToDOM(VaniCounter(), containerRef.current)
 
     // Cleanup when React unmounts
     return () => {
@@ -160,6 +193,148 @@ export function MyReactComponent() {
 
 ---
 
+## Philosophy and positioning
+
+### Core design principles
+
+| Principle         | Meaning                                   |
+| ----------------- | ----------------------------------------- |
+| Explicit updates  | Only `handle.update()` triggers rendering |
+| Locality          | Updates affect only the owning subtree    |
+| Determinism       | Same inputs → same DOM mutations          |
+| No hidden work    | No background tracking or diffing         |
+| Runtime clarity   | Debuggable without tooling                |
+| Opt-in complexity | Advanced features are explicit            |
+
+### Goals
+
+- Predictable performance at scale
+- Leaf-only updates by default
+- Zero runtime dependencies
+- SSR without hydration heuristics
+- Clear mental model for developers
+- Long-term maintainability over convenience
+- Web-standards-first
+- ESM-first and designed to run in any modern environment
+- Good and intuitive developer experience
+- Reduce magic and complexity, give freedom back to the developers
+
+### Ergonomic features
+
+- Real HTML attribute names, with a small set of library-specific exceptions (`ref`, `key`,
+  `fallback`, `clientOnly`)
+- Optional fine-grained state with `signal()`, `derive()`, `effect()`, plus `text()`/`attr()`
+  helpers
+- Async components with fallbacks
+- `onMount(getNodes, parent)` gives access to the rendered DOM subtree without ref plumbing,
+  aligning with explicit updates and simplifying vanilla JS integrations
+- `className` accepts string, array, and object forms for ergonomic composition
+- ESM-first and designed to run in any modern environment
+
+### What Vani is NOT
+
+- ❌ Not a Virtual DOM
+- ❌ Not reactive-by-default (signals are opt-in)
+- ❌ Not JSX-mandatory (optional adapter)
+- ❌ Not compiler-driven
+- ❌ Not a template language
+- ❌ Not a framework that guesses intent
+
+### Why not Web Components (yet)
+
+Vani does not use Web Components today because the developer ergonomics are still rough and SSR
+support is a key goal. We may revisit this if Web Components bring clear benefits without harming
+productivity and cross-browser compatibility.
+
+### Comparison with popular frameworks
+
+| Feature / Framework    | Vani | React | Vue | Svelte | Solid |
+| ---------------------- | ---- | ----- | --- | ------ | ----- |
+| Virtual DOM            | ❌   | ✅    | ✅  | ❌     | ❌    |
+| Implicit reactivity    | ❌   | ⚠️    | ✅  | ✅     | ✅    |
+| Compiler required      | ❌   | ❌    | ❌  | ✅     | ❌    |
+| JSX required           | ❌   | ✅    | ❌  | ❌     | ❌    |
+| Explicit updates       | ✅   | ❌    | ❌  | ❌     | ❌    |
+| Leaf-only updates      | ✅   | ❌    | ❌  | ❌     | ❌    |
+| Runtime-only           | ✅   | ⚠️    | ⚠️  | ❌     | ⚠️    |
+| SSR without heuristics | ✅   | ❌    | ❌  | ❌     | ❌    |
+| Dependency-free core   | ✅   | ❌    | ❌  | ❌     | ❌    |
+
+⚠️ = partially / indirectly supported / average
+
+The strength of Vani is its predictability and simplicity, while other frameworks focus on developer
+productivity and ease of use, handling a lot of complexity behind the scenes automatically.
+
+### Vani's sweet spot
+
+✅ Perfect for:
+
+- Dashboard widgets
+- Micro-frontends
+- Live-coding in the browser
+- Embeddable components in other frameworks
+- Performance-critical UIs where you need exact control
+- Server-rendered sites
+- Learning UI fundamentals (no magic, direct DOM)
+- Lightweight SPAs or small Multi-Page Applications
+
+❌ Not ideal for:
+
+- Large, complex web applications with many interrelated states
+- Teams that want framework conventions to handle complexity
+- Projects needing a mature ecosystem
+
+(at least not yet)
+
+### Mental model
+
+Think of Vani as:
+
+> **“Manually invalidated, DOM-owned UI subtrees.”**
+
+You decide:
+
+- when something updates
+- how much updates
+- and why it updates
+
+Nothing else happens behind your back.
+
+### Who Vani is for
+
+Vani is a good fit if you value:
+
+- full control over rendering
+- predictable performance
+- small runtimes
+- explicit data flow
+- SSR without complexity
+- understanding your tools deeply
+
+It is **not** optimized for:
+
+- rapid prototyping
+- beginners
+- implicit magic
+- large teams that rely on conventions
+
+### Status
+
+Vani is experimental and evolving. The core architecture is intentionally small and stable.
+
+Expect:
+
+- iteration
+- refinement
+- careful additions
+
+Not:
+
+- rapid feature creep
+- breaking conceptual changes
+
+---
+
 ## Core Concepts
 
 ### 1) Components are functions
@@ -213,23 +388,267 @@ Each component owns a DOM range delimited by anchors:
 
 Updates replace only the DOM between anchors.
 
+### 3.1) Nested component hierarchies (isolated subtrees)
+
+To build a nested tree, have a parent return child component instances as part of its render output.
+Each component instance creates its own anchor range, so parent and child updates stay isolated.
+
+#### How DOM isolation works
+
+When you nest components, each component gets its own pair of `<!--vani:start-->` and
+`<!--vani:end-->` comment anchors. The DOM structure for a parent containing a child looks like:
+
+```html
+<!--vani:start-->
+<!-- Parent start -->
+<div>
+  <div>Parent title</div>
+  <button>Rename parent</button>
+  <!--vani:start-->
+  <!-- Child start -->
+  <div>
+    Child clicks: 0
+    <button>Click child</button>
+  </div>
+  <!--vani:end-->
+  <!-- Child end -->
+</div>
+<!--vani:end-->
+<!-- Parent end -->
+```
+
+When the parent updates, Vani replaces the DOM between the parent's anchors **but preserves the
+child's anchors and their contents**. When the child updates, only the DOM between the child's
+anchors is replaced. This anchor-based isolation is automatic—no special API is needed.
+
+#### Update isolation rules
+
+- **Parent update**: replaces parent’s subtree but leaves nested child anchor ranges intact.
+- **Child update**: replaces only the child’s subtree; parent is unaffected.
+- **Re-render with new props**: if the parent re-renders and returns the same child component with
+  new props, the child’s component instance is preserved (not recreated) and the child can read the
+  new props on its next `update()`.
+
+#### Basic parent-child example
+
+```ts
+import { component, div, button, type Handle, type ComponentRef } from '@vanijs/vani'
+
+const Child = component<{ label: string }>((props, handle: Handle) => {
+  let clicks = 0
+  return () =>
+    div(
+      `${props.label} clicks: ${clicks}`,
+      button(
+        {
+          onclick: () => {
+            clicks += 1
+            handle.update()
+          },
+        },
+        'Click child',
+      ),
+    )
+})
+
+const Parent = component((_, handle: Handle) => {
+  let title = 'Parent'
+  const childRef: ComponentRef = { current: null }
+
+  const rename = () => {
+    title = title === 'Parent' ? 'Parent (renamed)' : 'Parent'
+    handle.update()
+  }
+
+  return () =>
+    div(
+      div(`Title: ${title}`),
+      button({ onclick: rename }, 'Rename parent'),
+      // Nested component subtree (isolated updates)
+      Child({ ref: childRef, label: 'Child' }),
+    )
+})
+```
+
+When you click "Rename parent", only the parent subtree updates. When you click "Click child", only
+the child subtree updates.
+
+#### Deeper nesting (grandparent → parent → child)
+
+You can nest components to any depth. Each level maintains its own isolated subtree:
+
+```ts
+import { component, div, button, type Handle } from '@vanijs/vani'
+
+const GrandChild = component<{ name: string }>((props, handle: Handle) => {
+  let value = 0
+  return () =>
+    div(
+      `GrandChild (${props.name}): ${value}`,
+      button(
+        {
+          onclick: () => {
+            value += 1
+            handle.update()
+          },
+        },
+        '+',
+      ),
+    )
+})
+
+const Child = component<{ id: number }>((props, handle: Handle) => {
+  let label = `Child #${props.id}`
+  return () =>
+    div(
+      div(label),
+      button(
+        {
+          onclick: () => {
+            label += '!'
+            handle.update()
+          },
+        },
+        'Edit label',
+      ),
+      GrandChild({ name: `gc-${props.id}` }),
+    )
+})
+
+const Parent = component((_, handle: Handle) => {
+  let count = 2
+  return () =>
+    div(
+      div(`Parent has ${count} children`),
+      button(
+        {
+          onclick: () => {
+            count += 1
+            handle.update()
+          },
+        },
+        'Add child',
+      ),
+      ...Array.from({ length: count }, (_, i) => Child({ id: i })),
+    )
+})
+```
+
+Each `GrandChild` can update independently of its `Child`, and each `Child` can update independently
+of the `Parent`. The anchor isolation means you can have deeply nested trees without cascading
+re-renders.
+
+#### Passing props and callbacks (prop drilling)
+
+Props flow down explicitly. If a child needs data from an ancestor, pass it through props:
+
+```ts
+import { component, div, button, type Handle } from '@vanijs/vani'
+
+const Display = component<{ value: number }>((props) => {
+  return () => div(`Current value: ${props.value}`)
+})
+
+const Controls = component<{ onIncrement: () => void }>((props) => {
+  return () => button({ onclick: props.onIncrement }, 'Increment')
+})
+
+const App = component((_, handle: Handle) => {
+  let count = 0
+  const increment = () => {
+    count += 1
+    handle.update()
+  }
+  return () => div(Display({ value: count }), Controls({ onIncrement: increment }))
+})
+```
+
+When `increment` is called, the `App` re-renders. Because `Display` and `Controls` are nested
+components with their own anchor ranges, their internal state (if any) is preserved. The new `value`
+prop is available to `Display` on the next render.
+
+#### Updating children from the parent via refs
+
+If you need to trigger a child update without re-rendering the parent, store a `ComponentRef` and
+call `update()` on it directly:
+
+```ts
+import { component, div, button, type Handle, type ComponentRef } from '@vanijs/vani'
+
+const Counter = component<{ start: number }>((props, handle: Handle) => {
+  let count = props.start
+  return () =>
+    div(
+      `Count: ${count}`,
+      button(
+        {
+          onclick: () => {
+            count += 1
+            handle.update()
+          },
+        },
+        '+',
+      ),
+    )
+})
+
+const Dashboard = component(() => {
+  const counterRef: ComponentRef = { current: null }
+
+  const resetCounter = () => {
+    // Update only the Counter subtree, not the Dashboard
+    counterRef.current?.update()
+  }
+
+  return () =>
+    div(
+      Counter({ ref: counterRef, start: 0 }),
+      button({ onclick: resetCounter }, 'Refresh counter'),
+    )
+})
+```
+
+Clicking "Refresh counter" calls `counterRef.current?.update()`, which re-renders only the `Counter`
+subtree. The `Dashboard` itself does not re-render.
+
+#### Summary
+
+- Nesting is standard component composition—no special API.
+- Each component instance owns an anchor-delimited DOM range.
+- Updates are isolated: a component’s `handle.update()` only affects its own subtree.
+- Props and callbacks flow down explicitly (prop drilling).
+- Use `ComponentRef` to update children without re-rendering parents.
+
 ### 4) Lists and item-level updates
 
-Lists are efficient in Vani when each item is its own component. Every item owns a tiny subtree and
-can update itself (or be updated via a ref) without touching siblings. Use `key` to preserve
-identity across reorders.
+Lists scale well in Vani when each item is its own component. Every item owns a tiny subtree and can
+update itself (or be updated via a ref) without touching siblings. Use `key` to preserve identity
+across reorders.
 
 Key ideas:
 
 - Represent list data by id (Map or array + id).
 - Render each row as a keyed component.
 - Store a `ComponentRef` per id so you can call `ref.current?.update()` for that item only.
-- Call the list handle only when the list structure changes (add/remove/reorder).
+- Call `renderKeyedChildren()` for structural list changes (add/remove/reorder).
+- Keys are only respected by `renderKeyedChildren()`. Passing keyed children into `div()` or another
+  component does not trigger keyed diffing.
 
 Example:
 
 ```ts
-import { component, ul, li, input, button, type Handle, type ComponentRef } from '@vanijs/vani'
+import {
+  component,
+  div,
+  ul,
+  li,
+  input,
+  button,
+  renderKeyedChildren,
+  type ComponentRef,
+  type DomRef,
+  type Handle,
+} from '@vanijs/vani'
 
 type Todo = { id: string; text: string; done: boolean }
 
@@ -267,6 +686,7 @@ const List = component((_, handle: Handle) => {
   ])
 
   const refs = new Map<string, ComponentRef>()
+  const listRef: DomRef<HTMLUListElement> = { current: null }
   const getRef = (id: string) => {
     let ref = refs.get(id)
     if (!ref) {
@@ -293,32 +713,43 @@ const List = component((_, handle: Handle) => {
 
   const rename = (id: string, text: string) => updateItem(id, { text })
 
+  const renderRows = () => {
+    if (!listRef.current) return
+    renderKeyedChildren(
+      listRef.current,
+      order.map((id) =>
+        Row({
+          key: id,
+          ref: getRef(id),
+          id,
+          getItem,
+          onToggle: toggle,
+          onRename: rename,
+        }),
+      ),
+    )
+  }
+  handle.onBeforeMount(() => {
+    queueMicrotask(renderRows)
+  })
+
   const add = (text: string) => {
     const id = String(order.length + 1)
     items.set(id, { id, text, done: false })
     order = [...order, id]
-    handle.update()
+    renderRows()
   }
 
   const remove = (id: string) => {
     items.delete(id)
     refs.delete(id)
     order = order.filter((value) => value !== id)
-    handle.update()
+    renderRows()
   }
 
   return () =>
-    ul(
-      order.map((id) =>
-        Row({
-          key: id,
-          ref: getRef(id),
-          id,
-          getItem,
-          onToggle: toggle,
-          onRename: rename,
-        }),
-      ),
+    div(
+      ul({ ref: listRef }),
       button({ onclick: () => add('New item') }, 'Add'),
       button(
         {
@@ -334,7 +765,7 @@ const List = component((_, handle: Handle) => {
 ```
 
 This pattern keeps updates local: changing an item triggers only that row’s subtree update, while
-structural list changes re-render the list container and reuse keyed rows.
+structural changes are handled by `renderKeyedChildren()` on the list container.
 
 ---
 
@@ -471,7 +902,31 @@ component’s subtree; the conditional element is added or removed accordingly.
 
 ---
 
-### 7) Scheduling across independent regions
+### 7) Signals (optional)
+
+Signals are opt-in fine-grained state. They do **not** auto-render components; you either bind them
+directly to DOM helpers like `text()` / `attr()` or explicitly call `handle.update()`.
+
+Example:
+
+```ts
+import { component, button, div, signal, text } from '@vanijs/vani'
+
+const Counter = component(() => {
+  const [count, setCount] = signal(0)
+  return () =>
+    div(
+      text(() => `Count: ${count()}`),
+      button({ onclick: () => setCount((value) => value + 1) }, 'Inc'),
+    )
+})
+```
+
+Use `derive()` for computed getters and `effect()` for side effects tied to signals.
+
+---
+
+### 8) Scheduling across independent regions
 
 In large apps, keep each UI region as its own component root, and schedule updates explicitly. Use
 microtasks for immediate batching and `startTransition()` for non‑urgent work. This lets you control
@@ -522,6 +977,82 @@ This design keeps scheduling predictable: each region updates at most once per f
 decide which updates are urgent vs. deferred. If a region needs data from another, call its public
 API first, then schedule both regions explicitly in the same flush.
 
+### Explicit multi-region scheduling strategy
+
+When multiple independent UI regions update in the same tick, prefer a central scheduler that:
+
+- deduplicates updates per region (one update per flush)
+- batches synchronous state changes into a microtask
+- separates urgent vs. non‑urgent work (`queueMicrotask` vs. `startTransition`)
+- avoids cascades by flushing a single pass and re‑queueing if new work appears
+
+Example:
+
+```ts
+import { startTransition, type Handle } from '@vanijs/vani'
+
+type RegionId = 'header' | 'content' | 'sidebar' | 'status'
+type Priority = 'urgent' | 'transition'
+
+const handles = new Map<RegionId, Handle>()
+const pendingUrgent = new Set<RegionId>()
+const pendingTransition = new Set<RegionId>()
+let microtaskScheduled = false
+let transitionScheduled = false
+
+export const registerRegion = (id: RegionId, handle: Handle) => {
+  handles.set(id, handle)
+}
+
+export const scheduleRegion = (id: RegionId, priority: Priority = 'urgent') => {
+  if (priority === 'transition') {
+    pendingTransition.add(id)
+    if (!transitionScheduled) {
+      transitionScheduled = true
+      startTransition(flushTransition)
+    }
+    return
+  }
+
+  pendingUrgent.add(id)
+  if (!microtaskScheduled) {
+    microtaskScheduled = true
+    queueMicrotask(flushUrgent)
+  }
+}
+
+const flushUrgent = () => {
+  microtaskScheduled = false
+  for (const id of pendingUrgent) {
+    handles.get(id)?.update()
+  }
+  pendingUrgent.clear()
+
+  // If urgent updates caused more urgent work, queue another microtask.
+  if (pendingUrgent.size > 0 && !microtaskScheduled) {
+    microtaskScheduled = true
+    queueMicrotask(flushUrgent)
+  }
+}
+
+const flushTransition = () => {
+  transitionScheduled = false
+  for (const id of pendingTransition) {
+    handles.get(id)?.update()
+  }
+  pendingTransition.clear()
+}
+```
+
+Guidelines:
+
+- **Priority conflicts**: if a region is queued in both sets, let urgent win and clear it from
+  transition during flush.
+- **Cascading updates**: if an update triggers more updates, re‑queue explicitly rather than looping
+  synchronously.
+- **Predictability**: keep region IDs stable and avoid cross‑region reads during render; use
+  coordinators to update shared data first, then schedule regions in a known order.
+
 ---
 
 ## Advanced patterns
@@ -557,7 +1088,7 @@ import { component, div, button, type Handle } from '@vanijs/vani'
 import { getState, setState, subscribe } from './store'
 
 const Counter = component((_, handle: Handle) => {
-  handle.effect(() => subscribe(() => handle.update()))
+  handle.onBeforeMount(() => subscribe(() => handle.update()))
 
   return () => {
     const { count } = getState()
@@ -627,42 +1158,78 @@ export const emit = (event: string, payload?: unknown) => {
 
 ## Large-scale app architecture
 
-Vani scales best when you keep update paths explicit and module boundaries clear. The core idea is
-to let feature modules own their local state and expose small, explicit APIs for coordination,
-instead of reaching into each other's state or relying on global reactive graphs. At scale, treat
-updates like messages: state lives in a module, views read from the module, and invalidation is
-triggered by module commands.
+Vani scales best when update paths stay explicit and module boundaries stay tight. Treat updates as
+messages: state lives in a feature module, views read snapshots, and invalidation is triggered by
+that module's commands. This prevents hidden dependencies and makes cross-feature coordination an
+explicit, testable surface.
+
+### Architecting large-scale, coordinated modules
+
+Use explicit feature modules with clear APIs, bind views to module subscriptions, and coordinate
+cross-module workflows through a small coordinator or typed event channel. Keep invalidation scoped
+to feature roots or keyed row components, and batch updates per handle. Avoid implicit dependencies
+by never mutating another module's state directly; instead call exported commands or emit events. At
+scale, manual invalidation challenges include fan-out, over- or under-invalidating, update
+ordering/races, stale reads during transitions, lifecycle leaks, and lack of observability. Mitigate
+with explicit contracts, centralized command surfaces, predictable ordering, cleanup via
+`handle.onBeforeMount()`, and lightweight logging around invalidation helpers.
+
+Architecture sketch:
+
+```
+ [UI/View A] --subscribe--> [Feature A]
+       |                        |
+       | update()               | commands
+       v                        v
+   [Handle A]              [Coordinator] ----> [Feature B]
+       ^                        |                 |
+       | update()               | events          | notify
+ [UI/View B] --subscribe--> [Feature B] <---------+
+```
 
 ### Suggested architecture
 
 1. Feature modules (state + commands)
 
-Each module exposes:
+Each module owns its state and exposes a small API:
 
-- a small state container
-- read accessors (snapshot getters)
-- explicit commands (mutations) that notify listeners
-- a `subscribe(listener)` for views to bind invalidation
+- snapshot getters (`getState`, `getUsers`, `getFilters`)
+- commands that mutate state (`setUsers`, `applyFilter`)
+- `subscribe(listener)` to notify views of invalidation
+- optional selectors for derived data
 
 2. View adapters (bind handles)
 
-Views subscribe once via `handle.effect()` and call `handle.update()` when their module notifies.
-This keeps invalidation scoped to the subtree that owns the handle.
+Views subscribe once via `handle.onBeforeMount()` and call `handle.update()` when their module
+notifies. This keeps invalidation scoped to the subtree that owns the handle.
 
-3. Coordinator (optional)
+3. Coordinator or message hub
 
-For cross-module workflows, add a thin coordinator that:
+For workflows that span multiple modules, add a thin coordinator that:
 
-- orchestrates sequences (e.g. save → refresh → notify)
+- orchestrates sequences (save → refresh → notify)
 - calls public APIs of each module
-- never accesses private state directly
+- never reaches into private state
+- batches invalidations when multiple modules change together
 
 4. Stable, explicit contracts
 
-Use interfaces, simple message payloads, or callbacks to avoid implicit coupling. If one feature
+Use interfaces, small message payloads, or callbacks to avoid implicit coupling. If one feature
 needs another to update, it calls that module's exported command (or `invalidate()` helper) rather
 than mutating shared data.
 
+### Cross-module coordination patterns
+
+Pick one, keep it explicit, and avoid hidden dependencies:
+
+- **Coordinator**: a domain-level workflow function that calls module commands in order.
+- **Event channel**: a small bus where modules emit typed events and subscribers decide how to
+  update; views still call `handle.update()` explicitly.
+- **Shared readonly data**: for truly global data, use a shared store with strict write APIs and
+  localized subscriptions.
+
+The goal is to keep "who invalidates whom" visible at the call site.
+
 ### Example: Feature module with explicit invalidation
 
 ```ts
@@ -703,7 +1270,7 @@ export const createUsersFeature = (): { api: UsersFeatureApi; View: Component }
   }
 
   const View = component((_, handle: Handle) => {
-    handle.effect(() => api.subscribe(() => handle.update()))
+    handle.onBeforeMount(() => api.subscribe(() => handle.update()))
     return () => div(api.getUsers().map((user) => div(user.name)))
   })
 
@@ -729,6 +1296,33 @@ export const createCoordinator = (users: UsersFeatureApi): Coordinator => {
 }
 ```
 
+### Example: Event channel for cross-feature updates
+
+```ts
+type EventMap = {
+  userSaved: { id: string }
+  searchChanged: { query: string }
+}
+
+type Listener<K extends keyof EventMap> = (payload: EventMap[K]) => void
+const listeners = new Map<keyof EventMap, Set<Listener<keyof EventMap>>>()
+
+export const on = <K extends keyof EventMap>(event: K, listener: Listener<K>) => {
+  const set = listeners.get(event) ?? new Set()
+  set.add(listener as Listener<keyof EventMap>)
+  listeners.set(event, set)
+  return () => set.delete(listener as Listener<keyof EventMap>)
+}
+
+export const emit = <K extends keyof EventMap>(event: K, payload: EventMap[K]) => {
+  const set = listeners.get(event)
+  if (!set) return
+  for (const listener of set) {
+    listener(payload)
+  }
+}
+```
+
 ### Example: Scoped invalidation by key
 
 When a large list exists, invalidate only the affected rows.
@@ -748,51 +1342,62 @@ export const invalidateUserRow = (id: string) => {
 }
 
 export const UserRow = component<{ id: string; name: string }>((props, handle) => {
-  handle.effect(() => bindUserRow(props.id, handle))
+  handle.onBeforeMount(() => bindUserRow(props.id, handle))
   return () => div(props.name)
 })
 ```
 
 ### Explicit batching (optional)
 
-If you dispatch many invalidations in a single tick, queue them and update once per handle.
+If you dispatch many invalidations in a single tick, you can wrap them in `batch()` or queue them
+and update once per handle.
+
+Useful cases:
+
+- Multiple store mutations in one click (only one update per handle).
+- Toggling many rows or cards at once.
+- Applying filters that update multiple feature roots.
 
 ```ts
-import type { Handle } from '@vanijs/vani'
+import { batch, type Handle } from '@vanijs/vani'
 
 const pending = new Set<Handle>()
 let scheduled = false
 
 export const queueUpdate = (handle: Handle) => {
-  pending.add(handle)
-  if (scheduled) return
-  scheduled = true
-  queueMicrotask(() => {
-    scheduled = false
-    for (const item of pending) item.update()
-    pending.clear()
+  batch(() => {
+    pending.add(handle)
+    if (scheduled) return
+    scheduled = true
+    queueMicrotask(() => {
+      scheduled = false
+      for (const item of pending) item.update()
+      pending.clear()
+    })
   })
 }
 ```
 
 ### Challenges with manual invalidation at scale
 
-- Update fan-out: one action may need to notify several modules; keep this explicit via a
-  coordinator instead of hidden subscriptions.
-- Over-invalidating: calling `handle.update()` too broadly can re-render large subtrees; prefer
-  small, keyed targets (row components, feature roots).
-- Under-invalidating: missing an update call leaves views stale; treat "update after state change"
-  as part of the module contract and centralize commands.
-- Ordering and race conditions: when multiple modules depend on shared data, update data first, then
-  invalidate in a predictable order; avoid interleaving async updates without coordination.
-- Lifecycle leaks: if a handle isn't unsubscribed, updates keep firing; ensure `subscribe()` returns
-  a cleanup and is wired through `handle.effect()`.
-- Debugging update paths: without implicit reactivity, you must trace who called `update()`. Keep
-  module APIs narrow, name update methods clearly (`refreshUsers`, `invalidateSearch`), and consider
-  instrumentation (log or wrap invalidation helpers).
-
-Vani trades automatic coordination for transparency. In large apps, that means you should invest in
-clear module boundaries, explicit cross-module APIs, and small invalidation targets.
+- Update fan-out: a single command may need to notify many modules. Use a coordinator or explicit
+  event channel so the fan-out is visible and testable.
+- Over-invalidating: calling `handle.update()` on large roots can cause avoidable work. Prefer
+  small, keyed targets (row components, feature roots) and batch per handle.
+- Under-invalidating: missing a manual update leaves views stale. Make "update after mutation" part
+  of the module contract and centralize mutations behind commands.
+- Ordering and race conditions: when modules depend on shared data, update data first, then
+  invalidate in a stable order; avoid interleaving async refreshes without a coordinator.
+- Stale reads during transitions: if you defer with `startTransition()`, ensure that the render
+  reads the latest snapshot or that the transition captures the intended version.
+- Lifecycle leaks: if a handle isn't unsubscribed, updates keep firing. Always return cleanup from
+  `subscribe()` and bind it through `handle.onBeforeMount()`.
+- Observability gaps: without implicit reactivity, you need traceability. Wrap invalidation helpers
+  to log or count updates per module and catch runaway loops early.
+
+Vani trades automatic coordination for transparency. In large apps, invest in clear module
+boundaries, explicit cross-module APIs, and small invalidation targets to keep manual invalidation
+manageable.
 
 ---
 
@@ -806,7 +1411,7 @@ Creates a component factory. The `fn` receives `props` and a `handle`.
 import { component, div, type Handle } from '@vanijs/vani'
 
 const Card = component<{ title: string }>((props, handle: Handle) => {
-  handle.effect(() => {
+  handle.onBeforeMount(() => {
     console.log('Mounted:', props.title)
   })
 
@@ -817,11 +1422,10 @@ const Card = component<{ title: string }>((props, handle: Handle) => {
 Components can return other component instances directly:
 
 ```ts
-import { component } from '@vanijs/vani'
-import * as h from 'vani/html'
+import { component, h1 } from '@vanijs/vani'
 
 const Hero = component(() => {
-  return () => h.h1('Hello')
+  return () => h1('Hello')
 })
 
 const Page = component(() => {
@@ -831,39 +1435,43 @@ const Page = component(() => {
 
 ### `renderToDOM(components, root)`
 
-Mounts components to the DOM immediately.
+Mounts components and schedules the first render on the next microtask. Accepts a single component
+or an array of components.
 
 ```ts
 import { renderToDOM, component, div } from '@vanijs/vani'
 
 const App = component(() => () => div('App'))
-renderToDOM([App()], document.getElementById('app')!)
+renderToDOM(App(), document.getElementById('app')!)
 ```
 
 ### `hydrateToDOM(components, root)`
 
-Binds handles to existing DOM (SSR/SSG) without rendering. You must call `handle.update()` to
-activate.
+Binds handles to existing DOM (SSR/SSG) without rendering. Accepts a single component or an array of
+components. You must call `handle.update()` to activate.
 
 ```ts
 import { hydrateToDOM } from '@vanijs/vani'
 import { App } from './app'
 
 const root = document.getElementById('app')!
-const handles = hydrateToDOM([App()], root)
+const handles = hydrateToDOM(App(), root)
 handles.forEach((handle) => handle.update())
 ```
 
+If hydration fails due to missing anchors or mismatched structure, Vani raises a `HydrationError`
+and `hydrateToDOM()` logs it. Other errors are rethrown so they surface immediately.
+
 ### `renderToString(components)`
 
-Server‑side render to HTML with anchors. Import from `vani/ssr`.
+Server‑side render to HTML with anchors. Accepts a single component or an array of components.
+Import from `@vanijs/vani`.
 
 ```ts
-import { component } from '@vanijs/vani'
-import { renderToString } from 'vani/ssr'
+import { component, renderToString } from '@vanijs/vani'
 
 const App = component(() => () => 'Hello SSR')
-const html = await renderToString([App()])
+const html = await renderToString(App())
 ```
 
 ### `mount(component, props)`
@@ -901,21 +1509,39 @@ div(span('Label'), input({ type: 'text' }), button({ onclick: () => {} }, 'Submi
 
 ### SVG icons (Lucide)
 
-Vani can render SVG strings directly using `renderSvgString()`. With `lucide-static`, import just
-the icon you need (tree-shakable) and render it with explicit sizing and class names.
+Use the Vite SVG plugin at `src/ecosystem/vite-plugin-vani-svg.ts` and import SVGs with `?vani`.
+This keeps the bundle small by only including the icons you actually import. Invalid SVG strings
+throw an error so failures stay obvious.
+
+In your `vite.config.ts`:
+
+```ts
+import vitePluginVaniSvg from './src/ecosystem/vite-plugin-vani-svg'
+
+export default defineConfig({
+  plugins: [vitePluginVaniSvg()],
+})
+```
 
 ```ts
+import GithubIcon from 'lucide-static/icons/github.svg?vani'
 import { component } from '@vanijs/vani'
-import { renderSvgString } from '@vanijs/vani/svg'
-import { Github } from 'lucide-static'
 
 const GithubLink = component(() => {
-  return () =>
-    renderSvgString(Github, {
-      size: 16,
-      className: 'h-4 w-4',
-      attributes: { 'aria-hidden': 'true' },
-    })
+  return () => GithubIcon({ size: 16, className: 'h-4 w-4', 'aria-hidden': true })
+})
+```
+
+### SVGs as components
+
+Any SVG can be turned into a Vani component with the same `?vani` suffix.
+
+```ts
+import LogoIcon from './logo.svg?vani'
+import { component } from '@vanijs/vani'
+
+const HeaderLogo = component(() => {
+  return () => LogoIcon({ className: 'h-8 w-8', 'aria-hidden': true })
 })
 ```
 
@@ -946,21 +1572,22 @@ const Parent = component(() => {
 })
 ```
 
-### Cleanup and effects
+### Cleanup and lifecycle
 
-Effects are explicit and can return a cleanup function.
+The `onBeforeMount` hook runs once during component setup (before the first render) and can return a
+cleanup function.
 
-If you plan to use vani for a SSR/SSG application, you should use effects to run client-only code
-such as accessing the window object, accessing the DOM, etc.
+If you plan to use vani for a SSR/SSG application, you should use `onBeforeMount` to run client-only
+code such as accessing the window object, accessing the DOM, etc.
 
-Effects are very simple and run once during component setup (the component function run). They do
-not re-run on every `handle.update()`; updates only call the render function.
+The `onBeforeMount` hook is very simple and runs once during component setup (the component function
+run). It does not re-run on every `handle.update()`; updates only call the render function.
 
 ```ts
 import { component, div } from '@vanijs/vani'
 
 const Timer = component((_, handle) => {
-  handle.effect(() => {
+  handle.onBeforeMount(() => {
     const id = setInterval(() => console.log('tick'), 1000)
     return () => clearInterval(id)
   })
@@ -968,6 +1595,89 @@ const Timer = component((_, handle) => {
 })
 ```
 
+The `onMount` hook runs after the first render, once the component's nodes are in the DOM. It
+receives a lazy `getNodes()` function and the parent mount point.
+
+Benefits:
+
+- No need to set up refs ahead of time just to access nodes after render.
+- Easy to initialize external, vanilla JS libraries with all rendered nodes in one place.
+- `getNodes()` is lazy, so you only pay for DOM traversal if you actually need it.
+
+```ts
+import { component, div } from '@vanijs/vani'
+
+const Measure = component((_, handle) => {
+  handle.onMount((getNodes, parent) => {
+    const nodes = getNodes()
+    const firstElement = nodes.find((node) => node instanceof HTMLElement)
+    if (!firstElement) return
+
+    const rect = (firstElement as HTMLElement).getBoundingClientRect()
+    console.log('Mounted in', parent, 'size', rect.width, rect.height)
+  })
+
+  return () => div('Measured')
+})
+```
+
+You can also register cleanup functions directly with `handle.onCleanup()`:
+
+```ts
+import { component, div } from '@vanijs/vani'
+
+const Subscription = component((_, handle) => {
+  const unsubscribe = someStore.subscribe(() => handle.update())
+  handle.onCleanup(unsubscribe)
+
+  return () => div('Subscribed')
+})
+```
+
+Both patterns are equivalent. Use `handle.onBeforeMount()` when the setup and cleanup are logically
+grouped, and `handle.onCleanup()` when you need to register cleanup separately from initialization.
+
+### Signals and DOM bindings (optional)
+
+Signals are opt-in fine-grained state. They update only the DOM nodes bound to them.
+
+```ts
+import { component, button, div, signal, text } from '@vanijs/vani'
+
+const Counter = component(() => {
+  const [count, setCount] = signal(0)
+  return () =>
+    div(
+      text(() => `Count: ${count()}`),
+      button({ onclick: () => setCount((value) => value + 1) }, 'Inc'),
+    )
+})
+```
+
+- `signal(initial)` returns `[get, set]`.
+- `derive(fn)` returns a computed getter.
+- `effect(fn)` re-runs when signals used inside `fn` change.
+- `text(getter)` binds a text node to a signal.
+- `attr(el, name, value)` binds an attribute/class to a signal getter or static value.
+
+### Partial attribute updates
+
+When you only need to update attributes (like `className`), you can request an attribute-only
+refresh:
+
+```ts
+ref.current?.update({ onlyAttributes: true })
+```
+
+This preserves existing event listeners and children and only patches the root element’s attributes.
+It applies when the component returns a single root element.
+
+Useful cases:
+
+- Toggle a selected row class without touching children.
+- Flip aria/disabled flags on a button.
+- Update theme/state classes on a card while leaving its subtree intact.
+
 ### Transitions
 
 `startTransition` marks a group of updates as non-urgent, so they are deferred and batched