objs-core 1.1.1 → 2.0.1

package/EXAMPLES.md

@@ -0,0 +1,1637 @@
+# Objs v2.0 — Examples & Architecture Guide
+
+All examples work as-is with `<script src="objs.js"></script>`.
+Runnable paste-and-run code: [examples.js](examples.js).
+
+---
+
+## Contents
+
+0. [Framework comparison & migration guide](#0-framework-comparison--migration-guide)
+1. [How render works](#1-how-render-works)
+2. [Single components — atoms](#2-single-components--atoms)
+3. [Nesting & composition — three patterns](#3-nesting--composition)
+4. [Design system architecture](#4-design-system-architecture)
+5. [Real-world examples](#5-real-world-examples)
+6. [React integration](#6-react-integration)
+
+---
+
+## 0. Framework comparison & migration guide
+
+Coming from React, Vue, or Solid? This section maps familiar patterns to their Objs equivalents, so you can start writing productive code immediately.
+
+### Feature comparison
+
+| | React 18 | Vue 3 | Solid | Objs 2.0 |
+|---|---|---|---|---|
+| **Min + gz size** | ~45 kB | ~22 kB | ~7 kB | ~6 kB |
+| **DOM update model** | Virtual DOM diff | Virtual DOM diff | Fine-grained signals | Direct — explicit state calls |
+| **Reactivity** | `useState` / hooks | `ref` / `reactive` | `createSignal` | None — you call update methods |
+| **Component format** | JSX function | SFC `.vue` / `setup()` | JSX function | Plain JS `states` object |
+| **Build step required** | Yes | Yes | Yes | No — works as a `<script>` tag |
+| **TypeScript** | Full generics | Full generics | Full generics | `.d.ts` definitions |
+| **SSR** | React Server / Next.js | Nuxt | SolidStart | Built-in `o.reactRender` |
+| **Routing** | React Router | Vue Router | @solidjs/router | Built-in `o.route` |
+| **State sharing** | Context / Zustand | Pinia | Signals / stores | Plain observer or `o.connectRedux` |
+| **Data fetching** | `useEffect` + fetch | `onMounted` + fetch | `createResource` | `o.newLoader` + `.connect()` |
+| **Testing** | Jest / RTL / Vitest | Vitest | Vitest | Built-in `o.addTest` |
+| **QA selectors** | `data-testid` (manual) | `data-testid` (manual) | `data-testid` (manual) | Auto via `o.autotag` |
+| **Action recording** | Playwright / Cypress | Playwright / Cypress | Playwright / Cypress | Built-in `o.startRecording` |
+| **Dev/prod split** | Manual | Manual | Manual | Built-in `__DEV__` + `build.js` |
+| **Integrates into existing projects** | `createRoot(el)` | `createApp().mount(el)` | `render(() => …, el)` | `.appendInside(el)` |
+
+> **Key difference:** React, Vue, and Solid track state automatically and re-render when it changes.
+> Objs does not — you explicitly call `component.stateMethod(data)`, which writes only the changed DOM nodes.
+> This gives you O(1) updates without a reactivity system or virtual DOM.
+
+---
+
+### Pattern 1 — Define and mount a component
+
+The most basic operation: create a component with initial data and insert it into the page.
+
+**React**
+```jsx
+function Badge({ count }) {
+  return <span className="badge">{count}</span>;
+}
+ReactDOM.createRoot(document.getElementById('nav')).render(<Badge count={3} />);
+```
+
+**Vue 3**
+```vue
+<!-- Badge.vue -->
+<template><span class="badge">{{ count }}</span></template>
+<script setup>
+defineProps(['count']);
+</script>
+```
+```js
+// main.js
+import { createApp } from 'vue';
+import Badge from './Badge.vue';
+createApp(Badge, { count: 3 }).mount('#nav');
+```
+
+**Solid**
+```jsx
+import { render } from 'solid-js/web';
+function Badge(props) {
+  return <span class="badge">{props.count}</span>;
+}
+render(() => <Badge count={3} />, document.getElementById('nav'));
+```
+
+**Objs**
+```js
+const badge = o.init({
+  name: 'Badge',
+  render: ({ count }) => ({ tag: 'span', class: 'badge', html: count }),
+}).render({ count: 3 }).appendInside('#nav');
+```
+
+---
+
+### Pattern 2 — Counter (click to increment)
+
+State that changes on user interaction.
+
+**React**
+```jsx
+function Counter() {
+  const [count, setCount] = React.useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+**Vue 3**
+```vue
+<template><button @click="count++">{{ count }}</button></template>
+<script setup>
+import { ref } from 'vue';
+const count = ref(0);
+</script>
+```
+
+**Solid**
+```jsx
+import { createSignal } from 'solid-js';
+function Counter() {
+  const [count, setCount] = createSignal(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count()}</button>;
+}
+```
+
+**Objs**
+```js
+// State lives in the element, not in a reactive variable
+const counter = o.init({
+  name: 'Counter',
+  render: { tag: 'button', html: '0' },
+  inc: ({ self }) => { self.html(+self.el.textContent + 1); },
+}).render().appendInside('#app');
+
+counter.on('click', () => counter.inc());
+```
+
+> In React/Vue/Solid, the framework schedules a re-render when state changes.
+> In Objs, `inc()` writes `innerHTML` directly — no scheduler, no diff.
+
+---
+
+### Pattern 3 — Props / parameterized component
+
+Pass data in at creation time.
+
+**React**
+```jsx
+function Card({ title, price }) {
+  return (
+    <article>
+      <h3>{title}</h3>
+      <p className="price">${price}</p>
+    </article>
+  );
+}
+<Card title="Laptop" price={999} />
+```
+
+**Vue 3**
+```vue
+<template>
+  <article>
+    <h3>{{ title }}</h3>
+    <p class="price">${{ price }}</p>
+  </article>
+</template>
+<script setup>
+defineProps(['title', 'price']);
+</script>
+```
+
+**Solid**
+```jsx
+function Card(props) {
+  return (
+    <article>
+      <h3>{props.title}</h3>
+      <p class="price">${props.price}</p>
+    </article>
+  );
+}
+<Card title="Laptop" price={999} />
+```
+
+**Objs**
+```js
+const cardStates = {
+  name: 'Card',
+  render: ({ title, price }) => ({
+    tag: 'article',
+    html: `<h3>${title}</h3><p class="price">$${price}</p>`,
+  }),
+};
+o.init(cardStates).render({ title: 'Laptop', price: 999 }).appendInside('#app');
+```
+
+---
+
+### Pattern 4 — Targeted partial update
+
+Update one part of a component without touching the rest.
+
+In React/Vue, the framework diffs and patches. In Solid, only the signal's text node updates. In Objs, you explicitly name which DOM node to write to.
+
+**React**
+```jsx
+// The whole Card function re-runs; React reconciles the output
+function Card({ title }) {
+  const [price, setPrice] = React.useState(999);
+  return (
+    <article>
+      <h3>{title}</h3>
+      <p className="price">${price}</p>
+    </article>
+  );
+  // Caller: setPrice(89) — triggers rerender, React diffs and patches <p>
+}
+```
+
+**Vue 3**
+```vue
+<template>
+  <article>
+    <h3>{{ title }}</h3>
+    <p class="price">${{ price }}</p>
+  </article>
+</template>
+<script setup>
+import { ref } from 'vue';
+defineProps(['title']);
+const price = ref(999);
+// Caller: price.value = 89 — Vue updates only the <p> text node
+</script>
+```
+
+**Solid**
+```jsx
+// Only the text node that reads price() is updated — no component re-run
+function Card(props) {
+  const [price, setPrice] = createSignal(999);
+  return (
+    <article>
+      <h3>{props.title}</h3>
+      <p class="price">${price()}</p>
+    </article>
+  );
+  // Caller: setPrice(89) — only the text node inside <p> changes
+}
+```
+
+**Objs**
+```js
+const cardStates = {
+  name: 'Card',
+  render: ({ title, price }) => ({
+    tag: 'article',
+    html: `<h3>${title}</h3><p class="price">$${price}</p>`,
+  }),
+  // Direct write — no reactivity system, no scheduler, no diff
+  setPrice: ({ self }, p) => { self.first('.price').html(`$${p}`); },
+};
+const card = o.init(cardStates).render({ title: 'Laptop', price: 999 }).appendInside('#app');
+card.setPrice(89); // one innerHTML write, nothing else evaluated
+```
+
+---
+
+### Pattern 5 — List rendering
+
+Render a collection of items. Handle adding and removing individual items without re-rendering the whole list.
+
+**React**
+```jsx
+function ProductList({ products }) {
+  return (
+    <ul>
+      {products.map(p => <li key={p.id}>{p.name}</li>)}
+    </ul>
+  );
+  // When products changes, React re-diffs the entire list
+}
+```
+
+**Vue 3**
+```vue
+<template>
+  <ul>
+    <li v-for="p in products" :key="p.id">{{ p.name }}</li>
+  </ul>
+</template>
+<script setup>
+import { ref } from 'vue';
+const products = ref([]);
+// When products.value changes, Vue patches the list
+</script>
+```
+
+**Solid**
+```jsx
+import { createSignal } from 'solid-js';
+import { For } from 'solid-js';
+function ProductList() {
+  const [products, setProducts] = createSignal([]);
+  return (
+    <ul>
+      <For each={products()}>
+        {p => <li>{p.name}</li>}
+      </For>
+    </ul>
+  );
+  // For only patches the changed item rows
+}
+```
+
+**Objs**
+```js
+const listStates = {
+  name: 'ProductList',
+  render: { tag: 'ul' },
+  // Initial load — creates all items, stores by ID
+  load: ({ self }, products) => {
+    self.el.innerHTML = '';
+    self.store.items = {};
+    products.forEach(p => {
+      const item = o.initState({ tag: 'li', html: p.name });
+      item.appendInside(self.el);
+      self.store.items[p.id] = item;
+    });
+  },
+  // Update one item — O(1), only that text node changes
+  updateName: ({ self }, { id, name }) => { self.store.items[id]?.html(name); },
+  // Remove one item — only that node is removed
+  remove: ({ self }, id) => { self.store.items[id]?.unmount(); delete self.store.items[id]; },
+  // Add one item — no list re-render
+  addItem: ({ self }, p) => {
+    const item = o.initState({ tag: 'li', html: p.name });
+    item.appendInside(self.el);
+    self.store.items[p.id] = item;
+  },
+};
+const list = o.init(listStates).render().appendInside('#app');
+list.load(products);
+list.updateName({ id: 42, name: 'New name' }); // one write
+```
+
+---
+
+### Pattern 6 — Conditional rendering (show / hide)
+
+Show or hide a field based on a checkbox.
+
+**React**
+```jsx
+function Form() {
+  const [showCompany, setShowCompany] = React.useState(false);
+  return (
+    <div>
+      <label>
+        <input type="checkbox" onChange={e => setShowCompany(e.target.checked)} />
+        {' '}Business account
+      </label>
+      {showCompany && <input name="company" placeholder="Company name" />}
+    </div>
+  );
+  // React unmounts / remounts the input element when showCompany toggles
+}
+```
+
+**Vue 3**
+```vue
+<template>
+  <div>
+    <label><input type="checkbox" v-model="show" /> Business account</label>
+    <input v-if="show" name="company" placeholder="Company name" />
+  </div>
+</template>
+<script setup>
+import { ref } from 'vue';
+const show = ref(false);
+// v-if removes / recreates the DOM node; v-show would toggle display
+</script>
+```
+
+**Solid**
+```jsx
+import { createSignal, Show } from 'solid-js';
+function Form() {
+  const [show, setShow] = createSignal(false);
+  return (
+    <div>
+      <label>
+        <input type="checkbox" onChange={e => setShow(e.target.checked)} />
+        {' '}Business account
+      </label>
+      <Show when={show()}>
+        <input name="company" placeholder="Company name" />
+      </Show>
+    </div>
+  );
+}
+```
+
+**Objs**
+```js
+// The company field is a full atom — show/hide are state methods on it
+const companyField = o.init(FieldStates).render({ name: 'company', label: 'Company name' });
+companyField.hide(); // display:none on the atom's root element
+
+const bizBox = o.initState({
+  tag: 'label', class: 'field',
+  html: '<input type="checkbox" class="biz-check"> Business account',
+});
+
+bizBox.first('.biz-check').on('change', e => {
+  e.target.checked ? companyField.show() : companyField.hide();
+});
+// DOM node is never removed — toggled with display:none/''
+// To fully unmount and remount use .unmount() / .appendInside()
+```
+
+---
+
+### Pattern 7 — Shared state between distant components
+
+A cart badge in the header and an "Add to cart" button deep in a product card both need to read from and write to the same count.
+
+**React** — lift state up / Context
+```jsx
+const CartContext = React.createContext(null);
+
+function App() {
+  const [count, setCount] = React.useState(0);
+  const addItem = () => setCount(c => c + 1);
+  return (
+    <CartContext.Provider value={{ count, addItem }}>
+      <Header />      {/* reads count via useContext — rerenders on every count change */}
+      <ProductList /> {/* calls addItem — triggers App rerender → Header rerender */}
+    </CartContext.Provider>
+  );
+}
+function Header() {
+  const { count } = React.useContext(CartContext);
+  return <nav><span className="badge">{count}</span></nav>;
+}
+```
+
+**Vue 3** — Pinia store
+```js
+// store.js
+import { defineStore } from 'pinia';
+export const useCartStore = defineStore('cart', () => {
+  const count = ref(0);
+  const add = () => count.value++;
+  return { count, add };
+});
+// Header.vue: const { count } = storeToRefs(useCartStore()) — only badge text updates
+// ProductCard.vue: useCartStore().add()
+```
+
+**Solid** — shared signal
+```js
+// cart.js
+import { createSignal } from 'solid-js';
+const [cartCount, setCartCount] = createSignal(0);
+export const addToCart = () => setCartCount(c => c + 1);
+export { cartCount };
+// Header.jsx: <span class="badge">{cartCount()}</span> — only this text node updates
+// ProductCard.jsx: import { addToCart }; <button onClick={addToCart}>Add</button>
+```
+
+**Objs** — plain observer, no library
+```js
+// cart.js — just a plain object
+const cartStore = { count: 0, listeners: [] };
+export const addToCart = () => {
+  cartStore.count++;
+  cartStore.listeners.forEach(fn => fn(cartStore.count));
+};
+
+// header.js — subscribe: only this one innerHTML write per add
+const navBadge = o.init(BadgeStates).render({ count: 0 }).appendInside('.nav');
+cartStore.listeners.push(n => navBadge.setCount(n));
+
+// product-card.js — publish
+card.first('.add-btn').on('click', () => addToCart());
+// No parent re-renders. No context. No signals. One function call → one DOM write.
+```
+
+---
+
+### Pattern 8 — Async data fetch
+
+Load data from an API and render it. Handle the loading state.
+
+**React**
+```jsx
+function ProductList() {
+  const [products, setProducts] = React.useState([]);
+  const [loading, setLoading] = React.useState(true);
+  React.useEffect(() => {
+    fetch('/api/products')
+      .then(r => r.json())
+      .then(data => { setProducts(data); setLoading(false); });
+  }, []);
+  if (loading) return <p>Loading…</p>;
+  return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
+}
+```
+
+**Vue 3**
+```vue
+<template>
+  <p v-if="loading">Loading…</p>
+  <ul v-else>
+    <li v-for="p in products" :key="p.id">{{ p.name }}</li>
+  </ul>
+</template>
+<script setup>
+import { ref, onMounted } from 'vue';
+const products = ref([]);
+const loading  = ref(true);
+onMounted(() =>
+  fetch('/api/products').then(r => r.json()).then(data => {
+    products.value = data;
+    loading.value  = false;
+  })
+);
+</script>
+```
+
+**Solid**
+```jsx
+import { createResource, Show, For } from 'solid-js';
+function ProductList() {
+  const [products] = createResource(() =>
+    fetch('/api/products').then(r => r.json())
+  );
+  return (
+    <Show when={!products.loading} fallback={<p>Loading…</p>}>
+      <ul><For each={products()}>{p => <li>{p.name}</li>}</For></ul>
+    </Show>
+  );
+}
+```
+
+**Objs**
+```js
+const listStates = {
+  name: 'ProductList',
+  render: { tag: 'div', html: '<p class="loading">Loading…</p>' },
+  // Called by the loader when data arrives — success state
+  load: ({ self }, products) => {
+    self.el.innerHTML = '';
+    products.forEach(p => o.initState({ tag: 'p', html: p.name }).appendInside(self.el));
+  },
+  // Called by the loader on network error — fail state
+  loadFailed: ({ self }) => { self.first('.loading').html('Failed to load. Retry?'); },
+};
+
+const list = o.init(listStates).render().appendInside('#app');
+const loader = o.newLoader(o.get('/api/products'));
+list.connect(loader, 'load', 'loadFailed');
+// loader fires the request; .connect wires success → load, failure → loadFailed
+```
+
+---
+
+### Concept map — if you think in framework X
+
+| Your mental model | React | Vue 3 | Solid | Objs |
+|---|---|---|---|---|
+| Component definition | `function Foo(props)` | `<script setup>` + `<template>` | `function Foo(props)` | `states` object |
+| Create & mount | `createRoot(el).render(<Foo/>)` | `createApp(Foo).mount(el)` | `render(()=><Foo/>, el)` | `o.init(states).render(props).appendInside(el)` |
+| Reactive value | `const [v, setV] = useState(x)` | `const v = ref(x)` | `const [v, setV] = createSignal(x)` | State method writing directly to DOM |
+| Update a value | `setV(newVal)` → re-render | `v.value = newVal` → patch | `setV(newVal)` → fine patch | `comp.setState(newVal)` → direct write |
+| Read in template | `{v}` | `{{ v }}` | `{v()}` | Not needed — state methods write directly |
+| Props | function parameter | `defineProps()` | function parameter | `render(props)` argument |
+| Events | `onClick={handler}` | `@click="handler"` | `onClick={handler}` | `.on('click', handler)` |
+| Child ref | `useRef()` | `ref="name"` | `let el` / `ref` | `self.store.child = childInstance` |
+| Lifecycle: mount | `useEffect(fn, [])` | `onMounted(fn)` | `onMount(fn)` | `init` state method called after render |
+| Lifecycle: unmount | `useEffect` return fn | `onBeforeUnmount(fn)` | `onCleanup(fn)` | `comp.unmount()` |
+| Shared state | Context / Zustand | Pinia | Signals / store | Plain observer or `o.connectRedux` |
+| Fetch on mount | `useEffect` + `useState` | `onMounted` + `ref` | `createResource` | `o.newLoader` + `.connect()` |
+| Conditional render | `{flag && <El/>}` | `v-if="flag"` | `<Show when={flag}>` | `comp.show()` / `comp.hide()` |
+| List render | `arr.map(x => <El key>)` | `v-for="x in arr"` | `<For each={arr}>` | `arr.forEach` in a state method |
+| CSS class toggle | `className={flag?'a':'b'}` | `:class="{a: flag}"` | `classList={{a: flag}}` | `comp.toggleClass('a', flag)` |
+
+---
+
+## 1. How render works
+
+The `render` state is the creation state. It accepts five different forms.
+
+### 1a. Plain object — static element
+
+The simplest form. All keys become HTML attributes; special keys (`html`, `style`, `dataset`, `class`, `append`, `children`) are handled by `transform()`.
+
+```js
+const badge = o.init({
+  name: 'Badge',
+  render: { tag: 'span', class: 'badge', html: '3' },
+  update: ({ self }, n) => { self.html(n); },
+}).render();
+badge.appendInside('.nav');
+badge.update(7); // writes only to this span's innerHTML
+```
+
+### 1b. Function returning an object — dynamic attributes
+
+The function receives `{self, o, i, ...originalProps}`. All extra keys passed to `render(props)` are merged in.
+
+> **Note:** Inside all state functions, `self` is the ObjsInstance. Use `self.first()`, `self.html()` etc. directly — `o(self)` works too but is redundant wrapping.
+
+```js
+const buttonStates = {
+  name: 'Button',
+  render: ({ variant = 'default', size = 'md', label }) => ({
+    tag: 'button',
+    class: `btn btn--${variant} btn--${size}`,
+    html: label,
+  }),
+  setVariant: ({ self }, v) => { self.el.className = `btn btn--${v}`; },
+  setLabel:   ({ self }, l) => { self.html(l); },
+  setDisabled:({ self }, v) => { v ? self.attr('disabled', 'true') : self.attr('disabled', null); },
+};
+
+const btn = o.init(buttonStates).render({ variant: 'primary', label: 'Submit' });
+btn.appendInside('#toolbar');
+btn.setLabel('Saving…');  // only this element's innerHTML changes
+btn.setDisabled(true);    // only this element's disabled attribute changes
+```
+
+### 1c. HTML string — unwrapped template
+
+If the string contains exactly one root element it is unwrapped; otherwise a `div` wrapper is kept.
+
+```js
+// Single root element — unwrapped to <a>
+o.initState('<a href="/" class="logo">Brand</a>').appendInside('header');
+```
+
+### 1d. Multiple instances — one init, many elements
+
+Pass an **array of props** to `render()`. One ObjsInstance manages all elements.
+State methods operate on **all** elements by default. Use `.select(i)` for one.
+
+```js
+const navLinkStates = {
+  name: 'NavLink',
+  render: ({ label, path }) => ({ tag: 'a', class: 'nav-link', html: label, href: path }),
+  setActive: ({ self }, activePath) => {
+    // 'self.el' is the element being iterated — transform() handles the loop internally
+    // For multi-element operations, use self.find/self.forEach
+    self.forEach(({ el }) => {
+      el.classList.toggle('nav-link--active', el.getAttribute('href') === activePath);
+    });
+  },
+};
+
+const links = o.init(navLinkStates).render([
+  { label: 'Home',     path: '/' },
+  { label: 'Products', path: '/products' },
+  { label: 'About',    path: '/about' },
+]);
+// links.els = [<a>Home</a>, <a>Products</a>, <a>About</a>]
+links.appendInside('.nav');
+links.setActive('/products');          // updates all three (each checks its own href)
+links.select(0).setActive('/');        // only first link
+links.all();                           // back to all-elements mode
+```
+
+### 1e. The `append` key — live child components
+
+Pass pre-built ObjsInstances into the render object. Their DOM elements are appended into the parent. Children are created once; only state methods need to update them later.
+
+```js
+const iconEl  = o.initState({ tag: 'span', class: 'btn-icon', html: '🛒' });
+const labelEl = o.initState({ tag: 'span', class: 'btn-label', html: 'Cart' });
+
+const cartBtn = o.init({
+  name: 'CartButton',
+  render: { tag: 'button', class: 'cart-btn', append: [iconEl, labelEl] },
+  // Targeted update — only the label span changes
+  setCount: ({ self }, n) => { self.store.label.html(n > 0 ? `Cart (${n})` : 'Cart'); },
+}).render();
+
+cartBtn.store.label = labelEl; // store reference for later updates
+cartBtn.appendInside('.nav');
+cartBtn.setCount(3);  // one innerHTML write on labelEl, nothing else touched
+```
+
+### 1f. The `children` key — positional reconciliation
+
+Unlike `append` (which always adds), `children` replaces DOM nodes at each position — like a minimal reconciler. Use it when the order or count of child components changes.
+
+```js
+const gridStates = {
+  name: 'CardGrid',
+  render: { tag: 'div', class: 'grid' },
+  // Returns an object — transform() applies it to the existing element
+  reconcile: ({ self }, cards) => ({ children: cards.map(c => c.el) }),
+};
+
+const grid = o.init(gridStates).render().appendInside('#app');
+const cards = products.map(p => o.init(cardStates).render(p));
+grid.reconcile(cards);
+
+// Reorder: only moved nodes get replaceWith(), unchanged nodes are untouched
+cards.sort((a, b) => a.store.price - b.store.price);
+grid.reconcile(cards);
+```
+
+---
+
+### 1g. `ref` attributes and `self.refs`
+
+Add a `ref="name"` attribute to any element in an HTML-string render. After `init`, every such element is available on the component as `component.refs.name` — an ObjsInstance wrapper, not a raw DOM node.
+
+```js
+const cardStates = {
+  name: 'ProductCard',
+  render: ({ title, price }) => ({
+    tag: 'article',
+    className: 'card',
+    html: `<h3 ref="title">${title}</h3>
+           <p ref="price">$${price}</p>
+           <button ref="addBtn">Add to cart</button>`,
+  }),
+  // Destructure refs for clean, selector-free access
+  setAdded: ({ self }) => {
+    const { addBtn } = self.refs;
+    addBtn.html('✓ Added').attr('disabled', '');
+  },
+  updatePrice: ({ self }, newPrice) => {
+    self.refs.price.html('$' + newPrice);
+  },
+};
+
+const card = o.init(cardStates).render({ title: 'Widget', price: 9.99 }).appendInside('#app');
+// card.refs.addBtn — ObjsInstance wrapping the <button ref="addBtn">
+// card.refs.title  — ObjsInstance wrapping the <h3 ref="title">
+card.refs.addBtn.on('click', () => card.setAdded());
+```
+
+> In React, `useRef` accesses a single DOM node. Objs `refs` auto-collects all named children at init time — no `useRef` call per element, no `ref={myRef}` on every JSX tag.
+
+---
+
+## 2. Single components — atoms
+
+Atoms are self-contained components with no children. They define only their own element and targeted update states.
+
+### Button atom
+
+```js
+const ButtonStates = {
+  name: 'Button',
+  render: ({ label, variant = 'default', size = 'md', disabled = false }) => ({
+    tag: 'button',
+    class: `btn btn--${variant} btn--${size}`,
+    html: label,
+    ...(disabled ? { disabled: 'true' } : {}),
+  }),
+  setLabel:    ({ self }, l) => { self.html(l); },
+  setVariant:  ({ self }, v) => { self.addClass(`btn--${v}`); },
+  setDisabled: ({ self }, v) => { v ? self.attr('disabled', 'true') : self.attr('disabled', null); },
+  setLoading:  ({ self }, v) => {
+    self.toggleClass('btn--loading', v);
+    v ? self.attr('disabled', 'true') : self.attr('disabled', null);
+  },
+};
+```
+
+### Badge atom
+
+```js
+const BadgeStates = {
+  name: 'Badge',
+  render: ({ count = 0, variant = 'primary' }) => ({
+    tag: 'span',
+    class: `badge badge--${variant}`,
+    html: String(count),
+    style: count === 0 ? 'display:none' : '',
+  }),
+  setCount: ({ self }, n) => {
+    self.html(n);
+    // Re-apply inline style — transform skips unchanged values
+    n === 0 ? self.css({ display: 'none' }) : self.css(null);
+  },
+};
+```
+
+### Input field atom
+
+```js
+const FieldStates = {
+  name: 'FormField',
+  render: ({ name, label, type = 'text', placeholder = '' }) => ({
+    tag: 'div',
+    class: 'field',
+    html: `<label class="field__label">${label}</label>
+           <input class="field__input" type="${type}" name="${name}" placeholder="${placeholder}">
+           <span class="field__error"></span>`,
+  }),
+  // Each state only touches its specific sub-element
+  setError:   ({ self }, msg) => {
+    self.first('.field__input').addClass('field__input--error');
+    self.first('.field__error').html(msg || '');
+  },
+  setSuccess: ({ self }) => {
+    self.first('.field__input').removeClass('field__input--error').addClass('field__input--ok');
+    self.first('.field__error').html('');
+  },
+  setIdle:    ({ self }) => {
+    self.first('.field__input').removeClass('field__input--error').removeClass('field__input--ok');
+    self.first('.field__error').html('');
+  },
+  getValue:   ({ self }) => self.first('.field__input').val(),
+  show:       ({ self }) => { self.css(null); },
+  hide:       ({ self }) => { self.css({ display: 'none' }); },
+};
+```
+
+---
+
+## 3. Nesting & composition
+
+Three patterns for building composite components. Choose based on how the parent and children relate.
+
+### Pattern A — Slot pattern
+
+Best for: containers with named regions (cards, dialogs, panels, toolbars).
+
+Parent defines named slot containers in `html`. Children fill them via `appendInside`. Parent tracks children in `self.store`.
+
+**When to update:** call child's own state methods directly. The parent DOM is never touched.
+
+```js
+const CardStates = {
+  name: 'Card',
+  render: {
+    tag: 'article',
+    class: 'card',
+    html: `<div class="card__header"></div>
+           <div class="card__body"></div>
+           <div class="card__footer"></div>`,
+  },
+  // Each slot setter unmounts the previous occupant and mounts the new one
+  setHeader: ({ self }, comp) => {
+    self.store.header?.unmount();
+    self.store.header = comp;
+    const slot = self.first('.card__header').el;
+    slot.innerHTML = '';
+    comp.appendInside(slot);
+  },
+  setBody: ({ self }, comp) => {
+    self.store.body?.unmount();
+    self.store.body = comp;
+    const slot = self.first('.card__body').el;
+    slot.innerHTML = '';
+    comp.appendInside(slot);
+  },
+  setFooter: ({ self }, comp) => {
+    self.store.footer?.unmount();
+    self.store.footer = comp;
+    const slot = self.first('.card__footer').el;
+    slot.innerHTML = '';
+    comp.appendInside(slot);
+  },
+};
+
+// Assembly — each component is independent, card just hosts them
+const card = o.init(CardStates).render().appendInside('#app');
+const title   = o.init(ButtonStates).render({ label: 'Product Title', variant: 'ghost' });
+const price   = o.init(BadgeStates).render({ count: 49 });
+const buyBtn  = o.init(ButtonStates).render({ label: 'Add to cart', variant: 'primary' });
+
+card.setHeader(title);
+card.setBody(price);
+card.setFooter(buyBtn);
+
+// Update — zero DOM above the component
+title.setLabel('New Product Name');  // only touches card__header's <button>
+price.setCount(39);                  // only touches card__body's <span>
+```
+
+### Pattern B — append in render
+
+Best for: molecules assembled from known atoms at creation time. Children are immutable after render.
+
+Children are created before the parent and passed via `append`. The parent is a structural wrapper only.
+
+```js
+function createSearchBar() {
+  // Build atoms first
+  const input = o.init({
+    name: 'SearchInput',
+    render: { tag: 'input', class: 'search__input', placeholder: 'Search…', type: 'search' },
+    clear: ({ self }) => { self.val(''); },
+  }).render();
+
+  const btn = o.init(ButtonStates).render({ label: '🔍', variant: 'icon' });
+
+  // Parent wraps them via append — no html needed
+  const bar = o.init({
+    name: 'SearchBar',
+    render: { tag: 'div', class: 'search-bar', append: [input, btn] },
+    clear:    ({ self }) => { self.store.input.clear(); },
+    getValue: ({ self }) => self.store.input.val(),
+    focus:    ({ self }) => { self.store.input.el.focus(); },
+  }).render();
+
+  // Store references after render
+  bar.store.input = input;
+  bar.store.btn   = btn;
+
+  // Wire events using stored refs — no DOM queries needed
+  btn.on('click', () => {
+    bar.el.dispatchEvent(new CustomEvent('search', { detail: bar.getValue(), bubbles: true }));
+  });
+
+  return bar;
+}
+
+const searchBar = createSearchBar().appendInside('.toolbar');
+document.addEventListener('search', (e) => console.log('query:', e.detail));
+```
+
+### Pattern C — factory function with lazy child creation
+
+Best for: dynamic lists, data-driven components, components where children change at runtime.
+
+Children are created inside a state method (not in render). The parent stores all child references and exposes methods to add, update, or remove individual items.
+
+```js
+const ListStates = {
+  name: 'ProductList',
+  render: { tag: 'ul', class: 'product-list' },
+
+  // Called once when data arrives
+  load: ({ self }, products) => {
+    self.el.innerHTML = ''; // clear
+    self.store.items = {};  // reset map
+
+    products.forEach((product) => {
+      const card = o.init(CardStates).render();
+      const titleComp = o.init(ButtonStates).render({ label: product.title, variant: 'ghost' });
+      const priceComp = o.init(BadgeStates).render({ count: product.price });
+
+      card.setHeader(titleComp);
+      card.setBody(priceComp);
+      card.appendInside(self.el);
+
+      // Store by product ID for O(1) targeted updates
+      self.store.items[product.id] = { card, titleComp, priceComp, product };
+    });
+  },
+
+  // Update a single item — only its components are touched
+  updatePrice: ({ self }, { id, price }) => {
+    self.store.items[id]?.priceComp.setCount(price);
+  },
+
+  // Remove a single item — only its node is removed
+  remove: ({ self }, id) => {
+    self.store.items[id]?.card.unmount();
+    delete self.store.items[id];
+  },
+
+  // Add one item without re-rendering the list
+  addItem: ({ self }, product) => {
+    const card = o.init(CardStates).render();
+    card.setHeader(o.init(ButtonStates).render({ label: product.title, variant: 'ghost' }));
+    card.setBody(o.init(BadgeStates).render({ count: product.price }));
+    card.appendInside(self.el);
+    self.store.items[product.id] = { card, product };
+  },
+};
+
+const list = o.init(ListStates).render().appendInside('#products');
+const loader = o.newLoader(o.get('/api/products'));
+list.connect(loader, 'load');
+
+// Later — only the changed item's badge is touched
+list.updatePrice({ id: 42, price: 39 });
+```
+
+---
+
+## 4. Design system architecture
+
+Objs maps naturally to Atomic Design. Each layer uses the composition pattern appropriate to its role.
+
+```
+Atoms      →  pure state objects, no children, no store
+Molecules  →  append pattern (atoms assembled at creation)
+Organisms  →  slot pattern (molecules mounted into named regions)
+Templates  →  factory functions wiring organisms to data stores
+```
+
+### Layer 1 — Atoms (reusable state objects)
+
+An atom is just a states object. Export it, share it, extend it.
+
+```js
+// atoms.js
+export const ButtonStates   = { name: 'Button',   render: ..., setLabel: ..., setDisabled: ... };
+export const BadgeStates    = { name: 'Badge',     render: ..., setCount: ... };
+export const FieldStates    = { name: 'FormField', render: ..., setError: ..., setSuccess: ... };
+export const AvatarStates   = { name: 'Avatar',    render: ({ src, alt }) => ({ tag:'img', class:'avatar', src, alt }) };
+export const SpinnerStates  = { name: 'Spinner',   render: { tag:'div', class:'spinner' } };
+```
+
+Atoms should have **no `self.store` usage** and **no child components**. Every state method writes directly to the element or its immediate children (via `self.first()`).
+
+### Layer 2 — Molecules (assembled atoms)
+
+A molecule is a factory function that builds atoms, wires them together, and returns the parent component.
+
+```js
+// molecules.js
+import { ButtonStates, BadgeStates } from './atoms.js';
+
+export function createCartButton(initialCount = 0) {
+  const badge  = o.init(BadgeStates).render({ count: initialCount });
+  const icon   = o.initState({ tag: 'span', class: 'cart-icon', html: '🛒' });
+
+  const btn = o.init({
+    name: 'CartButton',
+    render: { tag: 'button', class: 'cart-btn', append: [icon, badge] },
+    setCount: ({ self }, n) => { self.store.badge.setCount(n); },
+    setLoading: ({ self }, v) => { self.toggleClass('cart-btn--loading', v); },
+  }).render();
+
+  btn.store.badge = badge;
+  btn.store.icon  = icon;
+  return btn;
+}
+
+export function createIconButton(icon, label) {
+  const iconEl  = o.initState({ tag: 'span', class: 'btn__icon', html: icon });
+  const labelEl = o.initState({ tag: 'span', class: 'btn__label', html: label });
+
+  const btn = o.init({
+    name: 'IconButton',
+    render: { tag: 'button', class: 'btn btn--icon', append: [iconEl, labelEl] },
+    setIcon:  ({ self }, v) => { self.store.icon.html(v); },
+    setLabel: ({ self }, v) => { self.store.label.html(v); },
+  }).render();
+
+  btn.store.icon  = iconEl;
+  btn.store.label = labelEl;
+  return btn;
+}
+```
+
+### Layer 3 — Organisms (slot-based containers)
+
+An organism uses the slot pattern. It defines its structure and exposes methods to mount molecules into named regions.
+
+```js
+// organisms.js
+import { createCartButton, createSearchBar } from './molecules.js';
+
+export const ToolbarStates = {
+  name: 'Toolbar',
+  render: {
+    tag: 'header',
+    class: 'toolbar',
+    html: `<div class="toolbar__start"></div>
+           <div class="toolbar__center"></div>
+           <div class="toolbar__end"></div>`,
+  },
+  mount: ({ self }, { slot, comp }) => {
+    const slotEl = self.first(`.toolbar__${slot}`).el;
+    self.store[slot]?.unmount();
+    self.store[slot] = comp;
+    slotEl.innerHTML = '';
+    comp.appendInside(slotEl);
+  },
+  // Expose slot accessors
+  getSlot: ({ self }, slot) => self.store[slot],
+};
+
+// Template — assembles the toolbar, wires it to stores
+export function createAppToolbar(cartStore) {
+  const logo     = o.initState({ tag: 'a', class: 'logo', href: '/', html: 'Brand' });
+  const search   = createSearchBar();
+  const cartBtn  = createCartButton(0);
+
+  const toolbar = o.init(ToolbarStates).render().appendInside('body');
+  toolbar.mount({ slot: 'start',  comp: logo });
+  toolbar.mount({ slot: 'center', comp: search });
+  toolbar.mount({ slot: 'end',    comp: cartBtn });
+
+  // Wire cart store — only the badge updates on change
+  cartStore.listeners.push((items) => cartBtn.setCount(items.length));
+
+  return { toolbar, search, cartBtn };
+}
+```
+
+### Extending states (variant inheritance)
+
+Extend an atom's states object with `Object.assign` to create specialised variants:
+
+```js
+// atoms.js
+export const ButtonStates = { name: 'Button', render: ..., setLabel: ..., setDisabled: ... };
+
+// Add a variant — extends without modifying the base
+export const SubmitButtonStates = {
+  ...ButtonStates,
+  name: 'SubmitButton',
+  render: ({ label = 'Submit', ...rest }) => ButtonStates.render({ label, variant: 'primary', ...rest }),
+  // Adds loading state on top of atom's states
+  submit: ({ self }) => {
+    self.setDisabled(true);
+    self.setLabel('Saving…');
+    self.toggleClass('btn--loading', true);
+  },
+  reset: ({ self }) => {
+    self.setDisabled(false);
+    self.setLabel('Submit');
+    self.toggleClass('btn--loading', false);
+  },
+};
+```
+
+### Update efficiency summary
+
+| Update target | How to do it | DOM writes |
+|---|---|---|
+| Atom attribute | `atom.setLabel('x')` | 1 — direct innerHTML or setAttribute |
+| Atom in molecule | `molecule.store.atom.setLabel('x')` | 1 — same atom write |
+| Slot in organism | `organism.store.slot.stateMethod()` | 1 or more — only that slot's subtree |
+| List item | `list.store.items[id].comp.update(data)` | 1+ — only that card |
+| All list items | `list.reconcile(newOrder)` | replaceWith per changed position only |
+| Full list reload | `list.load(newProducts)` | clears and re-creates |
+
+---
+
+## 5. Real-world examples
+
+### 5a. Site navigation menu
+
+Active route highlighting, mobile toggle. Uses multi-instance render for links.
+
+```js
+o.autotag = 'qa';
+
+const navLinkStates = {
+  name: 'NavLink',
+  render: ({ label, path }) => ({ tag: 'a', class: 'nav-link', html: label, href: path }),
+  setActive: ({ self }, activePath) => {
+    self.forEach(({ el }) => {
+      el.classList.toggle('nav-link--active', el.getAttribute('href') === activePath);
+    });
+  },
+};
+
+const toggleStates = {
+  name: 'NavToggle',
+  render: { tag: 'button', class: 'nav-toggle', html: '☰' },
+};
+
+const menuStates = {
+  name: 'SiteMenu',
+  render: { tag: 'nav', class: 'nav' },
+  init: ({ self }) => {
+    const links = o.init(navLinkStates).render([
+      { label: 'Home',     path: '/' },
+      { label: 'Products', path: '/products' },
+      { label: 'About',    path: '/about' },
+    ]);
+    const toggle = o.init(toggleStates).render();
+
+    links.appendInside(self.el);
+    toggle.appendInside(self.el);
+
+    // Store for later access
+    self.store.links  = links;
+    self.store.toggle = toggle;
+
+    links.setActive(window.location.pathname);
+    toggle.on('click', () => self.toggleClass('nav--open'));
+  },
+};
+
+const menu = o.init(menuStates).render().appendInside('header');
+menu.init(); // sets up children
+```
+
+### 5b. Product card list + cart badge
+
+One shared cart store, two components subscribing to different state methods. Neither rerenders when the other updates.
+
+```js
+// ── Shared cart store (plain object with listeners) ───────────────────────
+const cartStore = { items: [], listeners: [] };
+const cartAdd = (product) => { cartStore.items.push(product); cartStore.listeners.forEach(fn => fn(cartStore.items)); };
+
+// ── Cart badge in nav ─────────────────────────────────────────────────────
+const cartBadge = o.init(BadgeStates).render({ count: 0 }).appendInside('.nav');
+cartStore.listeners.push((items) => cartBadge.setCount(items.length));
+
+// ── Product card ──────────────────────────────────────────────────────────
+const productCardStates = {
+  name: 'ProductCard',
+  render: ({ title, price }) => ({
+    tag: 'article',
+    class: 'card',
+    html: `<h3 class="card__title">${title}</h3>
+           <p class="card__price">$${price}</p>
+           <button class="card__btn">Add to cart</button>`,
+  }),
+  // Granular: only the button changes, card root never touched
+  setAdded: ({ self }) => {
+    self.first('.card__btn').html('✓ Added').attr('disabled', '');
+  },
+};
+
+// ── Product list (factory pattern — children in self.store) ───────────────
+const productListStates = {
+  name: 'ProductList',
+  render: { tag: 'div', class: 'card-list' },
+  load: ({ self }, products) => {
+    self.store.cards = {};
+    products.forEach((product) => {
+      const card = o.init(productCardStates).render(product);
+      card.appendInside(self.el);
+      // Wire button — no DOM query needed, card has .first()
+      card.first('.card__btn').on('click', () => {
+        cartAdd(product);
+        card.setAdded(); // only this card's button changes
+      });
+      self.store.cards[product.id] = card;
+    });
+  },
+};
+
+const productList = o.init(productListStates).render().appendInside('#products');
+productList.connect(o.newLoader(o.get('/api/products')), 'load');
+```
+
+### 5c. Overlay dialog with UTM auto-open
+
+Promo dialog triggered by `?promo=CODE` URL parameter. sessionStorage prevents repeat shows.
+
+```js
+const PROMO_KEY = 'oTest-promo-shown';
+
+const dialogStates = {
+  name: 'PromoDialog',
+  render: {
+    tag: 'div', class: 'dialog-overlay', style: 'display:none',
+    html: `<div class="dialog">
+      <button class="dialog__close">✕</button>
+      <h2 class="dialog__title"></h2>
+      <p class="dialog__body"></p>
+      <a class="dialog__cta" href="#">Get offer</a>
+    </div>`,
+  },
+  open: ({ self }, { title, body, cta, ctaUrl }) => {
+    self.first('.dialog__title').html(title);
+    self.first('.dialog__body').html(body);
+    self.first('.dialog__cta').html(cta).attr('href', ctaUrl);
+    self.css({ display: 'flex' });
+    sessionStorage.setItem(PROMO_KEY, '1');
+  },
+  close: ({ self }) => { self.css(null); },
+};
+
+const dialog = o.init(dialogStates).render().appendInside('body');
+dialog.first('.dialog__close').on('click', () => dialog.close());
+dialog.on('click', (e) => { if (e.target === dialog.el) dialog.close(); });
+
+const promoCode = o.getParams('promo');
+if (promoCode && !sessionStorage.getItem(PROMO_KEY)) {
+  o.get('/api/promos/' + promoCode).then(r => r.json()).then(data => dialog.open(data));
+}
+```
+
+### 5d. Filter drawer with two-way URL sync
+
+Filters write to the URL and restore from it on page load. No reload needed.
+
+```js
+const getFilters = () => {
+  const p = o.getParams();
+  return { category: p.category || '', minPrice: p.minPrice || '', maxPrice: p.maxPrice || '' };
+};
+
+const applyFilters = (filters, productsLoader) => {
+  const params = new URLSearchParams(filters);
+  for (const [k, v] of [...params]) { if (!v) params.delete(k); }
+  history.pushState({}, '', params.toString() ? '?' + params : window.location.pathname);
+  productsLoader.reload(o.get('/api/products?' + params.toString()));
+};
+
+const drawerStates = {
+  name: 'FilterDrawer',
+  render: {
+    tag: 'aside', class: 'drawer', style: 'transform:translateX(-100%)',
+    html: `<button class="drawer__close">✕</button>
+           <h3>Filters</h3>
+           <select class="drawer__cat"><option value="">All</option><option value="electronics">Electronics</option></select>
+           <input class="drawer__min" type="number" placeholder="Min $">
+           <input class="drawer__max" type="number" placeholder="Max $">
+           <button class="drawer__apply">Apply</button>
+           <button class="drawer__reset">Reset</button>`,
+  },
+  open:    ({ self }) => { self.css({ transform: 'translateX(0)' }); },
+  close:   ({ self }) => { self.css({ transform: 'translateX(-100%)' }); },
+  restore: ({ self }, { category, minPrice, maxPrice }) => {
+    self.first('.drawer__cat').val(category);
+    self.first('.drawer__min').val(minPrice);
+    self.first('.drawer__max').val(maxPrice);
+  },
+  getValues: ({ self }) => ({
+    category: self.first('.drawer__cat').val(),
+    minPrice:  self.first('.drawer__min').val(),
+    maxPrice:  self.first('.drawer__max').val(),
+  }),
+};
+
+const drawer = o.init(drawerStates).render().appendInside('body');
+drawer.restore(getFilters());
+
+drawer.first('.drawer__close').on('click', () => drawer.close());
+drawer.first('.drawer__apply').on('click', () => {
+  applyFilters(drawer.getValues(), productsLoader);
+  drawer.close();
+});
+drawer.first('.drawer__reset').on('click', () => {
+  const empty = { category: '', minPrice: '', maxPrice: '' };
+  applyFilters(empty, productsLoader);
+  drawer.restore(empty);
+});
+
+o.first('#open-filters').on('click', () => drawer.open());
+```
+
+### 5e. Complex form — validation, conditional fields, live preview
+
+Each field is an independent atom. Validation state and submit gate are pure JS, not in the DOM.
+
+```js
+const validators = {
+  email:   v => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) || 'Invalid email address',
+  name:    v => v.trim().length >= 2                  || 'Minimum 2 characters',
+  company: v => v.trim().length >= 1                  || 'Required for business accounts',
+};
+
+// ── Field atom (reuses FieldStates from section 2) ────────────────────────
+const emailField   = o.init(FieldStates).render({ name: 'email',   label: 'Email',       placeholder: 'you@example.com' });
+const nameField    = o.init(FieldStates).render({ name: 'name',    label: 'Full name',    placeholder: 'Jane Smith' });
+const companyField = o.init(FieldStates).render({ name: 'company', label: 'Company name', placeholder: 'Acme Inc' });
+
+// ── Checkbox (simple initState — no custom methods needed) ────────────────
+const bizBox = o.initState({
+  tag: 'label', class: 'field',
+  html: '<input type="checkbox" name="isBusiness" class="biz-check"> Business account',
+});
+
+// ── Live preview ──────────────────────────────────────────────────────────
+const previewStates = {
+  name: 'FormPreview',
+  render: { tag: 'div', class: 'preview', html: 'Preview: <b class="pv-name">—</b> &lt;<span class="pv-email">—</span>&gt;' },
+  update: ({ self }, { name, email }) => {
+    self.first('.pv-name').html(name || '—');
+    self.first('.pv-email').html(email || '—');
+  },
+};
+const preview = o.init(previewStates).render();
+
+// ── Form organism (slot pattern) ──────────────────────────────────────────
+const formStates = {
+  name: 'RegistrationForm',
+  render: {
+    tag: 'form', class: 'form',
+    html: '<div class="form__fields"></div><div class="form__preview"></div><button type="submit" class="btn btn--primary" disabled>Submit</button>',
+  },
+  init: ({ self }) => {
+    const fieldsRoot   = self.first('.form__fields').el;
+    const previewRoot  = self.first('.form__preview').el;
+
+    emailField.appendInside(fieldsRoot);
+    nameField.appendInside(fieldsRoot);
+    bizBox.appendInside(fieldsRoot);
+    companyField.appendInside(fieldsRoot);
+    preview.appendInside(previewRoot);
+
+    companyField.hide();
+
+    self.store.fields   = { emailField, nameField, companyField };
+    self.store.preview  = preview;
+    self.store.valid    = { email: false, name: false, company: true, isBiz: false };
+  },
+  checkSubmit: ({ self }) => {
+    const v = self.store.valid;
+    const ok = v.email && v.name && (!v.isBiz || v.company);
+    self.first('button[type="submit"]').el.disabled = !ok;
+  },
+};
+
+const form = o.init(formStates).render().appendInside('#form-container');
+form.init();
+
+// ── Validation wiring ─────────────────────────────────────────────────────
+const validate = (fieldComp, rule, value) => {
+  const res = validators[rule](value);
+  res === true ? fieldComp.setSuccess() : fieldComp.setError(res);
+  return res === true;
+};
+
+emailField.first('input')
+  .on('blur',  (e) => { form.store.valid.email = validate(emailField, 'email', e.target.value); form.checkSubmit(); })
+  .on('input', (e) => { preview.update({ name: nameField.getValue(), email: e.target.value }); });
+
+nameField.first('input')
+  .on('blur',  (e) => { form.store.valid.name = validate(nameField, 'name', e.target.value); form.checkSubmit(); })
+  .on('input', (e) => { preview.update({ name: e.target.value, email: emailField.getValue() }); });
+
+bizBox.first('.biz-check').on('change', (e) => {
+  form.store.valid.isBiz = e.target.checked;
+  if (e.target.checked) {
+    companyField.show();
+  } else {
+    companyField.hide();
+    companyField.setIdle();
+    form.store.valid.company = true;
+  }
+  form.checkSubmit();
+});
+
+companyField.first('input')
+  .on('blur', (e) => { form.store.valid.company = validate(companyField, 'company', e.target.value); form.checkSubmit(); });
+
+form.on('submit', (e) => {
+  e.preventDefault();
+  const submitBtn = form.first('button[type="submit"]');
+  submitBtn.setLoading?.(true);
+  o.post('/api/register', { data: Object.fromEntries(new FormData(e.target)) })
+    .then(r => r.json())
+    .then(() => submitBtn.setLoading?.(false));
+});
+```
+
+---
+
+## 6. React integration
+
+### Mode 1 — Objs inside a React ref (most common)
+
+Mount an Objs component into a React-managed DOM node via `useRef`. Always unmount in the cleanup function.
+
+```jsx
+function ProductSection() {
+  const containerRef = React.useRef(null);
+
+  React.useEffect(() => {
+    if (!containerRef.current) return;
+
+    // Create Objs components inside useEffect — NOT in component body
+    const list = o.init(productListStates).render().appendInside(containerRef.current);
+    list.connect(o.newLoader(o.get('/api/products')), 'load');
+
+    return () => list.unmount(); // required — prevents memory leak on unmount
+  }, []); // empty deps — run once
+
+  return <div ref={containerRef} />;
+}
+```
+
+### Mode 2 — React context bridge (shared state, no React rerender)
+
+`o.withReactContext` returns a React component that calls an Objs state method when context changes. It renders nothing — it is a pure side-effect bridge.
+
+```jsx
+// CartContext.js
+export const CartContext = React.createContext({ items: [], addItem: () => {} });
+
+// App.jsx
+import { CartContext } from './CartContext';
+
+function App() {
+  const [items, setItems] = React.useState([]);
+  const addItem = React.useCallback((item) => setItems(prev => [...prev, item]), []);
+
+  return (
+    <CartContext.Provider value={{ items, addItem }}>
+      <Header />
+      <ProductSection addItem={addItem} />
+    </CartContext.Provider>
+  );
+}
+
+// ProductSection.jsx — Objs grid with React context bridge
+function ProductSection({ addItem }) {
+  const containerRef = React.useRef(null);
+
+  React.useEffect(() => {
+    if (!containerRef.current) return;
+
+    // All Objs components created inside useEffect
+    const cartBadge = o.init(BadgeStates).render({ count: 0 });
+    const grid = o.init(productListStates).render().appendInside(containerRef.current);
+
+    // Wire the add-to-cart action to React's state setter
+    grid.store.onAdd = (product) => {
+      addItem(product); // React's useState → React header rerenders with new count
+    };
+
+    grid.connect(o.newLoader(o.get('/api/products')), 'load');
+
+    // Store cartBadge on the ref so the bridge component can access it
+    containerRef.current._cartBadge = cartBadge;
+
+    return () => { grid.unmount(); cartBadge.unmount(); };
+  }, []);
+
+  // Bridge: CartContext.items → cartBadge.setCount (no React subtree rerender)
+  // Created inline — React creates it once, re-runs only when context changes
+  const CartBridge = React.useMemo(
+    () => o.withReactContext(
+      React,
+      CartContext,
+      ctx => ctx.items.length,
+      // cartBadge may not exist yet on first render — the bridge handles undefined gracefully
+      { setCount: (n) => containerRef.current?._cartBadge?.setCount(n) },
+      'setCount'
+    ),
+    []
+  );
+
+  return (
+    <div>
+      <CartBridge />  {/* renders null — pure side effect */}
+      <div ref={containerRef} />
+    </div>
+  );
+}
+```
+
+### Mode 3 — Objs element as React element
+
+Use `prepareFor(React)` to export a rendered Objs element into a React render tree.
+
+```jsx
+function AnimatedBadge({ count }) {
+  const badge = React.useMemo(() => o.init(BadgeStates).render({ count }), []);
+
+  React.useEffect(() => {
+    badge.setCount(count);
+  }, [count]);
+
+  // Returns a React element that mounts the Objs DOM node
+  return badge.prepareFor(React);
+}
+```
+
+### Mode 4 — Bolt-on Playwright test generation for existing React apps
+
+Live demo: [Recording & Test Generation](examples/recording/index.html) — task app with scoped `o.startRecording(observe)`, auto-generated assertions in the export, and the dev-only manual check overlay `o.testConfirm` after replay.
+
+Add one script tag to `index.html` (dev/staging only, stripped from prod via the `__DEV__` block):
+
+```html
+<script src="objs.js"></script>
+<script> o.autotag = 'qa'; </script>
+```
+
+Mark key React elements with stable QA selectors — three options:
+
+```jsx
+// A) Manual attribute
+<button data-qa="checkout-btn" onClick={handleCheckout}>Checkout</button>
+
+// B) o.reactQA() utility — converts CamelCase to kebab-case automatically
+<button {...o.reactQA('CheckoutButton')} onClick={handleCheckout}>Checkout</button>
+// → <button data-qa="checkout-button">
+
+// C) Inline hook (no import needed)
+const useQA = n => ({ 'data-qa': n.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '') });
+<button {...useQA('CheckoutButton')} onClick={handleCheckout}>Checkout</button>
+```
+
+From the browser console (or a QA toolbar injected into staging):
+
+```js
+o.startRecording();
+// QA tester uses the app normally — clicks, fills forms, navigates
+const rec = o.stopRecording();
+console.log(o.exportPlaywrightTest(rec, { testName: 'Checkout flow' }));
+```
+
+Generated output — paste into `tests/checkout.spec.ts`:
+
+```ts
+// Auto-generated by o.exportPlaywrightTest() — review and anonymize mocks before committing
+// Prerequisites: npm install @playwright/test && npx playwright install chromium
+// Run: npx playwright test checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('Checkout flow', async ({ page }) => {
+  // Network mocks — edit/anonymize before committing
+  await page.route('**/api/cart', async route => {
+    await route.fulfill({ status: 200, contentType: 'application/json',
+      body: JSON.stringify({ items: [], total: 0 }) });
+  });
+
+  // Set baseURL in playwright.config.ts: { use: { baseURL: 'https://staging.example.com' } }
+  await page.goto('/checkout');
+
+  await page.locator('[data-qa="email-field"]').fill('jane@example.com');
+  await page.locator('[data-qa="checkout-button"]').click();
+
+  // TODO: Add assertions before committing, e.g.:
+  // await expect(page.locator('[data-qa="success-panel"]')).toBeVisible();
+  // await expect(page).toHaveURL(/\/confirmation/);
+});
+```
+
+> The `data-qa` selectors set by `o.autotag` or `o.reactQA()` are stable across deploys — they don't change when class names are renamed or elements are restructured.
+
+### Key rules for React coexistence
+
+| Rule | Reason |
+|---|---|
+| Create Objs components inside `useEffect`, not component body | Component body re-runs on every React render — Objs components would be recreated |
+| Always call `component.unmount()` in the useEffect return | Prevents memory leaks and orphaned event listeners |
+| Do not use `appendInside` with React-managed selectors | React may move or replace the DOM node — use `ref.current` |
+| Use `o.withReactContext` for context→Objs data flow | Zero React rerender; direct Objs state call |
+| Use React's `useState`/`useCallback` for Objs→React data flow | `addItem(product)` calls React's setter which triggers React's rerender in its own tree |
+| Use `o.reactQA(name)` for stable test selectors | `data-qa` attributes survive CSS refactors and component restructuring |