redweb 0.12.0 → 0.13.0

package/docs/DEVELOPMENT.md

@@ -0,0 +1,79 @@
+# Development refresh and inspection
+
+This API is **unreleased**. Use the matching packed candidate rather than assuming it exists in the published package.
+
+## Browser refresh
+
+The generated `npm run dev` command enables browser refresh while rebuilding and restarting your application. No extra application code is needed. For an existing Live HTML application, enable it explicitly:
+
+```ts
+const app = start(CounterPage, { development: { refresh: true } });
+```
+
+Alternatively, set `REDWEB_DEV_REFRESH=1` only for your development process. Explicit `development: { refresh: false }` overrides that environment flag. Setting `NODE_ENV=development` alone enables neither refresh nor inspection. Both features are refused at construction under `NODE_ENV=production`; changing environment variables after construction is not a mode switch. `npm start` does not set the refresh flag. Keep it out of production environments.
+
+On direct loopback access, the initial HTML embeds the serving process's revision. The browser polls the same listener sequentially, with a two-second request deadline and one second between completed attempts. Only a valid, different revision triggers refresh. Failed builds, unavailable listeners, malformed responses and redirects do not cause reload loops. A restart before the external script finishes loading is still detected against the revision embedded in the original document.
+
+Clean pages reload automatically after a new revision appears. The edit guard conservatively keeps the current document if it observes input/change events, sees differing form defaults when it starts, encounters an editable element with focus, or finds contenteditable content. A native, keyboard-operable notice offers **Reload and discard drafts**. Ordinary untouched selects are compared against the browser's actual reset defaults, not simply their `selected` attributes. Once confirmation is required, resetting or submitting a form does not silently permit automatic reload.
+
+This is not autosave or a precise unsaved-change detector. False positives are intentional; custom editors or programmatic changes without input/change events may not be detected. The helper does not persist or transmit form contents, write browser storage, replay actions, or restore files/passwords after reload. It keeps the current DOM while waiting for your decision. Manual navigation, browser termination, and confirmed reload can discard drafts.
+
+The notice uses a shadow root so ordinary reactive root updates preserve it and the application controls' existing focus/draft behavior. Its script, stylesheet and revision fetch are same-origin external resources; your CSP must allow those resources. Navigation away stops polling. History restoration resumes it, including back-forward-cache restoration where the browser supports and chooses it.
+
+### Connections and server state
+
+Keeping the old document does **not** make its old page token/session valid on a replacement process. Existing reconnect rules still apply to a temporary connection outage on the same server. A process restart resets in-memory page/chat/counter state; persistent application data remains the application's responsibility. Actions in flight may have uncertain outcomes. Refresh does not retry them, guarantee completion or migrate state. Reload creates a new page session.
+
+### Access and resource boundaries
+
+Refresh is for direct `localhost`, literal `127.x.x.x`, or `[::1]` URLs at the listener's actual port. It verifies the actual loopback peer, Host, any supplied Origin, and Fetch Metadata. It does not trust forwarding headers or support custom hostnames, tunnels or reverse-proxy origins. Rejected requests receive no refresh bootstrap; this restriction does not make the rest of your application private. An application can still bind publicly unless you separately set `bind`.
+
+Enabled refresh reserves `/__redweb/development`, `/__redweb/development.js` and `/__redweb/development.css`. They reveal only a boot revision, fixed client code and styling—not inspection snapshots, application state or compiler output. Responses and decorated HTML are no-store. There is no extra listener or server timer. Served `live: false` pages support refresh without a live socket client; `exportStatic()` output remains script-free and never enables it from the environment. Raw `SocketServer`/`SecureSocketServer` do not accept the HTML `refresh` option.
+
+The injected `rw-dev-refresh` element and `__redweb_dev` ID belong to this helper; do not reuse them in application markup. The repository's `npm run verify:development:browser` gate runs actual generated watchers and Chromium against real HTTP/WebSocket listeners, including edited-document confirmation and failed-build recovery. CI runs it separately from the production browser regression gate.
+
+## Inspection
+
+Enable inspection explicitly when starting a development application:
+
+```ts
+const app = start(CounterPage, {
+    port: 8181,
+    development: { inspect: true },
+});
+
+// Read this in your development code, debugger, or integration test.
+console.dir(app.inspect(), { depth: null });
+```
+
+`SocketServer` and `SecureSocketServer` accept the same option and expose the same `inspect()` method. Without the option, `inspect()` returns `null`. Merely setting `NODE_ENV=development` does not enable inspection. Explicitly enabling it while `NODE_ENV=production` throws before routes or listeners are attached. The environment check occurs at construction; changing environment variables afterward is not a runtime mode switch.
+
+Inspection itself is an in-process, read-only API. It does not create an HTTP/debugging route, listener, browser script, background timer, or automatic logger; browser refresh is a separate option and never exposes inspection data. Do not expose inspection results through an application endpoint in production. Your existing `redweb doctor --json` command remains the source/configuration checker; it does not inspect a running process.
+
+## What the snapshot means
+
+`inspect()` returns immutable, versioned JSON-compatible data:
+
+- `pages.registrations`: configured route paths, live/shared flags, class names, decorated action/state names, and descriptions of currently available owned components. It never constructs a page to discover its members. Standard decorator metadata and component fields may not exist before first construction, so `instanceMetadata: "unobserved"` means an incomplete inventory, not “this page has no actions.” Static or expired pages can have no current instance even when class metadata was observed previously.
+- `pages.connections`: separate counts for pending HTTP-created sessions, connected sockets, closing transports or disconnect hooks in progress (`detaching`), and disconnected sessions retained for reconnect. An attached socket that is no longer open is not yet a retained/reconnectable session. Shared pages appear once in each registration's instance list even when several visitors use them.
+- `pages.sessions`: bounded per-render descriptions using inspector-local numeric IDs. These are not page tokens, credentials, principal IDs or socket IDs. A reconnect to the same retained page session keeps its renderer ID.
+- `sockets.routes`: registered socket paths and handler names, registered connection counts, draining status, and room/session counts. Runtime-added routes and handlers appear on the next read. `pendingUpgrades` counts currently tracked handshakes. Room names, session identifiers and stored data are omitted. A registered raw connection is not a promise that every transport is currently open; lifecycle cleanup may be in progress.
+- `history`: the latest reactive state invalidations and flush attempts. A state invalidation lists the member/component name and affected render-owner IDs. An empty affected-owner list means no current reactive owner read that member. Several invalidations can be batched into one flush.
+
+Page-session and underlying socket counts describe overlapping resources—do not add them together as independent visitors. Counts remain available independently of truncated detail lists. A description failure yields `available: false` for its section without reflecting exception text.
+
+## Render history is not delivery tracing
+
+`flush-started` reports whether the attempt is a reconnect/attach snapshot and which owners were dirty. `flush-completed`, `flush-superseded`, and `flush-failed` describe that attempt, with elapsed milliseconds. Completion can mean unchanged HTML, no transport write, or a transport write that the peer did not receive. It is **not** a delivery acknowledgement. Supersession means a disconnect, disposal or generation change made the attempt obsolete.
+
+History does not attribute an invalidation to a particular action: timers, services and application code can also assign state. It does not retain action arguments, state values, HTML, request headers, cookies, query parameters, identities, socket contexts, or exception messages. It does not serialize getters or call action/render/lifecycle callbacks to produce a snapshot. Application accessors replacing declaration fields are skipped; standard action metadata excludes replaced accessor methods. This is not a security sandbox against hostile JavaScript Proxies or global monkey-patching.
+
+The history observes the reactive TSX renderer's connected update path, starting with socket attachment. Initial HTTP rendering, static output, changes with no connected reactive renderer, and nonreactive template `redweb:state` transport messages are not traced. `pages.sessions[].reactive` distinguishes those sessions. Existing runtime failure diagnostics and application tests remain necessary.
+
+## Bounds and overhead
+
+History retains at most 256 entries per inspected server and only primitive metadata; each event's owner list retains at most 100 names. Current page/socket description lists retain at most 100 items each and share a separate 1,000-item budget per snapshot. Lists include `total` and `truncated`. Labels are limited to 128 UTF-16 code units. Names and route paths are application-defined declarations: do not put secrets in them. The local history's `total` is its sequence counter, including any contained recording failure; retained entries may therefore have gaps.
+
+Inspection selects a specialized renderer once for the enabled server. Ordinary reactive invalidation, flush, and socket-message paths have no inspector callbacks or added inspection branches. Disabled servers retain the original renderer class. The only ordinary rendering seam is renderer-class selection when a page session is constructed. Enabled inspection deliberately does extra metadata work and allocations; its timings are diagnostic observations, not production benchmarks.
+
+Shutdown removes page sessions and connections through the existing lifecycle. The bounded primitive history remains readable while you retain the server object; it does not keep disposed page instances alive. The inspector's local ID table uses weak keys.

package/docs/DIAGNOSTIC_COMPATIBILITY.md

@@ -0,0 +1,76 @@
+# Diagnostic runtime compatibility
+
+This increment fixes private verification tools, not Redweb's public runtime or
+the recovery acceptance contract. The existing recovery workloads, deadlines,
+thresholds and historical evidence remain unchanged. It does not establish
+release readiness.
+
+## Confirmed causes and narrow fixes
+
+- Node 18.20.8 and 20.20.2 reject `--trace-flush-code`. Trace workers now use
+  `--trace-flush-bytecode` on those major versions and retain the modern flag on
+  Node 22/24. These traces have different scope; bytecode flushing is not proof
+  of all code flushing. Reports retain the actual flags and runtime identity.
+- Node 18 lacks `--no-log-source-position`. Omitting it emitted prohibited
+  source-position/feedback records in a real test. Code/deoptimization logging
+  therefore rejects Node 18 before either worker or an output directory starts;
+  no privacy assertion is weakened. Other diagnostic modes remain available.
+- Legacy V8 heap-snapshot streams never completed their destroy callback,
+  causing an actual Node 18 capture timeout. Node's upstream fix is documented in
+  [PR #58846](https://github.com/nodejs/node/pull/58846). The capture owner uses
+  `Readable.wrap` only when the snapshot's existing `_destroy` signature has no
+  callback parameters; modern streams retain their original pipeline. This is
+  read-only compatibility with the known implementations, not a guaranteed
+  future capability API. A major-version cutoff would miss older Node 20/22/24
+  releases before that upstream fix.
+- The output-limit regression now snapshots a small owned child instead of the
+  entire Jest process. It still verifies the actual one-byte limit, poisoned
+  session and exclusive file creation without mocks or increased deadlines.
+  This bounds the test workload; it is not proof of the cause of every prior CI
+  timeout.
+
+The 64 MiB file limit does not bound V8's synchronous snapshot-generation memory
+or pause. Existing process ownership/deadlines remain necessary. Heap graphs
+remain private local artifacts and are not committed or uploaded.
+
+## Verification
+
+Full local regression at `daacdac` passed `npm test -- --runInBand --silent`:
+863 tests across 83 suites in 419.852 seconds, including pretest/type checks.
+Instrumented library coverage is all-four 100%: 5,445 statements, 4,044 branches,
+978 functions and 4,464 lines. The local `coverage/coverage-final.json` SHA-256 is
+`546711819397028d98d5a45f6983919ec45a04231d985b31b0b671743e0b796e`.
+This library scope is separate from the diagnostic capture scope below and does
+not imply all repository tooling/browser sources are covered. The documentation
+catalogue was regenerated and checked; hosted final-head CI remains pending.
+
+Sequential focused Jest runs passed 34 tests across four suites on Windows:
+Node 18.20.8, 20.20.2 and 22.21.0. Suites cover flag units, real diagnostic workers,
+native code-log privacy/preflight rejection, deoptimization parsing boundaries,
+and real network heap captures. The Node 18/20 Jest runs preceded the final
+signature refinement with equivalent paths; Node 22 ran the final source.
+
+The final source additionally passed eight native tests on Node 18 and eight on
+Node 22, sequentially, combining original-source V8 coverage for legacy and
+modern capture paths. Only `scripts/diagnostics/ClientHeapCapture.cjs` is claimed
+at 100% here: 56 statements/lines, 17 branches, three functions. This is not
+whole-diagnostic or whole-repository coverage. Node 24 execution of this change
+remains a hosted CI gate, not a local result.
+
+- Capture source SHA-256:
+  `949e63376b402b7202b3a23e8bc0c381681766c79091b9a9c82156235048ae38`.
+- Local report: `coverage/compatibility-capture-runtime/coverage-final.json`.
+- Report SHA-256:
+  `d166288f7cce3d35441f6f2e1457a331631cf082383665660493b6c5b514521c`.
+- All matching native report ranges fit the same 2,553-character original source;
+  Jest-wrapped source was not merged into this coverage result.
+
+Rejected candidates are not passes: omitting the privacy flag leaked forbidden
+records; wrapping every snapshot caused a Node 22 premature-close failure;
+earlier concurrent attempts also timed out. Final focused runs were sequential.
+No recovery gate was retried or relaxed to qualify these changes. The senior
+critic independently inspected the final code and hashes and gave scoped
+approval, explicitly not release approval.
+
+The separate recovery acceptance decision remains documented in
+`docs/RECOVERY_COMPARISON.md` and `docs/RECOVERY_FOLLOWUP_SPIKE.md`.

package/docs/DOCUMENTATION.md

@@ -0,0 +1,37 @@
+# Maintaining executable documentation
+
+Edit the canonical Markdown guides listed in `docs/topics.json`, API/article/example metadata in `docs/reference.json`, or the maintained applications in `recipes/` and `examples/live-html/`. Do not edit `docs/generated.json` by hand. Reference entries can select a recipe file or a maintained snippet under `docs/snippets/` instead of duplicating source code.
+
+`npm run generate:docs` builds a deterministic, version-labelled catalogue containing topic Markdown, full public TypeScript declarations, a compact `llms.txt`, and complete recipe files. Recipe files come from the exact same `projectFiles()` implementation used by `redweb init`. Chat continues to reuse the canonical component example. Markdown code fences expand when necessary so nested Markdown/readme examples remain intact.
+
+The README's marked realtime and HTTP/WebSocket application blocks are generated from those same recipes. Its setup block uses the same channel-aware commands as recipe pages, including the version notice, directory change, and matching artifact for both initialization and installation. Other README prose is preserved. Package/test preflights reject stale, missing or duplicate blocks.
+
+The generated catalogue is included in the npm tarball but is not loaded by the HTTP/WebSocket runtime. A site or a separate read-only documentation adapter can consume the same JSON. Each page has a stable ID, versioned Markdown URL, source path, summary, and SHA-256 content hash. Recipe pages also contain their complete file lists. Hashes identify content, not package authenticity or signatures.
+
+Task-oriented guides live under `docs/guides/` and are registered in `docs/topics.json` with a `recipe: { template, file }` selection. Their walkthroughs explain the task; generation appends the same version-correct setup and exact selected starter source used by the initializer/API examples, plus a link to the complete recipe. Guide pages do not duplicate recipe `files` collections. The site selects current-version guides for its task cards and resolves historical guides and file downloads against their own catalogue version. Dashboard setup provisions an explicit account after installation and before development starts.
+
+API articles retain their ELI5 explanations, practical examples, walkthroughs, methods, and production cautions. Each API section and capability example also has an individual Markdown page. The shared HTTP/WebSocket example comes from the complete `http-ws` starter, exercised against both the checkout and packed package; it uses one listener with separate route and message-handler classes and the shared entrypoint lifecycle helper. Historical release snapshots retain their original source/examples.
+
+## Version boundaries
+
+Development output uses `/docs/reference/unreleased/`. Its package metadata version is informational: it does not claim that the published package of that version contains new behavior. Development recipe commands explicitly require the matching tarball for both initialization and installation.
+
+For a release, first update the package version and move the pending changelog entries into that version's section. Run `npm run generate:docs -- --release`. This creates a snapshot in `docs/releases/<version>.json` and updates the current catalogue. An existing release snapshot cannot be overwritten with different content. Commit the snapshot with the release. These commands do not publish npm or deploy the website.
+
+`npm test` and `npm pack` check generated content for drift. `--check` preserves the existing catalogue's channel rather than silently turning release documentation into development documentation. Run `npm run generate:docs` explicitly to start documenting the next unreleased increment.
+
+## Verification scope
+
+Unit tests check determinism, version labels, links, hashes, fences, and identity with the initializer's file plan. Real integration tests extract application files from the actual Markdown code fences, compile them, execute the shipped HTTP/WebSocket tests, remove source from the deployed location, and rerun those tests. The packed-package gate repeats this against the extracted tarball, including checking that packed docs match packed source.
+
+Complete recipe pages are executable programs. Topic/API snippets remain explanatory and are not all independently runnable; public declarations are separately covered by the package's type-test suites. Do not claim that every illustrative snippet or generated browser branch is covered by library coverage metrics.
+
+Website export, published-version availability, read-only MCP access, and fresh-agent benchmarks have separate acceptance gates. Generating this catalogue alone does not complete those requirements or guarantee agent discovery.
+
+The optional MCP integration reads this same catalogue rather than regenerating or duplicating documentation. See [agent access setup and limits](AGENT_ACCESS.md); its dependencies and tests are separate from the normal library runtime.
+
+## Website consumer
+
+The separate Redweb site imports this catalogue through `npm run sync:docs -- /absolute/path/to/redweb`; after a matching release is installed, `npm run sync:docs` reads that package by default. It does not import application runtime code from the development checkout. Its committed generated content allows independent clean-checkout builds.
+
+The site derives its existing API articles, examples, homepage snippets, versioned guides, raw recipe downloads, and agent-readable indexes from this source. Release snapshots are retained across imports rather than replaced by the newest package's snapshot set. Import preflight and atomic site-build replacement are separate safeguards. Website tests exercise real imports, builds, and HTTP requests for current and historical versions; publishing npm and deploying hosting remain separate actions.

package/docs/FEEDBACK_COMMAND_VERIFICATION.md

@@ -0,0 +1,228 @@
+# Browser-command deadlines for feedback verification
+
+Independent review identified unbounded command promises when the feedback driver
+received a raw debugging connection. A local native probe acquired a genuine
+Chromium tab, terminated its debugging socket, waited for its real close event,
+and returned the unchanged tab to the driver. After 20 seconds the verifier was
+still pending and its actual Redweb server was still listening. The probe then
+explicitly rescued and closed its resources. No browser/server methods or timers
+were replaced. This is a verifier hang, not an application WebSocket defect.
+
+Pre-fix helper SHA-256:
+`3174a331f8848c4efdff3a4aebdb7feddd4efd3dcb5f5caaedaf7b5cbaef4b76`.
+The retained diagnostic transcription `coverage/feedback-disconnect-before.json`
+has SHA-256 `8e5c442e9a00ad352d1b4c0c4b1175d2c6ae14a701dcb9d814f1c05546d5a0c4`.
+
+## Shared command adapter, unchanged ownership
+
+`browserCommands` bounds evaluation and protocol commands to 15 seconds. The raw
+tab is registered with its caller before the adapter is created. The adapter keeps
+the same socket and delegates through the original method receiver without mutating
+the tab. The coverage caller's duplicate adapter was removed; its separately bounded
+startup validation and final coverage collection remain. The installed-package
+harness copies the same helper, increasing its input inventory from 25 to 26 files.
+
+These command deadlines allow the feedback driver's existing `finally` to shut down
+its server after a disconnected debugging transport. They do not cancel an underlying
+command or establish page-acquisition ownership. In particular, raw `openPage`
+acquisition from the frozen launcher remains unbounded. No unowned timeout race was
+added there, and no complete-acquisition claim is made. The separate native tests
+below now measure all authored feedback-driver paths; complete coverage is not a
+claim that every underlying acquisition operation is bounded.
+
+## Feedback coverage milestone (`9897924`)
+
+At this checkpoint, `npm run verify:feedback:commands` combined nine explicit command-boundary units
+(including labelled fake-clock checks) with six real integration cases. The closed
+Chromium connection case uses actual sockets/timers and checks that the server is no longer
+listening and has no shared pages **before** rescue cleanup runs. The other three
+cases retain real page-disposal/setup failure coverage. Production shutdown wraps
+disposal rejections in `AggregateError`; this work does not claim a native falsy
+shutdown bug.
+
+Two additional Chromium cases run the complete acceptance driver. The successful
+case omits optional callbacks and verifies that its real HTTP listener refuses a
+connection after return. The cleanup-only failure registers an actual decorated
+page whose disposal throws, and verifies error identity, empty shared-page storage,
+listener closure and resolution of an actual pending fixture waiter. No browser,
+server or transport API is replaced. These cases reuse the existing workspace and
+page owners, with a 180-second driver watchdog, independent browser cleanup and a
+bounded drain of the original driver promise. Each has a 360-second outer budget.
+
+That 15-test/four-suite scope passed in 20.765 seconds with all-four 100%
+coverage: 176 statements, nine branches, 14 functions and 162 lines. The adapter
+accounts for five statements/lines, three functions and zero branches; the complete
+feedback driver accounts for 171 statements, nine branches, 11 functions and 157
+lines. Browser coordinator coverage remains separate. The closed-connection test allows 180 seconds
+for bounded launch, 60-second supervision and independent cleanup. Existing failure
+tests now allow 45 seconds instead of inheriting five while server shutdown can
+take 15. Uncertain browser shutdown retains its workspace and independently releases
+local pipe/reference handles; those releases are not proof of process termination.
+That checkpoint allowed 20 minutes in CI and retained coverage for 30 days.
+
+| Exact source | SHA-256 |
+| --- | --- |
+| `scripts/lib/browserCommands.js` | `cc6d26f257a20c8549225772d379a2091288a55719c7aa2f63dc151ce5a1fc76` |
+| `scripts/lib/verify-action-feedback.js` | `8f35661e324f8dd962f80165800cc15e491b9c9a0f0d3261470e9162df6dd028` |
+| `scripts/verify-browser-coverage.js` | `96325de65161f7d68c6da3ea85700e6fccb85b45ddb34c7645cdf5eaeefe8e06` |
+| `scripts/lib/PackedBrowserHarness.js` | `fd9cf313775b77fbebd73a0097efe0c8f5ec830b17f370451f2ed4f3cae39855` |
+
+That checkpoint's report `coverage/browser-commands/coverage-final.json`
+has SHA-256 `5c04776ecc36f5df1753c94afa388d3b509c54425f179a4454006261dec7f18b`,
+matching the initial expanded-scope report under `coverage/feedback-driver/`.
+The critic approved the corrected native tests after requiring exact error leaves,
+an actual waiter promise and preservation of late driver failures. Pretest,
+generated-documentation and all three type configurations also pass.
+
+## Refresh command reuse follow-up
+
+The same native disconnected-DevTools test now also runs the actual refresh
+control driver against its real revision peer. Before correction, it remained
+pending until the 60-second supervisory watchdog fired; the expected command
+deadline was never reached. No browser/server/timer method was replaced.
+Pre-fix refresh-control source SHA-256:
+`0573ef0f8f589f49cc64849285ed61967869e8085dd344246bf8566fca2a8275`.
+
+Generated-app refresh and its shared control driver now reuse `browserCommands`.
+Raw tabs are registered before wrapping. A private WeakSet recognizes already
+bounded facades, so the coverage caller can reuse the same adapter without
+stacking timers or keeping tabs alive. Its duplicate inline adapter was removed;
+coverage cleanup still receives bounded commands, and generated-app cleanup
+continues to use bounded DevTools HTTP requests.
+
+The maintained command now passes 17 tests/four suites in 36.407 seconds: ten
+explicit command-boundary units and seven real integration cases. Both disconnected
+native paths reach their 15-second command deadline and verify actual listener
+cleanup before rescue. The refresh test also verifies empty pending/script sets.
+All-four coverage of the adapter and complete feedback driver remains 100%:
+181 statements, 11 branches, 14 functions and 166 lines. The adapter contributes
+10 statements, two branches, three functions and nine lines. This is not complete
+direct coverage of refresh helpers or either browser coordinator.
+
+Current report `coverage/browser-commands/coverage-final.json` SHA-256:
+`5a4be585d836f0510a4ec80c0fef0a32dbbff3e41330af19af1f158709b45e21`.
+CI allows 25 minutes for the added native case and all declared failure budgets;
+individual command deadlines are unchanged. The critic approved the shared
+wrapper, raw ownership ordering, bounded cleanup and expanded budget.
+
+| Corrected source | SHA-256 |
+| --- | --- |
+| `scripts/lib/browserCommands.js` | `bb2d1de242289f543680e97493cb04fe99ae2f35c89b4e276e1862a1e21336e3` |
+| `scripts/lib/verify-refresh-controls.js` | `a05a1145e636a8e4f7750fff3dd8036aab54fa3ee22bbb6d8bdb068dbca104b2` |
+| `scripts/lib/verify-refresh-coverage.js` | `7062f23e3fcac0273b2c9d41858ad7e95dd519daaa0d70a60e10695930f1d6e9` |
+| `scripts/verify-development-refresh-browser.js` | `ccb01383ef684cb59bc07bcd87e576e7fb08d2c734abfabdb2c047d957449e0e` |
+
+The unchanged native runtime/refresh scopes also pass: 426/262/64/351 and
+82/44/12/71 statements/branches/functions/lines, respectively. Actual case
+inventories match between plain/instrumented runs; back-forward-cache restoration
+was observed. Runtime run: `f5943d26-64ae-4ea1-b754-c917996ccb8b`; refresh run:
+`732f7c31-bfeb-402d-bf2c-4446fb5c26d6`. No public runtime, frozen helper or
+acceptance threshold changed. Raw page acquisition remains a separate open
+boundary; command deadlines do not cancel its underlying operations.
+
+The corresponding runtime/refresh report SHA-256 values are
+`f0067f98198760a5ed07b5536c6ae9a0b8253b65e75e1b998f80dc5c57a42b86`
+and `7392a9a0d69d40bff5cfdf85ae1e21b6699ca60c2f485c38afc8948cdbbdb418`.
+The complete generated-app development gate also passes real TypeScript/CSS
+rebuilds, failed-build recovery, draft/focus retention, explicit discard and state
+reset, plus the shared outage/recovery and input guards. Actual back-forward-cache
+restoration was observed. Pretest, all three type configurations and the four
+documentation units pass for this increment.
+
+The refreshed linked-client authored gate passes its 26 collector/preflight/report
+tests, five worker reports and matching ordinary/instrumented native browser cases.
+All-four authored coverage remains 100% over 791 statements, 521 branches, 125
+functions and 659 lines. Its ordinary browser/transport bundles retain their
+production identities. Run `0248026f-dadf-42fe-bb9a-1bc287f4fbb5` under
+`coverage/client-source/` retains `summary.json` SHA-256
+`c876bc77f0261fff6e7b1f8761cbcd09e26053d802246a44eec431e4387fd876`
+and `coverage.json` SHA-256
+`8673e236f675d741cb0f55d4f4bf630f2e2a50c2f2f76f856622558491ac8009`.
+Both npm links and the client's pre-existing version edit remain untouched.
+
+The complete isolated-package gate subsequently passed with registry
+`redweb-client@0.2.0` and matching identities for all four production bundles.
+Installed counter/chat/reconnect/disconnect, dependency isolation, generated
+additions, authenticated dashboard, all three copied browser phases, source-free
+starters, executable docs, compiled consumers and static export passed. TLS
+verification remained enabled. Tested archive SHA-256:
+`97ab4789755132d66bcdd219b2390879ea4c4657fb273fafe2c8326edf975ee3`.
+This archive predates the final evidence-only documentation additions.
+Report `coverage/packed-browser/ed6f21ed-4300-4645-94e5-6a6842765e4f/report.json`
+has SHA-256 `01d047163d0569b30c0769231486ab815b33b4fac6bc6519bb081f8a18296e39`.
+It records 210 package files and 26 unchanged copied harness inputs, with harness
+SHA-256 `0a0cdf39fa16c8e995de1474fae0d70773594eb96552423cd5215c96a43232b4`.
+The critic approved all eleven actual remote files at implementation commit
+`82156ee`, their evidence identities and all 66 generated pages. The critic also
+approved the three actual remote package-evidence files at `7a0297e`.
+
+The full regression at `7a0297e` then passed 1,488 tests across 142 suites in
+794.914 seconds, with two POSIX-only skips. The unchanged 91-file library retained
+all-four 100% coverage: 5,449 statements, 4,046 branches, 978 functions and 4,468
+lines. Full result `coverage/refresh-commands-full-results.json` has SHA-256
+`7cba49a5fed554ceafbcba91e888b2e00a3ed4d541bb1e2ef216b086fff98e65`;
+its `coverage/coverage-final.json` has SHA-256
+`275f82a20c7ed1389b65ef7d2b3752006926ae85c8dc4800d5dc9c07173cb1ac`.
+The client type check also passed, and a fresh production dependency audit
+reported zero vulnerabilities with TLS verification retained. Later documentation
+corrections and their additional tests are not included in this full-run count.
+Both PR and push workflows for `82156ee` and `7a0297e` subsequently passed.
+Later-head hosted outcomes remain separate; no prior pass is relabelled current.
+
+## Earlier native acceptance and remaining gates
+
+The complete ordinary/instrumented browser-runtime and development-refresh gates
+pass with matching case inventories and unchanged all-four 100% emitted-code scopes.
+Runtime covers 426 statements, 262 branches, 64 functions and 351 lines; refresh
+covers 82 statements, 44 branches, 12 functions and 71 lines. Actual server actions,
+feedback, selection updates, history restoration and outage/draft guards pass on
+Windows / Node 22.21.0 / Chrome 152.0.7977.64.
+
+| Native report | Run | SHA-256 |
+| --- | --- | --- |
+| `coverage/browser-runtime/report.json` | `2813578e-7b5d-4af6-a331-403f2328b15c` | `5bc71d191bd66de750bdb08dd657772c4fb72b10dcd8743936b282e71c6643e3` |
+| `coverage/browser-refresh/report.json` | `fa70d407-f57f-45c3-8793-8a1626db594a` | `fd3b9bcfd5cedb970cc15a3412f21ffcbd05ec10c4830b562c61811045d8ba05` |
+
+The linked-client gate also passes 77 tests per ordinary/instrumented mode, five
+worker reports and actual browser acceptance. Its authored scope remains all-four
+100% over 791 statements, 521 branches, 125 functions and 659 lines. Source-built
+ordinary bundles still match the linked production build. Run
+`3ba3d058-886d-42e7-9e01-d07e64fe2dff` under `coverage/client-source/` retains
+`summary.json` SHA-256 `877858b6ad0b98b0bce825dde8f39f6010682905dfd5acd5574ded9205284aa7`
+and `coverage.json` SHA-256 `4f6c0ce9e07e613366360dbda6dffc0dff0cb16fa02e55cd4470a32a8bb9fb21`.
+The separate collector/preflight/report suite passes 26 tests. The standalone
+Node-only V8 diagnostic remains separate and is not relabelled passing.
+
+Pretest/generated/type checks and four documentation units pass. The critic approved
+the adapter, native test, independent fallback releases, budgets and scoped evidence.
+The actual-PR review approved all 16 remote blobs at `e3b4902`.
+
+The complete isolated-package gate then passed with registry `redweb-client@0.2.0`
+and matching identities for all four bundles. It exercised installed counter/chat,
+dependency isolation, generated additions, authenticated dashboard, copied browser
+acceptance/runtime/refresh, all source-free starters, executable docs, compiled
+action/room consumers and static export. No runtime modules were replaced, and
+TLS verification remained enabled.
+
+Tested archive SHA-256:
+`c2589e8fff6c4247b98b5aa0de47c2244feaefb79351bc0abf4ff4f8c0cbbdcd`.
+This archive predates subsequent evidence-only documentation edits. The retained
+browser phase report is
+`coverage/packed-browser/369c631b-7c8b-4986-9e23-8e8bba9b6a68/report.json`, SHA-256
+`c43cdc79bc50645e8f07d715f29982ce99b15946e2b23714ee17d1c4df0dd237`.
+It records all three browser phases passing, 210 package files, 26 unchanged
+harness inputs, and harness SHA-256
+`ce81b626e0d87bb50edf1856522a3916bdf983dd1629404b7e1ab1a2052608c3`.
+
+The full regression for `69dcbf8` passed 1,469 tests/140 suites in 759.054 seconds,
+with two POSIX-only skips and the unchanged 91-file library at all-four 100%
+(5,449 statements, 4,046 branches, 978 functions, 4,468 lines). The two full-driver
+cases were added after discovery and pass separately; they are not included in
+1,469. Retained full result `coverage/feedback-commands-full-results.json` has
+SHA-256 `b4a5bcb06d59d2759e7a6a7190c9100023916beeb70d062d25f6a02e0d749be9`;
+the corresponding `coverage/coverage-final.json` has SHA-256
+`04c2f534616e477c367126cb5009b7e0496fc832b3e1dfb57e9048b64330952f`.
+Both `659f638`, `9c29a6e` and `e3b4902` hosted workflows passed completely. Latest hosted
+results remain separate and are not presumed passed.
+No npm publication, deployment, frozen-file edit, benchmark waiver or new long-soak
+claim is made.

package/docs/GETTING_STARTED.md

@@ -0,0 +1,58 @@
+# Build a site and its realtime backend together
+
+Redweb renders TypeScript/TSX on Node.js and connects server-owned state and actions to the browser through WebSockets. Use it for live dashboards, chat, collaboration, documentation sites, and socket services. You can use HTTP or WebSockets independently.
+
+It is not React, a browser component framework, a database, an identity provider, or a managed multiplayer platform. Do not use React hooks or import `react/jsx-runtime`. An edge-only host without Node listeners cannot run a live Redweb server; exported static pages need no Node runtime.
+
+## Start with a complete recipe
+
+Choose one of these complete applications:
+
+- [Realtime counter](../recipes/realtime/README.md): the smallest live website, sharing server-owned state between visitors.
+- [Chatroom](../recipes/chat/README.md): reusable stateful components, messages, and live presence.
+- [Site](../recipes/site/README.md): non-live pages with a shared layout and stylesheet.
+- [Socket service](../recipes/socket/README.md): a typed `/match` route with separate join/move/resume handlers.
+- [HTTP and WebSockets](../recipes/http-ws/README.md): one listener, an HTTP health endpoint and a raw `/chat` route with an explicit cleanup owner.
+- [Private dashboard](../recipes/dashboard/README.md): persistent SQLite cards, account sessions and private live updates (Node 22.13+).
+
+Each generated recipe page contains its exact files, commands, limitations, and real HTTP/WebSocket acceptance tests. Follow that recipe's version-specific setup instructions rather than mixing an unreleased example with a published npm version.
+
+Requirements: Node.js satisfying the package's `engines` field and npm. Use a supported Node.js release in production. TypeScript and the development watcher are installed by the starter. No React, frontend bundler or broker is required. Only the dashboard starter uses a database; its native SQLite requirement is recipe-local.
+
+The installation floor is not a security-support promise for old Node releases. See [runtime compatibility, release verification and provenance](RELEASE_TRUST.md) before choosing a production version.
+
+## One development loop
+
+After initialization and installation, `npm test` compiles the project, copies assets, and runs the shipped network tests. `npm run dev` watches source/configuration files, rebuilds, and restarts. Served HTML pages on direct localhost access refresh when the replacement server is ready; detected edits instead produce a confirmation notice that keeps the current document until explicit reload. This is not autosave or browser hot-module replacement; in-memory state and old socket sessions reset on restart. See [development refresh and its guarantees](DEVELOPMENT.md#browser-refresh).
+
+Use `.tsx` for markup and extend `redweb/tsconfig.json`. Colocate CSS with the decorated page/component or declare an explicit asset root. `npm run build` prepares `dist/`; `npm start` runs that compiled application.
+
+When setup fails, run `npx --no-install redweb doctor --json` from the application directory. Fix reported errors and examine unresolved warnings, then rerun the build and real tests. Doctor does not execute application code or prove application correctness. See [diagnostics and boundaries](CLI.md).
+
+## The mental model
+
+- A page is a decorated class. Its `render()` returns server-side TSX.
+- State is server-owned data. An ordinary TSX expression reading `@state()` updates automatically when that property is assigned. Replace arrays/objects rather than mutating them in place.
+- Only decorated actions are browser-callable. Validate and authorize every untrusted input; hiding a button is not access control.
+- A class component owns reusable state/actions and has its own update boundary. Function components are convenient presentation helpers.
+- Pages are connection-scoped by default. `shared: true` intentionally shares one page instance; do not put private visitor data there.
+- Shared in-memory state survives visitors and reloads, not server restarts. Durable cards/history require application-owned persistence. Multiple processes do not automatically share memory.
+- Socket URLs select routes; message `type` selects a handler. Do not add a second `message.action` dispatcher inside a catch-all handler.
+
+See [rendering and lifecycle](LIVE_HTML.md) and [shared socket contracts](SOCKET_CONTRACTS.md) for exact semantics.
+
+For private raw socket subscriptions, see [room authorization and shared request identity](ROOM_AUTHORIZATION.md). Keep authentication, subscription permission, and application-specific write permission explicit.
+
+## Deploy deliberately
+
+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-client@0.2.0` is published and installs automatically through the matching Redweb dependency. Unreleased Redweb changes still require the matching tested tarball until their own release 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).
+
+## Evidence and compatibility
+
+Complete recipe files are executable applications; shorter API snippets explain individual methods and may require surrounding application code. Type-check and test a complete recipe before adapting it. The package verifier runs the documented recipe files against an extracted tarball and actual listeners, not mocks.
+
+Coverage reports refer to instrumented library code. They do not prove exhaustive browser behavior, application security, all generated-example branches, or production capacity. Historical [verification evidence](VERIFICATION_EVIDENCE.md) applies only to its recorded revision/environment; consult the [current release checklist](AGENT_READY_ACCEPTANCE.md) for remaining work.

package/docs/JSX_PERFORMANCE_VERIFICATION.md

@@ -0,0 +1,59 @@
+# JSX performance-verifier correction
+
+This changes the acceptance check, not Redweb's renderer. The previous predicate
+counted 10,000 `<li ` occurrences and required only one escaped label. Executing
+that exact predicate against malformed markup demonstrated a false pass despite
+missing numeric children and closing tags. A separate duplicate-index regression
+also failed before the correction: the verifier accepted the corrupted output.
+Neither result demonstrates that the actual renderer produces incorrect markup.
+
+One short-lived function now compares the complete expected list: every class,
+index, escaped label, numeric child and closing tag. Its independent literal
+oracle does not use the renderer under test. Validation runs after stopping the
+render timer, and its temporary data is out of scope before retained-heap sampling.
+
+The 10,000-row workload, original timing boundary, two GC calls, cleared page and
+output references, negative-growth clamp, five-second render threshold and 32 MiB
+retained-heap limit are unchanged. The stronger oracle is a harness revision;
+it is not a rendering optimization or byte-identical repeat of historical heap
+measurements.
+
+A performance comparison cannot interrupt stuck synchronous JavaScript. CI now
+supervises the default command with a two-minute external deadline. Native tests
+run real CLI subprocesses with 10/30-second command bounds and owned termination;
+the outer test allows 80 seconds for operations and cleanup. Direct manual command
+invocations still need an external supervisor if a hard execution deadline is
+required. No extra runtime worker or timer abstraction was added.
+
+## Scoped verification
+
+Windows / Node 22.21.0: the final maintained command passed 14 tests across two
+suites in 2.408 seconds (the initial focused run passed in 2.560 seconds). The
+maintained `npm run verify:jsx:coverage` command measures the original verifier:
+27 statements, eight branches, four functions and 23 lines, all 100%. CI retains
+this report on success or failure with a separate three-minute deadline.
+
+Thirteen explicitly labelled boundary units cover malformed markup, missing GC,
+slow rendering, excess retained heap, exact limit acceptance, negative-growth
+clamping, sampling order and suppression of success output after failure. The
+native integration test uses the real renderer, process, clock and GC for both
+missing-GC rejection and the complete 10,000-row CLI workload, without API mocks.
+It is separate from clean performance measurement; no native non-finite clock or
+heap defect is claimed from fault injection.
+
+Source `scripts/verify-jsx-performance.js` SHA-256:
+`31e4a1d88a55cecdc3c604d8fb87e911d4e79a180a22517880903830e340aeca`.
+Report `coverage/jsx-performance-tools/coverage-final.json` SHA-256:
+`eb88af0e3318c48abd24fbf30e34ce4819a7ea98287a1c10c6cfb52cbcf0a7ef`.
+
+The senior critic approved the scoped implementation, sampling parity, native
+command budgets and separation of real evidence from boundary fault injection.
+After the full regression exited and before rerunning scoped coverage, one clean
+default JSX command passed 10,000 rows in 48.8 ms with 0.6 MiB retained, against
+the unchanged 5,000 ms / 32 MiB limits. The smaller reported retained heap is not
+claimed as a runtime improvement; the validation allocation pattern changed.
+These 14 tests were added after the preceding full regression had selected its
+test inventory; they are not retroactively included in that run. Hosted review,
+remaining private-tool coverage and the separate unresolved throughput benchmark
+remain distinct release requirements. No npm publication, deployment or merge is
+claimed.