redweb 0.13.5 → 0.15.0

package/docs/SOCKET_PAGE_RELEASE_PREPARATION.md

@@ -0,0 +1,120 @@
+# Socket-page release preparation
+
+Updated 2026-09-02. The maintainer published client 0.3.0; no core publication or
+hosting deployment was performed during this preparation.
+
+## Client publication verified
+
+`redweb-client@0.3.0` was published from the sibling client checkout on
+`codex/socket-page-actions`, commit `3d2bcfec75db367b6e4924bcf430670f5569b1c7`.
+Its package version and lockfile agree, release notes are included, and prepack
+rebuilds the ESM/CommonJS bundles and declarations. Build logs use stderr so
+`npm pack --json` remains machine-readable.
+
+After npm's processing delay, the actual public registry returned version 0.3.0,
+the same source commit, and the tested candidate integrity below. A fresh local
+pack independently reproduced the publication's SHA-1
+`def8dcc0bb205ccff68bf8fd1c7ea91b7d289547`, 14 files and 31,378 bytes.
+
+```text
+sha512-hUBa40wdsvWKY5bqeyreDzUhMcaB0e0x0OX+YRyZw6ccri6BBSHnM6eEKMV0wOkprIF2cxDkGNILwAA5ELYkWw==
+```
+
+Core's real dependency installation now resolves that registry artifact, not a
+link. Its lockfile records the actual registry URL and integrity. This verifies
+artifact identity, not a claim that client provenance was available.
+
+## Finish the dependent releases afterward
+
+1. Completed: verify client 0.3.0 registry metadata and install the actual artifact.
+2. Redweb **0.15.0** now has `redweb-client@^0.3.0`, its real npm lockfile,
+   versioned changelog and immutable 69-page 0.15.0 documentation snapshot.
+   The final gates below passed; core is ready for manual publication.
+3. After core publication, update site/tutorial exact dependency pins and locks,
+   synchronize the released catalogue, run the downloadable-archive/browser gates,
+   then hand off manual Firebase deployment.
+
+No future registry URL, integrity value or already-published version was fabricated
+in a lockfile. The site's development tutorial remains undeployable with its
+previous published pins; its candidate-archive tests are not evidence that core
+0.15.0 is already published. Do not deploy it before step 3.
+
+## Verification completed
+
+- Client `npm test`: build, declarations, unit tests, mock-free HTTP/WS integration,
+  and headed Chrome passed. Original-source coverage remains 800 statements,
+  543 branches, 125 functions and 667 lines, all 100%. Report:
+  `coverage/client-source/af576edc-b382-424b-97a2-bd46ca163832/summary.json`.
+- The actual client tarball installs in a fresh, unlinked application with released
+  Redweb 0.14.0. Both module formats and the optional live-html entry load; native
+  socket requests wait for terminal replies and preserve null payloads. Actual
+  nested HTTP form parsing and the installed Express/body-parser qs versions pass.
+  Run the opt-in regression with `REDWEB_VERIFY_CLIENT_RELEASE=1` and
+  `tests/integration/client-release.integration.test.js`; it rebuilds/packs the
+  sibling client and uses the existing owned-workspace/process helpers.
+- After installing registry client 0.3.0, 308 core tests across 29 suites pass.
+  Every `src/htmx/*.js` module, `src/cli/templates.js`, and the socket
+  `BaseHandler`, `SocketContract`, `SocketAction` and `HandlerGuard` modules
+  reach 100% statements, branches, functions and lines. This is scoped coverage,
+  not whole-repository certification. Report: `coverage/socket-page-release`.
+- Canonical examples, protocol declarations, all three TypeScript configurations,
+  generated documentation and the prepublication release check pass.
+- The actual downloadable tutorial archive passes independent installation,
+  compilation, type tests, mock-free HTTP/WS/SQLite tests, all-four 100% coverage
+  of its game/schema modules, and headed Chrome acceptance. The explicit pair was
+  core 0.15.0 candidate plus a client 0.3.0 pack byte-identical to npm's artifact;
+  no developer links were used inside the extracted application. Its unchanged
+  old dependency pins still need replacement after core publication.
+- Core's production audit reports zero vulnerabilities under its application-root
+  qs policy. The installed dependency signature audit verifies 428 registry
+  signatures and 31 attestations; this aggregate does not claim every package has
+  provenance.
+- Fresh site/tutorial locked installs audit with zero reported vulnerabilities.
+  The site build, 438-page HTTP/link verification and its seven-module 100%
+  documentation coverage scope pass. After restoring npm links, the headed
+  three-player tutorial passes login, rejection/input retention, moves, reconnect,
+  disconnect presence, win and logout.
+- The complete isolated core package gate passes against registry client 0.3.0
+  without a candidate-client override: headed counter/chat/cards/components/JSX,
+  private dashboard login and actions, reconnect/disconnect, all six generated
+  starters and source-free execution, executable documentation and static export.
+  Bundled Live HTML and browser-refresh coverage each remain all-four 100%.
+  Report: `coverage/packed-browser/2cc05d98-d6b7-4c54-b5ce-fef4cbb83053`.
+  The tested core archive SHA-256 was
+  `1fd3fe3b35fd8ec0f9e805df9c3ad6655af40f373e38b44ab0418db71660eb1a`;
+  the subsequent evidence-only update to this file changes the final archive hash,
+  not its runtime, recipes, declarations or versioned catalogue.
+- The independent senior critic approved the release metadata, actual installed
+  client identity and catalogue consistency with no blocking findings. Core
+  publication dry run passes. No soak or long fixed-window tests were run.
+
+## Manual next step
+
+Publish from the clean `codex/socket-page-actions` core checkout:
+
+```powershell
+Set-Location C:\Users\arkam\Documents\redweb
+$env:NODE_OPTIONS = '--use-system-ca'
+npm publish
+```
+
+The system-trust-store option preserves TLS verification. Do not disable TLS
+checks. Do not publish the client again or deploy the site yet. After core is
+available in npm, replace the site's/tutorial's old pins with verified registry
+dependencies and synchronize the 0.15.0 catalogue before rebuilding and deploying.
+
+## Dependency mitigation, not a library-level promise
+
+Core development, generated applications, the site and the tutorial now use an
+application-root override scoped to the Express dependency subtree:
+`{ "express": { "qs": "6.16.0" } }`. Their checked locks and the fresh packed-client
+consumer audit report zero known vulnerabilities. Actual Express and body-parser
+both resolve the patched qs version. The generator reuses the root policy rather
+than maintaining a separate starter copy.
+
+The override does not upgrade Express or affect unrelated dependency subtrees.
+It also does **not** propagate from Redweb when another application installs it:
+existing consumers must apply the documented root policy and verify their own
+locks/tests. See [release trust](RELEASE_TRUST.md#temporary-express-4-dependency-mitigation)
+for the maintainer advisories and npm's override rules. Ordinary installs without
+the policy can remain affected until upstream dependency ranges are patched.

package/docs/SOCKET_PAGE_VERIFICATION.md

@@ -0,0 +1,85 @@
+# Socket-bound TSX verification
+
+Development verification on 2026-09-02, Windows, Node 22.21.0, headed Chrome 152.
+This records feature acceptance, not an npm release or full-repository certification.
+
+## Implementation and review
+
+Core/client branch: `codex/socket-page-actions`. Site branch:
+`codex/server-tsx-tutorial` in the sibling landing-page checkout.
+
+- Typed handler references and `.with(payload)` reuse contract validation, page
+  ownership, reactive rendering and the existing redweb-client runtime.
+- The tutorial has no application browser module or bundling step. Its private
+  page, game rules, commands, room fan-out and seat recovery live on the server.
+- Independent critic reviews covered core/client and the actual tutorial. Fixed
+  findings included attachment ordering, post-validation disconnect authorization,
+  duplicate-connection policy, intermediate reply correlation, obsolete render
+  cancellation and rejected forms incorrectly reporting success. Final review
+  reported no remaining blocking findings within that scope.
+
+## Passing gates
+
+- 294 tests / 27 suites passed in the rendering regression selection below.
+  Every module in `src/htmx/*.js`, plus `BaseHandler`, `SocketContract`,
+  `SocketAction` and `HandlerGuard`, reached 100% statements, branches, functions
+  and lines. The changed explicit-false dispatch in `SocketRoute` is exercised by
+  real-network tests; this measurement does not claim all of `SocketRoute` or the
+  whole repository is covered by this selection.
+- Client `npm test` passed linkage, build, declarations and the combined original
+  source gate: 800 statements, 543 branches, 125 functions and 667 lines, all 100%.
+  Report: `coverage/client-source/c819157b-6aaa-4020-99f4-152b8df473ed/summary.json`.
+  It runs plain and instrumented Node tests and headed Chrome on real HTTP/WS.
+  The existing instrumentation does not count every optional-chain/V8 branch.
+- Core pretest checked canonical example output, protocol declarations, all
+  TypeScript configurations and 69 generated unreleased documentation pages.
+  The standalone contract entry also bundled for browsers without Node builtins.
+- Site build and real HTTP verification passed: 438 pages, 11 examples, 30 API
+  articles, downloads and internal links. The seven-module documentation coverage
+  scope remains 100% lines, branches and functions.
+- The actual tutorial archive was extracted to a fresh temporary directory,
+  installed with both explicitly packed development candidates (no links),
+  compiled, typechecked and tested with real HTTP, WebSockets and SQLite. Its
+  game-rule and message-schema modules remain all-four 100%; this is not a
+  whole-tutorial/authentication coverage claim.
+- Headed Chrome passed both linked and extracted-package tutorial acceptance:
+  hello world, two-tab server counter, wrong/right login, two-player game,
+  third-player full-room rejection with retained input and reusable connection,
+  reconnect without move replay, disconnect presence, win and logout. Actual
+  outgoing game connections use `/match`; game commands are `join` and `move`.
+- Headed static-site navigation passed both minimal homepage examples, six
+  highlighted chapters, next links and the project download.
+
+New integration tests use actual transports, not mocks. Pure failure-boundary
+units supplement them. No soak or long fixed-window workload was run.
+
+### Reproduce the scoped core coverage gate
+
+```sh
+node node_modules/jest/bin/jest.js tests/htmx tests/ws tests/unit/socket-action.unit.test.js tests/unit/page-access.unit.test.js tests/unit/socket-contract.unit.test.js tests/unit/utilities.unit.test.js tests/unit/action-input.unit.test.js tests/unit/inspection.unit.test.js tests/unit/development-refresh.unit.test.js tests/unit/development-refresh-boundaries.unit.test.js tests/unit/development-refresh-cleanup.unit.test.js tests/unit/define-app.unit.test.js tests/integration/define-app.integration.test.js tests/integration/socket-page.integration.test.js tests/integration/socket-contract.integration.test.js tests/integration/live-html.integration.test.js tests/integration/page-access.integration.test.js tests/integration/action-input.integration.test.js tests/integration/inspection.integration.test.js --runInBand --silent --coverage --collectCoverageFrom=src/htmx/*.js --collectCoverageFrom=src/ws/BaseHandler.js --collectCoverageFrom=src/ws/SocketContract.js --collectCoverageFrom=src/ws/SocketAction.js --collectCoverageFrom=src/ws/HandlerGuard.js --coverageDirectory=coverage/socket-page-regression
+```
+
+The site README documents the two candidate-tarball environment variables for
+`npm test`. That gate includes headed browser acceptance inside the extracted
+archive; Chrome and the tutorial's Node version are required.
+
+## Release boundaries and outstanding dependency audit
+
+The follow-up [release preparation](SOCKET_PAGE_RELEASE_PREPARATION.md) prepares
+client 0.3.0 and records the tested application-root qs mitigation. The initial
+observations below remain historical; they do not override that later status.
+
+The old published versions (Redweb 0.14.0/client 0.2.0) do not contain these APIs.
+Local tarballs retaining those development metadata versions were verification
+inputs, not artifacts to publish over existing releases. Release a new client,
+align and release Redweb, then update the site's tutorial pins/lockfile and
+catalogue before manual deployment. Existing immutable release snapshots were
+not rewritten. Nothing was published or deployed during this task.
+
+An additional `npm audit --omit=dev` check reports four moderate dependency-tree
+entries in the existing site/tutorial locks, rooted in two `qs` advisories:
+[bracket-key parsing](https://github.com/advisories/GHSA-x5fp-wj9c-mxmx) and
+[attacker-controlled isBuffer](https://github.com/advisories/GHSA-4mjr-xmp4-gh2g).
+The installed Express 4 dependency range does not select the published qs 6.16.0
+fix. This feature work does not waive that audit or silently force an Express 5
+migration. Resolve and verify the dependency policy before production release.

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.