---
title: 'Welcome'
slug: intro
ogTitle: 'Welcome to Mochi'
description: 'A lightweight, server-first Svelte 5 framework running on Bun that ships client-side JavaScript only for interactive islands.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import IslandsDemo from './_components/IslandsDemo.svelte';
  import ComparisonTable from './_components/ComparisonTable.svelte';
  import ExpandComparison from './_components/ExpandComparison.svelte';
</script>

# mochi

Mochi is a lightweight, server-first framework for [Svelte 5](https://svelte.dev/) on [Bun](https://bun.sh/) — it renders everything as plain HTML and ships JavaScript only for the components you mark as islands.

## Server-rendered, with island interactivity

The websites we visit on the web are mostly static — text, images and links. Only a handful of elements on any given page actually need to be interactive: a search box, a logged-in badge, a comments widget. Mochi reflects this at the core of its design. Mochi sites renders server-side as plain HTML; the interactive pieces are marked with a `mochi:*` directive — each one an _island_ — and ship JS embedded in that HTML.

Go ahead, try hydrating the page below and see which components will load JavaScript.

<IslandsDemo mochi:hydrate />

The header text, the main column, and the footer ship as HTML and stay that way. The badge and the sidebar nav are wrapped as islands — same SSR HTML on first paint, with JS attached on top. Everything else is zero-JS forever.

## Why would I consider Mochi over SvelteKit?

- **Faster sites.** Mochi ships zero client JavaScript by default. SvelteKit code-splits per route but still hydrates the entire page — even purely static content. Mochi only hydrates the components you explicitly mark as islands, which means less JS on first load, better bfcache behavior, and a natural fit for any site.
- **Performant hydration.** Avoid hydrating islands until the users scrolls into them with `mochi:hydrate:visible`. Or avoid hydrating at all if the user never scrolls down to that component. Your users will thank you for the faster experience.
- **Uses the platform.** Mochi ships with first-class support for View Transitions. No client side router, no state to keep track of between requests.
- **No heavy bundler (no Vite).** Uses the lighting-fast Bun bundler, which builds sites with hundreds of routes in seconds.
- **Real-time built in.** WebSockets and Server Sent Events are first-class route types — no extra packages or services required.

Want to know more? <ExpandComparison mochi:hydrate /> to see a full feature comparison.

<ComparisonTable mochi:hydrate collapsed />

<Callout type="info">

**Work in progress.** Mochi is a new framework and we're still working on features. Be one of the first ones to try it and report any issues you find!

</Callout>

## Community

Questions, bug reports, ideas, or just want to see what others are building? Join the [Mochi Discord](/discord/).

---
title: 'Your first Mochi app'
slug: your-first-mochi-app
description: 'Build your first page with serverProps, selective hydration, and server islands in four steps.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Your first Mochi app

Let's build a small app that exercises every server/client boundary you'll touch in real code. We'll put together a single `/hello` page in four steps, picking up one pillar at a time: [`serverProps`](/docs/defining-routes/) for loading data on every request, and [passing props to islands](/docs/island-props/) so a server-rendered parent can hand values to a hydrated child. Then we'll add [`mochi:hydrate`](/docs/selective-hydration/) for one interactive island while the rest stays zero-JS, and [`mochi:defer`](/docs/server-islands/) for a server island that renders separately from the main request.

By the end we'll have a greeting card with a live like button and a personalized welcome that loads in after the page renders.

### Set up

You'll need [Bun installed](https://bun.com/docs/installation) (>=1.4.0). Scaffold a new project with the official CLI and pick the **minimal** template when prompted:

```sh
bun create mochi@latest my-app
# choose: minimal
cd my-app
bun install
bun run dev
```

The scaffold gives you a working app on `http://localhost:3333`, with ESLint and Prettier preconfigured (`bun run lint`, `bun run format`; create-mochi 0.4.0+) — opt out with `--no-eslint` / `--no-prettier`. Its entry point is `src/index.ts`, which boots the server and declares your routes inline in the `Mochi.serve()` call:

```ts
// file: src/index.ts (scaffolded)
import { Mochi } from 'mochi-framework';

const PORT = Number(process.env.PORT) || 3333;

await Mochi.serve({
  port: PORT,
  development: process.env.NODE_ENV === 'development',
  routes: {
    '/': Mochi.page('./src/HelloWorld.svelte'),
  },
});
```

`src/index.ts` is the single bootstrap file — you'll edit its `routes` object next, then build the Svelte components it points at.

### Step 1 — Register the route

Now let's point `/hello` at a Svelte page and give it some data to render. Open `src/index.ts` and replace the scaffolded route inside `routes` with this one. `serverProps` is either a plain object or a `(req, params) => props` resolver — whatever it returns becomes the page component's `$props`.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  port: Number(process.env.PORT) || 3333,
  development: process.env.NODE_ENV === 'development',
  routes: {
    '/hello': Mochi.page('./src/Hello.svelte', {
      serverProps: () => ({
        siteName: 'Mochi',
        renderedAt: new Date().toISOString(),
      }),
    }),
  },
});
```

The resolver runs on every request, so each reload produces a fresh `renderedAt`. See [Defining routes](/docs/defining-routes/) for the full `serverProps` contract and the other `Mochi.*` route helpers. (The scaffolded `src/HelloWorld.svelte` is now unused — feel free to delete it.)

### Step 2 — The page component

Next, let's write the page itself. `Hello.svelte` stays server-only (all `Mochi.page()` entry components are server-only) — it consumes the `serverProps`, renders a static layout, and mounts the two child islands we'll build next. Notice that even though it imports two components that ship JavaScript, this file itself ships zero: the `mochi:` directives where we render the components decide what hydrates.

```svelte
<!-- file: src/Hello.svelte -->
<script lang="ts">
  import LikeButton from './LikeButton.svelte';
  import Visitor from './Visitor.svelte';

  let { siteName, renderedAt }: { siteName: string; renderedAt: string } = $props();
</script>

<h1>Welcome to {siteName}</h1>
<p>Rendered at <code>{renderedAt}</code></p>

<LikeButton mochi:hydrate initialLikes={42} />

<Visitor mochi:defer>
  <p>Loading…</p>
</Visitor>
```

The `initialLikes={42}` value crosses the server→client boundary. Mochi serializes island props with [`devalue`](/docs/island-props/), so `Date`, `Map`, `Set`, `BigInt`, and cyclic references all survive the trip — not just JSON-safe values.

<Callout type="warning">

Island props end up serialized into the HTML payload, so they're **visible to the client**. Never pass secrets, API keys, or session tokens this way.

</Callout>

### Step 3 — A hydrated island

Now let's give the user something to click! `LikeButton.svelte` is a normal Svelte 5 component — we accept `initialLikes` as a prop, keep a `$state` counter, and bump it on click.

```svelte
<!-- file: src/LikeButton.svelte -->
<script lang="ts">
  let { initialLikes }: { initialLikes: number } = $props();
  let likes = $state(initialLikes);
</script>

<button onclick={() => likes++}>♥ {likes}</button>
```

<Callout type="tip">

The `mochi:hydrate` directive lives **where we render the component** in `Hello.svelte`, not inside the island itself. The same component can be mounted statically elsewhere.

</Callout>

Reload the page in dev mode and you'll see Mochi's [debug bar](/docs/debug-bar/) pinned to the bottom-right of the page. Open the **Islands** panel — `LikeButton` shows up tagged `mochi:hydrate` with the byte size of its serialized props (the `initialLikes` value), and the crosshair icon next to each row scrolls to and outlines the island on the page.

### Step 4 — A server island

Finally, let's add a personalized greeting that doesn't block the rest of the page. We marked `Visitor.svelte` with `mochi:defer` back in Step 2, so it skips the initial SSR pass — the page ships with our `<p>Loading…</p>` fallback in its place. The browser then fetches the component _in a separate request_, the server renders it, and the result swaps in.

<Callout type="tip">

The deferred island fetch is its own request, so `getRequestContext()` inside the island sees the island URL — not the page URL. Read page-specific state in the parent and forward it as a prop.

</Callout>

Update `Hello.svelte` to read `?name=` and pass it through to `Visitor`:

```svelte
<!-- file: src/Hello.svelte (updated) -->
<script lang="ts">
  import { getRequestContext } from 'mochi-framework';
  import LikeButton from './LikeButton.svelte';
  import Visitor from './Visitor.svelte';

  let { siteName, renderedAt }: { siteName: string; renderedAt: string } = $props();

  const { url } = getRequestContext();
  const visitorName = url.searchParams.get('name') ?? 'friend';
</script>

<h1>Welcome to {siteName}</h1>
<p>Rendered at <code>{renderedAt}</code></p>

<LikeButton mochi:hydrate initialLikes={42} />

<Visitor mochi:defer name={visitorName}>
  <p>Loading…</p>
</Visitor>
```

```svelte
<!-- file: src/Visitor.svelte -->
<script lang="ts">
  import type { Snippet } from 'svelte';

  let { name }: { name: string; children?: Snippet } = $props();
</script>

<p>Welcome back, {name}!</p>
```

`mochi:defer` lets the call site pass fallback children (our `<p>Loading…</p>`) that render in place of the island until the deferred fetch resolves. The framework handles the swap — `Visitor` itself never renders `children`, but we declare it in the prop type so TypeScript accepts the fallback at the call site.

The `name` prop rides through the same `devalue` round-trip as `initialLikes`. Try [`/docs/your-first-mochi-app/hello/?name=Alice`](/docs/your-first-mochi-app/hello/?name=Alice) — the main page is identical for every visitor, but the deferred fragment swaps in a personalized greeting.

<Callout type="tip">

Cookies are an exception worth knowing: the browser sends them along with the island fetch automatically, so `getRequestContext().cookies` inside a server island reads the visitor's cookies without needing the parent to forward them.

</Callout>

### See it live

The finished app is running on this site at [**/docs/your-first-mochi-app/hello/**](/docs/your-first-mochi-app/hello/). Click the heart, then try [`/docs/your-first-mochi-app/hello/?name=Alice`](/docs/your-first-mochi-app/hello/?name=Alice) to watch the deferred fragment swap in a personalized greeting. The [debug bar](/docs/debug-bar/)'s **Islands** panel groups the two islands separately: `LikeButton` under hydrated islands as `mochi:hydrate`, and `Visitor` under server islands as `mochi:defer` with a lock icon (server-island props are encrypted before being sent to the client).

### What's next

- [Defining routes](/docs/defining-routes/) — `Mochi.page`, `Mochi.api`, `Mochi.ws`, `Mochi.sse`, and the full `serverProps` contract
- [Selective hydration](/docs/selective-hydration/) — `mochi:hydrate`, `isHydratable()`, `$props.id()`
- [Lazy hydration](/docs/lazy-hydration/) — `mochi:hydrate:visible` for below-the-fold islands
- [Server islands](/docs/server-islands/) — `mochi:defer`, encrypted props, and `MOCHI_KEY`
- [Passing props to islands](/docs/island-props/) — every type `devalue` can round-trip

<SeeItInAction
demos={[
{ href: "/demos/hello-world/", title: "Hello World", hook: "How server-side rendering works — a Mochi.page() renders Svelte on the server and ships zero JavaScript." },
{ href: "/demos/server-props/", title: "Server Props", hook: "How server props work — pass fresh per-request data into a page via serverProps on Mochi.page()." },
]}
/>

---
title: 'Coming from SvelteKit'
slug: coming-from-sveltekit
description: 'Map each SvelteKit concept to its Mochi equivalent.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import ComparisonTable from './_components/ComparisonTable.svelte';
</script>

## Coming from SvelteKit

This page maps SvelteKit features to their Mochi equivalents so you can start quickly. Read the feature table first, or [skip to the feature list](#routing).

### Feature comparison

<ComparisonTable mochi:hydrate />

### Routing

SvelteKit uses a file-based router. Mochi uses a programmatic `routes` record passed to `Mochi.serve({ routes })`. Each key is a Bun router pattern. Each value is built with `Mochi.page`, `Mochi.api`, `Mochi.ws`, or `Mochi.sse`.

```
// SvelteKit
src/routes/+page.svelte              → /
src/routes/posts/[slug]/+page.svelte → /posts/:slug
src/routes/health/+server.ts         → /health
```

```ts
// file (Mochi): src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
    '/posts/:slug': Mochi.page('./src/Post.svelte'),
    '/health': Mochi.api(() => Response.json({ status: 'ok' })),
  },
});
```

### Advanced routing

Mochi uses Bun router patterns: `:slug` for a required parameter, `*` for a catch-all. There is no SvelteKit-style `[[optional]]` segment, no `[param=matcher]` syntax, and no `src/params/` directory. Validate a parameter's shape inline.

```ts
// file (SvelteKit): src/params/fruit.ts
export function match(param: string): param is 'apple' | 'orange' {
  return param === 'apple' || param === 'orange';
}
// then: src/routes/fruits/[name=fruit]/+page.svelte
```

```ts
// file (Mochi): src/index.ts
import { Mochi, error } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/fruits/:name': Mochi.page('./src/Fruit.svelte', {
      serverProps: (_req, params) => {
        if (params.name !== 'apple' && params.name !== 'orange') error(404, 'Unknown fruit');
        return { name: params.name };
      },
    }),
    '/files/*': Mochi.page('./src/Files.svelte'),
  },
});
```

A `:param` always captures the whole segment — you can't put literal text beside it. SvelteKit's `profile/@[user]` has no direct equivalent: Bun treats `@:user` as literal text, so `/profile/@:user` never matches. Match `/profile/:user` instead — the param captures the whole segment, sigil included (`params.user === '@bob'`) — and note it _also_ matches `/profile/bob`, silently serving the page at two URLs unless you guard:

```ts
// file (Mochi): the SvelteKit route profile/@[user]
'/profile/:user': Mochi.page('./src/Profile.svelte', {
  serverProps: (_req, params) => {
    if (!params.user.startsWith('@')) error(404); // /profile/bob must not alias /profile/@bob
    return { username: params.user.slice(1) };
  },
}),
```

<Callout type="tip">

Register the most specific patterns first. Bun matches in declaration order.

</Callout>

### Layouts

SvelteKit's `+layout.svelte` / `+layout.server.ts` have no Mochi equivalent. In SvelteKit, layouts persist across navigations: the client-side router keeps the layout component mounted and only swaps the page slot. That also lets `+layout.server.ts` skip refetching data that is still valid. Mochi has no client-side router, so every navigation is a full page load. There is no component tree to persist and no data to revalidate selectively.

Instead, create a wrapper component that accepts `children`, then import it from each page.

```svelte
<!-- file (SvelteKit): src/routes/+layout.svelte -->
<script>
  let { data, children } = $props();
</script>

<nav>Hi {data.user.name}</nav>
{@render children()}
```

```svelte
<!-- file (Mochi): src/lib/Layout.svelte -->
<script>
  let { user, children } = $props();
</script>

<nav>Hi {user.name}</nav>
{@render children()}
```

There is nothing special about the layout — it is a plain component. SvelteKit applies it for you; in Mochi you import it into the page and wrap the markup yourself:

```svelte
<!-- file (Mochi): src/Home.svelte -->
<script>
  import Layout from './lib/Layout.svelte';
  let { user, posts } = $props();
</script>

<Layout {user}>
  <h1>Posts</h1>
  {#each posts as post}
    <a href="/posts/{post.slug}">{post.title}</a>
  {/each}
</Layout>
```

<Callout type="warning">

Hydrated islands cannot take `children` — it is a [compile error](/docs/selective-hydration/#no-children-on-hydrate-islands). So never put `mochi:hydrate*` on a layout wrapper; hydrate the interactive components inside it instead.

</Callout>

Share the data that SvelteKit's `+layout.server.ts` would have loaded through a common helper, then spread the result into each route's `serverProps`:

```ts
// file (SvelteKit): src/routes/+layout.server.ts
export async function load() {
  return { user: await loadCurrentUser() };
}
```

```ts
// file (Mochi): src/lib/baseProps.ts
export async function baseProps() {
  return { user: await loadCurrentUser() };
}
```

```ts
// file (Mochi): src/index.ts
import { Mochi } from 'mochi-framework';
import { baseProps } from './lib/baseProps';

await Mochi.serve({
  routes: {
    '/': Mochi.page('./src/Home.svelte', {
      serverProps: async () => ({ ...(await baseProps()), posts: await loadPosts() }),
    }),
  },
});
```

<Callout type="tip">

Every page that shares a shell imports the layout component explicitly. There is no automatic nesting. This is more verbose than SvelteKit, but it makes the component tree visible at each call site.

</Callout>

### Load functions

SvelteKit's `load` becomes `serverProps` on your `Mochi.page` call. It is a plain object or a `(req, params) => props` resolver (sync or async). The result reaches the component as `$props`.

```ts
// file (SvelteKit): src/routes/posts/[slug]/+page.server.ts
export async function load({ params }) {
  return { post: await loadPost(params.slug) };
}
```

```ts
// file (Mochi): src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/posts/:slug': Mochi.page('./src/Post.svelte', {
      serverProps: async (_req, params) => ({ post: await loadPost(params.slug) }),
    }),
  },
});
```

```svelte
<!-- file (Mochi): src/Post.svelte -->
<script>
  let { post } = $props();
</script>

<h1>{post.title}</h1>
```

The `Mochi.page()` entry component renders on the server, so you can also call data helpers directly inside the component instead of threading every value through props. Client-side interactivity is opt-in per child component with `mochi:hydrate`, `mochi:hydrate:visible`, `mochi:defer`, or `mochi:defer:visible`.

You can read `getRequestContext().params` anywhere on the server instead of threading `params` through `serverProps`.

A guard redirect inside `load` ports directly: return `redirect(status, location)` from `serverProps` and the page render is skipped (see [Redirecting from serverProps](/docs/defining-routes/#redirecting-from-serverprops); requires mochi-framework 0.10.0).

```ts
serverProps: (req) => {
  if (!currentUser(req)) return redirect(303, '/login');
  return { settings: loadSettings() };
},
```

### Form actions

SvelteKit's `actions` export becomes the `actions` field on `Mochi.page`. The helpers `fail`, `redirect`, and `success` import from `mochi-framework`. A POST matches an `?/<name>` query (or `default` when absent). The action's return value populates a `form` prop on re-render. The action callback receives `{ request, url, server, locals, kind, method, formData, actionName, cookies, params }`.

```ts
// file (SvelteKit): src/routes/login/+page.server.ts
import { fail, redirect } from '@sveltejs/kit';

export const actions = {
  default: async ({ request }) => {
    const formData = await request.formData();
    const username = String(formData.get('username') ?? '');
    if (!username) return fail(400, { error: 'Username required' });
    return { username };
  },
  logout: () => redirect(303, '/'),
};
```

```ts
// file (Mochi): src/index.ts
import { Mochi, fail, success, redirect } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/login': Mochi.page('./src/Login.svelte', {
      actions: {
        default: ({ formData, cookies }) => {
          const username = String(formData.get('username') ?? '');
          if (!username) return fail(400, { error: 'Username required' });
          cookies.set('user', username, { httpOnly: true, path: '/' });
          return success({ username });
        },
        logout: () => redirect(303, '/'),
      },
    }),
  },
});
```

```svelte
<!-- file (Mochi): src/Login.svelte -->
<script>
  let { form } = $props();
</script>

{#if form?.data?.error}<p>{form.data.error}</p>{/if}
```

<Callout type="warning">

**`form.data`, not `form`.** SvelteKit spreads the `fail()` payload onto the `form` prop itself; Mochi nests it — `form = { ok, action, status?, data }`. Every `form?.error` read in ported code must become `form?.data?.error`, or the value is silently `undefined`.

</Callout>

<Callout type="tip">

When `actions` is declared, `form` is reserved for the action result. Do not return `form` from `serverProps`. See [Defining routes](/docs/defining-routes/).

</Callout>

### `use:enhance`

SvelteKit's `use:enhance` becomes Mochi's `enhance` attachment from `mochi-framework`. The wire format and `submit` callback semantics match closely — `MochiEnhanceResult` mirrors SvelteKit's `ActionResult`.

```svelte
<!-- file (SvelteKit): src/routes/login/+page.svelte -->
<script>
  import { enhance } from '$app/forms';
</script>

<form method="POST" action="?/login" use:enhance>
  <input name="username" />
  <button type="submit">Log in</button>
</form>
```

```svelte
<!-- file (Mochi): src/Login.svelte -->
<script>
  import { enhance } from 'mochi-framework';
</script>

<form method="POST" action="?/login" {@attach enhance()}>
  <input name="username" />
  <button type="submit">Log in</button>
</form>
```

<Callout type="tip">

Mark the surrounding component with `mochi:hydrate*` so the attachment runs in the browser. Attachments run only when Svelte hydrates a component. See [Progressive enhancement](/docs/progressively-enhancing-forms-with-enhance/).

</Callout>

### API routes (`+server.ts`)

SvelteKit's `+server.ts` with `GET` / `POST` exports becomes `Mochi.api(handler)`. One handler per route. Branch on `method` inside. The handler receives `{ request, url, server, locals, kind, method, params, cookies }`.

```ts
// file (SvelteKit): src/routes/api/users/[id]/+server.ts
export async function GET({ params }) {
  return Response.json(await loadUser(params.id));
}

export async function POST({ params, request }) {
  return Response.json(await createUser(params.id, await request.json()));
}
```

```ts
// file (Mochi): src/index.ts
import { Mochi, error } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/api/users/:id': Mochi.api(async ({ method, request, params }) => {
      if (method === 'GET') return Response.json(await loadUser(params.id));
      if (method === 'POST') return Response.json(await createUser(params.id, await request.json()));
      error(405, 'Method not allowed');
    }),
  },
});
```

<Callout type="tip">

Use `Mochi.page` for normal HTML routes. `Mochi.api` never goes through the error page or `handleError`. See [API routes](/docs/api-routes/).

</Callout>

### `error()`, `redirect()`, `fail()`

Same names, imported from `mochi-framework`. `error(status, message?)` throws `MochiHttpError`, defaulting the message to the canonical status text when omitted. `redirect(status, location)` returns from an action or a `serverProps` resolver. `fail(status, data)` and `success(data?)` round-trip through the `form` prop (under `form.data`) or the `enhance` envelope.

```ts
// SvelteKit
import { error, redirect, fail } from '@sveltejs/kit';
```

```ts
// Mochi
import { error, redirect, fail, success } from 'mochi-framework';
```

<Callout type="tip">

Call `error(status, message)` to signal an HTTP status. A bare `throw new Error()` becomes a 500.

</Callout>

### Error pages (`+error.svelte`)

SvelteKit's `+error.svelte` becomes the `errorPage` option on `Mochi.serve()` — one component for the whole app, defaulting to `DefaultError.svelte`. It receives one `error: MochiErrorProps` prop with `status`, `message`, and `stack` (dev only).

```svelte
<!-- file (SvelteKit): src/routes/+error.svelte -->
<script>
  import { page } from '$app/state';
</script>

<h1>{page.status}</h1><p>{page.error.message}</p>
```

```ts
// file (Mochi): src/index.ts
await Mochi.serve({ errorPage: './src/Error.svelte', routes });
```

```svelte
<!-- file (Mochi): src/Error.svelte -->
<script lang="ts">
  import type { MochiErrorProps } from 'mochi-framework';
  let { error }: MochiErrorProps = $props();
</script>

<h1>{error.status}</h1><p>{error.message}</p>
```

See [Error handling](/docs/error-handling/).

### Hooks (`handle`)

SvelteKit's `hooks.server.ts` `handle` export becomes the `handle` option on `Mochi.serve()`. The shape matches: `async ({ event, resolve }) => Response`. `event` carries `{ request, url, server, locals, kind }`. Compose handles with `sequence(...)`. Unlike SvelteKit, `event` itself does not carry `cookies`, `params`, or `getClientAddress` — read those from `getRequestContext()` inside the handler.

```ts
// file (SvelteKit): src/hooks.server.ts
import type { Handle } from '@sveltejs/kit';

export const handle: Handle = async ({ event, resolve }) => {
  event.locals.user = await loadUser(event.request);
  return resolve(event);
};
```

```ts
// file (Mochi): src/handle.ts
import type { Handle } from 'mochi-framework';

export const auth: Handle = async ({ event, resolve }) => {
  if (event.kind === 'asset') return resolve(event);
  event.locals.user = await loadUser(event.request);
  return resolve(event);
};
```

```ts
// file (Mochi): src/index.ts
import { Mochi, sequence } from 'mochi-framework';
import { auth } from './handle';

await Mochi.serve({ handle: sequence(auth), routes });
```

### `resolve` options

SvelteKit's `resolve(event, { transformPageChunk, filterSerializedResponseHeaders })` maps to Mochi's `resolve(event, { transformPage, filterResponseHeaders })`. `transformPage({ html, done })` rewrites the HTML body. `filterResponseHeaders(name, value)` keeps or drops a header.

```ts
// file (SvelteKit): src/hooks.server.ts
export const handle = ({ event, resolve }) =>
  resolve(event, {
    transformPageChunk: ({ html }) => html.replace('%THEME%', 'dark'),
    filterSerializedResponseHeaders: (name) => name.toLowerCase() !== 'server',
  });
```

```ts
// file (Mochi): src/handle.ts
import type { Handle } from 'mochi-framework';

export const stripServer: Handle = ({ event, resolve }) =>
  resolve(event, {
    transformPage: ({ html }) => html.replace('%THEME%', 'dark'),
    filterResponseHeaders: (name) => name.toLowerCase() !== 'server',
  });
```

### `handleError`

Same name. Configure it as a `Mochi.serve()` option. The hook receives `{ error, event, status, message }` and may return `{ status, message }`, a `Response`, or `void`.

```ts
// file (SvelteKit): src/hooks.server.ts
import type { HandleServerError } from '@sveltejs/kit';

export const handleError: HandleServerError = ({ error, event }) => {
  tracker.capture(error, { path: event.url.pathname });
  return { message: 'Internal error' };
};
```

```ts
// file (Mochi): src/index.ts
import type { HandleError } from 'mochi-framework';

const handleError: HandleError = ({ error, event }) => {
  if (error) tracker.capture(error, { path: event.url.pathname });
};

await Mochi.serve({ handleError, routes });
```

<Callout type="tip">

`handleError` never runs for `Mochi.api` failures. Return an error envelope inside the handler instead.

</Callout>

### `event.locals`

Same surface. Set `event.locals.x` from middleware. Read it from any server-side code with `getRequestContext().locals`.

```ts
// file (SvelteKit): src/routes/profile/+page.server.ts
export const load = ({ locals }) => ({ user: locals.user });
```

```ts
// file (Mochi): src/SomePage.svelte
import { getRequestContext } from 'mochi-framework';
const { locals } = getRequestContext();
```

### Observability

SvelteKit's experimental OpenTelemetry tracing has no direct equivalent. Mochi emits structured lifecycle events on `mochiEvents` — `request`, `ws:*`, `sse:*`, `cache:*`, `action:*`, `server:start`, `server:stop`, and compile-time events. Subscribe to feed tracing, metrics, or a custom logger.

```js
// file (SvelteKit): svelte.config.js
export default {
  kit: { experimental: { tracing: { server: true }, instrumentation: { server: true } } },
};
// then write OTel setup in src/instrumentation.server.ts
```

```ts
// file (Mochi): src/index.ts
import { mochiEvents } from 'mochi-framework';

mochiEvents.on('request', ({ method, path, status, duration }) => {
  metrics.timing('http.request', duration, { method, path, status });
});
```

`consoleLogger()` is the default subscriber for human-readable output. See [Events](/docs/events/).

### Client IP (`getClientAddress`)

SvelteKit's `event.getClientAddress()` becomes a method on `getRequestContext()`. Configure `proxy.addressHeader` / `proxy.xffDepth` on `Mochi.serve()` for trusted reverse-proxy hops.

```ts
// file (SvelteKit): src/routes/api/whoami/+server.ts
export const GET = ({ getClientAddress }) => new Response(getClientAddress());
```

```ts
// file (Mochi): src/handle.ts
import { getRequestContext } from 'mochi-framework';
const ip = getRequestContext().getClientAddress();
```

<Callout type="tip">

Set `proxy.xffDepth` so `getClientAddress()` picks the correct hop, instead of parsing `X-Forwarded-For` yourself.

</Callout>

### CSRF protection

Like SvelteKit, Mochi rejects cross-origin form POSTs by default. It checks the Origin header on `POST` / `PUT` / `PATCH` / `DELETE` when the body is a form content type. Configure it with the `csrf` option on `Mochi.serve()` and the `csrf:trustedOrigins`, `csrf:protectedMethods`, `csrf:formContentTypes`, and `csrf:check` filters.

```js
// file (SvelteKit): svelte.config.js
export default {
  kit: { csrf: { checkOrigin: true } }, // default
};
```

```ts
// file (Mochi): src/index.ts
await Mochi.serve({
  csrf: { trustedOrigins: ['https://embed.example'] },
  routes,
});
```

<Callout type="tip">

Pin trusted origins through `csrf.trustedOrigins` instead of disabling CSRF on a state-mutating endpoint.

</Callout>

### Cookies

`event.cookies` becomes `getRequestContext().cookies` (also on the form-action callback as `event.cookies`). Same `get` / `set` / `delete` API and `CookieSerializeOptions`. App-wide defaults live on the `cookie:defaults` filter rather than per call.

```ts
// file (SvelteKit): src/routes/login/+page.server.ts
export const actions = {
  default: ({ cookies }) => {
    cookies.set('session', token, { httpOnly: true, sameSite: 'lax', path: '/' });
  },
};
```

```ts
// file (Mochi): src/handle.ts
import { getRequestContext } from 'mochi-framework';

const { cookies } = getRequestContext();
cookies.set('session', token, { httpOnly: true, sameSite: 'Lax', path: '/' });
```

### `$app/state` and the `page` store

There is no reactive `page` store. Import `url`, `params`, `cookies`, and `locals` directly from `mochi-framework`. `url` is isomorphic — it reads the request context on the server and `window.location` on the client. `params` and `locals` are server-only.

```svelte
<!-- file (SvelteKit): src/routes/+page.svelte -->
<script>
  import { page } from '$app/state';
</script>

<p>{page.url.pathname} — {page.params.slug}</p>
```

```svelte
<!-- file (Mochi): src/Some.svelte -->
<script>
  import { url, params } from 'mochi-framework';
</script>

<p>{url.pathname} — {params.slug}</p>
```

<Callout type="tip">

`url` works on server and client. Guard `params` and `locals` with `isServer`. See [Request context](/docs/request-context/).

</Callout>

### `$app/navigation` (`goto`, `invalidate`, `preloadData`)

No equivalent. Mochi has no client-side router, so there is nothing to `goto` into and nothing to `invalidate`. Every navigation is a full HTML round-trip. For form submissions, use `enhance()`. For anything else, set `window.location.href` or call `history.pushState` from a hydrated island.

```svelte
<!-- file (SvelteKit): src/routes/+page.svelte -->
<script>
  import { goto, invalidateAll } from '$app/navigation';
</script>

<button onclick={() => goto('/dashboard')}>Go</button>
<button onclick={() => invalidateAll()}>Refresh</button>
```

```svelte
<!-- file (Mochi): src/SomeIsland.svelte -->
<button onclick={() => (window.location.href = '/dashboard')}>Go</button>
```

<Callout type="tip">

Listen for `beforeunload` or `popstate` directly. There is no `beforeNavigate` / `afterNavigate` / `onNavigate`.

</Callout>

### Link options (`data-sveltekit-preload-*`)

Planned, but not yet available. Mochi has no client router today, so there is nothing to preload code or data into. The browser handles `<a>` clicks natively, and link preloading is on the roadmap. `data-sveltekit-reload`, `data-sveltekit-replacestate`, `data-sveltekit-keepfocus`, and `data-sveltekit-noscroll` likewise have no Mochi attribute.

```html
<!-- SvelteKit -->
<body data-sveltekit-preload-data="hover">
  <a href="/about">About</a>
</body>
```

```html
<!-- Mochi -->
<a href="/about">About</a>
```

### Snapshots

No equivalent. SvelteKit's `snapshot` exists because its client router reuses page components across navigation. Mochi does full page reloads, so the browser's bfcache restores native `<input>` / `<textarea>` / scroll state on `Back` / `Forward` when the page is bfcache-eligible (no `Cache-Control: no-store`, no unfinished requests). For component state, or anything that must survive forward navigation or a hard reload, write to `sessionStorage` from a hydrated island, or use a cookie or query parameter.

```svelte
<!-- file (SvelteKit): src/routes/comment/+page.svelte -->
<script>
  let comment = $state('');
  export const snapshot = {
    capture: () => comment,
    restore: (v) => (comment = v),
  };
</script>

<textarea bind:value={comment}></textarea>
```

```svelte
<!-- file (Mochi): src/Comment.svelte (hydrated island) -->
<script>
  let comment = $state(sessionStorage.getItem('comment') ?? '');
  $effect(() => sessionStorage.setItem('comment', comment));
</script>

<textarea bind:value={comment}></textarea>
```

### Shallow routing (`pushState` / `replaceState`)

No framework helper. Call `history.pushState` / `history.replaceState` directly from a hydrated island. There is no `page.state` to read back, so store the value alongside the URL or in component state.

```svelte
<!-- file (SvelteKit): src/routes/photos/+page.svelte -->
<script>
  import { pushState } from '$app/navigation';
  import { page } from '$app/state';
</script>

<button onclick={() => pushState('', { modal: 'open' })}>Open</button>
{#if page.state.modal}<Modal />{/if}
```

```svelte
<!-- file (Mochi): src/PhotoGrid.svelte -->
<button onclick={() => history.pushState({ modal: 'open' }, '', location.href)}>Open</button>
```

### Service workers

Planned, but not yet available. There is no `src/service-worker.ts` convention and no `$service-worker` virtual module. Built-in service worker integration is on the roadmap. Register one yourself from a hydrated island if you need offline support today.

```ts
// file (SvelteKit): src/service-worker.ts
import { build, files, version } from '$service-worker';
const ASSETS = `cache-${version}`;
// install / fetch handlers …
```

```ts
// file (Mochi): src/Boot.svelte (hydrated island)
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}
// then ship /public/sw.js yourself
```

### Image optimization (`@sveltejs/enhanced-img`)

Supported, with a different split of the work. SvelteKit optimizes at build time through `@sveltejs/enhanced-img`, with runtime transformations available at extra cost through a CDN. Mochi imports local images the same Vite-style way — the import returns `{ src, width, height, format }` and copies the file to a content-hashed URL. Declare the transforms once as [named sizes](/docs/images/) on `Mochi.serve()`. They run on demand in `Bun.Image` behind an encrypted URL, cached to disk with stale-while-revalidate. The same `<Image>` works for remote sources, and `placeholder` adds a ThumbHash blur-up with no client JavaScript.

```svelte
<!-- file (SvelteKit): src/routes/+page.svelte -->
<script>
  import hero from './hero.png?enhanced';
</script>

<enhanced:img src={hero} alt="Hero" />
```

```svelte
<!-- file (Mochi): src/Home.svelte — `hero` size declared in Mochi.serve({ image: { sizes } }) -->
<script>
  import { Image } from 'mochi-framework/image';
  import hero from './hero.png';
</script>

<Image src={hero} size="hero" alt="Hero" />
```

### Remote functions

No equivalent. SvelteKit's type-safe `query` / `command` RPC has no built-in counterpart. Use `Mochi.api(handler)` with a hand-rolled `fetch()`, or `Mochi.page` actions with `enhance()` for form-driven mutations.

```ts
// file (SvelteKit): src/routes/likes.remote.ts
import * as v from 'valibot';
import { command } from '$app/server';

export const addLike = command(v.string(), async (id) => {
  await db.sql`UPDATE item SET likes = likes + 1 WHERE id = ${id}`;
});
```

```ts
// file (Mochi): src/index.ts
import { Mochi, error } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/api/like/:id': Mochi.api(async ({ method, params }) => {
      if (method !== 'POST') error(405, 'POST only');
      await db.sql`UPDATE item SET likes = likes + 1 WHERE id = ${params.id}`;
      return Response.json({ ok: true });
    }),
  },
});
// on the client: await fetch(`/api/like/${id}`, { method: 'POST' })
```

### `$env/static/*` and `$env/dynamic/*`

None of these virtual modules exist. Bun auto-loads `.env`, so read everything through `process.env.FOO`.

What `$env/static/private` really bought you was a build-time error when a private value reached a client-reachable module. In Mochi that job belongs to [`.server.ts` files](/docs/server-only-imports/), which are replaced with a throwing stub in the client build. Mochi's [environment constants](/docs/environment-constants/) (`isServer`, `isBrowser`, `isDev`) branch on render target, but they do **not** keep the untaken branch out of the bundle — reach for them to pick a code path, not to hide a secret.

```ts
// SvelteKit
import { API_KEY } from '$env/static/private';
import { PUBLIC_API_URL } from '$env/static/public';
```

```ts
// Mochi
const apiKey = process.env.API_KEY;
const publicApiUrl = process.env.PUBLIC_API_URL;
```

<Callout type="tip">

Bun loads `.env` for you. To send an environment variable to the client, pass it as a prop to a hydrated island.

</Callout>

### `$app/paths` (`asset`, `base`, `resolve`)

No equivalent for app links: write them as absolute paths (`/about`) and prefix them yourself when hosting under a sub-path. Framework assets are prefixed for you by `assetPrefix` (default `/_mochi`) — see [Sub-path and static hosting](/docs/deployment-options/#sub-path-and-static-hosting).

```svelte
<!-- SvelteKit -->
<script>
  import { asset, base } from '$app/paths';
</script>

<a href="{base}/about">About</a>
<img src={asset('/logo.png')} />
```

```svelte
<!-- Mochi -->
<a href="/about">About</a>
<img src="/logo.png" />
```

### Server-only modules

SvelteKit's `.server.ts` suffix carries over — Mochi uses the same convention. There is no `$lib/server` directory equivalent. The suffix is the entire mechanism, applied per file anywhere in your source tree. Every named and default export of a `*.server.ts` file is replaced with a throwing `Proxy` on the client, so the real module body compiles for SSR only.

```ts
// file (SvelteKit): src/lib/server/db.ts
import { Database } from 'better-sqlite3';
export const db = new Database(':memory:');
```

```ts
// file (Mochi): src/lib/db.server.ts
import { Database } from 'bun:sqlite';
export const db = new Database(':memory:');
```

```svelte
<!-- file (Mochi): src/FactCard.svelte — hydratable island -->
<script>
  import { hydratable } from 'svelte';
  import { db } from './lib/db.server.ts';

  const version = await hydratable('app:sqlite-version', () => db.query('SELECT sqlite_version() as v').get().v);
</script>

<p>SQLite {version}</p>
```

### `$lib`

No virtual `$lib` alias. Add the path to `tsconfig.json` if you want the same ergonomic.

```svelte
<!-- SvelteKit (works out of the box) -->
<script>
  import Button from '$lib/Button.svelte';
</script>
```

```json
// file (Mochi): tsconfig.json
{
  "compilerOptions": {
    "paths": { "$lib/*": ["./src/lib/*"] }
  }
}
```

### Page options (`ssr`, `csr`, `prerender`)

Not configurable per page. Mochi always renders on the server. Client-side JavaScript is opt-in per component with `mochi:hydrate`, `mochi:hydrate:visible`, `mochi:defer`, or `mochi:defer:visible`. There is no prerender / SSG mode — every request renders fresh. The `*.prerender.ts` suffix prerenders a module, not a route; see [Prerendered modules](/docs/prerender/).

Trailing-slash policy is global, not per page. Set `trailingSlash: 'never' | 'always'` on `Mochi.serve()` and Mochi registers both forms of every page route, then redirects to the canonical one. Only page routes follow it — `Mochi.api()`, `Mochi.sse()`, `Mochi.ws()` and `Mochi.file()` match the pattern you declared. See [Trailing slash](/docs/trailing-slash/).

```ts
// file (SvelteKit): src/routes/about/+page.ts
export const prerender = true;
export const csr = false;
export const trailingSlash = 'always';
```

```ts
// file (Mochi): src/index.ts
await Mochi.serve({ trailingSlash: 'always', routes });
// hydration is per-component: <Counter mochi:hydrate /> in the page
```

<Callout type="tip">

Control hydration with the `mochi:hydrate*` directives at each call site. There is no per-page `ssr` / `csr` / `prerender` export.

</Callout>

### Streaming / deferred data

Stream slow work with `mochi:defer` server islands. The deferred component renders out-of-band and swaps in once ready. Its fallback children stay visible until then.

```svelte
<!-- file (Mochi): src/Home.svelte -->
<SlowRecommendations mochi:defer>
  <p>Loading…</p>
</SlowRecommendations>
```

See [Server islands](/docs/server-islands/).

### Adapters

Mochi targets Bun through `Bun.serve()`. Containerize the Bun runtime or deploy to a supported serverless platform. See [Deployment](/docs/deployment-options/).

### `vite.config.ts`

Mochi uses Bun's bundler and Svelte 5's compiler. Pass preprocessors through the `compile:preprocessors` filter. Tweak the compiler in `svelte.config.js`, which loads automatically (override it with the `svelteConfigPath` option). See [Svelte config](/docs/svelte-config/).

```js
// file (Mochi): svelte.config.js
export default {
  compilerOptions: { runes: true },
};
```

### See also

- [Defining routes](/docs/defining-routes/) — the four `Mochi.*` route helpers.
- [Middleware (hooks)](/docs/middleware/) — `Handle`, `sequence`, `resolve` options.
- [Error handling](/docs/error-handling/) — `errorPage`, `handleError`, API error envelope.
- [Server islands](/docs/server-islands/) — `mochi:defer` and deferred rendering.
- [Hydratable values](/docs/hydratable/) — `hydratable(key, fn)`.
- [Extensions](/docs/extensions/) — `eventHooks` and `filters`.
- [Events](/docs/events/) — the `mochiEvents` bus.
- [Cache](/docs/cache/) — `MochiCache` SWR caching.
- [Trailing slash](/docs/trailing-slash/) — global `trailingSlash` policy.

<SeeItInAction
demos={[
{ href: "/demos/server-props/", title: "Server Props", hook: "How server props work — pass fresh per-request data into a page via serverProps on Mochi.page()." },
{ href: "/demos/login/", title: "Form Actions", hook: "How form actions work — a form rendered twice, as a plain HTML POST and intercepted with {@attach enhance(...)}." },
{ href: "/demos/api/", title: "API Endpoints", hook: "How API routes work — define JSON endpoints with Mochi.api(), tested live against the running server." },
]}
/>

---
title: 'Defining routes'
slug: defining-routes
description: 'Register pages, APIs, WebSockets, SSE endpoints, and file routes with the programmatic routes record.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Defining routes

Routes are a `Record<string, MochiRouteValue>` passed to `Mochi.serve({ routes })`. Each key is a Bun router pattern. Each value comes from one of the five `Mochi.*` helpers.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  port: 3333,
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
    '/about': Mochi.page('./src/About.svelte', { serverProps: { title: 'About' } }),
    '/health': Mochi.api(() => Response.json({ status: 'ok' })),
    '/ws/chat': Mochi.ws({
      message(ws, msg) {
        ws.send(String(msg));
      },
    }),
    '/sse/time': Mochi.sse((stream) => {
      stream.send(new Date().toISOString());
    }),
  },
});
```

### Route parameters

Use `:name` for a single segment and `*` for a wildcard tail. Read matched values from `getRequestContext().params`.

```svelte
<!-- file: src/Post.svelte -->
<script>
  import { getRequestContext } from 'mochi-framework';
  const { params } = getRequestContext();
</script>

<h1>{params.slug}</h1>
```

<Callout type="info">

A `:param` always captures the whole segment — you can't put literal text beside it. Bun reads `/profile/@:user` as literal text, so `/profile/@bob` never matches. Match `/profile/:user` instead; the sigil comes along in the param (`params.user === '@bob'`), and `/profile/bob` matches too. Guard and strip inline when you only want the prefixed form:

```ts
serverProps: (_req, params) => {
  if (!params.user.startsWith('@')) error(404);
  return { username: params.user.slice(1) };
};
```

</Callout>

### `Mochi.page`

Register an SSR Svelte page with `Mochi.page(componentPath, { serverProps?, actions? })`. `componentPath` resolves relative to the project root.

`serverProps` is a plain object or a `(req, params) => props` resolver (sync or async). The resolved object reaches the component as `$props`.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/posts/:slug': Mochi.page('./src/Post.svelte', {
      serverProps: async (_req, params) => ({
        post: await loadPost(params.slug),
      }),
    }),
  },
});
```

For a resolver that hits a slow upstream, wrap the load in a shared cache — see [Caching expensive serverProps](/docs/cache/).

`actions` is a `MochiFormActions` map that handles POST submissions to the route.

<Callout type="warning">

**Do not use `form` as a prop name.** When `actions` is declared, `form` is reserved for the action result. Return any other prop name from `serverProps` to avoid a runtime error.

</Callout>

#### Redirecting from serverProps

<VersionNote since="0.10.0" message="Returning redirect() from serverProps requires mochi-framework 0.10.0." />

A `serverProps` resolver may return `redirect(status, location)` instead of props — the page render is skipped and the response carries the redirect. Use it for auth gates:

```ts
// file: src/index.ts
import { Mochi, redirect } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/settings': Mochi.page('./src/Settings.svelte', {
      serverProps: (req) => {
        const user = currentUser(req);
        if (!user) return redirect(303, '/login');
        return { user };
      },
    }),
  },
});
```

The return type is `MochiRedirect`. Returning `fail()` or `success()` from `serverProps` is a runtime error — those are form-action results.

### `Mochi.api`

Register a JSON endpoint with `Mochi.api(handler)`. The handler receives a `MochiApiEvent` (`method`, `request`, `url`, `server`, `locals`, `params`, `cookies`) and returns a `Response`.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/health': Mochi.api(({ method }) => Response.json({ status: 'ok', method })),
  },
});
```

Throw `MochiHttpError` with `error(status, message)` for non-2xx responses. An uncaught throw becomes `500 Internal Server Error`. See [API routes](/docs/api-routes/).

### `Mochi.ws`

Register a WebSocket endpoint with `Mochi.ws(handlers)`. `message` is required. `upgrade`, `open`, `close`, and `drain` are optional. Return data from `upgrade` (or `false` to reject) to attach to `ws.data.user`.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/ws/chat': Mochi.ws({
      open(ws) {
        ws.subscribe('chat');
      },
      message(ws, msg) {
        ws.publish('chat', String(msg));
      },
    }),
  },
});
```

See [WebSocket routes](/docs/websocket-routes/).

### `Mochi.sse`

Register a Server-Sent Events stream with `Mochi.sse(handler)`. The handler receives a `MochiSseStream` with `send`, `close`, and `onClose`.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/sse/time': Mochi.sse((stream) => {
      const interval = setInterval(() => stream.send(new Date().toISOString()), 1000);
      stream.onClose(() => clearInterval(interval));
    }),
  },
});
```

<Callout type="warning">

**Tear down anything you open per connection.** Each client opens its own timers, intervals, and subscriptions. Without a matching `onClose` teardown they keep running after the client disconnects and leak memory.

```ts
Mochi.sse((stream) => {
  const unsubscribe = chat.subscribe((msg) => stream.send(msg));
  stream.onClose(unsubscribe); // fires on disconnect or stream.close()
});
```

</Callout>

### `Mochi.file`

Serve one file from disk with `Mochi.file(source)`. `source` is a string path or a `(req, params) => string` resolver (sync or async). Mochi infers `Content-Type` from the file extension and answers `HEAD` automatically. Paths resolve relative to the working directory. Every resolved path must stay inside the app root. A path outside returns `404`.

```ts
// file: src/index.ts
import { Mochi, error } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/report': Mochi.file('./files/report.pdf'),

    '/files/:name': Mochi.file((req, params) => {
      const name = params.name;
      if (!name || !/^[a-z0-9-]+$/.test(name)) {
        error(404, 'Not found');
      }
      return `./files/${name}.pdf`;
    }),
  },
});
```

Mochi reads the file from disk on every request, so files written or deleted at runtime are picked up at once. `Mochi.file` does not support `Range` requests, caching headers, or middleware. Use `Mochi.api` when you need full control over the response.

<Callout type="danger">

Route params are URL-decoded before they reach your resolver, so `params.name` can contain `../` (for example, from `/files/..%2f..%2fsecret`). Mochi refuses any path that resolves outside the app root, but that guard does not protect private files inside the root, such as `.env`, source, and config. Always validate params against an allow-list or a strict pattern, as above.

</Callout>

### HEAD requests

Every `Mochi.page` and `Mochi.api` route answers `HEAD` automatically. Mochi runs the `GET` logic and strips the body. Status and headers match the `GET`, and `Content-Length` is set to the `GET` body length. This also covers static assets and the `404` fallback.

<Callout type="info">

`Mochi.sse` is GET-only: a `HEAD` returns `405 Method Not Allowed` (`Allow: GET`) without opening a stream. `Mochi.ws` routes are upgrade-only and do not handle `HEAD`.

</Callout>

### Static files

Mochi serves files under `./public` automatically, in development and production, so the directory must ship with your deploy. A user-defined route wins over a same-path public file. See [Serve options](/docs/serve-options/) for `publicDir`.

<SeeItInAction
demos={[
{ href: "/demos/hello-world/", title: "Hello World", hook: "How server-side rendering works — a Mochi.page() renders Svelte on the server and ships zero JavaScript." },
{ href: "/demos/api/", title: "API Endpoints", hook: "How API routes work — define JSON endpoints with Mochi.api(), tested live against the running server." },
{ href: "/demos/file/", title: "File Routes", hook: "How file routes work — serve a file from disk with Mochi.file(), as a static path or a per-request resolver." },
]}
/>

---
title: 'Selective hydration with mochi:hydrate'
slug: selective-hydration
description: 'Mark components with mochi:hydrate to ship client JavaScript only where you need interactivity.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Selective hydration with `mochi:hydrate`

Components render on the server and ship zero JavaScript. Add `mochi:hydrate` to opt a component into client-side hydration. Everything else stays static HTML.

```svelte
<!-- file: src/routes/Page.svelte -->
<Counter mochi:hydrate count={5} />
<StaticHeader />
```

Mochi serializes props with `devalue` so the same values are available during hydration. See [Passing props to islands](/docs/island-props/) for the supported types.

### What is an island?

An island is any component you mark with a `mochi:*` directive: `mochi:hydrate`, `mochi:hydrate:visible`, `mochi:clientOnly`, `mochi:clientOnly:visible`, `mochi:defer`, or `mochi:defer:visible`. Everything else is server-rendered HTML that ships no JavaScript. The directive decides when and where the island runs.

### Supported import forms

Import an island statically from a **relative** `.svelte` / `.md` / `.svx` path in the same file's `<script>`. Default, named, and mixed imports all work.

```svelte
<script>
  import Counter from './Counter.svelte'; // default
  import { Widget } from './Barrel.svelte'; // named (module-script export)
  import Chart, { presets } from './Chart.svelte'; // mixed
</script>

<Counter mochi:hydrate />
<Widget mochi:hydrate />
<Chart mochi:hydrate:visible />
```

Framework components from `mochi-framework/components` are the one package exception. Put a directive directly on the package import.

```svelte
<script>
  import { MochiCaptcha } from 'mochi-framework/components';
</script>

<MochiCaptcha mochi:hydrate />
```

Any other import form is a **compile error**, surfaced on the dev error page and in `mochi-framework build`. The two you are most likely to hit:

- **Third-party package imports** (`import { Widget } from 'some-ui-lib'`). Wrap the component in a local `.svelte` file and put the directive on the wrapper.
- **Components received through props, variables, or namespaces** (`<Item.Row mochi:hydrate />`). An island needs a statically known source file. Use the same wrapper fix.

```svelte
<!-- file: src/lib/Wrapped.svelte — local wrapper makes a third-party component an island -->
<script>
  import { Widget } from 'some-ui-lib';
  let props = $props();
</script>

<Widget {...props} />
```

These rules apply to every directive family: `mochi:hydrate*`, `mochi:defer*`, and `mochi:clientOnly*`.

<Callout type="info">

**Hydration is all-or-nothing per island.** A `mochi:hydrate` directive hydrates the whole subtree, so nesting one hydratable island inside another is a compile error. Mark the outermost component and let it cover everything below.

</Callout>

### No children on hydrate islands

<VersionNote since="0.10.0" message="Children on mochi:hydrate* became a compile error in 0.10.0; they previously rendered server-side and silently vanished on hydration." />

A `mochi:hydrate` / `mochi:hydrate:visible` island cannot take children at the call site — the client hydrates from the serialized props alone, and a snippet cannot cross the server→client boundary:

```svelte
<Wrapper mochi:hydrate>
  <p>This is a compile error.</p>
</Wrapper>
```

Move the markup inside the component, or pass what it needs as serializable props. A layout-style wrapper that renders `{@render children()}` therefore cannot be a hydrate island — mark the interactive components _inside_ it instead. With `mochi:defer*` and `mochi:clientOnly*`, children are legal and mean something different: the loading fallback. See [Server islands](/docs/server-islands/) and [`mochi:clientOnly`](/docs/client-only/).

### `isHydratable()`

`isHydratable()` returns `true` when the calling component belongs to a subtree that will hydrate on this page load — `mochi:hydrate*`, `mochi:clientOnly*`, or `mochi:defer mochi:hydrate` — at any nesting depth. It returns `false` everywhere else (plain SSR, pure `mochi:defer` renders, emails). Use it to branch SSR-only fallback behavior.

```svelte
<!-- file: src/lib/Counter.svelte -->
<script lang="ts">
  import { isHydratable } from 'mochi-framework';

  let { count = 0 }: { count?: number } = $props();

  const hydratable = isHydratable();
</script>

{#if hydratable}
  <button onclick={() => count++}>{count}</button>
{:else}
  <span>{count}</span>
{/if}
```

<Callout type="info">

Like `getContext`, call `isHydratable()` during component initialization — at the top level of the `<script>` block, not inside an event handler or `$effect`.

</Callout>

### Unique ids with `$props.id()`

For an SSR-stable id inside an island, use Svelte's native [`$props.id()`](<https://svelte.dev/docs/svelte/$props#$props.id()>). The value from the server render is reused on hydration.

```svelte
<!-- file: src/lib/SignupField.svelte -->
<script lang="ts">
  const uid = $props.id();
</script>

<label for="{uid}-email">Email</label>
<input id="{uid}-email" type="email" />
```

Each instance gets its own id, so repeating the same island never produces duplicate DOM ids. It also works inside server islands: their ids are namespaced so a deferred fragment cannot collide with ids already on the page.

### `mochi:hydrate:visible`

Use `mochi:hydrate:visible` to defer hydration until the component scrolls into view. The component still server-renders. Only its JavaScript and CSS load on first intersection.

```svelte
<HeavyChart mochi:hydrate:visible />
<HeavyChart mochi:hydrate:visible={{ rootMargin: '200px' }} />
```

Pass `rootMargin` to start loading before the component enters the viewport. See [Lazy hydration](/docs/lazy-hydration/).

<Callout type="warning">

A `:visible` island loads its CSS with its bundle on intersection, not in the initial page `<head>`. It can briefly render unstyled. Use `mochi:hydrate` for anything that must look correct on the initial SSR load.

</Callout>

### `mochi:clientOnly`

Use `mochi:clientOnly` to skip SSR entirely. Mochi mounts the component in the browser only, with an optional fallback snippet as the SSR placeholder. See [Client-only components](/docs/client-only/).

```svelte
<AudioVisualizer mochi:clientOnly />
```

Add `:visible` to defer the browser mount until the placeholder scrolls into view, with the same `rootMargin` option.

```svelte
<AudioVisualizer mochi:clientOnly:visible={{ rootMargin: '200px' }} />
```

### `mochi:defer`

Use `mochi:defer` to render the component in a separate request after the page ships. Combine it with `mochi:hydrate` to also hydrate the deferred markup. See [Server islands](/docs/server-islands/).

```svelte
<ShoppingCart mochi:defer mochi:hydrate items={initialItems} />
```

Add `:visible` to defer the fetch until the placeholder scrolls into view.

```svelte
<UserAvatar mochi:defer:visible={{ rootMargin: '200px' }} userId={123} />
```

<SeeItInAction
demos={[
{ href: "/demos/hydration/", title: "Hydration Modes", hook: "How the hydration modes work — mochi:hydrate, mochi:hydrate:visible, rootMargin tuning, and mochi:defer server islands side by side." },
{ href: "/demos/lazy/", title: "Lazy Islands", hook: "How lazy hydration works — islands marked mochi:hydrate:visible hydrate and load their CSS only when scrolled into view." },
{ href: "/demos/server-island/", title: "Server Islands", hook: "How server islands work — components marked mochi:defer render server-side on demand after the initial page is delivered." },
]}
/>

---
title: 'Client-only components with mochi:clientOnly'
slug: client-only
description: 'Skip SSR and mount a component in the browser with mochi:clientOnly.'
---

<script>
  import Callout from './_components/Callout.svelte';
</script>

## Client-only components with `mochi:clientOnly`

Add `mochi:clientOnly` to a component that must never render on the server. SSR emits an empty island wrapper. In the browser Mochi mounts the component. Use it for components built on browser-only APIs: `window`, canvas, `localStorage`, `requestAnimationFrame`, third-party browser SDKs.

```svelte
<!-- file: src/Page.svelte -->
<AudioVisualizer mochi:clientOnly />
```

Props work like `mochi:hydrate` — serialized with `devalue` and embedded into the HTML. See [Passing props to islands](/docs/island-props/). [`isHydratable()`](/docs/selective-hydration/#ishydratable) always returns `true` here, since the component only ever runs at client mount. For a unique id, use Svelte's `$props.id()`, which is minted fresh in the browser.

```svelte
<MapWidget mochi:clientOnly zoom={12} center={coords} />
```

### Fallback content

Pass fallback markup as children. It renders on the server as placeholder content and is removed the moment the component mounts.

```svelte
<ChartCanvas mochi:clientOnly data={points}>
  <div class="chart-skeleton">Loading chart…</div>
</ChartCanvas>
```

Type the component's props with `ClientOnlyProps<T>` so `svelte-check` accepts the fallback children:

```svelte
<script lang="ts">
  import type { ClientOnlyProps } from 'mochi-framework';
  let { data }: ClientOnlyProps<{ data: number[] }> = $props();
</script>
```

<Callout type="warning">

The fallback children are an SSR placeholder only. They do not reach the component at runtime, so do not render `children` inside a client-only component. Keep the fallback to static markup. Do **not** put `mochi:*` islands inside it — the fallback is wiped from the DOM when the component mounts.

</Callout>

### Lazy client-only with `mochi:clientOnly:visible`

Defer the browser mount until the wrapper scrolls into the viewport. The component still never renders on the server. Its JavaScript and CSS are fetched and mounted only when the placeholder intersects the viewport.

```svelte
<AudioVisualizer mochi:clientOnly:visible={{ rootMargin: '200px' }} />
```

Provide fallback children as the placeholder. They reserve space and give the observer something to watch until the component mounts.

```svelte
<ChartCanvas mochi:clientOnly:visible data={points}>
  <div class="chart-skeleton">Loading chart…</div>
</ChartCanvas>
```

### Server-side APIs are unavailable

The component never runs on the server, so `getRequestContext()`, `cookies`, and `hydratable()` server reads are unavailable inside it. Pass server-derived values in as props from the page.

<Callout type="warning">

`<script module>` blocks still run during SSR — the page's import statement remains even though the component is never invoked. Keep module-scope code free of `window` and other browser globals. Access them from the instance script or `$effect`.

</Callout>

### Limitations

- Combining `mochi:clientOnly*` with `mochi:hydrate*` or `mochi:defer*` is a compile error.
- Like other islands, a client-only component must not nest inside another hydratable component.
- Import it statically from a relative `.svelte` / `.md` / `.svx` path. See [Supported import forms](/docs/selective-hydration/#supported-import-forms).

---
title: 'Lazy hydration with mochi:hydrate:visible'
slug: lazy-hydration
description: 'Defer island hydration until the component scrolls into view with mochi:hydrate:visible.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Lazy hydration with `mochi:hydrate:visible`

Defer hydration until a component scrolls into the viewport. The component still renders on the server on every request. Its JavaScript and CSS are fetched only when the wrapper intersects the viewport.

```svelte
<!-- file: src/Page.svelte -->
<HeavyChart mochi:hydrate:visible />
```

Pass an options object to start loading before the element enters the viewport. Mochi forwards `rootMargin` to `IntersectionObserver`.

```svelte
<HeavyChart mochi:hydrate:visible={{ rootMargin: '200px' }} />
```

The default `rootMargin` is `'0px'` — hydration fires the moment the island's first child crosses the viewport edge.

<Callout type="info">

**A lazy island's CSS loads lazily too.** Mochi fetches the stylesheet with the JavaScript on intersection, so the island can briefly render unstyled. Put critical above-the-fold styles in the page shell, or use `mochi:hydrate` for anything that must look right before it scrolls into view.

</Callout>

### Combining with `mochi:defer`

Stack `mochi:defer mochi:hydrate:visible` to defer both rendering and hydration. The placeholder ships with the page. The SSR HTML streams in when the deferred fetch resolves. The JavaScript loads only after the rendered island scrolls into view.

```svelte
<Comments mochi:defer mochi:hydrate:visible={{ rootMargin: '300px' }} />
```

See [Selective hydration](/docs/selective-hydration/) for `mochi:hydrate` and [Server islands](/docs/server-islands/) for `mochi:defer`.

<SeeItInAction
demos={[
{ href: "/demos/lazy/", title: "Lazy Islands", hook: "How lazy hydration works — islands marked mochi:hydrate:visible hydrate and load their CSS only when scrolled into view." },
{ href: "/demos/lazy-server-island/", title: "Lazy Server Islands", hook: "How lazy server islands work — server islands marked mochi:defer:visible only fetch when the wrapper scrolls into view." },
]}
/>

---
title: 'Server islands with mochi:defer'
slug: server-islands
description: 'Render components after initial page load by fetching their HTML from the server with mochi:defer.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Server islands with `mochi:defer`

Mark a component with `mochi:defer` to skip it during the initial SSR pass and render it on demand from a dedicated endpoint after the page loads. Use it for personalized fragments such as avatars and cart counts that would otherwise block the surrounding HTML from being cached.

```svelte
<!-- file: src/Page.svelte -->
<UserAvatar mochi:defer userId={123} />
```

Children of a deferred component become the fallback shown until the island resolves.

```svelte
<UserAvatar mochi:defer userId={123}>
  <div class="skeleton">Loading...</div>
</UserAvatar>
```

Import a deferred component statically from a relative `.svelte` / `.md` / `.svx` path. See [Supported import forms](/docs/selective-hydration/#supported-import-forms).

A server island is a normal Svelte component with full access to the request context through `getRequestContext()`. Cookies are forwarded automatically because the fetch is same-origin.

```svelte
<!-- file: src/UserAvatar.svelte -->
<script lang="ts">
  import { getRequestContext } from 'mochi-framework';

  const { cookies } = getRequestContext();
  const userName = cookies.get('user') ?? 'friend';
</script>

<p>Welcome back, {userName}!</p>
```

### How it renders

The page ships with the fallback in place of the island, plus an encrypted token carrying the island's props. The browser then fetches the rendered HTML from a per-island endpoint under `assetPrefix` (default `/_mochi/island/...`), and Mochi swaps it in over the fallback. A failed fetch retries with exponential backoff (default 9 retries, 1s–5s). Pass `mochi:defer={{ retries: 10 }}` to override.

<Callout type="info">

`mochi-framework build` precompiles every server island, so production renders them from the prebuilt bundle instead of compiling on first fetch.

</Callout>

### Combining with hydration

Apply `mochi:hydrate` alongside `mochi:defer` to fetch the island on demand and then hydrate it for client-side interactivity.

```svelte
<ShoppingCart mochi:defer mochi:hydrate items={initialItems} />
```

<Callout type="warning">

**Adding `mochi:hydrate` makes the props client-visible.** A pure `mochi:defer` island keeps its props on the server — the token on the wire is opaque and the endpoint returns only HTML. Hydration needs the raw props on the client, so `mochi:defer mochi:hydrate` echoes the decrypted props back as plaintext. Do not pass server-only secrets to an island you also hydrate.

</Callout>

### Reloading an island with `reloadDeferredIsland`

<VersionNote since="0.10.0" message="Named defers and reloadDeferredIsland were added in 0.10.0." />

Give a defer a `name`, then re-fetch its server HTML from the browser by calling `reloadDeferredIsland(name)`. Use it to refresh server-rendered content after a mutation without a full page reload. A `name` must be a non-empty string — anything else warns and leaves the island unnamed.

```svelte
<Cart mochi:defer={{ name: 'cart' }}>
  <div class="skeleton">Loading...</div>
</Cart>
```

```ts
import { reloadDeferredIsland, reloadDeferredIslandAll } from 'mochi-framework';

await reloadDeferredIsland('cart'); // re-fetches, resolves once swapped in
await reloadDeferredIslandAll(); // reloads every named defer on the page
```

`deferReloadState(name)` returns reactive state for that island, for UI that follows along:

```svelte
<script>
  import { deferReloadState } from 'mochi-framework';

  const cart = deferReloadState('cart');
</script>

<button disabled={cart.reloading} onclick={() => reloadDeferredIsland('cart')}>Refresh</button>
{#if cart.reloading}<Spinner />{/if}
{#if cart.lastReloadOk === false}<p>Last refresh failed.</p>{/if}
<p>
  Refreshed {cart.count} times{#if cart.lastReloaded}, last at {cart.lastReloaded.toLocaleTimeString()}{/if}
</p>
```

| Field          |                                                                                     |
| -------------- | ----------------------------------------------------------------------------------- |
| `reloading`    | `true` while that island has a fetch in flight — its first load as well as a reload |
| `count`        | completed reload rounds, successful or not                                          |
| `lastReloadOk` | whether the last reload round _fetched_ successfully, `null` before the first       |
| `lastReloaded` | `Date` the last reload completed, `null` before the first                           |

Islands sharing a name reload together and settle as one round: `count` adds one per round, and `lastReloadOk` is `true` only when every island in the round fetched successfully. You get one shared instance per name, so reading it repeatedly is free — and reading a field outside a component just gives you its current value.

`lastReloadOk` reports the fetch, not the render: an island whose component throws still answers with a 200, so it reads `true` while the island shows its `<svelte:boundary>` fallback. Render failures are the boundary's job, not the reload's.

<Callout type="warning">

**`deferReloadState` must be called from a `.svelte` or `.svelte.ts` file.** Its fields are runes, so Svelte has to compile the call site; calling it from plain server code throws `$state is not defined`.

</Callout>

Both return a promise that settles once every matching island has finished re-fetching. Islands sharing a `name` reload together, and a `mochi:defer mochi:hydrate` island unmounts its old component and re-hydrates when the new HTML lands. Reloads on the same island queue behind one another, so a reload issued after a mutation always observes it.

`name` works on `mochi:defer:visible` too. A reload fetches immediately regardless of viewport. The viewport trigger queues behind any reload already in flight and stands down once either has delivered content, so the two can never race or double-fetch.

Naming an island also opts it out of [nested inlining](#nesting-islands-inside-a-server-island): a reloadable island needs its own placeholder to fetch into. An explicit `inline: true` on a named island is ignored, with a warning.

<Callout type="info">

`reloadDeferredIsland` runs in the browser — call it from a hydrated island or other client code. During SSR no islands are mounted, so it resolves immediately and does nothing.

</Callout>

<Callout type="warning">

**A reload resolves even if the fetch failed.** It reuses the same retry-and-backoff policy as the initial load, so a hard failure only resolves once the retry budget is spent, leaving the previous content in place. Watch `lastReloadOk`, and lower `retries` on islands you invalidate interactively.

</Callout>

#### Loading state while reloading

A reloading island keeps showing its current content — the fallback children only ever show before the first load — and carries two attributes for the duration:

```html
<mochi-server-island data-reloading aria-busy="true"></mochi-server-island>
```

Style `data-reloading` to mark the wait. Island wrappers are `display: contents`, so they generate no box of their own — put the styles on the children:

```css
mochi-server-island[data-reloading] > * {
  opacity: 0.6;
}
```

The old content is swapped out only when the new HTML lands, so hydrated children keep their client state for the whole wait, and a failed fetch leaves the island exactly as it was.

Size the fallback to match the loaded content, or the swap shifts the page. The wrapper is `display: contents`, so it holds no space of its own while the content is away — the fallback's own box is the only thing keeping the layout still. Giving both a shared `min-height` is usually enough:

```css
.card,
.card-skeleton {
  min-height: 3.5rem;
}
```

### Nesting islands inside a server island

A server island's content is a full render, so it can contain `mochi:hydrate` islands and further `mochi:defer` server islands. Hydratable children hydrate once the deferred HTML lands.

```svelte
<!-- file: src/Dashboard.svelte (rendered via mochi:defer) -->
<Chart mochi:hydrate {data} />
<Notifications mochi:defer />
```

Mochi **inlines** nested `mochi:defer` islands into the parent's fetch. When the island endpoint renders `Dashboard`, it renders `Notifications` in-process too, so one request returns the whole chain no matter how deep it nests. The decision happens at render time. A nested island inside `{#if}` or `{#each}` inlines when its branch renders, with the same props the placeholder would seal, so Mochi never renders an unreachable island. If an inlined child throws, it degrades to a fetch placeholder and fetches on its own. The parent's content stays intact.

Inlining is capped at 32 expansions per island fetch. A recursive chain and a long `{#each}` list draw from the same budget. Past the cap, children fall back to fetching. Tune the cap per fetch with the `serverIsland:inlineBudget` filter (see [Extensions](/docs/extensions/)).

Opt out per call site to keep a child on its own fetch. This helps when a slow child must not delay the parent's content:

```svelte
<Notifications mochi:defer={{ inline: false }} />
```

Opt out globally with `inlineNestedIslands`:

```ts
Mochi.serve({ inlineNestedIslands: false });
```

`mochi:defer:visible` children are always exempt. Laziness is their point, so they keep their own viewport-triggered fetch.

Mochi delivers CSS for nested islands with the fetched HTML. The host page cannot link it ahead of time, because the island content does not render until the island resolves. Styles apply as soon as the island appears.

<Callout type="warning">

**`mochi:defer` inside a hydratable subtree is a compile error.** A component marked `mochi:hydrate*` or `mochi:clientOnly` re-renders on the client, where a server island cannot exist. Remove `mochi:defer` from the child — it already renders as part of the parent's island fetch — or remove the hydrate directive from the parent.

</Callout>

### Lazy server islands with `mochi:defer:visible`

Defer the fetch until the wrapper scrolls into view, mirroring [`mochi:hydrate:visible`](/docs/lazy-hydration/).

```svelte
<UserAvatar mochi:defer:visible={{ rootMargin: '200px' }} userId={123}>
  <div class="skeleton">Loading...</div>
</UserAvatar>
```

Combine `rootMargin` and `retries`: `mochi:defer:visible={{ rootMargin: '200px', retries: 10 }}`. Combine with `mochi:hydrate` for interactive lazy islands. Provide fallback children so the user has something to scroll past while waiting.

### Props

Mochi serializes props with `devalue` — see [Passing props to islands](/docs/island-props/). Server islands also encrypt the payload and pass it as a query parameter. The island's component name is bound as authenticated data, so a token sealed for one island cannot be replayed against another.

<Callout type="warning">

**Fetch data inside the island, not through props.** Large props inflate the encrypted URL until it trips a runtime warning at ~1800 characters. Use `getRequestContext()` inside the island to fetch data server-side, and pass only identifiers such as ids as props.

</Callout>

<Callout type="warning">

**Treat server-island rendering as idempotent. Never trigger mutable actions from it.** Tokens are encrypted, not single-use. Once a client has seen a prop permutation, it can re-fetch that island any number of times. A side effect inside the component — incrementing a counter, charging an account, sending an email — fires again on every replay.

</Callout>

### Encryption key

Mochi encrypts props with a key derived from `process.env.MOCHI_KEY` (base64url-encoded, any length). Without `MOCHI_KEY`, Mochi generates a random key and logs a warning — fine for local dev, broken across restarts and multi-instance deploys.

Generate a key and write it to `.env`:

```sh
bunx mochi-framework generate-key
```

<Callout type="warning">

**Set `MOCHI_KEY` for any deployment that runs more than one process or survives restarts.** Without a shared key, tokens minted by one instance fail to decrypt on another, and deferred islands fail to load after a restart or rolling deploy.

</Callout>

<Callout type="danger">

**Never commit `MOCHI_KEY`.** It signs server-island prop URLs. A leak lets attackers forge them. Supply it through your platform's secret store.

</Callout>

<SeeItInAction
demos={[
{ href: "/demos/server-island/", title: "Server Islands", hook: "How server islands work — components marked mochi:defer render server-side on demand after the initial page is delivered." },
{ href: "/demos/defer-invalidation/", title: "Invalidate mochi:defer islands", hook: "How to reload server islands on demand — name a mochi:defer island and call reloadDeferredIsland(name) from the browser to re-fetch its server HTML." },
{ href: "/demos/nested-islands/", title: "Nested Islands", hook: "How nested islands work — a mochi:defer server island wrapping mochi:hydrate components, and server islands nesting more server islands." },
{ href: "/demos/lazy-server-island/", title: "Lazy Server Islands", hook: "How lazy server islands work — server islands marked mochi:defer:visible only fetch when the wrapper scrolls into view." },
]}
/>

---
title: 'Passing props to islands'
slug: island-props
description: 'How Mochi serializes props for hydratable islands, the supported types, and reserved names.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Passing props to islands

Pass props to a component marked `mochi:hydrate`, `mochi:hydrate:visible`, or `mochi:defer` as you would to any Svelte component. Mochi serializes them with [`devalue`](https://github.com/Rich-Harris/devalue) so the same values reach the hydrating client.

```svelte
<!-- file: src/routes/Page.svelte -->
<script>
  const user = { name: 'Ada', id: 42 };
  const visitedAt = new Date();
  const tags = new Set(['svelte', 'bun']);
</script>

<UserCard mochi:hydrate {user} {visitedAt} {tags} />
```

### Typing props

Put the type on the `let { … } = $props()` declaration. For a few props, inline the type:

```svelte
<script lang="ts">
  let { adjective }: { adjective: string } = $props();
</script>
```

For larger or reused shapes, use a `Props` interface:

```svelte
<script lang="ts">
  interface Props {
    title: string;
    count?: number;
    user: { name: string; id: number };
  }

  let { title, count = 0, user }: Props = $props();
</script>
```

<Callout type="warning">

Annotate the `let { … }` declaration. Avoid the `$props<{ … }>()` type-argument form.

</Callout>

Type snippet props (including `children`) with the `Snippet` interface from `svelte`. Snippets can only be passed between components on the same side of the server→client boundary — inside an island's subtree, or between server-rendered components — never _into_ a hydrate island from the page (see below):

```svelte
<script lang="ts">
  import type { Snippet } from 'svelte';

  let { children }: { children: Snippet } = $props();
</script>

{@render children()}
```

When a component wraps a native element and forwards its attributes, type the spread with the matching interface from [`svelte/elements`](https://svelte.dev/docs/svelte/typescript#Typing-wrapper-components):

```svelte
<script lang="ts">
  import type { HTMLButtonAttributes } from 'svelte/elements';

  let { children, ...rest }: HTMLButtonAttributes = $props();
</script>

<button {...rest}>{@render children?.()}</button>
```

### How props travel

For `mochi:hydrate*` islands, props ship inline in the page HTML. When several islands share the same payload, it ships over the wire once and the rest reference it, which keeps the page small. For `mochi:defer` server islands, props are encrypted (opaque on the wire) and passed to a per-island endpoint. See [Server islands](/docs/server-islands/).

### Supported types

- Plain objects and arrays
- Primitives: strings, numbers, booleans, `null`
- `Date`, `RegExp`, `Map`, `Set`, `URL`, `URLSearchParams`
- `BigInt`, typed arrays (`Uint8Array`, and so on)
- `undefined`, `Infinity`, `NaN`, `-0`
- Repeated and cyclic references (identity is preserved)

### Unsupported types

- Functions
- Class instances (only own enumerable properties survive)
- `Symbol`
- Snippets / `children` — a snippet is a function, so it cannot cross the boundary. Children at a `mochi:hydrate*` call site are a [compile error](/docs/selective-hydration/#no-children-on-hydrate-islands); on `mochi:defer*` and `mochi:clientOnly*` they are the loading fallback instead.

### Detecting hydration

To branch on whether the current render will hydrate, call [`isHydratable()`](/docs/selective-hydration/#ishydratable). It works in any component at any nesting depth, with no prop involved.

```svelte
<!-- file: src/lib/UserCard.svelte -->
<script lang="ts">
  import { isHydratable } from 'mochi-framework';

  let { user }: { user: { name: string; id: number } } = $props();

  const hydratable = isHydratable();
</script>
```

`islandId` is a reserved name on every island. Passing it as a literal prop is a compile error, so a component can move between directives without the name changing meaning. For a unique id inside the component, use `$props.id()`.

<SeeItInAction
demos={[
{ href: "/demos/island-props/", title: "Crossing the server-client boundary with props", hook: "How props cross the server-client boundary — Date, Map, Set, BigInt, URL, typed arrays, and even cyclic refs survive devalue's round-trip into a hydrated island." },
{ href: "/demos/prop-dedup/", title: "Shared Props", hook: "How island prop deduplication works — nine islands share three unique payloads, each serialized once and referenced via props-ref." },
{ href: "/demos/props-id/", title: "Unique IDs", hook: "How stable island IDs work — Svelte's native $props.id() gives SSR-consistent, per-instance ids, namespaced inside server islands." },
]}
/>

---
title: 'Hydratable values'
slug: hydratable
description: 'Serialize computed server values into the page so the client reuses them instead of re-running the work.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Hydratable values (experimental)

> `hydratable` support is experimental. Please open an issue if you find problems.

Svelte 5's [`hydratable(key, fn)`](https://svelte.dev/docs/svelte/svelte#hydratable) computes a value on the server, serializes it into the page, and reads it back during client hydration. Use it to avoid running the same async work twice when a hydrated component fetches data at the top level.

Without it, the function runs on the server and again during hydration:

```svelte
<script>
  import { getUser } from 'my-database-library';

  // Runs on the server AND again on the client during hydration.
  const user = await getUser();
</script>

<h1>{user.name}</h1>
```

With it, the client reuses the server result:

```svelte
<script>
  import { hydratable } from 'svelte';
  import { getUser } from 'my-database-library';

  // SSR: runs getUser and serializes the result into the page.
  // Client: reads the serialized value and skips getUser.
  const user = await hydratable('app:user', () => getUser());
</script>

<h1>{user.name}</h1>
```

Mochi wires this up. Any `hydratable()` call inside a `Mochi.page(...)` route or a `mochi:hydrate*` island is collected during SSR and picked up by Svelte's `hydrate()` automatically. Import `hydratable` straight from `svelte`.

<Callout type="info">

**Namespace your keys.** Hydratable keys are global per render. Prefix every key with your app or library name (`app:user`, `mylib:cart`) so two callers cannot collide.

</Callout>

### Serialization

Mochi serializes values with [`devalue`](https://www.npmjs.com/package/devalue), so `Map`, `Set`, `Date`, `URL`, `BigInt`, and circular references round-trip. Promises work too — Svelte stitches them back together on the client.

### Limitations in Mochi today

<Callout type="warning">

**Server islands.** A `mochi:defer` server island renders in a separate request, and its serialized values are not merged into the parent page. Keep `hydratable()` calls in the page or in eagerly hydrated islands.

**No CSP nonce wiring.** Mochi does not yet pass a `csp.nonce` to Svelte's `render()`, so the inline lookup script is blocked under strict `script-src`. Allow `'unsafe-inline'` for scripts, or wait for nonce support.

</Callout>

<SeeItInAction
demos={[{ href: "/demos/hydratable/", title: "Hydratable", hook: "How hydratable() works — compute a value once on the server and reuse it on the client instead of re-running async work during hydration." }]}
/>

---
title: 'Server-only imports'
slug: server-only-imports
description: 'Keep server-only modules like bun:sqlite out of client bundles with the .server.ts convention.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Server-only imports

Any module reachable from a hydratable island gets bundled into the client. To use a server-only library (`bun:sqlite`, `node:fs`, anything that touches the filesystem) from inside an island, put the library plus a thin wrapper in a `*.server.ts` file. On the client, Mochi replaces these files with stubs that throw if used. The real module compiles for SSR only.

```ts
// db.server.ts
import { Database } from 'bun:sqlite';

const db = new Database(':memory:');

export const getVersion = (): string => (db.query('SELECT sqlite_version() as v').get() as { v: string }).v;
```

```svelte
<!-- FactCard.svelte — hydratable island -->
<script lang="ts">
  import { hydratable } from 'svelte';
  import { getVersion } from './db.server.ts';

  const version = await hydratable('app:sqlite-version', () => getVersion());
</script>

<p>SQLite {version}</p>
```

The `.server.ts` (or `.server.js`) suffix is the whole convention — no runtime API, no config. Import with the extension (`./db.server.ts`). Extensionless `./db.server` also works.

The sibling convention `*.prerender.ts` goes the other way: the module runs at build time and only its values ship — see [Prerendered modules](/docs/prerender/).

### Types are free

A type-only import is erased before the client build resolves anything, so a `.server.ts` file is also the right home for the types describing its data — even for types used inside a hydratable island.

```ts
// db.server.ts
export interface Row {
  id: number;
  title: string;
}

export const listRows = (): Row[] => db.query('SELECT * FROM rows').all() as Row[];
```

```svelte
<!-- RowList.svelte — hydratable island -->
<script lang="ts">
  import type { Row } from './db.server.ts';

  let { rows }: { rows: Row[] } = $props();
</script>
```

Mochi stubs only value imports. Use `import type` (or `import { type Row }`) so the compiler drops the import instead of resolving it to a stub.

<Callout type="warning">

**Wrap usage in `hydratable()` or `isServer`.** The stub throws on access. If you call a `.server.ts` export from client-running code (an `onclick` handler, an `$effect`), the page throws at runtime. The `hydratable()` producer function never runs on the client, so wrapping the call there is safe. Read the value once on the server, ship it through `hydratable()` or a prop, and use the resolved value on the client.

</Callout>

### What gets stubbed

On the client, every export of a `.server.ts` file throws on any use. The error names the export and its origin file:

```
getVersion from /…/db.server.ts was called on the client; this is a server-only export.
```

### Server-only components

<VersionNote since="0.10.0" message="Server-only components (*.server.svelte) ship in the next Mochi release (0.10.0). This section describes the upcoming API." />

Name a component `*.server.svelte` to keep it SSR-only. It renders on the server like any component, but the client build replaces it with a stub, so it never ships to the browser — even when an island pulls it in through a barrel re-export.

```svelte
<!-- Changelog.server.svelte — rendered on the server, stripped from client bundles -->
<script lang="ts">
  import { readFileSync } from 'node:fs';

  const entries = readFileSync('CHANGELOG.md', 'utf8');
</script>

<pre>{entries}</pre>
```

Import it with the extension (`./Changelog.server.svelte`). The framework's own `ViewTransitions` and `RawScript` use this convention.

<Callout type="warning">

**Don't hydrate a `.server.svelte`.** A `mochi:hydrate*` or `mochi:clientOnly` directive on one is a compile error, and rendering one anywhere deeper inside a hydrated island's subtree logs a build warning — the client stub would throw at hydration. `mochi:defer` (without also-hydrate) stays fine: a deferred island renders on the server only.

</Callout>

Only the default (component) export is stubbed. For server-only _values_, use a `.server.ts` file.

### Unsupported

- `export * from './x'` — Mochi warns at build time. Declare named exports in the `.server.ts` file directly.

<SeeItInAction
demos={[{ href: "/demos/data-loading/", title: "Data Loading", hook: "How server-side data loading works — fetch on the server, cache with MochiCache, and render at request time." }]}
/>

---
title: 'Progressively enhancing forms with enhance'
slug: progressively-enhancing-forms-with-enhance
description: 'Progressively enhance HTML forms to submit over fetch when JavaScript is available.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Progressively enhancing forms with enhance

`enhance` is a Svelte attachment that progressively enhances `<form method="POST">`. The same server action runs whether JavaScript is available or not. With `{@attach enhance(...)}` the client submits over `fetch`, and the server returns a JSON `MochiEnhanceResult` envelope with no full-page reload.

```svelte
<!-- file: src/Login.svelte -->
<script>
  import { enhance } from 'mochi-framework';
</script>

<form method="POST" action="?/login" {@attach enhance()}>
  <input name="username" />
  <input name="password" type="password" />
  <button type="submit">Log in</button>
</form>
```

Place the form inside a hydrated island (`mochi:hydrate`, `mochi:hydrate:visible`, or `mochi:defer mochi:hydrate`). When hydration is skipped, the attachment never runs and the form falls back to a native HTML POST. That is the progressive-enhancement contract.

`enhance` is a factory. Call it as `{@attach enhance()}` even with no options. Attachments require Svelte 5.29+.

### Wire format

`enhance` adds `Accept: application/json` and `x-mochi-action: true` to the POST. The server detects either header and responds with one of four shapes:

```ts
type MochiEnhanceResult =
  | { type: 'success'; status: number; data?: unknown }
  | { type: 'failure'; status: number; data?: unknown }
  | { type: 'redirect'; status: number; location: string }
  | { type: 'error'; status?: number; error: unknown };
```

HTTP status is `200` for `success`, `failure`, and `redirect`. The body's `status` field carries the action's status. For `error`, the HTTP status matches the error code. Mochi encodes `data` with [devalue](https://www.npmjs.com/package/devalue) so `Date`, `Map`, `Set`, `BigInt`, and cyclic references survive the wire.

### Default fallback

Without a callback, `enhance` runs a minimal default per result type:

| `result.type` | Default                                           |
| ------------- | ------------------------------------------------- |
| `success`     | `form.reset()`                                    |
| `failure`     | nothing (provide a callback to update the UI)     |
| `redirect`    | `window.location.assign(result.location)`         |
| `error`       | `console.error('[mochi] enhance:', result.error)` |

The `error` log is not part of the replaceable fallback: it fires on every submission, before any callback runs, so a custom handler that only branches on `success`/`failure` cannot turn a transport or server error into a silent no-op.

<Callout type="warning">

**The default fallback is intentionally lean.** Mochi has no client-side `page.form` store, `goto`, or `invalidateAll`, so it cannot auto-update component props or re-run server data after a submission. Pass a `submit` callback to react to `failure` or to do anything beyond a redirect.

</Callout>

When the same component renders both as a hydrated island and as a plain SSR-only child, call [`isHydratable()`](/docs/selective-hydration/#ishydratable) to skip the SSR `form`-prop peek when the client will take over.

### Submit callback

Pass a function. It runs once per submit and may return a result handler that replaces the default fallback for `success`, `failure`, and `redirect` (the `error` log above always fires):

```svelte
<!-- file: src/Login.svelte -->
<script>
  import { enhance } from 'mochi-framework';
  import type { MochiSubmitFunction } from 'mochi-framework';

  let errorMessage = $state<string | null>(null);
  let pending = $state(false);

  const handleLogin: MochiSubmitFunction<{ username: string }, { error: string }> = ({ formData }) => {
    pending = true;
    errorMessage = null;

    return ({ result, formElement }) => {
      pending = false;
      if (result.type === 'success') {
        formElement.reset();
      } else if (result.type === 'failure') {
        errorMessage = result.data?.error ?? 'Sign-in failed';
      }
    };
  };
</script>

<form method="POST" action="?/login" {@attach enhance(handleLogin)}>
  <!-- inputs -->
  <button type="submit" disabled={pending}>{pending ? 'Signing in…' : 'Log in'}</button>
</form>
```

The result handler receives `{ result, formElement, formData, action, update }`. Call `update({ reset?: boolean })` to re-invoke the default fallback.

### onPending

Pass an options object with `onPending` instead of tracking a `pending` flag inside the submit function. It fires `true` right before the fetch and `false` once the result handler settles (or when the submission is cancelled):

```svelte
<!-- file: src/Login.svelte -->
<script>
  import { enhance } from 'mochi-framework';
  import type { MochiEnhanceOptions } from 'mochi-framework';

  let pending = $state(false);

  const opts: MochiEnhanceOptions = {
    onPending: (v) => {
      pending = v;
    },
  };
</script>

<form method="POST" action="?/login" {@attach enhance(opts)}>
  <!-- inputs -->
  <button type="submit" disabled={pending}>{pending ? 'Signing in…' : 'Log in'}</button>
</form>
```

`onPending` fires `false` from a `finally` block, so it resets even if the fetch throws or the abort signal fires.

### Cancelling

The `submit` callback receives `cancel` and `controller`:

- `cancel()` — bail out before `fetch` runs. No callback runs.
- `controller.abort()` — cancel an in-flight request. The `AbortError` is swallowed.

### Server-side

Declare the action. The same `Mochi.page(path, { actions })` definition serves both the no-JS HTML POST flow and the enhanced JSON flow:

```ts
// file: src/index.ts
import { Mochi, fail, success } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/login': Mochi.page('./src/Login.svelte', {
      actions: {
        login: ({ formData }) => {
          const username = String(formData.get('username') ?? '');
          if (!username) return fail(400, { error: 'Username required' });
          return success({ username });
        },
      },
    }),
  },
});
```

Returning a `Response` directly from an action bypasses the JSON envelope on enhanced submissions. Treat that as an escape hatch.

<Callout type="warning">

**Wrap data in `success()` to round-trip it to the client.** A plain return like `return { username }` strips the data on the enhanced path, and the result handler receives an empty `data` object. Always use `success()` when the client needs the returned data.

</Callout>

### deserialize

`deserialize(text)` decodes a raw `MochiEnhanceResult` envelope. Use it when you roll your own `onsubmit` instead of `{@attach enhance(...)}`:

```svelte
<!-- file: src/Login.svelte -->
<script>
  import { deserialize } from 'mochi-framework';

  async function onsubmit(event: SubmitEvent) {
    event.preventDefault();
    const form = event.currentTarget as HTMLFormElement;
    const response = await fetch(form.action, {
      method: 'POST',
      headers: { Accept: 'application/json', 'x-mochi-action': 'true' },
      body: new URLSearchParams(new FormData(form) as unknown as Record<string, string>),
    });
    const result = deserialize(await response.text());
    // …
  }
</script>
```

### When to use enhance

Use `enhance` when the action's outcome should update the UI without a navigation flicker — interactive forms, optimistic patterns, inline validation. Use a plain `<form method="POST">` when the action ends in a redirect anyway and the JavaScript bundle is not worth shipping.

<SeeItInAction
demos={[
{ href: "/demos/login/", title: "Form Actions", hook: "How form actions work — a form rendered twice, as a plain HTML POST and intercepted with {@attach enhance(...)}." },
{ href: "/demos/form-errors/", title: "Form Errors", hook: "How form action errors work — a thrown action error shows inline via {@attach enhance(...)}, or as the Mochi error page on a plain submit." },
{ href: "/demos/form-return-data/", title: "Using form return data", hook: "How form action return data works — an action returns success({...}); {@attach enhance(...)} updates the UI in place, plain HTML re-renders." },
]}
/>

---
title: 'Why Bun?'
slug: why-bun
description: 'Why Mochi chose Bun as its runtime and which Bun APIs the framework uses.'
---

<script>
  import ComparisonTable from './_components/ComparisonTable.svelte';
</script>

## Why Bun?

Mochi delegates subsystem complexity to the Bun runtime. Instead of maintaining a bundler, an HTML parser, a router, database drivers, compression, and hashing as separate packages, Mochi calls Bun's standard library. Bun maintains those components. Mochi calls them.

Mochi ships about 10 runtime dependencies. It uses an external dependency when the dependency earns its place and improves the developer experience. The goal is an opinionated, batteries-included toolkit for building complex web apps.

### What Mochi uses from Bun

- `Bun.build()` — Mochi's fast bundler, which builds sites with hundreds of routes in seconds.
- `Bun.serve()` — the HTTP and WebSocket server behind `Mochi.serve()`.
- `bun:sqlite` and `bun:sql` — zero-dependency SQLite and PostgreSQL for app data.
- Native `.ts` execution and auto-loaded `.env` — TypeScript runs directly under `bun run`.

### Batteries included

Building on Bun's standard library lets Mochi ship this much out of the box. Here is how the surface compares to SvelteKit:

<ComparisonTable mochi:hydrate />

### On the horizon

As Bun adds features, Mochi gains new abilities. For example, `Bun.Image()` powers on-the-fly image resizing.

---
title: 'HTTP streaming'
slug: http-streaming
description: 'Mochi renders each page as one complete document. Use SSE, WebSockets, and server islands for anything that arrives later.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## HTTP streaming

Mochi renders each page as one complete document, then ships the HTML as a single `text/html` response.

<Callout type="info">

A page holds its response until everything it awaits resolves. A 2-second upstream call delays the whole page by 2 seconds. Push slow or personalized work to the tools below so the shell ships immediately.

</Callout>

### Streaming primitives

- `Mochi.sse(handler)` — Server-Sent Events. `stream.send(...)` pushes events as they happen.
- `Mochi.ws(handlers)` — WebSockets over the `Bun.serve` upgrade. Bidirectional, message by message.

Use these to layer real-time UI on top of a rendered base page.

### Keeping pages fast

- **Server islands** (`mochi:defer`) load slow or personalized fragments out-of-band after the shell ships. The island fetches itself once the browser sees the placeholder.
- **Visible hydration** (`mochi:hydrate:visible`) keeps the initial JavaScript payload small.
- **Shared HTTP cache** (Cloudflare, CloudFront, Fastly, Varnish, nginx) in front of the origin makes render time irrelevant for the cacheable case. A server island can stay uncached behind a cached shell — see [Cache](/docs/cache/).
- **[`compress()`](/docs/middleware/#compress) streams** every encoding it offers (gzip, zstd, deflate) through a `CompressionStream`, so a compressed response stays chunked.

<SeeItInAction
demos={[{ href: "/demos/streams/", title: "Real-time Streams", hook: "How server-sent events and WebSocket streaming work — live SSE and WebSocket clocks, lazily hydrated via mochi:hydrate:visible." }]}
/>

---
title: 'Environment constants'
slug: environment-constants
description: 'Constants for branching on render target (isServer, isBrowser), dev mode (isDev), and the build itself (isBuilding).'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Environment constants

Import these from `mochi-framework` to branch on render target or dev mode:

```ts
import { isServer, isBrowser, isDev } from 'mochi-framework';
```

Inside compiled code — `.svelte`, `.svelte.[jt]s`, and any `.ts` they import — Mochi substitutes a per-bundle module, so each constant is a literal boolean fixed when that bundle is built. In the server build `isServer` is `true` and `isBrowser` is `false`; in the client bundle the values are reversed.

Everywhere else — `src/index.ts`, `routes.ts`, a `.server.ts` reached from them — they are ordinary exports of the package, read at runtime.

<Callout type="warning">

**These do not keep code out of the client bundle.** The constant is a literal, but Bun does not fold it across module boundaries, so the untaken branch is still bundled — it just never runs. To keep a server-only implementation out of the browser entirely, put it in a [`.server.ts` file](/docs/server-only-imports/), which Mochi replaces with a throwing stub in the client build.

</Callout>

### `isServer`

`true` during server-side rendering, `false` in the browser.

```svelte
<!-- file: src/lib/HeavyChart.svelte -->
<script>
  import { isServer } from 'mochi-framework';

  if (isServer) {
    // reach into request-scoped APIs here
  }
</script>
```

### `isBrowser`

`true` in the client bundle, `false` on the server. Use it to gate browser-only APIs (`window`, `document`, `IntersectionObserver`).

```svelte
<!-- file: src/lib/Lazy.svelte -->
<script>
  import { isBrowser } from 'mochi-framework';

  if (isBrowser) {
    window.addEventListener('scroll', onScroll);
  }
</script>
```

### `isDev`

`true` in [development mode](/docs/development-mode/), which is `NODE_ENV=development`. Identical on server and client builds.

```ts
// file: src/lib/log.ts
import { isDev } from 'mochi-framework';

export function trace(msg: string) {
  if (isDev) console.log('[trace]', msg);
}
```

Because it comes from the environment, `isDev` is correct from the first line of your entry — including in module top-level code, which runs before `Mochi.serve()` does.

```json
// file: package.json
{
  "scripts": {
    "dev": "NODE_ENV=development bun src/index.ts",
    "start": "bun src/index.ts"
  }
}
```

Overriding the mode with `Mochi.serve({ development })` is the one way to make them disagree: top-level code has already run by then, so it saw the environment's answer, not your override. Mochi warns at boot when an override contradicts `NODE_ENV=development`, since dev-only top-level branches will have run inside a production process.

### `isBuilding`

`true` only while `mochi-framework build` runs your `index.ts`, `false` when serving (dev or prod). `mochi-framework build` executes your entry to capture its `Mochi.serve()` options, so top-level side effects in `index.ts` run at build time too. Gate the ones you don't want then — connecting a database, spawning workers, running migrations:

```ts
// file: src/index.ts
import { Mochi, isBuilding } from 'mochi-framework';

if (!isBuilding) await db.connect();

await Mochi.serve({ routes });
```

The dev server re-imports `index.ts` on every rebuild to pick up route changes; that import sees `true` too, so gated side effects don't re-run on each save.

Inside `.svelte` components it is always `false` — components are compiled but never executed during a build.

## Detecting hydration with `isHydratable()`

To branch on whether the client will take over rendering, use `isHydratable()`: it returns `true` when the calling component — at any nesting depth — belongs to a subtree that will hydrate on this page load. Unlike the constants above it is a runtime signal, not a build-time literal, so it lives with the hydration model rather than here. See [Selective hydration](/docs/selective-hydration/#ishydratable) for the full semantics and an example.

<SeeItInAction
demos={[{ href: "/demos/url/", title: "Isomorphic URL", hook: "How the isomorphic URL helper works — one import that reads the request URL on the server and window.location on the client." }]}
/>

---
title: 'Request context'
slug: request-context
description: 'Access the current URL, route params, cookies, and locals from server-side code, plus the isomorphic url export.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Request context

Inside components and server-side helpers, import context values directly from `mochi-framework`:

```ts
import { url, params, cookies, locals } from 'mochi-framework';
```

Each export reads from the current request's context on every property access, so you never thread values through props.

### `url`

The current page URL as a standard [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object.

```svelte
<!-- file: src/Post.svelte -->
<script>
  import { url } from 'mochi-framework';

  const page = Number(url.searchParams.get('page') ?? '1');
</script>

<p>Current path: {url.pathname}</p>
```

`url` is **isomorphic**. On the server it reads the parsed request URL. On the client it reflects the current browser URL, including after `pushState` / `replaceState`.

<Callout type="info">

`url` reflects the live browser URL on each access, so a destructured value like `const { pathname } = url` is a snapshot. Access `url.pathname` directly when you need the live value.

</Callout>

<Callout type="warning">

`url.hash` is always empty during SSR — browsers never send the fragment to the server. On the client the hash is available as expected.

</Callout>

### `params`

Route parameters matched by the Bun router. Server-only.

```svelte
<!-- file: src/Post.svelte -->
<script>
  import { params } from 'mochi-framework';
</script>

<h1>{params.slug}</h1>
```

### `cookies`

Read and write cookies on the server and the client through one API. See the [Cookies demo](/demos/cookies/).

```svelte
<script>
  import { cookies } from 'mochi-framework';

  const theme = cookies.get('theme') ?? 'light';
</script>
```

### `locals`

Per-request data set by middleware. Server-only.

```ts
// file: src/middleware.ts
import type { Handle } from 'mochi-framework';

export const auth: Handle = async ({ event, resolve }) => {
  event.locals.user = await getUser(event.cookies);
  return resolve(event);
};
```

```svelte
<!-- file: src/Dashboard.svelte -->
<script>
  import { locals } from 'mochi-framework';

  const user = locals.user;
</script>
```

### `getRequestContext()`

Returns the full context object with all fields. Server-only. Prefer the individual exports above unless you need several fields at once.

```ts
import { getRequestContext } from 'mochi-framework';

const { url, params, cookies, locals, request, requestId } = getRequestContext();
```

`url` and `cookies` work on the server and the client. `getRequestContext()`, `params`, and `locals` are server-only and throw in the browser, so guard those branches with `isServer`.

The context also carries `isWarmup` — `true` when the request came from [route warmup](/docs/serve-options/#route-warmup) at startup, not a real client. Guard side effects in `serverProps` that should not fire for synthetic warmup hits:

```ts
serverProps: async () => {
  const ctx = getRequestContext();
  if (!ctx.isWarmup) await recordVisit(ctx.url.pathname); // skip warmup
  return { posts: await loadPosts() };
};
```

<SeeItInAction
demos={[
{ href: "/demos/request-id/", title: "Request ID", hook: "How request IDs work — every request gets a UUID v7 on getRequestContext().requestId that rides every lifecycle event for correlation." },
{ href: "/demos/cookies/", title: "Cookies", hook: "How cookies work — read and write on the server and the client through one MochiCookieJar API (cookies.get/set/delete)." },
]}
/>

---
title: 'API routes'
slug: api-routes
description: 'Register JSON endpoints with Mochi.api() that receive a request event and return a Response.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## API routes

`Mochi.api(handler)` registers a JSON endpoint. The handler receives a `MochiApiEvent` (`method`, `request`, `url`, `server`, `locals`, `params`, `cookies`) and **must** return a `Response` (or a `Promise<Response>`).

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/health': Mochi.api(({ method }) => Response.json({ status: 'ok', method })),
  },
});
```

### `MochiApiEvent`

Destructure `params` and `cookies` off the event. They mirror what `Mochi.page` form-action handlers receive:

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/items/:id': Mochi.api(({ url, params, cookies }) => {
      const tab = url.searchParams.get('tab') ?? 'overview';
      const session = cookies.get('session');
      return Response.json({ id: params.id, tab, session });
    }),
  },
});
```

`getRequestContext()` exposes the same values plus `requestId`, `islandProps`, and `getClientAddress()`. Use it from helper functions that are not passed the event.

### Reading the request body

Use the standard `Request` body methods (`json()`, `text()`, `formData()`, `arrayBuffer()`). The body stream can be consumed once.

```ts
// file: src/index.ts
import { Mochi, error } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/add': Mochi.api(async ({ method, request }) => {
      if (method !== 'POST') error(405, 'Method Not Allowed');
      const { a, b } = await request.json();
      return Response.json({ result: a + b });
    }),
  },
});
```

<Callout type="warning">

**Read the request body once.** Calling `request.json()` (or any body method) a second time throws `TypeError: Body already used`. Await it once, store the result, and reuse the value.

</Callout>

### `json` (response helper)

Build a JSON `Response` with the right `Content-Type` through `json(data, init?)` from `mochi-framework`.

```ts
import { json } from 'mochi-framework';

Mochi.api(() => json({ ok: true }, { status: 201 }));
```

`init` accepts `status`, `statusText`, and `headers`. Mochi sets `Content-Type: application/json` for you.

### `error` (typed throw)

Use `error(status, message?)` to throw a `MochiHttpError` from anywhere inside the handler, including helper functions. The framework catches it and returns the canonical envelope `{ error: { message, status } }`. Omitting `message` fills in the canonical status text (`error(404)` → `Not Found`).

```ts
import { error } from 'mochi-framework';

Mochi.api(async () => {
  const user = await loadUser();
  if (!user) error(404, 'Not found');
  return Response.json(user);
});
// → 404 { "error": { "message": "Not found", "status": 404 } }
```

`error` is typed `: never`, so TypeScript narrows control flow after the call.

<Callout type="danger">

**Uncaught errors become 500s.** Any throw that is not a `MochiHttpError` is caught, coerced to `500 Internal Server Error` with a generic message, and logged server-side. Use `error(status, message)` to return intended status codes.

</Callout>

### `apiError` (typed return)

`apiError(status, message)` returns the same envelope as a plain `Response`, without throwing. Use it when the failure is part of the route's normal control flow.

```ts
import { apiError } from 'mochi-framework';

Mochi.api(async ({ request }) => {
  const body = await request.json().catch(() => null);
  if (!body) return apiError(400, 'Invalid JSON');
  return Response.json({ ok: true });
});
```

### `MochiHttpError`

The error class `error()` throws. Catch it explicitly when you want to inspect or re-shape it. Otherwise let it propagate.

```ts
import { MochiHttpError } from 'mochi-framework';

try {
  await mayThrow();
} catch (err) {
  if (err instanceof MochiHttpError && err.status === 404) {
    return apiError(404, 'Gone');
  }
  throw err;
}
```

### Uncaught errors

Anything else thrown inside a `Mochi.api` handler — a database failure, a typo, a rejected promise — returns `500 Internal Server Error` with a generic message. Mochi logs the original error and stack. The client never sees them.

API routes never render the HTML error page, and `handleError` is **not** called for them. The JSON envelope is the only contract.

<SeeItInAction
demos={[{ href: "/demos/api/", title: "API Endpoints", hook: "How API routes work — define JSON endpoints with Mochi.api(), tested live against the running server." }]}
/>

---
title: 'WebSocket routes'
slug: websocket-routes
description: 'Register WebSocket endpoints with Mochi.ws() and handle upgrade, open, message, close, and drain events.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## WebSocket routes

`Mochi.ws(handlers)` registers a WebSocket endpoint backed by Bun's `ServerWebSocket`. The handler map carries five callbacks — `upgrade`, `open`, `message`, `close`, `drain` — and exposes Bun's pub/sub primitives (`ws.subscribe`, `ws.publish`, `ws.unsubscribe`) on the socket.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/ws/chat': Mochi.ws({
      open(ws) {
        ws.subscribe('chat');
      },
      message(ws, message) {
        ws.publish('chat', String(message));
        ws.send(String(message));
      },
      close(ws) {
        ws.unsubscribe('chat');
      },
    }),
  },
});
```

Only `message` is required.

<Callout type="warning">

[`trailingSlash`](/docs/trailing-slash/) does not apply to WebSocket routes, so connect to exactly the pattern you declared.

</Callout>

### `upgrade`

Runs once per HTTP upgrade request. Return a value to attach to `ws.data.user`, or return `false` to reject the connection. The route's URL params are the second argument.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/ws/:room': Mochi.ws<{ userId: string; room: string }>({
      upgrade(req, params) {
        const userId = req.headers.get('x-user-id');
        if (!userId) return false; // reject the upgrade
        return { userId, room: params.room };
      },
      message(ws, msg) {
        console.log(ws.data.user.userId, ws.data.user.room, msg);
      },
    }),
  },
});
```

<Callout type="warning">

**Reject unauthenticated sockets in `upgrade`, not `message`.** Authenticating inside `message` still lets the connection establish. Return `false` from `upgrade` so the client never connects.

</Callout>

#### Request context during the handshake

<VersionNote since="0.10.0" message="Earlier versions threw from getRequestContext() inside upgrade." />

`getRequestContext()` works inside `upgrade`, so cookies and `getClientAddress()` are available there. `handle` middleware does not run for WebSocket upgrades, so `locals` is empty. Later callbacks receive only the socket, so derive anything header-based here and return it on `ws.data.user`.

```ts
// file: src/index.ts
import { Mochi, getRequestContext } from 'mochi-framework';

await Mochi.serve({
  proxy: { addressHeader: 'x-forwarded-for', xffDepth: 1 },
  routes: {
    '/ws/chat': Mochi.ws<{ address: string | null }>({
      upgrade() {
        return { address: getRequestContext().getClientAddress() };
      },
      message(ws, msg) {
        console.log(ws.data.user.address, msg);
      },
    }),
  },
});
```

<Callout type="info">

Behind a reverse proxy every socket shares one peer address, so `ws.remoteAddress` is the proxy rather than the visitor. Rate limiting keyed on it becomes one bucket for your whole site — configure `proxy.addressHeader` and read `getClientAddress()` instead.

</Callout>

### `open`

Fires once after a successful upgrade. Use it to subscribe the socket to topics or seed per-connection state.

```ts
open(ws) {
  ws.subscribe('chat');
}
```

### `message`

Fires for every inbound frame. The payload is `string | Buffer` — coerce or decode it before use.

```ts
message(ws, message) {
  ws.publish('chat', String(message));
}
```

<Callout type="warning">

**Keep `message` fast.** Slow work inside `message` holds up the next message from the same socket. Hand long tasks off to a queue or background task so the handler returns quickly.

</Callout>

### `close`

Fires once when the socket closes, with the close `code` and `reason`. Use it to release per-connection state and unsubscribe from topics.

```ts
close(ws, code, reason) {
  ws.unsubscribe('chat');
}
```

### `drain`

Fires when the socket's send buffer drains after a backpressured `ws.send`. Resume queued writes here.

### `ws.data`

Each socket carries a typed `data` object. Mochi reserves the internal fields `__mochiRoutePattern`, `__mochiOpenedAt`, and `__mochiPath`. Your `upgrade` return value is exposed as `ws.data.user`.

```ts
Mochi.ws<{ userId: string }>({
  upgrade(req) {
    const userId = req.headers.get('x-user-id');
    return userId ? { userId } : false;
  },
  message(ws) {
    console.log(ws.data.user.userId);
  },
});
```

### Pub/sub

Every socket exposes `ws.subscribe(topic)`, `ws.publish(topic, data)`, and `ws.unsubscribe(topic)`. To broadcast from outside a handler, capture the `server` returned by `Mochi.serve()` and call `server.publish(topic, data)`.

<Callout type="info">

**`ws.publish` does not echo to the sender.** It delivers only to other subscribers. Call `ws.send` alongside `ws.publish` if the publisher should also receive the message.

</Callout>

### Socket limits

<VersionNote since="0.10.0" message="The websocket serve option was added in 0.10.0." />

`Mochi.serve({ websocket })` passes Bun's socket-level options through to every `Mochi.ws()` route. Mochi owns `open`, `message`, `close`, and `drain`; everything else — `maxPayloadLength`, `idleTimeout`, `backpressureLimit`, `perMessageDeflate` — is yours.

```ts
await Mochi.serve({
  routes,
  websocket: { maxPayloadLength: 4 * 1024 },
});
```

<Callout type="warning">

`maxPayloadLength` is the only inbound size bound that runs **before** Bun buffers the frame, and it defaults to 16 MB. It caps what the server allocates while a length check inside `message` caps what you store — set both.

</Callout>

### Lifecycle events

Every WebSocket emits `ws:open`, `ws:message`, and `ws:close` on `mochiEvents`. `consoleLogger()` prints them. See [Events](/docs/events/) for the payload shape.

<SeeItInAction
demos={[
{ href: "/demos/chat/", title: "Real-time Chat", hook: "How WebSocket routes work — a hydrated island over Mochi.ws() with pub/sub broadcast and in-memory history." },
{ href: "/demos/streams/", title: "Real-time Streams", hook: "How server-sent events and WebSocket streaming work — live SSE and WebSocket clocks, lazily hydrated via mochi:hydrate:visible." },
]}
/>

---
title: 'Server-Sent Events'
slug: server-sent-events
description: 'Push real-time updates to clients over a single HTTP connection with Mochi.sse().'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Server-Sent Events

Register an SSE stream with `Mochi.sse(handler)`. The handler receives a `MochiSseStream` and the underlying `Request`, and runs once per client connection.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {
    '/sse/time': Mochi.sse((stream) => {
      stream.send(new Date().toISOString());
      const interval = setInterval(() => {
        stream.send(new Date().toISOString());
      }, 1000);
      stream.onClose(() => clearInterval(interval));
    }),
  },
});
```

<Callout type="warning">

[`trailingSlash`](/docs/trailing-slash/) does not apply to SSE routes, so connect to exactly the pattern you declared.

</Callout>

### `stream.send(data, options?)`

Push one SSE frame to the client. `data` is a string. `options` accepts `event` (named event type) and `id` (last-event-id).

```ts
stream.send(JSON.stringify({ ok: true }), { event: 'tick', id: '42' });
```

### `stream.close()`

End the stream from the server. The connection terminates and every registered `onClose` callback fires.

<Callout type="warning">

**Call `close()` when a stream is finished.** Leaving a long-running stream open keeps the client listening and holds resources. Call `close()` to release them.

</Callout>

### `stream.onClose(callback)`

Register cleanup that runs when the stream ends — whether the server called `close()` or the client disconnected. Use it to clear timers, unsubscribe from event buses, and release per-connection state.

<Callout type="warning">

**Pair every long-lived resource with `onClose`.** A timer or subscription with no matching cleanup leaks on each disconnect:

```ts
const sub = bus.subscribe(onTick);
stream.onClose(() => sub.unsubscribe());
```

</Callout>

### Events

`Mochi.sse` emits `sse:open`, `sse:message`, and `sse:close` on `mochiEvents`. `consoleLogger()` prints them by default.

<SeeItInAction
demos={[{ href: "/demos/streams/", title: "Real-time Streams", hook: "How server-sent events and WebSocket streaming work — live SSE and WebSocket clocks, lazily hydrated via mochi:hydrate:visible." }]}
/>

---
title: 'Queues'
slug: queues
ogTitle: 'Background jobs with Mochi.queue()'
description: 'Run background jobs with Mochi.queue(), backed by bun-boss on memory, SQLite, Postgres, or embedded PGlite storage.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
  import PersistenceTable from './_components/PersistenceTable.svelte';
</script>

## Queues

<VersionNote since="0.10.0" message="Mochi.queue was reworked in 0.10.0: descriptors are named and directly usable, and the serve-level queues option takes an array of them. This page documents the new API." />

Offload work that should not block a response — sending email, encoding media, calling slow APIs — to a background **queue**. A queue bundles a job channel with the `process` function that consumes it. Both run in your process, backed by [bun-boss](https://github.com/khromov/bun-boss).

<PersistenceTable feature="queues" />

`Mochi.queue(name, …)` returns a descriptor that is both the declaration and the producer handle. Mount it in the `Mochi.serve({ queues })` array to start its worker; call `.add()` on it from anywhere:

```ts
import { Mochi } from 'mochi-framework';

export const emails = Mochi.queue<{ to: string }>('emails', {
  concurrency: 10,
  process: async (job) => {
    await sendEmail(job.data.to);
    return { sent: true };
  },
});

await Mochi.serve({
  routes: {/* … */},
  queues: [emails],
});

// from a page action, an API route, anywhere:
await emails.add({ to: 'alice@example.com' });
```

### `Mochi.queue()`

```ts
const queue = Mochi.queue<JobData, Result>(name, { process, ...options });
```

`process` receives a read-only `MochiJob<T>` and returns the job result. Omit it for a queue that only receives jobs — e.g. a [dead-letter](#dead-letter-queues) holding pen.

| Field        | Type     | Notes                                   |
| ------------ | -------- | --------------------------------------- |
| `id`         | `string` | job id                                  |
| `data`       | `T`      | the enqueued payload                    |
| `queue`      | `string` | queue name                              |
| `attempt`    | `number` | 1-based attempt number (1 on first run) |
| `enqueuedAt` | `number` | epoch ms when enqueued                  |

Queue-level options are inherited by every job: `concurrency`, `pollingIntervalSeconds`, [retries](#retries) (`retryLimit`, `retryDelay`, `retryBackoff`, `retryDelayMax`), `expireInSeconds`, `retentionSeconds`, `deleteAfterSeconds`, `deadLetter`, [`worker`](#worker-tuning), [`storage`](#standalone-producers). Every duration is in **seconds**. `on` registers lifecycle listeners:

```ts
Mochi.queue('emails', {
  concurrency: 10,
  process,
  on: {
    completed: (job, result) => log.info(`${job.id} done`),
    failed: (job, error) => log.warn(`${job.id} failed: ${error.message}`),
  },
});
```

Or subscribe on the [`mochiEvents` bus](#observability) (filter by `queue` name) when the listener lives far from the queue declaration.

### Adding jobs

The descriptor itself is the producer handle — import it and add. `Mochi.getQueue<JobData>(name)` resolves the same handle by name, for call sites that should not import the declaring module; it throws for a name that was never declared, or before `Mochi.serve()` mounted its queues.

| Method                                     | Returns                   | Notes                                       |
| ------------------------------------------ | ------------------------- | ------------------------------------------- |
| `add(data, opts?)`                         | `Promise<string \| null>` | enqueue one job, resolves its id            |
| `addBulk(jobs)`                            | `Promise<string[]>`       | enqueue many in one call                    |
| `addThrottled(data, seconds, key?, opts?)` | `Promise<string \| null>` | at most one job per `seconds` slot per key  |
| `addDebounced(data, seconds, key?, opts?)` | `Promise<string \| null>` | like throttled, but books the next slot too |

Per-job options override their queue-level counterparts: `priority`, `startAfter` (seconds, or a `Date`), `id`, `retryLimit`, `retryDelay`, `retryBackoff`, `retryDelayMax`, `expireInSeconds`.

```ts
await emails.add({ to: 'bob@example.com' }, { priority: 10, startAfter: 5 });
await emails.addBulk([{ data: { to: 'a@x.com' } }, { data: { to: 'b@x.com' }, opts: { priority: 10 } }]);
```

<Callout type="info">

**`add()` can resolve `null`.** Passing an explicit `id` makes the add idempotent — a second add with the same id resolves `null` instead of duplicating the job. Throttled and debounced adds resolve `null` when the slot is already taken. A plain `add()` always resolves an id. `addBulk` skips jobs whose explicit `id` already exists, so it can resolve fewer ids than jobs submitted.

</Callout>

### Standalone producers

A script whose only job is _enqueueing_ — an external scheduler, a CLI backfill, a migration — can write straight to queue storage. (For recurring work inside the server process, use [scheduled jobs](/docs/scheduled-jobs/) instead.) Give the descriptor `storage` and its first `add()` lazily connects a **producer-only** runtime; tear down with [`Mochi.stop()`](#mochistop):

```ts
// enqueue.ts — a standalone producer script
import { Mochi } from 'mochi-framework';

const emails = Mochi.queue<{ to: string }>('emails', {
  storage: { postgres: process.env.DATABASE_URL! },
});

await emails.addBulk(jobs);
await emails.stop();
```

- A producer declaring no options simply ensures the queue exists. Declared options are enforced like everywhere else — [config is code-authoritative](#storage) — and a descriptor-form [`deadLetter`](#dead-letter-queues) is created with its link intact even when the producer runs first on fresh storage. To consume without a server, see [standalone workers](#standalone-workers).
- `queue.stop()` stops that queue in this process — its worker deregisters after in-flight jobs finish, and the shared runtime closes once the last active queue stops. [`Mochi.stop()`](#mochistop) remains the whole-app teardown; under `Mochi.serve()` queues stop with the server.
- Your app has **one queue storage**. Declare it on the descriptor (`storage`), app-wide via the serve-level [`queueStorage`](#storage) option, or both when they agree — conflicting declarations are a boot error. Standalone, a descriptor without `storage` throws on `add()`.
- `Mochi.serve()` inherits the descriptors' storage when `queueStorage` is unset, and a serve on the same storage adopts an already-connected standalone runtime — on a different storage it refuses to start.
- `mochi:queuesMounted` fires only under `Mochi.serve()`. For a standalone producer, readiness is the first `add()` resolving.

### Standalone workers

`Mochi.worker()` is the consuming counterpart: a process that polls and runs `process` without serving HTTP. `start()` connects to the app's queue storage — from the descriptors, or the worker's own `storage` option — ensures the queues exist, and begins polling:

```ts
// worker.ts — a standalone worker script
import { Mochi, consoleLogger } from 'mochi-framework';
import { emails } from './queues';

consoleLogger();

const worker = Mochi.worker({ queues: [emails] });
await worker.start();

process.on('SIGINT', async () => {
  await Mochi.stop();
  process.exit(0);
});
process.on('SIGTERM', async () => {
  await Mochi.stop();
  process.exit(0);
});
```

Queue config follows the same rule as every other path — [code is authoritative](#storage): a worker creates missing queues with their full declared config ([`deadLetter`](#dead-letter-queues) links included, targets first) and refuses to start when storage disagrees; `Mochi.worker({ queueConfig: 'sync' })` writes the declared config to storage instead. `worker.stop()` deregisters the worker's queues (waiting for in-flight jobs) while the runtime stays up for producing; `Mochi.stop()` tears the runtime down.

<Callout type="info">

**Standalone means standalone.** `Mochi.worker()` installs no signal handlers (wire them yourself, as above), fires no hooks or startup milestones, and subscribes no logger — call `consoleLogger()` for the `QUEUE` lines. A process that calls `Mochi.serve()` declares its queues there instead; `start()` refuses to run alongside it.

</Callout>

### Worker tuning

The rarely-needed bun-boss fetch options ride along in `worker`, forwarded to the worker verbatim: `orderByCreatedOn`, `priority`, `minPriority`, `maxPriority`, `ignoreStartAfter`, `notifyPollingIntervalSeconds`, `burstWhenReadyExceeds`, `heartbeatRefreshSeconds`.

```ts
Mochi.queue('plugin-info', {
  process: fetchPluginInfo,
  worker: { orderByCreatedOn: false, minPriority: 10 },
});
```

Mochi-owned settings (`concurrency`, `pollingIntervalSeconds`, and the per-job settlement contract) win where they overlap. `worker` options apply at fetch time only; stored queue options stay as declared.

### Storage

One store serves every queue — declared app-wide via the serve-level `queueStorage` option, or inherited from a [`storage`](#standalone-producers) declared on the descriptors:

```ts
await Mochi.serve({
  queues: [/* … */],
  queueStorage: 'memory', // the default
  // queueStorage: { sqlite: '.db/queue.sqlite' },
  // queueStorage: { postgres: process.env.DATABASE_URL },
  // queueStorage: { pglite: await PGlite.create('.db/queue-pglite') },
});
```

| Storage                | Survives restarts | Scope                                            |
| ---------------------- | ----------------- | ------------------------------------------------ |
| `'memory'`             | no                | single process                                   |
| `{ sqlite: path }`     | yes               | single process, one durable file                 |
| `{ postgres: url }`    | yes               | shared — multiple processes can work one backlog |
| `{ pglite: instance }` | yes (on-disk)     | single process, embedded in-process Postgres     |

See [Persistence](/docs/persistence/) for how queue storage compares to the other stateful Mochi features.

Postgres storage installs its tables into a dedicated `mochi_queue` schema on first start, away from your application's tables. The schema name is fixed, so every app sharing one database shares one queue namespace — give each app its own database to keep their queues apart.

On durable storage, **declared config is authoritative and storage is a cache of it**. At every boot — `Mochi.serve()`, `Mochi.worker()`, and standalone producers alike — each declared queue is created with its full config if missing, and verified field-by-field against storage if present. A mismatch is a boot error naming the queue, the fields, and both values; an option you leave undeclared is expected to hold its bun-boss default. A declaration with no persisted options at all (`Mochi.queue(name, { storage })`) only asserts the queue exists.

To change a queue's config, change the code — then let one deploy write it through:

```ts
await Mochi.serve({ queues, queueConfig: 'sync' }); // or MOCHI_QUEUE_SYNC=1 in the environment
```

`'sync'` replaces the mismatch error with a repair: the declared config is written to storage and every changed field is logged. `MOCHI_QUEUE_SYNC=1` forces sync process-wide (standalone producers included) and wins over the option — set it on the one deploy that migrates, or leave `queueConfig: 'sync'` on permanently for code-always-wins. The mismatch error also prints a ready-to-paste `Mochi.boss().updateQueue(…)` call for migrating by hand.

<Callout type="warning">

**Share one descriptor across processes.** Every process that declares a queue asserts its config — a producer script declaring different options than the server is a boot error, not a silent divergence. Export the descriptor from one module and import it everywhere. The `queue:expireInSeconds` filter counts as declared config too, so processes must register the same extensions.

</Callout>

### PGlite

`{ pglite: instance }` is the one storage that takes a live instance instead of a config string. Mochi recommends `{ postgres: url }` for production; PGlite — full Postgres compiled to WASM, running in your process with no server — covers dev and test environments while exercising the same Postgres storage path, including the `mochi_queue` schema, so jobs behave the way they will in production:

```ts
import { PGlite } from '@electric-sql/pglite';

const db = await PGlite.create('.db/queue-pglite'); // or PGlite.create() for a throwaway in-memory store

await Mochi.serve({
  queues: [/* … */],
  queueStorage: { pglite: db },
});
```

Passing the instance keeps `@electric-sql/pglite` out of Mochi's dependencies and lets your app share one instance between queue jobs and its own tables. You own the instance, so make sure to close it at shutdown.

### Retries

Failed jobs retry **by default**: `retryLimit` is 2, so a job runs up to 3 times before it fails terminally. Set `retryLimit: 0` for exactly-once execution, and `retryDelay`/`retryBackoff` to space attempts out:

```ts
Mochi.queue('webhooks', {
  process: deliverWebhook,
  retryLimit: 5,
  retryDelay: 5, // seconds; with retryBackoff it doubles per attempt, with jitter
  retryBackoff: true,
  retryDelayMax: 300,
});
```

`job.attempt` in `process` is 1-based, so `job.attempt > retryLimit` is true exactly on the final attempt.

### Dead-letter queues

Point `deadLetter` at another queue and a terminally failed job is copied there — same payload — for handling or inspection, while the original stays `failed` in its source queue as an audit trail. Pass the target's **descriptor** and the reference is self-sufficient: whichever process boots first — server, worker, or a lone producer — creates the target before the queue that points at it, link intact:

```ts
// No `process`: jobs wait here for inspection. Give it one to handle failures automatically.
export const webhooksDlq = Mochi.queue('webhooks-dlq');
export const webhooks = Mochi.queue('webhooks', { process: deliverWebhook, retryLimit: 3, deadLetter: webhooksDlq });

await Mochi.serve({ queues: [webhooks, webhooksDlq] });
```

A descriptor-form target does not need to be in the `queues` array — it is ensured in storage either way, but only mounted (worker started, handle resolvable) where it is declared. The string form (`deadLetter: 'webhooks-dlq'`) still works when the target is declared in the same array or already exists in storage. A dead-letter _loop_ (A→B→A) cannot be created from scratch — each target must exist before its referrer — though an existing loop that matches the declaration passes.

Drain or replay a dead-letter queue through the [escape hatch](#mochiboss): `Mochi.boss().redrive('webhooks-dlq')` moves its jobs back to their source queue.

Removing the link is a config change like any other: delete the option from code and migrate — [`sync`](#storage) clears it, or run the `updateQueue(name, { deadLetter: null })` the mismatch error prints.

<Callout type="info">

**Resetting a queue.** `Mochi.boss().deleteQueue(name)` removes a queue outright — jobs included, pending backlog and failed-job audit trail alike; the next boot recreates it from the declaration. A queue still referenced as another's `deadLetter` cannot be deleted until its referrers are repointed or deleted first.

</Callout>

### Long-running jobs

A job may stay active for `expireInSeconds` (default **900**) before the store assumes the worker died and retries or fails it. Raise it above the **worst-case** runtime of `process`, not the typical one — a job that outlives it is handed out again while the original still runs, firing its side effects twice:

```ts
Mochi.queue('transcode', { process: transcodeVideo, expireInSeconds: 3600 });
```

A deployment can override every queue at once with the [`queue:expireInSeconds`](/docs/extensions/) filter.

### `Mochi.boss()`

Everything Mochi does not wrap — fetching and cancelling jobs, `findJobs`, `redrive`, queue stats — is reachable on the shared [bun-boss](https://github.com/khromov/bun-boss) instance:

```ts
const stats = await Mochi.boss().getQueueStats('emails');
await Mochi.boss().cancel('emails', jobId);
```

It is available from the [`mochi:queuesMounted`](/docs/extensions/#mochiqueuesmounted) hook onwards (or once a standalone producer has connected) and throws before that, or when no queues are declared.

<Callout type="info">

**Queues mount late.** They are created after the `mochi:init` hook and after the server binds, so `Mochi.getQueue()` and `Mochi.boss()` throw if called from `mochi:init`. Add jobs from the `mochi:queuesMounted` hook onwards: the `mochi:ready` hook, or any request handler.

</Callout>

### Observability

Queues emit [events](/docs/events/) on `mochiEvents`: `queue:added`, `queue:addedBulk`, `queue:active`, `queue:completed`, `queue:failed`, `queue:error`. The [console logger](/docs/logging/) prints a `QUEUE` line for `added`, `addedBulk`, `completed`, `failed`, and `error` at `warn`. Wire your own metrics:

```ts
import { mochiEvents } from 'mochi-framework';

mochiEvents.on('queue:completed', ({ queue, jobId, duration }) => {
  metrics.timing('queue.job', duration, { queue });
});
```

`queue:completed` and `queue:failed` fire per attempt, as the processor settles — an immediate `Mochi.boss().findJobs()` from a listener may still see the job `active` for a beat. An `addBulk` emits `queue:added` per inserted job (flagged `bulk: true`) plus one `queue:addedBulk` summary — the console logger prints only the summary, so a 100k-job bulk add logs one line.

When a queue's backlog crosses the warning threshold (`warningQueueSize`, default `10000`), Mochi logs a `[queue]` warning that names the offending queue and its current depth — e.g. `[queue] Warning: large queue backlog. Your queue should be reviewed (queue "emails" has 12345 jobs queued)`.

### Dev mode & hot reload

`Mochi.serve({ queues })` starts the queue runtime once, so the dev route hot-reload watcher cannot spawn a duplicate consumer. The trade-off: **changes to a queue's `process` function or options do not hot-reload**. Restart the dev server to apply them.

### Shutdown

Queues close gracefully on `SIGTERM`/`SIGINT`. In-flight jobs get up to `queueShutdownTimeout` (default 10 seconds) to finish; a job still running after that is failed and follows its queue's retry policy from the store. Raise it for handlers that legitimately run longer than 10s, so a job in flight at shutdown finishes instead of being re-run:

```ts
Mochi.serve({ queues, queueShutdownTimeout: 60_000 }); // or Mochi.worker({ queues, queueShutdownTimeout })
```

<VersionNote since="0.10.0" message="queueShutdownTimeout was added in 0.10.0; before it, the queue graceful-drain window was fixed at 10s." />

It is distinct from `shutdownTimeout`, which bounds the HTTP-server drain. For a worker process with an HTTP port (health checks, metrics), use `Mochi.serve({ queues })` with no `routes` — [`Mochi.worker()`](#standalone-workers) is the serverless alternative:

```ts
// worker.ts — run with `bun worker.ts`
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  queueStorage: { postgres: process.env.DATABASE_URL },
  queues: [
    Mochi.queue('emails', {
      process: async (job) => {
        await sendEmail(job.data.to);
      },
    }),
  ],
});
```

<Callout type="info">

**Dispatch is instant in-process, polled across processes.** An `add()` from the serving process wakes its worker immediately. Other processes sharing Postgres storage — and deferred or retried jobs everywhere — are picked up on the worker's poll, every `pollingIntervalSeconds` (default 2, minimum 0.5).

</Callout>

### `Mochi.stop()`

`Mochi.stop()` runs the same graceful teardown as `SIGTERM`/`SIGINT` — the `mochi:shutdown` hook, queue drain, server stop — without exiting the process, so a finite-lifetime script or test ends naturally. In a [standalone producer](#standalone-producers) process it closes the queue runtime. It is idempotent, and a stopped process cannot `Mochi.serve()` again.

```ts
await Mochi.serve({ routes, queues });
// … later, from a test or an embedding script:
await Mochi.stop();
```

<SeeItInAction
demos={[{ href: "/demos/queue/", title: "Background jobs with queues", hook: "How background job queues work — offload work to a Mochi.queue() with an embedded worker, no Redis." }]}
/>

---
title: 'Email'
slug: email
ogTitle: 'Sending transactional email'
description: 'Send transactional email with Mochi.email() over SMTP, a custom send function, or Svelte templates rendered to inlined HTML.'
---

<script>
  import { Image } from 'mochi-framework/image';
  import Callout from './_components/Callout.svelte';
  import emailOutbox from './images/email-outbox.png';
</script>

## Email

Send transactional mail — password resets, verification links, notifications — with `Mochi.email()`. Configure a **transport** once under `Mochi.serve({ email })`, then send from anywhere on the server: a page action, an API route, or a queue job.

```ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  routes: {/* … */},
  email: {
    from: 'noreply@acme.dev',
    transport: { type: 'smtp', host: 'smtp.acme.dev', port: 587, auth: { user, pass } },
  },
});

// from an action, API handler, or queue job:
await Mochi.email({
  to: 'alice@example.com',
  subject: 'Reset your password',
  html: '<p>Click <a href="…">here</a> to reset.</p>',
});
```

<Callout type="warning">

With no transport configured, `Mochi.email()` uses the **dev** transport in development (captured to an in-memory viewer) and the **log** transport in production (logged only). Neither delivers. Configure a real transport before relying on delivery.

</Callout>

### The message

Envelope fields, plus the body:

```ts
await Mochi.email({
  to: 'alice@example.com', // string or string[]
  from: 'noreply@acme.dev', // optional — falls back to email.from
  cc,
  bcc,
  replyTo,
  subject: 'Welcome',
  component: './src/emails/Welcome.svelte', // the body — see "The body"
  props: { name: 'Alice' },
  attachments: [{ filename: 'invoice.pdf', content: bytes }],
  headers: { 'X-Entity': 'signup' },
});
```

`Mochi.email()` resolves the body, fills `from` from `email.from`, normalizes recipients, sends, and resolves to a `MochiEmailResult` (`{ transport, messageId?, accepted?, rejected? }`).

Any address field accepts a display name in the standard `Name <addr>` form:

```ts
await Mochi.email({ from: 'Acme <noreply@acme.dev>', to: 'Alice <alice@example.com>', subject, text });
```

### The body

A message has two parts:

- **The HTML part** — an `html` string **or** a `component` (a Svelte template rendered to inlined HTML). If you pass both, `component` wins.
- **The text part** — the `text` string. Mochi derives it from the HTML when you omit it, so the message stays multipart.

```ts
// HTML + your own plain-text alternative (recommended):
await Mochi.email({ to, subject, html: '<h1>Hi</h1>', text: 'Hi' });

// A Svelte component + your own plain-text alternative:
await Mochi.email({ to, subject, component: './src/emails/Welcome.svelte', props: { name: 'Alice' }, text: 'Welcome, Alice' });

// HTML only — Mochi derives the text part:
await Mochi.email({ to, subject, html: '<h1>Hi</h1>' });

// Plain-text only:
await Mochi.email({ to, subject, text: 'Hi' });
```

Supply `text` yourself when you can. The auto-derived fallback strips tags from your HTML, so a hand-written version usually reads better.

### Transports

Set `email.transport` to one of four shapes. Omit it for the environment default: **dev** in development, **log** in production.

**SMTP** — delivers over SMTP through [nodemailer](https://nodemailer.com/):

```ts
email: {
  from: 'noreply@acme.dev',
  transport: {
    type: 'smtp',
    host: 'smtp.acme.dev',
    port: 587,            // default 465 when secure, else 587
    secure: false,       // default: port === 465
    auth: { user: '…', pass: '…' },
    pool: true,
  },
}
```

**Custom** — an escape hatch for any HTTP email API (Resend, SES, Postmark) with no SDK. Receives the resolved message. No SMTP library is loaded:

```ts
email: {
  from: 'noreply@acme.dev',
  transport: {
    type: 'custom',
    send: async (msg) => {
      const res = await fetch('https://api.resend.com/emails', {
        method: 'POST',
        headers: { Authorization: `Bearer ${process.env.RESEND_KEY}`, 'Content-Type': 'application/json' },
        body: JSON.stringify({ from: msg.from, to: msg.to, subject: msg.subject, html: msg.html }),
      });
      const { id } = await res.json();
      return { messageId: id };
    },
  },
}
```

**Dev** (default in development) — captures each message into an in-memory outbox you can browse. Set it explicitly with `{ type: 'dev' }`.

**Log** (default in production) — logs a one-line summary. Set it explicitly with `{ type: 'log' }`.

### The dev outbox

The `dev` transport stores each message in the dev-server process and serves a viewer at **`/_mochi/email`**. The viewer renders the HTML in a sandboxed iframe, plus the plain-text part, the raw source, recipients, headers, and attachments. When the `dev` transport is active, an envelope icon in the [debug bar](/docs/debug-bar/) links to it.

<figure>
  <Image src={emailOutbox} size="doc" width={emailOutbox.width} height={emailOutbox.height} alt="The dev outbox: a list of four captured messages on the left, and on the right the selected message's from, to and date, an attachment chip, Preview / Text / Source tabs, and the rendered email body" />
  <figcaption>The outbox after sending four messages. The <code>Preview</code> / <code>Text</code> / <code>Source</code> tabs switch between the rendered HTML, the plain-text alternative, and the raw source.</figcaption>
</figure>

<Callout type="info">

The outbox is in-memory and dev-only. It holds the most recent 100 messages, is wiped on restart, and the `/_mochi/email` route is not registered in production.

</Callout>

Leaving `transport` unset gives you the dev/log split automatically. To pick the transport by hand, branch on `NODE_ENV` — this options object is evaluated before `Mochi.serve()` resolves [`isDev`](/docs/environment-constants/#isdev), so read the env var directly here:

```ts
await Mochi.serve({
  routes: {/* … */},
  email: {
    from: 'noreply@acme.dev',
    transport: process.env.NODE_ENV === 'production' ? { type: 'smtp', host: 'smtp.acme.dev', port: 587, auth: { user, pass } } : { type: 'dev' },
  },
});
```

### Svelte templates

Author a body as a Svelte component. Pass its path as `component` (like `Mochi.page()`) plus `props`. Mochi renders it and **inlines its scoped CSS** into `style=""` attributes (via [css-inline](https://github.com/Stranger6667/css-inline)) for email-client compatibility.

Keep templates in **`src/emails/`**. `mochi-framework build` walks that directory and compiles every `.svelte` under it into the manifest, so production sends need neither the compiler nor your Svelte sources.

<Callout type="info">

A template outside `src/emails/` still renders, but the build cannot prebuild it. The first send in each process pays a full compile and logs a manifest-miss warning. Move it into `src/emails/` and rebuild.

</Callout>

```svelte
<!-- ./src/emails/Welcome.svelte -->
<script lang="ts">
  let { name }: { name: string } = $props();
</script>

<div class="card"><h1>Welcome, {name}</h1></div>

<style>
  .card {
    padding: 24px;
  }
  h1 {
    color: #6b46c1;
  }
</style>
```

```ts
await Mochi.email({
  to: 'alice@example.com',
  subject: 'Welcome to Acme',
  component: './src/emails/Welcome.svelte',
  props: { name: 'Alice' },
});
```

<Callout type="info">

Email templates always render outside the request context, even when sent from a route action. Request-context APIs (`getRequestContext`, `cookies`, `url`) throw. Pass everything the template needs through `props`.

</Callout>

<Callout type="danger">

**No islands in emails.** A `mochi:hydrate*` island or a `mochi:defer*` server island — anywhere in the template or in anything it imports — is a hard error. Email clients run no JavaScript. Render the content inline instead.

</Callout>

<Callout type="warning">

`<script>` tags in an email body are stripped during rendering. Email clients block scripts, so a script only bloats the message and trips spam filters. The component's own `<script>` block (props, logic) is compile-time and never reaches the output, so it is unaffected. The strip applies to scripts you emit into the markup, for example through `<svelte:head>` or `{@html}`.

</Callout>

<Callout type="warning">

CSS inlining is best-effort, and email clients support only a limited, inconsistent subset of CSS. Rules that cannot inline (media queries, pseudo-classes) stay in a `<style>` block that some clients strip. Modern layout (flexbox/grid, custom properties) is unreliable. Favor simple, table- and inline-style-friendly markup, and test in the clients you care about.

`@font-face` rules are dropped from the message, with a warning: most clients ignore web fonts, and the ones that don't still count the bytes against the size at which Gmail clips a message. Use a font stack the client already has.

</Callout>

### Sending in the background

Delivery is slow and can fail. Offload the send to a [`Mochi.queue()`](/docs/queues/) so the action returns immediately and a background worker runs `Mochi.email()` with retries.

```ts
// jobs.server.ts
import { Mochi } from 'mochi-framework';

export const emailQueue = Mochi.queue<{ to: string; name: string }>('emails', {
  concurrency: 5,
  retryLimit: 2,
  process: async (job) => {
    await Mochi.email({
      to: job.data.to,
      subject: 'Welcome to Acme',
      component: './src/emails/Welcome.svelte',
      props: { name: job.data.name },
    });
  },
});
```

<Callout type="info">

A job runs outside an HTTP request, so the `process` function — and any Svelte template it renders — cannot reach `getRequestContext`, `cookies`, or `url`. Put everything the message needs into the job payload, which must be serializable.

</Callout>

### Intercepting messages

The [`email:message` filter](/docs/extensions/#emailmessage) runs on the fully-resolved message right before the transport. It can rewrite the message (audit BCC, `List-Unsubscribe` headers, a staging catch-all) or return `null` to suppress the send. Prefer it over a `custom` transport when you only need to touch the message.

```ts
await Mochi.serve({
  filters: {
    'email:message': (message) => ({ ...message, bcc: [...(message.bcc ?? []), 'audit@app.dev'] }),
  },
  routes,
});
```

### Observability

Each send emits `email:sent` (`{ to, subject, transport, messageId?, duration }`). Failures emit `email:error` (`{ to, subject, transport, error }`). A send vetoed by the `email:message` filter emits `email:sent` with `transport: 'suppressed'`. `consoleLogger()` formats them as `MAIL` lines. Successful deliveries log at `info`. The two "did not deliver" cases — the `log` transport and any `email:error` — log at `warn`.

### Keeping recipients and subjects out of logs

`MAIL` lines print recipients and the subject. Both are PII, so `email.filterPii` defaults to `true` in production (redacted) and `false` in development. Set it explicitly to override:

```ts
await Mochi.serve({
  email: {
    from: 'noreply@acme.dev',
    transport: { type: 'smtp', host: 'smtp.acme.dev', port: 587, auth: { user, pass } },
    filterPii: true, // redact recipients + subject from MAIL log lines
  },
  routes,
});
```

The transport, error, and duration are still logged, so the lines stay useful. `filterPii` affects `consoleLogger()` output only. The `email:sent` / `email:error` events still carry the real `to` and `subject`, so your own `mochiEvents` subscribers get the full values.

---
title: 'Persistence'
slug: persistence
description: 'Which storage backends each stateful Mochi feature supports — in-memory, file, SQLite, Postgres, or your own store.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import PersistenceTable from './_components/PersistenceTable.svelte';
</script>

## Persistence

A few Mochi features keep server-side state that outlives a single request — queued jobs, cached values, rate-limit counters, spent captcha nonces. Each one defaults to in-memory storage and can be pointed at something durable instead.

<PersistenceTable />

### Per feature

- **[Queues](/docs/queues/)** — in-memory by default. Point the serve-level `queueStorage` (or a descriptor's `storage`) at a SQLite file (`{ sqlite: path }`), a Postgres database (`{ postgres: url }`), or an embedded PGlite instance (`{ pglite }`). One store serves every queue; Postgres storage is shared, so multiple processes can work one backlog.
- **[Cache](/docs/cache/)** — `new MochiCache({ storage })`. Defaults to `MemoryStorage`; `FileStorage` writes one JSON file per entry. Built-in SQLite and Postgres backends are planned; until then any other backend is a `Storage` implementation (`getItem` / `setItem` / `removeItem` / `clear`), with `serialize` / `deserialize` when the backend needs strings.
- **[Image cache](/docs/images/)** — the one feature that persists by default: `FileStorage` under `cacheDir`. Pass `image: { storage }` to swap it (e.g. `new MemoryStorage()`); `cacheDir` is then ignored.
- **[Rate limiting](/docs/rate-limiting/)** — `rateLimit: { store }`. `rateLimitMemoryStore()` (default), `rateLimitSqliteStore({ path })` and `rateLimitPostgresStore({ url })` all ship with the framework; `MochiRateLimitStore` is the interface for your own. Create the store once and share the instance across routes.
- **[Captcha](/docs/captcha/)** — `captcha: { store: 'memory' | 'sqlite' }`, plus `storePath` for the SQLite file. A custom `NonceStore` needs only `consume(nonce, expiresAt)`.

### Choosing a backend

| Backend       | Survives restart | Shared across instances | Use it when                                                     |
| ------------- | ---------------- | ----------------------- | --------------------------------------------------------------- |
| **In-memory** | No               | No                      | Development, single-process apps, state that's cheap to rebuild |
| **File**      | Yes              | Only on shared storage  | Caches whose entries are large blobs (images, API responses)    |
| **SQLite**    | Yes              | Only on shared storage  | One host, one process — durability without another service      |
| **Postgres**  | Yes              | Yes                     | Several instances behind a load balancer                        |

<Callout type="warning">

In-memory state is **per process**. Two instances of your app each get their own rate-limit counters and their own spent-nonce set, so limits effectively multiply and a captcha nonce can be replayed once per instance. Pick a shared backend before you scale out.

</Callout>

---
title: 'Scheduled jobs'
slug: scheduled-jobs
ogTitle: 'Durable scheduled jobs with Mochi.cron()'
description: 'Run recurring work on a cron schedule with Mochi.cron(), backed by a durable, multi-node scheduler.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import VersionNote from './_components/VersionNote.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Scheduled jobs

<VersionNote since="0.10.0" message="Mochi.cron() and the serve-level cron option ship in the next Mochi release (0.10.0). This page describes the upcoming API." />

Run recurring work — nightly cleanups, hourly syncs, a weekly digest — on a cron schedule. `Mochi.cron()` declares a job; `Mochi.serve({ cron })` starts it. Jobs are **durable** and **run once across a multi-node setup**: the schedule is persisted and a single node is elected per firing, so scaling to N nodes does not fire a job N times.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';
import { routes } from './routes';

const cleanup = Mochi.cron('cleanup', '0 3 * * *', async () => {
  await purgeExpiredSessions();
});

await Mochi.serve({ cron: [cleanup], routes });
```

The third argument is the handler — a bare function as above, or `{ run, … }` when you need [options](#options). The descriptor is inert until `Mochi.serve()` starts it, so declaring one at module scope is free.

### Storage

`cronStorage` sets where schedules and their jobs live:

```ts
await Mochi.serve({
  queueStorage: { postgres: process.env.DATABASE_URL },
  cronStorage: { sqlite: '.db/cron.sqlite' }, // cron on its own store
  cron: [cleanup],
});
```

- Accepts `memory`, `{ sqlite }`, `{ postgres }`, or `{ pglite }`.
- **Defaults to `memory`**, independent of `queueStorage`. Cron always runs on its own instance under its own `mochi_cron` namespace — a Postgres schema, or a table-name prefix on SQLite — so queues and cron never share tables even when pointed at the same store.

<Callout type="info">

Pointing both at the **same SQLite file** is safe table-wise but puts two writers on one file. Give cron its own file when both are durable.

</Callout>

<Callout type="warning">

`memory` (and any per-node store) coordinates the run-once guarantee only **within one process**. For a multi-node deployment, point `cronStorage` at shared storage — Postgres, or a SQLite file on a shared volume.

</Callout>

### Schedules

Standard 5-field cron syntax — `minute hour day-of-month month day-of-week` — plus the nicknames `@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`. Month and weekday accept names (`MON-FRI`, `JAN`). Resolution is **one minute** — the smallest interval is `* * * * *`.

```ts
Mochi.cron('every-15-min', '*/15 * * * *', run);
Mochi.cron('weekdays-at-9', '0 9 * * MON-FRI', run);
Mochi.cron('nightly', '@daily', run);
```

An invalid expression throws **at declaration**, not at boot, so a typo fails when the module is imported rather than after a deploy.

### Options

Instead of a bare handler, pass `{ run, … }`:

- `tz` — IANA time-zone name the schedule is read in. Defaults to **UTC** — durable cron reads one zone across every node.
- `dev` — set `false` to skip the job when `development: true`. Default `true`.

```ts
Mochi.cron('digest', '0 9 * * MON', {
  tz: 'Europe/Stockholm',
  dev: false,
  run: async () => sendWeeklyDigest(),
});
```

### Runs once, transactionally, across a multi-node setup

Each firing is claimed by exactly one node through an atomic database update, and the enqueue is deduplicated by a per-minute key. You do **not** need to hand-roll an idempotency key — the scheduler handles the race, and it corrects for clock skew against database time. This is the reason cron is durable rather than a per-node timer.

### A run is a queue job

A scheduled run executes internally as a [queue](/docs/queues/) job named `cron-<name>`, so its lifecycle surfaces through the queue events — `queue:active`, `queue:completed`, `queue:failed` with `queue: "cron-<name>"`. Registration emits one `cron:scheduled` event.

A handler that throws is reported through `queue:failed` and logged; the schedule stays registered and runs again at its next occurrence.

The handler receives the run: `{ name, schedule, scheduledTime, tz? }`. `scheduledTime` is the epoch ms at which the scheduler claimed the firing — the same value on every retry of that firing, so it works as an idempotency key.

```ts
Mochi.cron('sync', '*/15 * * * *', async ({ name, scheduledTime }) => {
  await syncOnce(`${name}:${scheduledTime}`);
});
```

<Callout type="info">

The `cron-` prefix is reserved: a `Mochi.queue()` name may not start with it, so cron jobs and queues never collide.

</Callout>

### Editing and removing jobs

Schedules persist in the database. On each boot Mochi reconciles: it registers the declared jobs and **removes any schedule it manages that is no longer declared**, so deleting a `Mochi.cron()` line cleans up its schedule instead of leaving an orphan that keeps enqueuing jobs no worker consumes. In development, editing the `cron` array re-registers on save — no dev-server restart needed.

### Shutdown

The scheduler stops on `SIGTERM`/`SIGINT`, on `server.stop()`, and on [`Mochi.stop()`](/docs/queues/#mochistop). Schedules are **not** removed on shutdown — they are durable and resume on the next boot.

<SeeItInAction
demos={[{ href: "/demos/cron/", title: "Scheduled jobs with cron", hook: "A Mochi.cron() job appends to an in-memory log every minute; the browser streams each new entry over a WebSocket." }]}
/>

---
title: 'Middleware (hooks)'
slug: middleware
description: 'Intercept and transform requests and responses with SvelteKit-style handle functions.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Middleware (hooks)

Middleware uses `Handle` functions registered through `Mochi.serve({ handle })`. Each handle receives `{ event, resolve }`, mutates `event` as needed, calls `resolve(event)` to continue the chain, and returns the resulting `Response`.

### `Handle`

A `Handle` is `async ({ event, resolve }) => Response`. `event` carries `{ request, url, server, locals, kind }`. `resolve(event)` invokes the next middleware or the final route handler and returns its `Response`.

```ts
// file: src/handle.ts
import type { Handle } from 'mochi-framework';

export const auth: Handle = async ({ event, resolve }) => {
  if (!event.request.headers.get('Authorization')) {
    return new Response('Unauthorized', { status: 401 });
  }
  return resolve(event);
};
```

<Callout type="warning">

**Await `resolve()` to post-process responses.** To inspect or modify the response, use `const response = await resolve(event)` and return it explicitly. Without `await`, your function completes before post-processing finishes, causing silent data loss and race conditions.

</Callout>

### `event.locals`

`event.locals` is a per-request object for passing data between middleware layers and into route handlers. Read it from any server-side context with `getRequestContext().locals`.

```ts
// file: src/handle.ts
import type { Handle } from 'mochi-framework';

export const attachUser: Handle = async ({ event, resolve }) => {
  event.locals.user = await loadUser(event.request);
  return resolve(event);
};
```

### `event.kind`

Every event carries a `kind` that describes what the framework is about to do with the request:

| Value        | When                                                                         |
| ------------ | ---------------------------------------------------------------------------- |
| `'page'`     | `Mochi.page` route (GET render or POST form action)                          |
| `'api'`      | `Mochi.api` route                                                            |
| `'asset'`    | Framework static asset (`.js` / `.css` client bundle or the dev stats route) |
| `'fallback'` | Unmatched URL — passed to your `fetch` handler                               |
| `'error'`    | Unmatched URL with no `fetch` configured — framework renders a 404           |

`kind` is set once at construction. An error thrown during a `Mochi.page` render stays `kind: 'page'`.

Use it to opt out of per-request work for framework assets:

```ts
// file: src/handle.ts
import type { Handle } from 'mochi-framework';

export const auth: Handle = async ({ event, resolve }) => {
  if (event.kind === 'asset') return resolve(event);
  if (!event.request.headers.get('Authorization')) {
    return new Response('Unauthorized', { status: 401 });
  }
  return resolve(event);
};
```

### `sequence`

Compose multiple handles into one with `sequence(...handlers)`. Handles run in order. The first handle's pre-processing runs first, and its post-processing runs last (nested-middleware semantics).

```ts
// file: src/index.ts
import { Mochi, sequence } from 'mochi-framework';
import { auth, logging, rateLimit } from './handle';

await Mochi.serve({
  handle: sequence(auth, logging, rateLimit),
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});
```

### `resolve(event, opts)`

`resolve` accepts an options bag for post-processing the response:

- `transformPage({ html, done })` — rewrite the HTML body before it is sent. See [`transformPage`](/docs/transform-page/).
- `filterResponseHeaders(name, value)` — return `true` to keep a header, `false` to drop it.

```ts
// file: src/handle.ts
import type { Handle } from 'mochi-framework';

export const stripServerHeader: Handle = ({ event, resolve }) =>
  resolve(event, {
    filterResponseHeaders: (name) => name.toLowerCase() !== 'server',
  });
```

When composed with `sequence`, `transformPage` runs in **reverse** order (inner handle transforms first, outer wraps the result). `filterResponseHeaders` uses **first-defined-wins** — only the earliest handle's filter applies.

### `compress`

Built-in middleware factory for response compression. It negotiates gzip, zstd or deflate from the client's `Accept-Encoding`. Place it innermost in `sequence(...)` so it sees the body produced by the rest of the chain:

```ts
// file: src/index.ts
import { Mochi, sequence, compress } from 'mochi-framework';

await Mochi.serve({
  handle: sequence(auth, logging, compress()),
  routes,
});
```

Options:

- `methods` — the encodings the server is willing to use: `'gzip'`, `'zstd'`, `'deflate'`. Defaults to `['zstd', 'gzip']`. The client's `Accept-Encoding` picks the winner. The array order is only a tiebreak when the client expresses no preference.

```ts
sequence(auth, compress({ methods: ['gzip'] }));
sequence(auth, compress({ methods: ['zstd', 'gzip'] }));
```

Every encoding streams through one `CompressionStream`, so a chunked SSR response stays chunked and the client sees the first bytes before the handler has finished. Brotli is intentionally not offered — Bun's `CompressionStream("brotli")` is fixed at quality 11, far too slow for per-request SSR — so reach for `zstd` when you want brotli-class ratios without giving up streaming; a client that only accepts `br` is served uncompressed. Brotli returns once Bun's `CompressionStream` accepts a quality level. A `methods` entry this build does not support — `'brotli'`, carried over from an older config — is dropped with a warning at startup, leaving the remaining methods in play.

`compress()` is a no-op in development, because the debug bar must inject itself into the HTML after the response is built. In production it adds `Vary: Accept-Encoding` and compresses compressible content types (`text/*`, `application/json`, `application/javascript`, `application/xml`, and others). A response that already declares `Content-Encoding` passes through untouched. Static framework assets also flow through `handle`, so `compress()` covers them. Other body-touching middleware must branch on `event.kind === 'asset'` when it needs to skip framework bundles.

### `noCache`

Built-in middleware that defaults `Cache-Control: no-cache` on `page` and `api` responses. A route that sets its own `Cache-Control` is left untouched, so opt-in caching works per route.

```ts
// file: src/index.ts
import { Mochi, sequence, noCache, compress } from 'mochi-framework';

await Mochi.serve({
  handle: sequence(noCache, compress()),
  routes,
});
```

`asset`, `fallback`, and `error` events pass through unchanged. WebSocket upgrades and SSE streams never reach the middleware.

<SeeItInAction
demos={[{ href: "/demos/request-id/", title: "Request ID", hook: "How request IDs work — every request gets a UUID v7 on getRequestContext().requestId that rides every lifecycle event for correlation." }]}
/>

---
title: 'Trailing slash'
slug: trailing-slash
ogTitle: 'Trailing-slash policy and redirects'
description: 'Enforce a consistent trailing-slash policy for your page routes with automatic redirects.'
---

<script>
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Trailing slash

The `trailingSlash` option on `Mochi.serve()` enforces a consistent trailing-slash policy across your `Mochi.page()` routes. Mochi registers each page under both `/foo` and `/foo/`, then redirects requests to the non-canonical form. `Mochi.api()`, `Mochi.sse()`, `Mochi.ws()` and `Mochi.file()` routes are exempt — see below.

```ts
await Mochi.serve({
  trailingSlash: 'always',
  routes,
});
```

### Policy values

| Value      | Canonical form | Example redirect     |
| ---------- | -------------- | -------------------- |
| `'never'`  | No slash       | `/about/` → `/about` |
| `'always'` | Trailing slash | `/about` → `/about/` |

Default: unset. Neither form is redirected, and only the form you registered is matched.

### Only page routes follow the policy

<VersionNote since="0.10.0" message="Before 0.10.0, api and sse routes were mirrored and redirected like pages, ws and extensionless file routes answered on both slash forms without redirecting, and paths matching no route were redirected to the canonical form before 404ing." />

`trailingSlash` never applies to `Mochi.api()`, `Mochi.sse()`, `Mochi.ws()` or `Mochi.file()` routes — no mirroring, no redirect, regardless of policy. Only the exact pattern you declared matches; the other slash form 404s like any unregistered path.

```ts
await Mochi.serve({
  trailingSlash: 'always',
  routes: {
    '/about': Mochi.page(About), // /about → 301 → /about/
    '/api/ping': Mochi.api(() => json({ ok: true })), // only /api/ping matches
    '/sse/time': Mochi.sse(clock), // only /sse/time matches
    '/ws/chat': Mochi.ws(chat), // only /ws/chat matches
  },
});
```

A canonical URL is a navigation concern: it matters for links, crawlers and caches, which is what pages have and what a JSON fetch, an `EventSource` or a WebSocket does not.

A raw Bun route value (a bare `Response` or `{ GET }` object) isn't one of these helpers, so it still answers on both forms when a policy is set.

### Redirect status codes

| Method                        | Status                 |
| ----------------------------- | ---------------------- |
| `GET`, `HEAD`                 | 301 Moved Permanently  |
| `POST` (pages with `actions`) | 308 Permanent Redirect |

308 preserves the request method and body, so `<form method="POST" action="/submit">` still works after a redirect. The 308 only happens for pages that declare `actions`: those are the only pages registered for POST. A page without `actions` accepts just GET/HEAD, so a POST to it matches no route — it 404s instead of redirecting.

### Paths that are never redirected

- The root path `/` — already canonical.
- Paths with file extensions (`.css`, `.js`, `.png`, …) — browsers and CDNs expect exact asset URLs.
- Anything that isn't a `Mochi.page()` route.
- Paths that match no route — they 404 (or reach your `fetch` fallback) in whichever slash form they arrived, with no canonicalization hop.

### Query strings

Mochi preserves query parameters in the redirect target:

```
GET /search/?q=mochi  →  301  Location: /search?q=mochi   (policy: 'never')
GET /search?q=mochi   →  301  Location: /search/?q=mochi  (policy: 'always')
```

### Generating canonical links

`trailingSlashIt(path)` appends a trailing slash, first stripping any the string already ends with. It preserves a query string or `#fragment` and puts the slash on the path, so you can pass a full URL. Build hrefs with it under `trailingSlash: 'always'` so links point at the canonical URL and skip the redirect hop.

Apply it to page URLs only. Every other kind has no slashed form, so `trailingSlashIt('/api/ping')` yields a URL that 404s.

```ts
import { trailingSlashIt } from 'mochi-framework';

trailingSlashIt('/docs/intro'); // '/docs/intro/'
trailingSlashIt('/docs/intro/'); // '/docs/intro/'
trailingSlashIt('/'); // '/'
trailingSlashIt('/search?q=mochi'); // '/search/?q=mochi'
trailingSlashIt('/docs/intro#install'); // '/docs/intro/#install'
```

It is isomorphic — import it in SSR pages, hydrated islands, and plain `.ts` modules.

---
title: 'Rate limiting'
slug: rate-limiting
description: 'Per-route and global request rate limiting with memory, SQLite, and Postgres stores.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import PersistenceTable from './_components/PersistenceTable.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Rate limiting

Add a `rateLimit` config to any `Mochi.page()` or `Mochi.api()` route. It is driven by [`@joint-ops/hitlimit-bun`](https://www.npmjs.com/package/@joint-ops/hitlimit-bun), and the options pass straight through.

<PersistenceTable feature="rate-limiting" />

```ts
'/api/data': Mochi.api(handler, {
  rateLimit: { limit: 100, window: '1m' },
}),
'/pricing': Mochi.page('./src/Pricing.svelte', {
  rateLimit: { limit: 5, window: '1m' },
}),
```

Mochi keys requests by client IP by default. Over the limit:

- **API routes** return a `429` JSON body (`{ hitlimit: true, message, limit, remaining, resetIn }`).
- **Page routes** render your [error page](/docs/error-handling/) with status `429`. Enhanced form submissions get JSON, like other form errors.

A blocked request never reaches your [`handle` middleware](/docs/middleware/) — the `429` is produced before it runs, like a CSRF rejection — but it still emits the standard `request` event, so it appears in [logging](/docs/logging/).

Every limited route's responses carry `RateLimit-*` and `X-RateLimit-*` headers, plus `Retry-After` on a `429`.

### Global default

Set `rateLimit` on `Mochi.serve()` to cover every page and API route. Routes inheriting it share **one bucket per key** — a client's hits on any of them count against the same quota. A route's own config replaces the global one with its own bucket. `rateLimit: false` opts a route out.

```ts
await Mochi.serve({
  routes: {
    '/api/login': Mochi.api(login, { rateLimit: { limit: 5, window: '1m' } }), // own bucket
    '/health': Mochi.api(health, { rateLimit: false }), // exempt
  },
  rateLimit: { limit: 1000, window: '1m' }, // everything else
});
```

### Options

Mochi accepts all of hitlimit's options except `logger` (Mochi logs `429`s through its own [request events](/docs/events/)):

| Option         | Default       |                                                                                           |
| -------------- | ------------- | ----------------------------------------------------------------------------------------- |
| `limit`        | `100`         | Max requests per window                                                                   |
| `window`       | `'1m'`        | `'30s'`, `'1m'`, `'1h'`, `'1d'`, or milliseconds                                          |
| `key`          | client IP     | `(req, ctx) => string` — what to bucket by                                                |
| `store`        | in-memory     | `rateLimitSqliteStore(…)`, `rateLimitPostgresStore(…)`, or a custom `MochiRateLimitStore` |
| `tiers`/`tier` | —             | Named limits + `(req, ctx) => string` tier resolver                                       |
| `ban`          | —             | `{ threshold, duration }` — ban repeat offenders                                          |
| `group`        | route pattern | `string \| (req, ctx) => string` — bucket namespace; same value → shared bucket           |
| `skip`         | —             | `(req, ctx) => boolean` — bypass without consuming quota                                  |
| `response`     | hitlimit JSON | Custom 429 body (API routes)                                                              |
| `headers`      | all on        | `{ standard, legacy, retryAfter }`                                                        |
| `onStoreError` | `'allow'`     | Fail open, or `'deny'` when the store errors                                              |

### Stores

<VersionNote since="0.10.0" message="The store factories were renamed in 0.10.0: memoryStore, sqliteStore and postgresStore are now rateLimitMemoryStore, rateLimitSqliteStore and rateLimitPostgresStore. The old names are gone." />

`rateLimitMemoryStore()` is the default — zero config, per process. Use SQLite for persistence across restarts, or Postgres for shared state across instances. All three are re-exported from `mochi-framework`, and anything else is a custom `MochiRateLimitStore`:

```ts
import { rateLimitMemoryStore, rateLimitSqliteStore, rateLimitPostgresStore } from 'mochi-framework';

rateLimit: { limit: 100, window: '1m', store: rateLimitSqliteStore({ path: './ratelimit.db' }) }
rateLimit: { limit: 100, window: '1m', store: rateLimitPostgresStore({ url: process.env.DATABASE_URL }) }
```

See [Persistence](/docs/persistence/) for how these stores compare with the other Mochi features that persist state.

Mochi buckets counters by **key within a store**. A route with its own `rateLimit` config also folds its route pattern into the key, so different routes backed by the same database keep separate counters, even when the key resolves to the same value. Run the same route on two servers against one database and both write the same key, so they share a counter — that is how you rate-limit across a fleet. Routes inheriting the [global default](#global-default) share one bucket per key by design.

<Callout type="info">

**Overriding the namespace with `group`.** Setting `group` replaces the automatic route-pattern namespace. Give two routes the same `group` and they share one bucket — a single quota across a family of endpoints. Give a route on the global default its own `rateLimit` config to split it into an isolated bucket.

</Callout>

Each store instance owns its backend — a DB connection, prepared statements, and a cleanup timer. Create the store **once** and share the instance. Calling `rateLimitSqliteStore({ path })` inline in every route config opens one connection per route to the same file, all fighting over SQLite's single write lock.

```ts
const store = rateLimitSqliteStore({ path: './ratelimit.db' }); // one connection…
'/api/search': Mochi.api(search, { rateLimit: { limit: 30, window: '1m', store } }), // …own bucket
'/api/upload': Mochi.api(upload, { rateLimit: { limit: 5, window: '1m', store } }), // …own bucket
```

<Callout type="info">

**Dev reloads.** Creating a store inline in a route config builds a fresh store on every save while the old one is never closed, leaking a handle per reload. Counters still persist. If the churn bothers you, keep dev on the default memory store and attach the persisted store in production only.

</Callout>

### Keys and proxies

The default key is Mochi's **proxy-aware** client address — the same value as [`getClientAddress()`](/docs/request-context/), honouring `proxy.addressHeader` / `xffDepth`. Behind a reverse proxy, configure `proxy` or every client shares the proxy's IP:

```ts
await Mochi.serve({ proxy: { addressHeader: 'x-forwarded-for', xffDepth: 1 }, … });
```

Key by anything else with `key`. It receives the `Request` plus Mochi's [request context](/docs/request-context/), so you can bucket by the proxy-aware IP, cookies, params, or your own identity. It can be `async`. `tier`, `group`, and `skip` receive the same two arguments.

```ts
// by API key, falling back to the proxy-aware IP
key: (req, ctx) => req.headers.get('x-api-key') ?? ctx.getClientAddress() ?? 'anon'

// tiered by plan
tiers: { free: { limit: 10 }, pro: { limit: 1000 } },
tier: (req, ctx) => (ctx.locals.plan as string) ?? 'free',
```

<Callout type="warning">

**The limiter runs before your `handle` [middleware](/docs/middleware/).** `ctx` is fully populated — `request`, `url`, `params`, `cookies`, `getClientAddress()` — but `ctx.locals` reflects only what ran before the limiter. A `userId` your auth middleware puts on `locals` is **not** visible here. To key by the logged-in user, derive the identity straight from the request inside `key` (decode the session cookie or bearer token).

</Callout>

### Only counting failures

`skip` bypasses the limiter without consuming quota. Since the limiter runs before your middleware, re-do the credential check inside `skip` so only rejected attempts spend quota. A brute-force run burns the quota. Someone who knows the password is never throttled.

```ts
'/admin': Mochi.page('./src/Admin.svelte', {
  rateLimit: {
    limit: 10,
    window: '15m',
    ban: { threshold: 3, duration: '1h' },
    skip: (req) => credentialsMatch(req.headers.get('Authorization')),
  },
}),
```

`skip` may be `async`, so it is also a natural place for a tarpit. An `await Bun.sleep(…)` on the failing branch delays the rejection without slowing a valid request:

```ts
skip: async (req) => {
  const header = req.headers.get('Authorization');
  // No credentials at all is a browser fetching the 401 challenge, not a guess:
  // do not stall it, and do not charge it quota.
  if (!header || credentialsMatch(header)) return true;
  await Bun.sleep(5000);
  return false;
},
```

### Reading usage server-side

An allowed request exposes its limiter state on the request context. Render quotas in `serverProps` or any server-side code:

```ts
const rateLimit = getRequestContext().rateLimit;
// { limit, remaining, resetIn, resetAt, key, group?, tier? } — or undefined if no limiter ran
```

<Callout type="info">

**Not counted:** [warmup](/docs/serve-options/) requests, trailing-slash redirects, and CSRF rejections never consume quota. In dev, `rateLimit` edits apply on save — a route with its own config gets fresh in-memory counters, and routes on the global limiter keep their shared bucket.

</Callout>

<SeeItInAction
demos={[
{ href: "/demos/rate-limit/", title: "Rate Limiting", hook: "How rate limiting works — a rateLimit config on the route caps requests per IP per minute and serves the 429 error page past the limit." },
]}
/>

---
title: 'Transforming HTML with transformPage'
slug: transform-page
description: 'Rewrite rendered HTML before it is sent to the client with the transformPage callback.'
---

<script>
  import Callout from './_components/Callout.svelte';
</script>

## `transformPage`

Pass `transformPage` to `resolve(event, { transformPage })` inside a `Handle` to rewrite the rendered HTML before it ships. It runs once per response, only on `text/html` bodies, with the full HTML string and `done: true`.

```ts
// file: src/hooks.ts
import type { Handle } from 'mochi-framework';

const greeting: Handle = async ({ event, resolve }) => {
  return resolve(event, {
    transformPage({ html }) {
      return html.replace('{{app.greeting}}', 'Welcome to Mochi!');
    },
  });
};
```

```html
<!-- file: src/shell.html -->
<body>
  <header>{{app.greeting}}</header>
  {{mochi.body}}
</body>
```

The callback receives `{ html, done }` and returns `string | undefined | Promise<string | undefined>`. Returning `undefined` replaces the body with an empty string.

Use it for per-request mutations the shell template cannot express: a request-aware `<html lang>`, nonce injection, or A/B placeholder swaps.

```ts
const lang: Handle = async ({ event, resolve }) => {
  const locale = event.request.headers.get('accept-language')?.slice(0, 2) ?? 'en';
  return resolve(event, {
    transformPage({ html }) {
      return html.replace('<html', `<html lang="${locale}"`);
    },
  });
};
```

Mochi invokes the callback once with the full HTML, not chunk by chunk. `done` is always `true`. Treat it as a whole-document transform.

When `sequence()` chains handlers, transforms run inner-most first and outer-most last. The handler closest to the route sees the original HTML. The outermost wraps the final result.

<Callout type="info">

**Use `transformPage` for request-dependent values only.** Static markup belongs in `src/shell.html` (or the default shell) so it ships without per-request work.

</Callout>

---
title: 'Error handling'
slug: error-handling
description: 'Configure a custom error page and control how uncaught errors render to the client.'
---

<script>
  import { Image } from 'mochi-framework/image';
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
  import errorPage from './images/error-page.png';
</script>

## Error handling

Mochi renders an HTML error page for any uncaught error that escapes a page render: top-level SSR throws, `error(status, ...)` from `serverProps` or actions, malformed form bodies, unknown form actions, and unmatched routes. API routes return a JSON envelope instead. Island-level boundaries are scoped to hydratable islands — see [Error boundaries](/docs/error-boundaries/).

<figure>
  <Image src={errorPage} size="doc" width={errorPage.width} height={errorPage.height} alt="The built-in error page: a large 500 above the message Internal Server Error, a Go home link, and a Stack trace section showing the thrown error" />
  <figcaption>The built-in error page, shown when <code>errorPage</code> is omitted. The stack trace renders only under <code>development: true</code>.</figcaption>
</figure>

Configure the page with `errorPage` on `Mochi.serve()`. Omit it to use the built-in component.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  errorPage: './src/Error.svelte',
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});
```

### `errorPage`

The component receives one `error` prop typed by `MochiErrorProps`.

```svelte
<!-- file: src/Error.svelte -->
<script lang="ts">
  import type { MochiErrorProps } from 'mochi-framework';
  let { error }: MochiErrorProps = $props();
</script>

<h1>{error.status}</h1>
<p>{error.message}</p>
{#if error.stack}<pre>{error.stack}</pre>{/if}
```

| Field     | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| `status`  | HTTP status — `404`, `500`, or whatever was passed to `error()`   |
| `message` | Human-readable message, safe to render                            |
| `stack`   | Stack trace, populated only when `development: true`, else absent |

Default behavior without `errorPage`:

- Unmatched routes → `404 Not Found`.
- Uncaught throws in `serverProps`, page render, or an action handler → `500 Internal Server Error`.
- `error(status, message?)` thrown from any of these → that exact `status`, with the message defaulting to the canonical status text when omitted.

### Request context in the error page

<VersionNote since="0.10.0" message="Before 0.10.0, unmatched-route 404s rendered the error page without a request context." />

`getRequestContext()` works inside the error component — `url`, `cookies`, and `locals` behave as on any page, so a shared nav can read the current path. On unmatched-route 404s the context is minimal: `params` is empty because no route matched.

```svelte
<!-- file: src/Error.svelte -->
<script lang="ts">
  import { getRequestContext, type MochiErrorProps } from 'mochi-framework';
  let { error }: MochiErrorProps = $props();
  const { url } = getRequestContext();
</script>

<h1>{error.status}</h1><p>No page at {url.pathname}</p>
```

### `handleError`

Fires whenever the error page is about to render. Use it to log, forward to error tracking, or sanitize the message the user sees.

```ts
// file: src/index.ts
import type { HandleError } from 'mochi-framework';

const handleError: HandleError = ({ error, event, status, message }) => {
  if (error) tracker.capture(error, { path: event.url.pathname });
  if (status === 404) return Response.redirect(new URL('/', event.url), 302);
  if (status >= 500) return { status, message: 'Something went wrong.' };
};

await Mochi.serve({
  errorPage: './src/Error.svelte',
  handleError,
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});
```

Return one of:

- `{ status, message }` — override either field passed to the error component.
- a `Response` — short-circuit rendering (useful for redirects).
- `void` — keep the defaults.

`error` is `null` when the condition did not come from a throw (unmatched routes, unknown form actions). Inspect it before forwarding so benign 4xx cases do not page on-call.

<Callout type="warning">

**API routes bypass `handleError`.** The hook fires for page routes only. Handle `Mochi.api` failures inside the route with `error()` or `apiError()`:

```ts
Mochi.api(async () => {
  const data = await load();
  if (!data) return apiError(404, 'Not found');
  return json(data);
});
```

</Callout>

If the hook itself throws, Mochi logs the secondary error and renders the error page with the original `status` and `message`.

### API error envelope

`Mochi.api` routes return `{ "error": { "message", "status" } }` with the matching status code. Use `MochiHttpError` (typed throw via `error()`) or `apiError()` (typed return) to produce the envelope. See [API routes](/docs/api-routes/).

<Callout type="warning">

**Use `error(status, message)` to signal status codes.** A bare `throw new Error()` is coerced to a generic 500. Only `error(status, message)` returns the typed error envelope the framework expects.

</Callout>

### Fallback behavior

If your `errorPage` throws during render, Mochi returns a plain-text response mentioning both the original error and the secondary render failure. The error page cannot crash the server.

<SeeItInAction
demos={[{ href: "/demos/error/", title: "Error Handling", hook: "How error handling works — catch render errors and unmatched routes via Mochi.serve()'s errorPage option and the handleError hook." }]}
/>

---
title: 'Error boundaries'
slug: error-boundaries
description: 'Hydratable islands are auto-wrapped in svelte:boundary, so one island failure cannot crash the page.'
---

<script>
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Error boundaries

Mochi auto-wraps every `mochi:hydrate` and `mochi:hydrate:visible` island in `<svelte:boundary>`. A throw inside one island no longer takes down the page render. Mochi marks the failed island with a `<mochi-island-failure>` stub, and the rest of the page continues. No opt-in, no configuration.

### What is wrapped

- `mochi:hydrate` — wrapped.
- `mochi:hydrate:visible` — wrapped.
- `mochi:defer` — handled by the server-island endpoint, not by a boundary.
- Top-level page render throws — go to the configured `errorPage`. See [Error handling](/docs/error-handling/).

### What gets caught

- Synchronous SSR throws inside the island.
- Async SSR throws (`await Promise.reject(...)` in a top-level `<script>`).
- Client-side throws after hydration (`$effect`, `$derived`, synchronous script throws).
- A failure in the island's bundle import or in hydration itself.

A client-side throw logs to the browser console but does **not** emit `island:error`. The event bus is server-side only.

### Visual behavior

<VersionNote since="0.10.0" message="Before 0.10.0 a client-side hydration failure replaced the island's server-rendered markup with the marker." />

In development, the `<mochi-island-failure>` marker is a dashed-red box showing the component name and error message. In production, it is hidden with `display: none`.

What the marker replaces depends on where the failure happened. An SSR throw renders the marker instead of the island. A client-side failure — the bundle import, the CSS load, the props payload, or `hydrate()` itself — keeps the server-rendered markup and appends the marker after it. The static HTML stays on screen; it just never becomes interactive.

### Server islands (`mochi:defer`)

A failed server island returns a `<mochi-island-failure>` stub with status `200`. The `200` is intentional — a `5xx` would trigger the client's retry loop against a deterministic failure. Your fallback children stay visible until the response arrives.

### Author your own boundary

`<svelte:boundary>` works during SSR, so you can use it anywhere:

```svelte
<!-- file: src/SomePage.svelte -->
{#snippet failed(error: Error)}
  <p>Something went wrong: {error.message}</p>
{/snippet}

<svelte:boundary {failed}>
  <SomePieceThatMightThrow />
</svelte:boundary>
```

### `island:error` event

Every server-side island failure emits `island:error` on `mochiEvents`. Subscribe to forward failures to error tracking:

```ts
// file: src/index.ts
import { mochiEvents } from 'mochi-framework';

mochiEvents.on('island:error', ({ componentName, kind, message, stack }) => {
  tracker.capture(message, { componentName, kind, stack });
});
```

| Field           | Description                                                                             |
| --------------- | --------------------------------------------------------------------------------------- |
| `componentName` | Island component name.                                                                  |
| `islandId`      | Per-island id; set for `'server'` failures, else `undefined`.                           |
| `kind`          | `'hydratable'` (SSR throw in a hydratable island) or `'server'` (server-island render). |
| `message`       | Error message, safe to forward.                                                         |
| `stack`         | Stack trace, populated only when `development: true`.                                   |

`MochiIslandErrorKind` also reserves `'client-hydrate'`, but client-side errors are not currently emitted to the event bus.

### See also

- [Error handling](/docs/error-handling/) — top-level page errors and the configured `errorPage`.
- [Selective hydration](/docs/selective-hydration/), [Lazy hydration](/docs/lazy-hydration/), [Server islands](/docs/server-islands/) — the directives boundaries wrap.

<SeeItInAction
demos={[{ href: "/demos/error-boundaries/", title: "Error Boundaries", hook: "How error boundaries work — contain island failures with <svelte:boundary> so one broken component doesn't crash the page." }]}
/>

---
title: 'Utility helpers'
slug: utility-helpers
description: 'Helper functions for building JSON responses, error responses, and form-action results.'
---

<script>
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Utility helpers

Functions exported from `mochi-framework` for shaping responses and form-action results. Each helper is documented in depth where it is used. This page is an index.

### Response helpers

`json(data, init?)` builds a JSON `Response` with the right `Content-Type`. Use it from `Mochi.api()` handlers and middleware.

```ts
import { json } from 'mochi-framework';

return json({ ok: true }, { status: 201 });
```

`error(status, message?)` throws a `MochiHttpError` that the framework catches and renders as the configured error page (or a JSON envelope from API routes). Omit `message` to get the canonical status text — `Not Found`, `Too Many Requests`, … — with unknown codes falling back to `Error <status>`. See [Error handling](/docs/error-handling/).

<VersionNote since="0.10.0" message="Calling error(status) without a message requires mochi-framework 0.10.0." />

```ts
import { error } from 'mochi-framework';

if (!user) error(404, 'User not found');
if (!session) error(401); // → "Unauthorized"
```

`apiError(status, message)` returns a JSON error `Response` shaped as `{ error: { message, status } }`. Use it inside `Mochi.api()` for a typed error without unwinding the stack. See [API routes](/docs/api-routes/).

```ts
import { apiError } from 'mochi-framework';

return apiError(400, 'Missing id');
```

### Form-action helpers

Use these as return values from a `Mochi.page` action. See [Defining routes](/docs/defining-routes/) and [Progressive enhancement](/docs/progressively-enhancing-forms-with-enhance/) for the full action lifecycle.

`fail(status, data)` re-renders the page with `form = { ok: false, action, status, data }` and the given HTTP status. The payload nests under `form.data`, not on `form` itself. Use it for validation errors.

```ts
import { fail } from 'mochi-framework';

if (!username) return fail(400, { error: 'Username required', username });
```

```svelte
{#if form?.data?.error}<p>{form.data.error}</p>{/if}
```

`success(data?)` re-renders the page with `form = { ok: true, action, data }` and HTTP 200. Use it when the action completes and you want to stay on the page.

```ts
import { success } from 'mochi-framework';

return success({ message: 'Saved.' });
```

`redirect(status, location)` issues an HTTP redirect when returned from a form action or a [`serverProps` resolver](/docs/defining-routes/#redirecting-from-serverprops). `status` must be `301`, `302`, `303`, `307`, or `308`. Use 303 for the standard POST/Redirect/GET pattern.

```ts
import { redirect } from 'mochi-framework';

return redirect(303, '/dashboard');
```

### Sealed tokens

`encryptPayload(plaintext, { aad?, compress? })` and `decryptPayload(token, { aad? })` seal a string into an opaque, tamper-proof base64url token (AES-256-SIV keyed from `MOCHI_KEY`) and open it again. `decryptPayload` returns `null` on any tamper or `aad` mismatch. This is the same primitive Mochi uses for server-island props. Use it for short-lived signed values such as form challenges or magic links.

```ts
import { encryptPayload, decryptPayload } from 'mochi-framework';

const token = encryptPayload(JSON.stringify({ iat: Date.now() }), { aad: 'my-form' });
const opened = decryptPayload(token, { aad: 'my-form' }); // string | null
```

### HTML escaping

<VersionNote since="0.10.0" message="escapeHtmlAttr became a public export in 0.10.0." />

`escapeHtmlAttr(value)` replaces `&`, `"`, `<` and `>` with entities. It is the framework's single attribute encoder, so values round-trip exactly through `getAttribute()` — including payloads that already contain entity sequences like `&quot;`, which a bare `"`-only replace would corrupt. It works for text content too.

```ts
import { escapeHtmlAttr } from 'mochi-framework';

const html = `<pre><code>${escapeHtmlAttr(source)}</code></pre>`;
```

It has zero imports on purpose, so server modules, SSR, hydrated components and client-bundled web components all share the one implementation.

### Process singletons

`pinGlobal(key, factory)` returns one instance per `key` for the life of the process, pinned on `globalThis`. The `factory` runs at most once per key; every later call with the same key returns the same value.

```ts
import { SQL } from 'bun';
import { pinGlobal } from 'mochi-framework';

export function getSql() {
  return pinGlobal('app:sql', () => new SQL(process.env.DATABASE_URL!, { max: 8 }));
}
```

Call the accessor wherever you need the value — every call returns the same instance:

```ts
import { getSql } from './db/client';

const users = await getSql()`SELECT id, name FROM users`;
```

Reach for it to hold anything that must not be duplicated: a database pool, a connection, a background timer, an in-memory cache. In development this is what keeps such resources from leaking across [route-handler HMR](/docs/development-mode/#route-handler-hmr) — a plain module-scoped `let` is re-created on every reload and its old handle orphaned, but a `pinGlobal` value survives. Namespace your key with an `app:` prefix; the framework pins its own state under `__mochi_*__`.

<SeeItInAction
demos={[{ href: "/demos/url/", title: "Isomorphic URL", hook: "How the isomorphic URL helper works — one import that reads the request URL on the server and window.location on the client." }]}
/>

---
title: 'Cache'
slug: cache
ogTitle: 'Caching with stale-while-revalidate'
description: 'Cache server-side data with stale-while-revalidate semantics using MochiCache.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
  import PersistenceTable from './_components/PersistenceTable.svelte';
</script>

## Cache

<VersionNote since="0.8.0" href="/blog/mochi-0-8-0/" />

`MochiCache` caches server-side data — typically slow upstream API calls — with stale-while-revalidate semantics. Construct it once at module scope and share the instance across requests.

<PersistenceTable feature="cache" />

```ts
// src/lib/cache.ts
import { MochiCache } from 'mochi-framework';

export const pokemonCache = new MochiCache({
  minTimeToStale: 10_000, // serve fresh for 10s
  maxTimeToLive: 300_000, // hard expiry at 5min
});
```

Use it from a page or API route:

```svelte
<script>
  import { params } from 'mochi-framework';
  import { pokemonCache } from '../lib/cache';

  const id = params.id ?? 'pikachu';

  const pokemon = await pokemonCache.fetch(`pokemon:${id}`, async () => {
    const res = await fetch(`https://pokeapi.co/api/v2/pokemon/${id}`);
    return res.ok ? await res.json() : null;
  });
</script>
```

<Callout type="warning">

**A cache is shared across requests in one process.** So a key like `cart:current` leaks one user's data to another. Prefix per-user keys with the user id, for example `cart:${userId}`, and do the same for any other request-scoped dimension (tenant, locale, role).

</Callout>

### Caching expensive serverProps

A page's latency is usually dominated by its data loading, not the render — so `serverProps` resolvers are the highest-leverage place to cache. Construct a `MochiCache` at module scope and wrap the slow call in `fetch()`, keyed per route params:

```ts
// file: src/index.ts
import { Mochi, MochiCache } from 'mochi-framework';
import { loadPokemon } from './lib/pokemon';

const pokemonCache = new MochiCache({
  minTimeToStale: 10_000, // serve fresh for 10s
  maxTimeToLive: 300_000, // hard expiry at 5min
});

await Mochi.serve({
  routes: {
    '/pokemon/:id': Mochi.page('./src/Pokemon.svelte', {
      serverProps: async (_req, params) => ({
        pokemon: await pokemonCache.fetch(`pokemon:${params.id}`, () => loadPokemon(params.id)),
      }),
    }),
  },
});
```

The first request per key pays the load; later requests follow the fresh / stale / expired lifecycle below. Everything that shapes the result must be in the key — route params as above, plus any cookie- or locals-derived dimension per the warning above.

### Behavior

- **Fresh** (within `minTimeToStale`): cached value returned, no fetch.
- **Stale** (between `minTimeToStale` and `maxTimeToLive`): cached value returned at once, fetch runs in the background and updates the cache.
- **Expired** (past `maxTimeToLive`): fetch runs synchronously and the caller waits.

### API

| Method                     | Returns                              |
| -------------------------- | ------------------------------------ |
| `fetch(key, fn)`           | `Promise<T>`                         |
| `fetchWithStatus(key, fn)` | `Promise<{ value, status }>`         |
| `peek(key)`                | `Promise<{ value, status } \| null>` |
| `set(key, value)`          | `Promise<void>`                      |
| `markStale(key)`           | `Promise<void>`                      |
| `delete(key)`              | `Promise<void>`                      |
| `clearItems()`             | `Promise<void>`                      |
| `whenIdle()`               | `Promise<void>`                      |

`peek(key)` reports a key's `status` and value **without** running `fn`, revalidating, or emitting `cache:read` — a pure probe that returns `null` on a miss. `markStale(key)` backdates an entry so its next read serves stale-while-revalidate. It is a no-op on a missing or already-stale key, and it never freshens or un-expires one. Both run through the `storage` interface, so they apply to any backend. `set(key, value)` writes a value directly, stamped fresh. Prefer `set` over `delete(key)` then `fetch`: that sequence leaves the key absent, so concurrent readers each start their own recompute.

`status` is `'fresh' | 'stale' | 'expired' | 'miss'`.

#### Waiting for background revalidations

<VersionNote since="0.10.0" message="whenIdle() was added in 0.10.0." />

A stale read returns at once and refreshes in the background, so the new value is not readable when `fetch` resolves. `whenIdle()` waits for those background runs to finish — including the storage write, not just the upstream call — which is what you want before shutting down, or in a test that asserts on the refreshed value.

```ts
const stale = await cache.fetchWithStatus('users', loadUsers); // 'stale', old value
await cache.whenIdle();
const fresh = await cache.fetchWithStatus('users', loadUsers); // 'fresh', new value
```

<Callout type="warning">

`whenIdle()` waits for whatever is in flight, so on a busy cache it keeps waiting as new revalidations start. Treat it as a shutdown or test primitive — don't await it on a request path.

</Callout>

A run that throws settles it like any other, so a failing upstream can't leave it hanging. `ImageCache` exposes the same method for its own regenerations.

### Options

| Option           | Default           |
| ---------------- | ----------------- |
| `minTimeToStale` | `5_000` (5s)      |
| `maxTimeToLive`  | `600_000` (10min) |
| `storage`        | `MemoryStorage`   |
| `serialize`      | none (`v => v`)   |
| `deserialize`    | none (`v => v`)   |

Two storage backends ship with the framework: `MemoryStorage` (the default) and `FileStorage`. Built-in SQLite and Postgres backends are planned; until then any other backend — SQLite, Postgres, Redis — needs a `storage` you write yourself, implementing `getItem` / `setItem` / `removeItem` / `clear`. Those methods may be synchronous or `async`. The cache awaits every call. When a backend needs a string or buffer, supply `serialize` / `deserialize` — for example `serialize: JSON.stringify, deserialize: JSON.parse`.

The default `MemoryStorage` accepts `{ maxAge, purgeInterval }` for age-based eviction. With no options it never evicts.

See [Persistence](/docs/persistence/) for how cache storage compares to the other stateful subsystems.

### File-based storage

`FileStorage` persists the cache to disk, so it survives restarts — the only built-in persistent backend (see [Persistence](/docs/persistence/)). It needs no `serialize` / `deserialize`:

```ts
import { MochiCache, FileStorage } from 'mochi-framework';

export const pokemonCache = new MochiCache({
  minTimeToStale: 10_000,
  maxTimeToLive: 300_000,
  storage: new FileStorage({
    directory: './.cache/pokemon',
    maxAge: 300_000, // must be >= maxTimeToLive
  }),
});
```

A background sweep deletes expired files on an interval. `purgeOnInit` empties the directory on startup.

Binary fields (`Uint8Array` / `Buffer`) anywhere in a value round-trip transparently. By default Mochi inlines them as base64 in the JSON and returns them as `Uint8Array`. When values carry large binaries, set `offloadBinary: true`: Mochi writes each binary to its own file in a `<key-hash>/` folder and puts a pointer in the JSON instead of base64. An offloaded field reads back as a lazy blob reference, so a metadata read never loads the bytes. Resolve one with `readBlobRef(ref)`, and narrow a value with `isBlobRef(value)`. Deleting a key also removes its blob folder. Pointers already on disk always decode, so the flag never orphans existing entries. The built-in [image cache](/docs/images/) enables offloading internally.

| Option          | Default           |                                                                            |
| --------------- | ----------------- | -------------------------------------------------------------------------- |
| `directory`     | _(required)_      | Where cache files are written; created if missing.                         |
| `purgeOnInit`   | `false`           | Delete the directory's contents when the adapter is constructed.           |
| `purgeInterval` | `60_000` (1min)   | Background sweep interval in ms. `<= 0` disables the sweeper.              |
| `maxAge`        | `600_000` (10min) | Files older than this are deleted by the sweep.                            |
| `offloadBinary` | `false`           | Offload binary fields to per-key blob files, read back as lazy `BlobRef`s. |

Only one background sweeper runs per cache directory per process. A new `FileStorage` on the same directory transfers the sweep to the newest instance, and with it that instance's `maxAge`, so a dev-server reload that re-runs your module never stacks up duplicate sweepers. Ownership never moves back: `dispose()` on the newest instance ends the sweep for that directory, even if an older instance is still in use.

<Callout type="warning">

**Keep `maxAge` at or above `maxTimeToLive`.** The sweep deletes files past `maxAge`. Set it lower and the sweeper removes entries the cache still wants to serve stale, turning a fast stale read into a blocking recompute. Values must be JSON-serializable (no `Date`, `Map`, `BigInt`, or `undefined` round-trip).

</Callout>

<Callout type="warning">

**In-flight de-duplication is per-server.** Concurrent calls for the same key on one instance share a single `fn` invocation. With multiple instances behind a shared backend, each instance de-duplicates only its own requests, so on a cold key every instance may run `fn` once and race to write the same entry. The shared store keeps results consistent.

</Callout>

If a `storage` call throws, the cache degrades instead of failing the request: a read error recomputes via `fn` (reported as a `miss`), a write error returns the freshly computed value uncached, and a `delete` error is re-thrown to the caller. Every case emits a `cache:error` event.

### Subscribing to cache events

`MochiCache` emits these events on `mochiEvents`:

| Event                     | Payload                                  | When                                                               |
| ------------------------- | ---------------------------------------- | ------------------------------------------------------------------ |
| `cache:read`              | `{ key, status }`                        | Every cache lookup.                                                |
| `cache:revalidate`        | `{ key }`                                | A background refetch starts (stale read).                          |
| `cache:delete`            | `{ key }`                                | A key was removed via `delete(key)`.                               |
| `cache:sweep`             | `{ removed, durationMs }`                | A `FileStorage` background sweep deleted expired files.            |
| `cache:pressure`          | `{ level, removed, caches, durationMs }` | The OS reported low memory and Mochi drained its in-memory caches. |
| `cache:revalidate:failed` | `{ key, error }`                         | A background refetch threw; the stale value is still served.       |
| `cache:error`             | `{ key, operation, error }`              | A `storage` `get` / `set` / `remove` call threw.                   |

### Memory pressure

<VersionNote since="0.10.0" message="Memory-pressure cache draining (and the memoryPressure serve option) ships in the next Mochi release (0.10.0). This section describes the upcoming API." />

When the operating system runs low on memory, Bun raises `process.on("memoryPressure")` and Mochi drains every
in-memory cache before the kernel starts killing processes. `'critical'` (all platforms) clears them outright;
`'warning'` (macOS only) drops just the aged-out entries, so a store without `maxAge` keeps everything. Each response
emits one `cache:pressure` event and one `consoleLogger()` warning.

Only `MemoryStorage` participates — it is the backend that holds bytes in RAM. `FileStorage` is disk-backed, so
dropping it would not help. Turn the whole thing off with `Mochi.serve({ memoryPressure: false })`.

Reclamation runs in production only. In development (`development: true`) it is always disabled — the compile-heavy
boot hair-triggers the OS signal (Linux reports only `'critical'`), so the reclaim would be a spurious no-op.

The raw signal is also broadcast as a `memory:pressure` event (payload `{ level }`) the moment it arrives, before the
cache drain. Subscribe to reclaim resources Mochi doesn't own — idle connection pools, worker queues, your own maps:

```ts
import { mochiEvents } from 'mochi-framework';

mochiEvents.on('memory:pressure', ({ level }) => {
  if (level === 'critical') pool.drainIdle();
});
```

```ts
// file: src/index.ts
await Mochi.serve({ memoryPressure: false, routes });
```

`consoleLogger()` surfaces `cache:revalidate:failed` and `cache:error` as warnings. Use `mochiEvents.setHandler` to attach a custom subscriber — it replaces a prior handler under the same name, so dev re-imports do not pile up listeners:

```ts
import { mochiEvents } from 'mochi-framework';

mochiEvents.setHandler('metrics:cache-read', 'cache:read', ({ key, status }) => {
  metrics.increment(`cache.${status}`, { key });
});
```

`consoleLogger()` prints `cache:revalidate` lines by default. Pass `{ cache: 'verbose' }` to print every read, or `{ cache: false }` to silence cache logging.

### Per-request memoization

`MochiCache` is process-wide and outlives the request. To collapse repeated work **within** a single render, use the [request cache](/docs/request-cache/) instead. It needs no TTL because entries die with the request.

### Server-only

`MochiCache` lives on the server. Importing it into a hydratable island throws. Construct cache instances in `.ts` modules or page-route scripts, never inside a `mochi:hydrate` component.

<SeeItInAction
demos={[
{ href: "/demos/data-loading/", title: "Data Loading", hook: "How server-side data loading works — fetch on the server, cache with MochiCache, and render at request time." },
{ href: "/demos/cache-events/", title: "Cache Events", hook: "How cache events work — subscribe to MochiCache lifecycle events (hit, miss, set, evict) through mochiEvents for observability." },
{ href: "/cookie-vary-test/", title: "Cookie Vary Test", hook: "How cookie-partitioned caching works — a page that sets Vary: Cookie so responses key on cookies." },
]}
/>

---
title: 'Logging'
slug: logging
ogTitle: 'Isomorphic, level-gated logging'
description: 'An isomorphic, level-gated logger that works in server, SSR, and client contexts.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Logging

Mochi exposes one isomorphic `logger` with five methods. The same import works on the server, in SSR, in hydrated Svelte components, and in vanilla web components. A configurable level set on `Mochi.serve()` gates it.

```ts
import { logger } from 'mochi-framework';

logger.error('boom');
logger.warn('careful');
logger.info('starting up');
logger.log('verbose detail');
logger.debug('asset request');
```

Methods map to `console.error` / `console.warn` / `console.info` / `console.log` / `console.debug`. Each line is prefixed with a coloured `[mochi]`. A call below the configured level is a no-op with negligible overhead.

### Log level

```ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  port: 3333,
  routes,
  logger: { level: 'warn' },
});
```

`level` accepts `'silent' | 'error' | 'warn' | 'info' | 'log' | 'debug'`. A method runs when its severity is at or above the active level. So `'warn'` lets `error` and `warn` through and suppresses `info`, `log`, and `debug`.

| Level      | What you see                                                                       | When to use                                     |
| ---------- | ---------------------------------------------------------------------------------- | ----------------------------------------------- |
| `'silent'` | Nothing — no boot line, no requests, no errors                                     | Tests; CLI scripts that want no noise           |
| `'debug'`  | Everything `'log'` shows, plus per-asset request lines and fallbacks               | Investigating asset fetches or unmatched routes |
| `'log'`    | Adds chatty client-side hydration traces and other verbose detail                  | Debugging hydration / island lifecycle          |
| `'info'`   | Boot line, page/api/file requests, file-change notifications, plus warnings/errors | Default in development                          |
| `'warn'`   | Slow requests, 5xx responses, queue lifecycle, deprecations, recoverable problems  | Default in production                           |
| `'error'`  | Only handler failures and unhandled exceptions                                     | Production with a separate alerting pipeline    |

Which severity each event lands on is a framework default. Remap them per app with the [`consoleLogger:level` filter](/docs/extensions/).

If `level` is omitted, Mochi picks the default from the [mode](/docs/development-mode/): `'info'` in development, `'warn'` in production.

The level applies on both server and client. The server sends its configured level to the browser, so client-side `logger` calls honour it too. Reload the page after changing the config to pick up a new level on the client.

<Callout type="warning">

`level: 'silent'` really means silent, including the `BOOT` and `STOP` lines. To deliver lifecycle events to your own subscribers with no console output, set `logger: { enabled: false }` instead. That keeps the event bus alive and disables the formatter.

</Callout>

### Setting the level at runtime

```ts
import { setLogLevel, getLogLevel } from 'mochi-framework';

setLogLevel('error');
getLogLevel(); // 'error'
```

`setLogLevel` is for niche cases such as toggling verbosity from a feature flag. The serve-time config is the right place for normal use.

<Callout type="warning">

`setLogLevel` updates only the bundle it is called from. The server, the main client bundle, and each island bundle carry their own copy of the level. They are seeded consistently at startup. For a global change, update `Mochi.serve({ logger: { level } })` and reload.

</Callout>

### Relationship to `mochiEvents`

The event bus (`mochiEvents`) carries structured payloads to any subscriber you wire up, regardless of console output. The built-in `consoleLogger()` — the thing that prints request lines like `GET /foo 200 12ms` — is one consumer that subscribes to those events and calls `logger.info` / `logger.warn` per event. Plug Sentry, OpenTelemetry, or your own pipeline directly into `mochiEvents`. Use `logger` for ad-hoc messages.

<SeeItInAction
demos={[{ href: "/demos/cache-events/", title: "Cache Events", hook: "Subscribe to MochiCache lifecycle events through mochiEvents." }]}
/>

---
title: 'Request cache'
slug: request-cache
description: 'Memoize server-side work for the duration of a single request with requestCache and requestMemo.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Request cache

The request cache memoizes work for the duration of one HTTP request. Entries die with the request, so a page that renders the same lookup in ten components pays for it once, and the next request sees fresh data.

```ts
import { requestCache } from 'mochi-framework';

const user = await requestCache(`user:${id}`, () => db.user(id));
```

Every value the callback reads must appear in the key. The cache never inspects the function, so a key that omits `id` collides silently.

### requestMemo

Wrap a function once at module scope. Every call site is then memoized by its arguments:

```ts
import { requestMemo } from 'mochi-framework';

export const getUser = requestMemo((id: string) => db.user(id));
```

```svelte
<script>
  import { getUser } from '../lib/users';

  // However many components call this, one query per request.
  const user = await getUser(params.id);
</script>
```

The wrapper is the shared identity. Two separate `requestMemo()` calls over the same function get separate entries. Export the wrapped function so every importer shares it, or pass `{ namespace }` to share entries between wrappers.

Arguments are keyed by a type-tagged serialization (`1` and `'1'` never collide, and objects go through `JSON.stringify`). For arguments that cannot serialize, pass your own `key`:

```ts
const getProfile = requestMemo((user: User) => db.profile(user.id), { key: (user) => user.id });
```

### Async

Both forms store the in-flight promise on the first call, so concurrent callers share one execution:

```ts
// One fetch, three awaits.
const [a, b, c] = await Promise.all([getUser('42'), getUser('42'), getUser('42')]);
```

A rejected promise evicts its entry, so a failure is never cached. The next call retries.

### The store

`getRequestCache()` returns the underlying store for imperative access:

```ts
import { getRequestCache } from 'mochi-framework';

const cache = getRequestCache();
cache.set('tenant', tenant);
cache.get('tenant');
cache.delete('tenant');
cache.stats(); // { hits, misses } — also shown in the debug bar's Cache panel
```

### Outside a request

Called outside a request handler — a startup script, a background job, a detached email render — the callback runs uncached, with a one-time warning in development. Nothing throws, so helpers built on the request cache stay usable everywhere.

For a `requestMemo` wrapper expected to run outside a request, pass `{ quiet: true }` to suppress that warning:

```ts
export const getUser = requestMemo((id: string) => db.user(id), { quiet: true });
```

### On the client

These are server-only helpers. In the browser bundle they resolve to no-op stubs instead of throwing: `requestCache(key, fn)` runs `fn()` uncached, `requestMemo(fn)` returns `fn` unwrapped, and `getRequestCache()` hands back a fresh throwaway store per call.

<Callout type="warning">

**The request cache is a server-side convenience API.** Inside a hydrated component the calls run without the server's cached values — `requestCache(key, () => db.user(id))` runs on the server during SSR and again on the client during hydration, where `db` might not exist. To reuse a server-computed value on hydration, wrap it in Svelte's [`hydratable(key, fn)`](/docs/hydratable/) instead, or pass it as `serverProps`.

</Callout>

<Callout type="warning">

**Not a replacement for `MochiCache`.** The request cache has no TTL, no storage backend, and no eviction — the request boundary is the TTL. Use [`MochiCache`](/docs/cache/) for anything that should survive a request. Use the request cache to stop repeating work within one.

</Callout>

### In the debug bar

In development, the debug bar's **Cache** panel has a **Request cache** section reporting hits, misses, hit rate, and surviving entries for the render that produced the page.

<SeeItInAction
demos={[
{ href: "/demos/request-cache/", title: "Request Cache", hook: "Run an expensive computation once per request no matter how many components call it." },
]}
/>

---
title: 'Events'
slug: events
ogTitle: 'The framework lifecycle event bus'
description: 'Subscribe to framework lifecycle events like requests, WebSocket activity, and builds via a mitt emitter.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Events

Mochi exposes a process-wide [`mitt`](https://www.npmjs.com/package/mitt) emitter named `mochiEvents`. Subscribe from application code to feed metrics, audit logs, custom log destinations, or anything else that needs a structured view of server activity.

Event names use a `namespace:action` convention. Every key is in the typed `MochiEventMap`, so handlers receive a precise payload type without casts.

### Event index

- [`request`](#request) — every HTTP request (page or API)
- [`ws:open`](#wsopen), [`ws:message`](#wsmessage), [`ws:close`](#wsclose) — WebSocket lifecycle
- [`sse:open`](#sseopen), [`sse:message`](#ssemessage), [`sse:close`](#sseclose) — Server-Sent Events lifecycle
- [`queue:added`](#queueadded), [`queue:active`](#queueactive), [`queue:completed`](#queuecompleted), [`queue:failed`](#queuefailed), [`queue:error`](#queueerror) — [background job](/docs/queues/) lifecycle
- `cron:scheduled` — a [scheduled job](/docs/scheduled-jobs/) was registered (its runs surface through `queue:*` on the job name)
- [`email:sent`](#emailsent), [`email:error`](#emailerror) — [transactional email](/docs/email/) delivery
- [`server:start`](#serverstart), [`server:stop`](#serverstop) — server lifecycle
- [`warmup:start`](#warmupstart), [`warmup:complete`](#warmupcomplete) — route warmup batch (only with `warmup: true`)
- [`error`](#error) — a page/api/action handler threw
- [`action:invoke`](#actioninvoke), [`action:complete`](#actioncomplete) — form action lifecycle
- [`compile:start`](#compilestart), [`compile:complete`](#compilecomplete), [`compile:error`](#compileerror) — Svelte SSR build
- [`recompile:start`](#recompilestart), [`recompile:complete`](#recompilecomplete) — dev rebuild cycle
- [`recompile:module-churn`](#recompilemodule-churn) — entry re-imported many times in a dev session (resource-leak warning)
- [`client-bundle:complete`](#client-bundlecomplete) — hydratable client bundle finished
- [`island:error`](#islanderror) — an island errored
- [`captcha:verify`](#captchaverify) — a `<MochiCaptcha>` submission was verified or rejected
- [`file:change`](#filechange) — dev-only file watcher
- [`image:store`](#imagestore), [`image:delete`](#imagedelete) — [`<Image>`](/docs/images/) cache activity
- `image:cache-sweep` — aggregate counts per janitor sweep (see [Images](/docs/images/))
- `cache:read`, `cache:revalidate` — see [Cache events](/docs/cache/#subscribing-to-cache-events)
- `memory:pressure` — the OS reported low memory; fires before the cache drain so other subsystems can reclaim too (see [Cache](/docs/cache/#memory-pressure))
- `cache:pressure` — the OS reported low memory and in-memory caches were drained (see [Cache](/docs/cache/#memory-pressure))

### Subscribing

```ts
import { mochiEvents } from 'mochi-framework';

mochiEvents.on('request', ({ method, path, status, duration }) => {
  metrics.timing('http.request', duration, { method, path, status });
});
```

<Callout type="warning">

**Keep async work out of handlers.** Handlers run synchronously and block the emission chain. Offload metrics, logging, and I/O to a fire-and-forget async task so downstream handlers are not delayed.

</Callout>

### `mochiEvents.setHandler`

Use `setHandler(name, type, handler)` to register a named subscriber. It replaces any prior handler stored under the same `name`, so dev re-imports never pile up duplicate listeners.

```ts
mochiEvents.setHandler('metrics:request', 'request', ({ status, duration }) => {
  metrics.timing('http.request', duration, { status });
});
```

Namespace `name` (`metrics:request`, not `request`) so unrelated subsystems do not evict each other.

### `hasSubscribers`

Use `hasSubscribers(name)` to skip payload construction when nobody is listening:

```ts
import { hasSubscribers, mochiEvents } from 'mochi-framework';

if (hasSubscribers('compile:error')) {
  mochiEvents.emit('compile:error', expensivePayload());
}
```

### `requestId` correlation

Every HTTP request carries a stable `requestId` on `request`, `error`, `action:invoke`, and `action:complete`. Use it to stitch a 500 trace together. The same id is on the request context.

To honour an upstream id from a trusted reverse proxy, set `proxy.requestIdHeader` on `Mochi.serve()`.

<Callout type="danger">

**Only set `proxy.requestIdHeader` for traffic you fully control.** Clients can spoof headers. If you trust untrusted traffic, attacker-controlled ids correlate unrelated requests together in logs.

</Callout>

### Event reference

Each event ships a typed payload matching `MochiEventMap` in `events.ts`.

#### `request`

Fires once per HTTP response, including CSRF rejects. Covers `Mochi.page` and `Mochi.api` routes.

| Field       | Type                   | Notes                                                      |
| ----------- | ---------------------- | ---------------------------------------------------------- |
| `requestId` | `string`               | correlation id                                             |
| `kind`      | `'page' \| 'api'`      | which route type handled it                                |
| `method`    | `string`               | HTTP method                                                |
| `path`      | `string`               | URL pathname                                               |
| `status`    | `number`               | response status code                                       |
| `duration`  | `number`               | wall-clock ms, end to end                                  |
| `warmup`    | `boolean \| undefined` | `true` when issued by [route warmup](/docs/serve-options/) |

#### `ws:open`

Fires after a successful WebSocket upgrade.

| Field      | Type     | Notes                               |
| ---------- | -------- | ----------------------------------- |
| `path`     | `string` | URL pathname of the upgrade request |
| `duration` | `number` | ms spent in the upgrade handler     |

#### `ws:message`

Fires for every inbound WebSocket frame, after the user `message` handler returns.

| Field  | Type                 | Notes                         |
| ------ | -------------------- | ----------------------------- |
| `path` | `string`             | URL pathname                  |
| `size` | `number`             | bytes (text length or buffer) |
| `type` | `'text' \| 'binary'` | frame kind                    |

#### `ws:close`

Fires when a WebSocket connection closes.

| Field      | Type     | Notes                       |
| ---------- | -------- | --------------------------- |
| `path`     | `string` | URL pathname                |
| `duration` | `number` | ms the socket was open      |
| `code`     | `number` | WebSocket close code        |
| `reason`   | `string` | close reason (may be empty) |

#### `sse:open`

Fires when an SSE stream starts.

| Field  | Type     | Notes        |
| ------ | -------- | ------------ |
| `path` | `string` | URL pathname |

#### `sse:message`

Fires per `stream.send()` inside an SSE handler.

| Field   | Type                  | Notes                                   |
| ------- | --------------------- | --------------------------------------- |
| `path`  | `string`              | URL pathname                            |
| `size`  | `number`              | bytes written for the data line         |
| `event` | `string \| undefined` | optional named event passed to `send()` |

#### `sse:close`

Fires when the SSE stream closes. A client disconnect or an explicit close both count.

| Field      | Type     | Notes                  |
| ---------- | -------- | ---------------------- |
| `path`     | `string` | URL pathname           |
| `duration` | `number` | ms the stream was open |

#### `queue:added`

<VersionNote since="0.10.0" message="The bulk field is new in 0.10.0." />

Fires after `queue.add()` / `queue.addBulk()` enqueues a job. See [Queues](/docs/queues/).

| Field   | Type                   | Notes                                   |
| ------- | ---------------------- | --------------------------------------- |
| `queue` | `string`               | queue name                              |
| `jobId` | `string`               | generated job id                        |
| `bulk`  | `boolean \| undefined` | `true` when the add came from `addBulk` |

#### `queue:addedBulk`

<VersionNote since="0.10.0" message="queue:addedBulk is new in 0.10.0." />

Fires once per `addBulk()` call that inserted at least one job, alongside the per-job `queue:added` events. The [console logger](/docs/logging/) prints this summary instead of the per-job lines.

| Field    | Type       | Notes                                              |
| -------- | ---------- | -------------------------------------------------- |
| `queue`  | `string`   | queue name                                         |
| `count`  | `number`   | jobs actually inserted (duplicate ids are skipped) |
| `jobIds` | `string[]` | ids of the inserted jobs                           |

#### `queue:active`

Fires when a worker starts a job.

| Field     | Type     | Notes                                   |
| --------- | -------- | --------------------------------------- |
| `queue`   | `string` | queue name                              |
| `jobId`   | `string` | job id                                  |
| `attempt` | `number` | 1-based attempt number (1 on first run) |

#### `queue:completed`

Fires when a job's processor returns successfully.

| Field      | Type     | Notes                            |
| ---------- | -------- | -------------------------------- |
| `queue`    | `string` | queue name                       |
| `jobId`    | `string` | job id                           |
| `attempt`  | `number` | attempt that succeeded           |
| `duration` | `number` | ms the processor ran the attempt |

#### `queue:failed`

Fires when a job's processor throws. One emission per failed attempt.

| Field      | Type     | Notes                          |
| ---------- | -------- | ------------------------------ |
| `queue`    | `string` | queue name                     |
| `jobId`    | `string` | job id                         |
| `attempt`  | `number` | attempt that failed            |
| `duration` | `number` | processing ms before the throw |
| `error`    | `string` | thrown error message           |

#### `queue:error`

Fires for a queue-runtime error not tied to one job, for example a poll failure.

| Field   | Type      | Notes                                          |
| ------- | --------- | ---------------------------------------------- |
| `queue` | `string?` | absent for instance-level errors with no queue |
| `error` | `string`  | error message                                  |

#### `email:sent`

Fires after `Mochi.email()` hands a message to its transport. The [`email:message` filter](/docs/extensions/#emailmessage) can veto it first. See [Email](/docs/email/).

| Field       | Type                                                   | Notes                                                               |
| ----------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| `to`        | `string[]`                                             | recipient addresses, as actually sent                               |
| `subject`   | `string`                                               | message subject                                                     |
| `transport` | `'smtp' \| 'custom' \| 'log' \| 'dev' \| 'suppressed'` | which transport delivered it; `'suppressed'` when the filter vetoed |
| `messageId` | `string \| undefined`                                  | provider/SMTP id, when the transport returns one                    |
| `duration`  | `number`                                               | send wall-clock in ms                                               |

#### `email:error`

Fires when a transport throws while sending. `Mochi.email()` re-throws after emitting.

| Field       | Type                                   | Notes                                    |
| ----------- | -------------------------------------- | ---------------------------------------- |
| `to`        | `string[]`                             | recipient addresses                      |
| `cc`        | `string[] \| undefined`                | cc recipients, when the message had any  |
| `bcc`       | `string[] \| undefined`                | bcc recipients, when the message had any |
| `subject`   | `string`                               | message subject                          |
| `transport` | `'smtp' \| 'custom' \| 'log' \| 'dev'` | transport that failed                    |
| `error`     | `string`                               | error message                            |

#### `server:start`

Fires once after `Bun.serve()` binds the listening socket.

| Field         | Type                                                     | Notes                             |
| ------------- | -------------------------------------------------------- | --------------------------------- |
| `port`        | `number \| undefined`                                    | bound TCP port (absent over Unix) |
| `hostname`    | `string \| undefined`                                    | bound hostname if any             |
| `development` | `boolean`                                                | dev or prod mode                  |
| `routes`      | `{ page: number; api: number; ws: number; sse: number }` | route counts by kind              |

#### `server:stop`

<VersionNote since="0.10.0" message="The 'stop' reason is new in 0.10.0 — earlier versions emit this event only on signals." />

Fires when the server shuts down — on `SIGTERM` / `SIGINT`, or a programmatic [`Mochi.stop()`](/docs/queues/#mochistop) — after the `mochi:shutdown` hook runs.

| Field    | Type                                 | Notes                                          |
| -------- | ------------------------------------ | ---------------------------------------------- |
| `reason` | `'signal' \| 'stop'`                 | signal, or programmatic `Mochi.stop()`         |
| `signal` | `'SIGTERM' \| 'SIGINT' \| undefined` | the signal received; absent for `Mochi.stop()` |

#### `warmup:start`

Fires once when the [route warmup](/docs/serve-options/#route-warmup) batch begins. Only emitted with `warmup: true`.

| Field        | Type     | Notes                                 |
| ------------ | -------- | ------------------------------------- |
| `routeCount` | `number` | static page routes about to be warmed |

#### `warmup:complete`

Fires once after the [route warmup](/docs/serve-options/#route-warmup) batch finishes. Only emitted with `warmup: true`.

| Field        | Type     | Notes                                    |
| ------------ | -------- | ---------------------------------------- |
| `routeCount` | `number` | static page routes warmed                |
| `errorCount` | `number` | warmup invocations that threw or 5xx'd   |
| `durationMs` | `number` | wall-clock ms for the whole warmup batch |

#### `error`

Fires when a page, API, or form action handler throws and the framework returns an error response.

| Field        | Type                          | Notes                                  |
| ------------ | ----------------------------- | -------------------------------------- |
| `requestId`  | `string`                      | correlates with the matching `request` |
| `kind`       | `'page' \| 'api' \| 'action'` | which handler threw                    |
| `path`       | `string`                      | URL pathname + search                  |
| `method`     | `string`                      | HTTP method                            |
| `status`     | `number`                      | final response status                  |
| `message`    | `string`                      | error message                          |
| `stack`      | `string \| undefined`         | stack trace, dev only                  |
| `actionName` | `string \| undefined`         | present only when `kind=action`        |

```ts
mochiEvents.on('error', ({ kind, path, status, message, stack }) => {
  Sentry.captureException(new Error(message), { tags: { kind, path, status }, contexts: { stack } });
});
```

#### `action:invoke`

Fires immediately before a form action handler runs. Pairs with `action:complete` through `requestId`.

| Field        | Type     | Notes                                |
| ------------ | -------- | ------------------------------------ |
| `requestId`  | `string` | correlates with `action:complete`    |
| `path`       | `string` | URL pathname + search                |
| `actionName` | `string` | action name (`'default'` if unnamed) |

#### `action:complete`

Fires after a form action returns or throws. One emission per invocation, whatever the outcome.

| Field        | Type                                           | Notes                           |
| ------------ | ---------------------------------------------- | ------------------------------- |
| `requestId`  | `string`                                       | correlates with `action:invoke` |
| `path`       | `string`                                       | URL pathname + search           |
| `actionName` | `string`                                       | action name                     |
| `result`     | `'success' \| 'fail' \| 'redirect' \| 'error'` | outcome category                |
| `status`     | `number \| undefined`                          | set for `fail` and `redirect`   |

#### `compile:start`

Fires before each Svelte SSR compile. A cache hit skips it.

| Field  | Type     | Notes                       |
| ------ | -------- | --------------------------- |
| `path` | `string` | absolute path of the source |

#### `compile:complete`

Fires after a successful compile.

| Field               | Type     | Notes                                    |
| ------------------- | -------- | ---------------------------------------- |
| `path`              | `string` | absolute path of the source              |
| `ssrSizeBytes`      | `number` | size of the SSR bundle                   |
| `hydratableCount`   | `number` | hydratable islands found                 |
| `serverIslandCount` | `number` | server islands found                     |
| `durationMs`        | `number` | wall-clock time spent inside `compile()` |

#### `compile:error`

Fires when `Bun.build` rejects a Svelte source. The framework still throws after emitting. The event exists for tooling that wants the structured logs.

| Field     | Type                                                                        | Notes                            |
| --------- | --------------------------------------------------------------------------- | -------------------------------- |
| `path`    | `string`                                                                    | source that failed               |
| `message` | `string`                                                                    | top-line error message           |
| `logs`    | `Array<{ file?: string; line?: number; column?: number; message: string }>` | per-message diagnostics from Bun |

#### `recompile:start`

Fires from the dev watcher before a rebuild cycle begins. Production builds never emit. It wraps either a full SSR rebuild (`trigger: 'file' | 'svelte-config'`) or the CSS-only fast path (`trigger: 'css'`).

| Field       | Type                                 | Notes                                            |
| ----------- | ------------------------------------ | ------------------------------------------------ |
| `trigger`   | `'file' \| 'css' \| 'svelte-config'` | which watcher path fired                         |
| `path`      | `string`                             | file whose change triggered the rebuild          |
| `pageCount` | `number`                             | pages about to be rebuilt (`0` for the CSS path) |

#### `recompile:complete`

Fires after the matching `recompile:start`, once the rebuild finishes and clients are told to reload.

`clientBundleCount` counts `buildClientBundle()` calls inside the cycle. For a typical `'file'` trigger it must be `1`, or `0` when no hydratables are registered. A value above `1` means the registry's bundle deferral stopped working and you regressed to per-page bundling.

| Field               | Type                                 | Notes                                          |
| ------------------- | ------------------------------------ | ---------------------------------------------- |
| `trigger`           | `'file' \| 'css' \| 'svelte-config'` | matches `recompile:start`                      |
| `path`              | `string`                             | matches `recompile:start`                      |
| `pageCount`         | `number`                             | pages that were rebuilt                        |
| `clientBundleCount` | `number`                             | `buildClientBundle()` invocations during cycle |
| `durationMs`        | `number`                             | wall-clock ms for the whole cycle              |

#### `recompile:module-churn`

Fires once per dev session, when the entry has been re-imported `reloadCount` times (default 10). Each reload re-evaluates the whole first-party module graph, so a module-scoped resource is re-created and the old one orphaned — see [route-handler HMR](/docs/development-mode/#route-handler-hmr). `consoleLogger()` renders it as a `warn`-level `HMR` line; suppress that line with a [`consoleLogger:line`](/docs/extensions/#consoleloggerline) filter matching `source.name === 'recompile:module-churn'`.

| Field         | Type     | Notes                                       |
| ------------- | -------- | ------------------------------------------- |
| `reloadCount` | `number` | entry re-imports so far this session (≥ 10) |

```ts
import { mochiEvents } from 'mochi-framework';

mochiEvents.on('recompile:module-churn', ({ reloadCount }) => {
  console.warn(`entry re-imported ${reloadCount}× — hold resources with pinGlobal()`);
});
```

#### `client-bundle:complete`

Fires whenever the registry rebuilds the hydratable client bundle. Production builds emit once at startup. Dev mode emits during `recompileAll()` and on lazy first-hit compiles for server islands.

| Field         | Type     | Notes                                                    |
| ------------- | -------- | -------------------------------------------------------- |
| `entryCount`  | `number` | entrypoints fed to Bun.build (bootstrap + per-component) |
| `outputBytes` | `number` | sum of all output sizes (JS + CSS) from the bundle       |
| `durationMs`  | `number` | wall-clock ms inside `buildClientBundle()`               |

#### `captcha:verify`

Fires when [`verifyCaptcha()`](/docs/captcha/) finishes. The client gets one generic message, but this event carries the real cause.

| Field    | Type                  | Notes                                                                     |
| -------- | --------------------- | ------------------------------------------------------------------------- |
| `ok`     | `boolean`             | whether verification passed                                               |
| `reason` | `MochiCaptchaReason`  | `'ok' \| 'malformed' \| 'expired' \| 'too-fast' \| 'bad-pow' \| 'replay'` |
| `bits`   | `number \| undefined` | difficulty sealed in the token                                            |
| `ageMs`  | `number \| undefined` | token age at verification                                                 |

#### `island:error`

Fires when an island fails: a server-island render, a hydratable SSR render, or client-side hydration. The framework still ships an error placeholder. See [Error boundaries](/docs/error-boundaries/#islanderror-event).

| Field           | Type                                           | Notes                                             |
| --------------- | ---------------------------------------------- | ------------------------------------------------- |
| `componentName` | `string`                                       | island component identifier                       |
| `islandId`      | `string \| undefined`                          | envelope id; set for `'server'`, else `undefined` |
| `kind`          | `'hydratable' \| 'server' \| 'client-hydrate'` | which lifecycle stage failed                      |
| `message`       | `string`                                       | error message                                     |
| `stack`         | `string \| undefined`                          | stack trace, dev only                             |

#### `file:change`

Fires from the dev file watcher (chokidar). Production builds do not run the watcher, so this event never emits there.

| Field  | Type                  | Notes                                                      |
| ------ | --------------------- | ---------------------------------------------------------- |
| `path` | `string`              | absolute path of the changed file                          |
| `type` | `MochiFileChangeType` | `'add' \| 'change' \| 'unlink' \| 'addDir' \| 'unlinkDir'` |

#### `image:store`

Fires when the [`<Image>`](/docs/images/) cache commits a file to disk: a downloaded full-size `original`, a resized `variant`, or a ThumbHash blur `placeholder`. Emitted once per regeneration, because concurrent misses coalesce. Use it to mirror cache writes to durable storage such as S3.

| Field         | Type                                       | Notes                                                   |
| ------------- | ------------------------------------------ | ------------------------------------------------------- |
| `kind`        | `'original' \| 'variant' \| 'placeholder'` | which entry type was written                            |
| `src`         | `string`                                   | the image source (URL/key) this entry derives from      |
| `path`        | `string`                                   | absolute path of the file just committed on disk        |
| `id`          | `string`                                   | `variantId` for `variant`; `originalId(src)` otherwise  |
| `size`        | `number`                                   | bytes written                                           |
| `contentType` | `string`                                   | authoritative content type; `''` for `placeholder`      |
| `width`       | `number`                                   | pixel width; `0` for `original` and `placeholder`       |
| `height`      | `number`                                   | pixel height; `0` for `original` and `placeholder`      |
| `format`      | `string`                                   | encoded format such as `'webp'`; `''` for the two above |

```ts
import { readFileSync } from 'node:fs';
import { mochiEvents } from 'mochi-framework';

mochiEvents.on('image:store', ({ kind, src, path, contentType }) => {
  const body = readFileSync(path); // sync: the file is guaranteed present now
  void s3.putObject({ Bucket, Key: `img/${kind}/${src}`, Body: body, ContentType: contentType });
});
```

<Callout type="warning">

Read the file **synchronously at the top of the handler** — it provably exists at emit time — then offload the upload to a fire-and-forget task. A lazy `await readFile(path)` inside a slow handler could race the janitor sweep and miss the file.

</Callout>

#### `image:delete`

Fires when the `<Image>` cache removes a file from disk. The janitor sweep evicts it, a newer generation supersedes it, or you invalidate it explicitly. Pair it with `image:store` to keep an S3 mirror in sync. A bulk `invalidateSrc()` only emits per-file deletes while a subscriber is registered.

| Field    | Type                                         | Notes                                                                                                          |
| -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `kind`   | `'original' \| 'variant' \| 'placeholder'`   | which entry type was removed                                                                                   |
| `src`    | `string`                                     | the image source this entry derived from                                                                       |
| `path`   | `string`                                     | absolute path of the removed file                                                                              |
| `id`     | `string`                                     | same id scheme as `image:store`                                                                                |
| `size`   | `number`                                     | bytes reclaimed (`0` if the file was already gone)                                                             |
| `reason` | `'evicted' \| 'superseded' \| 'invalidated'` | `evicted` = past its window (sweep); `superseded` = newer generation; `invalidated` = explicit invalidate call |

```ts
mochiEvents.on('image:delete', ({ kind, src, path }) => {
  void s3.deleteObject({ Bucket, Key: `img/${kind}/${src}` });
});
```

### Custom events

`mochiEvents` is a plain mitt emitter. `emit` your own keys on it for quick experiments. Custom keys are absent from `MochiEventMap`, so handlers and emit sites lose typing.

### Built-in subscribers

`consoleLogger()` already prints `request`, `ws:*`, `sse:*`, `server:*`, `error`, and `cache:revalidate` lines. Pass `{ cache: 'verbose' }` to also print every `cache:read`, or `{ cache: false }` to silence cache logging.

<SeeItInAction
demos={[{ href: "/demos/cache-events/", title: "Cache Events", hook: "Subscribe to MochiCache lifecycle events through mochiEvents." }]}
/>

---
title: 'Images'
slug: images
ogTitle: 'On-the-fly image transforms'
description: 'On-the-fly image transforms on Bun.Image via named sizes, with encrypted URLs and a stale-while-revalidate disk cache.'
---

<script>
  import { Image } from 'mochi-framework/image';
  import Callout from './_components/Callout.svelte';
  import PersistenceTable from './_components/PersistenceTable.svelte';
  import placeholderShot from './images/image-placeholder.jpg';
</script>

## Images

Mochi transforms images on the fly with [`Bun.Image`](https://bun.com/docs/runtime/image) and serves them from an encrypted, stale-while-revalidate disk cache. Declare transforms once as **named sizes** in `Mochi.serve()`, then reference them by name. `<Image>` and `getImageUrl()` mint a signed URL only. The fetch, decode, and transform happen lazily in the `/_mochi/image` endpoint on the browser's request, so **SSR never blocks on image work**. Every URL payload is encrypted with a key derived from your `MOCHI_KEY`, so the source URL stays hidden and an attacker cannot request arbitrary sources or transforms.

<PersistenceTable feature="image-cache" />

### Declare sizes

Define transforms under `Mochi.serve({ image: { sizes } })`. Each size is a named recipe:

```ts
await Mochi.serve({
  image: {
    sizes: {
      thumbnail: { width: 200, height: 200, fit: 'inside', format: 'webp', quality: 80 },
      avatar: { width: 96, height: 96, fit: 'fill' },
      grayscale: { width: 600, modulate: { saturation: 0 }, format: 'jpeg', quality: 85 },
    },
  },
  routes,
});
```

Transforms apply in a fixed order: resize → rotate → flip → flop → modulate → format-encode. Mochi validates sizes at startup. Redefining a size re-renders every URL that uses it, since a config hash is folded into the cache key and `ETag`.

| Size field           | Default             | Notes                                                              |
| -------------------- | ------------------- | ------------------------------------------------------------------ |
| `width` / `height`   | —                   | Target size; height-only derives width by ratio                    |
| `fit`                | `'inside'`          | `inside` keeps aspect and fits within W×H; `fill` stretches to W×H |
| `withoutEnlargement` | `false`             | Never upscale beyond the source's intrinsic size                   |
| `rotate`             | none                | Degrees clockwise                                                  |
| `flip` / `flop`      | `false`             | Mirror vertically / horizontally                                   |
| `modulate`           | none                | `{ brightness?, saturation?, hue?, lightness? }` (`1` = unchanged) |
| `format`             | `defaultFormat`     | `webp` \| `jpeg` \| `png` \| `avif`                                |
| `quality`            | `defaultQuality`    | 1–100 (ignored for `png`)                                          |
| `autoOrient`         | global `autoOrient` | Apply EXIF orientation                                             |

> `Bun.Image` supports `fit: 'inside'` and `fit: 'fill'` only. For an exact square from a non-square source use `fill` (which stretches). Otherwise `inside` keeps the aspect ratio.

### Component

Import `Image` and reference a size by name. It renders one `<img>` with an encrypted `src` and no client JavaScript. The `<img>` `width`/`height` default to the size's declared dimensions.

```svelte
<script>
  import { Image } from 'mochi-framework/image';
</script>

<Image src="https://example.com/photo.jpg" size="thumbnail" alt="A photo" />
```

Add `placeholder` to render a [ThumbHash](https://evanw.github.io/thumbhash/) blur behind the image. It is set as the `<img>` `background-image` (no client JavaScript), and the loaded image paints over it with a CSS blur-up. The blur is computed in the background on first use, so it appears from the second render onward.

```svelte
<Image src="https://example.com/photo.jpg" size="thumbnail" alt="A photo" placeholder />
```

<figure>
  <Image src={placeholderShot} size="doc" width={placeholderShot.width} height={placeholderShot.height} alt="Side by side: a soft colour-blurred rectangle on the left, and on the right the photo it resolves to — a mochi on a wooden board beside a pink lily" />
  <figcaption>The ThumbHash blur (left) and the image it resolves to (right).</figcaption>
</figure>

| Prop                   | Default     | Notes                                                                      |
| ---------------------- | ----------- | -------------------------------------------------------------------------- |
| `src`                  | —           | http/https URL, or a [local image import](#local-image-imports) (required) |
| `size`                 | —           | Named size; omitted → the full-size original                               |
| `alt`                  | `''`        | Always set this                                                            |
| `placeholder`          | `false`     | Background-warmed ThumbHash blur-up; pure SSR, no client JavaScript        |
| `width` / `height`     | size's dims | `<img>` attribute override                                                 |
| `loading` / `decoding` | lazy/async  | Passed through to `<img>`                                                  |

A bare `<Image src>` with no `size` serves the full-size original. An unknown size name degrades to the original and logs a one-time server warning.

`<Image>` works inside `mochi:hydrate*` islands at any depth — it detects the hydrating subtree with [`isHydratable()`](/docs/selective-hydration/#ishydratable). Minting needs the server secret, so inside an island the minted URL is serialized into the page via Svelte's `hydratable` and reused during hydration. If a client-side re-render changes the image props, there is no snapshot to reuse and the `<img>` degrades to the raw `src` URL.

<Callout type="warning">

Hydrated-island props ship in plain text in the page HTML, so a `src` you pass into a `mochi:hydrate` island is visible to the client, even though the minted image URL stays encrypted. If your origin must stay secret, keep `<Image>` in server-rendered markup or a server island (`mochi:defer`), whose props are encrypted.

</Callout>

### Local image imports

Import a local image Vite-style and get an object with its served URL and intrinsic metadata:

```svelte
<script>
  import { Image } from 'mochi-framework/image';
  import hero from './hero.png';
  // hero → { src: '/_mochi/asset/hero-<hash>.png', width, height, format }
</script>

<Image src={hero} size="thumbnail" alt="A resized local photo" />
<img src={hero.src} width={hero.width} height={hero.height} alt="" />
```

Supported formats: png, jpg, jpeg, webp, avif, gif. Put SVGs in your `public/` directory and reference them with a plain `<img src>`.

Mochi copies the file to a content-hashed URL (`/_mochi/asset/<slug>-<hash>.<ext>`) and serves it from disk with a long-lived immutable cache in production. Transforms read the file from disk, so `<Image src={hero} size="…">` and `placeholder` work without an origin round-trip. Emitted copies live under `<outDir>/assets/` and [relocate with the build](/docs/production-builds/#relocatable-builds).

The `{ src, width, height, format }` shape is available as the exported `ImportedImage` type. Ambient module types come free through `mochi-framework/ambient`.

A bare `<Image src={hero}>` with no `size` renders the original at its intrinsic dimensions straight from that static URL. It never calls the image endpoint.

<Callout type="warning">

Two edge cases. With `image.enabled: false` the `/_mochi/asset/…` route still serves the file, because that route is plain static serving and registers independently of the flag. The transform does not run: `<Image>` falls back to the raw static URL, while the `<img>` keeps the size's declared `width`/`height`, so the browser scales the full-size original into that box. And the [`image:url`](/docs/extensions/#imageurl) CDN-rewrite filter runs on minted transform URLs only, so the no-size static URL (`hero.src`) bypasses it. Use a `size` if you need local assets routed through the filter.

</Callout>

### `getImageUrl` — deferred URLs

`getImageUrl(src, size)` returns an encrypted URL. It is synchronous and near-instant. No fetch happens until the browser requests it.

```ts
import { getImageUrl } from 'mochi-framework';

const url = getImageUrl('https://example.com/photo.jpg', 'thumbnail');
// → /_mochi/image/photo-thumbnail.webp?p=<encrypted token>

const original = getImageUrl('https://example.com/photo.jpg'); // no size → the original
```

The URL is relative by default. To serve images from a CDN, register the [`image:url`](/docs/extensions/#imageurl) filter.

### `getImageAttrs` — URL + declared dimensions

`getImageAttrs(src, size?)` returns `getImageUrl` plus the size's declared `width`/`height`. Synchronous, server-only.

```ts
import { getImageAttrs } from 'mochi-framework';

const { url, width, height } = getImageAttrs(src, 'thumbnail');
// → { url: '/_mochi/image/…', width: 200, height: 200 }
```

<Callout type="warning">

With `fit: 'inside'` (the default), the served image's real dimensions can be smaller than the declared ones. If the aspect ratio matters for layout, add CSS such as `height: auto` so the declared attributes only reserve space.

</Callout>

### `getImage` — inline bytes + metadata

When you need the transformed bytes server-side (OG images, inlining, a dimension probe), `getImage(src, size)` runs the size inline and returns bytes plus metadata. It shares the same disk cache. Prefer `getImageUrl` for anything that ends up in an `<img src>`.

```ts
import { getImage } from 'mochi-framework';

const { bytes, contentType, width, height, format } = await getImage(src, 'thumbnail');
const original = await getImage(src); // no size → the cached original bytes
```

### Placeholder APIs

The ThumbHash blur is also available directly. All three are server-only and share the image cache:

```ts
import { getImagePlaceholder, imagePlaceholder, warmImagePlaceholder } from 'mochi-framework';

const blur = await getImagePlaceholder(src); // compute-and-cache, blocking; data: URL or null
const maybeBlur = await imagePlaceholder(src); // non-blocking read; cached blur or null
warmImagePlaceholder(src); // fire-and-forget compute
```

### Caching & TTL

Mochi stores the original's encoded bytes and its stale-while-revalidate timers on disk (`cacheDir`), so the cache survives restarts. There is one TTL — the original's — and variants follow it:

```ts
await Mochi.serve({
  image: {
    timeToStale: 14_400_000, // serve fresh for 4h
    timeToEvict: 86_400_000, // re-fetch source after 1 day
  },
  routes,
});
```

- **Fresh** (within `timeToStale`): served from disk.
- **Stale** (between `timeToStale` and `timeToEvict`): served immediately, source re-fetched in the background.
- **Expired** (past `timeToEvict`): re-fetched synchronously.

A background janitor reclaims entries past `timeToEvict` every `sweepIntervalMs` (default 1h). Set `sweepIntervalMs: 0` to disable it.

Served images carry an `ETag` and a `Cache-Control` derived from the cache window (`public, max-age=<timeToStale>, stale-while-revalidate=<timeToEvict − timeToStale>`). In development no `Cache-Control` is sent, so edits and `invalidateImage()` calls always show up on the next request.

### Custom cache storage

Mochi backs the image cache with `FileStorage` under `cacheDir` by default. Pass `storage` to swap in a different backend, for example `MemoryStorage` — the only other built-in one; anything else (SQLite, Postgres, Redis, …) means implementing `Storage` yourself. See [Persistence](/docs/persistence/) for how this compares to other Mochi features.

```ts
import { MemoryStorage } from 'mochi-framework';

await Mochi.serve({
  image: {
    storage: new MemoryStorage({ maxAge: 86_400_000 }), // must be >= timeToEvict
    timeToStale: 14_400_000,
    timeToEvict: 86_400_000,
    sizes: { thumbnail: { width: 200, height: 200 } },
  },
  routes,
});
```

<Callout type="warning">

**In-memory image caching trades disk for RAM.** Every cached original and variant lives in process memory, so cache size adds to your process's memory footprint. The cache is lost on every restart, so the first request after a restart re-fetches and re-transforms.

</Callout>

### Invalidation

```ts
import { invalidateImage } from 'mochi-framework';

await invalidateImage(src); // mark stale: next request serves cached bytes, re-fetches in background
await invalidateImage(src, { hard: true }); // mark expired: next request blocks for a fresh re-fetch
```

`invalidateImage()` operates on the shared original, so it cascades to every variant and the ThumbHash placeholder.

### Configuration

Configure under `Mochi.serve({ image: { … } })`. Every option is optional.

| Option                 | Default                 | Notes                                                                     |
| ---------------------- | ----------------------- | ------------------------------------------------------------------------- |
| `sizes`                | `{}`                    | Named transform recipes                                                   |
| `enabled`              | `true`                  | `false` unmounts the endpoint; URL helpers then return the raw source URL |
| `cacheDir`             | `./.mochi/image-cache`  | Must not be under `publicDir`; ignored when `storage` is set              |
| `storage`              | `FileStorage(cacheDir)` | Override the cache backend                                                |
| `defaultFormat`        | `webp`                  | Used when a size omits `format`                                           |
| `defaultQuality`       | `80`                    | Used when a size omits `quality`                                          |
| `outputFormats`        | all four                | Allowed output formats                                                    |
| `allowedHosts`         | any public host         | Exact host or `*.example.com`                                             |
| `blockPrivateNetworks` | `true`                  | Reject private/loopback/link-local addresses                              |
| `fetchTimeoutMs`       | `10_000`                | Upstream fetch timeout                                                    |
| `maxResponseBytes`     | `20 MB`                 | Hard source-size cap                                                      |
| `maxPixels`            | `50_000_000`            | Decompression-bomb guard                                                  |
| `timeToStale`          | `14_400_000`            | Cache time-to-stale (ms); variants follow it                              |
| `timeToEvict`          | `86_400_000`            | Cache time-to-evict (ms); variants follow it                              |
| `sweepIntervalMs`      | `3_600_000`             | Background cache-janitor interval; `0` disables                           |
| `compressPayload`      | `true`                  | Deflate the encrypted URL payload                                         |

<Callout type="danger">

**Encryption is the security boundary.** The payload is encrypted with a key derived from your `MOCHI_KEY`, so only your server can mint URLs and the source URL stays hidden. If you pass a **user-controlled** `src` into `getImageUrl()`/`getImage()`, keep `blockPrivateNetworks` on (the default) and prefer an `allowedHosts` allowlist so a user cannot proxy requests to internal services. Upstream redirects are followed, but every hop is re-validated against those same checks. Cap the hop count with the [`image:maxRedirects`](/docs/extensions/#imagemaxredirects) filter. A full-size original that is SVG (or any non-raster type) is served as a download rather than inline.

</Callout>

See the [Named sizes demo](/demos/image-pipeline/) and the [Image demo](/demos/image/).

---
title: 'View Transitions'
slug: view-transitions
description: 'Animate full-page navigations with the browser cross-document View Transitions API and zero JavaScript.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## View Transitions

`<ViewTransitions />` opts your app into the browser's cross-document [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API), animating full-page navigations with **zero client JavaScript**. Mochi is an MPA, so every navigation is a real page load. The browser does the work. You declare the animation.

Render it from a component that appears on **every** page — for example, a shared page shell. Both the page you leave and the page you land on must opt in.

```svelte
<script>
  import { ViewTransitions } from 'mochi-framework/components';
</script>

<ViewTransitions type="fade" />
```

Navigate between pages and they crossfade. That is the whole setup.

<Callout type="warning">

Render exactly **one** `<ViewTransitions />` per page. Two instances would emit the same global `@keyframes` names and competing rules. If a second one renders, it logs a warning and emits nothing. The first instance wins.

</Callout>

### Props

| Prop                   | Type                                               | Default  | Description                                                           |
| ---------------------- | -------------------------------------------------- | -------- | --------------------------------------------------------------------- |
| `type`                 | `'fade' \| 'slide' \| 'scale' \| 'blur' \| 'flip'` | `'fade'` | The transition preset.                                                |
| `custom`               | `{ out?: string; in?: string }`                    | —        | Custom keyframe bodies. Overrides `type`.                             |
| `duration`             | `number` (ms)                                      | `250`    | Animation duration.                                                   |
| `easing`               | `string`                                           | `'ease'` | The animation timing function.                                        |
| `regions`              | `string \| string[]`                               | —        | Confine the animation to elements with these `view-transition-name`s. |
| `keepElementSelectors` | `string \| string[]`                               | —        | CSS selectors for persistent chrome to hold still across navigations. |

```svelte
<ViewTransitions type="slide" duration={400} easing="cubic-bezier(0.22, 1, 0.36, 1)" />
```

Five presets ship built in: `fade`, `slide`, `scale`, `blur`, and `flip`. They animate the page root, so they apply to any page with no per-element setup, and reduced-motion users get no animation automatically.

### Custom transitions

Pass `custom` to bring your own animation. `out` and `in` are the **body** of each keyframe for the page you leave and the page you land on. Mochi wraps each into an `@keyframes` for you.

```svelte
<ViewTransitions
  custom={{
    out: 'to { opacity: 0; transform: rotate(8deg) }',
    in: 'from { opacity: 0; transform: rotate(-8deg) }',
  }}
  easing="cubic-bezier(0.22, 1, 0.36, 1)"
/>
```

Either side is optional. `custom` composes with `duration`, `easing`, `regions`, `keepElementSelectors`, and reduced-motion.

<Callout type="info">

When `custom` is set it overrides `type`, so you can leave `type` unset.

</Callout>

### Animating only part of the page

The API always snapshots the whole viewport. You can scope which parts animate. Pass `regions` to confine the transition to elements you gave a [`view-transition-name`](https://developer.mozilla.org/en-US/docs/Web/CSS/view-transition-name). Everything else swaps instantly.

```svelte
<ViewTransitions type="slide" regions="card" />

<section style="view-transition-name: card">…</section>
```

An empty array (`regions={[]}`) disables the animation entirely.

<Callout type="info">

Each `view-transition-name` must be unique per document. Do not reuse one name across several elements on the same page.

</Callout>

### Keeping elements still

To hold persistent chrome — a banner, sidebar, or header — still while the rest of the page transitions, pass `keepElementSelectors` a list of CSS selectors. Mochi assigns each selector a unique `view-transition-name` and emits the freeze CSS. Render the same list on every page.

```svelte
<ViewTransitions type="fade" keepElementSelectors={['.banner', '.sidebar']} />
```

<Callout type="warning">

Each selector must match exactly one element per page. `view-transition-name`s are unique per document, so a selector that matches several elements breaks the transition.

</Callout>

<Callout type="info">

Cross-document view transitions are supported in current Chromium browsers. Where unsupported, the navigation happens with no animation.

</Callout>

<SeeItInAction
demos={[
{ href: "/demos/view-transitions/", title: "View Transitions", hook: "Drop <ViewTransitions /> into a layout to animate navigations with zero JavaScript." },
{ href: "/demos/custom-transitions/", title: "Custom Transitions", hook: "Supply your own @keyframes to <ViewTransitions /> via custom={{ in, out }}." },
]}
/>

---
title: 'RawScript'
slug: raw-script
ogTitle: 'Inlining a file at SSR time with RawScript'
description: 'Inline the raw contents of a file into the page at SSR time, addressed by a working-directory-relative path.'
---

<script>
  import Callout from './_components/Callout.svelte';
</script>

## RawScript

<Callout type="warning">

**Experimental.** This API is new and may change in a future release.

</Callout>

`<RawScript />` reads a file at SSR time and prints its contents verbatim with `{@html}`. Mochi resolves `src` relative to the **working directory** — the same convention as the paths you pass to `Mochi.page('./src/...')`.

```svelte
<script>
  import { RawScript } from 'mochi-framework/components';
</script>

<script type="speculationrules">
  <RawScript src="./src/inline/rules.json" />
</script>
```

Use it when you have a chunk of pre-authored JavaScript, JSON, or CSS on disk that you want inlined into the document — an inline `<script>`, speculation rules, or a critical-CSS blob — without a build step or a fetch.

To inline content you already have as a string, pass `string`. Provide exactly one of `src` or `string`. Passing both, or neither, throws.

```svelte
<RawScript string={`window.__BUILD__ = ${JSON.stringify(buildInfo)};`} />
```

<Callout type="info">

`src` is **not** relative to the component that renders it. By the time a component runs, it is compiled and bundled into `.mochi/`, so its original source location no longer exists. Address files from the working directory, like route paths.

</Callout>

<Callout type="warning">

`<RawScript />` is **SSR-only** — it reads from disk, which the browser cannot do. Do not put it inside a hydrated island. It throws if hydrated. It does no escaping, so point it only at files you author.

</Callout>

---
title: 'Captcha'
slug: captcha
ogTitle: 'Slide-to-verify captcha, no third party'
description: 'Slide-to-verify captcha with proof-of-work, replay protection, and no third-party service.'
---

<script>
  import { Image } from 'mochi-framework/image';
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import PersistenceTable from './_components/PersistenceTable.svelte';
  import captchaShot from './images/captcha.png';
</script>

## Captcha

<figure>
  <Image src={captchaShot} size="doc" width={captchaShot.width} height={captchaShot.height} alt="The MochiCaptcha slide-to-verify widget in its default styling" />
  <figcaption>The widget with no CSS applied — every colour falls back to a built-in default.</figcaption>
</figure>

`<MochiCaptcha />` is a slide-to-verify widget that gates form submissions without a third-party service or tracker. Mint a challenge in `serverProps`, render the component, verify in the action. To gate whole routes instead of forms, the same proof-of-work backs [Protection Mode](/docs/protection/).

<PersistenceTable feature="captcha" />

```ts
// src/routes.ts
import { Mochi, fail, success, mintCaptcha, verifyCaptcha } from 'mochi-framework';

export const routes = {
  '/contact': Mochi.page('./src/Contact.svelte', {
    serverProps: () => ({ captcha: mintCaptcha() }),
    actions: {
      send: async ({ formData }) => {
        const captcha = await verifyCaptcha(formData);
        if (!captcha.ok) {
          return fail(400, { error: captcha.error });
        }
        return success();
      },
    },
  }),
};
```

`mintCaptcha()` returns `{ token, bits, solveBudgetMs }`. Spread it onto the component. The widget adds its own `captcha_token` and `captcha_pow` hidden inputs to the surrounding form, so `verifyCaptcha(formData)` needs nothing else.

```svelte
<script lang="ts">
  import { MochiCaptcha } from 'mochi-framework/components';
  import type { MintedCaptcha } from 'mochi-framework';

  let { captcha }: { captcha: MintedCaptcha } = $props();
</script>

<form method="POST" action="?/send">
  <input name="email" type="email" required />
  <MochiCaptcha mochi:hydrate {...captcha} />
  <button type="submit">Send</button>
</form>
```

### Hydration

The captcha runs entirely in the browser — the slider, the hash chain, and the proof-of-work. The server renders only a blank spacer the size of the widget, and the slider appears in its place once it hydrates. Wire it up one of two ways:

- **Hydrate the captcha itself** — put `mochi:hydrate` on it, as above.
- **Hydrate the surrounding subtree** — if the captcha sits inside a component you hydrate, it hydrates with it.

The subtree route is the common one. The moment you attach [`enhance`](/docs/progressively-enhancing-forms-with-enhance/) to the form or bind `verified` to gate the submit button, you hydrate the form component anyway, and the captcha rides along. A binding cannot cross an island boundary, so `bind:verified` works only this way — the captcha and the code binding it must hydrate together.

```svelte
<!-- src/ContactForm.svelte -->
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import { MochiCaptcha } from 'mochi-framework/components';
  import type { MintedCaptcha } from 'mochi-framework';

  let { captcha }: { captcha: MintedCaptcha } = $props();
  let verified = $state(false);
</script>

<form method="POST" action="?/send" {@attach enhance()}>
  <input name="email" type="email" required />
  <MochiCaptcha {...captcha} bind:verified />
  <button type="submit" disabled={!verified}>Send</button>
</form>
```

`bind:verified` is optional. The server rejects an unsolved submission either way. With JavaScript off, the spacer shows a `<noscript>` message, overridable with `noscriptLabel`.

#### Props

| Prop             | Default                | Description                                                               |
| ---------------- | ---------------------- | ------------------------------------------------------------------------- |
| `token`          | —                      | The sealed challenge from `mintCaptcha()`.                                |
| `bits`           | `19`                   | Difficulty the widget solves at. Comes from `mintCaptcha()`.              |
| `solveBudgetMs`  | `60_000`               | Active solve time before the widget gives up. Comes from `mintCaptcha()`. |
| `emoji`          | `🧩`                   | The character on the handle.                                              |
| `label`          | `'Slide to verify'`    | The hint shown in the track, also the handle's accessible name.           |
| `verifyingLabel` | `'Verifying…'`         | Replaces the hint while the proof-of-work runs.                           |
| `verifiedLabel`  | `'Verified — thanks!'` | Replaces the hint once the proof-of-work lands.                           |
| `errorLabel`     | see below              | Shown if the widget cannot complete the challenge.                        |
| `noscriptLabel`  | see above              | The `<noscript>` message.                                                 |
| `verified`       | `false`                | `$bindable` — true once solved.                                           |

```svelte
<MochiCaptcha {...captcha} emoji="🍡" label="Slide the mochi to the right" />
```

### When it fails

Every failure is logged through the [logger](/docs/logging/) at `error` level, so it reaches production consoles. What the visitor sees depends on whether trying again could help.

- **A proof-of-work that ran out of budget, or a hash that threw** — the track becomes a retry button showing `errorLabel`. The nonce search resumes where it stopped.
- **A missing `token` or a `bits` value outside 1–32** — a configuration mistake, caught at mount, not retryable. In development the widget renders the cause. In production it falls back to a blank spacer, and the cause stays in the console.

Nothing is submitted from an errored widget: `captcha_token` and `captcha_pow` stay empty, so the server rejects it as unsolved.

### How it works

Sliding the handle advances a SHA-256 hash chain one link per step. The final link is the proof-of-work challenge. The widget then brute-forces a nonce whose digest has `bits` leading zeros. Hashing is synchronous pure JS (`@noble/hashes`), so it works over plain `http`.

The token is encrypted and authenticated (AES-256-SIV, keyed from `MOCHI_KEY`) and seals the mint time, a one-time nonce, and the difficulty. A passing submission proves the page was fetched, the widget ran, and real hashing work was spent.

<Callout type="info">

The token is a bearer token, not a secret. The client is meant to have it. Security rests on the fact that a client cannot **forge** one — the AEAD tag fails and `verifyCaptcha()` rejects it. Authenticity does the work, not confidentiality.

</Callout>

<Callout type="warning">

**This raises the cost of spam. It does not prove humanity.** An attacker can fetch a page, take the token, and solve the proof-of-work headlessly. What the captcha buys you is that every submission costs real CPU, must run JavaScript, and can be used once inside a short window. It is not a defence against a determined attacker and is not a substitute for rate limiting.

</Callout>

<Callout type="warning">

**Set `MOCHI_KEY` in production.** Tokens are sealed with a key derived from it. Without it, Mochi generates a random key per boot, so every in-flight challenge breaks on restart and no two instances accept each other's tokens. Generate one with `bunx mochi-framework generate-key`.

</Callout>

### Options

Configure defaults on `Mochi.serve()`:

```ts
await Mochi.serve({
  captcha: {
    bits: 19,
    minAgeMs: 2000,
    maxAgeMs: 900_000,
    store: 'memory',
  },
  routes,
});
```

| Option      | Default                        | Description                                                                 |
| ----------- | ------------------------------ | --------------------------------------------------------------------------- |
| `bits`      | `19`                           | Proof-of-work difficulty in leading zero bits. Each extra bit doubles work. |
| `minAgeMs`  | `2000`                         | Reject tokens younger than this — the timing floor.                         |
| `maxAgeMs`  | `900_000`                      | Reject tokens older than this (15 minutes).                                 |
| `store`     | `'memory'`                     | One-time nonce store: `'memory'`, `'sqlite'`, or your own `NonceStore`.     |
| `storePath` | `.mochi/captcha-nonces.sqlite` | SQLite file when `store: 'sqlite'`.                                         |

`'memory'` and `'sqlite'` are the only built-in nonce backends; anything else — Redis, Postgres, your own database — is a custom `NonceStore`. See [Persistence](/docs/persistence/) for how that compares across Mochi.

Every token failure returns the same message, so a probing bot cannot tell "too fast" from "tampered".

### The timing floor

`minAgeMs` is the only check that a submission took human time. The proof-of-work bounds an attacker's **cost** (~2^`bits` hashes per token), not any single solver's latency. A form with fields to type into runs past the 2s default. A form with nothing to fill in may not, so tune it per form with the [`captcha:minAgeMs`](/docs/extensions/#captchaminagems) filter.

### Clock skew

A token's age is `Date.now()` at verify minus the mint time sealed into the token. On one instance that is one clock, and the subtraction is exact. Across a multi-instance deploy the two reads come off different machines, so the difference also carries that pair's clock skew. A verifier that runs behind the minter understates the age and can refuse a real submission as too fast.

To absorb this, Mochi adds a 30s allowance to `maxAgeMs`, adjustable with the [`captcha:driftAllowanceMs`](/docs/extensions/#captchadriftallowancems) filter. It does not add one to `minAgeMs`.

<Callout type="info">

A **negative** `ageMs` on the [`captcha:verify` event](/docs/events/#captchaverify) means a token was verified before it was minted, which is impossible on a single clock. It is an unambiguous skew alarm, and it fires in the direction that quietly weakens the floor rather than the one visitors complain about.

</Callout>

### Replay protection

A solved token is single-use. `verifyCaptcha()` burns its nonce on success. A second submission of the same token is rejected.

<Callout type="warning">

**The default `'memory'` store is per-process.** It gives no replay protection across a multi-instance deploy. Use `store: 'sqlite'` with shared storage, or supply your own `NonceStore` backed by Redis or your database — there is no built-in Postgres store. See [Persistence](/docs/persistence/).

</Callout>

```ts
import type { NonceStore } from 'mochi-framework';

const store: NonceStore = {
  // Return false if the nonce was already spent. Must be atomic.
  consume: async (nonce, expiresAt) => (await redis.set(nonce, '1', { NX: true, PXAT: expiresAt })) === 'OK',
};
```

Pass `{ consume: false }` when other validation could still reject the submission, then burn the nonce yourself once you commit. This way a fixable mistake does not cost the visitor their solved captcha:

```ts
send: async ({ formData }) => {
  const captcha = await verifyCaptcha(formData, { consume: false });
  if (!captcha.ok) {
    return fail(400, { error: captcha.error });
  }
  if (!isValidEmail(formData.get('email'))) {
    return fail(400, { error: 'Enter a valid email address.' }); // nonce survives
  }
  if (!(await consumeCaptcha(captcha))) {
    return fail(400, { error: 'Already submitted. Reload to send another.' });
  }
  await sendIt();
  return success();
},
```

### Custom messages

`captcha.error` is ready to render. A failure also carries a `reason`, which is only ever `'replay'` or `'rejected'` (tampered, too-fast, expired, and bad proof-of-work all collapse into `'rejected'`). To distinguish the rest, listen for the [`captcha:verify` event](/docs/events/#captchaverify) — operators get the true cause, the client never does.

```ts
const captcha = await verifyCaptcha(formData);
if (!captcha.ok) {
  return fail(400, {
    error: captcha.reason === 'replay' ? 'You already sent this one — reload for a fresh form.' : captcha.error,
  });
}
```

### Theming

Every colour is a CSS custom property whose default lives in the `var()` fallback, so the widget looks finished with no CSS. Set any of them on an ancestor and they inherit down:

```css
.my-form {
  --mochi-captcha-accent: #4a7c59;
  --mochi-captcha-accent-soft: #e0ebe1;
  --mochi-captcha-accent-soft-text: #2f5b3f;
  --mochi-captcha-border: #e8e4d8;
  --mochi-captcha-track-bg: #faf8f1;
  --mochi-captcha-handle-bg: #fffdf8;
  --mochi-captcha-handle-text: var(--mochi-captcha-accent);
  --mochi-captcha-hint-text: #6e756d;
  --mochi-captcha-radius: 999px;
  --mochi-captcha-error-bg: #fdf3f2;
  --mochi-captcha-error-border: #e9c9c4;
  --mochi-captcha-error-text: #8a3324;
}
```

The three `error` properties apply only in the [failure state](#when-it-fails).

`--mochi-captcha-handle-text` colours the `emoji` glyph and follows the accent unless you set it. It applies only to glyphs with a text presentation, such as `▶` or `→`. Colour-font emoji like `🍡` paint themselves and ignore CSS colour.

The defaults are light-mode only. In a dark or themed app, point these at your own tokens — `--mochi-captcha-track-bg: var(--surface-muted)` and so on — so the widget follows your theme. The track height (44px) and handle width (44px) drive the drag maths and are not themeable.

### Testing

`solveCaptcha()` returns the exact fields the widget would submit, so form tests need no browser. Lower `bits` in the test server.

```ts
import { mintCaptcha, solveCaptcha } from 'mochi-framework';

await Mochi.serve({ captcha: { bits: 8, minAgeMs: 0 }, routes, port: 0 });

const res = await fetch(`${base}/contact/?/send`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({ ...solveCaptcha(mintCaptcha()), email: 'ada@example.com' }),
});
```

### API

| Export                              | Returns                          | Description                                          |
| ----------------------------------- | -------------------------------- | ---------------------------------------------------- |
| `mintCaptcha(options?)`             | `{ token, bits, solveBudgetMs }` | Mint a single-use challenge.                         |
| `verifyCaptcha(formData, options?)` | `Promise<CaptchaResult>`         | Verify and (unless `consume: false`) burn the nonce. |
| `consumeCaptcha(result)`            | `Promise<boolean>`               | Burn a deferred nonce; `false` if already spent.     |
| `solveCaptcha(minted)`              | `{ captcha_token, captcha_pow }` | Solve server-side, for tests.                        |

`CaptchaResult` is `{ ok: true; nonce: string; expiresAt: number }` or `{ ok: false; reason: 'replay' | 'rejected'; error: string }`.

<SeeItInAction
demos={[
{ href: "/demos/captcha/", title: "Captcha", hook: "Slide-to-verify backed by a hash chain and proof-of-work, no third party." },
{ href: "/demos/captcha-styling/", title: "Captcha Styling", hook: "The same captcha four ways, every colour a CSS custom property." },
]}
/>

---
title: 'Custom HTML shell'
slug: custom-html-shell
description: 'Replace the default HTML wrapper with a custom shell template containing Mochi placeholders.'
---

<script>
  import Callout from './_components/Callout.svelte';
</script>

## Custom HTML shell

`htmlShell` overrides the default `<!doctype html>` wrapper that Mochi renders pages into. Pass a path to an `.html` file (detected by the `.html` suffix) or the template string directly.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  htmlShell: './src/shell.html',
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});
```

Start from the minimal shell shown below and add your own markup around the placeholders.

### Placeholders

A custom shell must contain four placeholders. Mochi replaces each one per request:

| Placeholder        | Replaced with                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| `{{mochi.head}}`   | `<svelte:head>` output plus the warning-collector bootstrap script.                                    |
| `{{mochi.css}}`    | Island-display rules, island-failure styles, and `<link rel="stylesheet">` tags for compiled CSS.      |
| `{{mochi.body}}`   | Rendered component HTML, debug-info script, dev toolbar mount, dev error overlay, error-report script. |
| `{{mochi.script}}` | Hydration bootstrap `<script type="module">`, server-island loader, debug bar, and dev live-reload.    |

A minimal shell:

```html
<!-- file: src/shell.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    {{mochi.head}} {{mochi.css}}
  </head>
  <body>
    {{mochi.body}} {{mochi.script}}
  </body>
</html>
```

### When to customize

- Add `<meta>`, `<link rel="icon">`, analytics snippets, or third-party scripts site-wide.
- Set `lang`, `dir`, or class names on `<html>` / `<body>` for theming.
- Inline a fonts preload or a CSP `<meta>` tag.

For per-request HTML mutations (nonces, A/B class names, ENV-derived strings) use `transformPage` inside a `handle`:

```ts
// file: src/hooks.ts
import type { Handle } from 'mochi-framework';

export const handle: Handle = ({ event, resolve }) =>
  resolve(event, {
    transformPage: ({ html }) => html.replace('%nonce%', event.locals.nonce),
  });
```

---
title: 'Speculation Rules'
slug: speculation-rules
ogTitle: 'Instant navigations with Speculation Rules'
description: 'Prefetch and prerender same-site URLs via a typed speculationRules option, injected as a <script type="speculationrules"> tag.'
---

<script>
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Speculation Rules

<VersionNote since="0.10.0" message="The speculationRules option is new in 0.10.0." />

The [Speculation Rules API](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API) lets the browser prefetch or prerender same-site URLs ahead of a navigation, so the next page loads instantly. Pass a typed `speculationRules` object to `Mochi.serve()` and Mochi injects it as a `<script type="speculationrules">` tag in every page's `<head>`.

`prerender` here is the browser hint, unrelated to [`*.prerender.ts` modules](/docs/prerender/).

```ts
import { Mochi } from 'mochi-framework';
import type { SpeculationRules } from 'mochi-framework';

const speculationRules: SpeculationRules = {
  prefetch: [
    {
      where: {
        and: [{ href_matches: '/*' }, { not: { href_matches: '/api/*' } }, { not: { selector_matches: '[rel~=nofollow]' } }],
      },
      eagerness: 'moderate',
    },
  ],
  prerender: [{ where: { href_matches: '/' }, eagerness: 'moderate' }],
};

await Mochi.serve({ speculationRules, routes });
```

Both `prefetch` and `prerender` are optional. An omitted option — or an object whose arrays are both empty — injects nothing.

Rules are either **document rules** (`where` matches links on the page) or **list rules** (`urls` names explicit targets):

```ts
const listRules: SpeculationRules = {
  prefetch: [{ urls: ['/pricing', '/docs/'] }],
};
```

`href_matches` speaks the same [URL Pattern](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) syntax as the router, so a route pattern can be used verbatim: `/blog/:slug` matches one segment, while `*` crosses them. Match the URLs your server actually serves — with `trailingSlash: 'always'`, that means `/about/`, not `/about`.

### An important note about prerendering

Prerendering fully loads a page in a hidden tab — it is far more expensive than prefetching, so keep it to a few high-likelihood destinations and prefer `eagerness: 'moderate'`. Exclude URLs with side effects (sign-out, add-to-cart, one-time-password flows), and add `not: { selector_matches: '[rel~=nofollow]' }` and `[target=_blank]` guards so flagged links are left alone.

That hidden tab also runs the page's scripts, so an analytics snippet reports a pageview for a visit that may never happen. Gate the initialisation on activation — wherever the snippet lives, usually your [HTML shell](/docs/custom-html-shell/):

```js
if (document.prerendering) {
  document.addEventListener('prerenderingchange', initAnalytics, { once: true });
} else {
  initAnalytics();
}
```

Google Analytics already defers itself this way; most other vendors do not. For code that runs after load, `performance.getEntriesByType('navigation')[0]?.activationStart > 0` tells you the page was prerendered rather than visited directly.

---
title: 'Protection Mode'
slug: protection
ogTitle: 'Browser-verification interstitial'
description: 'Cloudflare-style browser verification on your own infrastructure: an interstitial auto-solves the captcha proof-of-work and redeems it for a signed clearance cookie.'
---

<script>
  import { Image } from 'mochi-framework/image';
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
  import ProtectionShellSource from './_components/ProtectionShellSource.svelte';
  import protectionShot from './images/protection.png';
</script>

## Protection Mode

<VersionNote since="0.10.0" message="Protection mode ships in 0.10.0." />

<figure>
  <Image src={protectionShot} size="doc" width={protectionShot.width} height={protectionShot.height} alt="The protection-mode interstitial: the Mochi logo, the text 'Please wait, we're validating your browser...', and the auto-captcha widget solving" />
  <figcaption>The built-in interstitial mid-verification — the widget solves the proof-of-work on its own and reloads into the page.</figcaption>
</figure>

Protection mode gates routes behind a browser check, like Cloudflare's "verifying your browser" page but on your own infrastructure. An unverified client gets a **403 interstitial page**: a hidden `<MochiCaptchaAuto />` island runs the [captcha](/docs/captcha/)'s hash chain and proof-of-work immediately — no slider — posts the solution to a built-in endpoint, receives a signed `HttpOnly` clearance cookie, and reloads into the real page. Every later request passes until the clearance expires.

```ts
await Mochi.serve({
  protection: { enabled: true },
  routes,
});
```

That alone protects **every** route — pages, APIs, WebSockets, SSE, and unmatched URLs handled by your `fetch` fallback.

### Choosing what to protect

`protect()` is an optional callback that runs on every request; return `true` to protect a resource. It receives `{ kind, path, url, request }`, so branching on route kind or path prefix is one line:

```ts
protection: {
  enabled: true,
  // Only APIs need verification; pages stay open.
  protect: ({ kind }) => kind === 'api',
},
```

`kind` is `'page' | 'api' | 'ws' | 'sse' | 'island' | 'file' | 'fallback'`. A `protect()` that throws counts as protected (fail closed).

Never gated, regardless of `protect()`: framework client assets (the interstitial must load its own JS/CSS), the image and local-asset endpoints (their URLs are server-minted and signed), warmup self-requests, the verify endpoint itself, and unmatched 404s with no `fetch` fallback. `publicDir` static files **are** gated (as kind `file`) — set `protectFiles: false` to leave them open. A blocked POST never gets the interstitial — solving one ends in a reload, which would re-submit the form — so non-GET requests fail as JSON instead.

### What a blocked client sees

| Kind                            | Response                                                   |
| ------------------------------- | ---------------------------------------------------------- |
| `page`, `fallback` (GET / HEAD) | The interstitial HTML — `403`, `Cache-Control: no-store`   |
| `api`, and any non-GET request  | `403` JSON: `{ "error": "Browser verification required" }` |
| `ws`, `sse`, `island`, `file`   | Plain `403`                                                |

A browser calling a protected API from an already-cleared page carries the cookie automatically, so in practice only direct, cookie-less clients see the API 403. The non-HTML bodies use `blockedMessage` (default shown above).

### Options

```ts
protection: {
  enabled: true,
  protect: ({ path }) => path.startsWith('/members'),
  bits: 19,                       // PoW difficulty; default 19
  maxAgeMs: 4 * 60 * 60 * 1000,   // clearance lifetime; default 4 hours
  maxAttempts: 5,                 // failed tries before the widget gives up; default 5
  protectFiles: true,             // gate publicDir static files too; default true
  cookieName: '_mochi_clearance', // clearance cookie name; default shown
  blockedMessage: 'Members only', // non-HTML 403 body; string or (ctx) => string
  page: './src/ProtectionShell.svelte', // custom interstitial component
},
```

- **`bits`** — proof-of-work difficulty in leading zero bits; each extra bit doubles the expected work. Default: 19.
- **`maxAgeMs`** — how long a passed verification lasts. The clearance is a sealed `{ iat }` token in the clearance cookie (`HttpOnly`, `SameSite=Lax`, `Path=/`, `Secure` on https); both the cookie's `Max-Age` and the server-side check use this value. It's keyed off `MOCHI_KEY`, so clearances survive restarts and work across instances.
- **`maxAttempts`** — after this many failed verification attempts the widget stops retrying and shows a terminal message instead (the `exhaustedLabel` prop on `<MochiCaptchaAuto />`). The count lives in `sessionStorage`, so closing the tab resets it. Default: 5.
- **`protectFiles`** — also gate `publicDir` static files (they hit `protect()` as kind `file`). Default: `true`.
- **`cookieName`** — rename the clearance cookie. Default: `_mochi_clearance`.
- **`blockedMessage`** — the 403 body blocked non-HTML kinds receive: the `error` field of the api JSON and the plain-text body for `ws`/`sse`/`island`/`file`. A string, or a callback receiving the same context as `protect()`. Default: `"Browser verification required"`.
- **`page`** — a Svelte component rendered as the interstitial, exactly like `errorPage` for error pages. See below.

### Customizing the interstitial

Point `page` at your own Svelte component. It renders through your app's HTML shell, receives `MochiProtectionPageProps` — `{ token, bits, solveBudgetMs, verifyUrl, maxAttempts }` — and only has to spread them onto `<MochiCaptchaAuto />`, which does the solving and submitting.

The built-in default below is a great natural starting point — copy it and restyle. This is the component's live source, read from the installed `mochi-framework`:

<ProtectionShellSource />

<Callout type="warning">

In production the verify POST goes through the same origin-header CSRF check as every Mochi form, so `proxy.origin` (or `proxy.hostHeader`) must be configured — without it every verification fails, and after `maxAttempts` tries visitors are told their browser couldn't be verified.

</Callout>

<Callout type="info">

Caching a protected route — Mochi's cache or a CDN — only works if the cache key varies on the clearance cookie (`Vary: Cookie`, honoring `_mochi_clearance` or your `cookieName`). A cache that ignores it will serve cached pages to unverified visitors, bypassing the gate entirely.

</Callout>

### Testing protected routes

`solveCaptcha()` solves a minted challenge server-side, so a test can clear itself without a browser:

```ts
import { mintCaptcha, solveCaptcha } from 'mochi-framework';

const fields = solveCaptcha(mintCaptcha());
const form = new FormData();
form.set('captcha_token', fields.captcha_token);
form.set('captcha_pow', fields.captcha_pow);
const res = await fetch(`${base}/_mochi/protection/verify`, { method: 'POST', body: form, headers: { origin: base } });
const cookie = res.headers.get('Set-Cookie'); // send this on protected requests
```

Lower `captcha: { bits: 8 }` in the test server so the solve takes milliseconds. Mind that the verify endpoint refuses tokens minted below the protection difficulty — if you set `protection.bits` above the captcha default, mint with `mintCaptcha({ bits })` to match.

<SeeItInAction
demos={[
{ href: "/demos/protection/", title: "Protection Mode", hook: "A Cloudflare-style browser check — the interstitial auto-solves the proof-of-work and redeems it for a clearance cookie." },
]}
/>

### API

| Export                                            | What it is                                    |
| ------------------------------------------------- | --------------------------------------------- |
| `PROTECTION_CLEARANCE_COOKIE`                     | The default clearance cookie name             |
| `DEFAULT_PROTECTION_MAX_AGE_MS`                   | Default clearance lifetime (4 hours)          |
| `DEFAULT_PROTECTION_MAX_ATTEMPTS`                 | Default verification attempt cut-off (5)      |
| `MochiProtectionOptions`                          | The `Mochi.serve({ protection })` option type |
| `MochiProtectionContext` / `MochiProtectionKind`  | What `protect()` receives                     |
| `MochiProtectionPageProps`                        | Props a custom `page` component receives      |
| `PROTECTION_SHELL_COMPONENT`                      | Absolute path of the built-in interstitial    |
| `MochiCaptchaAuto` (`mochi-framework/components`) | The auto-solving widget the interstitial uses |

---
title: 'CSS imports'
slug: css-imports
description: 'Import CSS from Svelte, TypeScript, or JavaScript files and have it bundled and injected automatically.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## CSS imports

A side-effect `import` of a `.css` file from any `.svelte`, `.ts`, or `.js` module bundles the stylesheet out-of-band and links it from the page `<head>`. Mochi strips the import from both the SSR and client JavaScript bundles, so the CSS content never ships through JavaScript.

```svelte
<!-- file: src/Page.svelte -->
<script>
  import '@fontsource/inter';
  import 'tippy.js/dist/tippy.css';
</script>
```

Bare specifiers resolve through `package.json#main`, so `@fontsource/*`, CSS-only libraries, and any package that points its main entry at a stylesheet work the same way. Relative paths (`import './styles.css'`) resolve from the importing file.

Mochi serves the bundle as `/_mochi/import-css/<name>-<hash>.css` (with `assetPrefix` configurable on `Mochi.serve`). It tracks the imports reachable from each page entry and injects a `<link rel="stylesheet">` only on pages that use them.

The import can live anywhere in the dependency graph — a leaf `.ts` module, a hydratable island, or the page component. Mochi follows the bundle, not the call site.

<Callout type="warning">

A failed CSS import (missing package, malformed file) surfaces as a `css-bundle-failed` entry in the dev error overlay and as an inline `console.error` in the browser. Fix the path. The side-effect strip fires only on `.css` files Bun can resolve.

</Callout>

### Component-scoped `<style>` blocks

The Svelte compiler handles `<style>` inside a `.svelte` file. Mochi extracts the compiled CSS, hashes it, and serves it from `/_mochi/css/<component>-<hash>.css`. This path is independent of side-effect CSS imports and applies to every component the page renders.

```svelte
<!-- file: src/Card.svelte -->
<h2>Card</h2>

<style>
  h2 {
    color: tomato;
  }
</style>
```

### Fonts

<VersionNote since="0.10.0" message="Earlier versions inline every font into the bundled CSS as a base64 data: URI." />

Fonts larger than 4 kB are served as content-hashed files from `/_mochi/fonts/*` instead of being inlined into the stylesheet:

```css
/* @fontsource/source-sans-pro ships */
src: url(./files/source-sans-pro-latin-400-normal.woff2) format('woff2');

/* Mochi serves */
src: url(/_mochi/fonts/source-sans-pro-latin-400-normal-1bfe8b9c.woff2) format(woff2);
```

Tunable via `Mochi.serve({ fonts })`:

```ts
await Mochi.serve({
  fonts: {
    inlineThreshold: 4096, // fonts at or below this stay inlined, up to Bun's 128 kB ceiling
    dropLegacyWoff: true, // drop format('woff') sources when the face also offers woff2
    preload: true, // <link rel="preload" as="font"> for the page's latin-visible woff2 fonts
  },
  routes,
});
```

- **`dropLegacyWoff`** — `woff2` is supported by every browser Mochi targets, so shipping the `woff` fallback doubles a face's payload for nothing.
- **`preload`** — separately-fetched fonts are only discovered after the CSS arrives; preloading from the `<head>` closes that gap. Faces whose `unicode-range` excludes latin are skipped, and at most 8 fonts are preloaded per page.
- **`inlineThreshold`** — Bun writes any `url()` asset of 128 kB or more to a file of its own, so fonts that large are always served separately whatever this is set to. That 128 kB cutoff is hardcoded in Bun and cannot currently be configured. Non-font assets over it (a background image, say) are served alongside the stylesheet; smaller ones stay inlined.

### Dev mode

A `.css` edit triggers a fast rebundle and a page reload, with no SSR recompile. Edits to `.svelte` or `.ts` files go through the full compile path.

<SeeItInAction
demos={[
{ href: "https://demos.mochi.fast/todo/", title: "Tailwind Todo App", hook: "Classic todo app styled with Tailwind CSS." },
{ href: "/demos/lazy/", title: "Lazy Islands", hook: "Islands hydrate and load their CSS only when scrolled into view." },
]}
/>

---
title: 'MdSvex'
slug: mdsvex
ogTitle: 'Markdown pages with MdSvex'
description: 'Enable Markdown support in Mochi pages with mdsvex and rehype/remark plugins.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## MdSvex

<Callout type="warning">

Experimental — `markdown` and `mochi-framework/highlight` APIs may change.

</Callout>

Markdown support is opt-in. Install `mdsvex` and any rehype/remark plugins you want, then inject them through `Mochi.serve({ markdown: ... })`.

```sh
bun add mdsvex@^0.12 rehype-slug@^6
```

Mochi is tested against `mdsvex ^0.12` and `rehype-slug ^6`.

With `markdown` configured, `.md` and `.svx` files compile through the pipeline and can be used anywhere a `.svelte` component is accepted, including as a `Mochi.page()` route target:

```ts
// src/index.ts
import { Mochi } from 'mochi-framework';
import { compile as mdsvexCompile } from 'mdsvex';
import rehypeSlug from 'rehype-slug';

await Mochi.serve({
  markdown: {
    compile: mdsvexCompile,
    rehypePlugins: [rehypeSlug],
  },
  routes: {
    '/about': Mochi.page('./src/about.md'),
  },
});
```

Markdown can embed Svelte syntax — a top-level `<script>` block, `$props`, and `{expression}` interpolation work as in a `.svelte` file:

```svelte
<script>
  let { name = 'world' } = $props();
</script>

# Hello, {name}

This page was rendered at {new Date().toISOString()}.
```

The `markdown` config accepts a full plugin chain compatible with mdsvex's `rehypePlugins` and `remarkPlugins`.

### Syntax highlighting with Shiki or twinkleplop

Fenced code blocks pass through unchanged unless you supply `markdown.highlight.highlighter`. Install a highlighting engine (twinkleplop, Shiki, highlight.js, Prism) and build a highlighter with the framework's `createHighlighter` factory. It adds the code-block wrapper, copy button, Svelte-brace escape, and memoization per `(code, lang)`.

This site uses twinkleplop, which ships one package per language and highlights synchronously:

```sh
bun add @twinkleplop/typescript @twinkleplop/bash
```

```ts
// src/lib/highlightCode.ts
import { language as bash } from '@twinkleplop/bash';
import { language as typescript } from '@twinkleplop/typescript';
import { createHighlighter } from 'mochi-framework/highlight';

const grammars: Record<string, (code: string) => string> = {
  bash: bash(),
  typescript: typescript(),
};

export const highlightCode = createHighlighter((code, lang) => (grammars[lang] ?? grammars.typescript)(code));
```

```ts
// src/index.ts
import { highlightCode } from './lib/highlightCode';

markdown: {
  compile: mdsvexCompile,
  highlight: { highlighter: (code, lang) => highlightCode(code, lang) },
}
```

The cache holds 1000 snippets and evicts in insertion order. Tune it with `cacheSize` (`0` disables memoization).

<Callout type="info">

twinkleplop has no alias table, so the `lang` mdsvex hands you is the raw fence word — map `ts`, `js`, `sh`, `yml` and friends onto your grammar keys yourself, and decide what an unknown language does. `escapeHtmlAttr` from `mochi-framework` renders one unhighlighted without throwing.

</Callout>

Any other engine drops in the same way, sync or async:

```ts
import hljs from 'highlight.js';
import { createHighlighter } from 'mochi-framework/highlight';

export const highlightCode = createHighlighter((code, lang) => hljs.highlight(code, { language: lang }).value);
```

#### Theming

twinkleplop emits token classes rather than inline colours, so the theme is a stylesheet you supply:

```html
<pre class="twinkleplop"><code><span class="l"><span class="tok keyword">const</span> …</span></code></pre>
```

Import a ready-made one (`import '@twinkleplop/theme-github'`), or write the rules yourself against the token names the theme packages export from their `/tokens` subpath:

```css
.twinkleplop .tok.keyword {
  color: #a7c9a8;
}
.twinkleplop .tok.string {
  color: #d5b982;
}
```

Engines that inline their own colours (Shiki, highlight.js themes) need no stylesheet of yours.

### Islands in markdown

`mochi:hydrate`, `mochi:hydrate:visible`, `mochi:defer`, and `mochi:defer:visible` work on components instantiated inside a `.md` / `.svx` file. Import the component as a default import from the markdown's top-level `<script>` block, then apply the directive on the tag:

```svelte
<script>
  import Counter from './Counter.svelte';
</script>

<Counter mochi:hydrate count={3} />
```

<Callout type="info">

Omitting the `markdown` config disables `.md`/`.svx` handling, so importing one surfaces a "no loader" error from Bun's bundler. Your `svelte.config.js` `compilerOptions` still apply to compiled markdown. See [Svelte config](/docs/svelte-config/).

</Callout>

### Mapping slugs to markdown components

<VersionNote since="0.10.0" message="*.prerender.ts modules and moduleRef() are not in the published release yet." />

A docs or blog section usually needs every `.md` file keyed by slug. Build that map in a [prerendered module](/docs/prerender/) instead of generating a barrel file into your source tree:

```ts
// src/lib/docs.prerender.ts
import { moduleRef } from 'mochi-framework';
import type { Component } from 'svelte';
import { loadDocs } from './docs';

export const docs: Record<string, Component> = Object.fromEntries((await loadDocs()).map((d) => [d.slug, moduleRef<Component>(`../../docs/${d.filename}`)]));
```

Each `moduleRef()` becomes a real `import` of the `.md` file, so the markdown still compiles through the pipeline above.

<SeeItInAction
demos={[{ href: "/demos/mdsvex/", title: "MdSvex", hook: "A .md file compiled through mdsvex and rendered as a Svelte component." }]}
/>

---
title: 'Serve options'
slug: serve-options
ogTitle: 'Every Mochi.serve() option'
description: 'Reference for every configuration option on Mochi.serve().'
---

<script>
  import Callout from './_components/Callout.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Serve options

`Mochi.serve(options)` boots the Bun server and registers routes. Pass one `MochiServeOptions` object. Every field is optional except `routes`.

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';

await Mochi.serve({
  port: 3333,
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});
```

Response compression is opt-in through the [`compress()` middleware](/docs/middleware/#compress).

### Asset caching

In production (`development: false`), prebuilt JS/CSS bundles served from `assetPrefix` (default `/_mochi`) get `Cache-Control: public, max-age=31536000, immutable`. Filenames are content-hashed, so any change yields a new URL. In development the header is omitted so live-reload edits are not pinned in the browser cache. Public-dir files (`./public/...`) are read from `publicDir` on disk in both modes and keep Bun's default static-route headers. To override, mutate `response.headers` in a `handle` middleware.

<Callout type="warning">

**One `serve()` call per process.** To run multiple sites, spawn separate processes on different ports. A second call in the same process throws `Mochi.serve() has already been called.`

</Callout>

<Callout type="info">

**Shutdown signals.** `Mochi.serve()` installs `SIGTERM` and `SIGINT` listeners that fire the [`mochi:shutdown`](/docs/extensions/#mochishutdown) hook, drain queues, then stop the server and exit with code 0. In-flight requests get `shutdownTimeout` ms to finish. Anything still connected is force-closed. A second signal exits immediately with code 1. An open WebSocket never drains, so shutdown waits the full `shutdownTimeout` before force-closing. Keep the timeout tight enough for your orchestrator's grace period. A finite-lifetime embedder (script, test) can run the same teardown without exiting via [`Mochi.stop()`](/docs/queues/#mochistop).

</Callout>

### Options reference

- `port` — TCP port. No default, so set it explicitly.
- `hostname` — interface to bind. Defaults to Bun's default (`0.0.0.0`).
- `development` — enables live reload, debug bar, and dev error overlay. Default: `true`.
- `liveReload` — enable the dev-mode live-reload WebSocket. Default: matches `development`. Set `false` to keep the debug bar but skip the socket.
- `shutdownTimeout` — grace period (ms) for in-flight requests on `SIGTERM`/`SIGINT`. Default: `5000` in production, `0` in development.
- `routes` — `Record<string, MochiRouteValue>` of route paths to `Mochi.page` / `Mochi.api` / `Mochi.ws` / `Mochi.sse`.
- `fetch` — `(req, server) => Response` fallback when no route matches. Default: built-in 404.
- `manifest` — path to a prebuilt manifest JSON. Default: `<outDir>/manifest.json`.
- `htmlShell` — path to an `.html` template or an inline string. Default: built-in shell. See [Custom HTML shell](/docs/custom-html-shell/).
- `handle` — a `Handle` (or `sequence(...)`) wrapping every request. See [Middleware](/docs/middleware/).
- `errorPage` — component rendered for uncaught page errors and unmatched routes. Default: built-in. See [Error handling](/docs/error-handling/).
- `handleError` — `HandleError` hook run before the error page renders. See [Error handling](/docs/error-handling/).
- `compressServerIslandProps` — deflate server-island props when it reduces size. Default: `true`.
- `inlineNestedIslands` — render nested `mochi:defer` islands in-process during an island fetch instead of emitting more client fetches. `mochi:defer:visible` children keep their own fetch; one call site opts out with `mochi:defer={{ inline: false }}`. Default: `true`. See [Server islands](/docs/server-islands/).
- `logger` — built-in request logger. Default: `{ enabled: true }`.
- `publicDir` — directory served as static assets. Default: `./public`. Scanned from disk at startup in every mode, so it must ship with a production deploy.
- `staticDirs` — extra directory trees mounted under a URL prefix. See [Static directories](#static-directories).
- `memoryPressure` — drain in-memory caches when the OS reports low memory. Default: `true`; always off in development. See [Cache](/docs/cache/#memory-pressure).
- `cron` — durable scheduled jobs to start with the server, from `Mochi.cron(name, schedule, handler)`. See [Scheduled jobs](/docs/scheduled-jobs/).
- `cronStorage` — where the cron scheduler stores schedules and jobs. Defaults to `memory`. See [Scheduled jobs](/docs/scheduled-jobs/#storage).
- `outDir` — base directory for build artifacts and dev cache. Default: `./.mochi`.
- `assetPrefix` — URL prefix for framework client assets and the server-island endpoint. Must start with `/`, must not be `/` or end with `/`. Default: `/_mochi`.
- `additionalWatchPaths` — extra dev-mode watcher paths added to `src` and `public`. Default: `[]`.
- `barrelWarnings` — warn when a dependency drags a large, tree-shaken module into the build graph. Default: enabled. See [Development mode](/docs/development-mode/).
- `build` — output controls for `mochi-framework build`. The runtime ignores it. See [CLI](/docs/cli/).
- `svelteConfigPath` — path to a Svelte config file. Default: `./svelte.config.js`. See [Svelte config](/docs/svelte-config/).
- `svelteCompiler` — which compiler emits component JS. Default: `'svelte'`. `'rsvelte'` needs `@mochi-framework/rsvelte`. See [rsvelte](/docs/rsvelte/).
- `optimize` — run the whole-program svelte-shaker pass over `.svelte` source before compiling, so the compiler emits less code. **Production only**, and needs `@mochi-framework/svelte-shaker`. `true` shakes everything; `{ enabled, exclude }` gives finer control. Default: `false`. See [Svelte Shaker](/docs/svelte-shaker/).
- `protection` — Cloudflare-style browser verification: unverified clients get an interstitial that auto-solves the captcha proof-of-work and redeems it for a signed clearance cookie. Default: disabled. See [Protection Mode](/docs/protection/).
- `csrf` — `MochiCsrfOptions` for the origin-header check. See below.
- `proxy` — `MochiProxyOptions` for trusted reverse-proxy headers. See below.
- `hooks` / `filters` — named lifecycle hooks and value filters. See [Extensions](/docs/extensions/).
- `warmup` — warm the SSR pipeline at startup by invoking every static page route once. `boolean | { enabledInProd, enabledInDev }`. Default: `false`. See below.
- `bun` — escape hatch for raw `Bun.serve()` options Mochi does not surface — `idleTimeout`, `maxRequestBodySize`, `reusePort`, `tls`. `fetch` / `websocket` / `routes` / `error` are framework-owned and throw if set. See below.

<Callout type="info">

**Sync `assetPrefix` between build and runtime.** When using a prebuilt manifest, pass `assetPrefix` to the `build()` call (or `--asset-prefix`) so the baked-in URLs match. The manifest's URLs take precedence at runtime if the two disagree.

</Callout>

### Static directories

<VersionNote since="0.10.0" message="staticDirs ships in the next Mochi release (0.10.0). This section describes the upcoming API." />

Mount a directory tree under a URL prefix. Each entry becomes one Bun directory route, so a large tree costs one route rather than one per file, and `Content-Type`, `ETag`, `If-None-Match`, `Range`, `index.html` and sendfile streaming all come from Bun.

```ts
// file: src/index.ts
await Mochi.serve({
  staticDirs: { '/assets': './media' },
  routes,
});
```

This is for **large or generated** trees — a media library, a docs export, a build directory from another tool. For ordinary site assets keep using `publicDir`, which scans and registers each file individually.

<Callout type="warning">

A mount is a native Bun directory route, matched **before** Mochi's request pipeline — so your middleware never sees it. `handle` hooks, `filterResponseHeaders`, `transformPage`, rate limiting, CSRF, trailing-slash normalization and the `request` event all skip `/prefix/*`, and a miss returns Bun's bare 404 rather than your `errorPage`. If you need any of that — auth, custom headers, logging — serve those files through `publicDir` (which can be gated with `protection.protectFiles`) or your own `Mochi.api` / `Mochi.file` route instead.

</Callout>

### Raw Bun.serve options

`bun` is spread straight into the underlying `Bun.serve()`, so any option Mochi doesn't expose is reachable through it:

```ts
Mochi.serve({
  port: 3333,
  routes,
  bun: {
    idleTimeout: 30, // seconds; HTTP default is 10, max 255, 0 disables
    maxRequestBodySize: 1024 * 1024 * 256,
  },
});
```

Bun times a connection out after `idleTimeout` seconds of inactivity, so a response that stays quiet for longer than the default 10 seconds dies with `request timed out after 10 seconds`. Mochi already disables the idle timer for page renders and SSE streams (`Mochi.sse`), so raising it mainly matters for quiet or long-lived `Mochi.api` responses (chunked streams) and slow request bodies.

<Callout type="info">

`fetch`, `websocket`, `routes`, and `error` are owned by the framework — setting them under `bun` throws at startup. Use the top-level `Mochi.serve()` options instead. To lift the timeout for one route without raising the global value, call `server.timeout(request, seconds)` (seconds, or `0` to disable) inside the handler — the `server` and `request` are on the API event.

</Callout>

### Route warmup

The render pipeline stays cold until a route is first visited, so the first request to each page pays a one-time penalty. Set `warmup: true` to invoke every static page route once, in the background, right after the server starts listening:

```ts
await Mochi.serve({
  warmup: true, // warms in production only
  routes,
});
```

`warmup: true` warms in **production only**. For per-mode control, pass an object:

```ts
await Mochi.serve({
  warmup: { enabledInProd: true, enabledInDev: false },
  routes,
});
```

Warmup is fire-and-forget. The server accepts real traffic immediately, and a [`warmup:complete`](/docs/events/) event fires when the batch finishes. Warmup requests carry `warmup: true` on their `request` event and log under a `WARM` label. Routes with parameter segments (`/docs/:slug`) and `*` catch-alls are skipped, since they have no single canonical URL.

Detect warmup hits with `event.isWarmup` (in [middleware](/docs/middleware/)) and `getRequestContext().isWarmup` (in `serverProps`, components, API handlers) to skip side effects that should not fire for synthetic traffic:

```ts
const analytics: Handle = async ({ event, resolve }) => {
  if (!event.isWarmup) track(event.url.pathname); // skip warmup hits
  return resolve(event);
};
```

### CSRF

`csrf` gates state-mutating form submissions (`POST`/`PUT`/`PATCH`/`DELETE` with a form content type) against an origin-header check. The request's `Origin` must match the expected origin or appear in `csrf.trustedOrigins`. JSON endpoints rely on the browser's CORS preflight and are not checked.

- `checkOrigin` — compare `Origin` against the resolved expected origin. Default: `true`.
- `trustedOrigins` — extra origins to allow. Default: `[]`.

```ts
await Mochi.serve({
  proxy: { origin: 'https://app.example.com' },
  csrf: { trustedOrigins: ['https://embed.partner.com'] },
  routes,
});
```

In production, the check refuses every form mutation until `proxy.origin` (or `proxy.hostHeader`) is set, so the deployment break is loud. In development the request is allowed through with a `[mochi]` warning. Routes declaring form `actions` without either option also warn once at boot — in both modes — so the misconfiguration is visible before deploy, not first discovered as a production 403.

### Proxy

`proxy` tells the framework how to recover the public origin (for the CSRF check) and the real client IP (for `getClientAddress()`) from forwarded headers.

- `origin` — explicit public origin. Wins over the header options.
- `protocolHeader` — forwarded-protocol header (`'x-forwarded-proto'`).
- `hostHeader` — forwarded-host header (`'x-forwarded-host'`).
- `portHeader` — forwarded-port header (`'x-forwarded-port'`).
- `addressHeader` — forwarded client-IP header (`'true-client-ip'`, `'x-forwarded-for'`).
- `xffDepth` — number of trusted proxies in front of the server when `addressHeader` is `'x-forwarded-for'`. Default: `1`.
- `requestIdHeader` — forwarded correlation-id header (`'x-request-id'`). Seeds `getRequestContext().requestId`.

```ts
await Mochi.serve({
  proxy: {
    origin: 'https://my.site',
    addressHeader: 'x-forwarded-for',
    xffDepth: 3,
  },
  routes,
});
```

<Callout type="danger">

**Only trust forwarded headers behind a trusted proxy.** Leave the header options unset unless a proxy you control overwrites them. When the app is reachable directly, clients can spoof these headers.

</Callout>

#### `xffDepth` and spoofing

`X-Forwarded-For` is comma-separated. Each proxy appends the address it saw. The framework reads from the **right**, skipping `xffDepth - 1` trusted proxies, so `xffDepth: 3` returns the real client:

```
spoofed, client, proxy1, proxy2   # xffDepth: 3 → "client" (spoofed entry ignored)
```

<Callout type="warning">

**Use `getClientAddress()` for a trusted client IP.** Reading `x-forwarded-for` directly could return a spoofable address. Pass the right `xffDepth`.

</Callout>

#### `getClientAddress()`

```ts
import { getRequestContext, Mochi } from 'mochi-framework';

export const handler = Mochi.api(() => {
  const ip = getRequestContext().getClientAddress();
  return Response.json({ ip });
});
```

Without `proxy.addressHeader`, this returns Bun's connecting `remoteAddress` (or `null` if unavailable).

---
title: 'Extensions (hooks & filters)'
slug: extensions
description: 'Observe or transform framework behavior at lifecycle moments with hooks and filters.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Extensions (hooks & filters)

Extension points for `Mochi.serve()`. Pass `eventHooks` and `filters` as top-level options. Each registry holds at most one entry per name.

```ts
// file: src/index.ts
await Mochi.serve({
  eventHooks: {
    'mochi:ready': async ({ server }) => log.info(`up on ${server.url}`),
  },
  filters: {
    'cookie:defaults': () => ({ secure: true, httpOnly: true, sameSite: 'Lax', path: '/' }),
  },
  routes,
});
```

Names use a `namespace:camelCase` convention. Each name is registered in a typed kind-map. Whether the callback is sync or async is declared per name and enforced by TypeScript.

### Hooks vs filters

- **Hooks** run a user function at a framework moment. No return value — observation or side effects only.
- **Filters** replace a framework default value. The callback receives the existing value and returns the new one.

### Server-only

The registry lives in the server process only. It is never shipped to the browser. Pulling the modules behind the registry into a client bundle fails the build, naming the import. To use a filtered value inside a hydratable island, resolve it during SSR and pass it down as a prop.

### Hooks

#### `mochi:init`

Fires first inside `Mochi.serve()`, before any framework state is set up. Async. Queues do not exist yet, so `Mochi.getQueue()` throws here.

#### `mochi:listening`

Fires right after `Bun.serve()` returns the bound server, before queues mount and before warmup. Use it when you need the port as early as possible. Async.

#### `mochi:queuesMounted`

Fires once every queue in the `Mochi.serve({ queues })` array is live. `ctx.queues` lists the mounted names. Earliest point at which [`Mochi.getQueue()`](/docs/queues/#adding-jobs) and [`Mochi.boss()`](/docs/queues/#mochiboss) resolve. A [standalone producer](/docs/queues/#standalone-producers) process never fires it — there, readiness is the first `add()` resolving. Async.

#### `mochi:ready`

Fires after `Bun.serve()` binds, just before `Mochi.serve()` resolves. Use it for post-bind setup that needs the live `Server`: warm caches, register with service discovery, start background workers. Async.

```ts
await Mochi.serve({
  eventHooks: {
    'mochi:ready': async ({ server }) => {
      await registerWithServiceDiscovery(server.url);
    },
  },
  routes,
});
```

#### `mochi:shutdown`

Fires on `SIGTERM` or `SIGINT`, and on a programmatic [`Mochi.stop()`](/docs/queues/#mochistop) — `ctx.signal` is `undefined` in that case. The framework awaits the hook, then calls `server.stop()`. A second signal force-exits with code 1. Async.

```ts
await Mochi.serve({
  eventHooks: {
    'mochi:shutdown': async ({ signal }) => {
      logger.info(`Got ${signal}, draining…`);
      await db.close();
    },
  },
  routes,
});
```

#### `route:matched`

Fires when a route matches, after the CSRF check passes and before middleware/handler runs. `kind` tells you which route type matched. Sync. `getRequestContext()` is available inside.

#### `image:localAssetEmitted`

Fires at **build time**, right after a locally-imported image is content-hashed and written to `<outDir>/assets/`. The context carries `sourcePath`, `diskPath`, `url`, `width`, `height`, `format`, and `contentType`. Use it to mirror imported assets to a CDN. Async. Treat any upload as idempotent.

```ts
await Mochi.serve({
  eventHooks: {
    'image:localAssetEmitted': async ({ diskPath, url }) => {
      await cdn.upload(url, await Bun.file(diskPath).bytes());
    },
  },
  routes,
});
```

### Filters

#### `csrf:formContentTypes`

Override the `Set<string>` of content types that gate the CSRF check. Resolved once at startup. Sync. Default exported as `DEFAULT_FORM_CONTENT_TYPES`.

#### `csrf:protectedMethods`

Override the `Set<string>` of HTTP methods the CSRF check applies to. Sync. Default exported as `DEFAULT_PROTECTED_METHODS`.

#### `csrf:trustedOrigins`

Override the `Set<string>` of cross-origin sources allowed past the CSRF check. Seeded from `csrf.trustedOrigins`. Sync.

#### `csrf:check`

Override the CSRF decision for the current request. The filter receives the default decision — `null` to pass, a `Response` (usually 403) to block. Return the input to delegate, `null` to bypass, or a fresh `Response` to substitute. Sync.

```ts
await Mochi.serve({
  filters: {
    'csrf:check': (decision, { url }) => {
      // Webhook endpoint with its own auth — bypass CSRF entirely.
      if (url.pathname.startsWith('/webhooks/')) return null;
      return decision;
    },
  },
  routes,
});
```

#### `trailingSlash:redirect`

Override the `trailingSlash` policy for the current request. The filter receives the computed redirect (a 301/308 `Response` or `null`). Return the input to delegate, or `null` to skip the redirect. Sync. It runs only when a `Mochi.page()` route matches; every other route kind and unmatched paths are [exempt from `trailingSlash` outright](/docs/trailing-slash/) and never reach it.

```ts
await Mochi.serve({
  trailingSlash: 'always',
  filters: {
    // A page a third party embeds at the slashless URL — leave it where it is.
    'trailingSlash:redirect': (redirect, { url }) => (url.pathname === '/embed' ? null : redirect),
  },
  routes,
});
```

#### `cookie:defaults`

Default `CookieSerializeOptions` merged into every `cookies.set()` call. Per-call options win per field. Resolved once at startup. Sync.

```ts
await Mochi.serve({
  filters: {
    'cookie:defaults': () => ({ secure: true, httpOnly: true, sameSite: 'Lax', path: '/' }),
  },
  routes,
});
```

#### `html:shell`

Modify the HTML shell template once at startup. The value is the resolved template with `{{mochi.head}}`, `{{mochi.css}}`, `{{mochi.body}}`, `{{mochi.script}}` placeholders intact. Sync.

<Callout type="warning">

**Use `htmlShell` on `serve()` for full template control.** This filter is for snippet injection. Replacing the whole template bypasses placeholder processing and breaks your layout.

</Callout>

#### `serverIsland:secretKey`

Override the secret key used to encrypt server-island props and image payloads. Default: the `MOCHI_KEY` env var (or a fresh random key if unset). Use it to source the key from KMS / Vault. Async. The `envKeyPresent` field says whether `MOCHI_KEY` was set.

```ts
await Mochi.serve({
  filters: {
    'serverIsland:secretKey': async () => {
      const raw = await kms.getSecret('mochi-island-key');
      return Buffer.from(raw, 'base64url');
    },
  },
  routes,
});
```

#### `serverIsland:inlineBudget`

<VersionNote since="0.10.0" message="Nested mochi:defer inlining (and the serverIsland:inlineBudget filter with DEFAULT_INLINE_BUDGET) ships in the next Mochi release (0.10.0). This section describes the upcoming API." />

How many nested `mochi:defer` call sites one island fetch expands in-process before the rest fall back to fetch placeholders (see `Server islands`). The budget counts total expansions per fetch — a recursive chain and a long `{#each}` list draw from the same pool. Resolved per island fetch, with the fetched island's identity key and the request in context. Never fires when `inlineNestedIslands` is off, or when the fetched island also hydrates. Sync.

```ts
import { DEFAULT_INLINE_BUDGET } from 'mochi-framework';

await Mochi.serve({
  filters: {
    // The dashboard island expands a wide row list; everything else keeps the default.
    'serverIsland:inlineBudget': (def, { componentName }) => (componentName.startsWith('Dashboard_') ? 128 : def),
  },
  routes,
});
```

Default is `DEFAULT_INLINE_BUDGET` (32). Return `0` to send every nested island of that fetch down the placeholder path — the same as `inlineNestedIslands: false` for that fetch.

#### `payload:compressMinBytes`

The minimum size (bytes) a server-island-prop or image payload must reach before Mochi deflates it ahead of encryption. Evaluated per payload. The filter receives the pre-encryption `payload` bytes. Sync. Default `DEFAULT_COMPRESS_MIN_BYTES` (80). Return `Infinity` to disable compression for a payload.

#### `compile:preprocessors`

A list of Svelte `PreprocessorGroup` to run on every `.svelte` source before compilation. Applies to server and client targets. Branch on `target` in context. Sync. Default `[]`.

```ts
import autoprefixer from 'autoprefixer';
import postcss from 'svelte-preprocess';

await Mochi.serve({
  filters: {
    'compile:preprocessors': () => [postcss({ postcss: { plugins: [autoprefixer] } })],
  },
  routes,
});
```

Bun transpiles `<script lang="ts">` automatically, so you need no TypeScript preprocessor. Preprocessors do not apply to `.md` / `.svx` (mdsvex handles those).

#### `publicDir:scan`

Modify the `Map<urlPath, diskPath>` of files served from the public directory. The filter receives a fresh copy after each scan. Use it to add virtual files, shadow built-in routes, or rename URLs. Async. A `Mochi.page` / `Mochi.api` route on the same URL still wins.

```ts
await Mochi.serve({
  filters: {
    'publicDir:scan': async (files) => {
      files.set('/robots.txt', '/etc/mochi/robots.generated.txt');
      return files;
    },
  },
  routes,
});
```

#### `consoleLogger:level`

Change the severity a log line is written at. Return `'info' | 'warn' | 'log' | 'debug'`. Runs after the automatic 5xx/slow-request escalation and before `consoleLogger:line`. The level still gates against the active [log level](/docs/logging/). Sync.

```ts
await Mochi.serve({
  filters: {
    // Job enqueues are noise in this app. Health checks matter more than usual.
    'consoleLogger:level': (level, { path, source }) => {
      if (source.name === 'queue:added') return 'debug';
      return path.startsWith('/health') ? 'warn' : level;
    },
  },
  routes,
});
```

Context fields: `label`, `path`, `status`, `kind`, `source`.

#### `consoleLogger:line`

Mutate or drop a formatted line right before `consoleLogger()` writes it. First argument is the rendered string (ANSI colours applied). Second is a structured context. Return the string to log it, a rewrite to substitute, or `null` to drop it. Sync. Mochi ships `silenceInternalRoutes`, which drops the Chrome devtools probe and the `/__mochi/admin/*` routes.

```ts
import { Mochi, silenceInternalRoutes } from 'mochi-framework';

await Mochi.serve({
  filters: { 'consoleLogger:line': silenceInternalRoutes },
  routes,
});
```

Context fields: `level`, `label`, `path`, `status`, `kind`, `source` (`{ name, payload }` — narrow on `source.name` for typed per-event fields).

#### `barrel:warn`

Mutate or drop a [barrel-import warning](/docs/development-mode) before it is logged. First argument is the rendered string. Second is `{ pkg, file, bytes, usedRatio }`. Return the string, a rewrite, or `null` to suppress. Sync.

```ts
await Mochi.serve({
  filters: {
    // Drop the warning for one package, rewrite the rest.
    'barrel:warn': (line, { pkg, bytes }) => {
      if (pkg === '@lucide/svelte') return null;
      return `${line} (${Math.round(bytes / 1024)} KB parsed)`;
    },
  },
  routes,
});
```

#### `image:maxRedirects`

Override how many upstream redirects the image fetcher follows. Each hop is re-validated against `allowedHosts` / `blockPrivateNetworks`. Default `5`. `0` rejects any redirect. The `src` is in context. Sync.

#### `image:url`

Rewrite the encrypted URL from `getImageUrl()` (and `<Image>`), typically to prepend a CDN origin. The context carries `src`, `filename`, and `original`. Return the URL unchanged to opt out per call. Sync.

```ts
await Mochi.serve({
  filters: {
    'image:url': (url) => `https://cdn.example.com${url}`,
  },
  routes,
});
```

<Callout type="danger">

Only rewrite the origin/prefix. Never rewrite the last path segment (the `filename`). That segment is authenticated (bound as AAD to the token), so the image endpoint re-derives it and rejects (403) any request whose filename changed.

</Callout>

#### `image:fileFilter`

Controls which local imports become `ImportedImage` objects. Default `IMAGE_FILE_FILTER` matches png, jpg/jpeg, webp, avif, gif. Return a narrower or wider regex. The `target` is in context. Sync. Widening only decides which files reach the loader. Each one is still decoded by `Bun.Image`.

#### `image:localAssetFilename`

Rename the content-hashed file a local import emits. Default `<slug>-<hash>.<ext>`. Must be deterministic and a bare filename (no path separator or `..`). Sync.

#### `image:localAssetUrl`

Rewrite the `src` URL a local import resolves to. Default `${assetPrefix}/asset/<filename>`. Must be deterministic. Sync. A same-origin override must stay under `${assetPrefix}/asset/` as a single segment.

<Callout type="warning">

Returning an absolute (CDN) URL bypasses the built-in `/asset/` route and the local-disk shortcut. Pair it with `image:localAssetEmitted` to upload the bytes there.

</Callout>

#### `email:message`

Intercept every message sent through `Mochi.email()` right before the transport. Return a modified message, or `null` to **suppress** the send. The context carries the configured `transport` type. Async. See [Email](/docs/email/#intercepting-messages).

```ts
await Mochi.serve({
  filters: {
    'email:message': (message, { transport }) => {
      if (transport === 'smtp' && process.env.STAGING) {
        return { ...message, to: ['qa@app.dev'], cc: undefined, bcc: undefined };
      }
      return { ...message, headers: { ...message.headers, 'List-Unsubscribe': '<mailto:unsub@app.dev>' } };
    },
  },
  routes,
});
```

A suppressed send still emits `email:sent` with `transport: 'suppressed'`.

#### `captcha:bits`

Proof-of-work difficulty in leading zero bits. Resolved once at startup. Bounds-checked to 1–32. The context carries the raw `captcha` options and `configured`. Sync.

```ts
await Mochi.serve({
  filters: {
    'captcha:bits': (def) => (process.env.NODE_ENV === 'test' ? 8 : def),
  },
  routes,
});
```

#### `captcha:minAgeMs`

The captcha timing floor. Applied per token. The context carries `bits`, `ageMs`, and `limitMs` (the returned floor must stay under `limitMs`). Sync. This is the only check that a submission took human time — see [The timing floor](/docs/captcha/#the-timing-floor).

#### `captcha:driftAllowanceMs`

Slack added to `maxAgeMs` before a token is refused as expired, to absorb clock skew across a multi-instance deploy. Resolved once. Sync. It widens the expiry side only, never the floor.

#### `captcha:solveBudgetMs`

How long the widget spends actively solving before it offers a retry. Resolved once and handed to the widget through `mintCaptcha()`. Must be positive and finite. Sync. Default `60_000`. A form can override it with the `solveBudgetMs` prop.

#### `queue:expireInSeconds`

How many seconds a job may stay active before the store retries or fails it. Resolved once per queue at mount, after the per-queue [`expireInSeconds`](/docs/queues/#long-running-jobs) option. `explicit` says whether the value came from that option. When the queue declared nothing and the filter leaves the default unchanged, nothing is sent to the store — an existing queue keeps its stored expiry. Sync. Default `900` (15 minutes).

```ts
await Mochi.serve({
  filters: {
    'queue:expireInSeconds': (value, { explicit }) => (explicit ? value : 300),
  },
  routes,
});
```

The returned value must exceed the worst-case runtime of `process` — a job that outlives it is handed out again while the original still runs.

---
title: 'Svelte config'
slug: svelte-config
description: 'Customize the Svelte compiler through svelte.config.js with compiler options and framework defaults.'
---

## Svelte config

Mochi loads `./svelte.config.js` from the cwd at startup and merges its `compilerOptions` into the framework defaults. Drop the file at the root of your app to customize the Svelte compiler.

```js
// file: svelte.config.js
export default {
  compilerOptions: {
    experimental: {
      async: true,
    },
  },
};
```

The file is optional. If it is missing, Mochi logs `[mochi] No Svelte config found at … — using framework defaults.` and continues with the framework defaults.

Both ESM (`export default`) and CJS (`module.exports`) are supported. In dev, Mochi watches the file — an edit reloads `compilerOptions` without restarting the server.

### Framework defaults

Two fields are seeded before your config merges in:

| Field                | Default | Why                                                                  |
| -------------------- | ------- | -------------------------------------------------------------------- |
| `experimental.async` | `true`  | Enables top-level `await` in `.svelte` components (Svelte 5 opt-in). |
| `discloseVersion`    | `false` | Suppresses the `<!-- svelte v… -->` comment in SSR output.           |

Override either by setting it in your own `compilerOptions`.

### svelteConfigPath

Pass `svelteConfigPath` to `Mochi.serve()` or `build()` to load the config from somewhere else. Relative paths resolve against `process.cwd()`. Absolute paths are used as-is.

```ts
// file: src/index.ts
await Mochi.serve({
  svelteConfigPath: './configs/svelte.staging.config.js',
  routes,
});
```

### Framework-owned fields

Mochi forces three `compilerOptions` at every compile call site:

| Field      | Forced to                                                                                            |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| `generate` | `'server'` for SSR builds, `'client'` for hydration bundles.                                         |
| `filename` | The actual file path being compiled.                                                                 |
| `dev`      | The `Mochi.serve()` `development` flag — **client target only**. Server compiles do not force `dev`. |

Every other field — `runes`, `css`, `accessors`, `cssHash`, `discloseVersion`, `experimental.*` — is yours to set.

### Where it applies

The merged options are used everywhere Mochi invokes the Svelte compiler:

- SSR compilation of `.svelte` files
- SSR compilation of `.svelte.js` / `.svelte.ts` rune modules
- Client-side island bundles
- mdsvex `.md` / `.svx` files (server target)

Under `svelteCompiler: 'rsvelte'`, the function-valued `cssHash` and `warningFilter` are stripped: `cssHash` with a one-time warning, `warningFilter` silently, since Mochi never surfaces compiler warnings. See [rsvelte](/docs/rsvelte/).

### What is not read

Only `compilerOptions` is honored. SvelteKit-style top-level keys are ignored:

- `preprocess` — register preprocessors through the `compile:preprocessors` filter instead.
- `extensions` — Mochi's accepted extensions are fixed (`.svelte`, `.svelte.[jt]s`, `.md`, `.svx`).
- `kit` — SvelteKit-only.

---
title: 'Development mode'
slug: development-mode
description: 'What the development flag enables: live reload, file watcher, route handler HMR, debug bar, and error overlay.'
---

<script>
  import Callout from './_components/Callout.svelte';
</script>

## Development mode

Mochi runs in development mode when `NODE_ENV=development`, and in production mode otherwise. Set the variable in your `dev` script and leave it unset everywhere else:

```json
// file: package.json
{
  "scripts": {
    "dev": "NODE_ENV=development bun src/index.ts",
    "start": "bun src/index.ts"
  }
}
```

`Mochi.serve()` needs no flag for this — the environment decides:

```ts
// file: src/index.ts
await Mochi.serve({ routes });
```

In development mode, Mochi enables:

- **Live reload** — a `mochi-live-reload` web component connects to `/__mochi_live_reload` and refreshes the page on file changes.
- **File watcher** — watches `src/` and `public/`. An edit invalidates the SSR compile cache and emits `file:change` on `mochiEvents`.
- **Debug bar** — `<div id="mochi-dev-toolbar">` is injected into every page.
- **Error overlay** — build and runtime errors render on top of the page.
- **Bundle stats** — a JSON report is served at `${assetPrefix}/client/stats`.
- **Stack traces on `error` events** — `error` payloads include `stack`. In production `stack` is `undefined`.

<Callout type="warning">

Never run development mode in production — whether from a stray `NODE_ENV=development` or a forced `development: true`. Stack traces leak through the `error` event and the error overlay, the file watcher holds open file descriptors, and SSR bundles recompile on every change instead of loading from the prebuilt manifest.

</Callout>

### Overriding the mode

Pass `development` to force a mode regardless of the environment:

```ts
// file: src/index.ts
await Mochi.serve({
  development: true, // ignores NODE_ENV
  routes,
});
```

Reach for it sparingly. Everything that runs outside `Mochi.serve()` still reads `NODE_ENV` — [`isDev`](/docs/environment-constants/#isdev) in module top-level code, and [`setupTailwind`](/docs/tailwind/#dev-rebuilds), which you call yourself — so an override makes those disagree with the running server. Mochi warns at boot when it contradicts `NODE_ENV=development`.

### Live reload

Set `liveReload: false` to keep the debug bar and file watcher but skip the `/__mochi_live_reload` WebSocket and the `mochi-live-reload` web component. Defaults to whatever `development` is.

### File watcher

The watcher always covers `src/` and `public/`. Extend it with `additionalWatchPaths`:

```ts
// file: src/index.ts
await Mochi.serve({
  additionalWatchPaths: ['../content', './docs'],
  routes,
});
```

`additionalWatchPaths` is additive. Paths that do not exist on disk are skipped silently.

### Route handler HMR

**Route handler code** — `Mochi.api` handlers, `serverProps` resolvers, form `actions`, `Mochi.ws` handlers, `Mochi.sse` handlers — is hot-swapped without a restart. The watcher builds your entry (`src/index.ts`) to discover its transitive dependencies. When any change, it rebuilds the entry, re-reads the `routes` from its `Mochi.serve()` call, and updates the running server in place. Adding, removing, and editing route patterns all work without a restart. WebSocket connections stay open. The browser reloads to pick up updated `serverProps`.

<Callout type="warning">

Each reload re-evaluates the **entire first-party dependency graph** — every `let` / `const` at module scope is recreated. This is not just a stale-cache annoyance: a module-scoped singleton that holds an **OS resource** (a DB pool, a `setInterval`, a file watcher, an SMTP pool) is re-created on every save while the previous instance is orphaned with its resource still open. Nothing closes it, so usage grows one leak per save until a hard failure — a Postgres pool, for example, exhausts `max_connections` after a dozen saves and takes the database down for every client.

Moving the singleton "into a module the entry imports" does **not** help — that module is first-party, so it is exactly what gets re-evaluated. Hold the resource with [`pinGlobal`](/docs/utility-helpers/#process-singletons) instead, which pins one instance on `globalThis` that survives every reload:

```ts
// file: src/db/client.ts
import { SQL } from 'bun';
import { pinGlobal } from 'mochi-framework';

export function getSql() {
  return pinGlobal('app:sql', () => new SQL(process.env.DATABASE_URL!, { max: 8, idleTimeout: 30 }));
}
```

Call `getSql()` wherever you need the pool — every call returns the same instance, so route handlers and `serverProps` share the one set of connections:

```ts
// file: src/routes.ts
import { getSql } from './db/client';

export const routes = {
  '/users': Mochi.page('./src/Users.svelte', {
    serverProps: async () => ({
      users: await getSql()`SELECT id, name FROM users`,
    }),
  }),
};
```

Namespace your key with an `app:` prefix — the framework uses `__mochi_*__` for its own pins. Setting `idleTimeout` is worth it regardless: it bounds the damage from any pool that still escapes.

</Callout>

Mochi warns once per dev session — via the [`recompile:module-churn`](/docs/events/#recompilemodule-churn) event — after the entry has been re-imported ten times, printed by `consoleLogger()` as a `warn`-level `HMR` line. If you have deliberately accepted the churn (or your resources are all held with `pinGlobal`), silence just that line with a [`consoleLogger:line`](/docs/extensions/#consoleloggerline) filter — the same mechanism the framework uses to hide its own internal routes:

```ts
// file: src/index.ts
await Mochi.serve({
  filters: {
    'consoleLogger:line': (line, { source }) => (source.name === 'recompile:module-churn' ? null : line),
  },
  routes,
});
```

Returning `null` drops the line; returning it unchanged keeps it. This suppresses only the churn warning — every other log line is untouched.

### `file:change` event

Every watcher event re-emits on `mochiEvents` as `file:change`. Use it to invalidate your own caches:

```ts
// file: src/lib/docs-cache.ts
import { mochiEvents } from 'mochi-framework';

mochiEvents.setHandler('docs:cache-clear', 'file:change', ({ path }) => {
  if (path.endsWith('.md')) clearMyMarkdownCache();
});
```

<Callout type="warning">

**Use `setHandler` here, not `.on()`.** In dev, the module holding this handler can be re-run when Mochi recompiles. Each `.on()` call leaves behind another duplicate listener. `setHandler` registers by name, so re-running replaces the previous one.

</Callout>

In production the watcher never starts and `file:change` never emits.

### HMR rebuild logger lines

The built-in logger prints a structured line per save:

- `BUILD` — one per page compiled, plus a summary with total file count and duration.
- `BNDL` — one per `buildClientBundle()` call.
- `HMR ` — one per rebuild cycle. Note shows the trigger, `pages=N`, and `bundles=N`.

A healthy `bundles=` for a non-CSS save is `1`. A higher number means a regression to per-page bundling, which is O(N²) work for N hydratable pages.

<Callout type="warning">

**Use `logger: { compile: false }` to suppress rebuild lines.** It drops only `BUILD` / `BNDL` / `HMR` output. Disabling the whole logger loses other diagnostics.

</Callout>

### Barrel-import warning

Mochi warns when a dependency drags a large module into the build graph that is then almost entirely tree-shaken away:

```ts
import { Sun } from '@lucide/svelte'; // ❌ parses the whole ~100 KB re-export index every rebuild
import Sun from '@lucide/svelte/icons/sun'; // ✅ pulls only the one icon
```

Bun tree-shakes the barrel's modules, but it still re-parses the package's big re-export file on every rebuild, which slows HMR. In dev the warning fires once per package. A production `mochi-framework build` runs the same check and collapses every offender into one grouped summary line.

Tune or silence it with `barrelWarnings` on `Mochi.serve()`:

```ts
await Mochi.serve({
  barrelWarnings: false, // silence entirely
  // or keep it on but suppress a package / raise the threshold:
  barrelWarnings: { ignore: ['@lucide/svelte'], minBytes: 100 * 1024 },
  routes,
});
```

`minBytes` defaults to 50 KB. For richer logic than a static `ignore` list, register the [`barrel:warn` filter](/docs/extensions#barrelwarn).

---
title: 'Discord'
slug: discord
ogTitle: 'Join the Mochi Discord'
description: 'Join the Mochi community on Discord.'
---

<script>
  import QrCode from './_components/QrCode.svelte';
</script>

## Discord

Questions, bug reports, ideas, or want to see what others are building?
Join the community: **[mochi.fast/discord](/discord/)**.

### Scan to join on your mobile

<QrCode url="https://mochi.fast/discord/" />

---
title: 'Debug bar'
slug: debug-bar
description: 'A floating dev toolbar showing hydration metrics, request data, island breakdown, and bundle stats.'
---

<script>
  import { Image } from 'mochi-framework/image';
  import debugBar from './images/debug-bar.png';
  import debugBarIslands from './images/debug-bar-islands.png';
</script>

## Debug bar

A floating toolbar pinned to the bottom-right of every page in development. It surfaces hydration cost, request metadata, runtime warnings, and a link to the bundle stats page. `Mochi.serve()` mounts it whenever `development: true`, with nothing to wire up.

<figure>
  <Image src={debugBar} size="doc" width={debugBar.width} height={debugBar.height} alt="The Mochi debug bar: a status dot, the mochi wordmark, and buttons for Request, Islands, JS, Info and Cache, plus the email outbox and cogwheel icons" />
  <figcaption>The bar as it sits on a page in development. The toolbar has its own dark styling and does not follow the site's theme.</figcaption>
</figure>

In production (`development: false`) the toolbar mount point, its entry script, and the per-request `window.__mochi_debug` payload are stripped from the HTML. The bar adds zero bytes to production responses. See [development mode](/docs/development-mode/) for the rest of what dev mode turns on.

### Buttons

| Button           | Opens                                                                               |
| ---------------- | ----------------------------------------------------------------------------------- |
| Status dot       | Live-reload connection state — green pulse when connected, red when dropped.        |
| `Request`        | Matched route pattern, pathname, params, response size, `Set-Cookie`s, headers.     |
| `Info`           | Mochi / Svelte / Bun versions and a snapshot of the active `Mochi.serve()` config.  |
| `Islands`        | Per-island breakdown with mode tag, props size, and a locate-on-page button.        |
| `Warnings`       | Anything pushed through `window.__mochi_warn(msg)`. Hidden when the queue is empty. |
| `Bundle Stats ↗` | Opens the bundle stats page (`/_mochi/client/stats`) in a new tab.                  |
| `Cache`          | Empty the on-disk [image cache](/docs/images/) in one click.                        |
| `⚙`              | Configure which panel buttons appear in the bar.                                    |

### Configuring panels

The cogwheel opens a checklist of the panels. Unchecked panels disappear from the bar. The choice persists across reloads in `localStorage` under `mochi:debug:hidden-panels`. At least one panel always stays enabled.

### Islands panel

Lists every `<mochi-hydratable-island>` and `<mochi-server-island>` on the page, grouped by type. Each row shows the component name, its hydration mode, and props size. Click a row to expand the props as syntax-highlighted JSON. Click the crosshair icon to scroll to the island and flash a cyan outline for ~1.5s.

<figure>
  <Image src={debugBarIslands} size="doc" width={debugBarIslands.width} height={debugBarIslands.height} alt="The Islands panel listing hydrated islands with their mochi:hydrate tags, props sizes, shared badges and crosshair buttons, above a summary reading 12 islands, 39.3 kB total props, 8 hydrated, 4 server" />
  <figcaption>The Islands panel. The summary row counts hydrated and server islands separately, and rows sharing a props payload carry a <code>shared</code> badge.</figcaption>
</figure>

The `Islands` button shows a running total props size and changes color past two thresholds — yellow above **10 KB**, red above **100 KB**. Props payload is the dominant tax on hydration. See [passing props to islands](/docs/island-props/) for how to keep payloads small.

When two or more islands ship the exact same props payload, Mochi hoists it into a single shared `<script type="application/json">` block. Those rows show a `shared` badge, and the totals count the shared payload once.

### Server islands

Server-island rows display a lock icon. Their props are encrypted before they reach the client. The decoded JSON shown in the panel comes from a dev-only sidecar copy. In production no plaintext props leave the server.

### Images panel

Lists every image produced during the request. Deferred URLs from [`<Image>` / `getImageUrl`](/docs/images/) show a lock icon and the size-name tag. Inline [`getImage`](/docs/images/#getimage-inline-bytes-metadata) results show an `inline` tag. Click a row to expand the preview and params.

### Cache panel

An **Empty image cache** button that clears the on-disk [image cache](/docs/images/) by `POST`ing to the dev-only `/_mochi/image-cache/` endpoint. Useful after tweaking resize settings or replacing a source image. The endpoint and tab exist only while the debug bar is enabled.

### Warnings

Any code can queue a warning into the toolbar by calling `window.__mochi_warn('message')`. Mochi uses this internally for soft hydration issues that are not severe enough to throw. Unread warnings also appear in the page console.

### Info panel

Shows the running Mochi, Svelte, and Bun versions, plus a snapshot of the resolved `Mochi.serve()` config — mode, port, trailing-slash policy, log level, route count, and whether warmup, live-reload, CSRF, proxy, and middleware are active. Captured once at startup.

### Panel errors

Each panel renders from live runtime state, so the panels are wrapped in an error boundary: a render fault in one degrades that panel instead of throwing onto the host page, and the toolbar stays usable. The fault is still logged to the console as `[mochi] debug-bar panel render fault: …`.

The bar ships as a production-Svelte bundle, so that log carries no detail. To debug a panel fault, restart with `MOCHI_DEBUGBAR_DIAGNOSTIC=1` — the bar then compiles dev-Svelte and un-minified, so the logged error names the exact cause (and, for a keyed-`{#each}` collision, the duplicate key) with a readable stack. For temporary debugging only; it makes the bundle larger.

---
title: 'Testing'
slug: testing
ogTitle: 'Testing a Mochi app'
description: 'Unit-test with bun:test and run full-app tests in isolated processes with the runTests helper.'
---

<script>
  import Callout from './_components/Callout.svelte';
</script>

## Testing

<Callout type="warning">

Testing support is **experimental**. The `bun test` runner works well for plain unit tests today. The full-app helper below is new, and its API may change.

</Callout>

### Unit tests

Test pure functions, stores, and any non-server logic directly with [`bun test`](https://bun.sh/docs/cli/test) — no Mochi-specific setup:

```ts
// src/lib/slugify.test.ts
import { expect, test } from 'bun:test';
import { slugify } from './slugify';

test('lowercases and dasherizes', () => {
  expect(slugify('Hello World')).toBe('hello-world');
});
```

```sh
bun test
```

### Full-app tests

A test that boots a real server with `Mochi.serve()` must run **one file per process**. `Mochi.serve()` allows one instance per process, so two server-booting test files in the same `bun test` run throw `Mochi.serve() has already been called.`

`runTests` solves this. It globs `src/**/*.test.ts` and runs each file in its own `bun test` process, parallelised across CPU cores. Add a small script:

```ts
// scripts/run-tests.ts
#!/usr/bin/env bun
import { runTests } from 'mochi-framework';

await runTests();
```

Point your `test` script at it:

```json
// package.json
{
  "scripts": {
    "test": "bun scripts/run-tests.ts"
  }
}
```

Each file gets a fresh process, so every test can call `Mochi.serve({ port: 0 })` without colliding:

```ts
// src/routes.test.ts
import { afterAll, beforeAll, expect, test } from 'bun:test';
import type { Server } from 'bun';
import { Mochi } from 'mochi-framework';
import { routes } from './routes';

let server: Server;

beforeAll(async () => {
  server = await Mochi.serve({ port: 0, logger: { enabled: false }, routes });
});

afterAll(() => server.stop(true));

test('GET / renders', async () => {
  const res = await fetch(`http://localhost:${server.port}/`);
  expect(res.status).toBe(200);
});
```

#### Options

`runTests(options?)` accepts:

- **`dir`** — package root to scan and run tests from. Defaults to the current working directory.
- **`sequential`** — files (relative to `dir`) that must run on their own, after the parallel batch, for tests that cannot share machine state:

```ts
await runTests({ sequential: ['src/liveReload.test.ts'] });
```

`runTests` reprints a recap at the end — every failed file, the failing test names, and their error output — and exits with code `1` if any file failed.

### Bun workspaces: use the hoisted linker

<Callout type="warning">

In Bun **workspaces**, `bun install` defaults to the isolated linker. Combined with `bun test`, this trips a Bun bug: a second `Bun.build()` in the test process fails with `EISDIR reading file` on a dependency inside `node_modules/.bun`. Pin the hoisted linker in your workspace root `bunfig.toml`:

```toml
# bunfig.toml
[install]
linker = "hoisted"
```

Then delete `node_modules` and reinstall. Single-package apps — including everything scaffolded by `create-mochi` — install hoisted by default and are unaffected.

</Callout>

---
title: 'Type checking'
slug: type-checking
description: 'Make svelte-check and your editor understand the mochi:* directives with the ambient types and a warningFilter in svelte.config.js.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Type checking

Scaffolded projects ship a `typecheck` script that runs [`svelte-check`](https://www.npmjs.com/package/svelte-check) and then `tsc`:

```sh
bun run typecheck
```

Both tools, and the Svelte VS Code extension, read `.svelte` files raw. They see the `mochi:*` directives that Mochi strips before the Svelte compiler runs, so two small additions keep them quiet.

### Ambient types

Reference `mochi-framework/ambient` from a `.d.ts` file in your project. Scaffolds do this in `src/global.d.ts`:

```ts
// file: src/global.d.ts
/// <reference types="mochi-framework/ambient" />
```

It declares Mochi's asset imports (`*.css`, `*.md`, images) and whitelists the directives on every HTML element and on every component, so `<UserAvatar mochi:defer userId={1} />` type-checks without the component declaring anything.

#### Directives on components

<VersionNote since="0.10.0" message="Directives on components are covered by the ambient types since 0.10.0. Earlier versions only covered HTML elements and patched svelte-check instead." />

svelte2tsx checks a call site against the component's own `$props()` type. Mochi widens that type where svelte2tsx builds it, so the `mochi:*` keys and their option objects are known on every component. Generic components (`<script generics="…">`) are the one exception: svelte2tsx types them separately, so intersect `MochiDirectives` into their props yourself:

```svelte
<!-- file: src/List.svelte -->
<script lang="ts" generics="T">
  import type { MochiDirectives } from 'mochi-framework';

  let { items }: { items: T[] } & MochiDirectives = $props();
</script>
```

<Callout type="info">

Projects scaffolded before 0.10.0 patch `svelte-check` instead (`patches/svelte-check@….patch` via `patchedDependencies`). The patch only reaches the CLI — editors bundle their own copy of svelte2tsx and keep reporting the error. After upgrading, delete the `patches/` directory and the `patchedDependencies` entry in `package.json`; the ambient types cover both.

</Callout>

### `attribute_illegal_colon`

The Svelte compiler warns about the colon in every `mochi:*` attribute. Filter it in `svelte.config.js`; `svelte-check` and the VS Code extension both read that file:

```js
// file: svelte.config.js
export default {
  compilerOptions: {
    experimental: { async: true },
    warningFilter: (warning) => warning.code !== 'attribute_illegal_colon',
  },
};
```

Scaffolds ship this filter. If yours predates it, adding the line replaces the `--compiler-warnings 'attribute_illegal_colon:ignore'` flag in the `typecheck` script.

---
title: 'Tailwind'
slug: tailwind
ogTitle: 'Tailwind CSS v4 in a Mochi app'
description: 'Integrate Tailwind CSS v4 into a Mochi app with the setupTailwind helper.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import SeeItInAction from './_components/SeeItInAction.svelte';
</script>

## Tailwind

<Callout type="warning">

Experimental — the `mochi-framework/tailwind` API may change.

</Callout>

Drive Tailwind v4 with its Node API. Mochi ships an opt-in helper at `mochi-framework/tailwind` that compiles your input CSS at server startup and re-runs on file changes in dev. Then `import` the generated file from any `.svelte` and Mochi's [CSS-import bundler](/docs/css-imports/) links it scoped to the page.

### Setup

1. Install Tailwind alongside its Node and scanner packages:

```sh
bun add tailwindcss @tailwindcss/node @tailwindcss/oxide
```

2. Write an input CSS that imports the layers you want and tells Tailwind where to scan:

```css
/* file: src/styles/app.css */
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css';

@source './*.svelte';
```

3. Call `setupTailwind` at module scope in `src/index.ts`, before `Mochi.serve()`. Top-level `await` ensures the generated CSS exists for both the build CLI and the dev server:

```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';
import { setupTailwind } from 'mochi-framework/tailwind';

await setupTailwind({
  input: './src/styles/app.css',
  output: './src/styles/app.generated.css',
  minify: process.env.NODE_ENV !== 'development',
});

await Mochi.serve({
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});
```

4. `import` the generated file from any `.svelte` that uses Tailwind classes:

```svelte
<!-- file: src/Home.svelte -->
<script>
  import './styles/app.generated.css';
</script>

<button class="rounded-md bg-emerald-600 px-3 py-1.5 text-white hover:bg-emerald-700">Click</button>
```

5. Add `app.generated.css` to `.gitignore` — it is a build artifact.

The bundler strips the import from the JS bundle and serves the CSS at `/_mochi/import-css/<hash>.css`. The `<link>` is added to every page that transitively imports it. Pages that do not reference it ship no Tailwind. See [CSS imports](/docs/css-imports/).

### `setupTailwind` options

| Option   | Default              | Meaning                                                       |
| -------- | -------------------- | ------------------------------------------------------------- |
| `input`  | —                    | Path to the input CSS (`@import`s and `@source` rules).       |
| `output` | —                    | Path where the generated CSS is written, stable for `import`. |
| `base`   | directory of `input` | Anchors `@source` patterns.                                   |
| `minify` | `false`              | Minify the optimised output. Set from `process.env.NODE_ENV`. |

<Callout type="info">

`@source` paths resolve against `base`. `./*.svelte` matches files next to `app.css` only. Use `**/*.svelte` for nested folders.

</Callout>

### Dev rebuilds

In development, `setupTailwind` subscribes to `file:change` on `mochiEvents` and rebuilds on `.svelte` / `.ts` / `.js` / `.html` / `.md` / `.svx` / `.css` changes. The resulting write goes through Mochi's CSS fast-path — a stylesheet swap, not a full SSR rebuild. The watcher attaches only when `process.env.NODE_ENV === 'development'`.

### Production builds

`setupTailwind` static-imports `@tailwindcss/oxide`, a native module. If your production runtime image uses a different libc than the install image, the binding installed at build time fails to load at runtime and the server crashes at startup with `Cannot find native binding`.

Generate the CSS at build time and dynamic-import the helper so production never loads oxide:

```ts
// file: src/index.ts
if (process.env.NODE_ENV === 'development') {
  const { setupTailwind } = await import('mochi-framework/tailwind');
  await setupTailwind({
    input: './src/styles/app.css',
    output: './src/styles/app.generated.css',
  });
}
```

Pair it with a prebuild script that compiles the CSS ahead of [`mochi-framework build`](/docs/cli/#build):

```ts
// file: scripts/prebuild.ts
import { compileTailwind } from 'mochi-framework/tailwind';

await compileTailwind({
  input: './src/styles/app.css',
  output: './src/styles/app.generated.css',
  minify: true,
});
```

```json
"scripts": {
  "build": "bun scripts/prebuild.ts && mochi-framework build"
}
```

<Callout type="info">

**Guard the `mochi-framework/tailwind` import dynamically.** A static import loads the oxide native binding even when the call site is gated by `NODE_ENV`. Put the `import()` inside the development guard so the binding is never resolved in production.

</Callout>

### Preflight and resets

The example imports `tailwindcss/utilities.css` **without** `layer(utilities)`. If your shell's CSS ships an unlayered universal reset, wrapping utilities in `layer(utilities)` lets the unlayered reset clobber `.p-6`, `.mt-2`, and so on, because unlayered styles beat layered ones in the cascade.

The example also skips Tailwind's preflight so the stylesheet does not reset unrelated UI. The cost is that user-agent defaults leak through, so `<button>` keeps its rounded macOS pill shape. Add a small reset:

```css
/* file: src/styles/app.css */
button {
  appearance: none;
  background: transparent;
  border: 0;
  font: inherit;
  color: inherit;
  cursor: pointer;
}
```

To opt back in, `@import 'tailwindcss/preflight.css' layer(base);`.

<Callout type="warning">

Preflight resets every element on every page that imports the stylesheet. On a multi-page site, scope your Tailwind CSS to a single page or accept that preflight resets shared chrome too.

</Callout>

<SeeItInAction
demos={[{ href: "https://demos.mochi.fast/todo/", title: "Tailwind Todo App", hook: "Classic todo app styled with Tailwind CSS." }]}
/>

---
title: 'Svelte Shaker optimization'
slug: svelte-shaker
description: 'Optimize and slim .svelte sources before compilation with the whole-program svelte-shaker optimizer.'
---

<script>
  import Callout from './_components/Callout.svelte';
</script>

## Svelte Shaker

[svelte-shaker](https://github.com/baseballyama/svelte-shaker) is a whole-program optimizer that slims `.svelte` **source** before the Svelte compiler runs. It folds props that never vary, removes the dead branches that folding opens up, and narrows unused CSS. The result is less generated code per component and smaller bundles.

It is opt-in and ships as a separate package, so apps that do not use it never install the engine. Add it:

```sh
bun add -d @mochi-framework/svelte-shaker
```

Then enable it with `optimize: true` on `Mochi.serve()`:

```ts
// src/index.ts
await Mochi.serve({
  port: 3000,
  optimize: true,
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});
```

<Callout type="info">

Shaking runs in **production only**. It is a whole-program pass — folding in one component can change when an unrelated component's call site changes — so it cannot be reused per file across hot reloads. In development the flag is ignored and components compile from their original source.

</Callout>

### Excluding components

If the shaker mis-transforms a component or you hit build-time errors, pass `{ exclude }` with cwd-relative globs to compile those files from their original source. Excluding is safe — the whole-app scan still covers an excluded file as a call site of the components that import it. Only its own output is left unshaken.

```ts
await Mochi.serve({
  optimize: {
    enabled: true,
    exclude: ['src/components/ThemeToggle.svelte', 'src/legacy/**'],
  },
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});
```

<Callout type="warning">

The svelte-shaker package supports Svelte 5 Runes syntax only, not Svelte 4 legacy syntax.

</Callout>

### Disabling temporarily

Pass `enabled: false` inside the options object to skip shaking while keeping the rest of your config visible:

```ts
await Mochi.serve({
  optimize: {
    enabled: false,
    exclude: ['src/components/ThemeToggle.svelte'],
  },
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});
```

This equals `optimize: false` but preserves the options so you can re-enable with one toggle.

### Size report

When shaking runs, Mochi logs a per-component before→after source-byte breakdown:

```
svelte-shaker: slimmed 15 of 86 component(s), 1 excluded
svelte-shaker: source size before → after
  src/components/Sidebar.svelte   3.21 kB → 2.74 kB  (-14.6%)
  …
  total (15 changed)              48.9 kB → 41.2 kB  (-15.7%)
```

`slimmed N of M` reports how many components the shaker changed versus the total scanned.

### Scope

Only components under `./src` are scanned. Prop folding is sound only when every call site of a component is in scope, so components imported from outside `./src` (a shared package) are left untouched. If the add-on is not installed, or shaking fails, Mochi logs a warning and falls back to the original source.

---
title: 'rsvelte compiler'
slug: rsvelte
ogTitle: 'rsvelte, the Rust Svelte compiler'
description: 'Swap the JavaScript Svelte compiler for rsvelte, a Rust port built on OXC, to cut compile time.'
---

<script>
  import Callout from './_components/Callout.svelte';
</script>

## rsvelte

[rsvelte](https://github.com/baseballyama/rsvelte) is a Rust port of the Svelte 5 compiler built on [OXC](https://oxc.rs/). Mochi can route component compilation through it instead of the JavaScript `svelte/compiler`, which speeds up cold builds and dev rebuilds.

It is opt-in. Install the adapter package:

```sh
bun add -d @mochi-framework/rsvelte
```

Then pass `svelteCompiler`:

```ts
// src/index.ts
await Mochi.serve({
  port: 3000,
  svelteCompiler: 'rsvelte',
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});
```

The default is `'svelte'`.

<Callout type="warning">

rsvelte is pre-1.0. Its authors note that APIs and behavior may change without notice.

</Callout>

### Without touching code

`MOCHI_SVELTE_COMPILER` overrides the option, which is the easy way to A/B a build:

```sh
MOCHI_SVELTE_COMPILER=rsvelte bun run build
MOCHI_SVELTE_COMPILER=svelte bun run build
```

Mochi logs which compiler it resolved (`Svelte compiler: rsvelte@0.2.8+svelte5.56.4`) once at startup. That line is also how you confirm a build ran on rsvelte, since the fallback is silent.

### Benchmark

This benchmark shows the gains on a small application (the `demos` preset from the CLI):

| phase           | svelte | rsvelte |    delta |
| --------------- | -----: | ------: | -------: |
| total           |  384ms |   289ms | **−25%** |
| `ssr-build`     |  213ms |   137ms | **−36%** |
| `client-bundle` |   40ms |    26ms | **−35%** |

(10 cold-start runs, median value)

### What runs on rsvelte

Only `compile()` and `compileModule()` run on rsvelte. **Parsing and preprocessing always stay on the official compiler**, so islands, `mochi:hydrate*`, `mochi:defer`, and user preprocessors behave identically either way.

### If it cannot load

Prebuilt binaries cover macOS arm64/x64, Linux x64/arm64 (glibc), and Windows x64 (MSVC). There is no musl build, so Alpine-based images are unsupported. When the package is missing or its binary fails to load, Mochi logs a warning and compiles with `svelte/compiler`.

### Known divergences

Production output should generally be byte-identical to `svelte/compiler`. Three differences remain:

- **`cssHash` and `warningFilter`** in `svelte.config.js` are functions and cannot cross the native boundary. They are stripped with a one-time warning. Use rsvelte's `cssHashOverride: '<hash>'` to force a fixed CSS hash.
- **Dev-only instrumentation** is not always reproduced. This affects development builds only. Production output matches.
- **`compileModule()`** emits a `vVERSION` placeholder in its header comment and different printer whitespace. Semantically identical.

---
title: 'Prerendered modules'
slug: prerender
description: 'Name a module *.prerender.ts to run it at build time and inline its exports, so the code that produced them never ships.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

## Prerendered modules

<VersionNote since="0.10.0" message="*.prerender.ts modules and moduleRef() are not in the published release yet. This page describes the upcoming API." />

A module named `*.prerender.ts` (or `.prerender.js`) runs while your app compiles. The bundler replaces it with its exported values, so the module, and everything it imports, is left out of the bundle.

This prerenders a module, not a page — Mochi has no SSG mode, and every request still renders fresh.

```ts
// src/demos/url/sources.prerender.ts
import { loadSources } from '../../components/utils.ts';
import { files } from './files.ts';

export const sources = await loadSources(files);
```

```svelte
<script>
  import { sources } from './sources.prerender.ts';
</script>
```

What the bundle holds is the finished value, not the code:

```js
const __mochi_export_0__ = [{ label: 'App.svelte', html: '<pre>…</pre>' }];
export { __mochi_export_0__ as sources };
```

`loadSources` and `files` are gone, and so is anything they imported — which is the point: a syntax highlighter, a markdown parser, or a database client used only to produce the value stops being a runtime dependency.

The suffix is the whole convention, like [`.server.ts`](/docs/server-only-imports/). Top-level `await` works; the build awaits it. Import the module with the extension (`./sources.prerender.ts`) from a `.svelte` or `.md` file, or from a `.ts` module one of them imports. Only the component bundler replaces it: imported from the server entry (`routes.ts`, an API handler), it runs as a plain module, and `moduleRef()` throws.

### What a prerendered module may export

Anything [devalue](https://github.com/sveltejs/devalue) can serialize: plain data, `Date`, `Map`, `Set`, `RegExp`, `BigInt`, `undefined`, cycles, and repeated references. Functions, class instances, and promises are a compile error naming the export:

```
src/lib/table.prerender.ts exports "rows", which cannot be inlined: Cannot stringify a function at rows[0].format.
```

Each export is serialized on its own, so an object shared between two exports is inlined twice.

### Returning components with `moduleRef()`

A component cannot be serialized. `moduleRef()` marks a module to import instead, and the build turns each marker into a real `import`:

```ts
// src/lib/docComponents.prerender.ts
import { moduleRef } from 'mochi-framework';
import type { Component } from 'svelte';
import { loadDocs } from './docs';

export const docComponents: Record<string, Component> = Object.fromEntries((await loadDocs()).map((d) => [d.slug, moduleRef<Component>(`../../docs/${d.filename}`)]));
```

becomes:

```js
import __mochi_ref_0__ from '../../docs/10-intro.md';
const __mochi_export_0__ = { intro: __mochi_ref_0__ };
export { __mochi_export_0__ as docComponents };
```

Specifiers resolve relative to the `.prerender.ts` file. This replaces generating a barrel file into your source tree before every build, and the map stays typed against the real module.

A prerendered module cannot `import` a `.svelte`, `.md`, or `.svelte.ts` file itself — it runs outside the bundler, where Svelte files have no loader. The build rejects the import and points at `moduleRef()`.

### In dev

The module is evaluated at build time in dev too, and re-evaluated on every rebuild. An edit to the module or to anything it imports rebuilds the pages that use it. A file it only _reads_ — a directory of markdown, say — is outside the import graph: adding or removing a source or data file (`.md`, `.svelte`, `.ts`, `.json`, …) rebuilds every prerendered module, while an edit to one shows up on the next rebuild of a page that imports the module.

<Callout type="warning">

Each dev evaluation gets fresh instances of the module's own imports, but the running server keeps its own. A memo that must be shared between the two, say a parsed-docs cache the prerendered module fills and a route reads, has to live on `globalThis` — use `pinGlobal(key, create)` from `mochi-framework`.

</Callout>

### What the build reports

`mochi-framework build` prints every module it inlined:

```
      Prerendered modules
  ┌ ✦ src/demos/url/sources.prerender.ts
  └ ✦ src/lib/docComponents.prerender.ts

  2 prerendered modules inlined
```

<Callout type="danger">

The value is inlined wherever the module is imported. Inside a `mochi:hydrate` island it is therefore sent to the browser, so never export a secret from a prerendered module a hydrated component imports.

</Callout>

---
title: 'Architecture'
slug: architecture
ogTitle: 'How a Mochi app fits together'
description: 'The high-level model behind a Mochi app: server-first rendering, islands, programmatic routes, and the request lifecycle.'
---

## Architecture

This page describes the model behind a Mochi app — what happens on each request and how the pieces fit together. You do not need any of it to build an app. The feature docs cover every API directly.

### Server-first rendering

Mochi renders each page to HTML on the server. A page ships zero client JavaScript by default. You opt individual components into the browser by marking them as **islands** with a `mochi:*` directive. Everything outside an island stays static HTML.

See [Selective hydration](/docs/selective-hydration/), [Client-only components](/docs/client-only/), and [Server islands](/docs/server-islands/) for the directives.

### Programmatic routes

Routes are a plain `Record<string, MochiRouteValue>` passed to `Mochi.serve({ routes })`. Each key is a URL pattern. Each value comes from `Mochi.page`, `Mochi.api`, `Mochi.ws`, `Mochi.sse`, or `Mochi.file`. There is no file-based routing.

See [Defining routes](/docs/defining-routes/).

### The request lifecycle

1. A request matches a route pattern.
2. Your `handle` middleware runs in order, and can read or rewrite the request and the response.
3. The matched route produces a response — a rendered page, a JSON payload, a stream, or a file.
4. Hydratable islands and deferred server islands (`mochi:defer`) load afterwards, each on its own request.

See [Middleware](/docs/middleware/) and [Request context](/docs/request-context/).

### The Bun runtime

Mochi runs on Bun and builds on its standard library for the bundler, the HTTP and WebSocket server, and native SQLite and PostgreSQL.

See [Why Bun?](/docs/why-bun/).

---
title: 'CLI reference'
slug: cli
description: 'The mochi-framework command-line tool: build, generate-key, and update-skill.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import VersionNote from './_components/VersionNote.svelte';
</script>

Installing `mochi-framework` puts a `mochi-framework` binary on your `PATH`. Inside a project it is available to `package.json` scripts directly. Anywhere else, run it with `bunx`:

```sh
bunx mochi-framework <command> [options]
```

```sh
bunx mochi-framework --help # list every command
```

```sh
bunx mochi-framework --version # print the installed version
```

`-h`/`--help` and `-v`/`--version` work as shorthands.

## build

Produces a production bundle by reading config straight from your entry's `Mochi.serve()` call, so the prebuilt manifest stays single-sourced with the runtime. This is the command behind your `build` script:

```json
{
  "scripts": {
    "build": "mochi-framework build"
  }
}
```

| Option                  | Default          | Description                                                                                          |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| `--entry <path>`        | `./src/index.ts` | Runtime entry whose `Mochi.serve()` call supplies `routes`, `markdown`, `optimize`, and `publicDir`. |
| `--out-dir <path>`      | `./.mochi`       | Base build output directory. `--dev` builds nest under `<out-dir>/dev`.                              |
| `--public-dir <path>`   | `./public`       | Static assets directory. Scanned, never copied.                                                      |
| `--asset-prefix <path>` | `/_mochi`        | URL prefix for framework client assets.                                                              |
| `--dev`                 | off              | Build with `development: true`.                                                                      |

The build lists every SSR entrypoint it compiled as one tree. Your routes come first, then three groups no route reaches: the [error page](/docs/error-handling/) (renders on a throw), [email templates](/docs/email/#svelte-templates) (render on a send), and [server islands](/docs/server-islands/) (render on a fetch of their own endpoint).

```
      Route                                   islands   bundle
  ┌ ● /                                             1  2.45 kB
  ├ λ /health                                       -        -
  ├ ● /orders/:id                                   1  2.45 kB
  │
  │   Error page
  ├ ⚠ $mochi/templates/DefaultError.svelte          1  3.17 kB
  │
  │   Email template
  ├ ✉ src/emails/Receipt.svelte                     -    316 B
  │
  │   Server island
  ├ ◐ /_mochi/island/Cart_3iqkh56ovhduk             1  89.6 kB
  └ ○ /_mochi/island/Stamp_dnp0teboqefy             0    235 B

  ● page with islands  ·  λ api  ·  ⚠ error page  ·  ✉ email template  ·  ◐ server island with islands  ·  ○ server island
```

After the tree, the build lists the **resources** it emitted — one row per [local image import](/docs/images/#local-image-imports), largest first:

```
      Resource                        dimensions     size
  ┌ ▣ error-page-3jm1noc19vxtj.png       1400×807   330 kB
  └ ▣ debug-bar-ycfe5vg1pwxv.png          1036×72  22.5 kB

  2 assets · 353 kB
```

Silence the list with `Mochi.serve({ build: { resources: false } })`. The `build: done` summary still reports the asset count.

The manifest stores all artifact paths relative to the out-dir, so the output is relocatable. Move or copy it and boot with `outDir` (or `manifest`) pointing at the new location. See [Production builds](/docs/production-builds/#relocatable-builds).

Static files are the exception: the build reads `--public-dir` only to reject a file that shadows a route, and copies nothing. The runtime serves that directory from disk, so it travels with your source. A `0 public file(s)` summary for an app with static assets means `--public-dir` points somewhere unexpected.

## generate-key

Generates a `MOCHI_KEY` (a base64url-encoded 32-byte secret) and writes it to `.env` in the current directory:

```sh
bunx mochi-framework generate-key
```

It creates `.env` if missing, appends `MOCHI_KEY` if absent, and prompts before overwriting an existing key.

| Option          | Description                                          |
| --------------- | ---------------------------------------------------- |
| `-f`, `--force` | Overwrite an existing `MOCHI_KEY` without prompting. |

<Callout type="info">

Set `MOCHI_KEY` for any deployment that runs more than one process or survives restarts. See [Server islands](/docs/server-islands/#encryption-key).

</Callout>

## update-skill

Fetches the latest `SKILL.md` — agent guidance for coding assistants — and writes it into your project for the given agent (default: `claude-code`):

```sh
bunx mochi-framework update-skill [agent]
```

Run it again whenever you upgrade the framework to keep the guidance in sync. See [Docs for LLMs](/docs/docs-for-llms/#agent-skill-recommended) for the full list of supported agents.

### Confirming an update

<VersionNote since="0.10.0" message="The confirmation prompt and --force flag were added in 0.10.0. Earlier versions overwrite an existing SKILL.md without asking." />

The hosted `SKILL.md` is instructions your coding agent will follow. When the file already exists and the fetched copy differs, the CLI prints a unified diff and asks before writing:

```sh
bunx mochi-framework update-skill
```

```
[mochi] Skill update fetched from https://mochi.fast/SKILL.md:

--- .claude/skills/mochi/SKILL.md
+++ https://mochi.fast/SKILL.md
@@ -12,3 +12,3 @@
 Routes live in src/routes.ts.
-Use Mochi.page() for SSR pages.
+Use Mochi.page() for SSR pages and Mochi.api() for JSON.

[mochi] Apply this update?
```

| Option          | Description                                                            |
| --------------- | ---------------------------------------------------------------------- |
| `-f`, `--force` | Accept the update without prompting. Required in non-interactive runs. |

A first write is not prompted — there is no prior content to review — and an unchanged file exits early with `is already up to date`.

<Callout type="warning">

Without `--force` and without a terminal, the command **exits 1** rather than answering the prompt for you. Scripts and CI must pass `--force` to accept whatever the endpoint serves.

</Callout>

---
title: 'Production builds'
slug: production-builds
description: 'How a Mochi build behaves in production: relocatable output and a persistent image cache.'
---

<script>
import Callout from './_components/Callout.svelte';
</script>

# Production builds

`mochi-framework build` writes a self-contained build to `.mochi/` (see the [CLI reference](/docs/cli/)). This page covers what that build gives you once it is deployed: it relocates cleanly from where you built it to where you run it, and its image cache can survive container restarts. For where to run it, see [Deployment options](/docs/deployment-options/); to containerize it, see [Building a Dockerfile](/docs/docker/).

## Relocatable builds

A manifest holds no absolute paths — artifacts are written relative to the out-dir, sources relative to the project root — so you can build in one place and run in another. Build in a CI stage, copy `.mochi/` into the final image, and point the runtime at wherever it landed:

```ts
Mochi.serve({ outDir: './.mochi' }); // default — or wherever you copied it
```

Paths resolve against the manifest's own directory, so pointing `manifest` at a relocated build works on its own:

```ts
Mochi.serve({ manifest: '/srv/app/build/manifest.json' });
```

<Callout type="warning">

Five things still anchor a prebuilt app to its project:

- **Build and serve from the same working directory.** Components are keyed relative to the project root, which both `mochi-framework build` and `Mochi.serve()` take to be the current working directory. Run both from the project root.
- **Ship your `public/` directory.** Static files are never copied into the build. The runtime scans `publicDir` (default `./public`) at startup in production exactly as in development. A deploy that ships only `.mochi/` and `src/` 404s every static file.
- **Keep the out-dir in the project tree.** The compiled SSR modules resolve `node_modules` from the out-dir's location.
- **On-demand server islands need sources.** Islands missing from the manifest are compiled at request time from source paths recorded at build. Prebuilt islands relocate fine.
- **Keep email templates in `src/emails/`.** A `Mochi.email({ component })` template is reachable only at send time, so the build walks that directory to find it. See [Svelte templates](/docs/email/#svelte-templates).

</Callout>

<Callout type="danger">

The manifest records a schema version, and the runtime loads only the exact version it writes. Booting a build made by a different `mochi-framework` version throws at startup. Always run `mochi-framework build` with the same version you serve with.

</Callout>

## Persistent image cache

Mochi's [image cache](/docs/images/) is written to disk under `cacheDir` (default `./.mochi/image-cache`). In a container that directory is recreated on every restart, so each redeploy starts with a cold cache and re-fetches and re-transforms every image. To keep the transformed bytes across restarts, point `cacheDir` at a dedicated path and mount a volume there:

```ts
Mochi.serve({
  image: { cacheDir: process.env.MOCHI_IMAGE_CACHE_DIR /* , sizes: … */ },
});
```

```yaml
services:
  site:
    image: your-app
    environment:
      MOCHI_IMAGE_CACHE_DIR: /data/image-cache
    volumes:
      - image-cache:/data/image-cache

volumes:
  image-cache:
```

A plain `docker run -v image-cache:/data/image-cache your-app` mounts the same volume. Keep the mount off `./.mochi` — its build cache is rebuilt on every boot and must not persist. If the container runs as a non-root user, pre-create the directory owned by that user in your `Dockerfile` so the mounted volume is writable.

<Callout type="info">

Keep `MOCHI_KEY` stable across restarts. Image URLs are signed with a key derived from it, so a changed key invalidates already-minted links even though the cached bytes are still on disk.

</Callout>

---
title: 'Deployment options'
slug: deployment-options
description: 'Where to deploy your Mochi app: PaaS, VPS, big cloud, and self-hosted options.'
---

<script>
import Callout from './_components/Callout.svelte';
import VersionNote from './_components/VersionNote.svelte';
</script>

# Deployment options

Mochi is a **serverful** application, so it does not run on every serverless host. That is what gives Mochi its features: built-in SQLite, in-memory cache, WebSockets, and Server-Sent Events. You can build complex, data-driven realtime apps with no extra dependency and no external cloud services.

You can host Bun and Mochi at hundreds of hosts. Some popular options are below. For how a build behaves once it is deployed — relocatable output, a persistent image cache — see [Production builds](/docs/production-builds/).

<Callout type="info">

None of the links below are affiliate links or endorsements.

</Callout>

## PaaS

Deploy code or containers. The platform manages infrastructure, scaling, and networking.

- <span title="USA">🇺🇸</span> <a href="https://railway.app" target="_blank" rel="nofollow noopener">Railway</a> — dedicated Bun and Docker support
- <span title="USA">🇺🇸</span> <a href="https://render.com" target="_blank" rel="nofollow noopener">Render</a> — Docker-based web services, Git-push deploys
- <span title="USA">🇺🇸</span> <a href="https://fly.io" target="_blank" rel="nofollow noopener">Fly.io</a> — Docker-native, global edge, scale-to-zero
- <span title="USA">🇺🇸</span> <a href="https://heroku.com" target="_blank" rel="nofollow noopener">Heroku</a> — supports Docker deployments
- <span title="France">🇫🇷</span> <a href="https://koyeb.com" target="_blank" rel="nofollow noopener">Koyeb</a> — Git or Docker, 250+ edge locations
- <span title="France">🇫🇷</span> <a href="https://www.clever.cloud" target="_blank" rel="nofollow noopener">Clever Cloud</a> — native Bun / Docker support
- <span title="USA — Zeabur Inc., Delaware">🇺🇸</span> <a href="https://zeabur.com" target="_blank" rel="nofollow noopener">Zeabur</a> — auto-detects Bun
- <span title="France">🇫🇷</span> <a href="https://www.scaleway.com/en/serverless-containers/" target="_blank" rel="nofollow noopener">Scaleway Serverless Containers</a> — deploy from any registry, billed per millisecond
- <span title="USA">🇺🇸</span> <a href="https://www.digitalocean.com/products/app-platform" target="_blank" rel="nofollow noopener">DigitalOcean App Platform</a> — Git or Docker deploy

## Traditional VPS / IaaS

You get a server, install Bun yourself, and manage the process (systemd, Docker).

- <span title="Germany">🇩🇪</span> <a href="https://hetzner.com" target="_blank" rel="nofollow noopener">Hetzner</a> — very cheap, popular with indie devs
- <span title="USA">🇺🇸</span> <a href="https://www.digitalocean.com/products/droplets" target="_blank" rel="nofollow noopener">DigitalOcean Droplets</a> — simple cloud VMs
- <span title="France">🇫🇷</span> <a href="https://ovhcloud.com" target="_blank" rel="nofollow noopener">OVHcloud</a> — dedicated servers, VPS, private cloud, with strong GDPR compliance
- <span title="France">🇫🇷</span> <a href="https://www.scaleway.com/en/virtual-instances/" target="_blank" rel="nofollow noopener">Scaleway Instances</a> — VMs alongside their serverless offering
- <span title="USA">🇺🇸</span> <a href="https://vultr.com" target="_blank" rel="nofollow noopener">Vultr</a>
- <span title="USA">🇺🇸</span> <a href="https://www.linode.com" target="_blank" rel="nofollow noopener">Akamai / Linode</a>
- <span title="USA">🇺🇸</span><span title="Israeli-founded">🇮🇱</span> <a href="https://kamatera.com" target="_blank" rel="nofollow noopener">Kamatera</a> — pay-as-you-go cloud VMs

## Big cloud

Each offers VPS, serverless, containers, and Kubernetes. Pick the model that fits.

- <span title="USA">🇺🇸</span> <a href="https://aws.amazon.com" target="_blank" rel="nofollow noopener">AWS</a> — EC2, Lambda + Web Adapter, Fargate, App Runner, ECS/EKS
- <span title="USA">🇺🇸</span> <a href="https://cloud.google.com" target="_blank" rel="nofollow noopener">Google Cloud</a> — Compute Engine, Cloud Run, GKE, Cloud Functions
- <span title="USA">🇺🇸</span> <a href="https://azure.microsoft.com" target="_blank" rel="nofollow noopener">Azure</a> — VMs, Container Apps, ACI, AKS
- <span title="USA">🇺🇸</span> <a href="https://cloud.oracle.com" target="_blank" rel="nofollow noopener">Oracle Cloud</a> — generous always-free ARM VMs
- <span title="USA">🇺🇸</span> <a href="https://www.ibm.com/cloud" target="_blank" rel="nofollow noopener">IBM Cloud</a> — VPC, Code Engine, IKS/OpenShift

## Self-hosted tools

Install these on a VPS from one of the providers above.

- <a href="https://coolify.io" target="_blank" rel="nofollow noopener">Coolify</a> — open-source, self-hosted PaaS
- <a href="https://dokku.com" target="_blank" rel="nofollow noopener">Dokku</a> — open-source mini-Heroku
- <a href="https://caprover.com" target="_blank" rel="nofollow noopener">CapRover</a> — open-source PaaS with web UI

## Hosted tools

Connect to your existing infrastructure at different cloud providers.

- <span title="United Kingdom">🇬🇧</span> <a href="https://northflank.com" target="_blank" rel="nofollow noopener">Northflank</a> — containers, jobs, and APIs, with bring-your-own-cloud
- <span title="India">🇮🇳</span> <a href="https://kuberns.com" target="_blank" rel="nofollow noopener">Kuberns</a> — Git-push deploy on AWS infra, no Dockerfile
- <span title="USA">🇺🇸</span> <a href="https://www.convox.com/" target="_blank" rel="nofollow noopener">Convox</a>

## Sub-path and static hosting

Mochi writes absolute URLs for everything it owns: `/_mochi/client/…`, `/_mochi/css/…`, the island `component-url`, and the `import` specifiers inside the client chunks. To host under a sub-path such as `https://example.com/my-app/`, bake the prefix in at build time:

```sh
mochi-framework build --asset-prefix /my-app/_mochi
```

The value lands in `manifest.json` and every emitted URL carries it. `Mochi.serve({ assetPrefix })` sets the same thing for on-demand compilation, but once a manifest exists its value wins and a differing `serve()` value only logs a warning.

<Callout type="info">

`assetPrefix` covers framework assets only. Links you write yourself (`href="/about"`) and files in `public/` are served at the paths you give them, so prefix those in your own markup.

</Callout>

The same prefix is what makes a hand-rolled static export work: copy `.mochi/svelte-client` to `<host>/my-app/_mochi/client` and `.mochi/svelte-css` to `<host>/my-app/_mochi/css`, save each prerendered page, and nothing needs rewriting.

### Rewriting URLs yourself

<VersionNote since="0.10.0" message="Before 0.10.0 a relative component-url resolved against the island loader module (/_mochi/client/), not the page." />

If you post-process the HTML into page-relative URLs instead, treat `component-url` like any other attribute: it resolves against the page, so `../_mochi/client/…` on `/my-app/writing/` loads from `/my-app/_mochi/client/`, the same place a `<link href="../_mochi/css/…">` on that page does.

## Where these companies are based

The flag next to each provider above shows where the **company** is headquartered, not where its data centers are.

<details>
<summary style="cursor: pointer">Provider headquarters &amp; sources</summary>

<!-- prettier-ignore -->
| Provider | Country | Source |
| --- | --- | --- |
| Railway | 🇺🇸 USA | <a href="https://railway.com/legal/dpa" target="_blank" rel="nofollow noopener">DPA (San Francisco, CA)</a> |
| Render | 🇺🇸 USA | <a href="https://render.com/about" target="_blank" rel="nofollow noopener">About (San Francisco, CA)</a> |
| Fly.io | 🇺🇸 USA | <a href="https://fly.io/legal/terms-of-service/" target="_blank" rel="nofollow noopener">Terms (San Francisco, CA)</a> |
| Heroku | 🇺🇸 USA | <a href="https://www.heroku.com/about" target="_blank" rel="nofollow noopener">About (San Francisco, CA)</a> |
| Koyeb | 🇫🇷 France | <a href="https://www.koyeb.com/careers" target="_blank" rel="nofollow noopener">Careers (Paris, France)</a> |
| Clever Cloud | 🇫🇷 France | <a href="https://clever.cloud/legal-notice/" target="_blank" rel="nofollow noopener">Legal notice (Nantes, France)</a> |
| Zeabur | 🇺🇸 USA | <a href="https://zeabur.com/about" target="_blank" rel="nofollow noopener">About (Zeabur Inc., Delaware)</a> |
| Scaleway | 🇫🇷 France | <a href="https://www.scaleway.com/en/legal-notice/" target="_blank" rel="nofollow noopener">Legal notice (Paris, France)</a> |
| DigitalOcean | 🇺🇸 USA | <a href="https://www.digitalocean.com/legal/terms-of-service-agreement" target="_blank" rel="nofollow noopener">Terms (USA)</a> |
| Hetzner | 🇩🇪 Germany | <a href="https://www.hetzner.com/legal/imprint" target="_blank" rel="nofollow noopener">Imprint (Gunzenhausen, Germany)</a> |
| OVHcloud | 🇫🇷 France | <a href="https://www.ovhcloud.com/en/terms-and-conditions/" target="_blank" rel="nofollow noopener">Terms (Roubaix, France)</a> |
| Vultr | 🇺🇸 USA | <a href="https://en.wikipedia.org/wiki/Vultr" target="_blank" rel="nofollow noopener">Wikipedia (West Palm Beach, FL)</a> |
| Akamai / Linode | 🇺🇸 USA | <a href="https://www.akamai.com/company" target="_blank" rel="nofollow noopener">Company (Cambridge, MA)</a> |
| Kamatera | 🇺🇸 USA · 🇮🇱 founded | <a href="https://en.wikipedia.org/wiki/Kamatera" target="_blank" rel="nofollow noopener">Wikipedia (US HQ, Israeli-founded)</a> |
| AWS | 🇺🇸 USA | <a href="https://www.aboutamazon.com/about-us" target="_blank" rel="nofollow noopener">About Amazon (Seattle, WA)</a> |
| Google Cloud | 🇺🇸 USA | <a href="https://en.wikipedia.org/wiki/Google" target="_blank" rel="nofollow noopener">Wikipedia (Mountain View, CA)</a> |
| Azure | 🇺🇸 USA | <a href="https://news.microsoft.com/facts-about-microsoft/" target="_blank" rel="nofollow noopener">Microsoft facts (Redmond, WA)</a> |
| Oracle Cloud | 🇺🇸 USA | <a href="https://en.wikipedia.org/wiki/Oracle_Corporation" target="_blank" rel="nofollow noopener">Wikipedia (Austin, TX)</a> |
| IBM Cloud | 🇺🇸 USA | <a href="https://en.wikipedia.org/wiki/IBM" target="_blank" rel="nofollow noopener">Wikipedia (Armonk, NY)</a> |
| Northflank | 🇬🇧 United Kingdom | <a href="https://northflank.com/about" target="_blank" rel="nofollow noopener">About (London, UK)</a> |
| Kuberns | 🇮🇳 India | <a href="https://www.linkedin.com/company/kuberns" target="_blank" rel="nofollow noopener">LinkedIn (Gujarat, India)</a> |
| Convox | 🇺🇸 USA | <a href="https://www.ycombinator.com/companies/convox" target="_blank" rel="nofollow noopener">Y Combinator (Atlanta, GA)</a> |

</details>

---
title: 'Building a Dockerfile'
slug: docker
description: 'A minimal production Dockerfile template for deploying Mochi apps with Bun.'
---

<script>
  import Callout from './_components/Callout.svelte';
</script>

## Building a Dockerfile

A production Mochi app is a single Bun process. This image is a one-stage build on `oven/bun:1.4-alpine`.

### Minimal Dockerfile

```dockerfile
# file: Dockerfile
FROM oven/bun:1.4-alpine
WORKDIR /app
COPY . .
RUN bun install --production
RUN bun run build
EXPOSE 3333
CMD ["bun", "run", "start"]
```

Build and run:

```sh
docker build -t my-app .
docker run --rm -p 3333:3333 my-app
```

<Callout type="info">

`bun run build` and `bun run start` must share a working directory. The template's single `WORKDIR /app` covers it. Watch a multi-stage build that copies `.mochi/` into a differently-shaped final image: keep the app at the same path in both stages, and copy `public/` across too — static files are read from that directory at runtime, never from `.mochi/`.

</Callout>

A one-route app lands at about 160 MB. About 87 MB is the Bun binary. The floor for any Bun-based image is around 105 MB.

### `.dockerignore`

Exclude artifacts and local state from the build context. They are regenerated inside the image:

```
# file: .dockerignore
node_modules
.mochi
.git
.env*
```

Do not add `public` to that list. Unlike `.mochi`, it is not regenerated inside the image — the runtime reads it from disk on every boot. If it does not make it in, the server warns at startup:

```
[mochi] publicDir "public" is missing or empty, but the build found 12 file(s) there —
every static file will 404.
```

### `--production` and devDeps

`bun install --production` omits everything under `devDependencies`. Keep `mochi-framework` and `svelte` in `dependencies`. Move `svelte-check`, `typescript`, and build-time scripts to `devDependencies`.

<Callout type="info">

`bun run start` runs your `start` script (typically `bun src/index.ts`). The port your app listens on is the one passed to `Mochi.serve({ port })`. Match it with `EXPOSE` and `-p`.

</Callout>

---
title: 'Docs for LLMs'
slug: docs-for-llms
description: 'A remote MCP server, an agent skill, and an llms.txt index with concatenated bundles for LLM contexts.'
---

<script>
  import Callout from './_components/Callout.svelte';
  import Disclosure from './_components/Disclosure.svelte';
</script>

## LLM integrations

Mochi offers several ways to give an LLM up-to-date documentation. We recommend either the [**Agent skill**](#agent-skill-recommended) or the [**MCP server**](#mcp-server-recommended). You can also use the older [llms.txt format](#llmstxt).

### Agent skill (recommended)

Mochi publishes a `SKILL.md` that tells a coding assistant to fetch the relevant docs and demos from `/llms.txt` before writing framework code. Pull the latest copy into your project with the CLI:

```sh
bunx mochi-framework update-skill [agent]
```

This fetches `https://mochi.fast/SKILL.md` and writes it into your project. Run it again whenever you upgrade the framework.

The optional `agent` argument controls where the skill is written (default: `claude-code`):

| Agent                 | Destination                       |
| --------------------- | --------------------------------- |
| `claude-code`         | `.claude/skills/mochi/SKILL.md`   |
| `opencode`            | `.opencode/skills/mochi/SKILL.md` |
| `antigravity` (`agy`) | `.agents/skills/mochi/SKILL.md`   |
| `codex`               | `.agents/skills/mochi/SKILL.md`   |

### MCP Server (recommended)

Mochi runs an official remote MCP server at `https://mochi.fast/mcp` (HTTP transport). It exposes the same docs and demos as the skill — `get_documentation_sections` to list everything and `get_section` to read specific pages. Add it to your tool of choice below.

<Disclosure title="Claude Code">

Run:

```sh
claude mcp add -t http -s project mochi https://mochi.fast/mcp
```

This adds the server at `project` scope. Pass `-s user` or `-s local` to change that.

</Disclosure>

<Disclosure title="Claude Desktop">

1. Open **Settings > Connectors**
2. Click **Add Custom Connector**
3. Name it `mochi`
4. Set the remote MCP server URL to `https://mochi.fast/mcp`
5. Click **Add**

</Disclosure>

<Disclosure title="Codex CLI">

Add to `~/.codex/config.toml`:

```toml
experimental_use_rmcp_client = true
[mcp_servers.mochi]
url = "https://mochi.fast/mcp"
```

</Disclosure>

<Disclosure title="Copilot CLI">

Run `/mcp add`, or edit `~/.copilot/mcp-config.json`:

```json
{ "mcpServers": { "mochi": { "url": "https://mochi.fast/mcp" } } }
```

</Disclosure>

<Disclosure title="Antigravity Editor">

Open the MCP store via the **"..."** dropdown at the top of the agent panel, click **Manage MCP Servers**, then **View raw config**, and add:

```json
{ "mcpServers": { "mochi": { "type": "http", "serverUrl": "https://mochi.fast/mcp" } } }
```

</Disclosure>

<Disclosure title="Antigravity CLI (previously Gemini)">

Edit `~/.gemini/config/mcp_config.json` and add:

```json
{ "mcpServers": { "mochi": { "type": "http", "serverUrl": "https://mochi.fast/mcp" } } }
```

</Disclosure>

<Disclosure title="OpenCode">

Run `opencode mcp add`, choose **Remote**, name it `mochi`, and enter `https://mochi.fast/mcp`.

</Disclosure>

<Disclosure title="VS Code">

1. Open the command palette
2. Select **MCP: Add Server...**
3. Choose **HTTP (HTTP or Server-Sent-Events)**
4. Enter `https://mochi.fast/mcp` and press Enter
5. Name it `mochi`
6. Choose Global or Workspace scope

</Disclosure>

<Disclosure title="Cursor">

Open the command palette, select **View: Open MCP Settings**, click **Add custom MCP**, and add:

```json
{ "mcpServers": { "mochi": { "url": "https://mochi.fast/mcp" } } }
```

</Disclosure>

<Disclosure title="GitHub Coding Agent">

In your repo, go to **Settings > Copilot > Coding agent**, edit the MCP configuration, then save:

```json
{ "mcpServers": { "mochi": { "type": "http", "url": "https://mochi.fast/mcp", "tools": ["*"] } } }
```

</Disclosure>

<Disclosure title="Other clients">

Refer to your client's documentation for adding a remote MCP server and use `https://mochi.fast/mcp` as the URL.

</Disclosure>

### llms.txt

[`/llms.txt`](/llms.txt) is the index: a title, a one-line summary, and a linked list of every doc (`## Docs`), demo (`## Examples`), and blog post (`## Blog`), each pointing at its own plain-text file. The concatenated bundles below are linked under `## Optional`.

#### All docs concatenated

The full set of docs, concatenated in reading order, is served at [`/llms-recommended.txt`](/llms-recommended.txt). Use it when you want the model to have the complete API in one paste.

#### Docs + demo source

[`/llms-full.txt`](/llms-full.txt) includes everything in `/llms-recommended.txt` plus the source of every demo, every blog post, and the changelog. Use it when the model needs both the API and working examples.

#### Per-document text

Each doc is reachable as plain text at `/docs/<slug>/llms.txt`, for example [`/docs/intro/llms.txt`](/docs/intro/llms.txt). The "Copy as llms.txt" button on each doc page emits just that page.

The changelog is served the same way at [`/docs/changelog/llms.txt`](/docs/changelog/llms.txt), and reads as a page at [`/docs/changelog/`](/docs/changelog/). Mochi fetches it from GitHub, so both return `503` (not `404`) when that fetch is unavailable.

#### Per-post text

Each published blog post is reachable as raw markdown at `/blog/<slug>/llms.txt`, for example [`/blog/mochi-0-8-0/llms.txt`](/blog/mochi-0-8-0/llms.txt).

#### Per-demo source

Each demo's source is reachable as plain text alongside its demo page, usually `/demos/<slug>/llms.txt`. It is the exact source `/llms-full.txt` bundles for that demo, scoped to one demo:

- [`/demos/hello-world/llms.txt`](/demos/hello-world/llms.txt)
- [`/demos/chat/llms.txt`](/demos/chat/llms.txt)

#### Machine-readable index

[`/llms.json`](/llms.json) returns a JSON index of every doc, blog post, and demo, each with its `title`, `description`, and an absolute `url` to its `llms.txt`.

```json
{
  "docs": [{ "title": "Welcome", "description": "…", "url": "https://mochi.fast/docs/intro/llms.txt" }],
  "posts": [{ "title": "Mochi 0.8.0", "description": "2026-07-21 — …", "url": "https://mochi.fast/blog/mochi-0-8-0/llms.txt" }],
  "demos": [{ "title": "Hello World", "description": "…", "url": "https://mochi.fast/demos/hello-world/llms.txt" }]
}
```

---
title: 'Demos'
slug: demos
ogTitle: 'Example apps built with Mochi'
description: 'Production-style example apps demonstrating Mochi primitives like SSR, hydration, and real-time updates.'
---

## Demos

Production-style Mochi apps you can poke at live. Each one uses the same primitives the docs cover: SSR pages, hydrated islands, WebSocket / SSE routes, and form actions.

### <a href="https://demos.mochi.fast/hn" target="_blank" rel="noopener noreferrer">Hacker News Clone</a>

A full Hacker News reader: SSR pages, hydrated islands, a real API.

### <a href="https://demos.mochi.fast/admin" target="_blank" rel="noopener noreferrer">Realtime Admin Panel</a>

A live admin dashboard with WebSocket updates and server-driven state.

### <a href="https://demos.mochi.fast/todo" target="_blank" rel="noopener noreferrer">Tailwind Todo App</a>

A classic todo app styled with Tailwind CSS.

---

Built something with Mochi? Share it in the <a href="/discord/">Mochi Discord</a>. We are happy to feature it.

---
title: 'Mochi vs SvelteKit'
slug: mochi-vs-sveltekit
description: 'A side-by-side feature comparison of Mochi and SvelteKit, filterable by performance, backend, and frontend.'
---

<script>
  import ComparisonTable from './_components/ComparisonTable.svelte';
</script>

## Mochi vs SvelteKit

Mochi and SvelteKit both render Svelte 5 on the server, and they make different bets. Mochi is SSR-first on Bun with islands-based selective hydration and a batteries-included backend (SQLite, queues, WebSockets, SSE, caching). SvelteKit is runtime-agnostic with a client-side router, broad deployment targets, and a mature ecosystem.

Use the filters below to focus on the areas you care about, or switch to **Mochi only** / **SvelteKit only** to see where each framework leads.

<ComparisonTable mochi:hydrate />

Migrating an existing app? The [Coming from SvelteKit](/docs/coming-from-sveltekit/) guide maps each SvelteKit concept to its Mochi equivalent.

# Demo Source Files

## Demo: api

### Api.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import ApiTester from './ApiTester.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage title="API Endpoints" description="You can build JSON routes with Mochi.api()." {sources}>
  <ApiTester mochi:hydrate />
</DemoPage>
```

### ApiTester.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';

  let result = $state('');
  let loading = $state(false);
  let addA = $state(2);
  let addB = $state(3);

  async function callApi(url: string, options?: RequestInit) {
    if (!isBrowser) {
      return;
    }
    loading = true;
    result = '';
    try {
      const res = await fetch(url, options);
      const json = await res.json();
      result = JSON.stringify(json, null, 2);
    } catch (e: unknown) {
      result = `Error: ${e instanceof Error ? e.message : String(e)}`;
    } finally {
      loading = false;
    }
  }

  function health() {
    callApi('/health');
  }

  function add() {
    callApi('/add', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ a: addA, b: addB }),
    });
  }
</script>

<div class="api-tester">
  <div class="endpoints">
    <button class="endpoint-btn" onclick={health}>
      <span class="method get">GET</span>
      <span class="path">/health</span>
    </button>

    <div class="add-row">
      <button class="endpoint-btn" onclick={add}>
        <span class="method post">POST</span>
        <span class="path">/add</span>
      </button>
      <div class="add-inputs">
        <input type="number" bind:value={addA} />
        <span class="plus">+</span>
        <input type="number" bind:value={addB} />
      </div>
    </div>
  </div>

  <div class="result" class:has-content={result !== ''}>
    {#if loading}
      <span class="loading">Loading...</span>
    {:else if result}
      <pre>{result}</pre>
    {:else}
      <span class="placeholder">Click an endpoint to test it</span>
    {/if}
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, error } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/api': Mochi.page('./src/demos/api/Api.svelte'),
  '/health': Mochi.api(({ method }) => Response.json({ status: 'ok', method })),
  // curl -X POST http://localhost:3333/add -H 'Content-Type: application/json' -d '{"a": 2, "b": 3}'
  '/add': Mochi.api(async ({ method, request }) => {
    if (method !== 'POST') {
      error(405, 'Method Not Allowed');
    }
    const { a, b } = (await request.json()) as { a: number; b: number };
    return Response.json({ result: a + b });
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: cache-events

### CacheEvents.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import { sources } from './sources.prerender.ts';
  import { getSlowTime } from './log';

  const { value: time, status } = await getSlowTime();
</script>

<DemoPage
  title="Cache Events"
  description="You can register a handler on mochiEvents to observe cache events. In this demo we are printing each one to the server console with a [demo:cache-events] prefix. After adding this code, refresh the page and watch your server terminal."
  {sources}
>
  <div class="card">
    <div class="row">
      <div>
        <span class="label">Cached value</span>
        <code>{time}</code>
      </div>
      <div>
        <span class="label">Status</span>
        <span class="status status-{status}">{status}</span>
      </div>
    </div>
    <p class="hint">
      Refresh under <strong>3s</strong> for a <code>fresh</code> hit. Refresh between
      <strong>3–10s</strong>
      for <code>stale</code> + a background revalidate. After <strong>10s</strong> the next refresh blocks on a fresh fetch (<code>expired</code>). Each event logs to your server
      console.
    </p>
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### log.ts
```ts
import { MochiCache, mochiEvents, logger } from 'mochi-framework';
import { delay } from '../../components/sourceUtils';

export const slowClock = new MochiCache({
  minTimeToStale: 3_000,
  maxTimeToLive: 10_000,
});

// Tags each line so it's easy to grep alongside the framework's own logger output.
// setHandler (rather than .on) means dev re-imports don't pile up duplicate subscribers.
mochiEvents.setHandler('demo:cache-events:read', 'cache:read', ({ key, status }) => {
  logger.info(`[demo:cache-events] read       ${key} → ${status}`);
});

mochiEvents.setHandler('demo:cache-events:revalidate', 'cache:revalidate', ({ key }) => {
  logger.info(`[demo:cache-events] revalidate ${key}`);
});

export async function getSlowTime() {
  return slowClock.fetchWithStatus('slow-clock', async () => {
    await delay(150);
    return new Date().toISOString();
  });
}
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/cache-events': Mochi.page('./src/demos/cache-events/CacheEvents.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: captcha

### Captcha.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import CaptchaForm from './CaptchaForm.svelte';
  import { sources } from './sources.prerender.ts';
  import type { MintedCaptcha } from 'mochi-framework';

  let { captcha }: { captcha: MintedCaptcha } = $props();
</script>

<DemoPage
  title="Captcha"
  description="A slide-to-verify captcha with no third party and no tracking. Sliding advances a hash chain and solves a proof-of-work, so a passing submit proves the page was really loaded and the work was really done."
  {sources}
>
  <p>
    <code>mintCaptcha()</code> seals a single-use token at SSR. Sliding the handle advances a hash chain one link per step, then solves a proof-of-work over the final link — so the
    challenge only exists once the slide has actually run, and never appears in the page.
    <code>verifyCaptcha()</code> re-derives it server-side.
  </p>
  <p>
    The submit button is <strong>not</strong> gated on the captcha here, so you can submit without solving it and watch the server reject you.
  </p>
  <p>
    <strong>Submit twice (replay)</strong> verifies the same token twice in one action — the first call burns the nonce, so the second is a real replay. A failure carries a
    <code>reason</code>, shown under each message: solve the captcha first and you get <code>replay</code>, which the demo answers with its own copy. Leave it unsolved and every
    probe-able failure — tampered, too fast, expired, bad proof-of-work — collapses to <code>rejected</code> behind one generic message, so a bot can't tell them apart.
  </p>

  <CaptchaForm mochi:hydrate {captcha} />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### CaptchaForm.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiSubmitFunction, MintedCaptcha } from 'mochi-framework';
  import { MochiCaptcha } from 'mochi-framework/components';

  let { captcha }: { captcha: MintedCaptcha } = $props();

  let errorMessage = $state<string | null>(null);
  let errorReason = $state<string | null>(null);
  let sentMessage = $state<string | null>(null);
  let pending = $state(false);

  const handleSubmit: MochiSubmitFunction = () => {
    pending = true;
    errorMessage = null;
    errorReason = null;
    return ({ result }) => {
      pending = false;
      if (result.type === 'success') {
        sentMessage = (result.data as { message?: string })?.message ?? 'Verified.';
      } else if (result.type === 'failure') {
        const data = result.data as { error?: string; reason?: string };
        errorMessage = data?.error ?? 'Verification failed.';
        errorReason = data?.reason ?? null;
      }
    };
  };
</script>

{#if sentMessage}
  <div class="sent">
    <p>✅ {sentMessage}</p>
    <!-- A full navigation, not a state reset: the token minted at SSR is
         single-use and this submit burned it — a reload mints a fresh one. -->
    <a href="/demos/captcha/">Reload for a fresh challenge</a>
  </div>
{:else}
  <form method="POST" action="?/submit" {@attach enhance(handleSubmit)}>
    <label>
      <span>Your name</span>
      <input name="name" autocomplete="name" />
    </label>

    <MochiCaptcha {...captcha} emoji="🍡" label="Slide the mochi to the right" />

    {#if errorMessage}
      <p class="error" role="alert">
        {errorMessage}
        {#if errorReason}
          <span class="reason">reason: {errorReason}</span>
        {/if}
      </p>
    {/if}

    <div class="actions">
      <!-- Deliberately not gated on the captcha, so you can submit unsolved and
           watch the server reject it. Real forms should disable until verified. -->
      <button type="submit" disabled={pending}>{pending ? 'Checking…' : 'Submit'}</button>
      <button type="submit" formaction="?/replay" class="secondary" disabled={pending}>Submit twice (replay)</button>
    </div>
  </form>
{/if}

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, fail, success, mintCaptcha, verifyCaptcha } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/captcha': Mochi.page('./src/demos/captcha/Captcha.svelte', {
    serverProps: () => ({ captcha: mintCaptcha() }),
    actions: {
      submit: async ({ formData }) => {
        const captcha = await verifyCaptcha(formData);
        if (!captcha.ok) {
          return fail(400, { error: captcha.error, reason: captcha.reason });
        }
        const name = String(formData.get('name') ?? '').trim();
        return success({ message: `Verified — nice to meet you, ${name || 'stranger'}.` });
      },

      // Verifies the token twice: the first call burns the nonce, so the second is a genuine replay.
      // An unsolved token instead fails both calls and lands on 'rejected'.
      replay: async ({ formData }) => {
        await verifyCaptcha(formData);
        const captcha = await verifyCaptcha(formData);
        if (!captcha.ok) {
          return fail(400, {
            error: captcha.reason === 'replay' ? 'Our own copy: that token is spent — reload for a fresh challenge.' : captcha.error,
            reason: captcha.reason,
          });
        }
        return success({ message: 'Unexpected — the nonce survived a double verify.' });
      },
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: captcha-styling

### CaptchaStyling.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import StylingDemo from './StylingDemo.svelte';
  import { sources } from './sources.prerender.ts';
  import { themes, defaultsSample, rule, markup } from './themes.ts';
  import { highlightCode } from '../../lib/highlight.server';
  import type { MintedCaptcha } from 'mochi-framework';

  let { captchas }: { captchas: MintedCaptcha[] } = $props();

  // Highlighted here rather than in the island: the highlighter is server-only.
  const css = {
    defaults: await highlightCode(defaultsSample, 'css'),
    themed: await highlightCode(rule('.themed', themes.themed.css), 'css'),
    candy: await highlightCode(rule('.candy', themes.candy.css), 'css'),
    terminal: await highlightCode(rule('.terminal', themes.terminal.css), 'css'),
  };

  const svelte = {
    defaults: await highlightCode('<MochiCaptcha {...captcha} />', 'svelte'),
    themed: await highlightCode(markup(themes.themed), 'svelte'),
    candy: await highlightCode(markup(themes.candy), 'svelte'),
    terminal: await highlightCode(markup(themes.terminal), 'svelte'),
  };
</script>

<DemoPage
  title="Captcha Styling"
  description="The same MochiCaptcha four times over. Every colour is a CSS custom property with a built-in fallback, so styling it is CSS — no props, no theme object, no wrapper component."
  {sources}
>
  <p>
    Set the <code>--mochi-captcha-*</code> vars on any ancestor and they inherit down into the widget. The <code>emoji</code> and <code>label</code> props cover the rest. Each one below
    is live — slide any of them.
  </p>

  <StylingDemo mochi:hydrate {captchas} {css} {svelte} />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### StylingDemo.svelte
```svelte
<script lang="ts">
  import { MochiCaptcha } from 'mochi-framework/components';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import { themes } from './themes.ts';
  import type { ThemeName } from './themes.ts';
  import type { MintedCaptcha } from 'mochi-framework';

  type Snippets = Record<ThemeName | 'defaults', string>;

  let { captchas, css, svelte }: { captchas: MintedCaptcha[]; css: Snippets; svelte: Snippets } = $props();
</script>

<div class="variants">
  <section>
    <h4>Defaults</h4>
    <p>No CSS at all. The widget ships light-mode defaults in each <code>var()</code> fallback, so it looks finished out of the box.</p>
    <MochiCaptcha {...captchas[0]} />
    <CodeSnippet html={svelte.defaults} />
    <CodeSnippet html={css.defaults} />
  </section>

  <section>
    <h4>Themed</h4>
    <p>Map the vars onto your palette. These point at this site's tokens, so this one follows the light/dark toggle.</p>
    <div style={themes.themed.css}>
      <MochiCaptcha
        {...captchas[1]}
        emoji={themes.themed.emoji}
        label={themes.themed.label}
        verifyingLabel={themes.themed.verifyingLabel}
        verifiedLabel={themes.themed.verifiedLabel}
      />
    </div>
    <CodeSnippet html={svelte.themed} />
    <CodeSnippet html={css.themed} />
  </section>

  <section>
    <h4>Candy</h4>
    <p>The vars are just colours — hand them anything, including gradients.</p>
    <div style={themes.candy.css}>
      <MochiCaptcha
        {...captchas[2]}
        emoji={themes.candy.emoji}
        label={themes.candy.label}
        verifyingLabel={themes.candy.verifyingLabel}
        verifiedLabel={themes.candy.verifiedLabel}
      />
    </div>
    <CodeSnippet html={svelte.candy} />
    <CodeSnippet html={css.candy} />
  </section>

  <section>
    <h4>Terminal</h4>
    <p>Square off the corners with <code>--mochi-captcha-radius</code> for a different silhouette.</p>
    <div style={themes.terminal.css}>
      <MochiCaptcha
        {...captchas[3]}
        emoji={themes.terminal.emoji}
        label={themes.terminal.label}
        verifyingLabel={themes.terminal.verifyingLabel}
        verifiedLabel={themes.terminal.verifiedLabel}
      />
    </div>
    <CodeSnippet html={svelte.terminal} />
    <CodeSnippet html={css.terminal} />
  </section>
</div>

<style>
  /* Styles omitted */
</style>
```

### themes.ts
```ts
// Each theme's emoji/labels/declarations feed both the live widget and the code
// samples rendered beside it, so what the page shows can't drift from what it does.
export const themes = {
  themed: {
    emoji: '🍡',
    label: 'Slide the mochi to the right',
    verifyingLabel: 'Steaming…',
    verifiedLabel: 'Freshly made — thanks!',
    css: `--mochi-captcha-accent: var(--accent);
--mochi-captcha-accent-soft: var(--accent-soft);
--mochi-captcha-accent-soft-text: var(--accent-soft-text);
--mochi-captcha-border: var(--border);
--mochi-captcha-track-bg: var(--surface-muted);
--mochi-captcha-handle-bg: var(--surface);
--mochi-captcha-hint-text: var(--text-subtle);`,
  },

  candy: {
    emoji: '🍭',
    label: 'Slide for a tasty treat',
    verifyingLabel: 'Unwrapping…',
    verifiedLabel: 'Enjoy your sweet!',
    css: `--mochi-captcha-accent: #d6336c;
--mochi-captcha-accent-soft: linear-gradient(90deg, #ffd6e7, #ffa8cd);
--mochi-captcha-accent-soft-text: #a61e4d;
--mochi-captcha-border: #ffa8cd;
--mochi-captcha-track-bg: #fff0f6;
--mochi-captcha-handle-bg: #fff;
--mochi-captcha-hint-text: #c2255c;`,
  },

  terminal: {
    emoji: '▶',
    label: 'SLIDE TO PROVE HUMANITY',
    verifyingLabel: 'VERIFYING…',
    verifiedLabel: 'ACCESS GRANTED',
    css: `--mochi-captcha-radius: 0;
--mochi-captcha-accent: #33ff77;
--mochi-captcha-accent-soft: #04301a;
--mochi-captcha-accent-soft-text: #33ff77;
--mochi-captcha-border: #33ff77;
--mochi-captcha-track-bg: #04150c;
--mochi-captcha-handle-bg: #04301a;
--mochi-captcha-hint-text: #2bbd5a;
font-family: var(--font-mono);`,
  },
} as const;

export type ThemeName = keyof typeof themes;

// The values baked into each var()'s fallback in MochiCaptcha.svelte. Shown as
// the "Defaults" sample; deliberately not applied to anything.
export const defaultsSample = `/* Each var's built-in fallback. */
:root {
  --mochi-captcha-accent: #4a7c59;
  --mochi-captcha-accent-soft: #e0ebe1;
  --mochi-captcha-accent-soft-text: #2f5b3f;
  --mochi-captcha-border: #e8e4d8;
  --mochi-captcha-track-bg: #faf8f1;
  --mochi-captcha-handle-bg: #fffdf8;
  --mochi-captcha-handle-text: var(--mochi-captcha-accent);
  --mochi-captcha-hint-text: #6e756d;
  --mochi-captcha-radius: 999px;
}`;

export const rule = (selector: string, declarations: string): string => `${selector} {\n${declarations.replace(/^/gm, '  ')}\n}`;

export const markup = (theme: (typeof themes)[ThemeName]): string =>
  `<MochiCaptcha\n  {...captcha}\n  emoji="${theme.emoji}"\n  label="${theme.label}"\n  verifyingLabel="${theme.verifyingLabel}"\n  verifiedLabel="${theme.verifiedLabel}"\n/>`;
```

### routes.ts
```ts
import { Mochi, mintCaptcha } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/captcha-styling': Mochi.page('./src/demos/captcha-styling/CaptchaStyling.svelte', {
    // One token per variant so each can be solved independently.
    serverProps: () => ({ captchas: [mintCaptcha(), mintCaptcha(), mintCaptcha(), mintCaptcha()] }),
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: charts

### Charts.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import StaticTrafficChart from './StaticTrafficChart.svelte';
  import TrafficChart from './TrafficChart.svelte';
  import HtmlBars from './HtmlBars.svelte';
  import RuntimeDonut from './RuntimeDonut.svelte';
  import Callout from '../../../../docs/_components/Callout.svelte';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';

  const install = await highlightCode('bun add layerchart', 'bash');

  const themingCss = await highlightCode(
    `/* shell.html — supply the definitions Bun's light-dark() downlevel expects */
:root {
  color-scheme: light dark;
  --buncss-light: initial;
  --buncss-dark: ;
}

/* System preference, unless the user explicitly picked light */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme='light']) {
    --buncss-light: ;
    --buncss-dark: initial;
  }
}

/* Explicit dark choice, regardless of system preference */
:root[data-theme='dark'] {
  --buncss-light: ;
  --buncss-dark: initial;
}`,
    'css',
  );

  const staticExample = await highlightCode(
    `<script lang="ts">
  import { Chart, Svg, Axis, Bars } from 'layerchart/svg';
  import { traffic } from './data.ts';
${'<'}/script>

<Chart ssr data={traffic} x="month" y="requests" c="requests" cRange={['var(--chart-1)']} width={600} height={220}>
  <Svg viewBox="0 0 600 220">
    <Axis placement="left" grid rule ticks={4} />
    <Axis placement="bottom" rule />
    <Bars fill="var(--chart-1)" />
  </Svg>
</Chart>`,
    'svelte',
  );

  const interactiveExample = await highlightCode(
    `<script lang="ts">
  import { AreaChart } from 'layerchart/svg';
  import { traffic, seriesColors } from './data.ts';

  const series = [
    { key: 'requests', label: 'Requests', color: seriesColors[0] },
    { key: 'cached', label: 'Cache hits', color: seriesColors[2] },
  ];
${'<'}/script>

<!-- No ssr, no width: hydration measures the container. -->
<AreaChart data={traffic} x="month" {series} height={260} props={{ tooltip: { root: { portal: false } } }} />`,
    'svelte',
  );

  const htmlExample = await highlightCode(
    `<script lang="ts">
  import { BarChart } from 'layerchart/html';
  import { traffic, seriesColors } from './data.ts';

  const series = [
    { key: 'requests', label: 'Requests', color: seriesColors[0] },
    { key: 'cached', label: 'Cache hits', color: seriesColors[2] },
  ];
${'<'}/script>

<!-- HTML renderer: real DOM boxes; the BarChart shortcut is fine since ssr is off. -->
<BarChart data={traffic} x="month" {series} seriesLayout="group" legend height={260} />`,
    'svelte',
  );

  const serverComponentExample = await highlightCode(
    `<script lang="ts">
  import { ServerChart } from 'layerchart/server';
  import { Axis, Grid, Spline } from 'layerchart';
  let { data, width, height, capture, onCapture } = $props();
${'<'}/script>

<ServerChart {capture} {onCapture} {width} {height} {data} x="month" y="requests" yDomain={[0, null]}>
  <Grid y />
  <Axis placement="left" rule ticks={4} format={(v) => v / 1000 + 'k'} />
  <Axis placement="bottom" rule />
  <Spline stroke="rgb(59,130,246)" strokeWidth={2} />
</ServerChart>`,
    'svelte',
  );

  const serverRouteExample = await highlightCode(
    `// routes.ts — renders the chart to an image buffer on request
'/demos/charts/traffic.png': Mochi.api(async ({ url }) => {
  // See implementation of serverChart in the tabs below
  const { renderTrafficChart } = await import('./serverChart');
  const format = url.searchParams.get('format') === 'jpeg' ? 'jpeg' : 'png';
  const image = await renderTrafficChart({ width: 640, height: 240, format });
  return new Response(image, { headers: { 'Content-Type': 'image/' + format } });
}),`,
    'typescript',
  );
</script>

<DemoPage
  title="Charts with LayerChart"
  description="LayerChart renders to plain HTML or SVG, so it server-renders like any other Svelte component. The first chart ships no JavaScript; the rest are islands."
  {sources}
>
  <p>
    Minimal setup: install it, import from <code>layerchart</code>, and Mochi bundles it into whichever island imports it. Full component reference at
    <a href="https://www.layerchart.com" target="_blank" rel="noopener noreferrer">layerchart.com</a>.
  </p>
  <CodeSnippet html={install} />

  <h2>Pure SSR — SVG</h2>
  <p>
    LayerChart can render to pure SVG or HTML by omitting Mochi's hydrate directives. That needs two opt-ins: <code>ssr</code> (LayerChart skips server rendering otherwise) and
    explicit
    <code>width</code>/<code>height</code> to set the dimensions, since nothing resizes the container client side.
  </p>
  <p>
    SVG is recommended for pure SSR graphs: the <code>&lt;Svg&gt;</code> gets a matching <code>viewBox</code>, so the fixed 600&times;220 geometry rescales to any column width with
    CSS alone.
  </p>
  <p>
    It's composed from <code>&lt;Chart&gt;</code> primitives rather than the <code>&lt;BarChart&gt;</code> shortcut: that shortcut's <code>marks</code> snippet shadows its own
    <code>marks</code> prop, which the Svelte server compiler turns into unbounded recursion once <code>ssr</code> forces a server render.
  </p>
  <Callout type="warning">
    <strong>LayerChart's SSR pitfall.</strong> LayerChart doesn't officially support SSR for its SVG and HTML renderers, and its all-in-one chart components (<code
      >&lt;BarChart&gt;</code
    >,
    <code>&lt;AreaChart&gt;</code>, <code>&lt;LineChart&gt;</code>, <code>&lt;PieChart&gt;</code>, <code>&lt;ScatterChart&gt;</code>, <code>&lt;ArcChart&gt;</code>) can't be
    server-rendered — turning on <code>ssr</code> crashes the whole page. For a no-JavaScript chart, build it from the smaller pieces like this one does.
  </Callout>
  <CodeSnippet html={staticExample} />
  <StaticTrafficChart />

  <h2>Theming — light/dark</h2>
  <p>
    LayerChart ships its tooltip, axis, and other default styles pre-coloured with CSS <code>light-dark()</code> so they read correctly in both modes out of the box — you lean on
    that any time you use a LayerChart component without hand-styling its colours, the tooltip most of all. Bun downlevels <code>light-dark()</code> to a
    <code>--buncss-light</code>/<code>--buncss-dark</code> toggle but only defines the pair beside a <code>color-scheme</code> rule in the same stylesheet, which LayerChart doesn't
    ship — so define it once on <code>:root</code> in your shell:
  </p>
  <CodeSnippet html={themingCss} />

  <h2>Interactive — SVG</h2>
  <p>
    The same library imported from <code>layerchart/svg</code>, hydrated via <code>mochi:hydrate</code> — hover the plot for the crosshair and tooltip. Leaving <code>ssr</code> off
    ships an empty frame; omitting
    <code>width</code> (which would override the measured container) is what makes it responsive. The tooltip sets <code>portal: false</code> because LayerChart otherwise portals
    it to <code>&lt;body&gt;</code>, escaping the themed frame and rendering unstyled.
  </p>
  <Callout type="info">
    <strong>Helpers are fine when hydrating.</strong> With <code>ssr</code> off, the marks never render on the server, so the all-in-one components like
    <code>&lt;AreaChart&gt;</code>
    work here — no need to compose from primitives the way the pure-SSR chart does.
  </Callout>
  <CodeSnippet html={interactiveExample} />
  <TrafficChart mochi:hydrate />

  <h2>Interactive — HTML</h2>
  <p>
    Imported from <code>layerchart/html</code>, so the bars are real DOM boxes instead of SVG. This one uses the <code>&lt;BarChart&gt;</code> shortcut — fine here because
    <code>ssr</code> is off, so the marks never render on the server. Hydration measures the container, so it reflows fluidly with no <code>viewBox</code> trick needed.
  </p>
  <CodeSnippet html={htmlExample} />
  <HtmlBars mochi:hydrate />

  <h2>Donut — SVG</h2>
  <p>
    A <code>PieChart</code> with a negative <code>innerRadius</code> and <code>cRange</code> colours; click a legend swatch to toggle a slice. Client-only is usually the better fit for
    a chart: since LayerChart draws nothing server-side anyway, hydrating would server-render an empty container and reconcile it, whereas a client-only island skips the server pass
    entirely and lets you ship real fallback markup — the skeleton below, wiped the moment the component mounts.
  </p>
  <RuntimeDonut mochi:clientOnly>
    <div class="skeleton">Loading chart…</div>
  </RuntimeDonut>

  <h2>Server-rendered image chart</h2>
  <p>
    You can server-render charts as an image (JPEG/PNG) using <code>layerchart/server</code>. This is possible today in Mochi but requires a bit of glue code code, see
    <code>serverChart.ts</code> in the tab view at the bottom of the demo for an example. The general recommendation if you want to go SSR-only is to use the SVG approach in the first
    example.
  </p>
  <CodeSnippet html={serverComponentExample} />
  <CodeSnippet html={serverRouteExample} />
  <img class="server-png" src="/demos/charts/traffic.png" alt="Server-rendered traffic chart, January through December" width="640" height="240" />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### ChartFrame.svelte
```svelte
<script lang="ts">
  import type { Snippet } from 'svelte';
  let { height = 240, children }: { height?: number; children: Snippet } = $props();
</script>

<div class="chart-frame" style="--frame-h: {height}px">
  {@render children()}
</div>

<style>
  /* Styles omitted */
</style>
```

### StaticTrafficChart.svelte
```svelte
<script lang="ts">
  import { Chart, Svg, Axis, Bars } from 'layerchart/svg';
  import ChartFrame from './ChartFrame.svelte';
  import { traffic } from './data.ts';

  // No hydration, so nothing measures the container on the client: `ssr` opts LayerChart into
  // server rendering, and width/height bake the coordinate space at render time. The chart stays
  // responsive anyway because the <Svg> carries a matching `viewBox` — the fixed 600x220 geometry
  // then scales to the column via CSS (see the .lc-root-container override below).
  //
  // Composed from <Chart> primitives rather than the <BarChart> shortcut: that shortcut's `marks`
  // snippet shadows its own `marks` prop, which the Svelte server compiler turns into unbounded
  // recursion once `ssr` forces a server render. See layerchart-repro/ for a standalone repro.
  const WIDTH = 600;
  const HEIGHT = 220;
</script>

<div class="ssr-chart" style="--ar: {WIDTH} / {HEIGHT}">
  <ChartFrame height={HEIGHT}>
    <Chart
      ssr
      data={traffic}
      x="month"
      y="requests"
      yDomain={[0, null]}
      yNice
      c="requests"
      cRange={['var(--chart-1)']}
      bandPadding={0.2}
      width={WIDTH}
      height={HEIGHT}
      padding={{ top: 8, right: 8, bottom: 24, left: 44 }}
    >
      <Svg viewBox="0 0 {WIDTH} {HEIGHT}">
        <Axis placement="left" grid rule ticks={4} format={(v: number) => `${v / 1000}k`} />
        <Axis placement="bottom" rule />
        <Bars fill="var(--chart-1)" fillOpacity={0.85} />
      </Svg>
    </Chart>
  </ChartFrame>
</div>

<style>
  /* Styles omitted */
</style>
```

### TrafficChart.svelte
```svelte
<script lang="ts">
  import { AreaChart } from 'layerchart/svg';
  import ChartFrame from './ChartFrame.svelte';
  import { traffic, seriesColors } from './data.ts';

  // Height only — `width` is a hard override of the measured container width, so leaving it
  // off is what lets the hydrated chart track the column.
  const HEIGHT = 260;

  const series = [
    { key: 'requests', label: 'Requests', color: seriesColors[0] },
    { key: 'cached', label: 'Cache hits', color: seriesColors[2] },
  ];
</script>

<ChartFrame height={HEIGHT}>
  <AreaChart
    data={traffic}
    x="month"
    {series}
    height={HEIGHT}
    padding={{ top: 8, right: 8, bottom: 24, left: 44 }}
    props={{
      xAxis: { rule: true },
      yAxis: { ticks: 4, format: (v: number) => `${v / 1000}k` },
      // LayerChart portals the tooltip to <body> by default, which would move it out of the
      // frame that maps its theme custom properties and leave it unstyled.
      tooltip: { root: { portal: false } },
    }}
  />
</ChartFrame>
```

### HtmlBars.svelte
```svelte
<script lang="ts">
  import { BarChart } from 'layerchart/html';
  import ChartFrame from './ChartFrame.svelte';
  import { traffic, seriesColors } from './data.ts';

  const HEIGHT = 260;

  const series = [
    { key: 'requests', label: 'Requests', color: seriesColors[0] },
    { key: 'cached', label: 'Cache hits', color: seriesColors[2] },
  ];
</script>

<ChartFrame height={HEIGHT}>
  <!-- Hydrated, so the client measures the container: no `width`, no `ssr` — the frame arrives
       empty and the chart draws (and reflows) once the island boots. Leaving `ssr` off also keeps
       the <BarChart> shortcut usable here; forcing a server render would hit its `marks` recursion. -->
  <BarChart
    data={traffic}
    x="month"
    {series}
    seriesLayout="group"
    legend
    height={HEIGHT}
    padding={{ top: 8, right: 8, bottom: 56, left: 44 }}
    props={{
      xAxis: { rule: true },
      yAxis: { ticks: 4, format: (v: number) => `${v / 1000}k` },
      tooltip: { root: { portal: false } },
    }}
  />
</ChartFrame>
```

### RuntimeDonut.svelte
```svelte
<script lang="ts">
  import type { ClientOnlyProps } from 'mochi-framework';
  import { PieChart } from 'layerchart/svg';
  import ChartFrame from './ChartFrame.svelte';
  import { runtimes, seriesColors } from './data.ts';

  let { height = 300 }: ClientOnlyProps<{ height?: number }> = $props();
</script>

<ChartFrame {height}>
  <PieChart
    data={runtimes}
    key="stage"
    value="ms"
    cRange={seriesColors}
    innerRadius={-36}
    cornerRadius={2}
    padAngle={0.02}
    legend
    {height}
    padding={{ bottom: 40 }}
    props={{ tooltip: { root: { portal: false } } }}
  />
</ChartFrame>
```

### ServerTrafficChart.svelte
```svelte
<script lang="ts">
  import { ServerChart } from 'layerchart/server';
  import type { CaptureTarget } from 'layerchart/server';
  import { Axis, Grid, Spline } from 'layerchart';
  import type { TrafficPoint } from './data.ts';

  let {
    data,
    width,
    height,
    capture,
    onCapture,
  }: {
    data: TrafficPoint[];
    width: number;
    height: number;
    capture?: CaptureTarget;
    onCapture?: (data: CaptureTarget) => void;
  } = $props();
</script>

<ServerChart {capture} {onCapture} {width} {height} {data} x="month" y="requests" yDomain={[0, null]} padding={{ top: 16, right: 20, bottom: 28, left: 48 }}>
  <Grid y stroke="rgba(148,163,184,0.3)" />
  <Axis placement="left" rule ticks={4} format={(v: number) => `${v / 1000}k`} stroke="rgba(100,116,139,0.4)" fill="rgba(71,85,105,0.9)" />
  <Axis placement="bottom" rule stroke="rgba(100,116,139,0.4)" fill="rgba(71,85,105,0.9)" />
  <Spline stroke="rgb(59,130,246)" strokeWidth={2} />
</ServerChart>
```

### serverChart.ts
```ts
import path from 'node:path';
import { compile, compileModule } from 'svelte/compiler';
import { createCanvas, Path2D, GlobalFonts } from '@napi-rs/canvas';
import { fontFile } from '../../lib/fontFile.ts';
import { traffic } from './data.ts';

// renderChart draws the marks with Path2D and expects it on globalThis.
if (typeof globalThis.Path2D === 'undefined') {
  (globalThis as { Path2D?: unknown }).Path2D = Path2D;
}

// layerchart's canvas renderer falls back to the `sans-serif` family, which Alpine (the
// production base image) can't resolve because it ships no fonts — so axis labels rasterize
// blank. Register the site's UI font under that family name so text renders everywhere.
GlobalFonts.registerFromPath(fontFile('@fontsource/public-sans', 'public-sans-latin-400-normal.woff2'), 'sans-serif');

export type ChartFormat = 'png' | 'jpeg';

type ChartBundle = {
  renderChart: (
    component: unknown,
    options: { width: number; height: number; format: ChartFormat; background: string; props: object; createCanvas: (w: number, h: number) => unknown },
  ) => Uint8Array;
  ServerTrafficChart: unknown;
};

// Mochi can't import `.svelte` in server code, so compile the ServerChart tree to a JS bundle here.
// `.svelte.js` rune modules (layerchart's chart state) need compileModule, not compile.
const svelteServerPlugin: import('bun').BunPlugin = {
  name: 'svelte-server',
  setup(build) {
    build.onLoad({ filter: /\.svelte$/ }, async ({ path: f }) => ({
      contents: compile(await Bun.file(f).text(), { generate: 'server', filename: f }).js.code,
      loader: 'js',
    }));
    build.onLoad({ filter: /\.svelte\.[jt]s$/ }, async ({ path: f }) => ({
      contents: compileModule(await Bun.file(f).text(), { generate: 'server', filename: f }).js.code,
      loader: 'js',
    }));
  },
};

let bundle: Promise<ChartBundle> | undefined;
async function loadBundle(): Promise<ChartBundle> {
  const result = await Bun.build({
    entrypoints: [path.join(import.meta.dir, 'serverChartBundle.ts')],
    plugins: [svelteServerPlugin],
    target: 'bun',
    conditions: ['svelte'],
    external: ['svelte', 'svelte/*'],
    outdir: path.join(import.meta.dir, '..', '..', '..', '.mochi', 'serverchart'),
    throw: true,
  });
  return import(result.outputs[0]!.path) as Promise<ChartBundle>;
}

export async function renderTrafficChart(opts: { width: number; height: number; format: ChartFormat }): Promise<Uint8Array<ArrayBuffer>> {
  const { renderChart, ServerTrafficChart } = await (bundle ??= loadBundle());
  const bytes = renderChart(ServerTrafficChart, {
    width: opts.width,
    height: opts.height,
    format: opts.format,
    background: 'white',
    props: { data: traffic },
    createCanvas,
  });
  // Copy into an ArrayBuffer-backed view so it satisfies Response's BodyInit.
  return new Uint8Array(bytes);
}
```

### serverChartBundle.ts
```ts
// Bun.build entrypoint only — never imported at runtime. Bundling renderChart together with the
// chart means the compiled output carries no `.svelte` import, which Mochi's server runtime can't
// load. serverChart.ts compiles this with a Svelte plugin and imports the pure-JS result.
export { renderChart } from 'layerchart/server';
export { default as ServerTrafficChart } from './ServerTrafficChart.svelte';
```

### data.ts
```ts
export type TrafficPoint = { month: string; requests: number; cached: number };

export const traffic: TrafficPoint[] = [
  { month: 'Jan', requests: 1240, cached: 820 },
  { month: 'Feb', requests: 1380, cached: 940 },
  { month: 'Mar', requests: 1610, cached: 1170 },
  { month: 'Apr', requests: 1520, cached: 1090 },
  { month: 'May', requests: 1840, cached: 1390 },
  { month: 'Jun', requests: 2110, cached: 1660 },
  { month: 'Jul', requests: 2340, cached: 1880 },
  { month: 'Aug', requests: 2280, cached: 1810 },
  { month: 'Sep', requests: 2560, cached: 2040 },
  { month: 'Oct', requests: 2890, cached: 2350 },
  { month: 'Nov', requests: 3120, cached: 2580 },
  { month: 'Dec', requests: 3410, cached: 2870 },
];

export type RuntimeSlice = { stage: string; ms: number };

export const runtimes: RuntimeSlice[] = [
  { stage: 'Server render', ms: 42 },
  { stage: 'Island hydration', ms: 27 },
  { stage: 'Asset transfer', ms: 19 },
  { stage: 'Idle', ms: 12 },
];

// Passed straight into LayerChart's `color` / `cRange` props, which write them into `fill`
// and `stroke` attributes. Custom properties inherit into SVG, so they resolve against
// `.chart-frame` and follow the site's theme toggle without any JavaScript.
export const seriesColors = ['var(--chart-1)', 'var(--chart-2)', 'var(--chart-3)', 'var(--chart-4)'];
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

const MIN_SIZE = 64;
const MAX_SIZE = 2000;

// The canvas is allocated in one shot from these, so an unclamped `?width=40000` is a memory-exhaustion lever.
function clampSize(raw: string | null, fallback: number): number {
  // `?width=` yields '' and `Number('')` is 0, which would clamp to MIN_SIZE instead of the default.
  const n = raw?.trim() ? Number(raw) : fallback;
  if (!Number.isFinite(n)) {
    return fallback;
  }
  return Math.min(MAX_SIZE, Math.max(MIN_SIZE, Math.trunc(n)));
}

export const routes: Record<string, MochiRouteValue> = {
  '/demos/charts': Mochi.page('./src/demos/charts/Charts.svelte'),
  '/demos/charts/traffic.png': Mochi.api(
    async ({ url }) => {
      const { renderTrafficChart } = await import('./serverChart');
      const width = clampSize(url.searchParams.get('width'), 640);
      const height = clampSize(url.searchParams.get('height'), 240);
      const format = url.searchParams.get('format') === 'jpeg' ? 'jpeg' : 'png';
      const image = await renderTrafficChart({ width, height, format });
      return new Response(image, {
        headers: { 'Content-Type': `image/${format}`, 'Cache-Control': 'public, max-age=3600' },
      });
    },
    { rateLimit: { limit: 60, window: '1m' } },
  ),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: chat

### Chat.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import ChatWidget from './ChatWidget.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Real-time Chat"
  description="An example of building a simple in-memory chat using a hydrated island and the built-in WebSocket support in Bun. The server stores a bounded message history and replays it to new connections; ws.publish() broadcasts each message to all clients. Messages over 4 KB are rejected, frames over 8 KB are dropped by Bun before they are buffered, and a per-client window closes anyone sending more than 20 messages per 10 seconds. Open this page in two tabs to see them sync in real time."
  {sources}
>
  <ChatWidget mochi:hydrate />
</DemoPage>
```

### ChatWidget.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';

  const GREETING = { text: 'Hello friend! How are you?', fromMe: false };

  let messages: Array<{ text: string; fromMe: boolean }> = $state([GREETING]);
  let input = $state('');
  let messagesEl: HTMLDivElement | undefined = $state();

  $effect(() => {
    void messages.length;
    messagesEl?.scrollTo({ top: messagesEl.scrollHeight, behavior: 'smooth' });
  });

  let chatSocket: WebSocket | null = null;
  let disconnected = $state<string | null>(null);
  let reconnecting = $state(false);
  const locked = $derived(!!disconnected || reconnecting);
  let userId = '';

  // The server states its reason for these; anything else is a transport drop worth retrying.
  const POLICY_CLOSE_CODES = new Set([1003, 1008, 1009]);
  const MAX_RECONNECT_ATTEMPTS = 5;
  // A connection that outlived the longest backoff was healthy, so its drop starts a fresh attempt budget.
  const STABLE_CONNECTION_MS = 500 * 2 ** MAX_RECONNECT_ATTEMPTS;

  if (isBrowser) {
    userId =
      localStorage.getItem('chatUserId') ??
      (() => {
        const id = crypto.randomUUID();
        localStorage.setItem('chatUserId', id);
        return id;
      })();

    const host = window.location.host;
    const wsProtocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
    let attempts = 0;
    let openedAt = 0;

    const connect = () => {
      chatSocket = new WebSocket(`${wsProtocol}//${host}/ws/chat`);

      chatSocket.addEventListener('open', () => {
        openedAt = Date.now();
        reconnecting = false;
        disconnected = null;
        // The server replays its whole history on every connection, so a reconnect would otherwise double every message.
        messages = [GREETING];
      });

      chatSocket.addEventListener('message', (e) => {
        const msg = JSON.parse(e.data);
        messages = [...messages, { text: msg.text, fromMe: msg.userId === userId }];
      });

      // send() on a closed socket is a silent no-op, so without this the box would keep accepting text into the void.
      chatSocket.addEventListener('close', (e) => {
        if (POLICY_CLOSE_CODES.has(e.code)) {
          disconnected = e.reason || 'Connection closed';
          return;
        }
        if (openedAt && Date.now() - openedAt > STABLE_CONNECTION_MS) {
          attempts = 0;
        }
        openedAt = 0;
        if (attempts >= MAX_RECONNECT_ATTEMPTS) {
          disconnected = 'Connection closed';
          return;
        }
        reconnecting = true;
        setTimeout(connect, 500 * 2 ** attempts++);
      });
    };

    connect();
  }

  function send() {
    const text = input.trim();
    if (!text || !chatSocket || chatSocket.readyState !== WebSocket.OPEN) {
      return;
    }
    chatSocket.send(JSON.stringify({ userId, text }));
    input = '';
  }

  function onKeydown(e: KeyboardEvent) {
    if (e.key === 'Enter') {
      send();
    }
  }
</script>

<div class="chat-container">
  <div class="chat-header">
    <span class="chat-title">Chat</span>
  </div>

  <div class="chat-messages" bind:this={messagesEl}>
    {#each messages as msg, i (i)}
      <div class="message" class:mine={msg.fromMe}>
        <span class="bubble">{msg.text}</span>
      </div>
    {/each}
    {#if messages.length === 0}
      <div class="empty">Send a message to get started</div>
    {/if}
  </div>

  {#if disconnected}
    <p class="disconnected" role="alert">{disconnected} — reload the page to reconnect.</p>
  {:else if reconnecting}
    <p class="disconnected" role="status">Reconnecting…</p>
  {/if}

  <div class="chat-input">
    <input type="text" bind:value={input} onkeydown={onKeydown} placeholder="Type a message..." disabled={locked} />
    <button onclick={send} disabled={locked}>Send</button>
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, getRequestContext, rateLimitMemoryStore } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const CHAT_MAX_MESSAGE_BYTES = 4 * 1024;
// Bun drops a frame past this before `message` runs, so it has to sit above the app limit or the handler's 1009 close is unreachable.
export const CHAT_WS_MAX_PAYLOAD_BYTES = 2 * CHAT_MAX_MESSAGE_BYTES;
export const CHAT_MAX_HISTORY_MESSAGES = 100;
export const CHAT_MAX_HISTORY_BYTES = 64 * 1024;
export const CHAT_RATE_LIMIT = 20;
export const CHAT_RATE_WINDOW_MS = 10_000;

interface HistoryEntry {
  text: string;
  bytes: number;
}

interface ChatSocketData {
  rateKey: string;
}

// `getClientAddress()` only returns null when Bun has no peer address at all (behind a proxy it still yields the proxy's IP,
// so separating visitors there is `proxy.addressHeader`'s job); a per-socket key keeps that edge case from sharing one bucket.
export function rateKeyFor(address: string | null): string {
  return address ? `ip:${address}` : `socket:${crypto.randomUUID()}`;
}

export function createChatRoutes(): Record<string, MochiRouteValue> {
  const history: HistoryEntry[] = [];
  let historyBytes = 0;
  // Keyed by client address so the allowance survives a reconnect, which would otherwise hand out a fresh budget and replay the history buffer again.
  const limiter = rateLimitMemoryStore();

  return {
    '/demos/chat': Mochi.page('./src/demos/chat/Chat.svelte'),
    '/ws/chat': (() => {
      const TOPIC = 'chat';
      return Mochi.ws<ChatSocketData>({
        upgrade() {
          return { rateKey: rateKeyFor(getRequestContext().getClientAddress()) };
        },
        open(ws) {
          ws.subscribe(TOPIC);
          for (const entry of history) {
            ws.send(entry.text);
          }
        },
        async message(ws, message) {
          const bytes = typeof message === 'string' ? Buffer.byteLength(message, 'utf8') : message.byteLength;
          if (bytes > CHAT_MAX_MESSAGE_BYTES) {
            ws.close(1009, 'Message too large');
            return;
          }
          if (typeof message !== 'string') {
            ws.close(1003, 'Chat frames must be text');
            return;
          }
          const { count } = await limiter.hit(ws.data.user.rateKey, CHAT_RATE_WINDOW_MS, CHAT_RATE_LIMIT);
          if (count > CHAT_RATE_LIMIT) {
            ws.close(1008, 'Message rate exceeded');
            return;
          }

          history.push({ text: message, bytes });
          historyBytes += bytes;
          while (history.length > CHAT_MAX_HISTORY_MESSAGES || historyBytes > CHAT_MAX_HISTORY_BYTES) {
            historyBytes -= history.shift()!.bytes;
          }
          ws.publish(TOPIC, message);
          ws.send(message);
        },
        close(ws) {
          ws.unsubscribe(TOPIC);
        },
      });
    })(),
  };
}

export const routes = createChatRoutes();
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: client-only

### ClientOnly.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import BrowserCanvas from './BrowserCanvas.svelte';
  import MountClock from './MountClock.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Client-only Islands"
  description="Components marked mochi:clientOnly are never server-rendered — SSR ships only an empty wrapper (plus optional fallback content), and the component mounts in the browser. The canvas below reads window.devicePixelRatio and getComputedStyle at the top of its script, which would crash any SSR render."
  {sources}
>
  <BrowserCanvas mochi:clientOnly waves={4}>
    <div class="skeleton">Mounting in the browser…</div>
  </BrowserCanvas>
  <p class="facts">
    The animation runs on <code>requestAnimationFrame</code> with a live fps counter, scaled to <code>window.devicePixelRatio</code> — browser APIs read at the top of the component's
    script. This paragraph, by contrast, sits outside the island — it ships with the SSR HTML and doesn't move when the component mounts.
  </p>

  <div class="spacer">
    <p>Scroll down — the island below is marked <code>mochi:clientOnly:visible</code>, so it stays a fallback until it reaches the viewport, then mounts in the browser.</p>
  </div>

  <h2 class="visible-heading">Lazy client-only with <code>mochi:clientOnly:visible</code></h2>
  <MountClock mochi:clientOnly:visible={{ rootMargin: '0px' }} label="Lazy island">
    <div class="skeleton">Mounts when scrolled into view…</div>
  </MountClock>
  <p class="facts">
    Same browser-only mount as above, but deferred: an <code>IntersectionObserver</code> holds off the <code>mount()</code> until the placeholder enters the viewport, and the component's
    bundle and CSS load only then. Open the console to see it mount as you scroll.
  </p>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### BrowserCanvas.svelte
```svelte
<script lang="ts">
  import type { ClientOnlyProps } from 'mochi-framework';

  let { waves = 3 }: ClientOnlyProps<{ waves?: number }> = $props();

  // These top-level browser reads would crash an SSR render — safe here
  // because mochi:clientOnly components never run on the server.
  const dpr = window.devicePixelRatio;
  const theme = getComputedStyle(document.documentElement);
  const accent = theme.getPropertyValue('--accent').trim();
  const textMuted = theme.getPropertyValue('--text-muted').trim();

  let canvas: HTMLCanvasElement;

  $effect(() => {
    const ctx = canvas.getContext('2d');
    if (!ctx) {
      return;
    }

    let width = 0;
    let height = 0;
    const resize = () => {
      width = canvas.clientWidth;
      height = canvas.clientHeight;
      canvas.width = width * dpr;
      canvas.height = height * dpr;
      // Re-setting canvas.width wipes the context state, so re-apply the
      // dpr scale absolutely instead of accumulating ctx.scale() calls.
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
    };
    resize();
    const observer = new ResizeObserver(resize);
    observer.observe(canvas);

    let frame: number;
    let frames = 0;
    let lastFpsUpdate = 0;
    let fps = 0;
    const draw = (t: number) => {
      frames++;
      if (t - lastFpsUpdate >= 500) {
        fps = Math.round((frames * 1000) / (t - lastFpsUpdate));
        frames = 0;
        lastFpsUpdate = t;
      }
      ctx.clearRect(0, 0, width, height);
      for (let line = 0; line < waves; line++) {
        ctx.beginPath();
        for (let x = 0; x <= width; x += 4) {
          const y = height / 2 + Math.sin(x / 60 + t / (600 + line * 200)) * (height / 4) * Math.sin(t / 2000 + line);
          if (x === 0) {
            ctx.moveTo(x, y);
          } else {
            ctx.lineTo(x, y);
          }
        }
        ctx.strokeStyle = accent;
        ctx.globalAlpha = 1 - (line / waves) * 0.75;
        ctx.lineWidth = 2;
        ctx.stroke();
      }
      ctx.globalAlpha = 1;
      ctx.fillStyle = textMuted;
      ctx.font = '12px ui-monospace, monospace';
      if (fps > 0) {
        ctx.fillText(`${fps} fps`, 12, height - 12);
      }
      frame = requestAnimationFrame(draw);
    };
    frame = requestAnimationFrame(draw);
    return () => {
      cancelAnimationFrame(frame);
      observer.disconnect();
    };
  });
</script>

<canvas bind:this={canvas}></canvas>

<style>
  /* Styles omitted */
</style>
```

### MountClock.svelte
```svelte
<script lang="ts">
  import { onMount } from 'svelte';
  import type { ClientOnlyProps } from 'mochi-framework';

  let { label = 'Lazy island' }: ClientOnlyProps<{ label?: string }> = $props();

  // `performance.now()` at the top level captures the moment this component
  // mounts in the browser — a client-only concept with no SSR equivalent.
  const mountedAt = performance.now();
  let seconds = $state(0);

  onMount(() => {
    const id = setInterval(() => {
      seconds = Math.floor((performance.now() - mountedAt) / 1000);
    }, 1000);
    return () => clearInterval(id);
  });
</script>

<div class="probe">
  <span class="dot"></span>
  {label}: mounted on scroll <strong>{seconds}s</strong> ago.
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/client-only': Mochi.page('./src/demos/client-only/ClientOnly.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: cookie-vary-test

### CookieVaryTest.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Cookie Vary Test"
  description="This page sets Vary: Cookie on every response. The page cache sees this header and emits a s-vary-cookie skip — it refuses to cache the response unless the matching rule explicitly opts in via varyOnCookies."
  {sources}
>
  <p>Check the response headers: <code>Vary: Cookie</code> is set by the route handle.</p>
</DemoPage>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { Handle, MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/cookie-vary-test': Mochi.page('./src/demos/cookie-vary-test/CookieVaryTest.svelte'),
};

export const handle: Handle = async ({ event, resolve }) => {
  const response = await resolve(event);
  if (event.url.pathname === '/cookie-vary-test' || event.url.pathname === '/cookie-vary-test/') {
    response.headers.set('Vary', 'Cookie');
  }
  return response;
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: cookies

### Cookies.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CookieDemo from './CookieDemo.svelte';
  import { sources } from './sources.prerender.ts';

  const cuteNames = ['mochi_fan', 'bun_bun', 'pixel_panda', 'tiny_tanuki', 'cloud_kitten', 'waffle_fox', 'cocoa_bear', 'starry_otter', 'maple_duck', 'peach_pup'];
  const randomCuteName = cuteNames[Math.floor(Math.random() * cuteNames.length)];
</script>

<DemoPage
  title="Cookies"
  description="You can read incoming cookies during SSR and write them back via Set-Cookie through the Mochi cookies API exposed on both server and client."
  {sources}
>
  <CookieDemo defaultUsername={randomCuteName} mochi:hydrate />
</DemoPage>
```

### CookieDemo.svelte
```svelte
<script lang="ts">
  import { isServer, isBrowser, cookies } from 'mochi-framework';

  let { defaultUsername = 'mochi_fan' } = $props();

  // svelte-ignore state_referenced_locally
  let username = $state(cookies.get('mochi_username') || defaultUsername);
  let theme = $state(cookies.get('mochi_theme') || 'auto');
  let message = $state('');

  // SSR snapshot — what the server saw in the request headers
  const ssrUsername = cookies.get('mochi_username') ?? '(not set)';
  const ssrTheme = cookies.get('mochi_theme') ?? '(not set)';

  async function setCookieViaApi() {
    if (!isBrowser) {
      return;
    }
    const res = await fetch('/api/cookie', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ username, theme }),
    });
    const json = (await res.json()) as { ok: boolean };
    if (json.ok) {
      message = 'Cookies set via API! Reload to see SSR pick them up.';
    }
  }

  function setCookieOnClient() {
    if (!isBrowser) {
      return;
    }
    cookies.set('mochi_username', username, { expires: 7, path: '/' });
    cookies.set('mochi_theme', theme, { expires: 7, path: '/' });
    message = 'Cookies set on client! Reload to see SSR pick them up.';
  }

  function clearCookies() {
    if (!isBrowser) {
      return;
    }
    cookies.delete('mochi_username', { path: '/' });
    cookies.delete('mochi_theme', { path: '/' });
    username = '';
    theme = 'light';
    message = 'Cookies cleared! Reload to confirm.';
  }
</script>

<div class="cookie-demo">
  <div class="section">
    <h3>SSR Read <span class="env">(server)</span></h3>
    <p class="desc">These values were read from the Cookie header during SSR:</p>
    <div class="values">
      <div class="val"><span class="label">mochi_username</span> <code>{ssrUsername}</code></div>
      <div class="val"><span class="label">mochi_theme</span> <code>{ssrTheme}</code></div>
    </div>
  </div>

  <div class="section">
    <h3>Client Read <span class="env">(browser)</span></h3>
    <p class="desc">
      Live values from <code>cookies.get()</code> on the {isServer ? 'server' : 'client'}:
    </p>
    <div class="values">
      <div class="val">
        <span class="label">mochi_username</span>
        <code>{cookies.get('mochi_username') ?? '(not set)'}</code>
      </div>
      <div class="val">
        <span class="label">mochi_theme</span>
        <code>{cookies.get('mochi_theme') ?? '(not set)'}</code>
      </div>
    </div>
  </div>

  <div class="section">
    <h3>Set Cookies</h3>
    <div class="form">
      <label>
        <span>Username</span>
        <input type="text" bind:value={username} placeholder="e.g. mochi_fan" />
      </label>
      <label>
        <span>Theme</span>
        <select bind:value={theme}>
          <option value="" disabled>(not set)</option>
          <option value="light">Light</option>
          <option value="dark">Dark</option>
          <option value="auto">Auto</option>
        </select>
      </label>
    </div>
    <div class="actions">
      <button onclick={setCookieOnClient}>Set via Client</button>
      <button onclick={setCookieViaApi}>Set via API</button>
      <button class="danger" onclick={clearCookies}>Clear</button>
    </div>
    {#if message}
      <p class="message">{message}</p>
    {/if}
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, error, getRequestContext } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/cookies': Mochi.page('./src/demos/cookies/Cookies.svelte'),
  '/api/cookie': Mochi.api(async ({ method, request }) => {
    if (method !== 'POST') {
      error(405, 'Method Not Allowed');
    }
    const { username, theme } = (await request.json()) as {
      username: string;
      theme: string;
    };
    const { cookies } = getRequestContext();
    cookies.set('mochi_username', username, { path: '/', maxAge: 604800 });
    cookies.set('mochi_theme', theme, { path: '/', maxAge: 604800 });
    return Response.json({ ok: true });
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: cron

### Cron.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CronLog from './CronLog.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Scheduled jobs with cron"
  description="A Mochi.cron() job appends one entry to an in-memory log every minute. The browser subscribes over a WebSocket and shows each new row the moment it lands."
  {sources}
>
  <CronLog mochi:hydrate />
</DemoPage>
```

### CronLog.svelte
```svelte
<script lang="ts">
  import type { CronLogEntry, CronLogMessage } from './types';

  let status = $state('connecting');
  let entries = $state<CronLogEntry[]>([]);

  const skeletons = $derived([...Array(Math.max(0, 5 - entries.length)).keys()]);

  $effect(() => {
    const host = window.location.host;
    const wsProtocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
    const ws = new WebSocket(`${wsProtocol}//${host}/ws/cron-log`);

    ws.addEventListener('open', () => (status = 'connected'));
    ws.addEventListener('close', () => (status = 'disconnected'));
    ws.addEventListener('message', (e) => {
      const msg = JSON.parse(e.data) as CronLogMessage;
      if (msg.type === 'snapshot') {
        entries = msg.entries;
      } else {
        entries = [msg.entry, ...entries].slice(0, 100);
      }
    });

    const close = () => ws.close();
    window.addEventListener('pagehide', close);

    return () => {
      window.removeEventListener('pagehide', close);
      close();
    };
  });

  const fmtTime = (ms: number): string => new Date(ms).toLocaleTimeString('en-GB');
</script>

<div class="cron">
  <div class="bar">
    <span class="status" class:connected={status === 'connected'}>{status}</span>
  </div>

  <ul class="log">
    {#each entries as entry (entry.seq)}
      <li class="row">
        <span class="seq">#{entry.seq}</span>
        <span class="time">{fmtTime(entry.at)}</span>
        <span class="label">demo-activity-log ran</span>
      </li>
    {/each}
    {#each skeletons as i (i)}
      <li class="row skeleton" aria-hidden="true">
        <span class="sk sk-seq"></span>
        <span class="sk sk-time"></span>
        <span class="sk sk-label"></span>
      </li>
    {/each}
  </ul>
</div>

<style>
  /* Styles omitted */
</style>
```

### cron.server.ts
```ts
import { Mochi } from 'mochi-framework';
import type { CronLogEntry } from './types';

const MAX_ENTRIES = 100;

// The cron appends one entry per minute forever; trimming to the last MAX_ENTRIES keeps the in-memory log bounded.
const log: CronLogEntry[] = [];
let seq = 0;

type WsClient = { send: (data: string) => void };
const clients = new Set<WsClient>();

function broadcast(message: string): void {
  for (const ws of clients) {
    ws.send(message);
  }
}

// The site rides the default `cronStorage: 'memory'`, so the demo writes no file into the working dir; set
// `Mochi.serve({ cronStorage })` to make the schedule durable across restarts and multiple nodes.
export const activityLog = Mochi.cron('demo-activity-log', '* * * * *', (run) => {
  const entry: CronLogEntry = { seq: ++seq, at: Date.now(), scheduledTime: run.scheduledTime };
  log.push(entry);
  if (log.length > MAX_ENTRIES) {
    log.splice(0, log.length - MAX_ENTRIES);
  }
  broadcast(JSON.stringify({ type: 'entry', entry }));
});

export function addClient(ws: WsClient): void {
  clients.add(ws);
  ws.send(JSON.stringify({ type: 'snapshot', entries: [...log].reverse() }));
}

export function removeClient(ws: WsClient): void {
  clients.delete(ws);
}
```

### types.ts
```ts
// Components must import types from here, NOT from cron.server.ts: a type import from a side-effectful server
// module still drags that module into the SSR component bundle, re-registering its cron job a second time.

export interface CronLogEntry {
  seq: number;
  /** Epoch ms at which the cron handler ran. */
  at: number;
  /** Epoch ms at which the scheduler claimed the firing, which is earlier than `at` by the queue pickup delay. */
  scheduledTime: number;
}

export type CronLogMessage = { type: 'snapshot'; entries: CronLogEntry[] } | { type: 'entry'; entry: CronLogEntry };
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue, MochiCronConfig } from 'mochi-framework';
import { activityLog, addClient, removeClient } from './cron.server';

// Mounted in the site's Mochi.serve({ cron }) call — see src/routes.ts.
export const cron: MochiCronConfig[] = [activityLog];

export const routes: Record<string, MochiRouteValue> = {
  '/demos/cron': Mochi.page('./src/demos/cron/Cron.svelte'),
  '/ws/cron-log': Mochi.ws({
    open(ws) {
      addClient(ws);
    },
    message() {},
    close(ws) {
      removeClient(ws);
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes, cron } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
  cron,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: custom-transitions

### PageOne.svelte
```svelte
<script lang="ts">
  import { ViewTransitions } from 'mochi-framework/components';
  import DemoPage from '../../components/DemoPage.svelte';
  import SpinCard from './SpinCard.svelte';
  import { description, sources } from './shared';
</script>

<DemoPage title="Custom Transitions" {description} {sources}>
  <ViewTransitions
    custom={{
      out: 'to { transform: rotate(540deg) scale(0); opacity: 0 }',
      in: 'from { transform: rotate(-540deg) scale(0); opacity: 0 }',
    }}
    easing="cubic-bezier(0.68, -0.55, 0.27, 1.55)"
    duration={600}
    regions="card"
  />
  <SpinCard page={1} />
</DemoPage>
```

### PageTwo.svelte
```svelte
<script lang="ts">
  import { ViewTransitions } from 'mochi-framework/components';
  import DemoPage from '../../components/DemoPage.svelte';
  import SpinCard from './SpinCard.svelte';
  import { description, sources } from './shared';
</script>

<DemoPage title="Custom Transitions" {description} {sources}>
  <ViewTransitions
    custom={{
      out: 'to { transform: rotate(540deg) scale(0); opacity: 0 }',
      in: 'from { transform: rotate(-540deg) scale(0); opacity: 0 }',
    }}
    easing="cubic-bezier(0.68, -0.55, 0.27, 1.55)"
    duration={600}
    regions="card"
  />
  <SpinCard page={2} />
</DemoPage>
```

### SpinCard.svelte
```svelte
<script lang="ts">
  import ViewTransitionFirefoxNote from '../../components/ViewTransitionFirefoxNote.svelte';

  let { page }: { page: 1 | 2 } = $props();

  const other = $derived(page === 1 ? '/demos/custom-transitions/two' : '/demos/custom-transitions');
</script>

<div class="card" class:two={page === 2}>
  <span class="num">Page {page}</span>
  <p>Each navigation is a full page load — the card does a custom <code>spin</code> while the rest of the page swaps instantly.</p>
  <a class="next" href={other}>Go to page {page === 1 ? 2 : 1} →</a>
</div>

<ViewTransitionFirefoxNote />

<style>
  /* Styles omitted */
</style>
```

### shared.ts
```ts
// Demo plumbing shared by PageOne/PageTwo so the description and source-tab
// list aren't duplicated. Hidden from the displayed demo source by
// stripDemoWrapper, like the sources.prerender.ts import it replaces.

export const description =
  'Bring your own animation to <ViewTransitions /> with custom={{ in, out }} — raw @keyframes bodies that drive the page you leave and the page you land on. Here the card does a funky 3D spin on every navigation.';

export { sources } from './sources.prerender.ts';
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/custom-transitions': Mochi.page('./src/demos/custom-transitions/PageOne.svelte'),
  '/demos/custom-transitions/two': Mochi.page('./src/demos/custom-transitions/PageTwo.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: data-loading

### DataLoading.svelte
```svelte
<script>
  import { params } from 'mochi-framework';
  import { pokemonCache } from '../../lib/cache';
  import DemoPage from '../../components/DemoPage.svelte';
  import PokemonHeader from './PokemonHeader.svelte';
  import PokemonMeta from './PokemonMeta.svelte';
  import PokemonStats from './PokemonStats.svelte';
  import PokemonSelector from './PokemonSelector.svelte';
  import { sources } from './sources.prerender.ts';

  const id = (params.id ?? 'pikachu').toLowerCase();

  const [pokemon, options] = await Promise.all([
    pokemonCache.fetch(`pokemon:${id}`, async () => {
      const res = await fetch(`https://pokeapi.co/api/v2/pokemon/${encodeURIComponent(id)}`);
      return res.ok ? await res.json() : null;
    }),
    pokemonCache.fetch('pokemon:list:151', async () => {
      const res = await fetch('https://pokeapi.co/api/v2/pokemon?limit=151');
      const data = await res.json();
      return data.results;
    }),
  ]);

  const types = pokemon?.types.map((t) => t.type.name) ?? [];
  const abilities = pokemon?.abilities.map((a) => a.ability.name) ?? [];
  const stats = pokemon?.stats.map((s) => ({ name: s.stat.name, value: s.base_stat })) ?? [];
</script>

<DemoPage
  title="Data Loading"
  description="You can fetch server-side data inside any non-hydrated Svelte component by loading it at the top level — no special API needed. Wrap the fetch in MochiCache for fast, cached access across requests."
  {sources}
>
  <PokemonSelector mochi:hydrate current={id} {options} />

  {#if pokemon}
    <div class="card">
      <PokemonHeader id={pokemon.id} name={pokemon.name} sprite={pokemon.sprites.front_default} />
      <div class="divider"></div>
      <PokemonMeta {types} height={pokemon.height} weight={pokemon.weight} baseXp={pokemon.base_experience} {abilities} />
      <div class="divider"></div>
      <PokemonStats mochi:hydrate {stats} />
    </div>
  {:else}
    <p class="not-found">No Pokémon found for "{id}".</p>
  {/if}
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### PokemonSelector.svelte
```svelte
<script lang="ts">
  let { current, options }: { current: string; options: { name: string }[] } = $props();

  function onChange(event: Event) {
    (event.currentTarget as HTMLSelectElement).form?.requestSubmit();
  }

  function capitalize(name: string) {
    return name.charAt(0).toUpperCase() + name.slice(1);
  }
</script>

<form class="selector" method="POST">
  <label for="pokemon-select">Pick a Pokémon:</label>
  <select id="pokemon-select" name="pokemon" value={current} onchange={onChange}>
    {#each options as option (option.name)}
      <option value={option.name} selected={option.name === current}>
        {capitalize(option.name)}
      </option>
    {/each}
  </select>
  <noscript>
    <button type="submit">Go</button>
  </noscript>
</form>

<style>
  /* Styles omitted */
</style>
```

### PokemonHeader.svelte
```svelte
<script>
  import { isServer, isDev } from 'mochi-framework';

  const { id, name, sprite } = $props();
</script>

<svelte:head>
  <script type="module">
    console.log('Hello world! from the client!');
  </script>
</svelte:head>

<p class="env-badge">{isServer ? 'SERVER' : 'BROWSER'} | {isDev ? 'DEV' : 'PROD'}</p>

<div class="header">
  <img src={sprite} alt={name} class="sprite" />
  <div class="title">
    <span class="id">#{String(id).padStart(3, '0')}</span>
    <h1>{name}</h1>
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### PokemonMeta.svelte
```svelte
<script>
  const { types, height, weight, baseXp, abilities } = $props();

  const typeColors = {
    normal: '#A8A878',
    fire: '#F08030',
    water: '#6890F0',
    electric: '#F8D030',
    grass: '#78C850',
    ice: '#98D8D8',
    fighting: '#C03028',
    poison: '#A040A0',
    ground: '#E0C068',
    flying: '#A890F0',
    psychic: '#F85888',
    bug: '#A8B820',
    rock: '#B8A038',
    ghost: '#705898',
    dragon: '#7038F8',
    dark: '#705848',
    steel: '#B8B8D0',
    fairy: '#EE99AC',
  };

  function textOn(hex) {
    const n = parseInt(hex.slice(1), 16);
    const r = (n >> 16) & 255,
      g = (n >> 8) & 255,
      b = n & 255;
    return (r * 299 + g * 587 + b * 114) / 1000 >= 140 ? '#1f2a24' : '#fff';
  }
</script>

<div class="meta">
  <div class="types">
    {#each types as t (t)}
      <span class="type-badge" style="background:{typeColors[t] ?? '#888'};color:{textOn(typeColors[t] ?? '#888')}">{t}</span>
    {/each}
  </div>

  <div class="stats-grid">
    <div class="stat-item">
      <span class="label">Height</span>
      <span class="value">{(height / 10).toFixed(1)} m</span>
    </div>
    <div class="stat-item">
      <span class="label">Weight</span>
      <span class="value">{(weight / 10).toFixed(1)} kg</span>
    </div>
    <div class="stat-item">
      <span class="label">Base XP</span>
      <span class="value">{baseXp}</span>
    </div>
    <div class="stat-item">
      <span class="label">Abilities</span>
      <span class="value abilities">{abilities.join(', ')}</span>
    </div>
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### PokemonStats.svelte
```svelte
<script>
  import { isBrowser, logger } from 'mochi-framework';
  if (isBrowser) {
    logger.info('PokemonStats is hydrating!');
  }
  const { stats } = $props();
  const maxStat = 255;
  let filter = $state('');
  const filtered = $derived(filter.trim() === '' ? stats : stats.filter((s) => s.name.toLowerCase().includes(filter.toLowerCase())));
</script>

<div class="stats">
  <h2>Base Stats</h2>
  <input class="filter" type="search" placeholder="Filter stats…" bind:value={filter} />
  {#each filtered as s (s.name)}
    <div class="row">
      <span class="name">{s.name}</span>
      <span class="num">{s.value}</span>
      <div class="bar-track">
        <div class="bar" style="width:{Math.round((s.value / maxStat) * 100)}%"></div>
      </div>
    </div>
  {/each}
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, fail, redirect } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/data-loading': (req: Request) => Response.redirect(new URL('/demos/data-loading/pikachu', req.url), 302),
  '/demos/data-loading/:id': Mochi.page('./src/demos/data-loading/DataLoading.svelte', {
    actions: {
      default: async ({ formData }) => {
        const pokemon = String(formData.get('pokemon') ?? '')
          .trim()
          .toLowerCase();
        if (!pokemon) {
          return fail(400, { error: 'Pokemon required' });
        }
        return redirect(303, `/demos/data-loading/${encodeURIComponent(pokemon)}`);
      },
    },
  }),
};
```

### cache.ts
```ts
import { MochiCache } from 'mochi-framework';

export const pokemonCache = new MochiCache({
  minTimeToStale: 14_400_000,
  maxTimeToLive: 86_400_000,
});
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: defer-invalidation

### DeferInvalidation.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import Controls from './Controls.svelte';
  import ServerClock from './ServerClock.svelte';
  import LiveCounter from './LiveCounter.svelte';
  import FlakyPanel from './FlakyPanel.svelte';
  import ErrorModes from './ErrorModes.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Invalidate mochi:defer islands"
  description="Give a mochi:defer island a name, then call reloadDeferredIsland(name) from the browser to re-fetch its server HTML. Island 1 is also hydrated, so it unmounts and re-hydrates on every reload — its counter resets. Islands 2 and 3 share the name 2-and-3, so they reload together. Everything below the buttons — the disabled states, counts and timestamps — is read from deferReloadState(name)."
  {sources}
>
  <Controls mochi:hydrate />

  <LiveCounter mochi:defer={{ name: '1' }} mochi:hydrate label="1">
    <div class="island-loading tall">Loading<span class="dots"></span></div>
  </LiveCounter>

  <div class="spacer"></div>

  <div class="pair">
    <ServerClock mochi:defer={{ name: '2-and-3' }} label="2">
      <div class="island-loading">Loading<span class="dots"></span></div>
    </ServerClock>
    <ServerClock mochi:defer={{ name: '2-and-3' }} label="3">
      <div class="island-loading">Loading<span class="dots"></span></div>
    </ServerClock>
  </div>

  <h2>Error modes</h2>
  <p class="lede">
    A reload can fail in two different places, and they are not the same thing: the render can throw while the island is being built on the server, or the request for that HTML can
    fail. Only the second counts as a failed reload.
  </p>

  <ErrorModes mochi:hydrate />

  <FlakyPanel mochi:defer={{ name: 'flaky' }} label="4">
    <div class="island-loading">Loading<span class="dots"></span></div>
  </FlakyPanel>

  <div class="spacer"></div>

  <ServerClock mochi:defer={{ name: 'offline', retries: 0 }} label="5">
    <div class="island-loading">Loading<span class="dots"></span></div>
  </ServerClock>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### Controls.svelte
```svelte
<script>
  import { onMount } from 'svelte';
  import { reloadDeferredIsland, reloadDeferredIslandAll, deferReloadState } from 'mochi-framework';

  const one = deferReloadState('1');
  const pair = deferReloadState('2-and-3');

  // Starts false so SSR and the first hydration render agree: no island has registered yet, so
  // `reloading` reads false and the buttons would otherwise ship enabled.
  let ready = $state(false);
  onMount(() => {
    ready = true;
  });

  // Includes the error-mode islands below, since "reload all" reaches every named island.
  const anyReloading = $derived([one, pair, deferReloadState('flaky'), deferReloadState('offline')].some((s) => s.reloading));

  const stamp = (s) => (s.lastReloaded ? `${s.lastReloadOk ? 'ok' : 'failed'} at ${s.lastReloaded.toLocaleTimeString()}` : 'not yet reloaded');
</script>

<div class="controls">
  <div class="buttons">
    <button disabled={!ready || one.reloading} onclick={() => reloadDeferredIsland('1')}>Reload 1</button>
    <button disabled={!ready || pair.reloading} onclick={() => reloadDeferredIsland('2-and-3')}>Reload 2 + 3</button>
    <button disabled={!ready || anyReloading} onclick={() => reloadDeferredIslandAll()}>Reload all</button>
  </div>

  <dl class="state">
    <div>
      <dt>Island 1</dt>
      <dd>{one.count} reloads · {stamp(one)}</dd>
    </div>
    <div>
      <dt>Islands 2 + 3</dt>
      <dd>{pair.count} reloads · {stamp(pair)}</dd>
    </div>
  </dl>
</div>

<style>
  /* Styles omitted */
</style>
```

### ServerClock.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';

  let { label = '' } = $props();

  await (isServer ? delay(700, 1300) : Promise.resolve());

  const renderedAt = new Date().toLocaleTimeString();
</script>

<div class="clock">
  <span class="label">{label}</span>
  <span class="value">rendered {renderedAt}</span>
</div>

<style>
  /* Styles omitted */
</style>
```

### LiveCounter.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';

  let { label = '' } = $props();

  await (isServer ? delay(700, 1300) : Promise.resolve());

  const renderedAt = new Date().toLocaleTimeString();
  let count = $state(0);
</script>

<div class="counter">
  <div class="meta">
    <span class="label">{label} <span class="tag">hydrated</span></span>
    <span class="minted">rendered {renderedAt}</span>
  </div>
  <button onclick={() => count++}>Clicked {count} {count === 1 ? 'time' : 'times'}</button>
</div>

<style>
  /* Styles omitted */
</style>
```

### ErrorModes.svelte
```svelte
<script>
  import { onMount } from 'svelte';
  import { reloadDeferredIsland, deferReloadState } from 'mochi-framework';

  const rendered = deferReloadState('flaky');
  const offline = deferReloadState('offline');

  // Starts false so SSR and the first hydration render agree: no island has registered yet, so
  // `reloading` reads false and the buttons would otherwise ship enabled.
  let ready = $state(false);
  onMount(() => {
    ready = true;
  });

  const stamp = (s) => (s.lastReloaded ? `${s.lastReloadOk ? 'ok' : 'failed'} at ${s.lastReloaded.toLocaleTimeString()}` : 'not yet reloaded');

  // The island endpoint answers 200 even when the render throws, so breaking the request itself
  // is the only way to show a failed fetch.
  async function reloadOffline() {
    const real = window.fetch;
    window.fetch = (url, ...rest) => (String(url).includes('/_mochi/island/') ? Promise.reject(new Error('simulated network failure')) : real(url, ...rest));
    try {
      await reloadDeferredIsland('offline');
    } finally {
      window.fetch = real;
    }
  }
</script>

<div class="modes">
  <div class="mode">
    <button disabled={!ready || rendered.reloading} onclick={() => reloadDeferredIsland('flaky')}>Reload 4 — make the render throw</button>
    <p class="note">
      Island 4 throws about half the time. Its own <code>&lt;svelte:boundary&gt;</code> catches it, so the island degrades to its failed snippet and the rest of the page is
      untouched. The fetch itself was fine, so <code>lastReloadOk</code> stays <strong>true</strong>.
    </p>
    <p class="state">Island 4: {rendered.count} reloads · {stamp(rendered)}</p>
  </div>

  <div class="mode">
    <button disabled={!ready || offline.reloading} onclick={reloadOffline}>Reload 5 — make the fetch fail</button>
    <p class="note">
      This one breaks the request instead of the render. Nothing comes back to swap in, so the island keeps the content it already had and
      <code>lastReloadOk</code> flips to <strong>false</strong>. Note the timestamp on island 5 does not change.
    </p>
    <p class="state">Island 5: {offline.count} reloads · {stamp(offline)}</p>
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### FlakyPanel.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';
  import FlakyContent from './FlakyContent.svelte';

  let { label = '' } = $props();

  await (isServer ? delay(700, 1300) : Promise.resolve());
</script>

<svelte:boundary>
  <FlakyContent {label} />

  {#snippet failed(error)}
    <div class="failed">
      <span class="label">{label}</span>
      <span class="value">failed — {error.message}</span>
    </div>
  {/snippet}
</svelte:boundary>

<style>
  /* Styles omitted */
</style>
```

### FlakyContent.svelte
```svelte
<script>
  let { label = '' } = $props();

  const renderedAt = new Date().toLocaleTimeString();

  if (Math.random() < 0.5) {
    throw new Error('Upstream service returned 503');
  }
</script>

<div class="ok">
  <span class="label">{label}</span>
  <span class="value">rendered {renderedAt}</span>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/defer-invalidation': Mochi.page('./src/demos/defer-invalidation/DeferInvalidation.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: email

### Email.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import EmailForm from './EmailForm.svelte';
  import AttachmentForm from './AttachmentForm.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Send Email"
  description={`Mochi.email() sends transactional mail. In development it uses the dev transport, which captures every message to an in-memory outbox at /_mochi/email instead of delivering it. Bodies here render from a Svelte template via Mochi.email({ component, props }). For safety this demo only lets you send one of a few pre-written emails — the recipient, subject, and body are all fixed server-side.`}
  {sources}
>
  <p>
    Pick one of the pre-written emails and send it. Then open the
    <a href="/_mochi/email" target="_blank" rel="noopener">dev email outbox</a> to read the captured message — the styled HTML body, plain-text part, recipients, and headers.
  </p>
  <h3>With <code>{'{@attach enhance(...)}'}</code></h3>
  <EmailForm mochi:hydrate />
  <h3>Plain HTML</h3>
  <EmailForm />
  <h3>Sending an attachment</h3>
  <p>
    Pass <code>attachments</code> to <code>Mochi.email(&#123; ... &#125;)</code> to send a file alongside the body. The route action reads a small pre-resized image off disk and
    attaches it; the outbox lists it as a <code>📎</code> chip on the captured message.
  </p>
  <AttachmentForm mochi:hydrate />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### EmailForm.svelte
```svelte
<script lang="ts">
  import { enhance, isServer, getRequestContext, isHydratable } from 'mochi-framework';
  import type { MochiEnhanceOptions, MochiSubmitFunction } from 'mochi-framework';
  import { EMAIL_PRESETS, DEMO_TO } from './presets.ts';

  const hydratable = isHydratable();
  // For SSR-only (plain HTML) renders, read the form action result so the
  // confirmation / error survives the page re-render after a POST.
  const _form = !hydratable && isServer ? getRequestContext().form : null;
  const _sentSubject = _form?.ok && typeof _form.data?.subject === 'string' ? _form.data.subject : null;
  const _failError = _form && !_form.ok && typeof _form.data?.error === 'string' ? _form.data.error : null;

  type SendData = { preset: string; subject: string };
  type FailData = { error: string };

  let sentSubject = $state<string | null>(_sentSubject);
  let errorMessage = $state<string | null>(_failError);
  let pending = $state(false);

  const handleSend: MochiSubmitFunction<SendData, FailData> = () => {
    errorMessage = null;
    return ({ result }) => {
      if (result.type === 'success' && result.data) {
        sentSubject = result.data.subject;
        errorMessage = null;
      } else if (result.type === 'failure' && result.data) {
        errorMessage = result.data.error;
      } else if (result.type === 'error') {
        errorMessage = 'Network error. Try again.';
      }
    };
  };

  const sendOpts: MochiEnhanceOptions<SendData, FailData> = {
    submit: handleSend,
    onPending: (v) => {
      pending = v;
    },
  };

  function reset() {
    sentSubject = null;
    errorMessage = null;
  }
</script>

{#if sentSubject}
  <div class="sent">
    <p>✅ Sent <strong>“{sentSubject}”</strong> to {DEMO_TO}.{hydratable ? ' No page reload happened.' : ''}</p>
    <p>
      <a class="outbox-link" href="/_mochi/email" target="_blank" rel="noopener">View it in the dev outbox →</a>
    </p>
    {#if hydratable}
      <button type="button" class="send-another" onclick={reset}>Send another</button>
    {:else}
      <!-- No JS in the plain version: a normal link back to the page drops the
           ?/send form snapshot so the empty form renders again. -->
      <a class="send-another" href="/demos/email/">Send another</a>
    {/if}
  </div>
{:else}
  <form method="POST" action="?/send" class="send" {@attach enhance(sendOpts)}>
    <p class="recipient">To: <strong>{DEMO_TO}</strong> <span class="fixed-note">(fixed — you pick the message, not the address)</span></p>
    <fieldset disabled={pending}>
      <legend>Choose a pre-written email</legend>
      {#each EMAIL_PRESETS as preset, i (preset.id)}
        <label class="option">
          <input type="radio" name="preset" value={preset.id} required checked={i === 0} />
          <span class="option-body">
            <span class="option-label">{preset.label}</span>
            <span class="option-blurb">{preset.blurb}</span>
          </span>
        </label>
      {/each}
    </fieldset>
    <div class="submit-row">
      <button type="submit" disabled={pending}>{pending ? 'Sending…' : 'Send email'}</button>
      {#if errorMessage}
        <p class="error" role="alert">{errorMessage}</p>
      {/if}
    </div>
  </form>
{/if}

<style>
  /* Styles omitted */
</style>
```

### AttachmentForm.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiEnhanceOptions, MochiSubmitFunction } from 'mochi-framework';
  import { ATTACHMENT, DEMO_TO } from './presets.ts';

  // Hydrated-only demo: this island always ships JS, so the form submits through
  // {@attach enhance(...)} — there's no plain-HTML fallback branch to handle.
  type SendData = { filename: string };
  type FailData = { error: string };

  let sentFilename = $state<string | null>(null);
  let errorMessage = $state<string | null>(null);
  let pending = $state(false);

  const handleSend: MochiSubmitFunction<SendData, FailData> = () => {
    errorMessage = null;
    return ({ result }) => {
      if (result.type === 'success' && result.data) {
        sentFilename = result.data.filename;
        errorMessage = null;
      } else if (result.type === 'failure' && result.data) {
        errorMessage = result.data.error;
      } else if (result.type === 'error') {
        errorMessage = 'Network error. Try again.';
      }
    };
  };

  const sendOpts: MochiEnhanceOptions<SendData, FailData> = {
    submit: handleSend,
    onPending: (v) => {
      pending = v;
    },
  };

  function reset() {
    sentFilename = null;
    errorMessage = null;
  }
</script>

{#if sentFilename}
  <div class="sent">
    <p>✅ Sent to {DEMO_TO} with <strong>{sentFilename}</strong> attached. No page reload happened.</p>
    <p>
      <a class="outbox-link" href="/_mochi/email" target="_blank" rel="noopener">View it in the dev outbox →</a>
    </p>
    <button type="button" class="send-another" onclick={reset}>Send another</button>
  </div>
{:else}
  <form method="POST" action="?/sendPhoto" class="send" {@attach enhance(sendOpts)}>
    <p class="recipient">To: <strong>{DEMO_TO}</strong></p>
    <div class="attachment">
      <img src={ATTACHMENT.previewUrl} alt="A mochi, ready to attach" width="120" height="80" />
      <span class="attach-meta">
        <span class="attach-name">📎 {ATTACHMENT.filename}</span>
        <span class="attach-note">rides along as a real file attachment</span>
      </span>
    </div>
    <div class="submit-row">
      <button type="submit" disabled={pending}>{pending ? 'Sending…' : 'Send email with attachment'}</button>
      {#if errorMessage}
        <p class="error" role="alert">{errorMessage}</p>
      {/if}
    </div>
  </form>
{/if}

<style>
  /* Styles omitted */
</style>
```

### emails/PresetEmail.svelte
```svelte
<script lang="ts">
  // Rendered by Mochi.email({ component, props }) — this runs server-side with no
  // request context, so it must not touch getRequestContext()/cookies/url.
  // The scoped style block below is inlined into the HTML by the mailer (css-inline).
  let { preset, name }: { preset: string; name: string } = $props();

  const receiptItems = [
    { label: 'Mochi Pro (annual)', amount: '$96.00' },
    { label: 'Priority support', amount: '$24.00' },
  ];
</script>

<div class="email">
  <div class="brand">🍡 Mochi</div>

  {#if preset === 'welcome'}
    <h1>Welcome aboard, {name}!</h1>
    <p>Thanks for signing up. Mochi renders Svelte on the server and hydrates only the islands that need it — so your pages stay fast by default.</p>
    <p><a class="button" href="https://mochi.fast/docs/">Read the docs</a></p>
    <p class="muted">Glad to have you. Reply any time — a real human reads these.</p>
  {:else if preset === 'receipt'}
    <h1>Thanks for your order, {name}</h1>
    <p>Here's a copy of your receipt for order <strong>#1024</strong>.</p>
    <table class="receipt">
      <tbody>
        {#each receiptItems as item (item.label)}
          <tr>
            <td>{item.label}</td>
            <td class="amount">{item.amount}</td>
          </tr>
        {/each}
        <tr class="total">
          <td>Total</td>
          <td class="amount">$120.00</td>
        </tr>
      </tbody>
    </table>
    <p class="muted">Charged to the card ending in 4242. Questions? Just reply.</p>
  {:else}
    <h1>Reset your password</h1>
    <p>Hi {name}, we received a request to reset the password on your Mochi account.</p>
    <p><a class="button" href="https://mochi.fast/reset?token=demo">Choose a new password</a></p>
    <p class="muted">This link expires in 30 minutes. If you didn't ask for this, you can safely ignore this email.</p>
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### emails/AttachmentEmail.svelte
```svelte
<script lang="ts">
  // Rendered by Mochi.email({ component, props }) server-side, no request context; the
  // scoped styles below are inlined into the HTML by the mailer. The photo itself rides
  // along as a real file attachment (see routes.ts), so the body only needs to mention it.
  let { name, filename }: { name: string; filename: string } = $props();
</script>

<div class="email">
  <div class="brand">🍡 Mochi</div>
  <h1>A photo for you, {name}</h1>
  <p>Here's a mochi we thought you'd like — it's attached as <strong>{filename}</strong>.</p>
  <p class="muted">Open the attachment to take a look. Reply any time.</p>
</div>

<style>
  /* Styles omitted */
</style>
```

### presets.ts
```ts
// The recipient is a fixed server-side constant — the demo never lets a visitor
// type an address, so no mail can be aimed at an arbitrary inbox.
export const DEMO_TO = 'Ada Lovelace <ada@example.com>';

export interface EmailPreset {
  id: string;
  label: string;
  subject: string;
  blurb: string;
}

export const EMAIL_PRESETS: EmailPreset[] = [
  {
    id: 'welcome',
    label: 'Welcome email',
    subject: 'Welcome to Mochi 🍡',
    blurb: 'A friendly onboarding note with a call-to-action button.',
  },
  {
    id: 'receipt',
    label: 'Order receipt',
    subject: 'Your receipt #1024',
    blurb: 'A transactional receipt with a small line-item table.',
  },
  {
    id: 'reset',
    label: 'Password reset',
    subject: 'Reset your password',
    blurb: 'A security email with a time-limited reset link.',
  },
];

export const presetById = (id: string): EmailPreset | undefined => EMAIL_PRESETS.find((p) => p.id === id);

// `path` resolves server-side in the route action; the client only needs `filename` and `previewUrl`.
export const ATTACHMENT = {
  subject: 'A photo for you 🍡',
  filename: 'mochi.jpg',
  path: './src/demos/email/mochi-photo.jpg',
  previewUrl: '/demos/email/mochi-photo.jpg',
  contentType: 'image/jpeg',
} as const;
```

### routes.ts
```ts
import { Mochi, fail, success } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';
import { ATTACHMENT, DEMO_TO, presetById } from './presets';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/email': Mochi.page('./src/demos/email/Email.svelte', {
    actions: {
      // The form only submits a `preset` id; validating it against the allowlist
      // means no visitor-supplied recipient/subject/body can ever reach the mailer.
      send: async ({ formData }) => {
        const preset = presetById(String(formData.get('preset') ?? ''));
        if (!preset) {
          return fail(400, { error: 'Pick one of the pre-written emails.' });
        }
        await Mochi.email({
          from: 'Mochi Demo <noreply@mochi.demo>',
          to: DEMO_TO,
          subject: preset.subject,
          component: './src/emails/PresetEmail.svelte',
          props: { preset: preset.id, name: 'Ada' },
        });
        return success({ preset: preset.id, subject: preset.subject });
      },
      // The recipient, subject, and file are all fixed server-side — nothing about the attachment comes from the request.
      sendPhoto: async () => {
        const content = await Bun.file(ATTACHMENT.path).bytes();
        await Mochi.email({
          from: 'Mochi Demo <noreply@mochi.demo>',
          to: DEMO_TO,
          subject: ATTACHMENT.subject,
          component: './src/emails/AttachmentEmail.svelte',
          props: { name: 'Ada', filename: ATTACHMENT.filename },
          attachments: [{ filename: ATTACHMENT.filename, content, contentType: ATTACHMENT.contentType }],
        });
        return success({ filename: ATTACHMENT.filename });
      },
    },
  }),
  // Serves the small demo image so the attachment form can preview it.
  '/demos/email/mochi-photo.jpg': Mochi.file(ATTACHMENT.path),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: entity-props

### EntityDemo.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import EntityIsland from './EntityIsland.svelte';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';

  const name = 'friend';

  const codeUsage = await highlightCode(
    `<EntityIsland
  label="Tom &amp; Jerry"
  quote="She said &quot;hi&quot;"
  comparison="5 &lt; 10 &amp;&amp; 10 &gt; 5"
  copyright="&copy; 2026 Mochi"
  greeting="Hi &amp; welcome, {name}"
  mochi:hydrate
/>`,
    'svelte',
  );
</script>

<DemoPage
  title="HTML Entities in Props"
  description="Static string-literal props on a hydrated island can contain HTML entities (&amp;, &quot;, &lt;, &copy;). They decode to their characters before reaching the island — identically on the server and after hydration — so the SSR text and the hydrated text always match."
  {sources}
>
  <section class="intro">
    <p>
      The parent (server-only) passes literal HTML entities in <code>string="…"</code> attributes on a <code>mochi:hydrate</code> island. Svelte decodes them for the SSR render,
      and Mochi's preprocessor decodes the same value into the serialized props the client hydrates with — so the two never disagree. Watch the
      <strong>Rendered on</strong> line flip from <code>server</code> to <code>client</code> after hydration while every value stays the same.
    </p>
    <CodeSnippet html={codeUsage} />
  </section>

  <EntityIsland
    label="Tom &amp; Jerry"
    quote="She said &quot;hi&quot;"
    comparison="5 &lt; 10 &amp;&amp; 10 &gt; 5"
    copyright="&copy; 2026 Mochi"
    greeting="Hi &amp; welcome, {name}"
    mochi:hydrate
  />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### EntityIsland.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';

  let {
    label,
    quote,
    comparison,
    copyright,
    greeting,
  }: {
    label: string;
    quote: string;
    comparison: string;
    copyright: string;
    greeting: string;
  } = $props();

  // The `authored` column shows the raw attribute text as written in the parent
  // (`&amp;`, `&quot;`, …); the `value` column shows what the island actually
  // received. They must differ — the entity is decoded before it reaches the prop.
  const rows: Array<{ name: string; authored: string; value: string }> = $derived([
    { name: 'label', authored: 'Tom &amp; Jerry', value: label },
    { name: 'quote', authored: 'She said &quot;hi&quot;', value: quote },
    { name: 'comparison', authored: '5 &lt; 10 &amp;&amp; 10 &gt; 5', value: comparison },
    { name: 'copyright', authored: '&copy; 2026 Mochi', value: copyright },
    { name: 'greeting (mixed)', authored: 'Hi &amp; welcome, {name}', value: greeting },
  ]);
</script>

<div class="island">
  <p class="where">
    Rendered on: <strong>{isBrowser ? 'client (hydrated)' : 'server (SSR)'}</strong>
  </p>
  <table>
    <thead>
      <tr>
        <th>Prop</th>
        <th>Authored attribute</th>
        <th>Value received</th>
      </tr>
    </thead>
    <tbody>
      {#each rows as row (row.name)}
        <tr>
          <td><code>{row.name}</code></td>
          <td><code>{row.authored}</code></td>
          <td class="value">{row.value}</td>
        </tr>
      {/each}
    </tbody>
  </table>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/entity-props': Mochi.page('./src/demos/entity-props/EntityDemo.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: error

### ErrorDemo.svelte
```svelte
<script>
  import { highlightCode } from '../../lib/highlight.server';
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import { sources } from './sources.prerender.ts';

  const handleErrorSnippet = `const handleError: HandleError = ({ error, event, status, message }) => {
  logger.info(
    \`handleError: \${event.url.pathname} → \${status} "\${message}" (error \${error ? 'present' : 'null'})\`,
  );
  // error is null for unmatched routes / unknown form actions — guard before forwarding
  if (error && status >= 500) {
    logger.error('app:', event.url.pathname, error);
  }
  // Short-circuit: redirect this specific demo path instead of rendering the error page
  if (event.url.pathname === '/demos/error/redirect') {
    return Response.redirect(new URL('/demos/error', event.url), 302);
  }
};`;
  const handleErrorHtml = await highlightCode(handleErrorSnippet, 'ts');
</script>

<DemoPage title="Error Handling" description="You can route render errors and unmatched routes through Mochi.serve()'s errorPage option and the handleError hook." {sources}>
  <div class="prose">
    <p>
      Mochi catches any throw from a page's <code>serverProps</code> resolver or Svelte <code>&lt;script&gt;</code>, plus any request that doesn't match a route, and renders the
      built-in default error page. Pass your own <code>errorPage</code> to <code>Mochi.serve()</code> to replace it. The <code>handleError</code> hook runs for every error — use it
      to log, forward to an error tracker, sanitize the message, or return a <code>Response</code> to short-circuit rendering.
    </p>

    <p class="lead">Try it:</p>

    <ul class="examples">
      <li>
        <a href="/demos/error/500/"><code>/demos/error/500</code></a>
        <span>the page's <code>&lt;script&gt;</code> throws during SSR</span>
      </li>
      <li>
        <a href="/demos/error/404/"><code>/demos/error/404</code></a>
        <span>the <code>serverProps</code> resolver calls <code>error(404, ...)</code></span>
      </li>
      <li>
        <a href="/does-not-exist/"><code>/does-not-exist</code></a>
        <span>no route matches — <code>handleError</code> fires with <code>error: null</code>, then the error page renders with status 404</span>
      </li>
      <li>
        <a href="/demos/error/redirect/"><code>/demos/error/redirect</code></a>
        <span>
          the page throws, but <code>handleError</code> returns <code>Response.redirect(...)</code> — you land back on this page instead of seeing the error component
        </span>
      </li>
    </ul>

    <p>
      A custom error component receives a single <code>error</code> prop with <code>status</code>,
      <code>message</code>, and (in development only) <code>stack</code> — typed as
      <code>MochiErrorProps</code>.
    </p>

    <p class="lead">This site's <code>handleError</code>:</p>

    <CodeSnippet html={handleErrorHtml} />

    <p>
      Watch your dev server output while clicking the links above — each visit logs one
      <code>handleError:</code> line via <code>logger</code> from <code>mochi-framework</code>. Unmatched routes log <code>error null</code>; SSR throws log
      <code>error present</code>.
    </p>
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### Error500.svelte
```svelte
<script>
  throw new Error('This route throws on purpose to demonstrate the errorPage.');
</script>

<p>You should never see this — the page throws during SSR.</p>
```

### routes.ts
```ts
import { Mochi, error } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/error': Mochi.page('./src/demos/error/ErrorDemo.svelte'),
  '/demos/error/500': Mochi.page('./src/demos/error/Error500.svelte'),
  '/demos/error/404': Mochi.page('./src/demos/error/Error500.svelte', {
    serverProps: () => {
      error(404, 'This item does not exist.');
    },
  }),
  // Throws during SSR, but the site-wide handleError returns a redirect Response
  // for this pathname, so the error page is never rendered.
  '/demos/error/redirect': Mochi.page('./src/demos/error/Error500.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: error-boundaries

### ErrorBoundaries.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import ThrowOnSsr from './ThrowOnSsr.svelte';
  import ThrowOnClient from './ThrowOnClient.svelte';
  import ThrowOnServerIsland from './ThrowOnServerIsland.svelte';
  import HealthyServerIsland from './HealthyServerIsland.svelte';
  import { sources } from './sources.prerender.ts';
</script>

{#snippet caughtFallback(error: unknown)}
  <div class="caught">
    Caught by user-written boundary:
    <code>{error instanceof Error ? error.message : String(error)}</code>
  </div>
{/snippet}

<DemoPage
  title="Error Boundaries"
  description="You can use Svelte error boundaries to isolate failures. Without them, any one throwing component could take down a whole page load (which might be what you want sometimes). With boundaries, the failure is walled off and the rest of the page keeps working. In dev, the failed island shows a small dashed-red marker; in prod, it disappears silently."
  {sources}
>
  <section class="mode">
    <header>
      <h2>1. Non-hydrated component + user <code>&lt;svelte:boundary&gt;</code></h2>
      <p>
        Non-hydrated components don't get an automatic boundary. If they can throw during SSR, wrap them in a hand-written <code>&lt;svelte:boundary&gt;</code> — otherwise the throw
        bubbles up and crashes the whole request.
      </p>
    </header>
    <svelte:boundary failed={caughtFallback}><ThrowOnSsr label="ThrowOnSsr (no directive)" /></svelte:boundary>
  </section>

  <section class="mode">
    <header>
      <h2>2. <code>mochi:hydrate</code> — SSR throw (recovery)</h2>
      <p>
        The framework auto-wraps every <code>mochi:hydrate</code> island in a boundary. This island throws on the server only — the boundary catches the SSR throw and the rest of the
        page renders unaffected.
      </p>
    </header>
    <ThrowOnSsr mochi:hydrate label="ThrowOnSsr" />
  </section>

  <section class="mode">
    <header>
      <h2>3. <code>mochi:hydrate</code> — client throw</h2>
      <p>
        SSR is fine, but the script throws synchronously once the island tries to hydrate. The defensive try/catch around <code>hydrate()</code> catches it and swaps the island for the
        failure stub — the rest of the page (already rendered on the server) is untouched.
      </p>
    </header>
    <ThrowOnClient mochi:hydrate label="ThrowOnClient" />
  </section>

  <section class="mode">
    <header>
      <h2>4. <code>mochi:defer</code> — server island throw</h2>
      <p>
        Server islands render at a separate endpoint. When that render throws, the endpoint returns a 200 with an error stub — the browser doesn't waste retries on a deterministic
        failure. The user-supplied loading children stay until the response arrives.
      </p>
    </header>
    <ThrowOnServerIsland mochi:defer label="ThrowOnServerIsland">
      <div class="placeholder">Loading from server…</div>
    </ThrowOnServerIsland>
  </section>

  <section class="mode">
    <header>
      <h2>
        5. <code>mochi:defer</code> — healthy island, inner <code>mochi:hydrate</code> client throw
      </h2>
      <p>
        The server island itself renders successfully — it's the inner <code>mochi:hydrate</code>
        child that throws once it tries to hydrate on the client. The child's auto-boundary catches its own failure, so the rest of the server island content stays intact.
      </p>
    </header>
    <HealthyServerIsland mochi:defer>
      <div class="placeholder">Loading from server…</div>
    </HealthyServerIsland>
  </section>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### ThrowOnSsr.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';

  const props: { label?: string } = $props();

  if (!isBrowser) {
    throw new Error(`SSR throw from <${props.label ?? 'ThrowOnSsr'}>`);
  }
</script>

<div class="card">
  On the server this island threw, so the boundary swapped in the failure stub — you briefly see it flash before hydration takes over, or if you disable JavaScript. Then the client
  re-renders the component cleanly and replaces the stub with this content. This works but is not recommended.
</div>

<style>
  /* Styles omitted */
</style>
```

### ThrowOnClient.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';

  const props: { label?: string } = $props();

  if (isBrowser) {
    throw new Error(`Client throw from <${props.label ?? 'ThrowOnClient'}>`);
  }
</script>

<div class="card">
  This island renders fine on the server. Once the client tries to hydrate, the script throws synchronously — the boundary catches it and swaps in the failure stub.
</div>

<style>
  /* Styles omitted */
</style>
```

### ThrowOnServerIsland.svelte
```svelte
<script lang="ts">
  import type { Snippet } from 'svelte';

  // children is the loading-state snippet shown until the server island
  // resolves (or, in this demo, fails) — declared so call sites can pass it.
  let { label = 'ThrowOnServerIsland', children: _children }: { label?: string; children?: Snippet } = $props();

  // Used as a `mochi:defer` target: the throw is caught by the server-island endpoint's try/catch,
  // which returns a 200 + island-failure stub so the client doesn't burn its retry budget.
  // svelte-ignore state_referenced_locally
  throw new Error(`Server-island throw from <${label}>`);
</script>

<div>never rendered</div>
```

### HealthyServerIsland.svelte
```svelte
<script lang="ts">
  import type { Snippet } from 'svelte';
  import ThrowOnClient from './ThrowOnClient.svelte';

  let { children: _children }: { children?: Snippet } = $props();
</script>

<div class="card">
  <p>The server island itself rendered successfully.</p>
  <p>
    Inside it sits a <code>mochi:hydrate</code> child that throws on the client — its boundary catches the failure independently:
  </p>
  <ThrowOnClient mochi:hydrate label="ThrowOnClient (inside server island)" />
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/error-boundaries': Mochi.page('./src/demos/error-boundaries/ErrorBoundaries.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: file

### File.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import FileViewer from './FileViewer.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="File Routes"
  description="You can serve a file straight from disk with Mochi.file() — pass a static path, or a resolver that picks the file per request from the route params. The file is read fresh on every request, so files written or deleted at runtime are picked up immediately. Missing files (or a resolver that throws error(404)) come back as a plain-text 404."
  {sources}
>
  <FileViewer mochi:hydrate />
</DemoPage>
```

### FileViewer.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';

  let path = $state('/demos/file/download');
  let body = $state('');
  let meta = $state('');
  let loading = $state(false);

  const routes = [
    { label: 'String path', path: '/demos/file/download' },
    { label: 'Resolver · sample', path: '/demos/file/dynamic/sample' },
    { label: 'Resolver · notes', path: '/demos/file/dynamic/notes' },
    { label: 'Resolver · missing (404)', path: '/demos/file/dynamic/nope' },
  ];

  async function load(target: string) {
    if (!isBrowser) {
      return;
    }
    path = target;
    loading = true;
    body = '';
    meta = '';
    try {
      const res = await fetch(target);
      meta = `${res.status} · ${res.headers.get('content-type') ?? 'no content-type'} · ${res.headers.get('content-length') ?? '?'} bytes`;
      body = await res.text();
    } catch (e: unknown) {
      meta = 'error';
      body = e instanceof Error ? e.message : String(e);
    } finally {
      loading = false;
    }
  }
</script>

<div class="viewer">
  <div class="routes">
    {#each routes as r (r.path)}
      <button class="route-btn" class:active={path === r.path} onclick={() => load(r.path)}>
        {r.label}
        <code>{r.path}</code>
      </button>
    {/each}
  </div>

  <div class="output">
    <div class="meta">{loading ? 'Loading…' : meta || 'Pick a route to fetch the file.'}</div>
    {#if body}
      <pre>{body}</pre>
    {/if}
  </div>

  <a class="download" href="/demos/file/download" download>Download sample.txt ↓</a>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, error } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

// Only these names map to a fixture on disk; anything else 404s from the
// resolver itself rather than probing the filesystem.
const ALLOWED = new Set(['sample', 'notes']);

export const routes: Record<string, MochiRouteValue> = {
  '/demos/file': Mochi.page('./src/demos/file/File.svelte'),

  // String form — serve one fixed file from disk.
  '/demos/file/download': Mochi.file('./src/demos/file/sample.txt'),

  // Resolver form — pick the file per request from the route param.
  '/demos/file/dynamic/:name': Mochi.file((_req, params) => {
    const name = params.name ?? '';
    if (!ALLOWED.has(name)) {
      error(404, `No file named "${name}"`);
    }
    return `./src/demos/file/${name}.txt`;
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: file-upload

### FileUploadDemo.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import FileUpload from './FileUpload.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="File Uploads via form actions"
  description={`You can uploads files similarly to how other forms are handled. In the demo below where you can upload a text or markdown file, with {@attach enhance(...)}, the demo file content you upload is echoed back to you. Without progressive enhancement, the page re-renders and the component reads the result from getRequestContext().form.`}
  {sources}
>
  <h3>With <code>{'{@attach enhance(...)}'}</code></h3>
  <FileUpload label="The enhance attachment submits multipart/form-data over fetch and shows the file content inline" mochi:hydrate />
  <h3>Plain HTML</h3>
  <FileUpload label="Plain multipart POST, page re-renders with the file content from the form snapshot" />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### FileUpload.svelte
```svelte
<script lang="ts">
  import { enhance, isServer, getRequestContext, isHydratable } from 'mochi-framework';
  import type { MochiSubmitFunction } from 'mochi-framework';
  import Paperclip from '@lucide/svelte/icons/paperclip';

  type UploadResult = { filename: string; content: string; size: number };

  let { label }: { label: string } = $props();

  const hydratable = isHydratable();
  const _form = !hydratable && isServer ? getRequestContext().form : null;
  const initialResult: UploadResult | null = _form?.ok && _form.action === 'uploadFile' ? (_form.data as UploadResult) : null;
  const initialError: string | null = !_form?.ok && _form?.action === 'uploadFile' ? String(_form.data.error ?? '') : null;

  let fileResult = $state<UploadResult | null>(initialResult);
  let errorMessage = $state<string | null>(initialError);
  let pending = $state(false);
  let selectedName = $state<string | null>(null);

  function onFileChange(e: Event) {
    selectedName = (e.currentTarget as HTMLInputElement).files?.[0]?.name ?? null;
  }

  const handleSubmit: MochiSubmitFunction<UploadResult, { error: string }> = () => {
    pending = true;
    fileResult = null;
    errorMessage = null;
    return ({ result, formElement }) => {
      pending = false;
      if (result.type === 'success' && result.data) {
        fileResult = result.data;
        formElement.reset();
      } else if (result.type === 'failure' && result.data) {
        errorMessage = result.data.error;
      } else if (result.type === 'error') {
        errorMessage = (result.error as { message?: string })?.message ?? 'Upload failed';
      }
    };
  };
</script>

<div class="demo-block">
  <p class="label">{label}</p>
  {#if errorMessage}
    <p class="error" role="alert">{errorMessage}</p>
  {/if}
  {#if fileResult}
    <div class="file-result">
      <p class="file-meta">{fileResult.filename} &mdash; {fileResult.size} bytes</p>
      <pre class="file-content">{fileResult.content}</pre>
    </div>
  {/if}
  <form method="POST" action="?/uploadFile" enctype="multipart/form-data" {@attach enhance(handleSubmit)}>
    <div class="file-row">
      <label class="file-btn">
        <Paperclip size={15} />
        Choose file
        <input type="file" name="file" accept=".txt,.md" required onchange={onFileChange} />
      </label>
      {#if hydratable}
        <span class="file-name" class:chosen={selectedName}>{selectedName ?? 'No file chosen'}</span>
      {/if}
    </div>
    <button type="submit" disabled={pending}>{pending ? 'Uploading…' : 'Upload'}</button>
  </form>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, fail, success } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/file-upload': Mochi.page('./src/demos/file-upload/FileUploadDemo.svelte', {
    actions: {
      uploadFile: async ({ formData }) => {
        const file = formData.get('file');
        if (!(file instanceof File) || file.size === 0) {
          return fail(400, { error: 'No file selected' });
        }
        const ext = file.name.split('.').pop()?.toLowerCase() ?? '';
        if (ext !== 'txt' && ext !== 'md') {
          return fail(400, { error: 'Only .txt and .md files are accepted' });
        }
        if (file.size > 100 * 1024) {
          return fail(400, { error: 'File too large (max 100 KB)' });
        }
        const content = await file.text();
        return success({ filename: file.name, content, size: file.size });
      },
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: font-loading

### FontLoading.svelte
```svelte
<script>
  import '@fontsource/jetbrains-mono';
  import './lobster.css';
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';

  const codeFontFace = await highlightCode(
    `@font-face {
  font-family: 'Lobster';
  src: url('./lobster.woff2') format('woff2');
}`,
    'css',
  );
</script>

<DemoPage
  title="Font loading"
  description="Mochi supports loading fonts from third-party packages like @fontsource or from local font files like .woff2 — all automatically bundled and linked from the page <head>."
  {sources}
>
  <section>
    <h2>Fontsource package example</h2>
    <p>
      Add <code>@fontsource/jetbrains-mono</code> and import it.
    </p>
    <p class="sample sample-mono">The quick brown fox jumps over the lazy dog. 1234567890</p>
  </section>

  <section>
    <h2>Standalone .woff2 example</h2>
    <p>
      Drop a <code>.woff2</code> next to your component and reference it from a tiny
      <code>@font-face</code> CSS file:
    </p>
    <CodeSnippet html={codeFontFace} />
    <p>
      Import the CSS (<code>import './lobster.css'</code>). Mochi serves the <code>.woff2</code> as a separate content-hashed file — small fonts (≤4&nbsp;kB) stay inlined in the bundled
      CSS as data URIs.
    </p>
    <p class="sample sample-display">The quick brown fox jumps over the lazy dog. 1234567890</p>
  </section>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### lobster.css
```ts
@font-face {
  font-family: 'Lobster';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url('./lobster.woff2') format('woff2');
}
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/font-loading': Mochi.page('./src/demos/font-loading/FontLoading.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: form-cancel

### FormCancel.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import CancelDemo from './CancelDemo.svelte';
  import AbortDemo from './AbortDemo.svelte';
  import PlainDemo from './PlainDemo.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Cancelling form submissions"
  description={`Inside {@attach enhance(...)} there are two distinct cancellation points: cancel() short-circuits before the fetch is issued; controller.abort() stops a request that is already in flight. They solve different problems — they are not interchangeable.`}
  {sources}
>
  <p>The action sleeps 3 s to simulate a slow lookup. Each variant below uses the same action but cancels at a different point — or not at all.</p>

  <h3><code>cancel()</code> — pre-flight short-circuit</h3>
  <p>
    The <code>submit</code> callback receives <code>cancel</code>. Calling it skips the fetch entirely — no request is sent, no result callback runs. Use this for client-side
    validation or any condition you can check before leaving the browser.
  </p>
  <CancelDemo label="Type fewer than 3 characters and submit — cancel() fires, no network request" mochi:hydrate />

  <h3><code>controller.abort()</code> — in-flight cancellation</h3>
  <p>
    The <code>submit</code> callback also receives an
    <code>AbortController</code>. Calling <code>controller.abort()</code>
    stops a fetch that has already started. Here a 1.5 s timeout aborts the 3 s lookup; <code>enhance</code> swallows the <code>AbortError</code> and resets the form to idle.
  </p>
  <AbortDemo label="Submit any query — the request aborts after 1.5 s" mochi:hydrate />

  <h3>Plain HTML — no <code>enhance</code></h3>
  <p>Without JavaScript there is nothing to cancel. The browser POSTs and waits the full 3 s, then the page re-renders with the result.</p>
  <PlainDemo label="Plain POST — waits the full 3 s, page re-renders with the result" />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### CancelDemo.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiEnhanceOptions, MochiSubmitFunction } from 'mochi-framework';

  let { label }: { label: string } = $props();

  let pending = $state(false);
  let result = $state<string | null>(null);
  let message = $state<string | null>(null);

  const handleSubmit: MochiSubmitFunction<{ result: string }, { error: string }> = ({ cancel, formData }) => {
    const query = String(formData.get('query') ?? '').trim();
    result = null;
    message = null;
    if (query.length < 3) {
      cancel();
      message = 'Query must be at least 3 characters — no request sent.';
      return;
    }
    return ({ result: r }) => {
      if (r.type === 'success' && r.data) {
        result = r.data.result;
      } else if (r.type === 'failure' && r.data) {
        message = r.data.error;
      }
    };
  };

  const opts: MochiEnhanceOptions<{ result: string }, { error: string }> = {
    submit: handleSubmit,
    onPending: (v) => {
      pending = v;
    },
  };
</script>

<div class="demo-block">
  <p class="label">{label}</p>
  <form method="POST" action="?/lookup" class="lookup" {@attach enhance(opts)}>
    <label>
      <span>Query</span>
      <input name="query" placeholder="Enter at least 3 characters…" disabled={pending} />
    </label>
    <button type="submit" disabled={pending}>{pending ? 'Searching…' : 'Search'}</button>
  </form>
  {#if result}
    <p class="result" role="status">{result}</p>
  {/if}
  {#if message}
    <p class="message" role="alert">{message}</p>
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### AbortDemo.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiEnhanceOptions, MochiSubmitFunction } from 'mochi-framework';

  let { label }: { label: string } = $props();

  let pending = $state(false);
  let result = $state<string | null>(null);
  let message = $state<string | null>(null);
  let gotResult = false;
  let timeoutId: ReturnType<typeof setTimeout> | null = null;

  const handleSubmit: MochiSubmitFunction<{ result: string }, { error: string }> = ({ controller }) => {
    result = null;
    message = null;
    gotResult = false;
    timeoutId = setTimeout(() => controller.abort(), 1500);
    return ({ result: r }) => {
      if (timeoutId) {
        clearTimeout(timeoutId);
      }
      timeoutId = null;
      gotResult = true;
      if (r.type === 'success' && r.data) {
        result = r.data.result;
      } else if (r.type === 'failure' && r.data) {
        message = r.data.error;
      }
    };
  };

  const opts: MochiEnhanceOptions<{ result: string }, { error: string }> = {
    submit: handleSubmit,
    onPending: (v) => {
      pending = v;
      if (!v && !gotResult) {
        message = 'Request timed out after 1.5 s — aborted in flight.';
      }
    },
  };
</script>

<div class="demo-block">
  <p class="label">{label}</p>
  <form method="POST" action="?/lookup" class="lookup" {@attach enhance(opts)}>
    <label>
      <span>Query</span>
      <input name="query" placeholder="Enter a name…" required disabled={pending} />
    </label>
    <button type="submit" disabled={pending}>{pending ? 'Searching…' : 'Search'}</button>
  </form>
  {#if result}
    <p class="result" role="status">{result}</p>
  {/if}
  {#if message}
    <p class="message" role="alert">{message}</p>
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### PlainDemo.svelte
```svelte
<script lang="ts">
  import { isServer, getRequestContext } from 'mochi-framework';

  let { label }: { label: string } = $props();

  const _form = isServer ? getRequestContext().form : null;
  const initialResult: string | null = _form?.ok && _form.action === 'lookup' ? String(_form.data.result ?? '') : null;
  const initialMessage: string | null = !_form?.ok && _form?.action === 'lookup' ? String(_form.data.error ?? '') : null;
</script>

<div class="demo-block">
  <p class="label">{label}</p>
  <form method="POST" action="?/lookup" class="lookup">
    <label>
      <span>Query</span>
      <input name="query" placeholder="Enter a name…" required />
    </label>
    <button type="submit">Search</button>
  </form>
  {#if initialResult}
    <p class="result" role="status">{initialResult}</p>
  {/if}
  {#if initialMessage}
    <p class="message" role="alert">{initialMessage}</p>
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, fail, success } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/form-cancel': Mochi.page('./src/demos/form-cancel/FormCancel.svelte', {
    actions: {
      lookup: async ({ formData }) => {
        const query = String(formData.get('query') ?? '').trim();
        if (!query) {
          return fail(400, { error: 'Query is required' });
        }
        await Bun.sleep(3000);
        return success({ result: `Found: ${query} — status active` });
      },
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: form-errors

### FormErrors.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import ErrorDemo from './ErrorDemo.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Form Errors"
  description={`Both standard HTML forms and progressively enhanced forms can handle errors gracefully. With {@attach enhance(...)}, the error message is shown inline. Without it, Mochi renders the server error page.`}
  {sources}
>
  <p>
    The action throws a plain <code>Error</code>. With <code>{'{@attach enhance(...)}'}</code> the error message is shown inline. Without it, the server renders the Mochi error page.
  </p>
  <h3>With <code>{'{@attach enhance(...)}'}</code></h3>
  <ErrorDemo label="The enhance attachment catches the thrown error and shows it inline" mochi:hydrate />
  <h3>Plain HTML</h3>
  <ErrorDemo label="Plain POST, server throws, Mochi renders the error page (press back to return)" />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### ErrorDemo.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiSubmitFunction } from 'mochi-framework';

  let { label }: { label: string } = $props();

  let errorMessage = $state<string | null>(null);
  let pending = $state(false);

  const handleSubmit: MochiSubmitFunction = () => {
    pending = true;
    errorMessage = null;
    return ({ result }) => {
      pending = false;
      if (result.type === 'error') {
        errorMessage = (result.error as { message?: string })?.message ?? 'Unknown server error';
      }
    };
  };
</script>

<div class="demo-block">
  <p class="label">{label}</p>
  <form method="POST" action="?/throwError" {@attach enhance(handleSubmit)}>
    {#if errorMessage}
      <p class="error" role="alert">{errorMessage}</p>
    {/if}
    <button type="submit" disabled={pending}>{pending ? 'Throwing…' : 'Trigger server error'}</button>
  </form>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/form-errors': Mochi.page('./src/demos/form-errors/FormErrors.svelte', {
    actions: {
      throwError: () => {
        throw new Error('Something went wrong on the server');
      },
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: form-redirects

### FormRedirects.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import RedirectDemo from './RedirectDemo.svelte';
  import { sources } from './sources.prerender.ts';

  let { redirected }: { redirected: boolean } = $props();
</script>

<DemoPage
  title="Form Redirects"
  description={`You can return redirect(<code>, …) from an action. With {@attach enhance(...)}, the JSON envelope is intercepted before navigating. Without it, the browser follows the native 303 response.`}
  {sources}
>
  {#if redirected}
    <p class="redirect-flash" role="status">Redirected here via HTTP 303 (non-enhanced path).</p>
  {/if}

  <p>
    The action returns <code>redirect(303, …)</code>. With <code>{'{@attach enhance(...)}'}</code> the JSON envelope is intercepted so you can inspect it before navigating. Without it,
    the browser follows the HTTP 303.
  </p>
  <h3>With <code>{'{@attach enhance(...)}'}</code></h3>
  <RedirectDemo label="The enhance attachment intercepts the redirect envelope; click Follow to navigate" mochi:hydrate />
  <h3>Plain HTML</h3>
  <RedirectDemo label="Plain POST, server returns 303, browser follows the Location header" />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### RedirectDemo.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiSubmitFunction, MochiEnhanceResult } from 'mochi-framework';

  let { label }: { label: string } = $props();

  let redirectResult = $state<{ status: number; location: string } | null>(null);
  let pending = $state(false);

  // Intercept the redirect instead of immediately navigating so we can show the JSON envelope.
  const handleSubmit: MochiSubmitFunction = () => {
    pending = true;
    redirectResult = null;
    return ({ result }: { result: MochiEnhanceResult }) => {
      pending = false;
      if (result.type === 'redirect') {
        redirectResult = { status: result.status, location: result.location };
      }
    };
  };

  function follow(): void {
    if (redirectResult) {
      window.location.assign(redirectResult.location);
    }
  }
</script>

<div class="demo-block">
  <p class="label">{label}</p>
  <form method="POST" action="?/doRedirect" {@attach enhance(handleSubmit)}>
    {#if redirectResult}
      <div class="result" role="status">
        <p>Server returned <code>type: "redirect"</code></p>
        <p><code>status: {redirectResult.status}</code></p>
        <p><code>location: "{redirectResult.location}"</code></p>
        <button type="button" onclick={follow}>Follow redirect</button>
      </div>
    {:else}
      <button type="submit" disabled={pending}>{pending ? 'Redirecting…' : 'Trigger redirect'}</button>
    {/if}
  </form>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, redirect, getRequestContext } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/form-redirects': Mochi.page('./src/demos/form-redirects/FormRedirects.svelte', {
    serverProps: () => {
      const { url } = getRequestContext();
      return { redirected: url.searchParams.has('redirected') };
    },
    actions: {
      doRedirect: () => redirect(303, '/demos/form-redirects?redirected=1'),
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: form-return-data

### FormReturnData.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import RandomRoll from './RandomRoll.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Using form return data"
  description={`You can return data from an action via success(...). With {@attach enhance(...)}, the JSON result updates the UI in place. Without it, the page re-renders and the component can read the value from getRequestContext().form.`}
  {sources}
>
  <p>
    A minimal action that returns a random number via <code>success({'{ value }'})</code>. The hydrated version updates the input reactively; the non-hydrated version re-renders
    the whole page and the component reads the value from <code>getRequestContext().form</code>.
  </p>
  <h3>With <code>{'{@attach enhance(...)}'}</code></h3>
  <RandomRoll label="The enhance attachment fills the input via fetch + JSON, no reload" mochi:hydrate />
  <h3>Plain HTML</h3>
  <RandomRoll label="Full HTML POST, page re-renders, RandomRoll reads the value from the request's form snapshot via !isHydratable() && isServer" />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### RandomRoll.svelte
```svelte
<script lang="ts">
  import { enhance, isServer, getRequestContext, isHydratable } from 'mochi-framework';
  import type { MochiSubmitFunction } from 'mochi-framework';

  let { label }: { label: string } = $props();

  const _form = !isHydratable() && isServer ? getRequestContext().form : null;
  const initialValue = _form?.ok && _form.action === 'random' && typeof _form.data.value === 'number' ? _form.data.value : null;

  let currentValue = $state<number | null>(initialValue);
  let pending = $state(false);

  const handleRoll: MochiSubmitFunction<{ value: number }> = () => {
    pending = true;
    return ({ result }) => {
      pending = false;
      if (result.type === 'success' && result.data) {
        currentValue = result.data.value;
      }
    };
  };
</script>

<form method="POST" action="?/random" class="roll" {@attach enhance(handleRoll)}>
  <p class="label">{label}</p>
  <label>
    <span>Random number</span>
    <input type="text" readonly value={currentValue ?? ''} placeholder="(click roll)" />
  </label>
  <button type="submit" disabled={pending}>{pending ? 'Rolling…' : 'Roll'}</button>
</form>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, success } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/form-return-data': Mochi.page('./src/demos/form-return-data/FormReturnData.svelte', {
    actions: {
      random: () => success({ value: Math.floor(Math.random() * 100) + 1 }),
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: hello-world

### HelloWorld.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage title="Hello World" description="The simplest possible Mochi page — a Svelte component rendered on the server with no client-side JavaScript." {sources}>
  <p>Hello, world!</p>
</DemoPage>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/hello-world': Mochi.page('./src/demos/hello-world/HelloWorld.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: hydratable

### Hydratable.svelte
```svelte
<script lang="ts">
  import { hydratable } from 'svelte';
  import { Database } from 'bun:sqlite';
  import DemoPage from '../../components/DemoPage.svelte';
  import { sources } from './sources.prerender.ts';
  import FactCard from './FactCard.svelte';
  import FactCardProps from './FactCardProps.svelte';

  // With hydratable, the result is serialized into <head>; the matching call inside the hydrated
  // island below reads it back from window.__svelte.h instead of re-running this function on the client.
  const fact = await hydratable('mochi-demo:fact', () => {
    console.log('[server] computing fact via bun:sqlite (should print once per request)');
    const db = new Database(':memory:');
    const row = db.query("SELECT datetime('now') as now, sqlite_version() as version").get() as { now: string; version: string };
    db.close();
    return {
      sqliteVersion: row.version,
      computedAt: row.now,
    };
  });
</script>

<DemoPage
  title="Hydratable"
  description="hydratable() runs once on the server; the hydrated island reads the same value from <head> on the client without re-running the async work. Watch the server console — the 'computing fact' line prints once per request, never on hydration."
  {sources}
>
  <h3>Page (SSR-only)</h3>
  <p class="hint">Runs in the page's top-level script and is inlined into the rendered HTML.</p>
  <p class="row">SQLite <strong>{fact.sqliteVersion}</strong>, server time <code>{fact.computedAt}</code></p>

  <h3>Island using hydratable()</h3>
  <p class="hint">Reads the SSR value out of window.__svelte.h on the client without re-running the work.</p>
  <FactCard mochi:hydrate />

  <h3>Island using a prop</h3>
  <p class="hint">Receives the value as a prop; Mochi serialises it into the island's HTML.</p>
  <FactCardProps {fact} mochi:hydrate />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### FactCard.svelte
```svelte
<script lang="ts">
  import { hydratable } from 'svelte';

  // Same key as the page's `hydratable()` call, so this closure never actually runs — the throw
  // is an assertion that fires loudly if that invariant ever breaks.
  const fact = await hydratable<{ sqliteVersion: string; computedAt: string }>('mochi-demo:fact', () => {
    throw new Error('hydratable fallback should never run on this page');
  });

  let clicks = $state(0);
</script>

<div class="card">
  <p>SQLite <strong>{fact.sqliteVersion}</strong>, server time <code>{fact.computedAt}</code></p>
  <button onclick={() => clicks++}>Clicked {clicks} times</button>
</div>

<style>
  /* Styles omitted */
</style>
```

### FactCardProps.svelte
```svelte
<script lang="ts">
  // Alternative to `hydratable()`: the page computes `fact` server-side and passes it as a prop,
  // which Mochi devalue-serialises into the HTML and re-hydrates client-side without re-running the SSR work.
  let { fact }: { fact: { sqliteVersion: string; computedAt: string } } = $props();

  let clicks = $state(0);
</script>

<div class="card">
  <p>SQLite <strong>{fact.sqliteVersion}</strong>, server time <code>{fact.computedAt}</code></p>
  <button onclick={() => clicks++}>Clicked {clicks} times</button>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/hydratable': Mochi.page('./src/demos/hydratable/Hydratable.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: hydration

### Hydration.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import HydrationTarget from './HydrationTarget.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Hydration Modes"
  description="You can render components in multiple ways: pure SSR, mochi:hydrate, mochi:hydrate:visible (default and with rootMargin), and mochi:defer. Each card in the demo below turns green when it hydrates — click to confirm JavaScript has taken over. Scroll to reach the lazy islands."
  {sources}
>
  <section class="mode">
    <header>
      <h2>No directive</h2>
      <p>Pure SSR — no client JavaScript is shipped for this component. It renders on the server and is inert in the browser. Best for content that never needs interactivity.</p>
    </header>
    <HydrationTarget label="<HydrationTarget />" />
  </section>

  <section class="mode">
    <header>
      <h2>mochi:hydrate</h2>
      <p>Eager hydration — the island ships and boots immediately when the page loads. Use for above-the-fold UI that needs to be interactive right away.</p>
    </header>
    <HydrationTarget mochi:hydrate label="<HydrationTarget mochi:hydrate />" />
  </section>

  <section class="mode">
    <header>
      <h2>mochi:hydrate:visible</h2>
      <p>
        Lazy hydration — the bundle and CSS are only fetched once the island scrolls into view (via an <code>IntersectionObserver</code>). The card below stays inert until you
        scroll it into the viewport.
      </p>
    </header>
    <div class="spacer">
      <p>↓ Scroll down ↓</p>
    </div>
    <HydrationTarget mochi:hydrate:visible label="<HydrationTarget mochi:hydrate:visible />" />
  </section>

  <section class="mode">
    <header>
      <h2>mochi:hydrate:visible</h2>
      <p>
        You can pass <code>IntersectionObserver</code> options — here
        <code>rootMargin: '200px'</code>
        starts hydration a bit before the island is actually in view.
      </p>
    </header>
    <HydrationTarget mochi:hydrate:visible={{ rootMargin: '200px' }} label={`<HydrationTarget mochi:hydrate:visible={{ rootMargin: '200px' }} />`} />
  </section>

  <section class="mode">
    <header>
      <h2>mochi:defer</h2>
      <p>
        Server island — the component is <em>not</em> in the initial page. A placeholder ships, then the browser fetches the rendered HTML on demand. Pair with hydrated child components
        to also hydrate parts of the island after it loads.
      </p>
    </header>
    <HydrationTarget mochi:defer mochi:hydrate label="<HydrationTarget mochi:defer mochi:hydrate />">
      <div class="placeholder">Loading from server…</div>
    </HydrationTarget>
  </section>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### HydrationTarget.svelte
```svelte
<script lang="ts">
  import type { Snippet } from 'svelte';
  import { isBrowser } from 'mochi-framework';
  import Badge from '../../components/Badge.svelte';

  let { label = 'Target', children }: { label?: string; children?: Snippet } = $props();

  let count = $state(0);
  const renderedAt = new Date().toLocaleTimeString();
</script>

<div class="target" class:hydrated={isBrowser}>
  <div class="header">
    <span class="label">{label}</span>
    <Badge kind={isBrowser ? 'success' : 'info'}>
      {isBrowser ? 'hydrated' : 'server-rendered only'}
    </Badge>
  </div>
  <div class="meta">rendered at <code>{renderedAt}</code></div>
  <button onclick={() => count++}>
    Clicked {count}
    {count === 1 ? 'time' : 'times'}
  </button>
  {#if !isBrowser}
    <p class="note">This button won't work since the component is not hydrated!</p>
  {/if}
  {@render children?.()}
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/hydration': Mochi.page('./src/demos/hydration/Hydration.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: image

### ImageDemo.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import ImageCredits from '../../components/ImageCredits.svelte';
  import Callout from '../../../../docs/_components/Callout.svelte';
  import { sources } from './sources.prerender.ts';
  import ImageIslandCard from './ImageIslandCard.svelte';
  import { Image } from 'mochi-framework/image';
  import { getImageUrl, getImagePlaceholder } from 'mochi-framework';
  import { highlightCode } from '../../lib/highlight.server';
  import ArrowDown from '@lucide/svelte/icons/arrow-down';
  import hero from './hero.jpg';

  const remote = 'https://sta-public.fra1.cdn.digitaloceanspaces.com/mochi/mochi-1.jpg';

  const gallery = Array.from({ length: 14 }, (_, i) => `https://sta-public.fra1.cdn.digitaloceanspaces.com/mochi/mochi-${i + 1}.jpg`);

  // Near-instant: mints a signed URL for the "square" size; no fetch/resize
  // happens here — the endpoint runs it lazily on the browser's request.
  const directUrl = getImageUrl(remote, 'square');

  // No size name → a URL for the un-resized original (shared by every variant).
  const originalUrl = getImageUrl(remote);

  const blur = await getImagePlaceholder(remote);

  // Syntax highlighting is server-side, so these are computed once during SSR.
  const svelte = (code) => highlightCode(code, 'svelte');
  const ts = (code) => highlightCode(code, 'typescript');
  const codeComponent = await svelte('<Image src={photo} size="hero" alt="A resized photo" />');
  const codePlaceholder = await svelte('<Image src={photo} size="hero" placeholder alt="A resized photo" />');
  const codeIsland = await svelte('<ImageIslandCard mochi:hydrate src={photo} />');
  const codeProgrammatic = await ts("const url = getImageUrl(src, 'square');");
  const codeOriginal = await ts('const url = getImageUrl(src); // no size name → the original');
  const codeGallery = await svelte('{#each gallery as src (src)}\n  <Image {src} size="square" placeholder alt="Photo" />\n{/each}');
  const codeLocalImport = await ts("import hero from './hero.jpg';\n// hero → { src, width, height, format }");
  const codeLocalUsage = await svelte('<Image src={hero} size="hero" alt="A local image" />');
  const codeLocalBare = await svelte('<Image src={hero} alt="At natural size" />');
  const codeLocalImg = await svelte('<img src={hero.src} width={hero.width} height={hero.height} alt="" />');
</script>

<DemoPage
  title="Image: Component"
  description="On-the-fly image transforms on Bun.Image, served from an encrypted, stale-while-revalidate disk cache. Transforms are declared once as named sizes in Mochi.serve(); <Image> and getImageUrl() only mint a signed URL, and the endpoint runs the size lazily — so SSR never blocks on image work."
  {sources}
>
  <h3>Component</h3>
  <p>
    A plain <code>&lt;Image&gt;</code> references a named size (declared in <code>image.sizes</code>) and renders a single <code>&lt;img&gt;</code> with no client JS. Minting is synchronous
    — no image is fetched or resized during SSR:
  </p>
  <div class="frame">
    <Image src={remote} size="hero" alt="A resized random photo" />
  </div>
  <CodeSnippet html={codeComponent} />

  <h3>Local image imports</h3>
  <p>
    Import a local image Vite-style and get back <code>{'{ src, width, height, format }'}</code>. Pass the object straight to <code>&lt;Image&gt;</code> (transforms and
    <code>placeholder</code> work as usual), or drop <code>hero.src</code> into a plain <code>&lt;img&gt;</code>. The file is served from a content-hashed URL and read from disk
    for transforms — no network fetch:
  </p>
  <CodeSnippet html={codeLocalImport} />
  <div class="frame">
    <Image src={hero} size="hero" alt="A locally-imported photo, resized" />
  </div>
  <CodeSnippet html={codeLocalUsage} />
  <p>
    A bare <code>&lt;Image src={'{hero}'}&gt;</code> with no size renders the original at its intrinsic dimensions ({hero.width}&times;{hero.height}), straight from the static URL:
  </p>
  <div class="frame">
    <Image src={hero} alt="Local image at natural size" />
  </div>
  <CodeSnippet html={codeLocalBare} />
  <p>Or use <code>hero.src</code> directly — it's a real URL (<code>{hero.src}</code>):</p>
  <div class="frame">
    <img src={hero.src} width="300" alt="Via hero.src in a plain img" />
  </div>
  <CodeSnippet html={codeLocalImg} />

  <h3>With a blur placeholder</h3>
  <p>
    Add <code>placeholder</code> to show a ThumbHash blur behind the image — it's the <code>&lt;img&gt;</code>'s own <code>background-image</code>, so no client JS is needed. The
    blur is computed in the background on first use (never blocking SSR), so it appears from the second render onward:
  </p>
  {#if blur}
    <div class="frame blur-compare">
      <span class="blur-compare__placeholder" style:background-image="url({blur})" role="img" aria-label="ThumbHash blur placeholder"></span>
      <span class="blur-compare__arrow"><ArrowDown size={28} aria-hidden="true" /></span>
      <Image src={remote} size="hero" placeholder alt="A resized random photo with blur-up" />
    </div>
  {:else}
    <div class="frame">
      <Image src={remote} size="hero" alt="A resized random photo with blur-up" placeholder />
    </div>
  {/if}
  <CodeSnippet html={codePlaceholder} />

  <h3>Inside a hydrated island</h3>
  <p>
    <code>&lt;Image&gt;</code> also works inside a <code>mochi:hydrate</code> island: the server-minted URL is serialized into the page (via Svelte's
    <code>hydratable</code>) and reused during hydration, so the browser never needs the encryption secret. The button is live client-side state:
  </p>
  <div class="frame">
    <ImageIslandCard mochi:hydrate src={remote} />
  </div>
  <CodeSnippet html={codeIsland} />
  <Callout type="warning">
    Props passed to a hydrated island — like this card's <code>src</code> — are serialized in plain text into the page for hydration, so the source URL is visible to the client
    here. If your origin must stay secret, keep <code>&lt;Image&gt;</code> in server-rendered markup or a server island, whose props are encrypted.
  </Callout>

  <h3>Programmatic</h3>
  <p><code>getImageUrl(src, 'square')</code> returns the same encrypted URL you can use anywhere:</p>
  <pre class="url">{directUrl}</pre>
  <div class="frame">
    <img src={directUrl} width="400" alt="Resized via getImageUrl()" />
  </div>
  <CodeSnippet html={codeProgrammatic} />
  <p class="note">
    The <code>square</code> size uses <code>fit: 'inside'</code>, which preserves aspect ratio and fits <em>within</em> the 400&times;400 box — so this 3:2 photo becomes
    400&times;267. Set <code>fit: 'fill'</code> on the size to force an exact square (stretching); <code>Bun.Image</code> has no crop/cover mode.
  </p>

  <h3>Full-size original</h3>
  <p>
    <code>getImageUrl(src)</code> with no size name returns a URL for the un-resized original — fetched once and shared, so every variant above reuses this one cached download:
  </p>
  <pre class="url">{originalUrl}</pre>
  <div class="frame">
    <img src={originalUrl} width="400" alt="Full-size original via getImageUrl()" />
  </div>
  <CodeSnippet html={codeOriginal} />

  <h3>Gallery</h3>
  <p>
    Fourteen source photos, each rendered through the <code>square</code> size with a <code>placeholder</code> blur-up — all server-rendered, zero client JS:
  </p>
  <div class="grid">
    {#each gallery as src, i (src)}
      <Image {src} size="square" placeholder alt="Gallery photo {i + 1}" class="grid__img" />
    {/each}
  </div>
  <CodeSnippet html={codeGallery} />

  <ImageCredits />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### ImageIslandCard.svelte
```svelte
<script lang="ts">
  import { Image } from 'mochi-framework/image';
  import Heart from '@lucide/svelte/icons/heart';

  // <Image> detects the hydrating island by itself via isHydratable(), so its
  // server-minted URL is serialized for hydration without any prop forwarding.
  let { src }: { src: string } = $props();
  let likes = $state(42);
</script>

<div class="card">
  <Image {src} size="card" placeholder alt="A photo rendered inside a hydrated island" />
  <button class="card__btn" onclick={() => likes++}>
    <Heart size={16} aria-hidden="true" />
    {likes}
    {likes === 1 ? 'like' : 'likes'}
  </button>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/image': Mochi.page('./src/demos/image/ImageDemo.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  // Named image sizes — the URL only carries the src + size name, and the endpoint runs the transform lazily on request.
  image: {
    sizes: {
      hero: { width: 600, height: 400, fit: 'inside' },
      square: { width: 400, height: 400, fit: 'inside' },
      card: { width: 400, height: 267, fit: 'inside' },
      thumb: { width: 240, height: 240, fit: 'inside' },
      'fit-fill': { width: 240, height: 240, fit: 'fill' },
      'fit-inside': { width: 240, height: 240, fit: 'inside' },
      rotate90: { width: 200, height: 200, fit: 'inside', rotate: 90 },
      rotate180: { width: 200, height: 200, fit: 'inside', rotate: 180 },
      rotate270: { width: 200, height: 200, fit: 'inside', rotate: 270 },
      flip: { width: 200, height: 200, fit: 'inside', flip: true },
      flop: { width: 200, height: 200, fit: 'inside', flop: true },
      grayscale: { width: 200, height: 200, fit: 'inside', modulate: { saturation: 0 } },
      brighten: { width: 200, height: 200, fit: 'inside', modulate: { brightness: 1.5 } },
      saturate: { width: 200, height: 200, fit: 'inside', modulate: { saturation: 2 } },
      'fmt-jpeg': { width: 300, height: 300, fit: 'inside', format: 'jpeg', quality: 85 },
      'fmt-png': { width: 300, height: 300, fit: 'inside', format: 'png' },
      'fmt-webp': { width: 300, height: 300, fit: 'inside', format: 'webp', quality: 80 },
    },
  },
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: image-events

### ImageEvents.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import ImageCredits from '../../components/ImageCredits.svelte';
  import { sources } from './sources.prerender.ts';
  import { remote } from './log.ts';
  import { Image } from 'mochi-framework/image';
</script>

<DemoPage
  title="Image: Events"
  description="The <Image> cache emits image:store when it downloads an original, generates a resized variant, or computes a blur placeholder — and image:delete when a file is evicted, superseded, or invalidated. Subscribe on mochiEvents to mirror the cache to durable storage like S3. This demo logs every event to the server console with a [demo:image-events] prefix — load this page cold and watch your terminal."
  {sources}
>
  <p>
    Rendering this <code>&lt;Image&gt;</code> on a cold cache fetches the original, encodes a resized variant, and computes a ThumbHash placeholder — three
    <code>image:store</code> events, one per file written to disk:
  </p>
  <div class="frame">
    <Image src={remote} size="hero" placeholder alt="A resized random photo" />
  </div>
  <p class="hint">
    Each event carries the on-disk <code>path</code> plus <code>kind</code>, <code>src</code>, <code>size</code>, and (for variants) dimensions/format — everything an S3 mirror
    needs to upload the byte file. <code>image:delete</code> fires later, when the background janitor sweep evicts stale entries or you call
    <code>invalidateImage()</code>.
  </p>

  <ImageCredits />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### log.ts
```ts
import { mochiEvents, logger } from 'mochi-framework';

// A few source photos the page resizes on cold load, minting original + variant
// (+ placeholder) cache writes — each fires an `image:store` we log below.
export const remote = 'https://sta-public.fra1.cdn.digitaloceanspaces.com/mochi/mochi-3.jpg';

// This is exactly where an S3 mirror would read `path` and PUT/DELETE the object.
// `setHandler` (not `.on`) keeps dev re-imports from piling up duplicate subscribers.
mochiEvents.setHandler('demo:image-events:store', 'image:store', ({ kind, path, size, width, height }) => {
  const dims = width && height ? ` ${width}x${height}` : '';
  logger.info(`[demo:image-events] store  ${kind}${dims} (${size}B) → ${path}`);
});

mochiEvents.setHandler('demo:image-events:delete', 'image:delete', ({ kind, reason, path, size }) => {
  logger.info(`[demo:image-events] delete ${kind} (${reason}, freed ${size}B) → ${path}`);
});
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/image-events': Mochi.page('./src/demos/image-events/ImageEvents.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  // Named image sizes — the URL only carries the src + size name, and the endpoint runs the transform lazily on request.
  image: {
    sizes: {
      hero: { width: 600, height: 400, fit: 'inside' },
      square: { width: 400, height: 400, fit: 'inside' },
      card: { width: 400, height: 267, fit: 'inside' },
      thumb: { width: 240, height: 240, fit: 'inside' },
      'fit-fill': { width: 240, height: 240, fit: 'fill' },
      'fit-inside': { width: 240, height: 240, fit: 'inside' },
      rotate90: { width: 200, height: 200, fit: 'inside', rotate: 90 },
      rotate180: { width: 200, height: 200, fit: 'inside', rotate: 180 },
      rotate270: { width: 200, height: 200, fit: 'inside', rotate: 270 },
      flip: { width: 200, height: 200, fit: 'inside', flip: true },
      flop: { width: 200, height: 200, fit: 'inside', flop: true },
      grayscale: { width: 200, height: 200, fit: 'inside', modulate: { saturation: 0 } },
      brighten: { width: 200, height: 200, fit: 'inside', modulate: { brightness: 1.5 } },
      saturate: { width: 200, height: 200, fit: 'inside', modulate: { saturation: 2 } },
      'fmt-jpeg': { width: 300, height: 300, fit: 'inside', format: 'jpeg', quality: 85 },
      'fmt-png': { width: 300, height: 300, fit: 'inside', format: 'png' },
      'fmt-webp': { width: 300, height: 300, fit: 'inside', format: 'webp', quality: 80 },
    },
  },
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: image-invalidation

### ImageInvalidationDemo.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import { sources } from './sources.prerender.ts';
  import { getImageUrl } from 'mochi-framework';
  import RefreshCw from '@lucide/svelte/icons/refresh-cw';

  let { src, generation } = $props();

  const variants = [
    { size: 'hero', label: 'hero — 600×400', w: 600, h: 400 },
    { size: 'card', label: 'card — 400×267', w: 400, h: 267 },
    { size: 'thumb', label: 'thumb — 240×240', w: 240, h: 240 },
  ];

  // `invalidateImage()` clears the *server* cache; the `&g` nonce makes the browser
  // re-request the otherwise URL-stable images so the swap is visible immediately.
  const bust = (url) => `${url}&g=${generation}`;
  const originalUrl = bust(getImageUrl(src));
</script>

<DemoPage
  title="Image: Invalidation"
  description="Clear a cached image on demand with invalidateImage(). Our own source endpoint returns a random bundled photo on every fetch, so a hard invalidation — which drops the shared original and cascades to its variants — is visible the moment the sizes re-fetch together."
  {sources}
>
  <p>
    The images below all derive from <strong>one shared cached original</strong>, fetched from our own
    <code>/demos/image-invalidation/source.jpg</code> route — a <code>Mochi.file()</code> endpoint that serves a random bundled photo on every request. Hit the button to
    <code>invalidateImage(src, &lbrace; hard: true &rbrace;)</code>: it <strong>hard-deletes</strong> the cached original and cascades to every named size, so the next request
    re-fetches the source and <strong>all sizes update to the same new photo in lockstep</strong>.
  </p>

  <div class="actions">
    <form method="POST">
      <button type="submit">
        <RefreshCw size={16} aria-hidden="true" />
        Invalidate &amp; re-fetch
      </button>
    </form>
    {#if generation > 0}
      <span class="count">Invalidated {generation} time{generation === 1 ? '' : 's'}</span>
    {/if}
  </div>

  <h3>Shared original</h3>
  <div class="frame">
    <img src={originalUrl} alt="The shared cached original at full size" />
  </div>

  <h3>Named sizes off that original</h3>
  <p>Shown at their relative sizes on one row, so the difference is visible at a glance:</p>
  <div class="sizes">
    {#each variants as v (v.size)}
      <figure style:flex="{v.w} 1 0">
        <img src={bust(getImageUrl(src, v.size))} width={v.w} height={v.h} alt="{v.size} variant of the cached original" />
        <figcaption>{v.label}</figcaption>
      </figure>
    {/each}
  </div>

  <p class="note">
    <code>invalidateImage()</code> clears the cache on the <em>server</em>. A browser already holding a copy (via <code>Cache-Control</code> in production) keeps showing it until
    that lapses — so this demo appends a small <code>&amp;g=</code> nonce to force an immediate re-request. Pass <code>&lbrace; hard: false &rbrace;</code> (the default) instead to mark
    the original stale: the next request serves the cached bytes right away and re-fetches in the background.
  </p>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, invalidateImage, redirect, getRequestContext } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

// Our own source endpoint serves a *random* one of the bundled photos on each
// request, so an invalidated cache is visibly different once it's re-fetched.
const IMAGE_COUNT = 14;
const pickImage = () => `./images/mochi-${1 + Math.floor(Math.random() * IMAGE_COUNT)}.jpg`;

// The image source is our own endpoint, absolute so the image endpoint can fetch
// it. `.jpg` keeps it clear of the site's trailingSlash normalization.
const sourceUrl = () => `${getRequestContext().url.origin}/demos/image-invalidation/source.jpg`;

let generation = 0;

export const routes: Record<string, MochiRouteValue> = {
  '/demos/image-invalidation/source.jpg': Mochi.file(pickImage),

  '/demos/image-invalidation': Mochi.page('./src/demos/image-invalidation/ImageInvalidationDemo.svelte', {
    serverProps: () => ({ src: sourceUrl(), generation }),
    actions: {
      // Post/Redirect/Get so a refresh doesn't re-submit; the bumped `generation` rides through serverProps on the GET.
      default: async () => {
        await invalidateImage(sourceUrl(), { hard: true });
        generation++;
        return redirect(303, '/demos/image-invalidation/');
      },
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  // Named image sizes — the URL only carries the src + size name, and the endpoint runs the transform lazily on request.
  image: {
    sizes: {
      hero: { width: 600, height: 400, fit: 'inside' },
      square: { width: 400, height: 400, fit: 'inside' },
      card: { width: 400, height: 267, fit: 'inside' },
      thumb: { width: 240, height: 240, fit: 'inside' },
      'fit-fill': { width: 240, height: 240, fit: 'fill' },
      'fit-inside': { width: 240, height: 240, fit: 'inside' },
      rotate90: { width: 200, height: 200, fit: 'inside', rotate: 90 },
      rotate180: { width: 200, height: 200, fit: 'inside', rotate: 180 },
      rotate270: { width: 200, height: 200, fit: 'inside', rotate: 270 },
      flip: { width: 200, height: 200, fit: 'inside', flip: true },
      flop: { width: 200, height: 200, fit: 'inside', flop: true },
      grayscale: { width: 200, height: 200, fit: 'inside', modulate: { saturation: 0 } },
      brighten: { width: 200, height: 200, fit: 'inside', modulate: { brightness: 1.5 } },
      saturate: { width: 200, height: 200, fit: 'inside', modulate: { saturation: 2 } },
      'fmt-jpeg': { width: 300, height: 300, fit: 'inside', format: 'jpeg', quality: 85 },
      'fmt-png': { width: 300, height: 300, fit: 'inside', format: 'png' },
      'fmt-webp': { width: 300, height: 300, fit: 'inside', format: 'webp', quality: 80 },
    },
  },
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: image-pipeline

### ImagePipelineDemo.svelte
```svelte
<script module>
  import { getImageUrl, getImage } from 'mochi-framework';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';

  const CDN = 'https://sta-public.fra1.cdn.digitaloceanspaces.com/mochi';
  const srcUrl = (n) => `${CDN}/mochi-${n}.jpg`;

  const snippet = (code) => highlightCode(code, 'typescript');

  // Every URL + snippet below is request-independent, so compute the whole page once and cache the result.
  async function computePage() {
    const codeSetup = await snippet(
      [
        "import { getImageUrl, getImage } from 'mochi-framework';",
        '',
        '// Sizes are declared once in Mochi.serve({ image: { sizes } }).',
        '// getImageUrl mints a signed URL; the transform runs in the endpoint.',
        "const url = getImageUrl(src, 'thumb'); // near-instant, for <img src>",
        '',
        '// getImage runs the size inline and returns bytes + metadata.',
        "const { bytes, width, height, format } = await getImage(src, 'thumb');",
      ].join('\n'),
    );

    const metaImg = getImageUrl(srcUrl(1), 'thumb');
    const meta = await getImage(srcUrl(1), 'thumb');
    const codeMeta = await snippet("await getImage(src, 'thumb');\n// { bytes, width, height, format }");

    const fitFill = getImageUrl(srcUrl(2), 'fit-fill');
    const fitInside = getImageUrl(srcUrl(2), 'fit-inside');
    const codeFit = await snippet("getImageUrl(src, 'fit-inside');");

    const rotate90 = getImageUrl(srcUrl(4), 'rotate90');
    const rotate180 = getImageUrl(srcUrl(4), 'rotate180');
    const rotate270 = getImageUrl(srcUrl(4), 'rotate270');
    const codeRotate = await snippet("// sizes: { rotate90: { rotate: 90, … } }\ngetImageUrl(src, 'rotate90');");

    const flipOriginal = getImageUrl(srcUrl(5), 'fit-inside');
    const flipped = getImageUrl(srcUrl(5), 'flip');
    const flopped = getImageUrl(srcUrl(5), 'flop');
    const codeFlip = await snippet("// { flip: true } or { flop: true }\ngetImageUrl(src, 'flip');");

    const modGrey = getImageUrl(srcUrl(7), 'grayscale');
    const modBright = getImageUrl(srcUrl(7), 'brighten');
    const modSaturate = getImageUrl(srcUrl(7), 'saturate');
    const codeModulate = await snippet("// { modulate: { saturation: 0 } }\ngetImageUrl(src, 'grayscale');");

    // getImage runs each inline so we can report the encoded byte size; same source + size for a fair comparison.
    const FMT_SRC = 9;
    const fmtDefs = [
      { label: 'fmt-jpeg (q85)', name: 'fmt-jpeg' },
      { label: 'fmt-png', name: 'fmt-png' },
      { label: 'fmt-webp (q80)', name: 'fmt-webp' },
    ];
    const formats = await Promise.all(
      fmtDefs.map(async (d) => ({ label: d.label, url: getImageUrl(srcUrl(FMT_SRC), d.name), size: (await getImage(srcUrl(FMT_SRC), d.name)).bytes.length })),
    );
    const codeFormat = await snippet("const { bytes } = await getImage(src, 'fmt-webp');");

    return {
      codeSetup,
      metaImg,
      meta,
      codeMeta,
      fitFill,
      fitInside,
      codeFit,
      rotate90,
      rotate180,
      rotate270,
      codeRotate,
      flipOriginal,
      flipped,
      flopped,
      codeFlip,
      modGrey,
      modBright,
      modSaturate,
      codeModulate,
      formats,
      codeFormat,
    };
  }

  // In-process layer: assemble the page (incl. syntax highlighting) once per
  // process; the image cache is the persistent, cross-restart layer underneath.
  let built;
  export function buildPage() {
    return (built ??= computePage());
  }
</script>

<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import ImageCredits from '../../components/ImageCredits.svelte';

  const kb = (bytes) => `${(bytes / 1024).toFixed(1)} KB`;

  const {
    codeSetup,
    metaImg,
    meta,
    codeMeta,
    fitFill,
    fitInside,
    codeFit,
    rotate90,
    rotate180,
    rotate270,
    codeRotate,
    flipOriginal,
    flipped,
    flopped,
    codeFlip,
    modGrey,
    modBright,
    modSaturate,
    codeModulate,
    formats,
    codeFormat,
  } = await buildPage();
</script>

<DemoPage
  title="Image: Named sizes"
  description="Transforms are declared once as named sizes under image.sizes in Mochi.serve() and referenced by name. getImageUrl(src, name) mints a signed URL and the /_mochi/image endpoint runs the size lazily — so SSR never blocks. getImage(src, name) is the inline escape hatch that returns the transformed bytes + metadata, used below for dimensions and byte sizes."
  {sources}
>
  <p>
    Each example references a size by name. <code>getImageUrl</code> is synchronous — it only signs a URL; the fetch, decode, and transform happen in the endpoint on the browser's
    request, cached on disk so later requests skip the work. <code>getImage</code> runs the same size inline when you need the bytes server-side.
  </p>
  <CodeSnippet html={codeSetup} />

  <h3>Metadata</h3>
  <p><code>getImage()</code> returns the transformed bytes plus dimensions and format:</p>
  <CodeSnippet html={codeMeta} />
  <div class="row">
    <div class="cell">
      <img src={metaImg} alt="Rendered via the thumb size" />
      <span class="cap"><code>{meta.width} × {meta.height}</code> · <code>{meta.format}</code></span>
    </div>
  </div>

  <h3>Resize · fit</h3>
  <p>The same source into a 240×240 box. <code>fit: 'fill'</code> stretches to the exact box; <code>fit: 'inside'</code> preserves aspect ratio and fits within it:</p>
  <CodeSnippet html={codeFit} />
  <div class="row">
    <div class="cell"><img src={fitFill} alt="fit fill" /><span class="cap"><code>fit: 'fill'</code></span></div>
    <div class="cell"><img src={fitInside} alt="fit inside" /><span class="cap"><code>fit: 'inside'</code></span></div>
  </div>

  <h3>Rotate</h3>
  <p>A size's <code>rotate</code> turns the image clockwise in multiples of 90:</p>
  <CodeSnippet html={codeRotate} />
  <div class="row">
    <div class="cell"><img src={rotate90} alt="rotated 90 degrees" /><span class="cap"><code>rotate: 90</code></span></div>
    <div class="cell"><img src={rotate180} alt="rotated 180 degrees" /><span class="cap"><code>rotate: 180</code></span></div>
    <div class="cell"><img src={rotate270} alt="rotated 270 degrees" /><span class="cap"><code>rotate: 270</code></span></div>
  </div>

  <h3>Flip · flop</h3>
  <p><code>flip: true</code> mirrors vertically (about the x-axis); <code>flop: true</code> mirrors horizontally:</p>
  <CodeSnippet html={codeFlip} />
  <div class="row">
    <div class="cell"><img src={flipOriginal} alt="original" /><span class="cap">original</span></div>
    <div class="cell"><img src={flipped} alt="flipped" /><span class="cap"><code>flip</code></span></div>
    <div class="cell"><img src={flopped} alt="flopped" /><span class="cap"><code>flop</code></span></div>
  </div>

  <h3>Modulate</h3>
  <p>A size's <code>modulate</code> adjusts brightness and saturation (<code>1</code> = unchanged):</p>
  <CodeSnippet html={codeModulate} />
  <div class="row">
    <div class="cell"><img src={modGrey} alt="greyscale" /><span class="cap"><code>saturation: 0</code></span></div>
    <div class="cell"><img src={modBright} alt="brightened" /><span class="cap"><code>brightness: 1.5</code></span></div>
    <div class="cell"><img src={modSaturate} alt="saturated" /><span class="cap"><code>saturation: 2</code></span></div>
  </div>

  <h3>Output formats</h3>
  <p>The same 300px image through three format sizes, with byte sizes from <code>getImage()</code>. <code>Bun.Image</code> can also encode <code>avif</code>:</p>
  <CodeSnippet html={codeFormat} />
  <div class="row">
    {#each formats as { label, url, size } (label)}
      <div class="cell">
        <img src={url} alt={label} />
        <span class="cap"><code>{label}</code> · {kb(size)}</span>
      </div>
    {/each}
  </div>

  <ImageCredits />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/image-pipeline': Mochi.page('./src/demos/image-pipeline/ImagePipelineDemo.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  // Named image sizes — the URL only carries the src + size name, and the endpoint runs the transform lazily on request.
  image: {
    sizes: {
      hero: { width: 600, height: 400, fit: 'inside' },
      square: { width: 400, height: 400, fit: 'inside' },
      card: { width: 400, height: 267, fit: 'inside' },
      thumb: { width: 240, height: 240, fit: 'inside' },
      'fit-fill': { width: 240, height: 240, fit: 'fill' },
      'fit-inside': { width: 240, height: 240, fit: 'inside' },
      rotate90: { width: 200, height: 200, fit: 'inside', rotate: 90 },
      rotate180: { width: 200, height: 200, fit: 'inside', rotate: 180 },
      rotate270: { width: 200, height: 200, fit: 'inside', rotate: 270 },
      flip: { width: 200, height: 200, fit: 'inside', flip: true },
      flop: { width: 200, height: 200, fit: 'inside', flop: true },
      grayscale: { width: 200, height: 200, fit: 'inside', modulate: { saturation: 0 } },
      brighten: { width: 200, height: 200, fit: 'inside', modulate: { brightness: 1.5 } },
      saturate: { width: 200, height: 200, fit: 'inside', modulate: { saturation: 2 } },
      'fmt-jpeg': { width: 300, height: 300, fit: 'inside', format: 'jpeg', quality: 85 },
      'fmt-png': { width: 300, height: 300, fit: 'inside', format: 'png' },
      'fmt-webp': { width: 300, height: 300, fit: 'inside', format: 'webp', quality: 80 },
    },
  },
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: is-hydratable

### IsHydratable.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import HydrationProbe from './HydrationProbe.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="isHydratable()"
  description="isHydratable() reports whether the calling component is part of a subtree that will hydrate on this page load — at any nesting depth, with no prop forwarding. The same three-level probe is rendered four ways."
  {sources}
>
  <section class="mode">
    <header>
      <h2><code>mochi:hydrate</code></h2>
      <p>The island root seeds the whole subtree: every depth reports <code>true</code>.</p>
    </header>
    <HydrationProbe mochi:hydrate />
  </section>

  <section class="mode">
    <header>
      <h2>Plain SSR</h2>
      <p>The same tree without a directive never hydrates: every depth reports <code>false</code>.</p>
    </header>
    <HydrationProbe />
  </section>

  <section class="mode">
    <header>
      <h2><code>mochi:defer</code></h2>
      <p>A pure server island is fetched as HTML and never hydrates, so it also reports <code>false</code> — deferred is not hydrated.</p>
    </header>
    <HydrationProbe mochi:defer />
  </section>

  <section class="mode">
    <header>
      <h2><code>mochi:defer mochi:hydrate</code></h2>
      <p>An also-hydrated server island takes over after the fetch, so every depth reports <code>true</code>.</p>
    </header>
    <HydrationProbe mochi:defer mochi:hydrate />
  </section>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### HydrationProbe.svelte
```svelte
<script lang="ts">
  import { isHydratable } from 'mochi-framework';
  import Badge from '../../components/Badge.svelte';
  import Self from './HydrationProbe.svelte';

  let { depth = 1, max = 3 }: { depth?: number; max?: number } = $props();

  const hydratable = isHydratable();
</script>

<div class="probe">
  <div class="row">
    <div class="label">
      <span class="name">Depth {depth}</span>
      <code>isHydratable()</code>
    </div>
    <Badge kind={hydratable ? 'success' : 'info'}>{String(hydratable)}</Badge>
  </div>
  {#if depth < max}
    <Self depth={depth + 1} {max} />
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/is-hydratable': Mochi.page('./src/demos/is-hydratable/IsHydratable.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: island-depth

### IslandDepth.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import DepthLevel1 from './DepthLevel1.svelte';
  import FailDeep from './FailDeep.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Nested Island Max Depth"
  description={"Server islands can nest to any depth, and by default Mochi inlines nested mochi:defer islands into their parent's fetch: one request returns the whole four-level chain, rendered in a single server pass. Opt out per call site with mochi:defer={{ inline: false }} to keep each level on its own fetch — its HTML then arrives with a placeholder that fetches the next level in turn, useful when a slow child shouldn't delay the parent's content. The flag is threaded down every level here, since an opt-out only applies to the call site it's written on. Either way the prebuild precompiles every level into the manifest in a single pass, so no level compiles on a request path in production."}
  {sources}
>
  <p class="delay-note">
    Each level is delayed on purpose — and twice as long in the opted-out chain, so the loading pattern is easy to follow. The opted-out chain fetches level by level; the inlined
    chain makes one fetch that takes roughly the sum of its delays.
  </p>

  <div class="chains">
    <section>
      <h3>Opted out — waterfall <code>{'{{ inline: false }}'}</code></h3>
      <DepthLevel1 mochi:defer={{ inline: false }} inline={false}>
        <div class="island-loading">Loading level 1<span class="dots"></span></div>
      </DepthLevel1>
    </section>
    <section>
      <h3>Inlined — one fetch <code>{'{{ inline: true }}'}</code></h3>
      <DepthLevel1 mochi:defer={{ inline: true }} inline={true}>
        <div class="island-loading">Loading levels 1–4<span class="dots"></span></div>
      </DepthLevel1>
    </section>
  </div>

  <section class="failures">
    <h3>Failure modes</h3>
    <p class="delay-note">
      A child that throws during its inline attempt degrades to a placeholder and fetches on its own — the parent's content is never lost. AlwaysThrows fails its fetch too and
      renders the failure stub; ThrowsWhenInlined only throws while being inlined, so its own fetch succeeds and the content still arrives.
    </p>
    <FailDeep mochi:defer>
      <div class="island-loading">Loading FailDeep<span class="dots"></span></div>
    </FailDeep>
  </section>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### DepthLevel1.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';
  import DepthLevel2 from './DepthLevel2.svelte';

  let { inline = true } = $props();

  await (isServer ? delay(inline ? 300 : 600, inline ? 600 : 1200) : Promise.resolve());
</script>

<div class="level level-1">
  <p><strong>Level 1</strong> — server island (<code>mochi:defer</code>). It nests one more:</p>
  <DepthLevel2 mochi:defer={{ inline }} {inline}>
    <div class="island-loading">Loading level 2<span class="dots"></span></div>
  </DepthLevel2>
</div>

<style>
  /* Styles omitted */
</style>
```

### DepthLevel2.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';
  import DepthLevel3 from './DepthLevel3.svelte';

  let { inline = true } = $props();

  await (isServer ? delay(inline ? 300 : 600, inline ? 600 : 1200) : Promise.resolve());
</script>

<div class="level level-2">
  <p><strong>Level 2</strong> — server island (<code>mochi:defer</code>). It nests one more:</p>
  <DepthLevel3 mochi:defer={{ inline }} {inline}>
    <div class="island-loading">Loading level 3<span class="dots"></span></div>
  </DepthLevel3>
</div>

<style>
  /* Styles omitted */
</style>
```

### DepthLevel3.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';
  import DepthLevel4 from './DepthLevel4.svelte';

  let { inline = true } = $props();

  await (isServer ? delay(inline ? 300 : 600, inline ? 600 : 1200) : Promise.resolve());
</script>

<div class="level level-3">
  <p><strong>Level 3</strong> — server island (<code>mochi:defer</code>). It nests one more:</p>
  <DepthLevel4 mochi:defer={{ inline }} {inline}>
    <div class="island-loading">Loading level 4<span class="dots"></span></div>
  </DepthLevel4>
</div>

<style>
  /* Styles omitted */
</style>
```

### DepthLevel4.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';

  let { inline = true } = $props();

  await (isServer ? delay(inline ? 300 : 600, inline ? 600 : 1200) : Promise.resolve());
</script>

<div class="level level-4">
  <p><strong>Level 4</strong> — deepest server island (<code>mochi:defer</code>). No more nesting below.</p>
</div>

<style>
  /* Styles omitted */
</style>
```

### FailDeep.svelte
```svelte
<script>
  import AlwaysThrows from './AlwaysThrows.svelte';
  import ThrowsWhenInlined from './ThrowsWhenInlined.svelte';
</script>

<div class="level">
  <p><strong>FailDeep</strong> — this parent island's content stays intact while both children fail their inline attempt:</p>
  <AlwaysThrows mochi:defer>
    <div class="island-loading">Waiting for AlwaysThrows<span class="dots"></span></div>
  </AlwaysThrows>
  <ThrowsWhenInlined mochi:defer>
    <div class="island-loading">Waiting for ThrowsWhenInlined<span class="dots"></span></div>
  </ThrowsWhenInlined>
</div>

<style>
  /* Styles omitted */
</style>
```

### AlwaysThrows.svelte
```svelte
<script>
  const boom = () => {
    throw new Error('AlwaysThrows: deliberate server failure');
  };
</script>

<p>{boom()}</p>
```

### ThrowsWhenInlined.svelte
```svelte
<script>
  import { getRequestContext } from 'mochi-framework';

  const { url } = getRequestContext();
  if (!url.pathname.includes('/island/ThrowsWhenInlined')) {
    throw new Error('ThrowsWhenInlined: failing the inline attempt');
  }
</script>

<div class="recovered">
  <p><strong>ThrowsWhenInlined</strong> — threw during the inline attempt, degraded to a placeholder, and its own fetch succeeded.</p>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/island-depth': Mochi.page('./src/demos/island-depth/IslandDepth.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: island-props

### ServerRenderedParent.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import ClientRenderedChild from './ClientRenderedChild.svelte';
  import { typeOf } from './devalueTypeOf.ts';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';

  const codeProps = await highlightCode(
    `const dateVal = new Date('2025-01-15T12:00:00Z');
const mapVal = new Map([['a', 1], ['b', 2], ['c', 3]]);
const setVal = new Set([10, 20, 30]);
const bigintVal = 9007199254740993n;
const urlVal = new URL('https://mochi.dev/docs?version=5');
// ...
const cyclic: { name: string; self?: unknown } = { name: 'cyclic' };
cyclic.self = cyclic;
const cyclicRef = cyclic;`,
    'ts',
  );

  const shared = { x: 1 };
  const cyclic: { name: string; self?: unknown } = { name: 'cyclic' };
  cyclic.self = cyclic;

  const dateVal = new Date('2025-01-15T12:00:00Z');
  const regexpVal = /hello\s+world/gi;
  const mapVal = new Map<string, number>([
    ['a', 1],
    ['b', 2],
    ['c', 3],
  ]);
  const setVal = new Set([10, 20, 30]);
  const bigintVal = 9007199254740993n;
  const urlVal = new URL('https://mochi.dev/docs?version=5');
  const searchParamsVal = new URLSearchParams('theme=dark&lang=en');
  const typedArrayVal = new Uint8Array([72, 101, 108, 108, 111]);
  const undefinedVal = undefined;
  const infinityVal = Infinity;
  const nanVal = NaN;
  const negZeroVal = -0;
  const repeatedRef = [shared, shared];
  const cyclicRef = cyclic;

  const serverTypes: Record<string, string> = {
    Date: typeOf(dateVal),
    RegExp: typeOf(regexpVal),
    Map: typeOf(mapVal),
    Set: typeOf(setVal),
    BigInt: typeOf(bigintVal),
    URL: typeOf(urlVal),
    URLSearchParams: typeOf(searchParamsVal),
    Uint8Array: typeOf(typedArrayVal),
    undefined: typeOf(undefinedVal),
    Infinity: typeOf(infinityVal),
    NaN: typeOf(nanVal),
    '-0': typeOf(negZeroVal),
    'Repeated ref': typeOf(repeatedRef),
    'Cyclic ref': typeOf(cyclicRef),
  };
</script>

<DemoPage
  title="Crossing the server-client boundary with props"
  description="Props you pass from a server-rendered parent to a hydrated child island are automatically serialized via devalue, preserving Date, RegExp, Map, Set, BigInt, URL, typed arrays, undefined, Infinity, NaN, -0, and even repeated and cyclic references — all reconstructed identically on the client."
  {sources}
>
  <section class="parent">
    <header>
      <h2>ServerRenderedParent.svelte</h2>
      <p>
        Runs only on the server. No <code>mochi:hydrate</code> directive, so this component ships zero JavaScript — its output is inert HTML. It builds a props bag covering every
        type devalue supports and hands it off to the child below. The <code>Server type</code> column in the child is captured here, before serialization; the
        <code>Client type</code> column is resolved after hydration. Matching values prove the round-trip preserved each type.
      </p>
    </header>
    <CodeSnippet html={codeProps} />
  </section>

  <div class="arrow" aria-hidden="true">
    <span>props</span>
    <span class="line"></span>
    <span class="head">▼</span>
  </div>

  <ClientRenderedChild
    {dateVal}
    {regexpVal}
    {mapVal}
    {setVal}
    {bigintVal}
    {urlVal}
    {searchParamsVal}
    {typedArrayVal}
    {undefinedVal}
    {infinityVal}
    {nanVal}
    {negZeroVal}
    {repeatedRef}
    {cyclicRef}
    {serverTypes}
    mochi:hydrate
  />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### ClientRenderedChild.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';
  import Badge from '../../components/Badge.svelte';
  import { typeOf } from './devalueTypeOf.ts';

  let {
    dateVal,
    regexpVal,
    mapVal,
    setVal,
    bigintVal,
    urlVal,
    searchParamsVal,
    typedArrayVal,
    undefinedVal,
    infinityVal,
    nanVal,
    negZeroVal,
    repeatedRef,
    cyclicRef,
    serverTypes,
  }: {
    dateVal: Date;
    regexpVal: RegExp;
    mapVal: Map<string, number>;
    setVal: Set<number>;
    bigintVal: bigint;
    urlVal: URL;
    searchParamsVal: URLSearchParams;
    typedArrayVal: Uint8Array;
    undefinedVal: undefined;
    infinityVal: number;
    nanVal: number;
    negZeroVal: number;
    repeatedRef: { x: number }[];
    cyclicRef: { name: string; self?: unknown };
    serverTypes: Record<string, string>;
  } = $props();

  function display(v: unknown): string {
    if (v === undefined) {
      return 'undefined';
    }
    if (v === null) {
      return 'null';
    }
    if (typeof v === 'number') {
      if (Number.isNaN(v)) {
        return 'NaN';
      }
      if (v === Infinity) {
        return 'Infinity';
      }
      if (Object.is(v, -0)) {
        return '-0';
      }
    }
    if (typeof v === 'bigint') {
      return `${v}n`;
    }
    if (v instanceof Date) {
      return v.toISOString();
    }
    if (v instanceof RegExp) {
      return String(v);
    }
    if (v instanceof Map) {
      return `Map(${v.size}) { ${[...v.entries()].map(([k, val]) => `${k} => ${val}`).join(', ')} }`;
    }
    if (v instanceof Set) {
      return `Set(${v.size}) { ${[...v].join(', ')} }`;
    }
    if (v instanceof URL) {
      return v.href;
    }
    if (v instanceof URLSearchParams) {
      return v.toString();
    }
    if (v instanceof Uint8Array) {
      return `Uint8Array [${[...v].join(', ')}]`;
    }
    if (Array.isArray(v)) {
      return JSON.stringify(v);
    }
    if (typeof v === 'object' && v !== null) {
      if ((v as { self?: unknown }).self === v) {
        return '{ self: [Circular] }';
      }
      return JSON.stringify(v);
    }
    return String(v);
  }

  // svelte-ignore state_referenced_locally
  const rows = [
    { label: 'Date', value: dateVal },
    { label: 'RegExp', value: regexpVal },
    { label: 'Map', value: mapVal },
    { label: 'Set', value: setVal },
    { label: 'BigInt', value: bigintVal },
    { label: 'URL', value: urlVal },
    { label: 'URLSearchParams', value: searchParamsVal },
    { label: 'Uint8Array', value: typedArrayVal },
    { label: 'undefined', value: undefinedVal },
    { label: 'Infinity', value: infinityVal },
    { label: 'NaN', value: nanVal },
    { label: '-0', value: negZeroVal },
    { label: 'Repeated ref', value: repeatedRef },
    { label: 'Cyclic ref', value: cyclicRef },
  ];
</script>

<div class="target" class:hydrated={isBrowser}>
  <div class="header">
    <span class="title">ClientRenderedChild.svelte</span>
    <Badge kind={isBrowser ? 'success' : 'info'}>
      {isBrowser ? 'Client (hydrated)' : 'Server (SSR)'}
    </Badge>
  </div>

  <table>
    <thead>
      <tr>
        <th>Prop</th>
        <th>Value</th>
        <th>Server type</th>
        <th>Client type</th>
      </tr>
    </thead>
    <tbody>
      {#each rows as row (row.label)}
        <tr>
          <td class="label"><code>{row.label}</code></td>
          <td class="value"><code>{display(row.value)}</code></td>
          <td class="type"><code>{serverTypes[row.label] ?? '—'}</code></td>
          <td class="type"><code>{isBrowser ? typeOf(row.value) : '—'}</code></td>
        </tr>
      {/each}
      <tr>
        <td class="label"><code>Repeated ref</code></td>
        <td class="value"><code>{repeatedRef[0] === repeatedRef[1] ? 'same ref' : 'different refs'}</code></td>
        <td class="type"><code>identity check</code></td>
        <td class="type"><code>{isBrowser ? 'identity check' : '—'}</code></td>
      </tr>
      <tr>
        <td class="label"><code>Cyclic ref</code></td>
        <td class="value"><code>{cyclicRef.self === cyclicRef ? 'self === obj' : 'broken'}</code></td>
        <td class="type"><code>identity check</code></td>
        <td class="type"><code>{isBrowser ? 'identity check' : '—'}</code></td>
      </tr>
    </tbody>
  </table>
</div>

<style>
  /* Styles omitted */
</style>
```

### devalueTypeOf.ts
```ts
export function typeOf(v: unknown): string {
  if (v === undefined) {
    return 'undefined';
  }
  if (v === null) {
    return 'null';
  }
  if (typeof v === 'bigint') {
    return 'BigInt';
  }
  if (typeof v === 'number') {
    if (Number.isNaN(v)) {
      return 'NaN';
    }
    if (v === Infinity) {
      return 'Infinity';
    }
    if (Object.is(v, -0)) {
      return '-0';
    }
  }
  if (v instanceof Date) {
    return 'Date';
  }
  if (v instanceof RegExp) {
    return 'RegExp';
  }
  if (v instanceof Map) {
    return 'Map';
  }
  if (v instanceof Set) {
    return 'Set';
  }
  if (v instanceof URL) {
    return 'URL';
  }
  if (v instanceof URLSearchParams) {
    return 'URLSearchParams';
  }
  if (v instanceof Uint8Array) {
    return 'Uint8Array';
  }
  if (ArrayBuffer.isView(v)) {
    return (v as { constructor: { name: string } }).constructor.name;
  }
  if (Array.isArray(v)) {
    return 'Array';
  }
  return typeof v;
}
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/island-props': Mochi.page('./src/demos/island-props/ServerRenderedParent.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: lazy

### Lazy.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import LazyDemo from './LazyDemo.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Lazy Islands"
  description="You can mark islands with mochi:hydrate:visible so each one fetches its JS and CSS only when it scrolls into view, via an IntersectionObserver. Lazy islands also have the benefit of not loading their CSS until they come into view, great for secondary content far down the page."
  {sources}
>
  <div class="stack">
    {#each Array(6) as _, i (i)}
      <div class="item">
        <h3>Lazy Island #{i + 1}</h3>
        <LazyDemo mochi:hydrate:visible index={i + 1} />
      </div>
    {/each}
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### LazyDemo.svelte
```svelte
<script>
  import { isBrowser } from 'mochi-framework';

  let { index = 0 } = $props();
  const rand = isBrowser ? Math.random().toFixed(4) : null;
</script>

<div class="lazy-demo">
  <span class="index">#{index}</span>
  {#if isBrowser}
    <span class="status hydrated">Hydrated! {rand}</span>
  {:else}
    <span class="status waiting">Waiting to hydrate...</span>
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/lazy': Mochi.page('./src/demos/lazy/Lazy.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: lazy-server-island

### LazyServerIsland.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import LazyServerDemo from './LazyServerDemo.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Lazy Server Islands"
  description="Server islands marked with mochi:defer:visible only fetch their HTML when the wrapper scrolls into view, via an IntersectionObserver. Each island is fetched independently from /_mochi/island/... — open the Network panel and scroll to watch the requests fire on demand. The first island uses rootMargin to start fetching 200px before it enters the viewport."
  {sources}
>
  <p class="hint">Scroll down to trigger each fetch. The IntersectionObserver fires per-island.</p>

  <div class="stack">
    <div class="item">
      <h3>Island #1 — <code>rootMargin: '200px'</code></h3>
      <LazyServerDemo mochi:defer:visible={{ rootMargin: '200px' }} index={1}>
        <div class="island-loading">Loading server island<span class="dots"></span></div>
      </LazyServerDemo>
    </div>

    {#each [2, 3, 4, 5] as i (i)}
      <div class="spacer"></div>
      <div class="item">
        <h3>Island #{i}</h3>
        <LazyServerDemo mochi:defer:visible index={i}>
          <div class="island-loading">Loading server island<span class="dots"></span></div>
        </LazyServerDemo>
      </div>
    {/each}
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### LazyServerDemo.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';

  let { index = 0 } = $props();

  await (isServer ? delay(200, 600) : Promise.resolve());

  const renderedAt = new Date().toLocaleTimeString();
</script>

<div class="lazy-server">
  <span class="index">#{index}</span>
  <span class="status">Fetched at {renderedAt}</span>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/lazy-server-island': Mochi.page('./src/demos/lazy-server-island/LazyServerIsland.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: login

### Login.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import EnhancedLoginForm from './EnhancedLoginForm.svelte';
  import { sources } from './sources.prerender.ts';

  let { currentUser }: { currentUser: string | null } = $props();
</script>

<DemoPage
  title="Form Actions"
  description={`Forms can render as plain HTML forms or progressively enhanced forms powered by JavaScript. Plain HTML does a full POST and page re-render; {@attach enhance(...)} submits via fetch and updates the UI in place. Sign in with any username / hunter2 as a password.`}
  {sources}
>
  <h3>With <code>{'{@attach enhance(...)}'}</code></h3>
  <EnhancedLoginForm initialUser={currentUser} mochi:hydrate />
  <h3>Plain HTML</h3>
  <EnhancedLoginForm initialUser={currentUser} />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### EnhancedLoginForm.svelte
```svelte
<script lang="ts">
  import { enhance, isServer, getRequestContext, isHydratable } from 'mochi-framework';
  import type { MochiEnhanceOptions, MochiSubmitFunction } from 'mochi-framework';

  let { initialUser }: { initialUser: string | null } = $props();

  const hydratable = isHydratable();
  // For SSR-only (plain HTML) renders, read the form action result so errors
  // and the prefilled username survive the re-render after a failed POST.
  const _form = !hydratable && isServer ? getRequestContext().form : null;
  const _failData = _form && !_form.ok ? _form.data : null;

  // initialUser is the SSR snapshot — local state takes over after hydration.
  // svelte-ignore state_referenced_locally
  let currentUser = $state(initialUser);
  let errorMessage = $state<string | null>(typeof _failData?.error === 'string' ? _failData.error : null);
  const prefillUsername = typeof _failData?.username === 'string' ? _failData.username : '';
  let pending = $state(false);

  const handleLogin: MochiSubmitFunction<{ username: string }, { error: string; username: string }> = () => {
    errorMessage = null;

    return ({ result, formElement }) => {
      if (result.type === 'success' && result.data) {
        currentUser = result.data.username;
        errorMessage = null;
        formElement.reset();
      } else if (result.type === 'failure' && result.data) {
        errorMessage = result.data.error;
      } else if (result.type === 'error') {
        errorMessage = 'Network error. Try again.';
      }
    };
  };

  const loginEnhanceOpts: MochiEnhanceOptions<{ username: string }, { error: string; username: string }> = {
    submit: handleLogin,
    onPending: (v) => {
      pending = v;
    },
  };
</script>

{#if currentUser}
  <div class="signed-in">
    <p>Signed in as <strong>{currentUser}</strong>.{hydratable ? ' No page reloads happened on the way here.' : ''}</p>
    <!-- No callback needed — the default redirect fallback (window.location.assign) already handles logout. -->
    <form method="POST" action="?/logout" {@attach enhance()}>
      <button type="submit">Log out</button>
    </form>
  </div>
{:else}
  <form method="POST" action="?/default" class="login" {@attach enhance(loginEnhanceOpts)}>
    <label>
      <span>Username</span>
      <input name="username" value={prefillUsername} disabled={pending} required />
    </label>
    <label>
      <span>Password</span>
      <input name="password" type="password" disabled={pending} required />
    </label>
    <div class="submit-row">
      <button type="submit" disabled={pending}>{pending ? 'Signing in…' : 'Log in'}</button>
      {#if errorMessage}
        <p class="error" role="alert">{errorMessage}</p>
      {/if}
    </div>
    <p class="hint">The password is <code>hunter2</code>. Any username works.</p>
  </form>
{/if}

<style>
  /* Styles omitted */
</style>
```

### session.ts
```ts
import { createHmac, timingSafeEqual } from 'node:crypto';
import { getMochiConfig } from 'mochi-framework';

const CONTEXT = 'mochi-demo-session';
const DEFAULT_MAX_AGE_SEC = 7 * 24 * 60 * 60;

function sign(data: string): string {
  const { secretKey } = getMochiConfig();
  return createHmac('sha256', secretKey).update(CONTEXT).update(':').update(data).digest().subarray(0, 16).toString('base64url');
}

export interface SessionData {
  username: string;
  exp: number;
}

export function createSessionToken(username: string, maxAgeSec: number = DEFAULT_MAX_AGE_SEC): { token: string; maxAgeSec: number; exp: number } {
  const exp = Math.floor(Date.now() / 1000) + maxAgeSec;
  const payload = Buffer.from(JSON.stringify({ username, exp })).toString('base64url');
  return { token: `${payload}.${sign(payload)}`, maxAgeSec, exp };
}

export function verifySessionToken(token: string | undefined): SessionData | null {
  if (!token) {
    return null;
  }
  const dot = token.lastIndexOf('.');
  if (dot === -1) {
    return null;
  }

  const payload = token.slice(0, dot);
  const sig = token.slice(dot + 1);
  const expected = sign(payload);

  if (sig.length !== expected.length) {
    return null;
  }
  try {
    if (!timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
      return null;
    }
  } catch {
    return null;
  }

  let parsed: SessionData;
  try {
    parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf-8'));
  } catch {
    return null;
  }
  if (typeof parsed.username !== 'string' || typeof parsed.exp !== 'number') {
    return null;
  }
  if (parsed.exp < Math.floor(Date.now() / 1000)) {
    return null;
  }

  return parsed;
}
```

### routes.ts
```ts
import { Mochi, fail, redirect, success, getRequestContext } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';
import { createSessionToken, verifySessionToken } from './session';

const SESSION_COOKIE = 'mochi_login_session';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/login': Mochi.page('./src/demos/login/Login.svelte', {
    serverProps: () => {
      const { cookies } = getRequestContext();
      const session = verifySessionToken(cookies.get(SESSION_COOKIE));
      return { currentUser: session?.username ?? null };
    },
    actions: {
      default: async ({ formData, cookies }) => {
        const username = String(formData.get('username') ?? '').trim();
        const password = String(formData.get('password') ?? '');
        if (!username) {
          return fail(400, { error: 'Username required', username });
        }
        if (password !== 'hunter2') {
          return fail(401, { error: 'Bad credentials', username });
        }
        const { token, maxAgeSec } = createSessionToken(username);
        cookies.set(SESSION_COOKIE, token, {
          path: '/',
          httpOnly: true,
          sameSite: 'Lax',
          maxAge: maxAgeSec,
        });
        return success({ username });
      },
      logout: async ({ cookies }) => {
        cookies.delete(SESSION_COOKIE, { path: '/' });
        return redirect(303, '/demos/login');
      },
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: mdsvex

### Greeting.md
```svelte
<script>
  let { name = 'world' } = $props();
  const renderedAt = new Date().toISOString();
</script>

## Hello, {name}!

This block was authored in **Markdown** but compiled into a Svelte component
via [`mdsvex`](https://mdsvex.pngwn.io/), so prose, _emphasis_, `inline code`,
and a normal Svelte `<script>` block all coexist.

Headings get `id` attributes via `rehype-slug`, so this section is linkable as
`#hello-name`. The page was rendered at:

> {renderedAt}
```

### Snippet.svx
```svelte
<script>
  let { items = [] } = $props();
</script>

### A `.svx` file

Same compile pipeline as `.md` — mdsvex accepts both extensions. This snippet
shows a fenced code block (run through the framework's syntax highlighter)
plus a Svelte `{#each}` loop driven by a prop:

```ts
const items = ['Hydration', 'CSS imports', 'MdSvex'];
```

<ol>
  {#each items as item}
    <li>{item}</li>
  {/each}
</ol>
```

### MdsvexDemo.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import { sources } from './sources.prerender.ts';
  import Greeting from './Greeting.md';
  import Snippet from './Snippet.svx';
</script>

<DemoPage
  title="MdSvex"
  description="`.md` and `.svx` files compile through mdsvex into Svelte components — pass them anywhere a `.svelte` component is accepted, or import them as children."
  {sources}
>
  <div class="mdsvex-output">
    <Greeting name="Mochi" />
    <hr />
    <Snippet items={['Hydration', 'CSS imports', 'MdSvex']} />
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/mdsvex': Mochi.page('./src/demos/mdsvex/MdsvexDemo.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: mode-watcher

### ModeWatcher.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import ModeControls from './ModeControls.svelte';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';

  let { initialMode = null } = $props();

  const codeInstall = await highlightCode('bun add mode-watcher', 'bash');
  const codeUsage = await highlightCode(
    `import { ModeWatcher, toggleMode } from 'mode-watcher';

// Mount ModeWatcher once; it applies the mode to <html>.
// <ModeWatcher />
// <button onclick={toggleMode}>Toggle</button>`,
    'typescript',
  );
  const codeSsr = await highlightCode(
    `// routes.ts — read the cookie server-side, feed it to <ModeWatcher> as defaultMode
Mochi.page('./ModeWatcher.svelte', {
  serverProps: () => ({ initialMode: cookies.get('mochi-demo-theme') }),
});

// and set the class on <html> before the page is sent — so there's no flash:
export const handle = async ({ event, resolve }) => {
  const dark = getRequestContext().cookies.get('mochi-demo-theme') === 'dark';
  return resolve(event, dark
    ? { transformPage: ({ html }) => html.replace('<html lang="en">', '<html lang="en" class="dark">') }
    : undefined);
};

// island — mirror the mode back into the cookie whenever it changes (isomorphic cookies API)
$effect(() => {
  if (mode.current) cookies.set('mochi-demo-theme', mode.current, { expires: 365 });
});`,
    'typescript',
  );
</script>

<DemoPage
  title="Mode Watcher"
  description="mode-watcher manages light/dark mode by mutating the global <html> element. Because it reads the DOM and localStorage, the whole thing lives in a mochi:hydrate island — the page renders on the server, then mode-watcher takes over on the client."
  {sources}
>
  <div class="intro">
    <p>
      <code>mode-watcher</code> needs a little setup: you mount its <code>&lt;ModeWatcher /&gt;</code> component once, and it reads <code>localStorage</code> and applies the mode
      to the global <code>&lt;html&gt;</code> element — adding a
      <code>dark</code> class and setting <code>color-scheme</code>. This site drives its own theme off a
      <code>data-theme</code> attribute, so the two coexist without collision.
    </p>
    <CodeSnippet html={codeInstall} />
    <p>Mount it once, then any button can drive the mode:</p>
    <CodeSnippet html={codeUsage} />
    <p>
      Full API at <a href="https://mode-watcher.dev" target="_blank" rel="noopener noreferrer">mode-watcher.dev</a>.
    </p>
  </div>

  <section class="card">
    <header>
      <h2>Toggle &amp; set the mode</h2>
      <p>
        <code>toggleMode</code>, <code>setMode</code>, and <code>resetMode</code> drive the global theme; the
        <code>mode</code>, <code>userPrefersMode</code>, and <code>systemPrefersMode</code> runes report the current state.
      </p>
    </header>
    <ModeControls {initialMode} mochi:hydrate />
  </section>

  <section class="card">
    <header>
      <h2>SSR-friendly theme, no flash</h2>
      <p>
        mode-watcher only persists to <code>localStorage</code>, which the server can't read — so on its own the first paint can flash. The bar above fixes that: the island mirrors
        the resolved mode into a cookie, <code>serverProps</code>
        reads it back into <code>&lt;ModeWatcher defaultMode&gt;</code>, and a <code>transformPage</code> hook stamps
        <code>class="dark"</code> onto <code>&lt;html&gt;</code> before the response is sent. Pick a mode, then reload — the page comes back correct with no flicker (<code
          >server sent:</code
        >
        shows the value the server used).
        <code>"system"</code> can't be server-resolved without JS, so the cookie stores the resolved
        <code>light</code>/<code>dark</code>.
      </p>
    </header>
    <CodeSnippet html={codeSsr} />
  </section>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### ModeControls.svelte
```svelte
<script lang="ts">
  import { ModeWatcher, toggleMode, setMode, resetMode, mode, userPrefersMode, systemPrefersMode } from 'mode-watcher';
  import { cookies, isBrowser } from 'mochi-framework';
  import Sun from '@lucide/svelte/icons/sun';
  import Moon from '@lucide/svelte/icons/moon';
  import Badge from '../../components/Badge.svelte';
  import { THEME_COOKIE } from './constants';

  let { initialMode = null }: { initialMode?: string | null } = $props();

  const defaultMode = $derived(initialMode === 'light' || initialMode === 'dark' ? initialMode : 'system');

  // mode.current is undefined during SSR and until mode-watcher resolves on the client. Fall back to
  // the cookie value the server used so the switch renders its final state right away — no flash.
  const shownMode = $derived(mode.current ?? (initialMode === 'dark' ? 'dark' : 'light'));

  // Mirror the resolved mode into a cookie so the server can render the right theme next time —
  // mode-watcher itself only persists to localStorage, which the server can't read.
  $effect(() => {
    const m = mode.current;
    if (isBrowser && (m === 'light' || m === 'dark')) {
      cookies.set(THEME_COOKIE, m, { expires: 365, path: '/demos/mode-watcher/', sameSite: 'Lax' });
    }
  });
</script>

<ModeWatcher {defaultMode} />

<header class="ssr-header">
  <div class="ssr-copy">
    <strong>SSR theme</strong>
    <span>server-rendered from a cookie — no flash on reload</span>
  </div>
  <div class="ssr-controls">
    <code>server sent: {initialMode ?? '(no cookie yet)'}</code>
    <button class="switch" onclick={toggleMode}>
      {#if shownMode === 'dark'}
        <Sun size={15} /> Light
      {:else}
        <Moon size={15} /> Dark
      {/if}
    </button>
  </div>
</header>

<div class="grid">
  <div class="card">
    <div class="head">
      <h3>toggleMode</h3>
      <span class="hint">flip the global &lt;html&gt; between light and dark</span>
    </div>
    <div class="preview">
      <span class="dot"></span>
      {#if mode.current}
        <Badge kind={mode.current === 'dark' ? 'info' : 'success'}>{mode.current}</Badge>
      {:else}
        <Badge kind="warning">undefined (server)</Badge>
      {/if}
    </div>
    <button class="primary" onclick={toggleMode}>Toggle mode</button>
  </div>

  <div class="card">
    <div class="head">
      <h3>setMode / resetMode</h3>
      <span class="hint">user pick vs resolved vs OS</span>
    </div>
    <div class="actions">
      <button onclick={() => setMode('light')}>Light</button>
      <button onclick={() => setMode('dark')}>Dark</button>
      <button onclick={resetMode}>System</button>
    </div>
    <dl class="readout">
      <div>
        <dt>userPrefersMode</dt>
        <dd>{userPrefersMode.current}</dd>
      </div>
      <div>
        <dt>mode (resolved)</dt>
        <dd>{mode.current ?? '—'}</dd>
      </div>
      <div>
        <dt>systemPrefersMode</dt>
        <dd>{systemPrefersMode.current ?? '—'}</dd>
      </div>
    </dl>
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, getRequestContext } from 'mochi-framework';
import type { MochiRouteValue, Handle } from 'mochi-framework';
import { THEME_COOKIE } from './constants';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/mode-watcher': Mochi.page('./src/demos/mode-watcher/ModeWatcher.svelte', {
    serverProps: () => ({ initialMode: getRequestContext().cookies.get(THEME_COOKIE) ?? null }),
  }),
};

// SSR the resolved theme: read the cookie the island mirrors the mode into, and set the `dark`
// class on <html> before it's sent so the first paint already matches — no flash on reload.
export const handle: Handle = async ({ event, resolve }) => {
  if (!event.url.pathname.startsWith('/demos/mode-watcher')) {
    return resolve(event);
  }
  if (getRequestContext().cookies.get(THEME_COOKIE) !== 'dark') {
    return resolve(event);
  }
  return resolve(event, {
    transformPage: ({ html }) => html.replace('<html lang="en">', '<html lang="en" class="dark">'),
  });
};
```

### constants.ts
```ts
// Shared by routes.ts (server read) and ModeControls.svelte (client write) so the name can't drift.
export const THEME_COOKIE = 'mochi-demo-theme';
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: nested-components

### NestedComponents.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import Level from './Level.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Nested Components"
  description="Hydrating a component with mochi:hydrate automatically hydrates all its children. Nested mochi:hydrate directives are forbidden and result in a fatal error."
  {sources}
>
  <section class="mode">
    <header>
      <h2><code>mochi:hydrate</code> on the root</h2>
      <p>One island wraps the whole five-level tree. Mochi serializes the root and its descendants once, ships a single bundle, and Svelte hydrates the entire subtree together.</p>
    </header>
    <Level mochi:hydrate />
  </section>

  <section class="mode">
    <header>
      <h2><code>mochi:defer</code> + <code>mochi:hydrate</code></h2>
      <p>
        The same recursive tree, rendered lazily as a server island. The placeholder ships with the page; the browser fetches the rendered HTML on demand. Because <code
          >mochi:hydrate</code
        > is also set, Svelte takes over once the fetched markup lands.
      </p>
    </header>
    <Level mochi:defer mochi:hydrate>
      <div class="placeholder">Loading nested tree from server<span class="dots"></span></div>
    </Level>
  </section>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### Level.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';
  import Badge from '../../components/Badge.svelte';
  import Self from './Level.svelte';

  let { depth = 1, max = 5 }: { depth?: number; max?: number } = $props();

  let Next = $state(Self);
  let count = $state(0);

  const tag = $derived(depth === 1 ? ' (root)' : depth === max ? ' (leaf)' : '');
</script>

<div class="level" class:hydrated={isBrowser}>
  <div class="header">
    <span class="name">Level {depth}{tag}</span>
    <Badge kind={isBrowser ? 'success' : 'info'}>
      {isBrowser ? 'hydrated' : 'SSR only'}
    </Badge>
  </div>
  <button onclick={() => count++}>L{depth} clicked {count} {count === 1 ? 'time' : 'times'}</button>
  {#if depth < max}
    <Next depth={depth + 1} {max} />
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/nested-components': Mochi.page('./src/demos/nested-components/NestedComponents.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: nested-islands

### NestedIslands.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import DeferWithHydrators from './DeferWithHydrators.svelte';
  import DeferNest from './DeferNest.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Nested Islands"
  description="Server islands can contain other islands. The first example is a mochi:defer server island wrapping several mochi:hydrate components — the deferred fetch delivers them, then each counter hydrates on its own. The second nests two more islands inside a mochi:defer server island: another mochi:defer server island and a mochi:defer mochi:hydrate one. Open the debug bar (bottom toolbar) to see each island accounted for exactly once."
  {sources}
>
  <p class="delay-note">The islands below are delayed on purpose to show the loading state.</p>

  <h3>1. mochi:defer server island with mochi:hydrate components inside</h3>
  <DeferWithHydrators mochi:defer>
    <div class="island-loading">Loading server island<span class="dots"></span></div>
  </DeferWithHydrators>

  <div class="spacer"></div>

  <h3>2. mochi:defer server island nesting two more islands</h3>
  <DeferNest mochi:defer>
    <div class="island-loading">Loading server island<span class="dots"></span></div>
  </DeferNest>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### DeferWithHydrators.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';
  import Counter from './Counter.svelte';

  await (isServer ? delay(800, 1500) : Promise.resolve());

  const renderedAt = new Date().toLocaleTimeString();
</script>

<div class="defer-box">
  <p>Server island (<code>mochi:defer</code>), rendered at {renderedAt}.</p>
  <p>It contains three independently hydrated counters — click them:</p>
  <div class="row">
    <Counter mochi:hydrate label="Alpha" />
    <Counter mochi:hydrate label="Beta" />
    <Counter mochi:hydrate label="Gamma" />
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### Counter.svelte
```svelte
<script>
  let { label = 'Counter' } = $props();
  let count = $state(0);
</script>

<button class="counter" onclick={() => count++}>{label}: <strong>{count}</strong></button>

<style>
  /* Styles omitted */
</style>
```

### DeferNest.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';
  import InnerServer from './InnerServer.svelte';
  import HydratedServer from './HydratedServer.svelte';

  await (isServer ? delay(800, 1500) : Promise.resolve());
</script>

<div class="defer-box">
  <p>Outer server island (<code>mochi:defer</code>). It nests two more islands:</p>
  <InnerServer mochi:defer label="Inner server island">
    <div class="island-loading">Loading inner server island<span class="dots"></span></div>
  </InnerServer>
  <HydratedServer mochi:defer mochi:hydrate label="Inner hydrated server island">
    <div class="island-loading">Loading hydrated server island<span class="dots"></span></div>
  </HydratedServer>
</div>

<style>
  /* Styles omitted */
</style>
```

### InnerServer.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';

  let { label = 'Inner server island' } = $props();
  const islandId = $props.id();

  await (isServer ? delay(600, 1200) : Promise.resolve());

  const randomNumber = Math.floor(Math.random() * 1000);
</script>

<div class="inner-server">
  <p>{label} (<code>mochi:defer</code>)</p>
  <p class="meta">Random number from the server: <strong>{randomNumber}</strong></p>
  <p class="meta">$props.id(): <strong>{islandId}</strong></p>
</div>

<style>
  /* Styles omitted */
</style>
```

### HydratedServer.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';

  let { label = 'Hydrated server island' } = $props();
  const islandId = $props.id();

  await (isServer ? delay(600, 1200) : Promise.resolve());

  let count = $state(0);
</script>

<div class="hydrated-server">
  <p>{label} (<code>mochi:defer mochi:hydrate</code>)</p>
  <p class="meta">$props.id(): <strong>{islandId}</strong></p>
  <button onclick={() => count++}>Hydrated, clicked <strong>{count}</strong> times</button>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/nested-islands': Mochi.page('./src/demos/nested-islands/NestedIslands.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: portable-text

### PortableTextDemo.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import Callout from '../../../../docs/_components/Callout.svelte';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';
  import { playgroundJson } from './blocks.ts';
  import Playground from './Playground.svelte';

  const sv = (code: string) => highlightCode(code, 'svelte');
  const ts = (code: string) => highlightCode(code, 'typescript');

  const codeInstall = await highlightCode('bun add @portabletext/svelte', 'bash');
  const codeImport = await ts("import { PortableText } from '@portabletext/svelte';");
  const codeBasic = await sv('<PortableText value={blocks} />');
  const codePair = await sv('<Playground source={playgroundJson} />\n<Playground mochi:hydrate source={playgroundJson} />');
</script>

<DemoPage
  title="Portable Text"
  description="@portabletext/svelte renders Portable Text — the JSON format editors like Sanity emit for rich text — by mapping each block, mark, style and list onto a Svelte component you own."
  {sources}
>
  <p>
    Portable Text stores rich text as an array of JSON blocks instead of HTML, so the same content can render to a web page, a PDF or a native app. <a
      href="https://github.com/portabletext/svelte-portabletext"
      target="_blank"
      rel="noopener noreferrer">@portabletext/svelte</a
    >
    is the official Svelte 5 renderer for it; the format itself is documented at
    <a href="https://portabletext.org" target="_blank" rel="noopener noreferrer">portabletext.org</a>. Everything on this page is server-rendered by Mochi except the last section.
  </p>

  <h3>Install</h3>
  <CodeSnippet html={codeInstall} />
  <CodeSnippet html={codeImport} />
  <CodeSnippet html={codeBasic} />

  <h3>The same renderer, hydrated and not</h3>
  <p>
    Both panels below are the same component rendered from the same JSON. The left one is plain SSR markup; the right one carries <code>mochi:hydrate</code>, so the renderer ships
    to the browser and re-runs on every keystroke.
  </p>
  <div class="pair">
    <Playground source={playgroundJson} />
    <Playground mochi:hydrate source={playgroundJson} />
  </div>
  <CodeSnippet html={codePair} />
  <Callout type="info">
    Hydration is all-or-nothing per island: the right panel ships <code>@portabletext/svelte</code> plus every component it references, and its props are serialized in plain text into
    the page. The left panel ships nothing.
  </Callout>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### blocks.ts
```ts
import type { InputValue } from '@portabletext/svelte';

// Every block and span carries an explicit _key: the renderer mints Math.random() keys for
// missing ones, which would differ between the server render and the hydrated one.

export const playground = [
  {
    _type: 'block',
    _key: 'pg1',
    style: 'h3',
    children: [{ _type: 'span', _key: 'pg1s1', text: 'A rendered heading' }],
  },
  {
    _type: 'block',
    _key: 'pg2',
    style: 'normal',
    children: [
      { _type: 'span', _key: 'pg2s1', text: 'A paragraph with a ' },
      { _type: 'span', _key: 'pg2s2', text: 'highlighted', marks: ['highlight'] },
      { _type: 'span', _key: 'pg2s3', text: ' word.' },
    ],
  },
  { _type: 'callout', _key: 'pg3', text: 'And a custom callout block.' },
] satisfies InputValue;

export const playgroundJson = JSON.stringify(playground, null, 2);
```

### CalloutBlock.svelte
```svelte
<script lang="ts">
  import type { CustomBlockComponentProps } from '@portabletext/svelte';
  import Info from '@lucide/svelte/icons/info';

  type Callout = { tone?: string; text?: string };

  let { portableText }: { portableText: CustomBlockComponentProps<Callout> } = $props();

  let { value, isInline } = $derived(portableText);
</script>

{#if isInline}
  <span class="pt-callout inline"><Info size={13} aria-hidden="true" />{value.text}</span>
{:else}
  <aside class="pt-callout">
    <Info size={15} aria-hidden="true" />
    <span>{value.text}</span>
    {#if value.tone}
      <span class="tone">{value.tone}</span>
    {/if}
  </aside>
{/if}

<style>
  /* Styles omitted */
</style>
```

### Highlight.svelte
```svelte
<script lang="ts">
  import type { MarkComponentProps } from '@portabletext/svelte';
  import type { Snippet } from 'svelte';

  // A decorator has no markDef, so `portableText.value` is undefined here.
  let { children }: { portableText: MarkComponentProps<'highlight'>; children: Snippet } = $props();
</script>

<mark>{@render children()}</mark>

<style>
  /* Styles omitted */
</style>
```

### Playground.svelte
```svelte
<script lang="ts">
  import { PortableText } from '@portabletext/svelte';
  import type { InputValue } from '@portabletext/svelte';
  import { isHydratable } from 'mochi-framework';
  import Badge from '../../components/Badge.svelte';
  import CalloutBlock from './CalloutBlock.svelte';
  import Highlight from './Highlight.svelte';

  let { source }: { source: string } = $props();

  const live = isHydratable();
  const uid = $props.id();

  // svelte-ignore state_referenced_locally
  let text = $state(source);
  let parsed = $derived.by(() => {
    try {
      return { value: JSON.parse(text) as InputValue, error: null };
    } catch (e) {
      return { value: null, error: (e as Error).message };
    }
  });
</script>

<div class="playground">
  <div class="head">
    <Badge kind={live ? 'success' : 'info'}>{live ? 'mochi:hydrate' : 'SSR only'}</Badge>
    <span class="note">{live ? 'edit the JSON — the output re-renders' : 'no JavaScript shipped — the field is read-only'}</span>
  </div>

  <label class="sr-only" for="pt-source-{uid}">Portable Text JSON</label>
  <textarea id="pt-source-{uid}" bind:value={text} readonly={!live} spellcheck="false" rows="12"></textarea>

  {#if parsed.error}
    <p class="error">{parsed.error}</p>
  {/if}

  <div class="output">
    <PortableText value={parsed.value ?? []} components={{ types: { callout: CalloutBlock }, marks: { highlight: Highlight } }} onMissingComponent={false} />
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/portable-text': Mochi.page('./src/demos/portable-text/PortableTextDemo.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: prop-dedup

### PropDedup.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import SharedPropsCard from './SharedPropsCard.svelte';
  import { sources } from './sources.prerender.ts';

  // Each payload is reused across three cards so Mochi dedupes it into one hoisted `<script type="application/json">` block instead of shipping it three times.
  const groups = [
    {
      heading: 'Group A — recipes',
      props: {
        label: '<SharedPropsCard /> · A',
        theme: { bg: '#1d2a23', fg: '#e6f1ea', accent: '#7fc89a' },
        items: [
          { id: 1, text: 'Boil water for tea' },
          { id: 2, text: 'Steep matcha 90s' },
          { id: 3, text: 'Whisk into oat milk' },
        ],
      },
    },
    {
      heading: 'Group B — TODOs',
      props: {
        label: '<SharedPropsCard /> · B',
        theme: { bg: '#26221d', fg: '#f1ece3', accent: '#d8a55c' },
        items: [
          { id: 1, text: 'Reply to design review' },
          { id: 2, text: 'Bump devalue to 5.x' },
          { id: 3, text: 'Triage prop-dedup PR' },
          { id: 4, text: 'Push staging deploy' },
        ],
      },
    },
    {
      heading: 'Group C — track',
      props: {
        label: '<SharedPropsCard /> · C',
        theme: { bg: '#1f242c', fg: '#e6ecf5', accent: '#7fa8d8' },
        items: [
          { id: 1, text: 'Distance: 5.4 km' },
          { id: 2, text: 'Pace: 5:42 / km' },
          { id: 3, text: 'HR avg: 152 bpm' },
        ],
      },
    },
  ];
</script>

<DemoPage
  title="Shared Props"
  description="When two or more islands share the same props (as serialized by devalue), the props are deduplicated to avoid shipping the same payload two or more times in one page load."
  {sources}
>
  <p class="hint">
    Each group below renders the same component three times with the same props. In the SSR: you'll find <strong>three</strong>
    <code>&lt;script type="application/json"&gt;</code>
    blocks (one per group) and nine <code>&lt;mochi-hydratable-island props-ref="…"&gt;</code> tags pointing at them. Each shared block carries a <code>data-shared</code> marker; a lone
    island (like the source code viewer on this page) still gets its own block, just without that marker.
  </p>

  {#each groups as group (group.heading)}
    <section class="group">
      <h3>{group.heading}</h3>
      <div class="row">
        <SharedPropsCard mochi:hydrate {...group.props} />
        <SharedPropsCard mochi:hydrate {...group.props} />
        <SharedPropsCard mochi:hydrate {...group.props} />
      </div>
    </section>
  {/each}
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### SharedPropsCard.svelte
```svelte
<script lang="ts">
  type Item = { id: number; text: string };
  type Theme = { bg: string; fg: string; accent: string };

  let {
    label,
    theme,
    items,
  }: {
    label: string;
    theme: Theme;
    items: Item[];
  } = $props();
</script>

<article class="card" style="--bg: {theme.bg}; --fg: {theme.fg}; --accent: {theme.accent};">
  <span class="label">{label}</span>
  <ul>
    {#each items as item (item.id)}
      <li>{item.text}</li>
    {/each}
  </ul>
</article>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/prop-dedup': Mochi.page('./src/demos/prop-dedup/PropDedup.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: props-id

### PropsId.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import { sources } from './sources.prerender.ts';
  import Field from './Field.svelte';
  import LabeledField from './LabeledField.svelte';
  import ServerStamp from './ServerStamp.svelte';
  import ServerHydratedStamp from './ServerHydratedStamp.svelte';
  import ClientStamp from './ClientStamp.svelte';
</script>

<DemoPage
  title="Unique IDs"
  description="Svelte's native $props.id() generates an id unique to each component instance, consistent between server render and hydration — use it for label/for and aria links inside islands."
  {sources}
>
  <h3>Static component (no hydration)</h3>
  <p class="hint">$props.id() works with zero JavaScript shipped — the id is minted during SSR, no hydration required.</p>
  <Field />

  <h3>Two hydrated islands, two ids</h3>
  <p class="hint">Each instance gets its own id, so the label/for pairs never collide. Hydration reuses the server-generated value — the id you see was minted during SSR.</p>
  <LabeledField mochi:hydrate />
  <LabeledField mochi:hydrate />

  <h3>Server island</h3>
  <p class="hint">
    Deferred islands render in a separate request; Mochi namespaces their ids with the island's own id (via render's idPrefix) so they cannot collide with ids already on the page.
  </p>
  <ServerStamp mochi:defer />

  <h3>Server island that also hydrates</h3>
  <p class="hint">
    With <code>mochi:defer mochi:hydrate</code> the namespaced id is read back from the SSR markers when the fragment hydrates — click the button and the id stays exactly the same, proving
    the value survived from the deferred render into the hydrated client.
  </p>
  <ServerHydratedStamp mochi:defer mochi:hydrate />

  <h3>Two client-only islands, two ids</h3>
  <p class="hint">
    Client-only islands are never server-rendered, so each <code>$props.id()</code> is minted in the browser at mount. Svelte draws these from a global counter — unique even across
    separate
    <code>mount()</code> calls — so two independently-mounted islands still get distinct ids (e.g. <code>c1</code> and <code>c2</code>) without any SSR pass to keep them apart.
  </p>
  <ClientStamp mochi:clientOnly />
  <ClientStamp mochi:clientOnly />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### Field.svelte
```svelte
<script lang="ts">
  import type { Snippet } from 'svelte';

  let { children }: { children?: Snippet<[string]> } = $props();
  const uid = $props.id();
</script>

<div class="card">
  {@render children?.(uid)}
  <p class="uid">$props.id(): <code>{uid}</code></p>
</div>

<style>
  /* Styles omitted */
</style>
```

### LabeledField.svelte
```svelte
<script lang="ts">
  import Field from './Field.svelte';

  let value = $state('');
</script>

<Field>
  {#snippet children(uid)}
    <label for="{uid}-name">Name</label>
    <input id="{uid}-name" type="text" bind:value placeholder="Type here…" />
    <button onclick={() => document.getElementById(`${uid}-name`)?.focus()}>Focus input via its id</button>
  {/snippet}
</Field>

<style>
  /* Styles omitted */
</style>
```

### ServerStamp.svelte
```svelte
<script lang="ts">
  import Field from './Field.svelte';
</script>

<Field>
  <p>Rendered on demand in a separate request 🏝️</p>
</Field>

<style>
  /* Styles omitted */
</style>
```

### ServerHydratedStamp.svelte
```svelte
<script lang="ts">
  import Field from './Field.svelte';

  let clicks = $state(0);
</script>

<Field>
  <p>Rendered on the server, then hydrated 🏝️⚡</p>
  <button onclick={() => clicks++}>Clicked {clicks} times</button>
</Field>

<style>
  /* Styles omitted */
</style>
```

### ClientStamp.svelte
```svelte
<script lang="ts">
  import Field from './Field.svelte';
</script>

<Field>
  <p>Never server-rendered — the id is minted in the browser at mount 🏝️🖥️</p>
</Field>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/props-id': Mochi.page('./src/demos/props-id/PropsId.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: protection

### Protection.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import ApiProbe from './ApiProbe.svelte';
  import { sources } from './sources.prerender.ts';
  import type { MochiFormResult } from 'mochi-framework';

  let { form }: { form: MochiFormResult } = $props();
</script>

<DemoPage
  title="Protection Mode"
  description="A Cloudflare-style browser check on your own infrastructure. Unverified visitors get an interstitial that auto-solves the captcha proof-of-work and redeems it for a signed clearance cookie — no third party, no tracking."
  {sources}
>
  <p>
    <strong>This very page is protected</strong> — the interstitial you just passed (or breezed through on a warm clearance) came from
    <code>Mochi.serve(&lbrace; protection &rbrace;)</code>. The first visit answers 403 with a verification page instead of the demo; a hidden
    <code>MochiCaptchaAuto</code> island runs the hash chain and proof-of-work immediately. The clearance is a signed
    <code>HttpOnly</code> cookie, so every later request just passes.
  </p>
  <p>
    <code>protect()</code> is an optional callback that picks what's gated; without it every route is protected. This site protects only this demo page and its API — the rest of the
    site never sees the interstitial.
  </p>

  <ApiProbe mochi:hydrate />

  <form method="POST" action="?/reset">
    <button type="submit">Reset clearance</button>
    {#if form?.ok && form.action === 'reset'}
      <span class="cleared">Clearance cookie deleted — reload the page to meet the interstitial again.</span>
    {/if}
  </form>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### ApiProbe.svelte
```svelte
<script lang="ts">
  let status = $state<number | null>(null);
  let body = $state('');
  let busy = $state(false);

  async function probe() {
    busy = true;
    try {
      const res = await fetch('/demos/protection/api');
      status = res.status;
      body = await res.text();
    } catch (e) {
      status = null;
      body = e instanceof Error ? e.message : String(e);
    } finally {
      busy = false;
    }
  }
</script>

<div class="probe">
  <button type="button" onclick={probe} disabled={busy}>Call protected API</button>
  {#if status !== null || body}
    <pre class:blocked={status !== 200}>{status ?? 'error'} — {body}</pre>
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, success, PROTECTION_CLEARANCE_COOKIE } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/protection': Mochi.page('./src/demos/protection/Protection.svelte', {
    actions: {
      reset: async ({ cookies }) => {
        cookies.delete(PROTECTION_CLEARANCE_COOKIE, { path: '/' });
        return success({ cleared: true });
      },
    },
  }),
  '/demos/protection/api': Mochi.api(async () => Response.json({ ok: true, message: 'You are cleared — this API answered.' })),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  protection: {
    enabled: true,
    // Without protect(), EVERY route requires browser verification. Here only
    // this demo's page and its API are gated.
    protect: ({ path }) => path === '/demos/protection' || path === '/demos/protection/' || path.startsWith('/demos/protection/api'),
    // Proof-of-work difficulty in leading zero bits — each extra bit doubles the work.
    bits: 20,
    // How long a passed verification lasts before the interstitial shows again.
    maxAgeMs: 4 * 60 * 60 * 1000,
  },
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: queue

### Queue.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import QueueWidget from './QueueWidget.svelte';
  import { sources } from './sources.prerender.ts';
  import type { QueueStatus } from './types.ts';

  let { initial, suggestedUser }: { initial: QueueStatus; suggestedUser: string } = $props();
</script>

<DemoPage
  title="Background jobs with queues"
  description="A Mochi.queue(name) bundles a job channel with its process() consumer, declared once in the Mochi.serve() queues array. The form enqueues a job, the queue processes it ~700ms later, and the result streams back live."
  {sources}
>
  <p>
    The page action calls the bounded <code>enqueueNotification({'{ user }'})</code> admission helper, which adds to the descriptor returned by
    <code>Mochi.queue('demo-notifications', …)</code>
    only while fewer than 100 jobs are pending. Its <code>process</code> function — with
    <code>concurrency: 2</code>, mounted via <code>queues: [notificationQueue]</code> in
    <code>Mochi.serve()</code> — picks the job up and records it. Initial state comes from
    <code>serverProps</code>; a <code>Mochi.sse()</code> route then pushes each completion in realtime — no polling.
  </p>
  <QueueWidget {initial} {suggestedUser} mochi:hydrate />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### QueueWidget.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiSubmitFunction } from 'mochi-framework';
  import type { ProcessedEntry, QueueStatus } from './types.ts';
  import { randomUsername } from './usernames.ts';

  let { initial, suggestedUser }: { initial: QueueStatus; suggestedUser: string } = $props();

  // Seed from the serverProps snapshot; the SSE stream then owns these server-global counters.
  // svelte-ignore state_referenced_locally
  let pending = $state(initial.inFlight);
  // svelte-ignore state_referenced_locally
  let processed = $state<ProcessedEntry[]>(initial.processed);
  // svelte-ignore state_referenced_locally
  let processedTotal = $state(initial.processedTotal);
  // Preloaded server-side so SSR and hydration match; refreshed after each submit.
  // svelte-ignore state_referenced_locally
  let username = $state(suggestedUser);
  let lastQueued = $state<string | null>(null);

  $effect(() => {
    const source = new EventSource('/demos/queue/events');
    source.addEventListener('message', (e) => {
      const status = JSON.parse(e.data) as QueueStatus;
      pending = status.inFlight;
      processed = status.processed;
      processedTotal = status.processedTotal;
    });

    const close = () => source.close();
    window.addEventListener('pagehide', close);
    return () => {
      window.removeEventListener('pagehide', close);
      close();
    };
  });

  let enqueueError = $state<string | null>(null);

  const handleEnqueue: MochiSubmitFunction<{ queued: string }, { error: string }> = () => {
    return ({ result }) => {
      if (result.type === 'success' && result.data) {
        enqueueError = null;
        lastQueued = result.data.queued;
        username = randomUsername();
      } else if (result.type === 'failure' && result.data) {
        enqueueError = result.data.error;
      } else if (result.type === 'error') {
        // The route limiter answers with a bare 429, which surfaces here as an error rather than in the failure branch's enhance envelope.
        enqueueError = result.status === 429 ? 'Too many submissions. Wait a moment and try again.' : 'Could not reach the server. Try again.';
      }
    };
  };
</script>

<div class="queue">
  <form method="POST" action="?/enqueue" {@attach enhance(handleEnqueue)}>
    <label>
      <span>Username</span>
      <input type="text" name="username" placeholder="alice" autocomplete="off" bind:value={username} />
    </label>
    <button type="submit">Enqueue notification</button>
  </form>

  {#if enqueueError}
    <p class="error" role="alert">{enqueueError}</p>
  {/if}

  <div class="status">
    <div class="stat">
      <span class="num">{pending}</span>
      <span class="lbl">in flight</span>
    </div>
    <div class="stat">
      <span class="num">{processedTotal}</span>
      <span class="lbl">processed</span>
    </div>
  </div>

  {#if lastQueued}
    <p class="hint">Queued a notification for <code>{lastQueued}</code>.</p>
  {/if}

  <h3>Recently processed</h3>
  {#if processed.length === 0}
    <p class="empty">No notifications processed yet. Enqueue one above.</p>
  {:else}
    <ul>
      <!-- {entry.user} is free-text from the user; Svelte escapes it on render, so it's XSS-safe. -->
      {#each processed as entry (entry.at + entry.user)}
        <li>
          <code>{entry.user}</code>
          <span class="time">{new Date(entry.at).toLocaleTimeString()} · {(entry.ms / 1000).toFixed(2)}s</span>
        </li>
      {/each}
    </ul>
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### queue.server.ts
```ts
import { Mochi, mochiEvents } from 'mochi-framework';
import type { NotificationJob, ProcessedEntry, QueueStatus } from './types';

export const QUEUE_NAME = 'demo-notifications';

// Pending jobs are tracked on the event bus as shared server state, so every connected browser sees the same numbers.
const processed: ProcessedEntry[] = [];
let processedTotal = 0;
let reservations = 0;

export const MAX_PENDING_NOTIFICATION_JOBS = 100;

// Jobs here take under two seconds, so anything still counted after a minute lost its terminal event. Ageing those
// out matters because the count also gates admission — a stuck counter would wedge the demo at "full" for everyone.
const PENDING_TTL_MS = 60_000;
const pendingSince: number[] = [];

function pendingJobs(): number {
  const cutoff = Date.now() - PENDING_TTL_MS;
  while (pendingSince.length > 0 && pendingSince[0]! < cutoff) {
    pendingSince.shift();
  }
  return pendingSince.length;
}

mochiEvents.on('queue:added', (e) => {
  if (e.queue === QUEUE_NAME) {
    pendingSince.push(Date.now());
  }
});
const settle = (e: { queue: string }) => {
  if (e.queue === QUEUE_NAME) {
    pendingSince.shift();
  }
};
mochiEvents.on('queue:completed', settle);
mochiEvents.on('queue:failed', settle);

// The site rides the default `queueStorage: 'memory'`, so the demo writes no queue file into the working dir;
// set `Mochi.serve({ queueStorage })` to persist.
export const notificationQueue = Mochi.queue<NotificationJob>(QUEUE_NAME, {
  concurrency: 2,
  process: async (job) => {
    // Simulate delivery latency so the UI shows the queued → processing → done transition.
    const start = Date.now();
    await Bun.sleep(500 + Math.random() * 1500);
    processed.push({ user: job.data.user, at: Date.now(), ms: Date.now() - start });
    if (processed.length > 20) {
      processed.shift();
    }
    processedTotal++;
    return { delivered: true };
  },
});

// `add()` awaits the queue write before `queue:added` fires, so concurrent submissions need the reservation to see
// each other during that window; the reservation is released once the event has taken over the count.
export function reserveNotificationSlot(): (() => void) | null {
  if (pendingJobs() + reservations >= MAX_PENDING_NOTIFICATION_JOBS) {
    return null;
  }
  reservations++;
  let released = false;
  return () => {
    if (!released) {
      reservations = Math.max(0, reservations - 1);
      released = true;
    }
  };
}

export async function enqueueNotification(data: NotificationJob): Promise<boolean> {
  const release = reserveNotificationSlot();
  if (!release) {
    return false;
  }
  try {
    await notificationQueue.add(data);
    return true;
  } finally {
    release();
  }
}

export function queueStatus(): QueueStatus {
  return { processed: [...processed].reverse(), processedTotal, inFlight: pendingJobs() };
}
```

### types.ts
```ts
// Pure types shared between the server module (queue.server.ts) and the island.
// Components must import types from here, NOT from queue.server.ts: a type import
// from a side-effectful server module still drags that module into the SSR
// component bundle, instantiating its worker/state a second time.

export interface NotificationJob {
  user: string;
}

export interface ProcessedEntry {
  user: string;
  at: number;
  ms: number;
}

export interface QueueStatus {
  processed: ProcessedEntry[];
  processedTotal: number;
  inFlight: number;
}
```

### usernames.ts
```ts
const names = ['alice', 'bob', 'carol', 'dave', 'erin', 'frank', 'grace', 'heidi', 'ivan', 'judy', 'mallory', 'olivia', 'peggy', 'trent', 'victor', 'wendy'];

export function randomUsername(): string {
  return names[Math.floor(Math.random() * names.length)] ?? 'alice';
}
```

### routes.ts
```ts
import { Mochi, fail, success, mochiEvents } from 'mochi-framework';
import type { MochiRouteValue, MochiQueueConfig } from 'mochi-framework';
import { enqueueNotification, notificationQueue, queueStatus, QUEUE_NAME } from './queue.server';
import { randomUsername } from './usernames';

// Mounted in the site's Mochi.serve({ queues }) call — see src/routes.ts.
export const queues: MochiQueueConfig[] = [notificationQueue];

export const routes: Record<string, MochiRouteValue> = {
  '/demos/queue': Mochi.page('./src/demos/queue/Queue.svelte', {
    // Scoped to the enqueue POST: a page-wide limit also counts GETs (including speculation-rules
    // prefetches), so a visitor reading the demo could be served a 429 instead of the page.
    rateLimit: { limit: 60, window: '1m', skip: (req) => req.method !== 'POST' },
    // `suggestedUser` is generated server-side so SSR and hydration agree.
    serverProps: () => ({ initial: queueStatus(), suggestedUser: randomUsername() }),
    actions: {
      enqueue: async ({ formData }) => {
        // Free-text username is safe unsanitized: it's only ever rendered through
        // Svelte text interpolation (`{entry.user}`), which auto-escapes.
        const user = String(formData.get('username') ?? '')
          .trim()
          .slice(0, 64);
        if (!(await enqueueNotification({ user: user || 'anonymous' }))) {
          return fail(503, { error: 'The demo queue is full. Try again after some jobs finish.' });
        }
        return success({ queued: user || 'anonymous' });
      },
    },
  }),
  '/demos/queue/events': Mochi.sse((stream) => {
    // Broadcast the shared snapshot on enqueue and on settle, so every client's
    // in-flight/processed counts move together — no per-client reconciliation.
    const push = (event: { queue: string }) => {
      if (event.queue === QUEUE_NAME) {
        stream.send(JSON.stringify(queueStatus()));
      }
    };
    mochiEvents.on('queue:added', push);
    mochiEvents.on('queue:completed', push);
    mochiEvents.on('queue:failed', push);
    stream.onClose(() => {
      mochiEvents.off('queue:added', push);
      mochiEvents.off('queue:completed', push);
      mochiEvents.off('queue:failed', push);
    });
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes, queues } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
  queues,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: rate-limit

### RateLimit.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import { sources } from './sources.prerender.ts';

  let { used, limit, resetIn }: { used: number; limit: number; resetIn: number } = $props();
</script>

<DemoPage
  title="Rate Limiting"
  description="Add rateLimit to any Mochi.page() or Mochi.api() route — or globally on Mochi.serve() — to throttle requests per client. Requests are keyed by the proxy-aware client IP by default, memory-backed out of the box, with rateLimitSqliteStore and rateLimitPostgresStore for persistence. Blocked page routes render the error page with a 429; API routes return JSON with RateLimit-* headers."
  {sources}
>
  <div class="card">
    <dl>
      <dt>Requests used</dt>
      <dd><code>{used} of {limit}</code></dd>
      <dt>Window resets in</dt>
      <dd><code>{resetIn}s</code></dd>
    </dl>
    <p class="hint">
      Reload this page. This route allows {limit} requests per minute per IP — after the {limit}th reload you'll get a 429 error page. Wait for the window to reset, then reload to
      get back in.
    </p>
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { mkdirSync } from 'node:fs';
import { Mochi, getRequestContext, rateLimitSqliteStore } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

// Persist rate-limit counters to SQLite so they survive restarts; bun:sqlite won't create ./db itself, and it's gitignored.
mkdirSync('./db', { recursive: true });
const store = rateLimitSqliteStore({ path: './db/rate-limit.sqlite' });

export const routes: Record<string, MochiRouteValue> = {
  '/demos/rate-limit': Mochi.page('./src/demos/rate-limit/RateLimit.svelte', {
    rateLimit: { limit: 5, window: '1m', store },
    serverProps: () => {
      const rateLimit = getRequestContext().rateLimit;
      return {
        used: rateLimit ? rateLimit.limit - rateLimit.remaining : 1,
        limit: rateLimit?.limit ?? 5,
        resetIn: rateLimit?.resetIn ?? 60,
      };
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: reload-form-data

### ReloadFormData.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import Guestbook from './Guestbook.svelte';
  import { sources } from './sources.prerender.ts';

  type GuestbookEntry = { id: string; name: string; at: number };

  let { guestbook }: { guestbook: GuestbookEntry[] } = $props();
</script>

<DemoPage
  title="Reloading associated form data"
  description="This page shows a pattern to reload associated data on a form submit. The plain HTML version simply reloads the page (the normal form behavior) which reloads the data. For associated data you can reload this inside the enhance callback."
  {sources}
>
  <p>
    Each successful submit appends the name to an in-memory list on the server. The hydrated version refetches <code>/api/guestbook</code> after a successful submit and updates the
    list in place. The plain version submits natively, the page re-renders with a fresh <code>guestbook</code> serverProp, and the new name shows up after the reload.
  </p>
  <h3>With <code>{'{@attach enhance(...)}'}</code></h3>
  <Guestbook entries={guestbook} mochi:hydrate />
  <h3>Plain HTML</h3>
  <Guestbook entries={guestbook} />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### Guestbook.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiEnhanceOptions, MochiSubmitFunction } from 'mochi-framework';

  type GuestbookEntry = { id: string; name: string; at: number };

  let { entries: initialEntries }: { entries: GuestbookEntry[] } = $props();

  // svelte-ignore state_referenced_locally
  let entries = $state<GuestbookEntry[]>(initialEntries);
  let errorMessage = $state<string | null>(null);
  let pending = $state(false);

  async function refetch(): Promise<void> {
    const res = await fetch('/api/guestbook', { headers: { accept: 'application/json' }, cache: 'no-store' });
    const body = (await res.json()) as { entries: GuestbookEntry[] };
    entries = body.entries;
  }

  const handleSign: MochiSubmitFunction<Record<string, never>, { error: string }> = () => {
    errorMessage = null;
    return async ({ result, formElement }) => {
      if (result.type === 'success') {
        formElement.reset();
        await refetch();
      } else if (result.type === 'failure' && result.data) {
        errorMessage = result.data.error;
      } else if (result.type === 'error') {
        errorMessage = 'Network error. Try again.';
      }
    };
  };

  const opts: MochiEnhanceOptions<Record<string, never>, { error: string }> = {
    submit: handleSign,
    onPending: (v) => {
      pending = v;
    },
  };

  function formatTime(at: number): string {
    return new Date(at).toLocaleTimeString();
  }
</script>

<div class="guestbook">
  {#if entries.length === 0}
    <p class="empty">No entries yet. Be the first to sign.</p>
  {:else}
    <ul class="entries">
      {#each entries as entry (entry.id)}
        <li>
          <span class="name">{entry.name}</span>
          <span class="time">{formatTime(entry.at)}</span>
        </li>
      {/each}
    </ul>
  {/if}

  <form method="POST" action="?/guestbookSign" class="sign" {@attach enhance(opts)}>
    <label>
      <span>Your name</span>
      <input name="name" maxlength="50" disabled={pending} required />
    </label>
    <div class="submit-row">
      <button type="submit" disabled={pending}>{pending ? 'Signing…' : 'Sign guestbook'}</button>
      {#if errorMessage}
        <p class="error" role="alert">{errorMessage}</p>
      {/if}
    </div>
  </form>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, fail, success } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

type GuestbookEntry = { id: string; name: string; at: number };
const guestbook: GuestbookEntry[] = [];
const MAX_ENTRIES = 100;

export const routes: Record<string, MochiRouteValue> = {
  '/api/guestbook': Mochi.api(({ method }) => {
    if (method !== 'GET') {
      return new Response('Method not allowed', { status: 405 });
    }
    return Response.json({ entries: [...guestbook].reverse() });
  }),
  '/demos/reload-form-data': Mochi.page('./src/demos/reload-form-data/ReloadFormData.svelte', {
    // Scoped to the sign POST: a page-wide limit also counts GETs (including speculation-rules
    // prefetches), so a visitor reading the demo could be served a 429 instead of the page.
    rateLimit: { limit: 60, window: '1m', skip: (req) => req.method !== 'POST' },
    serverProps: () => ({ guestbook: [...guestbook].reverse() }),
    actions: {
      guestbookSign: ({ formData }) => {
        const name = String(formData.get('name') ?? '').trim();
        if (!name) {
          return fail(400, { error: 'Name required' });
        }
        if (name.length > 50) {
          return fail(400, { error: 'Name too long (max 50 chars)' });
        }
        guestbook.push({ id: crypto.randomUUID(), name, at: Date.now() });
        if (guestbook.length > MAX_ENTRIES) {
          guestbook.shift();
        }
        return success({});
      },
    },
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: request-cache

### RequestCache.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';
  import { overview, topWords, themes, extremes, richness } from './analyzeBook.ts';

  // Each helper wraps the same memoized analysis, so these five calls parse the book exactly once.
  const facetOverview = overview();
  const facetTopWords = topWords();
  const facetThemes = themes();
  const facetExtremes = extremes();
  const facetHapax = richness();

  const nf = new Intl.NumberFormat('en-US');
  const topMax = facetTopWords[0]?.[1] ?? 1;

  // Snippets show the real pipeline so each panel's code matches what it renders.
  const snip = (pick) => highlightCode(`// parsed once per request, shared across panels\nconst analyzeCached = requestMemo(() => analyze(BOOK));\n${pick}`, 'ts');
  const codeOverview = await snip('const { words, unique, sentences } = analyzeCached();');
  const codeTopWords = await snip('const { topWords } = analyzeCached();');
  const codeThemes = await snip('const { themes } = analyzeCached();');
  const codeExtremes = await snip('const { longestWord, longestSentenceExcerpt } = analyzeCached();');
  const codeRichness = await snip('const { hapax } = analyzeCached();');
</script>

<DemoPage
  title="Request Cache"
  description="Five independent helpers each read the full text of Robinson Crusoe, but requestMemo() parses the 124k-word book only once per request — the first call analyses it, the other four are instant cache hits, and the whole cache is thrown away when the request ends."
  {sources}
>
  <div class="stack">
    <p class="hint">
      Each panel calls its own helper, but they all share one memoized analysis — a single parse per request, so one miss and four hits. Open the
      <strong>debug bar</strong> (bottom right) and its <strong>Cache</strong> tab to check the stats.
    </p>

    <div class="facets">
      <section class="facet">
        <h3>Overview</h3>
        <dl class="stats">
          <div>
            <dt>Words</dt>
            <dd>{nf.format(facetOverview.words)}</dd>
          </div>
          <div>
            <dt>Unique</dt>
            <dd>{nf.format(facetOverview.unique)}</dd>
          </div>
          <div>
            <dt>Sentences</dt>
            <dd>{nf.format(facetOverview.sentences)}</dd>
          </div>
          <div>
            <dt>Reading time</dt>
            <dd>~{facetOverview.readingMinutes} min</dd>
          </div>
        </dl>
        <!-- eslint-disable-next-line svelte/no-at-html-tags -->
        <div class="snippet">{@html codeOverview}</div>
      </section>

      <section class="facet">
        <h3>Top words</h3>
        <ul class="bars">
          {#each facetTopWords as [word, count] (word)}
            <li>
              <span class="bar-word">{word}</span>
              <span class="bar-track"><span class="bar-fill" style:width="{(count / topMax) * 100}%"></span></span>
              <span class="bar-count">{nf.format(count)}</span>
            </li>
          {/each}
        </ul>
        <!-- eslint-disable-next-line svelte/no-at-html-tags -->
        <div class="snippet">{@html codeTopWords}</div>
      </section>

      <section class="facet">
        <h3>Themes</h3>
        <ul class="chips">
          {#each facetThemes as [word, count] (word)}
            <li><span class="chip-word">{word}</span><span class="chip-count">{nf.format(count)}</span></li>
          {/each}
        </ul>
        <!-- eslint-disable-next-line svelte/no-at-html-tags -->
        <div class="snippet">{@html codeThemes}</div>
      </section>

      <section class="facet">
        <h3>Extremes</h3>
        <p class="extreme-label">Longest word</p>
        <p class="extreme-value"><code>{facetExtremes.longestWord}</code></p>
        <p class="extreme-label">Longest sentence · {facetExtremes.longestSentenceWords} words</p>
        <blockquote>{facetExtremes.longestSentenceExcerpt.slice(0, 260)}…</blockquote>
        <!-- eslint-disable-next-line svelte/no-at-html-tags -->
        <div class="snippet">{@html codeExtremes}</div>
      </section>

      <section class="facet">
        <h3>Vocabulary richness</h3>
        <p class="hapax"><strong>{nf.format(facetHapax)}</strong> words appear exactly once</p>
        <p class="extreme-label">Hapax legomena — {Math.round((facetHapax / facetOverview.unique) * 100)}% of the vocabulary</p>
        <!-- eslint-disable-next-line svelte/no-at-html-tags -->
        <div class="snippet">{@html codeRichness}</div>
      </section>
    </div>
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### analyzeBook.ts
```ts
import { requestMemo } from 'mochi-framework';

// Trimmed to Defoe's prose — the Gutenberg header/footer would skew word counts (and crown "unenforceability" longest word).
const RAW = await Bun.file('./src/demos/request-cache/robinson-crusoe.txt').text();
const bodyStart = RAW.indexOf('***', RAW.indexOf('*** START OF') + 3) + 3;
const BOOK = RAW.slice(bodyStart, RAW.indexOf('*** END OF'));

// Very common English words carry no signal in a top-words list; drop them so
// the narrative's real vocabulary (shore, boat, island, Friday…) rises to the top.
const STOPWORDS = new Set(
  'a an the and or but if of to in into on upon at by for from with without within as than then so such no not nor only own same other another some any each few many more most all both very much well now here there when where while though yet also about before after over under again ever never how what which who whom whose that this these those i me my we us our you your he him his she her it its they them their been being am is are was were be do does did done have has had having would should could shall will may might must can cannot thus therefore hence unto amongst out up down'.split(
    ' ',
  ),
);

const THEME_WORDS = ['island', 'sea', 'ship', 'god', 'friday', 'money', 'fear'] as const;

export interface Analysis {
  words: number;
  unique: number;
  sentences: number;
  /** Estimated reading time in minutes at 250 wpm. */
  readingMinutes: number;
  /** All words sorted by descending frequency, stopwords excluded. */
  topWords: Array<[string, number]>;
  themes: Array<[string, number]>;
  longestSentenceWords: number;
  longestSentenceExcerpt: string;
  longestWord: string;
  /** Count of words appearing exactly once (hapax legomena). */
  hapax: number;
}

// ~16-25ms of pure CPU per call — this is the unit of work requestMemo() below runs once instead of once per facet.
function analyze(text: string): Analysis {
  const words = text.toLowerCase().match(/[a-z']+/g) ?? [];
  const freq = new Map<string, number>();
  for (const w of words) {
    freq.set(w, (freq.get(w) ?? 0) + 1);
  }

  const sentences = text.split(/[.!?]+/).filter((s) => s.trim().length > 0);
  let longestSentenceWords = 0;
  let longestSentenceExcerpt = '';
  for (const s of sentences) {
    const n = (s.match(/[a-z']+/gi) ?? []).length;
    if (n > longestSentenceWords) {
      longestSentenceWords = n;
      longestSentenceExcerpt = s.replace(/\s+/g, ' ').trim();
    }
  }

  let longestWord = '';
  let hapax = 0;
  for (const [word, count] of freq) {
    if (count === 1) {
      hapax++;
    }
    if (word.length > longestWord.length) {
      longestWord = word;
    }
  }

  const topWords = [...freq.entries()].filter(([w]) => !STOPWORDS.has(w)).sort((a, b) => b[1] - a[1]);
  const themes = THEME_WORDS.map((w) => [w, freq.get(w) ?? 0] as [string, number]);

  return {
    words: words.length,
    unique: freq.size,
    sentences: sentences.length,
    readingMinutes: Math.round(words.length / 250),
    topWords,
    themes,
    longestSentenceWords,
    longestSentenceExcerpt,
    longestWord,
    hapax,
  };
}

// Zero-arg key means one shared cache entry — however many facet helpers below call this, the book parses once per request.
const analyzeCached = requestMemo(() => analyze(BOOK), { namespace: 'demo:crusoe' });

export interface Overview {
  words: number;
  unique: number;
  sentences: number;
  readingMinutes: number;
}

export function overview(): Overview {
  const a = analyzeCached();
  return { words: a.words, unique: a.unique, sentences: a.sentences, readingMinutes: a.readingMinutes };
}

export function topWords(): Array<[string, number]> {
  return analyzeCached().topWords.slice(0, 12);
}

export function themes(): Array<[string, number]> {
  return analyzeCached().themes;
}

export interface Extremes {
  longestSentenceWords: number;
  longestSentenceExcerpt: string;
  longestWord: string;
}

export function extremes(): Extremes {
  const a = analyzeCached();
  return {
    longestSentenceWords: a.longestSentenceWords,
    longestSentenceExcerpt: a.longestSentenceExcerpt,
    longestWord: a.longestWord,
  };
}

export function richness(): number {
  return analyzeCached().hapax;
}
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/request-cache': Mochi.page('./src/demos/request-cache/RequestCache.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: request-id

### RequestId.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import Fetcher from './Fetcher.svelte';
  import { sources } from './sources.prerender.ts';

  let { requestId }: { requestId: string } = $props();
</script>

<DemoPage
  title="Request ID"
  description="Every HTTP request carries a stable correlation id. Read it from any server-side code with getRequestContext().requestId — it's a Bun.randomUUIDv7() by default (time-ordered), can be seeded from an upstream proxy.requestIdHeader, and the same id rides every lifecycle event (request, error, action:*) so observability tooling can stitch a request together."
  {sources}
>
  <div class="card">
    <dl>
      <dt>This page render</dt>
      <dd><code>{requestId}</code></dd>
    </dl>
    <p class="hint">Reload the page to get a fresh id — each request re-runs the resolver.</p>

    <Fetcher mochi:hydrate />
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### Fetcher.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';

  let fetched = $state('');
  let loading = $state(false);

  async function load() {
    if (!isBrowser) {
      return;
    }
    loading = true;
    try {
      const res = await fetch('/demos/request-id/api');
      fetched = ((await res.json()) as { requestId: string }).requestId;
    } finally {
      loading = false;
    }
  }
</script>

<div class="fetcher">
  <button onclick={load} disabled={loading}>
    {loading ? 'Fetching…' : 'Fetch /demos/request-id/api'}
  </button>

  {#if fetched}
    <div class="result">
      <code>{fetched}</code>
      <p class="hint">A different id — this fetch is a separate HTTP request, so it gets its own.</p>
    </div>
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, getRequestContext } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/request-id': Mochi.page('./src/demos/request-id/RequestId.svelte', {
    serverProps: () => ({ requestId: getRequestContext().requestId }),
  }),
  '/demos/request-id/api': Mochi.api(() => Response.json({ requestId: getRequestContext().requestId })),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: runed

### Runed.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import Reactivity from './Reactivity.svelte';
  import StateCard from './StateCard.svelte';
  import Elements from './Elements.svelte';
  import Sensors from './Sensors.svelte';
  import AsyncFsm from './AsyncFsm.svelte';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';

  const codeInstall = await highlightCode('bun add runed', 'bash');
  const codeUsage = await highlightCode(
    `import { Debounced } from 'runed';

let query = $state('');
const search = new Debounced(() => query, 400);
// search.current — query, 400ms after it stops changing`,
    'typescript',
  );
</script>

<DemoPage
  title="Runed Utilities"
  description="Runed is a Svelte 5 collection of reactive utilities built on runes. Because most of them read the DOM, timers, or device sensors, each card is its own mochi:hydrate island — the page renders on the server with default values, then Runed brings it to life on the client."
  {sources}
>
  <div class="intro">
    <p>
      Runed needs no special setup — it's a plain Svelte 5 runes library, so you install it and import from
      <code>runed</code>. In Mochi it bundles straight into whichever island imports it.
    </p>
    <CodeSnippet html={codeInstall} />
    <p>Then import a utility and use it like any rune — e.g. the <code>Debounced</code> value driving the first card:</p>
    <CodeSnippet html={codeUsage} />
    <p>Explore the full toolkit at <a href="https://runed.dev" target="_blank" rel="noopener noreferrer">runed.dev</a>.</p>
  </div>

  <section class="card">
    <header>
      <h2>Reactivity & timing</h2>
      <p><code>Debounced</code>, <code>Throttled</code>, <code>Previous</code>, and <code>watch</code> — one input, four derived views.</p>
    </header>
    <Reactivity mochi:hydrate />
  </section>

  <section class="card">
    <header>
      <h2>State</h2>
      <p><code>StateHistory</code> undo/redo, <code>PersistedState</code> across reloads and tabs, and <code>IsMounted</code>.</p>
    </header>
    <StateCard mochi:hydrate />
  </section>

  <section class="card">
    <header>
      <h2>Elements & observers</h2>
      <p><code>ElementSize</code> + <code>useResizeObserver</code>, <code>IsInViewport</code>, <code>activeElement</code>, and <code>IsFocusWithin</code>.</p>
    </header>
    <Elements mochi:hydrate />
  </section>

  <section class="card">
    <header>
      <h2>Sensors & animation</h2>
      <p><code>PressedKeys</code>, <code>IsIdle</code>, and <code>AnimationFrames</code> with a live FPS cap.</p>
    </header>
    <Sensors mochi:hydrate />
  </section>

  <section class="card">
    <header>
      <h2>State machine & async</h2>
      <p>A self-driving <code>FiniteStateMachine</code> traffic light and a debounced <code>resource</code> search over a Mochi API.</p>
    </header>
    <AsyncFsm mochi:hydrate />
  </section>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### Reactivity.svelte
```svelte
<script lang="ts">
  import { Debounced, Throttled, Previous, watch } from 'runed';

  let text = $state('');
  const debounced = new Debounced(() => text, 400);
  const throttled = new Throttled(() => text, 400);
  const previous = new Previous(() => text);

  let seq = 0;
  let log = $state<{ id: number; text: string }[]>([]);
  watch(
    () => debounced.current,
    (value, prev) => {
      log = [{ id: seq++, text: `"${prev ?? ''}" → "${value}"` }, ...log].slice(0, 5);
    },
    { lazy: true },
  );
</script>

<div class="grid">
  <label class="field">
    <span>Type here</span>
    <input type="text" bind:value={text} placeholder="Start typing…" />
  </label>

  <div class="readouts">
    <div class="row"><span class="key">live</span><code>{text || '—'}</code></div>
    <div class="row"><span class="key">Debounced (400ms)</span><code>{debounced.current || '—'}</code></div>
    <div class="row"><span class="key">Throttled (400ms)</span><code>{throttled.current || '—'}</code></div>
    <div class="row"><span class="key">Previous</span><code>{previous.current ?? '—'}</code></div>
  </div>

  <div class="watch">
    <span class="key">watch() change log</span>
    {#if log.length === 0}
      <p class="empty">Waiting for the debounced value to settle…</p>
    {:else}
      <ul>
        {#each log as entry (entry.id)}
          <li><code>{entry.text}</code></li>
        {/each}
      </ul>
    {/if}
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### StateCard.svelte
```svelte
<script lang="ts">
  import { StateHistory, PersistedState, IsMounted } from 'runed';
  import Badge from '../../components/Badge.svelte';

  let count = $state(0);
  const history = new StateHistory(
    () => count,
    (c) => (count = c),
  );

  const persisted = new PersistedState('mochi-runed-demo:count', 0);

  const isMounted = new IsMounted();
</script>

<div class="grid">
  <div class="card">
    <div class="head">
      <h3>StateHistory</h3>
      <span class="hint">undo / redo any $state</span>
    </div>
    <div class="counter">
      <button onclick={() => count--}>−</button>
      <span class="value">{count}</span>
      <button onclick={() => count++}>+</button>
    </div>
    <div class="actions">
      <button onclick={history.undo} disabled={!history.canUndo}>Undo</button>
      <button onclick={history.redo} disabled={!history.canRedo}>Redo</button>
    </div>
    <p class="meta">{history.log.length} snapshot{history.log.length === 1 ? '' : 's'} recorded</p>
  </div>

  <div class="card">
    <div class="head">
      <h3>PersistedState</h3>
      <span class="hint">localStorage · survives reload · syncs tabs</span>
    </div>
    <div class="counter">
      <button onclick={() => persisted.current--}>−</button>
      <span class="value">{persisted.current}</span>
      <button onclick={() => persisted.current++}>+</button>
    </div>
    <p class="meta">Reload the page — the value sticks. Open a second tab to watch it sync.</p>
  </div>

  <div class="card mounted">
    <div class="head">
      <h3>IsMounted</h3>
      <span class="hint">false during SSR, true after hydration</span>
    </div>
    {#if isMounted.current}
      <Badge kind="success">mounted (client)</Badge>
    {:else}
      <Badge kind="warning">not mounted (server)</Badge>
    {/if}
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### Elements.svelte
```svelte
<script lang="ts">
  import { ElementSize, useResizeObserver, IsInViewport, activeElement, IsFocusWithin } from 'runed';
  import Badge from '../../components/Badge.svelte';

  let box = $state<HTMLElement>();
  const size = new ElementSize(() => box);

  let resizes = $state(0);
  useResizeObserver(
    () => box,
    () => resizes++,
  );

  let scroller = $state<HTMLElement>();
  let target = $state<HTMLElement>();
  const inViewport = new IsInViewport(() => target, { root: () => scroller ?? null });

  let form = $state<HTMLFormElement>();
  const focusWithin = new IsFocusWithin(() => form);
</script>

<div class="grid">
  <div class="panel">
    <div class="head">
      <h3>ElementSize + useResizeObserver</h3>
      <span class="hint">drag the corner of the box</span>
    </div>
    <textarea bind:this={box} class="resizable" readonly>Drag my bottom-right corner ↘</textarea>
    <div class="readout">
      <code>{Math.round(size.width)} × {Math.round(size.height)}</code>
      <span class="meta">{resizes} resize event{resizes === 1 ? '' : 's'}</span>
    </div>
  </div>

  <div class="panel">
    <div class="head">
      <h3>IsInViewport</h3>
      <span class="hint">scroll the target in and out</span>
    </div>
    <div bind:this={scroller} class="scroller">
      <div class="spacer">scroll down ↓</div>
      <div bind:this={target} class="target" class:visible={inViewport.current}>
        {inViewport.current ? 'In viewport' : 'Out of viewport'}
      </div>
      <div class="spacer">↑ scroll up</div>
    </div>
    {#if inViewport.current}
      <Badge kind="success">visible</Badge>
    {:else}
      <Badge kind="default">hidden</Badge>
    {/if}
  </div>

  <div class="panel">
    <div class="head">
      <h3>activeElement + IsFocusWithin</h3>
      <span class="hint">tab through the fields</span>
    </div>
    <form bind:this={form} class="fields" class:lit={focusWithin.current}>
      <input type="text" placeholder="First" />
      <input type="text" placeholder="Second" />
      <button type="button">Button</button>
    </form>
    <div class="readout">
      <span class="meta">focused: <code>{activeElement.current?.localName ?? 'none'}</code></span>
      {#if focusWithin.current}
        <Badge kind="info">focus within</Badge>
      {/if}
    </div>
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### Sensors.svelte
```svelte
<script lang="ts">
  import { PressedKeys, IsIdle, AnimationFrames } from 'runed';
  import Badge from '../../components/Badge.svelte';

  const keys = new PressedKeys();

  const idle = new IsIdle({ timeout: 2000 });

  let frames = $state(0);
  let fpsLimit = $state(30);
  const animation = new AnimationFrames(() => frames++, { fpsLimit: () => fpsLimit });
</script>

<div class="grid">
  <div class="panel">
    <div class="head">
      <h3>PressedKeys</h3>
      <span class="hint">hold any keys — try Ctrl + Shift</span>
    </div>
    <div class="keys">
      {#if keys.all.length === 0}
        <span class="empty">No keys pressed</span>
      {:else}
        {#each keys.all as key (key)}
          <kbd>{key}</kbd>
        {/each}
      {/if}
    </div>
  </div>

  <div class="panel">
    <div class="head">
      <h3>IsIdle</h3>
      <span class="hint">stop moving the mouse for 2s</span>
    </div>
    {#if idle.current}
      <Badge kind="warning">idle</Badge>
    {:else}
      <Badge kind="success">active</Badge>
    {/if}
    <p class="meta">Last active: <code>{new Date(idle.lastActive).toLocaleTimeString()}</code></p>
  </div>

  <div class="panel">
    <div class="head">
      <h3>AnimationFrames</h3>
      <span class="hint">rAF loop with an FPS cap</span>
    </div>
    <div class="fps">
      <code>{Math.round(animation.fps)} fps</code>
      <span class="meta">{frames} frames</span>
    </div>
    <label class="slider">
      <span>Limit: {fpsLimit} fps</span>
      <input type="range" min="1" max="60" bind:value={fpsLimit} />
    </label>
    <button onclick={() => (animation.running ? animation.stop() : animation.start())}>
      {animation.running ? 'Stop' : 'Start'}
    </button>
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### AsyncFsm.svelte
```svelte
<script lang="ts">
  import { FiniteStateMachine, resource } from 'runed';
  import { isBrowser } from 'mochi-framework';

  type Light = 'red' | 'yellow' | 'green';
  type LightEvent = 'next';

  // Time spent in each state before auto-advancing.
  const DURATIONS: Record<Light, number> = { red: 3000, green: 3000, yellow: 1200 };

  let auto = $state(true);

  // The FSM fires the initial state's _enter synchronously inside its constructor —
  // before `light` is assigned — so defer the self-referencing debounce to a microtask
  // (and only drive the cycle on the client, never during SSR).
  function scheduleNext(ms: number) {
    if (!isBrowser) {
      return;
    }
    queueMicrotask(() => {
      if (auto) {
        light.debounce(ms, 'next');
      }
    });
  }

  const light = new FiniteStateMachine<Light, LightEvent>('red', {
    red: { next: 'green', _enter: () => scheduleNext(DURATIONS.red) },
    green: { next: 'yellow', _enter: () => scheduleNext(DURATIONS.green) },
    yellow: { next: 'red', _enter: () => scheduleNext(DURATIONS.yellow) },
  });

  function toggleAuto() {
    auto = !auto;
    if (auto) {
      scheduleNext(DURATIONS[light.current]);
    }
  }

  const fruits = ['apple', 'apricot', 'banana', 'blueberry', 'cherry', 'grape', 'lemon', 'mango', 'orange', 'peach', 'pear', 'plum'];

  let query = $state('');
  const search = resource(
    () => query,
    async (q, _prev, { signal }) => {
      const res = await fetch(`/api/runed/search?q=${encodeURIComponent(q)}`, { signal });
      return (await res.json()) as { matches: string[] };
    },
    { debounce: 300, initialValue: { matches: fruits } },
  );
</script>

<div class="grid">
  <div class="panel">
    <div class="head">
      <h3>FiniteStateMachine</h3>
      <span class="hint">_enter hooks auto-advance via .debounce()</span>
    </div>
    <div class="light" aria-label="traffic light">
      <span class="lamp red" class:on={light.current === 'red'}></span>
      <span class="lamp yellow" class:on={light.current === 'yellow'}></span>
      <span class="lamp green" class:on={light.current === 'green'}></span>
    </div>
    <div class="light-actions">
      <code>{light.current}</code>
      <button onclick={() => light.send('next')}>Next →</button>
      <button onclick={toggleAuto}>{auto ? 'Pause' : 'Resume'}</button>
    </div>
  </div>

  <div class="panel">
    <div class="head">
      <h3>resource</h3>
      <span class="hint">debounced fetch with cancellation</span>
    </div>
    <input type="search" bind:value={query} placeholder="Filter fruits…" />
    <div class="status">
      {#if search.loading}
        <span class="meta">Loading…</span>
      {:else if search.error}
        <span class="meta error">Error: {search.error.message}</span>
      {:else}
        <span class="meta">{search.current?.matches.length ?? 0} match{search.current?.matches.length === 1 ? '' : 'es'}</span>
      {/if}
    </div>
    <div class="matches">
      {#each search.current?.matches ?? [] as fruit (fruit)}
        <span class="chip">{fruit}</span>
      {/each}
    </div>
  </div>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi, getRequestContext } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

const FRUITS = ['apple', 'apricot', 'banana', 'blueberry', 'cherry', 'grape', 'lemon', 'mango', 'orange', 'peach', 'pear', 'plum'];

export const routes: Record<string, MochiRouteValue> = {
  '/demos/runed': Mochi.page('./src/demos/runed/Runed.svelte'),
  '/api/runed/search': Mochi.api(() => {
    const { url } = getRequestContext();
    const q = (url.searchParams.get('q') ?? '').toLowerCase();
    const matches = q ? FRUITS.filter((f) => f.includes(q)) : FRUITS;
    return Response.json({ matches });
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: server-island

### ServerIsland.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import ServerGreeting from './ServerGreeting.svelte';
  import ServerNoProps from './ServerNoProps.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Server Islands"
  description="You can mark components with mochi:defer to render them on the server after the initial page is delivered. Server islands can read cookies and show personalized content and since they are a separate request, you can also cache them differently than the main page. The first island also pairs mochi:defer with a nested mochi:hydrate component so it hydrates once it loads. The downside with server islands is that they require JavaScript and have no SSR representation on the initial page load."
  {sources}
>
  <p class="delay-note">The islands below are delayed on purpose to show the loading state.</p>
  <ServerGreeting
    mochi:defer
    mochi:hydrate
    name="Visitor"
    bigProp="so theres this girl bella and she moves to forks which is rainy and sad and then theres this guy edward whos like super pale and sparkly in the sun and hes a vampire but like a vegetarian one who only eats animals and bella is like i dont care youre gorgeous and edward is like no stay away im dangerous and she is like no and then theres this werewolf jacob who is warm and shirtless and loves bella too and theres a whole love triangle thing and some evil vampires show up wanting to eat bella because she smells really good apparently and then edward leaves in the second book and bella just stares out a window for months and then she cliff dives and alice sees it in a vision and thinks shes dead and edward tries to get the vampire royalty the volturi to kill him because hes dramatic like that and bella has to fly to italy to save him and then they get back together and in the last book they get married and have a half vampire baby named renesmee which is a name and jacob imprints on the baby which is weird and then bella becomes a vampire and they fight the volturi with a bunch of vampire friends and nobody actually fights they just talk it out the end"
  >
    <div class="island-loading">Loading server island<span class="dots"></span></div>
  </ServerGreeting>
  <div class="spacer"></div>
  <ServerNoProps mochi:defer>
    <div class="island-loading">Loading server island<span class="dots"></span></div>
  </ServerNoProps>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### ServerGreeting.svelte
```svelte
<script>
  import { cookies, isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';

  let { name = 'World', bigProp = '' } = $props();
  const islandId = $props.id();

  await (isServer ? delay(1000, 3000) : Promise.resolve());

  const username = cookies.get('mochi_username');
  // svelte-ignore state_referenced_locally
  let displayName = username ?? name;

  const renderedAt = new Date().toLocaleTimeString();
  let mouseX = $state(0);
  let mouseY = $state(0);
</script>

<svelte:window
  onmousemove={(e) => {
    mouseX = e.clientX;
    mouseY = e.clientY;
  }}
/>

<div class="server-greeting">
  <p>Hello, <strong>{displayName}</strong>! 🏝️</p>
  <p class="timestamp">Rendered at {renderedAt}</p>
  <p class="timestamp">Mouse position: {mouseX}, {mouseY}</p>

  <p class="timestamp">$props.id(): {islandId}</p>
  <p class="timestamp">bigProp: {bigProp}</p>
  <p class="timestamp">bigProp length: {bigProp.length}</p>
</div>

<style>
  /* Styles omitted */
</style>
```

### ServerNoProps.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/sourceUtils';

  const islandId = $props.id();

  await (isServer ? delay(1000, 3000) : Promise.resolve());

  const randomNumber = Math.floor(Math.random() * 1000);
</script>

<div class="server-no-props">
  <p>Server island without props</p>
  <p class="number">Random number generated on server: <strong>{randomNumber}</strong></p>
  <p class="island-id">$props.id(): <strong>{islandId}</strong></p>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/server-island': Mochi.page('./src/demos/server-island/ServerIsland.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: server-props

### ServerProps.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import { sources } from './sources.prerender.ts';

  let { renderedAt, userAgent, random }: { renderedAt: string; userAgent: string; random: number } = $props();
</script>

<DemoPage
  title="Server Props"
  description="You can pass data from the route definition into the root Svelte component for the route via a serverProps resolver. The resolver runs on every request, so each reload produces fresh values."
  {sources}
>
  <div class="card">
    <dl>
      <dt>Rendered at</dt>
      <dd><code>{renderedAt}</code></dd>

      <dt>Random number</dt>
      <dd><code>{random}</code></dd>

      <dt>Your User-Agent</dt>
      <dd><code>{userAgent}</code></dd>
    </dl>
    <p class="hint">Reload the page to see the values change — each request re-runs the resolver.</p>
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/server-props': Mochi.page('./src/demos/server-props/ServerProps.svelte', {
    serverProps: (req) => ({
      renderedAt: new Date().toISOString(),
      userAgent: req.headers.get('user-agent') ?? 'unknown',
      random: Math.floor(Math.random() * 10_000),
    }),
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: shared-state

### SharedState.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CounterButton from './CounterButton.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Shared State"
  description="You can share reactive $state between separately-hydrated islands. Click either button — the count stays in sync across both."
  {sources}
>
  <div class="row">
    <CounterButton mochi:hydrate />
    <CounterButton mochi:hydrate />
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### CounterButton.svelte
```svelte
<script lang="ts">
  import { getLikes, like } from '../../stores/likes.svelte.ts';
</script>

<button class="counter-btn" onclick={like}>
  <span class="counter-label">♥ Likes</span>
  <span class="counter-value">{getLikes() ?? 0}</span>
</button>

<style>
  /* Styles omitted */
</style>
```

### likes.svelte.ts
```ts
const STORAGE_KEY = 'likes';

const stored = typeof localStorage !== 'undefined' ? localStorage.getItem(STORAGE_KEY) : null;

let likes: number | null = $state(stored !== null ? Number(stored) : null);

export function getLikes(): number | null {
  return likes;
}

export function like() {
  likes = (likes ?? 0) + 1;
  localStorage.setItem(STORAGE_KEY, String(likes));
}
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/shared-state': Mochi.page('./src/demos/shared-state/SharedState.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: static-dirs

### StaticDirsDemo.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import ImageCredits from '../../components/ImageCredits.svelte';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';

  const photos = [1, 2, 3, 6, 9, 13];

  const config = await highlightCode(
    [
      '// One Bun directory route serves the whole tree — no per-file registration.',
      'await Mochi.serve({',
      "  staticDirs: { '/gallery': './images' },",
      '  routes,',
      '});',
      '',
      '// GET /gallery/mochi-1.jpg  ->  packages/site/images/mochi-1.jpg',
      '//   served byte-for-byte, with Content-Type / ETag / Range / 304 from Bun.',
    ].join('\n'),
    'typescript',
  );
</script>

<DemoPage
  title="Static Directories"
  description="staticDirs mounts a whole directory tree under a URL prefix as a single Bun directory route. Every file inside is served straight from disk — Content-Type, ETag, conditional 304s, Range requests and index.html all come from Bun, with no per-file route registration."
  {sources}
>
  <p>
    The gallery below is the site's <code>images/</code> folder, mounted at <code>/gallery</code>. Each
    <code>&lt;img&gt;</code> points straight at the file on disk — a plain path, no query string, no signing, unlike the transformed
    <a href="/demos/image-pipeline/">image pipeline</a>.
  </p>
  <CodeSnippet html={config} />

  <div class="grid">
    {#each photos as n (n)}
      <figure>
        <img src="/gallery/mochi-{n}.jpg" alt="Mochi photo {n}" loading="lazy" />
        <figcaption><code>/gallery/mochi-{n}.jpg</code></figcaption>
      </figure>
    {/each}
  </div>

  <h3>When to reach for it</h3>
  <p>
    <code>staticDirs</code> is one route per mount, so it stays cheap for large or generated trees — a media library, a docs export, another tool's build directory. It serves
    dotfiles and returns Bun's bare 404 on a miss. For ordinary site assets keep using <code>publicDir</code>, which registers one route per file, skips dotfiles, and falls through
    to your error page.
  </p>

  <ImageCredits />
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/static-dirs': Mochi.page('./src/demos/static-dirs/StaticDirsDemo.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  // Mount a directory tree under a URL prefix — one Bun route, files served straight from disk.
  staticDirs: { '/gallery': './images' },
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: streams

### Streams.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import RealtimeClocks from './RealtimeClocks.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Real-time Streams"
  description="You can build a WebSocket clock and a Server-Sent Events clock side by side, ticking every second. The component hydrates only when scrolled into view via mochi:hydrate:visible with a 100px rootMargin."
  {sources}
>
  <RealtimeClocks mochi:hydrate />
</DemoPage>
```

### RealtimeClocks.svelte
```svelte
<script lang="ts">
  const islandId = $props.id();

  let wsTime = $state('--:--:--');
  let sseTime = $state('--:--:--');
  let wsStatus = $state('connecting');
  let sseStatus = $state('connecting');

  $effect(() => {
    const host = window.location.host;
    const wsProtocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';

    const timeWs = new WebSocket(`${wsProtocol}//${host}/ws/time`);
    timeWs.addEventListener('open', () => {
      wsStatus = 'connected';
    });
    timeWs.addEventListener('message', (e) => {
      wsTime = new Date(e.data).toLocaleTimeString('en-GB');
    });
    timeWs.addEventListener('close', () => {
      wsStatus = 'disconnected';
    });

    const timeSse = new EventSource('/sse/time');
    timeSse.addEventListener('open', () => {
      sseStatus = 'connected';
    });
    timeSse.addEventListener('message', (e) => {
      sseTime = new Date(e.data).toLocaleTimeString('en-GB');
    });
    timeSse.addEventListener('error', () => {
      sseStatus = 'disconnected';
    });

    const closeAll = () => {
      timeWs.close();
      timeSse.close();
    };
    window.addEventListener('pagehide', closeAll);

    return () => {
      window.removeEventListener('pagehide', closeAll);
      closeAll();
    };
  });
</script>

<div class="clocks">
  <div class="clock">
    <div class="clock-header">
      <span class="protocol">WebSocket</span>
      <span class="status" class:connected={wsStatus === 'connected'}>{wsStatus}</span>
    </div>
    <span class="time">{wsTime}</span>
    <span class="endpoint">/ws/time</span>
  </div>
  <div class="clock">
    <div class="clock-header">
      <span class="protocol">SSE</span>
      <span class="status" class:connected={sseStatus === 'connected'}>{sseStatus}</span>
    </div>
    <span class="time">{sseTime}</span>
    <span class="endpoint">/sse/time</span>
  </div>
  <div class="island-id">$props.id(): {islandId}</div>
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/streams': Mochi.page('./src/demos/streams/Streams.svelte'),
  '/ws/time': (() => {
    const intervals = new WeakMap();
    return Mochi.ws({
      open(ws) {
        ws.send(new Date().toISOString());
        const interval = setInterval(() => {
          ws.send(new Date().toISOString());
        }, 1000);
        intervals.set(ws, interval);
      },
      message() {},
      close(ws) {
        clearInterval(intervals.get(ws));
        intervals.delete(ws);
      },
    });
  })(),
  '/sse/time': Mochi.sse((stream) => {
    stream.send(new Date().toISOString());
    const interval = setInterval(() => {
      stream.send(new Date().toISOString());
    }, 1000);
    stream.onClose(() => clearInterval(interval));
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: tanstack-table

### TanStackTable.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import BasicTable from './BasicTable.svelte';
  import SortableTable from './SortableTable.svelte';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';

  const codeInstall = await highlightCode('bun add @tanstack/svelte-table', 'bash');
  const codeUsage = await highlightCode(
    `import { createTable, FlexRender, tableFeatures } from '@tanstack/svelte-table';

const table = createTable({
  features: tableFeatures({}), // opt into features (sorting, filtering…) as you need them
  columns,
  get data() {
    return people; // a getter keeps the table in sync with your $state
  },
});
// then render table.getHeaderGroups() / table.getRowModel() with <FlexRender />`,
    'typescript',
  );
</script>

<DemoPage
  title="Tables with TanStack Table"
  description="TanStack Table is a headless table library. A read-only table renders entirely on the server and ships zero JavaScript; interactive features like sorting opt into a mochi:hydrate island."
  {sources}
>
  <div class="intro">
    <p>
      TanStack Table needs no special setup — it's a headless, framework-agnostic table library with a Svelte 5 runes adapter. You install it and import from <code
        >@tanstack/svelte-table</code
      >; in Mochi it bundles straight into whichever island imports it.
    </p>
    <CodeSnippet html={codeInstall} />
    <p>
      Declare which features you need with <code>tableFeatures</code>, pass your <code>columns</code> and
      <code>data</code>, then render the header/cell definitions with <code>&lt;FlexRender /&gt;</code>:
    </p>
    <CodeSnippet html={codeUsage} />
    <p>
      Full API at <a href="https://tanstack.com/table" target="_blank" rel="noopener noreferrer">tanstack.com/table</a>.
    </p>
  </div>

  <section class="card">
    <header>
      <h2>Read-only table — server-rendered, zero JS</h2>
      <p>
        The whole table is plain server HTML: no <code>mochi:hydrate</code>, so nothing ships to the browser. This only makes sense when you don't need sorting, filtering, or any
        client interaction — otherwise reach for an island.
      </p>
    </header>
    <BasicTable />
  </section>

  <section class="card">
    <header>
      <h2>Sortable table — <code>mochi:hydrate</code></h2>
      <p>
        Registering <code>rowSortingFeature</code> makes the headers clickable — cycle ascending → descending → unsorted. Sorting runs on the client, so this card is a hydrated island.
      </p>
    </header>
    <SortableTable mochi:hydrate />
  </section>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### BasicTable.svelte
```svelte
<script lang="ts">
  import { createTable, FlexRender, tableFeatures } from '@tanstack/svelte-table';
  import type { ColumnDef } from '@tanstack/svelte-table';
  import { people, type Person } from './data.ts';

  const features = tableFeatures({});

  const columns: ColumnDef<typeof features, Person>[] = [
    { accessorKey: 'firstName', header: 'First name', cell: (info) => info.getValue() },
    { accessorKey: 'lastName', header: 'Last name', cell: (info) => info.getValue() },
    { accessorKey: 'age', header: 'Age', cell: (info) => info.getValue() },
  ];

  const table = createTable({
    features,
    columns,
    get data() {
      return people;
    },
  });
</script>

<div class="table-wrap">
  <table>
    <thead>
      {#each table.getHeaderGroups() as headerGroup (headerGroup.id)}
        <tr>
          {#each headerGroup.headers as header (header.id)}
            <th>
              {#if !header.isPlaceholder}
                <FlexRender {header} />
              {/if}
            </th>
          {/each}
        </tr>
      {/each}
    </thead>
    <tbody>
      {#each table.getRowModel().rows as row (row.id)}
        <tr>
          {#each row.getAllCells() as cell (cell.id)}
            <td><FlexRender {cell} /></td>
          {/each}
        </tr>
      {/each}
    </tbody>
  </table>
</div>

<style>
  /* Styles omitted */
</style>
```

### SortableTable.svelte
```svelte
<script lang="ts">
  import { createSortedRowModel, createTable, FlexRender, rowSortingFeature, sortFns, tableFeatures } from '@tanstack/svelte-table';
  import type { ColumnDef } from '@tanstack/svelte-table';
  import { people, type Person } from './data.ts';

  const features = tableFeatures({
    rowSortingFeature,
    sortedRowModel: createSortedRowModel(),
    sortFns,
  });

  const columns: ColumnDef<typeof features, Person>[] = [
    { accessorKey: 'firstName', header: 'First name', cell: (info) => info.getValue() },
    { accessorKey: 'lastName', header: 'Last name', cell: (info) => info.getValue() },
    { accessorKey: 'age', header: 'Age', cell: (info) => info.getValue() },
  ];

  const table = createTable({
    features,
    columns,
    get data() {
      return people;
    },
  });
</script>

<div class="table-wrap">
  <table>
    <thead>
      {#each table.getHeaderGroups() as headerGroup (headerGroup.id)}
        <tr>
          {#each headerGroup.headers as header (header.id)}
            <th>
              {#if !header.isPlaceholder}
                <button
                  type="button"
                  class="sort"
                  class:active={header.column.getIsSorted() !== false}
                  disabled={!header.column.getCanSort()}
                  onclick={header.column.getToggleSortingHandler()}
                >
                  <FlexRender {header} />
                  <span class="arrow" aria-hidden="true">
                    {#if header.column.getIsSorted() === 'asc'}
                      ▲
                    {:else if header.column.getIsSorted() === 'desc'}
                      ▼
                    {/if}
                  </span>
                </button>
              {/if}
            </th>
          {/each}
        </tr>
      {/each}
    </thead>
    <tbody>
      {#each table.getRowModel().rows as row (row.id)}
        <tr>
          {#each row.getAllCells() as cell (cell.id)}
            <td><FlexRender {cell} /></td>
          {/each}
        </tr>
      {/each}
    </tbody>
  </table>
</div>

<style>
  /* Styles omitted */
</style>
```

### data.ts
```ts
export type Person = { firstName: string; lastName: string; age: number };

export const people: Person[] = [
  { firstName: 'tanner', lastName: 'linsley', age: 24 },
  { firstName: 'tandy', lastName: 'miller', age: 40 },
  { firstName: 'joe', lastName: 'dirte', age: 45 },
  { firstName: 'kevin', lastName: 'vandy', age: 33 },
  { firstName: 'nora', lastName: 'reed', age: 29 },
];
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/tanstack-table': Mochi.page('./src/demos/tanstack-table/TanStackTable.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: url

### Url.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import UrlInfo from './UrlInfo.svelte';
  import { sources } from './sources.prerender.ts';
</script>

<DemoPage
  title="Isomorphic URL"
  description={"import { url } from 'mochi-framework' returns the current URL on both server and client. On the server it reads from the request context; on the client it reads from window.location. Try adding ?name=mochi to the URL."}
  {sources}
>
  <div class="sections">
    <UrlInfo label="SSR snapshot" />
    <hr />
    <UrlInfo label="Hydrated island" mochi:hydrate />
  </div>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### UrlInfo.svelte
```svelte
<script lang="ts">
  import { url, isServer } from 'mochi-framework';

  let { label = '' } = $props();

  const env = isServer ? 'server' : 'client';

  function getParams(): [string, string][] {
    return [...url.searchParams] as [string, string][];
  }
</script>

<div class="url-info">
  <h3>{label} <span class="env">({env})</span></h3>

  <div class="props">
    <div class="prop"><span class="key">href</span> <code>{url.href}</code></div>
    <div class="prop"><span class="key">origin</span> <code>{url.origin}</code></div>
    <div class="prop"><span class="key">pathname</span> <code>{url.pathname}</code></div>
    <div class="prop"><span class="key">search</span> <code>{url.search || '(empty)'}</code></div>
    <div class="prop">
      <span class="key">hash</span>
      <code>{url.hash || '(empty)'}</code>
      {#if isServer}<span class="note">never sent to the server</span>{/if}
    </div>
  </div>

  {#if getParams().length > 0}
    <div class="params">
      <h4>searchParams</h4>
      {#each getParams() as [key, value] (key)}
        <div class="prop"><span class="key">{key}</span> <code>{value}</code></div>
      {/each}
    </div>
  {/if}
</div>

<style>
  /* Styles omitted */
</style>
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/url': Mochi.page('./src/demos/url/Url.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```

## Demo: varlock

### Varlock.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import CodeSnippet from '../../components/CodeSnippet.svelte';
  import Badge from '../../components/Badge.svelte';
  import { sources } from './sources.prerender.ts';
  import { highlightCode } from '../../lib/highlight.server';
  import type { VarlockConfig } from './env.ts';

  let { config }: { config: VarlockConfig } = $props();

  const codeInstall = await highlightCode('bun add varlock', 'bash');
  const codeUsage = await highlightCode(
    `import { load } from 'varlock';
import { ENV } from 'varlock/env';

await load(); // parse + validate .env.schema once at boot
const port = ENV.DEMO_API_PORT; // typed + coerced: a number, not a string`,
    'typescript',
  );
</script>

<DemoPage
  title="Varlock env schemas"
  description="Load a validated, typed .env schema with Varlock and read live config through the ENV proxy on every SSR render — with types, coercion, variable expansion, and redacted secrets."
  {sources}
>
  <div class="intro">
    <p>
      <a href="https://varlock.dev" target="_blank" rel="noopener noreferrer">Varlock</a> turns your
      <code>.env</code> into a validated, typed schema — a <code>.env.schema</code> annotated with JSDoc-style decorators (<code>@type</code>, <code>@required</code>,
      <code>@sensitive</code>). Mochi renders every page on the server on each request, so there's nothing to prerender or statically inline: you <code>load()</code> the schema
      once at boot, then read live values through the typed <code>ENV</code> proxy during SSR.
    </p>
    <CodeSnippet html={codeInstall} />
    <p>
      Point <code>package.json</code>'s <code>varlock.loadPath</code> at your schema, then do this once at the top of your server entry — <code>index.ts</code>, before
      <code>Mochi.serve()</code> — so config is validated before the server boots and every request can read it:
    </p>
    <CodeSnippet html={codeUsage} />
    <p>
      The <code>index.ts</code> tab below shows the full wiring, including <code>patchGlobalConsole()</code> to keep secrets out of your logs. See the decorator DSL at
      <a href="https://varlock.dev" target="_blank" rel="noopener noreferrer">varlock.dev</a>.
    </p>
  </div>

  <section class="card">
    <header>
      <h2>Resolved on this request</h2>
      <p>These values were parsed, coerced, and validated by <code>varlock</code> during this page's SSR render.</p>
    </header>
    <table class="config">
      <thead>
        <tr><th>Variable</th><th>Value</th><th>Reads as</th></tr>
      </thead>
      <tbody>
        {#each config.items as item (item.key)}
          <tr>
            <td class="var">
              <code>{item.key}</code>
              {#if item.isSensitive}<Badge kind="danger">@sensitive</Badge>{/if}
            </td>
            <td>
              {#if item.isSensitive}
                <span class="masked">••••••••</span>
              {:else}
                <code>{item.value}</code>
              {/if}
            </td>
            <td><code>{item.jsType}</code></td>
          </tr>
        {/each}
      </tbody>
    </table>
    <p class="note">
      <code>DEMO_API_PORT</code> arrives as a JavaScript <code>number</code> ({config.apiPort}), and
      <code>DEMO_API_URL</code> already has its <code>{'${DEMO_API_PORT}'}</code> reference expanded to
      <code>{config.apiUrl}</code>. The <code>@sensitive</code> key never leaves the server — it's masked before it reaches the props, and <code>patchGlobalConsole()</code> keeps it
      out of your logs.
    </p>
  </section>
</DemoPage>

<style>
  /* Styles omitted */
</style>
```

### env.ts
```ts
import { load } from 'varlock';
import { ENV } from 'varlock/env';

// varlock's CLI generates this augmentation from the schema; we inline it so `ENV.KEY` stays fully typed.
declare module 'varlock/env' {
  interface TypedEnvSchema {
    DEMO_APP_ENV: 'development' | 'preview' | 'production';
    DEMO_API_PORT: number;
    DEMO_API_URL: string;
    DEMO_SECRET_KEY: string;
  }
}

export interface VarlockItem {
  key: string;
  value: string | null;
  jsType: string;
  isSensitive: boolean;
}

export interface VarlockConfig {
  items: VarlockItem[];
  apiUrl: string;
  apiPort: number;
}

let cached: VarlockConfig | null = null;

export async function loadVarlockConfig(): Promise<VarlockConfig> {
  if (cached) {
    return cached;
  }

  await load();

  const graph = JSON.parse(process.env.__VARLOCK_ENV ?? '{}') as {
    config?: Record<string, { value: unknown; isSensitive?: boolean }>;
  };

  const items: VarlockItem[] = Object.entries(graph.config ?? {}).map(([key, item]) => ({
    key,
    isSensitive: Boolean(item.isSensitive),
    jsType: typeof item.value,
    value: item.isSensitive ? null : String(item.value),
  }));

  cached = { items, apiUrl: ENV.DEMO_API_URL, apiPort: ENV.DEMO_API_PORT };
  return cached;
}
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';
import { loadVarlockConfig } from './env';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/varlock': Mochi.page('./src/demos/varlock/Varlock.svelte', {
    serverProps: async () => ({ config: await loadVarlockConfig() }),
  }),
};
```

### .env.schema
```bash
# @defaultSensitive=false @defaultRequired=infer @currentEnv=$DEMO_APP_ENV
# ---

# Which environment we're running in — drives automatic loading of `.env.<env>` files.
# @type=enum(development, preview, production)
DEMO_APP_ENV=development

# The port the API listens on — coerced from string to a number.
# @type=port
DEMO_API_PORT=8080

# Built by expanding another variable — `${DEMO_API_PORT}` is resolved at load time.
# @type=url
DEMO_API_URL=http://localhost:${DEMO_API_PORT}

# A secret: required, redacted from logs, and validated to start with `sk-`.
# @required @sensitive @type=string(startsWith=sk-)
DEMO_SECRET_KEY=sk-demo-000000000000
```

### index.ts
```ts
import { load } from 'varlock';
import { patchGlobalConsole } from 'varlock/patch-console';
import { ENV } from 'varlock/env';
import { Mochi } from 'mochi-framework';
import { routes } from './routes';

// Parse + validate `.env.schema` before any code reads config; throws on a schema violation.
await load();

// Redact every `@sensitive` value from console output for the rest of the process.
patchGlobalConsole();

await Mochi.serve({
  port: ENV.DEMO_API_PORT,
  development: ENV.DEMO_APP_ENV === 'development',
  routes,
});
```

## Demo: view-transitions

### PageOne.svelte
```svelte
<script lang="ts">
  import { url } from 'mochi-framework';
  import { ViewTransitions } from 'mochi-framework/components';
  import DemoPage from '../../components/DemoPage.svelte';
  import TransitionCard from './TransitionCard.svelte';
  import { description, sources, parseTransition } from './shared';

  const type = parseTransition(url.searchParams.get('type'));
</script>

<DemoPage title="View Transitions" {description} {sources}>
  <ViewTransitions {type} regions="card" />
  <TransitionCard page={1} {type} />
</DemoPage>
```

### PageTwo.svelte
```svelte
<script lang="ts">
  import { url } from 'mochi-framework';
  import { ViewTransitions } from 'mochi-framework/components';
  import DemoPage from '../../components/DemoPage.svelte';
  import TransitionCard from './TransitionCard.svelte';
  import { description, sources, parseTransition } from './shared';

  const type = parseTransition(url.searchParams.get('type'));
</script>

<DemoPage title="View Transitions" {description} {sources}>
  <ViewTransitions {type} regions="card" />
  <TransitionCard page={2} {type} />
</DemoPage>
```

### TransitionCard.svelte
```svelte
<script lang="ts">
  import PersistentVideo from './PersistentVideo.svelte';
  import ViewTransitionFirefoxNote from '../../components/ViewTransitionFirefoxNote.svelte';
  import { TRANSITIONS, type TransitionType } from './shared';

  let { page, type }: { page: 1 | 2; type: TransitionType } = $props();

  const self = $derived(page === 1 ? '/demos/view-transitions' : '/demos/view-transitions/two');
  const other = $derived(page === 1 ? '/demos/view-transitions/two' : '/demos/view-transitions');
  const query = $derived(type === 'fade' ? '' : `?type=${type}`);
</script>

<div class="card" class:two={page === 2}>
  <span class="num">Page {page}</span>
  <p>Each navigation is a full page load — the browser animates it with a <code>{type}</code> transition.</p>
  <a class="next" href={`${other}${query}`}>Go to page {page === 1 ? 2 : 1} →</a>
</div>

<ViewTransitionFirefoxNote />

<div class="picker">
  <span>Transition:</span>
  {#each TRANSITIONS as opt (opt)}
    <a class="opt" class:active={type === opt} href={opt === 'fade' ? self : `${self}?type=${opt}`}>{opt}</a>
  {/each}
</div>

<PersistentVideo />

<style>
  /* Styles omitted */
</style>
```

### PersistentVideo.svelte
```svelte
<script lang="ts">
  import { persistentVideoScript } from './persistent.js';
</script>

<video class="vt-video" src="/mochi.mp4" autoplay muted loop playsinline></video>
<p class="vt-credit">
  Music:
  <a href="https://pixabay.com/music/world-traditional-japanese-2-437931/" target="_blank" rel="noopener noreferrer">Traditional Japanese 2 — Bounce-Bay-Records</a>
</p>
<!-- eslint-disable-next-line svelte/no-at-html-tags -- self-authored boot script (persistent.js), not end-user input; runs on initial parse to resume the video timestamp without a hydration bundle -->
{@html persistentVideoScript}

<style>
  /* Styles omitted */
</style>
```

### persistent.js
```ts
// Rendered into the page via {@html} in PersistentVideo.svelte, so it runs on initial parse of every
// page — including after a cross-document navigation — resuming the video with no hydration bundle.
// The closing script tag is split across concatenation here rather than assembled in the .svelte file,
// since a literal one there would close that file's own script block early.
export const persistentVideoScript =
  `<script>(function () {
  var KEY = 'mochi-vt-video-time';
  var video =
    (document.currentScript &&
      document.currentScript.parentElement &&
      document.currentScript.parentElement.querySelector('video.vt-video')) ||
    document.querySelector('video.vt-video');
  if (!video) return;

  // sessionStorage can throw in some privacy modes; the video then simply
  // restarts on each navigation instead of resuming.
  var saved = null;
  try {
    saved = sessionStorage.getItem(KEY);
  } catch {}
  if (saved) {
    var t = parseFloat(saved);
    var restore = function () {
      if (Number.isFinite(t)) video.currentTime = t;
    };
    if (video.readyState >= 1) restore();
    else video.addEventListener('loadedmetadata', restore, { once: true });
  }

  window.addEventListener('pagehide', function () {
    try {
      sessionStorage.setItem(KEY, String(video.currentTime));
    } catch {}
  });
})();</scr` + `ipt>`;
```

### routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/view-transitions': Mochi.page('./src/demos/view-transitions/PageOne.svelte'),
  '/demos/view-transitions/two': Mochi.page('./src/demos/view-transitions/PageTwo.svelte'),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes } from './routes';

await Mochi.serve({
  port: 3333,
  routes,
});

logger.info('Server running at http://localhost:3333');
```


# Blog Posts


---
title: 'Mochi 0.9.0'
slug: mochi-0-9-0
description: 'The rsvelte compiler backend, per-request caching, relocatable build output, and precompiled email templates — 30 commits since 0.8.0.'
date: '2026-07-28'
author: stanislav
---

<script>
  import Callout from '../../../docs/_components/Callout.svelte';
</script>

# Mochi 0.9.0

Mochi 0.9.0 is out, with 30 commits since [0.8.0](https://github.com/khromov/mochi/blob/main/packages/mochi/CHANGELOG.md). It's a smaller release, but with some breaking changes.

- [Faster builds with rsvelte](#faster-builds-with-rsvelte)
- [Request cache](#request-cache)
- [Relocatable builds](#relocatable-builds)
- [Precompiled email templates](#precompiled-email-templates)
- [Other improvements](#other-improvements)
- [Install or upgrade](#install-or-upgrade)

## Faster builds with rsvelte

[rsvelte](https://github.com/baseballyama/rsvelte) is a Rust port of the Svelte 5 compiler built on [OXC](https://oxc.rs/), and Mochi can now route component compilation through it. It's [opt-in](/docs/rsvelte/) — add `@mochi-framework/rsvelte` and pick the backend:

```ts
await Mochi.serve({
  svelteCompiler: 'rsvelte',
  routes,
});
```

On the `demos` preset from `bun create mochi@latest`:

| phase           | svelte | rsvelte |    delta |
| --------------- | -----: | ------: | -------: |
| total           |  384ms |   289ms | **−25%** |
| `ssr-build`     |  213ms |   137ms | **−36%** |
| `client-bundle` |   40ms |    26ms | **−35%** |

## Request cache

[The request cache](/docs/request-cache/) memoizes work for the duration of a single HTTP request, so a lookup rendered by ten components runs once. Concurrent callers share one in-flight promise. The cache is reset on every new request.

```ts
import { requestCache, requestMemo } from 'mochi-framework';

const user = await requestCache(`user:${id}`, () => db.user(id));

// Or wrap once at module scope — every importer shares the memo.
export const getUser = requestMemo((id: string) => db.user(id));
```

## Relocatable builds

Build output no longer contains a single absolute path, and the same commit built on any machine produces identical island names, bundle filenames and SSR'd HTML.

```ts
Mochi.serve({ manifest: '/srv/app/build/manifest.json' });
```

<Callout type="danger">

**Breaking change:** re-run `mochi-framework build` when you upgrade — the [manifest](/docs/production-builds/#relocatable-builds) is now versioned, and an older build throws at startup.

</Callout>

### The public directory

`publicDir` is no longer copied into the build — the runtime scans it from disk at boot.

<Callout type="danger">

**Breaking change:** keep `public` out of your `.dockerignore`.

</Callout>

## Precompiled email templates

`mochi-framework build` now compiles every template in `src/emails/` into the manifest, so sending no longer waits on a cold compile.

```ts
await Mochi.email({ to, subject: 'Welcome', component: './src/emails/Welcome.svelte', props });
```

<Callout type="danger">

**Breaking change:** [email templates](/docs/email/#svelte-templates) must live in `src/emails/`.

</Callout>

## Other improvements

- **Captcha** — [`<MochiCaptcha />`](/docs/captcha/) no longer hangs on slow mobile browsers, and its proof-of-work difficulty and solve budget are now configurable.
- **Extensions** — pulling a [server-only module](/docs/extensions/#server-only) into a client bundle now fails the build.
- **Svelte Shaker** — [`optimize`](/docs/svelte-shaker/) requires `svelte-shaker` 0.18.1 or newer, which fixes a bug that stripped `mochi:` directives so islands never hydrated.

## Install or upgrade

New project:

```sh
bun create mochi@latest my-app
```

Existing project — bump the dependency and restart the dev server:

```sh
bun add mochi-framework@latest   # or @0.9.0 to pin
bun run dev
```

The [full changelog](https://github.com/khromov/mochi/blob/main/packages/mochi/CHANGELOG.md) has everything else. Mochi is still early and in alpha — if something breaks, [Discord](/discord/) or a [GitHub issue](https://github.com/khromov/mochi/issues) both work.

---
title: 'Mochi 0.8.0'
slug: mochi-0-8-0
description: 'Queues, transactional email, image transforms, captcha and rate limiting — 93 commits since 0.7.0.'
date: '2026-07-21'
author: stanislav
---

<script>
  import { Image } from 'mochi-framework/image';
  import PostImageGrid from '../components/PostImageGrid.svelte';
  import PostCaptchaDemo from '../components/PostCaptchaDemo.svelte';
  import PostRateLimitDemo from '../components/PostRateLimitDemo.svelte';
  import emailOutbox from '../../../docs/images/email-outbox.png';
  import debugBar from '../../../docs/images/debug-bar.png';
</script>

# Mochi 0.8.0

Mochi 0.8.0 is out — bringing 93 commits since [0.7.0](https://github.com/khromov/mochi/blob/main/packages/mochi/CHANGELOG.md) — the biggest release so far. The main features in this release are:

- [Image transformations](#image-transformations)
- [Email sending](#email-sending)
- [Queues](#queues)
- [Form captcha](#form-captcha)
- [Rate limiting](#rate-limiting)
- [Client-only components](#client-only-components)
- [Debug bar improvements](#debug-bar-improvements)
- [Other improvements](#other-improvements)
- [Looking ahead](#looking-ahead)
- [Install or upgrade](#install-or-upgrade)

## Image transformations

Mochi now supports [runtime image transformations](/docs/images/). Images are also automatically cached. Both Vite-style imports _and external servers_ are supported for fetching images. We also get a new `<Image />` component for responsive images.

```ts
await Mochi.serve({
  image: {
    sizes: {
      thumbnail: { width: 200, height: 200, fit: 'inside', format: 'webp', quality: 80 },
    },
  },
  // …
});
```

Then reference the size by name wherever you need it — the source is either a Vite-style import or a remote URL:

```svelte
<script>
  import { Image } from 'mochi-framework/image';
  import photo from './photo.jpg';
</script>

<Image src={photo} size="thumbnail" alt="A resized photo" />
<Image src="https://example.com/photo.jpg" size="thumbnail" alt="A resized remote photo" />
```

Every tile below is the same kind of source photo run through a different named size declared on this site:

<PostImageGrid />

## Email sending

[`Mochi.email()`](/docs/email/) brings first-class support for sending emails via Mochi. After configuring an email transport in `Mochi.serve()`, you can send emails from a page action, an API route or even a queue job. Making templates is a breeze thanks to the built-in support for using Svelte components as email templates, with automatic CSS inlining.

```ts
await Mochi.email({
  to: 'alice@example.com',
  subject: 'Reset your password',
  html: '<p>Click <a href="…">here</a> to reset.</p>',
});
```

In development every message also lands in a development outbox, so you can read what your app just sent without any extra setup:

<figure>
  <a href={emailOutbox.src} target="_blank" rel="noopener">
    <Image src={emailOutbox} size="doc" width={emailOutbox.width} height={emailOutbox.height} alt="The dev email outbox: captured messages on the left, and the selected message's headers, attachment chip, Preview / Text / Source tabs and rendered body on the right" />
  </a>
  <figcaption>The dev outbox.</figcaption>
</figure>

## Queues

Use [`Mochi.queue()`](/docs/queues/) to easily defer work to the background and take it off the request path — for example sending email, encoding media or calling a slow API.

```ts
await Mochi.serve({
  routes,
  queues: {
    emails: Mochi.queue<{ to: string }>({
      concurrency: 10,
      process: async (job) => sendEmail(job.data.to),
    }),
  },
});

await Mochi.getQueue<{ to: string }>('emails').add('send', { to: 'alice@example.com' });
```

## Form captcha

[`<MochiCaptcha />`](/docs/captcha/) is a simple CAPTCHA based on cryptographic proof-of-work — no third-party service or extra costs.

You'll find a real example below:

<PostCaptchaDemo mochi:hydrate />

The [captcha demo](/demos/captcha/) covers the failure modes — replay, expiry, and a submit that never solved the slider.

## Rate limiting

Any `Mochi.page()` or `Mochi.api()` route can now take a [`rateLimit`](/docs/rate-limiting/) config, allowing you to easily rate limit a route.

<PostRateLimitDemo mochi:hydrate />

```ts
'/api/data': Mochi.api(handler, {
  rateLimit: { limit: 100, window: '1m' },
}),
```

A `skip` callback decides per request whether to spend quota:

```ts
'/admin': Mochi.page('./src/admin/Admin.svelte', {
  rateLimit: {
    limit: 10,
    window: '15m',
    ban: { threshold: 3, duration: '1h' },
    skip: (req) => {
      const header = req.headers.get('Authorization');
      return !header || credentialsMatch(header);
    },
  },
}),
```

## Client-only components

Some components can't render on the server at all — canvas, `localStorage`, third-party browser SDKs. The new [`mochi:clientOnly`](/docs/client-only/) directive emits an empty island wrapper during SSR and mounts the component in the browser, with optional fallback markup as children. There's also a `:visible` variant that waits for the viewport.

```svelte
<AudioVisualizer mochi:clientOnly />
```

## Debug bar improvements

The dev [debug bar](/docs/debug-bar/) grew alongside the new features: an **Images** tab for inspecting every transform on the page, a **Cache** tab for watching cache reads and writes, and an **email outbox** indicator that lights up when your app sends mail.

<figure>
  <a href={debugBar.src} target="_blank" rel="noopener">
    <Image src={debugBar} size="doc" width={debugBar.width} height={debugBar.height} alt="The Mochi dev debug bar, showing the Request, Islands, Images, JS, Info, Cache and email-outbox controls" />
  </a>
  <figcaption>The debug bar, with the new Images, Cache and email-outbox controls.</figcaption>
</figure>

## Other improvements

- **Logging** — the severity each framework event lands on is now remappable per app via the `consoleLogger:level` [filter](/docs/extensions/), so you can promote what you care about and demote what you don't without moving the [global level](/docs/logging/).
- **CLI** — the `mochi-framework` command line tool got its own [reference page](/docs/cli/), covering `build`, `generate-key` and `update-skill`.
- **Performance** — faster builds, quicker dev HMR, and smaller client bundles across the board.
- **Package updates** — dependencies across the monorepo bumped to their latest versions.

## Looking ahead

This release was bigger than normal, and a lot of the groundwork was laid in preparation for adding further built-in primitives. Some of the features currently in the pipeline are native internationalization support, `Mochi.http()` (a lightweight wrapper around `fetch` with retries and caching) and `Mochi.feature()` (built-in A/B testing).

Preparation work on the future Integration API has also started. It's inspired by the [equivalent Astro API](https://docs.astro.build/en/reference/integrations-reference/) and lets external packages hook into the framework through the existing hooks and filters system.

## Install or upgrade

New project:

```sh
bun create mochi@latest my-app
```

Existing project — bump the dependency and restart the dev server:

```sh
bun add mochi-framework@latest   # or @0.8.0 to pin
bun run dev
```

If you code with an AI assistant, don't forget to add or refresh the [agent skill](/docs/docs-for-llms/). Copy the line for the agent you use:

```sh
bunx mochi-framework update-skill              # claude-code (default)
bunx mochi-framework update-skill opencode
bunx mochi-framework update-skill antigravity  # alias: agy
bunx mochi-framework update-skill codex
```

The [full changelog](https://github.com/khromov/mochi/blob/main/packages/mochi/CHANGELOG.md) has everything else, including the performance work on builds and dev HMR. Mochi is still early and in alpha — if something breaks, [Discord](/discord/) or a [GitHub issue](https://github.com/khromov/mochi/issues) both work.

---
title: Mochi on This Week in Svelte
slug: this-week-in-svelte
description: A live walkthrough of Mochi with Paolo Ricciuti on This Week in Svelte.
date: '2026-07-20'
author: stanislav
---

<script>
  import YouTubeEmbed from '../components/YouTubeEmbed.svelte';
</script>

# Mochi on This Week in Svelte

<YouTubeEmbed mochi:hydrate id="HCpuzfRdVvI" start={2535} title="This Week in Svelte — Mochi" />

I joined Paolo Ricciuti on _This Week in Svelte_ to demo Mochi and talk through the thinking behind it. The Mochi segment starts at [40:16](https://www.youtube.com/watch?v=HCpuzfRdVvI&t=2535s).

We spent a while on SvelteKit, and where Mochi goes a different way. SvelteKit has to run everywhere — static hosts, serverless, the edge — and that generality shapes what its API can offer. Mochi only targets a stateful server, so it can lean on things SvelteKit can't assume you have — real-time, caching, queues and image resizing are all in the box.

The rest of the segment was live coding:

- A brand new app from `bun create mochi@latest`.
- A click counter that stubbornly did nothing, because the page shipped zero JavaScript, until [`mochi:hydrate`](/docs/selective-hydration/) turned it into an island and the first script tag showed up in the network tab.
- The same counter as a [server island](/docs/server-islands/) with `mochi:defer`, fetched in its own request so it can be cached separately from the page around it.
- A Pokémon page pulling live data from an API, first through `serverProps` on the route, then with a plain `await` at the top of the component.
- That page nearly shipping its entire 183 KB API response to the browser as island props — spotted in the debug bar, and cut down to 22 bytes by passing only the field the island actually reads.

We also talked about what isn't there yet. File-based routing came up from Paolo and from the chat, and it's on my list to revisit before 1.0 — likely through an extensions API rather than baked into the core. I'm also not happy with hot module reloading — it works, but SvelteKit's is nicer.

Mochi is early and in alpha. The [docs](/docs/intro/) and [demos](/) are the fastest way in, and I'd genuinely like to hear what breaks — [Discord](/discord/) or a [GitHub issue](https://github.com/khromov/mochi/issues), either works.

---
title: Hello World
slug: hello-world
description: Introducing the Mochi blog.
date: '2026-07-14'
author: stanislav
---

# Hello World

Welcome to the Mochi blog. Mochi is an SSR-first framework for Svelte 5 on Bun with islands-based selective hydration.

Expect posts on new releases, Mochi internals (how and why things are implemented the way they are) and on the runtime we build on top of, Bun.

If you're new to Mochi, start with the [docs](/docs/intro/) or poke at the live demos on the [home page](/). See you in the next post.

# Changelog

# Changelog

## [0.9.1](https://github.com/khromov/mochi/compare/mochi-framework-v0.9.0...mochi-framework-v0.9.1) (2026-07-30)


### Bug Fixes

* **cache:** run one FileStorage sweeper per directory ([#227](https://github.com/khromov/mochi/issues/227)) ([45f2c7b](https://github.com/khromov/mochi/commit/45f2c7b6ab3153a41d2a5db14b33b0f97e6561b6))

## [0.9.0](https://github.com/khromov/mochi/compare/mochi-framework-v0.8.2...mochi-framework-v0.9.0) (2026-07-28)


### ⚠ BREAKING CHANGES

* **build:** precompile src/emails templates into the manifest - email templates must now be in src/emails ([#220](https://github.com/khromov/mochi/issues/220))
* relocatable build output — manifest v2, publicDir served from disk ([#170](https://github.com/khromov/mochi/issues/170))

### Features

* add optional rsvelte compiler backend ([#197](https://github.com/khromov/mochi/issues/197)) ([df9aede](https://github.com/khromov/mochi/commit/df9aede35eb49cc9ff74a86ef867939bb84b5ccc))
* **build:** precompile src/emails templates into the manifest - email templates must now be in src/emails ([#220](https://github.com/khromov/mochi/issues/220)) ([000e193](https://github.com/khromov/mochi/commit/000e193233227f49484d99d5076b0ceb9a2ab13b))
* **captcha:** fix hang, sync PoW, a11y/CLS, configurable bits/budget ([#199](https://github.com/khromov/mochi/issues/199)) ([5028c6b](https://github.com/khromov/mochi/commit/5028c6b616119c0cd647715050cb982ac0b7f6d5))
* **extensions:** crash when server-only internals reach the client ([#206](https://github.com/khromov/mochi/issues/206)) ([ad496ee](https://github.com/khromov/mochi/commit/ad496eec94ee43127ef2b6d2c38cb44f3b313156))
* memlab heap-snapshot analyzer + property-based fuzzing suite ([#203](https://github.com/khromov/mochi/issues/203)) ([49b3c85](https://github.com/khromov/mochi/commit/49b3c857e0e1635ca1c68a9918ae5d548e80c767))
* relocatable build output — manifest v2, publicDir served from disk ([#170](https://github.com/khromov/mochi/issues/170)) ([b31c052](https://github.com/khromov/mochi/commit/b31c05277a10196a8ba73ea74b88268e7a891bc5))
* request cache ([#202](https://github.com/khromov/mochi/issues/202)) ([9dd20b6](https://github.com/khromov/mochi/commit/9dd20b675b80d8f28176f3c570e7223cf3d34be8))
* warn at boot when publicDir was non-empty at build time but empty at serve ([#214](https://github.com/khromov/mochi/issues/214)) ([f807d31](https://github.com/khromov/mochi/commit/f807d3141db80f033fc708c9c3a8763ffa55138b))


### Bug Fixes

* require svelte-shaker &gt;=0.18.1 so mochi: directives survive shaking ([#221](https://github.com/khromov/mochi/issues/221)) ([f5b4522](https://github.com/khromov/mochi/commit/f5b45224756b2b6431b402a66be3dc9790e83cf1))


### Documentation

* **mochi:** slim down over-verbose source comments ([#217](https://github.com/khromov/mochi/issues/217)) ([82b29f6](https://github.com/khromov/mochi/commit/82b29f6bf55b6f978fbe99742a2c3fff831da34d))

## [0.8.2](https://github.com/khromov/mochi/compare/mochi-framework-v0.8.1...mochi-framework-v0.8.2) (2026-07-21)


### Bug Fixes

* **email:** stop nodemailer TS7016 leaking from the value-level import ([#194](https://github.com/khromov/mochi/issues/194)) ([9575619](https://github.com/khromov/mochi/commit/9575619a416bc2a21aaddbd99c9fc503f3067f34))

## [0.8.1](https://github.com/khromov/mochi/compare/mochi-framework-v0.8.0...mochi-framework-v0.8.1) (2026-07-21)


### Bug Fixes

* **email:** stop leaking a nodemailer TS7016 error into consumers ([#192](https://github.com/khromov/mochi/issues/192)) ([4eb74f2](https://github.com/khromov/mochi/commit/4eb74f2c80e7c886916551680d062048bcb96730))

## [0.8.0](https://github.com/khromov/mochi/compare/mochi-framework-v0.7.0...mochi-framework-v0.8.0) (2026-07-21)


### Features

* add mochi:clientOnly and mochi:clientOnly:visible directives for browser-only components ([#89](https://github.com/khromov/mochi/issues/89)) ([5f318dc](https://github.com/khromov/mochi/commit/5f318dcebc052030652947600b181fb02d2143a0))
* add Mochi.email() transactional mailer ([#140](https://github.com/khromov/mochi/issues/140)) ([58a4850](https://github.com/khromov/mochi/commit/58a485009355e3f3f0b56e4e7e110d820383c556))
* add signed image-resize API with stale-while-revalidate cache ([#65](https://github.com/khromov/mochi/issues/65)) ([d1fb6b6](https://github.com/khromov/mochi/commit/d1fb6b68ae185386ad266b5e437a716a2b0e02d4))
* **cli:** add `bunx mochi-framework generate-key` command ([#114](https://github.com/khromov/mochi/issues/114)) ([f47a029](https://github.com/khromov/mochi/commit/f47a029cfc309a3bd2c24ca4fef67917b319262f))
* **image:** support Vite-style local image imports and filesystem imports ([#169](https://github.com/khromov/mochi/issues/169)) ([33beb89](https://github.com/khromov/mochi/commit/33beb8956786e7a182fe9b9262b0d00324362029))
* **logging:** remappable console log levels ([#179](https://github.com/khromov/mochi/issues/179)) ([b559717](https://github.com/khromov/mochi/commit/b5597172918b121f0bc383b2c27b005b9992959c))
* named image sizes — defer all image transforms to the endpoint, captcha ([#144](https://github.com/khromov/mochi/issues/144)) ([e733500](https://github.com/khromov/mochi/commit/e733500255f3ab14d278e72fc8c2d06e2195549e))
* per-route and global rate limiting via @joint-ops/hitlimit-bun ([#157](https://github.com/khromov/mochi/issues/157)) ([8a51dfd](https://github.com/khromov/mochi/commit/8a51dfdd14d0972a81980ccc743d3a57bab52426))
* precompile server islands into the build manifest ([#132](https://github.com/khromov/mochi/issues/132)) ([a89cce2](https://github.com/khromov/mochi/commit/a89cce20027b8e733a4592cc6acdd010fb9fa79b))
* Reword docs and improve trailingSlash ([#116](https://github.com/khromov/mochi/issues/116)) ([7ab4fa7](https://github.com/khromov/mochi/commit/7ab4fa7e079b05a44eead2301ed6421e951195c9))
* separate dev build cache from production .mochi output ([#130](https://github.com/khromov/mochi/issues/130)) ([1b5f4f6](https://github.com/khromov/mochi/commit/1b5f4f61977a01709a13fe5a3aea4eec09091b31))
* **support:** store submissions, queue email, add admin inbox ([#174](https://github.com/khromov/mochi/issues/174)) ([a47a9d0](https://github.com/khromov/mochi/commit/a47a9d00a7b5c6efe028afaa765837bfe640f74a))
* warn on large barrel imports ([#131](https://github.com/khromov/mochi/issues/131)) ([1d1b36c](https://github.com/khromov/mochi/commit/1d1b36c81244234c8303cdf260ea13d32fe631db))


### Bug Fixes

* always reconnect the dev live-reload socket ([#178](https://github.com/khromov/mochi/issues/178)) ([ebcf467](https://github.com/khromov/mochi/commit/ebcf4677c345cf1052543e1f4d3ced86bdf977dd))
* avoid HTMLRewriter onEndTag request-context leak ([#155](https://github.com/khromov/mochi/issues/155)) ([be5e15e](https://github.com/khromov/mochi/commit/be5e15e899451977bad6a4bf31f53538c169e12a))
* **deps:** update dependencies across the monorepo ([#189](https://github.com/khromov/mochi/issues/189)) ([f220ec5](https://github.com/khromov/mochi/commit/f220ec51f77f2952eafa1bf04075b3fcda3fb63e))
* force-close connections on shutdown so the process actually exits ([#176](https://github.com/khromov/mochi/issues/176)) ([16c3b2f](https://github.com/khromov/mochi/commit/16c3b2fc64a0307d87d44a6cfa008dbdc140cec0))
* forward-slash paths in user-facing output on windows ([#163](https://github.com/khromov/mochi/issues/163)) ([98f05a8](https://github.com/khromov/mochi/commit/98f05a895ee51d8385e26cbbb4ff6dcca36c6cc5))
* fully transpile `<script lang="ts">` in .svelte with Bun ([#128](https://github.com/khromov/mochi/issues/128)) ([d4b9ea0](https://github.com/khromov/mochi/commit/d4b9ea088ba5b9fb949447b4588ce933a3d0f3c7))
* **logger:** make queue added/completed lines visible at the production log level ([#184](https://github.com/khromov/mochi/issues/184)) ([86ddcb4](https://github.com/khromov/mochi/commit/86ddcb497d5a3c01f81aa03dfa75d634139422c6))
* make unresolvable island directives a compile error ([#160](https://github.com/khromov/mochi/issues/160)) ([bef2d60](https://github.com/khromov/mochi/commit/bef2d6074161958b6273a139d92d79c83fcc432f))
* nested islands support — inject CSS for islands inside deferred content and deduplicate the debug bar ([#125](https://github.com/khromov/mochi/issues/125)) ([4044e87](https://github.com/khromov/mochi/commit/4044e87840a546bd58b62717cfabd2a7950af3a8))
* **queue:** stop falsely failing jobs that run longer than 30 seconds ([#188](https://github.com/khromov/mochi/issues/188)) ([32b5209](https://github.com/khromov/mochi/commit/32b5209cbecb273ed26a0204e872a70d840c4a81))
* resolve HTML validation warnings (lang, charset position, aria-label) ([#145](https://github.com/khromov/mochi/issues/145)) ([0b21eca](https://github.com/khromov/mochi/commit/0b21ecaaf7aa51e46a0e245b1003dbaceb4a3b9d))
* resolve validated bugs, security issues & dead code from framework review ([#137](https://github.com/khromov/mochi/issues/137)) ([373e31a](https://github.com/khromov/mochi/commit/373e31a596fc9e3f6f52952fadbcad298a7e6703))
* workaround eisdir testing bug ([#172](https://github.com/khromov/mochi/issues/172)) ([73b4db4](https://github.com/khromov/mochi/commit/73b4db483e3dff6326e04b93d1118751bf767806))


### Performance

* **build:** single client bundle, batched CSS minify, overlapped build steps ([#181](https://github.com/khromov/mochi/issues/181)) ([aac7ea2](https://github.com/khromov/mochi/commit/aac7ea226640337b64c40b301b6f1801a2d83cf0))
* extract mochi-env virtual modules to plain .js templates, decrease bundle by ~2kb for unused client side imports from mochi-framework ([#162](https://github.com/khromov/mochi/issues/162)) ([a5fd1a7](https://github.com/khromov/mochi/commit/a5fd1a712ced7ab357e91c8f05c145a7ae8e6b22))
* memoize per-serve() startup work in mochi framework ([#142](https://github.com/khromov/mochi/issues/142)) ([ef00dea](https://github.com/khromov/mochi/commit/ef00dea4ad2dea7d3c6eb72d4ff7cf6f7f1cf8ed))
* **mochi:** cache compiled component output to speed up dev HMR ([#122](https://github.com/khromov/mochi/issues/122)) ([91420f2](https://github.com/khromov/mochi/commit/91420f2f62913b95b54a020a4d72db68340974a5))


### Documentation

* serve doc screenshots through local image imports ([#186](https://github.com/khromov/mochi/issues/186)) ([b54fe8e](https://github.com/khromov/mochi/commit/b54fe8e58a88a0b9f9cadaf793f758654990020e))


### Code Refactoring

* core cleanup ([#134](https://github.com/khromov/mochi/issues/134)) ([133c26a](https://github.com/khromov/mochi/commit/133c26a7fd4d58e527e1fbee7f44e53ba22b8fb6))
* isolate email render via renderDetached primitive ([#149](https://github.com/khromov/mochi/issues/149)) ([8ac8aa6](https://github.com/khromov/mochi/commit/8ac8aa6d9d021188cb6b0739bcaaf7aae551aeaa))

## [0.7.0](https://github.com/khromov/mochi/compare/mochi-framework-v0.6.0...mochi-framework-v0.7.0) (2026-06-16)


### Features

* add automatic HEAD request support for all route types ([#76](https://github.com/khromov/mochi/issues/76)) ([925ba6c](https://github.com/khromov/mochi/commit/925ba6cca27d92f8c007c251f0f2ebb0ea72953b))
* add official mcp server ([47acc11](https://github.com/khromov/mochi/commit/47acc11e7483ca3b81e3fe6d615d50931589b45c))
* add ViewTransitions and RawScript components (+ view-transitions & custom-transitions demos) ([#66](https://github.com/khromov/mochi/issues/66)) ([7402c28](https://github.com/khromov/mochi/commit/7402c281099feee8c659fd4a6946d0ab45e7af7e))
* configurable debug bar panels via cogwheel setting ([#87](https://github.com/khromov/mochi/issues/87)) ([b36e224](https://github.com/khromov/mochi/commit/b36e2248b7fde216f058945cc0fb23f8a216d6e1))
* Mochi skill ([#100](https://github.com/khromov/mochi/issues/100)) ([ae8fea5](https://github.com/khromov/mochi/commit/ae8fea510d7b900a71d26c15ebe6d5132148bd6d))
* replace islandId auto-prop with native $props.id(), remove nanoid dependency ([#96](https://github.com/khromov/mochi/issues/96)) ([e1236a5](https://github.com/khromov/mochi/commit/e1236a5bc31c5d1edf351c6f0d27bd4ae5e8ec60))


### Bug Fixes

* drop @types/negotiator runtime dep via local ambient declaration ([#88](https://github.com/khromov/mochi/issues/88)) ([773d2d0](https://github.com/khromov/mochi/commit/773d2d05cb0532755c20a98aa7221ea13e452ff6))
* mark shared island props blocks correctly, show actual prop content in debug bar instead of devalue format ([3cda6da](https://github.com/khromov/mochi/commit/3cda6da298b100274254795f4a0a517c82e71373))
* surface svelte-shaker failures and point users at its tracker ([#80](https://github.com/khromov/mochi/issues/80)) ([41fb9eb](https://github.com/khromov/mochi/commit/41fb9ebf6716e3563a0cfa9ce32c7a42ecd85d02))


### Code Refactoring

* replace $props&lt;T&gt;() with annotated let destructuring ([#91](https://github.com/khromov/mochi/issues/91)) ([0304446](https://github.com/khromov/mochi/commit/0304446271e48137b8f136200959fc0be2c8bdeb))
* replace stale-while-revalidate-cache with inline helper (remove 2 deps) ([#92](https://github.com/khromov/mochi/issues/92)) ([dd33f82](https://github.com/khromov/mochi/commit/dd33f820458556e6aecead8b48451d1ff0efbf00))

## [0.6.0](https://github.com/khromov/mochi/compare/mochi-framework-v0.5.1...mochi-framework-v0.6.0) (2026-06-07)


### Features

* add svelte-shaker support and remove routes.ts convention in favor of single index.ts ([#74](https://github.com/khromov/mochi/issues/74)) ([ec4487f](https://github.com/khromov/mochi/commit/ec4487f4dedd75fd5e72be2b38054a4445342178))
* added a new "info" tab to debug bar showing runtime versions and mochi configuration ([a6a1792](https://github.com/khromov/mochi/commit/a6a1792252fd3ec2a063c7e834a9709be9cc26ff))


### Bug Fixes

* **mochi-framework:** various hmr edge case fixes ([ecb627d](https://github.com/khromov/mochi/commit/ecb627daaf75df8f8b39599b7889abc66a624876))
* trigger hmr when shell.html is edited ([#72](https://github.com/khromov/mochi/issues/72)) ([d519b89](https://github.com/khromov/mochi/commit/d519b891ca8d2dc39b4ce7e1e6c3970497f3ce22))
* various hmr edge case fixes ([79048e3](https://github.com/khromov/mochi/commit/79048e3cad8447882feac1362584c63becef75fb))

## [0.5.1](https://github.com/khromov/mochi/compare/mochi-framework-v0.5.0...mochi-framework-v0.5.1) (2026-06-04)


### Bug Fixes

* stray {{mochi.script}} text rendered on pages that mention the placeholder ([#67](https://github.com/khromov/mochi/issues/67)) ([38d3ee4](https://github.com/khromov/mochi/commit/38d3ee4a88660c8db728196b43abc74e02c42546))
* windows support ([8547194](https://github.com/khromov/mochi/commit/854719458680d306910eac12c3aa43feaf3e1f96))

## [0.5.0](https://github.com/khromov/mochi/compare/mochi-framework-v0.4.0...mochi-framework-v0.5.0) (2026-05-28)


### Features

* hot-swap route handlers in dev mode ([#41](https://github.com/khromov/mochi/issues/41)) ([106a4a2](https://github.com/khromov/mochi/commit/106a4a2b4c2a763c6e571cfb13a9ae3d4a61d616))
* opt-in route warmup to pre-warm static pages at startup ([#64](https://github.com/khromov/mochi/issues/64)) ([9f28ede](https://github.com/khromov/mochi/commit/9f28ede42e606f55a78535673a863a779e3db0dd))
* replace highlight.js with Shiki ([#54](https://github.com/khromov/mochi/issues/54)) ([3d2dc6a](https://github.com/khromov/mochi/commit/3d2dc6ae3092f72fd74224770fdcc414bed1922c))


### Code Refactoring

* replace `cookie` npm package with Bun native cookie APIs ([#60](https://github.com/khromov/mochi/issues/60)) ([4e0d953](https://github.com/khromov/mochi/commit/4e0d953c9594eadec8eb047c4373186ed1779456))
* run all tests in per-file isolation, drop .isolated.test.ts suffix ([#55](https://github.com/khromov/mochi/issues/55)) ([68cdc06](https://github.com/khromov/mochi/commit/68cdc065f1ec901131dde40c7da677fefc35c849))
* vendor debounce, drop npm dependency ([#63](https://github.com/khromov/mochi/issues/63)) ([d465fea](https://github.com/khromov/mochi/commit/d465feafbd3bda4ae7657ae4ea6168d0af17cc5f))
* vendor json-format-highlight, drop npm dependency ([#61](https://github.com/khromov/mochi/issues/61)) ([0b88399](https://github.com/khromov/mochi/commit/0b883994a089b8beedfb2e0c703a544b495ce07c))

## [0.4.0](https://github.com/khromov/mochi/compare/mochi-framework-v0.3.2...mochi-framework-v0.4.0) (2026-05-26)


### Features

* make url export isomorphic (server + client) ([#47](https://github.com/khromov/mochi/issues/47)) ([11bbbe6](https://github.com/khromov/mochi/commit/11bbbe6b4d500a7efa17ba7ebc053783a1dd7f5e))
* per-page JS bundle panel in debug bar ([#42](https://github.com/khromov/mochi/issues/42)) ([7eba984](https://github.com/khromov/mochi/commit/7eba9847727f9685566044c1c28ea84bb48704f9))


### Bug Fixes

* resolve Svelte 5 state warnings and add autofixer tooling ([#49](https://github.com/khromov/mochi/issues/49)) ([3d949a5](https://github.com/khromov/mochi/commit/3d949a5cd52592de268a57ae22de9d58a33d8163))


### Performance

* consolidate per-request HTML passes in renderComponent ([#36](https://github.com/khromov/mochi/issues/36)) ([285a87f](https://github.com/khromov/mochi/commit/285a87f3ea117d0b7147a1ec50d46be19dabd514))
* reduce server island runtime by ~80% (8.59kB → 1.91kB ) ([#50](https://github.com/khromov/mochi/issues/50)) ([d570bc8](https://github.com/khromov/mochi/commit/d570bc83e2e5f202b37f96e4c02f6f1267d86292))

## [0.3.2](https://github.com/khromov/mochi/compare/mochi-framework-v0.3.1...mochi-framework-v0.3.2) (2026-05-24)


### Bug Fixes

* register trailing-slash alternates for internal framework routes ([#33](https://github.com/khromov/mochi/issues/33)) ([453eac5](https://github.com/khromov/mochi/commit/453eac5358e39abba036dcede1e19e99b889f503))

## [0.3.1](https://github.com/khromov/mochi/compare/mochi-framework-v0.3.0...mochi-framework-v0.3.1) (2026-05-23)


### Bug Fixes

* debug bar Bundles link points to undefined in production ([#30](https://github.com/khromov/mochi/issues/30)) ([2c77825](https://github.com/khromov/mochi/commit/2c778256858254e617b3c1d7e3cadeddbe4827f4))
* immutable asset caching + feat: SSR duration in debug bar ([#32](https://github.com/khromov/mochi/issues/32)) ([0f8bb68](https://github.com/khromov/mochi/commit/0f8bb6804ccd8b150ba70c93941f38b7724fad84))

## [0.3.0](https://github.com/khromov/mochi/compare/mochi-framework-v0.2.0...mochi-framework-v0.3.0) (2026-05-23)


### Features

* add liveReload option to disable dev WS ([#23](https://github.com/khromov/mochi/issues/23)) ([616ab7a](https://github.com/khromov/mochi/commit/616ab7ac95a8553b47ee7daed473b9745770a7b0))
* **mdsvex:** preprocess mochi:hydrate inside markdown files ([#22](https://github.com/khromov/mochi/issues/22)) ([bcf08e4](https://github.com/khromov/mochi/commit/bcf08e46f369255706e64164df67d04c1dad5e80))


### Bug Fixes

* **debug-bar:** show green status dot when liveReload is disabled ([#27](https://github.com/khromov/mochi/issues/27)) ([f8896f5](https://github.com/khromov/mochi/commit/f8896f53bc8fc3553efd5277e52e8421e468768f))

## [0.2.0](https://github.com/khromov/mochi/compare/mochi-framework-v0.1.1...mochi-framework-v0.2.0) (2026-05-23)


### Features

* **debug-bar:** redesign + landing Quick Start + Discord links ([#16](https://github.com/khromov/mochi/issues/16)) ([91a0931](https://github.com/khromov/mochi/commit/91a09313abb310f8e5e71d5f5678e4bdbeb6980c))
* **docs:** first-app walkthrough, docker page, intro rewrite, Dockerfile cleanup ([#18](https://github.com/khromov/mochi/issues/18)) ([a0df099](https://github.com/khromov/mochi/commit/a0df0998c882f18fe1978ba7b388cfbd27c4768b))


### Performance

* **ssr:** cache and skip Svelte preprocessing for non-island sources ([#19](https://github.com/khromov/mochi/issues/19)) ([1bbbd79](https://github.com/khromov/mochi/commit/1bbbd79a870bde1c8a04b5fb0d69af5497740390))

## [0.1.1](https://github.com/khromov/mochi/compare/mochi-framework-v0.1.0...mochi-framework-v0.1.1) (2026-05-22)


### Bug Fixes

* typecheck errors in scaffolded `bun create mochi` projects ([#10](https://github.com/khromov/mochi/issues/10)) ([202ff53](https://github.com/khromov/mochi/commit/202ff531306140306a8990a2e47ba081195957c3))

## [0.1.0](https://github.com/khromov/mochi/compare/mochi-framework-v0.0.1...mochi-framework-v0.1.0) (2026-05-21)


### Features

* expose params and cookies on MochiApiEvent ([#1](https://github.com/khromov/mochi/issues/1)) ([8fc956d](https://github.com/khromov/mochi/commit/8fc956daaa0c293775f3386efe46748ec1a18f68))

## Changelog