toiljs 0.0.115 → 0.0.117

package/docs/database/views.md

@@ -1,246 +0,0 @@
-# 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

@@ -1,104 +0,0 @@
-# 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.
-- **[Navigation](./navigation.md)**: move between pages. Links and active state, navigating in code, typed hrefs, prefetching, scroll restoration, and animated transitions.
-- **[Components](./components.md)**: use your own React components, plus the toiljs primitives (`Image`, `Script`, `Form`, `Slot`, `Head`, and the SSR markers).
-- **[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`).
-- **[The Toil global (reference)](./toil-global.md)**: a complete, grouped list of everything on the `Toil` object.
-
-## 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/components.md

@@ -1,286 +0,0 @@
-# Components
-
-A toiljs frontend is a normal React app, so the components you write are just React components: functions that return JSX, hold state with hooks, and compose however you like. There is no toiljs-specific base class, no decorator, and no registration step. On top of your own components, toiljs ships a small set of ready-made ones on the `Toil` global (an image, a script loader, a form, and a few more) for the jobs a plain React app makes you wire up by hand. This page covers both: how your components fit in, and a reference for every `Toil.*` component.
-
-## Writing your own components
-
-Anything you already know about writing React components applies unchanged. You write ordinary functions, use `useState` / `useEffect` / `useMemo` and any hooks you like, and return JSX:
-
-```tsx
-// client/components/Counter.tsx
-import { useState } from 'react';
-
-export default function Counter({ start = 0 }: { start?: number }) {
-  const [n, setN] = useState(start);
-  return <button onClick={() => setN(n + 1)}>Clicked {n} times</button>;
-}
-```
-
-Your reusable components live in `client/components/`, and you import them the normal way from anywhere in `client/`:
-
-```tsx
-// client/routes/index.tsx
-import Counter from '../components/Counter';
-
-export default function Home() {
-  return (
-    <main>
-      <h1>Welcome</h1>
-      <Counter start={10} />
-    </main>
-  );
-}
-```
-
-A few things are worth spelling out, because they are the parts that are handled for you rather than by you:
-
-- **Route files must `export default` a component.** A file under `client/routes/` becomes a page only if it default-exports a component (see [Routing](./routing.md)). Files under `client/components/` have no such rule; export them however you please (default or named).
-- **The `Toil.*` globals need no import.** `Toil.Link`, `Toil.useParams()`, `Toil.Image`, and everything else on `Toil` are ambient. The compiler generates a `toil-env.d.ts` that types the global, so your editor autocompletes `Toil.` and type-checks it with no `import` line. The same goes for `Server` (the typed backend client) and the `FastMap` / `DataWriter` data utilities. See the [Frontend overview](./README.md) for the whole ambient surface.
-- **The JSX runtime is configured for you.** You do not write `import React from 'react'` at the top of every file. The build sets up the automatic JSX runtime, so JSX just works. Import named hooks and types from `react` when you need them (`import { useState, type ReactNode } from 'react'`), but the bare React import for JSX is unnecessary.
-
-In other words, a component in a toiljs app is indistinguishable from a component in any React app. Two things are genuinely special, and both are opt-in.
-
-### Special case 1: components inside an SSR route
-
-If a route opts into server rendering with `export const ssr = true`, its component tree is rendered once at build time into a template, then filled per request on the edge (see [Rendering and SSR](./rendering.md)). For that to work, any part of the JSX that changes per request (a value from the URL, a list from a loader, a block of user HTML) has to be wrapped in one of the [SSR marker primitives](#ssr-marker-primitives) below, or isolated in a `Toil.Island`. Anything you leave unwrapped gets frozen into the template at its build-time value.
-
-You do not have to get this perfect: if an SSR route (or a layout above it) cannot render on the server, toiljs skips SSR for that route at build, prints a warning telling you what to move, and falls back to plain client rendering. So the route still works, it just loses its server first paint until you address the warning.
-
-### Special case 2: importing images and other assets
-
-Importing an image with the `?toil` suffix gives you an object carrying the resolved URL, the intrinsic width and height, and an auto-generated blur placeholder (a `blurDataURL`), ready to hand straight to `Toil.Image`:
-
-```tsx
-import hero from './hero.webp?toil';
-// hero is { src, width, height, blurDataURL }
-
-<Toil.Image src={hero} alt="Our office" />;
-```
-
-Passing the whole object lets `Toil.Image` reserve the correct aspect ratio and paint the blur while the real image loads, with no extra props. See [Images](./images.md) for the full treatment.
-
-Plain asset imports are typed for you as well. A bare `import logo from './logo.svg'` (or `.png`, `.webp`, and so on) resolves to the hashed URL string, and the vite-imagetools query forms (`?url`, `?as=srcset`, `?as=metadata`) are typed too, so you get autocomplete and type-checking on all of them without declaring any modules yourself.
-
-## The toiljs component primitives
-
-These are the components toiljs provides on the `Toil` global. They cover the framework-level jobs a plain React app leaves to you. All are ambient (no import), and all are fully typed.
-
-| Component | What it is | Renders |
-| --- | --- | --- |
-| `Toil.Image` | Layout-shift-free `<img>` replacement with lazy-load and blur placeholder. | An `<img>` (optionally wrapped in a sizing box). |
-| `Toil.Script` | One-time external or inline `<script>` loader with a load strategy. | Nothing (`null`). |
-| `Toil.Form` | A `<form>` that runs an action on submit and revalidates loader data. | A `<form>`. |
-| `Toil.Slot` | Renders a named parallel-route slot for the current URL. | The slot's route tree, or a fallback. |
-| `Toil.Head` | Declarative `<head>` contribution (title, meta, link). | Nothing (`null`). |
-| `Toil.Metadata` | Declarative route-style metadata applied from any component. | Nothing (`null`). |
-
-The [SSR marker primitives](#ssr-marker-primitives) (`Toil.Hole`, `Toil.Repeat`, `Toil.RawHtml`, `Toil.attr`, `Toil.Island`) are a separate group, covered in their own section below.
-
-### `Toil.Image`
-
-A drop-in `<img>` replacement that prevents layout shift and lazy-loads by default. You give it `width` and `height` (or `fill`) so it reserves space before the image arrives, it decodes asynchronously, it lazy-loads unless you mark it `priority`, and it can fade in from a blur placeholder. It accepts either a string URL or a `?toil` import object (which auto-fills the size and blur):
-
-```tsx
-import hero from './hero.webp?toil';
-
-export default function Home() {
-  return (
-    <>
-      <Toil.Image src={hero} alt="Our office" priority placeholder="blur" />
-      <Toil.Image src="/team.jpg" alt="The team" width={800} height={600} />
-    </>
-  );
-}
-```
-
-Key props are `src`, `alt` (required, pass `alt=""` for a decorative image), `width` / `height` or `fill`, `priority` (for an above-the-fold hero), and `placeholder` (`'empty'` or `'blur'`). It also accepts any standard `<img>` attribute. This is kept brief on purpose: [Images](./images.md) covers sizing, `fill`, blur placeholders, and how it stops layout shift in full.
-
-### `Toil.Script`
-
-Loads an external or inline `<script>` exactly once for the whole life of the app (even across client-side navigations), and lets you choose when it runs with a `strategy` prop. Use it instead of a hand-written `<script>` tag for third-party snippets like analytics or chat widgets, which a plain `<script>` in a single-page app runs unreliably or twice:
-
-```tsx
-// client/layout.tsx
-export default function Layout({ children }: { children?: React.ReactNode }) {
-  return (
-    <div className="app">
-      <Toil.Script src="https://cdn.example-analytics.com/analytics.js" />
-      {children}
-    </div>
-  );
-}
-```
-
-The `strategy` is `afterInteractive` (default), `lazyOnload`, or `beforeInteractive`, and there are `onLoad` / `onReady` / `onError` callbacks. `Toil.Script` renders nothing. See [Scripts](./scripts.md) for the strategies, inline scripts, dedup rules, and the full prop table.
-
-### `Toil.Form`
-
-A `<form>` that submits without reloading the page. On submit it runs your `action` (which receives the form's `FormData`), tracks pending and error state, and on success revalidates the current route's loader data so the page reflects the write. It is the convenient front end of the loader/action data loop:
-
-```tsx
-// A guestbook that refreshes its list after a successful sign.
-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, error }) => (
-        <>
-          <input name="author" placeholder="Your name" />
-          <textarea name="message" />
-          <button disabled={pending}>{pending ? 'Signing...' : 'Sign'}</button>
-          {error ? <p className="err">Could not sign, try again.</p> : null}
-        </>
-      )}
-    </Toil.Form>
-  );
-}
-```
-
-Pass a render function as the child to read the live submit state: it receives `{ pending, error, data }`, which is how you disable the button while pending or show an error. The props:
-
-| Prop | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `action` | `(data: FormData) => void \| Promise<void>` | (required) | Runs on submit, receiving the form's `FormData`. May be async. |
-| `revalidate` | `RevalidateTarget` | `true` | Which loader data to refetch after a successful submit. `true` is the current route. |
-| `onSuccess` | `() => void` | (none) | Called after a successful submit. |
-| `onError` | `(error: unknown) => void` | (none) | Called when the action throws. |
-| `resetOnSuccess` | `boolean` | `false` | Reset the form fields after a successful submit. |
-| `className` | `string` | (none) | Class on the `<form>` element. |
-| `children` | `ReactNode` or `(state) => ReactNode` | (none) | Form contents. A function child receives `{ pending, error, data }`. |
-
-For writes that are not form submits (a delete button, a like toggle), reach for the underlying `Toil.useAction` hook instead. Both are covered in [Fetching data](./data-fetching.md).
-
-### `Toil.Slot`
-
-Renders the named parallel-route slot for the current URL. A folder starting with `@` (like `@modal`) under `client/routes/` is a whole second route tree that matches the URL independently of the main page; placing `<Toil.Slot name="modal" />` is where that tree renders. If no slot route matches the current URL, it renders the `fallback` (nothing by default):
-
-```tsx
-// client/routes/gallery/layout.tsx
-export default function GalleryLayout({ children }: { children?: React.ReactNode }) {
-  return (
-    <div>
-      {children}
-      <Toil.Slot name="modal" fallback={null} />
-    </div>
-  );
-}
-```
-
-| Prop | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `name` | `string` | (required) | The slot name: the `@name` directory under `routes/`, without the `@`. |
-| `fallback` | `ReactNode` | `null` | Rendered when no slot route matches the current URL. |
-
-Parallel slots and the intercepting routes that fill them (the "click a photo, open it in a modal" pattern) are explained in [Routing](./routing.md).
-
-### `Toil.Head`
-
-A declarative way for any component (a page, a layout, a deep child) to contribute to the document `<head>`: a title, `<meta>` tags, and `<link>` tags. It renders nothing; it just applies its head entries for the lifetime of the component and reverts them on unmount. Entries compose across the tree, with later or deeper ones winning per key:
-
-```tsx
-export default function ArticlePage() {
-  const post = Toil.useLoaderData<typeof loader>();
-  return (
-    <>
-      <Toil.Head
-        title={post.title}
-        meta={[
-          { name: 'description', content: post.summary },
-          { property: 'og:title', content: post.title },
-        ]}
-        link={[{ rel: 'canonical', href: `https://example.com/blog/${post.id}` }]}
-      />
-      <article>{/* ... */}</article>
-    </>
-  );
-}
-```
-
-`<Toil.Head>` takes `title`, `meta` (an array of `{ name | property, content }` tags), and `link` (an array of `{ rel, href }` tags). The hook form `Toil.useHead(spec)` and the shorthand `Toil.useTitle(title)` do the same job imperatively. See [Metadata and SEO](./metadata.md).
-
-### `Toil.Metadata`
-
-The declarative, convenience-shaped cousin of `Toil.Head`. Instead of raw meta and link arrays, you pass a route-style metadata object (the same shape a route file's `export const metadata` uses), and toiljs expands the convenience fields (`description`, `keywords`, `canonical`, `openGraph`, and so on) into the right tags. It renders nothing, and applies for the component's lifetime. Use it to set metadata from a component that is not itself a route file (a rendered article, a widget):
-
-```tsx
-<Toil.Metadata
-  title="Our pricing"
-  description="Simple, flat pricing for teams of any size."
-  openGraph={{ title: 'Pricing', image: 'https://example.com/og/pricing.png' }}
-/>
-```
-
-Because a route's own `metadata` export is applied last (highest priority), `Toil.Metadata` fills in for routes that declare none and yields to a route that sets the same key. The full field list lives in [Metadata and SEO](./metadata.md).
-
-## SSR marker primitives
-
-These five primitives matter only for routes with `export const ssr = true`. They are how you tell the build which parts of a server-rendered page are dynamic (filled per request) versus static (baked into the template once). On a client-only route they do nothing special, so you never need them unless you opt a route into SSR.
-
-**The mental model.** In the browser these markers are transparent: `<Toil.Hole>` renders its children, `<Toil.Repeat>` maps its rows, `<Toil.RawHtml>` renders a raw-HTML wrapper, and `Toil.attr(id, value)` returns the value unchanged. Your client-side app runs exactly as written. But under the build-time SSR extractor, each marker instead emits a sentinel token that marks an insertion point. The extractor strips those tokens and records their positions, producing a static template with numbered holes. Per request, your compiled backend fills only the hole values, and the edge splices them into the template. Because the static scaffold around each hole is React's own rendering output and the hole values are escaped exactly as React escapes them, the browser hydrates the result byte-for-byte, with no mismatch.
-
-| Marker | Use it for | Shape |
-| --- | --- | --- |
-| `Toil.Hole` | A single dynamic **text** value. | `<Toil.Hole id="...">{value}</Toil.Hole>` |
-| `Toil.Repeat` | A **list**: one row template repeated over an `each` array. | `<Toil.Repeat id="..." each={rows}>{(item, i) => ...}</Toil.Repeat>` |
-| `Toil.RawHtml` | A block of **trusted, pre-rendered HTML**. | `<Toil.RawHtml id="..." html={s} as="section" />` |
-| `Toil.attr` | A dynamic value in **attribute position** (an `href`, a `class`). | `href={Toil.attr('id', value)}` (a function call) |
-| `Toil.Island` | Content that must render **only in the browser** (escape hatch). | `<Toil.Island>{children}</Toil.Island>` |
-
-A few rules that keep the template valid:
-
-- **Every marker needs a stable `id`**, a short name unique within the page. The build maps each id to a numbered slot, so keep the ids constant across builds.
-- **`Toil.Repeat` needs at least one row at build time.** It captures that first row as the sub-template for every row, so the build render must see a sample with one or more items. An empty `each` gives it nothing to capture.
-- **`Toil.RawHtml` renders inside a wrapper element** (a `<div>` by default, `as="section"` to change the tag), and you own sanitising that HTML, exactly like React's `dangerouslySetInnerHTML`.
-- **`Toil.attr` is a function, not an element.** An attribute is not a child node, so it cannot be a JSX element. You call `Toil.attr(id, value)` right where the attribute value goes, and it composes with literal text around it (`` className={`btn ${Toil.attr('kind', d.kind)}`} ``).
-- **`Toil.Island` renders nothing on the server and on the first (hydration) render**, then reveals its children after mount. So an island gets no server first paint and no SEO, by design. It is the place for anything that genuinely cannot run on the server (reads `window`, calls `Date.now()`, depends on the live URL).
-
-Here is a compact SSR route wiring several of them together. The title, tag list, and author link all come from the route's `loader`:
-
-```tsx
-// client/routes/blog/[id].tsx
-export const ssr = true;
-
-export const loader = async ({ params }: Toil.LoaderArgs) => {
-  // Illustrative shape: { title, tags, authorUrl }.
-  return Server.REST.blog.get({ params: { id: params.id } });
-};
-
-export default function BlogPost() {
-  const post = Toil.useLoaderData<typeof loader>();
-  return (
-    <article>
-      <h1>
-        <Toil.Hole id="title">{post.title}</Toil.Hole>
-      </h1>
-
-      {/* A dynamic attribute: call attr() in attribute position. */}
-      <a href={Toil.attr('authorUrl', post.authorUrl)}>By the author</a>
-
-      {/* A list: one row template, stamped once per item on the server. */}
-      <ul>
-        <Toil.Repeat id="tags" each={post.tags}>
-          {(tag) => <li key={tag}>{tag}</li>}
-        </Toil.Repeat>
-      </ul>
-    </article>
-  );
-}
-```
-
-For the whole SSR story (the template extraction flow, keeping a route SSR-safe, and the current SSR limitations), see [Rendering and SSR](./rendering.md).
-
-## Related
-
-- [Rendering and SSR](./rendering.md): how SSR routes render, hydrate, and use the marker primitives.
-- [Images](./images.md): the full `Toil.Image` reference, blur placeholders, and layout shift.
-- [Scripts](./scripts.md): `Toil.Script` strategies, inline scripts, and dedup.
-- [Fetching data](./data-fetching.md): `Toil.Form`, `useAction`, loaders, and the typed backend clients.
-- [Metadata and SEO](./metadata.md): `Toil.Head`, `Toil.Metadata`, and per-route metadata.
-- [Routing](./routing.md): pages, layouts, and the parallel slots `Toil.Slot` renders.