redweb 0.16.1 → 0.16.3

package/contract.d.ts

@@ -15,17 +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];
-
-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;
-}
+}[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):
@@ -44,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): SocketHandler<ContractInput<Schemas[Type]>>;
+    ) => 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/API_EXAMPLES_VERIFICATION.md

@@ -1,22 +1,22 @@
-# API example refresh verification
-
-Verified locally on Windows, 2026-09-02, for the 0.16.1 documentation patch.
-
-## Scope
-
-- Reviewed the current 31 API sections and 11 showcase examples. Prefer concise `defineApp`, plain decorated classes and TSX for application examples; retain explicitly labeled lower-level APIs.
-- Source reuse keeps the counter, component and multi-page/CSS examples identical between generated documentation and acceptance fixtures.
-- No runtime API change. Documentation generation and the executable room example were changed.
-- Prior release snapshots, including 0.16.0, remain untouched. The website remains pinned to published 0.16.0 until manual npm publication and subsequent site synchronization.
-
-## Passed checks
-
-- `tests/unit/documentation.unit.test.js` and `tests/unit/api-examples.unit.test.js`: 13 tests; 100% statements, branches, functions and lines for `src/docs/Documentation.js`. All current API/showcase examples parse as TSX; partial API patterns are not claimed to be independently runnable or fully type-checked applications.
-- `tests/integration/api-examples.integration.test.js`: six real headed-Chromium scenarios, counter/components/two-page site under both standard and legacy decorators. Exact source is compiled; only a fixture ownership export is appended. Verifies server updates, a second counter tab, component isolation, CSS and navigation without mocks.
-- Focused `tests/integration/documentation.integration.test.js` and `tests/unit/room-verifier.unit.test.js` gate (`shared page/room|actual generator|room`): 10 tests passed, two unrelated tests not selected. Includes actual HTTP/WebSocket room authorization and cleanup under both decorator modes.
-- `npm run pretest`: generated examples, protocol declarations, documentation freshness and all three consumer type configurations pass.
-- `npm run prepublishOnly`: release channel and immutable 0.16.1 snapshot match the package version.
-- `npm pack --dry-run --json`: packaging/prepack checks pass.
-- Senior critic reviewed modular source reuse, tests and API semantics. Corrected all findings, including both lifecycle prose and option-table distinctions between application and lower-level shutdown budgets.
-
-No soak, fixed-duration observation gate, full runtime suite or deployment was run for this documentation-only patch. Coverage above is scoped to the changed documentation generator, not a new whole-project coverage claim.
+# API example refresh verification
+
+Verified locally on Windows, 2026-09-02, for the 0.16.1 documentation patch.
+
+## Scope
+
+- Reviewed the current 31 API sections and 11 showcase examples. Prefer concise `defineApp`, plain decorated classes and TSX for application examples; retain explicitly labeled lower-level APIs.
+- Source reuse keeps the counter, component and multi-page/CSS examples identical between generated documentation and acceptance fixtures.
+- No runtime API change. Documentation generation and the executable room example were changed.
+- Prior release snapshots, including 0.16.0, remain untouched. The website remains pinned to published 0.16.0 until manual npm publication and subsequent site synchronization.
+
+## Passed checks
+
+- `tests/unit/documentation.unit.test.js` and `tests/unit/api-examples.unit.test.js`: 13 tests; 100% statements, branches, functions and lines for `src/docs/Documentation.js`. All current API/showcase examples parse as TSX; partial API patterns are not claimed to be independently runnable or fully type-checked applications.
+- `tests/integration/api-examples.integration.test.js`: six real headed-Chromium scenarios, counter/components/two-page site under both standard and legacy decorators. Exact source is compiled; only a fixture ownership export is appended. Verifies server updates, a second counter tab, component isolation, CSS and navigation without mocks.
+- Focused `tests/integration/documentation.integration.test.js` and `tests/unit/room-verifier.unit.test.js` gate (`shared page/room|actual generator|room`): 10 tests passed, two unrelated tests not selected. Includes actual HTTP/WebSocket room authorization and cleanup under both decorator modes.
+- `npm run pretest`: generated examples, protocol declarations, documentation freshness and all three consumer type configurations pass.
+- `npm run prepublishOnly`: release channel and immutable 0.16.1 snapshot match the package version.
+- `npm pack --dry-run --json`: packaging/prepack checks pass.
+- Senior critic reviewed modular source reuse, tests and API semantics. Corrected all findings, including both lifecycle prose and option-table distinctions between application and lower-level shutdown budgets.
+
+No soak, fixed-duration observation gate, full runtime suite or deployment was run for this documentation-only patch. Coverage above is scoped to the changed documentation generator, not a new whole-project coverage claim.

package/docs/APPLICATION.md

@@ -1,94 +1,96 @@
-# 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] });
-app.run();
-```
-
-`run()` returns a Promise. Await it when startup completion matters; an ESM entry point can use top-level `await app.run()`. In CommonJS, the direct call above also works; add rejection handling when the application needs a custom failure policy. A module imported by tests should export its definition separately or guard startup with `require.main === module`. Constructing 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).
+# 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] });
+app.run();
+```
+
+`run()` returns a Promise. Await it when startup completion matters; an ESM entry point can use top-level `await app.run()`. In CommonJS, the direct call above also works; add rejection handling when the application needs a custom failure policy. A module imported by tests should export its definition separately or guard startup with `require.main === module`. Constructing 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.
+
+`providers` is different from `services`: it is a named map of already-created application objects that a page explicitly requests through `@inject('name')`. Use it for a store or other dependency shared across page instances. Redweb does not construct, persist, or authorize those objects for you.
+
+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 a general-purpose dependency-injection container, distributed worker manager, or durable storage. `services` are lifecycle classes and are not injected into page constructors. For an explicit application-owned dependency, register an instance in `providers` and declare a matching `@inject('name')` field on the page; see the [complete Live HTML example](LIVE_HTML.md#putting-uploads-providers-and-resources-together). `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).