# Rouse
> Rouse (`rousejs` on [npm](https://www.npmjs.com/package/rousejs)) is a directive-driven reactivity and state-sync layer for server-rendered HTML. The server sends the markup; `data-rz-*` attributes bind it to reactive state, events, and network requests. Logic lives in plain JavaScript scopes and stores, never in attribute expressions. Rouse is pre-release. Source: [github.com/dehkr/rouse](https://github.com/dehkr/rouse).
## Setup
Create an app, register its scopes, stores, interceptors, and listeners, then start it. Starting scans the page and binds every directive.
```js
import { rouse } from 'rousejs';
// Creates the app with config; config is read-only after creation
const app = rouse({
root: '#app',
baseUrl: '/api',
headers: { 'X-Tenant': '42' },
});
app.scope('counter', () => { /* ... */ }); // defines the API inside data-rz-scope="counter"
app.store('prefs', { theme: 'dark' }); // app-wide state, addressed as @prefs in HTML
app.interceptor('request', addAuth); // edits every request before it's sent
app.on('rz:fetch:error', showToast); // hears lifecycle events from the whole app
app.start(); // scans the root and binds directives
```
`start()` scans the DOM once and then watches for added nodes. Registration applies to DOM scanned afterward and never retroactively. `
Unsaved changes
```
- `rz-push`, `rz-pull`, and `rz-deposit` always name their store, including on the store's own script (`
```
- Removing the script leaves the store registered. Only `app.stores.remove(name)` deletes a store.
- A second script with the same name, while the first is still in the page, is ignored with a dev warning. So is a script for a store created with `app.store()`.
- Bindings follow the store, not the script: the same `@cart` paths keep updating across a re-declaration.
### Store manager methods
`app.stores` manages every store by name. It's a manager, not a record of stores.
| Method | Returns | Notes |
| --- | --- | --- |
| `get(name)` | The store, or `undefined` | The same reactive object `@name` reads in markup and `app.store()` returns. Writes through it update bindings and mark the store dirty |
| `has(name)` | `true` if the store exists | A `
```
```http
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json
Rouse-Deposit: @form-errors
{ "email": "Enter a valid email address." }
```
```js
// App-wide: e.detail is the full response; data is the parsed error body
app.on('rz:fetch:error', (e) => {
const { error, data } = e.detail;
if (error.code === 401) location.assign('/login');
else toast(error.message);
});
// Interceptor: listeners and app.fetch callers see the returned error
app.interceptor('error', (error) => {
if (error.code === 'TIMEOUT') {
error.message = 'The server took too long to respond.';
}
return error;
});
```
- **Clear field errors.** Send every field on each response, with `""` for valid ones, and send `Rouse-Deposit` on the success response too. A field left out keeps its old message.
- **Typed sub-events.** `rz:fetch:error:html` and `rz:fetch:error:json` fire right after `rz:fetch:error`, filtered by the error body's content type.
- **Bubbling.** Error events bubble to `app.root`, so one listener on a container handles every trigger inside it.
- **Order.** Error interceptors run before any error event, after the read retry.
- **Cancellations aren't errors.** `CANCELED` from a newer request or a signal fires `:abort`, not `:error`, so it needs no error UI.
## Programmatic API
Everything markup does is also callable from JavaScript, through the app and a few package exports.
```js
// Request through the app's config and interceptors; never throws
const { data, error } = await app.fetch('/api/user', { timeout: 5000 });
// Listen with the same modifiers as markup: keyup|ctrl.key-[arrowup]
app.on('keyup', bump, { ctrl: true, key: 'ArrowUp' });
// Insert HTML the way rz-place would
app.place('#log', '
Done
', { position: 'beforeend' });
// Add a header to every request
app.interceptor('request', (config) => {
config.headers['X-Trace'] = crypto.randomUUID();
return config;
});
```
### App members
Methods and properties on the app that `rouse()` returns.
| Member | Returns | Notes |
| --- | --- | --- |
| `app.scope(name, setup)` | The app | Registers a scope; chainable |
| `app.store(name, data, config?)` | The store | Creates a store; see Stores |
| `app.start()` | | Scans and binds; a second call warns and does nothing |
| `app.destroy()` | | Unbinds everything, fires `rz:app:destroy`, and ends every listener and request. Terminal |
| `app.fetch(url, options?)` | `Promise<{ data, error, status, headers, response, config }>`; never rejects | Sends a request through the app's config and interceptors |
| `app.on([target,] event, callback, options?)` | A teardown function | Listens until the app is destroyed or `options.signal` aborts |
| `app.place(target, html, options?)` | `true` if anything was placed | Inserts HTML the way `rz-place` does |
| `app.sse(url, options?)` | A close function | Opens a stream, or joins one already open at that URL |
| `app.interceptor(phase, fn, options?)` | A teardown function | Adds an interceptor; phase is `'request'`, `'response'`, or `'error'` |
| `app.stores` | The store manager | See Store manager methods |
| `app.root` | The root element | Resolved from `config.root` at creation. Every event bubbles to it, and `app.on` listens on it by default |
| `app.config` | The resolved config | Read-only after creation. Per-request options go in `rz-request`, `app.fetch` options, or a `request` interceptor |
| `app.isReady` | `true` once `rz:app:ready` has fired | `false` until the frame after the first scan. Once it's `true`, a `ready` trigger fires immediately |
- `app.fetch` options: `method`, `body`, `headers`, `params`, `timeout`, `abortKey`, `signal`, `indicator`, `triggerEl`, `skipInterceptors`, and any other `RequestInit` field. Without `triggerEl` it reads nothing from the DOM and routes nothing (unless the server sends `Rouse-Place` / `Rouse-Deposit`).
- `app.on` target defaults to `app.root`. The event is one name or a one-key trigger-source descriptor; modifiers go in options, never in the name. `media-[(min-width: 640px)]|once` is `app.on({ media: '(min-width: 640px)' }, fn, { once: true })`; `edit-[@cart.items]` is `{ edit: 'cart.items' }` (no `@`).
- `app.place` target is an element or a selector within the app root (every match). Positions, case-sensitive: `innerHTML` (default), `outerHTML`, `beforebegin`, `afterbegin`, `beforeend`, `afterend`, `delete`.
- `app.sse` options: `triggerEl`, `withCredentials`, `signal`.
### Package exports
Named exports from `rousejs`.
| Export | Returns | Notes |
| --- | --- | --- |
| `rouse(config?)` | An app (`RouseApp`) | Also the default export. One app per root |
| `signal(value)` | A signal: `s()` reads, `s(v)` writes | One reactive value. Use it for scope state, exposed through a getter |
| `computed(fn)` | A cached derived value, read as `c()` | Recomputes only after a value `fn` read changes. Keep `fn` pure: no writes or side effects |
| `effect(fn)` | A stop function | Runs `fn` now and whenever what it read changes. Created in a scope setup, it stops with the scope |
| `reactive(object)` | A deeply reactive proxy of the object or array | Stores are already reactive; a scope's returned object isn't. Mutate the proxy in place |
| `dispatch(el, name, detail?, init?)` | The `CustomEvent` | Dispatches a bubbling event from `el`. Use it to signal between nested scopes |
| `createKey(prefix?)` | A key unique for the page's lifetime | For `rz-key` on client-created items. Assign it once at creation, never in a getter |
### Interceptor phases
Interceptors run on every fetch, push, and pull the app makes, in registration order, and may be async. `skipInterceptors: true` in `app.fetch` opts one call out; markup can't. `rz-sse` doesn't use them. Each `app.interceptor` call returns a teardown and takes `{ signal }`.
| Phase | Function | Runs |
| --- | --- | --- |
| `request` | `(config) => config` | After `:config` listeners, before sending. The return is merged into the config; a throw fails the request through the `error` phase |
| `response` | `(data, response, config) => data` | On a 2xx response, before routing. The return replaces `data` |
| `error` | `(error, config) => error` | On any failure, including HTTP errors, timeouts, and cancellations, after the retry. The return replaces `error` |
## TypeScript
Rouse ships its own types. The JavaScript API is typed end to end; markup is not: directive values are strings, so nothing checks `data-rz-text="usr.name"` against the scope.
```ts
import type { LifecycleEventMap, RenderHandlerCtx, ScopeSetup } from 'rousejs';
type Todo = { id: string; title: string };
// The type argument types host
const todos: ScopeSetup = ({ host }) => ({
get count() { return host.children.length; },
// Inside rz-render, render.item is the row's Todo
remove({ render }: RenderHandlerCtx) { /* render.item.id */ },
});
// app.on infers the detail from the event name
app.on('rz:fetch:error', (e) => console.warn(e.detail.status));
// Elsewhere, index LifecycleEventMap
el.addEventListener('rz:store:patch', (e) => {
const { storeName } = (e as CustomEvent).detail;
});
```
### Exported types
Import these with `import type { … } from 'rousejs'`.
| Type | For |
| --- | --- |
| `RouseConfig` | Options for `rouse()` |
| `ScopeSetup` | A setup function; `E` types `host` |
| `ScopeCtx` | The setup's argument: `{ host, app, term, scan }` |
| `HandlerCtx` | A handler's argument: `{ el, e, render }` |
| `RenderHandlerCtx` | A handler's argument inside `rz-render`; `render.item` is `Item` |
| `BindableValue` | What a binding can write |
| `LifecycleEvent` | Union of every lifecycle event name |
| `LifecycleEventMap` | Lifecycle event name → `detail` type |
- `app.store('cart', data)` returns `data`'s type, so the store's fields, getters, and methods are typed. `app.stores.get(name)` takes the type explicitly.
- `dispatch(el, name, detail)` checks `detail` when `name` is a lifecycle event.
## Lifecycle events
Rouse dispatches `rz:*` events as an app, scope, request, store, or stream changes state. Listen with `app.on` or use one as a trigger in markup.
```js
// Report failed requests from anywhere in the app
app.on('rz:fetch:error', (e) => toast(`Request failed: ${e.detail.status}`));
// Add a header to fetches from one form; config is the object that gets sent
app.on(form, 'rz:fetch:config', (e) => {
e.detail.config.headers['X-Form'] = form.id;
});
// Cancelable: veto an HTML placement
app.on('rz:dom:place:before', (e) => {
if (!e.detail.payload.trim()) e.preventDefault();
});
```
Every event bubbles to `app.root`. Each fires from the element it describes:
- **App** from `app.root`; **scope** from the scope's host.
- **Request** (a network operation) from the triggering element, or `app.root` without one. `rz:push:*` and `rz:pull:*` have the same events as `rz:fetch:*`, minus the per-content-type ones.
- **Destination** (what a response changed) from the store's script (else `app.root`) or the placement target (its parent for `outerHTML` / `delete`). `operation` or `source` names the cause.
- **Connection** (a stream) from the `rz-sse` element.
### All lifecycle events
Every `rz:*` event, when it fires, and its `detail`.
| Event | When | Detail |
| --- | --- | --- |
| `rz:app:start` | `start()` begins, before the scan | `{ app }` |
| `rz:app:ready` | The frame after the first scan | `{ app }` |
| `rz:app:destroy` | `destroy()` | `{ app }` |
| `rz:scope:init` | Setup returned | `{ context, instance }` |
| `rz:scope:connect` | Bindings attached, after `rz-wake` | `{ instance }` |
| `rz:scope:disconnect` | Bindings detached | `{ instance }` |
| `rz:scope:destroy` | Torn down; fires last. `instance` is for recognizing the scope, not calling it | `{ instance }` |
| `rz:fetch:config` | Before sending. **Cancelable**: prevented, nothing else fires. Edit `config` in place (absolute `url`, `method`, `headers`); it's the object sent | `{ config }`; push/pull add `storeName` |
| `rz:fetch:start` | Sent | as `:config` |
| `rz:fetch:success` | 2xx response. Exactly one of `:success`, `:error`, `:abort` fires | Fetch: the response `{ data, error, status, headers, response, config }`. Push/pull: `{ storeName, result }` |
| `rz:fetch:success:{html,json,file}` | Right after `:success`, per content type; what `rz-place` and `rz-deposit` route | the response |
| `rz:fetch:error` | Error status, network failure, or timeout | as `:success` |
| `rz:fetch:error:{html,json,file}` | Right after `:error`, per content type | the response |
| `rz:fetch:abort` | Aborted by a newer request or a signal | as `:config` |
| `rz:fetch:end` | Always last | as `:config` |
| `rz:store:patch:before` | Before a payload is applied. **Cancelable**; `payload` can be rewritten | `{ storeName, operation, data, payload }` |
| `rz:store:patch` | Payload applied | `{ storeName, operation, data, payload, response }` |
| `rz:store:patch:skipped` | An edit made during the request kept the response from applying. A deposit never skips | `{ storeName, operation, localData, serverData, response }` |
| `rz:dom:place:before` | Before placing. **Cancelable**; `payload` can be rewritten | `{ target, position, payload, source }` |
| `rz:dom:place` | Placed | `{ target, position, payload, source }` |
| `rz:sse:config` | Before the first connection, once. **Cancelable**; edit `config` in place | `{ config }` |
| `rz:sse:open` | Each successful (re)connection | `{ config }` |
| `rz:sse:message:{html,json}` | Unnamed messages, before `:message`; what `rz-place` and `rz-deposit` route | as `:message` |
| `rz:sse:message` | Every message | `{ config, event, data, raw, lastEventId }` |
| `rz:sse:error` | Connection lost. **Cancelable**: prevented, no reconnect | `{ config, attempt }` |
| `rz:sse:close` | Stream closed | `{ config, reason }` |
- Request order is always `:config` → `:start` → one of `:success` / `:error` / `:abort` → `:end`, and the request's outcome fires before any destination event (`rz:push:success` before `rz:store:patch:before`).
- Destination events fire only when something changed, so failures appear only on the request events.
- Only real network operations fire request events. `update()`, `reset()`, and triggers dropped by a guard (disconnected, disabled, a sync already running, a write in flight) fire nothing.
- A stream has no final event per message and no `:end`: it opens once and receives many messages.
## Multiple apps
Each `rouse({ root })` is self-contained: its own stores, scopes, interceptors, listeners, and config, so `@cart` in one app never reaches another app's `cart`. Use separate apps for micro-frontends or widgets that must stay isolated. One app per root; after `destroy()`, a new app can mount on the same element.
```js
// The page app owns the whole document
const page = rouse();
page.start();
// Later, a widget with its own app. Constructing it first marks the root,
// so the page app skips the widget's markup when it's inserted
const root = document.createElement('div');
const widget = rouse({ root, baseUrl: '/widget-api' });
widget.store('cart', { items: [] }); // a different cart from the page's @cart
document.querySelector('#sidebar').append(root);
widget.start();
```
- Apps can nest. A page app on the default `document.documentElement` with an embedded widget is nested. The outer app skips the inner app's markup, and a nested app mounted after the outer one started takes its markup over.
- Construct a nested app before inserting its root element, or the outer app binds that markup until the nested app exists.
- Events bubble across roots: an outer `app.on('rz:fetch:success', …)` or `sse-[name]|root` also hears the inner app's. To handle only your own app's events, check `e.target.closest('[data-rouse-app]') === app.root`.
## Silent pitfalls
These fail without an error, at most a dev warning. Most do nothing; some do the wrong thing.
- **Modifiers need a pipe.** `click.debounce-[300ms]` is one event named `click.debounce` and never fires. Write `click|debounce-[300ms]`.
- **Render fields need a dot.** `%name` is not `%.name`. The dot-less form reads `undefined` and writes nothing.
- **Key names are exact.** `key-[entr]` never fires, and `keydown|enter` (no `key-[]`) fires on every key, with only a dev warning. `key-[ctrl]` is wrong: the key name is `control`, the held flag is `ctrl`.
- **Scope state isn't reactive by default.** A plain field or `let` returned from setup renders once and never updates; use a `signal` behind a getter, or return a `reactive` object directly.
- **Scope listeners and requests are app-wide.** `app.on` in a scope listens on the whole app unless you pass `host` first, and lasts as long as the app without `signal: term`. `app.fetch` likewise keeps running after teardown without `signal: term`.
- **Register before scanning.** A store registered after the markup reading it was scanned stays `undefined` in those bindings for good.
- **Stream events stay local.** `sse-[name]` hears only its own element's stream and descendants. A listener beside the stream needs `sse-[name]|root`.
- **Some events fire off the element.** `visibilitychange` fires on `document`: write `visibilitychange|document`. `load|window` never fires if the app starts after load; use `ready`.
- **Network directives don't wait for a lazy scope.** `rz-fetch`, `rz-pull`, `rz-push`, and `rz-sse` inside a scope with `rz-wake` start at page load. Use the `wake` trigger: `data-rz-sse="wake: /events"`.
- **Wake waits for every trigger.** `rz-wake` is AND: `interact timeout-[5s]` waits for both.
- **Wake and close need a host directive.** `rz-wake` does nothing without `rz-scope`, and `rz-close` nothing without `rz-sse`.
- **Null deletes synced fields.** In a synced store `null` deletes the key, so leave a field absent instead of `null`. A server serializer that omits empty values (Go `omitempty`) can never clear a field.
- **Placement defaults to the host.** `rz-place` defaults to the host's `innerHTML`, so a stream element without it writes every unnamed HTML message into itself. Use `data-rz-place="null"` to opt out.
- **Edit triggers watch data fields.** `edit-[@store.key]` filters on data fields. A setter writes its underlying field, so watching the accessor's key never fires.
- **CORS must allow Rouse headers.** A cross-origin server must list the `Rouse-*` headers in `Access-Control-Allow-Headers` (or sync requests fail as `Failed to fetch`) and `Access-Control-Expose-Headers` (or response headers are ignored).
- **Push isn't plain JSON.** Push bodies are `application/merge-patch+json`. A server parsing only `application/json` (Express `express.json()`) sees an empty body.
- **Streams send no headers.** `EventSource` can't set headers, so `rz-headers`, `rz-request`, and interceptors don't apply to `rz-sse`.
- **URLs can read as methods.** A relative URL spelled like an HTTP method is read as one: write `./query`, not `query`.
- **Scripts in placed HTML don't run.** `rz-place`, `Rouse-Place`, `rz-sse`, `rz-html`, and `app.place` insert HTML through `innerHTML`, which never runs `