rask-ui 0.2.0 → 0.2.1

package/README.md

@@ -1,263 +1,1001 @@
 # RASK
 
-A lightweight reactive component library built on [Snabbdom](https://github.com/snabbdom/snabbdom) with MobX-inspired reactivity.
+<p align="center">
+  <img src="logo.png" alt="Logo" width="200">
+</p>
 
-## Component and Element Lifecycle
+A lightweight reactive component library that combines the simplicity of observable state management with the full power of a virtual DOM reconciler.
 
-### Overview
+```bash
+npm install rask-ui
+```
+
+## The Problem with Modern UI Frameworks
+
+Modern UI frameworks present developers with a fundamental tradeoff between state management and UI expression:
+
+### React: Great UI, Complex State
+
+```tsx
+function MyApp() {
+  const [count, setCount] = useState(0);
+
+  return <h1 onClick={() => setCount(count + 1)}>Count is {count}</h1>;
+}
+```
+
+React excels at UI composition - you simply use the language to create dynamic UIs. However, including state management within the reconciler causes significant mental strain:
+
+- Understanding closure captures and stale state
+- Managing dependency arrays in hooks
+- Dealing with re-render cascades
+- Optimizing with `useMemo`, `useCallback`, and `memo`
+- Wrestling with the "rules of hooks"
+
+### Solid: Simple Reactivity, Hidden Complexity
 
-RASK uses a **host-based architecture** where each component creates a host DOM element (`<component>` tag with `display: contents`) and manages its own virtual DOM independently. Components track their direct children for efficient cleanup detection.
+```tsx
+function MyApp() {
+  const [count, setCount] = createSignal(0);
+
+  return <h1 onClick={() => setCount(count() + 1)}>Count is {count()}</h1>;
+}
+```
+
+Solid offers a simpler mental model with fine-grained reactivity. Updates don't happen by calling the component function again, but in "hidden" parts of expressions in the UI. However:
 
-### Component Lifecycle Phases
+- Requires understanding special compiler transformations
+- Special components for expressing dynamic UIs (`<Show>`, `<For>`, etc.)
+- Function call syntax for accessing values: `count()`
 
-#### 1. Component Creation
+### RASK: Best of Both Worlds
+
+```tsx
+function MyApp() {
+  const state = createState({ count: 0 });
+
+  return () => <h1 onClick={() => state.count++}>Count is {state.count}</h1>;
+}
+```
+
+RASK gives you:
+
+- **Predictable observable state management** - No reconciler interference, just plain reactivity
+- **Full reconciler power** - Express complex UIs naturally with components
+- **No special syntax** - Access state properties directly, no function calls
+- **No compiler magic** - Plain JavaScript/TypeScript
+- **Simple mental model** - State updates trigger only affected components
+
+## Getting Started
+
+### Installation
+
+```bash
+npm install rask-ui
+```
+
+### Basic Example
+
+```tsx
+import { createState, render } from "rask-ui";
+
+function Counter() {
+  const state = createState({ count: 0 });
+
+  return () => (
+    <div>
+      <h1>Count: {state.count}</h1>
+      <button onClick={() => state.count++}>Increment</button>
+      <button onClick={() => state.count--}>Decrement</button>
+    </div>
+  );
+}
+
+render(<Counter />, document.getElementById("app")!);
+```
+
+### Key Concepts
+
+#### 1. Component Structure
+
+Components in RASK have two phases:
 
 ```tsx
 function MyComponent(props) {
-  // Setup Phase - runs ONCE per component instance
+  // SETUP PHASE - Runs once when component is created
+  const state = createState({ value: props.initial });
+
+  onMount(() => {
+    console.log("Component mounted!");
+  });
+
+  // RENDER PHASE - Returns a function that runs on every update
+  return () => (
+    <div>
+      <p>{state.value}</p>
+      <button onClick={() => state.value++}>Update</button>
+    </div>
+  );
+}
+```
+
+The setup phase runs once, while the render function runs whenever reactive dependencies change.
+
+#### 2. Reactive State
+
+State objects are automatically reactive. Any property access during render is tracked:
+
+```tsx
+function TodoList() {
+  const state = createState({
+    todos: [],
+    filter: "all",
+  });
+
+  const addTodo = (text) => {
+    state.todos.push({ id: Date.now(), text, done: false });
+  };
+
+  return () => (
+    <div>
+      <input
+        value={state.filter}
+        onInput={(e) => (state.filter = e.target.value)}
+      />
+      <ul>
+        {state.todos
+          .filter(
+            (todo) => state.filter === "all" || todo.text.includes(state.filter)
+          )
+          .map((todo) => (
+            <li key={todo.id}>{todo.text}</li>
+          ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+#### 3. Props are Reactive Too
+
+Props passed to components are automatically reactive:
+
+```tsx
+function Child(props) {
+  // props is reactive - accessing props.value tracks the dependency
+  return () => <div>{props.value}</div>;
+}
+
+function Parent() {
+  const state = createState({ count: 0 });
+
+  return () => (
+    <div>
+      <Child value={state.count} />
+      <button onClick={() => state.count++}>Update</button>
+    </div>
+  );
+}
+```
+
+When `state.count` changes in Parent, only Child re-renders because it accesses `props.value`.
+
+### Important: Do Not Destructure Reactive Objects
+
+**RASK follows the same rule as Solid.js**: Never destructure reactive objects (state, props, context values, async, query, mutation). Destructuring extracts plain values and breaks reactivity.
+
+```tsx
+// ❌ BAD - Destructuring breaks reactivity
+function Counter(props) {
+  const state = createState({ count: 0 });
+  const { count } = state; // Extracts plain value!
+
+  return () => <div>{count}</div>; // Won't update!
+}
+
+function Child({ value, name }) {
+  // Destructuring props!
+  return () => (
+    <div>
+      {value} {name}
+    </div>
+  ); // Won't update!
+}
+
+// ✅ GOOD - Access properties directly in render
+function Counter(props) {
   const state = createState({ count: 0 });
-  const ref = createRef();
 
-  onMount(() => console.log('Mounted!'));
-  onCleanup(() => console.log('Cleaning up!'));
+  return () => <div>{state.count}</div>; // Reactive!
+}
 
-  // Return render function
-  return () => <div ref={ref}>{state.count}</div>;
+function Child(props) {
+  // Don't destructure
+  return () => (
+    <div>
+      {props.value} {props.name}
+    </div>
+  ); // Reactive!
 }
 ```
 
-**What happens:**
-- `createComponentInstance()` creates a new component instance
-- Component function executes (setup phase)
-- `createState()` creates reactive state
-- `onMount()` and `onCleanup()` register lifecycle callbacks
-- Render function is stored on the instance
-- Instance is wrapped with an observer for reactivity
+**Why this happens:**
+
+Reactive objects are implemented using JavaScript Proxies. When you access a property during render (e.g., `state.count`), the proxy tracks that dependency. But when you destructure (`const { count } = state`), the destructuring happens during setup—before any tracking context exists. You get a plain value instead of a tracked property access.
+
+**This applies to:**
+
+- `createState()` - Never destructure state objects
+- Props - Never destructure component props
+- `createContext().get()` - Never destructure context values
+- `createAsync()` - Never destructure async state
+- `createQuery()` - Never destructure query objects
+- `createMutation()` - Never destructure mutation objects
+- `createView()` - Never destructure view objects
 
-#### 2. Initial Render
+**Learn more:** This is the same design decision as [Solid.js reactive primitives](https://www.solidjs.com/tutorial/introduction_signals), which also use this pattern for fine-grained reactivity.
 
+## API Reference
+
+### Core Functions
+
+#### `render(component, container)`
+
+Mounts a component to a DOM element.
+
+```tsx
+import { render } from "rask-ui";
+
+render(<App />, document.getElementById("app")!);
 ```
-render(<MyComponent />, container)
-  ↓
-jsxToVNode() - Convert JSX to VNode
-  ↓
-renderComponent() - Create component instance
-  ↓
-observer(() => { /* render function */ })
-  ↓
-Initial render (hostElement = null)
-  ↓
-Store child VNodes for host element creation
-  ↓
-Create host <component> VNode with children
-  ↓
-patch() - Superfine creates DOM
-  ↓
-setupComponentInstances() - Walk VNode tree
-  ↓
-Set instance.hostElement from vnode.node
-  ↓
-Store instance on element.__componentInstance
-  ↓
-Find parent component via DOM traversal
-  ↓
-Add to parent.children Set
-  ↓
-Run onMount() callbacks
+
+**Parameters:**
+
+- `component` - The JSX component to render
+- `container` - The DOM element to mount into
+
+---
+
+#### `createState<T>(initialState)`
+
+Creates a reactive state object. Any property access during render is tracked, and changes trigger re-renders.
+
+```tsx
+import { createState } from "rask-ui";
+
+function Example() {
+  const state = createState({
+    count: 0,
+    items: ["a", "b", "c"],
+    nested: { value: 42 },
+  });
+
+  // All mutations are reactive
+  state.count++;
+  state.items.push("d");
+  state.nested.value = 100;
+
+  return () => <div>{state.count}</div>;
+}
 ```
 
-**Key steps:**
-1. **JSX to VNode**: JSX is converted to Superfine VNodes
-2. **Component Instance Creation**: Each component gets a unique instance
-3. **Observer Setup**: Render function is wrapped to track state dependencies
-4. **Initial Render**: Observer runs but hostElement is null, so child VNodes are stored
-5. **Host Element Creation**: A `<component>` VNode is created with the children
-6. **Superfine Patch**: Superfine creates actual DOM elements
-7. **Instance Setup**: VNode tree is walked to set `hostElement` from `vnode.node`
-8. **Parent-Child Tracking**: Each instance finds its parent and registers as a child
-9. **Mount Callbacks**: `onMount()` callbacks run after DOM is ready
+**Parameters:**
+
+- `initialState: T` - Initial state object
+
+**Returns:** Reactive proxy of the state object
+
+**Features:**
+
+- Deep reactivity - nested objects and arrays are automatically reactive
+- Direct mutations - no setter functions required
+- Efficient tracking - only re-renders components that access changed properties
+
+---
 
-#### 3. State Changes and Re-renders
+#### `createView<T>(...objects)`
 
+Creates a view that merges multiple objects (reactive or plain) into a single object while maintaining reactivity through getters. Properties from later arguments override earlier ones.
+
+```tsx
+import { createView, createState } from "rask-ui";
+
+function Counter() {
+  const state = createState({ count: 0, name: "Counter" });
+  const helpers = {
+    increment: () => state.count++,
+    decrement: () => state.count--,
+    reset: () => (state.count = 0),
+  };
+
+  const view = createView(state, helpers);
+
+  return () => (
+    <div>
+      <h1>
+        {view.name}: {view.count}
+      </h1>
+      <button onClick={view.increment}>+</button>
+      <button onClick={view.decrement}>-</button>
+      <button onClick={view.reset}>Reset</button>
+    </div>
+  );
+}
 ```
-state.count++ (or props change)
-  ↓
-Observer notified (reactive dependency)
-  ↓
-observer() callback executes
-  ↓
-Render function executes
-  ↓
-jsx() - Convert new JSX to VNodes
-  ↓
-patch(hostNode, newVNode)
-  ↓
-Snabbdom updates DOM
+
+**Parameters:**
+
+- `...objects: object[]` - Objects to merge (reactive or plain). Later arguments override earlier ones.
+
+**Returns:** A view object with getters for all properties, maintaining reactivity
+
+**Use Cases:**
+
+1. **Merge state with helper methods:**
+
+   ```tsx
+   const state = createState({ count: 0 });
+   const helpers = { increment: () => state.count++ };
+   const view = createView(state, helpers);
+   // Access both: view.count, view.increment()
+   ```
+
+2. **Combine multiple reactive objects:**
+
+   ```tsx
+   const user = createState({ name: "Alice" });
+   const settings = createState({ theme: "dark" });
+   const view = createView(user, settings);
+   // Access both: view.name, view.theme
+   ```
+
+3. **Override properties with computed values:**
+   ```tsx
+   const state = createState({ firstName: "John", lastName: "Doe" });
+   const computed = {
+     get fullName() {
+       return `${state.firstName} ${state.lastName}`;
+     },
+   };
+   const view = createView(state, computed);
+   // view.fullName returns "John Doe" and updates when state changes
+   ```
+
+**Notes:**
+
+- Reactivity is maintained through getters that reference the source objects
+- Changes to source objects are reflected in the view
+- Only enumerable properties are included
+- Symbol keys are supported
+- **Do not destructure** - See warning section above
+
+---
+
+#### `createRef<T>()`
+
+Creates a ref object for accessing DOM elements or component instances directly.
+
+```tsx
+import { createRef } from "rask-ui";
+
+function Example() {
+  const inputRef = createRef<HTMLInputElement>();
+
+  const focus = () => {
+    inputRef.current?.focus();
+  };
+
+  return () => (
+    <div>
+      <input ref={inputRef} type="text" />
+      <button onClick={focus}>Focus Input</button>
+    </div>
+  );
+}
 ```
 
-**Key steps:**
-1. **State Change**: Setting a state property notifies observers
-2. **Observer Execution**: The component's observer callback runs
-3. **Re-render**: Render function executes, accessing state (tracks dependencies)
-4. **JSX to VNode**: New JSX is converted to VNodes
-5. **Patch**: Snabbdom updates the host element's children
+**Returns:** Ref object with:
+
+- `current: T | null` - Reference to the DOM element or component instance
+- Function signature for use as ref callback
+
+**Usage:**
 
-#### 4. Component Cleanup
+Pass the ref to an element's `ref` prop. The `current` property will be set to the DOM element when mounted and `null` when unmounted.
 
-**Cleanup happens in two scenarios:**
+**Example with SVG:**
 
-##### A. Parent Re-renders and Removes Child
+```tsx
+function Drawing() {
+  const svgRef = createRef<SVGSVGElement>();
+
+  const getSize = () => {
+    if (svgRef.current) {
+      const bbox = svgRef.current.getBBox();
+      console.log(`Width: ${bbox.width}, Height: ${bbox.height}`);
+    }
+  };
 
+  return () => (
+    <div>
+      <svg ref={svgRef} width="200" height="200">
+        <circle cx="100" cy="100" r="50" />
+      </svg>
+      <button onClick={getSize}>Get SVG Size</button>
+    </div>
+  );
+}
 ```
-Parent re-renders
-  ↓
-patch(parentHost, newVNode)
-  ↓
-Snabbdom removes child <component> from DOM
-  ↓
-Destroy hook called
-  ↓
-Run cleanupCallbacks
+
+---
+
+### Lifecycle Hooks
+
+#### `onMount(callback)`
+
+Registers a callback to run after the component is mounted to the DOM.
+
+```tsx
+import { onMount } from "rask-ui";
+
+function Example() {
+  onMount(() => {
+    console.log("Component mounted!");
+  });
+
+  return () => <div>Hello</div>;
+}
+```
+
+**Parameters:**
+
+- `callback: () => void` - Function to call on mount. Can optionally return a cleanup function.
+
+**Notes:**
+
+- Only call during component setup phase (not in render function)
+- Can be called multiple times to register multiple mount callbacks
+
+---
+
+#### `onCleanup(callback)`
+
+Registers a callback to run when the component is unmounted.
+
+```tsx
+import { onCleanup } from "rask-ui";
+
+function Example() {
+  const state = createState({ time: Date.now() });
+
+  const interval = setInterval(() => {
+    state.time = Date.now();
+  }, 1000);
+
+  onCleanup(() => {
+    clearInterval(interval);
+  });
+
+  return () => <div>{state.time}</div>;
+}
 ```
 
-**Key steps:**
-1. **Detection**: Snabbdom's destroy hook is called when element is removed
-2. **Callbacks**: `onCleanup()` callbacks execute (clear timers, subscriptions, etc.)
+**Parameters:**
+
+- `callback: () => void` - Function to call on cleanup
+
+**Notes:**
+
+- Only call during component setup phase
+- Can be called multiple times to register multiple cleanup callbacks
+- Runs when component is removed from DOM
+
+---
+
+### Context API
+
+#### `createContext<T>()`
+
+Creates a context object for passing data through the component tree without props.
+
+```tsx
+import { createContext } from "rask-ui";
 
-### Element Lifecycle (Regular DOM Elements)
+const ThemeContext = createContext<{ color: string }>();
 
-Regular DOM elements (div, span, etc.) follow Snabbdom's patching lifecycle:
+function App() {
+  ThemeContext.inject({ color: "blue" });
 
+  return () => <Child />;
+}
+
+function Child() {
+  const theme = ThemeContext.get();
+
+  return () => <div style={{ color: theme.color }}>Themed text</div>;
+}
 ```
-JSX: <div>Hello</div>
-  ↓
-jsx() creates VNode
-  ↓
-patch() creates or updates DOM
-  ↓
-vnode.elm contains DOM element
+
+**Returns:** Context object with `inject` and `get` methods
+
+**Methods:**
+
+- `inject(value: T)` - Injects context value for child components (call during setup)
+- `get(): T` - Gets context value from nearest parent (call during setup)
+
+**Notes:**
+
+- Context traversal happens via component tree (parent-child relationships)
+- Must be called during component setup phase
+- Throws error if context not found in parent chain
+
+---
+
+### Async Data Management
+
+#### `createAsync<T>(promise)`
+
+Creates reactive state for async operations with loading and error states.
+
+```tsx
+import { createAsync } from "rask-ui";
+
+function UserProfile() {
+  const user = createAsync(fetch("/api/user").then((r) => r.json()));
+
+  return () => (
+    <div>
+      {user.isPending && <p>Loading...</p>}
+      {user.error && <p>Error: {user.error}</p>}
+      {user.value && <p>Hello, {user.value.name}!</p>}
+    </div>
+  );
+}
 ```
 
-**Key points:**
-- Regular elements don't create component instances
-- They're managed entirely by Snabbdom's patch algorithm
-- No special cleanup needed (browser handles DOM removal)
+**Parameters:**
+
+- `promise: Promise<T>` - The promise to track
 
-### Parent-Child Relationship Tracking
+**Returns:** Reactive object with:
 
-Components track their parent via the component stack during initialization:
+- `isPending: boolean` - True while promise is pending
+- `value: T | null` - Resolved value (null while pending or on error)
+- `error: string | null` - Error message (null while pending or on success)
 
+**States:**
+
+- `{ isPending: true, value: null, error: null }` - Loading
+- `{ isPending: false, value: T, error: null }` - Success
+- `{ isPending: false, value: null, error: string }` - Error
+
+---
+
+#### `createQuery<T>(fetcher)`
+
+Creates a query with refetch capability and request cancellation.
+
+```tsx
+import { createQuery } from "rask-ui";
+
+function Posts() {
+  const posts = createQuery(() => fetch("/api/posts").then((r) => r.json()));
+
+  return () => (
+    <div>
+      <button onClick={() => posts.fetch()}>Refresh</button>
+      <button onClick={() => posts.fetch(true)}>Force Refresh</button>
+
+      {posts.isPending && <p>Loading...</p>}
+      {posts.error && <p>Error: {posts.error}</p>}
+      {posts.data &&
+        posts.data.map((post) => <article key={post.id}>{post.title}</article>)}
+    </div>
+  );
+}
 ```
-componentStack.unshift(instance)
-const render = component(instance.reactiveProps)
+
+**Parameters:**
+
+- `fetcher: () => Promise<T>` - Function that returns a promise
+
+**Returns:** Query object with:
+
+- `isPending: boolean` - True while fetching
+- `data: T | null` - Fetched data
+- `error: string | null` - Error message
+- `fetch(force?: boolean)` - Refetch data
+  - `force: false` (default) - Keep existing data while refetching
+  - `force: true` - Clear data before refetching
+
+**Features:**
+
+- Automatic request cancellation on refetch
+- Keeps old data by default during refetch
+- Automatically fetches on creation
+
+---
+
+#### `createMutation<T>(mutator)`
+
+Creates a mutation for data updates with pending and error states.
+
+```tsx
+import { createMutation } from "rask-ui";
+
+function CreatePost() {
+  const state = createState({ title: "", body: "" });
+
+  const create = createMutation((data) =>
+    fetch("/api/posts", {
+      method: "POST",
+      body: JSON.stringify(data),
+    }).then((r) => r.json())
+  );
+
+  const handleSubmit = () => {
+    create.mutate({ title: state.title, body: state.body });
+  };
+
+  return () => (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={state.title}
+        onInput={(e) => (state.title = e.target.value)}
+      />
+      <textarea
+        value={state.body}
+        onInput={(e) => (state.body = e.target.value)}
+      />
+      <button disabled={create.isPending}>
+        {create.isPending ? "Creating..." : "Create"}
+      </button>
+      {create.error && <p>Error: {create.error}</p>}
+    </form>
+  );
+}
 ```
 
-**Key points:**
-- Parent-child relationships tracked through component stack
-- Used for context propagation
-- Cleanup handled by Snabbdom's destroy hooks
+**Parameters:**
+
+- `mutator: (params: T) => Promise<T>` - Function that performs the mutation
+
+**Returns:** Mutation object with:
 
-### Complete Lifecycle Example
+- `isPending: boolean` - True while mutation is in progress
+- `params: T | null` - Current mutation parameters
+- `error: string | null` - Error message
+- `mutate(params: T)` - Execute the mutation
+
+**Features:**
+
+- Automatic request cancellation if mutation called again
+- Tracks mutation parameters
+- Resets state after successful completion
+
+---
+
+### Error Handling
+
+#### `ErrorBoundary`
+
+Component that catches errors from child components.
 
 ```tsx
-function Counter() {
-  // SETUP PHASE (once)
+import { ErrorBoundary } from "rask-ui";
+
+function App() {
+  return () => (
+    <ErrorBoundary
+      error={(err) => (
+        <div>
+          <h1>Something went wrong</h1>
+          <pre>{String(err)}</pre>
+        </div>
+      )}
+    >
+      <MyComponent />
+    </ErrorBoundary>
+  );
+}
+
+function MyComponent() {
   const state = createState({ count: 0 });
 
-  onMount(() => {
-    console.log('Counter mounted');
+  return () => {
+    if (state.count > 5) {
+      throw new Error("Count too high!");
+    }
+
+    return <button onClick={() => state.count++}>{state.count}</button>;
+  };
+}
+```
+
+**Props:**
+
+- `error: (error: unknown) => ChildNode | ChildNode[]` - Render function for error state
+- `children` - Child components to protect
+
+**Notes:**
+
+- Catches errors during render phase
+- Errors bubble up to nearest ErrorBoundary
+- Can be nested for granular error handling
+
+---
+
+## Advanced Patterns
+
+### Lists and Keys
+
+Use keys to maintain component identity across re-renders:
+
+```tsx
+function TodoList() {
+  const state = createState({
+    todos: [
+      { id: 1, text: "Learn RASK" },
+      { id: 2, text: "Build app" },
+    ],
   });
 
-  onCleanup(() => {
-    console.log('Counter cleaning up');
+  return () => (
+    <ul>
+      {state.todos.map((todo) => (
+        <TodoItem key={todo.id} todo={todo} />
+      ))}
+    </ul>
+  );
+}
+
+function TodoItem(props) {
+  const state = createState({ editing: false });
+
+  return () => (
+    <li>
+      {state.editing ? (
+        <input value={props.todo.text} />
+      ) : (
+        <span onClick={() => (state.editing = true)}>{props.todo.text}</span>
+      )}
+    </li>
+  );
+}
+```
+
+Keys prevent component recreation when list order changes.
+
+### Computed Values
+
+Create computed values using functions in setup:
+
+```tsx
+function ShoppingCart() {
+  const state = createState({
+    items: [
+      { id: 1, price: 10, quantity: 2 },
+      { id: 2, price: 20, quantity: 1 },
+    ],
   });
 
-  // RENDER PHASE (every update)
+  const total = () =>
+    state.items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+
   return () => (
     <div>
-      <p>Count: {state.count}</p>
-      <button onClick={() => state.count++}>+</button>
+      <ul>
+        {state.items.map((item) => (
+          <li key={item.id}>
+            ${item.price} x {item.quantity}
+          </li>
+        ))}
+      </ul>
+      <p>Total: ${total()}</p>
     </div>
   );
 }
+```
+
+Computed functions automatically track dependencies when called during render.
 
-// Mount
-render(<Counter />, document.getElementById('app'));
-// Logs: "Counter mounted"
+### Composition
 
-// User clicks button
-// → state.count++ triggers observer
-// → Render function executes
-// → DOM updates via patch()
+Compose complex logic by combining state and methods using `createView`:
+
+```tsx
+function createAuthStore() {
+  const state = createState({
+    user: null,
+    isAuthenticated: false,
+    isLoading: false,
+  });
 
-// Component removed (parent re-renders without it)
-// → Snabbdom destroy hook called
-// → Logs: "Counter cleaning up"
+  const login = async (username, password) => {
+    state.isLoading = true;
+    try {
+      const user = await fetch("/api/login", {
+        method: "POST",
+        body: JSON.stringify({ username, password }),
+      }).then((r) => r.json());
+      state.user = user;
+      state.isAuthenticated = true;
+    } finally {
+      state.isLoading = false;
+    }
+  };
+
+  const logout = () => {
+    state.user = null;
+    state.isAuthenticated = false;
+  };
+
+  return createView(state, { login, logout });
+}
+
+function App() {
+  const auth = createAuthStore();
+
+  return () => (
+    <div>
+      {auth.isAuthenticated ? (
+        <div>
+          <p>Welcome, {auth.user.name}!</p>
+          <button onClick={auth.logout}>Logout</button>
+        </div>
+      ) : (
+        <button onClick={() => auth.login("user", "pass")}>Login</button>
+      )}
+    </div>
+  );
+}
 ```
 
-## Key Architectural Decisions
+This pattern is great for organizing complex business logic while keeping both state and methods accessible through a single object.
 
-### 1. Host-Based Architecture
-- Each component has a host `<component>` element (display: contents)
-- Components render independently to their own host
-- No parent-child instance relationships for rendering
-- Isolation enables fine-grained updates
+### External State Management
 
-### 2. Lifecycle Management
-- Snabbdom hooks manage component lifecycle
-- Insert hook runs onMount callbacks
-- Destroy hook runs onCleanup callbacks
-- Parent-child tracking for context propagation
+Share state across components:
 
-### 3. Observer Pattern for Reactivity
-- Render functions wrapped with observer
-- Automatically tracks state/props access
-- Re-renders only when observed properties change
-- No manual subscriptions needed
+```tsx
+// store.ts
+export const store = createState({
+  user: null,
+  theme: "light",
+});
 
-### 4. Context Traversal
-- Context walks component tree via parent references
-- Set during component initialization
-- Natural hierarchical lookup
-- Works with host element architecture
+// App.tsx
+import { store } from "./store";
 
-### 5. Hook-Based Cleanup
-- Cleanup callbacks run via Snabbdom destroy hooks
-- Synchronous and predictable
-- No manual tracking required
-- Integrated with virtual DOM lifecycle
+function Header() {
+  return () => <div>Theme: {store.theme}</div>;
+}
 
-### 6. Thunk-Based Components
+function Settings() {
+  return () => (
+    <button
+      onClick={() => (store.theme = store.theme === "light" ? "dark" : "light")}
+    >
+      Toggle Theme
+    </button>
+  );
+}
+```
 
-Components use Snabbdom's thunk feature for optimization:
+Any component accessing `store` will re-render when it changes.
+
+### Conditional Rendering
 
 ```tsx
-const thunkNode = thunk("component", props.key, component, [props, children]);
+function Conditional() {
+  const state = createState({ show: false });
+
+  return () => (
+    <div>
+      <button onClick={() => (state.show = !state.show)}>Toggle</button>
+      {state.show && <ExpensiveComponent />}
+    </div>
+  );
+}
 ```
 
-**How it works:**
-- Components wrapped as thunks with custom hooks
-- Init hook: Creates component instance and runs setup
-- Prepatch hook: Updates reactive props before render
-- Postpatch hook: Syncs props after patch
-- Insert hook: Runs onMount callbacks
-- Destroy hook: Runs onCleanup callbacks
+Components are only created when rendered, and automatically cleaned up when removed.
 
-**Benefits:**
-- Leverages Snabbdom's thunk optimization
-- Props changes trigger reactive updates
-- Lifecycle hooks integrated with virtual DOM
-- Efficient component reconciliation
+## TypeScript Support
 
-## API Reference
+RASK is written in TypeScript and provides full type inference:
+
+```tsx
+import { createState, Component } from "rask-ui";
+
+interface Todo {
+  id: number;
+  text: string;
+  done: boolean;
+}
+
+interface TodoItemProps {
+  todo: Todo;
+  onToggle: (id: number) => void;
+}
+
+const TodoItem: Component<TodoItemProps> = (props) => {
+  return () => (
+    <li onClick={() => props.onToggle(props.todo.id)}>{props.todo.text}</li>
+  );
+};
+
+function TodoList() {
+  const state = createState<{ todos: Todo[] }>({
+    todos: [],
+  });
+
+  const toggle = (id: number) => {
+    const todo = state.todos.find((t) => t.id === id);
+    if (todo) todo.done = !todo.done;
+  };
+
+  return () => (
+    <ul>
+      {state.todos.map((todo) => (
+        <TodoItem key={todo.id} todo={todo} onToggle={toggle} />
+      ))}
+    </ul>
+  );
+}
+```
+
+## Configuration
+
+### JSX Setup
+
+Configure TypeScript to use RASK's JSX runtime:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "rask-ui"
+  }
+}
+```
+
+## Performance
+
+RASK is designed for performance:
+
+- **Fine-grained reactivity**: Only components that access changed state re-render
+- **No wasted renders**: Components skip re-render if reactive dependencies haven't changed
+- **Efficient DOM updates**: Powered by a custom virtual DOM implementation optimized for reactive components
+- **No reconciler overhead for state**: State changes are direct, no diffing required
+- **Automatic cleanup**: Components and effects cleaned up automatically
+
+## Comparison with Other Frameworks
+
+| Feature           | React                     | Solid                    | RASK             |
+| ----------------- | ------------------------- | ------------------------ | ---------------- |
+| State management  | Complex (hooks, closures) | Simple (signals)         | Simple (proxies) |
+| UI expression     | Excellent                 | Limited                  | Excellent        |
+| Reactivity        | Coarse (component level)  | Fine-grained             | Fine-grained     |
+| Reconciler        | Yes                       | Limited                  | Yes (custom)     |
+| Syntax            | JSX                       | JSX + special components | JSX              |
+| Compiler required | No                        | Yes                      | No               |
+| Learning curve    | Steep                     | Moderate                 | Gentle           |
+| Access pattern    | Direct                    | Function calls `count()` | Direct           |
+| Mental model      | Complex                   | Simple (with rules)      | Simple           |
+
+## Examples
+
+Check out the demo app in `packages/demo` for more examples.
+
+## Contributing
+
+Contributions are welcome! This is an early-stage project.
+
+## License
+
+MIT
+
+## Why "RASK"?
 
-See main [README](../../README.md) for full API details:
-- `createState(initialState)` - Create reactive state
-- `onMount(callback)` - Register mount callback
-- `onCleanup(callback)` - Register cleanup callback
-- `createContext()` - Create context for data sharing
-- `createAsync(promise)` - Handle async operations
-- `createQuery(fetcher)` - Create query with refetch
-- `createMutation(mutator)` - Create mutation handler
-- `ErrorBoundary` - Error boundary component
-- `render(jsx, container)` - Mount component to DOM
+The name comes from Norwegian/Swedish meaning "fast" - which captures the essence of this library: fast to write, fast to understand, and fast to run.