@getforma/core 1.0.1 → 1.0.2

package/README.md

@@ -2,9 +2,30 @@
 
 [![CI](https://github.com/getforma-dev/formajs/actions/workflows/ci.yml/badge.svg)](https://github.com/getforma-dev/formajs/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@getforma/core)](https://www.npmjs.com/package/@getforma/core)
+[![Socket Badge](https://socket.dev/api/badge/npm/package/@getforma/core)](https://socket.dev/npm/package/@getforma/core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Reactive DOM library with fine-grained signals. No virtual DOM — `h()` creates real elements, signals update only what changed. ~15KB gzipped.
+Reactive DOM library with fine-grained signals. No virtual DOM — signals update only the DOM nodes that changed. Components run once. ~15 KB gzipped.
+
+```tsx
+import { createSignal, h, mount } from "@getforma/core";
+
+const [count, setCount] = createSignal(0);
+
+function Counter() {
+  return (
+    <button onClick={() => setCount((c) => c + 1)}>
+      {() => `Clicked ${count()} times`}
+    </button>
+  );
+}
+
+mount(() => <Counter />, "#app");
+```
+
+No re-renders. No dependency arrays. No `useMemo`. The button text updates because it reads `count()` inside a reactive function — nothing else in the tree is touched.
+
+---
 
 ## Install
 
@@ -12,15 +33,23 @@ Reactive DOM library with fine-grained signals. No virtual DOM — `h()` creates
 npm install @getforma/core
 ```
 
-Or use the CDN (no build step required):
+Or use a CDN — no build step, no bundler:
 
 ```html
+<!-- jsDelivr (recommended) -->
+<script src="https://cdn.jsdelivr.net/npm/@getforma/core@latest/dist/formajs-runtime.global.js"></script>
+
+<!-- unpkg -->
 <script src="https://unpkg.com/@getforma/core/dist/formajs-runtime.global.js"></script>
 ```
 
-### Getting Started with a Bundler
+> **Production:** Pin the version (e.g., `@getforma/core@1.0.1`) instead of `@latest`.
+
+---
+
+## Getting Started with a Bundler
 
-After `npm install`, you need a bundler to resolve the ES module imports. Here's a minimal Vite setup:
+After `npm install`, you need a bundler to resolve ES module imports. Here's a minimal Vite setup:
 
 ```bash
 npm install @getforma/core
@@ -33,17 +62,20 @@ npm install -D vite
 <script type="module" src="./main.ts"></script>
 ```
 
-```typescript
+```ts
 // main.ts
-import { createSignal, h, mount } from '@getforma/core';
+import { createSignal, h, mount } from "@getforma/core";
 
 const [count, setCount] = createSignal(0);
 
-mount(() =>
-  h('button', { onClick: () => setCount(count() + 1) },
-    () => `Clicked ${count()} times`
-  ),
-  '#app'
+mount(
+  () =>
+    h(
+      "button",
+      { onClick: () => setCount((c) => c + 1) },
+      () => `Clicked ${count()} times`,
+    ),
+  "#app",
 );
 ```
 
@@ -51,167 +83,288 @@ mount(() =>
 npx vite
 ```
 
-For **esbuild**, **tsup**, or other bundlers — no special config is needed. FormaJS ships standard ESM and CJS via `package.json` exports.
+**Any bundler works.** Vite, esbuild, tsup, webpack, Rollup — FormaJS ships standard ESM and CJS via `package.json` exports. No plugins, no special config.
 
-## Why FormaJS?
+---
+
+## Coming from React?
+
+If you know React, you already know ~80% of FormaJS. Components are functions. Props flow down. You import, export, and compose the same way. The difference is *how reactivity works* — and it's simpler.
 
-Most UI libraries make you choose: simple but limited (Alpine, htmx), or powerful but complex (React, Vue, Svelte). FormaJS gives you a single reactive core that scales from a CDN script tag to a full-stack Rust SSR pipeline.
+React re-runs your entire component function on every state change, diffs a virtual DOM, and patches the real one. FormaJS runs each component **once**. Signals update only the specific DOM nodes that read them. No reconciliation, no stale closures, no `useCallback`.
 
-**Design principles:**
+| React | FormaJS | What changes |
+|---|---|---|
+| `useState` | `createSignal` | Same `[value, setter]` tuple |
+| `useMemo` | `createComputed` | No dependency array — auto-tracks |
+| `useEffect` | `createEffect` | No dependency array — auto-tracks |
+| `useReducer` | `createReducer` | Same dispatch pattern |
+| `useContext` | `createContext` / `inject` | Same provider pattern |
+| `React.memo` | *Not needed* | Components already run once |
+| Component functions | Same | `function Counter(props) { ... }` |
+| Props | Same | `<Counter count={count} />` |
+| Children | Same | Rest params or `props.children` |
+| Import / export | Same | Standard ES modules |
 
-- **Real DOM, not virtual DOM.** `h('div')` returns an actual `HTMLDivElement`. Signals mutate it directly. No diffing pass, no reconciliation overhead for simple updates. Inspired by [Solid](https://www.solidjs.com/).
-- **Fine-grained reactivity.** Powered by [alien-signals](https://github.com/nicolo-ribaudo/alien-signals). When a signal changes, only the specific DOM text node or attribute that depends on it updates — not the whole component tree.
-- **Three entry points, one engine.** HTML Runtime (like Alpine — zero build step), `h()` hyperscript (like Preact), or JSX. All share the same signal graph. Pick the right tool for the job, upgrade without rewriting.
-- **CSP-safe capable.** The HTML Runtime includes a hand-written expression parser. The standard build enables `new Function()` as a fallback for complex expressions; the hardened build (`forma.hardened.js`) locks it off entirely for strict CSP environments.
-- **Islands over SPAs.** `activateIslands()` hydrates independent regions of server-rendered HTML. Each island is self-contained. Ship less JavaScript, keep server-rendered content instant.
+**The mental model:** "I write components the same way, pass props the same way, compose the same way — but I never think about re-renders, dependency arrays, or memoization. Signals just work."
 
-**What FormaJS is not:** It's not a framework with opinions about routing, data fetching, or state management patterns. It's a reactive DOM library. You bring the architecture.
+---
 
 ## Three Ways to Use FormaJS
 
-### 1. HTML Runtime (no build step)
+All three share the same signal graph and reactive engine. Pick the one that fits your project — or mix them.
+
+### 1. JSX
+
+The most familiar path for React and Solid developers. JSX compiles to `h()` calls — it's syntactic sugar, not a different system.
+
+Configure your bundler (TypeScript or Babel):
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "jsx": "react",
+    "jsxFactory": "h",
+    "jsxFragmentFactory": "Fragment"
+  }
+}
+```
+
+```tsx
+import { createSignal, h, Fragment, mount } from "@getforma/core";
+
+const [count, setCount] = createSignal(0);
+
+function Counter() {
+  return (
+    <>
+      <p>{() => `Count: ${count()}`}</p>
+      <button onClick={() => setCount((c) => c + 1)}>+1</button>
+    </>
+  );
+}
+
+mount(() => <Counter />, "#app");
+```
+
+Under the hood, the JSX above compiles to the exact `h()` calls shown in the next section. There's no JSX-specific runtime — it's the same function.
+
+### 2. Hyperscript — `h()`
+
+No JSX transform needed. Same reactive behavior, explicit function calls.
+
+```ts
+import { createSignal, h, mount } from "@getforma/core";
 
-Drop a script tag, write `data-*` attributes. Zero config, zero tooling.
+const [count, setCount] = createSignal(0);
+
+mount(
+  () =>
+    h(
+      "button",
+      { onClick: () => setCount((c) => c + 1) },
+      () => `Clicked ${count()} times`,
+    ),
+  "#app",
+);
+```
+
+See [The `h()` function](#the-h-function) below for the full signature and all call patterns.
+
+### 3. HTML Runtime (no build step)
+
+Drop a script tag, write `data-*` attributes. Zero config, zero tooling — works from a CDN.
 
 ```html
-<script src="https://unpkg.com/@getforma/core/dist/formajs-runtime.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@getforma/core@latest/dist/formajs-runtime.global.js"></script>
 
-<div data-forma-state='{"count": 0}'>
+<div data-forma-state='{ "count": 0 }'>
   <p data-text="{count}"></p>
   <button data-on:click="{count++}">+1</button>
   <button data-on:click="{count = 0}">Reset</button>
 </div>
 ```
 
-#### Supported Directives
+The expression parser is hand-written — no `eval()`, no `new Function()` by default. For strict CSP environments, use the hardened build:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@getforma/core@latest/dist/formajs-runtime-hardened.global.js"></script>
+```
+
+<details>
+<summary><strong>Full directive reference</strong></summary>
 
 | Directive | Description | Example |
-|-----------|-------------|---------|
+|---|---|---|
 | `data-forma-state` | Declare reactive state (JSON) | `data-forma-state='{"count": 0}'` |
 | `data-text` | Bind text content | `data-text="{count}"` |
 | `data-show` | Toggle visibility (display) | `data-show="{isOpen}"` |
-| `data-if` | Conditional render (add/remove from DOM) | `data-if="{loggedIn}"` |
+| `data-if` | Conditional render (add/remove DOM) | `data-if="{loggedIn}"` |
 | `data-model` | Two-way binding (inputs) | `data-model="{email}"` |
 | `data-on:event` | Event handler | `data-on:click="{count++}"` |
 | `data-class:name` | Conditional CSS class | `data-class:active="{isActive}"` |
 | `data-bind:attr` | Dynamic attribute | `data-bind:href="{url}"` |
-| `data-list` | List rendering with keyed reconciliation | `data-list="{items}"` |
+| `data-list` | List rendering (keyed reconciliation) | `data-list="{items}"` |
 | `data-computed` | Computed value | `data-computed="doubled = count * 2"` |
 | `data-persist` | Persist state to localStorage | `data-persist="{count}"` |
 | `data-fetch` | Fetch data from URL | `data-fetch="GET /api/items → items"` |
 | `data-transition:*` | Enter/leave CSS transitions | `data-transition:enter="fade-in"` |
 | `data-ref` | Register element for `$refs` access | `data-ref="myInput"` |
-| `$el` | Reference to the current DOM element | `data-on:click="{$el.classList.toggle('active')}"` |
-| `$dispatch` | Fire a CustomEvent (bubbles, crosses Shadow DOM) | `data-on:click="{$dispatch('selected', {id: itemId})}"` |
+| `$el` | Current DOM element | `data-on:click="{$el.classList.toggle('active')}"` |
+| `$dispatch` | Fire CustomEvent (bubbles, crosses Shadow DOM) | `data-on:click="{$dispatch('selected', {id})}"` |
 | `$refs` | Named element references | `data-on:click="{$refs.myInput.focus()}"` |
 
-CSP-safe expression parser — no `eval()` or `new Function()` by default. For strict CSP environments, use the hardened build:
+</details>
 
-```html
-<script src="https://unpkg.com/@getforma/core/dist/formajs-runtime-hardened.global.js"></script>
-```
+---
 
-### 2. Hyperscript — `h()`
+## The `h()` Function
 
-```bash
-npm install @getforma/core
+`h()` is the core of FormaJS rendering. Every component — whether written in JSX, hyperscript, or compiled from the HTML Runtime — resolves to `h()` calls that create real DOM elements.
+
+### Signature
+
+```ts
+h(tag, props?, ...children)
 ```
 
-```typescript
-import { createSignal, h, mount } from '@getforma/core';
+| Parameter | Type | Description |
+|---|---|---|
+| `tag` | `string \| Function` | An HTML tag name (`'div'`, `'button'`) or a component function (`Counter`) |
+| `props` | `object \| null` | Attributes, event handlers, and component props. Pass `null` or `{}` to skip. |
+| `children` | `string \| number \| () => string \| Node \| Array` | Zero or more children — static text, reactive functions, elements, or arrays of any of these. |
 
-const [count, setCount] = createSignal(0);
+### The key rule
 
-mount(() =>
-  h('button', { onClick: () => setCount(count() + 1) },
-    () => `Clicked ${count()} times`
-  ),
-  '#app'
-);
-```
+**If a child is a function, it's reactive.** FormaJS wraps it in an effect so the DOM text node or subtree updates automatically when signals inside it change. If a child is a plain string or number, it's static — rendered once, never touched again.
 
-### 3. JSX
+### Patterns
 
-Same `h()` function, JSX syntax. Configure your bundler:
+```ts
+// Static text child
+h("footer", { class: "text-sm" }, "Built with Forma")
 
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "jsx": "react",
-    "jsxFactory": "h",
-    "jsxFragmentFactory": "Fragment"
-  }
-}
-```
+// Reactive text child — updates when count() changes
+h("button", { onClick: fn }, () => `Count: ${count()}`)
 
-```tsx
-import { createSignal, h, Fragment, mount } from '@getforma/core';
+// Multiple children
+h("div", { class: "card" },
+  h("h2", null, "Title"),
+  h("p", null, "Body text"),
+  h("button", { onClick: fn }, "Click"),
+)
 
-const [count, setCount] = createSignal(0);
+// Children as an array (useful for dynamic lists)
+h("ul", null, items.map(item => h("li", null, item.name)))
 
-function Counter() {
-  return (
-    <>
-      <p>{() => `Count: ${count()}`}</p>
-      <button onClick={() => setCount(count() + 1)}>+1</button>
-    </>
-  );
-}
+// No props, just children
+h("p", null, "Hello world")
+
+// Component function with props
+h(Counter, { initial: 5 })
 
-mount(() => <Counter />, '#app');
+// Nested reactive children
+h("div", null,
+  () => showHeader() ? h("h1", null, "Welcome") : null,
+  h("p", null, () => `You have ${count()} items`),
+)
 ```
 
-## CDN Usage
+### JSX equivalence
 
-### Script tag (IIFE — auto-initializes)
+JSX is syntactic sugar that compiles to `h()` calls. These are identical:
 
-```html
-<!-- unpkg -->
-<script src="https://unpkg.com/@getforma/core@1.0.0/dist/formajs-runtime.global.js"></script>
+```tsx
+// JSX
+<button class="btn" onClick={() => setCount((c) => c + 1)}>
+  {() => `Count: ${count()}`}
+</button>
 
-<!-- jsDelivr (faster globally) -->
-<script src="https://cdn.jsdelivr.net/npm/@getforma/core@1.0.0/dist/formajs-runtime.global.js"></script>
+// h()
+h("button", { class: "btn", onClick: () => setCount((c) => c + 1) },
+  () => `Count: ${count()}`
+)
 ```
 
-### ESM import (no bundler, modern browsers)
+---
 
-```html
-<script type="module">
-  import { createSignal, h, mount } from 'https://cdn.jsdelivr.net/npm/@getforma/core@1.0.0/dist/index.js';
+## Why FormaJS?
 
-  const [count, setCount] = createSignal(0);
-  mount(() => h('button', { onClick: () => setCount(count() + 1) }, () => `${count()}`), '#app');
-</script>
-```
+Most UI libraries force a choice: simple but limited (Alpine, htmx), or powerful but heavy (React, Vue, Svelte). FormaJS gives you a single reactive core that scales from a CDN script tag to a compiled Rust SSR pipeline.
 
-### All CDN builds
+**Components run once.** No virtual DOM, no diffing, no reconciliation overhead. `h('div')` returns an actual `HTMLDivElement`. When a signal changes, only the specific text node or attribute that reads it updates — not the component, not the tree.
 
-| Build | Filename |
-|-------|----------|
-| **Standard** (recommended) | `formajs-runtime.global.js` |
-| **CSP-safe** (no `new Function`) | `formajs-runtime-hardened.global.js` |
-| Standard (short alias) | `forma-runtime.js` |
-| CSP-safe (short alias) | `forma-runtime-csp.js` |
+**Fine-grained reactivity.** Powered by [alien-signals](https://github.com/nicolo-ribaudo/alien-signals) 3.x. The signal graph tracks dependencies automatically. No dependency arrays, no stale closures, no `useCallback` / `useMemo` ceremony.
+
+**Three entry points, one engine.** HTML Runtime (like Alpine — zero build step), `h()` hyperscript (like Preact), or JSX (like React/Solid). All share the same signal graph. Start with a CDN script tag, graduate to a full build pipeline without rewriting.
+
+**Islands over SPAs.** `activateIslands()` hydrates independent regions of server-rendered HTML. Each island is self-contained with error isolation, deferred hydration triggers (`visible`, `idle`, `interaction`), and disposal for module swaps.
+
+**CSP-safe.** The HTML Runtime includes a hand-written expression parser — no `eval()`, no `new Function()`. The hardened build locks it off entirely, with zero `new Function` in the dist (verified by dead code elimination).
+
+**What FormaJS is not:** It's not a framework with opinions about routing, data fetching, or state management. It's a reactive DOM library. You bring the architecture.
+
+---
+
+## The Rust Compiler (Optional)
+
+Everything above works without the Rust compiler. You can build a complete application with just `npm install @getforma/core` and a bundler. The compiler is an **optimization layer** — you add it when performance and deployment constraints demand it.
+
+### What the compiler does
+
+| Without compiler | With compiler |
+|---|---|
+| `h()` calls create DOM elements at runtime | `h()` calls are pre-compiled to `template()` + `cloneNode()` for faster initial render |
+| SSR requires Node.js (`renderToString`) | SSR runs natively in Rust via the FMIR binary walker — no JS runtime on the server |
+| Standard JS bundle shipped to the client | Components compile to FMIR (Forma Module IR), a compact binary format sent over the wire |
+| Islands hydrate from HTML + JS | Islands hydrate from FMIR binary — smaller payload, faster parse |
+
+### When to add it
+
+You don't need the compiler to get started, prototype, or even ship to production. Add it when:
 
-Available from both `unpkg.com/@getforma/core@VERSION/dist/` and `cdn.jsdelivr.net/npm/@getforma/core@VERSION/dist/`.
+- **SSR without Node.js** — your backend is Rust/Axum and you don't want a Node.js sidecar just for rendering.
+- **Faster initial render** — pre-compiled templates skip the `h()` → `createElement` path and go straight to `cloneNode()`.
+- **Smaller payloads** — FMIR binary is more compact than the equivalent JavaScript for complex component trees.
+- **The full Forma stack** — `@getforma/compiler` → FMIR → `forma-ir` (Rust parser) → `forma-server` (Axum SSR) gives you a complete pipeline at ~$18/month deployment cost.
 
-For production, always pin the version (e.g., `@1.0.0`). Unversioned URLs resolve to latest.
+### Architecture
 
-> The CSP build uses a hand-written expression parser and never calls `new Function`.
-> It supports most common patterns. See [examples/csp](./examples/csp) for a working demo.
+```
+TypeScript/JSX components
+        ↓
+  @getforma/compiler        (TS → FMIR binary)
+        ↓
+  forma-ir                  (Rust: parse + walk FMIR)
+        ↓
+  forma-server              (Rust/Axum: SSR + asset serving + CSP)
+        ↓
+  HTML response             (server-rendered, islands hydrate on client)
+```
+
+All entry points — JSX, `h()`, and the HTML Runtime — work both with and without the compiler:
+
+|  | Without Compiler | With Compiler |
+|---|---|---|
+| HTML Runtime | `data-*` directives | + SSR from IR walker |
+| `h()` hyperscript | `createSignal` + `h()` | + compiled templates |
+| JSX | `createSignal` + JSX | + compiled templates + SSR |
+| Islands | `activateIslands()` | + FMIR hydration |
+
+---
 
 ## Core API
 
 ### Signals
 
-```typescript
-import { createSignal, createEffect, createComputed, batch } from '@getforma/core';
+```ts
+import { createSignal, createEffect, createComputed, batch } from "@getforma/core";
 
 const [count, setCount] = createSignal(0);
 const doubled = createComputed(() => count() * 2);
 
-createEffect(() => console.log('count:', count()));
+createEffect(() => console.log("count:", count()));
 
 batch(() => {
   setCount(1);
@@ -219,25 +372,21 @@ batch(() => {
 });
 ```
 
-#### Custom Equality
-
-Skip updates when the new value is equal to the current value:
+**Custom equality** — skip updates when the value hasn't meaningfully changed:
 
-```typescript
+```ts
 const [pos, setPos] = createSignal(
   { x: 0, y: 0 },
   { equals: (a, b) => a.x === b.x && a.y === b.y },
 );
 
-setPos({ x: 0, y: 0 }); // skipped — values are equal
-setPos({ x: 1, y: 0 }); // applied — values differ
+setPos({ x: 0, y: 0 }); // skipped — equal
+setPos({ x: 1, y: 0 }); // applied — different
 ```
 
-#### Computed with Previous Value
-
-The computed getter receives the previous value for efficient diffing:
+**Computed with previous value** — the getter receives the previous result:
 
-```typescript
+```ts
 const changes = createComputed((prev) => {
   const current = items();
   if (prev) console.log(`${prev.length} → ${current.length} items`);
@@ -245,218 +394,217 @@ const changes = createComputed((prev) => {
 });
 ```
 
-#### Reactive Introspection
+**Reactive introspection** — type guards and utilities from alien-signals 3.x:
 
-Type guards and utilities from alien-signals 3.x:
+```ts
+import { isSignal, isComputed, getBatchDepth, trigger } from "@getforma/core";
 
-```typescript
-import { isSignal, isComputed, getBatchDepth, trigger } from '@getforma/core';
-
-isSignal(count);           // true — is this a signal getter?
-isComputed(doubled);       // true — is this a computed value?
-getBatchDepth();           // 0 outside batch, 1+ inside
-trigger(doubled);          // force recomputation even if deps unchanged
+isSignal(count);       // true
+isComputed(doubled);   // true
+getBatchDepth();       // 0 outside batch, 1+ inside
+trigger(doubled);      // force recomputation
 ```
 
 ### Conditional Rendering
 
-```typescript
-import { createSignal, createShow, createSwitch, h } from '@getforma/core';
+```ts
+import { createSignal, createShow, createSwitch, h } from "@getforma/core";
 
 const [loggedIn, setLoggedIn] = createSignal(false);
 
-// createShow — toggle between two branches
-createShow(loggedIn,
-  () => h('p', null, 'Welcome back'),
-  () => h('p', null, 'Please sign in'),
+// Two branches
+createShow(
+  loggedIn,
+  () => h("p", null, "Welcome back"),
+  () => h("p", null, "Please sign in"),
 );
 
-// createSwitch — multi-branch with caching
-const [view, setView] = createSignal('home');
-createSwitch(view, [
-  { match: 'home', render: () => h('div', null, 'Home') },
-  { match: 'settings', render: () => h('div', null, 'Settings') },
-], () => h('div', null, '404 Not Found'));
+// Multi-branch with caching
+const [view, setView] = createSignal("home");
+
+createSwitch(
+  view,
+  [
+    { match: "home", render: () => h("div", null, "Home") },
+    { match: "settings", render: () => h("div", null, "Settings") },
+  ],
+  () => h("div", null, "404 Not Found"),
+);
 ```
 
 ### List Rendering
 
-```typescript
-import { createSignal, createList, h } from '@getforma/core';
+```ts
+import { createSignal, createList, h } from "@getforma/core";
 
 const [items, setItems] = createSignal([
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' },
+  { id: 1, name: "Alice" },
+  { id: 2, name: "Bob" },
 ]);
 
 createList(
   items,
-  (item) => item.id,  // key function
-  (item) => h('li', null, item.name),
+  (item) => item.id,
+  (item) => h("li", null, item.name),
 );
 ```
 
-### Store (deep reactivity)
+### Store (Deep Reactivity)
 
-```typescript
-import { createStore } from '@getforma/core';
+```ts
+import { createStore } from "@getforma/core";
 
 const [state, setState] = createStore({
-  user: { name: 'Alice', prefs: { theme: 'dark' } },
+  user: { name: "Alice", prefs: { theme: "dark" } },
   items: [1, 2, 3],
 });
 
 // Read reactively — tracked at the exact property path
-state.user.name;        // 'Alice'
-state.items[0];         // 1
+state.user.name;   // "Alice"
+state.items[0];    // 1
 
-// Setter API — partial object merge (batched)
-setState({ user: { ...state.user, name: 'Bob' } });
-setState(prev => ({ items: [...prev.items, 4] }));
+// Setter API — partial merge
+setState({ user: { ...state.user, name: "Bob" } });
+setState((prev) => ({ items: [...prev.items, 4] }));
 
-// Or mutate directly via proxy — only affected subscribers update
-state.user.name = 'Bob';          // only "user.name" subscribers notified
-state.items.push(4);              // array mutation batched automatically
+// Or mutate directly — only affected subscribers update
+state.user.name = "Bob";
+state.items.push(4);
 ```
 
-### Components
+> **Note:** `Object.keys(state)`, `for...in`, and spread (`{...state}`) are NOT reactive. Use signals or explicit arrays for collections that need to react to membership changes.
 
-```typescript
-import { defineComponent, onMount, onUnmount, h } from '@getforma/core';
+### Components & Lifecycle
+
+```ts
+import { createSignal, defineComponent, onMount, onUnmount, h } from "@getforma/core";
 
 const Timer = defineComponent(() => {
   const [seconds, setSeconds] = createSignal(0);
 
   onMount(() => {
-    const id = setInterval(() => setSeconds(s => s + 1), 1000);
+    const id = setInterval(() => setSeconds((s) => s + 1), 1000);
     return () => clearInterval(id); // cleanup on unmount
   });
 
-  return h('span', null, () => `${seconds()}s`);
+  return h("span", null, () => `${seconds()}s`);
 });
 
 document.body.appendChild(Timer());
 ```
 
-#### Lifecycle: `onMount` vs `onUnmount`
-
-- **`onMount(fn)`** — runs after the component's DOM is created. If `fn` returns a function, that function is automatically registered as an unmount callback.
-- **`onUnmount(fn)`** — explicitly registers a cleanup function that runs when the component is disposed.
-
-Both mechanisms feed into the same cleanup queue — the `onMount` return shorthand is convenience for the common pattern of setting up and tearing down in one place:
+`onMount(fn)` runs after DOM creation. If `fn` returns a function, it registers as an unmount callback. `onUnmount(fn)` explicitly registers cleanup. Both feed the same cleanup queue:
 
-```typescript
+```ts
 // These are equivalent:
 onMount(() => {
   const id = setInterval(tick, 1000);
   return () => clearInterval(id);
 });
 
-// vs.
 onMount(() => {
   const id = setInterval(tick, 1000);
   onUnmount(() => clearInterval(id));
 });
 ```
 
-### Error Handling
-
-**`mount()` fails fast.** If the container selector doesn't match any element, it throws:
-
-```typescript
-mount(() => h('p', null, 'hello'), '#nonexistent');
-// Error: mount: container not found — "#nonexistent"
-```
+### Context (Dependency Injection)
 
-**Global error handler.** Register a handler for errors in effects and lifecycle callbacks:
+```ts
+import { createContext, provide, inject } from "@getforma/core";
 
-```typescript
-import { onError } from '@getforma/core';
+const ThemeCtx = createContext("light");
 
-onError((error, info) => {
-  console.error(`[${info?.source}]`, error);
-});
+provide(ThemeCtx, "dark");
+const theme = inject(ThemeCtx); // "dark"
 ```
 
-**Error boundaries.** Catch rendering errors and display fallback UI with a retry option:
+### Reducer
 
-```typescript
-import { createErrorBoundary, h } from '@getforma/core';
+```ts
+import { createReducer } from "@getforma/core";
 
-createErrorBoundary(
-  () => h(UnstableComponent),
-  (error, retry) => h('div', null,
-    h('p', null, `Something went wrong: ${error.message}`),
-    h('button', { onClick: retry }, 'Retry'),
-  ),
+const [state, dispatch] = createReducer(
+  (state, action) => {
+    switch (action.type) {
+      case "INCREMENT": return { count: state.count + 1 };
+      case "DECREMENT": return { count: state.count - 1 };
+      default: return state;
+    }
+  },
+  { count: 0 },
 );
+
+dispatch({ type: "INCREMENT" }); // state() === { count: 1 }
 ```
 
-### Context (Dependency Injection)
+### History (Undo / Redo)
+
+```ts
+import { createHistory } from "@getforma/core";
 
-```typescript
-import { createContext, provide, inject } from '@getforma/core';
+const [state, setState, { undo, redo, canUndo, canRedo }] = createHistory({ text: "" });
 
-const ThemeCtx = createContext('light');
+setState({ text: "hello" });
+setState({ text: "hello world" });
 
-provide(ThemeCtx, 'dark');
-const theme = inject(ThemeCtx); // 'dark'
+undo();     // state.text === "hello"
+canUndo();  // true
+redo();     // state.text === "hello world"
 ```
 
-### History (undo/redo)
+### Error Handling
+
+`mount()` fails fast — if the selector doesn't match, it throws:
 
-```typescript
-import { createHistory } from '@getforma/core';
+```ts
+mount(() => h("p", null, "hello"), "#nonexistent");
+// Error: mount: container not found — "#nonexistent"
+```
 
-const [state, setState, { undo, redo, canUndo, canRedo }] = createHistory({ text: '' });
+**Global error handler** for effects and lifecycle callbacks:
 
-setState({ text: 'hello' });
-setState({ text: 'hello world' });
+```ts
+import { onError } from "@getforma/core";
 
-undo();              // state.text === 'hello'
-canUndo();           // true
-redo();              // state.text === 'hello world'
+onError((error, info) => {
+  console.error(`[${info?.source}]`, error);
+});
 ```
 
-### Reducer
+**Error boundaries** — catch rendering errors with fallback UI:
 
-```typescript
-import { createReducer } from '@getforma/core';
+```ts
+import { createErrorBoundary, h } from "@getforma/core";
 
-const [state, dispatch] = createReducer(
-  (state, action) => {
-    switch (action.type) {
-      case 'INCREMENT': return { count: state.count + 1 };
-      case 'DECREMENT': return { count: state.count - 1 };
-      default: return state;
-    }
-  },
-  { count: 0 },
+createErrorBoundary(
+  () => h(UnstableComponent),
+  (error, retry) =>
+    h("div", null,
+      h("p", null, `Something went wrong: ${error.message}`),
+      h("button", { onClick: retry }, "Retry"),
+    ),
 );
-
-dispatch({ type: 'INCREMENT' }); // state() === { count: 1 }
 ```
 
+---
+
 ## Islands Architecture
 
-For server-rendered HTML, activate independent interactive regions. Each island callback receives the root DOM element and parsed props, then returns a component tree — the same `h()` calls you'd use for client-side rendering. The hydration system walks the descriptor tree against the existing SSR DOM, attaching event handlers and reactive bindings without recreating elements.
+Hydrate independent interactive regions of server-rendered HTML. Each island callback receives the root element and parsed props, then returns a component tree. The hydration system walks the tree against existing SSR DOM, attaching handlers and reactive bindings without recreating elements.
 
-```typescript
-import { activateIslands, createSignal, h } from '@getforma/core';
+```ts
+import { activateIslands, createSignal, h } from "@getforma/core";
 
 activateIslands({
   Counter: (el, props) => {
     const [count, setCount] = createSignal(props?.initial ?? 0);
 
-    // el is the island's root HTMLElement — useful for layout measurement,
-    // focus management, CSS classes, or reading extra data-* attributes.
-    el.classList.add('is-hydrated');
+    el.classList.add("is-hydrated");
 
-    // Return the same tree shape as the SSR output.
-    // Hydration matches this against existing DOM — no elements are created.
-    return h('div', null,
-      h('span', null, () => String(count())),
-      h('button', { onClick: () => setCount(c => c + 1) }, '+1'),
+    return h("div", null,
+      h("span", null, () => String(count())),
+      h("button", { onClick: () => setCount((c) => c + 1) }, "+1"),
     );
   },
 });
@@ -470,135 +618,169 @@ activateIslands({
 </div>
 ```
 
-Each island is activated inside its own `createRoot` scope with error isolation — a broken island never takes down its siblings.
+Each island runs in its own `createRoot` scope with error isolation — a broken island never takes down its siblings.
 
 ### Hydration Triggers
 
 Control when an island hydrates via `data-forma-hydrate`:
 
 | Trigger | When it hydrates | Use case |
-|---------|-----------------|----------|
-| `load` (default) | Immediately on page load | Above-the-fold interactive content |
+|---|---|---|
+| `load` (default) | Immediately on page load | Above-the-fold content |
 | `visible` | When island enters viewport | Below-the-fold components |
-| `idle` | During browser idle time (`requestIdleCallback`) | Non-critical functionality |
-| `interaction` | On first `pointerdown` or `focusin` | Skeleton+skin pattern |
+| `idle` | During browser idle time | Non-critical functionality |
+| `interaction` | On first `pointerdown` or `focusin` | Skeleton + skin pattern |
 
 ```html
 <div data-forma-island="1" data-forma-component="Comments" data-forma-hydrate="visible">
-  <!-- Only loads JS when scrolled into view -->
+  <!-- JS loads only when scrolled into view -->
 </div>
 ```
 
 ### Island Disposal
 
-When swapping module content (e.g., inside `<forma-stage>` Shadow DOM), dispose islands to prevent leaked effects and listeners:
+When swapping content (e.g., inside `<forma-stage>` Shadow DOM), dispose islands to prevent leaked effects:
 
-```typescript
-import { deactivateIsland, deactivateAllIslands } from '@getforma/core';
+```ts
+import { deactivateIsland, deactivateAllIslands } from "@getforma/core";
 
-// Dispose all active islands under a root
 deactivateAllIslands(shadowRoot);
-
-// Or dispose a single island
 deactivateIsland(islandElement);
 ```
 
+---
+
+## CDN Builds
+
+### Script tag (IIFE — auto-initializes)
+
+```html
+<!-- jsDelivr (recommended) -->
+<script src="https://cdn.jsdelivr.net/npm/@getforma/core@1.0.1/dist/formajs-runtime.global.js"></script>
+
+<!-- unpkg -->
+<script src="https://unpkg.com/@getforma/core@1.0.1/dist/formajs-runtime.global.js"></script>
+```
+
+### ESM import (modern browsers, no bundler)
+
+```html
+<script type="module">
+  import { createSignal, h, mount } from "https://cdn.jsdelivr.net/npm/@getforma/core@1.0.1/dist/index.js";
+
+  const [count, setCount] = createSignal(0);
+  mount(() => h("button", { onClick: () => setCount((c) => c + 1) }, () => `${count()}`), "#app");
+</script>
+```
+
+### All builds
+
+| Build | Filename |
+|---|---|
+| Standard (recommended) | `formajs-runtime.global.js` |
+| CSP-safe (no `new Function`) | `formajs-runtime-hardened.global.js` |
+| Standard (short alias) | `forma-runtime.js` |
+| CSP-safe (short alias) | `forma-runtime-csp.js` |
+
+Available from `unpkg.com/@getforma/core@VERSION/dist/` and `cdn.jsdelivr.net/npm/@getforma/core@VERSION/dist/`.
+
+---
+
 ## Subpath Exports
 
-The main entry point (`@getforma/core`) has **zero network code** — no `fetch`, no WebSocket, no `process.env`. Network-capable modules are separate subpath imports.
+The main entry point (`@getforma/core`) has **zero network code** — no fetch, no WebSocket, no `process.env`. Network-capable modules are separate imports:
 
 | Import | Description |
-|--------|-------------|
-| `@getforma/core` | Signals, `h()`, `mount()`, lists, stores, components, islands, events, DOM utils |
+|---|---|
+| `@getforma/core` | Signals, `h()`, mount, lists, stores, components, islands, events, DOM utils |
 | `@getforma/core/http` | `createFetch`, `fetchJSON`, `createSSE`, `createWebSocket` |
 | `@getforma/core/storage` | `createLocalStorage`, `createSessionStorage`, `createIndexedDB` |
 | `@getforma/core/server` | `createAction`, `$$serverFunction`, `handleRPC`, `createRPCMiddleware` |
 | `@getforma/core/runtime` | HTML Runtime — `initRuntime()`, `mount()`, `unmount()` |
-| `@getforma/core/runtime/global` | HTML Runtime global build (IIFE, for `<script>` tags) |
 | `@getforma/core/runtime-hardened` | Runtime with `new Function()` locked off (strict CSP) |
-| `@getforma/core/runtime-csp` | Alias for `runtime-hardened` (CSP-safe build) |
-| `@getforma/core/runtime-csp/global` | CSP-safe global build (IIFE, for `<script>` tags) |
 | `@getforma/core/ssr` | Server-side rendering — `renderToString()`, `renderToStream()` |
 | `@getforma/core/tc39` | TC39-compatible `Signal.State` and `Signal.Computed` classes |
 
-```typescript
-// Core (zero network code)
-import { createSignal, h, mount, createStore } from '@getforma/core';
+```ts
+// Core — zero network code
+import { createSignal, h, mount, createStore } from "@getforma/core";
 
-// HTTP (only if needed)
-import { createFetch, createSSE } from '@getforma/core/http';
+// HTTP — only when needed
+import { createFetch, createSSE } from "@getforma/core/http";
 
-// Storage (only if needed)
-import { createLocalStorage } from '@getforma/core/storage';
+// Storage — only when needed
+import { createLocalStorage } from "@getforma/core/storage";
 
-// Server (only if needed)
-import { createAction, $$serverFunction } from '@getforma/core/server';
+// Server — only when needed
+import { createAction, $$serverFunction } from "@getforma/core/server";
 ```
 
-## Examples
+---
 
-See the [`examples/`](./examples) directory:
+## How Is This Different from Solid?
 
-- **counter** — minimal `h()` counter
-- **counter-jsx** — same counter with JSX syntax
-- **csp** — CSP-safe runtime with strict Content-Security-Policy meta tag
-- **todo** — todo list with `createList` and keyed reconciliation
-- **data-table** — sortable table with `createList`
+FormaJS shares Solid's core insight — fine-grained signals updating the real DOM without a virtual DOM. If you know Solid, you'll feel at home.
 
-## How Is This Different from Solid?
+The differences are in scope and delivery: FormaJS adds built-in islands hydration without a meta-framework, CSP compliance without a build step, three entry points (CDN, hyperscript, JSX) sharing one signal graph, and a Rust SSR path that eliminates Node.js from the server. Solid gives you a mature JavaScript ecosystem with routing, a meta-framework (SolidStart), devtools, and community component libraries.
 
-FormaJS shares Solid's core insight — fine-grained signals updating the real DOM without a virtual DOM. If you know Solid, you'll feel at home. The differences are in scope and delivery:
+**Choose FormaJS** when you want islands baked in, CSP safety out of the box, a Rust backend without a Node.js sidecar, or a CDN-first starting point that scales to a full compiled pipeline.
 
-| | Solid | FormaJS |
-|-|-------|---------|
-| **Build requirement** | Always needs a compiler (JSX transform) | CDN runtime works with zero build step; bundler is optional |
-| **Entry points** | JSX-first | HTML Runtime (`data-*` attributes), `h()` hyperscript, or JSX |
-| **CSP** | Relies on compiler output | Hand-written expression parser; hardened build has no `new Function()` |
-| **Islands** | Via [solid-start](https://start.solidjs.com/) meta-framework | Built-in `activateIslands()` — no meta-framework needed |
-| **Ecosystem** | Mature (router, meta-framework, devtools) | Minimal — reactive core only, you bring the architecture |
-| **SSR runtime** | Node.js required | Node.js via `renderToString`, or Rust walker (no JS runtime on the server) |
-| **Size** | ~7KB | ~15KB (includes runtime parser, stores, SSR) |
+**Choose Solid** when you want a mature JS ecosystem, SolidStart for full-stack JS, community devtools, and your backend is already Node.js.
 
-**When to choose FormaJS:** You want islands hydration built into the library, not bolted on through a meta-framework. You need CSP compliance without a build step. You want three entry points (CDN, hyperscript, JSX) sharing one signal graph. Or you're building on a Rust backend and want your frontend reactive layer to integrate natively with the server stack.
+> FormaJS is the reactive layer of the [Forma stack](https://getforma.dev). The full pipeline compiles components to FMIR binary, renders them in Rust via `forma-ir`, and serves pages through `forma-server` — SSR without Node.js, binary IR over the wire, deployed for ~$18/month.
 
-**When to choose Solid:** You want a mature JavaScript ecosystem with routing, SSR meta-framework (SolidStart), devtools, and community-built component libraries. Your backend is Node.js and you want SSR in the same language as your frontend.
+---
 
-> FormaJS is the reactive layer of the [Forma stack](https://getforma.dev). The full pipeline compiles components to a binary IR (FMIR), renders them in Rust via `forma-ir`, and serves pages through `forma-server` — SSR without Node.js, binary IR over the wire, deployed for ~$18/month.
+## Examples
 
-## Stability
+See the [`examples/`](./examples) directory:
+
+| Example | Description |
+|---|---|
+| **counter** | Minimal `h()` counter |
+| **counter-jsx** | Same counter with JSX syntax |
+| **csp** | CSP-safe runtime with strict `Content-Security-Policy` |
+| **todo** | Todo list with `createList` and keyed reconciliation |
+| **data-table** | Sortable table with `createList` |
+
+---
 
-Some features are more battle-tested than others:
+## Stability
 
 | Feature | Status | Notes |
-|---------|--------|-------|
-| Signals (`createSignal`, `createEffect`, `createComputed`, `batch`) | **Stable** | Core primitive, well-tested. Custom `equals` option supported. |
+|---|---|---|
+| Signals (`createSignal`, `createEffect`, `createComputed`, `batch`) | **Stable** | Core primitive. Custom `equals` supported. |
 | Reactive introspection (`isSignal`, `isComputed`, `trigger`, `getBatchDepth`) | **Stable** | alien-signals 3.x type guards |
-| `h()` / JSX rendering | **Stable** | |
+| `h()` / JSX rendering | **Stable** | Function components supported |
 | `mount()`, `createShow`, `createSwitch`, `createList` | **Stable** | |
-| HTML Runtime (`data-*` directives) | **Stable** | Expression parser covers common patterns |
-| CSP-hardened runtime | **Stable** | No `new Function()`, tested with strict CSP headers |
+| HTML Runtime (`data-*` directives) | **Stable** | CSP-safe expression parser |
+| CSP-hardened runtime | **Stable** | Zero `new Function()` in dist |
 | `createStore` (deep reactivity) | **Stable** | |
 | Components (`defineComponent`, lifecycle) | **Stable** | |
 | Context (`createContext`, `provide`, `inject`) | **Stable** | |
 | Islands (`activateIslands`, disposal, triggers) | **Stable** | 10 activation + 88 hydration + 10 trigger tests |
 | `createHistory` (undo/redo) | **Stable** | |
-| `createReducer` | **Stable** | 8 tests |
-| `data-fetch`, `data-transition:*` | **Stable** | Fully implemented in HTML Runtime |
+| `createReducer` | **Stable** | |
+| `data-fetch`, `data-transition:*`, `data-ref` | **Stable** | |
 | SSR (`renderToString`, `renderToStream`) | **Beta** | Functional, API may evolve |
-| TC39 Signals compat (`Signal.State`, `Signal.Computed`) | **Beta** | 9 tests, but tracks an evolving TC39 proposal |
+| TC39 Signals compat (`Signal.State`, `Signal.Computed`) | **Beta** | Tracks an evolving TC39 proposal |
+
+---
 
 ## Ecosystem
 
-FormaJS is the reactive frontend layer of a full-stack Rust + TypeScript framework. The pipeline flows: TypeScript components → `@getforma/compiler` → FMIR binary → `forma-ir` (parse) → `forma-server` (render) → Axum HTTP response.
+FormaJS is the reactive frontend layer of a full-stack Rust + TypeScript framework.
 
 | Package | Language | Description |
-|---------|----------|-------------|
+|---|---|---|
 | [@getforma/core](https://www.npmjs.com/package/@getforma/core) | TypeScript | This library — reactive DOM, signals, islands, SSR hydration |
 | [@getforma/compiler](https://github.com/getforma-dev/forma-tools) | TypeScript | TypeScript-to-FMIR compiler, Vite plugin, esbuild SSR plugin |
 | [@getforma/build](https://github.com/getforma-dev/forma-tools) | TypeScript | esbuild pipeline with content hashing, compression, manifest |
 | [@getforma/create-app](https://github.com/getforma-dev/create-forma-app) | TypeScript | `npx @getforma/create-app` — scaffold a new Forma project |
 | [forma-ir](https://crates.io/crates/forma-ir) | Rust | FMIR binary format: parser, walker, WASM exports |
-| [forma-server](https://crates.io/crates/forma-server) | Rust | Axum middleware for SSR page rendering, asset serving, CSP |
+| [forma-server](https://crates.io/crates/forma-server) | Rust | Axum middleware for SSR, asset serving, CSP |
+
+---
 
 ## License