toiljs 0.0.59 → 0.0.61

package/build/devserver/wasm/surface.js

@@ -0,0 +1,41 @@
+import { DataReader } from 'toiljs/io';
+import { customSection } from './sections.js';
+export function parseSurface(wasm) {
+    let sec;
+    try {
+        sec = customSection(wasm, 'toil.surface');
+    }
+    catch {
+        return 'invalid';
+    }
+    if (sec === null)
+        return 'absent';
+    const r = new DataReader(sec);
+    r.readU16();
+    const targetMode = r.readU8() === 1 ? 'cold' : 'hot';
+    r.readU8();
+    const f = r.readU32();
+    const abiVersion = r.readU16();
+    const buildId = r.readString();
+    const fingerprint = r.readU32();
+    const dataCoherenceHash = r.readU32();
+    const pairCoherenceHash = r.readU32();
+    if (!r.ok)
+        return 'invalid';
+    return {
+        targetMode,
+        flags: {
+            rest: !!(f & 1),
+            stream: !!(f & 2),
+            daemon: !!(f & 4),
+            scheduled: !!(f & 8),
+            database: !!(f & 16),
+            render: !!(f & 32),
+        },
+        abiVersion,
+        buildId,
+        fingerprint,
+        dataCoherenceHash,
+        pairCoherenceHash,
+    };
+}

package/docs/README.md

@@ -34,7 +34,7 @@ and as a named export from `toiljs/server/runtime`.
   type, `AuthService` (post-quantum login, signed sessions, `getUser()`), and
   the client half.
 - [Environment variables & secrets](./environment.md): `Environment.get` /
-  `getSecure` — per-tenant config + secrets set out of band (GitHub-Actions
+  `getSecure`, per-tenant config + secrets set out of band (GitHub-Actions
   style), so the `.wasm` carries no credentials. Two disjoint buckets, read-only.
 - [Email](./email.md): `EmailService`, `EmailTemplate`, the `emails/` React
   template pipeline, the stateless `TwoFactor` codes, provider config
@@ -52,14 +52,14 @@ and as a named export from `toiljs/server/runtime`.
 
 ## Conventions
 
-- **"Global, no import"** — a symbol marked `@global` in the runtime is in scope
+- **"Global, no import"**, a symbol marked `@global` in the runtime is in scope
   everywhere in a tenant without an `import`, exactly like `crypto`. The
   matching named export exists so editors resolve the type and so the module is
   pulled into every build. Either form works.
-- **Binary, not JSON, on the hot paths** — request/response bodies, sessions,
+- **Binary, not JSON, on the hot paths**, request/response bodies, sessions,
   and cookies use the deterministic `DataWriter`/`DataReader` codec. JSON is
   available for `@rest` routes but binary is the default for anything
   performance- or security-sensitive.
-- **One fresh instance per request** — guest memory is wiped between requests,
+- **One fresh instance per request**, guest memory is wiped between requests,
   so nothing persists in module globals across requests. Use a host-backed store
   for anything that must outlive a single request.

package/docs/auth-todo.md

@@ -24,7 +24,7 @@ imports in `toil-backend` (`crypto.mlkem_decapsulate`, `crypto.voprf_evaluate`),
 
 ---
 
-## Tier 1 — blocks production (cannot run on the edge yet)
+## Tier 1, blocks production (cannot run on the edge yet)
 
 ### 1.1 Storage on toildb (THE blocker) -- "when building toildb, consider this"
 The accounts + login challenges live in the **DEV-ONLY** `kv.*` Map
@@ -72,17 +72,17 @@ in-prod `mldsa_verify` import). Do before trusting in prod.
 
 ---
 
-## Tier 2 — protocol hardening
+## Tier 2, protocol hardening
 
-### 2.6 A properly bound session key — DONE (on main, unreleased)
+### 2.6 A properly bound session key, DONE (on main, unreleased)
 The session key is now `K = HMAC-SHA256(sharedSecret, SESSION_KEY_LABEL || H(M))` and the
 mutual-auth tag is `HMAC-SHA256(K, SERVER_CONFIRM_LABEL || H(M))` (`AuthService.deriveSessionKey`
 + `serverConfirmTag`; client mirrors it with hash-wasm `createHMAC`). REMAINING: binding the
 *session cookie* to the transport (so a stolen cookie is useless on another channel) needs
-the TLS exporter, which the wasm guest cannot see — an edge/transport follow-up, not doable
+the TLS exporter, which the wasm guest cannot see, an edge/transport follow-up, not doable
 purely in the guest.
 
-### 2.7 Bind the KDF params + server key into the transcript — DONE (on main, unreleased)
+### 2.7 Bind the KDF params + server key into the transcript, DONE (on main, unreleased)
 The single `buildLoginMessage` now binds the ML-KEM ciphertext, the Argon2id params
 (mem/iters/par), and `serverKemKeyId = SHA-256(serverKemPublicKey)`. Closes
 key-substitution and param-downgrade confusion. (There is ONE login message format, no
@@ -96,7 +96,7 @@ a reviewable artifact.
 
 ---
 
-## Tier 3 — account lifecycle (missing today)
+## Tier 3, account lifecycle (missing today)
 
 ### 3.1 Password change / key rotation
 Re-derive under a fresh salt while authenticated, re-register the new public key. None

package/docs/caching.md

@@ -59,14 +59,14 @@ return Response.bytes(blob).cacheFor(5);
 
 The cache layer refuses to store anything unsafe, regardless of the directive:
 
-- **5xx** responses are never cached — a server error is transient, and `@cache`
+- **5xx** responses are never cached, a server error is transient, and `@cache`
   wraps the whole route, so a `@cache`d route that hits a blip returns its 500
   carrying the directive; caching it would serve the failure for the full TTL.
   **2xx, 3xx, and 4xx are cacheable** (a redirect or a `404`/`410` is a
   deterministic function of the request key);
 - a response that sets a **`Set-Cookie`** is never cached;
 - a response to an **authenticated** request is not cached unless you pass
-  `allowAuth = true` — this prevents one user's personalized response from being
+  `allowAuth = true`, this prevents one user's personalized response from being
   served to another;
 - the edge TTL is **clamped to 24 hours**.
 
@@ -75,7 +75,7 @@ an unauthorized request is rejected with 401 before anything is cached, and a
 cached entry is only ever produced from a handler that actually ran.
 
 Caching is **always opt-in.** A response with no `Toil-Cache-Control` directive
-(i.e. no `@cache` / `Response.cache(...)`) is never stored — there is no blind
+(i.e. no `@cache` / `Response.cache(...)`) is never stored, there is no blind
 "cache every GET" mode, because an automatic window cannot tell a personalized
 response from a public one and would key it without a per-user component.
 
@@ -84,11 +84,11 @@ response from a public one and would key it without a per-user component.
 The edge cache is per-core and hard-capped so it can never exhaust node memory.
 It has two tiers:
 
-- **RAM tier** — small, short-TTL responses. Bounded by a per-core byte budget
+- **RAM tier**, small, short-TTL responses. Bounded by a per-core byte budget
   (each core holds at most ~128 MB) plus an entry-count cap; an insert that would
   exceed the budget drops expired entries first, then evicts the soonest-to-expire
   ones. A response over ~256 KB does not go in the RAM tier.
-- **Disk tier (spill)** — when the operator enables `--spill-dir`, a **big**
+- **Disk tier (spill)**, when the operator enables `--spill-dir`, a **big**
   (over the ~256 KB RAM cap) or **long-TTL** (≥ 10 min) cacheable response is
   written to disk instead and served back zero-RAM via a memory map, the same way
   static files are served. This keeps the RAM tier for the hot working set while

package/docs/cli.md

@@ -0,0 +1,15 @@
+# CLI
+
+- `toiljs create [name]`, scaffold a project. Flags: `--template app|minimal`,
+  `--style css|sass|less|stylus`, `--tailwind`, `--no-ai`, `-y`/`--yes`.
+- `toiljs dev`, dev server with HMR (`--port`, `--root`). With a `toilconfig.json` it builds
+  the server first, then rebuilds it whenever a `server/` file changes (regenerating
+  `shared/server.ts`, which Vite HMRs into the client); client-only edits just HMR the client.
+- `toiljs build`, production build. With a `toilconfig.json` it builds the server (toilscript,
+  regenerating `shared/server.ts`) first, then the client → `build/client`. `--server` builds
+  only the server. Every `server/` file declaring a surface (`@data`/`@rest`/...) is compiled.
+- `toiljs start`, self-host the built app (hyper-express) with a `/_toil` WebSocket channel.
+- `toiljs configure`, toggle styling features on an existing project (see [styling.md](./styling.md)).
+- `toiljs doctor`, diagnose project setup (`--json` for CI). `--fix` auto-wires the typed-RPC
+  setup (build scripts, tsconfig `shared` + alias, `.gitignore`, toilscript version, and the
+  toilscript prettier plugin) so an existing project upgrades in one command.

package/docs/client.md

@@ -0,0 +1,40 @@
+# Client runtime
+
+Everything is on the `Toil` global, no imports needed in route files.
+
+## Entry
+
+`client/toil.tsx` imports the route table + global styles and mounts the app:
+
+```tsx
+import { routes, layout, notFound } from "toiljs/routes";
+import "./styles/main.css";
+Toil.mount(routes, layout, notFound);
+```
+
+## API (on `Toil`)
+
+- Components: `Link`, `NavLink`, `Head`
+- Navigation: `navigate`, `useRouter`, `useNavigate`
+- Location: `usePathname`, `useSearchParams`, `useParams`, `useNavigationPending`
+- Data: `useLoaderData` (see [routing.md](./routing.md))
+- Head: `useHead`, `useTitle`, `<Head>`, set the `<title>` / meta per route
+- Realtime: `useChannel`, `connectChannel` (WebSocket to the backend at `/_toil`)
+- IO globals (no `Toil.` prefix): `FastMap`, `FastSet`, `DataWriter`, `DataReader`
+- `parseError(err)` global: message from an unknown caught value (handy in `catch`)
+- `Server` global: the typed RPC surface generated from the server (see [server.md](./server.md))
+- `Server.REST.<controller>.<route>(args)`: a working, typed `fetch` client for your
+  `@rest` controllers, e.g. `await Server.REST.todos.getTodo({ params: { id } })` or
+  `await Server.REST.todos.add({ body: new AddTodo("milk") })`. `args` is
+  `{ params?, body?, query?, headers? }`; returns are typed (`@data` classes are parsed for
+  you). The REST client attaches when you import from `shared/server`.
+
+## Head example
+
+```tsx
+Toil.useHead({
+    title: "Blog",
+    titleTemplate: "%s, MyApp",
+    meta: [{ name: "description", content: "..." }],
+});
+```

package/docs/crypto.md

@@ -2,7 +2,7 @@
 
 The guest gets a synchronous Web Crypto surface through the ambient `crypto`
 global, backed by host functions. It mirrors the browser `crypto` /
-`crypto.subtle` API but **without Promises** — ToilScript has no `async`, so
+`crypto.subtle` API but **without Promises**, ToilScript has no `async`, so
 every call returns its result directly. Keys are opaque per-request handles in a
 host keystore; a `CryptoKey` is valid only for the request that created it.
 
@@ -84,7 +84,7 @@ Each algorithm has a small params class you pass to `importKey`/`sign`/etc.:
 - **Key formats:** `FMT_RAW`, `FMT_PKCS8`, `FMT_SPKI` (`FMT_JWK` is rejected).
 - **Usages (bitmask):** `USAGE_ENCRYPT`, `USAGE_DECRYPT`, `USAGE_SIGN`,
   `USAGE_VERIFY`, `USAGE_DERIVE_KEY`, `USAGE_DERIVE_BITS`, `USAGE_WRAP_KEY`,
-  `USAGE_UNWRAP_KEY` — OR them together.
+  `USAGE_UNWRAP_KEY`, OR them together.
 - **Named curves:** `CURVE_P256`, `CURVE_P384` (`CURVE_P521` is not supported).
 
 ### `CryptoKey`
@@ -116,7 +116,7 @@ const ct = crypto.subtle.encrypt(new AesGcmParams(iv, aad, 128), k, plaintext);
 ## Post-quantum verify
 
 The host also exposes ML-DSA-44 (FIPS 204) signature verification as
-`crypto.mldsa_verify`. It is verify-only — the host never holds a secret key — and
+`crypto.mldsa_verify`. It is verify-only, the host never holds a secret key, and
 underpins the [auth primitive](./auth.md). Most code reaches it through
 `AuthService.verifyLogin(publicKey, message, signature)` rather than calling the
 import directly. Public key is 1312 bytes, signature 2420 bytes, with a FIPS 204
@@ -124,7 +124,7 @@ domain-separation context.
 
 ## Limitations
 
-- **No Promises** — every call is synchronous.
+- **No Promises**, every call is synchronous.
 - **No RSA** and **no JWK** key format.
 - **P-521** is not supported (P-256 and P-384 are).
 - Signature *generation* for ML-DSA is client-side only; the server verifies.

package/docs/data.md

@@ -17,13 +17,13 @@ class Player {
 
 From that the compiler synthesizes, on the class:
 
-- `encode(): Uint8Array` / `static decode(buf): T` — the binary codec (with a
+- `encode(): Uint8Array` / `static decode(buf): T`, the binary codec (with a
   4-byte type id prefix).
-- `encodeInto(w: DataWriter)` / `static decodeFrom(r: DataReader)` — the codec
+- `encodeInto(w: DataWriter)` / `static decodeFrom(r: DataReader)`, the codec
   without the type-id frame, for nesting.
-- `toJSON()` / `static fromJSON(v)` — the JSON codec (64-bit-and-larger integers
+- `toJSON()` / `static fromJSON(v)`, the JSON codec (64-bit-and-larger integers
   as decimal strings, so they survive `JSON.parse` exactly).
-- `static dataId(): u32` — a stable FNV-1a hash of the class name, written as the
+- `static dataId(): u32`, a stable FNV-1a hash of the class name, written as the
   type-id prefix by `encode()`.
 
 Fields may be scalars (`u8`..`u256`, `i8`..`i256`, `f32`, `f64`, `bool`),
@@ -47,8 +47,8 @@ public blob(input: FileData): FileResult { /* input.decode, result.encode */ }
 
 ## The binary codec: `DataWriter` / `DataReader`
 
-When you need to lay out bytes yourself — custom bodies, session payloads,
-challenge messages — use the codec directly. It lives in the `data` module:
+When you need to lay out bytes yourself, custom bodies, session payloads,
+challenge messages, use the codec directly. It lives in the `data` module:
 
 ```ts
 import { DataWriter, DataReader } from 'data';

package/docs/email.md

@@ -5,17 +5,17 @@ toiljs can send transactional email from a route handler. A handler calls
 `emails/` folder, or the stateless `TwoFactor` helper); the edge hands the
 message to a single off-core mailer thread that talks to the provider over the
 kernel network (never the worker cores), and **suspends** the wasm call until the
-provider responds — so a slow send never blocks the worker.
+provider responds, so a slow send never blocks the worker.
 
 Everything here is an ambient **global** (no import), like `crypto` and
 `AuthService`. A tenant that never sends email pulls none of it into its build.
 
-- **`EmailService`** — send one email.
-- **`EmailTemplate`** — a reusable template with `{{placeholder}}` substitution
+- **`EmailService`**, send one email.
+- **`EmailTemplate`**, a reusable template with `{{placeholder}}` substitution
   (plain text and/or HTML).
-- **`emails/*.tsx`** — author emails as React components; the build renders them
+- **`emails/*.tsx`**, author emails as React components; the build renders them
   to static HTML and generates a typed `Emails.<Name>.send(...)`.
-- **`TwoFactor`** — stateless email verification codes (2FA / confirm), no DB.
+- **`TwoFactor`**, stateless email verification codes (2FA / confirm), no DB.
 
 > **The one rule of HTML email:** email clients run **no JavaScript** and strip
 > `<style>`/external CSS. So HTML email is a static, inline-styled string, and
@@ -24,7 +24,7 @@ Everything here is an ambient **global** (no import), like `crypto` and
 
 ## Configure email
 
-Email is a **framework-reserved namespace of the tenant's environment** — the
+Email is a **framework-reserved namespace of the tenant's environment**, the
 same out-of-band [Environment](./environment.md) store that backs
 `Environment.get` / `getSecure`, but the `[email]` block is **host-only**: it is
 read and used in Rust (the off-core mailer) and is **never exposed to the
@@ -35,7 +35,7 @@ On the edge today it lives in the tenant's env secrets file,
 `$TOIL_ENV_DIR/<host>.env.secrets` (default dir `/run/toil/env`), kept `0600` and
 **out of `hosts/`** so the config watcher never sees a credential (the dashboard /
 edge DB replaces this file later). Email config is a set of **reserved
-`TOIL_EMAIL_*` keys** — host-only, stripped from the guest buckets, so a tenant
+`TOIL_EMAIL_*` keys**, host-only, stripped from the guest buckets, so a tenant
 can never read them via `Environment.getSecure`:
 
 ```bash
@@ -57,15 +57,15 @@ reserved namespace the framework consumes.
 When `enabled` is `false` (the default) the host has no email capability and
 `EmailService.send` returns `Disabled`. The env is loaded **lazily** (on the
 first send) and the `api_key` is materialized into a zeroizing secret in host
-memory — never written to logs or `/_admin`. A malformed `[email]` block is
+memory, never written to logs or `/_admin`. A malformed `[email]` block is
 treated as "no email" (the host returns `Disabled`); validate config on the
 dashboard before deploying.
 
 ### Providers
 
-**Resend** (`provider = "resend"`) — a JSON API; `api_key` holds the API key.
+**Resend** (`provider = "resend"`), a JSON API; `api_key` holds the API key.
 
-**Gmail** (`TOIL_EMAIL_PROVIDER=gmail`) — SMTP with Gmail defaults:
+**Gmail** (`TOIL_EMAIL_PROVIDER=gmail`), SMTP with Gmail defaults:
 `smtp.gmail.com`, port `587` (STARTTLS), username = `from`. `TOIL_EMAIL_API_KEY`
 holds a Gmail **App Password** (create one at
 <https://myaccount.google.com/apppasswords>; the account needs 2-Step
@@ -78,7 +78,7 @@ TOIL_EMAIL_PROVIDER=gmail
 TOIL_EMAIL_API_KEY=abcd efgh ijkl mnop
 ```
 
-**Generic SMTP** (`TOIL_EMAIL_PROVIDER=smtp`) — any submission server (Outlook,
+**Generic SMTP** (`TOIL_EMAIL_PROVIDER=smtp`), any submission server (Outlook,
 SendGrid/Mailgun SMTP, your own). Requires `TOIL_EMAIL_SMTP_HOST`; port defaults
 to `587` (STARTTLS), or set `465` for implicit TLS. `TOIL_EMAIL_SMTP_USER`
 defaults to `from`.
@@ -95,9 +95,9 @@ TOIL_EMAIL_SMTP_USER=noreply@example.com
 
 ### In dev
 
-`toiljs dev` runs the **full email pipeline** in Node — recipient validation,
+`toiljs dev` runs the **full email pipeline** in Node, recipient validation,
 dedup, and the per-minute / per-day / per-recipient caps all behave exactly like
-the edge — and **really sends** once you configure a provider. Configure it in
+the edge, and **really sends** once you configure a provider. Configure it in
 `toil.config.ts` (non-secret) with the API key in `.env.secrets`:
 
 ```ts
@@ -153,7 +153,7 @@ class Notify {
 
 | Status            | Meaning                                                     | Retry?           |
 | ----------------- | ----------------------------------------------------------- | ---------------- |
-| `Sent`            | Accepted by the provider                                    | —                |
+| `Sent`            | Accepted by the provider                                    |, |
 | `Deduped`         | An identical recent `(recipient, purpose)` was collapsed    | treat as sent    |
 | `Budget`          | The host's per-minute budget is exhausted                   | yes, later       |
 | `TryLater`        | The mailer was saturated / a queue was full                 | yes, back off    |
@@ -193,7 +193,7 @@ const status = welcome.send('alice@example.com', vars, 'welcome');
 - `template.render(vars)` returns the rendered `{ subject, body, html }` without
   sending (useful for preview/testing).
 
-For anything richer than `{{token}}` substitution — real layout, CSS, brand —
+For anything richer than `{{token}}` substitution, real layout, CSS, brand,
 author the email as a React component instead.
 
 ## React email templates
@@ -247,7 +247,7 @@ Authoring notes:
   email name), `export const text` (a plain-text alternative; otherwise derived
   from the HTML), `export const purpose`.
 - **Build-time, field substitution only.** Because the component renders once at
-  build, per-send data is `{{token}}` substitution — a runtime `{items.map(...)}`
+  build, per-send data is `{{token}}` substitution, a runtime `{items.map(...)}`
   or conditional bakes in at build, it does not re-run per recipient. That covers
   transactional / 2FA / confirmation email; dynamic lists need a different
   approach.
@@ -265,7 +265,7 @@ editor. It refreshes live as you edit the template or its CSS.
 ## Email verification codes (`TwoFactor`)
 
 `TwoFactor` is a **stateless** email-code primitive (2FA, email confirmation,
-magic codes) — no database. It emails a random code and returns a signed
+magic codes), no database. It emails a random code and returns a signed
 **token** that commits to the code via HMAC, without putting the code in the
 token (the code is only in the email). Verification recomputes the HMAC from the
 token plus the user-entered code, so a valid `(token, code)` pair can only come
@@ -281,18 +281,18 @@ const challenge = TwoFactor.send('alice@example.com', 'login'); // emails the co
 const ok: bool = TwoFactor.verify(challenge.token, 'alice@example.com', userEntered);
 ```
 
-- **`send(recipient, purpose, ttlSecs = 600, digits = 6)`** — issues a code,
+- **`send(recipient, purpose, ttlSecs = 600, digits = 6)`**, issues a code,
   emails it with a built-in template, returns `{ token, status }`.
-- **`issue(recipient, purpose, ttlSecs, digits)`** — returns `{ code, token }`
+- **`issue(recipient, purpose, ttlSecs, digits)`**, returns `{ code, token }`
   **without** sending, so you can email `code` with your own `EmailTemplate` /
   `Emails.*` for a branded message.
-- **`verify(token, recipient, code)`** — `true` only for a code issued for that
+- **`verify(token, recipient, code)`**, `true` only for a code issued for that
   recipient that hasn't expired. Constant-time compare.
-- **`TwoFactor.setSecret(secret)`** — the HMAC secret for the tokens. Call once
+- **`TwoFactor.setSecret(secret)`**, the HMAC secret for the tokens. Call once
   at startup in `main.ts`; it must be identical on every edge instance and out of
   any client bundle. (This is separate from the provider `api_key`.)
 
-**Limitation:** this gives integrity + expiry but **not single-use** — a valid
+**Limitation:** this gives integrity + expiry but **not single-use**, a valid
 code verifies repeatedly within its TTL, because there is no server state to burn
 it. Keep the TTL short; for true single-use, store a per-recipient
 last-verified-at and reject at or before it.
@@ -302,13 +302,13 @@ last-verified-at and reject at or before it.
 All enforced authoritatively in the single mailer (so the counts are exact across
 all workers):
 
-- **Per-host budget** — two rolling windows, both enforced: a 1-minute cap
+- **Per-host budget**, two rolling windows, both enforced: a 1-minute cap
   (`max_per_min`) and a 24-hour cap (`max_per_day`, `0` = unlimited). Over either
   one → `Budget`. Each host's caps, in-window sends, and reject counts are visible
   per host at `GET /_admin/email`.
-- **Per-recipient cap** — `max_per_recipient_per_hour`. Over it →
+- **Per-recipient cap**, `max_per_recipient_per_hour`. Over it →
   `RecipientCapped`.
-- **Dedup** — identical `(host, recipient, purpose)` within ~30s → `Deduped`.
+- **Dedup**, identical `(host, recipient, purpose)` within ~30s → `Deduped`.
 
 Editing these in the host config takes effect on the next send (no restart).
 
@@ -316,11 +316,11 @@ Editing these in the host config takes effect on the next send (no restart).
 
 `GET /_admin/email` returns process-wide counters by reason (JSON), e.g.
 `submitted`, `sent`, `deduped`, `budget`, `recipient_capped`, `try_later`,
-`bad_recipient`, `provider_error`. It exposes **counts only** — never a
+`bad_recipient`, `provider_error`. It exposes **counts only**, never a
 recipient, code, subject, body, or secret.
 
 ## See also
 
-- [Rate limiting](./ratelimit.md) — protect your routes (including any email
+- [Rate limiting](./ratelimit.md), protect your routes (including any email
   trigger) with `@ratelimit`.
-- [Web Crypto](./crypto.md) — the `crypto` global `TwoFactor` builds on.
+- [Web Crypto](./crypto.md), the `crypto` global `TwoFactor` builds on.

package/docs/environment.md

@@ -2,7 +2,7 @@
 
 `Environment` gives a tenant **per-app environment variables and secrets**, set
 out of band (a dashboard, like GitHub Actions) so the deployed `.wasm` carries
-**no credentials**. It is read-only from app code — there is no `set`; values are
+**no credentials**. It is read-only from app code, there is no `set`; values are
 configured on the deployment side, never from the module.
 
 ```ts
@@ -20,15 +20,15 @@ class Cfg {
 }
 ```
 
-`Environment` is a global — no import needed (like `EmailService` / `AuthService`).
+`Environment` is a global, no import needed (like `EmailService` / `AuthService`).
 
 ## Two disjoint buckets
 
 Just like GitHub Actions' `vars` vs `secrets`:
 
-- **`Environment.get(key)`** reads **plain vars** — non-sensitive config (a public
+- **`Environment.get(key)`** reads **plain vars**, non-sensitive config (a public
   API base URL, a feature flag, a region). Returns the string, or `null`.
-- **`Environment.getSecure(key)`** reads **secrets** — sensitive values (a
+- **`Environment.getSecure(key)`** reads **secrets**, sensitive values (a
   third-party API key). Returns the string, or `null`.
 
 The buckets are **disjoint**: a secret is **never** returned by `get()`, and a
@@ -37,13 +37,13 @@ through a code path that logs the result of a `get()`. Keys are case-sensitive,
 exact-match.
 
 > Secrets you read with `getSecure` are plaintext in your module at runtime
-> (that's the point — you need them to call out). Don't log them, don't put them
+> (that's the point, you need them to call out). Don't log them, don't put them
 > in a response, and don't copy them into a client bundle.
 
 ## What is NOT here
 
-Framework-reserved namespaces (today: **email** provider config) are **host-only**
-— resolved and used in Rust where the framework needs them, and **never exposed to
+Framework-reserved namespaces (today: **email** provider config) are **host-only**,
+resolved and used in Rust where the framework needs them, and **never exposed to
 the `.wasm`**. There is no `Environment.email`; you configure email in the
 `[email]` block of the same env file and the platform uses it for you (see
 [Email](./email.md)). The env imports only ever see your own `vars` / `secrets`.
@@ -53,7 +53,7 @@ the `.wasm`**. There is no `Environment.email`; you configure email in the
 Vars and secrets live in **two separate dotenv (`.env`) files**, so the disjoint
 split is structural and the secrets file can be locked down on its own. On the
 edge they are per host, **out of `hosts/`** (so the config watcher never sees a
-credential) — the dashboard / edge database replaces them later:
+credential), the dashboard / edge database replaces them later:
 
 ```bash
 # $TOIL_ENV_DIR/<host>.env          (default dir /run/toil/env)
@@ -63,7 +63,7 @@ REGION=eu
 # $TOIL_ENV_DIR/<host>.env.secrets  (mode 0600)
 STRIPE_KEY=sk_live_xxx                     # -> Environment.getSecure("STRIPE_KEY")
 
-# host-only email config — reserved TOIL_EMAIL_* keys, NEVER exposed to the .wasm
+# host-only email config, reserved TOIL_EMAIL_* keys, NEVER exposed to the .wasm
 TOIL_EMAIL_ENABLED=true
 TOIL_EMAIL_PROVIDER=resend
 TOIL_EMAIL_FROM=noreply@example.com
@@ -72,7 +72,7 @@ TOIL_EMAIL_API_KEY=re_xxx
 
 Each file is plain dotenv: `KEY=value` per line, `#` comments, optional `export`,
 optional quotes. Keys with the reserved **`TOIL_`** prefix are framework/host-only
-and are stripped from BOTH guest buckets — a tenant can never read them via
+and are stripped from BOTH guest buckets, a tenant can never read them via
 `get`/`getSecure` (see [Email](./email.md) for `TOIL_EMAIL_*`).
 
 On the edge, env is loaded **lazily** (the first time your code reads it) into a

package/docs/index.md

@@ -0,0 +1,26 @@
+# toiljs
+
+A full-stack React framework: a Vite-bundled client SPA with file-based routing, plus a
+toilscript-to-WebAssembly server target.
+
+## Project layout
+
+- `client/`, the app: `routes/` (file-based), `layout.tsx`, `components/`, `styles/`,
+  `public/`, and `toil.tsx` (the entry that calls `Toil.mount`).
+- `server/`, the toilscript → WASM target (`@main` entry), compiled by `toilscript`.
+  `@data`/`@remote`/`@service` here generate the typed client `Server` API (see [server.md](./server.md)).
+- `toil.config.ts`, configuration via `defineConfig` (`toiljs.config.ts` also works).
+- Generated, gitignored, do not edit: `.toil/` (working dir), `toil-env.d.ts` (ambient
+  globals), `toil-routes.d.ts` (typed routes), `shared/server.ts` (the typed RPC module,
+  emitted by the server build; import `@data` classes from `shared/server`).
+
+## Key ideas
+
+- `Toil` is a native global (no import): `Toil.Link`, `Toil.useRouter`, `Toil.useLoaderData`,
+  etc. The IO classes (`FastMap`, `FastSet`, `DataWriter`, `DataReader`), `parseError`, and the
+  generated `Server` RPC surface are globals too.
+- Scripts: `npm run dev` (HMR), `npm run build` (→ `build/client` + `build/server`),
+  `npm start` (self-host the build).
+
+See [routing.md](./routing.md), [client.md](./client.md), [styling.md](./styling.md),
+[server.md](./server.md), [ssr.md](./ssr.md), [cli.md](./cli.md).

package/docs/ratelimit.md

@@ -1,6 +1,6 @@
 # Rate limiting
 
-The `@ratelimit` decorator throttles **any** `@rest` route — a login, a signup, a
+The `@ratelimit` decorator throttles **any** `@rest` route, a login, a signup, a
 public API, an email trigger, anything. It is enforced at the edge, before your
 handler runs, and keyed by default on the connecting client's **unspoofable** IP,
 so it works as an abuse / brute-force control out of the box.
@@ -28,9 +28,9 @@ class Auth {
 
 `@ratelimit(strategy, limit, window)`:
 
-- **`strategy`** — a `RateLimit` value (ambient global, no import):
+- **`strategy`**, a `RateLimit` value (ambient global, no import):
   `RateLimit.FixedWindow`, `RateLimit.SlidingWindow`, or `RateLimit.TokenBucket`.
-- **`limit`** and **`window`** — integer literals whose meaning depends on the
+- **`limit`** and **`window`**, integer literals whose meaning depends on the
   strategy (see below).
 
 When a request is over the limit the edge returns **`429 Too Many Requests`**
@@ -39,7 +39,7 @@ guard runs **before `@auth`**, so unauthenticated floods are limited too.
 
 > Both arguments must be **integer literals** and the strategy a `RateLimit`
 > member (or a bare integer tag). A malformed decorator emits no guard rather
-> than miscompiling — the same fail-safe rule as `@cache`.
+> than miscompiling, the same fail-safe rule as `@cache`.
 
 ## Strategies
 
@@ -64,17 +64,17 @@ Examples:
 
 ## How requests are keyed
 
-By default the limiter keys on the **client IP** — specifically the TCP peer
+By default the limiter keys on the **client IP**, specifically the TCP peer
 address the edge observed (`ctx.clientIp()`), **not** a header like
 `X-Forwarded-For`, which a client can forge. That makes it a real abuse control:
 a caller can't reset their bucket by spoofing a header.
 
 The count is **exact across all 14 edge workers** (a given IP always maps to one
 authoritative shard), so the limit is global per route, not per worker. Only
-routes that opt in with `@ratelimit` ever pay anything — the lock-free fast path
+routes that opt in with `@ratelimit` ever pay anything, the lock-free fast path
 for everything else is untouched.
 
-> Each rate-limited route has its own independent limiter — a limit on `/login`
+> Each rate-limited route has its own independent limiter, a limit on `/login`
 > does not consume the budget of `/signup`.
 
 ## Notes and limits
@@ -82,14 +82,14 @@ for everything else is untouched.
 - **Route-level only.** Put `@ratelimit` on each route you want limited; there is
   no controller-wide form yet (unlike `@auth`).
 - **Keyed on IP.** The decorator keys on the peer IP today. (A per-user / custom
-  key — limiting by account instead of IP — exists in the runtime but is not yet
+  key, limiting by account instead of IP, exists in the runtime but is not yet
   exposed through the decorator.)
 - **In dev.** `toiljs dev` runs a single-process mirror of the same three
   strategies, so a limited route behaves the same locally as on the edge.
 
 ## See also
 
-- [Email](./email.md) — `@ratelimit` pairs well with email triggers (verification
+- [Email](./email.md), `@ratelimit` pairs well with email triggers (verification
   codes, password resets) to blunt abuse.
-- [Auth, sessions, and `@user`](./auth.md) — `@ratelimit` runs before the `@auth`
+- [Auth, sessions, and `@user`](./auth.md), `@ratelimit` runs before the `@auth`
   guard, so it protects the login itself.

package/docs/routing.md

@@ -134,11 +134,11 @@ serialized.
 
 Each route is either **JSON** (default) or **Binary**:
 
-- **JSON** — the body is `JSON.parse`d and revived via the `@data` type's
+- **JSON**, the body is `JSON.parse`d and revived via the `@data` type's
   `fromJSON`; the response is the type's `toJSON()`. 64-bit-and-larger integers
   cross the wire as decimal strings (exact at any size). Best for endpoints a
   browser or third party calls directly.
-- **Binary** — the body is `Body.decode(bytes)` and the response is
+- **Binary**, the body is `Body.decode(bytes)` and the response is
   `value.encode()`, using the deterministic `DataWriter`/`DataReader` codec. No
   precision loss, smaller, faster. Best for app-to-app and anything
   security-sensitive.