@vanijs/vani 0.2.0 → 0.4.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,11 +64,275 @@ const Counter = component((_, handle: Handle) => {
 const appRoot = document.getElementById('app')
 if (!appRoot) throw new Error('#app not found')
 
-renderToDOM([Counter()], appRoot)
+renderToDOM(Counter(), appRoot)
+```
+
+---
+
+## JSX mode examples
+
+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
+import { component, renderToDOM, type Handle } from '@vanijs/vani'
+
+const Counter = component((_, handle: Handle) => {
+  let count = 0
+  return () => (
+    <button
+      type="button"
+      onclick={() => {
+        count += 1
+        handle.update()
+      }}
+    >
+      Count: {count}
+    </button>
+  )
+})
+
+renderToDOM(Counter(), document.getElementById('app')!)
+```
+
+### 2) JSX component inside JS-first components
+
+```tsx
+import { component } from '@vanijs/vani'
+import * as h from '@vanijs/vani/html'
+
+const Badge = component<{ label: string }>((props) => {
+  return () => <span>{props.label}</span>
+})
+
+const Panel = component(() => {
+  return () =>
+    h.div(
+      'Mixed render:',
+      Badge({ label: 'JSX component' }),
+      h.span('inside a JS-first component.'),
+    )
+})
 ```
 
 ---
 
+## Incremental adoption (mounting points)
+
+Vani is intentionally small and lightweight, so you don't need to replace your full stack. You can
+adopt it gradually by mounting Vani components inside existing apps (React, Vue, server-rendered
+pages, etc.) using plain DOM elements as mounting points.
+
+Benefits:
+
+- Gradual migration: move one widget or screen at a time without a rewrite.
+- Minimal surface area: no global runtime or framework lock-in.
+- Clear ownership: a Vani component owns only its subtree between anchors.
+- Easy rollback: remove a mount point and the rest of the app keeps working.
+
+### Example: mount a Vani widget inside React
+
+```tsx
+import { useEffect, useRef } from 'react'
+import { component, div, button, renderToDOM, type Handle } from '@vanijs/vani'
+
+// Vani component (local state + explicit updates)
+const VaniCounter = component((_, handle) => {
+  let count = 0
+  return () =>
+    div(
+      `Count: ${count}`,
+      button(
+        {
+          onclick: () => {
+            count += 1
+            handle.update()
+          },
+        },
+        'Increment',
+      ),
+    )
+})
+
+// React component that hosts the Vani widget
+export function MyReactComponent() {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const vaniHandlesRef = useRef<Handle[] | null>(null)
+
+  useEffect(() => {
+    if (!containerRef.current) return
+
+    // Mount Vani into a React-managed DOM element (the mounting point)
+    vaniHandlesRef.current = renderToDOM(VaniCounter(), containerRef.current)
+
+    // Cleanup when React unmounts
+    return () => {
+      for (const handle of vaniHandlesRef.current ?? []) {
+        handle.dispose()
+      }
+      vaniHandlesRef.current = null
+    }
+  }, [])
+
+  return <div ref={containerRef} />
+}
+```
+
+---
+
+## 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
+- `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
@@ -102,21 +388,34 @@ Updates replace only the DOM between anchors.
 
 ### 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 }
 
@@ -154,6 +453,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) {
@@ -180,32 +480,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.effect(() => {
+    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(
         {
@@ -221,7 +532,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.
 
 ---
 
@@ -358,7 +669,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
@@ -409,6 +744,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
@@ -514,99 +925,246 @@ 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.
+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.effect()`, 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
+1. Feature modules (state + commands)
+
+Each module owns its state and exposes a small API:
+
+- snapshot getters (`getState`, `getUsers`, `getFilters`)
+- commands that mutate state (`setUsers`, `applyFilter`)
+- `subscribe(listener)` to notify views of invalidation
+- optional selectors for derived data
 
-Each module exposes:
+2. View adapters (bind handles)
 
-- a small state container
-- read accessors (snapshot getters)
-- explicit mutation functions that call `handle.update()` on the owning component(s)
+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.
 
-2. 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
 
-3. Stable, explicit contracts
+4. Stable, explicit contracts
 
-Use interfaces, simple message payloads, or callbacks to avoid implicit coupling. If one feature
-needs another to update, it calls that module’s exported `invalidate()` (or specific mutation
-method) rather than mutating shared data.
+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
-import { component, div, type Handle } from '@vanijs/vani'
+import { component, div, type Handle, type Component } from '@vanijs/vani'
 
 type User = { id: string; name: string }
 
-export type UserFeatureApi = {
+export type UsersFeatureApi = {
   getUsers: () => User[]
-  refreshUsers: () => void
+  setUsers: (next: User[]) => void
+  refreshUsers: () => Promise<void>
+  subscribe: (listener: () => void) => () => void
 }
 
-export const UsersView = component((_, handle: Handle) => {
+export const createUsersFeature = (): { api: UsersFeatureApi; View: Component } => {
   let users: User[] = []
+  const listeners = new Set<() => void>()
 
-  const getUsers = () => users
-
-  const setUsers = (next: User[]) => {
-    users = next
-    handle.update()
+  const notify = () => {
+    for (const listener of listeners) listener()
   }
 
-  const refreshUsers = async () => {
-    const response = await fetch('/api/users')
-    const data = (await response.json()) as User[]
-    setUsers(data)
+  const api: UsersFeatureApi = {
+    getUsers: () => users,
+    setUsers: (next) => {
+      users = next
+      notify()
+    },
+    refreshUsers: async () => {
+      const response = await fetch('/api/users')
+      const data = (await response.json()) as User[]
+      api.setUsers(data)
+    },
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
   }
 
-  ;(UsersView as any).api = { getUsers, refreshUsers } satisfies UserFeatureApi
+  const View = component((_, handle: Handle) => {
+    handle.effect(() => api.subscribe(() => handle.update()))
+    return () => div(api.getUsers().map((user) => div(user.name)))
+  })
 
-  return () => div(getUsers().map((user) => div(user.name)))
-})
+  return { api, View }
+}
 ```
 
 ### Example: Coordinator calling explicit APIs
 
 ```ts
-import type { UserFeatureApi } from './users-feature'
+import type { UsersFeatureApi } from './users-feature'
 
 type Coordinator = {
-  onUserSaved: () => void
+  onUserSaved: () => Promise<void>
 }
 
-export const createCoordinator = (users: UserFeatureApi): Coordinator => {
+export const createCoordinator = (users: UsersFeatureApi): Coordinator => {
   return {
-    onUserSaved: () => {
-      users.refreshUsers()
+    onUserSaved: async () => {
+      await users.refreshUsers()
     },
   }
 }
 ```
 
-### Challenges with manual invalidation at scale
+### Example: Event channel for cross-feature updates
 
-- Update fan‑out: one action may need to notify several modules; keep this explicit via a
-  coordinator instead of hidden subscriptions.
-- Over‑invalidating: it’s easy to call `handle.update()` too broadly; prefer small, keyed subtrees
-  (item components, feature-level roots).
-- Stale reads: when multiple modules depend on shared data, ensure you update the data first, then
-  invalidate dependent modules in a predictable order.
-- Debugging update paths: without implicit reactivity, you must track who called `update()`. Keep
-  module APIs narrow and name update methods clearly (`refreshUsers`, `invalidateSearch`).
+```ts
+type EventMap = {
+  userSaved: { id: string }
+  searchChanged: { query: string }
+}
 
-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.
+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.
+
+```ts
+import { component, div, type Handle } from '@vanijs/vani'
+
+const rowHandles = new Map<string, Handle>()
+
+export const bindUserRow = (id: string, handle: Handle) => {
+  rowHandles.set(id, handle)
+  return () => rowHandles.delete(id)
+}
+
+export const invalidateUserRow = (id: string) => {
+  rowHandles.get(id)?.update()
+}
+
+export const UserRow = component<{ id: string; name: string }>((props, handle) => {
+  handle.effect(() => bindUserRow(props.id, handle))
+  return () => div(props.name)
+})
+```
+
+### Explicit batching (optional)
+
+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 { batch, type Handle } from '@vanijs/vani'
+
+const pending = new Set<Handle>()
+let scheduled = false
+
+export const queueUpdate = (handle: Handle) => {
+  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: 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.effect()`.
+- 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.
 
 ---
 
@@ -632,7 +1190,7 @@ Components can return other component instances directly:
 
 ```ts
 import { component } from '@vanijs/vani'
-import * as h from 'vani/html'
+import * as h from '@vanijs/vani'
 
 const Hero = component(() => {
   return () => h.h1('Hello')
@@ -645,39 +1203,40 @@ 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())
 ```
 
 ### `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)`
@@ -715,21 +1274,38 @@ 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.
+
+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 })
 })
 ```
 
@@ -782,6 +1358,47 @@ const Timer = component((_, handle) => {
 })
 ```
 
+### 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, getter)` binds an attribute/class to a signal.
+
+### 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