redweb 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 
-## Unreleased
+## 0.16.0
+
+- Add opt-in `connectedClients` over the existing RoomRegistry: verified per-connection identity, synchronous room/domain joins with membership rollback, deduplicated presence and checked per-player page projection. Typed handlers bind without changing the browser-safe socket contract. Raw command completion is independent of state updates; only deliberate rejections expose text.
+- Fence obsolete projection failures, bound asynchronous adapters by connection lifetime, and keep a failed recipient from rejecting another player's committed command. Add mock-free socket regressions and unit coverage; no client package changes are needed.
 
 ## 0.15.0
 

package/README.md

@@ -11,12 +11,12 @@ Redweb 0.14.0 adds [`defineApp({ pages, sockets, services, port })`](docs/APPLIC
 Start with a complete, tested counter application:
 
 <!-- redweb:setup:start -->
-> Documentation for Redweb 0.15.0. Install that exact version when following these examples.
+> Documentation for Redweb 0.16.0. Install that exact version when following these examples.
 
 ```sh
-npx --yes redweb@0.15.0 init my-realtime --template realtime
+npx --yes redweb@0.16.0 init my-realtime --template realtime
 cd my-realtime
-npm install --save-exact redweb@0.15.0
+npm install --save-exact redweb@0.16.0
 npm test
 npm run dev
 ```

package/docs/CONNECTED_CLIENTS_VERIFICATION.md

@@ -0,0 +1,65 @@
+# Connected-client implementation verification
+
+Date: 2026-09-02. Runtime commit: `e001a58`, branch `codex/connected-clients`.
+This is an unreleased development feature, not the published Redweb 0.15.0 package.
+No client source changes or client publication are required; tests use published
+redweb-client 0.3.0.
+
+## Scope
+
+`connectedClients` composes the existing RoomRegistry, bounded authorization,
+projection work, typed socket handlers and private page ownership. It introduces
+no second membership registry. The tutorial consumes it on the companion site's
+`codex/tutorial-connected-clients` branch.
+
+## Passed gates
+
+- `npm run pretest`: generated examples, protocol types, development documentation
+  and all three TypeScript consumer configurations.
+- 368 unit/integration tests in 25 suites: socket servers/routes, connected clients,
+  room access, multiplayer policies/state, protocol/contracts, socket pages,
+  distribution, inspection, page access and the existing HTML test directory.
+- Coverage: 100% statements, branches, functions and lines in **ConnectedClients.js,
+  RoomRegistry.js, RouteRuntime.js and SocketRoute.js**. Report:
+  `coverage/connected-client-rooms`. This is an affected-module claim, not a claim
+  that every module in the repository was measured by this command.
+- `npm run verify:live-html:package`: actual tarball installed in isolation;
+  counter, chat, reconnect/disconnect, cards, components, JSX, dashboard login,
+  generated starters, rendering and development-refresh browser checks passed.
+  Browser: headed Google Chrome 152.0.7977.64. Existing bundled HTML-runtime and
+  refresh coverage gates also reached 100% in their declared scopes.
+- Production dependency audit: zero reported vulnerabilities.
+
+Packed runtime SHA-256 (before adding this evidence document):
+`818bfeb32683089b883bd88f2cef8ac444a8611365a9fe121b4fe2d6b597e540`.
+Package verification report:
+`coverage/packed-browser/8a79c650-cf59-460b-b024-ad791406147f`.
+The archive retains the development checkout's 0.15.0 manifest version; it is
+**not** the npm release bearing that version and must not be published over it.
+
+## Real-network regressions
+
+Independent tabs receive separate private pages; presence counts unique identities
+and reacts to the last tab disconnecting. Tests also cover capacity before domain
+commit, rejected-join membership rollback, room isolation, authorization revoked
+during validation/projection, stale successful and failed projections, failing
+recipients, page-only groups, raw clients and overlapping commands.
+
+Senior critic findings were fixed and regression-tested:
+
+1. A stale authorization/projection failure cannot disconnect a newer valid view.
+2. Raw command completion is independent of superseded state projections.
+3. Raw rejection adapters are bounded and cancel when the connection closes.
+
+No soak or long fixed-observation-time tests were run. Test timeouts are failure
+deadlines. Application callbacks still must validate before mutating domain state;
+membership rollback is not an arbitrary application/database transaction.
+
+## Release boundary
+
+The implementation above was tested as unreleased. Release preparation now targets
+**0.16.0**, with matching package/lock metadata and a generated immutable release
+catalogue. This preparation does not publish the package or change runtime code.
+After publication, update the site's dependency pins, lockfiles and catalogue;
+remove development-preview notices and retest the archive against registry packages
+before manual deployment. Immutable published documentation snapshots are unchanged.

package/docs/SOCKET_PAGES.md

@@ -1,5 +1,78 @@
 # Server-side TSX for custom socket routes
 
+## Connected clients (0.16.0)
+
+The following convenience layer requires Redweb **0.16.0**; it is not in Redweb 0.15.0.
+It uses existing redweb-client 0.3.0 without a client upgrade.
+
+`connectedClients({ identity, page, project })` creates one route-owned group.
+Register it as `connections` in `SocketRoute`; rooms and handler drain tracking
+are enabled by default. Create a fresh group inside each application factory.
+It reuses RoomRegistry capacity, authorization and disconnect cleanup, not a second
+membership map. Normal raw SocketRoute/SocketContract APIs remain unchanged.
+
+```ts
+const players = connectedClients({
+    identity: context => account(context.request),
+    page: () => GamePage,
+    project: (player, room, online) => ({
+        game: games.resume(room, player.identity).snapshot(player.identity),
+        online,
+    }),
+});
+const match = players.bind(contract);
+const Join = match.handler('join', (player, { room }) =>
+    player.join(room, () => games.join(room, player.identity)));
+```
+
+This is a composition excerpt: the application supplies `account`, `games`, the
+typed `contract`, and decorated `GamePage` state fields. Register the resulting
+handler, contract protocol and `connections: players` on the page's SocketRoute.
+Handler `.with(payload)` bindings keep their inferred input type.
+
+The client exposes `identity`, `page`, `rooms`, `room` (exactly one membership),
+`join(room, commit?)`, `leave(room)` and an explicit underlying `socket` escape hatch.
+`players.get(socket)` supports page lifecycle callbacks, and
+`players.refresh(room)` publishes changes made outside a handler. Successful
+handlers automatically refresh their client's current rooms. Room changes batch
+refresh requests; multiple tabs count as one online identity, but receive separate
+private page projections.
+
+Identity must remain exactly equal to the admitted principal. The group checks it
+after payload validation and before/after asynchronous projection work. Existing
+page authorization and generation guards remain in force. Access is not granted
+by a button or a room name. The application still defines room access, game rules,
+seat recovery, revisions and durable storage.
+
+`join` checks membership capacity/permission before its synchronous domain commit.
+A rejected commit removes newly added membership, but does not remove pre-existing
+membership. Domain operations must validate before changing their own state:
+Redweb cannot roll back arbitrary application or database side effects. Async
+domain commits are rejected; they must not be used as an external transaction.
+
+Projection callbacks return partial page state and must be side-effect-free.
+Authorization and projection work use bounded operations (5000ms defaults;
+`authorizationTimeoutMs` and `projectionTimeoutMs` configure them). Disconnect
+cancels delivery; late results and late failures cannot overwrite or disconnect a
+newer generation. Recipient failures do not reject someone else's committed move.
+Cancellation cannot stop arbitrary work inside user callbacks, only its acceptance.
+
+Throw `ClientError` only for deliberately public text, or classify domain errors
+with `reject(error): string | undefined`. Unexpected exceptions retain normal
+private server error handling. Optional `errorState(message)` returns page fields
+such as a notice; the framework owns protocol errors and form completion.
+
+An optional `raw.update(state)` adapter returns `{ type, payload }` for non-HTML
+clients. Optional `raw.reject(message)` returns an uncorrelated display event.
+Redweb performs the final authorized send, not the adapter. State events are
+uncorrelated; successful raw requests complete with `redweb:result`, while safe
+rejections use correlated protocol errors. With redweb-client use
+`request(type, payload, { responseType: 'redweb:result' })` and subscribe to state
+separately. This is an opt-in completion contract, not a silent change to existing
+raw handlers. Custom adapters must not send from inside their callbacks.
+
+## Socket-bound pages (0.15.0)
+
 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`.