redweb 0.12.0 → 0.13.0

package/recipes/dashboard/cards.tsx

@@ -0,0 +1,102 @@
+import { action, component, state, type ActionInput, type LivePageConnectionContext, type LivePageRequestContext } from 'redweb';
+import { z } from 'zod';
+import { sessionToken } from './auth';
+import { DashboardStore, MAX_CARDS, type Card } from './store';
+
+const addInput = z.object({ title: z.string().trim().min(1).max(80).regex(/^[^\p{Cc}\p{Cf}]+$/u) }).strict();
+const removeInput = z.object({ id: z.string().uuid() }).strict();
+const tokenOf = (context: LivePageRequestContext) => sessionToken(context.request.get('cookie'));
+
+interface Subscriber { token: string; update(): void; close(): void; }
+
+/** Single-process notifications; SQLite remains the source of truth on every connection. */
+export class PrivateCards {
+    private readonly accounts = new Map<string, Set<Subscriber>>();
+    constructor(readonly store: DashboardStore) {}
+
+    allowed(context: LivePageRequestContext) {
+        const session = this.store.session(tokenOf(context));
+        return !!session && session.account === context.principal && !context.signal.aborted;
+    }
+
+    subscribe(context: LivePageConnectionContext, update: (cards: Card[]) => void): () => void {
+        const token = tokenOf(context);
+        const session = this.store.session(token);
+        if (!session || !this.allowed(context)) throw new Error('Sign in again.');
+        let group = this.accounts.get(session.account);
+        if (!group) this.accounts.set(session.account, group = new Set());
+        let closed = false;
+        const subscriber: Subscriber = {
+            token, update: () => update(this.store.list(token)),
+            close: () => { unsubscribe(); context.socket.close(1008, 'Sign in again.'); },
+        };
+        const unsubscribe = () => {
+            if (closed) return;
+            closed = true;
+            clearTimeout(expiry);
+            context.signal.removeEventListener('abort', unsubscribe);
+            group.delete(subscriber);
+            if (!group.size && this.accounts.get(session.account) === group) this.accounts.delete(session.account);
+        };
+        const expiry = setTimeout(subscriber.close, Math.max(1, session.expires - Date.now()));
+        expiry.unref();
+        group.add(subscriber);
+        context.signal.addEventListener('abort', unsubscribe, { once: true });
+        try { subscriber.update(); }
+        catch (error) { unsubscribe(); throw error; }
+        return unsubscribe;
+    }
+
+    publish(account: string) {
+        for (const subscriber of this.accounts.get(account) ?? []) {
+            try {
+                if (this.store.session(subscriber.token)?.account === account) subscriber.update();
+                else subscriber.close();
+            } catch { subscriber.close(); }
+        }
+    }
+}
+
+@component()
+export class Cards {
+    @state() items: Card[] = [];
+    private unsubscribe?: () => void;
+
+    constructor(private readonly cards: PrivateCards) {}
+    loading(context: LivePageRequestContext) { this.items = this.cards.store.list(tokenOf(context)); }
+    connected(context: LivePageConnectionContext) {
+        this.disconnected();
+        this.unsubscribe = this.cards.subscribe(context, items => { this.items = items; });
+    }
+    disconnected() { this.unsubscribe?.(); this.unsubscribe = undefined; }
+    disposed() { this.disconnected(); }
+
+    @action({ input: addInput })
+    add({ title }: ActionInput<typeof addInput>, context: LivePageConnectionContext) {
+        this.cards.publish(this.cards.store.add(tokenOf(context), title));
+    }
+
+    @action({ input: removeInput })
+    remove({ id }: ActionInput<typeof removeInput>, context: LivePageConnectionContext) {
+        this.cards.publish(this.cards.store.remove(tokenOf(context), id));
+    }
+
+    render() {
+        return <section class="cards" aria-label="Your saved cards">
+            <form rw-submit="add">
+                <label for="card-title">New card</label>
+                <input id="card-title" name="title" maxlength="80" required autocomplete="off" />
+                <button type="submit" disabled={this.items.length >= MAX_CARDS}>Add card</button>
+            </form>
+            <p>{this.items.length} / {MAX_CARDS} cards · saved automatically</p>
+            <ul class="card-grid">{this.items.map(card => <li key={card.id} data-card-id={card.id}>
+                <h2>{card.title}</h2>
+                <form rw-submit="remove">
+                    <input type="hidden" name="id" value={card.id} />
+                    <button type="submit" aria-label={`Delete ${card.title}`}>Delete</button>
+                </form>
+            </li>)}</ul>
+            {!this.items.length && <p>No cards yet. Add your first one above.</p>}
+        </section>;
+    }
+}

package/recipes/dashboard/rate-window.test.cjs

@@ -0,0 +1,17 @@
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { DashboardStore } = require('../dist/store');
+const { DashboardAuth, credentials } = require('../dist/auth');
+
+test('login admission reopens after the real one-minute window, without clock mocks', { timeout: 65000 }, async t => {
+    const store = new DashboardStore(':memory:');
+    const auth = new DashboardAuth(store);
+    t.after(() => { auth.close(); store.close(); });
+    const password = 'test-only-login-window-password';
+    store.provision('alice', await credentials(password));
+    for (let attempt = 0; attempt < 10; attempt++) assert.equal(await auth.login('same-peer', 'invalid', password), undefined);
+    assert.equal(await auth.login('same-peer', 'alice', password), undefined);
+    await new Promise(resolve => setTimeout(resolve, 60010));
+    const token = await auth.login('same-peer', 'alice', password);
+    assert.equal(store.session(token).account, 'alice');
+});

package/recipes/dashboard/store.ts

@@ -0,0 +1,120 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+
+export interface Card { id: string; title: string; }
+export interface Session { account: string; expires: number; }
+export interface Credentials { salt: string; hash: string; }
+export const MAX_CARDS = 100;
+export const USERNAME = /^[a-z][a-z0-9_-]{2,31}$/;
+const digest = (token: string) => createHash('sha256').update(token).digest('hex');
+
+/** Recipe-local persistence. Every private query derives its owner from a live session. */
+export class DashboardStore {
+    private readonly db: DatabaseSync;
+    private closed = false;
+
+    constructor(filename: string) {
+        this.db = new DatabaseSync(filename);
+        try {
+            this.db.exec('PRAGMA foreign_keys = ON; PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL; PRAGMA busy_timeout = 1000;');
+            const version = this.db.prepare('PRAGMA user_version').get()!.user_version;
+            if (version !== 0 && version !== 1) throw new Error('Unsupported dashboard database version.');
+            this.db.exec(`
+                BEGIN IMMEDIATE;
+                CREATE TABLE IF NOT EXISTS accounts (
+                    id TEXT PRIMARY KEY, salt TEXT NOT NULL, hash TEXT NOT NULL, epoch INTEGER NOT NULL DEFAULT 0
+                ) STRICT;
+                CREATE TABLE IF NOT EXISTS sessions (
+                    token TEXT PRIMARY KEY, account TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
+                    expires INTEGER NOT NULL
+                ) STRICT;
+                CREATE INDEX IF NOT EXISTS sessions_owner ON sessions(account);
+                CREATE INDEX IF NOT EXISTS sessions_expiry ON sessions(expires);
+                CREATE TABLE IF NOT EXISTS cards (
+                    id TEXT PRIMARY KEY, account TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
+                    title TEXT NOT NULL CHECK(length(title) BETWEEN 1 AND 80)
+                ) STRICT;
+                CREATE INDEX IF NOT EXISTS cards_owner ON cards(account);
+                PRAGMA user_version = 1;
+                COMMIT;
+            `);
+        } catch (error) { this.db.close(); throw error; }
+    }
+
+    provision(account: string, credentials: Credentials) {
+        if (!USERNAME.test(account) || !/^[a-f0-9]{32}$/.test(credentials.salt) || !/^[a-f0-9]{128}$/.test(credentials.hash)) {
+            throw new TypeError('Invalid account credentials.');
+        }
+        this.db.prepare('INSERT INTO accounts(id, salt, hash) VALUES (?, ?, ?)').run(account, credentials.salt, credentials.hash);
+    }
+
+    credentials(account: string): (Credentials & { epoch: number }) | undefined {
+        return this.db.prepare('SELECT salt, hash, epoch FROM accounts WHERE id = ?').get(account) as unknown as (Credentials & { epoch: number }) | undefined;
+    }
+
+    issue(account: string, ttlMs: number, expectedEpoch?: number): string {
+        if (!Number.isInteger(ttlMs) || ttlMs < 100 || ttlMs > 86400000) throw new RangeError('Session lifetime must be 100ms–24h.');
+        return this.transaction(() => {
+            if (expectedEpoch !== undefined && this.credentials(account)?.epoch !== expectedEpoch) throw new Error('Sign-out occurred during sign-in. Try again.');
+            this.db.prepare('DELETE FROM sessions WHERE expires <= ?').run(Date.now());
+            const count = this.db.prepare('SELECT COUNT(*) AS count FROM sessions WHERE account = ?').get(account)!.count as number;
+            if (count >= 32) throw new Error('Sign out existing sessions before signing in again.');
+            const token = randomBytes(32).toString('base64url');
+            this.db.prepare('INSERT INTO sessions(token, account, expires) VALUES (?, ?, ?)').run(digest(token), account, Date.now() + ttlMs);
+            return token;
+        });
+    }
+
+    session(token: string): Session | undefined {
+        if (!/^[A-Za-z0-9_-]{43}$/.test(token)) return undefined;
+        return this.db.prepare('SELECT account, expires FROM sessions WHERE token = ? AND expires > ?').get(digest(token), Date.now()) as unknown as Session | undefined;
+    }
+
+    list(token: string): Card[] {
+        const { account } = this.requireSession(token);
+        return this.db.prepare('SELECT id, title FROM cards WHERE account = ? ORDER BY rowid').all(account) as unknown as Card[];
+    }
+
+    add(token: string, title: string): string {
+        if (typeof title !== 'string' || !title.trim() || title.length > 80 || /[\p{Cc}\p{Cf}]/u.test(title)) throw new TypeError('Invalid card title.');
+        return this.transaction(() => {
+            const { account } = this.requireSession(token);
+            const count = this.db.prepare('SELECT COUNT(*) AS count FROM cards WHERE account = ?').get(account)!.count as number;
+            if (count >= MAX_CARDS) throw new Error('Card limit reached.');
+            this.db.prepare('INSERT INTO cards(id, account, title) VALUES (?, ?, ?)').run(randomUUID(), account, title.trim());
+            return account;
+        });
+    }
+
+    remove(token: string, id: string): string {
+        return this.transaction(() => {
+            const { account } = this.requireSession(token);
+            this.db.prepare('DELETE FROM cards WHERE id = ? AND account = ?').run(id, account);
+            return account;
+        });
+    }
+
+    signOut(token: string): string | undefined {
+        return this.transaction(() => {
+            const session = this.session(token);
+            if (!session) return undefined;
+            this.db.prepare('DELETE FROM sessions WHERE account = ?').run(session.account);
+            this.db.prepare('UPDATE accounts SET epoch = epoch + 1 WHERE id = ?').run(session.account);
+            return session.account;
+        });
+    }
+
+    close() { if (!this.closed) { this.closed = true; this.db.close(); } }
+
+    private requireSession(token: string): Session {
+        const session = this.session(token);
+        if (!session) throw new Error('Session expired. Sign in again.');
+        return session;
+    }
+
+    private transaction<T>(operation: () => T): T {
+        this.db.exec('BEGIN IMMEDIATE');
+        try { const result = operation(); this.db.exec('COMMIT'); return result; }
+        catch (error) { this.db.exec('ROLLBACK'); throw error; }
+    }
+}

package/recipes/http-ws/README.md

@@ -0,0 +1,11 @@
+## HTTP and WebSockets on one listener
+
+One Node server answers ordinary HTTP requests and upgrades `/chat` connections to WebSockets. HTTP paths select Express services; a socket URL selects a route and each message's `type` selects a handler. No socket decorators or secondary `message.action` dispatcher are needed.
+
+After starting the application, request `http://127.0.0.1:8181/health` to receive `{"ok":true}`. Connect a WebSocket to `ws://127.0.0.1:8181/chat` and send `{"type":"hello"}` to receive `{"type":"hello","message":"Hello from the server!"}`. This is a raw JSON socket example, not a chatroom UI or the versioned socket-contract protocol. Use the chat or socket starter for those applications.
+
+The HTTP builder does not bind a port. The socket service explicitly takes responsibility for listening and closing the supplied server with `listen: true` and `closeServerOnShutdown: true`. Call the returned application's `shutdown()`; it processes route failures and still closes its HTTP/TCP peers. Do not separately close the HTTP builder. Importing this module creates no listener; the standalone entrypoint uses the same bounded `runApp` helper as the other starters.
+
+`/health` reports liveness, not readiness or completed application work. Loopback binding is intentional. Before exposing the service, choose your deployment bind address, configure HTTPS/WSS, trusted origins, authentication, authorization, payload/connection limits, and any persistence you need. Shared listeners do not automatically provide these policies. Shutdown may force connections closed; it does not guarantee message delivery or durable work.
+
+`npm test` runs real HTTP and WebSocket requests on ephemeral ports, checks strict socket routing and multiple clients, verifies idempotent cleanup with an incomplete HTTP peer, and proves a failing route cleanup still closes the listener. It also runs the shared process-lifecycle suite. No mocks are used. The package verification gate repeats the tests against the compiled application with `src/` unavailable.

package/recipes/http-ws/app.test.cjs

@@ -0,0 +1,92 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const net = require('node:net');
+const { once } = require('node:events');
+const WebSocket = require('ws');
+const { SocketRoute } = require('redweb');
+const { createApp, Hello } = require('../dist/app.js');
+const { listen, connect } = require('./network.cjs');
+
+test('an absent PORT binds the documented default or reports that exact port occupied', { timeout: 10000 }, async () => {
+    const { spawnSync } = require('node:child_process');
+    const env = { ...process.env };
+    delete env.PORT;
+    const result = spawnSync(process.execPath, ['-e', `
+        const assert = require('node:assert/strict');
+        const { once } = require('node:events');
+        const WebSocket = require('ws');
+        const { createApp } = require('./dist/app.js');
+        (async () => {
+            const app = createApp();
+            let socket;
+            try {
+                try { if (!app.server.listening) await once(app.server, 'listening'); }
+                catch (error) {
+                    assert.equal(error.code, 'EADDRINUSE');
+                    assert.equal(error.port, 8181);
+                    return; // Never send test traffic to a listener this test does not own.
+                }
+                assert.equal(app.server.address().port, 8181);
+                const response = await fetch('http://127.0.0.1:8181/health', { signal: AbortSignal.timeout(3000) });
+                assert.deepEqual(await response.json(), { ok: true });
+                socket = new WebSocket('ws://127.0.0.1:8181/chat', { handshakeTimeout: 3000 });
+                await once(socket, 'open');
+                const reply = once(socket, 'message');
+                socket.send(JSON.stringify({ type: 'hello' }));
+                assert.equal(JSON.parse((await reply)[0].toString()).type, 'hello');
+            } finally { socket?.terminate(); await app.shutdown(); }
+        })().catch(error => { console.error(error); process.exitCode = 1; });
+    `], { env, encoding: 'utf8', timeout: 7000, windowsHide: true });
+    assert.equal(result.error, undefined);
+    assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+
+test('HTTP and separate message handlers share one port, with strict socket paths', { timeout: 10000 }, async t => {
+    const origin = await listen(t);
+    const response = await fetch(`${origin}/health`, { signal: AbortSignal.timeout(3000) });
+    assert.equal(response.status, 200);
+    assert.deepEqual(await response.json(), { ok: true });
+    assert.equal((await fetch(`${origin}/missing`, { signal: AbortSignal.timeout(3000) })).status, 404);
+    for (let index = 0; index < 2; index++) {
+        const client = await connect(t, `${origin.replace('http:', 'ws:')}/chat`, origin);
+        client.send({ type: 'hello' });
+        assert.deepEqual(await client.receive(message => message.type === 'hello'),
+            { type: 'hello', message: 'Hello from the server!' });
+    }
+    const unknown = new WebSocket(`${origin.replace('http:', 'ws:')}/missing`, { handshakeTimeout: 3000 });
+    t.after(() => unknown.terminate());
+    await once(unknown, 'error');
+});
+
+for (const failingRoute of [false, true]) {
+    test(`shutdown closes incomplete HTTP peers${failingRoute ? ' despite a route failure' : ' idempotently'}`, { timeout: 10000 }, async t => {
+        const app = createApp({ port: 0, logger: null });
+        t.after(() => app.shutdown().catch(() => {}));
+        if (!app.server.listening) await once(app.server, 'listening');
+        assert.equal(app.closeServerOnShutdown, true);
+        const failure = new Error('Application cleanup failed');
+        if (failingRoute) {
+            class FailingRoute extends SocketRoute {
+                constructor() { super({ path: '/fails', handlers: [Hello] }); }
+                async shutdown() { await super.shutdown(); throw failure; }
+            }
+            app.addRoute(FailingRoute);
+        }
+        const accepted = once(app.server, 'connection');
+        const peer = net.connect(app.server.address().port, '127.0.0.1');
+        t.after(() => peer.destroy());
+        peer.on('error', () => {});
+        await once(peer, 'connect');
+        const [serverPeer] = await accepted;
+        peer.write('POST /health HTTP/1.1\r\nHost: localhost\r\nContent-Length: 100\r\n\r\nx');
+        const closed = once(serverPeer, 'close');
+        const shutdown = app.shutdown();
+        assert.equal(app.shutdown(), shutdown);
+        if (failingRoute) await assert.rejects(shutdown, error => error.errors.length === 1 && error.errors[0] === failure);
+        else await shutdown;
+        await closed;
+        assert.equal(serverPeer.destroyed, true);
+        assert.equal(app.server.listening, false);
+        assert.equal(app.server.listenerCount('upgrade'), 0);
+    });
+}

package/recipes/http-ws/app.tsx

@@ -0,0 +1,36 @@
+import { BaseHandler, HttpServer, METHODS, SocketRoute, SocketServer, type RedWebSocket, type SocketServerOptions } from 'redweb';
+import { runApp } from './run-app';
+
+export class Hello extends BaseHandler {
+    constructor() { super('hello'); }
+
+    onMessage(socket: RedWebSocket) {
+        socket.sendJson({ type: 'hello', message: 'Hello from the server!' });
+    }
+}
+
+export class ChatRoute extends SocketRoute {
+    constructor() {
+        super({ path: '/chat', handlers: [Hello], allowDuplicateConnections: true });
+    }
+}
+
+export function createApp(options: Pick<SocketServerOptions, 'port' | 'bind' | 'logger'> = {}) {
+    const http = new HttpServer({
+        listen: false,
+        publicPaths: [],
+        services: [{ serviceName: '/health', method: METHODS.GET, function: (_req, res) => res.json({ ok: true }) }],
+    });
+
+    return new SocketServer({
+        port: options.port ?? Number(process.env.PORT ?? 8181),
+        bind: options.bind ?? '127.0.0.1',
+        logger: options.logger,
+        server: http.server,
+        routes: [ChatRoute],
+        listen: true,
+        closeServerOnShutdown: true, // One owner closes routes and the shared HTTP listener.
+    });
+}
+
+if (require.main === module) runApp(createApp);

package/recipes/realtime/README.md

@@ -0,0 +1,8 @@
+## Realtime starter
+
+`CounterPage` owns its state on the server. `shared: true` deliberately shares the counter between visitors.
+The browser button invokes only the decorated `increment` action; it does not supply the new count.
+Open two tabs to check the broadcast. State is in memory and resets when the server restarts.
+
+`<output>{this.count}</output>` updates automatically because the page reads decorated state during rendering.
+No repeated binding name or browser-side state is needed. State changes are assignment-driven; render methods must not modify state.

package/recipes/realtime/app.test.cjs

@@ -0,0 +1,15 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { listen, live } = require('./network.cjs');
+
+test('one server action updates both visitors', { timeout: 10000 }, async t => {
+    const origin = await listen(t);
+    const first = await live(t, origin);
+    const second = await live(t, origin);
+    await first.patch(patch => patch.html.includes('<output>0</output>'));
+    await second.patch(patch => patch.html.includes('<output>0</output>'));
+    first.action('increment');
+    await first.patch(patch => patch.html.includes('<output>1</output>'));
+    await second.patch(patch => patch.html.includes('<output>1</output>'));
+    assert.match(await (await fetch(origin)).text(), /<output>1<\/output>/);
+});

package/recipes/realtime/app.tsx

@@ -0,0 +1,28 @@
+import { action, page, start, state, type LiveHtmlStartOptions } from 'redweb';
+import { runApp } from './run-app';
+
+@page('/', { css: 'app.css', shared: true })
+export class CounterPage {
+    @state() count = 0;
+
+    @action()
+    increment() { this.count += 1; }
+
+    render() {
+        return (
+            <main class="home">
+                <h1>A counter owned by the server</h1>
+                <p>Open this page in two tabs. Either button updates both.</p>
+                <button rw-click="increment">
+                    Count <output>{this.count}</output>
+                </button>
+            </main>
+        );
+    }
+}
+
+export function createApp(options: LiveHtmlStartOptions = {}) {
+    return start(CounterPage, { port: Number(process.env.PORT ?? 8181), templateRoot: __dirname, ...options });
+}
+
+if (require.main === module) runApp(createApp);

package/recipes/shared/README.md

@@ -0,0 +1,40 @@
+# Your Redweb application
+
+Requirements: Node.js 18 or newer and npm for the realtime, chat, site, socket and http-ws templates; the dashboard template requires Node.js 22.13+ for native SQLite. Use a currently supported Node.js release in production.
+
+For an unreleased checkout or tarball, first run `npm install --save-exact TARBALL`, replacing `TARBALL` with the absolute path to the same tested Redweb tarball used to generate this app (quote paths containing spaces). This installs the matching package and its published client dependency. Do not substitute an older registry release or `latest`. Published Redweb releases can use the installation command below directly.
+
+```sh
+npm install
+npm test
+npm run dev
+```
+
+HTTP starters open at http://localhost:8181; the authenticated dashboard uses http://127.0.0.1:8181/login and requires account provisioning described below. Set the `PORT` environment variable to change the listener.
+`npm test` builds and runs real HTTP/WebSocket integration tests on an ephemeral loopback port. No mocks or external service are needed.
+`npm run test:coverage` runs the same tests with application coverage mapped back to TypeScript. Reports are written to the ignored `coverage/` directory; this is separate from Redweb library coverage. TypeScript-generated decorator accessors can appear in function counts even when the framework does not call them. The report exposes remaining gaps; it does not certify complete application coverage. Source maps are generated during the build for diagnostics and coverage, but no coverage collector is loaded by `npm start`.
+
+## Development and production
+
+Edit `src/app.tsx`. `npm run dev` watches TypeScript, TSX, CSS, HTML, and the root TypeScript configuration,
+then rebuilds and restarts the server. A type error stops startup until you fix it. On direct localhost access,
+HTML pages refresh automatically when a new server revision is ready. If edits were detected, a keyboard-accessible
+notice keeps the old document until you choose **Reload and discard drafts**. This is a conservative edit guard,
+not autosave or browser hot-module replacement: restarts reset in-memory state and old socket sessions.
+The generated development command sets `REDWEB_DEV_REFRESH=1`; `development: { refresh: false }` overrides it.
+The refresh feature is refused under `NODE_ENV=production`, applies only to served HTML (not raw sockets or static exports),
+and creates no local/session-storage copy of form contents. Use direct `localhost`, `127.x.x.x`, or `[::1]` access;
+custom hostnames, tunnels and proxy-forwarded origins are not supported by this development helper.
+`npm run build` checks types and copies CSS/HTML beside the compiled classes in `dist/`.
+Run `npm start` to serve the compiled app. For deployment, build first, ship `dist/`, `package.json`, and the lockfile,
+then install runtime dependencies with `npm ci --omit=dev`. The application does not require TypeScript or `src/` at runtime.
+
+The standalone entrypoint calls the shared `runApp(createApp)` helper. Importing either module starts no listener and installs no process handlers. On SIGINT/SIGTERM, a listener error, or native listener closure, the helper calls application shutdown once. Repeated signals do not bypass cleanup. The five-second outer deadline covers the whole application, including database/worker cleanup after HTTP closes; customize it with the helper's second argument if necessary. Cleanup must resolve only after resources are released. A failed cleanup sets a failure exit status and retains a deadline for any surviving handles; the helper never resets an existing failure status. If cleanup does not finish in time, the entrypoint terminates the process with a failure status. This cannot preempt synchronous code blocking Node's event loop and does not make in-memory state durable. Factory functions remain responsible for releasing partially constructed resources before throwing.
+
+The shipped lifecycle tests exercise actual processes, HTTP/TCP/WebSocket peers and timers. Linux uses actual OS signals; Windows tests explicitly emit signal events inside the process because killing a Windows child does not exercise graceful POSIX signal delivery. This is not a claim that Windows console/service managers forward the same signals. Deploy with a supervisor that forwards the supported termination signal and allows longer than the configured cleanup deadline.
+
+For public deployment, configure HTTPS/WSS at your Node server or reverse proxy, authentication, trusted origins,
+and application-specific rate limits. These starters are demonstrations, not a hosted identity or database service.
+Never commit secrets; `.env` is ignored but is not loaded automatically.
+
+`npx --no-install redweb doctor --json` reports configuration problems without changing your files.

package/recipes/shared/app.css

@@ -0,0 +1,8 @@
+:root { color-scheme: dark; font-family: system-ui, sans-serif; background: #08090d; color: #fff; }
+body { margin: 0; }
+.home { width: min(42rem, calc(100% - 2rem)); margin: 18vh auto 0; }
+h1 { font-size: clamp(2rem, 6vw, 4rem); line-height: 1.1; }
+p { color: #bfc1ca; line-height: 1.6; }
+button { padding: .8rem 1.2rem; background: #ff5064; color: #08090d; border: 0; border-radius: .5rem; cursor: pointer; font: inherit; }
+button:focus-visible, a:focus-visible { outline: 3px solid #fff; outline-offset: 4px; }
+nav { padding: 1rem; } a { color: #ff8795; }

package/recipes/shared/copy-assets.cjs

@@ -0,0 +1,8 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Keep runtime assets beside the compiled classes. Production needs only dist/ and dependencies.
+fs.cpSync('src', 'dist', {
+    recursive: true,
+    filter: file => fs.statSync(file).isDirectory() || ['.css', '.html'].includes(path.extname(file)),
+});

package/recipes/shared/network.cjs

@@ -0,0 +1,59 @@
+const assert = require('node:assert/strict');
+const { once } = require('node:events');
+const WebSocket = require('ws');
+const { createApp } = require('../dist/app.js');
+
+async function listen(t) {
+    const app = createApp({ port: 0, bind: '127.0.0.1', logger: null });
+    t.after(() => app.shutdown());
+    if (!app.server.listening) await once(app.server, 'listening');
+    return `http://127.0.0.1:${app.server.address().port}`;
+}
+
+async function connect(t, url, origin, headers = {}) {
+    const socket = new WebSocket(url, { headers: { ...headers, Origin: origin } });
+    const messages = [];
+    socket.on('message', raw => messages.push(JSON.parse(raw.toString())));
+    t.after(async () => {
+        if (socket.readyState === WebSocket.CLOSED) return;
+        const closed = once(socket, 'close');
+        // Cleanup must not depend on a peer completing the closing handshake.
+        // Tests of graceful disconnect explicitly close and await their sockets.
+        socket.terminate();
+        await closed;
+    });
+    await once(socket, 'open');
+    return {
+        socket,
+        send: message => socket.send(JSON.stringify(message)),
+        async receive(predicate) {
+            const deadline = Date.now() + 3000;
+            while (Date.now() < deadline) {
+                const index = messages.findIndex(predicate);
+                if (index !== -1) return messages.splice(index, 1)[0];
+                await new Promise(resolve => setTimeout(resolve, 10));
+            }
+            assert.fail(`Timed out waiting for a socket message; received ${JSON.stringify(messages)}`);
+        },
+    };
+}
+
+async function live(t, origin, headers = {}) {
+    const response = await fetch(origin, { headers });
+    assert.equal(response.status, 200);
+    const document = await response.text();
+    const config = JSON.parse(document.match(/id="__redweb_page">([^<]+)</)[1]);
+    const connection = await connect(t, `${origin.replace('http:', 'ws:')}${config.socketPath}?pageId=${config.pageId}&redwebVersion=${encodeURIComponent(config.version)}`, origin, headers);
+    return {
+        ...connection,
+        document, config,
+        patch: predicate => connection.receive(message => message.type === 'redweb:patch' && message.payload.patches.some(predicate)),
+        action: (name, args = [], component) => connection.send({
+            v: config.version, type: 'redweb:html', payload: { kind: 'action', name, args, component },
+        }),
+        state: (name, value, component) => connection.receive(message => message.type === 'redweb:state' &&
+            message.payload.name === name && message.payload.component === component && value(message.payload.value)),
+    };
+}
+
+module.exports = { listen, connect, live };