toiljs 0.0.85 → 0.0.87

package/docs/database/views.md

@@ -0,0 +1,246 @@
+# Views (materialized views)
+
+A `View` collection is a **precomputed, read-optimized result** that you publish
+once and read many times. Reads are a single cheap keyed lookup, no scanning, no
+recomputing.
+
+## What and why
+
+A "materialized view" is a fancy name for a simple idea: instead of computing an
+answer every time someone asks, you compute it **once**, store the finished
+answer, and just hand it out on each request. "Materialized" means the result is
+made real and saved (as opposed to computed on the fly). "View" means it is a
+read-friendly projection of your underlying data.
+
+Think of a leaderboard. Computing "the top 10 players by score" means scanning
+every player and sorting. You do not want to do that on every page load. So you
+compute it in the background, save the finished top-10 list as a view, and every
+page load just reads that saved list. Fast, cheap, and it does not get slower as
+you add players.
+
+Use a `View` when:
+
+- A page needs a result that is **expensive to compute** (a scan, a sort, a fold
+  over many rows).
+- That result is **read far more often than it changes** (a home page, a feed, a
+  leaderboard, a "latest N" list, a rendered summary).
+
+The rule of thumb: if a route wants "the newest N of something" or "the top N of
+something", that is a scan, and scans are barred on the request path. A `View`
+is how you serve that result without scanning per request.
+
+```mermaid
+flowchart LR
+  subgraph off["Off the request path (@derive)"]
+    S[("Source data<br/>events / counters / records")] --> D["@derive: scan + compute"]
+    D --> P["publish(key, result)"]
+  end
+  P --> V[("View")]
+  subgraph on["On the request path (@get)"]
+    G["view.get(key)"] --> V
+  end
+```
+
+## The type
+
+A `View` has two type parameters: the **key** (which view) and the **value**
+(the precomputed result).
+
+```ts
+View<K, V>
+```
+
+- `K` is the key type: it picks *which* view to read or publish. For a single
+  global leaderboard, the key can be a fixed constant like `'main'`.
+- `V` is the value type: the finished result you serve. Both are
+  [`@data`](../concepts/types.md) classes.
+
+Declare it as a `@collection` field inside a `@database` class, alongside the
+sources it is built from:
+
+```ts
+@database
+class BoardDb {
+  @collection static scores: Events<GameKey, ScoreEvent>;  // a source
+  @collection static board: View<GameKey, Leaderboard>;    // the view
+}
+```
+
+## Operations
+
+A `View` has exactly two operations you use directly (plus `require`, a
+convenience wrapper). Exact signatures:
+
+| Operation | Signature | What it does |
+| --- | --- | --- |
+| `get` | `get(key: K): V \| null` | Read the published view, or `null` if nothing has been published yet. |
+| `require` | `require(key: K): V` | Like `get`, but traps (aborts the request) if nothing is published. |
+| `publish` | `publish(key: K, value: V): void` | Overwrite the view for `key` with a fresh result. |
+
+### `get`
+
+A plain keyed read. It is cheap and is allowed from **any** handler, including a
+read-only `@get` route.
+
+```ts
+const board = BoardDb.board.get(new GameKey('main'));
+if (board == null) {
+  // Nothing published yet (e.g. brand-new game). Serve an empty default.
+  return new Leaderboard();
+}
+return board;
+```
+
+Always handle the `null` case: until a `@derive` (or `@job`) has published at
+least once, `get` returns `null`.
+
+### `publish`
+
+Overwrites the stored view with a new value. This is how the view gets its
+content.
+
+```ts
+BoardDb.board.publish(new GameKey('main'), freshBoard);
+```
+
+`publish` is **restricted**: you may only call it from a
+[`@derive`](../background/derive.md) or a `@job` (a background task), never from a
+request handler (`@get`/`@post`/...). The compiler enforces this, and so does the
+edge at runtime. The reason: a view is meant to be maintained off the request
+path from the source of truth, not written ad hoc by whichever request happens to
+run.
+
+### How `publish` differs from a Documents write
+
+A `View`'s `publish` looks like writing a value, but it is not the same as a
+[Documents](./documents.md) `patch`/`create`. The differences matter:
+
+| | `Documents` write (`create` / `patch`) | `View` `publish` |
+| --- | --- | --- |
+| Who may call it | Any action handler (`@post`, ...) | Only a `@derive` or `@job` |
+| Meaning | The record IS the source of truth | The view is a **copy** derived from a source |
+| Version control | You may version-check (optimistic concurrency) | The host assigns the version; a later publish always wins (last writer wins) |
+| Read path | Standard keyed read | A read-optimized fast path (views are heavily read) |
+| Who owns correctness | You (each writer edits the true value) | The derive (it recomputes from the source, so the view always converges) |
+
+In short: a Document is the truth; a View is a saved snapshot of a computation
+over the truth. If the view is ever wrong or stale, the derive just recomputes and
+republishes it. You never hand-edit a view from a route.
+
+## Automatic maintenance with `@derive`
+
+You rarely call `publish` by hand. The normal pattern is a
+[`@derive`](../background/derive.md): a method on your `@database` class that
+reads the sources, builds the value, and publishes it. The runtime runs it for
+you:
+
+- **Right after a write to a source.** When a request writes one of the
+  database's source collections (an `append`, a `counter.add`, a record write),
+  the database's derives run right after the response is produced. So the view
+  reflects the new data on the next read.
+- **On box load.** When the server starts or reloads, the views are rebuilt from
+  their sources before the first read is served.
+
+You never call a derive yourself, and a derive's own `publish` never re-triggers
+it. See [`@derive`](../background/derive.md) for the full rules.
+
+## Worked example: a leaderboard
+
+A game appends score events; a derive folds them into a top-10 list; a route
+serves that list with a single `get`.
+
+```ts
+import { ScoreEvent } from '../models/ScoreEvent';
+import { Leaderboard } from '../models/Leaderboard';
+import { GameKey } from '../models/GameKey';
+import { NewScore } from '../models/NewScore';
+
+@database
+class BoardDb {
+  // The source of truth: every score, appended as it happens.
+  @collection static scores: Events<GameKey, ScoreEvent>;
+  // The materialized view: the current top entries, ready to serve.
+  @collection static board: View<GameKey, Leaderboard>;
+
+  // Off the request path: scan the recent scores, sort, publish the top 10.
+  @derive
+  rebuild(): void {
+    const key = new GameKey('main');
+    const recent = BoardDb.scores.latest(key, 500); // a scan, allowed in a derive
+    const board = new Leaderboard();
+    board.entries = topTen(recent);                 // your own sort/aggregate
+    BoardDb.board.publish(key, board);
+  }
+}
+
+@rest('leaderboard')
+class LeaderboardRoutes {
+  // GET reads the precomputed view: one keyed read, no scan.
+  @get('/')
+  public top(): Leaderboard {
+    const board = BoardDb.board.get(new GameKey('main'));
+    return board == null ? new Leaderboard() : board;
+  }
+
+  // POST records a score. The @derive rebuilds `board` right after.
+  @post('/')
+  public submit(input: NewScore): Leaderboard {
+    BoardDb.scores.append(new GameKey('main'), new ScoreEvent(input.player, input.score));
+    return new Leaderboard(); // ack; the GET serves the updated board from the view
+  }
+}
+```
+
+The models:
+
+```ts
+@data
+export class ScoreEvent {
+  player: string = '';
+  score: u64 = 0;
+}
+
+@data
+export class Leaderboard {
+  entries: ScoreEvent[] = [];
+}
+```
+
+A "latest N" view is the same shape: the derive calls `latest(key, N)` and
+publishes the list. See the [Events](./events.md) page for that variant end to
+end.
+
+## Consistency
+
+- **Last writer wins.** The host assigns each `publish` a version, and a later
+  publish always supersedes an earlier one. Because a derive recomputes the whole
+  view from the source of truth, the view converges to a correct snapshot; you do
+  not need to coordinate concurrent publishes.
+- **A view can be briefly stale.** ToilDB is worldwide, and a view is published
+  at its home then copied to other regions in the background (asynchronous
+  replication). A read from a far region can lag the newest publish by a moment.
+  This is usually fine for the things views hold (feeds, leaderboards, summaries):
+  a leaderboard that is a second behind is still a good leaderboard.
+- **`get` returns `null` until the first publish.** Always default the empty case.
+
+## Gotchas
+
+- **`publish` is derive/job only.** You cannot publish from a route. If you need
+  to update a view in response to a request, write the *source* (append an event,
+  add to a counter) from the action and let the `@derive` republish.
+- **Handle `null` from `get`.** A never-published view reads as `null`, not as an
+  empty value. Return a sensible default.
+- **A view is a copy, not the truth.** Never store data *only* in a view. Keep
+  the real data in a source family (Documents, Events, Counters) and treat the
+  view as a disposable, recomputable projection.
+- **Keep views bounded.** A view value is read whole on every request, so build
+  it from a bounded read (top N, latest N, a total), not the entire history.
+
+## Related
+
+- [`@derive`](../background/derive.md): the normal way a view is maintained.
+- [Events](./events.md): the append-only log a view is often folded from.
+- [Counters](./counters.md): another common source for a view (totals).
+- [Documents](./documents.md): mutable source-of-truth records (and how a write
+  differs from a publish).
+- [Data types (`@data`)](../concepts/types.md): how view keys and values are stored.

package/docs/frontend/README.md

@@ -0,0 +1,101 @@
+# Frontend
+
+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.
+
+If you have written React before, everything here is familiar React: components, hooks, JSX. toiljs adds the parts a plain React app makes you wire up yourself: a router, data loading, `<head>` and SEO management, an image component, and a typed client for calling your backend. You get them for free and you do not import most of them, they live on a global called `Toil`.
+
+## What "frontend" means here
+
+A toiljs project has three top-level folders. The frontend is the first two:
+
+- **`client/`** is your React app: pages, components, and styles. This is what runs in the user's browser.
+- **`shared/`** is a typed bridge that toiljs generates for you. It lets the browser call your backend with full type safety (see [Fetching data](./data-fetching.md)).
+- **`server/`** is your backend. It compiles to WebAssembly and runs on the edge. That is a separate section (see [Backend](../backend/README.md)).
+
+Inside `client/`, the important pieces are:
+
+| Path | What it is |
+| --- | --- |
+| `client/toil.tsx` | The entry file. It imports your routes and global styles and mounts the app. |
+| `client/routes/` | Your pages. One file per URL (file-based routing). See [Routing](./routing.md). |
+| `client/layout.tsx` | The root layout that wraps every page (a header, a footer, and so on). |
+| `client/components/` | Your own reusable React components. |
+| `client/styles/` | Your CSS. See [Styling](./styling.md). |
+| `client/public/` | Static files served as-is (`favicon.ico`, images, `robots.txt`). |
+
+The entry file is tiny, and you rarely touch it:
+
+```tsx
+// client/toil.tsx
+import { routes, layout, notFound, globalError, slots } from 'toiljs/routes';
+import './styles/main.css';
+
+Toil.mount(routes, layout, notFound, globalError, slots);
+```
+
+`toiljs/routes` is a virtual module: the compiler scans `client/routes/` and generates the route table for you, so you never hand-maintain a list of pages. Adding a file under `client/routes/` adds a page.
+
+## SPA, but with a server head start
+
+By default a toiljs app is a single-page application (SPA). The word "SPA" means the browser loads one HTML shell, then JavaScript builds every page and swaps between them without a full reload. That makes navigation instant, but it has a classic weakness: the very first load shows a blank page until the JavaScript runs, and simple crawlers that do not run JavaScript see nothing useful.
+
+toiljs closes that gap in two ways, both optional and both explained in [Rendering and SSR](./rendering.md):
+
+1. **Build-time prerendering.** At build time toiljs bakes each route's `<head>` (title, description, Open Graph, and so on) into real HTML, so crawlers and link-preview bots see correct metadata even without running your code.
+2. **Edge server-side rendering (SSR).** For routes you opt in with `export const ssr = true`, the edge fills in real first-paint HTML for the page body, then the browser "hydrates" it (attaches React to the already-drawn markup instead of redrawing it).
+
+Here is the full life of one request, from a cold link click to a warm client-side app:
+
+```mermaid
+sequenceDiagram
+    participant U as User's browser
+    participant E as Dacely edge
+    U->>E: GET /some-page
+    E-->>U: HTML (baked head + first-paint body if ssr=true)
+    Note over U: First paint appears immediately
+    U->>E: fetch the JS bundle + route chunk
+    Note over U: React "hydrates": attaches to the existing HTML
+    Note over U: Page is now interactive
+    U->>U: Click a link -> client-side navigation (no reload)
+    Note over U: Only the new route's data + chunk are fetched
+```
+
+The key idea: the server gets you a correct first paint fast, and from then on the app runs entirely in the browser, fetching only small route chunks and data as you navigate.
+
+## The `Toil` global
+
+Most of the client API lives on a global object called `Toil`, so route files need no imports for the common things. A few examples you will meet across these pages:
+
+```tsx
+Toil.Link          // a client-side navigation link
+Toil.NavLink       // a Link that knows when it is "active"
+Toil.useParams()   // read dynamic URL params, e.g. { id } for /blog/[id]
+Toil.useLoaderData // read data your route's loader fetched
+Toil.Image         // an <img> that avoids layout shift and lazy-loads
+Toil.useHead       // set the <title> and <meta> tags
+Server.REST.*      // the typed fetch client for your backend
+```
+
+`Server` is also global (it is the typed backend client, see [Fetching data](./data-fetching.md)). Everything on `Toil` is fully typed: your editor autocompletes it, because toiljs generates a `toil-env.d.ts` that maps `Toil` onto the `toiljs/client` package.
+
+The same fast data utilities your backend uses are available in client code too, as bare globals with no import: `FastMap` and `FastSet` (high-performance map and set collections), and `DataWriter` / `DataReader` (a compact binary codec for encoding and decoding buffers). They are handed to you the same way `Toil` and `Server` are, so you can write `new DataWriter()` straight in a component. See [Data types](../backend/data.md) for the codec and when to reach for it.
+
+## The frontend pages
+
+Read them in roughly this order:
+
+- **[Routing](./routing.md)**: turn files into URLs. Index, nested, and dynamic pages; layouts and templates; active links; and navigating in code.
+- **[Rendering and SSR](./rendering.md)**: what renders on the server versus in the browser, how hydration works, and the current SSR limitations.
+- **[Styling](./styling.md)**: plain CSS, preprocessors (Sass / Less / Stylus), and Tailwind.
+- **[Images](./images.md)**: the `Toil.Image` component, automatic blur placeholders, and how it stops layout shift.
+- **[Metadata and SEO](./metadata.md)**: set the page title, description, and social-share tags per route.
+- **[Fetching data](./data-fetching.md)**: call your backend with the generated typed clients, submit forms, and read who is logged in.
+- **[Scripts](./scripts.md)**: load external or inline `<script>` tags with a loading strategy, using `Toil.Script`.
+- **[Search](./search.md)**: the built-in, statically-baked page search and command palette (`usePageSearch`).
+
+## Related
+
+- [Getting started](../getting-started/README.md): install toiljs and create a project.
+- [Project structure](../getting-started/project-structure.md): the full folder layout.
+- [Backend overview](../backend/README.md): the `server/` side your frontend talks to.
+- [The CLI](../cli/README.md): `toiljs dev`, `toiljs build`, and every flag.

package/docs/frontend/data-fetching.md

@@ -0,0 +1,243 @@
+# Fetching data
+
+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. This page covers loading data for a page, calling the backend directly, submitting forms, and reading who is logged in.
+
+## The generated `Server` client
+
+When you build the server, toiljs writes a file at `shared/server.ts` that contains your `@data` classes and a typed description of every backend endpoint. Importing anything from `shared/server` attaches the runtime clients to a global called `Server`. From then on you call your backend through `Server`, fully typed, with editor autocomplete.
+
+There are two surfaces under `Server`:
+
+- **`Server.REST.<controller>.<route>(args)`**: a real, typed `fetch` client for your `@rest` HTTP controllers. This is the working, recommended way to call the backend today.
+- **`Server.<service>.<method>(args)` and `Server.<remote>(args)`**: the typed RPC surface for `@service` / `@remote` functions.
+
+Both are generated from your server code, so if you rename a route or change an argument type, the call site is a compile error until you fix it.
+
+## Calling a REST endpoint
+
+`Server.REST` mirrors your `@rest` controllers. If your backend has a `players` controller with routes on it, you call them like this:
+
+```tsx
+import { NewPlayer, ScoreDelta } from 'shared/server';
+
+// POST /players with a typed @data body -> typed Promise<Player>
+const player = await Server.REST.players.create({ body: new NewPlayer('Ada') });
+
+// POST /players/:id/score with a path param AND a body
+const updated = await Server.REST.players.addScore({
+  params: { id: 1 },
+  body: new ScoreDelta(5n),
+});
+
+// GET /leaderboard -> typed Promise<Standings>
+const board = await Server.REST.leaderboard.top();
+```
+
+The single argument is an object with up to four optional parts:
+
+| Key | What it is |
+| --- | --- |
+| `params` | Path parameters, e.g. `{ id: 1 }` for a `/players/:id` route. |
+| `body` | The request body, usually a `@data` class instance. |
+| `query` | Query-string values. |
+| `headers` | Extra request headers. |
+
+Return values are typed and decoded for you. A route that returns a `@data` type hands you the parsed class instance. A route that returns a raw `Response` hands you the raw fetch `Response`, so you can inspect the status and headers yourself:
+
+```tsx
+// This route returns a Response, so you get the raw fetch Response.
+const res = await Server.REST.players.get({ params: { id: 1 } });
+if (!res.ok) {
+  console.log('status', res.status);
+} else {
+  const p = await res.json();
+}
+```
+
+`@data` classes are the typed values that cross the wire. You import them from `shared/server` and construct them normally (`new NewPlayer('Ada')`). See [Data types](../backend/data.md) for how they are defined on the server.
+
+### Handling errors
+
+A failed call throws. The global `parseError` helper turns any caught value into a readable message, which is handy in a `catch`:
+
+```tsx
+try {
+  const board = await Server.REST.leaderboard.top();
+} catch (err) {
+  console.error(parseError(err));
+}
+```
+
+## Loading data for a page (loaders)
+
+Calling the backend from a button handler (as above) is fine for actions. For the data a page needs to *render*, use a route **loader** instead of a `useEffect`. A loader runs on navigation, in parallel with loading the page's code, and the page suspends (showing its `loading.tsx`) until the data is ready:
+
+```tsx
+// client/routes/blog/[id].tsx
+export const loader = async ({ params }: Toil.LoaderArgs) => {
+  return Server.REST.blog.get({ params: { id: params.id } });
+};
+
+export default function BlogPost() {
+  const post = Toil.useLoaderData<typeof loader>();
+  return <article><h1>{post.title}</h1></article>;
+}
+```
+
+`useLoaderData<typeof loader>()` is fully typed from the loader's return. This keeps data fetching declarative and out of effects, and it is what lets server-rendered pages seed the browser with the server's data so hydration stays clean.
+
+### Caching and revalidating loader data
+
+Loader results are cached by URL. You control how long with `export const revalidate`:
+
+| `revalidate` value | Behavior |
+| --- | --- |
+| `0` (default) | Re-run the loader on every navigation to the route. |
+| a number `n` | Reuse cached data for `n` seconds, then refetch. |
+| `false` | Cache until you invalidate it manually. |
+
+After a mutation (say you just POSTed a new comment), refresh the current page's data with `revalidate()` or the router:
+
+```tsx
+const router = Toil.useRouter();
+await Server.REST.comments.add({ body: new NewComment(text) });
+router.revalidate();            // refetch the active route's loader
+// or target another route: router.revalidate('/posts');
+```
+
+`router.refresh()` re-runs the current loader and clears the cache; `router.revalidate(href)` invalidates a specific route.
+
+### Invalidating loader data by hand
+
+`revalidate()` and the `<Toil.Form>` `revalidate` prop are both built on one lower-level primitive: `Toil.invalidateLoaderData(href?)`. It drops cached loader data so the next render refetches it, but it does **not** trigger the re-render itself (that is the difference from `revalidate()`, which does both):
+
+- `invalidateLoaderData()` with no argument clears every route's cached data.
+- `invalidateLoaderData('/posts')` clears just that one route's entry.
+
+You rarely need it directly; `revalidate()` (which pairs it with a re-render) is what you usually want. Reach for the primitive when you want to mark data stale *now* but let a later navigation do the actual refetch:
+
+```tsx
+// After a background sync finished, mark the dashboard stale so its
+// next visit refetches, without disturbing the page the user is on.
+Toil.invalidateLoaderData('/dashboard');
+```
+
+Signature: `invalidateLoaderData(href?: string): void`.
+
+## Forms
+
+For the common "submit a form, then refresh the page's data" loop, use `Toil.Form`. It runs an async action on submit (no page reload), tracks pending and error state, and revalidates the route's loader data on success:
+
+```tsx
+import { NewMessage } from 'shared/server';
+
+export default function Guestbook() {
+  const entries = Toil.useLoaderData<typeof loader>();
+
+  const sign = async (data: FormData) => {
+    const author = String(data.get('author'));
+    const message = String(data.get('message'));
+    await Server.REST.guestbook.sign({ body: new NewMessage(author, message) });
+  };
+
+  return (
+    <Toil.Form action={sign} resetOnSuccess>
+      {({ pending }) => (
+        <>
+          <input name="author" />
+          <input name="message" />
+          <button disabled={pending}>Sign</button>
+        </>
+      )}
+    </Toil.Form>
+  );
+}
+```
+
+Key `Toil.Form` props:
+
+| Prop | Default | What it does |
+| --- | --- | --- |
+| `action` | (required) | Runs on submit, receiving the form's `FormData`. May be async. |
+| `revalidate` | `true` (current route) | Which loader data to refetch after a successful submit. |
+| `resetOnSuccess` | `false` | Clear the form fields after success. |
+| `onSuccess` / `onError` | | Callbacks for the two outcomes. |
+
+Passing a **render function** as `children` gives you live submit state (`pending`, `error`), so you can disable the button while the request is in flight. On success, `Form` revalidates the loader, so the page's data updates automatically without a manual refetch.
+
+## Mutations without a form: `useAction`
+
+`Toil.Form` is convenient sugar over a more general primitive, `Toil.useAction`. Use `useAction` for any write that is not a form submit: a delete button, a "like" toggle, a "mark as read" action. It runs your async function on demand and tracks the whole lifecycle (`pending`, `error`, `data`), then revalidates the affected loader data on success so the page reflects the change, exactly like `Form` does.
+
+You call it with the function to run and an optional options object, and it hands back a handle:
+
+```tsx
+export default function PostRow({ id }: { id: number }) {
+  const del = Toil.useAction(
+    (postId: number) => Server.REST.posts.remove({ params: { id: postId } }),
+    { revalidate: true, onError: (e) => alert(parseError(e)) },
+  );
+
+  return (
+    <button disabled={del.pending} onClick={() => void del.run(id)}>
+      {del.pending ? 'Deleting...' : 'Delete'}
+    </button>
+  );
+}
+```
+
+The handle it returns:
+
+| Field | What it is |
+| --- | --- |
+| `run(input)` | Runs the action. Resolves to the result, or `undefined` if it threw. The error is captured in `error` rather than rejected, so a fire-and-forget `onClick` cannot leak an unhandled rejection. |
+| `pending` | `true` while a run is in flight. Drive a spinner or a disabled button off this. |
+| `error` | The error from the last failed run, or `undefined`. |
+| `data` | The value the last successful run returned, or `undefined`. |
+| `reset()` | Clear `pending` / `error` / `data` back to idle. |
+
+The options mirror `Toil.Form`:
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `revalidate` | `true` (current route) | Which loader data to refetch after a successful run: `true` (the active route), an `href` or array of hrefs (those routes), or `false` (none). |
+| `onSuccess` | | Called with the action's return value after a successful run. |
+| `onError` | | Called with the thrown value when the action fails. |
+
+`Toil.Form` is just this hook wired to a `<form>`'s submit event, with the form's `FormData` passed as the input. Anything a form does, you can do by hand with `useAction`.
+
+## Reading who is logged in
+
+To render "logged in as ..." you need the current user. toiljs generates a `getUser()` helper (from the backend's `@user` surface) that reads the current user from a readable session cookie with no network round-trip. It is instant, which makes it perfect for display, but it is **untrusted**: a value read on the client can be forged, so never gate anything security-sensitive on it. For a trusted check, call a guarded backend route that re-verifies the signed session.
+
+The full auth flow (post-quantum login, sessions, `getUser()`, and guarding routes) is its own guide:
+
+- [Auth usage](../auth/usage.md): reading the session, `getUser()`, and guarding pages.
+
+## RPC (`@service` / `@remote`)
+
+Alongside REST, toiljs generates a typed RPC surface for `@service` methods and free `@remote` functions. These read like plain function calls with no URL:
+
+```tsx
+const n = await Server.ping(10);              // a free @remote
+const count = await Server.stats.playerCount(); // a @service method
+```
+
+The types come straight from your server, so `Server.ping` knows it takes a number and returns a number. Under the hood each call encodes its arguments and POSTs them to a single reserved endpoint (`/__toil_rpc`) with a compact method id, then decodes the typed result. Both the local dev server and the production edge dispatch this endpoint, so RPC works end to end.
+
+If a call throws an "unavailable" error, it means the generated client has not attached yet: build the server (`npm run build:server`) to regenerate `shared/server.ts`, and import from `shared/server` so the client loads (see the gotchas below). See [Typed RPC](../backend/rpc.md) for the backend side and when to choose RPC over REST.
+
+## Gotchas
+
+- **Import from `shared/server` to attach the clients.** `Server.REST` (and the RPC client) attach when you import from `shared/server`. Importing your `@data` classes from there does it naturally; if `Server.REST.foo()` throws an "unavailable" error, make sure the server has been built (`npm run build:server`) and that `shared/server` is imported.
+- **The server runs a fresh instance per request.** In the examples, in-memory writes are previews that do not persist. To keep data, write it to the database (see [Database](../database/README.md)). This is a backend property, but it explains why a create returns a value that is not there on the next request.
+- **Fetch page data in a `loader`, not `useEffect`.** A loader runs in parallel with the route chunk and integrates with `loading.tsx`, suspense, caching, and SSR hydration. A `useEffect` fetch runs only after the page mounts (slower, and invisible to the server).
+- **`getUser()` is display-only.** It is fast because it does not verify anything. Do real authorization on the server.
+
+## Related
+
+- [Routing](./routing.md): loaders, `loading.tsx`, and navigation.
+- [Backend HTTP routes](../backend/rest.md): the `@rest` controllers behind `Server.REST`.
+- [Typed RPC](../backend/rpc.md): the `@service` / `@remote` surface behind `Server`.
+- [Data types](../backend/data.md): the `@data` classes that cross the wire.
+- [Auth usage](../auth/usage.md): sessions and `getUser()`.