redweb 0.12.0 → 0.13.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "redweb",
-  "version": "0.12.0",
-  "description": "A small Node.js foundation for HTTP, WebSockets, multiplayer services, and server-rendered HTML",
+  "version": "0.13.0",
+  "description": "A small Node.js foundation for HTTP, WebSockets, multiplayer services, and server-rendered HTML",
   "main": "index.js",
   "types": "index.d.ts",
   "bin": {
@@ -20,6 +20,12 @@
       "require": "./client.js",
       "default": "./client.js"
     },
+    "./contract": {
+      "types": "./contract.d.ts",
+      "import": "./contract.js",
+      "require": "./contract.js",
+      "default": "./contract.js"
+    },
     "./jsx-runtime": {
       "types": "./jsx-runtime.d.ts",
       "import": "./jsx-runtime.js",
@@ -36,8 +42,17 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "pretest": "node scripts/build-live-html-examples.js --check && node scripts/generate-protocol-types.js --check && tsc -p tests/types/tsconfig.json && tsc -p tests/types/tsconfig.jsxdev.json && tsc -p tests/types/tsconfig.standard.json",
-    "prepack": "node scripts/build-live-html-examples.js --check",
+    "pretest": "node scripts/build-live-html-examples.js --check && node scripts/generate-protocol-types.js --check && node scripts/generate-docs.js --check && tsc -p tests/types/tsconfig.json && tsc -p tests/types/tsconfig.jsxdev.json && tsc -p tests/types/tsconfig.standard.json",
+    "prepack": "node scripts/build-live-html-examples.js --check && node scripts/generate-docs.js --check",
+    "generate:docs": "node scripts/generate-docs.js",
+    "verify:docs:mcp": "npm --prefix integrations/docs-mcp test",
+    "verify:cli": "c8 --all --src=bin --include=bin/redweb.js --reporter=text --reporter=json --reports-dir=coverage/cli-entrypoint --check-coverage --lines=100 --branches=100 --functions=100 --statements=100 node node_modules/jest/bin/jest.js tests/integration/init-cli.integration.test.js tests/integration/add-cli.integration.test.js --testNamePattern=\"redweb init CLI integration|human and subprocess CLI\" --runInBand --coverage=false",
+    "verify:agents:controls": "node scripts/evaluation/validate.js",
+    "verify:live-html:browser:coverage": "node node_modules/jest/bin/jest.js tests/integration/frozen-live-browser.integration.test.js tests/unit/frozen-live-browser.unit.test.js --runInBand --coverage --collectCoverageFrom=scripts/verify-live-html-browser.js --coverageDirectory=coverage/frozen-live-browser",
+    "verify:evaluation:controls:coverage": "node node_modules/jest/bin/jest.js tests/integration/evaluation-controls.integration.test.js tests/unit/evaluation-controls-boundaries.unit.test.js tests/integration/evaluation-verifier.integration.test.js tests/unit/evaluation-verifier-boundaries.unit.test.js --runInBand --coverage --collectCoverageFrom=scripts/evaluation/validate.js --collectCoverageFrom=scripts/evaluation/verify.js --coverageDirectory=coverage/frozen-controls",
+    "verify:evaluation:prepare:coverage": "node node_modules/jest/bin/jest.js tests/integration/evaluation-prepare.integration.test.js tests/unit/evaluation-prepare-boundaries.unit.test.js --runInBand --coverage --collectCoverageFrom=scripts/evaluation/prepare.js --coverageDirectory=coverage/frozen-prepare",
+    "verify:evaluation:trial:coverage": "node node_modules/jest/bin/jest.js tests/unit/evaluation-evidence.unit.test.js tests/integration/evaluation-trial.integration.test.js tests/unit/evaluation-trial-boundaries.unit.test.js --runInBand --coverage --collectCoverageFrom=scripts/evaluation/run-trial.js --coverageDirectory=coverage/frozen-trial",
+    "verify:evaluation:process:coverage": "node node_modules/jest/bin/jest.js tests/unit/evaluation-process-boundaries.unit.test.js tests/unit/evaluation-evidence.unit.test.js tests/unit/evaluation-process.unit.test.js tests/integration/evaluation-frozen.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/evaluation/seal.js --collectCoverageFrom=scripts/evaluation/process.js --coverageDirectory=coverage/frozen-process-seal",
     "example:counter": "node examples/live-html/counter.js",
     "example:chatroom": "node examples/live-html/chatroom.js",
     "example:cards": "node examples/live-html/cards.js",
@@ -45,15 +60,52 @@
     "example:jsx": "node examples/live-html/jsx-page.js",
     "generate:protocol-types": "node scripts/generate-protocol-types.js",
     "verify:overhead": "node scripts/verify-disabled-overhead.js",
+    "verify:overhead:coverage": "node node_modules/jest/bin/jest.js tests/unit/benchmark-command.unit.test.js tests/integration/benchmark-measurement.integration.test.js tests/unit/benchmark-traffic.unit.test.js tests/unit/benchmark-batch.unit.test.js tests/unit/benchmark-comparison.unit.test.js --runInBand --coverage --collectCoverageFrom=scripts/benchmark-worker.js --collectCoverageFrom=scripts/verify-disabled-overhead.js --collectCoverageFrom=scripts/lib/BenchmarkBatch.js --collectCoverageFrom=scripts/lib/BenchmarkComparison.js --collectCoverageFrom=scripts/lib/BenchmarkWorkload.js --collectCoverageFrom=scripts/lib/measureBenchmarkBatch.js --coverageDirectory=coverage/benchmark-tools",
     "verify:soak": "node --expose-gc scripts/verify-soak.js",
+    "verify:soak:coverage": "node node_modules/jest/bin/jest.js tests/unit/soak-measurement.unit.test.js tests/unit/soak-clients.unit.test.js tests/unit/soak-command.unit.test.js tests/unit/soak-command-evidence.unit.test.js tests/integration/soak-tools.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/verify-soak.js --collectCoverageFrom=scripts/lib/SoakClients.js --collectCoverageFrom=scripts/lib/SoakMeasurement.js --collectCoverageFrom=tests/helpers/SoakCommandEvidence.js --coverageDirectory=coverage/soak-tools",
     "verify:memory": "node scripts/verify-memory-overhead.js",
+    "verify:memory:coverage": "node node_modules/jest/bin/jest.js tests/unit/memory-command.unit.test.js tests/unit/memory-measurement.unit.test.js tests/integration/memory-measurement.integration.test.js tests/unit/verification-workspace.unit.test.js --runInBand --coverage --collectCoverageFrom=scripts/memory-worker.js --collectCoverageFrom=scripts/verify-memory-overhead.js --collectCoverageFrom=scripts/lib/MemoryMeasurement.js --collectCoverageFrom=scripts/lib/VerificationWorkspace.js --coverageDirectory=coverage/memory-tools",
     "verify:load": "node scripts/verify-load.js",
+    "verify:load:coverage": "node node_modules/jest/bin/jest.js tests/unit/load-command.unit.test.js tests/unit/load-traffic.unit.test.js tests/unit/load-measurement.unit.test.js tests/integration/load-measurement.integration.test.js tests/unit/realtime-harness.unit.test.js tests/integration/realtime-harness.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/verify-load.js --collectCoverageFrom=scripts/lib/LoadMeasurement.js --collectCoverageFrom=scripts/lib/measureLoadTraffic.js --collectCoverageFrom=scripts/realtime-harness.js --coverageDirectory=coverage/load-tools",
     "verify:recovery": "node --expose-gc scripts/verify-recovery.js",
+    "verify:recovery:original:coverage": "node node_modules/jest/bin/jest.js tests/unit/original-recovery.unit.test.js tests/integration/recovery-verifier.integration.test.js --runInBand --silent --coverage --collectCoverageFrom=scripts/verify-recovery.js --coverageDirectory=coverage/original-recovery",
+    "verify:recovery:server": "node scripts/verify-server-recovery.js",
+    "verify:recovery:coverage": "node node_modules/jest/bin/jest.js tests/unit/server-recovery-policy.unit.test.js tests/unit/server-recovery-candidate.unit.test.js tests/unit/server-recovery-cli.unit.test.js tests/unit/recovery-split.unit.test.js tests/unit/recovery-coordinator-boundaries.unit.test.js tests/unit/recovery-worker-boundaries.unit.test.js tests/unit/recovery-worker-error.unit.test.js tests/integration/server-recovery-candidate.integration.test.js tests/integration/recovery-split.integration.test.js tests/integration/recovery-channel.integration.test.js --runInBand --silent --coverage --collectCoverageFrom=scripts/lib/ServerRecoveryPolicy.js --collectCoverageFrom=scripts/lib/ServerRecoveryCandidate.js --collectCoverageFrom=scripts/verify-server-recovery.js --collectCoverageFrom=scripts/diagnostics/recovery-split.cjs --collectCoverageFrom=scripts/diagnostics/recovery-split-worker.cjs --coverageDirectory=coverage/server-recovery-acceptance",
+    "verify:assets:coverage": "c8 --all --src=recipes/shared --include=recipes/shared/copy-assets.cjs --reporter=text --reporter=json --reports-dir=coverage/recipe-assets --check-coverage --lines=100 --branches=100 --functions=100 --statements=100 node node_modules/jest/bin/jest.js tests/integration/copy-assets.integration.test.js --runInBand --coverage=false",
+    "verify:room:coverage": "node node_modules/jest/bin/jest.js tests/unit/room-verifier.unit.test.js tests/integration/documentation.integration.test.js --testNamePattern=\"room cleanup|shared page/room\" --runInBand --coverage --collectCoverageFrom=scripts/lib/verify-room-example.js --coverageDirectory=coverage/room-verifier",
+    "verify:action:coverage": "node node_modules/jest/bin/jest.js tests/unit/action-verifier.unit.test.js tests/integration/action-verifier.integration.test.js tests/integration/action-input.integration.test.js --runInBand --silent --coverage --collectCoverageFrom=scripts/lib/verify-action-input.js --coverageDirectory=coverage/action-verifier",
+    "verify:reports:coverage": "node node_modules/jest/bin/jest.js tests/unit/report-command.unit.test.js tests/integration/command-report.integration.test.js --runInBand --silent --coverage --collectCoverageFrom=scripts/lib/reportCommand.js --coverageDirectory=coverage/command-report",
+    "verify:build:coverage": "node node_modules/jest/bin/jest.js tests/integration/protocol-generator.integration.test.js tests/integration/example-builder.integration.test.js tests/integration/documentation.integration.test.js tests/integration/script-coverage.integration.test.js --testNamePattern=\"protocol generator|example builder|release snapshots|unit fault: script verifier|real command evidence\" --runInBand --coverage=false",
+    "verify:recorder:coverage": "node node_modules/jest/bin/jest.js tests/unit/application-recorder.unit.test.js tests/integration/script-coverage.integration.test.js --testNamePattern=\"native coverage recorder|real command evidence associates\" --runInBand --coverage --collectCoverageFrom=scripts/lib/record-application-coverage.cjs --coverageDirectory=coverage/application-recorder-authored",
+    "verify:recovery:diagnostics": "c8 --all --include=scripts/diagnostics/recovery-heap-graph.cjs --include=scripts/diagnostics/recovery-heap-summary.cjs --reporter=text --reporter=json --reports-dir=coverage/recovery-native-exact --check-coverage --lines=100 --branches=100 --functions=100 --statements=100 node --test tests/unit/recovery-heap-graph.unit.test.js",
     "verify:live-html": "node scripts/build-live-html-examples.js --check && npx jest tests/integration/live-html.integration.test.js --runInBand --coverage=false",
     "verify:live-html:browser": "node scripts/build-live-html-examples.js --check && node scripts/verify-live-html-browser.js",
+    "verify:browser:supplements": "node node_modules/jest/bin/jest.js tests/unit/browser-supplements.unit.test.js tests/integration/browser-supplements.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/verify-live-page-ownership.js --collectCoverageFrom=scripts/lib/verify-runtime-browser.js --coverageDirectory=coverage/browser-supplements-authored",
+    "verify:dashboard:coverage": "node node_modules/jest/bin/jest.js tests/unit/dashboard-verifier.unit.test.js tests/integration/dashboard-verifier.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/verify-dashboard-browser.js --coverageDirectory=coverage/dashboard-verifier",
+    "verify:refresh:coverage": "node node_modules/jest/bin/jest.js tests/unit/refresh-controls-failures.unit.test.js tests/unit/refresh-observation.unit.test.js tests/unit/heading-readiness.unit.test.js tests/integration/refresh-observation.integration.test.js tests/integration/refresh-coverage.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/verify-refresh-controls.js --collectCoverageFrom=scripts/lib/verify-refresh-coverage.js --coverageDirectory=coverage/refresh-verifier",
+    "verify:browser:coverage": "node node_modules/jest/bin/jest.js tests/unit/browser-coverage.unit.test.js tests/unit/application-coverage.unit.test.js tests/unit/packed-browser-harness.unit.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/BrowserCoverage.js --collectCoverageFrom=scripts/lib/ApplicationCoverage.js --collectCoverageFrom=scripts/lib/assertCoverageFile.js --coverageDirectory=coverage/browser-collector && npm run verify:browser:coordinator:coverage",
+    "verify:browser:coordinator:coverage": "node node_modules/jest/bin/jest.js tests/unit/browser-coordinator-report.unit.test.js tests/unit/browser-coordinator-lifecycle.unit.test.js tests/unit/browser-coverage-cleanup.unit.test.js tests/unit/browser-supplements.unit.test.js tests/unit/refresh-controls-failures.unit.test.js tests/unit/refresh-observation.unit.test.js tests/unit/heading-readiness.unit.test.js tests/integration/browser-coordinator.integration.test.js tests/integration/browser-supplements.integration.test.js tests/integration/refresh-observation.integration.test.js tests/integration/refresh-coverage.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/verify-browser-coverage.js --collectCoverageFrom=scripts/lib/verify-live-page-ownership.js --collectCoverageFrom=scripts/lib/verify-runtime-browser.js --collectCoverageFrom=scripts/lib/verify-refresh-controls.js --collectCoverageFrom=scripts/lib/verify-refresh-coverage.js --coverageDirectory=coverage/browser-coordinator",
+    "verify:feedback:commands": "node node_modules/jest/bin/jest.js tests/unit/browser-commands.unit.test.js tests/integration/feedback-browser.integration.test.js tests/integration/feedback-command-timeout.integration.test.js tests/integration/feedback-verifier.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/browserCommands.js --collectCoverageFrom=scripts/lib/verify-action-feedback.js --coverageDirectory=coverage/browser-commands",
+    "measure:browser:client": "node scripts/verify-browser-coverage.js client",
+    "verify:client:coordinator:coverage": "node node_modules/jest/bin/jest.js tests/unit/client-source-coordinator.unit.test.js tests/integration/client-source-preflight.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/verify-client-source-coverage.js --coverageDirectory=coverage/client-source-coordinator",
+    "verify:client:source-coverage": "node node_modules/jest/bin/jest.js tests/unit/client-source-coverage.unit.test.js tests/integration/client-source-preflight.integration.test.js tests/integration/command-report.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/ClientSourceCoverage.js --collectCoverageFrom=scripts/lib/reportCommand.js --coverageDirectory=coverage/client-source-collector && node --test tests/integration/client-worker-retention.integration.test.cjs && node scripts/verify-client-source-coverage.js",
+    "verify:development:browser": "node scripts/verify-development-refresh-browser.js",
+    "verify:development:coverage": "node node_modules/jest/bin/jest.js tests/unit/development-refresh-cleanup.unit.test.js tests/unit/development-refresh-boundaries.unit.test.js tests/integration/development-refresh-verifier.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/verify-development-refresh-browser.js --coverageDirectory=coverage/development-coordinator",
+    "verify:starters:lifecycle": "node scripts/verify-starter-lifecycle.js",
+    "verify:starters:lifecycle:coverage": "node node_modules/jest/bin/jest.js tests/unit/starter-lifecycle-command.unit.test.js tests/integration/starter-lifecycle-coverage.integration.test.js --runInBand --silent --coverage --collectCoverageFrom=scripts/verify-starter-lifecycle.js --coverageDirectory=coverage/starter-lifecycle-coordinator",
+    "measure:starters:coverage": "node scripts/measure-starter-coverage.js",
+    "verify:starter-coordinators:coverage": "node node_modules/jest/bin/jest.js tests/unit/starter-coordinators.unit.test.js tests/integration/verification-summary.integration.test.js tests/integration/starter-coordinator-input.integration.test.js --runInBand --silent --coverage --collectCoverageFrom=scripts/measure-starter-coverage.js --collectCoverageFrom=scripts/verify-starter-source-coverage.js --collectCoverageFrom=scripts/lib/finishVerificationSummary.js --coverageDirectory=coverage/starter-coordinators",
+    "verify:starters:source-coverage": "node node_modules/jest/bin/jest.js tests/unit/application-coverage.unit.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/ApplicationCoverage.js --collectCoverageFrom=scripts/lib/assertCoverageFile.js --coverageDirectory=coverage/application-collector && node scripts/verify-starter-source-coverage.js",
+    "verify:package:tools": "node node_modules/jest/bin/jest.js tests/unit/verification-workspace.unit.test.js tests/unit/client-candidate.unit.test.js tests/unit/packed-browser-harness.unit.test.js tests/unit/packed-browser-report.unit.test.js tests/integration/starter-verifier.integration.test.js tests/integration/starters.integration.test.js tests/integration/documentation.integration.test.js tests/integration/action-input.integration.test.js tests/integration/consumer-compiler.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/VerificationWorkspace.js --collectCoverageFrom=scripts/lib/ClientCandidate.js --collectCoverageFrom=scripts/lib/InstalledClient.js --collectCoverageFrom=scripts/lib/PackedBrowserHarness.js --collectCoverageFrom=scripts/lib/preservePackedBrowserReport.js --collectCoverageFrom=scripts/lib/verificationError.js --collectCoverageFrom=scripts/lib/verify-starter.js --collectCoverageFrom=scripts/lib/verify-documentation.js --collectCoverageFrom=scripts/lib/compile-consumer.js --coverageDirectory=coverage/package-tools",
     "verify:live-html:load": "node scripts/build-live-html-examples.js --check && node --expose-gc scripts/verify-live-html-load.js",
+    "verify:live-html:load:coverage": "node node_modules/jest/bin/jest.js tests/unit/live-html-load-command.unit.test.js tests/unit/live-html-load-tools.unit.test.js tests/integration/live-html-load-tools.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/verify-live-html-load.js --collectCoverageFrom=scripts/lib/readLiveHtmlPage.js --collectCoverageFrom=scripts/lib/LiveHtmlLoadClient.js --coverageDirectory=coverage/live-html-load-tools",
     "verify:jsx:performance": "node --expose-gc scripts/verify-jsx-performance.js",
+    "verify:jsx:coverage": "node node_modules/jest/bin/jest.js tests/unit/jsx-performance-command.unit.test.js tests/integration/jsx-performance.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/verify-jsx-performance.js --coverageDirectory=coverage/jsx-performance-tools",
     "verify:live-html:package": "node scripts/verify-live-html-package.js",
+    "verify:package:coordinator:coverage": "node node_modules/jest/bin/jest.js tests/unit/package-coordinator.unit.test.js tests/unit/packed-browser-report.unit.test.js tests/unit/packed-browser-report-failures.unit.test.js tests/integration/package-coordinator.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/verify-live-html-package.js --collectCoverageFrom=scripts/lib/preservePackedBrowserReport.js --coverageDirectory=coverage/package-coordinator",
+    "verify:package:examples:coverage": "node node_modules/jest/bin/jest.js tests/unit/packed-action.unit.test.js tests/unit/example-dependencies.unit.test.js tests/unit/example-probe.unit.test.js tests/integration/packed-action.integration.test.js tests/integration/example-dependencies.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/performProbeAction.js --collectCoverageFrom=scripts/lib/verify-example-dependencies.js --collectCoverageFrom=scripts/lib/example-dependency-probe.cjs --coverageDirectory=coverage/example-dependency-tools",
+    "verify:package:browser:coverage": "node node_modules/jest/bin/jest.js tests/unit/browser-pages.unit.test.js tests/unit/packed-browser-verifier.unit.test.js tests/unit/browser-coverage-cleanup.unit.test.js tests/integration/packed-browser-verifier.integration.test.js --runInBand --silent --coverage --collectCoverageFrom=scripts/lib/verify-packed-browser.js --collectCoverageFrom=scripts/lib/BrowserPages.js --coverageDirectory=coverage/packed-browser-verifier",
+    "verify:client:link": "node --test tests/integration/npm-link.integration.test.cjs",
     "test": "npx jest"
   },
   "files": [
@@ -62,6 +114,8 @@
     "src/*",
     "client.js",
     "client.d.ts",
+    "contract.js",
+    "contract.d.ts",
     "jsx-runtime.js",
     "jsx-runtime.d.ts",
     "jsx-dev-runtime.js",
@@ -69,9 +123,28 @@
     "CHANGELOG.md",
     "index.d.ts",
     "docs",
+    "recipes",
     "examples/live-html"
   ],
-  "keywords": [],
+  "homepage": "https://redweb.magnisolution.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lakam99/redweb.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lakam99/redweb/issues"
+  },
+  "keywords": [
+    "typescript",
+    "jsx",
+    "server-rendering",
+    "websocket",
+    "realtime",
+    "multiplayer",
+    "express",
+    "ssr",
+    "static-site"
+  ],
   "author": "",
   "license": "ISC",
   "engines": {
@@ -84,13 +157,21 @@
     "@types/ws": "^8.18.1",
     "cors": "^2.8.5",
     "express": "^4.22.2",
-    "redweb-client": "^0.1.0",
+    "redweb-client": "^0.2.0",
     "ws": "^8.21.3"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",
+    "c8": "^10.1.3",
+    "expect": "29.7.0",
     "jest": "^29.7.0",
+    "istanbul-lib-coverage": "3.2.2",
+    "istanbul-lib-instrument": "6.0.2",
+    "nodemon": "^3.1.11",
+    "redweb-dashboard-types": "npm:@types/node@^22.20.1",
+    "redweb-legacy-compiler-fixture": "file:tests/fixtures/legacy-compiler",
     "supertest": "^7.0.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "zod": "^4.4.3"
   }
 }

package/recipes/add/artifact.test.cjs

@@ -0,0 +1,57 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { once } = require('node:events');
+const { pathToFileURL } = require('node:url');
+const path = require('node:path');
+const WebSocket = require('ws');
+const { start, page, SocketServer } = require('redweb');
+const { jsx } = require('redweb/jsx-runtime');
+
+test('__NAME__ generated __KIND__ works over the network', { timeout: 10000 }, async t => {
+    // Import only this artifact, never the application's entry point.
+    const artifact = await import(pathToFileURL(path.resolve(__dirname, __IMPORT__)).href);
+    let Page = artifact.__CLASS__;
+    if ('__KIND__' === 'component') {
+        Page = page('/') (class TestPage {
+            subject = new artifact.__CLASS__();
+            render() { return jsx('main', { children: this.subject }); }
+        });
+    }
+    const app = '__KIND__' === 'socket-route'
+        ? new SocketServer({ port: 0, bind: '127.0.0.1', logger: null, routes: [artifact.__CLASS__] })
+        : start(Page, { port: 0, bind: '127.0.0.1', logger: null });
+    let socket;
+    t.after(async () => {
+        socket?.terminate();
+        await app.shutdown();
+    });
+    if (!app.server.listening) await once(app.server, 'listening');
+    const origin = `http://127.0.0.1:${app.server.address().port}`;
+    let config;
+    if ('__KIND__' !== 'socket-route') {
+        const response = await fetch(`${origin}${'__KIND__' === 'page' ? '/__NAME__' : '/'}`);
+        assert.equal(response.status, 200);
+        const document = await response.text();
+        assert.match(document, /<output>0<\/output>/);
+        config = JSON.parse(document.match(/id="__redweb_page">([^<]+)</)[1]);
+    }
+    const endpoint = config
+        ? `${config.socketPath}?pageId=${config.pageId}&redwebVersion=${encodeURIComponent(config.version)}`
+        : `/__NAME__?redwebVersion=${artifact.contract.version}`;
+    socket = new WebSocket(`${origin.replace('http:', 'ws:')}${endpoint}`, { origin, handshakeTimeout: 3000 });
+    const received = [];
+    socket.on('message', raw => received.push(JSON.parse(raw.toString())));
+    await once(socket, 'open');
+    if (config) {
+        socket.send(JSON.stringify({ v: config.version, type: 'redweb:html', payload: {
+            kind: 'action', name: 'increment', args: [],
+            ...('__KIND__' === 'component' ? { component: 'subject' } : {}),
+        } }));
+    } else await artifact.contract.client(socket).send('ping', { text: 'Hello' }, { requestId: 'probe' });
+    const success = message => config
+        ? message.type === 'redweb:patch' && message.payload.patches.some(patch => patch.html?.includes('<output>1</output>'))
+        : message.type === 'pong' && message.payload.text === 'Hello' && message.requestId === 'probe';
+    const deadline = Date.now() + 3000;
+    while (!received.some(success) && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 10));
+    assert.ok(received.some(success), `Expected action result; received ${JSON.stringify(received)}`);
+});

package/recipes/add/live.tsx

@@ -0,0 +1,18 @@
+import { action, __DECORATOR__, state } from 'redweb';
+
+__DECORATION__
+export class __CLASS__ {
+    @state() count = 0;
+
+    @action()
+    increment() { this.count += 1; }
+
+    render() {
+        return (
+            <section>
+                <h1>__TITLE__</h1>
+                <button rw-click="increment">Count <output>{this.count}</output></button>
+            </section>
+        );
+    }
+}

package/recipes/add/socket-route.ts

@@ -0,0 +1,24 @@
+import { SocketRoute } from 'redweb';
+import { defineSocketContract } from 'redweb/contract';
+import { z } from 'zod';
+
+// This example is stateless. Add application-owned identity and persistence as needed.
+export const contract = defineSocketContract('1', {
+    ping: z.object({ text: z.string().max(500) }).strict(),
+    pong: z.object({ text: z.string().max(500) }).strict(),
+});
+
+export const Ping = contract.handler('ping', (socket, payload, message) =>
+    contract.send(socket, 'pong', payload, { requestId: message.requestId }));
+
+export class __CLASS__ extends SocketRoute {
+    constructor() {
+        super({
+            path: '/__NAME__', handlers: [Ping], protocol: contract.protocol,
+            orderedMessages: true,
+            allowDuplicateConnections: true,
+            websocketOptions: { maxPayload: 4096 },
+            limits: { maxConnections: 100, maxPendingMessages: 32, maxBufferedBytes: 65536 },
+        });
+    }
+}

package/recipes/chat/README.md

@@ -0,0 +1,22 @@
+## Chat starter
+
+`src/chatroom.tsx` is the canonical Redweb chat component example, included directly rather than a second implementation.
+The component stores ordinary message/member data and renders it with reactive TSX and stable list keys; no HTML-valued state or explicit binding names are needed.
+Visitors choose a name once, chat in a shared room, and see live presence. Disconnect removes online presence;
+the page session retains its identity briefly for reconnect, then disposal releases it.
+
+Display names are not authenticated identities. History is bounded to 100 messages in memory, not a persistent database.
+Use an application-owned persistence service before promising history across restarts or multiple server processes.
+
+`@action({ input: chatInputs.join })` validates and normalizes the form before `join` runs;
+`ActionInput<typeof chatInputs.join>` supplies its TypeScript input type. The same pattern handles messages.
+The starter installs Zod as an application dependency; Redweb itself remains validator-independent.
+Invalid field values (including repeated names represented as arrays) receive `ACTION_INVALID_INPUT`, keep the draft,
+and show Redweb's built-in form feedback. Name collisions remain a room rule with their own friendly message.
+Calling a component method directly from server code bypasses transport validation: pass schema-parsed input.
+The schemas reject ordinary unexpected fields; Zod may discard reserved object keys such as `__proto__`.
+Only the parsed `name` or `message` reaches the corresponding action.
+
+When using the packed `examples/live-html/chatroom.js` directly instead of the generated starter,
+install its application validator with `npm install zod`. A cloned-repository development install already
+includes it. Redweb's core and the counter example do not require Zod.

package/recipes/chat/app.test.cjs

@@ -0,0 +1,105 @@
+const test = require('node:test');
+const { once } = require('node:events');
+const assert = require('node:assert/strict');
+const { listen, live, connect } = require('./network.cjs');
+const { createChatroomPage, chatInputs } = require('../dist/chatroom.js');
+
+test('the standalone canonical chat reports an occupied default port', { timeout: 10000 }, async t => {
+    const net = require('node:net');
+    const { spawnSync } = require('node:child_process');
+    const occupied = net.createServer(socket => socket.destroy());
+    t.after(() => new Promise(resolve => occupied.close(resolve)));
+    occupied.listen(8080, '0.0.0.0');
+    try { await once(occupied, 'listening'); }
+    catch (error) { assert.equal(error.code, 'EADDRINUSE'); } // An existing listener is left untouched.
+    const result = spawnSync(process.execPath, ['dist/chatroom.js'], {
+        encoding: 'utf8', timeout: 5000, windowsHide: true,
+    });
+    assert.equal(result.error, undefined);
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /EADDRINUSE/);
+});
+
+test('members join once, exchange messages, and leave presence on disconnect', { timeout: 10000 }, async t => {
+    const origin = await listen(t);
+    const alice = await live(t, origin);
+    const bob = await live(t, origin);
+    alice.action('join', [{ name: 'Alice' }], 'chat');
+    bob.action('join', [{ name: 'Bob' }], 'chat');
+    await alice.patch(patch => patch.html.includes('Online · 2'));
+    await bob.patch(patch => patch.html.includes('Online · 2'));
+    alice.action('send', [{ message: 'Hello <friends>' }], 'chat');
+    await bob.patch(patch => patch.html.includes('Hello &lt;friends&gt;'));
+    const closed = once(alice.socket, 'close');
+    alice.socket.close();
+    await closed;
+    await bob.patch(patch => patch.html.includes('Online · 1'));
+});
+
+test('identities stay reserved across reconnects and are released by leaving', { timeout: 10000 }, async t => {
+    const origin = await listen(t);
+    const alice = await live(t, origin);
+    const visitor = await live(t, origin);
+    alice.action('join', [{ name: ' Ａlice ' }], 'chat');
+    await alice.patch(patch => patch.html.includes('Connected as') && patch.html.includes('Alice'));
+    visitor.action('join', [{ name: 'ALICE' }], 'chat');
+    await visitor.patch(patch => patch.html.includes('already in use'));
+    const closed = once(alice.socket, 'close');
+    alice.socket.close();
+    await closed;
+    visitor.send({ v: visitor.config.version, type: 'redweb:html', requestId: 'reserved-name', payload: { kind: 'action', name: 'join', args: [{ name: 'ALICE' }], component: 'chat' } });
+    assert.equal((await visitor.receive(message => message.requestId === 'reserved-name')).payload, false);
+    const { config } = alice;
+    const resumed = await connect(t, `${origin.replace('http:', 'ws:')}${config.socketPath}?pageId=${config.pageId}&redwebVersion=${encodeURIComponent(config.version)}`, origin);
+    await resumed.receive(message => message.type === 'redweb:patch' && message.payload.patches.some(patch => patch.html.includes('Online · 1')));
+    resumed.send({ v: config.version, type: 'redweb:html', payload: { kind: 'action', name: 'leave', args: [], component: 'chat' } });
+    await resumed.receive(message => message.type === 'redweb:patch' && message.payload.patches.some(patch => patch.html.includes('Join the chatroom')));
+    visitor.action('join', [{ name: 'Alice' }], 'chat');
+    await visitor.patch(patch => patch.html.includes('Connected as') && patch.html.includes('Online · 1'));
+});
+
+test('room units bound history/presence, isolate rooms, and make repeated lifecycle calls harmless', () => {
+    const Page = createChatroomPage();
+    const alice = new Page().chat;
+    const bob = new Page().chat;
+    const isolated = new (createChatroomPage())().chat;
+    assert.equal(alice.send({ message: 'not joined' }), false);
+    alice.connected();
+    assert.equal(alice.join(chatInputs.join.parse({ name: ' Ａlice ' })), true);
+    assert.equal(alice.join({ name: 'Replacement' }), false);
+    assert.equal(bob.join({ name: 'ALICE' }), false);
+    assert.match(bob.render().toString(), /already in use/);
+    assert.equal(bob.join({ name: 'Bob' }), true);
+    assert.equal(isolated.join({ name: 'Alice' }), true);
+    assert.match(alice.render().toString(), /No messages yet/);
+    for (let index = 0; index < 101; index++) assert.equal(alice.send({ message: `message-${index}` }), true);
+    assert.equal(bob.messages.length, 100);
+    assert.deepEqual(bob.messages[0], { id: 2, sender: 'Alice', text: 'message-1' });
+    assert.equal(bob.messages.at(-1).id, 101);
+    assert.equal(isolated.messages.length, 0);
+    assert.match(bob.render().toString(), /message-100/);
+    alice.disconnected();
+    alice.disconnected();
+    assert.deepEqual(bob.members, ['Bob']);
+    assert.equal(alice.send({ message: 'offline' }), false);
+    alice.connected();
+    assert.deepEqual(bob.members, ['Bob', 'Alice']);
+    const visitors = Array.from({ length: 100 }, (_, index) => {
+        const member = new Page().chat;
+        assert.equal(member.join({ name: `visitor-${index}` }), true);
+        return member;
+    });
+    const rendered = alice.render().toString();
+    assert.match(rendered, /Online · 102/);
+    assert.match(rendered, /\+2 more/);
+    assert.doesNotMatch(rendered, /<li[^>]*>visitor-99<\/li>/);
+    visitors.forEach(member => member.disposed());
+    alice.leave();
+    alice.disposed();
+    alice.disposed();
+    assert.deepEqual([alice.displayName, alice.feedback, alice.messages, alice.members], ['', '', [], []]);
+    assert.deepEqual(bob.members, ['Bob']);
+    assert.match(alice.render().toString(), /Join the chatroom/);
+    bob.disposed();
+    isolated.disposed();
+});

package/recipes/chat/app.tsx

@@ -0,0 +1,9 @@
+import { start, type LiveHtmlStartOptions } from 'redweb';
+import { createChatroomPage } from './chatroom';
+import { runApp } from './run-app';
+
+export function createApp(options: LiveHtmlStartOptions = {}) {
+    return start(createChatroomPage(), { port: Number(process.env.PORT ?? 8181), templateRoot: __dirname, ...options });
+}
+
+if (require.main === module) runApp(createApp);

package/recipes/dashboard/README.md

@@ -0,0 +1,43 @@
+# Persistent private dashboard
+
+This recipe combines decorator-first pages, reusable live cards, validated actions, and real SQLite persistence. It is an application example, not an authentication framework or managed database.
+
+## Run it
+
+Requires **Node 22.13 or newer** (native `node:sqlite`, experimental in Node 22) and npm. Other Redweb starters retain their own Node requirements. Use a supported Node release in production.
+
+After installing dependencies, create your account:
+
+```sh
+npm run add-user -- alice
+npm test
+npm run dev
+```
+
+The provisioning command displays a randomly generated password once. Save it securely; there are no default accounts or passwords. Open **http://127.0.0.1:8181/login**, sign in, and add a card. A second signed-in tab updates immediately. Restart the app: your cards and unexpired credentials remain valid. Sign out all sessions to close every connected tab for that account and invalidate all its cookies.
+
+`npm test` provisions temporary test accounts and a real temporary database, then exercises HTTP, WebSockets, isolation, restart, and session expiry. It never modifies your application database. Integration tests use no mocks. A separately labelled unit test injects a cleanup error after closing a real SQLite database to verify rejection handling; it does not simulate a real operating-system failure.
+
+`npm run test:coverage` measures the TypeScript application through source maps, separately from Redweb's own instrumented-library coverage. It also waits through the actual one-minute login admission window without mocking the clock. The report includes TypeScript-generated decorator accessor functions; inspect that distinction rather than assuming a library coverage figure applies to this recipe. The generated npm configuration enforces this recipe's Node engine requirement before installation.
+
+## Where the behavior lives
+
+- `app.tsx`: composition, login page, protected dashboard, listener and shutdown.
+- `cards.tsx`: reusable `Cards` component and account-scoped live subscriptions. Normal TSX expressions update automatically. Forms call typed actions; feedback requires no browser glue.
+- `store.ts`: prepared SQL, bounded cards/sessions, owner-filtered operations and synchronous transactions.
+- `auth.ts`: asynchronous scrypt, bounded login attempts, hashed session tokens, cookies and sign-out.
+- `admin.ts`: explicit local account provisioning.
+
+## Production boundaries
+
+Set `DASHBOARD_DATABASE` to a writable persistent file path (default `data/dashboard.sqlite`). Protect the directory with OS permissions: the database contains password hashes, private card text, and session metadata. It, its WAL/SHM files, and backups must never be served as public assets or committed. Stop the process cleanly before copying the database for a backup, or use a proper SQLite online backup facility; copying only the main file during live WAL writes is not a backup plan.
+
+Set `NODE_ENV=production` and `DASHBOARD_ORIGIN=https://your-domain.example` behind an HTTPS reverse proxy. The origin must have no path or trailing slash. This enables Secure cookies; all session cookies are HttpOnly and SameSite=Strict. Both login/logout forms and socket upgrades require the exact trusted origin. The application does not trust Host or forwarded headers to establish origin or identity. The HTTP listener must not be publicly reachable around your TLS proxy.
+
+Provision accounts on the same persistent volume before serving requests. Passwords use salted scrypt; only hashes of random session tokens are stored. Default sessions last one hour. Up to 32 unexpired sessions and 100 cards per account are supported. Login work is limited to four simultaneous checks and ten attempts per minute per direct peer IP, with at most 1,024 tracked IPs; clients behind one proxy share its bucket. Add appropriate proxy-level abuse controls for an Internet deployment. There is no registration, password reset, MFA, or account recovery; integrate a dedicated identity provider if your product needs those features.
+
+SQL checks the current session and card owner inside each write transaction. Private subscriptions recheck session validity before publishing and close at expiry. Sign-out invalidates credentials before revoking Redweb sessions. An expired or disconnected page may need a reload/sign-in; the recipe does not silently retry actions with uncertain outcomes.
+
+This is a **single-process live-update model**. SQLite transactions are synchronous and kept small; this is not a claim of unlimited concurrency. Do not put multiple app workers behind a load balancer and expect cross-worker notifications or revocation. Add a deliberate shared notification/session-revocation design before scaling horizontally. Static export cannot include protected dashboards.
+
+Build and deploy using the shared instructions above, including the persistent data volume and the environment settings here. Neither `npm run dev` nor a process restart should erase durable cards. Redweb itself does not depend on SQLite.

package/recipes/dashboard/admin.ts

@@ -0,0 +1,21 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { credentials } from './auth';
+import { databasePath } from './app';
+import { DashboardStore, USERNAME } from './store';
+
+async function main() {
+    const account = process.argv[2];
+    if (!account || !USERNAME.test(account) || process.argv.length !== 3) throw new Error('Usage: npm run add-user -- alice (3–32 lowercase letters, digits, _ or -; starts with a letter).');
+    const filename = databasePath();
+    mkdirSync(dirname(filename), { recursive: true });
+    const store = new DashboardStore(filename);
+    try {
+        const password = randomBytes(24).toString('base64url');
+        store.provision(account, await credentials(password));
+        console.log(`Created ${account}. Store this password safely; it is displayed only once:\n${password}`);
+    } finally { store.close(); }
+}
+
+void main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/recipes/dashboard/app.css

@@ -0,0 +1,16 @@
+:root { font-family: system-ui, sans-serif; color: #e8edf5; background: #111827; color-scheme: dark; }
+* { box-sizing: border-box; }
+body { margin: 0; }
+.home { width: min(64rem, 100%); margin: 3rem auto; padding: 0 1.5rem; }
+header { display: flex; align-items: center; justify-content: space-between; gap: 1rem; flex-wrap: wrap; }
+form { display: flex; align-items: center; flex-wrap: wrap; gap: .75rem; }
+input, button { font: inherit; border: 1px solid #526179; border-radius: .5rem; padding: .75rem; }
+input { background: #1f2937; max-width: 100%; }
+button { background: #a7f3d0; color: #102c23; cursor: pointer; }
+button:disabled { opacity: .5; cursor: default; }
+:focus-visible { outline: 3px solid #60a5fa; outline-offset: 3px; }
+.cards { margin-top: 2rem; }
+.card-grid { padding: 0; list-style: none; display: grid; grid-template-columns: repeat(auto-fit, minmax(min(15rem, 100%), 1fr)); gap: 1rem; }
+.card-grid li { border: 1px solid #526179; border-radius: .75rem; padding: 1.25rem; overflow-wrap: anywhere; }
+h2 { font-size: 1.25rem; }
+[role="alert"] { color: #fca5a5; }