npm - toiljs - Versions diffs - 0.0.85 → 0.0.87 - Mend

toiljs 0.0.85 → 0.0.87

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (132) hide show

package/CHANGELOG.md +5 -0
package/README.md +2 -2
package/build/cli/.tsbuildinfo +1 -1
package/build/cli/index.js +303 -293
package/build/compiler/.tsbuildinfo +1 -1
package/build/compiler/config.d.ts +2 -0
package/build/compiler/config.js +1 -0
package/build/compiler/docs.js +8 -24
package/build/compiler/generate.js +4 -2
package/build/compiler/index.d.ts +1 -1
package/build/compiler/index.js +69 -6
package/build/compiler/toil-docs.generated.js +64 -22
package/build/devserver/.tsbuildinfo +1 -1
package/build/devserver/analytics/index.js +7 -3
package/build/devserver/db/database.d.ts +4 -0
package/build/devserver/db/database.js +43 -1
package/build/devserver/db/index.d.ts +1 -1
package/build/devserver/db/index.js +1 -1
package/build/devserver/db/types.d.ts +3 -0
package/build/devserver/db/types.js +2 -0
package/build/devserver/runtime/module.js +4 -1
package/docs/README.md +104 -65
package/docs/auth/README.md +102 -0
package/docs/auth/configuration.md +94 -0
package/docs/auth/extending.md +202 -0
package/docs/auth/how-it-works.md +138 -0
package/docs/auth/usage.md +188 -0
package/docs/backend/README.md +143 -0
package/docs/backend/data.md +351 -0
package/docs/backend/rest.md +402 -0
package/docs/backend/rpc.md +226 -0
package/docs/background/README.md +114 -0
package/docs/background/daemons.md +230 -0
package/docs/background/derive.md +179 -0
package/docs/cli/README.md +377 -0
package/docs/concepts/config.md +416 -0
package/docs/concepts/decorators.md +127 -0
package/docs/concepts/security.md +108 -0
package/docs/concepts/tiers.md +166 -0
package/docs/concepts/types.md +216 -0
package/docs/database/README.md +143 -0
package/docs/database/capacity.md +350 -0
package/docs/database/counters.md +174 -0
package/docs/database/documents.md +255 -0
package/docs/database/events.md +307 -0
package/docs/database/membership.md +246 -0
package/docs/database/setup.md +155 -0
package/docs/database/unique.md +216 -0
package/docs/database/views.md +246 -0
package/docs/frontend/README.md +101 -0
package/docs/frontend/data-fetching.md +243 -0
package/docs/frontend/images.md +148 -0
package/docs/frontend/metadata.md +344 -0
package/docs/frontend/rendering.md +236 -0
package/docs/frontend/routing.md +344 -0
package/docs/frontend/scripts.md +118 -0
package/docs/frontend/search.md +191 -0
package/docs/frontend/styling.md +147 -0
package/docs/getting-started/README.md +81 -0
package/docs/getting-started/create-project.md +131 -0
package/docs/getting-started/deploy.md +101 -0
package/docs/getting-started/first-app.md +215 -0
package/docs/getting-started/installation.md +106 -0
package/docs/getting-started/migrating.md +125 -0
package/docs/getting-started/project-structure.md +163 -0
package/docs/introduction/README.md +41 -0
package/docs/introduction/design-principles.md +55 -0
package/docs/introduction/distributed.md +74 -0
package/docs/introduction/how-it-works.md +74 -0
package/docs/introduction/hyperscale.md +51 -0
package/docs/introduction/modern-stack.md +36 -0
package/docs/introduction/vs-other-frameworks.md +48 -0
package/docs/introduction/why-toil.md +93 -0
package/docs/llms.txt +90 -0
package/docs/realtime/README.md +102 -0
package/docs/realtime/channels.md +211 -0
package/docs/realtime/streams.md +369 -0
package/docs/services/README.md +60 -0
package/docs/services/analytics.md +268 -0
package/docs/services/caching.md +175 -0
package/docs/services/cookies.md +235 -0
package/docs/services/crypto.md +209 -0
package/docs/services/email.md +289 -0
package/docs/services/environment.md +141 -0
package/docs/services/ratelimit.md +174 -0
package/docs/services/time.md +85 -0
package/examples/basic/client/routes/analytics.tsx +13 -12
package/examples/basic/server/models/SiteAnalytics.ts +29 -17
package/examples/basic/server/routes/Analytics.ts +15 -17
package/examples/basic/server/routes/UserId.ts +22 -0
package/package.json +15 -11
package/scripts/gen-toil-docs.mjs +24 -35
package/server/auth/AuthController.ts +336 -0
package/server/auth/AuthUser.ts +23 -0
package/server/auth/index.ts +16 -0
package/server/globals/auth.ts +31 -0
package/server/globals/userid.ts +107 -0
package/src/compiler/config.ts +13 -0
package/src/compiler/docs.ts +16 -33
package/src/compiler/generate.ts +6 -2
package/src/compiler/index.ts +114 -6
package/src/compiler/toil-docs.generated.ts +64 -22
package/src/devserver/analytics/index.ts +10 -4
package/src/devserver/db/database.ts +67 -1
package/src/devserver/db/index.ts +1 -0
package/src/devserver/db/types.ts +13 -0
package/src/devserver/runtime/module.ts +7 -0
package/test/analytics-dev.test.ts +2 -1
package/test/devserver-database.test.ts +113 -0
package/docs/auth-todo.md +0 -149
package/docs/auth.md +0 -322
package/docs/caching.md +0 -115
package/docs/cli.md +0 -17
package/docs/client.md +0 -39
package/docs/cookies.md +0 -457
package/docs/crypto.md +0 -130
package/docs/daemon.md +0 -123
package/docs/data.md +0 -131
package/docs/derive.md +0 -159
package/docs/email.md +0 -326
package/docs/environment.md +0 -97
package/docs/getting-started.md +0 -128
package/docs/index.md +0 -30
package/docs/ratelimit.md +0 -95
package/docs/routing.md +0 -259
package/docs/rpc.md +0 -149
package/docs/server.md +0 -61
package/docs/ssr.md +0 -632
package/docs/streams.md +0 -178
package/docs/styling.md +0 -22
package/docs/tiers.md +0 -133
package/docs/time.md +0 -43

package/docs/frontend/rendering.md ADDED Viewed

@@ -0,0 +1,236 @@
+# Rendering and SSR
+This page explains where your pages are built: in the browser, ahead of time at build, or on the server for each request. Getting this right is what makes a page paint fast and rank well.
+## The three ways a page can render
+A toiljs page can reach the user in three ways. You mostly get all three for free; the only one you opt into per page is edge SSR.
+| Mode | Who builds the HTML | When | Good for |
+| --- | --- | --- | --- |
+| **Client rendering** | The browser, from JavaScript | On every visit | Interactive, per-user pages (a dashboard). The default. |
+| **Build-time prerender** | The build, once | When you run `toiljs build` | Baking each route's `<head>` (SEO) into real HTML. Automatic. |
+| **Edge SSR** | The edge server, per request | When you set `ssr = true` | A real first-paint page body plus SEO, for landing and content pages. |
+Let us define the two words that trip people up:
+- **Rendering** means turning your React components into HTML.
+- **Hydration** means React attaching to HTML that already exists on the page (from the server) instead of throwing it away and redrawing it. Hydration is what makes a server-rendered page interactive without a flash.
+## Client rendering (the default)
+By default, toiljs ships a small HTML shell with an empty `<div id="root">`, plus your JavaScript. The browser downloads the JS, React runs, and it builds the page into `#root`. From then on, navigating between pages is pure JavaScript: only the next route's small code chunk and its data are fetched, and the page swaps in place with no reload.
+This is fast to navigate and simple to reason about. Its one weakness is the *first* paint: until the JavaScript runs, `#root` is empty. For an app behind a login (a dashboard) that is fine, nobody is trying to index it. For a public landing page, you usually want one of the two server-assisted modes below.
+## Build-time prerender (automatic SEO)
+Every time you build, toiljs renders each static route once and bakes its resolved `<head>` (title, description, canonical link, Open Graph tags, and so on) into that route's HTML file. This happens for all routes with no extra work from you, and it is driven by the `metadata` you export from a route plus the site-wide `seo` config (see [Metadata and SEO](./metadata.md)).
+The payoff: a crawler or a link-preview bot (Slack, Discord, iMessage) that fetches your page sees correct tags immediately, even though it does not run your JavaScript. "View source" on a built page shows the real title and meta tags, not an empty shell.
+In production, `toiljs build` writes one prerendered HTML file per route (for example `about/index.html`), and the production static server (`npm start`) serves each route its own prerendered file rather than a single shared shell. That is how each page gets its own metadata in the raw HTML.
+Build-time prerender covers the `<head>`. It does not, by itself, fill in the page *body*: for a client-rendered route the body is still built by React in the browser. To get real first-paint body HTML, opt the route into edge SSR.
+### Prerendering dynamic routes with `generateStaticParams`
+Build-time prerender bakes a `<head>` for every **static** route on its own. A **dynamic** route (`client/routes/blog/[id].tsx`, one file that serves `/blog/1`, `/blog/2`, and so on) has no single URL to prerender, so by default it gets none of that per-URL HTML. If you know the concrete URLs ahead of time (a fixed set of blog posts, product pages, or docs), you can opt the route into **static site generation (SSG)**, which means the build renders one HTML file per known URL: it enumerates each URL and writes a real `<url>/index.html` with that page's resolved metadata, plus a `sitemap.xml` entry. This is the toiljs analog of Next.js `generateStaticParams`.
+You opt in by exporting `generateStaticParams` from the dynamic route. It returns one object per URL, keyed by the route's param names:
+```tsx
+// client/routes/blog/[id].tsx
+// One entry per URL to prerender. `id` matches the [id] segment.
+export const generateStaticParams: Toil.GenerateStaticParams = () => {
+  return [{ id: '1' }, { id: '2' }, { id: '3' }];
+};
+// The build runs this once per URL, so each baked page gets its own <head>.
+export const generateMetadata: Toil.GenerateMetadata = ({ params }) => ({
+  title: `Blog post ${params.id}`,
+  description: `Reading blog post ${params.id}.`,
+});
+export default function BlogPost() {
+  const { id } = Toil.useParams();
+  return <h1>Blog post {id}</h1>;
+}
+```
+At build, that writes `blog/1/index.html`, `blog/2/index.html`, and `blog/3/index.html`, each with its own title and description in the raw HTML (so a crawler that does not run JavaScript sees them), and all three land in `sitemap.xml`. The param values also feed the route's `loader`, so per-URL metadata can depend on real data.
+`generateStaticParams` is async-friendly (return a promise if you fetch the id list first) and completely opt-in: a dynamic route without it is untouched, and the whole pass is skipped when your project has no `seo` config. A catch-all segment (`[...slug]`) takes an array value: `{ slug: ['2024', 'hello'] }` fills the URL as `2024/hello`.
+> Two things this is **not**: it is build-time prerender of the `<head>`, not edge SSR of the body. To also serve real body HTML for these URLs on first paint, add `export const ssr = true` as well (see below). And to make a dynamic route show up in the on-site [search index](./search.md) even though its title is dynamic, export `searchHints` (covered there), which is separate from `generateStaticParams`.
+## Edge SSR (`ssr = true`)
+For a route where you want the body content visible on first paint (a marketing page, an article), add one line:
+```tsx
+// client/routes/index.tsx
+export const ssr = true;
+export default function Home() {
+  return (
+    <section className="hero">
+      <h1>Welcome</h1>
+    </section>
+  );
+}
+```
+Now the Dacely edge sends a real, filled-in first paint for that page, and the browser hydrates it. The user sees content immediately, and React takes over without redrawing anything.
+### How it works, in brief
+toiljs does something clever to keep SSR cheap. It does not re-run React on the server for every request. Instead, at build time it renders the page once into a **template**: the static HTML with the dynamic bits punched out into named holes. Then, per request, your compiled backend fills only the hole values (a small list of "slot 3 = this text"), and the edge splices those values into the pre-baked template. The result is real first-paint HTML produced about as fast as serving a static file.
+```mermaid
+sequenceDiagram
+    participant B as Build
+    participant Edge as Dacely edge
+    participant U as Browser
+    B->>Edge: prebuilt template (HTML with holes) + a coherence hash
+    U->>Edge: GET / (ssr route)
+    Edge->>Edge: run the wasm render -> small "hole values" list
+    Edge->>Edge: splice values into the template
+    Edge-->>U: real first-paint HTML
+    Note over U: Content is visible immediately
+    U->>Edge: fetch JS + route chunk
+    Note over U: React hydrates: attaches to the existing HTML
+    Note over U: Page is interactive; no redraw, no flash
+```
+For SSR to hydrate cleanly, the HTML the server produced and the HTML the browser would produce must match byte-for-byte. toiljs guarantees this by escaping hole values exactly as React does and by carrying a hash that ties the running backend to the exact template it was built against. Authoring the server side of an SSR route (the hole markers in the page and the matching `render` function in `server/`) is a deeper topic that lives with the [backend](../backend/README.md). For most pages you only need `export const ssr = true` and to keep the page "SSR-safe" (below).
+### Authoring an SSR route
+`export const ssr = true` is all you need for a page whose body is fully static. The moment the body has a **dynamic bit** (a value that changes per request: a name from the URL, a list from a loader, a chunk of user HTML), you have to tell the build *where* that dynamic bit lives, so it can be punched out into a hole. You do that by wrapping the dynamic value in a **hole marker**.
+Why is this necessary? The build renders your page once into a template. It cannot guess which `{expression}` in your JSX is a per-request value and which is a constant, so it does not try: any dynamic content you leave unwrapped gets frozen into the template as whatever value it happened to have during that one build render, and it will never update per request. The markers are the explicit "fill this in later" signal.
+The markers live on the `Toil` global (so you do not import them), and they are **transparent in the browser**: `<Toil.Hole>` just renders its children, `<Toil.Repeat>` just maps its rows. They only behave differently during the build render, so your client-side app runs exactly as written.
+| Marker | Use it for | Shape |
+| --- | --- | --- |
+| `Toil.Hole` | A single dynamic **text** value. | JSX element with `id` + children |
+| `Toil.Repeat` | A **list**: a row template repeated over an `each` array. | JSX element with `id` + `each` + a render function |
+| `Toil.RawHtml` | A block of **pre-rendered HTML** you trust (Markdown you rendered, say). | JSX element with `id` + `html` (+ optional `as`) |
+| `Toil.attr` | A dynamic value in **attribute position** (an `href`, a `class`). | a **function** you call inside the attribute |
+| `Toil.Island` | Content that must render **only in the browser** (the escape hatch). | JSX element with children |
+`Toil.attr` is a function rather than an element because an attribute is not a child node, so it cannot be a JSX element. You call it right where the value goes.
+Here is a full SSR route: a blog post whose title, body HTML, tag list, and author link all come from the route's `loader`.
+```tsx
+// client/routes/blog/[id].tsx
+export const ssr = true;
+// Runs on the server for the first paint, then again on the client to reproduce
+// the same data so hydration matches (see "Keeping a route SSR-safe" below).
+export const loader = async ({ params }: Toil.LoaderArgs) => {
+  // Illustrative shape: { title, bodyHtml, 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 block of trusted, pre-rendered HTML. */}
+      <Toil.RawHtml id="body" html={post.bodyHtml} />
+      {/* 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>
+  );
+}
+```
+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 sample data with one or more items (an empty `each` gives it nothing to capture).
+- **`Toil.RawHtml` renders inside a wrapper element** (a `<div>` by default; pass `as="section"` to change the tag), and you own sanitising that HTML, exactly like React's `dangerouslySetInnerHTML`.
+Anything that genuinely cannot run on the server (it reads `window`, calls `Date.now()`, or depends on the live URL) goes inside a `Toil.Island`, which renders nothing on the server and reveals its children only after hydration:
+```tsx
+<Toil.Island>
+  <LiveClock />
+</Toil.Island>
+```
+This is the flow from your marked-up JSX to the first-paint HTML:
+```mermaid
+flowchart TD
+  A["Your SSR route JSX<br/>dynamic bits wrapped in Toil.Hole / Repeat / RawHtml / attr"] --> B["Build render (once, in sentinel mode)"]
+  B --> C[".tmpl: static HTML with numbered holes"]
+  B --> D[".slots: which hole is text / raw / attr / repeat"]
+  B --> E["Slot enum + coherence HASH"]
+  C --> F["Deployed to the Dacely edge"]
+  E --> G["Compiled backend render(req)"]
+  G -->|"per request: fill only the hole values"| F
+  D --> G
+  F -->|"splice values into the template"| H["First-paint HTML to the browser"]
+```
+#### Advanced: hand-writing the server `render`
+You almost never do this. The compiler generates the server `render(req)` for an SSR route from the JSX above, so the hole ids line up automatically. But the server side is backed by a plain, hand-writable API for the rare case you need full control (an unusual template, or a value the compiler cannot derive). Your `render` returns a `SlotValues` object, filled with:
+- `setText(slot, value)`: a text hole (React-escaped for you).
+- `setRaw(slot, html)`: a raw-HTML hole (you own sanitising).
+- `setAttr(slot, value)`: an attribute hole.
+- `setRepeat(slot, rows)`: a repeat region, with the rows assembled through an `HtmlBuilder` (chain `.raw(...)`, `.text(...)`, `.attr(...)`).
+- `setHeader(name, value)`, `setTitle(title)`, and `setStatus(code)`: response headers, a per-request `<title>`, and the status code.
+`SlotValues` and `HtmlBuilder` live in `server/runtime/ssr/slots.ts`. The `setTitle` helper is the supported way to give an SSR page a data-driven `<title>` (a blog post's real title from its loader), overriding the one baked into the template. This is server (backend) code, so it belongs with the [backend](../backend/README.md).
+### Keeping a route SSR-safe
+Server rendering happens where there is no browser: no `window`, no `document`, no mouse. So an SSR route (and every layout above it) must render without touching browser-only APIs during that first render. Anything that must run only in the browser (reading `window`, using `Date.now()`, or router hooks that need the live URL) goes inside an **island**, a marker that renders nothing on the server and appears only after hydration.
+If a route or one of its layouts throws while rendering on the server, toiljs does not ship a broken page. It **skips SSR for that route at build with a warning** and falls back to plain client rendering. So adding `ssr = true` is always safe: worst case you get client rendering plus a build warning telling you what to move into an island.
+### Suspense markers and self-healing hydration
+Under the hood the client wraps each route and layout in React `Suspense` boundaries that line up with what the server emitted, so hydration matches. If hydration ever does mismatch (the server HTML and the client's idea of the page disagree), React does the safe thing: it discards the server markup for that part and re-renders it on the client. You get a correct page either way. The cost of a mismatch is a small flash and some wasted work, not a broken page, which is why the guidance above (keep it SSR-safe, put browser-only bits in islands) is about smoothness, not correctness.
+## Known SSR limitations
+Be aware of these honest gaps as of today:
+- **`template.tsx` is not server-rendered.** A `template.tsx` wrapper (the re-mounting cousin of a layout) is not part of the SSR output. A route under one still works: hydration self-heals to client rendering for that part.
+- **Parallel slots (`@slot`) are not server-rendered.** Slot content (including intercepted modals) renders on the client after hydration, not in the first paint. Since slots are typically modals and overlays that appear on interaction, this is rarely a problem.
+- **Islands have no first paint or SEO.** That is by design: an island is your "client only" escape hatch, so anything inside it is intentionally absent from the server HTML and from what crawlers see.
+- **The client loader must reproduce the server's data.** For a hole whose value comes from the request (a query param), the route's client `loader` has to derive the same value the server used, or hydration will re-render that part. If the client cannot reproduce a value, put that content in an island.
+## Which mode should I use?
+- **Interactive, per-user page** (dashboard, settings): client rendering. Do nothing.
+- **Public page that needs correct link previews and titles**: you already have build-time prerender. Do nothing extra.
+- **Public page that should also show its content instantly on first load** (landing page, blog post, docs): add `export const ssr = true` and keep it SSR-safe.
+## Related
+- [Backend overview](../backend/README.md): where the server-side `render` for an SSR route lives.
+- [Metadata and SEO](./metadata.md): what gets baked into the `<head>`.
+- [Routing](./routing.md): layouts, templates, and slots.
+- [Fetching data](./data-fetching.md): loaders and how their data seeds hydration.

package/docs/frontend/routing.md ADDED Viewed

@@ -0,0 +1,344 @@
+# Routing
+toiljs uses file-based routing: every file under `client/routes/` becomes a page, and its path on disk becomes its URL. There is no route config to maintain, you create a file and the route exists.
+This page is about **frontend** (browser) routing: the pages a user visits and how they navigate between them. Your **backend** HTTP endpoints use a different, decorator-based system (see [HTTP routes](../backend/rest.md)).
+## The basic idea
+Drop a React component at `client/routes/<something>.tsx`, `export default` it, and it is a page. The default export is the component that renders at that URL.
+```tsx
+// client/routes/about.tsx  ->  /about
+export default function About() {
+  return (
+    <main>
+      <h1>About us</h1>
+    </main>
+  );
+}
+```
+Run `toiljs dev`, open `/about`, and it is there. Nothing else to register.
+## How a file path becomes a URL
+The compiler scans `client/routes/` and turns each file into a URL pattern with a small set of rules. Here is the whole mapping in one table:
+| File under `client/routes/` | URL | What it is |
+| --- | --- | --- |
+| `index.tsx` | `/` | The home page. |
+| `about.tsx` | `/about` | A static page. |
+| `blog/index.tsx` | `/blog` | An index inside a folder. |
+| `blog/[id].tsx` | `/blog/:id` | A **dynamic** page (one param). |
+| `docs/[...slug].tsx` | `/docs/*` | A **catch-all** (one or more segments). |
+| `files/[[...slug]].tsx` | `/files` and `/files/*` | An **optional** catch-all (zero or more). |
+| `(marketing)/pricing.tsx` | `/pricing` | A **route group**: parens add no URL segment. |
+| `@modal/photo/[id].tsx` | (a parallel slot, see below) | A named **slot**. |
+The rules, spelled out:
+- **`index`** means "the folder itself", so `blog/index.tsx` is `/blog`, and the top `index.tsx` is `/`.
+- **Square brackets** mark a dynamic segment. `[id]` captures one path segment into a param named `id`. You read it with `Toil.useParams()`.
+- **`[...name]`** is a catch-all: it captures the rest of the path (one segment or more) as a single `/`-joined string.
+- **`[[...name]]`** is an *optional* catch-all: like `[...name]`, but it also matches the bare parent URL with nothing after it (the param is then absent).
+- **Parentheses** like `(marketing)` create a **route group**: a folder that organizes files without adding anything to the URL. Handy for grouping pages that share a layout.
+```mermaid
+flowchart LR
+    A["client/routes/blog/[id].tsx"] -->|scan| B["/blog/:id"]
+    B -->|visit /blog/42| C["params = { id: '42' }"]
+    C -->|Toil.useParams| D["render Blog post 42"]
+```
+### Dynamic pages: reading the param
+A file named with brackets gets its captured values from `Toil.useParams()`:
+```tsx
+// client/routes/blog/[id].tsx  ->  /blog/:id
+export default function BlogPost() {
+  const { id } = Toil.useParams();
+  return (
+    <main>
+      <h1>Blog post {id}</h1>
+    </main>
+  );
+}
+```
+Visiting `/blog/42` renders "Blog post 42". Param values are URL-decoded for you.
+For a catch-all, the param is the whole tail joined with slashes:
+```tsx
+// client/routes/docs/[...slug].tsx  ->  /docs/*slug
+export default function Docs() {
+  const { slug } = Toil.useParams();
+  // /docs/getting-started/install  ->  slug === "getting-started/install"
+  return <main>{slug}</main>;
+}
+```
+An optional catch-all (`[[...slug]]`) matches the bare parent too, so `slug` can be empty:
+```tsx
+// client/routes/files/[[...slug]].tsx  ->  matches /files AND /files/a/b
+export default function Files() {
+  const { slug } = Toil.useParams();
+  // "/files" -> slug is undefined; "/files/a/b" -> slug === "a/b"
+  return <main>{slug ?? '(the base /files page)'}</main>;
+}
+```
+### When two routes could match
+If a URL could match more than one pattern, toiljs picks the most specific one. Static segments win over dynamic (`:id`) segments, which win over catch-alls (`*slug`), and deeper routes win over shallower ones. So `/blog/new` prefers a literal `blog/new.tsx` over `blog/[id].tsx` if both exist. You do not configure this, it just does the intuitive thing.
+## Special files
+Some filenames are not pages, they are helpers that wrap or replace pages. They live alongside your routes and are never matched as a URL:
+| Filename | Role |
+| --- | --- |
+| `layout.tsx` | Wraps the pages in its folder (and below). **Persists** across navigation. |
+| `template.tsx` | Like a layout, but **re-mounts** on every navigation within it. |
+| `loading.tsx` | Shown while the page (and its data) is loading. |
+| `error.tsx` | Shown when the page throws (an error boundary). |
+| `global-error.tsx` | The last-resort error boundary, wraps even the root layout. |
+| `404.tsx` (or `not-found.tsx`) | Shown when no route matches. |
+### Layouts
+A `layout.tsx` receives the page (or nested layout) as `children` and renders around it. The root `client/layout.tsx` wraps every page. It is the natural home for your header, footer, and site-wide `<head>` defaults:
+```tsx
+// client/layout.tsx
+import type { ReactNode } from 'react';
+import Header from './components/Header';
+import Footer from './components/Footer';
+export default function Layout({ children }: { children?: ReactNode }) {
+  return (
+    <div className="app">
+      <Header />
+      <main className="content">{children}</main>
+      <Footer />
+    </div>
+  );
+}
+```
+Layouts nest by folder. A `client/routes/dashboard/layout.tsx` wraps every page under `/dashboard`, inside the root layout. Because a layout **persists** across navigations, state inside it (a sidebar's open/closed flag, a scroll position) survives when you move between its child pages.
+### Templates vs layouts
+A `template.tsx` looks like a layout but does the opposite on navigation: it **re-mounts** every time you move to a new page within it. Use a layout when state should persist (a nav sidebar), and a template when it should reset (an enter animation that should replay, or a counter that should start fresh per page).
+### Loading and error states
+Put a `loading.tsx` next to a page (or in a folder) and it shows automatically while that page's chunk and its `loader` data are still resolving:
+```tsx
+// client/routes/dashboard/loading.tsx
+export default function Loading() {
+  return <p>Loading dashboard...</p>;
+}
+```
+Put an `error.tsx` there and it catches any error the page throws, showing a fallback instead of a blank screen. `global-error.tsx` sits outside the root layout, so it catches errors thrown by the layout itself.
+## Route groups: shared layout, no URL change
+Wrap a folder name in parentheses to group files without changing their URLs. This is the trick for "these three pages share one layout, but I do not want a `/legal` prefix":
+```
+client/routes/
+  (legal)/
+    layout.tsx      -> wraps both pages below
+    privacy.tsx     -> /privacy   (NOT /legal/privacy)
+    terms.tsx       -> /terms
+```
+## Parallel slots (`@slot`) and intercepting routes
+This is an advanced feature; skip it until you need a modal that keeps the page behind it alive.
+A folder starting with `@`, like `@modal`, is a **named slot**. It is a whole second route tree that matches the current URL *independently* of the main page, and renders wherever you place a `<Toil.Slot>`:
+```tsx
+// client/routes/gallery/layout.tsx
+import type { ReactNode } from 'react';
+export default function GalleryLayout({ children }: { children?: ReactNode }) {
+  return (
+    <div>
+      {children}
+      <Toil.Slot name="modal" />   {/* renders the @modal slot for this URL */}
+    </div>
+  );
+}
+```
+The `@` folder adds nothing to the URL; it just says "these routes fill the slot named `modal`". A slot with no match renders nothing (or a `fallback` you pass).
+An **intercepting route** is a slot route whose folder name starts with `(.)`, `(..)`, or `(...)`. It hijacks a *soft* (in-app) navigation to another URL and renders that URL's content inside the slot instead, while the main page stays mounted behind it. That is exactly how a "click a photo, see it in a modal over the gallery" pattern works, where reloading the page (a hard load) shows the full photo page instead:
+```
+client/routes/gallery/
+  index.tsx                     -> /gallery
+  photo/[id].tsx                -> /gallery/photo/:id  (full page, on hard load)
+  @modal/(.)photo/[id].tsx      -> fills @modal on a soft click to that URL
+```
+The `(.)` markers mean: `(.)` same level, `(..)` up one level, `(...)` from the routes root. This tells the interceptor which real URL it is standing in for.
+## Links and navigation
+### `Toil.Link`
+Use `Toil.Link` instead of a plain `<a>` for in-app links. It navigates client-side (no full page reload), and prefetches the target route's code on hover or focus so the click feels instant:
+```tsx
+<Toil.Link href="/about">About</Toil.Link>
+```
+`Link` accepts every normal anchor attribute (`className`, `target`, `rel`, `download`, and so on), plus a few toiljs controls:
+| Prop | Default | What it does |
+| --- | --- | --- |
+| `replace` | `false` | Replace the current history entry instead of pushing a new one. |
+| `scroll` | `true` | Scroll to the top after navigating. |
+| `prefetch` | `true` | Prefetch the route on hover/focus. Set `false` to opt out. |
+`Link` is smart about when *not* to intercept: external URLs, `target="_blank"`, `download`, `#hash` links, and modified clicks (Ctrl/Cmd/middle-click) all fall through to normal browser behavior. The `href` is typed to your project's real routes, so a typo is a compile error.
+### `Toil.NavLink` and active state
+`NavLink` is a `Link` that knows whether it points at the current page. When active it adds the class `active` (configurable) and `aria-current="page"`. This is what you want for a navigation bar that highlights the current section:
+```tsx
+<Toil.NavLink href="/blog" activeClassName="is-current">
+  Blog
+</Toil.NavLink>
+```
+You can also drive `className`, `style`, or `children` from the active state with a function:
+```tsx
+<Toil.NavLink href="/blog" className={({ isActive }) => (isActive ? 'on' : 'off')}>
+  Blog
+</Toil.NavLink>
+```
+By default a parent link is active for its sub-paths too (`/blog` is active on `/blog/42`). Pass `end` to require an exact match:
+```tsx
+<Toil.NavLink href="/" end>Home</Toil.NavLink>
+```
+### Navigating in code
+For navigation that is not a link (after a form submit, a redirect), use the router hook or the free `navigate` function:
+```tsx
+export default function Login() {
+  const router = Toil.useRouter();
+  const onDone = () => router.push('/dashboard');
+  // router.replace(href), router.back(), router.forward(), router.refresh()
+  return <button onClick={onDone}>Continue</button>;
+}
+```
+`useRouter()` returns a handle with `push`, `replace`, `back`, `forward`, `refresh` (re-run the current page's data loader), `revalidate` (refetch data), and `prefetch`.
+If you just need to jump to a URL and nothing else, `Toil.useNavigate()` returns the bare `navigate(href, options)` function:
+```tsx
+export default function Login() {
+  const navigate = Toil.useNavigate();
+  return (
+    <button onClick={() => navigate('/dashboard', { replace: true })}>
+      Continue
+    </button>
+  );
+}
+```
+The options are `{ replace?: boolean; scroll?: boolean }`, the same two controls `Toil.Link` exposes above. The same function is also available free of any hook as `Toil.navigate(href, options)`, which is handy in code that is not a React component (a plain event handler, a utility module).
+### Typed hrefs and the `href()` escape hatch
+Every href you pass to `Toil.Link`, `navigate`, or `router.push` is type-checked against your project's real routes. The compiler scans `client/routes/` and generates a file called `toil-routes.d.ts` that registers the union of your route paths (it fills in the `Href` type). So a typo is a compile error before you ever run the app:
+```tsx
+<Toil.Link href="/abuot">About</Toil.Link>
+// ^ Type error: "/abuot" is not assignable to type 'Href'. (No such route.)
+```
+Dynamic routes show up in that union as template-literal types. A file at `client/routes/blog/[id].tsx` contributes the type `` `/blog/${string}` ``, so a link built with one interpolation usually still checks:
+```tsx
+<Toil.Link href={`/blog/${post.id}`}>Read</Toil.Link>   // fine: matches `/blog/${string}`
+```
+The catch is a URL assembled from several data pieces (or one TypeScript cannot prove the shape of): it is typed as a plain `string`, and `string` is not assignable to `Href`, so you get a type error:
+```tsx
+const cat = product.category;   // string
+const slug = product.slug;      // string
+navigate(`/${cat}/${slug}`);
+// ^ Argument of type 'string' is not assignable to parameter of type 'Href'.
+```
+The escape hatch is `Toil.href()`. It takes a `string` and asserts it is a valid href, returning the `Href` type the navigation APIs expect. Use it right at the call site once you are sure the path is a real route:
+```tsx
+navigate(Toil.href(`/${cat}/${slug}`));                 // asserted valid
+<Toil.Link href={Toil.href(`/${cat}/${slug}`)}>Open</Toil.Link>;
+```
+`href()` is a pure type assertion (it returns the string unchanged), so reach for it only when the type-check is in your way, not to paper over a genuine typo. Before the routes are generated (a fresh project, the first build), `Href` is just `string`, so nothing complains until `toil-routes.d.ts` exists.
+### Reading the current location
+A handful of hooks let a component read where it is:
+| Hook | Returns |
+| --- | --- |
+| `Toil.useParams()` | The dynamic route params, e.g. `{ id }`. |
+| `Toil.usePathname()` | The current path, e.g. `"/blog/42"`. |
+| `Toil.useLocation()` | The current path, e.g. `"/blog/42"` (an alias of `usePathname()`). |
+| `Toil.useSearchParams()` | The query string as a `URLSearchParams`. |
+| `Toil.useNavigationPending()` | `true` while a navigation is in flight (for a loading bar). |
+## Loading data for a route
+A route file can `export const loader` alongside its component. The loader runs on navigation, in parallel with loading the page's code, and the page reads the result with `Toil.useLoaderData`. This keeps data fetching out of `useEffect` and lets `loading.tsx` show while it runs. Loaders are covered in depth in [Fetching data](./data-fetching.md):
+```tsx
+export const loader = async ({ params }: Toil.LoaderArgs) => {
+  const post = await Server.REST.blog.get({ params: { id: params.id } });
+  return post;
+};
+export default function BlogPost() {
+  const post = Toil.useLoaderData<typeof loader>();
+  return <article><h1>{post.title}</h1></article>;
+}
+```
+## Gotchas
+- **`export default` is required.** A route file without a default-exported component is not a page. The special files (`layout`, `loading`, and so on) also use the default export.
+- **Reserved filenames are not pages.** `layout.tsx`, `template.tsx`, `loading.tsx`, `error.tsx`, `global-error.tsx`, `404.tsx`, and `not-found.tsx` are helpers, not routes. Do not name a real page one of these.
+- **Use `Toil.Link`, not `<a>`, for in-app links.** A plain `<a href="/about">` triggers a full page reload, throwing away the SPA speed. Reserve `<a>` for external links.
+- **Params are always strings.** `useParams()` gives you `{ id: "42" }`, not a number. Convert if you need a number.
+- **Route groups and slots are invisible in the URL.** `(group)` and `@slot` folders never appear in the address bar. If a URL looks wrong, check for a stray bracket or paren in the file path.
+## Related
+- [Rendering and SSR](./rendering.md): what renders on the server versus the browser.
+- [Fetching data](./data-fetching.md): loaders, the typed backend clients, and forms.
+- [Metadata and SEO](./metadata.md): set the title and tags per route.
+- [Backend HTTP routes](../backend/rest.md): the separate, decorator-based server routing.