ajo 0.1.34 → 0.1.35

package/jsx.js

@@ -4,15 +4,15 @@ 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.34",
+  "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

@@ -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]
 	}
 
@@ -50,32 +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> & CommonAttrs> & 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: {
 			(): undefined,
-			<R>(fn: (this: StatefulElement<TArgs, TTag>, args: TArgs) => R): R,
+			<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>> & CommonAttrs> & Args
+		[TTag in Tag]: Partial<PropertySetter<TTag> & SpecialAttrs<ElementType<TTag>> & CommonAttrs> & Args
 	}
 
 	interface IntrinsicElements extends HTMLIntrinsicElements { }
@@ -94,7 +94,7 @@ declare module 'ajo' {
 	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>
 }
@@ -104,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' {
@@ -116,9 +116,9 @@ 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
+	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>