ajo 0.1.33 → 0.1.35

package/LLMs.md

@@ -74,8 +74,8 @@ const Counter: Stateful<Args, 'section'> = function* ({ initial }) {
   }
 }
 
-Counter.is = 'section'                    // wrapper element (default: div)
-Counter.attrs = { class: 'counter-wrap' } // default wrapper attributes
+Counter.is = 'section'                    // host element (default: div)
+Counter.attrs = { class: 'counter-wrap' } // default host attributes
 Counter.args = { step: 1 }                // default args
 
 // Or use stateful() to avoid duplicating 'section':
@@ -83,19 +83,19 @@ Counter.args = { step: 1 }                // default args
 // Counter.attrs = { class: 'counter-wrap' }
 // Counter.args = { step: 1 }
 
-// Example usage - special attrs apply to wrapper, rest goes to args:
+// Example usage - special attrs apply to the host, rest goes to args:
 
 let ref: ThisParameterType<typeof Counter> | null = null
 
 <Counter
   initial={0} step={5}                    // → args
-  attr:id="main" attr:class="my-counter"  // → wrapper attributes (HTML attrs)
-  set:onclick={fn}                        // → wrapper properties (DOM props)
-  key={id}                                // → wrapper key
-  memo={[id]}                             // → wrapper memo (array)
-  memo={id}                               // → wrapper memo (single value)
-  memo                                    // → wrapper memo (render once)
-  ref={el => ref = el}                    // → wrapper ref (el is <section> + .next()/.throw()/.return())
+  attr:id="main" attr:class="my-counter"  // → host attributes (HTML attrs)
+  set:onclick={fn}                        // → host properties (DOM properties)
+  key={id}                                // → host key
+  memo={[id]}                             // → host memo (array)
+  memo={id}                               // → host memo (single value)
+  memo                                    // → host memo (render once)
+  ref={el => ref = el}                    // → host ref (el is <section> + .next()/.throw()/.return())
 />
 
 ref?.next()  // trigger re-render from outside
@@ -105,27 +105,29 @@ ref?.next()  // trigger re-render from outside
 
 | Topic | Rule |
 |-------|------|
-| **Elements** | Everything becomes HTML attributes. `set:prop` assigns DOM properties instead (`node[prop] = value`) |
+| **Elements** | Everything becomes HTML attributes. `set:property` assigns DOM properties instead (`node[property] = value`) |
 | **Stateless** | Everything goes to `args`. Special attrs like `memo` must be applied to elements inside |
-| **Stateful** | `key`, `memo`, `skip`, `ref`, `set:*` apply to implicit wrapper element. `attr:*` sets wrapper attributes. Rest goes to `args` |
+| **Stateful** | `key`, `memo`, `skip`, `ref`, `set:*` apply to the host (the implicit wrapper DOM element every stateful component gets). `attr:*` sets host attributes. Rest goes to `args` |
 | **Events** | `set:onclick`, `set:oninput`, etc. Never `onClick` |
 | **Classes** | `class`, never `className`. Must be string, no object/array syntax. Use `clsx()` or template literals |
 | **Styles** | `style` must be string (`style="color: red"`), not object. No special handling |
-| **Args** | Destructure in parameter for init code. Render loops: `for (const { prop } of this)` for fresh args each cycle (new bindings), or `for ({ prop } of this)` without `const` to reassign variables from the outer scope. `while (true)` when you don't need fresh args |
+| **Args** | Destructure in parameter for init code. Render loops: `for (const { step } of this)` for fresh args each cycle (new bindings), or `for ({ step } of this)` without `const` to reassign variables from the outer scope. `while (true)` when you don't need fresh args |
 | **Generators** | Stateful components are JS generators with a main render loop (`while`/`for...of`). Since they're generators, yields can also appear outside the loop — sequential phases, conditional blocks, etc. are all valid |
-| **Root JSX** | Use `<>...</>` in stateful to avoid double wrapper |
+| **Root JSX** | Use `<>...</>` in stateful to avoid an extra element inside the host |
 | **Re-render** | `this.next(fn?)` — returns `fn`'s result. Safe after unmount (no-op). Use `this.throw(e)` for explicit error routing |
 | **Context** | `context<T>(fallback)` creates context. Stateless: read only. Stateful: read/write. Reads go inside loop (fresh each render). Constant writes can go before loop; dynamic writes go inside loop |
 | **Lists** | Always provide unique `key` on elements |
+| **SVG** | Set `xmlns="http://www.w3.org/2000/svg"` on the root `<svg>` element — children inherit the namespace |
 | **Refs** | `ref={el => ...}` on elements. Receives `null` on unmount. Stateful ref type: `ThisParameterType<typeof Component>` |
 | **Memo** | `memo={[deps]}` array, `memo={value}` single, or just `memo` (never re-render). Skips subtree if unchanged |
 | **Skip** | `skip` excludes children from reconciliation; it does not sanitize `set:innerHTML` |
-| **Custom wrapper** | `stateful(fn, 'tagname')` sets `.is` and infers `this` type. Or manually: `Stateful<Args, 'tagname'>` + `.is = 'tagname'`. Default is `div` (no need to set) |
+| **Custom host** | `stateful(fn, 'tagname')` sets `.is` and infers `this` type. Or manually: `Stateful<Args, 'tagname'>` + `.is = 'tagname'`. Default is `div` (no need to set) |
 | **Default attrs** | `.attrs = { class: '...' }` on stateful component generator function |
-| **Default args** | `.args = { prop: value }` on stateful component generator function |
+| **Default args** | `.args = { step: 1 }` on stateful component generator function |
 | **Cleanup** | `this.signal` aborts on lifecycle end (unmount, `this.return()`, generator done). Use for fetch, addEventListener, etc. `try/finally` for the rest |
 | **Error recovery** | `try { ... } catch { yield error UI }` inside loop |
-| **this** | Stateful wrapper element with `.signal`, `.next(fn?)` (returns `fn`'s result), `.throw()`, `.return(deep?)`. Iterable: `for...of this` yields args. Type: `ThisParameterType<typeof Component>` |
+| **this** | The host element with `.signal`, `.next(fn?)` (returns `fn`'s result), `.throw()`, `.return(deep?)`. Iterable: `for...of this` yields args. Type: `ThisParameterType<typeof Component>` or `Host` |
+| **Cloves** | Shared logic = plain function `(host: Host, options?) => live view`. Pass `this` as host. See Cloves section |
 
 ## Common Patterns
 
@@ -144,8 +146,8 @@ const DataLoader: Stateful<LoaderArgs> = function* ({ url }) {
 
   fetch(url, { signal: this.signal })  // signal auto-aborts on lifecycle end
     .then(r => r.json())
-    .then(d => this.next(() => data = d))   // no-op if unmounted
-    .catch(e => this.next(() => error = e)) // no-op if unmounted
+    .then(d => this.next(() => data = d)) // no-op if unmounted
+    .catch(e => e.name == 'AbortError' || this.next(() => error = e)) // skip AbortError: the signal already fired because the component ended
 
   while (true) yield (
     <>
@@ -252,6 +254,97 @@ let map: MapLibrary | null = null
 <div skip ref={el => el ? (map ??= new MapLibrary(el)) : map?.destroy()} />  // skip lets library control children
 ```
 
+## Cloves — Reusable Logic
+
+A clove is Ajo's unit of shared component logic (what hooks/composables are in other frameworks): a plain function that takes the component host (`this`) and returns a live view of one stateful concern. No runtime, no registry, no ordering rules — generators already provide persistent closures, so the instance protocol (`signal` + `next`) is the whole mechanism.
+
+```tsx
+import type { Host } from 'ajo'
+
+/** Tracks the pointer position. */
+const pointer = (host: Host) => {
+
+  const pos = { x: 0, y: 0 }
+
+  if (typeof document != 'undefined' && host.nodeType == 1) // SSR guard: inert view on the server
+    document.addEventListener('pointermove',
+      e => host.next(() => { pos.x = e.clientX; pos.y = e.clientY }),
+      { signal: host.signal }) // teardown on unmount AND on reset, automatically
+
+  return pos
+}
+
+function* Cursor() {
+  const pos = pointer(this) // setup phase: call before the render loop
+  while (true) yield <p>{pos.x}, {pos.y}</p>
+}
+```
+
+**The contract — all six rules are mandatory when writing a clove:**
+
+1. **Signature**: `(host, options?) => view`. Host first. Options in a single object with defaults, never positional flags.
+2. **Cleanup goes through `host.signal`, exclusively.** Pass `{ signal: host.signal }` to `addEventListener`; use `host.signal.addEventListener('abort', () => ...)` for timers, observers, sockets. Never return a dispose function. This makes teardown compose with unmount and with explicit reset (`el.return()` + `el.next()` restarts the generator with a fresh signal, so setup re-runs and the clove re-subscribes with zero extra code).
+3. **Invalidation goes through `host.next(fn)`**, mutating state inside `fn`. Already safe: no-op after unmount, no reentrant render while rendering.
+4. **The view is a stable reference.** Mutate its fields; never reassign or spread it (that breaks liveness — same contract as Ajo's own live `args`). Use getters for derived values. Name state as nouns (`x`, `open`, `data`), methods as verbs (`load`, `start`).
+5. **Per-render input is an explicit method call inside the render loop**, internally a no-op when input is unchanged. No hidden dependency tracking.
+6. **SSR-inert by shape.** During `ajo/html` SSR the host is protocol-only (`next` is a noop, no DOM). Guard DOM access (`typeof document != 'undefined' && host.nodeType == 1`) and always return the correctly shaped view so universal components can call cloves unconditionally.
+
+Per-render input + async, the canonical shape:
+
+```tsx
+/** Keyed async loader: chains host.signal, re-loads only when the key changes. */
+const loader = <T,>(host: Host) => {
+
+  let key: string | undefined
+
+  const q = {
+    data: null as T | null, error: null as Error | null, loading: false,
+    load(url: string) {
+      if (url == key) return // per-render no-op: rule 5
+      key = url
+      q.loading = true
+      q.data = q.error = null
+      fetch(url, { signal: host.signal })
+        .then(r => r.json())
+        .then(d => host.next(() => { q.data = d; q.loading = false }))
+        .catch(e => e.name == 'AbortError' || host.next(() => { q.error = e; q.loading = false }))
+    },
+  }
+
+  return q
+}
+
+function* User() {
+  const q = loader<{ name: string }>(this)
+  for (const { id } of this) {
+    q.load(`/api/users/${id}`) // reacts to args because it runs every render
+    yield q.loading ? <p>Loading...</p> : q.error ? <p>{q.error.message}</p> : <h1>{q.data!.name}</h1>
+  }
+}
+```
+
+Composition is function calls sharing the host — a clove may call other cloves, and conditional calls are legal (there are no hook rules):
+
+```tsx
+const idle = (host: Host, ms = 60000) => { /* uses timer(host) + pointer(host) internally */ }
+
+function* App(args: { track?: boolean }) {
+  const t = args.track ? idle(this) : { idle: false } // conditional: fine
+  while (true) yield <p>{t.idle ? 'away' : 'here'}</p>
+}
+```
+
+Shared state across components is a clove factory: module-level state + a `Set` of hosts, `next()` on all hosts when mutating, each host auto-unsubscribed via its signal.
+
+```tsx
+// ❌ Clove anti-patterns
+const bad1 = (host: Host) => { /* ... */ return () => cleanup() }   // dispose fn: use host.signal
+const bad2 = (host: Host) => ({ ...state })                         // copy: breaks liveness, return the live object
+const useBad3 = (host: Host) => { }                                 // use* prefix: signals React rules that don't exist
+setInterval(() => host.next(), 1000)                                // leak: no abort wiring
+fetch(url).catch(e => host.next(() => error = e))                   // missing host.signal + AbortError filter
+```
+
 ## Anti-patterns
 
 ```tsx
@@ -261,7 +354,7 @@ className="..."
 onClick={...}
 useState, useEffect, useCallback
 
-// ❌ class/style as object or array: no special handling in Ajo
+// ❌ class/style as object or array: no special handling in Ajo (compile error)
 <div class={{ active: isActive }} />        // won't work
 <div class={['btn', 'primary']} />          // won't work
 <div style={{ color: 'red' }} />            // won't work
@@ -337,10 +430,17 @@ pnpm add ajo
 yarn add ajo
 ```
 
-Configure JSX automatic runtime (Vite example):
+Configure the JSX automatic runtime in the build tool:
 
 ```ts
-// vite.config.ts
+// vite.config.ts (Vite 8+, rolldown/oxc)
+export default defineConfig({
+  oxc: {
+    jsx: { importSource: 'ajo' },
+  },
+})
+
+// vite.config.ts (Vite 7 and below, esbuild)
 export default defineConfig({
   esbuild: {
     jsx: 'automatic',
@@ -349,4 +449,30 @@ export default defineConfig({
 })
 ```
 
+And in tsconfig, so JSX types resolve in the editor:
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "ajo"
+  }
+}
+```
+
 For other build systems: `jsx: 'react-jsx'` (or `'automatic'`), `jsxImportSource: 'ajo'`. No manual imports needed — the build tool auto-imports from `ajo/jsx-runtime`.
+
+Mount and server-render:
+
+```tsx
+import { render } from 'ajo'
+
+render(<App />, document.getElementById('root')!)
+// render(h, el, child?, ref?) — optional child/ref bound the reconciled
+// range to [child, ref) for hydration or partial updates inside el
+
+import { render as toString } from 'ajo/html'
+
+const html = toString(<App />)  // SSR: stateful components run one iteration, then finalize
+```

package/dist/html.js

@@ -1 +1 @@
-import{isVNode as t,mark as n}from"./jsx.js";import{Context as e,current as o}from"./context.js";var{keys:r}=Object,a=new Set(["area","base","br","col","command","embed","hr","img","input","keygen","link","meta","param","source","track","wbr"]),l=Symbol.for("ajo.args"),s=e=>e.replace(/[&<>"']/g,e=>`&#${e.charCodeAt(0)};`),i=/^[A-Za-z][\w:.-]*$/,m=/^[^\s"'/>=\0-\x1F\x7F]+$/,f=()=>{},c={tag:"div"},u=e=>{let t="";return d(e,e=>t+=e),t},d=(e,r)=>{if(null==e)return;let a=typeof e;if("boolean"!=a)if("string"==a)r(s(e));else if("number"==a||"bigint"==a)r(s(String(e)));else if(t(e))"function"==typeof e.nodeName?b(e,r):g(e,r);else if(Symbol.iterator in Object(e))for(e of e)d(e,r);else r(s(String(e)))},g=(e,t)=>{let{nodeName:o,children:n}=e;o="string"==typeof o&&i.test(o)?o:c.tag;let l="";for(let t of r(e))"nodeName"==t||"children"==t||"key"==t||"skip"==t||"memo"==t||"ref"==t||t.startsWith("set:")||!m.test(t)||null==e[t]||!1===e[t]||(!0===e[t]?l+=` ${t}`:l+=` ${t}="${s(String(e[t]))}"`);t(`<${o}${l}>`),a.has(o)||(null!=n&&d(n,t),t(`</${o}>`))},b=({nodeName:e,...t},r)=>{"GeneratorFunction"==e.constructor.name?h(e,t,r):d(e(t),r)},h=(t,a,s)=>{let i={...t.attrs},m={...t.args};for(let e of r(a))e.startsWith("attr:")?i[e.slice(5)]=a[e]:"key"==e||"skip"==e||"memo"==e||"ref"==e||e.startsWith("set:")?i[e]=a[e]:m[e]=a[e];let u=new AbortController,d={*[Symbol.iterator](){for(;;)yield this[l]},[e]:Object.create(o()?.[e]??null),[l]:m,signal:u.signal,next:f,return:f,throw:e=>{throw e}},b=t.call(d,m),h=o();o(d);let y=e=>n({...i,nodeName:t.is??c.tag,children:e}),p="";try{g(y(b.next().value),e=>p+=e)}catch(t){p="",g(y(b.throw(t).value),e=>p+=e)}finally{b.return(),u.abort(),o(h)}s(p)};export{c as defaults,d as html,u as render};
+import{isVNode as t}from"./jsx.js";import{Context as n,current as e}from"./context.js";var{keys:o}=Object,r=new Set(["area","base","br","col","command","embed","hr","img","input","keygen","link","meta","param","source","track","wbr"]),a=Symbol.for("ajo.args"),l=e=>e.replace(/[&<>"']/g,e=>`&#${e.charCodeAt(0)};`),i=/^[A-Za-z][\w:.-]*$/,s=/^[^\s"'/>=\0-\x1F\x7F]+$/,f=()=>{},m=e=>"key"==e||"skip"==e||"memo"==e||"ref"==e||e.startsWith("set:"),c={tag:"div"},d=e=>{let t="";return g(e,e=>t+=e),t},g=(e,r)=>{if(null==e)return;let a=typeof e;if("boolean"!=a)if("string"==a)r(l(e));else if("number"==a||"bigint"==a)r(l(String(e)));else if(t(e))"function"==typeof e.nodeName?b(e,r):u(e,r);else if(Symbol.iterator in Object(e))for(e of e)g(e,r);else r(l(String(e)))},u=(e,t)=>{let{nodeName:a,children:n}=e;a="string"==typeof a&&i.test(a)?a:c.tag;let f="";for(let t of o(e))"nodeName"==t||"children"==t||m(t)||!s.test(t)||null==e[t]||!1===e[t]||(!0===e[t]?f+=` ${t}`:f+=` ${t}="${l(String(e[t]))}"`);t(`<${a}${f}>`),r.has(a)||(null!=n&&g(n,t),t(`</${a}>`))},b=({nodeName:e,...t},r)=>{e.prototype?.next?h(e,t,r):g(e(t),r)},h=(t,r,l)=>{let i={...t.attrs},s={...t.args};for(let e of o(r))e.startsWith("attr:")?i[e.slice(5)]=r[e]:m(e)?i[e]=r[e]:s[e]=r[e];i.nodeName=t.is??c.tag;let d=new AbortController,g={*[Symbol.iterator](){for(;;)yield this[a]},[n]:Object.create(e()?.[n]??null),[a]:s,signal:d.signal,next:f,return:f,throw:e=>{throw e}},b=t.call(g,s),h=e();e(g);let y="",p=e=>y+=e;try{i.children=b.next().value,u(i,p)}catch(t){y="",i.children=b.throw(t).value,u(i,p)}finally{b.return(),d.abort(),e(h)}l(y)};export{c as defaults,g as html,d as render};

package/dist/index.js

@@ -1 +1 @@
-import{isVNode as t,mark as n}from"./jsx.js";import{Context as e,current as o}from"./context.js";var y,{isArray:r}=Array,{assign:a,hasOwn:l,keys:s}=Object,i=Symbol.for("ajo.key"),m=Symbol.for("ajo.keyed"),f=Symbol.for("ajo.memo"),c=Symbol.for("ajo.cache"),u=Symbol.for("ajo.generator"),d=Symbol.for("ajo.iterator"),g=Symbol.for("ajo.render"),b=Symbol.for("ajo.args"),h=Symbol.for("ajo.controller"),p={tag:"div"},S=(e,t)=>(t&&(e.is=t),e),x=(e,t,r=t.firstChild,n=null)=>{if(C(e,e=>{let i="string"==typeof e?E(e,r,n):k(e,t,r,n);null==r?A(t,i,n):i==r?r=i.nextSibling:i==r.nextSibling?(A(t,r,n),r=i.nextSibling):A(t,i,r)}),r&&!n&&r==t.firstChild){let e=[];for(t[m]?.clear();r;)e.push(r),r=r.nextSibling;for(r of(t.textContent="",e))1==r.nodeType&&O(r)}else for(;r&&r!=n;){let e=r.nextSibling,n=t.removeChild(r);1==n.nodeType&&O(n,t),r=e}},C=(e,r)=>{if(null==e)return;let n=typeof e;if("boolean"!=n)if("string"==n)r(e);else if("number"==n||"bigint"==n)r(String(e));else if(t(e))"function"==typeof e.nodeName?N(e,r):r(e);else if(Symbol.iterator in Object(e))for(e of e)C(e,r);else r(String(e))},N=({nodeName:e,...t},r)=>{"GeneratorFunction"==e.constructor.name?r(j(e,t)):C(e(t),r)},j=(e,t)=>{let r={...e.attrs},i={...e.args};for(let e of s(t))e.startsWith("attr:")?r[e.slice(5)]=t[e]:"key"==e||"skip"==e||"memo"==e||"ref"==e||e.startsWith("set:")?r[e]=t[e]:i[e]=t[e];return n({...r,nodeName:e.is??p.tag,[u]:e,[b]:i})},E=(e,t,r)=>{for(;t&&t!=r&&3!=t.nodeType;)t=t.nextSibling;return t&&t!=r?t.data!=e&&(t.data=e):t=document.createTextNode(e),t},k=(e,t,r,n)=>{let o=e.nodeName,l=e.key,s=e[u];for(r&&null!=l&&null==n&&(r=(t[m]??=new Map).get(l)??r);r&&r!=n&&(r.localName!=o||null!=r[i]&&r[i]!=l||r[u]&&r[u]!=s);)r=null==r[i]?r.nextElementSibling:null;return r==n&&(r=null),r??=document.createElementNS(e.xmlns??t.namespaceURI,o),null!=l&&(t[m]??=new Map).set(r[i]=l,r),(!r[c]||null==e.memo||w(r[f],e.memo))&&(v(r[c],e,r),e.skip||(s?T(s,e[b],r):r[c]||"string"!=typeof e.children&&"number"!=typeof e.children?x(e.children,r):r.textContent=e.children+""),r[f]=e.memo,r[c]=e),r},v=(e,t,r)=>{if(!e)for(let e=r.attributes.length;e--;)l(t,r.attributes[e].name)||r.removeAttribute(r.attributes[e].name);for(let n in t)if(l(t,n)){let i=t[n];if(e&&e[n]===i||"nodeName"==n||"children"==n||"key"==n||"skip"==n||"memo"==n)continue;"ref"==n&&"function"==typeof i?i(r):n.startsWith("set:")?r[n.slice(4)]=i:null==i||!1===i?r.removeAttribute(n):"class"==n&&"string"==typeof r.className?r.className=!0===i?"":i:r.setAttribute(n,!0===i?"":i)}if(e)for(let n in e)if(l(e,n)){if(l(t,n)||"nodeName"==n||"children"==n||"key"==n||"skip"==n||"memo"==n)continue;n.startsWith("set:")?r[n.slice(4)]=void 0:r.removeAttribute(n)}},w=(e,t)=>{if(r(e)&&r(t)){if(e.length!=t.length)return!0;for(let r=e.length;r--;)if(e[r]!==t[r])return!0;return!1}return e!==t},A=(e,t,r)=>{if(t.isConnected&&t.contains(document.activeElement)){let n=t.nextSibling;for(;r&&r!=t;){let t=r.nextSibling;e.insertBefore(r,n),r=t}}else e.insertBefore(t,r)},O=(e,t)=>{if(e[f]==O)return;e[f]=O;let r=e;for(;r.firstElementChild;)r=r.firstElementChild;for(;;){let{nextElementSibling:n,parentNode:o}=r;if(null!=r[i]&&(o??t)?.[m]?.delete(r[i]),"function"==typeof r.return&&r.return(!1),"function"==typeof r[c]?.ref&&r[c].ref(null),r===e)break;if(r=n??o??e,n)for(;r.firstElementChild;)r=r.firstElementChild}},T=(t,r,n)=>{n[u]??=(W(),a(n,M)[e]=Object.create(o()?.[e]??null),t);for(let e of s(n[b]??=r))l(r,e)||delete n[b][e];a(n[b],r),n[g]()},W=()=>y||(y=new MutationObserver(e=>{for(let t of e)for(let e of t.removedNodes)1==e.nodeType&&!e.isConnected&&O(e,t.target)})).observe(document,{childList:!0,subtree:!0}),M={*[Symbol.iterator](){for(;;)yield this[b]},[g](){let e=o();o(this);try{this[d]||(this.signal=(this[h]=new AbortController).signal,this[d]=this[u].call(this,this[b]));let{value:e,done:t}=this[d].next();x(e,this),t&&this.return()}catch(e){this.throw(e)}finally{o(e)}},next(e,t){if(!1===this[d]||!this.isConnected)return t;try{"function"==typeof e&&(t=e.call(this,this[b]))}catch(e){return this.throw(e)}return o()?.contains(this)||this[g](),t},throw(e){for(let t=this;t;t=t.parentNode)if(t[d]?.throw)try{return x(t[d].throw(e).value,t)}catch(t){e=Error(t?.message??t,{cause:e})}throw e},return(e=!0){if(!1===this[d])return;let t=this[d];this[d]=!1,e&&((e,t)=>{let r=t.firstElementChild;for(;r;)if(e(r)&&r.firstElementChild)r=r.firstElementChild;else{for(;r!=t&&!r.nextElementSibling;)r=r.parentNode??t;r=r!=t&&r.nextElementSibling}})(e=>"function"!=typeof e.return||e.return(),this);try{t?.return()}catch(e){this.throw(e)}finally{this[d]=null,this[h]?.abort()}}};export{p as defaults,x as render,S as stateful};
+import{isVNode as t}from"./jsx.js";import{Context as n,current as e}from"./context.js";var y,{isArray:o}=Array,{assign:r,hasOwn:a,keys:l}=Object,i=Symbol.for("ajo.key"),s=Symbol.for("ajo.keyed"),f=Symbol.for("ajo.memo"),m=Symbol.for("ajo.cache"),c=Symbol.for("ajo.generator"),d=Symbol.for("ajo.iterator"),g=Symbol.for("ajo.render"),u=Symbol.for("ajo.args"),b=Symbol.for("ajo.controller"),h={tag:"div"},p=(e,t)=>(t&&(e.is=t),e),S=(e,t,r=t.firstChild,n=null)=>{if(x(e,e=>{let o="string"==typeof e?N(e,r,n):v(e,t,r,n);null==r?A(t,o,n):o==r?r=o.nextSibling:o==r.nextSibling?(r.contains(document.activeElement)?t.insertBefore(o,r):t.insertBefore(r,n),r=o.nextSibling):A(t,o,r)}),r&&!n&&r==t.firstChild){let e=[...t.children];t[s]?.clear(),t.textContent="";for(let t of e)B(t)}else for(;r&&r!=n;){let e=r.nextSibling;t.removeChild(r),B(r,t),r=e}},x=(e,r)=>{if(null!=e&&"boolean"!=typeof e)if(t(e)){if("function"!=typeof e.nodeName)return r(e);let{nodeName:t,...n}=e;t.prototype?.next?r(j(t,n)):x(t(n),r)}else if("object"==typeof e&&Symbol.iterator in e)for(e of e)x(e,r);else r(String(e))},j=(e,t)=>{let r={...e.attrs},n={...e.args};for(let e of l(t))e.startsWith("attr:")?r[e.slice(5)]=t[e]:"key"==e||"skip"==e||"memo"==e||"ref"==e||e.startsWith("set:")?r[e]=t[e]:n[e]=t[e];return r.nodeName=e.is??h.tag,r[c]=e,r[u]=n,r},N=(e,t,r)=>{for(;t&&t!=r&&3!=t.nodeType;)t=t.nextSibling;return null==t||t==r?t=document.createTextNode(e):t.data!=e&&(t.data=e),t},v=(e,t,r,n)=>{let o=e.nodeName,l=e.key,a=e[c];for(r&&null!=l&&null==n&&(r=t[s]?.get(l)??r);r&&r!=n;){let e=r[i],t=r[c];if(!(r.localName!=o||null!=e&&e!=l||t&&t!=a))break;r=null==e?r.nextElementSibling:null}return(null==r||r==n)&&(r=document.createElementNS(e.xmlns??t.namespaceURI,o)),null!=l&&(t[s]??=new Map).set(r[i]=l,r),(!r[m]||null==e.memo||k(r[f],e.memo))&&(w(r[m],e,r),e.skip||(a?O(a,e[u],r):r[m]||"string"!=typeof e.children&&"number"!=typeof e.children?S(e.children,r):r.textContent=e.children+""),r[f]=e.memo,r[m]=e),r},C=e=>"nodeName"==e||"children"==e||"key"==e||"skip"==e||"memo"==e,w=(e,t,r)=>{for(let n of e?l(e):r.getAttributeNames())a(t,n)||C(n)||(n.startsWith("set:")?r[n.slice(4)]=void 0:r.removeAttribute(n));for(let n of l(t)){let o=t[n];e&&e[n]===o||C(n)||("ref"==n&&"function"==typeof o?o(r):n.startsWith("set:")?r[n.slice(4)]=o:null==o||!1===o?r.removeAttribute(n):"class"==n&&"string"==typeof r.className?r.className=!0===o?"":o:r.setAttribute(n,!0===o?"":o))}},k=(e,t)=>o(e)&&o(t)?e.length!=t.length||e.some((e,r)=>e!==t[r]):e!==t,E=(e,t)=>{for(let r=t.firstElementChild;r;r=r.nextElementSibling)e(r)&&E(e,r)},A=(e,t,r)=>{if(t.isConnected&&t.contains(document.activeElement)){let n=t.nextSibling;for(;r&&r!=t;){let t=r.nextSibling;e.insertBefore(r,n),r=t}}else e.insertBefore(t,r)},B=(e,t)=>{if(e[f]==B)return;e[f]=B;let r=e=>{for(let t,n=e.firstElementChild;n;n=t)t=n.nextElementSibling,r(n);null!=e[i]&&(e.parentNode??t)?.[s]?.delete(e[i]),"function"==typeof e.return&&e.return(!1),"function"==typeof e[m]?.ref&&e[m].ref(null)};r(e)},O=(t,o,i)=>{i[c]||(y||(y=new MutationObserver(e=>{for(let t of e)for(let e of t.removedNodes)1==e.nodeType&&!e.isConnected&&B(e,t.target)})).observe(document,{childList:!0,subtree:!0}),r(i,W)[n]=Object.create(e()?.[n]??null),i[c]=t);let s=i[u]??=o;for(let e of l(s))a(o,e)||delete s[e];r(s,o),i[g]()},W={*[Symbol.iterator](){for(;;)yield this[u]},[g](){let t=e();e(this);try{this[d]||(this.signal=(this[b]=new AbortController).signal,this[d]=this[c].call(this,this[u]));let{value:e,done:t}=this[d].next();S(e,this),t&&this.return()}catch(t){this.throw(t)}finally{e(t)}},next(t,r){if(!1===this[d]||!this.isConnected)return r;try{"function"==typeof t&&(r=t.call(this,this[u]))}catch(t){return this.throw(t)}return e()?.contains(this)||this[g](),r},throw(e){for(let t=this;t;t=t.parentNode)if(t[d]?.throw)try{return S(t[d].throw(e).value,t)}catch(t){e=Error(t?.message??t,{cause:e})}throw e},return(e=!0){let t=this[d];if(!1!==t){this[d]=!1,e&&E(e=>"function"!=typeof e.return||e.return(),this);try{t?.return()}catch(e){this.throw(e)}finally{this[d]=null,this[b]?.abort()}}}};export{h as defaults,S as render,p as stateful};

package/dist/jsx.js

@@ -1 +1 @@
-var t=Symbol.for("ajo.vnode"),n=a=>(a[t]=a,a),e=a=>a?.[t]===a,o=a=>a.children;function r(a,s,e){return(s??={}).nodeName=a,null!=e&&(s.key=e),n(s)}var a=r,l=r;export{o as Fragment,e as isVNode,r as jsx,l as jsxDEV,a as jsxs,n as mark};
+var t=Symbol(),n=a=>(a[t]=a,a),e=a=>a?.[t]===a,o=a=>a.children;function r(a,s,e){return(s??={}).nodeName=a,null!=e&&(s.key=e),n(s)}var a=r,l=r;export{o as Fragment,e as isVNode,r as jsx,l as jsxDEV,a as jsxs,n as mark};

package/html.js

@@ -1,17 +1,19 @@
-import { Context, current } from './context.js'
-import { isVNode, mark } from './jsx.js'
-
-const { keys } = Object
-
-const Void = new Set(['area', 'base', 'br', 'col', 'command', 'embed', 'hr', 'img', 'input', 'keygen', 'link', 'meta', 'param', 'source', 'track', 'wbr'])
-
-const Args = Symbol.for('ajo.args')
-
-const escape = s => s.replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`)
-
-const Tag = /^[A-Za-z][\w:.-]*$/, Attr = /^[^\s"'/>=\0-\x1F\x7F]+$/
-
-const noop = () => { }
+import { Context, current } from './context.js'
+import { isVNode } from './jsx.js'
+
+const { keys } = Object
+
+const Void = new Set(['area', 'base', 'br', 'col', 'command', 'embed', 'hr', 'img', 'input', 'keygen', 'link', 'meta', 'param', 'source', 'track', 'wbr'])
+
+const Args = Symbol.for('ajo.args')
+
+const escape = s => s.replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`)
+
+const Tag = /^[A-Za-z][\w:.-]*$/, Attr = /^[^\s"'/>=\0-\x1F\x7F]+$/
+
+const noop = () => { }
+
+const special = key => key == 'key' || key == 'skip' || key == 'memo' || key == 'ref' || key.startsWith('set:')
 
 export const defaults = { tag: 'div' }
 
@@ -24,55 +26,55 @@ export const render = h => {
 	return out
 }
 
-export const html = (h, emit) => {
-
-	if (h == null) return
-
-	const type = typeof h
-
-	if (type == 'boolean') return
+export const html = (h, emit) => {
+
+	if (h == null) return
+
+	const type = typeof h
+
+	if (type == 'boolean') return
 
 	if (type == 'string') emit(escape(h))
 
-	else if (type == 'number' || type == 'bigint') emit(escape(String(h)))
+	else if (type == 'number' || type == 'bigint') emit(escape(String(h)))
+
+	else if (isVNode(h)) typeof h.nodeName == 'function' ? run(h, emit) : element(h, emit)
 
-	else if (isVNode(h)) typeof h.nodeName == 'function' ? run(h, emit) : element(h, emit)
-
-	else if (Symbol.iterator in Object(h)) for (h of h) html(h, emit)
-
-	else emit(escape(String(h)))
-}
+	else if (Symbol.iterator in Object(h)) for (h of h) html(h, emit)
+
+	else emit(escape(String(h)))
+}
 
 const element = (h, emit) => {
 
-	let { nodeName, children } = h
-
-	nodeName = typeof nodeName == 'string' && Tag.test(nodeName) ? nodeName : defaults.tag
-
-	let a = ''
-
-	for (const key of keys(h)) {
-
-		if (key == 'nodeName' || key == 'children' || key == 'key' || key == 'skip' || key == 'memo' || key == 'ref' || key.startsWith('set:') || !Attr.test(key) || h[key] == null || h[key] === false) continue
-
-		if (h[key] === true) a += ` ${key}`
-
-		else a += ` ${key}="${escape(String(h[key]))}"`
-	}
-
-	emit(`<${nodeName}${a}>`)
-
-	if (!Void.has(nodeName)) {
-
-		if (children != null) html(children, emit)
-
-		emit(`</${nodeName}>`)
+	let { nodeName, children } = h
+
+	nodeName = typeof nodeName == 'string' && Tag.test(nodeName) ? nodeName : defaults.tag
+
+	let a = ''
+
+	for (const key of keys(h)) {
+
+		if (key == 'nodeName' || key == 'children' || special(key) || !Attr.test(key) || h[key] == null || h[key] === false) continue
+
+		if (h[key] === true) a += ` ${key}`
+
+		else a += ` ${key}="${escape(String(h[key]))}"`
+	}
+
+	emit(`<${nodeName}${a}>`)
+
+	if (!Void.has(nodeName)) {
+
+		if (children != null) html(children, emit)
+
+		emit(`</${nodeName}>`)
 	}
 }
 
-const run = ({ nodeName, ...h }, emit) => {
+const run = ({ nodeName, ...h }, emit) => {
 
-	if (nodeName.constructor.name == 'GeneratorFunction') runGenerator(nodeName, h, emit)
+	if (nodeName.prototype?.next) runGenerator(nodeName, h, emit)
 
 	else html(nodeName(h), emit)
 }
@@ -81,20 +83,22 @@ const runGenerator = (fn, h, emit) => {
 
 	const attrs = { ...fn.attrs }, args = { ...fn.args }
 
-	for (const key of keys(h)) {
+	for (const key of keys(h)) {
 
 		if (key.startsWith('attr:')) attrs[key.slice(5)] = h[key]
 
-		else if (key == 'key' || key == 'skip' || key == 'memo' || key == 'ref' || key.startsWith('set:')) attrs[key] = h[key]
+		else if (special(key)) attrs[key] = h[key]
 
 		else args[key] = h[key]
 	}
 
+	attrs.nodeName = fn.is ?? defaults.tag
+
 	const controller = new AbortController()
 
 	const instance = {
 
-		*[Symbol.iterator]() { while (true) yield this[Args] },
+		*[Symbol.iterator]() { while (true) yield this[Args] },
 
 		[Context]: Object.create(current()?.[Context] ?? null),
 
@@ -115,19 +119,23 @@ const runGenerator = (fn, h, emit) => {
 
 	current(instance)
 
-	const vnode = children => mark({ ...attrs, nodeName: fn.is ?? defaults.tag, children })
-
-	let out = ''
-
-	try {
-
-		element(vnode(iterator.next().value), chunk => out += chunk)
-
-	} catch (error) {
-
-		out = ''
-
-		element(vnode(iterator.throw(error).value), chunk => out += chunk)
+	let out = ''
+
+	const write = chunk => out += chunk
+
+	try {
+
+		attrs.children = iterator.next().value
+
+		element(attrs, write)
+
+	} catch (error) {
+
+		out = ''
+
+		attrs.children = iterator.throw(error).value
+
+		element(attrs, write)
 
 	} finally {
 

package/index.js

@@ -1,5 +1,5 @@
 import { Context, current } from './context.js'
-import { isVNode, mark } from './jsx.js'
+import { isVNode } from './jsx.js'
 
 const { isArray } = Array, { assign, hasOwn, keys } = Object
 
@@ -33,7 +33,9 @@ export const render = (h, el, child = el.firstChild, ref = null) => {
 
 		} else if (node == child.nextSibling) {
 
-			before(el, child, ref)
+			if (child.contains(document.activeElement)) el.insertBefore(node, child)
+
+			else el.insertBefore(child, ref)
 
 			child = node.nextSibling
 
@@ -45,23 +47,21 @@ export const render = (h, el, child = el.firstChild, ref = null) => {
 
 	if (child && !ref && child == el.firstChild) {
 
-		const gone = []
+		const gone = [...el.children]
 
 		el[Keyed]?.clear()
 
-		while (child) gone.push(child), child = child.nextSibling
-
 		el.textContent = ''
 
-		for (child of gone) if (child.nodeType == 1) unref(child)
+		for (const node of gone) unref(node)
 
 	} else while (child && child != ref) {
 
 		const node = child.nextSibling
 
-		const gone = el.removeChild(child)
+		el.removeChild(child)
 
-		if (gone.nodeType == 1) unref(gone, el)
+		unref(child, el)
 
 		child = node
 	}
@@ -69,30 +69,23 @@ export const render = (h, el, child = el.firstChild, ref = null) => {
 
 const walk = (h, fn) => {
 
-	if (h == null) return
+	if (h == null || typeof h == 'boolean') return
 
-	const type = typeof h
+	if (isVNode(h)) {
 
-	if (type == 'boolean') return
+		if (typeof h.nodeName != 'function') return fn(h)
 
-	if (type == 'string') fn(h)
+		const { nodeName, ...rest } = h
 
-	else if (type == 'number' || type == 'bigint') fn(String(h))
+		if (nodeName.prototype?.next) fn(runGenerator(nodeName, rest))
 
-	else if (isVNode(h)) typeof h.nodeName == 'function' ? run(h, fn) : fn(h)
+		else walk(nodeName(rest), fn)
 
-	else if (Symbol.iterator in Object(h)) for (h of h) walk(h, fn)
+	} else if (typeof h == 'object' && Symbol.iterator in h) for (h of h) walk(h, fn)
 
 	else fn(String(h))
 }
 
-const run = ({ nodeName, ...h }, fn) => {
-
-	if (nodeName.constructor.name == 'GeneratorFunction') fn(runGenerator(nodeName, h))
-
-	else walk(nodeName(h), fn)
-}
-
 const runGenerator = (fn, h) => {
 
 	const attrs = { ...fn.attrs }, args = { ...fn.args }
@@ -106,14 +99,22 @@ const runGenerator = (fn, h) => {
 		else args[key] = h[key]
 	}
 
-	return mark({ ...attrs, nodeName: fn.is ?? defaults.tag, [Generator]: fn, [Args]: args })
+	attrs.nodeName = fn.is ?? defaults.tag
+
+	attrs[Generator] = fn
+
+	attrs[Args] = args
+
+	return attrs
 }
 
 const text = (h, node, ref) => {
 
 	while (node && node != ref && node.nodeType != 3) node = node.nextSibling
 
-	node && node != ref ? node.data != h && (node.data = h) : node = document.createTextNode(h)
+	if (node == null || node == ref) node = document.createTextNode(h)
+
+	else if (node.data != h) node.data = h
 
 	return node
 }
@@ -122,21 +123,18 @@ const element = (h, el, node, ref) => {
 
 	const nodeName = h.nodeName, key = h.key, gen = h[Generator]
 
-	if (node && key != null && ref == null) node = (el[Keyed] ??= new Map()).get(key) ?? node
-
-	while (node && node != ref && (
-
-		(node.localName != nodeName) ||
+	if (node && key != null && ref == null) node = el[Keyed]?.get(key) ?? node
 
-		(node[Key] != null && node[Key] != key) ||
+	while (node && node != ref) {
 
-		(node[Generator] && node[Generator] != gen)
+		const k = node[Key], g = node[Generator]
 
-	)) node = node[Key] != null ? null : node.nextElementSibling
+		if (node.localName == nodeName && (k == null || k == key) && (!g || g == gen)) break
 
-	if (node == ref) node = null
+		node = k != null ? null : node.nextElementSibling
+	}
 
-	node ??= document.createElementNS(h.xmlns ?? el.namespaceURI, nodeName)
+	if (node == null || node == ref) node = document.createElementNS(h.xmlns ?? el.namespaceURI, nodeName)
 
 	if (key != null) (el[Keyed] ??= new Map()).set(node[Key] = key, node)
 
@@ -144,7 +142,14 @@ const element = (h, el, node, ref) => {
 
 		attrs(node[Cache], h, node)
 
-		if (!h.skip) gen ? next(gen, h[Args], node) : !node[Cache] && (typeof h.children == 'string' || typeof h.children == 'number') ? node.textContent = h.children + '' : render(h.children, node)
+		if (!h.skip) {
+
+			if (gen) next(gen, h[Args], node)
+
+			else if (!node[Cache] && (typeof h.children == 'string' || typeof h.children == 'number')) node.textContent = h.children + ''
+
+			else render(h.children, node)
+		}
 
 		node[Memo] = h.memo
 
@@ -154,15 +159,24 @@ const element = (h, el, node, ref) => {
 	return node
 }
 
+const special = key => key == 'nodeName' || key == 'children' || key == 'key' || key == 'skip' || key == 'memo'
+
 const attrs = (cache, h, node) => {
 
-	if (!cache) for (let i = node.attributes.length; i--;) hasOwn(h, node.attributes[i].name) || node.removeAttribute(node.attributes[i].name)
+	for (const key of cache ? keys(cache) : node.getAttributeNames()) {
+
+		if (hasOwn(h, key) || special(key)) continue
+
+		if (key.startsWith('set:')) node[key.slice(4)] = undefined
 
-	for (const key in h) if (hasOwn(h, key)) {
+		else node.removeAttribute(key)
+	}
+
+	for (const key of keys(h)) {
 
 		const value = h[key]
 
-		if (cache && cache[key] === value || key == 'nodeName' || key == 'children' || key == 'key' || key == 'skip' || key == 'memo') continue
+		if (cache && cache[key] === value || special(key)) continue
 
 		if (key == 'ref' && typeof value == 'function') value(node)
 
@@ -174,45 +188,15 @@ const attrs = (cache, h, node) => {
 
 		else node.setAttribute(key, value === true ? '' : value)
 	}
-
-	if (cache) for (const key in cache) if (hasOwn(cache, key)) {
-
-		if (hasOwn(h, key) || key == 'nodeName' || key == 'children' || key == 'key' || key == 'skip' || key == 'memo') continue
-
-		if (key.startsWith('set:')) node[key.slice(4)] = undefined
-
-		else node.removeAttribute(key)
-	}
 }
 
-const some = (a, b) => {
-
-	if (isArray(a) && isArray(b)) {
-
-		if (a.length != b.length) return true
-
-		for (let i = a.length; i--;) if (a[i] !== b[i]) return true
+const some = (a, b) =>
 
-		return false
-	}
-
-	return a !== b
-}
+	isArray(a) && isArray(b) ? a.length != b.length || a.some((v, i) => v !== b[i]) : a !== b
 
 const each = (fn, node) => {
 
-	let child = node.firstElementChild
-
-	while (child)
-
-		if (fn(child) && child.firstElementChild) child = child.firstElementChild
-
-		else {
-
-			while (child != node && !child.nextElementSibling) child = child.parentNode ?? node
-
-			child = child != node && child.nextElementSibling
-		}
+	for (let child = node.firstElementChild; child; child = child.nextElementSibling) if (fn(child)) each(fn, child)
 }
 
 const before = (el, node, child) => {
@@ -239,46 +223,50 @@ const unref = (root, parent) => {
 
 	root[Memo] = unref
 
-	let node = root
+	const clean = node => {
 
-	while (node.firstElementChild) node = node.firstElementChild
+		for (let child = node.firstElementChild, next; child; child = next) {
 
-	while (true) {
+			next = child.nextElementSibling
 
-		const { nextElementSibling, parentNode } = node
+			clean(child)
+		}
 
-		if (node[Key] != null) (parentNode ?? parent)?.[Keyed]?.delete(node[Key])
+		if (node[Key] != null) (node.parentNode ?? parent)?.[Keyed]?.delete(node[Key])
 
 		if (typeof node.return == 'function') node.return(false)
 
 		if (typeof node[Cache]?.ref == 'function') node[Cache].ref(null)
-
-		if (node === root) break
-
-		node = nextElementSibling ?? parentNode ?? root
-
-		if (nextElementSibling) while (node.firstElementChild) node = node.firstElementChild
 	}
+
+	clean(root)
 }
 
+let observer
+
 const next = (fn, args, el) => {
 
-	el[Generator] ??= (watch(), assign(el, methods)[Context] = Object.create(current()?.[Context] ?? null), fn)
+	if (!el[Generator]) {
 
-	for (const key of keys(el[Args] ??= args)) hasOwn(args, key) || delete el[Args][key]
+		if (!observer) (observer = new MutationObserver(records => {
 
-	assign(el[Args], args)
+			for (const record of records) for (const node of record.removedNodes) if (node.nodeType == 1 && !node.isConnected) unref(node, record.target)
 
-	el[Render]()
-}
+		})).observe(document, { childList: true, subtree: true })
 
-let observer
+		assign(el, methods)[Context] = Object.create(current()?.[Context] ?? null)
 
-const watch = () => observer || (observer = new MutationObserver(records => {
+		el[Generator] = fn
+	}
+
+	const prev = el[Args] ??= args
 
-	for (const record of records) for (const node of record.removedNodes) if (node.nodeType == 1 && !node.isConnected) unref(node, record.target)
+	for (const key of keys(prev)) if (!hasOwn(args, key)) delete prev[key]
 
-})).observe(document, { childList: true, subtree: true })
+	assign(prev, args)
+
+	el[Render]()
+}
 
 const methods = {
 
@@ -349,10 +337,10 @@ const methods = {
 
 	return(deep = true) {
 
-		if (this[Iterator] === false) return
-
 		const iterator = this[Iterator]
 
+		if (iterator === false) return
+
 		this[Iterator] = false
 
 		if (deep) each(el => typeof el.return == 'function' ? el.return() : true, this)

package/jsx.js

@@ -1,18 +1,18 @@
-const VNode = Symbol.for('ajo.vnode')
+const VNode = Symbol()
 
 export const mark = v => (v[VNode] = v, v)
 
 export const isVNode = v => v?.[VNode] === v
 
-export const Fragment = props => props.children
+export const Fragment = args => args.children
 
-export function jsx(type, props, key) {
+export function jsx(type, args, key) {
 
-	(props ??= {}).nodeName = type
+	(args ??= {}).nodeName = type
 
-	if (key != null) props.key = key
+	if (key != null) args.key = key
 
-	return mark(props)
+	return mark(args)
 }
 
 export const jsxs = jsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ajo",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "ajo is a JavaScript view library for building user interfaces",
   "type": "module",
   "types": "./types.ts",

package/readme.md

@@ -74,7 +74,7 @@ export default defineConfig({
 
 ### Stateless Components
 
-Pure functions that receive props and return JSX:
+Pure functions that receive args and return JSX:
 
 ```javascript
 const Greeting = ({ name }) => <p>Hello, {name}!</p>
@@ -82,7 +82,7 @@ const Greeting = ({ name }) => <p>Hello, {name}!</p>
 
 ### Stateful Components
 
-Generator functions with automatic wrapper elements. The structure provides a natural mental model:
+Generator functions with an automatic **host** — a wrapper DOM element Ajo creates for each stateful component and uses to store its state and lifecycle. The structure provides a natural mental model:
 
 - **Before the loop**: Persistent state and handlers (survives re-renders)
 - **Inside the loop**: Derived values (computed fresh each render)
@@ -226,9 +226,9 @@ function* ErrorBoundary() {
 | `key` | Unique identifier for list reconciliation |
 | `ref` | Callback receiving DOM element (or `null` on unmount) |
 | `memo` | Skip reconciliation: `memo={[deps]}`, `memo={value}`, or `memo` (render once) |
-| `skip` | Exclude children from reconciliation; not a sanitizer |
+| `skip` | Exclude children from reconciliation; not a sanitizer |
 | `set:*` | Set DOM properties instead of HTML attributes |
-| `attr:*` | Force HTML attributes on stateful component wrappers |
+| `attr:*` | Force HTML attributes on stateful component hosts |
 
 ### `set:` - DOM Properties vs HTML Attributes
 
@@ -243,8 +243,8 @@ function* ErrorBoundary() {
 <input type="checkbox" set:checked={bool} />
 <video set:currentTime={0} set:muted />
 
-// innerHTML is only for trusted/sanitized HTML; skip preserves assigned children
-<div set:innerHTML={trustedHtml} skip />
+// innerHTML is only for trusted/sanitized HTML; skip preserves assigned children
+<div set:innerHTML={trustedHtml} skip />
 ```
 
 ### `ref` - DOM Access
@@ -254,13 +254,13 @@ function* AutoFocus() {
 
   let input = null
 
-  while (true) yield (
-    <>
-      <input ref={el => { input = el; el?.focus() }} />
-      <button set:onclick={() => input?.select()}>Select</button>
-    </>
-  )
-}
+  while (true) yield (
+    <>
+      <input ref={el => { input = el; el?.focus() }} />
+      <button set:onclick={() => input?.select()}>Select</button>
+    </>
+  )
+}
 
 // Ref to stateful component includes control methods
 let timer = null
@@ -289,20 +289,20 @@ function* Chart() {
 }
 ```
 
-### `attr:` - Wrapper Attributes
+### `attr:` - Host Attributes
 
 ```javascript
 <Counter
   initial={0}                    // → args
-  attr:id="main"                 // → wrapper HTML attribute
-  attr:class="widget"            // → wrapper HTML attribute
-  set:onclick={fn}               // → wrapper DOM property
+  attr:id="main"                 // → host HTML attribute
+  attr:class="widget"            // → host HTML attribute
+  set:onclick={fn}               // → host DOM property
 />
 ```
 
 ## Context API
 
-Share data across component trees without prop drilling:
+Share data across component trees without passing args down every level:
 
 ```javascript
 import { context } from 'ajo/context'
@@ -355,7 +355,7 @@ function* UserProfile({ id }) {
   fetch(`/api/users/${id}`, { signal: this.signal })
     .then(r => r.json())
     .then(d => this.next(() => { data = d; loading = false }))
-    .catch(e => this.next(() => { error = e; loading = false }))
+    .catch(e => e.name == 'AbortError' || this.next(() => { error = e; loading = false }))
 
   while (true) {
     if (loading) yield <p>Loading...</p>
@@ -365,6 +365,61 @@ function* UserProfile({ id }) {
 }
 ```
 
+## Cloves: Sharing Logic
+
+Other frameworks need a dedicated mechanism to share component logic — React has hooks (with ordering rules, because state lives in positional slots), Vue has composables (wired into a reactivity graph). Ajo needs neither: a generator body runs once, so closures are real, and the component instance already exposes everything shared logic needs — `this.signal` for cleanup and `this.next()` for invalidation.
+
+A **clove** (ajo is garlic; a bulb is made of cloves) is that idea as a convention: a plain function that takes the host and returns a live view of one concern.
+
+```javascript
+const pointer = host => {
+
+  const pos = { x: 0, y: 0 }
+
+  document.addEventListener('pointermove',
+    e => host.next(() => { pos.x = e.clientX; pos.y = e.clientY }),
+    { signal: host.signal })
+
+  return pos
+}
+
+function* Cursor() {
+  const pos = pointer(this)
+  while (true) yield <p>{pos.x}, {pos.y}</p>
+}
+```
+
+The rules that make a clove reliable:
+
+1. **`(host, options?) => view`** — the host (`this`) is always the first argument.
+2. **Cleanup through `host.signal` only.** Listeners take `{ signal: host.signal }`; timers and observers register an `abort` listener. Never return a dispose function. Teardown then composes automatically with unmount *and* with reset (`el.return()` + `el.next()` restarts the generator with a fresh signal, and the clove re-subscribes by re-running setup).
+3. **Invalidation through `host.next(fn)`**, mutating state inside the callback — safe by design: it no-ops after unmount and never re-renders reentrantly.
+4. **The view is a stable reference whose fields mutate** — the same live-object contract as Ajo's `args`. Never reassign or spread it; use getters for derived values.
+5. **Per-render input is an explicit call inside the render loop** (a no-op when unchanged), because in Ajo lifecycle is code position:
+
+```javascript
+function* User() {
+  const q = loader(this)
+  for (const { id } of this) {
+    q.load(`/api/users/${id}`)
+    yield q.loading ? <p>Loading...</p> : <h1>{q.data.name}</h1>
+  }
+}
+```
+
+6. **SSR-inert:** guard DOM access (`typeof document != 'undefined' && host.nodeType == 1`) and always return the correctly shaped view, so universal components can call cloves unconditionally.
+
+There are no ordering rules — cloves are ordinary function calls, so conditionals are legal and composition is just passing the host along. Don't name them `useX`: that prefix signals React constraints that don't exist here.
+
+TypeScript ships a `Host` type for authoring cloves — the host's protocol plus its DOM surface, satisfied by any stateful component's `this`:
+
+```typescript
+import type { Host } from 'ajo'
+
+const focus = (host: Host) => { /* host.signal, host.next(), host.addEventListener()... */ }
+const input = (host: Host<HTMLInputElement>) => host.value // narrow the element when needed
+```
+
 ## Server-Side Rendering
 
 ```javascript
@@ -378,15 +433,15 @@ const html = render(<App />)
 import type { Stateless, Stateful, WithChildren } from 'ajo'
 
 // Stateless
-type CardProps = WithChildren<{ title: string }>
-const Card: Stateless<CardProps> = ({ title, children }) => (
+type CardArgs = WithChildren<{ title: string }>
+const Card: Stateless<CardArgs> = ({ title, children }) => (
   <div class="card"><h3>{title}</h3>{children}</div>
 )
 
-// Stateful with custom wrapper element
-type CounterProps = { initial: number; step?: number }
+// Stateful with custom host element
+type CounterArgs = { initial: number; step?: number }
 
-const Counter: Stateful<CounterProps, 'section'> = function* ({ initial }) {
+const Counter: Stateful<CounterArgs, 'section'> = function* ({ initial }) {
 
   let count = initial
 
@@ -395,16 +450,20 @@ const Counter: Stateful<CounterProps, 'section'> = function* ({ initial }) {
   }
 }
 
-Counter.is = 'section'               // wrapper element (default: 'div')
-Counter.attrs = { class: 'counter' } // default wrapper attributes
+Counter.is = 'section'               // host element (default: 'div')
+Counter.attrs = { class: 'counter' } // default host attributes
 Counter.args = { step: 1 }           // default args
 
 // Or use stateful() to avoid duplicating 'section':
-// const Counter = stateful(function* ({ initial }: CounterProps) { ... }, 'section')
+// const Counter = stateful(function* ({ initial }: CounterArgs) { ... }, 'section')
 
 // Ref typing
 let ref: ThisParameterType<typeof Counter> | null = null
 <Counter ref={el => ref = el} initial={0} />
+
+// Clove typing: Host is satisfied by any stateful component's `this`
+import type { Host } from 'ajo'
+const pointer = (host: Host) => { /* ... */ }
 ```
 
 ## API Reference
@@ -413,8 +472,8 @@ let ref: ThisParameterType<typeof Counter> | null = null
 | Export | Description |
 |--------|-------------|
 | `render(children, container, start?, end?)` | Render to DOM. Optional `start`/`end` for targeted updates. |
-| `stateful(fn, tag?)` | Create stateful component with type inference for custom wrapper. |
-| `defaults` | Default wrapper tag config (`defaults.tag`). |
+| `stateful(fn, tag?)` | Create stateful component with type inference for a custom host. |
+| `defaults` | Default host tag config (`defaults.tag`). |
 
 ### `ajo/context`
 | Export | Description |
@@ -424,9 +483,9 @@ let ref: ThisParameterType<typeof Counter> | null = null
 ### `ajo/html`
 | Export | Description |
 |--------|-------------|
-| `render(children)` | Render to HTML string. |
-| `html(children, emit)` | Render to HTML chunks by calling `emit(chunk)`. |
-| `defaults` | Default SSR wrapper tag config (`defaults.tag`). |
+| `render(children)` | Render to HTML string. |
+| `html(children, emit)` | Render to HTML chunks by calling `emit(chunk)`. |
+| `defaults` | Default SSR host tag config (`defaults.tag`). |
 
 ### Stateful `this`
 | Property | Description |
@@ -435,9 +494,9 @@ let ref: ThisParameterType<typeof Counter> | null = null
 | `this.signal` | AbortSignal that aborts on unmount. Pass to `fetch()`, `addEventListener()`, etc. |
 | `this.next(fn?)` | Re-render. Callback receives current args. Returns callback's result. |
 | `this.throw(error)` | Throw to parent boundary. |
-| `this.return(deep?)` | Terminate generator. Deep cleanup is the default; pass `false` to skip child generators. |
+| `this.return(deep?)` | Terminate generator. Deep cleanup is the default; pass `false` to skip child generators. |
 
-`this` is also the wrapper element (`this.addEventListener()`, etc).
+`this` is also the host element itself (`this.addEventListener()`, etc).
 
 ## For AI Assistants
 

package/types.ts

@@ -2,7 +2,7 @@ declare module 'ajo' {
 
 	type Tag = keyof (HTMLElementTagNameMap & SVGElementTagNameMap)
 
-	type Type = Tag | (string & {}) | Stateless | Stateful
+	type Type = Tag | (string & {}) | Stateless<any> | Stateful<any, any>
 
 	type Children = unknown
 
@@ -27,7 +27,7 @@ declare module 'ajo' {
 		ref: (el: TElement | null) => void,
 	} & ElementChildrenAttribute
 
-	type PropSetter<TTag> = {
+	type PropertySetter<TTag> = {
 		[K in keyof ElementType<TTag> as `set:${Exclude<K, symbol>}`]: ElementType<TTag>[K]
 	}
 
@@ -35,6 +35,12 @@ declare module 'ajo' {
 		[key: `attr:${string}`]: unknown
 	}
 
+	type CommonAttrs = {
+		class: string | boolean | null,
+		style: string | boolean | null,
+		xmlns: string,
+	}
+
 	interface Defaults { }
 
 	type DefaultTag = Defaults extends { tag: infer T extends string } ? T : 'div'
@@ -44,29 +50,32 @@ declare module 'ajo' {
 	type Stateless<TArgs extends Args = {}> = (args: TArgs) => Children
 
 	type Stateful<TArgs extends Args = {}, TTag extends string = DefaultTag> = {
-		(this: StatefulElement<TArgs, TTag>, args: TArgs): Iterator<Children>
+		(this: Host<ElementType<TTag>, TArgs>, args: TArgs): Iterator<Children>
 	} & (TTag extends DefaultTag ? { is?: TTag } : { is: TTag }) & {
-		attrs?: Partial<PropSetter<TTag>> & Args,
+		attrs?: Partial<PropertySetter<TTag> & CommonAttrs> & Args,
 		args?: Partial<TArgs>,
 	}
 
 	type Component<TArgs extends Args = {}> = Stateless<TArgs> | Stateful<TArgs>
 
 	type StatefulArgs<TArgs, TTag> =
-		Partial<SpecialAttrs<StatefulElement<TArgs, TTag>> & PropSetter<TTag>> &
+		Partial<SpecialAttrs<Host<ElementType<TTag>, TArgs>> & PropertySetter<TTag>> &
 		AttrSetter &
 		TArgs
 
-	type StatefulElement<TArgs, TTag> = ElementType<TTag> & {
+	type Host<TElement extends object = HTMLElement, TArgs = Args> = TElement & {
 		[Symbol.iterator](): Iterator<TArgs>,
 		signal: AbortSignal,
-		next: <R>(fn?: (this: StatefulElement<TArgs, TTag>, args: TArgs) => R) => R,
+		next: {
+			(): undefined,
+			<R>(fn: (this: Host<TElement, TArgs>, args: TArgs) => R): R,
+		},
 		throw: (value?: unknown) => void,
 		return: (deep?: boolean) => void,
 	}
 
 	type HTMLIntrinsicElements = {
-		[TTag in Tag]: Partial<PropSetter<TTag> & SpecialAttrs<ElementType<TTag>>> & Args
+		[TTag in Tag]: Partial<PropertySetter<TTag> & SpecialAttrs<ElementType<TTag>> & CommonAttrs> & Args
 	}
 
 	interface IntrinsicElements extends HTMLIntrinsicElements { }
@@ -82,10 +91,10 @@ declare module 'ajo' {
 				: P
 			: P
 
-	function render(h: Children, el: ParentNode, child?: ChildNode, ref?: ChildNode): void
+	function render(h: Children, el: ParentNode, child?: ChildNode | null, ref?: ChildNode | null): void
 
 	function stateful<TArgs extends Args, TTag extends string = DefaultTag>(
-		fn: (this: StatefulElement<TArgs, TTag>, args: TArgs) => Iterator<Children>,
+		fn: (this: Host<ElementType<TTag>, TArgs>, args: TArgs) => Iterator<Children>,
 		is?: TTag
 	): Stateful<TArgs, TTag>
 }
@@ -95,7 +104,7 @@ declare module 'ajo/context' {
 		(): T
 		<V extends T>(value: V): V
 	}
-	function current(): import('ajo').StatefulElement<any, any> | null
+	function current(): import('ajo').Host<object, any> | null
 }
 
 declare module 'ajo/html' {
@@ -105,11 +114,11 @@ declare module 'ajo/html' {
 }
 
 declare module 'ajo/jsx-runtime' {
-	import { Type, Args, VNode, ElementChildrenAttribute, IntrinsicElements as _IE } from 'ajo'
-	export function Fragment({ children }: ElementChildrenAttribute): typeof children
-	export function jsx(type: Type, props: Args | null, key?: string | number): VNode
-	export function jsxs(type: Type, props: Args | null, key?: string | number): VNode
-	export function jsxDEV(type: Type, props: Args | null, key?: string | number): VNode
+	import { Type, Args, VNode, ElementChildrenAttribute, IntrinsicElements as _IE } from 'ajo'
+	export function Fragment({ children }: ElementChildrenAttribute): typeof children
+	export function jsx(type: Type, args: Args | null, key?: string | number): VNode
+	export function jsxs(type: Type, args: Args | null, key?: string | number): VNode
+	export function jsxDEV(type: Type, args: Args | null, key?: string | number): VNode
 	export namespace JSX {
 		type ElementChildrenAttribute = import('ajo').ElementChildrenAttribute
 		type LibraryManagedAttributes<C, P> = import('ajo').ManagedAttributes<C, P>
@@ -117,9 +126,9 @@ declare module 'ajo/jsx-runtime' {
 	}
 }
 
-declare module 'ajo/jsx-dev-runtime' {
-	import { IntrinsicElements as _IE } from 'ajo'
-	export { Fragment, jsx, jsxs, jsxDEV } from 'ajo/jsx-runtime'
+declare module 'ajo/jsx-dev-runtime' {
+	import { IntrinsicElements as _IE } from 'ajo'
+	export { Fragment, jsx, jsxs, jsxDEV } from 'ajo/jsx-runtime'
 	export namespace JSX {
 		type ElementChildrenAttribute = import('ajo').ElementChildrenAttribute
 		type LibraryManagedAttributes<C, P> = import('ajo').ManagedAttributes<C, P>