toiljs 0.0.96 → 0.0.97

package/docs/README.md

@@ -71,10 +71,11 @@ Run `toiljs dev`, open the browser, and both are live with hot reload. That is t
 
 **Build the frontend**
 - [Frontend overview](./frontend/README.md), [Routing](./frontend/routing.md),
+  [Navigation](./frontend/navigation.md), [Components](./frontend/components.md),
   [Rendering and SSR](./frontend/rendering.md), [Styling](./frontend/styling.md),
   [Images](./frontend/images.md), [Metadata and SEO](./frontend/metadata.md),
   [Fetching data](./frontend/data-fetching.md), [Scripts](./frontend/scripts.md),
-  [Search](./frontend/search.md).
+  [Search](./frontend/search.md), [The Toil global (reference)](./frontend/toil-global.md).
 
 **Build the backend**
 - [Backend overview](./backend/README.md), [HTTP routes (`@rest`)](./backend/rest.md),

package/docs/frontend/README.md

@@ -84,7 +84,9 @@ The same fast data utilities your backend uses are available in client code too,
 
 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.
+- **[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.
@@ -92,6 +94,7 @@ Read them in roughly this order:
 - **[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
 

package/docs/frontend/components.md

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

package/docs/frontend/navigation.md

@@ -0,0 +1,296 @@
+# Navigation
+
+Once your files are turned into URLs (see [Routing](./routing.md)), you need a way to move between them. This page is about that half: the links, hooks, and functions that navigate a user from one page to the next without a full reload, keep the current section highlighted, prefetch what is coming, and restore scroll. Everything here lives on the global `Toil` object, so route files need no imports for the common cases.
+
+Routing is "file to URL"; navigation is "get me to that URL". If you are looking for how a file becomes a page, or for dynamic params and layouts, that is the [Routing](./routing.md) page.
+
+## `Toil.Link`
+
+`Toil.Link` is the client-side replacement for a plain `<a>`. It navigates in place (no full page reload), and it prefetches the target route's chunk on hover or focus, so the click feels instant:
+
+```tsx
+<Toil.Link href="/about">About</Toil.Link>
+```
+
+`Link` accepts every standard anchor attribute (`className`, `style`, `target`, `rel`, `download`, `referrerPolicy`, `ref`, `data-*`, `aria-*`, event handlers, and so on), plus a few toiljs controls:
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `href` | `Href` | (required) | Destination, typed to your project's real routes (a typo is a compile error). |
+| `replace` | `boolean` | `false` | Replace the current history entry instead of pushing a new one. |
+| `scroll` | `boolean` | `true` | Scroll to the top after navigating. `false` keeps the current position. |
+| `prefetch` | `boolean` | `true` | Prefetch the route chunk on hover/focus. `false` opts this link out. |
+
+### When `Link` does not intercept
+
+`Link` is deliberate about when to hand a click back to the browser. It only intercepts a plain, same-origin, left-click. All of these fall through to native browser behavior instead:
+
+- **External URLs** (a different origin), and opaque targets like `mailto:` or `tel:`.
+- **`target` other than `_self`** (for example `target="_blank"`, a new tab).
+- **`download`** links.
+- **In-page `#hash`-only** links.
+- **Modified clicks**: middle-click or any click with Ctrl, Cmd (Meta), Shift, or Alt held (so "open in new tab" keeps working).
+
+Because of this, you can point a `Link` at an external site or a download and it behaves exactly like an `<a>` would, no special-casing on your part. For genuinely external links a plain `<a>` is still fine; reach for `Link` when the target is one of your own routes.
+
+## `Toil.NavLink` and active state
+
+`Toil.NavLink` is a `Link` that knows whether it points at the current page. When active it adds a class (`active` by default) and sets `aria-current="page"`, which is exactly what a navigation bar wants for highlighting the current section. It inherits Link's full anchor API and its prefetching.
+
+On top of `LinkProps` it adds:
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `end` | `boolean` | `false` | Require an exact match. Without it, a parent link is active for its sub-paths. |
+| `activeClassName` | `string` | `'active'` | The class added when active (used with a string `className`). |
+| `className` | `string \| (state) => string \| undefined` | (none) | A string, or a function of `{ isActive }`. |
+| `style` | `CSSProperties \| (state) => CSSProperties \| undefined` | (none) | A style object, or a function of `{ isActive }`. |
+| `children` | `ReactNode \| (state) => ReactNode` | (none) | Content, or a function of `{ isActive }`. |
+
+A simple nav bar with string classes:
+
+```tsx
+// client/components/Nav.tsx
+export default function Nav() {
+  return (
+    <nav>
+      <Toil.NavLink href="/" end>Home</Toil.NavLink>
+      <Toil.NavLink href="/blog">Blog</Toil.NavLink>
+      <Toil.NavLink href="/about" activeClassName="is-current">About</Toil.NavLink>
+    </nav>
+  );
+}
+```
+
+By default a parent link stays active for its sub-paths, so `/blog` is active on `/blog`, `/blog/42`, and `/blog/42/edit`. Pass `end` to require an exact match. This matters most for the home link: `/` would otherwise be active on every page, so `Home` almost always wants `end`.
+
+The function forms let the active state drive `className`, `style`, or `children` directly. Each receives a `{ isActive }` object:
+
+```tsx
+<Toil.NavLink href="/blog" className={({ isActive }) => (isActive ? 'tab on' : 'tab')}>
+  {({ isActive }) => <span>{isActive ? '• ' : ''}Blog</span>}
+</Toil.NavLink>
+```
+
+## Navigating in code
+
+Not every navigation is a click. After a form submit, a login, or a `fetch`, you often want to move the user yourself. There are three ways, from smallest to fullest.
+
+### `Toil.useNavigate()`
+
+The hook 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 `NavigateOptions`, the same two controls `Link` exposes:
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `replace` | `boolean` | `false` | Replace the current history entry instead of pushing. |
+| `scroll` | `boolean` | `true` | Scroll to top after navigating. `false` keeps the position. |
+
+### `Toil.navigate` (outside React)
+
+The exact same function is available free of any hook as `Toil.navigate(href, options)`. Use it in code that is not a React component: a plain event handler, a utility module, or right after a `fetch` resolves:
+
+```tsx
+async function saveDraft(draft: Draft) {
+  await Server.REST.posts.create({ body: draft });
+  Toil.navigate('/posts');
+}
+```
+
+`Toil.back()`, `Toil.forward()`, and `Toil.refresh()` are the history counterparts, also callable from anywhere: `back` and `forward` step through history, and `refresh` re-renders the current route (re-running its loader for the current URL).
+
+### `Toil.useRouter()`
+
+For a full imperative handle, `useRouter()` returns a `RouterInstance`:
+
+```tsx
+export default function PostActions() {
+  const router = Toil.useRouter();
+  return (
+    <>
+      <button onClick={() => router.push('/blog/new')}>New post</button>
+      <button onClick={() => router.back()}>Back</button>
+      <button onClick={() => router.revalidate()}>Refresh data</button>
+    </>
+  );
+}
+```
+
+| Method | What it does |
+| --- | --- |
+| `push(href, options?)` | Navigate to `href`, pushing a new history entry (or replacing with `{ replace: true }`). |
+| `replace(href)` | Navigate to `href`, replacing the current history entry. |
+| `back()` | Go back one history entry. |
+| `forward()` | Go forward one history entry. |
+| `refresh()` | Re-render the current route and re-run its loader (clears all cached loader data). |
+| `revalidate(href?)` | Invalidate cached loader data and re-render so it refetches. No argument targets the active route; pass an `href` for a specific route. Use after a mutation. |
+| `prefetch(href)` | Warm a route's chunk ahead of navigation. |
+
+Reach for `revalidate()` after a write (you changed some data and want the current page's loader to refetch), and `refresh()` when you want a clean re-run of everything. `push`/`replace` are the imperative twins of a `Link` click.
+
+## Typed hrefs and the `href()` escape hatch
+
+Every `href` you pass to `Toil.Link`, `NavLink`, `navigate`, or `router.push` is type-checked against your project's real routes. The compiler scans `client/routes/` and generates a `toil-routes.d.ts` that narrows the `Href` type to the union of your actual paths, so a typo is a compile error before you 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 appear in that union as template-literal types, so a file at `client/routes/blog/[id].tsx` contributes `` `/blog/${string}` `` and a single interpolation still checks:
+
+```tsx
+<Toil.Link href={`/blog/${post.id}`}>Read</Toil.Link>   // fine
+```
+
+When a URL is assembled from several data pieces (or from values TypeScript cannot prove the shape of), it is typed as a plain `string`, and `string` is not assignable to `Href`. That is when you reach for `Toil.href()`, the escape hatch that asserts a runtime string is a valid href:
+
+```tsx
+const path = `/${product.category}/${product.slug}`;   // string
+Toil.navigate(Toil.href(path));                         // asserted valid
+<Toil.Link href={Toil.href(path)}>Open</Toil.Link>;
+```
+
+`href()` is a pure type assertion (it returns the string unchanged), so use it only when the type-check is genuinely in your way, not to paper over a real 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. Each re-reads on every navigation, so a component using one re-renders when the location changes:
+
+| Hook | Returns |
+| --- | --- |
+| `Toil.usePathname()` | The current pathname, e.g. `"/blog/42"`. |
+| `Toil.useLocation()` | The current pathname (an alias of `usePathname()`). |
+| `Toil.useParams<T>()` | The dynamic route params, e.g. `{ id }` for `/blog/[id]`. |
+| `Toil.useSearchParams()` | The query string as a `URLSearchParams`. |
+| `Toil.useNavigationPending()` | `true` while a navigation is in flight (started but not committed). |
+
+`useNavigationPending()` is what you wire a top loading bar to. It flips to `true` when a navigation begins and back to `false` once the new route commits:
+
+```tsx
+// client/components/ProgressBar.tsx
+export default function ProgressBar() {
+  const pending = Toil.useNavigationPending();
+  return <div className="progress" data-active={pending} />;
+}
+```
+
+`useSearchParams()` gives you a live `URLSearchParams`, so a filtered list reads its state from the URL:
+
+```tsx
+export default function Results() {
+  const params = Toil.useSearchParams();
+  const q = params.get('q') ?? '';
+  return <p>Results for {q}</p>;
+}
+```
+
+## Prefetching
+
+toiljs prefetches routes before you navigate to them, so a click resolves with nothing left to download. There are two intents, both automatic:
+
+- **Hover / focus intent.** When you hover or focus a link that points at a known internal route, toiljs warms both its route chunk and its loader data, so the actual click can commit right away.
+- **Viewport intent.** As a link scrolls into view (or within about 200px of it), its route chunk is warmed. Links added later by client navigation are picked up automatically.
+
+Prefetching is best-effort and cheap: each route loads at most once, a failed prefetch is forgotten (so the real navigation can retry and surface the error), and new-tab / download / opted-out links are skipped. It is also **skipped entirely when the browser signals data-saver** (or reports a 2g-class connection), so you never spend a metered user's bandwidth on speculation.
+
+Opt a single link out with `prefetch={false}`, which emits a `data-no-prefetch` attribute the prefetcher respects:
+
+```tsx
+<Toil.Link href="/huge-report" prefetch={false}>Annual report</Toil.Link>
+```
+
+You can also warm a route yourself, for example right before an imperative `navigate`, with the standalone `Toil.prefetch(href)`:
+
+```tsx
+<button
+  onPointerEnter={() => Toil.prefetch('/dashboard')}
+  onClick={() => Toil.navigate('/dashboard')}>
+  Open dashboard
+</button>
+```
+
+## Scroll restoration
+
+toiljs manages scroll for you (it switches off the browser's automatic restoration and does the intuitive thing per navigation type):
+
+- **A push navigation** (a `Link` click, `navigate`, `router.push`) **scrolls to the top** of the new page.
+- **Back and forward restore** the scroll position you had on that entry, so returning to a long list lands you where you were.
+- **A `#hash` target** scrolls that element into view instead of jumping to the top.
+
+To keep the current scroll on a push navigation, set `scroll={false}` on the `Link` (or `{ scroll: false }` in `NavigateOptions`). This is handy for tab bars or filters that change the URL but should not yank the viewport:
+
+```tsx
+<Toil.Link href="/settings/billing" scroll={false}>Billing</Toil.Link>
+```
+
+```tsx
+navigate('/settings/billing', { scroll: false });
+```
+
+## Animated transitions
+
+Two optional effects can animate navigations. Both are **off by default** and are normally enabled from `toil.config.ts`, not in code:
+
+```ts
+// toil.config.ts
+export default {
+  client: {
+    viewTransitions: true, // browser View Transitions API (a crossfade between pages)
+    transitions: true,     // React transition: keep the old page visible while the next loads
+  },
+};
+```
+
+`viewTransitions` uses the browser's View Transitions API to crossfade the old and new page (and it respects `prefers-reduced-motion`, animating nothing for users who ask for less motion). `transitions` wraps each navigation in a React transition, keeping the current page on screen while the next route's loader runs, instead of showing its `loading.tsx` right away (smoother, but you trade away the immediate loading state).
+
+Config is the normal way to turn these on. For a manual override at runtime, the setters are `Toil.setViewTransitions(enabled)` and `Toil.setTransitions(enabled)`:
+
+```tsx
+Toil.setViewTransitions(true);
+Toil.setTransitions(false);
+```
+
+You rarely need the setters; prefer the config keys unless you are toggling an effect dynamically.
+
+## Types
+
+Almost everything on this page is a value on the global `Toil` object, so you call it with no import (`Toil.Link`, `Toil.navigate`, `Toil.useRouter`, and so on). A few of the **types**, though, are not namespaced under `Toil`, so if you want to annotate a prop or a variable you import them from `toiljs/client`:
+
+```tsx
+import type {
+  LinkProps,
+  NavLinkProps,
+  NavLinkState,
+  NavigateOptions,
+  RouterInstance,
+} from 'toiljs/client';
+```
+
+For example, a component that forwards `Link` props, or a helper typed against the router handle:
+
+```tsx
+import type { RouterInstance } from 'toiljs/client';
+
+function logoutThenGo(router: RouterInstance) {
+  router.replace('/login');
+}
+```
+
+## Related
+
+- [Routing](./routing.md): how files become URLs, dynamic params, layouts, and templates.
+- [Fetching data](./data-fetching.md): loaders, the typed backend clients, forms, and revalidation.
+- [Rendering and SSR](./rendering.md): what renders on the server versus the browser, and how hydration fits with client navigation.

package/docs/frontend/routing.md

@@ -195,6 +195,8 @@ The `(.)` markers mean: `(.)` same level, `(..)` up one level, `(...)` from the
 
 ## Links and navigation
 
+This is a quick tour. For the full treatment, programmatic navigation, typed hrefs, prefetching, scroll restoration, and animated transitions, see [Navigation](./navigation.md).
+
 ### `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: