toiljs 0.0.85 → 0.0.87

package/docs/introduction/why-toil.md

@@ -0,0 +1,93 @@
+# Why toil? Who is it for?
+
+toil is a full-stack framework: you write a React frontend and a TypeScript backend in one project, and toil runs both (plus a database) close to every user, worldwide.
+
+The thesis in one line: toil is the modern full-stack tech a developer would actually want, AAA-grade from the very first line, and hyper-scalable at the same time. Even a simple pizza site gets top-tier infrastructure with zero setup. Distributed writes are one pillar of that. The modern stack that just works is the heart.
+
+## The problem with today's stacks
+
+Two problems, really.
+
+**Read-global, write-central.** Your pages load fast from caches worldwide. But a *write* (a comment, a like, an order) usually travels to one database in one region. A user in Sydney writing to a database in Virginia pays for the round trip. That single region is also a single point of failure.
+
+**The ten-vendor tax.** A typical production stack is stitched from rented services: a frontend host, serverless functions, a managed database, auth, email, a queue, a cache, analytics, realtime. Each is its own account, bill, SDK, and failure mode. You did not set out to be a systems integrator, but the stack hands you the job.
+
+And every third-party service on your **critical path** (what must work for a request to succeed) is a black box you cannot inspect, patch, or fully secure. When it is slow, you are slow. When it is breached, part of you is breached.
+
+The result: a solo builder and a funded startup hit the *same* wall. Good, safe, fast infrastructure means assembling and babysitting a lot of parts, so most people settle for less.
+
+## What toil does instead
+
+Close the gap, own the pieces, and make the good version the *default* version. Four pillars.
+
+### 1. AAA-grade from the first line
+
+Top-tier infrastructure on day one, on the smallest project, with zero setup: edge compute (your code runs near users worldwide), one-line post-quantum login, automatic tamper-proofing of your app's code, HTTP/3, and a global database already there.
+
+A pizza site and a planet-scale app start from the same baseline. "AAA-grade" is the actual bar toil grades itself against; see [design principles](./design-principles.md).
+
+### 2. Batteries-included, and owned
+
+Auth, database, email, rate limiting, analytics, realtime streaming, and background jobs are all built in and are toil's own. Nothing third-party sits on your critical path.
+
+Because they are one system, the parts already fit. You are not gluing ten SDKs together and praying they agree. Full catalog: [The modern stack](./modern-stack.md).
+
+```mermaid
+flowchart TB
+    subgraph assemble["Usual way: assemble ten vendors"]
+        direction TB
+        A1["Your app"] --> V1["host"]
+        A1 --> V2["functions"]
+        A1 --> V3["database"]
+        A1 --> V4["auth"]
+        A1 --> V5["email"]
+        A1 --> V6["rate limiter"]
+        A1 --> V7["analytics"]
+        A1 --> V8["realtime"]
+        A1 --> V9["jobs"]
+    end
+    subgraph toil["toil: one owned stack"]
+        direction TB
+        A2["Your app"] --> T["edge + database + auth + email +<br/>rate limiting + analytics +<br/>streaming + jobs, built in"]
+    end
+```
+
+Honest boundary: "owned" means the *core* of a working app is toil's, not that outside services are banned. Call a payment provider or another API and you still can.
+
+### 3. A modern DX that just works
+
+TypeScript end to end, one repo, one deploy, wired by types: change a field on the server and the frontend stops compiling until you fix it (a compile error at your desk, not a production bug).
+
+The toolchain is set up for you: ESLint, Prettier (with a plugin for toil's decorators), an editor plugin, one CLI, and a `doctor` that fixes common problems in place. The docs are even LLM-friendly, so an AI assistant reads your current conventions instead of guessing. More in [The modern stack](./modern-stack.md).
+
+### 4. Hyper-scalable and distributed (one pillar, not the whole story)
+
+Your backend compiles to a tiny sandboxed **WebAssembly** module (a compact, locked-down binary that runs at near-native speed), so one edge box safely runs many apps, which makes running near everyone affordable.
+
+And the database, **ToilDB**, distributes the *writes*, not just the reads: every key has one **home** region that orders its writes, while data replicates outward for fast local reads. Distributing writes is the hard part almost nobody does. The trade is eventual consistency: a far read can lag a few milliseconds. See [How toil works](./how-it-works.md) and [How toil is distributed](./distributed.md).
+
+## Who it is for
+
+- **Solo builders and small teams:** a full, global, secure stack without hiring a platform team. The pizza site is first-class.
+- **Latency-sensitive apps:** writes that resolve near the user, not across an ocean.
+- **Global apps:** logic and data near users on every continent.
+- **Realtime apps:** chat, presence, and live cursors on built-in streaming, not a bolted-on vendor.
+
+Same install for the smallest project and the largest. You grow into the scale; you do not rebuild to reach it.
+
+## When not to use toil
+
+- **You need SQL or heavy joins.** ToilDB is seven purpose-built families, not a general SQL engine. See the [database overview](../database/README.md).
+- **You lean on the Node ecosystem.** The server is a strict TypeScript subset compiled to WebAssembly: no arbitrary npm packages, no Node APIs, built-in globals instead.
+- **You are happy single-region and simple.** If one region already fits, toil's distribution is effort you do not need.
+- **You need a big integration catalog today.** toil is younger, and that catalog is smaller.
+
+None of these are permanent, and the right tool is the one that fits the job in front of you.
+
+## Related
+
+- [The modern stack](./modern-stack.md): the full, verified catalog of what is built in.
+- [How toil works](./how-it-works.md): the whole machine end to end, from React client to ToilDB.
+- [toil versus other frameworks](./vs-other-frameworks.md): an honest, axis-by-axis comparison.
+- [Security](../concepts/security.md): the defaults that are already on.
+- [Getting started](../getting-started/README.md): install the tool and build a small feature.

package/docs/llms.txt

@@ -0,0 +1,90 @@
+# toiljs
+
+> toiljs is a full-stack web framework: you write the frontend in React and the backend in TypeScript, and toiljs compiles the backend to a sandboxed WebAssembly module that runs on the worldwide Dacely edge, with a built-in global database (ToilDB), streaming, background jobs, and auth included.
+
+This is the canonical documentation, organized by section. Each link points to a Markdown page (each folder's README.md is its landing page). If you are new, read the Understanding toil section first. A toiljs project has three parts: client/ (the React app in the browser), server/ (the backend, compiled to WebAssembly and run on the edge), and shared/ (a generated, fully typed client so the browser calls the server with end-to-end type safety). The backend is compiled by toilscript, a strict TypeScript-to-WebAssembly subset, so server code uses fixed-width number types (u64, i32, and so on) rather than the single JavaScript number type.
+
+## Understanding toil
+- [Understanding toil](introduction/README.md): This section is the "why." It explains what toil is, the problem it solves, how it works underneath, and why it is built the way it is.
+- [Why toil is built this way (the RSG bar)](introduction/design-principles.md): toil is opinionated on purpose.
+- [How toil is distributed](introduction/distributed.md): Distributing a website's reads is easy.
+- [How toil works](introduction/how-it-works.md): What your project compiles into, and what happens when a user makes a request.
+- [What makes toil hyper-scalable](introduction/hyperscale.md): **Hyper-scale** is serving very large, worldwide traffic at low latency without rebuilding your app as it grows.
+- [The modern stack: what toil gives you that others do not](introduction/modern-stack.md): Most frameworks give you a way to write code and then send you shopping: a database, an auth provider, email, a rate limiter, analytics, a realtime service, a job runner, all wired together and kept in sync by you.
+- [toil versus other stacks](introduction/vs-other-frameworks.md): An honest look at where each stack you already use hits a ceiling, and why toil bets on a different shape.
+- [Why toil? Who is it for?](introduction/why-toil.md): toil is a full-stack framework: you write a React frontend and a TypeScript backend in one project, and toil runs both (plus a database) close to every user, worldwide.
+
+## Getting started
+- [Getting started](getting-started/README.md): toiljs is a full-stack web framework: you write a React frontend and a TypeScript backend in one project, and toiljs ships both together.
+- [Create a project](getting-started/create-project.md): Scaffold a brand-new toiljs app with one command.
+- [Deploying a toiljs app](getting-started/deploy.md): This page is an honest look at how you get a toiljs app in front of real users.
+- [Your first app](getting-started/first-app.md): Build a tiny feature end to end: a page with a "Like" button that reads and writes a real number in ToilDB, so the count survives page reloads and restarts.
+- [Installation](getting-started/installation.md): Install the toiljs command-line tool (CLI) so you can create and run projects.
+- [Migrating an existing React app](getting-started/migrating.md): How to bring a React app you already have into toiljs.
+- [Project structure](getting-started/project-structure.md): A tour of every folder and file in a toiljs project, what each one is for, and the single most important question: **where does this code run, the browser or the edge?**
+
+## CLI
+- [The toiljs CLI](cli/README.md): The `toiljs` command is how you scaffold, run, build, self-host, and diagnose a toiljs app.
+
+## Frontend
+- [Frontend](frontend/README.md): Your toiljs frontend is a React app with file-based routing that runs in the browser, and can also be rendered ahead of time on the server for a fast first paint and good SEO.
+- [Fetching data](frontend/data-fetching.md): Your React frontend and your toiljs backend live in one project, so toiljs generates a **typed client** that lets the browser call your server with full type safety and no hand-written `fetch` boilerplate.
+- [Images](frontend/images.md): `Toil.Image` is a drop-in replacement for `<img>` that stops layout shift, lazy-loads by default, and can fade in from a blurred placeholder.
+- [Metadata and SEO](frontend/metadata.md): Metadata is the information in a page's `<head>`: its title, its description, and the tags that control how it looks when shared on social media or listed by a search engine.
+- [Rendering and SSR](frontend/rendering.md): This page explains where your pages are built: in the browser, ahead of time at build, or on the server for each request.
+- [Routing](frontend/routing.md): toiljs uses file-based routing: every file under `client/routes/` becomes a page, and its path on disk becomes its URL.
+- [Scripts](frontend/scripts.md): `Toil.Script` loads an external or inline `<script>` for you, with control over *when* it runs and a guarantee it runs only *once* across your whole app.
+- [Page search](frontend/search.md): toiljs ships a built-in search over your own pages: at build time it indexes every route's metadata (title, description, keywords, Open Graph), and at runtime you query that index to build a search box or a command palette that jumps straight to a page.
+- [Styling](frontend/styling.md): toiljs does not force a styling system on you.
+
+## Backend
+- [Backend overview](backend/README.md): Your backend is TypeScript that toilscript compiles into a small, sandboxed WebAssembly program, which runs on the Dacely edge and answers every request.
+- [Data types (`@data`)](backend/data.md): `@data` turns a plain class into a typed value that can travel safely between your frontend and your WASM backend, and in and out of the database, with both a binary and a JSON codec generated for you.
+- [HTTP routes (`@rest`)](backend/rest.md): Expose a real HTTP API by tagging a class `@rest` and its methods with an HTTP verb; toiljs generates the router for you.
+- [Typed RPC (`@service` / `@remote`)](backend/rpc.md): Write a server function, tag it `@remote`, and call it from your React frontend like a local async function, with the argument and return types checked end to end.
+
+## Database (ToilDB)
+- [ToilDB](database/README.md): ToilDB is the database built into toiljs.
+- [Capacity (limited stock without overselling)](database/capacity.md): A `Capacity` collection models a **finite resource that must never be oversold**: concert tickets, seats, limited-drop stock, rate grants.
+- [Counters](database/counters.md): The **Counter** family is a distributed running total that many callers can increase at the same time, from anywhere in the world, without ever losing a count.
+- [Documents](database/documents.md): The **Documents** family is ToilDB's general-purpose record store: you keep a value under a key and look it up, update it, or delete it by that key.
+- [Events (append-only logs)](database/events.md): An `Events` collection is an **append-only log**: a growing list of immutable facts under a key.
+- [Membership (sets and relationships)](database/membership.md): A `Membership` collection stores **sets**: unordered groups of members under a key.
+- [Declaring a database](database/setup.md): You set up ToilDB by **declaring** it in code: a `@database` class listing your collections, plus the `@data` key and value types those collections use.
+- [Unique](database/unique.md): The **Unique** family enforces that a value is claimed by only one owner across the entire world.
+- [Views (materialized views)](database/views.md): A `View` collection is a **precomputed, read-optimized result** that you publish once and read many times.
+
+## Auth
+- [Authentication](auth/README.md): Toil ships a complete, **post-quantum password login** you turn on with one line.
+- [Configuring auth for production](auth/configuration.md): Built-in auth runs locally with **zero configuration**, it falls back to published, insecure DEV secrets so `toiljs dev` Just Works.
+- [Extending & integrating auth](auth/extending.md): Built-in auth is deliberately opinionated so the common case is one line.
+- [How Toil auth works](auth/how-it-works.md): Toil auth is a **post-quantum, password-based, mutually-authenticated** login.
+- [Using auth](auth/usage.md): Either the config flag (canonical) or a one-line import, both do the same thing (the build appends the framework's auth controller + user shape to your server as compiled entries, so `/auth/*` self-mounts):
+
+## Realtime
+- [Realtime](realtime/README.md): Realtime is how your app pushes data to the browser the instant it happens, instead of the browser having to ask again and again.
+- [Channels (`useChannel`)](realtime/channels.md): `useChannel` is the client-side React hook for realtime.
+- [Streams (`@stream`)](realtime/streams.md): A `@stream` is a server class that handles one live connection from start to finish.
+
+## Background work
+- [Background work](background/README.md): Background work is code that runs **without a user waiting for it**: on a timer, once globally, or automatically after your data changes.
+- [Daemons (`@daemon` / `@scheduled`)](background/daemons.md): A `@daemon` is a single, long-lived background worker for your whole app.
+- [Derived views (`@derive`)](background/derive.md): A `@derive` keeps a fast, precomputed **View** of your data in sync automatically.
+
+## Platform services
+- [Platform services](services/README.md): Your toiljs backend runs on the **Dacely edge**: a fleet of servers spread around the world that sit close to your users and run your compiled backend (a small, sandboxed WebAssembly program).
+- [Analytics](services/analytics.md): Read your site's own usage numbers (requests, bytes, cache hits, database ops, errors, and more) straight from a route, with no extra code and no third-party service.
+- [Caching](services/caching.md): **Caching lets the edge keep a copy of a response and hand it back instantly, without re-running your code.** You opt in per route, either with the `@cache` decorator or by calling `Response.cache(...)`.
+- [Cookies](services/cookies.md): **Cookies let you store a small piece of state in the user's browser and read it back on the next request.** toiljs ships a complete cookie layer: read incoming cookies, set them on a response, and (optionally) sign or encrypt their values so they cannot be tampered with.
+- [Crypto](services/crypto.md): A small, safe cryptography toolkit (hashing, random bytes, HMAC, symmetric encryption, key derivation, and signatures) available with no import through the ambient `crypto` global.
+- [Email](services/email.md): Send transactional email (verification codes, password resets, receipts) straight from a route handler.
+- [Environment and secrets](services/environment.md): **`Environment` gives your app configuration values and secrets that are set outside your code**, so your compiled backend (`.wasm`) never carries a password or an API key.
+- [Rate limiting](services/ratelimit.md): **Rate limiting caps how often one client can call a route.** You add the `@ratelimit` decorator to a route, and the edge rejects a client that goes over the limit **before your code runs**.
+- [Time](services/time.md): **`Time` is the edge's clock: the blessed way to read the current time in your backend.** It gives you the number of milliseconds or seconds since a fixed reference point, so you can stamp events and compute expiries.
+
+## Concepts and reference
+- [Configuration (`toil.config.ts`)](concepts/config.md): `toil.config.ts` is the one file that configures your whole toiljs app: the client (React/Vite) side and the server (WebAssembly) side.
+- [Decorators reference](concepts/decorators.md): Every feature of a toiljs backend, an HTTP route, an RPC method, a database collection, a scheduled job, is switched on by a **decorator**.
+- [Security](concepts/security.md): Security in toil is not a single feature you switch on.
+- [Compute tiers](concepts/tiers.md): Your toiljs backend runs across four **compute tiers**, from a per-request handler at the very edge (L1) up to a single worldwide coordinator (L4).
+- [The server type system](concepts/types.md): Your backend is TypeScript, but a stricter, faster dialect of it.

package/docs/realtime/README.md

@@ -0,0 +1,102 @@
+# Realtime
+
+Realtime is how your app pushes data to the browser the instant it happens, instead of the browser having to ask again and again. In toiljs you get realtime from two small pieces: a server class marked `@stream`, and a client React hook called `useChannel`.
+
+## What "realtime" means
+
+A normal web request is one round trip. The browser asks ("give me the todos"), the server answers, and the connection closes. If you want fresh data a second later, you have to ask again. That is fine for a page load or a form submit, but it is a poor fit for anything that changes on its own: a live chat, a game, a price ticker, a progress bar, a presence indicator ("3 people online").
+
+Realtime flips it around. The browser opens **one long-lived connection** and keeps it open. After that, either side can send a message at any time, as many times as it likes, with no new handshake. That open connection is often called a **socket**.
+
+## WebTransport in plain words
+
+To hold that long-lived connection open, the browser and the Dacely edge speak a protocol called **WebTransport**.
+
+Here is all you need to know as a beginner:
+
+- WebTransport is a modern, built-in browser feature (like `fetch`, but for a persistent two-way connection).
+- It runs on top of **HTTP/3** and **QUIC**, which are the newest, fastest versions of the web's plumbing. They are built for low latency (messages arrive quickly) and for surviving network changes (your phone switching from Wi-Fi to cellular without dropping the connection).
+- You do not write any WebTransport code by hand. toiljs gives you a tiny client API, and it uses WebTransport underneath on the production edge.
+
+One helpful detail for later: in local development (`toiljs dev`) the same client API runs over a **WebSocket** instead, because a WebSocket is simpler to serve from one local process. A WebSocket is the older, widely supported "keep a socket open" browser feature. The point is that **your code is identical** in dev and in production; only the transport underneath differs, and toiljs picks it for you.
+
+## When to use realtime (and when not to)
+
+Reach for realtime when **the server needs to talk first**, or when messages fly back and forth quickly:
+
+| Use realtime when...                          | Use a plain HTTP request when...                 |
+| --------------------------------------------- | ------------------------------------------------ |
+| A chat or comment thread updates live.        | You load a page or a list once.                  |
+| A multiplayer game syncs moves and positions. | You submit a form and get one answer.            |
+| You show live presence or typing indicators.  | You fetch data on a button click.                |
+| You stream progress of a long job.            | The data rarely changes, or the user pulls it.   |
+
+**Games are a first-class use case, not an afterthought.** Realtime multiplayer (player moves, low-latency input, live presence, per-player state) is one of the hardest things to build on the plain web, and it is exactly what toil streaming is designed for. More on why, and how far it is built to scale, in [Built for massive fan-out and world-wide sync](#built-for-massive-fan-out-and-world-wide-sync) below.
+
+If a single request-and-response does the job, prefer that: it is simpler, it caches well, and it needs no open connection. Plain requests in toiljs are [HTTP routes](../backend/rest.md) and [typed RPC](../backend/rpc.md). Reach for realtime only when the "ask again and again" model genuinely gets in your way.
+
+## The two pieces
+
+Realtime in toiljs is always a pair:
+
+1. **The server: a `@stream` class.** You write a small class and mark it `@stream`. The edge turns it into a **resident box**: a live instance that is created when a connection opens, handles every message on that connection, and is torn down when it closes. It has four lifecycle hooks (`@connect`, `@message`, `@close`, `@disconnect`). See [Streams](./streams.md).
+
+2. **The client: a hook.** From your React UI you open the connection and send or receive messages. The low-level way is the `useChannel` hook; the typed, generated way is `Server.Stream.<ClassName>.connect()`. See [Channels](./channels.md).
+
+```mermaid
+sequenceDiagram
+    participant B as Browser (React)
+    participant E as Dacely edge
+    participant S as Your @stream box
+    B->>E: open connection (WebTransport, or WebSocket in dev)
+    E->>S: create the box, run @connect
+    Note over S: the box is now resident for this connection
+    B->>E: send "hello"
+    E->>S: @message("hello")
+    S-->>B: reply "hi back"
+    B->>E: send "still here"
+    E->>S: @message("still here")
+    S-->>B: reply "yep"
+    B->>E: close
+    E->>S: run @close, then destroy the box
+```
+
+Notice that the box lives across **many** messages in that diagram. That is the whole idea: because it is the same instance every time, it can remember things between messages (a counter, who you are, what room you joined). A normal HTTP handler forgets everything after each request; a stream box does not, for as long as the connection stays open.
+
+## Built for massive fan-out and world-wide sync
+
+Realtime gets exciting when a single event reaches **many** people at nearly the same moment. Picture a live sports app: a goal is scored, and every fan watching sees it light up together. Picture a multiplayer game: one player moves, and everyone in the match sees it happen right away. That shape, one event fanning out to a huge live audience, is what toil streaming is built for. We call it **world-wide packet sync**: everyone in the same live session gets the same update at nearly the same time, wherever they are on the planet.
+
+```mermaid
+flowchart TB
+    P["One event<br/>(a goal, a chat line, a game move)"] --> E["Dacely edge<br/>(spread across cores and cities)"]
+    E --> S1["Player in Tokyo"]
+    E --> S2["Player in Paris"]
+    E --> S3["Player in Sao Paulo"]
+    E --> Sn["...many more, at once"]
+```
+
+### Why it can go so wide
+
+Three design choices make massive scale possible, without any single machine or single lock becoming the ceiling.
+
+1. **Connections spread across the fleet in parallel.** Every new connection is handled on its own, with no shared lock in the middle for connections to fight over. There is no central bottleneck that every connection has to pass through, so adding machines adds capacity in a straight line.
+2. **The session follows the user.** A phone that switches from Wi-Fi to cellular keeps its exact session, in-memory game state and all. A network change does not drop the connection or reset the box.
+3. **The session sits near the user.** The edge is a fleet of servers in many cities. A `@stream` runs at a regional or continental node (see [Compute tiers](../concepts/tiers.md)), so the round trip to a player stays short no matter where on the map they are.
+
+### An honest word on numbers
+
+The framework is **designed** for very large live audiences, aiming at the scale of millions of concurrent connections in a single live session as its ambition. That is the target the architecture is built toward, not a number measured in these docs. Real capacity depends entirely on your deployment: how many machines and cores you run, how big each message is, how often it is sent, and where your users are. We do not publish a benchmarked figure here. What we can say honestly is **why** it scales (the three design choices above), and that the design removes the usual single-machine and single-lock ceilings that cap other realtime stacks.
+
+One more honest note. Fanning a single message out to **other** users' connections (true one-to-many broadcast, the arrows in the diagram above) is the job of `@channel`. The client side of that (`useChannel`, `Server.Stream`) is live today. The server-side broadcast that reaches every subscriber across the mesh is **planned, not shipped yet**. See [Channels](./channels.md) for exactly what works now and what is coming, so you can build on solid ground.
+
+## Where to go next
+
+- [Streams](./streams.md): the server side. How to declare a `@stream` class, the four lifecycle hooks, per-connection state, replying, and the separate `main.stream.ts` file.
+- [Channels](./channels.md): the client side. The `useChannel` React hook, the generated typed client, and a chat-style example. Also covers the planned `@channel` broadcast feature.
+
+## Related
+
+- [Compute tiers (L1 to L4)](../concepts/tiers.md): where a stream box runs on the edge.
+- [HTTP routes (`@rest`)](../backend/rest.md) and [Typed RPC](../backend/rpc.md): the plain request-and-response alternatives.
+- [Daemons](../background/daemons.md): long-lived background work that is not tied to a browser connection.

package/docs/realtime/channels.md

@@ -0,0 +1,211 @@
+# Channels (`useChannel`)
+
+`useChannel` is the client-side React hook for realtime. It opens a live connection from the browser to a server `@stream` box, tracks whether it is connected, collects the messages that arrive, and gives you a `send` function. It reconnects on its own if the connection drops.
+
+## What a channel is
+
+A **channel** is simply an open, two-way connection between one browser and the server, viewed from the client's side. On the server that connection is handled by a [`@stream`](./streams.md) box. On the client you hold the other end with `useChannel` (a React hook) or `connectChannel` (a plain function, no React).
+
+You have already met the two-piece model in the [realtime overview](./README.md): a `@stream` on the server, a channel on the client. This page is the client half.
+
+## The `useChannel` hook
+
+`useChannel` is available on the global `Toil` object in your route files, so no import is needed:
+
+```tsx
+export default function Ping() {
+    const chan = Toil.useChannel({ path: '/echo' });
+
+    return (
+        <main>
+            <p>Status: <strong>{chan.connected ? 'connected' : 'offline'}</strong></p>
+            <button type="button" onClick={() => chan.send('ping')}>Send ping</button>
+            <ul>
+                {chan.messages.map((m, i) => (
+                    <li key={i}><code>{typeof m === 'string' ? m : '(binary frame)'}</code></li>
+                ))}
+            </ul>
+        </main>
+    );
+}
+```
+
+### What it returns
+
+`useChannel(options?)` returns an object with three things:
+
+| Field       | Type                       | What it is                                                              |
+| ----------- | -------------------------- | ---------------------------------------------------------------------- |
+| `connected` | `boolean`                  | `true` while the socket is open. Re-renders when it changes.           |
+| `messages`  | `(string \| ArrayBuffer)[]`| every frame received so far, in order. A new frame re-renders.         |
+| `send`      | `(data) => void`           | send one frame to the server (a no-op until the socket is open).       |
+
+A frame is either a **string** (text) or an **`ArrayBuffer`** (binary). Send accepts a string or binary data. To send or read structured data, encode and decode it yourself:
+
+```ts
+chan.send(new TextEncoder().encode('hello'));           // send bytes
+const text = (m: string | ArrayBuffer) =>
+    typeof m === 'string' ? m : new TextDecoder().decode(m); // read either kind as text
+```
+
+### Options
+
+```ts
+Toil.useChannel({
+    path: '/echo',        // which @stream route to connect to. Default: '/_toil'
+    url: 'wss://...',     // full ws(s):// override (wins over path). Usually omit this.
+    reconnect: true,      // auto-reconnect after an unexpected close. Default: true
+    reconnectDelay: 1000  // ms to wait before each reconnect attempt. Default: 1000
+});
+```
+
+The most important option is **`path`**: it points the channel at a specific `@stream` route. `{ path: '/echo' }` connects to a stream mounted with `@stream('echo')`. If you omit `path`, it connects to the default `/_toil` channel.
+
+You do not build the `ws://` or `wss://` URL yourself. The hook derives it from the current page (a page served over `https` uses `wss`, otherwise `ws`), and on the production edge the transport is upgraded to WebTransport for you. Your code stays the same.
+
+### Lifecycle and cleanup
+
+`useChannel` connects when the component mounts and closes when it unmounts, so a channel lives exactly as long as the page that uses it is on screen. React's rules apply: call it at the top level of your component, not inside a loop or condition.
+
+### `connectChannel`: the non-React version
+
+If you need a channel outside a React component (in a plain module, a store, an event handler), use `connectChannel`. It takes a callback for each incoming frame and returns a handle:
+
+```ts
+import { connectChannel } from 'toiljs/client';
+
+const chan = connectChannel(
+    (frame) => console.log('got', frame),
+    { path: '/echo' }
+);
+chan.send('hello');
+chan.close(); // stop and stop reconnecting
+```
+
+`useChannel` is `connectChannel` wrapped for React (it manages the `connected` / `messages` state for you).
+
+## The typed client: `Server.Stream`
+
+`useChannel` deals in raw frames. For a typed experience, toiljs also generates a client per `@stream` class at `Server.Stream.<ClassName>`, described in full on the [Streams](./streams.md#reaching-a-stream-from-the-browser) page. Use whichever fits: `useChannel` for a quick reactive hook, `Server.Stream.<Name>.connect()` for typed messages and explicit `onMessage` / `onClose` callbacks. Both open the same kind of connection to the same box.
+
+## A full chat-style example
+
+Here is a chat UI wired end to end: a React page that sends what you type and shows every reply, plus the server box it talks to.
+
+### Client (`client/routes/chat.tsx`)
+
+```tsx
+import { useState } from 'react';
+
+export default function Chat() {
+    const chan = Toil.useChannel({ path: '/room' });
+    const [draft, setDraft] = useState('');
+
+    const asText = (m: string | ArrayBuffer): string =>
+        typeof m === 'string' ? m : new TextDecoder().decode(m);
+
+    function submit(): void {
+        if (draft.length === 0) return;
+        chan.send(draft);   // one send() becomes one @message on the server
+        setDraft('');
+    }
+
+    return (
+        <main>
+            <h1>Chat</h1>
+            <p>Status: <strong>{chan.connected ? 'connected' : 'offline'}</strong></p>
+            <ul>
+                {chan.messages.map((m, i) => <li key={i}>{asText(m)}</li>)}
+            </ul>
+            <input
+                value={draft}
+                onChange={(e) => setDraft(e.target.value)}
+                onKeyDown={(e) => { if (e.key === 'Enter') submit(); }}
+                placeholder="Say something"
+            />
+            <button type="button" onClick={submit}>Send</button>
+        </main>
+    );
+}
+```
+
+### Server (`server/streams/Room.ts`)
+
+```ts
+@stream('room')
+class Room {
+    private seen: i32 = 0;
+
+    @connect
+    onConnect(): void {
+        this.seen = 0;
+    }
+
+    @message
+    onMessage(packet: StreamPacket): StreamOutbound {
+        this.seen = this.seen + 1;
+        const text = new TextDecoder().decode(packet.bytes());
+        const reply = '#' + this.seen.toString() + ': ' + text;
+        return StreamOutbound.reply(Uint8Array.wrap(String.UTF8.encode(reply)));
+    }
+}
+```
+
+Do not forget to import the stream in `server/main.stream.ts` (see [Streams](./streams.md#the-mainstreamts-file-a-separate-tier)):
+
+```ts
+import './streams/Room';
+```
+
+Run `toiljs dev`, open the page, and every line you send comes back numbered, live.
+
+### An honest limitation: this echoes, it does not broadcast
+
+Read the example carefully. Each browser has its **own** `Room` box, and that box replies only to **its own** connection. So in this version, two people in "the same room" do **not** see each other's messages: each just sees their own, echoed back. That is enough for a private assistant, a progress feed, or a single-player game, but it is **not** a shared chat room where one message reaches everyone.
+
+To send one message to **many** connected users (true broadcast, the heart of a group chat or a live feed), you need the server to **fan out** a message to every subscriber. That is what `@channel` is for.
+
+## `@channel`: server broadcast (not yet available)
+
+> **Status: planned, not live in the current runtime.** A `@stream` class that declares a `@channel` hook is **rejected** by the edge today ("stream channels are not a v1 runtime ABI"), and the compiler does not yet emit it. The information below describes the intended shape so you can plan for it, not an API you can call right now.
+
+The idea is **publish/subscribe** ("pub/sub"), a standard pattern for broadcast:
+
+- A **channel** is a named topic, for example a chat room id.
+- A connection **subscribes** to a channel to start receiving everything sent to it.
+- Anyone can **publish** a message to the channel, and every subscriber receives it.
+- A connection **unsubscribes** (or disconnects) to stop.
+
+With `@channel`, the server box would join a connection to a named topic and publish messages to it, and the edge would deliver each published message to every subscriber across all the connections in that topic, no matter which worker or node each one landed on. That is the missing "one to many" piece that turns the echo example above into a real shared room. The plan already reserves per-plan limits for it (a cap on subscribers per channel and on message size), so the surface is designed; it is the runtime delivery that is not shipped yet.
+
+### The picture: world-wide sync (the design)
+
+When `@channel` ships, one `publish` will fan out across the whole edge mesh, reaching every subscriber wherever they are, at nearly the same moment. That is the **world-wide sync** idea: a live session where everyone sees the same update together, whether they are in the same city or on opposite sides of the planet.
+
+```mermaid
+flowchart TB
+    Pub["One publish()<br/>(a chat line, a goal, a game tick)"] --> Mesh["Dacely edge mesh<br/>(routes to every subscriber's core)"]
+    Mesh --> A["Subscriber in Tokyo"]
+    Mesh --> B["Subscriber in Paris"]
+    Mesh --> C["Subscriber in New York"]
+    Mesh --> D["...every other subscriber, at once"]
+```
+
+The mechanism meant to make this fast is the same one that already spreads plain connections across the edge: because the edge always knows where each subscriber's connection lives, a broadcast is a direct fan-out to a known set of destinations, not a search for who is listening. For the wider picture, see [Built for massive fan-out and world-wide sync](./README.md#built-for-massive-fan-out-and-world-wide-sync) in the overview.
+
+Keep the status in mind: the diagram above is the **intended shape**. The delivery runtime is not shipped yet, so treat it as the plan, not an API you can call today.
+
+**What you can build today:** anything where each user talks to their own box (assistants, per-user live updates, single-player sync, progress streams). **What needs `@channel`:** shared rooms and one-to-many broadcast. Until it ships, a common workaround is to persist messages to [the database](../database/README.md) and have clients poll or re-read, which is simpler but not instant.
+
+## Gotchas
+
+- **Frames are `string` or `ArrayBuffer`.** Decode binary frames with `TextDecoder`; there is no automatic parsing in `useChannel` (the typed `Server.Stream` client is the structured option).
+- **`send` before "connected" is dropped.** It is a no-op until the socket is open. Guard on `chan.connected`, or expect the first eager sends to be lost.
+- **`messages` grows forever.** It keeps every frame received. For a long-lived page, slice it or keep your own bounded list.
+- **One box per connection.** `useChannel` does not broadcast between users; that is the `@channel` feature described above.
+
+## Related
+
+- [Realtime overview](./README.md): the two-piece model and when to use realtime.
+- [Streams](./streams.md): the server `@stream` class this hook talks to.
+- [The database (ToilDB)](../database/README.md): where to persist messages that must outlive a connection or reach users who are offline.