redweb 0.13.5 → 0.15.0

package/contract.d.ts

@@ -15,9 +15,17 @@ export interface SocketSchema<Input = unknown, Output = Input> {
 export type SocketSchemas = Readonly<Record<string, SocketSchema>>;
 export type ContractInput<Schema extends SocketSchema> = NonNullable<Schema['~standard']['types']>['input'];
 export type ContractOutput<Schema extends SocketSchema> = Awaited<NonNullable<Schema['~standard']['types']>['output']>;
-export type ContractMessage<Schemas extends SocketSchemas> = {
+export type ContractMessage<Schemas extends SocketSchemas> = {
     [Type in keyof Schemas & string]: ProtocolEnvelope<ContractOutput<Schemas[Type]>> & { type: Type };
-}[keyof Schemas & string];
+}[keyof Schemas & string];
+
+declare const socketActionBrand: unique symbol;
+export interface SocketAction { readonly [socketActionBrand]: true; }
+export interface SocketHandler<Input> {
+    new (): BaseHandler;
+    /** Bind a JSON payload to a server-rendered rw-click/rw-submit control. */
+    with(payload: Input): SocketAction;
+}
 
 export interface ContractClient<Schemas extends SocketSchemas> {
     envelope<Type extends keyof Schemas & string>(type: Type, payload: ContractInput<Schemas[Type]>, metadata?: ProtocolMetadata):
@@ -36,7 +44,7 @@ export interface SocketContract<Schemas extends SocketSchemas> {
     handler<Type extends keyof Schemas & string>(type: Type, callback: (
         socket: RedWebSocket, payload: ContractOutput<Schemas[Type]>,
         message: ProtocolEnvelope<ContractOutput<Schemas[Type]>> & { type: Type },
-    ) => unknown): new () => BaseHandler;
+    ) => unknown): SocketHandler<ContractInput<Schemas[Type]>>;
     client(socket: SendableSocket): ContractClient<Schemas>;
     send<Type extends keyof Schemas & string>(socket: RedWebSocket, type: Type, payload: ContractInput<Schemas[Type]>, metadata?: ProtocolMetadata): Promise<boolean>;
 }

package/docs/APPLICATION.md

@@ -0,0 +1,98 @@
+# One application, one listener
+
+`defineApp()` describes the application. `await app.run()` initializes it and opens one port for HTTP pages and WebSocket routes. You do not create an HTTP server and then pass it to a second socket server.
+
+Added in Redweb 0.14.0. Earlier releases do not export `defineApp`.
+
+## The entry point
+
+In a Redweb TypeScript project, the application can be as small as:
+
+```tsx
+import { defineApp, page, action, state } from 'redweb';
+
+@page('/', { shared: true })
+class HomePage {
+    @state() count = 0;
+    @action() increment() { this.count += 1; }
+    render() {
+        return <main><h1>Hello</h1><button rw-click="increment">Count {this.count}</button></main>;
+    }
+}
+
+@page('/about', { live: false })
+class AboutPage {
+    render() { return <main><h1>About this app</h1></main>; }
+}
+
+const app = defineApp({ pages: [HomePage, AboutPage], port: 8181 });
+
+async function main() {
+    await app.run();
+}
+void main().catch(error => { console.error(error); process.exitCode = 1; });
+```
+
+The final error handler is for this CommonJS TypeScript entry point; an ESM project that permits top-level await can simply use `await app.run()`. A module that is also imported by tests should export its application definition and guard its entry-point invocation with `require.main === module`. Importing a definition never opens a port or installs signal handlers.
+
+## Add socket routes and services
+
+The same definition accepts all three registration arrays:
+
+```ts
+const app = defineApp({
+    pages: [HomePage, AboutPage],
+    sockets: [MatchRoute, ChatRoute],
+    services: [GameSimulation],
+    port: 8181,
+});
+
+await app.run();
+```
+
+These names refer to your application's classes. A page's decorator chooses its HTTP path. A `SocketRoute` chooses its WebSocket path, such as `/match`; its handlers dispatch `join`, `move`, and `resume` by message `type`. Live-page connections and custom socket routes share one upgrade listener. Do not register a custom socket route at the live-page socket path.
+
+In five-year-old terms: the app has one front door. Pages are ordinary visits, sockets are ongoing conversations, and services are the staff who prepare the building before the door opens and clean up after it closes.
+
+`services` are application-wide lifecycle classes, not HTTP endpoint descriptors or route-specific `SocketService` classes:
+
+```ts
+import type { ApplicationContext, ApplicationService } from 'redweb';
+
+class GameSimulation implements ApplicationService {
+    private timer?: ReturnType<typeof setInterval>;
+    private ticks = 0;
+
+    onInit(app: ApplicationContext, signal: AbortSignal) {
+        signal.throwIfAborted();
+        app.app.get('/health', (_request, response) => response.json({ ticks: this.ticks }));
+        this.timer = setInterval(() => { this.ticks++; }, 1000);
+    }
+
+    onShutdown() { clearInterval(this.timer); }
+}
+```
+
+Keep constructors inert. Acquire resources in `onInit(app, signal)` and release them in `onShutdown()`. Initializers run in registration order before the port opens; cleanup runs in reverse order, including the service whose initialization failed. Asynchronous methods are supported. Pass the abort signal to cancelable work and make cleanup safe after partial initialization. A deadline cannot stop arbitrary code that ignores cancellation or blocks the event loop.
+
+Use `httpServices` for the existing HTTP endpoint descriptor array. Keep route-specific `SocketService` registrations on their `SocketRoute`. For an existing Express application, pass it as `server`; Redweb still creates and owns the underlying Node listener. The low-level server classes remain available for applications that explicitly manage their own listener ownership.
+
+## Lifecycle contract
+
+- Definitions are deferred. `app.server`, `app.app`, `app.http`, and `app.sockets` are initially `null`. Await `run()` before accessing their runtime values; its returned value has non-null HTTP members in TypeScript.
+- `pages`, `sockets`, and `services` are optional. HTTP-only, socket-only, and non-live-page applications use the same entry point. Non-live pages need no WebSocket server unless custom socket routes were supplied.
+- Repeated `run()` calls share the pending or successful startup promise while the application is running. `shutdown()` is idempotent. A stopped application cannot restart; define a new application instead.
+- Startup failure rolls back resources before rejection, subject to the shutdown deadline. Cleanup failures are retained alongside the original startup error, not reported as success.
+- `startupTimeoutMs` and `shutdownTimeoutMs` default to 5000. Each is one total application budget, not a fresh full timeout for every service. Shutdown cancels pending startup, closes admission, attempts page/socket cleanup, closes owned connections, and releases services.
+- `signals: true` is the default. Signal handlers are installed when `run()` begins, so SIGINT/SIGTERM also cancel pending initialization. Unexpected listener closure and listener errors trigger owned shutdown. Repeated signals do not bypass active cleanup. Failed process-owned cleanup sets a failure exit status and retains a deadline for leaked handles. Explicit `shutdown()` rejects on cleanup failure but never forcibly exits its caller.
+- Tests and embedded applications should set `signals: false` and call `shutdown()` in their own cleanup. Use `port: 0` for an OS-assigned test port. TLS uses the existing `ssl` key/certificate options and shares one HTTPS/WSS listener.
+
+## Boundaries
+
+This is application composition, not dependency injection, a distributed worker manager, or durable storage. It does not automatically inject services into page constructors. `shared: true` shares in-process state across visitors, not across server processes or restarts. Static file export remains the separate `exportStatic()` API; a non-live page served over HTTP is not a static export.
+
+`app.revoke(principal)` revokes matching live-page sessions and returns their count; it returns zero when no live-page server has been created. `app.inspect()` exposes opt-in development metadata and otherwise returns `null`. These preserve the same live-page policies as `start()`.
+
+`app.options` is the copied definition. An independent test instance can use `defineApp({ ...app.options, port: 0, signals: false })`, followed by `await run()` and owned cleanup. This creates new page/service instances, but does not clone an Express application or objects deliberately captured by class closures. The chat module exports a default `ChatroomPage`; its optional `createChatroomPage()` factory creates isolated rooms for separate apps or tests.
+
+For rendering and CSS see [Live HTML](LIVE_HTML.md). For message validation and handler classes see [socket contracts](SOCKET_CONTRACTS.md). For deployment and persistence boundaries see [operations](MULTIPLAYER_OPERATIONS.md).

package/docs/CLI.md

@@ -4,7 +4,7 @@ Use the version installed in your project (`npx --no-install redweb`) when troub
 
 ## Add pages, components, and socket routes
 
-These commands are available in `redweb@0.13.5`.
+These commands are available in `redweb@0.15.0`.
 
 ```sh
 npx --no-install redweb add page dashboard

package/docs/CLIENT_DEVELOPMENT.md

@@ -1,12 +1,16 @@
 # Developing Redweb with redweb-client
 
 The Live HTML implementation is maintained in published `redweb-client/live-html`
-starting with client 0.2.0. This Redweb development branch requires `^0.2.0`;
+starting with client 0.2.0. Redweb 0.15.0 requires client `^0.3.0`;
 normal application installation retrieves it automatically. The linking workflow
 below is optional for contributors editing both repositories.
 Redweb serves that module and emits only its import and `mountLivePage()` call.
-DOM reconciliation, reactive updates, delegated actions, form feedback and page
-disposal belong to the client. The root `redweb-client` entry remains socket-only.
+DOM reconciliation, reactive updates, delegated actions, form feedback and page
+disposal belong to the client. The root `redweb-client` entry remains socket-only.
+
+Socket-bound TSX command bindings and terminal-response filtering use the published
+client 0.3.0 runtime. No link is needed for applications using Redweb 0.15.0.
+See [socket pages](SOCKET_PAGES.md).
 
 ## Link the sibling repositories
 
@@ -107,7 +111,7 @@ For example, from Redweb in PowerShell (use a fresh output directory):
 npm --prefix ../redweb-client run build
 New-Item -ItemType Directory -Path coverage/client-candidate
 npm pack ../redweb-client --pack-destination coverage/client-candidate
-$env:REDWEB_CLIENT_CANDIDATE = (Resolve-Path coverage/client-candidate/redweb-client-0.2.0.tgz).Path
+$env:REDWEB_CLIENT_CANDIDATE = (Resolve-Path coverage/client-candidate/redweb-client-0.3.0.tgz).Path
 npm run verify:live-html:package
 Remove-Item Env:REDWEB_CLIENT_CANDIDATE
 ```
@@ -143,7 +147,7 @@ bundles with the source-tested local build and run the same browser checks.
 A candidate pass is not a registry release pass. `npm run verify:package:tools` includes the fingerprint/containment
 unit regressions; its scoped coverage is not coverage of every browser driver.
 
-Published `redweb-client@0.2.0` supplies both required entry points; version 0.1.0
+Historically, published `redweb-client@0.2.0` supplied both required entry points; version 0.1.0
 does not. The 0.2.0 archive's runtime bundles match the previously source-tested
 build, and the clean registry-installed package gate passes without an override.
 The developer link can remain in place because registry checks own independent

package/docs/COVERAGE_SCOPE_AUDIT.md

@@ -1,5 +1,12 @@
 # Coverage scope and remaining work
 
+> This is a historical coverage inventory. Following the `defineApp` migration,
+> the generated `run-app` helper and its separate verifier no longer exist.
+> Current lifecycle coverage targets `Application` and `StartupCleanup` via
+> `verify:starters:lifecycle:coverage`; authored starter coverage remains under
+> `verify:starters:source-coverage`. Older results below do not establish coverage
+> of the current release candidate.
+
 This inventory separates shipped authored code from verification machinery.
 Passing behavior tests do not establish complete coverage; a coverage report's
 instrumentation hash alone does not prove correspondence with current source.

package/docs/DEFINE_APP_VERIFICATION.md

@@ -0,0 +1,101 @@
+# Unified application verification
+
+Implementation history for `codex/define-app`. These are scoped results recorded
+during development, not a substitute for final release status. The exact-head
+checks and reviewer discussion are retained in
+[PR #23](https://github.com/lakam99/redweb/pull/23).
+
+## Starter migration (2026-09-01, Windows / Node 22.21.0)
+
+- `verify:starters:lifecycle:coverage`: 72 unit and real HTTP/WebSocket/process
+  tests pass. `Application.js` and `StartupCleanup.js` are 100% covered in
+  statements, branches, functions, and lines.
+- The CLI templates, `SourceInspector`, and `Documentation` reach all-four 100%
+  with 80 unit/source-repair integration tests. The narrower unit-only command
+  does not cover external template inspection; include the action-reference and
+  doctor-source suites when reproducing this scope.
+- `verify:starters:source-coverage` passed for all six original TypeScript
+  applications, separately from compiler-generated JavaScript coverage. The
+  retained run is `coverage/starter-source/a011d72d-1450-409f-935a-d21623c582a6/`.
+  Its summary records input/report hashes and the actual source inventories.
+- `verify:starter:browser:coverage`: 30 tests pass, including headed counter,
+  chatroom, and multi-page site interactions from compiled/source-removed apps.
+- `verify:dashboard:coverage`: 27 tests pass, including headed rejected/accepted
+  login, private cards, draft preservation, logout/relogin, and deletion.
+- The six generated applications pass real-network tests. Their shared process
+  test imports inert definitions, runs each application, closes it via signals
+  or native listener closure, and checks occupied-port startup failure. Windows
+  exercises Node signal events; Linux exercises delivered OS signals.
+
+The independent reviewer found no runtime blocker in the migration. The stale
+generated-helper report is now explicitly historical. The copied `run-app`
+implementation was removed, not retained beside the library lifecycle owner.
+
+An earlier interrupted full-suite run had a browser-control failure before its
+intended negative assertion. A standalone rerun passed all four working controls
+and seven intentional faults (63.9 seconds), without changing the control or
+weakening its assertions. That does not establish the cause of the earlier
+failure or replace a completed full-suite run. Final regression, package, CI,
+release-catalogue, and exact-PR-head review remain outstanding.
+
+No soak or long fixed-window acceptance test was run for this migration.
+
+## Follow-up regression repair
+
+The earlier Linux CI matrix exposed `StartupCleanup` replacing native errors
+from another JavaScript context with a generic error. The existing owned-listener
+integration reproduced both failures locally. Using Node's `isNativeError`
+preserves the original error identity/message without treating arbitrary thrown
+values as native errors. A real VM-context regression was added; lifecycle
+coverage is now 73 passing tests at all-four 100%, and all eight owned-listener
+integration tests pass. The VM/owned-listener suites also pass on Node 18.
+
+CI also identified an obsolete test-count assertion in the starter coordinator's
+input-mutation check. Its expected successful fixture now includes one realtime
+test and four application-entrypoint tests; failure-on-input-mutation assertions
+are unchanged.
+
+The reviewer caught a Node 18 distinction: `DOMException` is an `Error` there
+but is not recognized by `isNativeError`. Keeping both checks preserves native
+abort-reason identity as well as foreign-context errors. A native-process abort
+regression passes on Node 18 and 22; the lifecycle scope now has 74 passing tests
+and all-four 100% coverage. The corrected starter coordinator gate passes all
+56 tests with all-four 100% coverage of its three coordinator modules.
+
+## Release catalogue checks
+
+The prepared package and lockfile are `0.14.0`. The 68-page generated catalogue
+matches `docs/releases/0.14.0.json`; older release snapshots were not edited.
+The package dry run includes the unified runtime and shared entrypoint tests,
+and the release-documentation guard passes. No package was published.
+
+The optional docs MCP adapter previously hard-coded an unreleased-channel
+expectation. Its tests now compare against the loaded canonical channel and
+exercise both valid channel variants. All seven tests pass, including actual
+MCP subprocesses and isolated production-only package installation; all three
+adapter modules have 100% line, branch, and function coverage.
+
+## Broader regression findings
+
+The first completed Windows run finished with 174 passing suites and four
+failing suites (1,984 passing tests, seven failures, five skips). It began before
+the final source repairs and version update, so it is not final-head evidence.
+
+- The standalone-example unit launcher still stubbed `start`. It now explicitly
+  tests `defineApp().run()` and its rejection handler. Both original-TypeScript
+  coverage runs (standard and legacy decorators) pass with unchanged real page
+  behavior checks alongside the separately labelled launcher units.
+- Current guide version labels were left at 0.13.5. They now match 0.14.0; the
+  candidate catalogue was corrected before publication. No published release
+  snapshot was changed. The documentation unit/coverage and release guard pass.
+- The HTML load workload timed out awaiting disconnected-session expiry. Its
+  unchanged standalone replay passed: 200 expired renders, 110 clients, and
+  8,288,824 bytes heap growth. A standalone pass does not establish the earlier
+  timeout's cause.
+- Server recovery reproduced a server-connection cleanup timeout in isolation.
+  Evidence remains in `coverage/server-recovery-candidate-kFjY7N/`; this failed
+  run is not acceptance. Its limits and workload have not been weakened.
+
+Coverage review also added real acceptance for non-live pages with custom
+socket routes and direct invalid socket-registration validation. Later exact-head
+test results and any further repairs belong to the PR's final verification record.

package/docs/DEVELOPMENT.md

@@ -1,6 +1,6 @@
 # Development refresh and inspection
 
-This API is available in `redweb@0.13.5`. Use documentation matching the installed package before enabling it.
+This API is available in `redweb@0.15.0`. Use documentation matching the installed package before enabling it.
 
 ## Browser refresh
 

package/docs/GETTING_STARTED.md

@@ -47,7 +47,7 @@ For private raw socket subscriptions, see [room authorization and shared request
 
 Build first. Deploy `dist/`, the package manifest, and the lockfile, then install runtime dependencies with `npm ci --omit=dev`. The starters are tested with `src/` unavailable after compilation. Configure HTTPS/WSS and a proxy that supports WebSocket upgrades when using a reverse proxy.
 
-These deployment commands require a verified release pair. `redweb@0.13.5` installs published `redweb-client@0.2.0` automatically through its dependency. Future unreleased Redweb changes require their matching tested tarball until a release containing them is published. The `npm link` workflow is local development only: a clean production install does not preserve that link.
+These deployment commands require a verified release pair. `redweb@0.15.0` installs published `redweb-client@0.3.0` automatically through its dependency. Future unreleased Redweb changes require their matching tested tarball until a release containing them is published. The `npm link` workflow is local development only: a clean production install does not preserve that link.
 
 Before public access, add authentication, authorization, trusted-origin policy, input/rate limits, application persistence where needed, and bounded shutdown. Treat reconnect/session tokens as credentials. Do not promise exactly-once delivery or durable sessions from an in-memory starter. See [operations](MULTIPLAYER_OPERATIONS.md) and [guarantees and limits](PRODUCTION_READINESS.md).
 

package/docs/LIVE_HTML.md

@@ -340,7 +340,7 @@ The same bounded validation implementation is shared with socket contracts. Thei
 
 ## Action authorization
 
-Identity and permission are separate: the server's existing `authenticate(request)` hook establishes `context.principal`; an action policy decides whether that identity may perform this operation. In Redweb 0.13.5, add `authorize` to the action decorator instead of repeating permission checks inside each method:
+Identity and permission are separate: the server's existing `authenticate(request)` hook establishes `context.principal`; an action policy decides whether that identity may perform this operation. In Redweb 0.15.0, add `authorize` to the action decorator instead of repeating permission checks inside each method:
 
 ```tsx
 // Inside a page/component; `input` is the amount schema from the example above.
@@ -365,7 +365,7 @@ Denial returns recoverable `ACCESS_DENIED`; timeout returns `ACCESS_TIMEOUT`; co
 
 ## Protected pages and shared request identity
 
-In Redweb 0.13.5, a page can declare `authorize(context)` alongside its route. This is an API pattern for an application that already supplies the server's `authenticate(request)` hook, not a standalone login system:
+In Redweb 0.15.0, a page can declare `authorize(context)` alongside its route. This is an API pattern for an application that already supplies the server's `authenticate(request)` hook, not a standalone login system:
 
 ```tsx
 @page('/account/:id', {

package/docs/MIGRATION.md

@@ -1,6 +1,6 @@
 # Upgrade an existing Redweb application
 
-Match the installed package to its versioned documentation. Redweb 0.13.5 contains the capabilities described by the 0.13.5 guides; a later development checkout may not match that release. See [release verification](RELEASE_TRUST.md) and the changelog shipped with your selected package. Keep your lockfile and rollback artifact, and run your own real HTTP/WebSocket/browser tests after upgrading.
+Match the installed package to its versioned documentation. Redweb 0.15.0 contains the capabilities described by the 0.15.0 guides; a later development checkout may not match that release. See [release verification](RELEASE_TRUST.md) and the changelog shipped with your selected package. Keep your lockfile and rollback artifact, and run your own real HTTP/WebSocket/browser tests after upgrading.
 
 ## 0.8 migration notes
 

package/docs/MULTIPLAYER_OPERATIONS.md

@@ -19,6 +19,12 @@ process.once('SIGTERM', async () => {
 
 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`.
 
+## Closing connections
+
+Once a WebSocket closing handshake starts, Redweb lets the native `ws` transport finish it for up to 5000ms, then terminate the peer if necessary. This releases connections that exchange close frames but never finish TCP shutdown. Configure `websocketOptions: { closeTimeout: 10000 }` on a route if its peers need longer; values must be integers from 1 through 2147483647 milliseconds.
+
+This is not an idle timeout: healthy open connections are unaffected. Heartbeats detect unresponsive open peers, session TTL controls retained application state after disconnection, and `shutdownTimeoutMs` separately bounds route shutdown.
+
 ## 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.

package/docs/RELEASE_TRUST.md

@@ -16,20 +16,43 @@ Redweb is a Node.js HTTP/WebSocket library with server-rendered TSX, not a hoste
 
 Use the [official Node release schedule](https://nodejs.org/en/about/previous-releases) for maintained releases, the [TypeScript decorator documentation](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#decorators) for the distinction between decorator modes, and [Node's TypeScript limitations](https://nodejs.org/api/typescript.html) for native execution constraints. Current per-commit test evidence and uncompleted checks are recorded in the [release checklist](AGENT_READY_ACCEPTANCE.md), not inferred from this table.
 
-## Pin the package and the documentation together
-
-For a published application, select an exact release, commit its lockfile, and use `npm ci` in CI/deployment. This guide is versioned for 0.13.5. Before registry publication, verify the packed candidate; after publication, repeat these registry checks from a clean application:
+## Pin the package and the documentation together
+
+### Temporary Express 4 dependency mitigation
+
+As verified on 2026-09-02, Express 4.22.2 selects `qs ~6.15.1`; the maintainer's
+[isBuffer advisory](https://github.com/ljharb/qs/security/advisories/GHSA-4mjr-xmp4-gh2g)
+and [bracket-key advisory](https://github.com/ljharb/qs/security/advisories/GHSA-x5fp-wj9c-mxmx)
+identify patched `qs@6.16.0`. Until compatible upstream ranges select that fix,
+use this temporary mitigation in the **application's root** `package.json`:
+
+```json
+{ "overrides": { "express": { "qs": "6.16.0" } } }
+```
+
+Merge it with existing overrides, run `npm install`, commit the resulting lockfile,
+and verify with `npm ls qs`, `npm audit --omit=dev`, and application HTTP/form tests.
+New generated starters include the same policy. It is scoped to Express so it
+does not force unrelated dependency trees onto another `qs` version.
+
+This is an application-level mitigation, not a transparent fix for every Redweb
+consumer. [npm ignores overrides inside installed dependencies](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/#overrides).
+An ordinary installation without this root policy can still select affected
+dependencies. No Express 5 migration, bundled fork or published shrinkwrap is
+introduced. Audit results remain time-sensitive and application-specific.
+
+For a published application, select an exact release, commit its lockfile, and use `npm ci` in CI/deployment. This guide is versioned for 0.15.0. Before registry publication, verify the packed candidate; after publication, repeat these registry checks from a clean application:
 
 ```sh
-npm view redweb@0.13.5 version engines dist.integrity dist.signatures dist.attestations gitHead --json
-npm install --save-exact redweb@0.13.5
+npm view redweb@0.15.0 version engines dist.integrity dist.signatures dist.attestations gitHead --json
+npm install --save-exact redweb@0.15.0
 npm audit signatures
 npm audit --omit=dev
 ```
 
 The signature command must run in the installed application directory. Keep TLS verification enabled and use a current npm CLI; a certificate/trust-store failure is not a reason to disable verification. A lockfile's integrity value detects changed package bytes; registry signatures authenticate registry metadata; provenance, when present and verified, links an artifact to a build/source identity. Vulnerability audit is a separate check against known advisories, not an application penetration test.
 
-Redweb 0.13.5 contains the server-rendered TSX, reactive state/actions, complete starters, shared socket contracts, authorization, diagnostics, lifecycle work, and bounded heartbeat grace described by these versioned guides. Keep the package and documentation version aligned; do not mix a development guide or a future checkout with 0.13.5 and assume newer APIs exist.
+Redweb 0.15.0 contains socket-bound TSX controls and connection-owned page state, unified application startup, server-rendered TSX, reactive state/actions, complete starters, shared socket contracts, authorization, diagnostics, lifecycle work, and bounded heartbeat grace described by these versioned guides. Keep the package and documentation version aligned; do not mix a development guide or a future checkout with 0.15.0 and assume newer APIs exist.
 
 Redweb is pre-1.0. Consult the changelog and versioned guide before upgrading, run your own real HTTP/WebSocket/browser tests, and keep a rollback artifact. Patch/minor numbers and a compatible TypeScript build alone do not prove wire compatibility, preserved sessions, database compatibility or application authorization. HTTP-created live-page sessions are process-owned; a restart or rolling replacement does not migrate them automatically. Raw socket protocol versions are negotiated only when the route opts in, and application payload compatibility remains your contract.
 

package/docs/RUNTIME_DIAGNOSTICS.md

@@ -1,6 +1,6 @@
 # Understand failures before retrying
 
-Status: included in `redweb@0.13.5`.
+Status: included in `redweb@0.15.0`.
 
 Authentication identifies a visitor. Authorization decides what that visitor may do. Validation checks an input's shape. An application failure means server code or a dependency failed; it is not evidence that the visitor supplied bad credentials.
 

package/docs/SOCKET_CONTRACTS.md

@@ -1,16 +1,19 @@
 # Shared socket contracts
 
-Status: included in `redweb@0.13.5`.
+Status: included in `redweb@0.15.0`.
 
 A contract declares message payloads once. The same schema supplies runtime validation and inferred TypeScript types for senders and handlers. The URL still selects the route (`/match`), and the envelope's `type` selects an individual handler (`join`, `move`, `resume`). No socket decorators or second action dispatcher are required.
 
-Start with `npx --yes redweb@0.13.5 init my-match --template socket`. The complete maintained example lives in [the socket recipe](../recipes/socket/README.md): [contract](../recipes/socket/contract.ts), [handlers](../recipes/socket/handlers.ts), [server](../recipes/socket/app.tsx), and [real-network tests](../recipes/socket/app.test.cjs).
+Start with `npx --yes redweb@0.15.0 init my-match --template socket`. The complete maintained example lives in [the socket recipe](../recipes/socket/README.md): [contract](../recipes/socket/contract.ts), [handlers](../recipes/socket/handlers.ts), [server](../recipes/socket/app.tsx), and [real-network tests](../recipes/socket/app.test.cjs).
 
 Session ownership is separate from room fan-out. For authenticated group delivery,
 see [room authorization](ROOM_AUTHORIZATION.md) and the complete
 [shared page/private-room example](snippets/room-access.tsx).
 
-## One schema, two sides
+## One schema, two sides
+
+Redweb 0.15.0 also supports [typed handlers in server TSX](SOCKET_PAGES.md)
+with per-connection page state; earlier releases do not include that extension.
 
 Import `defineSocketContract` from `redweb/contract` for a shared module, or from `redweb` in server-only code. The standalone entry does not import the HTTP server or Node socket listener. Browser consumers need a bundler capable of consuming the CommonJS package; this is not a native browser script URL or a React integration.
 

package/docs/SOCKET_PAGES.md

@@ -0,0 +1,99 @@
+# Server-side TSX for custom socket routes
+
+Added in Redweb 0.15.0 with redweb-client 0.3.0, installed automatically by Redweb.
+Earlier Redweb 0.14.0/client 0.2.0 packages do not provide this extension.
+Contributors editing both packages can use the optional npm-link workflow in the repository's `docs/CLIENT_DEVELOPMENT.md`.
+
+A live page can attach to a registered custom `SocketRoute` using
+`@page('/', { socket: MatchRoute })`. There is no new view class, no second renderer,
+and no application-specific browser module. Its connection carries ordinary typed
+commands and reserved `redweb:*` rendering/completion messages.
+
+## Typed controls
+
+`defineSocketContract(...).handler(type, callback)` still returns a handler class.
+That class can now be used as a JSX binding:
+
+```tsx
+<form rw-submit={Join}>
+    <input name="room" required />
+    <button>Join room</button>
+</form>
+
+<button rw-click={Move.with({ cell, revision })}>Move</button>
+```
+
+`.with()` snapshots JSON data; it never invokes the handler during rendering.
+TypeScript checks the payload's input type. Incoming wire data is independently
+validated by the contract, including asynchronous schemas. Form fields merge over
+the bound object payload. A click sends its bound payload, or an empty object when
+none was supplied. Bound values are untrusted inputs, not server-held secrets or
+authorization capabilities. Do not embed private data in them.
+
+Bindings are server-owned identities, not arbitrary function closures. Rendering
+rejects references to handlers absent from the attached route, even if a different
+handler has the same message name. Existing string `rw-click`/`rw-submit` actions
+remain unchanged on ordinary live pages. Socket-bound pages dispatch only their
+custom route handlers; do not mix local `@action()`/`rw-bind` commands into them.
+
+## Server-owned client state
+
+On an attached connection, `socket.page(PageClass)` returns that connection's
+concrete page after checking its class, ownership and active lifetime:
+
+```ts
+if (socket.page) {
+    socket.page(GamePage).game = games.snapshot(room, account);
+}
+```
+
+Assigning `@state()` fields uses the existing reactive renderer and keyed TSX.
+Raw connections have no `page` accessor and keep their existing socket protocol.
+Shared domain state belongs in a room/service; each private page receives only its
+authorized perspective. Components remain ordinary page-owned Redweb components.
+
+## Configuration and boundaries
+
+Register the route once in `defineApp({ pages: [GamePage], sockets: [MatchRoute] })`.
+Socket-bound pages must be live, connection-scoped and render TSX. Their route must
+support protocol version `1` with the default `redwebVersion` query parameter and
+explicitly allow duplicate connections (independent tabs). `redweb:*` handler names
+are reserved. Page-enabled routes use ordered, bounded message dispatch and track
+in-flight work for shutdown. JSON commands are supported; binary input is rejected
+on page-attached connections. Raw route connections retain binary handling.
+
+The adapter preserves route admission, origin and placement policies, then checks
+the page token, exact route, page identity and page origin. Use `authenticate` for
+page identity and `authorize` for current permissions/session validity. Authorization
+runs before commands, again after contract validation, and before render publication.
+Revocation and disconnect cancel ownership even when validation is still running.
+The page token is not a substitute for credentials.
+
+Initial page attachment completes before custom initialization hooks or commands.
+Do not call page commands from initialization hooks expecting those hooks themselves
+to finish first. Each page owns its connection; the same token cannot attach twice.
+
+Reconnect reauthenticates, invokes existing `connected()` hooks, and sends a fresh
+rendering snapshot. Game-seat recovery remains in that server hook. Commands are
+not queued or replayed. Page-session expiration requires a reload; game persistence
+is not provided by page retention.
+
+## Completion and client runtime
+
+After successful handler dispatch, Redweb sends a correlated `redweb:result`.
+The generated runtime waits specifically for that terminal type or a protocol error,
+not intermediate correlated progress messages. Direct client users can opt into
+the same behavior using `client.request(type, payload, { responseType })`; omitting
+the option preserves the existing any-correlated-response behavior.
+
+For an expected application rejection, send a safe correlated error with
+`socket.sendProtocolError('GAME_REJECTED', safeMessage, { requestId })` and return
+`false` from the handler. Only literal `false` declines successful dispatch;
+`undefined` remains success. The browser shows error feedback, preserves the form,
+and keeps its connection usable. Returning `false` without sending a correlated
+reply leaves a requesting client waiting until its deadline. Unexpected exceptions
+retain the existing sanitized handler-failure behavior and close the connection.
+
+This browser support lives in redweb-client's existing feedback/transport modules.
+The server still owns validation, authorization, game revisions, room fan-out and
+private rendering. Disabled controls are presentation, never permissions.