redweb 0.8.0 → 0.10.0

package/client.d.ts

@@ -0,0 +1,42 @@
+// Generated from src/ws/protocol-schema.json by scripts/generate-protocol-types.js.
+export type RedWebProtocolErrorCode =
+    | 'INVALID_MESSAGE'
+    | 'UNKNOWN_HANDLER'
+    | 'HANDLER_FAILED'
+    | 'BINARY_UNSUPPORTED'
+    | 'RATE_LIMITED'
+    | 'QUEUE_FULL'
+    | 'CAPACITY_REACHED'
+    | 'INITIALIZATION_FAILED';
+
+export interface ProtocolMetadata {
+    requestId?: string;
+    sequence?: number;
+}
+
+export interface ProtocolEnvelope<T = unknown> extends ProtocolMetadata {
+    v: string;
+    type: string;
+    payload: T;
+}
+
+export interface ProtocolErrorEnvelope extends ProtocolMetadata {
+    v: string;
+    type: 'error';
+    error: { code: RedWebProtocolErrorCode | string; message: string };
+}
+
+export interface SendableSocket {
+    send(data: string): unknown;
+}
+
+export class ProtocolClient {
+    constructor(socket: SendableSocket, version: string);
+    readonly socket: SendableSocket;
+    readonly version: string;
+    envelope<T>(type: string, payload: T, metadata?: ProtocolMetadata): ProtocolEnvelope<T>;
+    send<T>(type: string, payload: T, metadata?: ProtocolMetadata): void;
+    parse<T = unknown>(input: string | Uint8Array | ArrayBuffer | { data: string | Uint8Array | ArrayBuffer }): ProtocolEnvelope<T> | ProtocolErrorEnvelope;
+}
+
+export const ERROR_CODES: Readonly<Record<RedWebProtocolErrorCode, RedWebProtocolErrorCode>>;

package/client.js

@@ -0,0 +1,55 @@
+const schema = require('./src/ws/protocol-schema.json');
+const { validateEnvelope } = require('./src/ws/protocol-validation');
+
+const ERROR_CODES = Object.freeze(Object.fromEntries(schema.errorCodes.map(code => [code, code])));
+
+function boundedString(value, name, maxLength) {
+    if (typeof value !== 'string' || !value || value.length > maxLength) {
+        throw new TypeError(`${name} must be a non-empty string of at most ${maxLength} characters.`);
+    }
+    return value;
+}
+
+class ProtocolClient {
+    constructor(socket, version) {
+        if (!socket || typeof socket.send !== 'function') throw new TypeError('socket must provide send(data).');
+        this.socket = socket;
+        this.version = boundedString(version, 'version', 64);
+    }
+
+    envelope(type, payload, metadata = {}) {
+        const message = { v: this.version, type: boundedString(type, 'type', 256), payload };
+        if (metadata.requestId !== undefined) {
+            message.requestId = boundedString(metadata.requestId, 'requestId', 256);
+        }
+        if (metadata.sequence !== undefined) {
+            if (!Number.isSafeInteger(metadata.sequence) || metadata.sequence < 0) {
+                throw new TypeError('sequence must be a non-negative safe integer.');
+            }
+            message.sequence = metadata.sequence;
+        }
+        return message;
+    }
+
+    send(type, payload, metadata) {
+        this.socket.send(JSON.stringify(this.envelope(type, payload, metadata)));
+    }
+
+    parse(input) {
+        const raw = input && typeof input === 'object' && 'data' in input ? input.data : input;
+        let serialized;
+        if (typeof raw === 'string') serialized = raw;
+        else if (raw instanceof ArrayBuffer) serialized = new TextDecoder().decode(new Uint8Array(raw));
+        else if (ArrayBuffer.isView(raw)) serialized = new TextDecoder().decode(
+            new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength)
+        );
+        else serialized = raw.toString();
+        const message = JSON.parse(serialized);
+        if (!validateEnvelope(message, this.version)) {
+            throw new TypeError('Received an invalid Redweb protocol envelope.');
+        }
+        return message;
+    }
+}
+
+module.exports = { ProtocolClient, ERROR_CODES };

package/docs/LIVE_HTML.md

@@ -0,0 +1,313 @@
+# 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.
+
+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.
+
+Run the examples immediately with `npm run example:counter`, `npm run example:chatroom`, `npm run example:cards`, and `npm run example:components`. Their checked-in JavaScript artifacts are generated from the decorated TypeScript 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/docs/MULTIPLAYER_OPERATIONS.md

@@ -0,0 +1,50 @@
+# Multiplayer operations
+
+Redweb exposes small composition points and leaves deployment policy to the game. These examples are deliberately infrastructure-neutral.
+
+## Readiness and shutdown
+
+Expose `socketServer.isReady()` from the HTTP stack used by the orchestrator. On termination, call `beginDrain()` first, stop external placement to the node, then call and await `shutdown()`. New upgrades receive `503` after draining begins.
+
+```js
+app.get('/ready', (_request, response) => {
+  response.sendStatus(socketServer.isReady() ? 200 : 503)
+})
+
+process.once('SIGTERM', async () => {
+  socketServer.beginDrain()
+  await socketServer.shutdown()
+})
+```
+
+If `drainHandlers` is enabled, handlers should observe `socket.context.signal` and return promptly. Set the platform termination grace period above the application's maximum cooperative handler time plus `shutdownTimeoutMs`.
+
+## Placement and partitions
+
+The admission `place(principal, request, context)` hook can return another node's `ws`/`wss` URL before upgrade. Keep placement decisions short-lived and retryable. A redirect is not a reservation: the destination must still authenticate, enforce capacity, and reject stale placement.
+
+Treat the distribution adapter as ephemeral fan-out. During broker or network partitions, pause affected matches, continue from one authoritative owner, or reconcile from durable application state. Do not treat adapter delivery or its bounded deduplication window as persistence.
+
+Adapter lifecycle and publish methods receive an optional final `AbortSignal`. Observe it in broker clients that support cancellation. Redweb compensates late startup and subscription completion, but a publish that the broker has already accepted cannot be recalled.
+
+## Capacity signals
+
+Alert on rejected connections, rate-limited messages, full queues, handler failures, active connections, and readiness. Metrics intentionally contain only the route label. Join high-cardinality player, room, and match diagnostics in application logs or traces under the studio's own privacy and retention policy.
+
+Size `maxConnections`, `maxBufferedBytes`, `maxPendingMessages`, room limits, session limits, adapter event limits, and codec byte limits from measured budgets. Run the included verification scripts on the deployment's Node version and instance class before changing those ceilings.
+
+Redweb limits the number and lifetime of session records, but it deliberately does not inspect application session data. Keep that data small, schema-validated, and free of authoritative state that belongs in durable storage.
+
+## Verification
+
+Run `npm test` for unit, real HTTP/WebSocket/WSS integration, fuzz, type-generation, and 100% coverage gates. The additional production gates are:
+
+```bash
+npm run verify:load
+npm run verify:memory
+npm run verify:recovery
+npm run verify:soak
+npm run verify:overhead -- /path/to/redweb-0.8-baseline
+```
+
+The soak defaults to 60 minutes. Shorter durations are useful for CI smoke checks but are not release evidence.

package/docs/PRODUCTION_READINESS.md

@@ -0,0 +1,68 @@
+# Multiplayer production-readiness contract
+
+Redweb remains a small transport foundation. Applications own game rules, authoritative state, matchmaking, databases, and identity providers. Redweb owns bounded connection admission, delivery, grouping, lifecycle, and optional composition points.
+
+## Compatibility invariants
+
+- Every production feature is opt-in.
+- Existing route, handler, and service subclasses require no source changes.
+- The default route, strict routing, IP collision policy, handler dispatch, error hiding, listener ownership, and shutdown behavior remain compatible with 0.8.
+- Disabled multiplayer features create no timers or per-connection queues.
+- No global mutable registry or mandatory infrastructure dependency is permitted.
+- Every timer, listener, queued task, membership, session lease, and adapter subscription has one deterministic cleanup owner.
+- User hooks may be synchronous or asynchronous and may not escape as process-level failures.
+- Cleanup is bounded, idempotent, best-effort, and continues after individual failures. Owned listeners also terminate incomplete HTTP peers at the route deadline; borrowed listeners remain application-owned.
+
+## Delivery claims
+
+WebSocket provides an ordered byte stream while a connection remains healthy. Redweb does not claim exactly-once delivery. Reconnection, distributed adapters, and application retries can introduce loss or duplication; protocol users must use explicitly scoped sequence identifiers when those cases matter.
+
+## Roadmap gates
+
+1. **Bounded transport:** pre-upgrade admission, origin policy, rate limits, slow-consumer enforcement, bounded ordered processing, payload limits, and route-level heartbeat.
+2. **Multiplayer grouping:** route-scoped rooms, atomic membership cleanup, bounded session resumption, fixed-step services, and vendor-neutral metrics.
+3. **Horizontal composition:** draining/readiness, adapter lifecycle, loop prevention, bounded validation, placement hooks, and documented partition behavior.
+4. **Protocol and clients:** version negotiation, stable envelopes and error codes, generated client-facing types, binary replication hooks, and operational examples.
+
+## Release gates
+
+- Existing tests and documented examples run unchanged.
+- New behavior has unit tests and mock-free HTTP/WS/WSS integration tests.
+- Coverage remains 100% for statements, branches, functions, and lines.
+- Disabled-feature throughput regression is at most 3%; p99 latency regression is at most 5% on the same machine and Node version.
+- Heartbeat uses one scheduler per route, never one interval per connection.
+- Every queue, retained session, room, adapter backlog, and deduplication window is finite.
+- Broadcast serializes once and remains O(n) in selected recipients.
+- Slow clients cannot grow framework-owned memory without bound.
+- A 60-minute soak shows no monotonic growth in timers, listeners, rooms, sessions, or queues.
+- Reconnect storms return retained heap to within 10% of the warmed baseline after expiry and forced collection.
+- Readiness becomes false before draining and shutdown completes within its documented bound.
+
+The independent senior-review gate rejects releases that weaken any invariant, hide ambiguous delivery semantics, add mandatory brokers or identity libraries, or substitute coverage percentages for race, load, soak, and failure evidence.
+
+## Horizontal composition contract
+
+- Placement runs before upgrade within the admission timeout. Redirects must use `wss`, contain no credentials or fragment, and may be restricted with `allowedPlacementOrigins`. Plain `ws` placement requires the explicit `allowInsecurePlacement` escape hatch for private development networks.
+- Readiness becomes false before shutdown work begins. New upgrades receive `503`; existing connections stop accepting messages.
+- `drainHandlers` is opt-in. When enabled, every connection context shares the route drain signal and shutdown awaits tracked work. Application handlers remain responsible for observing the signal; non-cooperating promises cannot be forcibly cancelled.
+- Distribution adapters have no framework backlog. Publish and inbound concurrency are finite; publish failure returns `false`; startup, subscription, unsubscription, draining, and close are bounded. Adapter operations receive an optional `AbortSignal`, and late startup/subscription settlement is compensated. Adapters must observe the signal when their external side effects are not otherwise reversible.
+- A failed publish marks a `required` adapter unhealthy, makes the route unready, and causes new upgrades to receive `503`; a later successful publish restores health. Best-effort adapters do not affect route readiness.
+- Event IDs are deduplicated only inside a finite TTL/size window. Source-node events are ignored to prevent reflection loops.
+- Broker partitions and process failure can lose events. Redweb makes no exactly-once or durable-delivery claim; applications own authoritative persistence, reconciliation, tick/sequence semantics, and partition policy.
+
+## Protocol contract
+
+- Negotiation is opt-in and happens before upgrade. Unsupported clients receive `426` plus the finite supported-version list.
+- JSON events use `{ v, type, payload, requestId?, sequence? }`. Error events use `{ v, type: "error", error: { code, message }, requestId? }`.
+- `requestId` correlates a request and response; `sequence` expresses application ordering. Neither implies acknowledgement, durability, or exactly-once delivery.
+- Stable framework codes are generated from `src/ws/protocol-schema.json`; the client declarations and runtime constants share that source.
+- Binary replication is a codec hook, not a codec dependency. Size is checked before decode and after encode, and outbound data uses the normal backpressure ceiling.
+- Protocol-disabled routes retain their 0.8 wire shapes and allocate no protocol context.
+
+## Resource ownership
+
+- `maxPendingUpgrades` bounds authorization work before a socket is accepted.
+- Timed-out admission hooks that ignore cancellation retain their reservation until they actually settle, preventing repeated timeout waves from accumulating unbounded application work.
+- Fixed-step services clamp retained lag with `maxRetainedLagMs`; dropped time is observable rather than replayed forever.
+- Session count, ID length, and lifetime are bounded by Redweb. Session `data` is application-owned, so applications must validate and cap its shape and byte size before storing it.
+- Fully enabled idle routes have a 2 KiB framework-metadata budget per connection. Disabled features retain the legacy path and are compared against 0.8 by the performance gate.

package/docs/VERIFICATION_EVIDENCE.md

@@ -0,0 +1,20 @@
+# 0.9.0 verification evidence
+
+Release-candidate measurements were taken on Windows x64, Node 22.21.0, and an AMD Ryzen 7 7800X3D. Performance numbers are machine-specific; the scripts and thresholds are the durable contract.
+
+## Automated correctness
+
+- 290 unit and mock-free integration/fuzz tests pass on Node 18, 20, and 22.
+- Statements, branches, functions, and lines are each 100% covered.
+- Type declarations compile and generated protocol declarations match their schema.
+
+## Resource and failure gates
+
+- Real-socket load: 32 concurrent clients, 3,200 request/response messages, 6,874 messages/second, 5.87 ms p99, with a paused slow consumer disconnected by the outbound-buffer policy.
+- Reconnect recovery: 200 warm connections followed by 1,200 storm connections; retained heap recovered to 104.33% of warm baseline and connection, room, and session registries returned to zero.
+- Fully enabled idle-route metadata: 1,756.93 bytes per connection across the median of three 500-connection trials, below the 2,048-byte gate.
+- Disabled-feature comparison with Redweb 0.8: throughput improved 1.09% and p99 regressed 2.00% (limits: 3% and 5%), using five alternating 20,000-message trials at concurrency 128.
+- `npm audit` reports zero vulnerabilities after upgrading Express to 4.22.2, `ws` to 8.21.3, and patched transitive dependencies.
+- The corrected 60-minute soak sent 2,099,717 messages across 64 rotating clients and received 2,099,565 responses (99.993%). Steady-state clients, rooms, sessions, in-flight work, queued work, listeners, and Redweb-owned timers showed no sustained growth; late-window heap was 3.24% above the early window, within the 10% gate. Final heap was 100.04% of the warmed baseline; all registries returned to zero; active handles stayed within the one-handle allowance.
+
+All measurements above were rerun on the final release candidate. Shortened soak smoke runs are not counted as release evidence.

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;
+}

package/examples/live-html/cards.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Redweb cards</title></head>
+<body>
+    <main>
+        <h1>Server-rendered cards</h1>
+        <section class="card-grid" aria-live="polite" rw-each="cards"></section>
+        <button type="button" rw-click="add">Add a card</button>
+    </main>
+</body>
+</html>