---
title: 'Welcome'
slug: intro
---

# mochi

Mochi is a SSR-focused framework for [Svelte 5](https://svelte.dev/) and [Bun](https://bun.sh/). It has a strong focus on performance and uses an islands architecture. This means you can selectively hydrate the Svelte components you want to be interactive, and leave the rest as performant HTML without having to ship the runtime for those components to the client. Less JavaScript, faster pages, and happier users are ahead!

> **Early prototype.** Only use in production if you are brave!

---
title: 'Setup'
slug: setup
---

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

## Setup

```sh
bun install
bun run dev       # Development mode with live reload
bun run start     # Production mode
```

<Callout type="warning">

**What to expect in the current state**

There are many things that aren't implemented yet. You'll find a non-exhaustive list below:

- HMR always does full page reloads
- No SCSS/SASS support
- No HTTP streaming (see <a href="/docs/http-streaming">this page</a> for why you probably don't need it)

</Callout>

---
title: 'Scripts'
slug: scripts
---

## Scripts

| Script    | Command             | Description                     |
| --------- | ------------------- | ------------------------------- |
| dev       | `bun run dev`       | Start dev server (live reload)  |
| start     | `bun run start`     | Start production server         |
| build     | `bun run build`     | Pre-build islands for prod      |
| typecheck | `bun run typecheck` | Type-check with tsc             |
| lint      | `bun run lint`      | Lint with ESLint                |
| lint:fix  | `bun run lint:fix`  | Lint and auto-fix               |
| format    | `bun run format`    | Format with Prettier            |
| clean     | `bun run clean`     | Remove `.mochi` build artifacts |

---
title: 'Defining routes'
slug: defining-routes
---

## Defining routes

Routes map URL paths to page entries, API handlers, WebSocket endpoints, or SSE streams:

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

const routes = {
  '/': Mochi.page('./src/Home.svelte'),
  '/about': Mochi.page('./src/About.svelte', { serverProps: { title: 'About' } }),
  '/health': Mochi.api(({ method }) => Response.json({ status: 'ok' })),
  '/ws/chat': Mochi.ws({
    message(ws, msg) {
      ws.send(msg);
    },
  }),
  '/sse/time': Mochi.sse((stream) => {
    stream.send('hello');
  }),
};

await Mochi.serve({
  port: 3333,
  development: process.env.MODE === 'development',
  routes,
});
```

---
title: 'Progressively enhancing forms with enhance'
slug: progressively-enhancing-forms-with-enhance
---

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

## Progressively enhancing forms with enhance

`enhance` is a Svelte attachment that progressively enhances a `<form method="POST">`. The same server-side action handler runs whether JavaScript is available or not — but with `{@attach enhance(...)}`, the client submits over `fetch`, the server returns a JSON `MochiEnhanceResult` instead of a re-rendered HTML page, and there's no full-page reload.

```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>
```

The form must live inside a hydrated island (eg: `mochi:hydrate`, `mochi:hydrate:visible`). If hydration is skipped, the attachment never runs and the form falls back to a native HTML POST automatically — that's the progressive-enhancement contract.

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

### Wire format

`enhance` adds two headers to the POST: `Accept: application/json` and `x-mochi-action: true`. The server detects these 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 };
```

The 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. `data` is encoded 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 for each 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)` |

<Callout type="warning">

**Mochi's default fallback is intentionally lean.** Unlike SvelteKit's `use:enhance`, Mochi has no client-side `page.form` store, no `goto`, and no `invalidateAll`. The framework can't auto-update component props or re-run server data after a submission. For interactive feedback on `failure` (or anything more involved than a redirect), provide a `submit` callback.

</Callout>

When the same component renders both as a hydrated island (where `enhance` will fire) and as a plain SSR-only child (where it won't), read the [auto-injected `isHydratable` prop](/docs/environment-constants#auto-injected-props) to skip the SSR `form`-prop peek when the client will take over.

### Submit callback

Pass a function as the argument. It runs once per submit and may return a result handler that fully replaces the default fallback:

```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" {@attach enhance(handleLogin)}>
  …
  <button type="submit" disabled={pending}>{pending ? 'Signing in…' : 'Log in'}</button>
</form>
```

The result handler receives `{ result, formElement, formData, action, update }`. Calling `update({ reset?: boolean })` re-invokes the default fallback — useful when you only want to layer extra behavior on top of the framework default.

### onPending

Instead of managing a `pending` flag inside the submit function, pass an options object with `onPending`. The callback fires with `true` immediately before the fetch and `false` once the result handler has settled (or when the submission is cancelled):

```svelte
<script>
  import { enhance } from 'mochi-framework';
  import type { MochiEnhanceOptions, MochiSubmitFunction } from 'mochi-framework';

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

  const handleLogin: MochiSubmitFunction<{ username: string }, { error: string }> = () => {
    errorMessage = null;
    return ({ result }) => {
      if (result.type === 'failure') {
        errorMessage = result.data?.error ?? 'Sign-in failed';
      }
    };
  };

  const opts: MochiEnhanceOptions<{ username: string }, { error: string }> = {
    submit: handleLogin,
    onPending: (v) => {
      pending = v;
    },
  };
</script>

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

`onPending` is guaranteed to fire `false` in 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 the `fetch` is issued. No callback runs.
- `controller.abort()` — cancel an in-flight request. The `AbortError` is silently swallowed.

### Server-side

No server changes are needed beyond declaring the action. The same `Mochi.page(path, { actions })` definition serves both the no-JS HTML POST flow and the enhanced JSON flow:

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

Mochi.page('./Login.svelte', {
  actions: {
    default: ({ formData, cookies }) => {
      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 path as an escape hatch.

<Callout type="warning">

**Wrap data in `success()` to round-trip it to the client.** If an action returns a plain object (e.g. `return { username }`) instead of `return success({ username })`, the enhanced path replaces the data with `{}`. This matches the non-enhanced behavior and is not a regression, but it means your result handler will receive 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 rolling your own `onsubmit` instead of `{@attach enhance(...)}`:

```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

Reach for `enhance` when the action's outcome should update UI without a navigation flicker — interactive forms, optimistic patterns, inline validation messages. Stick with a plain `<form method="POST">` when the action ends in a redirect anyway and the JS bundle isn't worth shipping.

---
title: 'Selective hydration with mochi:hydrate'
slug: selective-hydration
---

## Selective hydration with `mochi:hydrate`

Components render server-side by default and ship zero JavaScript. Add `mochi:hydrate` to opt a component into client-side hydration:

```svelte
<Counter mochi:hydrate count={5} />
<StaticHeader />
<!-- No JS shipped -->
```

Props are serialized into the HTML so they're available during hydration. Hydration is all-or-nothing per island — the entire component subtree hydrates together.

---
title: 'Lazy hydration with mochi:hydrate:visible'
slug: lazy-hydration
---

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

Defer hydration until a component scrolls into view using `mochi:hydrate:visible`:

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

The component is server-rendered, but its JavaScript and CSS are only loaded when it becomes visible. Pass `rootMargin` to start loading before the component enters the viewport.

**Note:** Visible islands require JS to be fully styled — their CSS is not included in the initial page load.

---
title: 'Server islands with mochi:defer'
slug: server-islands
---

## Server islands with `mochi:defer`

Server islands allow you to defer rendering of dynamic or personalized components until after the initial page load. The page renders immediately with fallback content, then each server island fetches its own HTML from a dedicated endpoint.

This is useful for personalized content (user avatars, cart counts) that shouldn't block the rest of the page from being aggressively cached.

```svelte
<!-- Basic server island — renders on-demand after page load -->
<UserAvatar mochi:defer userId={123} />

<!-- With fallback content shown while loading -->
<UserAvatar mochi:defer userId={123}>
  <div class="skeleton">Loading...</div>
</UserAvatar>
```

Server island components are normal Svelte components that run on the server. They have full access to the request context (cookies, headers) via `getRequestContext()`:

```svelte
<script>
  import { getRequestContext } from 'mochi-framework';
  const { cookies } = getRequestContext();
  const session = cookies.get('session');
  // Fetch personalized data...
</script>

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

### How it works

1. During initial SSR, the component is **not rendered** — only the fallback content is emitted inside a `<mochi-server-island>` custom element
2. Props are HMAC-signed and passed as a query parameter to prevent tampering
3. The browser fetches the component's HTML from `/_mochi/island/{ComponentName}?p={signedProps}` (the `/_mochi` prefix is configurable via `assetPrefix`)
4. Cookies are forwarded automatically (same-origin fetch), so the component can access the user's session
5. The returned HTML replaces the fallback content

### Combining with hydration

Server islands can also be hydrated for client-side interactivity:

```svelte
<!-- Fetched on-demand, then hydrated for interactivity -->
<ShoppingCart mochi:defer mochi:hydrate items={initialItems} />
```

### Props

Props are serialized with `devalue` — see [Passing props to islands](island-props) for the full list of supported types. Server islands additionally HMAC-sign the payload and pass it as a query parameter; if the signed props exceed URL length limits (~1800 bytes), a warning is emitted.

### Prop deduplication

During SSR each island registers its serialized props in a per-request map keyed by the exact `devalue` output, then carries a small `props-ref="mochi-props-<n>"` pointer to the matching `<script type="application/json">` block hoisted at the top of the body:

```html
<script type="application/json" id="mochi-props-0">
  [{ "items": 1 }, [1, 2, 3]]
</script>
…
<mochi-hydratable-island props-ref="mochi-props-0">…</mochi-hydratable-island>
<mochi-hydratable-island props-ref="mochi-props-0">…</mochi-hydratable-island>
```

Two islands whose props serialize byte-identically share a single block — this reduces bytes over the wire when two islands share the same props. Server islands (`mochi:defer`) are unaffected: their `signed-props` are HMAC-signed and stay inline so the signature ties to the exact attribute value the client sees.

### Encryption key

Props are HMAC-signed with a random key generated at server startup. For multi-instance deployments (rolling deploys, CDN caching), set the `MOCHI_KEY` environment variable to a constant base64url-encoded 32-byte key so all instances share the same signing key.

---
title: 'Passing props to islands'
slug: island-props
---

## Passing props to islands

Any component marked with `mochi:hydrate`, `mochi:hydrate:visible`, or `mochi:defer` becomes an island, and its props have to cross the SSR → client boundary. Mochi serializes them with [`devalue`](https://github.com/Rich-Harris/devalue), which preserves richer types than `JSON.stringify`.

```svelte
<!-- Parent runs only on the server -->
<script>
  const user = { name: 'Ada', id: 42 };
  const visitedAt = new Date();
  const tags = new Set(['svelte', 'bun']);
</script>

<!-- Child is the island; props travel via devalue -->
<UserCard mochi:hydrate {user} {visitedAt} {tags} />
```

### How it works

1. During SSR, `devalue.stringify` serializes the props object.
2. The serialized string is placed on the `<mochi-hydratable-island>` custom element as a `props` attribute. When multiple islands on the same page share an identical payload, it's hoisted into a shared `<script type="application/json">` block and each island gets a `props-ref` pointer instead.
3. In the browser, the custom element reads the attribute (or the referenced script block) and runs `devalue.parse` on it.
4. The reconstructed props are passed to Svelte's `hydrate(...)`, and the island takes over.

For `mochi:defer` server islands the flow is similar, except props are HMAC-signed and passed as a query parameter to a per-island endpoint — see [Server islands](server-islands).

### Supported types

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

### Not supported

- Functions
- Class instances (the constructor is lost — only own enumerable properties survive)
- `Symbol`

If you need any of these, compute them after hydration or pass a plain-data representation that the island can rebuild from.

---
title: 'Why Bun?'
slug: why-bun
---

## Why Bun?

Mochi targets the [Bun](https://bun.sh/) runtime, not Node. Bun ships a bundler, transpiler, file API, HTTP and WebSocket server, glob, hashing and compression in its standard library — features that on Node typically arrive as `esbuild`/`vite` + `express` + `node:fs` + `glob` + `zlib` + `crypto`. Building on top of those built-ins keeps the framework small (there are no transitive bundler or server dependencies), starts fast (no separate build step in dev), and means there is exactly one thing to install before you can `bun run dev`.

### What Mochi uses Bun for

| Bun API                              | Where it shows up in the framework                                                    |
| ------------------------------------ | ------------------------------------------------------------------------------------- |
| `Bun.serve()`                        | The HTTP and WebSocket server backing every route declared with `Mochi.serve()`.      |
| `Bun.build()` + `Bun.Transpiler`     | Bundles client-side islands and transpiles `.ts` / `.svelte` on demand during SSR.    |
| `Bun.file()` / `Bun.write()`         | Reads the HTML shell and component sources, writes built assets, serves static files. |
| `Bun.Glob`                           | Discovers routes, docs, and raw CSS files without an extra `glob` package.            |
| `Bun.hash`                           | Generates content-hashed filenames for cache-busted bundles and CSS.                  |
| `Bun.gzipSync` / `Bun.deflateSync`   | Compresses HTTP responses, and packs signed server-island prop payloads into URLs.    |
| `Bun.resolveSync`                    | Resolves npm modules (`devalue`, `mitt`) injected into generated client code.         |
| Native `.ts` execution + auto `.env` | Run sources directly with `bun run` — no `ts-node`, no `dotenv`.                      |

### What this means for your app

When you write app code on top of Mochi, prefer Bun's built-ins over their Node equivalents:

- Use `Bun.serve` / `bun:sqlite` / `Bun.file` instead of `express` / `better-sqlite3` / `node:fs`.
- Don't add `dotenv` — Bun loads `.env` automatically.
- Run `.ts` files directly with `bun run` — no separate transpile step.

### The tradeoff

Mochi will not run on plain Node. That is deliberate: the framework's surface area stays small precisely because the runtime does the heavy lifting.

---
title: 'HTTP streaming'
slug: http-streaming
---

## HTTP streaming

Mochi does **not** currently stream HTML responses. Every page is rendered to completion on the server and returned as a single response. This applies only to page rendering — `Mochi.sse()` and `Mochi.ws()` are streaming primitives in their own right and can be used for realtime interactions on the page with the client side powered by Svelte.

### Why we're comfortable with this (for now)

Streamed SSR is mostly a latency mitigation — a way to start sending bytes before the slowest data dependency on the page resolves. Mochi pushes you toward solutions that make that mitigation unnecessary in the first place:

- **Server islands** let slow, personalized, or expensive fragments load out-of-band after the rest of the page ships.
- **Lazy and visible hydration** keep the initial payload small and fast without needing progressive HTML.
- For pages that don't need per-request personalized, the right answer is usually a **shared HTTP cache in front of the app** — Cloudflare, CloudFront, Fastly, Varnish, or Nginx — so origin render time stops mattering for the common case. Remember that you can also cache the main page but leave certain or all server islands uncached.

### Before 1.0

Streaming is on the list of things to revisit before the 1.0 release. If an important use case forces it, the stance above may change.

---
title: 'Environment constants'
slug: environment-constants
---

## Environment constants

Import build-time constants from the virtual `mochi-framework` module:

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

| Constant    | Server  | Browser | Description                             |
| ----------- | ------- | ------- | --------------------------------------- |
| `isServer`  | `true`  | `false` | True during server-side rendering       |
| `isBrowser` | `false` | `true`  | True in the browser                     |
| `isDev`     | varies  | varies  | True when `development: true` in config |

### Auto-injected props

The preprocessor injects two props on every component used with `mochi:hydrate`, `mochi:hydrate:visible`, or `mochi:defer mochi:hydrate`:

| Prop           | Type                | Description                                                                      |
| -------------- | ------------------- | -------------------------------------------------------------------------------- |
| `islandId`     | `string`            | Stable id matching the wrapping `<mochi-hydratable-island island-id>` attribute. |
| `isHydratable` | `true \| undefined` | `true` for hydratable invocations; absent on plain SSR-only invocations.         |

Use `isHydratable` to branch SSR-only behavior off the same call site that hydrates client-side — e.g. peek the request's form snapshot only when the client won't take over:

```svelte
<script>
  import { isServer, getRequestContext } from 'mochi-framework';

  let { isHydratable } = $props<{ isHydratable?: boolean }>();

  // Hydrated: the client will fill state via the enhance attachment. Plain SSR: read
  // the post-submit form snapshot so the rendered HTML reflects the last
  // action result.
  const initial = isHydratable || !isServer ? null : peekForm();

  function peekForm() {
    const f = getRequestContext().form;
    return f && f.ok && typeof f.data.value === 'number' ? f.data.value : null;
  }
</script>
```

See the [Forms demo](/demos/login) for a side-by-side comparison of hydrated and SSR-only render paths.

---
title: 'API routes'
slug: api-routes
---

## API routes

`Mochi.api()` creates JSON API endpoints. The handler receives a `MochiApiEvent` with `method`, `request`, `url`, and `locals`:

```ts
import { error } from "./mochi-framework/utils";

"/health": Mochi.api(({ method }) =>
  Response.json({ status: "ok", method }),
),

"/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 });
}),
```

### Error responses

API routes return a standard JSON envelope for all errors — they never render the HTML error page, and `handleError` is not called for them. Use `apiError(status, message)` to build the envelope response:

```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 });
});
// bad body → 400 { "error": { "message": "Invalid JSON", "status": 400 } }
```

`apiError` returns a `Response` with `Content-Type: application/json` and the HTTP status set to match. Prefer it over throwing when the error is part of the route's normal control flow.

**Thrown `MochiHttpError`** — same envelope. Use `error(status, message)` from `mochi-framework` to throw one from deep inside helper code where returning is awkward:

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

error(404, 'Not found');
// → 404 { "error": { "message": "Not found", "status": 404 } }
```

**Any other uncaught throw** — returned as `500 Internal Server Error` with a generic message. The original error (including stack) is logged server-side via `log.error` with the method and path; it is **not** leaked to the client. Throw `MochiHttpError` (or return `apiError(…)`) explicitly when you want a specific status or message to reach the caller.

```ts
Mochi.api(async () => {
  await db.query('SELECT …'); // throws ConnectionError
  return Response.json({ ok: true });
});
// → 500 { "error": { "message": "Internal Server Error", "status": 500 } }
// (real error + stack logged to stderr)
```

---
title: 'WebSocket routes'
slug: websocket-routes
---

## WebSocket routes

`Mochi.ws()` creates WebSocket endpoints with `open`, `message`, `close`, and `drain` handlers. Bun's pub/sub is available via `ws.subscribe()` and `ws.publish()`:

```ts
"/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");
  },
}),
```

An optional `upgrade` handler can validate the connection and attach user data:

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

---
title: 'Server-Sent Events'
slug: server-sent-events
---

## Server-Sent Events

`Mochi.sse()` creates SSE streams. The handler receives a stream with `send()`, `close()`, and `onClose()`:

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

`send()` accepts an optional second argument with `event` and `id` fields for named events.

---
title: 'Middleware (hooks)'
slug: middleware
---

## Middleware (hooks)

Middleware uses SvelteKit-style `Handle` functions. Compose multiple handlers with `sequence()`:

```ts
import { sequence } from './mochi-framework/hooks';
import type { Handle } from './mochi-framework/hooks';

const auth: Handle = async ({ event, resolve }) => {
  if (!event.request.headers.get('Authorization')) {
    return new Response('Unauthorized', { status: 401 });
  }
  return resolve(event);
};

const logging: Handle = async ({ event, resolve }) => {
  console.log('→', event.url.pathname);
  const response = await resolve(event);
  console.log('←', response.status);
  return response;
};

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

`event.locals` is a per-request object for passing data between middleware layers.

`resolve()` accepts options for post-processing:

- **`transformPageChunk({ html })`** — transform the HTML response before sending
- **`filterResponseHeaders(name, value)`** — filter which headers are included

---
title: 'Transforming HTML with transformPageChunk'
slug: transform-page-chunk
---

## Transforming HTML with `transformPageChunk`

`transformPageChunk` is a resolve option that lets middleware transform the final HTML before it's sent to the client. It only runs on `text/html` responses.

```ts
import type { Handle } from 'mochi-framework/hooks';

const greeting: Handle = async ({ event, resolve }) => {
  return resolve(event, {
    transformPageChunk({ html }) {
      return html.replace('{{app.greeting}}', 'Welcome to Mochi!');
    },
  });
};
```

Add a `{{app.greeting}}` placeholder anywhere in your HTML shell, and the middleware will replace it on every page response:

```html
<body>
  <header>{{app.greeting}}</header>
  {{mochi.body}}
</body>
```

The callback receives `{ html, done }` and can return a `string`, `undefined`, or a `Promise` — so async transforms work too:

```ts
const inject: Handle = async ({ event, resolve }) => {
  return resolve(event, {
    async transformPageChunk({ html }) {
      const banner = await fetchBannerMessage();
      return html.replace('{{app.banner}}', banner);
    },
  });
};
```

When multiple handlers in a `sequence()` use `transformPageChunk`, they run in reverse order — inner handlers transform first, then outer handlers receive the result.

---
title: 'Error handling'
slug: error-handling
---

## Error handling

Mochi renders an error page for uncaught page-render errors, `error(status, ...)` thrown from `serverProps` or actions, and any request that doesn't match a route. API routes are unaffected — they return a JSON envelope instead; see [API routes → Error responses](#error-responses) above.

Configure an error page via `errorPage` on `Mochi.serve()`. If omitted, a minimal built-in component is used.

```ts
await Mochi.serve({
  errorPage: './src/Error.svelte',
  handleError: ({ error, status, event }) => {
    if (status >= 500) console.error('[app]', event.url.pathname, error);
  },
  routes,
});
```

The error component receives a single `error` prop:

```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. Only populated when `development: true`, else absent |

### `handleError` hook

Fires whenever the error page is about to render — uncaught page/form render errors, unmatched routes, unknown form actions, and malformed form bodies. Use it to log, forward to error tracking, or sanitize the message the user sees.

`error` is `null` when the condition didn't originate from a throw (e.g. unmatched routes, unknown form actions). Inspect it before forwarding so benign 4xx cases don't page on-call.

Return one of:

- `{ status, message }` — override either field passed to the error component
- a `Response` — short-circuit rendering entirely (useful for redirects or custom responses)
- nothing — keep the defaults

```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.' };
};
```

If the hook itself throws, Mochi logs the secondary error and renders the error page with the original `status`/`message`. Not called for API-route errors.

### Fallback behavior

If the user's `errorPage` component itself throws during render, Mochi returns a plain-text response that mentions both the original error and the secondary render failure — the error page cannot crash the server.

---
title: 'Error boundaries'
slug: error-boundaries
---

## Error boundaries

Every `mochi:hydrate` and `mochi:hydrate:visible` island is auto-wrapped in `<svelte:boundary>`. A throw in one island no longer takes down the whole page render — the failed island is replaced by a small marker (or hidden in production) and the rest of the page continues. No opt-in, no configuration.

### What's wrapped

- `mochi:hydrate` — wrapped.
- `mochi:hydrate:visible` — wrapped.
- `mochi:defer` — handled by the server-island endpoint instead (see below).
- Top-level page render throws — go to the configured `errorPage`, not to a boundary. Mochi does not insert a page-level boundary; if you want a section to degrade gracefully, author `<svelte:boundary>` yourself.

### 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 (synchronous script throws, `$effect`, `$derived`) — caught via `transformError` on `hydrate()`. Note: client-side errors are logged to the browser console but do not emit `island:error` (the event bus is server-side only).
- Synchronous failures in the island's bundle import or in `hydrate()` itself — caught by a defensive try/catch and rendered as the same failure stub.

### Visual behaviour

In development the failed island is replaced by a dashed-red `<mochi-island-failure>` marker showing the component name and error message. In production the element is hidden (`display: none`) so end users see a clean gap instead of a stack trace.

### Server islands (`mochi:defer`)

The `/island/:name` endpoint try/catches the SSR render and returns `200` plus a `<mochi-island-failure>` stub. The `200` is intentional — it stops the client's retry loop from hammering a deterministic failure. Whatever fallback children you passed stay visible until the response arrives.

### Author your own boundary

Mochi makes `<svelte:boundary>` work during SSR — stock Svelte boundaries are no-ops on the server without `transformError`, which Mochi passes for you. Use it anywhere — wrap a hand-written non-island component, or wrap a chunk of a page when you want bespoke degradation:

```svelte
{#snippet failed(error: Error)}
  <p>Something went wrong: {error.message}</p>
{/snippet}

<svelte:boundary {failed}>
  <SomePieceThatMightThrow />
</svelte:boundary>
```

### Observability — `island:error` event

Every server-side island failure emits an `island:error` event on `mochiEvents`. Subscribe to forward failures to error tracking:

```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 (matches the `island-id` attribute); set for `'server'` failures, `undefined` for `'hydratable'` SSR failures                                                                                                               |
| `kind`          | `'hydratable'` (SSR throw inside a hydratable island) or `'server'` (server-island endpoint render). The `MochiIslandErrorKind` type also reserves `'client-hydrate'`, but client-side errors are not currently emitted to the event bus. |
| `message`       | Error message — safe to forward                                                                                                                                                                                                           |
| `stack`         | Stack trace; populated only when `development: true`                                                                                                                                                                                      |

### See also

- [Error handling](error-handling) — top-level page errors and the configured `errorPage`.
- [Selective hydration](selective-hydration), [Lazy hydration](lazy-hydration), [Server islands](server-islands) — the directives boundaries wrap.

---
title: 'Utility helpers'
slug: utility-helpers
---

## Utility helpers

Importable from `./mochi-framework/utils`:

| Function                | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `json(data, init?)`     | Create a JSON `Response`                            |
| `error(status, msg)`    | Throw a `MochiHttpError` (caught by framework)      |
| `apiError(status, msg)` | Build a JSON error `Response` for API route returns |

---
title: 'Cache'
slug: cache
---

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

## Cache

`MochiCache` wraps [`stale-while-revalidate-cache`](https://www.npmjs.com/package/stale-while-revalidate-cache) for caching server-side data — typically slow upstream API calls. Construct once at module scope and share the instance across requests.

```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">

**Caches are shared in-process.** Every request reads from the same `Map`, so a key like `cart:current` will leak one user's data to another. Prefix per-user keys with the user id — e.g. `` `cart:${userId}` `` — and do the same for any other request-scoped dimension (tenant, locale, role).

</Callout>

### Behaviour

- **Fresh** (within `minTimeToStale`): cached value returned, no fetch.
- **Stale** (between `minTimeToStale` and `maxTimeToLive`): cached value returned immediately, 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 }>` |
| `delete(key)`              | `Promise<void>`              |

`status` is `'fresh' \| 'stale' \| 'expired' \| 'miss'`.

### Options

`MochiCacheOptions` extends the upstream `Config` (so `retry`, `retryDelay`, `serialize`, `deserialize` and any future options pass through). Mochi-specific defaults:

| Option           | Default           |
| ---------------- | ----------------- |
| `minTimeToStale` | `5_000` (5s)      |
| `maxTimeToLive`  | `600_000` (10min) |
| `storage`        | in-memory `Map`   |

For multi-process or persistent caching, pass a custom `storage` that implements `getItem` / `setItem` / `removeItem` (e.g. Redis, SQLite via `bun:sqlite`).

### Subscribing to cache events

`MochiCache` emits two events on `mochiEvents`:

| Event              | Payload           | When                                                |
| ------------------ | ----------------- | --------------------------------------------------- |
| `cache:read`       | `{ key, status }` | Every cache lookup, regardless of which method ran. |
| `cache:revalidate` | `{ key }`         | A background refetch starts (stale read).           |

`status` is `'fresh' \| 'stale' \| 'expired' \| 'miss'`. Use `mochiEvents.setHandler` to attach a custom subscriber — it replaces a prior handler under the same name, so dev re-imports don't pile up listeners:

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

mochiEvents.setHandler('metrics:cache-read', 'cache:read', ({ key, status }) => {
  metrics.increment(`cache.${status}`, { key });
});
```

`logger()` already prints `cache:revalidate` lines by default. Pass `{ cache: 'verbose' }` to also print every read, or `{ cache: false }` to silence cache logging:

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

logger({ cache: 'verbose' });
```

See the [Cache Events demo](/demos/cache-events) for a worked example that pipes events into an in-memory ring buffer and renders them on the page.

### Server-only

`MochiCache` lives on the server. Importing it into a hydratable island throws — caches are shared per-process state and don't make sense in the browser. Construct cache instances in `.ts` modules or page-route scripts, never inside a `mochi:hydrate` component.

---
title: 'Events'
slug: events
---

## Events

Mochi emits lifecycle events through a process-wide [`mitt`](https://www.npmjs.com/package/mitt) emitter exported as `mochiEvents`. Subscribe from application code to feed metrics, audit logs, custom log destinations, or anything else that wants a structured view of what the server is doing.

Names use a `namespace:action` convention. Every event key is in the typed `MochiEventMap`, so handlers receive a precise payload type without casts.

Events:

- [`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
- [`server:start`](#serverstart), [`server:stop`](#serverstop) — server lifecycle
- [`error`](#error) — page/api/action handler threw, response was an error page or `apiError`
- [`action:invoke`](#actioninvoke), [`action:complete`](#actioncomplete) — form action lifecycle
- [`compile:start`](#compilestart), [`compile:complete`](#compilecomplete), [`compile:error`](#compileerror) — Svelte SSR build
- [`island:error`](#islanderror) — a hydratable, server, or client-hydrate island errored
- [`file:change`](#filechange) — dev-only file watcher
- `cache:read`, `cache:revalidate` — see [Subscribing to cache events](/docs/cache#subscribing-to-cache-events)

### Subscribing

Two patterns:

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

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

`.on()` is the standard mitt API. Handlers are sync — to do async work, kick it off without awaiting (e.g. fire-and-forget to your metrics client) so you don't stall the next emitter.

For HMR-safe subscribers — i.e. modules that may be re-imported by the dev SSR compile cache — use `setHandler` instead. It registers under a name and replaces any prior handler under the same name, so re-imports don't pile up listeners:

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

mochiEvents.setHandler('metrics:request', 'request', ({ status, duration }) => {
  metrics.timing('http.request', duration, { status });
});
```

Namespace the name (`metrics:request`, not `request`) so unrelated subsystems don't silently evict each other. Don't mix `setHandler` with `.off()` for the same name — the name table is maintained only by `setHandler`.

### Correlating events for one request

Every HTTP request gets a stable `requestId` carried on `request`, `error`, `action:invoke`, and `action:complete`. Use it to stitch together a full picture (e.g. trace a 500: `error` payload + the matching `request` payload). The same id is exposed on the request context:

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

const { requestId } = getRequestContext();
```

By default the framework generates the id with `nanoid`. To pick up an upstream id from a trusted reverse proxy instead, set `proxy.requestIdHeader`:

```ts
Mochi.serve({
  proxy: { requestIdHeader: 'X-Request-Id' },
  // …
});
```

Only enable this behind a proxy you control — clients can spoof any header, so trusting a public-internet `X-Request-Id` lets attackers smear log lines for unrelated requests together.

### Skipping work when nobody listens

If you `emit` your own custom events whose payload is expensive to build (large allocations, stack capture, structured log mapping), wrap the construction in `hasSubscribers(name)`:

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

if (hasSubscribers('compile:error')) {
  mochiEvents.emit('compile:error', expensivePayload());
}
```

The built-in events emit unconditionally — their payloads are cheap, and the cost of an extra object literal per request is below noise. Reach for `hasSubscribers` only when payload construction would dominate.

### Event reference

#### `request`

Fires after an HTTP response is finalized — once per request, including CSRF rejects. Covers both `Mochi.page()` and `Mochi.api()` routes (distinguished by `kind`).

| Field       | Type              | Notes                       |
| ----------- | ----------------- | --------------------------- |
| `requestId` | `string`          | correlation id (see above)  |
| `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   |

```ts
mochiEvents.on('request', ({ kind, method, path, status, duration }) => {
  if (status >= 500) alerts.fire({ kind, method, path, status, duration });
});
```

#### `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     |

```ts
mochiEvents.on('ws:open', ({ path }) => {
  metrics.increment('ws.open', { path });
});
```

#### `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                    |

```ts
mochiEvents.on('ws:message', ({ path, size, type }) => {
  metrics.histogram('ws.message.size', size, { path, type });
});
```

#### `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) |

```ts
mochiEvents.on('ws:close', ({ path, code, duration }) => {
  metrics.timing('ws.session', duration, { path, code });
});
```

#### `sse:open`

Fires when an SSE stream starts (the `ReadableStream` is pulled by the runtime).

| Field  | Type     | Notes        |
| ------ | -------- | ------------ |
| `path` | `string` | URL pathname |

```ts
mochiEvents.on('sse:open', ({ path }) => {
  metrics.increment('sse.open', { path });
});
```

#### `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()` |

```ts
mochiEvents.on('sse:message', ({ path, size, event }) => {
  metrics.histogram('sse.message.size', size, { path, event: event ?? 'message' });
});
```

#### `sse:close`

Fires when the SSE stream closes (client disconnect or explicit close).

| Field      | Type     | Notes                  |
| ---------- | -------- | ---------------------- |
| `path`     | `string` | URL pathname           |
| `duration` | `number` | ms the stream was open |

```ts
mochiEvents.on('sse:close', ({ path, duration }) => {
  metrics.timing('sse.session', duration, { path });
});
```

#### `server:start`

Fires once after `Bun.serve()` binds the listening socket. Includes a count of routes by kind.

| Field         | Type                             | Notes                 |
| ------------- | -------------------------------- | --------------------- |
| `port`        | `number`                         | bound port            |
| `hostname`    | `string \| undefined`            | bound hostname if any |
| `development` | `boolean`                        | dev or prod mode      |
| `routes`      | `{ page, api, ws, sse: number }` | route counts by kind  |

```ts
mochiEvents.on('server:start', ({ port, routes }) => {
  log.info(`listening on ${port} — ${routes.page} pages, ${routes.api} APIs`);
});
```

#### `server:stop`

Fires when the server is shutting down via `SIGTERM`/`SIGINT`, after the `mochi:shutdown` hook has run.

| Field    | Type                         | Notes                       |
| -------- | ---------------------------- | --------------------------- |
| `reason` | `'signal'`                   | what initiated the shutdown |
| `signal` | `'SIGTERM' \| 'SIGINT' \| -` | the signal received         |

```ts
mochiEvents.on('server:stop', ({ reason, signal }) => {
  metrics.flush(); // drain before the process exits
});
```

#### `error`

Fires when a page, API, or form action handler throws and the framework returns an error response. Useful for routing exceptions to Sentry/Rollbar/Datadog without monkey-patching.

| Field        | Type                          | Notes                                             |
| ------------ | ----------------------------- | ------------------------------------------------- |
| `requestId`  | `string`                      | correlates with the matching `request` event      |
| `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, populated in dev only                |
| `actionName` | `string \| undefined`         | form action name; 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` via `requestId`.

| Field        | Type     | Notes                                |
| ------------ | -------- | ------------------------------------ |
| `requestId`  | `string` | correlates with `action:complete`    |
| `path`       | `string` | URL pathname + search                |
| `actionName` | `string` | action name (`'default'` if unnamed) |

```ts
mochiEvents.on('action:invoke', ({ requestId, actionName }) => {
  starts.set(requestId, performance.now());
});
```

#### `action:complete`

Fires after a form action returns (or throws). One emission per invocation, regardless of 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`   |

```ts
mochiEvents.on('action:complete', ({ requestId, actionName, result }) => {
  const ms = performance.now() - (starts.get(requestId) ?? 0);
  starts.delete(requestId);
  metrics.timing('form.action', ms, { actionName, result });
});
```

#### `compile:start`

Fires before each Svelte SSR compile (skipped on cache hit).

| Field  | Type     | Notes                       |
| ------ | -------- | --------------------------- |
| `path` | `string` | absolute path of the source |

#### `compile:complete`

Fires after a successful compile. Pair with `compile:start` to time the build per file.

| 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        |

```ts
const compileStart = new Map<string, number>();
mochiEvents.on('compile:start', ({ path }) => compileStart.set(path, performance.now()));
mochiEvents.on('compile:complete', ({ path, ssrSizeBytes }) => {
  const ms = performance.now() - (compileStart.get(path) ?? 0);
  log.info(`compiled ${path} in ${ms}ms (${ssrSizeBytes} bytes)`);
  compileStart.delete(path);
});
```

#### `compile:error`

Fires when `Bun.build` rejects a Svelte source. The framework still throws after emitting; the event is for tooling that wants the structured logs.

| Field     | Type                                        | Notes                            |
| --------- | ------------------------------------------- | -------------------------------- |
| `path`    | `string`                                    | source that failed               |
| `message` | `string`                                    | top-line error message           |
| `logs`    | `Array<{ file?, line?, column?, message }>` | per-message diagnostics from Bun |

#### `island:error`

Fires when an island fails — server-island render, hydratable SSR render, or client-side hydration. The framework still ships an error placeholder; this event lets you observe it.

| Field           | Type                                           | Notes                              |
| --------------- | ---------------------------------------------- | ---------------------------------- |
| `componentName` | `string`                                       | island component identifier        |
| `islandId`      | `string \| undefined`                          | DOM `island-id` if known           |
| `kind`          | `'hydratable' \| 'server' \| 'client-hydrate'` | which lifecycle stage failed       |
| `message`       | `string`                                       | error message                      |
| `stack`         | `string \| undefined`                          | stack trace, populated in dev only |

```ts
mochiEvents.on('island:error', ({ componentName, kind, message }) => {
  log.error(`[${kind}] ${componentName}: ${message}`);
});
```

#### `file:change`

Fires from the dev file watcher (chokidar). Production builds don't 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'` |

```ts
mochiEvents.on('file:change', ({ path, type }) => {
  if (type === 'change' && path.endsWith('.env')) restartWorkers();
});
```

### Custom events

`mochiEvents` is a plain mitt emitter — you can `emit` your own keys on it. They won't appear in `MochiEventMap`, so handlers and emit sites lose their typing. For anything beyond a quick experiment, prefer a separate emitter you control.

---
title: 'Custom HTML shell'
slug: custom-html-shell
---

## Custom HTML shell

Pass an HTML file path or template string to `htmlShell`. Use these placeholders:

| Placeholder        | Replaced with                      |
| ------------------ | ---------------------------------- |
| `{{mochi.head}}`   | `<svelte:head>` content            |
| `{{mochi.css}}`    | Scoped component styles            |
| `{{mochi.body}}`   | Rendered HTML                      |
| `{{mochi.script}}` | Hydration bootstrap `<script>` tag |

```ts
await Mochi.serve({
  htmlShell: './src/shell.html',
  routes,
});
```

Custom placeholders can be injected via `transformPageChunk` in middleware.

---
title: 'CSS imports'
slug: css-imports
---

## CSS imports

Side-effect CSS imports in any `.svelte` (or imported `.ts`) file are bundled
by Bun and served as a hashed `/import-css/<name>-<hash>.css` asset. Mochi
auto-links the bundle from every page that transitively imports it — you don't
add anything to the shell.

```svelte
<script>
  import '@fontsource/inter';
  import '@fontsource/fraunces';
</script>
```

The import is stripped from both the SSR and client JS bundles (so no runtime
cost) and the CSS is bundled separately. Per-entry tracking ensures pages only
ship the CSS they actually depend on. The same import in a hydratable
component works the same way — the bundle URL is linked from the page `<head>`
regardless of where the import lives.

Use this for self-hosted fonts (`@fontsource/*`), CSS-only libraries
(`tippy.js/dist/tippy.css`), or any third-party stylesheet you'd rather not
load via a runtime `<link>`.

In dev, a `.css` edit triggers a fast rebundle (no full SSR recompile) and a
page reload. Edits to `.svelte` / `.ts` files trigger the normal full recompile
path.

---
title: 'Serve options'
slug: serve-options
---

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

## Serve options

Selected `Mochi.serve()` options (see `MochiServeOptions` for the full list):

| Option                      | Default             | Description                                                                 |
| --------------------------- | ------------------- | --------------------------------------------------------------------------- |
| `port`                      | —                   | Port to listen on                                                           |
| `development`               | `true`              | Enables live reload, debug bar, and error overlay                           |
| `htmlShell`                 | built-in            | Path or template string for the HTML shell                                  |
| `publicDir`                 | `./public`          | Directory served as static assets                                           |
| `outDir`                    | `./.mochi`          | Directory for build artifacts and dev cache                                 |
| `assetPrefix`               | `/_mochi`           | URL prefix for framework client assets and the server-island endpoint       |
| `additionalWatchPaths`      | `[]`                | Extra dev-mode file watcher paths, added to the defaults `src` and `public` |
| `gzip`                      | `true`              | Gzip-compress responses when the client sends `Accept-Encoding: gzip`       |
| `compressServerIslandProps` | `true`              | Deflate-compress server island props when it reduces size                   |
| `logger`                    | `{ enabled: true }` | Built-in request logger; pass `{ enabled: false }` to disable               |

```ts
await Mochi.serve({
  port: 3333,
  gzip: false, // disable response compression (e.g. when a reverse proxy handles it)
  routes,
});
```

<Callout type="warning">

**One `Mochi.serve()` per process.** Calling it a second time throws `Mochi.serve() has already been called. Only one instance is allowed.` To run two sites side by side (e.g. `site` + `demos` in this repo), start them as separate processes on different ports.

</Callout>

<Callout type="info">

**Shutdown signals.** `Mochi.serve()` installs `SIGTERM` and `SIGINT` listeners that fire the [`mochi:shutdown`](/docs/extensions#mochishutdown) hook and call `server.stop()`. A second signal force-exits with code 1. Existing user listeners on those signals are not displaced — Node.js dispatches signals to every registered listener.

</Callout>

### CSRF

State-mutating form submissions (`POST` / `PUT` / `PATCH` / `DELETE` with `application/x-www-form-urlencoded`, `multipart/form-data`, or `text/plain`) are gated by an origin-header check: the request's `Origin` must match the expected origin (see [Proxy](#proxy) below) or appear in `csrf.trustedOrigins`. JSON endpoints rely on the browser's CORS preflight and aren't checked.

**Safe by default.** In production the check refuses every form mutation until you set [`proxy.origin`](#proxy) (or `proxy.hostHeader`) so the framework knows what origin to trust. The 403 body explains the missing config so the deployment break is loud rather than silent. In development the same request is allowed through with a `[mochi]` warning instead, so local work isn't blocked. Opt out entirely with `csrf.checkOrigin: false` if you really mean to.

A configured production setup looks like this:

```ts
await Mochi.serve({
  proxy: {
    origin: 'https://app.example.com',
  },
  csrf: {
    trustedOrigins: ['https://embed.partner.com'], // optional extra origins
    // checkOrigin: false,                          // disable the check entirely
  },
  routes,
});
```

### Proxy

Behind a reverse proxy (load balancer, CDN, ngrok), the connection Bun sees is from the proxy, not the client. `proxy` options tell the framework how to recover the public origin (used by the CSRF check) and the real client IP (returned by `getClientAddress()` on the request context) from forwarded headers.

> **Only set the header options when the proxy is trusted to overwrite them** — clients can spoof these headers when reaching the app directly.

| Option           | Use when                                                                                     | Example               |
| ---------------- | -------------------------------------------------------------------------------------------- | --------------------- |
| `origin`         | The public URL is fixed and known. Wins over the header options.                             | `'https://my.site'`   |
| `protocolHeader` | The proxy sets a forwarded-protocol header you trust.                                        | `'x-forwarded-proto'` |
| `hostHeader`     | The proxy sets a forwarded-host header you trust.                                            | `'x-forwarded-host'`  |
| `portHeader`     | The proxy listens on a non-standard port and forwards it.                                    | `'x-forwarded-port'`  |
| `addressHeader`  | The proxy forwards the client IP (e.g. `True-Client-IP`, `X-Forwarded-For`).                 | `'x-forwarded-for'`   |
| `xffDepth`       | Number of trusted proxies in front of the server, when `addressHeader` is `x-forwarded-for`. | `3`                   |

```ts
await Mochi.serve({
  proxy: {
    // Either pin the public origin…
    origin: 'https://my.site',
    // …or derive it from forwarded headers.
    protocolHeader: 'x-forwarded-proto',
    hostHeader: 'x-forwarded-host',
    portHeader: 'x-forwarded-port', // optional, only if the public port differs

    // Client IP for getClientAddress():
    addressHeader: 'x-forwarded-for',
    xffDepth: 3, // 3 trusted proxies in front of the server
  },
  routes,
});
```

#### `xffDepth` and spoofing

`X-Forwarded-For` is a comma-separated chain — each proxy appends the address it saw. With three trusted proxies in front of the server and no spoofing:

```
client, proxy1, proxy2
```

The framework reads from the **right**, skipping `xffDepth - 1` trusted proxies, so `xffDepth: 3` returns `client`. Reading from the right blocks spoofing: a client setting its own `X-Forwarded-For` gets pushed leftward by each trusted proxy.

```
spoofed, client, proxy1, proxy2   # xffDepth: 3 → "client" (spoofed entry ignored)
```

If you need the leftmost address instead — for example, geolocation where the IP being real matters more than its being trusted — read `request.headers.get('x-forwarded-for')` directly in your handler.

#### `getClientAddress()` on the request context

```ts
import { getRequestContext } 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
---

## Extensions (hooks & filters)

Extension points for `Mochi.serve()`. Two kinds:

- **Hooks** run a user function at a specific framework moment (no return value).
- **Filters** replace a framework default value (receive the existing value, return the new one).

Names use a `namespace:camelCase` convention. Each name is registered in a typed registry; whether the user callback can be sync or async is declared per name and enforced by TypeScript — sync filters in hot paths can't accidentally be async.

Hooks:

- [`mochi:init`](#mochiinit) — async
- [`mochi:ready`](#mochiready) — async
- [`mochi:shutdown`](#mochishutdown) — async
- [`route:matched`](#routematched) — sync

Filters:

- [`csrf:formContentTypes`](#csrfformcontenttypes) — sync
- [`csrf:protectedMethods`](#csrfprotectedmethods) — sync
- [`csrf:trustedOrigins`](#csrftrustedorigins) — sync
- [`csrf:check`](#csrfcheck) — sync
- [`cookie:defaults`](#cookiedefaults) — sync
- [`html:shell`](#htmlshell) — sync
- [`serverIsland:secretKey`](#serverislandsecretkey) — async
- [`compile:preprocessors`](#compilepreprocessors) — sync
- [`publicDir:scan`](#publicdirscan) — async

### Hooks

#### `mochi:init`

Fires as the very first thing inside `Mochi.serve()`, before any framework state is set up. Async.

```ts
await Mochi.serve({
  hooks: {
    'mochi:init': async ({ options }) => {
      await warmCache(options);
    },
  },
  routes,
});
```

#### `mochi:ready`

Fires after `Bun.serve()` returns the bound server, just before `Mochi.serve()` resolves. Use it to do post-bind setup that needs the live `Server` instance (warm caches, register with service discovery, kick off background workers). Async.

```ts
await Mochi.serve({
  hooks: {
    'mochi:ready': async ({ server }) => {
      await registerWithServiceDiscovery(server.url);
    },
  },
  routes,
});
```

#### `mochi:shutdown`

Fires when the framework receives `SIGTERM` or `SIGINT`. The framework then calls `server.stop()`. A second signal force-exits with code 1. Async — the framework awaits the hook before stopping the server.

```ts
await Mochi.serve({
  hooks: {
    'mochi:shutdown': async ({ signal }) => {
      log.info(`Got ${signal}, draining…`);
      await db.close();
    },
  },
  routes,
});
```

The framework installs the signal listeners as part of `serve()`. Pre-existing user listeners on those signals are not displaced — Node.js dispatches signals to every registered listener.

#### `route:matched`

Fires when a `Mochi.page` / `Mochi.api` / `Mochi.ws` / `Mochi.sse` route matches an incoming request, after the CSRF check passes (for page/api) and before middleware/handler runs. Sync — observation only; do heavier work in a `handle` middleware. The `kind` field tells you which route type matched.

```ts
await Mochi.serve({
  hooks: {
    'route:matched': ({ pattern, kind, request }) => {
      tracer.startSpan(`${kind}:${pattern}`, { method: request.method });
    },
  },
  routes,
});
```

The hook does not fire when the framework rejects the request before route handling (e.g. CSRF block) — those cases reach the `request` event with the rejection's status instead.

`getRequestContext()` is available inside the hook for all four kinds — page, api, ws, sse — and returns a context with the matched `requestId`, `url`, and `params`.

### Filters

#### `csrf:formContentTypes`

Override the `Set<string>` of content types that gate the built-in CSRF check. Resolved once at startup. Sync.

```ts
await Mochi.serve({
  filters: {
    'csrf:formContentTypes': (types) => new Set([...types, 'application/csp-report']),
  },
  routes,
});
```

Default exported as `DEFAULT_FORM_CONTENT_TYPES` from `mochi-framework`.

#### `csrf:protectedMethods`

Override the `Set<string>` of HTTP methods that the CSRF check applies to. Resolved once at startup. Sync.

```ts
await Mochi.serve({
  filters: {
    'csrf:protectedMethods': (methods) => {
      methods.delete('DELETE');
      return methods;
    },
  },
  routes,
});
```

Default exported as `DEFAULT_PROTECTED_METHODS` from `mochi-framework`.

#### `csrf:trustedOrigins`

Override the `Set<string>` of cross-origin sources allowed past the CSRF check. Seeded from `csrf.trustedOrigins` (an array on `Mochi.serve()`). Resolved once at startup. Sync.

```ts
await Mochi.serve({
  filters: {
    'csrf:trustedOrigins': (origins) => {
      origins.add('https://embed.example');
      return origins;
    },
  },
  routes,
});
```

#### `csrf:check`

Override the framework's CSRF decision for the current request. The filter receives the framework's default decision — `null` if the request would pass, a `Response` (typically 403) if it would be blocked. Return the input unchanged to delegate to the framework, `null` to bypass, or a fresh `Response` to substitute a custom block.

```ts
await Mochi.serve({
  filters: {
    'csrf:check': (decision, { request, url }) => {
      // Webhook endpoint with its own auth — bypass CSRF entirely.
      if (url.pathname.startsWith('/webhooks/')) {
        return null;
      }
      return decision;
    },
  },
  routes,
});
```

Use sparingly: bypassing CSRF on a state-mutating endpoint reopens the attack the check exists to prevent. For most needs prefer the narrower [`csrf:trustedOrigins`](#csrftrustedorigins) filter or `csrf.checkOrigin: false` on `Mochi.serve()`.

#### `cookie:defaults`

Default `CookieSerializeOptions` merged into every `cookies.set()` call. Per-call options win on a per-field basis. `path` and `domain` from defaults also apply to `cookies.delete()` so the browser still matches the original `Set-Cookie`. 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 string with `{{mochi.head}}`, `{{mochi.css}}`, `{{mochi.body}}`, `{{mochi.script}}` placeholders intact. Sync.

```ts
await Mochi.serve({
  filters: {
    'html:shell': (tpl) => tpl.replace('{{mochi.head}}', '<meta name="csp-nonce" content="abc123">{{mochi.head}}'),
  },
  routes,
});
```

Use this when you only want to inject a snippet — for full ownership of the shell, set `htmlShell` directly.

#### `serverIsland:secretKey`

Override the HMAC key used to sign server-island props. The default value is the `MOCHI_KEY` env var (or a fresh random key if unset). Use this to source the key from KMS / Vault / a secret manager. Async.

```ts
await Mochi.serve({
  filters: {
    'serverIsland:secretKey': async () => {
      const raw = await kms.getSecret('mochi-island-key');
      return Buffer.from(raw, 'base64url');
    },
  },
  routes,
});
```

The `envKeyPresent` field on the filter context tells you whether `MOCHI_KEY` was set, in case you want to fall back to the env-derived default.

#### `compile:preprocessors`

A list of Svelte `PreprocessorGroup` to run on every `.svelte` source file before compilation. Applies to both server and client targets — branch on `target` in the filter context if you only want one. Sync (the preprocessor list is sync; Svelte's `preprocess()` itself is awaited internally).

```ts
import autoprefixer from 'autoprefixer';
import postcss from 'svelte-preprocess';

await Mochi.serve({
  filters: {
    'compile:preprocessors': () => [postcss({ postcss: { plugins: [autoprefixer] } })],
  },
  routes,
});
```

Default is `[]`. Preprocessors do not currently apply to `.md` / `.svx` files (mdsvex handles those itself).

#### `publicDir:scan`

Modify the `Map<urlPath, diskPath>` of files served from the public directory. The filter receives a fresh copy after each scan (initial startup + every dev-mode `public/` change), so in-place mutation is safe. Use it to add virtual files (entries that map to disk paths the framework didn't discover), shadow built-in routes, or rename URLs. Async.

```ts
await Mochi.serve({
  filters: {
    'publicDir:scan': async (files) => {
      files.set('/robots.txt', '/etc/mochi/robots.generated.txt');
      return files;
    },
  },
  routes,
});
```

A `Mochi.page` / `Mochi.api` route on the same URL still wins — the filter only adds entries; the wiring step skips entries whose URL is already a user route, with a `[mochi]` warning.

---
title: 'Svelte config'
slug: svelte-config
---

## Svelte config

Drop a `svelte.config.js` at the root of your app to customize the Svelte compiler. Mochi reads it on startup (and during `mochi build`) and merges its `compilerOptions` into the framework defaults.

```js
// svelte.config.js
export default {
  compilerOptions: {
    experimental: {
      async: true,
    },
  },
};
```

The file is optional. If it is missing, Mochi logs a warning and uses its defaults — the most important one being `experimental.async: true`, which is what allows `await` at the top level of `.svelte` components and is currently a Svelte 5 opt-in.

### Custom config path

By default Mochi looks for `./svelte.config.js` at the current working directory. Point it elsewhere with `svelteConfigPath` on `Mochi.serve()` or `build()` — relative paths resolve against `process.cwd()`, absolute paths are used as-is:

```ts
await Mochi.serve({
  svelteConfigPath: './configs/svelte.staging.config.js',
  routes,
});
```

### Merge order

1. **Framework defaults**
2. **Your `compilerOptions`** — overlaid on top of the defaults. You can override most fields.

### Framework-owned fields

A small set of `compilerOptions` are managed by Mochi and cannot be overridden, because they are part of the framework's contract with the compiler:

| Field      | Why                                                        |
| ---------- | ---------------------------------------------------------- |
| `generate` | Set to `'server'` for SSR builds, `'client'` for hydration |
| `filename` | Always the actual file path                                |
| `dev`      | Tied to the `development` flag passed to `Mochi.serve()`   |

Everything else 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 (both `.svelte` and `.svelte.[jt]s`)
- mdsvex `.md` / `.svx` files (server target)

### Limitations

Only `compilerOptions` is read today. SvelteKit-style keys like `preprocess`, `extensions`, and `kit` are not supported.

---
title: 'Development mode'
slug: development-mode
---

## Development mode

Development mode is controlled by the `development` option on `Mochi.serve()`. It defaults to `true`, so if you do nothing you get the dev experience.

```ts
await Mochi.serve({
  development: true, // the default
  routes,
});
```

When enabled, Mochi turns on:

- **Live reload** — pages refresh automatically on file changes (SSE-based; browser listens on `/__mochi_live_reload`)
- **File watcher** — `chokidar` watches source files; changes invalidate the component compile cache and notify any subscribers
- **Debug bar** — injected into HTML with component and hydration info
- **Error overlay** — build and runtime errors displayed in-browser
- **Bundle stats** — available at `/_mochi/client/stats` (or `${assetPrefix}/client/stats` if customized)

### The `MODE=development` convention

You'll often see the dev entry wired from a `MODE` env var:

```ts
// src/index.ts
await Mochi.serve({
  development: process.env.MODE === 'development',
  routes,
});
```

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

`MODE` is just a user-space convention — the framework does not read it directly. The framework only reads `options.development`. Using an env var lets one entry file serve both `bun run dev` (dev mode) and `bun run start` (production).

### What the file watcher covers

By default, chokidar watches:

- `src/` — your application source
- `public/` — static assets

Use `additionalWatchPaths` to extend this (for example, a separate content directory):

```ts
await Mochi.serve({
  additionalWatchPaths: ['../content', './docs'],
  routes,
});
```

The defaults are always included — `additionalWatchPaths` is purely additive. Paths that don't exist on disk are silently skipped.

### Reacting to file changes (`file:change` event)

Every filesystem change detected by the watcher is emitted on the `mochiEvents` bus as a `file:change` event. Use this to invalidate your own caches on edit without restarting the server:

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

if (process.env.MODE === 'development') {
  mochiEvents.on('file:change', ({ path, type }) => {
    if (path.endsWith('.md')) {
      // path is absolute; type is 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir'
      clearMyMarkdownCache();
    }
  });
}
```

The event fires synchronously, before the debounced browser reload, so subscribers can refresh their state in time for the next request.

`mochiEvents` is also available from `.svelte` files during SSR. All server-side copies of the emitter (the main runtime and every SSR bundle) share one pinned instance, so a subscription made from a component running server-side sees events emitted by the framework. On the client, `mochiEvents` is a stub — `on`/`off`/`setHandler` are no-ops and `emit` logs a warning to the console, since the bus is server-only.

#### Subscribing from a module that isn't your server entry

If your subscribing module can end up bundled into an SSR island (either directly via `import` in a `.svelte` file, or transitively), prefer `mochiEvents.setHandler(name, type, handler)` over `.on(...)`. The dev compile cache re-imports each SSR bundle on every `.svelte` change, so a module-top-level `.on(...)` registers a fresh handler each time and they pile up. `setHandler` replaces any prior registration with the same name — so 15 re-imports collapse to 1 live subscriber.

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

mochiEvents.setHandler('docs-cache-clear', 'file:change', ({ path }) => {
  if (path.endsWith('.md')) clearMyMarkdownCache();
});
```

Plain `.on(...)` remains the right choice when the subscribing module runs exactly once (e.g., your server entry) or when you legitimately want multiple handlers fanning out.

In production (`development: false`) the watcher is never started and no `file:change` events are emitted.

---
title: 'Tailwind'
slug: tailwind
---

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

## Tailwind

Drive Tailwind v4 with its Node API — no PostCSS, no Vite. 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.

Install Tailwind alongside its standalone Node + scanner packages (`mochi-framework` is already in your project; the Tailwind packages are optional peers):

```sh
bun add tailwindcss @tailwindcss/node @tailwindcss/oxide
```

Write an input CSS that imports the layers you want and tells Tailwind where to scan:

```css
/* src/styles/app.css */
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);

@source './*.svelte';

/* Preflight is skipped above. If your host shell already ships an unlayered
   universal reset (`*, *::before, *::after { margin: 0; padding: 0 }`), add
   element-level resets here for tags whose UA defaults you care about. */
button {
  appearance: none;
  background: transparent;
  border: 0;
  font: inherit;
  color: inherit;
  cursor: pointer;
}
```

<Callout type="info">
`@source` paths are resolved against the <code>base</code> directory passed to <code>compile()</code>. The helper sets <code>base</code> to the input file's directory by default, so <code>./*.svelte</code> matches files next to <code>app.css</code>. Use `**/*.svelte` for nested folders, or pass an explicit <code>base</code>.
</Callout>

Call `setupTailwind` before `Mochi.serve()`:

```ts
// src/index.ts
import { setupTailwind } from 'mochi-framework/tailwind';

await setupTailwind({
  input: './src/styles/app.css',
  output: './src/styles/app.generated.css',
  minify: process.env.MODE !== 'development',
});
```

Then `import` the generated file from any `.svelte` that uses Tailwind classes:

```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>
```

The framework strips the import from the JS bundle and serves the CSS at `/_mochi/import-css/<hash>.css`. The `<link>` is added to the `<head>` of every page that transitively imports it — pages that don't use Tailwind don't pay for it.

In dev, `setupTailwind` subscribes to Mochi's file watcher and rebuilds on `.svelte` / `.ts` / `.css` changes; the resulting `.css` write goes through Mochi's CSS fast-path (no full SSR rebuild) and the page reloads.

<Callout type="warning">
The example skips Tailwind's preflight so the stylesheet doesn't reset unrelated UI when loaded onto pages that already have their own resets. The cost is that user-agent defaults for elements like <code>&lt;button&gt;</code> leak through (rounded macOS pill shape, default gray background) and clobber utilities like <code>rounded-lg</code> or <code>bg-transparent</code>. Add element-level resets in your input CSS for any tags you actually use, or `@import 'tailwindcss/preflight.css' layer(base);` to opt back in.
</Callout>

Add `app.generated.css` to `.gitignore` — it's a build artifact.

---
title: 'Architecture'
slug: architecture
---

## Architecture

| File                                        | Role                                                      |
| ------------------------------------------- | --------------------------------------------------------- |
| `src/index.ts`                              | HTTP server entry point                                   |
| `src/routes.ts`                             | Route definitions                                         |
| `src/mochi-framework/Mochi.ts`              | `Mochi.serve()`, `page()`, `api()`, `ws()`, `sse()`       |
| `src/mochi-framework/ComponentRegistry.ts`  | SSR compilation, hydration preprocessing, client bundling |
| `src/mochi-framework/hooks.ts`              | Middleware system (`Handle`, `sequence()`)                |
| `src/mochi-framework/utils.ts`              | `json()`, `error()`, gzip                                 |
| `src/mochi-framework/HydratableIsland.ts`   | Client-side custom element for island hydration           |
| `src/mochi-framework/ServerIsland.ts`       | Client-side custom element for server island fetching     |
| `src/mochi-framework/serverIslandCrypto.ts` | HMAC signing/verification for server island props         |
| `src/mochi-framework/types.ts`              | Shared TypeScript types                                   |

---
title: 'Docs for LLMs'
slug: docs-for-llms
---

## Docs for LLMs

The Mochi documentation is published as plain-text bundles you can paste
into an LLM context.

### Full documentation

The full set of docs, concatenated in reading order, is served at
[`/llms.txt`](/llms.txt) — **recommended**. Use this when you want the model
to have the complete picture of the framework API.

### Docs + demo source

[`/llms-full.txt`](/llms-full.txt) includes everything in `/llms.txt` plus
the full source of every demo (`.svelte` and `.ts` files), grouped by demo
name. Use this when you want the model to understand both the API and
real working examples.

### Per-document text

Each individual doc is also reachable as plain text at
`/docs/<slug>/llms.txt`. For example:

- [`/docs/intro/llms.txt`](/docs/intro/llms.txt)
- [`/docs/server-islands/llms.txt`](/docs/server-islands/llms.txt)
- [`/docs/api-routes/llms.txt`](/docs/api-routes/llms.txt)

The "Copy as llms.txt" button on each doc page emits just that page —
useful when you want to give the model focused context without the rest
of the framework.

# Demo Source Files

## Demo: api

### api/Api.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import ApiTester from './ApiTester.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'Api.svelte', path: './src/demos/api/Api.svelte' },
    { label: 'ApiTester.svelte', path: './src/demos/api/ApiTester.svelte' },
    { label: 'routes.ts', path: './src/demos/api/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage title="API Endpoints" description="First-class JSON API routes via Mochi.api(). Test /health and /add live — responses come straight from the server." {sources}>
  <ApiTester mochi:hydrate />
</DemoPage>
```

### api/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>
  .api-tester {
    display: flex;
    flex-direction: column;
    gap: 0.75rem;
  }

  .endpoints {
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
  }

  .endpoint-btn {
    display: flex;
    align-items: center;
    gap: 0.6rem;
    padding: 0.55rem 0.85rem;
    background: var(--surface-muted);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    color: var(--text);
    cursor: pointer;
    font-family: inherit;
    font-size: 0.95rem;
    text-align: left;
    transition:
      background 0.12s ease,
      border-color 0.12s ease,
      color 0.12s ease;
  }

  .endpoint-btn:hover {
    background: var(--accent-soft);
    border-color: var(--accent);
    color: var(--accent-soft-text);
  }

  .endpoint-btn:focus-visible {
    outline: none;
    box-shadow: var(--focus-ring);
  }

  .method {
    font-size: 0.75rem;
    font-weight: 700;
    padding: 0.18rem 0.5rem;
    border-radius: var(--radius-sm);
    letter-spacing: 0.04em;
    font-family: var(--font-mono);
  }

  .method.get {
    background: var(--badge-success-bg);
    color: var(--badge-success-text);
  }

  .method.post {
    background: var(--badge-warning-bg);
    color: var(--badge-warning-text);
  }

  .path {
    font-family: var(--font-mono);
    font-size: 0.95rem;
    color: inherit;
  }

  .add-row {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    flex-wrap: wrap;
  }

  .add-inputs {
    display: flex;
    align-items: center;
    gap: 0.4rem;
  }

  .add-inputs input {
    width: 56px;
    padding: 0.35rem 0.5rem;
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    background: var(--surface);
    color: var(--text);
    font-family: var(--font-mono);
    font-size: 0.95rem;
    text-align: center;
    outline: none;
    transition:
      border-color 0.12s ease,
      box-shadow 0.12s ease;
  }

  .add-inputs input:focus {
    border-color: var(--accent);
    box-shadow: var(--focus-ring);
  }

  .plus {
    color: var(--text-subtle);
    font-weight: 500;
  }

  .result {
    background: var(--code-bg);
    border-radius: var(--radius-md);
    padding: 0.9rem 1rem;
    min-height: 56px;
    display: flex;
    align-items: center;
  }

  .result pre {
    color: var(--code-accent);
    font-family: var(--font-mono);
    font-size: 0.9rem;
    line-height: 1.5;
    margin: 0;
    white-space: pre-wrap;
    word-break: break-word;
  }

  .placeholder {
    color: var(--code-muted);
    font-size: 0.9rem;
  }

  .loading {
    color: var(--code-muted);
    font-size: 0.9rem;
    font-style: italic;
  }
</style>
```

### api/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 });
  }),
};
```

## Demo: cache-events

### cache-events/CacheEvents.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import { loadSources } from '../../components/utils';
  import { getSlowTime } from './log';

  const sources = await loadSources([
    { label: 'CacheEvents.svelte', path: './src/demos/cache-events/CacheEvents.svelte' },
    { label: 'log.ts', path: './src/demos/cache-events/log.ts' },
    { label: 'routes.ts', path: './src/demos/cache-events/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);

  const { value: time, status } = await getSlowTime();
</script>

<DemoPage
  title="Cache Events"
  description="A custom subscriber prints MochiCache lifecycle events to the server console with a [demo:cache-events] prefix. Refresh the page and watch your terminal — the subscriber lives in log.ts."
  {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 prints a line in the
      server console.
    </p>
  </div>
</DemoPage>

<style>
  .card {
    background: var(--surface);
    border: 1px solid var(--border);
    border-radius: var(--radius-lg);
    padding: 1rem 1.25rem;
    display: flex;
    flex-direction: column;
    gap: 0.75rem;
  }

  .row {
    display: flex;
    flex-wrap: wrap;
    gap: 1.5rem;
    align-items: baseline;
  }

  .label {
    display: block;
    font-size: 0.7rem;
    text-transform: uppercase;
    letter-spacing: 0.06em;
    color: var(--text-muted);
    margin-bottom: 0.2rem;
  }

  code {
    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
    font-size: 0.92rem;
    color: var(--text);
  }

  .hint {
    font-size: 0.85rem;
    color: var(--text-muted);
    margin: 0;
  }

  .status {
    font-size: 0.78rem;
    padding: 0.05rem 0.4rem;
    border-radius: 4px;
    border: 1px solid var(--border);
  }

  .status-fresh {
    color: #4ade80;
    border-color: rgba(74, 222, 128, 0.35);
  }

  .status-stale {
    color: #facc15;
    border-color: rgba(250, 204, 21, 0.35);
  }

  .status-expired {
    color: #f87171;
    border-color: rgba(248, 113, 113, 0.4);
  }

  .status-miss {
    color: var(--text-muted);
  }
</style>
```

### cache-events/log.ts
```ts
import { MochiCache, mochiEvents } from 'mochi-framework';
import { delay } from '../../components/utils';

export const slowClock = new MochiCache({
  minTimeToStale: 3_000,
  maxTimeToLive: 10_000,
});

// Custom integration: every cache event is printed to the console with a
// distinctive prefix so it stands out from the framework's built-in logger
// lines. setHandler (rather than .on) means dev re-imports don't pile up
// duplicate subscribers.
mochiEvents.setHandler('demo:cache-events:read', 'cache:read', ({ key, status }) => {
  console.log(`[demo:cache-events] read       ${key} → ${status}`);
});

mochiEvents.setHandler('demo:cache-events:revalidate', 'cache:revalidate', ({ key }) => {
  console.log(`[demo:cache-events] revalidate ${key}`);
});

export async function getSlowTime() {
  return slowClock.fetchWithStatus('slow-clock', async () => {
    await delay(150);
    return new Date().toISOString();
  });
}
```

### cache-events/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'),
};
```

## Demo: chat

### chat/Chat.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import ChatWidget from './ChatWidget.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'Chat.svelte', path: './src/demos/chat/Chat.svelte' },
    { label: 'ChatWidget.svelte', path: './src/demos/chat/ChatWidget.svelte' },
    { label: 'routes.ts', path: './src/demos/chat/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage
  title="Real-time Chat"
  description="Live chat over a WebSocket route with server-side message history. Open this page in two tabs to see messages broadcast in real time."
  {sources}
>
  <ChatWidget mochi:hydrate />
</DemoPage>
```

### chat/ChatWidget.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';

  let messages: Array<{ text: string; fromMe: boolean }> = $state([]);
  let input = $state('');

  let chatSocket: WebSocket | null = null;
  let userId = '';

  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:';

    chatSocket = new WebSocket(`${wsProtocol}//${host}/ws/chat`);
    chatSocket.addEventListener('message', (e) => {
      const msg = JSON.parse(e.data);
      messages = [...messages, { text: msg.text, fromMe: msg.userId === userId }];
    });
  }

  function send() {
    const text = input.trim();
    if (!text || !chatSocket) {
      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">
    {#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>

  <div class="chat-input">
    <input type="text" bind:value={input} onkeydown={onKeydown} placeholder="Type a message..." />
    <button onclick={send}>Send</button>
  </div>
</div>

<style>
  .chat-container {
    display: flex;
    flex-direction: column;
    width: 100%;
    max-width: 400px;
    height: 500px;
    margin: 0 auto;
    border-radius: var(--radius-md);
    overflow: hidden;
    background: var(--surface);
    border: 1px solid var(--border);
    box-shadow: var(--shadow-md);
  }

  .chat-header {
    padding: 1rem 1.25rem;
    background: var(--code-chrome-bg);
    color: var(--code-text);
  }

  .chat-title {
    font-weight: 600;
    font-size: 1rem;
  }

  .chat-messages {
    flex: 1;
    overflow-y: auto;
    padding: 1rem;
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
    background: var(--surface-muted);
  }

  .message {
    display: flex;
  }

  .message.mine {
    justify-content: flex-end;
  }

  .bubble {
    padding: 0.5rem 0.85rem;
    border-radius: var(--radius-md);
    background: var(--surface);
    color: var(--text);
    border: 1px solid var(--border);
    font-size: 0.95rem;
    max-width: 75%;
    word-break: break-word;
  }

  .message.mine .bubble {
    background: var(--accent);
    color: var(--accent-text);
    border-color: var(--accent);
  }

  .empty {
    margin: auto;
    color: var(--text-subtle);
    font-style: italic;
    font-size: 0.95rem;
  }

  .chat-input {
    display: flex;
    gap: 0.5rem;
    padding: 0.75rem;
    border-top: 1px solid var(--border);
    background: var(--surface);
  }

  .chat-input input {
    flex: 1;
    padding: 0.5rem 0.75rem;
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    background: var(--surface);
    color: var(--text);
    font-family: inherit;
    font-size: 0.95rem;
    outline: none;
    transition:
      border-color 0.12s ease,
      box-shadow 0.12s ease;
  }

  .chat-input input:focus {
    border-color: var(--accent);
    box-shadow: var(--focus-ring);
  }

  .chat-input button {
    padding: 0.5rem 1rem;
    background: var(--accent);
    color: var(--accent-text);
    border: none;
    border-radius: var(--radius-sm);
    font-family: inherit;
    font-size: 0.95rem;
    font-weight: 600;
    cursor: pointer;
    transition: background 0.12s ease;
  }

  .chat-input button:hover {
    background: var(--accent-hover);
  }
</style>
```

### chat/routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/chat': Mochi.page('./src/demos/chat/Chat.svelte'),
  '/ws/chat': (() => {
    const history: string[] = [];
    const TOPIC = 'chat';
    return Mochi.ws({
      open(ws) {
        ws.subscribe(TOPIC);
        for (const msg of history) {
          ws.send(msg);
        }
      },
      message(ws, message) {
        const text = String(message);
        history.push(text);
        // send to all subscribers including the sender
        ws.publish(TOPIC, text);
        ws.send(text);
      },
      close(ws) {
        ws.unsubscribe(TOPIC);
      },
    });
  })(),
};
```

## Demo: cookies

### cookies/CookieDemo.svelte
```svelte
<script lang="ts">
  import { isServer, isBrowser, cookies } from 'mochi-framework';

  let { defaultUsername = 'mochi_fan' } = $props();

  // Read cookies on both server and client
  // 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>
  .cookie-demo {
    display: flex;
    flex-direction: column;
    gap: 1rem;
  }

  .section h3 {
    font-size: 1.05rem;
    font-weight: 700;
    margin-bottom: 0.4rem;
    color: var(--text);
  }

  .env {
    font-weight: 400;
    color: var(--text-subtle);
    font-size: 0.85rem;
  }

  .desc {
    font-size: 0.95rem;
    color: var(--text-muted);
    margin-bottom: 0.6rem;
  }

  .desc code {
    background: var(--surface-muted);
    border: 1px solid var(--border);
    color: var(--text);
    font-family: var(--font-mono);
    padding: 0.1em 0.35em;
    border-radius: 4px;
    font-size: 0.85em;
  }

  .values {
    display: flex;
    flex-direction: column;
    gap: 0.35rem;
  }

  .val {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    font-size: 0.95rem;
  }

  .val .label {
    font-family: var(--font-mono);
    font-size: 0.9rem;
    color: var(--text-muted);
    min-width: 120px;
  }

  .val code {
    background: var(--code-bg);
    color: var(--code-accent);
    font-family: var(--font-mono);
    padding: 0.2rem 0.55rem;
    border-radius: 4px;
    font-size: 0.9rem;
  }

  .form {
    display: flex;
    gap: 0.75rem;
    flex-wrap: wrap;
    margin-bottom: 0.5rem;
  }

  .form label {
    display: flex;
    flex-direction: column;
    gap: 0.25rem;
    font-size: 0.85rem;
    color: var(--text-muted);
    font-weight: 600;
  }

  .form input,
  .form select {
    padding: 0.45rem 0.65rem;
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    background: var(--surface);
    color: var(--text);
    font-family: inherit;
    font-size: 0.95rem;
    outline: none;
    transition:
      border-color 0.12s ease,
      box-shadow 0.12s ease;
  }

  .form input:focus,
  .form select:focus {
    border-color: var(--accent);
    box-shadow: var(--focus-ring);
  }

  .actions {
    display: flex;
    gap: 0.5rem;
    flex-wrap: wrap;
  }

  .actions button {
    padding: 0.5rem 0.9rem;
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    background: var(--surface-muted);
    color: var(--text);
    font-family: inherit;
    font-size: 0.95rem;
    cursor: pointer;
    transition:
      background 0.12s ease,
      border-color 0.12s ease,
      color 0.12s ease;
  }

  .actions button:hover {
    background: var(--accent-soft);
    border-color: var(--accent);
    color: var(--accent-soft-text);
  }

  .actions button:focus-visible {
    outline: none;
    box-shadow: var(--focus-ring);
  }

  .actions button.danger {
    color: var(--badge-danger-text);
    border-color: var(--border);
    background: var(--surface-muted);
  }

  .actions button.danger:hover {
    background: var(--badge-danger-bg);
    border-color: var(--badge-danger-text);
    color: var(--badge-danger-text);
  }

  .message {
    margin-top: 0.4rem;
    font-size: 0.95rem;
    color: var(--badge-success-text);
    font-weight: 500;
  }
</style>
```

### cookies/Cookies.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CookieDemo from './CookieDemo.svelte';
  import { loadSources } from '../../components/utils.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)];

  const sources = await loadSources([
    { label: 'Cookies.svelte', path: './src/demos/cookies/Cookies.svelte' },
    { label: 'CookieDemo.svelte', path: './src/demos/cookies/CookieDemo.svelte' },
    { label: 'routes.ts', path: './src/demos/cookies/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage title="Cookies" description="Unified cookies API from 'mochi-framework'. Read and write cookies on the server and the client with the same accessor." {sources}>
  <CookieDemo defaultUsername={randomCuteName} mochi:hydrate />
</DemoPage>
```

### cookies/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 });
  }),
};
```

## Demo: data-loading

### 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 { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'DataLoading.svelte', path: './src/demos/data-loading/DataLoading.svelte' },
    { label: 'PokemonSelector.svelte', path: './src/demos/data-loading/PokemonSelector.svelte' },
    { label: 'PokemonHeader.svelte', path: './src/demos/data-loading/PokemonHeader.svelte' },
    { label: 'PokemonMeta.svelte', path: './src/demos/data-loading/PokemonMeta.svelte' },
    { label: 'PokemonStats.svelte', path: './src/demos/data-loading/PokemonStats.svelte' },
    { label: 'routes.ts', path: './src/demos/data-loading/routes.ts' },
    { label: 'cache.ts', path: './src/lib/cache.ts' },
    { label: 'index.ts', path: './src/demoIndex.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="Server-side data fetching with the PokéAPI. The Pokémon detail is rendered at request time — pick a different Pokémon from the dropdown to load it via a route param. The stats block hydrates when scrolled into view."
  {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:visible={{ rootMargin: '100px' }} {stats} />
    </div>
  {:else}
    <p class="not-found">No Pokémon found for "{id}".</p>
  {/if}
</DemoPage>

<style>
  .card {
    background: var(--surface);
    border-radius: var(--radius-lg);
    width: 100%;
    max-width: 320px;
    margin: 0 auto;
    overflow: hidden;
    border: 1px solid var(--border);
  }

  .divider {
    height: 1px;
    background: var(--border);
    margin: 0 1.5rem;
  }

  .not-found {
    text-align: center;
    color: var(--text-muted);
    padding: 2rem 0;
  }
</style>
```

### data-loading/PokemonHeader.svelte
```svelte
<script>
  import { isServer, isDev } from 'mochi-framework';
  // console.log('Running on:', isServer ? 'SERVER' : 'BROWSER', '|', isDev ? 'DEV' : 'PROD');

  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>
  .header {
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 0.5rem;
    padding: 1.5rem 1.5rem 0;
  }

  .sprite {
    width: 140px;
    height: 140px;
    image-rendering: pixelated;
    filter: drop-shadow(0 4px 8px rgba(0, 0, 0, 0.15));
  }

  .title {
    text-align: center;
  }

  .id {
    font-size: 0.85rem;
    color: var(--text-muted);
    font-weight: 500;
    letter-spacing: 0.05em;
  }

  h1 {
    margin: 0.1rem 0 0;
    font-size: 1.8rem;
    font-weight: 700;
    color: var(--text);
    text-transform: capitalize;
    letter-spacing: 0.02em;
  }

  .env-badge {
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    padding: 0.2rem 0.6rem;
    font-size: 0.75rem;
    color: var(--text-muted);
    display: table;
    margin: 0.5rem auto;
  }
</style>
```

### data-loading/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',
  };
</script>

<div class="meta">
  <div class="types">
    {#each types as t (t)}
      <span class="type-badge" style="background:{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>
  .meta {
    padding: 1rem 1.5rem;
    display: flex;
    flex-direction: column;
    gap: 1rem;
  }

  .types {
    display: flex;
    gap: 0.5rem;
    justify-content: center;
  }

  .type-badge {
    padding: 0.25rem 0.9rem;
    border-radius: 999px;
    color: #fff;
    font-size: 0.78rem;
    font-weight: 600;
    text-transform: capitalize;
    letter-spacing: 0.04em;
    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
  }

  .stats-grid {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 0.6rem;
  }

  .stat-item {
    background: var(--surface-muted);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    padding: 0.5rem 0.75rem;
    display: flex;
    flex-direction: column;
    gap: 0.15rem;
  }

  .label {
    font-size: 0.75rem;
    color: var(--text-muted);
    text-transform: uppercase;
    letter-spacing: 0.06em;
    font-weight: 600;
  }

  .value {
    font-size: 0.95rem;
    color: var(--text);
    font-weight: 500;
    text-transform: capitalize;
  }

  .abilities {
    font-size: 0.85rem;
  }
</style>
```

### data-loading/PokemonSelector.svelte
```svelte
<script lang="ts">
  let { current, options } = $props<{
    current: string;
    options: { name: string }[];
  }>();

  function onChange(event: Event) {
    (event.currentTarget as HTMLSelectElement).form?.requestSubmit();
  }
</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}>
        {option.name}
      </option>
    {/each}
  </select>
  <noscript>
    <button type="submit">Go</button>
  </noscript>
</form>

<style>
  .selector {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    margin-bottom: 1rem;
    flex-wrap: wrap;
  }

  label {
    font-size: 0.85rem;
    color: var(--text-muted);
    font-weight: 500;
  }

  select {
    flex: 1;
    min-width: 0;
    padding: 0.5rem 0.75rem;
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    background: var(--surface);
    color: var(--text);
    font-size: 0.9rem;
    text-transform: capitalize;
    cursor: pointer;
    transition:
      border-color 0.12s ease,
      box-shadow 0.12s ease;
  }

  select:focus-visible {
    outline: none;
    border-color: var(--accent);
    box-shadow: var(--focus-ring);
  }

  button {
    padding: 0.5rem 0.9rem;
    border: 1px solid var(--accent);
    border-radius: var(--radius-md);
    background: var(--accent);
    color: var(--accent-text);
    font-family: inherit;
    font-size: 0.85rem;
    font-weight: 600;
    cursor: pointer;
    transition: background 0.12s ease;
  }

  button:hover {
    background: var(--accent-hover);
    border-color: var(--accent-hover);
  }
</style>
```

### data-loading/PokemonStats.svelte
```svelte
<script>
  import { isBrowser } from 'mochi-framework';
  if (isBrowser) {
    console.log('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>
  .stats {
    padding: 0 1.5rem 1.5rem;
  }

  h2 {
    font-size: 0.75rem;
    text-transform: uppercase;
    letter-spacing: 0.08em;
    color: var(--text-muted);
    font-weight: 600;
    margin: 0 0 0.75rem;
  }

  .row {
    display: grid;
    grid-template-columns: 80px 36px 1fr;
    align-items: center;
    gap: 0.5rem;
    margin-bottom: 0.45rem;
  }

  .name {
    font-size: 0.8rem;
    color: var(--text-muted);
    text-transform: capitalize;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
  }

  .num {
    font-size: 0.85rem;
    font-weight: 600;
    color: var(--text);
    font-family: var(--font-mono);
    text-align: right;
  }

  .filter {
    width: 100%;
    box-sizing: border-box;
    margin-bottom: 0.75rem;
    padding: 0.3rem 0.5rem;
    font-size: 0.85rem;
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    background: var(--surface);
    color: var(--text);
    outline: none;
    transition:
      border-color 0.12s ease,
      box-shadow 0.12s ease;
  }

  .filter:focus-visible {
    border-color: var(--accent);
    box-shadow: var(--focus-ring);
  }

  .bar-track {
    background: var(--surface-muted);
    border: 1px solid var(--border);
    border-radius: 999px;
    height: 6px;
    overflow: hidden;
  }

  .bar {
    height: 100%;
    border-radius: 999px;
    background: linear-gradient(90deg, var(--accent-soft), var(--accent));
    min-width: 4px;
  }
</style>
```

### data-loading/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)}`);
      },
    },
  }),
};
```

## Demo: devalue

### devalue/Devalue.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import DevalueDemo from './DevalueDemo.svelte';
  import { typeOf } from './devalueTypeOf.ts';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'DevalueDemo.svelte', path: './src/demos/devalue/DevalueDemo.svelte' },
    { label: 'devalueTypeOf.ts', path: './src/demos/devalue/devalueTypeOf.ts' },
    { label: 'routes.ts', path: './src/demos/devalue/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);

  const shared = { x: 1 };
  const cyclic = { name: 'cyclic' };
  cyclic.self = cyclic;

  const devalueProps = {
    dateVal: new Date('2025-01-15T12:00:00Z'),
    regexpVal: /hello\s+world/gi,
    mapVal: new Map([
      ['a', 1],
      ['b', 2],
      ['c', 3],
    ]),
    setVal: new Set([10, 20, 30]),
    bigintVal: 9007199254740993n,
    urlVal: new URL('https://mochi.dev/docs?version=5'),
    searchParamsVal: new URLSearchParams('theme=dark&lang=en'),
    typedArrayVal: new Uint8Array([72, 101, 108, 108, 111]),
    undefinedVal: undefined,
    infinityVal: Infinity,
    nanVal: NaN,
    negZeroVal: -0,
    repeatedRef: [shared, shared],
    cyclicRef: cyclic,
  };

  const serverTypes = {
    Date: typeOf(devalueProps.dateVal),
    RegExp: typeOf(devalueProps.regexpVal),
    Map: typeOf(devalueProps.mapVal),
    Set: typeOf(devalueProps.setVal),
    BigInt: typeOf(devalueProps.bigintVal),
    URL: typeOf(devalueProps.urlVal),
    URLSearchParams: typeOf(devalueProps.searchParamsVal),
    Uint8Array: typeOf(devalueProps.typedArrayVal),
    undefined: typeOf(devalueProps.undefinedVal),
    Infinity: typeOf(devalueProps.infinityVal),
    NaN: typeOf(devalueProps.nanVal),
    '-0': typeOf(devalueProps.negZeroVal),
    'Repeated ref': typeOf(devalueProps.repeatedRef),
    'Cyclic ref': typeOf(devalueProps.cyclicRef),
  };
</script>

<DemoPage
  title="Devalue Serialization"
  description="Rich type serialization via devalue. The Server Type column is captured during SSR and shipped as strings; the Client Type column is resolved live after hydration. They should match — proving the types survived the round-trip."
  {sources}
>
  <DevalueDemo {...devalueProps} {serverTypes} mochi:hydrate />
</DemoPage>
```

### devalue/DevalueDemo.svelte
```svelte
<script>
  import { isBrowser } from 'mochi-framework';
  import { typeOf } from './devalueTypeOf.ts';

  let {
    dateVal,
    regexpVal,
    mapVal,
    setVal,
    bigintVal,
    urlVal,
    searchParamsVal,
    typedArrayVal,
    undefinedVal,
    infinityVal,
    nanVal,
    negZeroVal,
    repeatedRef,
    cyclicRef,
    serverTypes,
  } = $props();

  function display(v) {
    if (v === undefined) {
      return 'undefined';
    }
    if (v === null) {
      return 'null';
    }
    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.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="devalue-demo">
  <table>
    <thead>
      <tr>
        <th>Type</th>
        <th>Value</th>
        <th>Server Type</th>
        <th>Client Type</th>
      </tr>
    </thead>
    <tbody>
      {#each rows as row (row.label)}
        {@const clientType = isBrowser ? typeOf(row.value) : ''}
        {@const serverType = serverTypes?.[row.label] ?? '—'}
        <tr>
          <td class="label">{row.label}</td>
          <td class="value"><code>{display(row.value)}</code></td>
          <td class="type">{serverType}</td>
          <td class="type pending">{clientType}</td>
        </tr>
      {/each}
      <tr>
        <td class="label">Repeated ref</td>
        <td class="value"><code>{repeatedRef?.[0] === repeatedRef?.[1] ? 'same ref' : 'different refs'}</code></td>
        <td class="type">identity check</td>
        <td class="type pending">{isBrowser ? 'identity check' : ''}</td>
      </tr>
      <tr>
        <td class="label">Cyclic ref</td>
        <td class="value"><code>{cyclicRef?.self === cyclicRef ? 'self === obj' : 'broken'}</code></td>
        <td class="type">identity check</td>
        <td class="type pending">{isBrowser ? 'identity check' : ''}</td>
      </tr>
    </tbody>
  </table>
  <p class="env">{isBrowser ? 'Client (hydrated)' : 'Server (SSR)'}</p>
</div>

<style>
  .devalue-demo {
    background: var(--surface-muted);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    padding: 0.85rem 1rem;
    overflow-x: auto;
  }

  table {
    width: 100%;
    min-width: 520px;
    border-collapse: collapse;
    font-size: 0.9rem;
  }

  th {
    text-align: left;
    padding: 0.4rem 0.55rem;
    border-bottom: 2px solid var(--border-strong);
    color: var(--text-muted);
    font-weight: 600;
    font-size: 0.72rem;
    text-transform: uppercase;
    letter-spacing: 0.06em;
  }

  td {
    padding: 0.4rem 0.55rem;
    border-bottom: 1px solid var(--border);
    vertical-align: middle;
  }

  tbody tr:last-child td {
    border-bottom: 0;
  }

  .label {
    font-weight: 600;
    color: var(--text);
  }

  .value code {
    background: var(--surface);
    border: 1px solid var(--border);
    padding: 0.12rem 0.4rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
    color: var(--text);
    word-break: break-all;
  }

  .type {
    color: var(--text-subtle);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }

  .type.pending:empty::before {
    content: '—';
    color: var(--text-subtle);
    opacity: 0.5;
  }

  .env {
    margin-top: 0.85rem;
    font-family: var(--font-serif);
    font-style: italic;
    font-size: 0.95rem;
    color: var(--text-muted);
    text-align: right;
  }
</style>
```

### devalue/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;
}
```

### devalue/routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/devalue': Mochi.page('./src/demos/devalue/Devalue.svelte'),
};
```

## Demo: error-boundaries

### 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 { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    {
      label: 'ErrorBoundaries.svelte',
      path: './src/demos/error-boundaries/ErrorBoundaries.svelte',
    },
    { label: 'ThrowOnSsr.svelte', path: './src/demos/error-boundaries/ThrowOnSsr.svelte' },
    { label: 'ThrowOnClient.svelte', path: './src/demos/error-boundaries/ThrowOnClient.svelte' },
    {
      label: 'ThrowOnServerIsland.svelte',
      path: './src/demos/error-boundaries/ThrowOnServerIsland.svelte',
    },
    {
      label: 'HealthyServerIsland.svelte',
      path: './src/demos/error-boundaries/HealthyServerIsland.svelte',
    },
    { label: 'routes.ts', path: './src/demos/error-boundaries/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.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="Each section contains a component that throws on purpose. Without boundaries, any one of them would take down this whole page; 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> yourself — 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 catches it and returns a 200 with an error stub — so the browser doesn't burn its retry
        budget 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>
  .mode {
    display: flex;
    flex-direction: column;
    gap: 0.75rem;
    margin-bottom: 2.5rem;
  }

  .mode header {
    display: flex;
    flex-direction: column;
    gap: 0.35rem;
  }

  .mode h2 {
    margin: 0;
    font-size: 1.05rem;
  }

  .mode h2 code,
  .mode p code {
    font-family: var(--font-mono);
    background: var(--surface-muted);
    border: 1px solid var(--border);
    color: var(--text);
    padding: 0.1em 0.35em;
    border-radius: 4px;
    font-size: 0.85em;
    font-weight: 500;
  }

  .mode p {
    margin: 0;
    color: var(--text-muted);
    font-size: 0.95rem;
    line-height: 1.5;
  }

  .placeholder {
    padding: 1rem;
    border: 2px dashed var(--border-strong);
    border-radius: var(--radius-md);
    color: var(--text-subtle);
    text-align: center;
    font-size: 0.9rem;
  }

  .caught {
    padding: 0.75rem 1rem;
    border: 2px dashed var(--badge-warning-text, #c80);
    background: var(--badge-warning-bg, #fff7e6);
    color: var(--badge-warning-text, #8a4d00);
    border-radius: var(--radius-md);
    font-size: 0.9rem;
  }

  .caught code {
    font-family: var(--font-mono);
    font-size: 0.85em;
  }
</style>
```

### error-boundaries/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>
  .card {
    padding: 1rem 1.25rem;
    background: var(--surface-muted);
    border: 2px solid var(--border);
    border-radius: var(--radius-md);
    color: var(--text);
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
  }

  .card p {
    margin: 0;
    font-size: 0.95rem;
  }

  .card code {
    font-family: var(--font-mono);
    background: var(--surface);
    border: 1px solid var(--border);
    padding: 0.05em 0.3em;
    border-radius: 4px;
    font-size: 0.85em;
  }
</style>
```

### error-boundaries/ThrowOnClient.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';

  let { label = 'ThrowOnClient' }: { label?: string } = $props();

  if (isBrowser) {
    throw new Error(`Client throw from <${label}>`);
  }
</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>
  .card {
    padding: 1rem 1.25rem;
    background: var(--surface-muted);
    border: 2px solid var(--border);
    border-radius: var(--radius-md);
    color: var(--text);
    font-size: 0.95rem;
  }
</style>
```

### error-boundaries/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();

  // Throws synchronously every render. Used as a `mochi:defer` target — the
  // throw happens at the /island/:name endpoint and 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>
```

### error-boundaries/ThrowOnSsr.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';

  let { label = 'ThrowOnSsr' }: { label?: string } = $props();

  if (!isBrowser) {
    throw new Error(`SSR throw from <${label}>`);
  }
</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>
  .card {
    padding: 1rem 1.25rem;
    background: var(--surface-muted);
    border: 2px solid var(--border);
    border-radius: var(--radius-md);
    color: var(--text);
    font-size: 0.95rem;
  }
</style>
```

### error-boundaries/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'),
};
```

## Demo: error

### error/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>
```

### error/ErrorDemo.svelte
```svelte
<script>
  import { highlightCode } from 'mochi-framework/highlight';
  import DemoPage from '../../components/DemoPage.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'ErrorDemo.svelte', path: './src/demos/error/ErrorDemo.svelte' },
    { label: 'Error500.svelte', path: './src/demos/error/Error500.svelte' },
    { label: 'routes.ts', path: './src/demos/error/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);

  const handleErrorSnippet = `const handleError: HandleError = ({ error, event, status, message }) => {
  console.log(
    \`[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) {
    console.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 = highlightCode(handleErrorSnippet, 'ts');
</script>

<DemoPage title="Error Handling" description="The built-in default error page plus a handleError hook, rendered for uncaught render errors and unmatched routes." {sources}>
  <div class="prose">
    <p>
      Mochi catches any throw from a page's <code>serverProps</code> resolver or Svelte
      <code>&lt;script&gt;</code>, along with 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 such error — use it to log, forward to an error tracker, sanitize the message, or return a <code>Response</code> to short-circuit rendering
      entirely.
    </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>

    <!-- eslint-disable-next-line svelte/no-at-html-tags -->
    {@html handleErrorHtml}

    <p>
      Tail your dev server's output while clicking the links above — you'll see one
      <code>[handleError]</code> line per visit. Unmatched routes log <code>error null</code>; SSR throws log <code>error present</code>.
    </p>
  </div>
</DemoPage>

<style>
  .prose {
    font-size: 0.95rem;
    line-height: 1.6;
    color: var(--text);
  }

  .prose p {
    margin: 0 0 1rem;
  }

  .prose p.lead {
    margin-top: 0.5rem;
    margin-bottom: 0.5rem;
    font-weight: 600;
    color: var(--text);
  }

  .prose code {
    font-family: var(--font-mono);
    background: var(--surface-muted);
    padding: 0.12rem 0.4rem;
    border-radius: var(--radius-sm);
    font-size: 0.88em;
    color: var(--text);
  }

  .examples {
    list-style: none;
    margin: 0 0 1.25rem;
    padding: 0;
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
  }

  .examples li {
    display: flex;
    align-items: baseline;
    gap: 0.75rem;
    padding: 0.6rem 0.85rem;
    background: var(--surface-muted);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    flex-wrap: wrap;
  }

  .examples li a {
    text-decoration: none;
    flex-shrink: 0;
  }

  .examples li a code {
    background: var(--surface);
    border: 1px solid var(--border);
    color: var(--text);
    transition:
      background 0.12s ease,
      color 0.12s ease,
      border-color 0.12s ease;
  }

  .examples li a:hover code {
    background: var(--accent-soft);
    border-color: var(--accent);
    color: var(--accent-soft-text);
  }

  .examples li span {
    color: var(--text-muted);
    font-size: 0.88rem;
  }
</style>
```

### error/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'),
};
```

## Demo: file-upload

### file-upload/FileUpload.svelte
```svelte
<script lang="ts">
  import { enhance, isServer, getRequestContext } 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, isHydratable } = $props<{ label: string; isHydratable?: boolean }>();

  // svelte-ignore state_referenced_locally
  const _form = !isHydratable && 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 isHydratable}
        <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>
  .demo-block {
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
    align-items: flex-start;
    margin-top: 0.75rem;
  }

  .label {
    margin: 0;
    font-size: 0.85rem;
    color: var(--text-subtle);
  }

  .error {
    margin: 0;
    padding: 0.5rem 0.75rem;
    background: var(--badge-danger-bg);
    color: var(--badge-danger-text);
    border-radius: var(--radius-sm);
    font-size: 0.9rem;
  }

  .file-result {
    width: 100%;
    display: flex;
    flex-direction: column;
    gap: 0.4rem;
  }

  .file-meta {
    margin: 0;
    font-size: 0.85rem;
    color: var(--text-muted);
    font-family: var(--font-mono);
  }

  .file-content {
    margin: 0;
    padding: 0.75rem;
    background: var(--code-bg);
    color: var(--text);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
    white-space: pre-wrap;
    word-break: break-word;
    max-height: 12rem;
    overflow-y: auto;
    width: 100%;
    box-sizing: border-box;
  }

  form {
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
    align-items: flex-start;
  }

  .file-row {
    display: flex;
    align-items: center;
    gap: 0.65rem;
  }

  .file-btn {
    display: inline-flex;
    align-items: center;
    gap: 0.4rem;
    padding: 0.4rem 0.85rem;
    background: var(--surface-muted);
    color: var(--text);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 0.9rem;
    font-weight: 500;
    cursor: pointer;
    user-select: none;
    transition:
      background 0.1s,
      border-color 0.1s;
  }

  .file-btn:hover {
    background: var(--surface);
    border-color: var(--accent);
    color: var(--accent);
  }

  .file-btn input[type='file'] {
    display: none;
  }

  .file-name {
    font-size: 0.875rem;
    color: var(--text-subtle);
    font-family: var(--font-mono);
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
    max-width: 18rem;
  }

  .file-name.chosen {
    color: var(--text);
  }

  button {
    padding: 0.5rem 1rem;
    background: var(--accent);
    color: var(--accent-text);
    border: 1px solid var(--accent);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 0.95rem;
    font-weight: 600;
    cursor: pointer;
  }

  button:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }

  button:hover:not(:disabled) {
    background: var(--accent-hover);
    border-color: var(--accent-hover);
  }
</style>
```

### file-upload/FileUploadDemo.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import FileUpload from './FileUpload.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'FileUploadDemo.svelte', path: './src/demos/file-upload/FileUploadDemo.svelte' },
    { label: 'FileUpload.svelte', path: './src/demos/file-upload/FileUpload.svelte' },
    { label: 'routes.ts', path: './src/demos/file-upload/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage
  title="File Upload"
  description="multipart/form-data submission with server-side validation. With the enhance attachment, the file content is shown inline; without it the page re-renders with the result from the form snapshot."
  {sources}
>
  <p>
    The action reads a <code>.txt</code> or <code>.md</code> file from <code>multipart/form-data</code> and echoes its name and content back via <code>success()</code>. With
    <code>{'{@attach enhance(...)}'}</code> the content appears inline; without it the page re-renders with the file content from the form snapshot.
  </p>
  <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>
  h3 {
    margin: 1.5rem 0 0.25rem;
    font-size: 0.95rem;
    font-weight: 600;
    color: var(--text-muted);
  }

  p {
    margin: 0 0 0.5rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }
</style>
```

### file-upload/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 });
      },
    },
  }),
};
```

## Demo: font-loading

### font-loading/FontLoading.svelte
```svelte
<script>
  import '@fontsource/jetbrains-mono';
  import './lobster.css';
  import HydratedBox from './HydratedBox.svelte';
  import DemoPage from '../../components/DemoPage.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'FontLoading.svelte', path: './src/demos/font-loading/FontLoading.svelte' },
    { label: 'HydratedBox.svelte', path: './src/demos/font-loading/HydratedBox.svelte' },
    { label: 'lobster.css', path: './src/demos/font-loading/lobster.css' },
    { label: 'routes.ts', path: './src/demos/font-loading/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage
  title="Font loading"
  description="Ship a custom font with a Mochi page: as an @fontsource package, or a standalone .woff2 file referenced from a colocated CSS file. The same import works inside a hydratable island — the bundle stays in the page <head>, never in the JS. All go through the framework's CSS-import bundler with no shell.html changes."
  {sources}
>
  <section>
    <h2>Fontsource package</h2>
    <p>
      Add <code>@fontsource/jetbrains-mono</code> as a dependency and side-effect-import it from any component. The framework bundles the package's CSS (with woff2 inlined as data
      URIs), serves it from <code>/_mochi/import-css/*.css</code>, and links it from every page that transitively imports the component.
    </p>
    <p class="sample sample-mono">The quick brown fox jumps over the lazy dog. 1234567890</p>
  </section>

  <section>
    <h2>Standalone .woff2</h2>
    <p>
      Drop a <code>.woff2</code> next to your component and reference it from a tiny
      <code>@font-face</code> CSS file:
    </p>
    <pre><code
        >{`@font-face {
  font-family: 'Lobster';
  src: url('./lobster.woff2') format('woff2');
}`}</code
      ></pre>
    <p>
      Side-effect-import the CSS from the component (<code>import './lobster.css'</code>). Bun's CSS bundler inlines the <code>.woff2</code> as a base64 data URI in the bundled CSS,
      so the font ships in the same request as the stylesheet — no separate font fetch.
    </p>
    <p class="sample sample-display">The quick brown fox jumps over the lazy dog. 1234567890</p>
  </section>

  <section>
    <h2>Inside a hydratable island</h2>
    <p>
      The same import works in a component with <code>mochi:hydrate</code>. The framework strips the CSS import from both the SSR and the client bundle, then links the bundled
      stylesheet from the page <code>&lt;head&gt;</code>. The badge flips to <em>hydrated</em> in the browser; the styled text uses the bundled font on first paint with no JS-injected
      styles.
    </p>
    <HydratedBox mochi:hydrate />
  </section>
</DemoPage>

<style>
  section {
    margin: 2rem 0;
  }
  h2 {
    margin-bottom: 0.5rem;
    font-family: var(--font-serif);
  }
  .sample {
    margin-top: 1rem;
    padding: 1.25rem;
    background: var(--surface-muted);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    font-size: 1.5rem;
  }
  .sample-mono {
    font-family: 'JetBrains Mono', ui-monospace, SFMono-Regular, monospace;
  }
  .sample-display {
    font-family: 'Lobster', cursive;
    font-size: 2rem;
  }
  pre {
    margin: 0.75rem 0;
  }
</style>
```

### font-loading/HydratedBox.svelte
```svelte
<script lang="ts">
  import '@fontsource/lobster-two';
  import { isBrowser } from 'mochi-framework';
  import Badge from '../../components/Badge.svelte';
</script>

<div class="box" class:hydrated={isBrowser}>
  <div class="header">
    <span class="title">Hydrated island</span>
    <Badge kind={isBrowser ? 'success' : 'info'}>
      {isBrowser ? 'hydrated' : 'server-rendered only'}
    </Badge>
  </div>
  <p class="display">Lobster Two ships with this island.</p>
</div>

<style>
  .box {
    margin-top: 1.5rem;
    padding: 1.25rem;
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    background: var(--surface-muted);
    transition: border-color 200ms ease;
  }
  .box.hydrated {
    border-color: var(--success, #59c08a);
  }
  .header {
    display: flex;
    align-items: center;
    justify-content: space-between;
    margin-bottom: 0.75rem;
  }
  .title {
    font-weight: 600;
  }
  .display {
    font-family: 'Lobster Two', cursive;
    font-size: 1.75rem;
    margin: 0.5rem 0 0;
  }
</style>
```

### font-loading/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'),
};
```

## Demo: form-cancel

### form-cancel/FormCancel.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import LookupDemo from './LookupDemo.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'FormCancel.svelte', path: './src/demos/form-cancel/FormCancel.svelte' },
    { label: 'LookupDemo.svelte', path: './src/demos/form-cancel/LookupDemo.svelte' },
    { label: 'routes.ts', path: './src/demos/form-cancel/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage
  title="Cancelling"
  description="Two cancellation paths: cancel() short-circuits before the fetch; controller.abort() stops an in-flight request. Both leave the form in a clean idle state."
  {sources}
>
  <p>
    The action sleeps 3 seconds to simulate a slow lookup. With <code>{'{@attach enhance(...)}'}</code>, submitting the same query twice calls <code>cancel()</code> — the fetch
    never fires. The visible "Cancel" button calls <code>controller.abort()</code> to stop the in-flight request. Without enhancement, it is a plain POST that waits for the server.
  </p>
  <h3>With <code>{'{@attach enhance(...)}'}</code></h3>
  <LookupDemo label="Search, then search the same query again (cancel) or click Cancel while searching (abort)" mochi:hydrate />
  <h3>Plain HTML</h3>
  <LookupDemo label="Plain POST — waits the full 3 s, page re-renders with the result" />
</DemoPage>

<style>
  h3 {
    margin: 1.5rem 0 0.25rem;
    font-size: 0.95rem;
    font-weight: 600;
    color: var(--text-muted);
  }

  p {
    margin: 0 0 0.5rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }
</style>
```

### form-cancel/LookupDemo.svelte
```svelte
<script lang="ts">
  import { enhance, isServer, getRequestContext } from 'mochi-framework';
  import type { MochiEnhanceOptions, MochiSubmitFunction } from 'mochi-framework';

  let { label, isHydratable } = $props<{ label: string; isHydratable?: boolean }>();

  // svelte-ignore state_referenced_locally
  const _form = !isHydratable && 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;

  let pending = $state(false);
  let currentController = $state<AbortController | null>(null);
  let result = $state<string | null>(initialResult);
  let message = $state<string | null>(initialMessage);
  let lastQuery = '';

  const handleSubmit: MochiSubmitFunction<{ result: string }, { error: string }> = ({ cancel, controller, formData }) => {
    const query = String(formData.get('query') ?? '').trim();
    if (query === lastQuery && result !== null) {
      cancel();
      message = `Already fetched "${query}" — no request sent.`;
      return;
    }
    lastQuery = query;
    result = null;
    message = null;
    currentController = controller;
    return ({ result: r }) => {
      currentController = null;
      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 && currentController) {
        message = 'Request aborted.';
        currentController = null;
      }
    },
  };
</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>
    <div class="button-row">
      <button type="submit" disabled={pending}>{pending ? 'Searching…' : 'Search'}</button>
      {#if pending}
        <button type="button" class="cancel-btn" onclick={() => currentController?.abort()}> Cancel </button>
      {/if}
    </div>
  </form>
  {#if result}
    <p class="result" role="status">{result}</p>
  {/if}
  {#if message}
    <p class="message" role="alert">{message}</p>
  {/if}
</div>

<style>
  .demo-block {
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
    align-items: flex-start;
    margin-top: 0.75rem;
  }

  .label {
    margin: 0;
    font-size: 0.85rem;
    color: var(--text-subtle);
  }

  .lookup {
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
    align-items: flex-start;
  }

  .lookup label {
    display: flex;
    flex-direction: column;
    gap: 0.25rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  .lookup input {
    padding: 0.5rem 0.7rem;
    background: var(--surface);
    color: var(--text);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    font-family: inherit;
    font-size: 0.95rem;
    min-width: 16rem;
  }

  .lookup input:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }

  .lookup input:focus-visible {
    outline: none;
    border-color: var(--accent);
    box-shadow: var(--focus-ring);
  }

  .button-row {
    display: flex;
    align-items: center;
    gap: 0.6rem;
  }

  button {
    padding: 0.5rem 1rem;
    background: var(--accent);
    color: var(--accent-text);
    border: 1px solid var(--accent);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 0.95rem;
    font-weight: 600;
    cursor: pointer;
  }

  button:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }

  button:hover:not(:disabled) {
    background: var(--accent-hover);
    border-color: var(--accent-hover);
  }

  .cancel-btn {
    background: var(--surface-muted);
    color: var(--text);
    border-color: var(--border);
  }

  .cancel-btn:hover:not(:disabled) {
    background: var(--badge-danger-bg);
    color: var(--badge-danger-text);
    border-color: var(--badge-danger-text);
  }

  .result {
    margin: 0;
    padding: 0.5rem 0.75rem;
    background: var(--surface);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.9rem;
    color: var(--text);
  }

  .message {
    margin: 0;
    font-size: 0.9rem;
    color: var(--text-subtle);
    font-style: italic;
  }
</style>
```

### form-cancel/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` });
      },
    },
  }),
};
```

## Demo: form-errors

### form-errors/ErrorDemo.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiSubmitFunction } from 'mochi-framework';

  let { label } = $props<{ label: string }>();

  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>
  .demo-block {
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
    align-items: flex-start;
    margin-top: 0.75rem;
  }

  .label {
    margin: 0;
    font-size: 0.85rem;
    color: var(--text-subtle);
  }

  .error {
    margin: 0 0 0.5rem;
    padding: 0.5rem 0.75rem;
    background: var(--badge-danger-bg);
    color: var(--badge-danger-text);
    border-radius: var(--radius-sm);
    font-size: 0.9rem;
  }

  button {
    padding: 0.5rem 1rem;
    background: var(--badge-danger-bg);
    color: var(--badge-danger-text);
    border: 1px solid var(--badge-danger-text);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 0.95rem;
    font-weight: 600;
    cursor: pointer;
  }

  button:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }

  button:hover:not(:disabled) {
    opacity: 0.85;
  }
</style>
```

### form-errors/FormErrors.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import ErrorDemo from './ErrorDemo.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'FormErrors.svelte', path: './src/demos/form-errors/FormErrors.svelte' },
    { label: 'ErrorDemo.svelte', path: './src/demos/form-errors/ErrorDemo.svelte' },
    { label: 'routes.ts', path: './src/demos/form-errors/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage
  title="Form Errors"
  description="The action throws a plain Error. With the enhance attachment, the error message is shown inline; without it the server renders the Mochi 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>
  h3 {
    margin: 1.5rem 0 0.25rem;
    font-size: 0.95rem;
    font-weight: 600;
    color: var(--text-muted);
  }

  p {
    margin: 0 0 0.5rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }
</style>
```

### form-errors/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');
      },
    },
  }),
};
```

## Demo: form-redirects

### form-redirects/FormRedirects.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import RedirectDemo from './RedirectDemo.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'FormRedirects.svelte', path: './src/demos/form-redirects/FormRedirects.svelte' },
    { label: 'RedirectDemo.svelte', path: './src/demos/form-redirects/RedirectDemo.svelte' },
    { label: 'routes.ts', path: './src/demos/form-redirects/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);

  let { redirected } = $props<{ redirected: boolean }>();
</script>

<DemoPage
  title="Form Redirects"
  description="The action returns redirect(303, …). With the enhance attachment, the JSON envelope is intercepted so you can inspect it before navigating; without it the browser follows the HTTP 303."
  {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>
  h3 {
    margin: 1.5rem 0 0.25rem;
    font-size: 0.95rem;
    font-weight: 600;
    color: var(--text-muted);
  }

  p {
    margin: 0 0 0.5rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }

  .redirect-flash {
    padding: 0.5rem 0.75rem;
    background: var(--badge-info-bg, #dbeafe);
    color: var(--badge-info-text, #1e40af);
    border-radius: var(--radius-sm);
    font-size: 0.9rem;
    margin: 0 0 1rem;
  }
</style>
```

### form-redirects/RedirectDemo.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiSubmitFunction, MochiEnhanceResult } from 'mochi-framework';

  let { label } = $props<{ label: string }>();

  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. Call follow() to actually navigate.
  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>
  .demo-block {
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
    align-items: flex-start;
    margin-top: 0.75rem;
  }

  .label {
    margin: 0;
    font-size: 0.85rem;
    color: var(--text-subtle);
  }

  .result {
    display: flex;
    flex-direction: column;
    gap: 0.25rem;
    padding: 0.75rem;
    background: var(--surface-muted);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    font-size: 0.9rem;
  }

  .result p {
    margin: 0;
  }

  .result button {
    margin-top: 0.5rem;
    align-self: flex-start;
  }

  button {
    padding: 0.5rem 1rem;
    background: var(--accent);
    color: var(--accent-text);
    border: 1px solid var(--accent);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 0.95rem;
    font-weight: 600;
    cursor: pointer;
  }

  button:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }

  button:hover:not(:disabled) {
    background: var(--accent-hover);
    border-color: var(--accent-hover);
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.3rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }
</style>
```

### form-redirects/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'),
    },
  }),
};
```

## Demo: form-return-data

### form-return-data/FormReturnData.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import RandomRoll from './RandomRoll.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'FormReturnData.svelte', path: './src/demos/form-return-data/FormReturnData.svelte' },
    { label: 'RandomRoll.svelte', path: './src/demos/form-return-data/RandomRoll.svelte' },
    { label: 'routes.ts', path: './src/demos/form-return-data/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage
  title="Using form return data"
  description="An action returns a payload via success(...). With the enhance attachment, the JSON result updates the UI in place. Without it, the page re-renders and the component reads the value from the request's form snapshot."
  {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>
  h3 {
    margin: 1.5rem 0 0.25rem;
    font-size: 0.95rem;
    font-weight: 600;
    color: var(--text-muted);
  }

  p {
    margin: 0 0 0.5rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }
</style>
```

### form-return-data/RandomRoll.svelte
```svelte
<script lang="ts">
  import { enhance, isServer, getRequestContext } from 'mochi-framework';
  import type { MochiSubmitFunction } from 'mochi-framework';

  let { label, isHydratable } = $props<{ label: string; isHydratable?: boolean }>();

  // svelte-ignore state_referenced_locally
  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>
  .roll {
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
    align-items: flex-start;
    margin-top: 0.75rem;
  }

  .label {
    margin: 0;
    font-size: 0.85rem;
    color: var(--text-subtle);
  }

  .roll label {
    display: flex;
    flex-direction: column;
    gap: 0.25rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  .roll input {
    padding: 0.5rem 0.7rem;
    background: var(--surface);
    color: var(--text);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 1rem;
    width: 8rem;
    text-align: center;
  }

  .roll button {
    padding: 0.5rem 1rem;
    background: var(--accent);
    color: var(--accent-text);
    border: 1px solid var(--accent);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 0.95rem;
    font-weight: 600;
    cursor: pointer;
  }

  .roll button:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }

  .roll button:hover:not(:disabled) {
    background: var(--accent-hover);
    border-color: var(--accent-hover);
  }
</style>
```

### form-return-data/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 }),
    },
  }),
};
```

## Demo: hello-world

### hello-world/HelloWorld.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'HelloWorld.svelte', path: './src/demos/hello-world/HelloWorld.svelte' },
    { label: 'routes.ts', path: './src/demos/hello-world/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.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>
```

### hello-world/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'),
};
```

## Demo: hydration

### hydration/Hydration.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import HydrationTarget from './HydrationTarget.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'Hydration.svelte', path: './src/demos/hydration/Hydration.svelte' },
    { label: 'HydrationTarget.svelte', path: './src/demos/hydration/HydrationTarget.svelte' },
    { label: 'routes.ts', path: './src/demos/hydration/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage
  title="Hydration Modes"
  description="The same component rendered four different ways. Watch each card turn green when it hydrates — click its button to confirm the 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><code>mochi:hydrate</code></h2>
      <p>
        Eager hydration — the island boots as soon as its bundle arrives, making it interactive immediately. Use this for above-the-fold UI that the user will touch right away.
      </p>
    </header>
    <HydrationTarget mochi:hydrate label="<HydrationTarget mochi:hydrate />" />
  </section>

  <section class="mode">
    <header>
      <h2><code>mochi:hydrate:visible</code></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><code>mochi:hydrate:visible={'{{ rootMargin }}'}</code></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><code>mochi:defer</code></h2>
      <p>
        Server island — the component is <em>not</em> rendered with the initial page. Instead, a placeholder ships and the browser fetches the rendered HTML from the server
        on-demand. Pair with <code>mochi:hydrate</code> to also make it interactive 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>
  .mode {
    display: flex;
    flex-direction: column;
    gap: 0.75rem;
    margin-bottom: 2.5rem;
  }

  .mode header {
    display: flex;
    flex-direction: column;
    gap: 0.35rem;
  }

  .mode h2 {
    margin: 0;
    font-size: 1.05rem;
  }

  .mode h2 code,
  .mode p code {
    font-family: var(--font-mono);
    background: var(--surface-muted);
    border: 1px solid var(--border);
    color: var(--text);
    padding: 0.1em 0.35em;
    border-radius: 4px;
    font-size: 0.85em;
    font-weight: 500;
  }

  .mode p {
    margin: 0;
    color: var(--text-muted);
    font-size: 0.95rem;
    line-height: 1.5;
  }

  .spacer {
    height: 60vh;
    display: flex;
    align-items: center;
    justify-content: center;
    border: 2px dashed var(--border);
    border-radius: var(--radius-md);
    color: var(--text-subtle);
    font-size: 0.9rem;
  }

  .spacer p {
    margin: 0;
  }

  .placeholder {
    padding: 1rem;
    border: 2px dashed var(--border-strong);
    border-radius: var(--radius-md);
    color: var(--text-subtle);
    text-align: center;
    font-size: 0.9rem;
  }
</style>
```

### hydration/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>
  .target {
    padding: 1rem 1.25rem;
    border: 2px solid var(--border);
    border-radius: var(--radius-md);
    background: var(--surface-muted);
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
    transition:
      border-color 0.12s ease,
      background 0.12s ease;
  }

  .target.hydrated {
    border-color: var(--badge-success-text);
    background: var(--badge-success-bg);
  }

  .header {
    display: flex;
    align-items: center;
    justify-content: space-between;
    gap: 1rem;
  }

  .label {
    font-family: var(--font-mono);
    font-weight: 600;
    font-size: 1.05rem;
    color: var(--text);
  }

  .meta {
    font-size: 0.95rem;
    color: var(--text-muted);
  }

  code {
    background: var(--surface-muted);
    border: 1px solid var(--border);
    color: var(--text);
    font-family: var(--font-mono);
    padding: 0.1em 0.35em;
    border-radius: 4px;
    font-size: 0.9em;
  }

  button {
    align-self: flex-start;
    font: inherit;
    font-size: 1rem;
    padding: 0.5rem 1rem;
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    background: var(--surface);
    color: var(--text);
    cursor: pointer;
    transition:
      background 0.12s ease,
      border-color 0.12s ease,
      color 0.12s ease;
  }

  button:hover {
    background: var(--accent-soft);
    border-color: var(--accent);
    color: var(--accent-soft-text);
  }

  button:focus-visible {
    box-shadow: var(--focus-ring);
    outline: none;
  }

  .note {
    margin: 0;
    font-size: 0.9rem;
    color: var(--badge-warning-text);
  }
</style>
```

### hydration/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'),
};
```

## Demo: island-props

### island-props/ClientRenderedChild.svelte
```svelte
<script lang="ts">
  import { isBrowser } from 'mochi-framework';
  import Badge from '../../components/Badge.svelte';

  let {
    user,
    visitedAt,
    tags,
    scores,
  }: {
    user: { name: string; id: number };
    visitedAt: Date;
    tags: Set<string>;
    scores: Map<string, number>;
  } = $props();

  function describe(value: unknown): string {
    return Object.prototype.toString.call(value).slice(8, -1);
  }

  // svelte-ignore state_referenced_locally
  const rows = [
    { label: 'user', value: user, display: () => `{ name: "${user.name}", id: ${user.id} }` },
    { label: 'visitedAt', value: visitedAt, display: () => visitedAt.toISOString() },
    { label: 'tags', value: tags, display: () => `Set(${tags.size}) { ${[...tags].join(', ')} }` },
    {
      label: 'scores',
      value: scores,
      display: () => `Map(${scores.size}) { ${[...scores].map(([k, v]) => `${k} => ${v}`).join(', ')} }`,
    },
  ];
</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>Runtime type</th>
      </tr>
    </thead>
    <tbody>
      {#each rows as row (row.label)}
        <tr>
          <td class="label"><code>{row.label}</code></td>
          <td class="value"><code>{row.display()}</code></td>
          <td class="type"><code>{describe(row.value)}</code></td>
        </tr>
      {/each}
    </tbody>
  </table>
</div>

<style>
  .target {
    padding: 1rem 1.25rem;
    border: 2px solid var(--border);
    border-radius: var(--radius-md);
    background: var(--surface-muted);
    display: flex;
    flex-direction: column;
    gap: 0.85rem;
    transition:
      border-color 0.12s ease,
      background 0.12s ease;
  }

  .target.hydrated {
    border-color: var(--badge-success-text);
    background: var(--badge-success-bg);
  }

  .header {
    display: flex;
    align-items: center;
    justify-content: space-between;
    gap: 1rem;
  }

  .title {
    font-family: var(--font-mono);
    font-weight: 600;
    font-size: 1rem;
    color: var(--text);
  }

  table {
    width: 100%;
    border-collapse: collapse;
    font-size: 0.9rem;
  }

  th {
    text-align: left;
    padding: 0.4rem 0.55rem;
    border-bottom: 2px solid var(--border-strong);
    color: var(--text-muted);
    font-weight: 600;
    font-size: 0.72rem;
    text-transform: uppercase;
    letter-spacing: 0.06em;
  }

  td {
    padding: 0.4rem 0.55rem;
    border-bottom: 1px solid var(--border);
    vertical-align: middle;
  }

  tbody tr:last-child td {
    border-bottom: 0;
  }

  .label code {
    font-weight: 600;
    color: var(--text);
  }

  .value code,
  .type code {
    background: var(--surface);
    border: 1px solid var(--border);
    padding: 0.12rem 0.4rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
    color: var(--text);
    word-break: break-all;
  }

  .type code {
    color: var(--text-muted);
  }
</style>
```

### island-props/ServerRenderedParent.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import ClientRenderedChild from './ClientRenderedChild.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    {
      label: 'ServerRenderedParent.svelte',
      path: './src/demos/island-props/ServerRenderedParent.svelte',
    },
    {
      label: 'ClientRenderedChild.svelte',
      path: './src/demos/island-props/ClientRenderedChild.svelte',
    },
    { label: 'routes.ts', path: './src/demos/island-props/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);

  const user = { name: 'Ada', id: 42 };
  const visitedAt = new Date();
  const tags = new Set(['svelte', 'bun', 'islands']);
  const scores = new Map<string, number>([
    ['speed', 95],
    ['dx', 88],
    ['size', 72],
  ]);
</script>

<DemoPage
  title="Island Props"
  description="The parent has no mochi:hydrate directive, so its own code never ships to the browser — only the child island does. Watch how the props (a Date, a Map, a Set) cross the SSR → client boundary intact."
  {sources}
>
  <section class="parent">
    <header>
      <h2>ServerRenderedParent.svelte</h2>
      <p>
        Runs only on the server. No <code>mochi:hydrate</code> directive, so this component's own code ships zero JavaScript — its output is inert HTML. It builds a props bag with mixed
        types and hands it off to the child below.
      </p>
    </header>
    <pre><code
        >{`const user = { name: 'Ada', id: 42 };
const visitedAt = new Date();
const tags = new Set(['svelte', 'bun', 'islands']);
const scores = new Map([['speed', 95], ['dx', 88], ['size', 72]]);`}</code
      ></pre>
  </section>

  <div class="arrow" aria-hidden="true">
    <span>props</span>
    <span class="line"></span>
    <span class="head">▼</span>
  </div>

  <ClientRenderedChild {user} {visitedAt} {tags} {scores} mochi:hydrate />

  <section class="explainer">
    <h3>How the props get there</h3>
    <ol>
      <li>
        At SSR time, Mochi calls <a href="https://github.com/Rich-Harris/devalue" target="_blank" rel="noreferrer"><code>devalue.stringify</code></a>
        on the props you pass to the island. Unlike <code>JSON.stringify</code>, it preserves
        <code>Date</code>, <code>Map</code>, <code>Set</code>, <code>BigInt</code>,
        <code>RegExp</code>, <code>URL</code>, typed arrays, <code>undefined</code>,
        <code>NaN</code>, and even cyclic references.
      </li>
      <li>
        The serialized string is placed on the <code>&lt;mochi-hydratable-island&gt;</code> custom element as a <code>props</code> attribute. (When two islands share the exact same
        payload, it gets hoisted into a shared <code>&lt;script type="application/json"&gt;</code> block and the attribute becomes a <code>props-ref</code> pointer instead.)
      </li>
      <li>
        In the browser, the custom element's <code>connectedCallback</code> reads that string and runs
        <code>devalue.parse</code> on it, reconstructing the rich types.
      </li>
      <li>
        The result is handed to Svelte's <code>hydrate(...)</code> as the component's props — and the child takes over.
      </li>
    </ol>
    <p class="hint">
      <strong>Try it:</strong> view source on this page (or inspect the
      <code>mochi-hydratable-island</code>
      element) and you'll see the serialized props on the
      <code>props</code> attribute. Functions, class instances, and Symbols can't be serialized — pass a plain-data representation, or compute them after hydration.
    </p>
  </section>
</DemoPage>

<style>
  .parent {
    border: 2px dashed var(--border);
    border-radius: var(--radius-md);
    padding: 1rem 1.25rem;
    background: var(--surface);
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
  }

  .parent header {
    display: flex;
    flex-direction: column;
    gap: 0.25rem;
  }

  .parent h2 {
    margin: 0;
    font-family: var(--font-mono);
    font-size: 1rem;
    font-weight: 600;
    color: var(--text);
  }

  .parent p {
    margin: 0;
    color: var(--text-muted);
    font-size: 0.95rem;
    line-height: 1.5;
  }

  .parent code {
    font-family: var(--font-mono);
    background: var(--surface-muted);
    border: 1px solid var(--border);
    color: var(--text);
    padding: 0.1em 0.35em;
    border-radius: 4px;
    font-size: 0.85em;
  }

  pre {
    margin: 0;
    padding: 0.75rem 0.85rem;
    background: var(--surface-muted);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    overflow-x: auto;
    font-size: 0.85rem;
    line-height: 1.5;
  }

  pre code {
    background: transparent;
    border: none;
    padding: 0;
    font-family: var(--font-mono);
    color: var(--text);
  }

  .arrow {
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 0.15rem;
    color: var(--text-subtle);
    font-size: 0.78rem;
    text-transform: uppercase;
    letter-spacing: 0.08em;
    margin: 0.4rem 0;
  }

  .arrow .line {
    width: 2px;
    height: 1.25rem;
    background: var(--border-strong);
  }

  .arrow .head {
    color: var(--border-strong);
    line-height: 1;
  }

  .explainer {
    margin-top: 1.5rem;
    padding: 1rem 1.25rem;
    background: var(--surface);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    color: var(--text);
  }

  .explainer h3 {
    margin: 0 0 0.6rem 0;
    font-family: var(--font-serif);
    font-size: 1.1rem;
    font-weight: 500;
  }

  .explainer ol {
    margin: 0;
    padding-left: 1.25rem;
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
    font-size: 0.95rem;
    line-height: 1.55;
    color: var(--text-muted);
  }

  .explainer code {
    font-family: var(--font-mono);
    background: var(--surface-muted);
    border: 1px solid var(--border);
    color: var(--text);
    padding: 0.1em 0.35em;
    border-radius: 4px;
    font-size: 0.85em;
  }

  .explainer a {
    color: var(--accent);
  }

  .hint {
    margin: 0.85rem 0 0 0;
    padding: 0.75rem 0.85rem;
    background: var(--surface-muted);
    border-left: 3px solid var(--accent);
    border-radius: var(--radius-sm);
    font-size: 0.92rem;
    line-height: 1.55;
    color: var(--text-muted);
  }

  .hint strong {
    color: var(--text);
  }
</style>
```

### island-props/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'),
};
```

## Demo: lazy

### lazy/Lazy.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import LazyDemo from './LazyDemo.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'Lazy.svelte', path: './src/demos/lazy/Lazy.svelte' },
    { label: 'LazyDemo.svelte', path: './src/demos/lazy/LazyDemo.svelte' },
    { label: 'routes.ts', path: './src/demos/lazy/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage title="Lazy Islands" description="Six identical islands that hydrate (and fetch their CSS) only when they scroll into view." {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>
  .stack {
    display: flex;
    flex-direction: column;
    gap: 1.5rem;
  }

  .item h3 {
    font-size: 0.95rem;
    font-weight: 600;
    color: var(--text-muted);
    margin-bottom: 0.5rem;
  }
</style>
```

### lazy/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>
  .lazy-demo {
    display: flex;
    align-items: center;
    justify-content: space-between;
    padding: 0.75rem 1rem;
    background: var(--surface-muted);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
  }

  .index {
    font-size: 0.9rem;
    font-weight: 600;
    color: var(--text-muted);
    font-family: var(--font-mono);
  }

  .status {
    font-size: 0.75rem;
    font-weight: 700;
    padding: 0.15rem 0.5rem;
    border-radius: 999px;
    text-transform: uppercase;
    letter-spacing: 0.04em;
  }

  .status.waiting {
    background: var(--badge-warning-bg);
    color: var(--badge-warning-text);
  }

  .status.hydrated {
    background: var(--badge-success-bg);
    color: var(--badge-success-text);
  }
</style>
```

### lazy/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'),
};
```

## Demo: login

### login/EnhancedLoginForm.svelte
```svelte
<script lang="ts">
  import { enhance, isServer, getRequestContext } from 'mochi-framework';
  import type { MochiEnhanceOptions, MochiSubmitFunction } from 'mochi-framework';

  let { initialUser, isHydratable } = $props<{ initialUser: string | null; isHydratable?: boolean }>();

  // 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.
  // svelte-ignore state_referenced_locally
  const _form = !isHydratable && 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>.{isHydratable ? ' No page reloads happened on the way here.' : ''}</p>
    <!-- The default fallback handles redirect by calling window.location.assign,
         which works fine for logout. No callback needed. -->
    <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>
  .signed-in {
    display: flex;
    flex-direction: column;
    gap: 0.75rem;
    align-items: flex-start;
  }

  .login {
    display: flex;
    flex-direction: column;
    gap: 0.75rem;
  }

  .login label {
    display: flex;
    flex-direction: column;
    gap: 0.25rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  .login input {
    padding: 0.5rem 0.7rem;
    background: var(--surface);
    color: var(--text);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    font-family: inherit;
    font-size: 0.95rem;
  }

  .login input:disabled {
    opacity: 0.5;
    cursor: not-allowed;
    background: var(--surface-muted);
  }

  .login input:focus-visible {
    outline: none;
    border-color: var(--accent);
    box-shadow: var(--focus-ring);
  }

  .login button {
    align-self: flex-start;
    padding: 0.5rem 1rem;
    background: var(--accent);
    color: var(--accent-text);
    border: 1px solid var(--accent);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 0.95rem;
    font-weight: 600;
    cursor: pointer;
  }

  .login button:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }

  .login button:hover:not(:disabled) {
    background: var(--accent-hover);
    border-color: var(--accent-hover);
  }

  .submit-row {
    display: flex;
    align-items: center;
    gap: 0.75rem;
  }

  .signed-in button {
    align-self: flex-start;
    padding: 0.5rem 1rem;
    background: var(--surface-muted);
    color: var(--badge-danger-text);
    border: 1px solid var(--badge-danger-bg);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 0.95rem;
    font-weight: 600;
    cursor: pointer;
  }

  .signed-in button:hover {
    background: var(--badge-danger-bg);
  }

  .error {
    margin: 0;
    font-size: 0.9rem;
    color: var(--badge-danger-text);
  }

  .hint {
    font-size: 0.8rem;
    color: var(--text-subtle);
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }
</style>
```

### login/Login.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import EnhancedLoginForm from './EnhancedLoginForm.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'Login.svelte', path: './src/demos/login/Login.svelte' },
    { label: 'EnhancedLoginForm.svelte', path: './src/demos/login/EnhancedLoginForm.svelte' },
    { label: 'session.ts', path: './src/demos/login/session.ts' },
    { label: 'routes.ts', path: './src/demos/login/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);

  let { currentUser } = $props<{ currentUser: string | null }>();
</script>

<DemoPage
  title="Forms"
  description="Server-side action handlers behind a normal <form>. Shown plain (full HTML POST + page re-render) and with the enhance attachment (fetch + JSON, no reload). Sign in with hunter2 / any username."
  {sources}
>
  <p>
    The same login form, rendered twice. With <code>{'{@attach enhance(...)}'}</code> the submission goes over <code>fetch</code> and the UI updates in place. Without it, the browser
    submits natively and Mochi re-renders the page.
  </p>
  <h3>With <code>{'{@attach enhance(...)}'}</code></h3>
  <EnhancedLoginForm initialUser={currentUser} mochi:hydrate />
  <h3>Plain HTML</h3>
  <EnhancedLoginForm initialUser={currentUser} />
</DemoPage>

<style>
  h3 {
    margin: 1.5rem 0 0.25rem;
    font-size: 0.95rem;
    font-weight: 600;
    color: var(--text-muted);
  }

  p {
    margin: 0 0 0.5rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }
</style>
```

### login/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');
      },
    },
  }),
};
```

### login/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;
}
```

## Demo: nested-components

### nested-components/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>
  .level {
    padding: 0.65rem 0.85rem;
    border: 2px solid var(--border);
    border-radius: var(--radius-md);
    background: var(--surface-muted);
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
    transition:
      border-color 0.12s ease,
      background 0.12s ease;
  }

  .level.hydrated {
    border-color: var(--badge-success-text);
    background: var(--badge-success-bg);
  }

  .header {
    display: flex;
    align-items: center;
    justify-content: space-between;
    gap: 0.75rem;
  }

  .name {
    font-family: var(--font-mono);
    font-weight: 600;
    font-size: 0.9rem;
    color: var(--text);
  }

  button {
    align-self: flex-start;
    font: inherit;
    font-size: 0.9rem;
    padding: 0.35rem 0.75rem;
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    background: var(--surface);
    color: var(--text);
    cursor: pointer;
  }

  button:hover {
    background: var(--accent-soft);
    border-color: var(--accent);
    color: var(--accent-soft-text);
  }
</style>
```

### nested-components/NestedComponents.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import Level from './Level.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'NestedComponents.svelte', path: './src/demos/nested-components/NestedComponents.svelte' },
    { label: 'Level.svelte', path: './src/demos/nested-components/Level.svelte' },
    { label: 'routes.ts', path: './src/demos/nested-components/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage
  title="Nested Components"
  description="A single Level.svelte renders itself recursively five deep — the next child held in $state, dispatched as <Next />. Hydrating just the root carries the entire subtree across; every button at every depth works."
  {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.
        Every button at every depth is interactive.
      </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 — same five interactive levels, just delivered later.
      </p>
    </header>
    <Level mochi:defer mochi:hydrate>
      <div class="placeholder">Loading nested tree from server<span class="dots"></span></div>
    </Level>
  </section>
</DemoPage>

<style>
  .mode {
    display: flex;
    flex-direction: column;
    gap: 0.75rem;
    margin-bottom: 2.5rem;
  }

  .mode header {
    display: flex;
    flex-direction: column;
    gap: 0.35rem;
  }

  .mode h2 {
    margin: 0;
    font-size: 1.05rem;
  }

  .mode h2 code,
  .mode p code {
    font-family: var(--font-mono);
    background: var(--surface-muted);
    border: 1px solid var(--border);
    color: var(--text);
    padding: 0.1em 0.35em;
    border-radius: 4px;
    font-size: 0.85em;
    font-weight: 500;
  }

  .mode p {
    margin: 0;
    color: var(--text-muted);
    font-size: 0.95rem;
    line-height: 1.5;
  }

  .placeholder {
    padding: 1rem;
    border: 2px dashed var(--border-strong);
    border-radius: var(--radius-md);
    background: var(--surface-muted);
    color: var(--text-subtle);
    font-style: italic;
    text-align: center;
  }

  .dots::after {
    content: '';
    display: inline-block;
    width: 1.5em;
    text-align: left;
    animation: dots 1.2s steps(4, end) infinite;
  }

  @keyframes dots {
    0% {
      content: '';
    }
    25% {
      content: '.';
    }
    50% {
      content: '..';
    }
    75% {
      content: '...';
    }
  }
</style>
```

### nested-components/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'),
};
```

## Demo: prop-dedup

### prop-dedup/PropDedup.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import SharedPropsCard from './SharedPropsCard.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'PropDedup.svelte', path: './src/demos/prop-dedup/PropDedup.svelte' },
    { label: 'SharedPropsCard.svelte', path: './src/demos/prop-dedup/SharedPropsCard.svelte' },
    { label: 'routes.ts', path: './src/demos/prop-dedup/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);

  // Three distinct prop payloads. Each is reused across three cards in its
  // group, so the page renders nine hydratable islands but only three unique
  // serialized payloads — Mochi hoists each into a single
  // <script type="application/json"> block and points the islands at it.
  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="Three groups of three islands each. Cards inside a group take byte-identical props, so the nine islands ship as three shared <script type='application/json'> blocks instead of nine inline payloads. View source on this page to see it."
  {sources}
>
  <p class="hint">
    Each group below renders the same component three times with the same props. View source: 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.
  </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>
  .hint {
    margin: 0 0 1.5rem;
    color: var(--text-muted);
    font-size: 0.95rem;
    line-height: 1.55;
  }

  .hint code {
    font-family: var(--font-mono);
    background: var(--surface-muted);
    border: 1px solid var(--border);
    padding: 0.05em 0.3em;
    border-radius: 4px;
    font-size: 0.85em;
  }

  .group {
    margin-bottom: 2rem;
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
  }

  .group h3 {
    margin: 0;
    font-family: var(--font-serif);
    font-size: 1.05rem;
    font-weight: 500;
    color: var(--text);
  }

  .row {
    display: grid;
    grid-template-columns: repeat(3, minmax(0, 1fr));
    gap: 0.75rem;
  }

  @media (max-width: 640px) {
    .row {
      grid-template-columns: 1fr;
    }
  }
</style>
```

### prop-dedup/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>
  .card {
    padding: 0.85rem 1rem;
    border: 2px solid var(--accent);
    border-radius: var(--radius-md);
    background: var(--bg);
    color: var(--fg);
    display: flex;
    flex-direction: column;
    gap: 0.55rem;
  }

  .label {
    font-family: var(--font-mono);
    font-weight: 600;
    font-size: 0.95rem;
  }

  ul {
    margin: 0;
    padding-left: 1.1rem;
    font-size: 0.88rem;
    line-height: 1.5;
    display: flex;
    flex-direction: column;
    gap: 0.1rem;
  }
</style>
```

### prop-dedup/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'),
};
```

## Demo: reload-form-data

### reload-form-data/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 } = $props<{ entries: GuestbookEntry[] }>();

  // 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>
  .guestbook {
    display: flex;
    flex-direction: column;
    gap: 0.9rem;
    margin-top: 0.75rem;
  }

  .empty {
    margin: 0;
    font-size: 0.85rem;
    color: var(--text-subtle);
    font-style: italic;
  }

  .entries {
    list-style: none;
    margin: 0;
    padding: 0.5rem 0.75rem;
    background: var(--surface);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    display: flex;
    flex-direction: column;
    gap: 0.35rem;
    max-height: 12rem;
    overflow-y: auto;
  }

  .entries li {
    display: flex;
    justify-content: space-between;
    gap: 1rem;
    font-size: 0.9rem;
  }

  .name {
    color: var(--text);
    font-weight: 600;
  }

  .time {
    color: var(--text-subtle);
    font-family: var(--font-mono);
    font-size: 0.8rem;
  }

  .sign {
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
  }

  .sign label {
    display: flex;
    flex-direction: column;
    gap: 0.25rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  .sign input {
    padding: 0.5rem 0.7rem;
    background: var(--surface);
    color: var(--text);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    font-family: inherit;
    font-size: 0.95rem;
  }

  .sign input:disabled {
    opacity: 0.5;
    cursor: not-allowed;
    background: var(--surface-muted);
  }

  .sign input:focus-visible {
    outline: none;
    border-color: var(--accent);
    box-shadow: var(--focus-ring);
  }

  .sign button {
    align-self: flex-start;
    padding: 0.5rem 1rem;
    background: var(--accent);
    color: var(--accent-text);
    border: 1px solid var(--accent);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 0.95rem;
    font-weight: 600;
    cursor: pointer;
  }

  .sign button:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }

  .sign button:hover:not(:disabled) {
    background: var(--accent-hover);
    border-color: var(--accent-hover);
  }

  .submit-row {
    display: flex;
    align-items: center;
    gap: 0.75rem;
  }

  .error {
    margin: 0;
    font-size: 0.9rem;
    color: var(--badge-danger-text);
  }
</style>
```

### reload-form-data/ReloadFormData.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import Guestbook from './Guestbook.svelte';
  import { loadSources } from '../../components/utils.ts';

  type GuestbookEntry = { id: string; name: string; at: number };

  const sources = await loadSources([
    { label: 'ReloadFormData.svelte', path: './src/demos/reload-form-data/ReloadFormData.svelte' },
    { label: 'Guestbook.svelte', path: './src/demos/reload-form-data/Guestbook.svelte' },
    { label: 'routes.ts', path: './src/demos/reload-form-data/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);

  let { guestbook } = $props<{ guestbook: GuestbookEntry[] }>();
</script>

<DemoPage
  title="Reloading associated form data"
  description="A successful submit appends to a server-side list. The hydrated version refetches /api/guestbook to update in place; the plain version relies on the post-POST page re-render with fresh serverProps."
  {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>
  h3 {
    margin: 1.5rem 0 0.25rem;
    font-size: 0.95rem;
    font-weight: 600;
    color: var(--text-muted);
  }

  p {
    margin: 0 0 0.5rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }
</style>
```

### reload-form-data/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[] = [];

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', {
    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() });
        return success({});
      },
    },
  }),
};
```

## Demo: server-island

### server-island/ServerGreeting.svelte
```svelte
<script>
  import { cookies, isServer } from 'mochi-framework';
  import { delay } from '../../components/utils.ts';

  let { name = 'World', islandId, bigProp = '' } = $props();

  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">island-id: {islandId}</p>
  <p class="timestamp">bigProp: {bigProp}</p>
  <p class="timestamp">bigProp length: {bigProp.length}</p>
</div>

<style>
  .server-greeting {
    padding: 1rem 1.1rem;
    border: 2px dashed var(--badge-info-text);
    border-radius: var(--radius-md);
    background: var(--badge-info-bg);
    color: var(--text);
    overflow-wrap: anywhere;
    word-break: break-word;
  }

  .server-greeting p {
    margin: 0 0 0.35rem;
  }

  .server-greeting p:last-child {
    margin-bottom: 0;
  }

  .timestamp {
    font-size: 0.92em;
    color: var(--text-muted);
    font-family: var(--font-mono);
    font-variant-numeric: tabular-nums;
  }
</style>
```

### server-island/ServerIsland.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import ServerGreeting from './ServerGreeting.svelte';
  import ServerNoProps from './ServerNoProps.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'ServerIsland.svelte', path: './src/demos/server-island/ServerIsland.svelte' },
    { label: 'ServerGreeting.svelte', path: './src/demos/server-island/ServerGreeting.svelte' },
    { label: 'ServerNoProps.svelte', path: './src/demos/server-island/ServerNoProps.svelte' },
    { label: 'routes.ts', path: './src/demos/server-island/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage
  title="Server Island"
  description="These components render on-demand after the page is delivered. They read cookies and show personalized content. Set your name in the Cookies demo to see it reflected here."
  {sources}
>
  <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>
  .spacer {
    height: 0.75rem;
  }

  .island-loading {
    padding: 1rem;
    border: 2px dashed var(--border-strong);
    border-radius: var(--radius-md);
    background: var(--surface-muted);
    color: var(--text-subtle);
    font-style: italic;
    text-align: center;
  }

  .dots::after {
    content: '';
    display: inline-block;
    width: 1.5em;
    text-align: left;
    animation: dots 1.2s steps(4, end) infinite;
  }

  @keyframes dots {
    0% {
      content: '';
    }
    25% {
      content: '.';
    }
    50% {
      content: '..';
    }
    75% {
      content: '...';
    }
  }
</style>
```

### server-island/ServerNoProps.svelte
```svelte
<script>
  import { isServer } from 'mochi-framework';
  import { delay } from '../../components/utils.ts';

  let { islandId } = $props();

  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">Island ID: <strong>{islandId}</strong></p>
</div>

<style>
  .server-no-props {
    padding: 1rem 1.1rem;
    border: 2px dashed var(--badge-warning-text);
    border-radius: var(--radius-md);
    background: var(--badge-warning-bg);
    color: var(--text);
    margin-top: 0.75rem;
  }

  .server-no-props p {
    margin: 0 0 0.35rem;
  }

  .server-no-props p:last-child {
    margin-bottom: 0;
  }

  .number,
  .island-id {
    font-size: 0.92em;
    color: var(--text-muted);
    font-family: var(--font-mono);
    font-variant-numeric: tabular-nums;
  }
</style>
```

### server-island/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'),
};
```

## Demo: server-props

### server-props/ServerProps.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'ServerProps.svelte', path: './src/demos/server-props/ServerProps.svelte' },
    { label: 'routes.ts', path: './src/demos/server-props/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);

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

<DemoPage
  title="Server Props"
  description="Pass data from the route definition into a Svelte page 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>
  .card {
    background: var(--surface);
    color: var(--text);
    border-radius: var(--radius-lg);
    border: 1px solid var(--border);
    padding: 1.5rem;
    max-width: 560px;
    margin: 0 auto;
  }

  dl {
    display: grid;
    grid-template-columns: max-content 1fr;
    column-gap: 1.25rem;
    row-gap: 0.75rem;
    margin: 0 0 1rem 0;
  }

  dt {
    font-weight: 600;
    color: var(--text-muted);
  }

  dd {
    margin: 0;
    word-break: break-all;
    color: var(--text);
  }

  code {
    font-family: var(--font-mono);
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.2rem 0.45rem;
    border-radius: var(--radius-sm);
    font-size: 0.9em;
  }

  .hint {
    color: var(--text-subtle);
    font-size: 0.9rem;
    margin: 0;
  }
</style>
```

### server-props/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),
    }),
  }),
};
```

## Demo: shared-state

### shared-state/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>
  .counter-btn {
    display: flex;
    align-items: center;
    justify-content: center;
    gap: 0.75rem;
    width: 100%;
    padding: 0.75rem 1.25rem;
    background: var(--surface-muted);
    color: var(--text);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 1.1rem;
    font-weight: 500;
    cursor: pointer;
    transition:
      background 0.12s ease,
      border-color 0.12s ease,
      color 0.12s ease;
  }

  .counter-btn:hover {
    background: var(--accent-soft);
    border-color: var(--accent);
    color: var(--accent-soft-text);
  }

  .counter-btn:active {
    transform: translateY(1px);
  }

  .counter-btn:focus-visible {
    outline: none;
    box-shadow: var(--focus-ring);
  }

  .counter-label {
    color: var(--text-muted);
    font-size: 1rem;
  }

  .counter-btn:hover .counter-label {
    color: inherit;
  }

  .counter-value {
    background: var(--accent-soft);
    color: var(--accent-soft-text);
    border-radius: 999px;
    padding: 0.1rem 0.7rem;
    font-size: 1.1rem;
    font-weight: 700;
    min-width: 1.8rem;
    text-align: center;
    font-variant-numeric: tabular-nums;
  }

  .counter-btn:hover .counter-value {
    background: var(--surface);
  }
</style>
```

### shared-state/SharedState.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import CounterButton from './CounterButton.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'SharedState.svelte', path: './src/demos/shared-state/SharedState.svelte' },
    { label: 'CounterButton.svelte', path: './src/demos/shared-state/CounterButton.svelte' },
    { label: 'routes.ts', path: './src/demos/shared-state/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage title="Shared State" description="Two separately-hydrated islands sharing the same reactive $state. Click either button — the count stays in sync across both." {sources}>
  <div class="row">
    <CounterButton mochi:hydrate />
    <CounterButton mochi:hydrate />
  </div>
</DemoPage>

<style>
  .row {
    display: flex;
    gap: 1rem;
    flex-wrap: wrap;
  }
</style>
```

### shared-state/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'),
};
```

## Demo: streams

### streams/RealtimeClocks.svelte
```svelte
<script lang="ts">
  let { islandId } = $props();

  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>
  {#if islandId}
    <div class="island-id">island-id: {islandId}</div>
  {/if}
</div>

<style>
  .clocks {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 0.75rem;
  }

  @media (max-width: 480px) {
    .clocks {
      grid-template-columns: 1fr;
    }
  }

  .clock {
    background: var(--surface-muted);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    padding: 1rem 1.1rem;
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 0.4rem;
  }

  .clock-header {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    width: 100%;
    justify-content: space-between;
  }

  .protocol {
    font-size: 0.78rem;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 0.06em;
    color: var(--text-muted);
  }

  .status {
    font-size: 0.7rem;
    padding: 0.15rem 0.5rem;
    border-radius: 999px;
    background: var(--badge-danger-bg);
    color: var(--badge-danger-text);
    font-weight: 600;
    letter-spacing: 0.02em;
  }

  .status.connected {
    background: var(--badge-success-bg);
    color: var(--badge-success-text);
  }

  .time {
    font-size: 1.75rem;
    font-weight: 700;
    color: var(--text);
    font-family: var(--font-mono);
    font-variant-numeric: tabular-nums;
    letter-spacing: 0.02em;
  }

  .endpoint {
    font-size: 0.8rem;
    color: var(--text-subtle);
    font-family: var(--font-mono);
  }

  .island-id {
    grid-column: 1 / -1;
    text-align: center;
    font-size: 0.75rem;
    color: var(--text-subtle);
    font-family: var(--font-mono);
  }
</style>
```

### streams/Streams.svelte
```svelte
<script>
  import DemoPage from '../../components/DemoPage.svelte';
  import RealtimeClocks from './RealtimeClocks.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'Streams.svelte', path: './src/demos/streams/Streams.svelte' },
    { label: 'RealtimeClocks.svelte', path: './src/demos/streams/RealtimeClocks.svelte' },
    { label: 'routes.ts', path: './src/demos/streams/routes.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);
</script>

<DemoPage
  title="Real-time Streams"
  description="A WebSocket clock and a Server-Sent Events clock side by side. The component hydrates lazily — JS and CSS load only when it scrolls into view."
  {sources}
>
  <RealtimeClocks mochi:hydrate:visible={{ rootMargin: '100px' }} />
</DemoPage>
```

### streams/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));
  }),
};
```

## Demo: tailwind

### tailwind/Tailwind.svelte
```svelte
<script>
  import './app.generated.css';
  import DemoPage from '../../components/DemoPage.svelte';
  import { loadSources } from '../../components/utils.ts';

  const sources = await loadSources([
    { label: 'Tailwind.svelte', path: './src/demos/tailwind/Tailwind.svelte' },
    { label: 'app.css', path: './src/demos/tailwind/app.css' },
    { label: 'routes.ts', path: './src/demos/tailwind/routes.ts' },
    { label: 'tailwind.ts (mochi-framework/tailwind)', path: '../mochi/src/tailwind.ts' },
    { label: 'index.ts', path: './src/demoIndex.ts' },
  ]);

  const palette = [
    { name: 'emerald', bg: 'bg-emerald-500', ring: 'ring-emerald-600/20' },
    { name: 'sky', bg: 'bg-sky-500', ring: 'ring-sky-600/20' },
    { name: 'violet', bg: 'bg-violet-500', ring: 'ring-violet-600/20' },
    { name: 'rose', bg: 'bg-rose-500', ring: 'ring-rose-600/20' },
    { name: 'amber', bg: 'bg-amber-500', ring: 'ring-amber-600/20' },
    { name: 'slate', bg: 'bg-slate-500', ring: 'ring-slate-600/20' },
  ];
</script>

<DemoPage
  title="Tailwind"
  description="Tailwind v4 driven directly by its Node API — no PostCSS, no Vite. The integration runs at startup, scans the demo's sources for class candidates, writes a generated CSS file, and lets Mochi's side-effect CSS bundler link it scoped to this page."
  {sources}
>
  <div class="stack">
    <!-- Hero card -->
    <div
      class="overflow-hidden rounded-2xl border border-slate-200/80 bg-gradient-to-br from-white to-slate-50 shadow-sm dark:border-slate-800 dark:from-slate-900 dark:to-slate-950"
    >
      <div class="p-7 sm:p-8">
        <div class="flex items-start justify-between gap-4">
          <div>
            <h3 class="text-xl font-semibold tracking-tight text-slate-900 dark:text-slate-100">Tailwind v4, no PostCSS</h3>
            <p class="mt-2 max-w-prose text-sm leading-relaxed text-slate-600 dark:text-slate-400">
              Compiled by
              <code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-xs text-slate-800 dark:bg-slate-800 dark:text-slate-200">@tailwindcss/node</code>
              at server startup, scanned by
              <code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-xs text-slate-800 dark:bg-slate-800 dark:text-slate-200">@tailwindcss/oxide</code>, served as a hashed
              stylesheet linked only on this page.
            </p>
          </div>
          <span
            class="inline-flex shrink-0 items-center rounded-full bg-emerald-50 px-2.5 py-1 text-xs font-medium text-emerald-700 ring-1 ring-emerald-600/20 dark:bg-emerald-500/10 dark:text-emerald-300 dark:ring-emerald-400/30"
          >
            v4.2
          </span>
        </div>

        <div class="mt-7 flex flex-wrap items-center gap-3">
          <button
            class="inline-flex items-center gap-1.5 rounded-lg bg-emerald-600 px-4 py-2 text-sm font-medium text-white shadow-sm shadow-emerald-600/25 transition hover:bg-emerald-700 hover:shadow-emerald-600/40 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-emerald-600"
          >
            Primary action
          </button>
          <button
            class="inline-flex items-center gap-1.5 rounded-lg border border-slate-300 bg-white px-4 py-2 text-sm font-medium text-slate-700 transition hover:bg-slate-50 dark:border-slate-700 dark:bg-slate-900 dark:text-slate-200 dark:hover:bg-slate-800"
          >
            Secondary
          </button>
          <button
            class="inline-flex items-center gap-1.5 rounded-lg px-4 py-2 text-sm font-medium text-slate-600 transition hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-800"
          >
            Ghost
          </button>
        </div>
      </div>

      <div class="border-t border-slate-200/80 bg-slate-50/60 px-7 py-4 sm:px-8 dark:border-slate-800 dark:bg-slate-950/60">
        <div class="flex items-center gap-2 text-xs text-slate-500 dark:text-slate-400">
          <span class="inline-block h-1.5 w-1.5 rounded-full bg-emerald-500 ring-2 ring-emerald-500/30"></span>
          Scoped to <code class="font-mono">/demos/tailwind</code> only
        </div>
      </div>
    </div>

    <!-- Palette swatches -->
    <div class="grid grid-cols-2 gap-3 sm:grid-cols-3 lg:grid-cols-6">
      {#each palette as swatch (swatch.name)}
        <div
          class="group flex flex-col gap-2 rounded-xl border border-slate-200 bg-white p-3 transition hover:-translate-y-0.5 hover:shadow-sm dark:border-slate-800 dark:bg-slate-900"
        >
          <span class="h-12 w-full rounded-md ring-1 {swatch.bg} {swatch.ring}"></span>
          <span class="font-mono text-xs text-slate-600 dark:text-slate-400">{swatch.name}-500</span>
        </div>
      {/each}
    </div>
  </div>
</DemoPage>

<style>
  .stack {
    display: grid;
    gap: 1.25rem;
    margin-top: 0.5rem;
  }
</style>
```

### tailwind/routes.ts
```ts
import { Mochi } from 'mochi-framework';
import type { MochiRouteValue } from 'mochi-framework';

export const routes: Record<string, MochiRouteValue> = {
  '/demos/tailwind': Mochi.page('./src/demos/tailwind/Tailwind.svelte'),
};
```