redweb 0.13.5 → 0.14.0

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## Unreleased
+## 0.14.0
+
+- Bound already-closing WebSocket peers with the native `ws` closing-handshake deadline: `websocketOptions.closeTimeout` defaults to 5000ms instead of 30000ms and remains configurable. Real TCP tests cover a peer withholding FIN; heartbeat, session expiry, and shutdown deadlines remain separate.
+- Introduce deferred `defineApp({ pages, sockets, services, port })` composition and `await app.run()` with one owned HTTP/WebSocket listener, ordered application service initialization, cancellation, bounded shutdown, and partial-startup rollback.
+- Run the five canonical headed-browser example scenarios through `defineApp`; cover its lifecycle with real HTTP/WSS, process, and unit tests. Recognize the unified page/socket registrations in `redweb doctor` without executing application code.
+- Simplify all six generated starters around `app.run()` and remove their copied startup helper. Move dashboard auth/database ownership into an application service; retain real generated-app process tests and centralize lifecycle coverage on the framework implementation.
+- Guard late native listener completion after cancellation or timeout on Node 18, and avoid racing duplicate deadlines during owned HTTP peer cleanup.
+- Preserve native constructor errors across JavaScript contexts while awaiting partial-startup cleanup, including the original already-listening error.
 
 ## 0.13.5
 

package/README.md

@@ -4,17 +4,19 @@ Build a TypeScript website and its realtime backend together. Decorated classes
 
 Use the same package for a live site, static HTML, Express HTTP endpoints, or routed WebSocket services.
 
+Redweb 0.14.0 adds [`defineApp({ pages, sockets, services, port })`](docs/APPLICATION.md), followed by `await app.run()`, for one owned HTTP/WebSocket listener.
+
 ## Install
 
 Start with a complete, tested counter application:
 
 <!-- redweb:setup:start -->
-> Documentation for Redweb 0.13.5. Install that exact version when following these examples.
+> Documentation for Redweb 0.14.0. Install that exact version when following these examples.
 
 ```sh
-npx --yes redweb@0.13.5 init my-realtime --template realtime
+npx --yes redweb@0.14.0 init my-realtime --template realtime
 cd my-realtime
-npm install --save-exact redweb@0.13.5
+npm install --save-exact redweb@0.14.0
 npm test
 npm run dev
 ```
@@ -22,12 +24,11 @@ npm run dev
 
 Open two tabs at `http://localhost:8181`. Clicking either button changes the counter on the server and updates both tabs.
 
-This is the starter's exact `src/app.tsx`. The initializer also supplies its stylesheet, compiler configuration, shutdown helper, and real-network tests; the file is not a standalone copy-and-run program.
+This is the starter's exact `src/app.tsx`. The initializer also supplies its stylesheet, compiler configuration, and real-network tests; startup and shutdown belong to Redweb itself. The file is not a standalone copy-and-run program.
 
 <!-- redweb:realtime:start -->
 ```tsx
-import { action, page, start, state, type LiveHtmlStartOptions } from 'redweb';
-import { runApp } from './run-app';
+import { action, defineApp, page, state } from 'redweb';
 
 @page('/', { css: 'app.css', shared: true })
 export class CounterPage {
@@ -49,11 +50,9 @@ export class CounterPage {
     }
 }
 
-export function createApp(options: LiveHtmlStartOptions = {}) {
-    return start(CounterPage, { port: Number(process.env.PORT ?? 8181), templateRoot: __dirname, ...options });
-}
+export const app = defineApp({ pages: [CounterPage], port: Number(process.env.PORT ?? 8181), templateRoot: __dirname });
 
-if (require.main === module) runApp(createApp);
+if (require.main === module) void app.run().catch(error => { console.error(error); process.exitCode = 1; });
 ```
 <!-- redweb:realtime:end -->
 
@@ -95,8 +94,7 @@ The `http-ws` starter answers `GET /health` and accepts `{"type":"hello"}` at `w
 
 <!-- redweb:http-ws:start -->
 ```tsx
-import { BaseHandler, HttpServer, METHODS, SocketRoute, SocketServer, type RedWebSocket, type SocketServerOptions } from 'redweb';
-import { runApp } from './run-app';
+import { BaseHandler, defineApp, METHODS, SocketRoute, type RedWebSocket } from 'redweb';
 
 export class Hello extends BaseHandler {
     constructor() { super('hello'); }
@@ -112,29 +110,19 @@ export class ChatRoute extends SocketRoute {
     }
 }
 
-export function createApp(options: Pick<SocketServerOptions, 'port' | 'bind' | 'logger'> = {}) {
-    const http = new HttpServer({
-        listen: false,
-        publicPaths: [],
-        services: [{ serviceName: '/health', method: METHODS.GET, function: (_req, res) => res.json({ ok: true }) }],
-    });
-
-    return new SocketServer({
-        port: options.port ?? Number(process.env.PORT ?? 8181),
-        bind: options.bind ?? '127.0.0.1',
-        logger: options.logger,
-        server: http.server,
-        routes: [ChatRoute],
-        listen: true,
-        closeServerOnShutdown: true, // One owner closes routes and the shared HTTP listener.
-    });
-}
+export const app = defineApp({
+    sockets: [ChatRoute],
+    port: Number(process.env.PORT ?? 8181),
+    bind: '127.0.0.1',
+    publicPaths: [],
+    httpServices: [{ serviceName: '/health', method: METHODS.GET, function: (_req, res) => res.json({ ok: true }) }],
+});
 
-if (require.main === module) runApp(createApp);
+if (require.main === module) void app.run().catch(error => { console.error(error); process.exitCode = 1; });
 ```
 <!-- redweb:http-ws:end -->
 
-Follow the [shared-listener notes](recipes/http-ws/README.md) and initialize with `--template http-ws` using the matching artifact above. The socket service explicitly owns cleanup of the supplied HTTP listener. `/health` reports liveness, not readiness. This demonstrates raw JSON messages, not a chatroom UI.
+Follow the [shared-listener notes](recipes/http-ws/README.md) and initialize with `--template http-ws` using the matching artifact above. The unified application owns cleanup of its HTTP and socket resources. `/health` reports liveness, not readiness. This demonstrates raw JSON messages, not a chatroom UI.
 
 For validated, inferred client/server payloads, use [shared socket contracts](docs/SOCKET_CONTRACTS.md). The client wraps your transport; it does not create or reconnect one for you.
 
@@ -265,7 +253,7 @@ The isolated browser harness copies its verification helpers explicitly and chec
 
 `npm run verify:live-html:browser:coverage` combines the existing full browser workload (counter, chat, CSS, JSX, components, forms and dashboard) with explicit failure-path unit tests. Its 100% authored-tool coverage is separate from frontend coverage and release acceptance. The native workload requires the dashboard's supported Node version. Known limitations of the unchanged legacy browser tool— including uncertain descendant cleanup—are characterized, not silently fixed or counted as verified cleanup; see the [coverage audit](docs/COVERAGE_SCOPE_AUDIT.md).
 
-The frontend is maintained in `redweb-client/live-html`; Redweb emits only a two-line mounting bootstrap. Redweb 0.13.5 depends on published `redweb-client@^0.2.0`, so ordinary application installation needs no client checkout or link. Contributors editing the client can still use the [linked development workflow](docs/CLIENT_DEVELOPMENT.md).
+The frontend is maintained in `redweb-client/live-html`; Redweb emits only a two-line mounting bootstrap. Redweb 0.14.0 depends on published `redweb-client@^0.2.0`, so ordinary application installation needs no client checkout or link. Contributors editing the client can still use the [linked development workflow](docs/CLIENT_DEVELOPMENT.md).
 
 `npm run measure:browser:client` separately serves the exact installed socket-only module with and without instrumentation through the same real HTTP/WebSocket/browser cases and retains its source hash and counters. It exits unsuccessfully until all four coverage metrics reach 100%; incomplete results are not a passing dependency-coverage claim. Reports are local under `coverage/browser-client` and do not alter the installed dependency or published package.
 

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.14.0`.
 
 ```sh
 npx --no-install redweb add page dashboard

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.14.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.14.0` 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.
 
 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.14.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.14.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.14.0 contains the capabilities described by the 0.14.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

@@ -18,18 +18,18 @@ Use the [official Node release schedule](https://nodejs.org/en/about/previous-re
 
 ## 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:
+For a published application, select an exact release, commit its lockfile, and use `npm ci` in CI/deployment. This guide is versioned for 0.14.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.14.0 version engines dist.integrity dist.signatures dist.attestations gitHead --json
+npm install --save-exact redweb@0.14.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.14.0 contains 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.14.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.14.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,10 +1,10 @@
 # Shared socket contracts
 
-Status: included in `redweb@0.13.5`.
+Status: included in `redweb@0.14.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.14.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

package/docs/STARTER_LIFECYCLE_VERIFICATION.md

@@ -1,5 +1,14 @@
 # Lifecycle coverage must measure actual code
 
+> Historical report, superseded by the `defineApp` migration. The generated
+> `run-app` helper and `verify-starter-lifecycle.js` described below have been
+> removed. The current `verify:starters:lifecycle:coverage` gate measures the
+> shared `Application` and `StartupCleanup` implementation, while
+> `verify:starters:source-coverage` measures all six original TypeScript starters.
+> Generated applications also run real child-process lifecycle tests. The
+> observations and paths below are retained as historical evidence, not current
+> commands or release results.
+
 The lifecycle gate previously trusted c8's exit code. A real command with all four
 100% thresholds and an empty source match exits successfully with `{}` coverage:
 c8 compares a nonnumeric empty-map percentage against the thresholds.