redweb 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.11.0
+
+- Added dependency-free server-side TSX rendering through `redweb/jsx-runtime` and `redweb/jsx-dev-runtime`, with fragments, function components, automatic text and attribute escaping, safe URL validation, boolean attributes, and direct interoperability with existing `HtmlFragment` values.
+- Added a compiled TSX Live HTML example plus real HTTP, WebSocket, type-checking, and packed-consumer verification.
+
+## 0.10.0
+
+- Added `defineSite()` for shared static-site CSS, metadata, caching, layouts, canonical URLs, public asset copying, and concise page decorators.
+- Added synchronous function components, readonly collection typings, direct safe primitive attribute/URL interpolation, and a `codeBlock()` highlighter hook.
+- Enabled a bounded heartbeat for Live HTML so chat presence and component disconnect hooks detect half-open browser connections instead of waiting for operating-system TCP timeouts.
+- Rebuilt the Live HTML chatroom as a reusable component with a one-time join flow, reserved display names, online presence, bounded shared history, reconnect recovery, and a dedicated message composer.
+- Added reusable `@component()` Live HTML classes with nested composition, isolated state/actions, shared request and connection lifecycle hooks, and deterministic cascading cleanup.
+- Added explicit safe attribute and URL interpolation for Live HTML.
+- Added nested fragment composition and reusable safe code blocks.
+- Added page head metadata, non-live ETag/cache handling, and runtime-free static export with content-addressed CSS.
+- Replaced the executable `.htmx` sandbox with decorator-first, declarative Live HTML pages.
+- Added context-restricted safe server rendering, shallow reactive state, explicit browser actions and bindings, connection/shared page scopes, expiring page sessions, same-origin admission, optional identity binding, HTTPS/WSS, reconnect snapshots, and awaited deterministic cleanup.
+- Integrated the browser runtime with `redweb-client` rather than maintaining a second WebSocket client.
+- Added runnable server-counter and shared-chatroom examples with real HTTP/WebSocket, browser DOM, load, memory, and packed-artifact verification gates.
+- Converted the canonical Live HTML examples to compiled TypeScript so they use `@page()`, `@state()`, and `@action()` directly.
+- Added `start(PageClass)`, optional `LivePage` inheritance, inferred colocated templates, and `shared: true` to remove framework setup boilerplate from decorated pages.
+
 ## 0.9.0
 
 - Added opt-in pre-upgrade admission, origin validation, secure placement, bounded pending upgrades, transport limits, ordered processing, and route-level heartbeat monitoring.

package/README.md

@@ -30,10 +30,191 @@ const {
   HTTP_OPTIONS,        // Defaults for HTTP servers
   ENCODINGS,           // json/urlencoded encoding names
   SOCKET_OPTIONS,      // Defaults for socket servers
-  METHODS              // Express method helpers
+  METHODS,             // Express method helpers
+  LiveHtmlServer,      // SSR plus lifecycle-safe realtime HTML
+  HtmlRenderer,        // Safe HTML templates, collections, and state payloads
+  LivePage,            // Optional base for advanced page internals
+  page, state, action, view, // Live HTML decorators
+  html, start          // Safe HTML plus one-call page startup
 } = require('redweb');
 ```
 
+## Live HTML
+
+`start(PageClass)` combines server-rendered TSX or `.html` templates and Redweb WebSockets on one listener. Decorated plain classes hold the behavior. Redweb injects a small browser runtime backed by [`redweb-client`](https://www.npmjs.com/package/redweb-client), binds the HTTP render to an expiring page token, and disposes connection-owned state after disconnect.
+
+TSX is the concise default for new pages. It renders straight to Redweb's existing `HtmlFragment`; there is no React dependency, virtual DOM, hydration pass, or client component runtime:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "redweb"
+  }
+}
+```
+
+```tsx
+import { LivePage, action, component, page, start, state } from 'redweb';
+import type { Child } from 'redweb/jsx-runtime';
+
+const Card = component((props: { title: string; children?: Child }) => (
+  <article class="card">
+    <h2>{props.title}</h2>
+    {props.children}
+  </article>
+));
+
+@page('/', { css: 'counter.css' })
+class CounterPage extends LivePage {
+  @state() count = 0;
+
+  @action()
+  increment() { this.count += 1; }
+
+  render() {
+    return (
+      <main>
+        <Card title="Server counter">
+          <button rw-click="increment">
+            Count <output data-rw-state="count">{this.count}</output>
+          </button>
+        </Card>
+      </main>
+    );
+  }
+}
+
+start(CounterPage, { port: 8181 });
+```
+
+Text and attribute values are escaped automatically. URL attributes use Redweb's existing safe-protocol policy. `on*`, inline `style`, `srcdoc`, `srcset`, and executable `<script>` or `<style>` children are rejected; use `rw-*` server directives and external CSS or JavaScript assets. Existing `html` fragments can be nested in TSX, and TSX fragments can be nested in `html`, so migration can be incremental.
+
+Ordinary declarative `.html` templates remain available when separating markup into a standalone file is preferable:
+
+```ts
+import { page, start, state } from 'redweb';
+
+@page('/', { template: 'counter.html', css: 'counter.css' })
+class CounterPage {
+  @state()
+  count = 0;
+
+  private ticker?: NodeJS.Timeout;
+
+  connected() {
+    this.ticker = setInterval(() => this.count++, 1000);
+  }
+
+  disconnected() {
+    clearInterval(this.ticker);
+  }
+}
+
+start(CounterPage, { port: 8080 });
+```
+
+`counter.html` contains no executable server code:
+
+```html
+<h1>Server-side counter</h1>
+<output aria-live="polite" data-rw-state="count"></output>
+```
+
+Changing a `@state()` property sends only that binding's new value. State updates are shallow and assignment-driven; Redweb does not install deep proxies or rerender the document for scalar changes.
+
+CSS is colocated with the page and needs no static-server setup. Pass one file with `css: 'counter.css'` or compose several with `css: ['base.css', 'counter.css']`. Redweb resolves the files beside the decorated class, injects `<link>` elements during SSR, and serves content-addressed stylesheets with immutable browser caching.
+
+Browser events can call only explicitly exposed actions:
+
+```ts
+@component()
+class Chatroom {
+  @state()
+  screen = html`<form rw-submit="join"><input name="name"><button>Join</button></form>`;
+
+  @action()
+  join({ name }: { name: string }) {
+    this.screen = html`<p>Connected as ${name}</p><form rw-submit="send"><input name="message"><button>Send</button></form>`;
+  }
+}
+```
+
+```ts
+@page('/chat', { css: 'chatroom.css' })
+class ChatroomPage {
+  chat = new Chatroom();
+  render() { return html`<main>${this.chat}</main>`; }
+}
+```
+
+Interpolations created with `html` are escaped by default and are restricted to element text—not attributes, URLs, scripts, or styles. Only `HtmlFragment` values may produce HTML patches; ordinary state uses `textContent`. Use `@state({ writable: true })` to opt a property into `rw-bind="property"` browser updates. A page is connection-scoped by default; `shared: true` deliberately shares one instance across its connected visitors. The older `scope: 'shared'` spelling remains supported.
+
+Collections use the same model without manual concatenation. Keep the array in `@state()`, render one item with `@view('cards')`, and place it with `<section rw-each="cards"></section>`. Item views must return `html` fragments, so values remain escaped. The current protocol replaces the collection contents atomically; keyed incremental patches can be added later without changing the page API.
+
+Documentation and content-heavy pages can compose nested fragments without a client framework:
+
+```ts
+import { attribute, codeBlock, each, html, url } from 'redweb';
+
+const sections = each(apiSections, section => html`
+  <article id="${attribute(section.id)}">
+    <h2>${section.name}</h2>
+    <a href="${url(`#${section.id}`)}">Permalink</a>
+    ${each(section.methods, method => html`<section><h3>${method.name}</h3></section>`)}
+    ${codeBlock(section.usage, { language: 'ts', label: 'TypeScript' })}
+  </article>
+`);
+```
+
+Primitive values may be interpolated directly into quoted attributes and safe URL attributes. Redweb escapes attributes and rejects unsafe or protocol-relative URL schemes; `attribute()` and `url()` remain available when explicit intent helps readability. Event handlers, inline styles, `srcdoc`, and `srcset` remain prohibited. `codeBlock()` escapes ordinary code and can call a server-side `highlight` function that returns an `HtmlFragment`.
+
+For React-free documentation or marketing pages, set `live: false`. Redweb omits page tokens, browser JavaScript, and WebSockets; adds document metadata; and serves the result with an ETag:
+
+```ts
+@page('/docs', {
+  template: 'docs.html',
+  css: 'docs.css',
+  live: false,
+  head: {
+    title: 'Redweb API',
+    description: 'Complete Redweb API reference.',
+    canonical: 'https://example.com/docs',
+    image: 'https://example.com/og.png',
+  },
+  cache: { maxAge: 300, staleWhileRevalidate: 3600 },
+})
+class DocsPage {}
+```
+
+Export the same decorated page to CDN-ready files with `await exportStatic(DocsPage, { outDir: 'dist' })`. Route paths become `index.html` files, colocated stylesheets are emitted under their content-addressed URLs, and no Live HTML runtime is included. Static export requires `live: false`.
+
+For a multi-page site, `defineSite()` removes repeated static-page configuration. It shares CSS, metadata, caching, and a safe layout; generates canonical URLs; and can copy a public asset directory during export:
+
+```ts
+const docs = defineSite({
+  origin: 'https://redweb.example',
+  css: 'site.css',
+  head: { description: 'Redweb documentation' },
+  layout: content => html`<body><nav>Redweb</nav><main>${content}</main></body>`,
+});
+
+@docs.page('/docs', { head: { title: 'Documentation' } })
+class DocsPage {
+  render() { return html`<h1>Documentation</h1>`; }
+}
+
+await docs.export(DocsPage, { outDir: 'dist', publicDir: 'public' });
+```
+
+An `html` fragment returned by `render()` is final safe markup, so documentation examples containing literal `{{ bindings }}` are never parsed a second time. Return a string or use a template file when Redweb should resolve template bindings and directives.
+
+The same API serves HTTPS/WSS when `ssl` is provided. For private pages, an optional `authenticate(request)` callback binds the page token to the same stable user identity across the HTTP render and WebSocket upgrade. Initial connections and reconnects always receive a complete authoritative state snapshot.
+
+See the [Live HTML guide](docs/LIVE_HTML.md), runnable [TSX page](examples/live-html/jsx-page.tsx), TypeScript [server counter](examples/live-html/counter.ts), component-based [chatroom](examples/live-html/chatroom.ts), and [persistent card collection](examples/live-html/cards.ts). The chatroom separates joining from its stable message composer, tracks online members, preserves bounded history, restores identity and missed messages after reconnect, and creates an isolated room for every server. The cards page uses `shared: true`, so additions survive reloads, reconnects, and new visitors while its server is running. Run the examples with `npm run example:jsx`, `npm run example:counter`, `npm run example:chatroom`, and `npm run example:cards`. The decorated sources are compiled and exercised unchanged by mock-free HTTP/WebSocket integration tests and a real-Chromium DOM gate.
+
+Reusable snippets can own server behavior without page-level forwarding methods. Decorate a class with `@component()`, put instances in page fields, and interpolate them directly: `` html`<main>${this.primary}${this.secondary}</main>` ``. Each instance gets isolated `@state()`, scoped `@action()` methods, nested-component support, and page-owned lifecycle cleanup. See the runnable [component counters](examples/live-html/components.ts) or run `npm run example:components`.
+
 ## Multiplayer in 0.9
 
 Redweb keeps each production feature independent and opt-in:
@@ -66,8 +247,7 @@ Options:
 - `encoding` (`'json' | 'urlencoded'`): body parser selection.
 - `corsOptions`: passed to `cors`.
 - `corsOptions: false`: disables the CORS middleware entirely.
-- `enableHtmxRendering` (boolean): render `.htmx` files with the built-in renderer.
-- `exposeErrors` (boolean): include HTMX rendering details in responses; defaults to `false`.
+- `exposeErrors` (boolean): include WebSocket handler details in responses; defaults to `false`.
 - `logger`: an object with optional `log`, `warn`, and `error` methods. Pass `null` to disable library logging.
 
 Example:
@@ -88,26 +268,6 @@ new HttpServer({
 });
 ```
 
-HTMX rendering example (`enableHtmxRendering: true`):
-
-```js
-new HttpServer({ publicPaths: ['./public'], enableHtmxRendering: true });
-```
-
-`public/example.htmx`:
-
-```js
-const name = 'RedWeb';
-
-<@>
-  <h1>Hello, {{name}}!</h1>
-<@/>
-```
-
-Requesting `/example.htmx` returns rendered HTML.
-
-Templates are trusted server-side code. They may load relative modules within their configured public directory, execute for at most one second by default, and interpolate raw HTML. Never render user-supplied template files.
-
 CORS remains permissive by default for backward compatibility. CORS is not authorization; configure `corsOptions`, add authentication middleware to `server.app`, or disable the middleware as appropriate.
 
 ## WebSocket servers
@@ -453,6 +613,10 @@ Helpers: `add`, `remove(itemOrId, byKey = 'id')`, `all()`, `count()`.
 - `ProtocolClient` is available from `redweb/client` for negotiated protocol routes without adding runtime dependencies.
 - The minimum supported Node.js version is 18.
 
+## Live HTML migration
+
+The earlier executable `.htmx` sandbox and `enableHtmxRendering` option have been replaced. Templates are now ordinary `.html` files registered through decorated plain classes. Move template calculations and imports into the page class, mark reactive fields with `@state()`, expose browser-callable methods with `@action()`, and launch the page with `start(PageClass)`.
+
 ## Developing
 
 - Run tests with `npm test` (Jest). The suite includes mock-free HTTP, HTTPS, WebSocket, and secure WebSocket integration tests plus unit tests, with 100% coverage enforced for statements, branches, functions, and lines.

package/docs/LIVE_HTML.md

@@ -0,0 +1,352 @@
+# Redweb Live HTML
+
+Live HTML is Redweb's decorator-first server-rendering layer. It uses the existing `HttpServer`, `SocketRoute`, admission, protocol, ordering, backpressure, and shutdown implementations rather than maintaining a second network stack.
+
+## TSX rendering
+
+New pages can return TSX directly. Configure TypeScript with `"jsx": "react-jsx"` and `"jsxImportSource": "redweb"`; Redweb supplies its own dependency-free JSX runtimes and renders immediately to `HtmlFragment` values:
+
+```tsx
+import { LivePage, action, component, page, state } from 'redweb';
+import type { Child } from 'redweb/jsx-runtime';
+
+const Panel = component((props: { title: string; children?: Child }) => (
+  <section class="panel">
+    <h2>{props.title}</h2>
+    {props.children}
+  </section>
+));
+
+@page('/counter', { css: 'counter.css' })
+class CounterPage extends LivePage {
+  @state() count = 0;
+
+  @action()
+  increment() { this.count += 1; }
+
+  render() {
+    return (
+      <Panel title="Server counter">
+        <button rw-click="increment">
+          Count <output data-rw-state="count">{this.count}</output>
+        </button>
+      </Panel>
+    );
+  }
+}
+```
+
+Intrinsic elements, fragments (`<>...</>`), nested readonly arrays, and synchronous function components are supported. Strings, numbers, and attributes are escaped once; null, undefined, and boolean children render nothing. Safe existing `html` fragments compose in either direction.
+
+JSX intentionally remains a server serializer rather than a React compatibility layer. It retains no tree and provides no hooks, refs, hydration, client event functions, or object-style API. Use `rw-click`, `rw-submit`, `rw-bind`, and the other Redweb directives for server actions, and use `@page({ css })` or external assets for styling and scripts. Unsafe URL protocols, `on*`, dynamic `style`, `srcdoc`, `srcset`, children on void elements, and executable `<script>` or `<style>` children are rejected.
+
+This layer deliberately owns page concerns only: `@page`, `@state`, `@view`, and `@action`. It does not clone jax.on's `@get`/`@post` controller API. Continue using Redweb's `services` option for ordinary HTTP APIs; a unified controller decorator surface is a separate compatibility decision rather than hidden behavior in the rendering layer.
+
+## Page model
+
+Every page is a plain class registered with `@page(path, options)`. Extending `LivePage` remains compatible but is not required:
+
+```ts
+@page('/profile', { template: 'profile.html', css: 'profile.css' })
+class ProfilePage {
+  @state()
+  displayName = 'Guest';
+}
+```
+
+The decorators support both TypeScript's current standard decorator emit and the legacy `experimentalDecorators` ABI.
+
+Pages use connection scope by default: each rendered browser page receives its own instance. `shared: true` creates one instance shared by every visitor to that page class and is appropriate for intentionally shared state such as a bounded chatroom history. `scope: 'shared'` remains available as the explicit equivalent.
+
+`start(PageClass)` creates the Live HTML server. `@page()` captures its source directory when the module is evaluated, so colocated templates and styles work for unexported classes, CommonJS, ESM, and barrel exports without module scanning. Pass `templateRoot` explicitly only when page assets live in a different directory. Template and stylesheet traversal outside that root is rejected.
+
+## Colocated CSS
+
+Declare a stylesheet on the same decorator—no Express static middleware or manual `<link>` is required:
+
+```ts
+@page('/profile', { template: 'profile.html', css: 'profile.css' })
+class ProfilePage {}
+```
+
+For composed styles, use `css: ['base.css', 'profile.css']`. Paths resolve from the same captured source directory as the template and cannot traverse outside it. Redweb reads each file once at startup, injects stylesheet links into the server-rendered document, and serves the CSS from a content-addressed URL with the correct content type and immutable caching. Remote URLs and static asset hosting remain under the application's control.
+
+## Declarative HTML templates
+
+Template files use the ordinary `.html` extension and contain no executable server code:
+
+```html
+<h1>{{ displayName }}</h1>
+<input rw-bind="displayName">
+```
+
+`{{ property }}` creates an inline text binding. For context-safe container updates, bind an existing element; this is especially useful when a value contains several list or table children:
+
+```html
+<ul data-rw-state="messages"></ul>
+```
+
+During SSR Redweb fills the bound element with the current property value, and subsequent assignments to a decorated `@state()` property update the same element.
+
+Ordinary values are escaped during SSR and applied with `textContent` in the browser. The `html` tagged template returns an explicit `HtmlFragment`; its interpolations are escaped, while the resulting fragment may be applied as HTML.
+
+## Rendering collections
+
+Keep collection data as an ordinary array and decorate the method that renders one item:
+
+```ts
+@state()
+cards = [{ title: 'Sword' }, { title: 'Shield' }];
+
+@view('cards')
+card(item: { title: string }) {
+    return html`<article class="card"><h2>${item.title}</h2></article>`;
+}
+```
+
+Place the collection in the template with `<section rw-each="cards"></section>`. Redweb server-renders every item, escapes interpolated values, and replaces the collection contents when the array is reassigned. View methods are synchronous and must return an `HtmlFragment`. Arrays of fragments also compose naturally inside `html`, such as ``html`<div>${items.map(renderItem)}</div>` ``.
+
+For a small, auditable safety model, primitive values may be interpolated into quoted attributes. URL-bearing attributes additionally pass through Redweb's safe-URL policy. The explicit `attribute()` and `url()` wrappers remain supported when they improve intent. Interpolation in event handlers, inline styles, `srcdoc`, `srcset`, `<script>`, and `<style>` remains prohibited.
+
+## Reusable components
+
+For stateless snippets, pass a render function directly to `component()`:
+
+```ts
+const Badge = component((properties: { label: string }) =>
+  html`<strong class="badge">${properties.label}</strong>`
+);
+```
+
+Function components are synchronous and must return `html`. Use a decorated class when a component needs state, actions, or lifecycle hooks.
+
+Decorate a plain class with `@component()` to give a reusable HTML snippet its own server state, actions, and lifecycle. Store component instances in page fields and interpolate them like any other safe HTML fragment:
+
+```ts
+import { action, component, html, page, start, state } from 'redweb';
+
+@component()
+class Counter {
+  @state()
+  count = 0;
+
+  constructor(private readonly label: string) {}
+
+  @action()
+  increment() {
+    this.count += 1;
+  }
+
+  render() {
+    return html`
+      <article>
+        <h2>${this.label}</h2>
+        <output data-rw-state="count">${this.count}</output>
+        <button rw-click="increment">Increment</button>
+      </article>
+    `;
+  }
+}
+
+@page('/')
+class Dashboard {
+  primary = new Counter('Primary');
+  secondary = new Counter('Independent');
+
+  render() {
+    return html`<main>${this.primary}${this.secondary}</main>`;
+  }
+}
+
+start(Dashboard);
+```
+
+The field path is the component's public protocol namespace, so both counters can expose `count` and `increment` without collisions. Browser events carry that visible namespace and the server resolves it through its component registry; client-supplied object paths are never evaluated. It is routing metadata, not an authorization boundary—component actions must enforce the same application authorization as page actions. Components may contain other decorated components, and state updates retain the complete nested namespace.
+
+Component instances are owned by exactly one construction-time page or component field. Their synchronous `render(context)` method may return a safe `HtmlFragment` or a declarative template string; request context is propagated per render, including on concurrent shared pages. Components receive the same `loading`, `connected`, `disconnected`, and `disposed` hooks as their page, including the authenticated principal and cancellation signal where applicable. Disposal starts every child and owner cleanup together and preserves every settled failure, so one broken sibling cannot starve later hooks.
+
+Redweb scopes only elements that carry a state, binding, or action directive; it does not add layout wrappers or inline styles. Components therefore remain valid in restricted contexts such as tables and selects and work with strict `style-src` policies.
+
+### Safe attributes and links
+
+Dynamic document navigation remains explicit:
+
+```ts
+import { attribute, html, url } from 'redweb';
+
+const section = { id: 'socket-server', name: 'SocketServer' };
+const markup = html`
+  <article id="${attribute(section.id)}">
+    <a href="${url(`#${section.id}`)}">${section.name}</a>
+  </article>
+`;
+```
+
+`attribute()` accepts primitive values and is valid only inside a quoted non-URL attribute. `url()` explicitly brands URL-bearing attributes such as `href`, `src`, and `action`; direct string values receive the same validation. Redweb permits relative URLs plus HTTP, HTTPS, mail, and telephone URLs, while rejecting control characters, protocol-relative URLs, and executable schemes. Both wrappers are escaped when rendered and are rejected in element text.
+
+### Nested components and code
+
+Plain functions returning `html` fragments are reusable server components. `each()` validates and joins arrays of those fragments, including nested lists:
+
+```ts
+import { codeBlock, each, html } from 'redweb';
+
+const method = (entry: Method) => html`
+  <section>
+    <h3>${entry.name}</h3>
+    <p>${entry.description}</p>
+    ${codeBlock(entry.usage, { language: 'ts', label: 'TypeScript' })}
+  </section>
+`;
+
+const reference = each(apiSections, section => html`
+  <article>
+    <h2>${section.name}</h2>
+    ${each(section.methods, method)}
+  </article>
+`);
+```
+
+`codeBlock()` escapes strings by default. It may also receive an explicit `HtmlFragment`, or a `highlight(source, language)` callback that returns one, allowing a server-side highlighter to compose safe token spans without accepting arbitrary HTML strings.
+
+An `HtmlFragment` returned from `render()` is already fully composed and is never reparsed for `{{ bindings }}` or directives. This keeps code samples literal and prevents escaped documentation text from becoming executable template syntax. Return a string or use `template` when Redweb should process declarative bindings.
+
+State observation is deliberately shallow. Assigning a new value publishes an update; mutating a nested object or array in place does not. Reassign after nested changes:
+
+```ts
+this.players = [...this.players, player];
+```
+
+## Browser actions and input
+
+Only methods decorated with `@action()` may be invoked by the browser:
+
+```ts
+@action()
+save(form: { displayName: string }) {
+  this.displayName = form.displayName;
+}
+```
+
+```html
+<form rw-submit="save">
+  <input name="displayName">
+  <button>Save</button>
+</form>
+```
+
+`rw-click="action"` prevents default navigation and invokes an action without arguments. `rw-submit="action"` prevents submission, passes form fields as the first argument, preserves duplicate field names as arrays, and resets only after the server acknowledges success. `rw-bind="property"` sends text values or checkbox state only when that property was declared with `@state({ writable: true })`.
+
+When an HTML-valued component state renders new actions or bindings, Redweb automatically scopes those directives back to that component. A component can therefore replace a join form with a composer—or swap any other interactive view—without manual component IDs or browser glue.
+
+The document emits `redweb:connection` events as transport state changes and `redweb:error` events when an interaction fails. A bounded queue covers interaction during initial connection; actions are request/response operations and are not replayed during reconnect.
+
+Names such as `constructor`, `prototype`, and `__proto__` are rejected. Arbitrary methods and undeclared state cannot be reached through the Live HTML protocol.
+
+## Lifecycle
+
+Pages can implement these optional hooks:
+
+- `loading(context)` runs before SSR and receives the portable page request, params, query, body, and shutdown `signal`.
+- `connected(context)` runs after the page's authenticated socket connects and receives the socket and cancellation signal.
+- `disconnected(context)` runs when that socket closes and may be asynchronous.
+- `disposed()` runs once when a connection-scoped page expires or the server shuts down and may be asynchronous.
+
+Timers and subscriptions created by a page should be owned by that page and stopped in `disconnected()` or `disposed()`. `dispose()` is idempotent.
+
+Shutdown aborts the render signal and waits up to `shutdownTimeoutMs` (one second by default) for active `loading()` and `render()` hooks. If a hook ignores cancellation, Redweb disposes its page, force-closes the affected HTTP connection, completes the remaining cleanup phases, and then reports the timeout.
+
+HTTP rendering produces an unpredictable page ID. The browser presents it during a same-origin, versioned WebSocket upgrade. Pending and disconnected sessions expire, the registry is bounded by `maxSessions`, and a page ID cannot own two active sockets simultaneously.
+
+For authenticated pages, provide `authenticate(request)`. It runs for both the HTTP render and WebSocket upgrade and must return the same stable primitive identity (commonly a user ID) for both requests. A missing, rejected, changed, or object identity is denied, preventing a copied page token from crossing authentication boundaries. The identity is available as `context.principal` in page hooks and actions.
+
+## Browser transport
+
+The injected module uses the published `redweb-client` package served by the same Redweb listener. It derives `ws:` or `wss:` from the current page, negotiates protocol version `1`, uses one socket per page, delegates DOM events at the document level, and opts into bounded reconnection attempts. Every initial connection and reconnect receives an authoritative state snapshot. Supplying the normal `ssl` option runs both the page and socket over HTTPS/WSS.
+
+## Options
+
+`start(PageClass, options)` accepts normal HTTP options plus the following Live HTML controls. `new LiveHtmlServer({ pages, ...options })` remains available for explicit composition:
+
+- `pages`: non-empty array of decorated class constructors when using `LiveHtmlServer` directly.
+- `templateRoot`: optional root for all `.html` templates and CSS files; when omitted, each page uses the source directory captured by its `@page()` decorator.
+- `livePaths.css`: optional internal URL prefix for generated stylesheet routes; defaults to `/__redweb/css`.
+- `sessionTtlMs`: pending/reconnect session lifetime; defaults to 30 seconds.
+- `maxSessions`: maximum pending plus active page sessions; defaults to 1,000.
+- `maxConcurrentRenders`: maximum simultaneous HTTP page renders, independent of live session occupancy; defaults to `maxSessions`.
+- `shutdownTimeoutMs`: maximum render/route drain time before forced cleanup; defaults to one second.
+- `heartbeat`: optional `{ intervalMs, timeoutMs }` WebSocket liveness policy. Live HTML defaults to a 15-second ping interval and 10-second pong timeout so half-open browsers are disconnected and component `disconnected()` hooks update presence promptly.
+- `authenticate`: optional HTTP/WebSocket identity function for binding page sessions to an authenticated principal.
+- `origins`: optional exact origin list or predicate for deployments behind a trusted proxy. Without it, Redweb requires a scheme-and-host match (`http`/WS or `https`/WSS).
+- `livePaths`: optional `{ socket, client, runtime }` internal path overrides.
+
+The internal paths and application page paths must be unique.
+
+## Verification examples
+
+- `examples/live-html/counter.ts` uses `@page()`, colocated CSS, and `@state()` to prove a connection-owned server timer can update browser state and is stopped on disconnect.
+- `examples/live-html/chatroom.ts` uses a connection-scoped `@component()` backed by a room service created by `createChatroomPage()`, so separate server instances cannot leak history or names. Visitors join once, receive a stable dedicated composer, see a capped presence list with the total online count, share bounded history, and recover their identity and missed messages after reconnect.
+- `examples/live-html/cards.ts` uses a shared decorated page, `@view()`, and `rw-each` to prove server-rendered collection SSR, realtime replacement, and persistence across reloads and reconnects while the server is running.
+- `examples/live-html/components.ts` uses two instances of one `@component()` class to prove reusable markup, isolated server state, scoped actions, and component CSS composition.
+- `examples/live-html/jsx-page.tsx` uses Redweb's automatic JSX runtime, a function component, decorated state, and a server action without HTML template strings.
+
+Run the examples immediately with `npm run example:counter`, `npm run example:chatroom`, `npm run example:cards`, `npm run example:components`, and `npm run example:jsx`. Their checked-in JavaScript artifacts are generated from the decorated TypeScript or TSX sources, and every test and package build rejects stale output. The artifacts are launched unchanged by `tests/integration/live-html.integration.test.js` over real loopback HTTP and WebSocket connections. Run the focused gate with `npm run verify:live-html`, or the complete 100% coverage suite with `npm test`.
+
+## Static pages and documentation export
+
+Set `live: false` when a page needs server rendering but no realtime session:
+
+```ts
+import { exportStatic, page } from 'redweb';
+
+@page('/docs', {
+  template: 'docs.html',
+  css: ['base.css', 'docs.css'],
+  live: false,
+  head: {
+    title: 'Redweb API reference',
+    description: 'HTTP, WebSocket, multiplayer, and Live HTML APIs.',
+    canonical: 'https://example.com/docs',
+    image: 'https://example.com/og.png',
+    robots: 'index,follow',
+  },
+  cache: { maxAge: 300, staleWhileRevalidate: 3600 },
+})
+class DocsPage {}
+
+await exportStatic(DocsPage, { outDir: 'dist' });
+```
+
+Non-live pages contain no page token or browser runtime. When served by `start()`, Redweb skips its WebSocket route, emits an ETag, honors `If-None-Match`, and applies the declared public cache policy. Interactive pages are always sent with `private, no-store`.
+
+`exportStatic()` accepts one decorated class or an array. It requires `live: false`, maps `/` to `index.html` and `/docs` to `docs/index.html`, emits content-addressed CSS beside the pages, and returns frozen lists of written files. It never deletes or cleans the output directory.
+
+For several pages, define shared defaults once:
+
+```ts
+import { defineSite, html } from 'redweb';
+
+const docs = defineSite({
+  origin: 'https://example.com',
+  css: 'site.css',
+  head: { description: 'Redweb documentation' },
+  cache: { maxAge: 300 },
+  layout: (content, context) => html`
+    <body data-path="${context.request.path}">
+      <nav>Redweb</nav>
+      <main>${content}</main>
+    </body>
+  `,
+});
+
+@docs.page('/docs', { head: { title: 'Documentation' } })
+class DocsPage {
+  render() { return html`<h1>Documentation</h1>`; }
+}
+
+await docs.export(DocsPage, { outDir: 'dist', publicDir: 'public' });
+```
+
+`defineSite()` creates runtime-free page decorators, merges and deduplicates shared CSS, inherits head/cache/layout defaults, and derives canonical URLs from `origin`. Shared and page-local styles resolve from the modules that declare them. Layouts receive a trusted page fragment plus the normal render context, run synchronously, and must return `html`. `site.export()` stages a validated, link-free `publicDir` with the rendered pages before touching the destination, rejects case-insensitive public/generated path collisions, never cleans existing output, and includes copied files in its returned `assets` list.
+
+The request exposed to `loading()` and `render()` is deliberately the portable `LivePageRequest` surface: `path`, `url`, `method`, `headers`, `params`, `query`, `body`, and `get(name)`. HTTP rendering supplies these from Express; static export supplies deterministic empty headers, parameters, query, and body values. Framework-specific Express request methods are not part of the page contract.

package/examples/live-html/cards.css

@@ -0,0 +1,36 @@
+:root {
+    color-scheme: dark;
+    font-family: system-ui, sans-serif;
+    background: #111827;
+    color: #f9fafb;
+}
+
+main {
+    width: min(64rem, calc(100% - 2rem));
+    margin: 3rem auto;
+}
+
+.card-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr));
+    gap: 1rem;
+}
+
+.card {
+    padding: 1rem;
+    border: 1px solid #374151;
+    border-radius: .75rem;
+    background: #1f2937;
+}
+
+button {
+    margin-top: 1rem;
+    padding: .7rem 1rem;
+    border: 0;
+    border-radius: .4rem;
+    background: #22d3ee;
+    color: #083344;
+    font: inherit;
+    font-weight: 700;
+    cursor: pointer;
+}