redweb 0.12.0 → 0.13.0

package/docs/guides/chatroom.md

@@ -0,0 +1,27 @@
+# Build a chatroom with live presence
+
+Build a shared chatroom where visitors choose a name once, send messages, and see who is online. The starter includes the canonical reusable `ChatroomComponent`, its stylesheet, input validation and real-network tests. You do not write a browser WebSocket handler for every message or member change.
+
+## Explain it like I'm five
+
+The room is a noticeboard managed by the server. Each visitor gets a little window onto it. The room keeps the recent messages and the online list; each visitor's component keeps their name and what their window should show. When the noticeboard changes, the server updates the windows.
+
+## Follow the design
+
+1. The [application entrypoint](../../recipes/chat/app.tsx) starts a page created by `createChatroomPage()`. The component source shown below is copied from the maintained example, not a separate implementation.
+2. `ChatRoom` owns shared message/member data. `ChatroomComponent` owns a participant's state, server-callable actions and view. Normal TypeScript conditions choose the join screen or conversation screen.
+3. Decorated join/send actions validate form values through the starter's Zod schemas. Redweb provides loading/error feedback; invalid input does not require custom browser glue to preserve the draft.
+4. `connected()` restores online participation when a retained participant reconnects. `disconnected()` removes online presence; later disposal releases retained identity. A name reserved briefly for reconnect does not mean the person is still online.
+5. State assignments and stable JSX keys update messages and members. A function that returns reusable markup alone would not replace this component's owned lifecycle and actions.
+
+Display names are not authenticated identities. Use the [private dashboard guide](realtime-dashboard.md) and [authorization reference](../ROOM_AUTHORIZATION.md) when your application needs verified accounts and private data.
+
+## Check that it works
+
+Open two tabs at `http://localhost:8181/`, choose different names and send a message. Both should see its sender and text. Close one tab and confirm its online presence disappears once the server observes the disconnect. Abrupt network loss is not necessarily detected immediately; heartbeat and network timing matter. Reconnect is not a promise of durable identity.
+
+The [starter tests](../../recipes/chat/app.test.cjs) exercise actual pages, sockets, server actions, escaped message delivery and disconnect behavior. The package gate repeats them after source removal. Test invalid inputs, browser focus, unsent drafts and reconnects on your supported browsers as well.
+
+## Before promising durable chat
+
+History is bounded to **100 messages in server memory**. It survives neither a process restart nor independent workers. Add application-owned persistence and a deliberate cross-process notification design before promising durable history or distributed rooms. Add authentication, membership authorization and abuse controls before exposing private or public rooms. The raw socket handler starter is a different abstraction; do not replace this component with a second browser message dispatcher merely to update its HTML.

package/docs/guides/http-websocket.md

@@ -0,0 +1,28 @@
+# Serve HTTP and WebSockets on one port
+
+Build an Express endpoint and a raw WebSocket route on the same Node listener. Use this when an existing HTTP application needs socket endpoints without a second port or a separate web framework. This guide demonstrates server composition, not a rendered chat interface.
+
+## Explain it like I'm five
+
+Imagine one front door with two signs. Ordinary HTTP visitors ask for a page or JSON response. WebSocket visitors ask to keep a conversation open. Both use the same door, but different route and handler classes decide what happens inside. One owner is responsible for closing the building.
+
+## Follow the design
+
+1. `HttpServer({ listen: false })` builds the Express application and Node server without opening a port. `/health` answers ordinary HTTP requests; `publicPaths: []` avoids exposing an incidental working-directory folder.
+2. Pass that Node server to `SocketServer`, alongside the `/chat` route. `listen: true` explicitly starts the supplied listener; `closeServerOnShutdown: true` assigns its cleanup to the socket service.
+3. The URL selects `ChatRoute`. A raw JSON message with `type: "hello"` selects `Hello`; there is no secondary action dispatcher.
+4. `createApp()` returns the one cleanup owner. Its `shutdown()` processes route failures and still closes the shared HTTP peers. The generated entrypoint helper adds bounded process shutdown without another handwritten signal policy.
+
+The framework ordinarily leaves supplied listeners caller-owned. These explicit flags are a choice made by this starter, not a change to that default. Use [migration and ownership guidance](../MIGRATION.md) when adapting an existing application; do not let two independent services compete to close the same listener.
+
+## Check that it works
+
+Request `http://127.0.0.1:8181/health` and expect `{"ok":true}`. Open a WebSocket to `ws://127.0.0.1:8181/chat`, send `{"type":"hello"}`, and expect `{"type":"hello","message":"Hello from the server!"}`. An unknown socket path is rejected rather than sent to a catch-all handler.
+
+The [shipped tests](../../recipes/http-ws/app.test.cjs) use real HTTP and WebSocket clients on one ephemeral port. They also leave an HTTP request incomplete, repeat shutdown, and deliberately fail an application route's cleanup to confirm the listener still closes. Shared lifecycle tests cover process-level shutdown failures; the package gate repeats the compiled application checks with source removed.
+
+## Before public deployment
+
+The starter deliberately binds loopback. Configure the deployment bind address and HTTPS/WSS termination, trusted origins, identity, authorization and capacity limits before exposing it. `/health` proves liveness, not readiness to accept game traffic or completion of durable work. Forced shutdown closes transports; it does not guarantee delivery, transaction completion or storage.
+
+For shared validation and inferred payloads, use the [typed WebSocket guide](typed-websockets.md). For UI updates driven by server-side components, use the [chatroom guide](chatroom.md). See [operations and deployment boundaries](../MULTIPLAYER_OPERATIONS.md) before adding proxies or multiple workers.

package/docs/guides/jsx-without-react.md

@@ -0,0 +1,26 @@
+# Render JSX without React
+
+Build a two-page TypeScript site with shared navigation, a stylesheet and per-page metadata. JSX is a markup syntax here: Redweb renders it on Node.js, without React hooks, hydration, or a browser component runtime. This is useful for documentation, content sites and server-rendered pages that do not need browser-side component execution.
+
+## Explain it like I'm five
+
+The page class is a recipe and the server is the kitchen. `render()` prepares HTML before it reaches the browser. A shared layout adds the same navigation around each page, like putting different meals on the same kind of plate. The browser receives the finished document, not the kitchen.
+
+## Follow the design
+
+1. The initializer supplies `redweb/tsconfig.json` inheritance, TypeScript, the stylesheet and the entrypoint helper. Keep the file as `.tsx`; do not point its JSX settings at `react/jsx-runtime`.
+2. `defineSite()` supplies one layout and CSS declaration. Its page decorators register `/` and `/about`, with metadata beside each page.
+3. Each `render()` returns ordinary TSX. Function components can share presentation; page-specific data remains in your server code. Text and attribute values are escaped, and URL protocols are restricted.
+4. `createApp()` combines both pages on one listener. The standalone entrypoint owns bounded shutdown through the shared helper; importing the module starts nothing.
+
+Keep CSS in external files. The [rendering reference](../LIVE_HTML.md) covers components, templates, assets and static export. For interactive pages, start from the [realtime counter](../../recipes/realtime/README.md): assignments to decorated state update the browser through Redweb's runtime. Non-live site pages do not acquire that behavior just because their markup is JSX.
+
+## Check that it works
+
+Open `http://localhost:8181/`, follow About, and confirm the navigation and styling stay consistent while the title and content change. View the response source: it is server-rendered HTML, not an empty mount point. The [shipped test](../../recipes/site/app.test.cjs) checks actual HTTP responses, both pages, CSS and absence of the live-page runtime. The package gate repeats it with the source directory unavailable.
+
+`npm run build` produces compiled code and copied assets; `npm start` serves that output. `site.export()` is a separate static-export workflow, not what the starter's default build does. Static export cannot replace protected or live application requests.
+
+## When to choose another approach
+
+Redweb TSX is not React-compatible. Do not import React components or expect hooks, client effects, browser rendering or automatic support for browser-only libraries. Choose an appropriate browser framework when those are core requirements. Live Redweb applications require a Node host with long-lived listeners; exported static files have a different deployment model. See [compatibility and release verification](../RELEASE_TRUST.md).

package/docs/guides/realtime-dashboard.md

@@ -0,0 +1,29 @@
+# Build a private realtime dashboard
+
+Build a page where signed-in users create cards, see their other tabs update, and find the same cards after a server restart. Use the dashboard starter on **Node 22.13 or newer**; this application uses native SQLite. It is a complete application recipe, not a new database or authentication framework inside Redweb.
+
+## Explain it like I'm five
+
+Think of SQLite as a locked notebook and each browser tab as a window onto it. The server checks whose notebook you may open before reading or changing a card. After a successful change, it tells that account's other open windows to read their latest cards. The windows are not the notebook: closing them does not erase saved data.
+
+## Follow the design
+
+1. The setup command below provisions `alice` after installing dependencies. It prints a generated password once; save it privately. There is no default password. Open `http://127.0.0.1:8181/login` after development starts.
+2. `app.tsx` composes the store, session checks, protected page and shutdown. The `Cards` component below owns presentation and actions, not the database connection.
+3. `loading()` reads the current account's cards. `connected()` subscribes that browser connection to private updates; disconnect and disposal release the subscription.
+4. The add/remove actions validate form input before calling the store. The store rechecks the session and owner within each write transaction; a hidden input is not permission to delete someone else's card.
+5. `PrivateCards.publish()` refreshes only valid subscribers for that account. Assigning the new array to decorated state updates keyed TSX without a manual browser message handler.
+
+See the complete [composition](../../recipes/dashboard/app.tsx), [store](../../recipes/dashboard/store.ts), [authentication](../../recipes/dashboard/auth.ts), and [acceptance tests](../../recipes/dashboard/app.test.cjs). The generated recipe supplies all of them together.
+
+## Check that it works
+
+Sign in from two tabs, add a card in one, and confirm both show it. A different account must not see it. Restart the process with the same database path and confirm the card remains. Sign out all sessions and verify both tabs lose access. `npm test` exercises real HTTP, WebSockets, temporary SQLite data, account isolation, restart and expiry; it does not modify your application database. Run your own browser checks for the browsers you support.
+
+## Before deployment
+
+Keep `DASHBOARD_DATABASE` on a writable persistent volume and out of public assets, source control and logs. Follow the [recipe's origin, cookie, account-provisioning and backup instructions](../../recipes/dashboard/README.md). Browser refresh is not persistence; successful storage and a retained database are what preserve cards.
+
+On a compiled-only deployment, provision accounts with `node dist/admin.js alice` using the same database environment and volume, before starting the service. The development `npm run add-user` script rebuilds first and therefore needs development tooling; the compiled administrator command does not. Never copy a generated password into logs or deployment manifests.
+
+This recipe uses **single-process** notifications and revocation. Multiple workers do not automatically exchange updates or logout events. It has no password reset, MFA or account recovery; use a dedicated identity integration when those are requirements. Do not replace server-side permission checks with a `shared: true` page containing private state. See [request and room authorization](../ROOM_AUTHORIZATION.md) and [production boundaries](../PRODUCTION_READINESS.md).

package/docs/guides/typed-websockets.md

@@ -0,0 +1,26 @@
+# Share typed WebSocket contracts
+
+Build a `/match` service with independent join, move and resume handlers. A shared schema validates payloads and supplies TypeScript types to both sides. Use this when you need a raw socket protocol, such as a game client or a custom realtime client, rather than a server-rendered page.
+
+## Explain it like I'm five
+
+The URL is the room's address. A message's `type` tells the receptionist which person should handle it. The shared contract is the form that says what information that person needs. Checking the form before handing it over prevents a movement handler from receiving a name where a coordinate should be.
+
+## Follow the design
+
+1. [The contract](../../recipes/socket/contract.ts) declares `join`, `move`, `resume` and `state` once. It is safe to import into a browser bundle because it does not import the server application.
+2. [The route](../../recipes/socket/app.tsx) binds `/match`, enables the contract protocol and registers `Join`, `Move` and `Resume`. There is no socket decorator layer and no inner `message.action` switch.
+3. The handlers below receive parsed payloads. `Join` creates an in-memory player session, `Move` changes its server-owned coordinates, and `Resume` reclaims it using a private bearer token.
+4. Each sends a validated `state` response. A client uses `match.client(socket)` to send and parse typed messages. That wrapper does **not** open or reconnect its transport; the application creates the WebSocket first.
+
+Connect to `ws://localhost:8181/match?redwebVersion=1` during local development. Follow the [complete recipe's client example](../../recipes/socket/README.md) for opening a transport and handling responses; use WSS outside local development. The [contract reference](../SOCKET_CONTRACTS.md) documents wire envelopes, validation and failure behavior.
+
+## Check that it works
+
+Join with two independent clients, move one, then disconnect and resume it with its session token. The other player's state must remain independent. Send invalid coordinates and a malformed raw message to verify both client and server checks. The [real-socket acceptance test](../../recipes/socket/app.test.cjs) covers those sequences, including server rejection that bypasses client validation.
+
+## This is not a complete game backend
+
+The example bounds coordinate values; it does not prove a move obeys your game's speed, turn or collision rules. Add authoritative game rules and authentication. Keep session tokens private: possession permits resume and connection takeover. Sessions are capped at 100, expire 30 seconds after disconnect, and are lost on restart. They are not a durable or cross-worker identity store.
+
+Per-connection ordering is not exactly-once delivery. After a disconnect, a client may not know whether its last action completed; reconcile state before retrying side effects. Choose transport limits from measured load and read [operations](../MULTIPLAYER_OPERATIONS.md) and [runtime retry boundaries](../RUNTIME_DIAGNOSTICS.md).