@rip-lang/ui 0.1.3 → 0.3.2

package/README.md

@@ -1,877 +1,316 @@
-<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/rip.svg" style="width:50px" /> <br>
+<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/rip.png" style="width:50px" /> <br>
 
 # Rip UI - @rip-lang/ui
 
-> **A zero-build reactive web framework — ship the compiler to the browser, compile on demand, render with fine-grained reactivity**
+> **Zero-build reactive web framework for the Rip language.**
 
-Rip UI inverts the traditional web development model. Instead of building,
-bundling, and shipping static JavaScript artifacts to the browser, it ships the
-40KB Rip compiler itself. Components are delivered as source files, stored in a
-browser-local Virtual File System, compiled on demand, and rendered with
-fine-grained DOM updates powered by Rip's built-in reactivity. No build step.
-No bundler. No configuration files.
+Load the Rip compiler in the browser. Write inline Rip. Launch your app.
+No build step, no bundler, no configuration.
 
-The component model adds exactly **two keywords** to the Rip language —
-`component` and `render` — and reuses everything else (classes, reactivity,
-functions, methods) that Rip already provides.
-
-## Architecture
-
-```
-                     ┌─────────────────────────────────────────┐
-                     │  Server (Bun + @rip-lang/api)           │
-                     │                                         │
-                     │  serve.rip (ripUI middleware)           │
-                     │  ├── /rip-ui/*.js   → framework files   │
-                     │  ├── /rip-ui/manifest.json → all pages  │
-                     │  ├── /rip-ui/watch  → SSE hot-reload    │
-                     │  └── /pages/*.rip   → individual pages  │
-                     └──────────────┬──────────────────────────┘
-                                    │
-         ┌──────────────────────────┼──────────────────────────┐
-         │                          │                          │
-         ▼                          ▼                          ▼
-   rip.browser.js (40KB)    @rip-lang/ui (~8KB)         SSE EventSource
-   (Rip compiler)           (framework modules)        (hot-reload channel)
-         │                          │                          │
-         │         ┌────────────────┼────────────────┐         │
-         │         │                │                │         │
-         │    Reactive Stash   Virtual FS       Router         │
-         │    (app state)     (file storage)  (URL → VFS)      │
-         │         │                │                │         │
-         │         └────────────────┼────────────────┘         │
-         │                          │                          │
-         └─────────────────►   Renderer   ◄────────────────────┘
-                          (compiles + mounts)
-                                    │
-                                  DOM
-```
-
-| Module | Size | Role |
-|--------|------|------|
-| `ui.js` | ~175 lines | `createApp` entry point with `loadBundle`, `watch`, re-exports |
-| `stash.js` | ~400 lines | Deep reactive state tree with path-based navigation |
-| `vfs.js` | ~200 lines | Browser-local Virtual File System with watchers |
-| `router.js` | ~300 lines | File-based router (URL ↔ VFS paths, History API) |
-| `renderer.js` | ~250 lines | Component lifecycle, layouts, transitions, `remount` |
-| `serve.rip` | ~140 lines | Server middleware: framework files, manifest, SSE hot-reload |
-
-## The Idea
-
-Modern web frameworks — React, Vue, Svelte, Solid — all share the same
-fundamental assumption: code must be compiled and bundled on the developer's
-machine, then shipped as static artifacts. This creates an entire ecosystem of
-build tools (Vite, Webpack, Turbopack, esbuild), configuration files, dev
-servers, hot module replacement protocols, and deployment pipelines. The
-developer experience is powerful, but the machinery is enormous.
-
-Rip UI asks: **what if the compiler ran in the browser?**
-
-At 40KB, the Rip compiler is small enough to ship alongside your application.
-Components arrive as `.rip` source files — plain text — and are compiled to
-JavaScript on the client's machine. This eliminates the build step entirely.
-There is no `dist/` folder, no source maps, no chunk splitting, no tree
-shaking, no CI build minutes. You write a `.rip` file, the browser compiles it,
-and it runs.
-
-This is not a toy or a limitation. The compiler produces the same output it
-would on a server. The reactive system is the same signal-based engine that
-powers server-side Rip. The component model compiles to anonymous ES6 classes
-with fine-grained DOM manipulation — no virtual DOM diffing.
-
-### How It Differs from Existing Frameworks
-
-| | React/Vue/Svelte | Rip UI |
-|---|---|---|
-| **Build step** | Required (Vite, Webpack, etc.) | None — compiler runs in browser |
-| **Bundle size** | 40-100KB+ framework + app bundle | 40KB compiler + ~8KB framework + raw source |
-| **HMR** | Dev server ↔ browser WebSocket | SSE notify + VFS invalidation + recompile |
-| **Deployment** | Build artifacts (`dist/`) | Source files served as-is |
-| **Component format** | JSX, SFC, templates | Rip source (`.rip` files) |
-| **Reactivity** | Library-specific (hooks, refs, signals) | Language-native (`:=`, `~=`, `~>`) |
-| **DOM updates** | Virtual DOM diff or compiled transforms | Fine-grained effects, direct DOM mutation |
-| **Routing** | Framework plugin (react-router, etc.) | Built-in file-based router over VFS |
-| **State management** | External library (Redux, Pinia, etc.) | Built-in reactive stash with deep tracking |
-
-## Component Model
-
-The component system adds two keywords to Rip: `component` and `render`. Everything
-else — reactive state (`:=`), computed values (`~=`), effects (`~>`), methods,
-lifecycle — uses standard Rip syntax. A component is an expression that evaluates
-to an anonymous ES6 class.
-
-### Defining a Component
-
-```coffee
-Counter = component
-  @count := 0         # reactive state (signal) — parent can override via props
-  @step = 1           # plain prop — parent can set, not reactive
-
-  doubled ~= @count * 2   # computed (derived, read-only)
-
-  increment: -> @count += @step
-  decrement: -> @count -= @step
-
-  mounted: ->
-    console.log "Counter mounted"
-
-  render
-    div.counter
-      h1 "Count: #{@count}"
-      p "Doubled: #{doubled}"
-      button @click: @increment, "+#{@step}"
-      button @click: @decrement, "-#{@step}"
-```
-
-This compiles to an anonymous ES6 class expression:
-
-```javascript
-Counter = class {
-  constructor(props = {}) {
-    this.count = isSignal(props.count) ? props.count : __state(props.count ?? 0);
-    this.step = props.step ?? 1;
-    this.doubled = __computed(() => this.count.value * 2);
-  }
-  increment() { return this.count.value += this.step; }
-  decrement() { return this.count.value -= this.step; }
-  mounted() { return console.log("Counter mounted"); }
-  _create() { /* fine-grained DOM creation */ }
-  _setup() { /* reactive effect bindings */ }
-  mount(target) { /* ... */ }
-  unmount() { /* ... */ }
-}
-```
-
-### The Two Keywords
-
-**`component`** — Declares an anonymous class with component semantics:
-
-- `@` properties become instance variables that the parent can set via props
-- `:=` assignments create reactive signals (`__state`)
-- `~=` assignments create computed values (`__computed`)
-- `~>` assignments create effects (`__effect`)
-- Plain `=` assignments with function values become methods
-- `mounted`, `unmounted`, `updated` are lifecycle hooks called by the runtime
-- Everything else is standard Rip class behavior
-
-**`render`** — Defines the component's template using a Pug/Jade-like DSL:
-
-- Tags are bare identifiers: `div`, `h1`, `button`, `span`
-- Classes use dot notation: `div.card.active`, `button.btn.btn-primary`
-- Dynamic classes use dot-parens: `div.("active" if @selected)` (CLSX-like)
-- Attributes use object syntax: `input type: "text", placeholder: "..."`
-- Events use `@` prefix: `button @click: @handleClick`
-- Text content is a string argument: `h1 "Hello"`
-- Interpolation works: `p "Count: #{@count}"`
-- Children are indented below their parent
-- `if`/`else` and `for...in` work inside templates
-
-That's it. No special attribute syntax, no directive system, no template
-compiler — just Rip's existing syntax applied to DOM construction.
-
-### Props
-
-Every `@` property on a component is a prop that the parent can set. The child
-owns the property; the parent can provide an initial value or pass a reactive
-signal:
-
-```coffee
-# Parent passes plain value — child wraps it in a signal
-Counter {count: 10}
-
-# Parent passes its own signal — child uses it directly (shared state)
-Counter {count: parentCount}
-```
-
-The `isSignal` check in the constructor handles this automatically:
-
-```javascript
-this.count = isSignal(props.count) ? props.count : __state(props.count ?? 0);
-```
-
-If you don't want the parent to override a prop, don't use `@`:
-
-```coffee
-MyComponent = component
-  active := false      # internal state — not a prop, parent can't set it
-  @count := 0          # prop — parent can set or share a signal
-```
-
-### Required and Optional Props
-
-```coffee
-UserCard = component
-  @name               # required — no default, error if missing
-  @avatar = "/default.png"   # optional — has a default
-  @bio? := ""         # optional reactive — ? makes it explicitly optional
-```
-
-### Computed Values and Effects
-
-```coffee
-TodoList = component
-  @todos := []
-  remaining ~= @todos.filter((t) -> not t.done).length
-  total ~= @todos.length
-
-  ~> console.log "#{remaining} of #{total} remaining"
-
-  render
-    div
-      h2 "Todos (#{remaining}/#{total})"
-      # ...
-```
-
-### Lifecycle
+## Quick Start
 
-`mounted`, `unmounted`, and `updated` are just methods. No special syntax. The
-runtime calls them at the appropriate times:
+**`index.rip`** — the server:
 
 ```coffee
-Timer = component
-  @elapsed := 0
-  @interval = null
-
-  mounted: ->
-    @interval = setInterval (=> @elapsed += 1), 1000
-
-  unmounted: ->
-    clearInterval @interval
+import { get, use, start, notFound } from '@rip-lang/api'
+import { ripUI } from '@rip-lang/ui/serve'
 
-  render
-    p "#{@elapsed} seconds"
+dir = import.meta.dir
+use ripUI dir: dir, components: 'pages', includes: ['ui'], watch: true, title: 'My App'
+get '/css/*', -> @send "#{dir}/css/#{@req.path.slice(5)}"
+notFound -> @send "#{dir}/index.html", 'text/html; charset=UTF-8'
+start port: 3000
 ```
 
-### Two-Way Binding
-
-The `<=>` operator creates two-way bindings between form elements and reactive
-state:
-
-```coffee
-SearchBox = component
-  @query := ""
+**`index.html`** — the page:
 
-  render
-    input type: "text", value <=> @query
-    p "Searching for: #{@query}"
+```html
+<script type="module" src="/rip/rip-ui.min.js"></script>
+<script type="text/rip">
+  { launch } = importRip! 'ui.rip'
+  launch()
+</script>
 ```
 
-### Child Components
-
-Components can nest. Props are passed as object arguments:
+**`pages/index.rip`** — a page component:
 
 ```coffee
-App = component
-  @user := { name: "Alice" }
-
+export Home = component
+  @count := 0
   render
-    div
-      Header {title: "My App"}
-      UserCard {name: @user.name, avatar: "/alice.png"}
-      Footer
+    .
+      h1 "Hello from Rip UI"
+      button @click: (-> @count += 1), "Clicked #{@count} times"
 ```
 
-### Context
+Run `bun index.rip`, open `http://localhost:3000`.
 
-Components can share state down the tree without passing props at every level:
+## Component Composition
 
-```coffee
-# In a parent component's constructor:
-setContext 'theme', @theme
-
-# In any descendant component:
-theme = getContext 'theme'
-```
-
-### Multiple Components Per File
-
-Because `component` is an expression (not a declaration), multiple components
-can live in one file:
+Page components in `pages/` map to routes via file-based routing. Shared
+components in `ui/` (or any `includes` directory) are available by PascalCase
+name. No imports needed:
 
 ```coffee
-Button = component
-  @label = "Click"
-  @onClick = null
+# ui/card.rip
+export Card = component
+  title =! ""
   render
-    button.btn @click: @onClick, @label
+    .card
+      if title
+        h3 "#{title}"
+      @children
 
-Card = component
-  @title = ""
+# pages/about.rip
+export About = component
   render
-    div.card
-      h3 @title
-      div.card-body
-        slot
-
-Page = component
-  render
-    div
-      Card {title: "Welcome"}
-        Button {label: "Get Started", onClick: -> alert "Go!"}
-```
-
-## Virtual File System
-
-The VFS is a browser-local file storage layer. Components are delivered as
-source text and stored in memory. The compiler reads from the VFS, not from
-disk.
-
-```javascript
-import { vfs } from '@rip-lang/ui/vfs'
-
-const fs = vfs()
-
-// Write source files
-fs.write('pages/index.rip', 'component Home\n  render\n    h1 "Hello"')
-fs.write('pages/users/[id].rip', '...')
-
-// Read
-fs.read('pages/index.rip')       // source string
-fs.exists('pages/index.rip')     // true
-fs.list('pages/')                // ['index.rip', 'users/']
-fs.listAll('pages/')             // all files recursively
-
-// Watch for changes (triggers recompilation)
-fs.watch('pages/', ({ event, path }) => {
-  console.log(`${event}: ${path}`)
-})
-
-// Fetch from server
-await fs.fetch('pages/index.rip', '/api/pages/index.rip')
-await fs.fetchManifest([
-  'pages/index.rip',
-  'pages/about.rip',
-  'pages/counter.rip'
-])
+    .
+      h1 "About"
+      Card title: "The Idea"
+        p "Components compose naturally."
+      Card title: "Architecture"
+        p "PascalCase resolution, signal passthrough, children blocks."
 ```
 
-### Why a VFS?
+Reactive props via `:=` signal passthrough. Readonly props via `=!`.
+Children blocks passed as DOM nodes via `@children`.
 
-Traditional frameworks read from the server's file system during the build step
-and produce static bundles. Rip UI has no build step, so it needs somewhere to
-store source files in the browser. The VFS provides:
+## How It Works
 
-- **Addressable storage** — components are referenced by path, just like files
-- **File watching** — the renderer re-compiles when a file changes
-- **Lazy loading** — pages can be fetched on demand as the user navigates
-- **Hot update** — write a new version of a file and the component re-renders
-- **Manifest loading** — bulk-fetch an app's files in one call
+The browser loads one file — `rip-ui.min.js` (~52KB Brotli) — which bundles the
+Rip compiler and the pre-compiled UI framework. No runtime compilation of the
+framework, no extra network requests.
 
-The VFS is not IndexedDB or localStorage — it's a plain in-memory Map. Fast,
-simple, ephemeral. For persistence, the server delivers files on page load.
+Then `launch()` fetches the app bundle, hydrates the stash, and renders.
 
-## File-Based Router
+### Browser Execution Contexts
 
-URLs map to VFS paths. The routing conventions match Next.js / SvelteKit:
+Rip provides full async/await support across every browser context — no other
+compile-to-JS language has this:
 
-```javascript
-import { createRouter } from '@rip-lang/ui/router'
+| Context | How async works | Returns value? |
+|---------|-----------------|----------------|
+| `<script type="text/rip">` | Async IIFE wrapper | No (fire-and-forget) |
+| Playground "Run" button | Async IIFE wrapper | No (use console.log) |
+| `rip()` console REPL | Rip `do ->` block | Yes (sync direct, async via Promise) |
+| `.rip` files via `importRip()` | ES module import | Yes (module exports) |
 
-const router = createRouter(fs, { root: 'pages' })
-```
-
-| VFS Path | URL Pattern | Example |
-|----------|-------------|---------|
-| `pages/index.rip` | `/` | Home page |
-| `pages/about.rip` | `/about` | Static page |
-| `pages/users/index.rip` | `/users` | User list |
-| `pages/users/[id].rip` | `/users/:id` | Dynamic segment |
-| `pages/blog/[...slug].rip` | `/blog/*slug` | Catch-all |
-| `pages/_layout.rip` | — | Root layout (wraps all pages) |
-| `pages/users/_layout.rip` | — | Nested layout (wraps `/users/*`) |
-
-```javascript
-// Navigate
-router.push('/users/42')
-router.replace('/login')
-router.back()
-
-// Reactive route state
-effect(() => {
-  console.log(router.path)     // '/users/42'
-  console.log(router.params)   // { id: '42' }
-})
-```
+The `!` postfix compiles to `await`. Inline scripts are wrapped in an async IIFE
+automatically. The `rip()` console function wraps user code in a `do ->` block
+so the Rip compiler handles implicit return and auto-async natively.
 
-The router intercepts `<a>` clicks automatically for SPA navigation. External
-links and modified clicks (ctrl+click, etc.) pass through normally.
+### globalThis Exports
 
-## Reactive Stash
+When `rip-ui.min.js` loads, it registers these on `globalThis`:
 
-Deep reactive state tree with path-based navigation. Every nested property is
-automatically tracked — changing any value triggers fine-grained updates.
+| Function | Purpose |
+|----------|---------|
+| `rip(code)` | Console REPL — compile and execute Rip code |
+| `importRip(url)` | Fetch, compile, and import a `.rip` file as an ES module |
+| `compileToJS(code)` | Compile Rip source to JavaScript |
+| `__rip` | Reactive runtime — `__state`, `__computed`, `__effect`, `__batch` |
+| `__ripComponent` | Component runtime — `__Component`, `__clsx`, `__fragment` |
+| `__ripExports` | All compiler exports — `compile`, `formatSExpr`, `VERSION`, etc. |
 
-```javascript
-import { stash, effect } from '@rip-lang/ui/stash'
+## The Stash
 
-const app = stash({
-  user: { name: 'Alice', prefs: { theme: 'dark' } },
-  cart: { items: [], total: 0 }
-})
+App state lives in one reactive tree:
 
-// Direct property access (tracked)
-app.user.name                       // 'Alice'
-app.user.prefs.theme = 'light'      // triggers updates
-
-// Path-based access
-app.get('user.prefs.theme')         // 'light'
-app.set('cart.items[0]', { id: 1 }) // deep set with auto-creation
-app.has('user.name')                // true
-app.del('cart.items[0]')            // delete
-app.inc('cart.total', 9.99)         // increment
-app.merge({ user: { role: 'admin' }}) // shallow merge
-app.keys('user')                    // ['name', 'prefs', 'role']
-
-// Reactive effects
-effect(() => {
-  console.log(`Theme: ${app.user.prefs.theme}`)
-  // Re-runs whenever theme changes
-})
 ```
-
-### State Tiers
-
-Three levels of reactive state, each scoped appropriately:
-
-| Tier | Scope | Lifetime | Access |
-|------|-------|----------|--------|
-| **App** | Global | Entire session | `app.user`, `app.theme` |
-| **Route** | Per-route | Until navigation | `router.params`, `router.query` |
-| **Component** | Per-instance | Until unmount | `:=` reactive state |
-
-App state lives in the stash. Route state lives in the router. Component state
-lives in the component instance as signals. All three are reactive — changes at
-any level trigger the appropriate DOM updates.
-
-## Component Renderer
-
-The renderer is the bridge between the router and the DOM. When the route
-changes, the renderer:
-
-1. Resolves the VFS path for the new route
-2. Reads the `.rip` source from the VFS
-3. Compiles it to JavaScript using the Rip compiler
-4. Evaluates the compiled code to get a component class
-5. Instantiates the component, passing route params as props
-6. Wraps it in any applicable layout components
-7. Mounts the result into the DOM target
-8. Runs transition animations (if configured)
-9. Unmounts the previous component
-
-```javascript
-import { createRenderer } from '@rip-lang/ui/renderer'
-
-const renderer = createRenderer({
-  router,
-  fs,
-  stash: appState,
-  compile: compileToJS,
-  target: '#app',
-  transition: { duration: 200 }
-})
-
-renderer.start()   // Watch for route changes, mount components
-renderer.stop()    // Unmount everything, clean up
-```
-
-### Compilation Cache
-
-Compiled components are cached by VFS path. A file is only recompiled when it
-changes. The VFS watcher triggers cache invalidation, so updating a file in the
-VFS automatically causes the next render to use the new version.
-
-## Server Integration
-
-### `ripUI` Middleware
-
-The `ripUI` export from `@rip-lang/ui/serve` is a setup function that registers
-routes for serving framework files, auto-generated page manifests, and an SSE
-hot-reload channel. It works with `@rip-lang/api`'s `use()`:
-
-```coffee
-import { use } from '@rip-lang/api'
-import { ripUI } from '@rip-lang/ui/serve'
-
-use ripUI pages: 'pages', watch: true
+app
+├── routes    ← navigation state (path, params, query, hash)
+└── data      ← reactive app state (title, theme, user, etc.)
 ```
 
-When called, `ripUI` registers the following routes:
-
-| Route | Description |
-|-------|-------------|
-| `GET /rip-ui/ui.js` | Framework entry point |
-| `GET /rip-ui/stash.js` | Reactive state module |
-| `GET /rip-ui/vfs.js` | Virtual File System |
-| `GET /rip-ui/router.js` | File-based router |
-| `GET /rip-ui/renderer.js` | Component renderer |
-| `GET /rip-ui/compiler.js` | Rip compiler (40KB) |
-| `GET /rip-ui/manifest.json` | Auto-generated manifest of all `.rip` pages |
-| `GET /rip-ui/watch` | SSE hot-reload endpoint (when `watch: true`) |
-| `GET /pages/*` | Individual `.rip` page files (for hot-reload refetch) |
+Writing to `app.data.theme` updates any component reading it. The stash
+uses Rip's built-in reactive primitives — the same signals that power
+`:=` and `~=` in components.
 
-### Options
+## The App Bundle
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `pages` | `string` | `'pages'` | Directory containing `.rip` page files |
-| `base` | `string` | `'/rip-ui'` | URL prefix for framework files |
-| `watch` | `boolean` | `false` | Enable SSE hot-reload endpoint |
-| `debounce` | `number` | `250` | Milliseconds to batch filesystem change events |
-
-### Page Manifest
-
-The manifest endpoint (`/rip-ui/manifest.json`) auto-discovers every `.rip` file
-in the `pages` directory and bundles them into a single JSON response:
+The bundle is JSON served at `/{app}/bundle`:
 
 ```json
 {
-  "pages/index.rip": "Home = component\n  render\n    h1 \"Hello\"",
-  "pages/about.rip": "About = component\n  render\n    h1 \"About\"",
-  "pages/counter.rip": "..."
+  "components": {
+    "components/index.rip": "export Home = component...",
+    "components/counter.rip": "export Counter = component...",
+    "components/_lib/card.rip": "export Card = component..."
+  },
+  "data": {
+    "title": "My App",
+    "theme": "light"
+  }
 }
 ```
 
-The client loads this with `app.loadBundle('/rip-ui/manifest.json')`, which
-populates the VFS in a single request — no need to list pages manually.
+On disk you organize your app into `pages/` and `ui/`. The middleware
+maps them into a flat `components/` namespace in the bundle — pages go
+under `components/`, shared components under `components/_lib/`. The `_`
+prefix tells the router to skip `_lib/` entries when generating routes.
 
-## Hot Reload
+## Server Middleware
 
-The hot-reload system uses a **notify-only** architecture — the server tells the
-browser *which files changed*, then the browser decides what to refetch.
-
-### How It Works
-
-```
-  Developer saves a .rip file
-           │
-           ▼
-  Server (fs.watch)
-  ├── Debounce (250ms, batches rapid saves)
-  └── SSE "changed" event: { paths: ["pages/counter.rip"] }
-           │
-           ▼
-  Browser (EventSource)
-  ├── Invalidate VFS entries (fs.delete)
-  ├── Rebuild router (router.rebuild)
-  ├── Smart refetch:
-  │   ├── Current page file? → fetch immediately
-  │   ├── Active layout?     → fetch immediately
-  │   ├── Eager file?        → fetch immediately
-  │   └── Other pages?       → fetch lazily on next navigation
-  └── Re-render (renderer.remount)
-```
-
-### Server Side
-
-The `watch` option enables filesystem monitoring with debounced SSE
-notifications. A heartbeat every 5 seconds keeps the connection alive:
+The `ripUI` middleware registers routes for the framework files, the app
+bundle, and optional SSE hot-reload:
 
 ```coffee
-use ripUI pages: "#{dir}/pages", watch: true, debounce: 250
+use ripUI dir: dir, components: 'pages', includes: ['ui'], watch: true, title: 'My App'
 ```
 
-### Client Side
+| Option | Default | Description |
+|--------|---------|-------------|
+| `app` | `''` | URL mount point |
+| `dir` | `'.'` | App directory on disk |
+| `components` | `'components'` | Directory for page components (file-based routing) |
+| `includes` | `[]` | Directories for shared components (no routes) |
+| `watch` | `false` | Enable SSE hot-reload |
+| `debounce` | `250` | Milliseconds to batch file change events |
+| `state` | `null` | Initial app state |
+| `title` | `null` | Document title |
 
-Connect to the SSE endpoint after starting the app:
+Routes registered:
 
-```javascript
-app.watch('/rip-ui/watch');
 ```
-
-The `watch()` method accepts an optional `eager` array — files that should always
-be refetched immediately, even if they're not the current route:
-
-```javascript
-app.watch('/rip-ui/watch', {
-  eager: ['pages/_layout.rip']
-});
+/rip/rip-ui.min.js   — Rip compiler + pre-compiled UI framework
+/{app}/bundle        — app bundle (components + data as JSON)
+/{app}/watch         — SSE hot-reload stream (when watch: true)
+/{app}/components/*  — individual component files (for hot-reload refetch)
 ```
 
-### `loadBundle(url)`
+## State Preservation (Keep-Alive)
 
-Fetches a JSON manifest containing all page sources and loads them into the VFS
-in a single request. Returns the app instance (chainable).
+Components are cached when navigating away instead of destroyed. Navigate
+to `/counter`, increment the count, go to `/about`, come back — the count
+is preserved. Configurable via `cacheSize` (default 10).
 
-```javascript
-await app.loadBundle('/rip-ui/manifest.json');
-```
+## Data Loading
 
-### `remount()`
+`createResource` manages async data with reactive `loading`, `error`, and
+`data` properties:
 
-The renderer's `remount()` method re-renders the current route. This is called
-automatically by `watch()` after refetching changed files, but it can also be
-called manually:
+```coffee
+export UserPage = component
+  user := createResource -> fetch!("/api/users/#{@params.id}").json!
 
-```javascript
-app.renderer.remount();
+  render
+    if user.loading
+      p "Loading..."
+    else if user.error
+      p "Error: #{user.error.message}"
+    else
+      h1 user.data.name
 ```
 
-## Quick Start
-
-### With Server Integration (Recommended)
-
-The fastest way to get started is with `@rip-lang/api` and the `ripUI` middleware.
-The middleware serves all framework files, auto-generates a page manifest, and
-provides hot-reload — your server is just a few lines:
+## Error Boundaries
 
-**`index.rip`** — The complete server:
+Layouts with an `onError` method catch errors from child components:
 
 ```coffee
-import { get, use, start, notFound } from '@rip-lang/api'
-import { ripUI } from '@rip-lang/ui/serve'
-
-dir = import.meta.dir
-
-use ripUI pages: "#{dir}/pages", watch: true
-
-get '/css/*', -> @send "#{dir}/css/#{@req.path.slice(5)}"
+export Layout = component
+  errorMsg := null
 
-notFound -> @send "#{dir}/index.html", 'text/html; charset=UTF-8'
+  onError: (err) -> errorMsg = err.message
 
-start port: 3000
+  render
+    .app-layout
+      if errorMsg
+        .error-banner "#{errorMsg}"
+      #content
 ```
 
-**`index.html`** — The HTML shell:
+## Navigation Indicator
 
-```html
-<!DOCTYPE html>
-<html>
-<head><title>My App</title></head>
-<body>
-  <div id="app"></div>
-  <script type="module">
-    import { compileToJS } from '/rip-ui/compiler.js';
-    import { createApp } from '/rip-ui/ui.js';
-
-    const app = createApp({
-      target: '#app',
-      compile: compileToJS,
-      state: { theme: 'light' }
-    });
-
-    await app.loadBundle('/rip-ui/manifest.json');
-    app.start();
-    app.watch('/rip-ui/watch');
-  </script>
-</body>
-</html>
+`router.navigating` is a reactive signal — true while a route transition
+is in progress:
+
+```coffee
+if @router.navigating
+  span "Loading..."
 ```
 
-That's it. Run `bun index.rip` and open `http://localhost:3000`. Every `.rip`
-file in the `pages/` directory is auto-discovered, served as a manifest, and
-hot-reloaded on save.
+## Multi-App Hosting
 
-### Standalone (No Server)
+Mount multiple apps under one server:
 
-For static deployments or quick prototyping, you can inline components directly:
+```coffee
+import { get, start, notFound } from '@rip-lang/api'
+import { mount as demo } from './demo/index.rip'
+import { mount as labs } from './labs/index.rip'
 
-```html
-<script type="module">
-  import { compileToJS } from './rip.browser.js'
-  import { createApp } from './ui.js'
-
-  createApp({
-    target: '#app',
-    compile: compileToJS,
-    files: {
-      'pages/index.rip': `
-        Home = component
-          render
-            h1 "Hello, World"
-            p "This was compiled in your browser."
-      `
-    }
-  }).start()
-</script>
+demo '/demo'
+labs '/labs'
+get '/', -> Response.redirect('/demo/', 302)
+start port: 3002
 ```
 
-### File Structure
+The `/rip/` namespace is shared — all apps use the same compiler and framework.
+
+## File Structure
 
 ```
 my-app/
-├── index.rip                # Server (uses @rip-lang/api + ripUI middleware)
-├── index.html               # HTML shell
-├── pages/
-│   ├── _layout.rip          # Root layout (nav, footer)
-│   ├── index.rip            # Home page       → /
-│   ├── about.rip            # About page      → /about
+├── index.rip            # Server
+├── index.html           # HTML page
+├── pages/               # Page components (file-based routing)
+│   ├── _layout.rip      # Root layout
+│   ├── index.rip        # Home          → /
+│   ├── about.rip        # About         → /about
 │   └── users/
-│       ├── _layout.rip      # Users layout    → wraps /users/*
-│       ├── index.rip        # User list       → /users
-│       └── [id].rip         # User profile    → /users/:id
+│       └── [id].rip     # User profile  → /users/:id
+├── ui/                  # Shared components (no routes)
+│   └── card.rip         # Card          → available as Card
 └── css/
-    └── styles.css           # Tailwind or plain CSS
+    └── styles.css       # Styles
 ```
 
-> **Note:** Framework files (`ui.js`, `stash.js`, `router.js`, etc.) are served
-> automatically by the `ripUI` middleware from the installed `@rip-lang/ui`
-> package — you don't need to copy them into your project.
-
-## Render Template Syntax
+Files starting with `_` don't generate routes (`_layout.rip` is a layout,
+not a page). Directories starting with `_` are also excluded, which is how
+shared components from `includes` stay out of the router.
 
-The `render` block uses a concise, indentation-based template syntax:
+## Hash Routing
 
-### Tags and Classes
+For static hosting (GitHub Pages, S3, etc.) where the server can't handle
+SPA fallback routing, use hash-based URLs:
 
 ```coffee
-render
-  div                           # <div></div>
-  div.card                      # <div class="card"></div>
-  div.card.active               # <div class="card active"></div>
-  button.btn.btn-primary        # <button class="btn btn-primary"></button>
+launch '/app', hash: true
 ```
 
-### Dynamic Classes (CLSX)
+This switches from `/about` to `page.html#/about`. Back/forward navigation,
+direct URL loading, and `href="#/path"` links all work correctly.
 
-```coffee
-render
-  div.("active" if @selected)                    # conditional class
-  div.("bg-red" if error, "bg-green" if ok)      # multiple conditions
-  div.card.("highlighted" if @featured)           # static + dynamic
-```
+## Static Deployment — `launch bundle:`
 
-Dynamic class expressions are evaluated at runtime. Falsy values are filtered
-out. This provides native CLSX-like behavior without a library.
+Inline all components in a single HTML file for zero-server deployment.
+Use `rip-ui.min.js` (~52KB Brotli) — a combined bundle with the compiler
+and pre-compiled UI framework. No extra network requests, no runtime
+compilation of the framework:
 
-### Attributes and Events
-
-```coffee
-render
-  input type: "text", placeholder: "Search..."
-  button @click: @handleClick, "Submit"
-  a href: "/about", "About Us"
-  img src: @imageUrl, alt: "Photo"
-```
-
-### Text and Interpolation
-
-```coffee
-render
-  h1 "Static text"
-  p "Hello, #{@name}"
-  span "Count: #{@count}"
-```
-
-### Conditionals
-
-```coffee
-render
-  if @loggedIn
-    p "Welcome back, #{@name}"
-  else
-    p "Please log in"
-```
-
-### Loops
-
-```coffee
-render
-  ul
-    for item in @items
-      li item.name
-```
-
-### Nesting
-
-Indentation defines parent-child relationships:
-
-```coffee
-render
-  div.app
-    header.app-header
-      h1 "My App"
-      nav
-        a href: "/", "Home"
-        a href: "/about", "About"
-    main.app-body
-      p "Content goes here"
-    footer
-      p "Footer"
+```html
+<script type="module" src="dist/rip-ui.min.js"></script>
+<script type="text/rip">
+  { launch } = importRip! 'ui.rip'
+
+  launch bundle:
+    '/':        '''
+                  export Home = component
+                    render
+                      h1 "Hello"
+                '''
+    '/about':   '''
+                  export About = component
+                    render
+                      h1 "About"
+                '''
+  , hash: true
+</script>
 ```
 
-## API Reference
-
-### `createApp(options)`
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `target` | `string\|Element` | `'#app'` | DOM mount target |
-| `state` | `object` | `{}` | Initial app state (becomes reactive stash) |
-| `files` | `object` | `{}` | Initial VFS files `{ path: content }` |
-| `root` | `string` | `'pages'` | Pages directory in VFS |
-| `compile` | `function` | — | Rip compiler (`compileToJS`) |
-| `transition` | `object` | — | Route transition `{ duration }` |
-| `onError` | `function` | — | Error handler |
-| `onNavigate` | `function` | — | Navigation callback |
-
-Returns an instance with these methods:
-
-| Method | Description |
-|--------|-------------|
-| `start()` | Start routing and rendering |
-| `stop()` | Unmount components, close SSE connection, clean up |
-| `load(paths)` | Fetch `.rip` files from server into VFS |
-| `loadBundle(url)` | Fetch a JSON manifest and bulk-load all pages into VFS |
-| `watch(url, opts?)` | Connect to SSE hot-reload endpoint |
-| `go(path)` | Navigate to a route |
-| `addPage(path, source)` | Add a page to the VFS |
-| `get(key)` | Get app state value |
-| `set(key, value)` | Set app state value |
-
-Also exposes: `app` (stash), `fs` (VFS), `router`, `renderer`
-
-### `stash(data)`
-
-Creates a deeply reactive proxy around `data`. Every property read is tracked,
-every write triggers effects.
-
-### `effect(fn)`
-
-Creates a side effect that re-runs whenever its tracked dependencies change.
-
-### `computed(fn)`
-
-Creates a lazy computed value that caches until dependencies change.
-
-### `batch(fn)`
-
-Groups multiple state updates — effects only fire once at the end.
-
-## Design Principles
-
-**No build step.** The compiler is small enough to ship. Source files are the
-deployment artifact.
-
-**Language-native reactivity.** `:=` for state, `~=` for computed, `~>` for
-effects. These are Rip language features, not framework APIs.
-
-**Fine-grained DOM updates.** No virtual DOM. Each reactive binding creates a
-direct effect that updates exactly the DOM nodes it touches.
-
-**Components are classes.** `component` produces an anonymous ES6 class.
-Methods, lifecycle hooks, and state are ordinary class members. No hooks API, no
-composition functions, no magic — just a class with a `render` method.
-
-**Props are instance variables.** `@count := 0` defines a reactive prop. The
-parent can set it, ignore it, or share a signal. The child owns it.
-
-**File-based everything.** Components live in the VFS. Routes map to VFS paths.
-Layouts are `_layout.rip` files in the directory tree. The file system is the
-API.
+See `docs/demo.html` for a complete example — the full Rip UI Demo app
+(6 components, router, reactive state, persistence) in 337 lines of
+static HTML.
 
 ## License
 
 MIT
-
-## Requirements
-
-- [Bun](https://bun.sh) runtime
-- `@rip-lang/api` ≥ 1.1.4 (for `@send` file serving used by `ripUI` middleware)
-- `rip-lang` ≥ 3.1.1 (Rip compiler with browser build)
-
-## Links
-
-- [Rip Language](https://github.com/shreeve/rip-lang)
-- [@rip-lang/api](../api/README.md) — API framework (routing, middleware, `@send`)
-- [@rip-lang/server](../server/README.md) — Production server (HTTPS, mDNS, multi-worker)
-- [Report Issues](https://github.com/shreeve/rip-lang/issues)