redweb 0.12.0 → 0.13.0

package/docs/CLI.md

@@ -0,0 +1,116 @@
+# Redweb command-line tools
+
+Use the version installed in your project (`npx --no-install redweb`) when troubleshooting an existing app. The tool reports a warning if its version differs from the project's installed Redweb version.
+
+## Add pages, components, and socket routes
+
+This command is currently **unreleased**, like the other branch-specific capabilities in the README.
+
+```sh
+npx --no-install redweb add page dashboard
+npx --no-install redweb add component notifications
+npx --no-install redweb add socket-route match
+npx --no-install redweb add page account-settings --dry-run --json
+```
+
+Each addition writes a named-export TypeScript module and a `.test.cjs` file. Pages and owned components demonstrate server state plus an exposed increment action. The socket route demonstrates a validated `ping` handler returning `pong`, without an inner action dispatcher; extend its contract and register additional handlers as needed. For complete join/move/resume behavior, use the existing socket starter instead.
+
+Run these commands in an existing project with Redweb declared as an installed runtime dependency and TypeScript installed. Declare/install `ws` explicitly (normally as a development dependency) for the generated network tests. Socket additions also require application-installed Zod as a runtime dependency. The generator reports missing prerequisites; it never installs dependencies or changes your manifest.
+
+The default source location is the effective TypeScript `rootDir`, with `pages/`, `components/`, or `socket-routes/` beneath it. The default test directory is `test/`. An optional project directory follows the kind/name. Use `--config build.json`, `--source-dir features`, or `--test-dir checks` to select paths relative to that project. Names must be lowercase kebab-case, start with a letter, and contain at most 64 characters.
+
+The command supports a single emitting TypeScript project using CommonJS, Node16 or NodeNext module settings and standard or legacy decorators. HTML additions require Redweb's automatic JSX runtime. Effective inherited configuration controls inclusion and emission; `--source-dir` chooses placement, **not** the compiler's `rootDir`. Ambiguous placement requires that option or an explicit `rootDir`. Project-reference roots, bundler-only pipelines, bundled output, disabled JavaScript emission, output outside the project, mismatched source/output package module types, and compiled test locations are rejected with guidance. Select the appropriate child project/configuration yourself rather than allowing the command to rewrite a monorepo.
+
+The planner parses source and performs an in-memory TypeScript emit, without importing the application or writing build output. It checks the prospective module, its actual emitted path (including imported source dependencies), and whether an inferred root would relocate existing output. It rejects a test directory that TypeScript would compile when `allowJs` is enabled. This is not a replacement for a whole-project build or its existing tests. The virtual-file matcher uses a feature-checked TypeScript runtime API; unsupported compiler shapes fail explicitly rather than guessing glob behavior.
+
+`--dry-run` writes nothing; `--json` returns a versioned report with planned/created paths, source/output/test paths, a named import, `registration.status: "pending"`, and explicit build/test argument arrays. Human commands are quoted for PowerShell on Windows and a POSIX shell elsewhere. Run the reported build and then its test from the project root. The test imports **only the generated artifact**, starts an isolated loopback server on a temporary port, and exercises a real HTTP/WebSocket action or message exchange. It never imports the existing application entry point.
+
+Registration is intentionally your next step. Add a page to the existing `start([...])` list; add a socket route to the server's route list. For components, create an owned field (`widget = new NotificationsComponent()`) and render `{this.widget}`. Adjust the report's project-root-relative named import to the file where you use it; Node-compatible imports use the emitted `.js` extension. No imports, registration lists, package scripts, manifests, or configuration files are rewritten. Add the new test to your project's normal test command yourself; a generated test is not claimed to be automatically registered.
+
+The shared writer rejects any destination conflict before writing and creates files exclusively. It rejects path escapes, unsafe portable names, case aliases and symbolic-link ancestors. Concurrent failures report which files were completed and which path was attempted; writing is not transactional and does not lock the filesystem tree. Existing application files are never overwritten.
+
+## Initialize a project
+
+Follow a [complete recipe's version-specific setup](GETTING_STARTED.md#start-with-a-complete-recipe). Its commands initialize a new directory, install the matching release or packed artifact, run tests, and start development. The unreleased channel requires the same tarball for initialization and installation; ordinary `npx redweb` does not select this checkout.
+
+The initializer creates missing files only. It does not install dependencies, run package scripts, or validate existing source code. A message saying initialization completed means the file operation completed, not that a preserved existing project is valid.
+
+`--template realtime|chat|site|socket|dashboard|http-ws` selects a complete runnable recipe. The default is `realtime`, a shared server-owned counter. `chat` includes the canonical reusable chat component, validated actions and its stylesheet; `site` has two non-live pages with a shared layout; `socket` exposes `/match` with separate `join`, `move`, and `resume` handlers, a shared Zod contract, and bounded in-memory sessions. The [dashboard](../recipes/dashboard/README.md) combines private live cards, SQLite persistence, explicit account provisioning, expiring sessions and account-wide sign-out. It requires Node 22.13+. The [http-ws starter](../recipes/http-ws/README.md) combines an HTTP health endpoint and a raw socket route on one explicitly owned listener. Each starter includes network tests, build/production instructions, and a development watcher. `--existing` and `--template` cannot be combined. The chat, socket and dashboard starters add Zod; Redweb itself does not require Zod or SQLite at runtime.
+
+Doctor also checks the application's declared `engines.node` minimum (for example `>=22.13.0`). An incompatible runtime produces `PROJECT_NODE_UNSUPPORTED`. More complex ranges produce `PROJECT_NODE_UNCHECKED`, not a guessed success; npm remains responsible for its full engine-range interpretation. CI runs the dashboard acceptance tests on Node 22; older core compatibility jobs explicitly skip that recipe's runtime execution.
+
+Run `npm test` for type checking, asset copying, and real HTTP/WebSocket tests on an ephemeral loopback port. `npm run dev` uses development-only Nodemon to rebuild and restart on changes to `src/` or `tsconfig.json`, enabling loopback-only browser refresh through its `REDWEB_DEV_REFRESH=1` environment. Clean HTML pages refresh automatically; detected edits keep the old document with a confirmation notice. This is not browser hot-module replacement or autosave. A type error prevents startup until corrected; outages alone do not trigger reload. See [development refresh](DEVELOPMENT.md#browser-refresh) for draft, connection, hostname and production boundaries. `npm run build` produces runtime code and assets in `dist/`; production needs that directory and installed runtime dependencies, not TypeScript or `src/`.
+
+Templates come from `recipes/`, with common configuration/test helpers maintained once. The package gate extracts a tarball, generates every template, runs each generated `npm test`, then removes access to `src/` and runs the network tests again to validate production asset resolution.
+
+For an existing application:
+
+```sh
+npx --no-install redweb init --existing --dry-run --json
+npx --no-install redweb init --existing
+npx --no-install redweb doctor --json
+```
+
+`--existing` creates only a missing `tsconfig.json`; it does not generate a new app, CSS, or package manifest. Adjust the generated source/output directories for your application. An existing `tsconfig.json` is never overwritten, even if it is incompatible.
+
+`--dry-run` does not create files or directories. `--json` reports a versioned result with `operation`, `root`, `created`, `skipped`, and `planned`. The shared file-plan writer preflights all destinations, including planned directory/file conflicts, case aliases and nonportable segments such as Windows device names, alternate streams and trailing dots/spaces. It rejects symbolic links/junctions in the destination's ancestor chain, including above the chosen project root. Exclusive creation prevents overwriting a file created concurrently.
+
+This is not a transactional installer or a lock on the filesystem tree. An operating-system error during writing can leave completed files, a partial attempted file, or new directories; the error reports completed writes and the attempted destination. Inspect those paths before retrying. Rerunning preserves existing files rather than repairing their contents. Another process must not rename or replace destination directories while generation runs.
+
+## Diagnose without changing the project
+
+```sh
+npx --no-install redweb doctor --json
+npx --no-install redweb doctor --port 8181
+```
+
+The current checks are explicit in the result's `checks` array:
+
+- Node version against the package's current minimum.
+- Redweb installation in the project or its ancestor workspace's `node_modules`.
+- Difference between the invoked CLI and installed library versions.
+- Installed TypeScript (5 or newer) and a root `tsconfig.json`.
+- Effective inherited JSX runtime configuration, syntax/config errors, and legacy-decorator settings.
+- Declared page CSS/templates and duplicate page/route/handler registrations in statically readable TypeScript source.
+- Literal `rw-click`/`rw-submit` names against the owning page/component's public `@action()` methods.
+- Optional temporary bind to `127.0.0.1` to check a TCP port, immediately released on success.
+
+Each finding includes `code`, `severity`, `file`, `message`, and `suggestion`. Source findings also include one-based `line` and `column` when attached to a specific declaration. Error findings produce exit status 1; warnings do not. JSON diagnostic reports go to stdout. Invalid CLI arguments and filesystem failures go to stderr, with exit status 1. `--help` and `--version` require no project.
+
+Doctor loads the installed TypeScript compiler to read configuration and parse source, but never imports or executes the application's modules. It does not perform a full type check, emit files, run application functions/plugins, or apply repairs. These checks do not prove full application correctness or validate every package's semver range. Port availability is a point-in-time loopback check, not a reservation or a test of an external proxy. Dependency discovery currently targets conventional npm-style `node_modules` installations.
+
+## Source checks and their boundaries
+
+The `source` JSON object reports inspected file count, registration-group count, `mode: "static-source"`, and the number of unresolved/limited warnings. It is `null` when configuration or compiler problems prevent source inspection. `checks` lists `source-assets`, `source-routes`, `source-handlers`, and `source-actions` only when the source reader ran.
+
+Supported syntax includes named/namespace TypeScript imports from Redweb, imported local constants, literal strings, constant arrays/objects, known spreads, and simple handler/route constructors. The reader starts with the configuration's source files and follows relative source imports within the project. Declaration files and dependency implementation code are not inspected; an explicitly configured source outside the project can be read, but additional outside-project imports are not followed automatically.
+
+Duplicate paths are checked **within one registration group**, not across independent servers. The reader recognizes `start`, `exportStatic`, `site.export`, `LiveHtmlServer`, `SocketServer`, and `SecureSocketServer`. Handler names are checked in a `SocketRoute` configuration, including classes based on `BaseHandler` and contract handler factories. It does not evaluate arbitrary factory calls, CommonJS destructuring imports, custom boot wrappers, dynamic route additions, or application control flow.
+
+Page assets are checked for registered pages using their decorator's source directory, the owning site's shared-CSS directory, or a statically known explicit `templateRoot`. Shared stylesheet names are deduplicated with site-root precedence, like the runtime. `__dirname` is interpreted as the source directory for this source-only check. Missing assets, directory paths, path traversal, and links escaping the effective root are reported. This does **not** verify compiled/deployed asset copies: keep the starter's build/network tests and production checks.
+
+| Code | Meaning |
+| --- | --- |
+| `TYPESCRIPT_UNSUPPORTED` | Upgrade the project's compiler to TypeScript 5 or newer. |
+| `SOURCE_SYNTAX`, `SOURCE_UNREADABLE` | A configured source could not be parsed or read. |
+| `DUPLICATE_ROUTE`, `DUPLICATE_HANDLER` | A readable registration repeats a path or message type. |
+| `ASSET_UNAVAILABLE`, `ASSET_NOT_FILE`, `ASSET_OUTSIDE_ROOT` | A declared asset cannot be loaded from its effective source root. |
+| `SOURCE_UNRESOLVED` | Dynamic, mutated, escaped, or unsupported source cannot be determined safely. |
+| `SOURCE_LIMIT` | Source count/size or expression expansion exceeded the inspection budget. |
+| `ACTION_NOT_EXPOSED` | A literal binding has no matching public decorated instance method on its statically known owner. |
+| `ACTION_REFERENCE_INVALID` | The literal action name is empty, reserved, missing, or longer than 128 characters. |
+| `ACTION_REFERENCE_UNRESOLVED` | Action names, render output, method exposure, or component ownership cannot be established by the supported source checks. |
+
+### Repair an action binding
+
+If a button says `<button rw-click="saev">Save</button>` but the class exposes `@action() save()`, doctor reports `ACTION_NOT_EXPOSED` at the binding. Correct the name, run doctor again, then run `npm test`. Doctor never calls the action or executes the renderer to discover it.
+
+Action inspection recognizes decorator aliases, literal names (including imported string constants), inherited methods and overrides, method/function-field renderers, conditional literal returns, and returned JSX/`html` constants. Literal HTML templates use the runtime's lexical tag scanner, ignoring comments and raw-text bodies. External templates are inspected for registered pages at their source asset root and have a separate 1 MiB limit. Page and component owners are checked separately.
+
+This is deliberately not a JavaScript evaluator or a full template type checker. JSX spreads (including constant objects), custom JSX wrappers, explicit component-scope attributes, HTML entities in action names, interpolated/dynamic HTML, unavailable inherited implementations, custom decorators, and potentially replaced instance methods produce warnings where encountered. Arbitrary function calls, dependency renderers and all runtime-produced nested markup cannot be proved by source inspection. A warning is a request for application/browser verification, not a hidden success. Keep real tests for reusable helpers, scoped components and dynamic output even when doctor exits successfully.
+
+`const` is not treated as proof that an array/object is immutable. Mutated aggregates, aliases that escape into unknown calls, runtime option spreads, custom class decorators, and constructor initialization that can overwrite names/paths produce warnings rather than guessed facts. A normal starter exposes runtime option overrides, so its `templateRoot` may correctly produce an unresolved warning. Green exit status means **no errors among the selected checks**, not that warnings were resolved or the application was proved correct.
+
+Source selection is limited to 256 files and 8 MiB; expression reading is limited to 50,000 operations and 4,096 entries per expanded array. Cycles and repeated spreads cannot expand without limit. The doctor is a read-only diagnostic, not a sandbox for untrusted installed compiler code or a substitute for tests.
+
+The remaining release work is tracked in [the release acceptance checklist](AGENT_READY_ACCEPTANCE.md).

package/docs/CLIENT_DEVELOPMENT.md

@@ -0,0 +1,152 @@
+# 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`;
+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.
+
+## Link the sibling repositories
+
+With `redweb` and `redweb-client` checked out beside each other:
+
+```sh
+cd ../redweb-client
+npm ci
+npm run build
+npm link --ignore-scripts
+cd ../redweb
+npm ci
+npm link redweb-client --no-save --ignore-scripts
+```
+
+Rebuild with `npm run build` in `redweb-client` after editing its source. Redweb's
+link reads the resulting `dist` files directly; no repeated packing or dependency
+installation is needed. The link is local development configuration, not a saved
+dependency or a change to either lockfile. Running `npm ci` in Redweb replaces it
+with the locked registry dependency; repeat the link command afterward.
+
+The README and recipe setup use the published client without a separate checkout.
+To check that printed setup and the optional contributor linking workflow independently,
+set `REDWEB_CLIENT_CHECKOUT` to the absolute path of the matching client checkout
+and run `npm run verify:client:link` from Redweb. It copies the client's build
+inputs, uses an isolated npm global prefix, executes the documented initialization,
+installation and linking commands, then runs the realtime starter's real HTTP,
+WebSocket and process tests. No client override is installed. Resolution is checked
+from the installed Redweb package, and all four rebuilt client bundles must match
+the checkout's existing build. Developer inputs and the existing link are checked
+afterward. The interactive `npm run dev` is covered by the separate watcher gate,
+not this check. The first case verifies default registry setup; the second verifies
+optional local development without changing the developer's existing link.
+
+Verify the resolved entry from Redweb:
+
+```sh
+node -p "require.resolve('redweb-client/live-html')"
+npm run verify:live-html:browser
+npm run verify:browser:coverage
+npm run verify:client:source-coverage
+```
+
+The first browser gate checks real server-side counter/chat, dashboard, form and
+rendering behavior. The coverage gate instruments every bundled Live HTML module
+separately from the transport. Both use real HTTP/WebSockets and native browser
+APIs. `npm run measure:browser:client` measures the transport separately; its
+remaining native-browser coverage gaps are not waived by the rendering results.
+Client unit tests include isolated transports and an explicitly simulated stale
+timer callback; its integration tests use real connections and timers.
+
+The source-coverage command instruments original client modules once and shares
+their maps between Node and Chromium. It checks every test file reported exactly
+once, compares plain/instrumented results, verifies unchanged inputs and saves
+separate contributions. Plain browser candidates must equal the linked build.
+Raw worker files are written directly to `coverage/client-source/<run-id>/workers/`
+before parsing, so command, JSON and collection failures cannot discard them during
+temporary-workspace cleanup. Terminal recording reuses the shared summary helper;
+recording errors remain failures and preserve any retained-workspace location.
+`npm run verify:client:coordinator:coverage` checks the private coordinator with
+explicit boundary units and real preflight subprocesses. The full source command
+also runs real Vitest failure fixtures before the unchanged complete client gate.
+Those fixtures require the linked client's installed development dependencies;
+the registry-only CI coordinator job does not claim to run them or the full client.
+Coverage of generated recorder/configuration strings is not coverage of their
+generated programs; the native fixtures and full gate execute those separately.
+
+The combined gate now passes its unchanged 100% threshold: 791 statements, 521
+branches, 125 functions and 659 lines. The redundant empty-entry queue branch was
+removed because the private queue is dense and its length is checked immediately
+before removal, without an intervening callback. A shared disposed-client guard
+also fixes new sends/requests being accepted into an unusable queue after disposal.
+Unit and real-socket regressions cover that failure, queued ordering, cancellation
+before opening and no replay after reconnect. Verified client commit: `859487b`;
+source/browser run: `cc9aead6-cfbb-44af-aba6-94124ab03419`.
+
+This is distinct from the standalone client's Node-only V8 report, which still
+fails its unchanged thresholds because it does not exercise the browser modules.
+Neither denominator is substituted for the other. The canonical client `npm run check` validates
+the matching link before building, runs build/types, then delegates to the full
+combined original-source Node/browser gate. It requires this matching sibling
+Redweb checkout and Chromium, and passes for the verified development pair.
+The client's default `npm test` delegates to the same `npm run check` path; the
+original Node-only V8 diagnostic remains available as `npm run test:v8`, with
+unchanged thresholds and its known missing-browser coverage failure. This is an
+explicit choice of the combined original-source gate, not a V8 coverage fix.
+The preflight works without built client bundles, so a fresh linked checkout can
+reach its first build. Wrong/missing checkouts fail instead of checking another
+installed client. No duplicate browser harness or production dependency was added.
+
+## Release boundary
+
+For an isolated packed-pair check before publishing, explicitly select a client
+tarball. This does not replace the development link or modify repository lockfiles.
+For example, from Redweb in PowerShell (use a fresh output directory):
+
+```powershell
+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
+npm run verify:live-html:package
+Remove-Item Env:REDWEB_CLIENT_CANDIDATE
+```
+
+Use the actual filename printed by `npm pack` if the client version changes.
+The verifier installs both tarballs in a temporary consumer with an explicit local
+override, checks npm integrity and every browser/CommonJS bundle, and resolves
+the client from the installed Redweb package. It compares fingerprints before and
+after testing. The shared browser phase exercises the server-driven
+counter, two-user chat, escaping, draft preservation, reconnect and disconnect
+presence. The broader package gate verifies generated consumers and source-free
+production execution using the isolated runtime dependencies. Certificate checks
+stay enabled; a machine needing its system trust store can use Node's
+`--use-system-ca` option.
+
+Both registry and candidate paths copy the unchanged browser acceptance/coverage drivers
+and their required fixtures beside the extracted package. It never overwrites
+packed application code. Four individually linked development tools support the
+checks; client, WebSocket, Express and Zod resolution must stay inside the isolated
+consumer. The full browser driver and plain/instrumented frontend and refresh
+checks run through bounded child processes. Their temporary profiles stay inside
+the owning workspace, and reports survive under `coverage/packed-browser/<id>`.
+Original package files, copied test bytes and client fingerprints are checked even
+on failure. The runtime coverage report must identify the selected client bundle.
+This is installed-runtime testing with external test tools, not a production-only
+installation or full original-client-source coverage. The frozen browser driver
+does not itself prove that every individual shutdown error is propagated.
+
+Without `REDWEB_CLIENT_CANDIDATE`, the command keeps the ordinary registry path;
+it does not use or infer the local npm link. The installed version, registry URL
+and integrity must match Redweb's lockfile. Both paths compare the installed
+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
+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
+temporary consumers. Latest-head CI, the documented release gates and Redweb's own
+versioned release still remain required; this is not approval to merge or publish.
+No publishing or deployment is part of this local workflow.

package/docs/CLIENT_POLISH_VERIFICATION.md

@@ -0,0 +1,282 @@
+# Client lifecycle and installed-pair verification
+
+This release-polish increment fixes a demonstrated lifecycle bug and closes the
+remaining combined original-client-source branch gap. It does not resume the
+[deferred runtime investigation](RECOVERY_FOLLOWUP_SPIKE.md) or waive any release gate.
+
+## Published client integration: current checkpoint
+
+The maintainer published `redweb-client@0.2.0`. Its actual registry archive now
+contains both root and `./live-html` exports with ESM, CommonJS and declarations.
+Redweb commit `f3c91e9` selects `^0.2.0` and locks the published archive. This
+supersedes the historical client-publication blockers recorded below; Redweb's
+new implementation itself is still unreleased.
+
+- Registry archive: `https://registry.npmjs.org/redweb-client/-/redweb-client-0.2.0.tgz`.
+- Archive SHA-256: `89cc32946cb787aa921b5f383c91201890208d9099da741f0d2571b927b9fa95`.
+- Integrity: `sha512-0bC8j/wJ2WXGuYom5ewijM+sgzRdD5bccnQaQVWqNQBWOkeHH4oXBQTW+3YY2LpnBPT0Hlcxj/OHLCXzD/cZ9Q==`.
+- All four published runtime bundles exactly match the locally tested client build.
+
+The complete default package gate passed without a client override or local link
+in its isolated consumer. Registry and candidate modes now share installed-client
+containment/export/hash verification and the full existing browser harness. The
+registry mode additionally checks the version, URL and integrity against Redweb's
+lockfile. Developer links and the client's user-edited version manifest were preserved.
+
+- Packed Redweb SHA-256: `e773a5270bf66719cb0c83f499301d5a6a19fda2b9a8e24b673519dc7ac8af8a`.
+- Report: `coverage/packed-browser/3b890ae9-2b40-4bfd-8df1-f58c0fb9eb65/report.json`,
+  SHA-256 `cb8055893ed906b4d6739a54913bc25e45063040924d5136099c2265eba4ff19`.
+- `candidateOnly` is false; 190 original package files, 23 harness files and four
+  explicitly external development tools passed identity checks.
+- Actual counter/chat, reconnect/disconnect, full browser acceptance, all six
+  starters, executable recipes and source-free consumer execution passed.
+- Runtime run `46c7aa29-bd08-4aac-aee1-13e1acc01843`: all-four 100% over
+  426 statements, 262 branches, 64 functions and 351 lines.
+- Refresh run `6a1a3e5c-707f-428e-a454-f4fd15141cd9`: all-four 100% over
+  82 statements, 44 branches, 12 functions and 71 lines, including real bfcache restoration.
+- Eleven filesystem unit tests cover both client verification helpers at all-four
+  100%; `coverage/registry-client-helper/coverage-final.json` SHA-256
+  `c40ccac1581f7fef467b9b0af6ae9792743baccc243505b4abc9a3be510ce363`.
+
+After that archive was verified, the unreleased quickstart was simplified to
+install the matching Redweb tarball and obtain its published client automatically.
+The printed commands passed a separate clean-install integration test, with no
+client checkout, override or symlink. The optional contributor workflow also passed
+actual isolated `npm ci`, build and `npm link`, preserving developer inputs. Both
+generated realtime applications passed their 14 HTTP/WebSocket/process tests;
+the two workflow tests passed in 47.631 seconds. The interactive development
+watcher is intentionally covered by its separate lifecycle gate, not these tests.
+Four documentation unit tests passed with all-four 100% coverage of
+`Documentation.js`; report `coverage/registry-setup-docs/coverage-final.json`
+SHA-256 `6172507dae191592c5b9002f0d69848150e3be6317ad2a9d3d8b98a57c884345`.
+Generation freshness and all three TypeScript configurations passed. These later
+quickstart/prose changes are not claimed to be inside the earlier full-gate archive.
+
+The final scoped package-tool regression passed 76 tests in nine suites (201.158
+seconds), with all-four 100% coverage across its nine helpers, including the new
+shared installed-client verifier. Report: `coverage/package-tools/coverage-final.json`,
+SHA-256 `6dd5988e3f00ada240a7ba590c41dfa2159845e198ec00f043616688650cab5f`.
+The senior critic approved the implementation and evidence after stale coverage
+and blanket mock-free claims were corrected. Integration remains mock-free;
+the dashboard cleanup fault injection is explicitly identified as a unit test.
+
+The environment remains Windows, Node 22.21.0 and Chromium 152.0.7977.64.
+Latest-head CI, website alignment, Redweb publication and the bounded Ubuntu
+recovery decision remain open. No failed recovery threshold was waived.
+
+## Runtime change
+
+A disposed `RedwebClient` with outbound queue capacity previously accepted new
+`sendRaw`, `send` and `request` work, despite never being able to connect again.
+Unit and real-WebSocket regression tests failed before the fix. One guard in the
+shared transmit path now rejects all three paths, including cleanup of a rejected
+request's pending state. The tests pass after the fix.
+
+The private outbound queue is dense and synchronously length-checked before
+`shift()`. Removing an impossible undefined-entry branch simplifies that invariant;
+it does not alter supported transport behavior. Real-network tests verify queued
+FIFO delivery, aborted requests being removed before connection, and no replay
+of sent messages after reconnect. No browser or transport API is replaced in
+these integration tests.
+
+The senior critic approved the implementation and regression coverage after an
+unobserved pending-request rejection in a test's failure path was corrected.
+Client implementation commit: `859487b` on `codex/client-lifecycle`.
+
+## Combined original-source verification
+
+Build and type checks pass. All 77 client tests in five files pass in both plain
+and instrumented execution. Sixteen collector/reporting unit and real-process
+tests pass with all-four 100% coverage over the two collection helpers.
+
+The combined gate instruments the same original client TS/JS maps across Node
+and native Chromium. It covers 791/791 statements, 521/521 branches, 125/125
+functions and 659/659 lines. No threshold, source exclusion or coverage-ignore
+directive was added. Static export linkage and erased declarations remain
+structurally verified outside executable coverage, as before.
+
+Browser tests run plain and instrumented feedback/runtime/ownership/morph cases
+(18/13/7/46 assertions), plus client protocol/network cases (58/43 assertions).
+Actual Redweb HTTP/WebSocket actions and native keyboard/pointer selection pass.
+Both plain built bundles match the linked production build; input hashes are
+checked before and after execution.
+
+- Environment: Windows, Node 22.21.0, Chromium 152.0.7977.64, TypeScript 5.9.3,
+  Istanbul instrumenter 6.0.2, esbuild 0.28.2.
+- Final run: `cc9aead6-cfbb-44af-aba6-94124ab03419`,
+  `2026-08-30T22:24:53.089Z`–`2026-08-30T22:25:05.008Z`.
+- Summary: `coverage/client-source/cc9aead6-cfbb-44af-aba6-94124ab03419/summary.json`,
+  SHA-256 `395eb78997106e81d5d1370b0d977add9ae0f23c3ff687d07998df93f9db94c8`.
+- Coverage: same directory's `coverage.json`,
+  SHA-256 `8673e236f675d741cb0f55d4f4bf630f2e2a50c2f2f76f856622558491ac8009`.
+
+This is tracked original-source coverage, not exhaustive optional-chain or
+compiler-generated V8 branch coverage. At the start of this increment, the client's
+`npm run check` failed because it used only the Node-only V8 command, which does
+not exercise browser modules. That underlying command is now `npm run test:v8` with
+unchanged thresholds and an unresolved result; the comprehensive command update
+below does not reclassify the earlier failure as a pass.
+
+## Matching installed artifacts
+
+The full candidate package verifier exited normally with a passed result. It
+installed the fixed client tarball alongside the Redweb tarball in a temporary
+consumer, without changing the developer link or repository lockfiles. It passed
+counter/chat rendering, reconnect and disconnect presence, the unchanged full
+browser acceptance, rendering/refresh coverage, all six starters, executable
+documentation and source-free production execution, additions and consumer checks.
+
+- Redweb at `3b247bc` before these evidence-prose updates: archive SHA-256
+  `6dfc9984245567248adbf8e1538f55d3725039cd3a0a6df6bf93726d5e589965`.
+- Fixed client archive: `coverage/client-polish-20260830T2225/redweb-client-0.1.0.tgz`,
+  SHA-256 `464e70bcb326c8d108d81d13d979e00700ae1ad093d2825fc35acf2e6e661875`.
+- Packed browser evidence: `coverage/packed-browser/64d840c3-fd42-41ad-8e38-87b4e4bb7d19/report.json`,
+  SHA-256 `4384b90fc7d8a509e33db3ce2694f7c1f3b53b3ed662b7c97761d2a765b4de64`.
+- All 189 original package files and 23 copied harness files passed identity/ownership
+  checks. The four external development tools remain explicitly disclosed.
+- Packed runtime run `b73299ce-521b-4a46-baa7-9da0ea6d87f3` and refresh run
+  `28d1d1ff-942e-4929-a92e-546a9f6c8d35` passed all-four 100% coverage for their
+  respective scopes. Runtime measured 426 statements, 262 branches, 64 functions
+  and 351 lines; refresh measured 82/44/12/71 respectively, including observed
+  back-forward-cache restoration.
+
+The source, linked build and installed candidate agree on the Live HTML bundle
+SHA-256 `26cae5402947d27d405cecaf2cafc0638cb0030663a7068bb487d99106aa64f5`.
+The critic independently checked source reports, installed browser evidence and
+all four bundle hashes. Production dependency audit reported zero vulnerabilities
+using the system trust store without disabling certificate verification.
+
+This is a local candidate pair, not the published registry pair. The local client
+still identifies itself as 0.1.0 while that published version lacks the new export;
+it needs an appropriate version and publication before Redweb's saved dependency
+can select it. No npm publication, deployment, merge, CI/recovery-policy change or
+claim that remaining release requirements are complete is made here.
+
+## Full Redweb regression
+
+With the fixed client linked, 853 tests in 82 suites passed in 424.323 seconds,
+with a normal exit and all pretest/generated-documentation/type checks. The owned
+HTTP/WebSocket shutdown cases passed; their historical timeout remains unexplained.
+Instrumented-library coverage is 100% over 5,445 statements, 4,044 branches,
+978 functions and 4,464 lines. No runtime or test inputs changed during this run.
+
+Report: `coverage/client-polish-full-suite.json`; SHA-256
+`bb3c58eadef1aece8c7e761713e6e3da44ad536981e181b4c1d9ddc04d70b004`.
+
+## Canonical client check
+
+Client `ee74017` and Redweb `45a34d5` make `npm run check` use the complete
+original-source Node/browser gate rather than only running Node tests over browser
+code. At that increment, the separate `npm test` V8 command and thresholds remained
+unchanged; the later default-command increment below names it `npm run test:v8`.
+Its failure is still recorded, not presented as fixed.
+
+Before building, `check:link` compares the expected client's canonical path with
+the package installed into Redweb. It resolves the package/junction independently
+of `dist`, allowing an unbuilt linked checkout to pass preflight. Full verification
+still requires normal built-export resolution to match that checkout. Missing or
+wrong linkage fails without fallback. `test:source` rechecks the expected path and
+delegates directly to the existing runner; no browser harness is duplicated.
+
+Twenty-one focused unit and actual-process tests pass, including a linked fixture
+whose normal export cannot yet resolve but whose preflight succeeds without
+building or creating reports. The two collector/reporting helpers remain all-four
+100% covered. The critic approved after catching and correcting that first-build
+problem. Native `npm run check` then passed build/types, all 77 client tests in
+both modes, native Chromium checks and the same 791/521/125/659 covered counters.
+
+- Final canonical-check source run: `6ae0027f-b078-43ee-8069-be386a984007`,
+  `2026-08-30T22:42:44.784Z`–`2026-08-30T22:42:56.970Z`.
+- Summary: `coverage/client-source/6ae0027f-b078-43ee-8069-be386a984007/summary.json`,
+  SHA-256 `694dadb8082a1430b08c4829e4560d3dc131d324d58bc41ddd9c6ceae27bd4df`.
+- Coverage JSON SHA-256 remains
+  `8673e236f675d741cb0f55d4f4bf630f2e2a50c2f2f76f856622558491ac8009`.
+- Helper coverage: `coverage/client-check-preflight/coverage-final.json`,
+  SHA-256 `7305ad80c8bb09e5dc1d6715889fcfb6fca2836620329da9bf75854bb056b4a2`.
+
+The earlier full regression and packed archives precede these command/preflight
+and README changes; their production source and all four client bundles remain
+unchanged. These later changes are verified by the focused real-process checks
+and the actual canonical command, not claimed as another full package run.
+
+After the final evidence update, generated-documentation and all type/pretest
+checks passed, along with 25 focused documentation/preflight/report tests and two
+real generator/release-immutability cases. The critic independently rechecked the
+final source report hashes and unchanged client bundles. Both development links
+and dependency lockfiles remain unchanged.
+
+## Default test command
+
+The client now delegates `npm test` to that same complete `npm run check` path.
+The original `vitest run --coverage` command is preserved as `npm run test:v8`;
+its thresholds and known Node-only missing-browser failure are unchanged. This
+chooses the documented combined original-source denominator for the default
+command; it does not retroactively fix the V8 diagnostic. No runtime, tests or
+coverage instrumentation changed. The client README now reflects the current
+77-test inventory and passing original-source metrics instead of stale failures.
+
+Actual `npm test` passed linkage preflight, build, types, 77 tests in each mode,
+native Chromium acceptance and all 791/521/125/659 authored counters. The run
+completed normally at `2026-08-30T22:56:53.072Z`, on Windows/Node 22.21.0 and
+Chrome 152.0.7977.64. Evidence:
+
+- `coverage/client-source/a7c2bcd8-bc07-4496-b8a1-571e40d68288/summary.json`,
+  SHA-256 `f5770e60d8c011da0874ba2094dbe07904a3f6fdaed7a772f6dbd053b60f3e8b`.
+- Coverage JSON SHA-256 remains
+  `8673e236f675d741cb0f55d4f4bf630f2e2a50c2f2f76f856622558491ac8009`.
+
+The senior critic approved the nonrecursive delegation and explicit denominator
+boundary. Final README wording was corrected after this run; production source,
+test/configuration inputs and built bundles did not change. Matching registry
+publication, latest-head CI and remaining release gates are still outstanding.
+
+The subsequent full linked Redweb regression passed 858 tests across 83 suites
+in 421.094 seconds, with all 5,445 statements, 4,044 branches, 978 functions and
+4,464 library lines covered. No runtime/test inputs changed during that run.
+Report: `coverage/polish-final-core-suite.json`, SHA-256
+`73e41db9f26285b13aa293e168be8b8a012d0824403d31b750ae8020772721aa`.
+The README and guide's stale current coverage/command claims were corrected
+afterward; the type/generated-documentation preflight was rerun for that prose
+increment. Production dependency audit reported zero vulnerabilities with system
+certificate trust enabled, without disabling TLS verification.
+
+## Current package and performance checkpoint
+
+Redweb `28f9c62` and client `a8b6a9f` passed the complete isolated candidate
+package gate on Windows/Node 22.21.0/Chrome 152.0.7977.64. This includes the
+server-driven counter, two-user chat, disconnect/reconnect presence, dashboard,
+full browser acceptance, runtime/refresh coverage, generated applications,
+executable documentation and source-free consumers. The process exited normally
+and completed owned-workspace cleanup. Nothing was published or deployed.
+
+- Redweb archive SHA-256:
+  `f2a8649dfcf83f6fba6351a4bfdf39bb50d85ffde59e09d2b2e62c9b4fd10511`.
+- Client archive: `coverage/client-default-20260830-2259/redweb-client-0.1.0.tgz`,
+  SHA-256 `86ad220edad8a00010659c1c89028de937ea84dfe35b13ac747cac39bf10a440`.
+- Packed browser report:
+  `coverage/packed-browser/9caf08f4-7cc6-4d7b-9ca5-e15b4a229edc/report.json`,
+  SHA-256 `9de780f16203fcde0d1cb3f22fab540978a0a7af64cf6a6b383bc18c842e0857`.
+  It verifies 190 original package files, 23 unchanged harness files and four
+  explicit external development tools. All four client bundles match the built
+  source-verification inputs. Runtime and refresh coverage each remain all-four
+  100%; the refresh check observed actual back/forward-cache restoration.
+
+After the package process terminated, the following gates ran sequentially with
+their default workloads and limits, without diagnostic or coverage overrides.
+Every command exited successfully on its first run in this checkpoint:
+
+| Gate | Observed result |
+| --- | --- |
+| `verify:load` | 32 clients, 3,200 messages, 5,789 messages/second, 6.97 ms p99; slow consumer contained |
+| `verify:memory` | 500 connections, three trials; 1,880.704 bytes/connection incremental metadata against 2,048 maximum |
+| `verify:live-html:load` | 200 expired renders, 110 live clients; 8,052,960-byte heap delta |
+| `verify:jsx:performance` | 10,000 component rows in 49.7 ms; 1.3 MiB retained |
+
+These are bounded Windows checkpoint results, not a recovery, extended-soak,
+cross-runtime or registry-release certificate. The existing Ubuntu/Node 22.23.2
+recovery failure remains unresolved, and the predeclared comparison has not run.
+The local Docker Linux engine is unavailable and WSL lists no Ubuntu environment;
+no alternative platform was substituted. Publication of a newly versioned client,
+Redweb dependency/lockfile integration, final-head CI, website alignment and the
+explicit recovery decision remain open. This evidence-only section was added
+after packing and does not claim its own text was in the tested archive.