pawajs 2.3.6 → 2.4.0-beta.11

package/AGENT.md

@@ -0,0 +1,163 @@
+# AGENT.md — PawaJS
+
+Context for any AI agent (or new contributor) working in this codebase. Read this before making changes — several of the rules below exist because of real bugs found and fixed during development, not theoretical concerns.
+
+---
+
+## What PawaJS is
+
+PawaJS is a **reactive web runtime** — not a virtual-DOM framework. Its identity, unchanged across the whole rewrite:
+
+- **Extends the browser rather than replacing it.** HTML with directive attributes (`if`, `for-each`, `state-*`, `@{ }`) is the interface. No JSX, no compiler, no build step required to author with it.
+- **No VDOM, no diffing pass.** Reactive effects (`createEffect`) wire directly to the specific DOM node/attribute that needs to change. An update touches only what changed.
+- **Fine-grained reactivity**, structurally close to Vue 3's own core (`track`/`trigger`/`activeEffect`, a `WeakMap` of target → key → effect `Set`) — but the rendering strategy on top of it is closer to Solid's (no VDOM, direct DOM wiring).
+- **Components are synchronous by default.** There is no async-component mode (`useAsync`/`$async` are removed). All async lives in the `await` / `as-fallback` / `as-catch` directives.
+
+## The one organizing question
+
+Nearly everything non-trivial in this codebase — rendering, SSR pruning, `.client` detection, what goes in the continuity payload — reduces to the same question, asked at different points in the pipeline: **did this specific evaluation touch reactive state (a Proxy read)?**
+
+- At render time: decides whether something gets wrapped in `createEffect` at all.
+- At SSR time (`isProxy`): decides whether a component becomes `.client`, and whether a given prop/expression needs to be sent to the client at all.
+- At payload-build time: decides whether a construct earns a JSON entry — gated down to individual props and hook calls, not just per-component.
+
+When adding a new construct or directive, ask this same question before inventing new detection logic. It is very likely the answer is "reuse `isProxy`," not "write a new check."
+
+---
+
+## Package layout
+
+- **`pawajs` (core)** — the reactive engine, Graph/render system, control-flow directives, component handling, built-ins (`Active`, `Transition`). No SSR code, no `linkedom`. Ships to the client. Current size: **6.6kB gzipped** (down from 17.7kB pre-rewrite, with more capability — see `bundlephobia.com/package/pawajs`).
+- **`pawa-ssr`** — server-side render pass. Produces HTML + a continuity JSON payload (SCP). Depends on `linkedom` for server-side DOM. Never ships to the client.
+- **`pawajs-continue`** — client-side resumer (`PawaContinue`). Consumes the HTML + JSON pair `pawa-ssr` produces and attaches live reactivity without re-rendering.
+- **`pawajs-dom-router`** — pure client-side router. No server involvement past initial load.
+- **`supapawajs`** — full-stack meta-framework on Express. Owns delivery strategy: normal SSR, streaming, or SSG. Calls `pawa-ssr`/`pawajs-continue` but doesn't duplicate their logic. Route navigation fetches data only — it does **not** re-invoke `pawaServer`.
+- **`pawajs-vite-plugin`** — build tooling, HMR, state preservation across reloads.
+
+`pawa-ssr` and `pawajs-continue` don't know about delivery mode (streamed vs. cached vs. per-request) — that's entirely `supapawajs`'s job. Keep that boundary intact.
+
+---
+
+## Core reactivity (`reactive.js`)
+
+- `track`/`trigger`/`activeEffect`, `targetMap: WeakMap<target, Map<key, Set<effect>>>`.
+- **Every effect re-run must clear its own prior subscriptions before re-tracking.** `cleanupEffect(effect)` runs at the top of every effect invocation, unsubscribing from every dep set the effect was in from its *previous* run, so stale dependencies never accumulate. This was a real historical bug — don't reintroduce a version of `createEffect` that skips this.
+- **Dead effects are tracked via a flag (`effect._killed`), not a global `Set`.** `stopEffect`/the `deletes` closure from `createEffect` set `_killed = true`; `trigger`/`runEffectNow` check the flag. There used to be a module-level `deleteEffect` Set that only grew — don't resurrect that pattern.
+- **`graph.unActive`** — effects deferred while their owning `Graph` node is inactive (see `Active`, below) get pushed here by `runEffectNow` and flushed via `queueEffect`/`setTimeout` when the graph reactivates. Each `Graph` node owns its own `unActive`/timer list — never share one across nodes (see reentrancy note below).
+
+### Reentrancy — a recurring bug class, watch for it
+
+Several real bugs today were the same shape: **a single module-level mutable variable standing in for what should be call-scoped or per-node state**, unsafe under nesting or reentrant calls (`inProxy`, `transfer`/`schedule`, `store`/`useStorage`, `Active`'s single shared `timer`). The fix pattern is `withSlot` (save previous value, set new, run, restore previous in `finally`) or — better — moving the state onto the specific object it belongs to (e.g., `Active`'s timers now live on `g.timers` per-graph-node, not one shared array). When adding new module-level state that gets mutated inside a callback, ask: **can this function be called while another call to the same function is still in progress (nested or nearly-concurrent)?** If yes, it needs `withSlot` or per-instance storage, not a bare `let`.
+
+---
+
+## The Graph model (`graph/graph.js`)
+
+Every dynamic construct (`condition`, `for-each` item, `component`, `template`, `key`) gets a `Graph` node: `{ref, children, parent, move, insertAfter, getElement, remove, killDown, ...}`.
+
+- **`ref`** can point to: a real DOM node, another `Graph` node (recursive — chase via `getElement()`), or be temporarily unset. `getElement()` walks the `ref` chain recursively until it finds a concrete node. This is the mechanism that lets deeply nested constructs collapse to a single anchor instead of needing bracket-comment pairs at every level.
+- **`move(anchor)`** repositions a node's DOM before `anchor`. **`insertAfter`-style methods must mirror `move`'s recursive structure** (template-node branch vs. direct-ref branch) — don't hardcode a single anchor node inside a helper like `createItem`; always thread the current anchor through, or moves will silently land in the wrong position (see `for-each` reconciler notes below).
+- **Directionality matters.** `insertBefore(el, anchor)` puts `el` before `anchor`; `anchor.after(el)` (or an `insertAfter` graph method) puts it after. Getting this backwards is a real, easy-to-make mistake — verify against a 3+ item sequence by hand or by testing, not by reading the code once.
+
+---
+
+## `for-each` reconciliation
+
+`for.js`'s `initializer` does keyed, LIS-based reconciliation — not naive full-rebuild:
+
+1. On each evaluate, compare old key order to new key order (`sameArrangement` check). **If identical, do nothing — zero DOM cost.** This is the common case (an unrelated dependency triggered the effect) and must stay free.
+2. If the arrangement changed, compute the **longest increasing subsequence** of old-indices among surviving keys. LIS members are already in correct relative order and are *not* moved.
+3. Walk backward (`i = length-1` down to `0`), maintaining a **running anchor** (starts at the `comment`, updated to each processed item's own element after handling it) — never anchor every move against one fixed node. Anchoring everything against a single fixed node breaks correctness the moment some items are skipped (stable/LIS) and others aren't.
+4. `createItem` must accept and insert against the **passed-in anchor**, not a hardcoded `comment`. A hardcoded anchor in `createItem` was a real bug: it caused a second newly-created item to land behind the first instead of in its correct position.
+5. New pushes should land visually **after** the current last item (`children[length-1]`), matching `array.push()` intuition — this requires `.after()`, not `insertBefore`, when re-anchoring the marker comment (getting the direction backward here was also a real, caught bug).
+6. `enqueueUpdate` chains updates through a promise (`updatePromise`) so overlapping triggers (e.g., two removals in quick succession, each awaiting exit-animation time via `Transition`) queue correctly instead of racing. This path is less thoroughly tested than the single-update case — see Testing below.
+
+When touching this file: **test with a running app, not just by reading the diff.** Every bug in this reconciler so far was only caught by actually running append/swap/remove/reinsert/filter sequences, never by code review alone.
+
+---
+
+## SSR / Continuity (SCP — Server Continuation Protocol)
+
+The core idea: SSR produces (a) real HTML with `p:id` attributes marking construct boundaries, and (b) a flat, id-keyed JSON payload carrying only what's genuinely needed to resume without recomputation. The client resumer (`pawajs-continue`) walks the JSON, not the DOM — one targeted lookup per entry via `p:id`, never a DOM traversal.
+
+### Payload principles — do not violate these when adding a new construct
+
+- **Flat, not tree-shaped.** No nested structural encoding in the JSON — position/ownership is discovered via `p:id` lookups and explicit `forkey` tags, not by JSON nesting. This is what keeps the format backend-portable (any language can emit a flat object; no language-specific tree-shape assumptions).
+- **Gated by proxy-touch, at the finest available granularity.** A construct earns a JSON entry only if `isProxy` fired true for its evaluation — not because it's "inside a client boundary," not because its type is usually reactive. This applies down to individual props and hook calls on components, not just whole components.
+- **`id` is a pure lookup handle. `key` is diff identity.** Never conflate them. A `for-key` item's `id` is how the resumer finds its DOM node; its `key` is what a future array diff uses to decide "same item, moved" vs. "new item."
+- **`hydrate.ref` follows one of two patterns**, and both are legitimate — know which one you're in:
+  - **Sentinel (`ref: "ref"`)**: "resolve by chasing into children/self" — used by `condition`, `await`, `template`, `component` boundaries that don't correspond to a single fixed element yet.
+  - **Direct (`ref: "<own id>"`)**: the construct's own element is the final anchor (most components, `state`, `Active`-style self-binding via `useRef()`).
+  - Note: `ref="ref"` as a literal *HTML attribute* is a completely different thing — it's `useRef()`'s own binding syntax (the string is the JS variable name), unrelated to the hydrate sentinel. They share a string value coincidentally, not semantically.
+- **Every hydrate node needs a `type` field.** The resumer dispatches on it. Don't add a construct type without one — relying on field-shape inference instead of an explicit `type` was a real gap that got fixed; don't reintroduce it.
+- **`resolved` (on `await` nodes) means "settled and ready to attach," not "succeeded vs failed."** Success/error is carried by which branch's HTML actually rendered (`awaits` vs `awaitError`), not by this field — both branches correctly set `resolved:true`.
+- **`forkey`** tags a nested construct with its owning `for-each` item's key, so a flat `children` array under a `for-each` node can still be correctly attributed per-item without nesting. Only relevant when the parent hydrate node looks like a for-each (`hydrate?.arrayName` present).
+- **Region ownership, not per-element ids.** `p:id` marks the boundary of a *construct's region* — everything inside (plain, non-reactive content) shares that id. Don't expect one id per DOM node; expect one id per independently-resolvable reactive unit.
+
+### Per-construct resume strategy — don't unify these into one code path
+
+- **`condition` / `for-each`** — genuinely paused: seed comparison state (`oldChain`/`current`, keyed `children`) from JSON, skip the first `evaluate()` entirely (`isHydrate?.enter` check), resume real computation only at the next genuine trigger.
+- **`await`** — resolved/error value handed straight into context via the same merge `apply()` uses live. The promise function is never called. Retry (if the app needs it) goes through a `Key`-forced remount at the parent, not a bespoke retry mechanism inside `Await` itself.
+- **`component`** — re-executes in full on the client (cheap; accepted cost) to rebuild `useInsert` context and effects, but the returned HTML string is discarded — the component attaches to the already-correct SSR element found via `p:id`, never rebuilding DOM.
+- **`only-client`** — opts out of SSR entirely. Ships as an inert `<template on-client>` for the client to instantiate fresh. No JSON entry, since nothing was evaluated server-side.
+- **`state-*` attributes** — SSR-evaluated inline; the resolved value **must** be sent (nothing re-derives it). Component-*internal* `$state` calls (inside a component's JS body) do **not** need to be sent — the component's re-execution naturally reproduces them for free. Don't send both; sending the internal ones is pure duplication.
+
+### Detection: `.client` / `force` / auto-inheritance
+
+A component is treated as client if **any** of:
+1. Registration-time flag (`Component.client = true` on the function itself — e.g. `Active`, `Transition`).
+2. Internal hook usage (`$state`, `stateWatch`) — calling a client-reactive hook is itself what marks the component client, as a side effect of the call, via `AsyncLocalStorage`-scoped detection during SSR.
+3. Ancestor is client (transitive through non-client intermediaries).
+4. **`force`** — an SSR-time template directive (`el.hasAttribute('force')`), scoped per usage site, not a static component property. Exists specifically for the one case `isProxy` structurally cannot see: a function value (event handler, callback) passed as a prop or into `useInsert`'s context. Calling a function during SSR never executes its body, so state read *inside* that function is invisible to proxy-touch detection — `force` is the deliberate escape hatch, applied at the exact call site that needs it.
+
+Once a component is client for any reason, **nested components under it do not need repeated manual `force` calls** just because they also carry function-valued context — a check inside already-confirmed client boundaries handles function-valued `useInsert`/context entries automatically. `force` is only for establishing the boundary in the first place, not for every nested case beneath it.
+
+`$state` cannot be called in a component that isn't (or doesn't become) client — calling it is what makes a component client, there's no separate permission check.
+
+### Streaming
+
+Raw chunked HTTP, not SSE. First chunk: fully resolved content + placeholders (`awaitsLoading`, `resolved:false`) for pending `await`s. Each pending item resolves independently and flushes its own chunk with an inline `<script>` on settling — never waits for siblings. Client/server rendezvous is a flat, id-keyed handshake (`window.awaits[id]` / `window.states[id]`): whichever side (server chunk arriving, or client resumer walking to that point) gets there *second* consumes what the *first* side left behind. Neither side polls or waits.
+
+---
+
+## Directive reference (current, post-rewrite)
+
+- `if` / `else` / `else-if` — conditional rendering. (`switch`/`case`/`default` are **removed**.)
+- `for-each` + `for-key` — keyed list rendering (see reconciliation notes above).
+- `state-*` — inline reactive state scoped to an element and its children.
+- `await` / `as-fallback` / `as-catch` — async handling. `await` must be given a **function that returns a promise**, never an already-invoked call (`await="fetchUser"`, not `await="fetchUser()"`). `as="name"` binds the resolved/caught value under a custom name (defaults: `res` / `error`).
+- `key` — forces a full remount when its watched value changes. Used as the retry mechanism for failed `await`s (force a parent `Key` change rather than building retry into `Await`).
+- `on-<event>` / `out-<event>` — event handling, with `.self`/`.prevent`/`.once`/`.capture` chain modifiers.
+- `:prop` — reactive component prop.
+- `<slot>` / `<slot name="...">` — content projection (not a `children` prop — this changed in the rewrite).
+- `<template prop="name">` — pass a raw string/markup chunk as a prop value.
+- `aschild` — component's root element merges into (rather than wraps) what the caller passed.
+- `ref` — bind a `useRef()` object to an element. Unrelated to the SCP hydrate sentinel of the same string value — see note above.
+- `force` — SSR directive forcing a component to client status at this usage site (see Detection above).
+- ~~`is-exit`~~ — **removed.** Superseded by `Transition`'s own `onExit`/`onEnter` graph hooks, which wait for the exit animation before actual DOM removal automatically.
+- ~~`useServer`, `useAsync`/`$async`~~ — **removed.** No async-component mode; use `await`/`as-fallback`/`as-catch` instead.
+
+## Built-in components
+
+- **`Active`** — `:show="expr"` controls visibility (`display:none`) and pauses/resumes reactive effects underneath while hidden (via `graph.active` + `graph.unActive`, see reactivity notes above). Always client (`Active.client = true`).
+- **`Transition`** — `:enter`/`:exit` (class-name arrays or inline style-string arrays, same shape as `el.animation()`) + `:duration` (default 300ms). Waits for the exit animation to finish before the element is actually removed. Always client.
+
+---
+
+## Testing conventions
+
+There is no automated correctness harness yet (SSR-render → resume → compare against fresh client render is a known, not-yet-built gap — high priority if adding one). Until it exists:
+
+- **Trust real, running output over code review for anything touching the reconciler, the Graph model, or resume seeding.** Every bug caught in these areas during development was found by actually running sequences (append/remove/reorder/filter), never by reading the diff.
+- When testing `for-each` changes, exercise at minimum: append, remove-from-middle, filter-then-restore (items reappearing at original relative position), multi-item reorder (not just single swaps), and rapid back-to-back updates (overlapping `enqueueUpdate` calls, especially with `Transition`'s exit-animation delay in play).
+- When testing SSR/continuity changes, check real payload output for: correct `type` per node, correct `resolved` semantics on `await`, `p:id` region boundaries matching expectations, and — critically — that pruning is actually happening (static/non-reactive content should produce **zero** hydrate entries, not just small ones).
+
+---
+
+## Things intentionally *not* built yet — don't assume otherwise
+
+- No automated resume-correctness harness.
+- No second (non-JS) backend implementation of SCP — portability is a design property, not yet a proven one.
+- No dev-mode warning system beyond the initial `stripComponent` (statically-pruned-but-in-a-client-boundary) warning — a broader dev-mode/error-handling pass is planned but not started.
+- No PML (partial re-render / DOM morph after initial resume) — designed in concept (compare live Graph tree against a parsed incoming tree, route first-boundary component updates through `reProps` rather than DOM diffing) but unimplemented.
+- No large-list payload/perf measurement has been taken yet — treat "for-each cost at scale" as an open, unmeasured question, not a solved one.

package/CHANGELOG.md

@@ -23,4 +23,6 @@ CHANGELOG.md
 + version 2.0.1 -2.0.2 made runEffect to be global or component capability
 + version 2.0.3 integrating HMR system
 + version 2.0.4 experimental of hmr
-+ version 2.0.5 - 2.0.6 experimental of hmr
++ version 2.0.5 - 2.0.6 experimental of hmr
++ 2.4.0.beta.4 new pawajs Rewrite;
++ 2.4.0.beta.5 - 2.4.0.beta.7 added LIS for ForEach directive

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -3,24 +3,30 @@ pawajs - power the web (reactivity and html runtime)
 
 # PawaJS
 
-**A lightweight and reactive JavaScript library for building modern web interfaces with a simple, declarative syntax.**
+**A lightweight and reactive JavaScript library for building modern web interfaces with a simple, declarative syntax (15kb).**
 
-PawaJS (reactive web runtime) is a JavaScript library designed for building dynamic user interfaces. It combines a component-based architecture and progressive enhancement with a powerful reactivity system no v-dom. Its intuitive, directive-based templating feels familiar and makes it easy to create interactive applications, from simple widgets to complex single-page apps. With built-in support for server-side rendering using pawa-ssr (server rendering runtime) and pawajs-continue (continuous rendering), PawaJS is equipped for performance and scalability.
+PawaJS (reactive web runtime) is a JavaScript library designed for building dynamic user interfaces. It combines a component-based architecture and progressive enhancement with a powerful reactivity system, no v-dom. Its intuitive, directive-based templating feels familiar and makes it easy to create interactive applications, from simple widgets to complex single-page apps. With built-in support for server-side rendering using pawa-ssr (server rendering runtime) and pawajs-continue (continuity runtime), PawaJS is equipped for performance and scalability.
+
+PawaJS is a **reactive web runtime** for HTML-first UIs: components, directives, and fine-grained `$state` updates with **no virtual DOM**.
+
+On the client it powers widgets through SPAs. With **pawa-ssr** and **pawajs-continue** it uses **selective continue** (SCP): the server sends HTML plus a sparse index of reactive areas; the client continues only those areas. **Static components are stripped** from that index so they are not re-executed on the client.
 
 🌐 **Website:** [pawajs.vercel.app](https://pawajs.vercel.app)
 
----
+
 
 ## Features
 
--   **Declarative Rendering:** Use a clean, HTML-based template syntax with powerful directives (`if`, `for-each`, `on-event`, etc.) to describe your UI.
+-   **Declarative Rendering:** Use a clean, HTML-based template syntax with powerful directives (`if`, `for-each`, `await`, `on-event`, etc.) to describe your UI.
 -   **Reactive State Management:** Effortlessly create reactive state that automatically updates the DOM when it changes using the `$state` utility.
--   **Component-Based Architecture:** Build encapsulated components with just js function that manage their own state, making your code more reusable and maintainable.
--   **Async Components:** First-class support for asynchronous components, allowing you to fetch data directly within your component definition.
+-   **Component-Based Architecture:** Build encapsulated components with just a JS function that manages its own state, making your code more reusable and maintainable. Components are synchronous by default — no async component mode to reason about.
+-   **First-Class Async Handling:** Fetch and await data directly in your templates with the `await` / `as-fallback` / `as-catch` directives — no special component wiring required.
 -   **Efficient List Rendering:** Render lists of data with the `for-each` directive, including support for keyed updates for optimal performance.
 -   **Lifecycle Hooks:** Tap into a component's lifecycle with `mount` and `unmount` directives, or the `runEffect` hook for more complex side effects.
 -   **Context API:** Pass data through the component tree without having to pass props down manually at every level.
--   **Server-Side Rendering (SSR) Isomorphic architecture:** PawaJS is built with SSR in mind, featuring a "resuming" mechanism to efficiently continue server-rendered HTML on the client.
+
+- **Selective continue (SSR):** `pawa-ssr` emits HTML + SCP; `pawajs-continue` binds reactive regions only. Static UI stays plain HTML (no client re-execution).
+---
 -   **Plugin System:** Extend PawaJS's core functionality with custom directives and lifecycle behaviors.
 
 ---
@@ -33,7 +39,7 @@ Install PawaJS into your project using npm:
 npm install pawajs
 ```
 CDN
- 
+
 ```html
     <!doctype html>
 <html lang="en">
@@ -86,7 +92,7 @@ CDN
 
 OR
 
-Then, you can import it into your application: through npm
+Then, you can import it into your application through npm:
 
 ```javascript
 import { pawaStartApp, $state, RegisterComponent, html } from 'pawajs';
@@ -162,7 +168,7 @@ pawaStartApp(appElement);
 
 ### State Management with `$state`
 
-The `$state` function is the heart of PawaJS's reactivity. It creates a reactive object whose `value` property can be read and written to. Any changes to `.value` will automatically trigger updates in the parts of your application that depend on it (fine-granded) no component re-rendering or diffing. `$state` can be global when used outside a component. Also inline state in the html or template `state-*="any js types"`
+The `$state` function is the heart of PawaJS's reactivity. It creates a reactive object whose `value` property can be read and written to. Any changes to `.value` will automatically trigger updates in the parts of your application that depend on it (fine-grained) — no component re-rendering or diffing. `$state` can be global when used outside a component. You can also declare inline state directly in HTML or a template with `state-*="any js value"`.
 
 ```html
     <!--- number-->
@@ -187,48 +193,37 @@ name.value = 'PawaJS'; // The UI will update automatically
 const user = $state({ name: 'Alex', loggedIn: false });
 user.value.loggedIn = true; // This is also reactive
 
-// Persist state to localStorage
+// Persist state to localStorage — wrap the $state call in useStorage(),
 // The state will be saved under the key 'session' and reloaded on page refresh.
-const session = $state({ id: null }, 'session');
+const session = useStorage(() => $state({ id: null }), 'session');
 
 // Compute state - must be used inside a component
-// when ever count changes the state update
+// whenever count changes, the state updates
 const doubleCount=$state(()=>count.value * 2,[count])
 
 //AutoCompute
-// Any function that uses any reactive state for reactive bindings or direcives becomes computed function
+// Any function that uses any reactive state for reactive bindings or directives becomes a computed function
 const doubleCount=()=>count.value * 2
+
+// Schedule a batch of state updates through the frame-budgeted scheduler
+// instead of the default immediate/microtask path — useful for grouping a
+// burst of updates so they get spread across animation frames rather than
+// forced through synchronously in one go.
+schedule(() => {
+    count.value++
+    name.value = 'Updated'
+})
 ```
 
 ### Components
 
-Components are the building blocks of your application. In PawaJS, a component is a JavaScript function that returns an HTML template string or not.
+Components are the building blocks of your application. In PawaJS, a component is a **synchronous** JavaScript function that returns an HTML template string, or nothing.
 
 -   **Defining:** Create a function that returns a template or not.
 -   **Registering:** Use `RegisterComponent(MyComponent)` to make it available globally. In HTML, you can then use it as `<my-component>`.
 -   **`useInsert`:** To make variables, state, and functions from your component's setup available in its template, pass them in an object to `useInsert()`.
 
-### Asynchronous Components
-
-PawaJS supports async components ( `useAsync()` hook) out of the box. You can define a component as an `async` function, allowing you to perform asynchronous operations (like fetching data) before the component renders.
-wrap any pawajs hook with $async after any await call
-
-```javascript
-const UserProfile = async () => {
-    // Async hook store the current component instance for $async to use
-    const {$async}=useAsync()
-    // The component will wait for this promise to resolve before rendering
-    const data = await fetch('/api/user').then(res => res.json());
-    const user = $async(()=>$state(data);)
-    $async(()=>useInsert({user}))
-
-    return html`
-        <div class="profile">
-            <h1>@{user.value.name}</h1>
-        </div>
-    `;
-}
-```
+Components are always synchronous — there's no separate "async component" mode to learn. If a component needs to fetch or await data, reach for the [`await` directive](#await--as-fallback--as-catch) inside its template instead.
 
 ### Templating
 
@@ -249,7 +244,7 @@ PawaJS uses a simple `@{...}` syntax to embed dynamic JavaScript expressions dir
 Directives are special attributes that apply reactive behavior to DOM elements.
 
 #### `state-*`
-create inline state for the element and children 
+Create inline state for the element and its children.
 
 ```html
     <div state-count="0">
@@ -258,7 +253,6 @@ create inline state for the element and children
 
 ```
 
-
 #### `if` / `else` / `else-if`
 For conditional rendering.
 
@@ -273,36 +267,15 @@ For conditional rendering.
     Please log in to continue.
 </div>
 ```
-#### `switch` / `case` / `default`
-switch conditional rendering.
 
-```html
-<div switch="user.value.type" case="'admin'">
-    Welcome back, @{user.name.value}!
-</div>
-<div case="'guest">
-    You are browsing as a guest.
-</div>
-<div default>
-    Please log in to continue.
-</div>
-```
 #### `key`
-re-renders the element/component when the reactivity changes 
+Re-renders the element/component when the value it watches changes.
 
 ```html
 <user-component key="user.value.type"></user-component>
 
 ```
 
-#### `is-exit`
-makes pawajs engine to wait before removing the element until the animation/transition is done.
-
-```html
-<div if="user.value.loggedIn" class="user-card @{user.value.isActive ? 'active' : 'inactive'}" is-exit>
-    <input value="@{user.value.name}" on-input="user.value.value = e.target.value">
-</div>
-```
 #### `for-each`
 For rendering lists from an array. Use `for-key` to give each element a unique identity, which helps PawaJS optimize rendering.
 
@@ -314,7 +287,35 @@ For rendering lists from an array. Use `for-key` to give each element a unique i
 </ul>
 ```
 
-#### `on-<event>..chainModifiers` 
+#### `await` / `as-fallback` / `as-catch`
+For handling asynchronous data directly in a template — no async component wiring needed. The `await` attribute must point to a **function that returns a promise**, not an already-invoked call.
+
+The resolved value is exposed in scope under `res` by default (the caught error under `error`), or under whatever name you give with `as`.
+
+```html
+<div await="fetchUser">
+    <p>Welcome, @{res.name}</p>
+</div>
+<div as-fallback>
+    <p>Loading...</p>
+</div>
+<div as-catch>
+    <p>Failed to load: @{error.message}</p>
+</div>
+```
+
+Use `as` to bind the resolved (or caught) value under a custom name:
+
+```html
+<div await="fetchUser" as="user">
+    <p>Welcome, @{user.name}</p>
+</div>
+<div as-catch as="err">
+    <p>Failed to load: @{err.message}</p>
+</div>
+```
+
+#### `on-<event>..chainModifiers`
 modifiers - 'self','prevent','once','capture' etc
 For handling DOM events.
 
@@ -322,19 +323,46 @@ For handling DOM events.
 <button on-click="addTodo()">Add Todo</button>
 <input on-input="newTodoText.value = e.target.value" />
 ```
+
 #### `out-<event>.chainModifiers`
 modifiers - 'self','prevent','once','capture' etc
-For handling DOM events.
+For handling events fired outside the element.
 
 ```html
 <button out-click.once="console.log('outside')">Add Todo</button>
 ```
 
+#### `after-[ms]` / `every-[ms]`
+Run a callback once after a delay or repeatedly on an interval. The expression is evaluated with the current render context and the timer is cleaned up when the component unmounts.
+
+```html
+<div after-[2000]="console.log('done after 2s')"></div>
+<div every-[1000]="count.value++"></div>
+```
+
+This is the runtime timer directive path used by the graph scheduler and is cleaned up automatically on unmount.
+
+### Direct element property updates (JSA) - JavaScript Attribute
+PawaJS also supports direct property assignment (javascript element attribute)  with the `@` shorthand on an element. This avoids needing to write a full `on-*` event handler when you just want to set a DOM property or style field.
+
+```html
+<div @style.color="red" @inner-text="inner text"></div>
+```
+
+Nested properties are also supported:
+
+```html
+<div @style.background-color="tomato" @dataset.role="admin"></div>
+```
+
+The same shorthand works for native properties like `@value`, `@checked`, `@textContent`, and `@innerHTML`.
+
 ### Component Props
 
 You can pass data from a parent component to a child component using props. To declare a prop, prefix the attribute with a colon (`:`).
-Children are passed by default in pawajs, they are not functional prop.
-For rest props pass `--` to the element that needs the attributes.
+
+Children are **not** passed as a prop in PawaJS — they're passed as a `<slot>`, the same way native web components handle content projection. For rest props, pass `--` to the element that needs the attributes.
+
 **Parent Component (`app.js`)**
 ```javascript
 // ...
@@ -342,13 +370,15 @@ const message = $state('This is a message from the parent!');
 useInsert({ message });
 
 return html`
-    <todo-list title="My Todo List" :message="message.value" class="to the rest prop">Children in here</todo-list>
+    <todo-list title="My Todo List" :message="message.value" class="to the rest prop">
+        <p>Children go in here</p>
+    </todo-list>
 `;
 ```
 
 **Child Component (`todo-list.js`)**
 ```javascript
-export const TodoList = ({ title, message,children }) => {
+export const TodoList = ({ title, message }) => {
     // Props are passed as functions that return the reactive value
     useInsert({ title, message });
 
@@ -356,7 +386,7 @@ export const TodoList = ({ title, message,children }) => {
         <div -->
             <h2>@{title()}</h2>
             <p>@{message()}</p>
-            ${children}
+            <slot></slot>
         </div>
     `;
 }
@@ -374,6 +404,106 @@ useValidateComponent(TodoList, {
 });
 ```
 
+### Slots
+
+A component's `<slot>` is where the caller's children land. A plain `<slot></slot>` (or a `<slot name="default">`) catches every child the caller passed that wasn't targeted at a specific named slot — this is what `TodoList` above uses.
+
+You can have **more than one slot**, each with its own `name`, to project different pieces of content into different parts of a component's template. On the caller's side, target a named slot with a `<template slot="name">` wrapper:
+
+**Parent (`app.js`)**
+```javascript
+return html`
+    <card-panel>
+        <template slot="header">
+            <h2>Project status</h2>
+        </template>
+
+        <p>This is the default slot content — the body of the card.</p>
+
+        <template slot="footer">
+            <button on-click="dismiss()">Dismiss</button>
+        </template>
+    </card-panel>
+`;
+```
+
+**Child (`card-panel.js`)**
+```javascript
+export const CardPanel = () => {
+    return html`
+        <div class="card">
+            <header>
+                <slot name="header"></slot>
+            </header>
+            <section class="card-body">
+                <slot></slot>
+            </section>
+            <footer>
+                <slot name="footer"></slot>
+            </footer>
+        </div>
+    `;
+}
+```
+
+Anything the caller passes that isn't wrapped in a `<template slot="...">` falls through to the unnamed default slot — so plain, un-templated children and a `<template slot="...">` block can be mixed freely on the same call site, as in the example above.
+
+### Passing a string prop with `<template prop="...">`
+
+Sometimes you want to pass a chunk of raw markup or text to a component as a **prop value** (a string), not as projected content. Use `<template prop="name">` for that — its inner HTML becomes the string value of that prop, available on the child the same way any other prop is.
+
+```javascript
+// Parent
+return html`
+    <alert-box>
+        <template prop="message">Something went wrong.</template>
+    </alert-box>
+`;
+```
+
+```javascript
+// Child (alert-box.js)
+export const AlertBox = ({ message }) => {
+    useInsert({ message });
+    return html`
+        <div class="alert">@{message()}</div>
+    `;
+}
+```
+
+A component's root element can also **become** whatever the caller passed, instead of wrapping it, by marking either the component's own root with `aschild` or letting a top-level `<slot>` take over as the root — useful when a component shouldn't add an extra wrapping element (e.g. a `Button` component that should render as the caller's own `<a>` if one is passed). In that case, the two elements' attributes are merged rather than one replacing the other — `class`/`style` are concatenated, everything else is kept from both (with collisions resolved by prefixing).
+
+---
+
+## Built-in Components
+
+PawaJS ships two built-in components for common structural and animation needs.
+
+### `Active`
+
+Controls whether its content is visible and reactive, toggling `display: none` and pausing/resuming the effects underneath it based on a `show` prop. Useful for tabs, panels, or any content that should stop doing reactive work while it's hidden.
+
+```html
+<active :show="isOpen.value">
+    <expensive-panel></expensive-panel>
+</active>
+```
+
+### `Transition`
+
+Wraps its content with enter/exit animation. When the content is added to the DOM, `Transition` plays the `enter` animation; when it's about to be removed (e.g. an `if` flipping false), it plays `exit` first and waits for it to finish before the element is actually taken out — so removal-triggering content never just vanishes mid-animation.
+
+`enter` and `exit` take the same frame arguments as `el.animation()` — either an array of class names or an array of inline style strings — and `duration` controls how long each takes (defaults to `300`ms).
+
+```html
+<transition 
+    :enter="['opacity-0 scale-95', 'opacity-100 scale-100']"
+    :exit="['opacity-100 scale-100', 'opacity-0 scale-95']"
+    :duration="250">
+    <div if="user.value.loggedIn">Welcome back!</div>
+</transition>
+```
+
 ---
 
 ## API Reference
@@ -381,17 +511,34 @@ useValidateComponent(TodoList, {
 ### Core Functions
 -   `pawaStartApp(rootElement, initialContext)`: Initializes the PawaJS application on a given root DOM element.
 -   `RegisterComponent(...components)`: Registers one or more components to be used in templates.
--   `$state(initialValue, localStorageKey?)`: Creates a new reactive state object. Used inside or outside Component (module export)
--   `PluginSystem(plugin)`: Registers a plugin to extend PawaJS functionality (e.g., Routers, Global Stores).
+-   `Graph(parentGraph?)`: Creates a render graph node for a component or section of the DOM tree. This is the low-level runtime model used to track child nodes, lifecycle hooks, and reactive state.
+-   `PawaRender(graph, contexts?)`: Creates a render driver and returns `{ render, renderGraph, setContext }`. It walks a DOM subtree, resolves directives, mounts components, and attaches the current context graph to each node.
+-   `setComponentGraph(graph)` / `getComponentGraph()`: Set or read the active component graph from the current rendering context.
+-   `$state(initialValue, section?)`: Creates a new reactive state object. Used inside or outside a component (module export). `section` is used for compute dependencies (pass an array) or for naming an async batch — not for localStorage persistence.
+-   `useStorage(createCall, name)`: Wraps a `$state` creation call so its value is persisted to `localStorage` under `name` and restored on reload.
+-   `schedule(callback)`: Runs any state updates made inside `callback` through the frame-budgeted scheduler instead of the default immediate path — useful for batching a burst of updates across animation frames.
+-   `Plugin(plugin)`: Registers a plugin to extend PawaJS functionality (e.g., Routers, Global Stores).
 -   `html`: A tagged template literal for syntax highlighting and potential future optimizations.
 
 ### Component Hooks
 -   `useInsert(object)`: Exposes data and functions from a component's setup to its template.
--   `runEffect(callback, dependencies?)`: Runs a side effect after or before the component renders, and re-runs it when its dependencies change . Used inside or outside Component 
+-   `runEffect(callback, dependencies?)`: Runs a side effect after or before the component renders, and re-runs it when its dependencies change. Used inside or outside a component.
 -   `useContext(contextObject)` & `setContext()`: A mechanism for providing and consuming data throughout a component tree.
 -   `useRef()`: Creates a reference object that can be attached to a DOM element using the `ref` directive.
 -   `useValidateComponent(Component, rules)`: Defines validation rules for a component's props.
--   `useServer()`: Returns `{ setServerData, getServerData }` for handling server-side data serialization and client-side retrieval in SSR applications.
+
+### Low-level Render Graph
+PawaJS keeps internal render metadata in a graph object attached to the DOM node tree. That graph tracks parent/child relationships, mount hooks, enter/exit transitions, storage for context, and the current render state. This is the runtime structure behind directives like `if`, `for-each`, `key`, `await`, and component mounting.
+
+```javascript
+import { Graph, PawaRender } from 'pawajs';
+
+const graph = Graph();
+const { render, renderGraph } = PawaRender(graph, { user: { name: 'Pawa' } });
+render(document.getElementById('app'));
+```
+
+The graph is not usually something app code needs to manipulate directly, but it is the internal foundation for the library's reactive rendering pipeline and is exposed for advanced runtime integration and debugging.
 
 ---
 

package/examples/Text.js

@@ -0,0 +1,5 @@
+import { html } from "../src/hooks/index.js"
+
+export const Text=()=>{
+    return html`<h1>TEXTING COMPONENT LAZYLOADING</h1>`
+}