create-rivet 0.0.0-stage → 0.1.0-alpha.0

package/templates/starter-static/CLAUDE.md

@@ -0,0 +1,457 @@
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/agents.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Rivet app: instructions for AI assistants
+
+Read this before editing this project. Rivet looks like React / Solid JSX but is neither: the habits below are compile errors or silent bugs. When unsure, look the API up (MCP server or `llms.txt`, section 11) instead of guessing, and run `npm run check` after every change.
+
+## 1. What Rivet is
+
+Rivet is a compiled, resumable JSX framework. A Rust compiler turns `.tsx` into server HTML (streamed) and DOM templates. A component function runs **once, on the server**; the browser never re-runs it. It **resumes** the page from the HTML plus serialized state: only event handlers, bindings that read signals, and client effects run in the browser, and their code loads on intent / visibility / idle. State is fine-grained signals (`@rivetjs/reactivity`). Routing is file-based (`@rivetjs/router`), i18n is compile-time (`@rivetjs/i18n`), forms are progressive (`@rivetjs/forms`), UI is `@rivetjs/ui` (styled compound components) on headless `@rivetjs/cdk`.
+
+## 2. Differences from React / Solid
+
+### Mental model
+
+- No virtual DOM, no re-renders. A signal change updates only the text / attribute / row that reads it. No `useMemo`, `useCallback`, dependency arrays, or hooks rules: `signal()` / `computed()` can be created anywhere.
+- Component body = server code. `window`, `document`, `localStorage` there are a compile error (RV2001). `console.log` in the body prints in the terminal.
+- `typeof window !== "undefined"` branches in a component never run in the browser. Use a handler, `clientEffect`, `clientEvent` or `clientOnly`.
+
+### JSX
+
+- `class` (`className` also works; never both on one element). `for` (`htmlFor` also works). Some attrs are camelCase in types: `autoComplete`, `autoFocus`, `tabIndex`.
+- Class object / array: `class={{ active: on() }}`, `class={["a", on() && "b"]}`; toggle one: `class:active={on()}`.
+- `style` must be an object or `style:prop`. Style strings are compile errors (RV5003).
+- Events: `on` + PascalCase from lib.dom (`onClick`, `onInput`, `onKeyDown`, `onFocusOut`). Lowercase `onclick` = error (RV1012). Text inputs: `onInput` (or `model:value`), not React's `onChange`.
+- `window:onResize={fn}` / `document:onKeyDown={fn}` listen globally; `on:my-event={fn}` for custom events; `onClickCapture` for capture phase.
+- Not supported: `dangerouslySetInnerHTML`, `innerHTML`, `srcdoc` (RV1101), `<script>` / `<style>` in JSX (RV1007), children spread `{...items}` (RV1002), `javascript:` / `data:` URLs.
+- Handler value must be a function that does not read state when bound (RV1016):
+
+```tsx
+// Avoid: evaluated once at render
+<button onClick={mode() === "a" ? onA : onB}>Go</button>
+// Prefer
+<button onClick={(e) => (mode() === "a" ? onA(e) : onB(e))}>Go</button>
+```
+
+- Two-way form binding: `<input model:value={name} />`, `<input type="checkbox" model:checked={agree} />`, also `<select model:value={choice}>`. The value must be a signal name/property.
+- No JSX inside handlers, effects or computeds (RV2006): render JSX in the component, switch it with a signal.
+- No `this` in handlers (RV2007): use `event.currentTarget`.
+
+### Signals (`@rivetjs/reactivity`)
+
+```tsx
+import { signal, computed, effect, batch, untrack, onCleanup } from "@rivetjs/reactivity";
+
+const count = signal(0); // read: count()
+count.set(5); // write
+count.update((n) => n + 1); // derive from current
+const double = computed(() => count() * 2); // no dependency list; read: double()
+untrack(count); // read without subscribing (there is no .peek())
+```
+
+- Avoid `count(5)` (not a setter) and `count.value`.
+- `computed` / `effect` must be synchronous (an async fn is a type error).
+- Stores: `createStore` from `@rivetjs/reactivity/store`.
+
+### Effects, lifecycle, cleanup
+
+- In components use `clientEffect` from `@rivetjs/runtime/dom`: recorded on the server, runs only in the browser, re-runs when its signals change. Return a function for cleanup.
+- `effect` from `@rivetjs/reactivity` runs immediately where called — in a component that means on the server only. Use it in plain TS / tests.
+- `onCleanup(fn)` (reactivity) registers cleanup for the current effect / root; throws outside one.
+- Options: `clientEffect(fn, { when: "idle" | "load" | "visible" | "interaction" | "media:(…)" })`. Default `visible` if it uses a ref, else `idle`.
+- Async `clientEffect`: only signals read before the first `await` are tracked; returned cleanup works only from non-async effects.
+
+```tsx
+// Avoid (server-only run, document undefined → RV2001)
+document.title = `${unread()} unread`;
+// Prefer
+clientEffect(() => {
+  document.title = `${unread()} unread`;
+});
+```
+
+- Browser listeners: `clientEvent(window, "resize", () => width.set(innerWidth))`.
+- Browser-only libraries (maps, charts): `const MapView = clientOnly(() => import("../components/Map.tsx"), undefined, { fallback: () => <p>Loading…</p> });` — importer and selector must be inline.
+
+### Props are live (Solid-style)
+
+- `<Badge count={count()} />` passes a getter; the child sees updates when it reads `props.count` where it is shown.
+- Destructuring reads once: on a resumed page a destructuring child is re-created on the first change (local signals reset). Read `props.x`.
+- Object spread `{ ...props }` / `Object.assign` reads every getter once; JSX spreads `<button {...props} />` stay live.
+- Defaults / forwarding: `mergeProps`, `splitProps` from `@rivetjs/runtime/props`.
+- `count={count}` passes the signal itself (child calls `props.count()` / writes it). Use for two-way props.
+- Type `children` (and other JSX-holding props) as `Content`: `import type { Content } from "@rivetjs/runtime/jsx-runtime"`; `props: { title: string; children?: Content }`.
+- A prop holding JSX (`icon={<Star />}`) creates new nodes on every read: read once, or pass a render function.
+
+```tsx
+// Avoid
+export function Badge({ count }: { count: number }) {
+  return <b>{count}</b>;
+}
+// Prefer
+export function Badge(props: { count: number }) {
+  return <b>{props.count}</b>;
+}
+```
+
+### Control flow, lists (all from `@rivetjs/runtime/dom`, named imports only — no `rt.For`)
+
+```tsx
+import { For, Show, Switch, Match } from "@rivetjs/runtime/dom";
+
+<For each={todos} by={(t) => t.id}>{(todo, index) => <li>{index() + 1}. {todo().text}</li>}</For>
+<Show when={open()} fallback={<p>Closed</p>}>…</Show>
+<Switch fallback={<p>None</p>}><Match when={a()}>A</Match><Match when={b()}>B</Match></Switch>
+```
+
+- `For`: `by` key is required; `item` and `index` are **accessors** (`todo()`, `index()`). Use for lists that change. `.map()` is fine for fixed data (loader data, constants).
+- Conditionals: `cond() && <p />`, ternary, or `Show`. Always read the signal (`cond()`, not `cond`).
+- Other helpers: `Async`, `Suspense`, `ErrorBoundary`, `Dynamic`, `Portal`, `Provider`, `lazyComponent`, `clientOnly`.
+- A function child `{() => …}` re-runs when the signals its body reads change.
+
+### Refs
+
+```tsx
+import { ref } from "@rivetjs/runtime/dom";
+const input = ref<HTMLInputElement>();
+<input ref={input} />; // input() → element | undefined (signal-backed)
+let el!: HTMLCanvasElement;
+<canvas ref={(e) => (el = e)} />; // callback must assign a local (RV2002)
+```
+
+### Context
+
+```tsx
+// theme.ts
+import { createContext, signal, type Signal } from "@rivetjs/reactivity";
+export const ThemeContext = createContext<Signal<"light" | "dark">>(signal("light"));
+// provider
+import { Provider } from "@rivetjs/runtime/dom";
+<Provider token={ThemeContext} value={theme}>
+  …
+</Provider>;
+// reader: at the top of the component, never in a handler or after await
+const theme = useContext(ThemeContext); // import { useContext } from "@rivetjs/reactivity"
+```
+
+- The provided value is read once: provide a signal for changing values. It must be serializable (data / signals, no service objects).
+
+## 3. Resumability rules
+
+Everything a handler, effect, computed or binding uses from its component (its **captures**) is written into the HTML. It must be serializable.
+
+- OK: primitives, plain objects/arrays, `Date`, `URL`, `URLSearchParams`, `Map`, `Set`, `RegExp`, typed arrays, `ArrayBuffer`, `DataView`, `Error`, signals, `computed`, and functions Rivet compiled: inline arrows, local `const` functions, inline callback props, functions in object literals, returned functions, inline functions written into a value a handler uses (`api.inc = () => …`, `signal(() => …)`, `[() => …]`), local functions stored by name into such a value (`api.open = open`, `list.push(open)`), module-level or imported functions used by name inside a component (called by a handler, passed as a prop, kept in a local const, put in an object / array / call argument).
+- Not OK: class instances (`new Intl.NumberFormat()`, `new Api()` → RV2003; a data class declared in the component module resumes — no `#private` field, no base other than a data class of that module, no decorator, no `window` / `document` read while constructing, else RV2102; `reconstruct(() => new Api(…))` from `@rivetjs/runtime/dom` builds it in the browser on first read (no value in the page); a resource holder resumes with `[serialize]()` + `static [revive](data)`, a package class with `registerClass(Cls, { id, serialize, revive })` from `@rivetjs/runtime/resume-format`), `Promise`, `WeakMap`, `Symbol`, `Error`, `.bind(...)` written inside an object literal (RV2014; inline in a prop / handler or a local `const inc = add.bind(null, 2)` of a compiled function used by name is OK; `.bind(ctx)` of a `this` function stays RV2007), methods / getters, functions using `this`, functions created at runtime by libraries (`memoize(fn)`), module-level / imported functions put into objects only outside a component (module level, hooks, helpers).
+
+```tsx
+// Avoid: captures a class instance
+const fmt = new Intl.NumberFormat("en", { style: "currency", currency: "EUR" });
+<button onClick={() => alert(fmt.format(n()))}>Pay</button>
+// Prefer: create it where it runs
+<button onClick={() => alert(new Intl.NumberFormat("en", { style: "currency", currency: "EUR" }).format(n()))}>Pay</button>
+```
+
+- Wrap foreign functions in an arrow: `onPress={() => analytics.track("save")}`.
+- Imports are not captures: import modules at the top, create objects inside the handler, keep browser objects (EventSource, chart instances) inside `clientEffect`.
+- Render props and item renderers take functions: `({ close }) => …` on Dialog / Modal / Popover, `{(item) => …}` on ListBox / Select / Tabs, Tabs `panel`. Plain JSX children are fine elsewhere: a closed overlay renders nothing on the server and creates its content when it opens.
+- Render a function child as `{props.children}` directly; a copy in a local (`const c = props.children`) is not tracked on resumed pages.
+- `For each={xs}` (accessor) keeps resumed rows and branches better than `xs().map(...)`.
+- `.ts` files are not server-rewritten: import `@rivetjs/runtime/dom` (`For`, `Show`, `clientEffect`, …) only from `.tsx` files, else the DOM runtime is bundled into SSR.
+- Components outside `src/routes` need no registration: `rivetRouter` resumes every `.tsx` / `.jsx` file a route imports.
+- Errors: build/prerender prints `Cannot resume <file>#<Component>$<hash>: function is not serializable`. The dev server names the capture (``capture `<name>` ``); dev builds (`NODE_ENV=development vite build`) give its position (`capture #<i>`) and the value path. Fixes: build the object inside the component; a library object holding functions → `reconstruct(() => createChart(…))` (`@rivetjs/runtime/dom`; module level = one server instance per process, no request state in it); a class instance → `reconstruct(() => new X(…))`, `[serialize]()` + `static [revive](data)`, or for a package class `registerClass(X, { id, serialize, revive })` (`@rivetjs/runtime/resume-format`).
+- Playwright tests: the first trusted mouse click per document flushes DOM updates one task later. After a page's first `page.click`, wait (`expect(...).toHaveText` retries / `waitForFunction`), don't read the DOM synchronously.
+
+## 4. File routes
+
+```
+src/
+  document.ts            HTML shell (DocumentShell, headTags)
+  styles.css             listed in rivetRouter({ styles })
+  routes/
+    _layout.tsx          wraps its folder and below
+    index.tsx            /
+    about.tsx            /about
+    blog/[slug].tsx      /blog/:slug        → params.slug
+    docs/[[lang]]/x.tsx  optional param
+    files/[...path].tsx  rest param
+    (marketing)/p.tsx    /p (group: no segment, shares a layout)
+    api/time.ts          endpoint (exports onGet/onPost…, returns Response)
+    _404.tsx  _error.tsx
+```
+
+- Files/folders starting with `_` (except `_layout`, `_404`, `_error`), `.`, `*.test.*`, `*.d.ts` are ignored. `*.server.ts` = server-only module (cannot be imported by browser code, RV3008).
+- `.rivet/` is generated (route types `routes.d.ts`, editor manifest): never edit; `rivet sync` regenerates it.
+
+### Page module exports
+
+```tsx
+import { redirect, notFound, type PageProps, type RequestEvent } from "@rivetjs/router";
+
+export const serverLoad = async ({ params }: RequestEvent<"blog/[slug]">) => {
+  const post = await findPost(params.slug);
+  if (!post) throw notFound();
+  return { post };
+};
+
+export const serverActions = {
+  // <form method="post" action="?/comment">
+  comment: async ({ request }: RequestEvent<"blog/[slug]">) => {
+    const text = String((await request.formData()).get("text") ?? "");
+    await saveComment(text);
+    return redirect("/blog", 303);
+  },
+};
+
+export const head = { title: "Post" }; // or ({ data, params, url }) => Head
+
+export default function Post({ data, params }: PageProps<"blog/[slug]">) {
+  return <h1>{data.post.title}</h1>;
+}
+```
+
+- Server exports: `serverLoad`, `serverActions`, `serverGuard` (throw/return `redirect()`, `deny()`, `notFound()`, `error()`), `serverHeaders`, `serverEntries` (prerender params), `prerender`, `onRequest` / `onGet` / `onPost` …. The compiler strips them (and code only they use) from the browser build.
+- `event`: `request`, `url`, `params`, `locals`, `signal`, `cookies`, `setHeader`.
+- Page props: `{ data, params, url }` — plain values. Layout props (`LayoutProps`): `data()`, `params()`, `url()` are **accessors**, plus `children`.
+
+```tsx
+// Avoid in a layout
+<header>{data.user}</header>;
+// Prefer
+export default function Layout({ data, children }: LayoutProps<typeof serverLoad>) {
+  return (
+    <>
+      <header>{data().user}</header>
+      {children}
+    </>
+  );
+}
+```
+
+### Live pages
+
+- `export const live = true` + `LivePageProps<typeof serverLoad>`: `data` becomes an accessor (`data().customers`). Same-URL revalidation (a `@rivetjs/forms` submit, `invalidate()`, search-param change) updates `data` in place: the page is not re-rendered, signals (an open drawer, typed input, focus) survive. Use it for forms in drawers / dialogs.
+- Don't copy `data()` into a signal (it never updates). Render lists with `<For each={data().items} by={…}>`.
+
+### Links and navigation
+
+- Plain `<a href="/about">` works (client navigation). Typed: `import { Link } from "@rivetjs/router/link"`; `<Link to="/items/42">`.
+- `import { navigate, invalidate, useSearchParams, setSearchParams, beforeLeave, actionResult } from "@rivetjs/router/client"`.
+- Under a base path, plain anchors need `withBase("/x")` from `@rivetjs/router`.
+- Never call `history.pushState` yourself: the router does not see it.
+
+### Modes (`vite.config.ts`)
+
+- `rivetRouter()` = `mode: "server"` (render per request; `npm run build` → `dist/server`, `npm start`).
+- `rivetRouter({ mode: "static" })` = prerender to HTML files (`prerender.js` / `prerenderBuild`). `serverLoad` runs at build time. A page with nothing to resume (no handlers, signals in markup, client effects, forms) ships zero JS and its links load documents; `clientRouter: true` keeps in-place navigation on every page.
+- `mode: "csr"` = SPA, no server code.
+
+### Forms (`@rivetjs/forms`)
+
+```ts
+// src/forms/contact.ts
+import { defineForm } from "@rivetjs/forms";
+import { z } from "zod"; // any Standard Schema library
+export const contactForm = defineForm({ name: "contact", schema: z.object({ email: z.string().email() }), validateOn: "blur" });
+```
+
+```tsx
+// src/routes/contact.tsx
+import { action, invalid } from "@rivetjs/forms/server";
+import { actionResult } from "@rivetjs/router/client";
+import { createForm, fieldId, formId, onInput, onBlur, onSubmit, defaultValue, isInvalid, describedBy } from "@rivetjs/forms";
+import { FieldError, ErrorSummary } from "@rivetjs/forms/components";
+
+export const serverActions = {
+  contact: action(contactForm, async (value) => {
+    /* typed, valid */
+  }),
+};
+
+export default function Contact() {
+  const form = createForm(contactForm, { result: actionResult() });
+  return (
+    <form
+      id={formId(form)}
+      method="post"
+      action="?/contact"
+      onInput={(e) => onInput(contactForm, form, e)}
+      onFocusOut={(e) => onBlur(contactForm, form, e)}
+      onSubmit={(e) => onSubmit(contactForm, form, e)}
+    >
+      <label for={fieldId(form, "email")}>Email</label>
+      <input
+        id={fieldId(form, "email")}
+        name="email"
+        value={defaultValue(form, "email")}
+        aria-invalid={isInvalid(form, "email")}
+        aria-describedby={describedBy(form, "email")}
+      />
+      <FieldError of={form} name="email" />
+      <button>Send</button>
+    </form>
+  );
+}
+```
+
+- Works without JS (plain post, 400 re-render with messages). Server-side rejection: `return invalid({ email: "Taken" })`.
+- A successful submit re-renders a normal page (its signals reset: a "thanks" flag set after `await onSubmit(…)` is lost). Keep client state across a submit with `export const live = true`.
+- In an overlay: live page + `onSubmit={async (e) => (await onSubmit(def, form, e)) && open.set(false)}`.
+- Keeping native `required`? Add `onInvalidCapture={(e) => onInvalid(def, form, e)}`.
+
+## 5. i18n (`@rivetjs/i18n`)
+
+- Compile-time: `t("key")` is replaced by the string for the locale being built; no runtime catalog. One client build per locale.
+- `i18n.config.ts` (`locales`, `defaultLocale`, `catalogs: "locales/{locale}.json"`, `routing`); Vite: `plugins: [i18n(config), rivetRouter()]` — `i18n()` from `@rivetjs/i18n/vite`, **before** the router.
+- Catalogs: JSON, nested keys → dotted, values ICU MessageFormat (`"Hello, {name}!"`, plural / select).
+
+```tsx
+import { t } from "@rivetjs/i18n";
+<h1>{t("cart.title")}</h1>
+<p>{t("cart.greeting", { name: props.name })}</p>
+<p>{t("terms", { link: (c) => <a href="/terms">{c}</a> })}</p>
+```
+
+- Key = string literal; params = inline object literal. Unknown key RV4001, missing / extra param RV4002, bad args RV4003, tags in attributes RV4004.
+- Server code outside rendering (emails in actions): `t.in("de", "cart.title")`. Never `String(t(…))` on the server.
+- Generated types: `src/rivet-i18n.d.ts` (do not edit). Locale URLs: `[[lang]]` route folder.
+
+## 6. Styles
+
+- Templates use Tailwind v4: `src/styles.css` (`@import "tailwindcss"; @source "./**/*.{ts,tsx}";`), listed in `rivetRouter({ styles: ["src/styles.css"] })`, plus `tailwindcss()` Vite plugin. Write utilities in `class`.
+- Scoped CSS (experimental): ``const styles = css`.card { … }` `` at module top level, `import { css, cx } from "@rivetjs/runtime/css"`; use `class={styles.card}`, combine with `cx(styles.card, on() && styles.selected, props.class)`.
+- Dynamic values: `style={{ "--x": n(), marginTop: "1px" }}` or `style:color={c()}`; `data-*` attributes for state styling.
+
+## 7. Icons (mandatory rule)
+
+- Never hand-write SVG paths. Never use Unicode glyphs (✓ × → ★ …) as icons.
+- Use lucide through Rivet's `Icon`:
+
+```tsx
+import { Icon } from "@rivetjs/kit/icon";
+import { Check } from "lucide";
+<Icon icon={Check} size={16} class="text-success" />           // decorative (aria-hidden)
+<Icon icon={Check} title="Done" />                              // accessible name
+```
+
+- Props: `icon` (lucide data), `size` (default 24), `color`, `strokeWidth`, `absoluteStrokeWidth`, `title`, any `<svg>` attribute. Requires `lucide` + `@rivetjs/kit` dependencies (starter-ui has both).
+
+## 8. UI components
+
+- `@rivetjs/ui`: styled compound components. Import per component subpath (`@rivetjs/ui/button`, `@rivetjs/ui/select`, `@rivetjs/ui/modal`, `@rivetjs/ui/card`, …); the root barrel exists, prefer subpaths. Styles: `@import "@rivetjs/ui/styles";` after Tailwind (tokens, base, utilities; other looks = `@rivetjs/ui/theme` presets); each component module brings its own stylesheet, never import component CSS by hand.
+- Compound parts: `Card.Header`, `Select.Trigger`, `Modal.Content` …; wrapper parts with no own choice fold (`Modal.Content` = Backdrop + Container + Dialog + close button; `<Table aria-label columns items />` = ScrollContainer + Content + header + rows; explicit parts stay for custom layouts). Event props follow React Aria: `onPress` (not `onClick`), `onSelectionChange`, `onOpenChange`.
+- Two-way props take a signal: `isOpen={open}`, `value={selected}`, `selectedKeys={keys}`.
+- State props are live: `isDisabled={busy()}`, `isInvalid={!ok()}`, `variant={v()}`, a plain `value={v()}` (controlled) update in place, focus stays; attributes too (TextField `type={shown() ? "text" : "password"}`, `placeholder`, NumberField `step`, Button `type`). Read once ("Read once at mount" in the API docs): handlers, `id`, `name`, element-picking props (`elementType`, `orientation` of Separator), `autoFocus`, state options (`default*`, `selectionMode`, a collection's `disabledKeys`), MenuTrigger / DialogTrigger `trigger`: re-create with `<Show keyed>` to change them. Slider `minValue` / `maxValue` / `step` / `orientation` and Tabs `orientation` are live.
+
+```tsx
+import { signal } from "@rivetjs/reactivity";
+import { Button } from "@rivetjs/ui/button";
+import { Modal } from "@rivetjs/ui/modal";
+
+const open = signal(false);
+<Button onPress={() => open.set(true)}>Open</Button>
+<Modal.Content isOpen={open}>
+  <Modal.Header>Title</Modal.Header>
+  <Modal.Body>…</Modal.Body>
+  <Modal.Footer><Button slot="close">Close</Button></Modal.Footer>
+</Modal.Content>
+```
+
+```tsx
+import { Label } from "@rivetjs/ui/label";
+import { ListBox } from "@rivetjs/ui/list-box";
+import { Select } from "@rivetjs/ui/select";
+<Select placeholder="Select one" value={state}>
+  <Label>State</Label>
+  <Select.Trigger>
+    <Select.Value />
+    <Select.Indicator />
+  </Select.Trigger>
+  <Select.Popover>
+    <ListBox>
+      <ListBox.Item id="ca" textValue="California">
+        California
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </Select.Popover>
+</Select>;
+```
+
+- `@rivetjs/cdk`: headless 1:1 ports of React Aria / React Stately / RAC / Angular CDK, one subpath per module (`@rivetjs/cdk/select`, `@rivetjs/cdk/dialog`, `@rivetjs/cdk/overlay`, …). Unstyled: default `rv-*` classes + `data-*` state attributes. Overlays use a div layer in a portal (no native `<dialog>` / `popover`). Use it for custom-styled widgets; prefer `@rivetjs/ui` when its look fits.
+- Animations: `@rivetjs/motion` (Motion / motion.dev API, peer `motion` 14.x, no React): `<Motion.div initial={…} animate={…} exit={…} whileHover={…} whilePress={…}>` (`whilePress`, not `whileTap`), `Presence` / `PresenceFor` from `/presence` (not `AnimatePresence`; cdk / ui overlays and kit `Transition` already are presences), `layout` / `layoutId` + `animateLayout(scope, update)` from `/layout` (layout animates inside `animateLayout`, not on every render), `createScroll` / `createInView` / `prefersReducedMotion` accessors. Entrances render final styles + CSS on the server (no JS); values Motion's mini engine cannot animate (`rotateX`, `pathLength`, …) are a dev error: use `animate` from `@rivetjs/motion/animate` in a handler or `clientEffect`. Gestures with physics (drag, flick, carousel, sheet) stay cdk `motion` (`@rivetjs/cdk/motion`); there is no `drag` prop.
+
+## 9. Commands
+
+| Script            | Templates  | Does                                                                               |
+| ----------------- | ---------- | ---------------------------------------------------------------------------------- |
+| `npm run dev`     | all        | Vite dev server (pages resumed; DevTools panel Alt+Shift+R)                        |
+| `npm run build`   | all        | `vite build && vite build --ssr` (+ `node prerender.js` for static / ui / minimal) |
+| `npm start`       | server     | `node serve.js` (`PORT`, `HOST`)                                                   |
+| `npm run preview` | static, ui | serve `dist/client`                                                                |
+| `npm run check`   | all        | `rivet sync && rivet-check`                                                        |
+
+- Create: `npm create rivet@latest my-app -- --template static|server|ui|minimal --yes`.
+- `rivet sync` (bin of `@rivetjs/router`): regenerates `.rivet/` (route types + `.rivet/editor.json`). Run on a fresh clone before `tsc`.
+- `rivet-check` (bin of `@rivetjs/language-core`): compiler diagnostics for both targets + type-aware checks for every `.tsx` / `.jsx` of `tsconfig.json`. Flags: `-p <tsconfig|dir>` (repeatable), `--no-types`, `--no-manifest`, `--format text|json`. Exit 0 clean (warnings ok), 1 errors, 2 setup error. Run it after every change and before reporting done; also `npx tsc -p .`.
+- Editor: `@rivetjs/typescript-plugin` in `tsconfig.json` shows the same diagnostics + quick fixes while typing.
+- Measure in a build (`npm run build` + start/preview), not dev.
+- Tests (optional setup): `rivetTest()` from `@rivetjs/testing/vite`; `render`, `fire`, `flush` from `@rivetjs/runtime/testing`; `renderToString` from `@rivetjs/runtime/testing/server`.
+
+## 10. RV diagnostic codes
+
+- Format `RVnnnn`. Compiler errors fail the build; compiler warnings (RV2012–RV2014 on a `.bind` receiver that may be an object with its own `bind`, RV2015 on a returned accessor that cannot resume) print and the module still compiles; the language service adds type-aware warnings.
+- Where: Vite (terminal + overlay) as `[RV1016] src/x.tsx:12:8: message`; `rivet-check` as `file:line:col - error RV1016: message`; editor via the TS plugin. The MCP tool `explain_diagnostic("RV1016")` gives the meaning, the mechanical fix and an Avoid / Prefer pair; `check_code` returns the fix and the fixed source for a whole file.
+- Ranges: 1xxx JSX / attributes, 2xxx resume, 3xxx imports / helpers / route modules, 4xxx i18n, 5xxx styles, 6xxx slots, 7xxx config, 9xxx internal.
+
+| Code            | Meaning                                                                                     | Fix                                                     |
+| --------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| RV1000          | Parse error                                                                                 | fix syntax                                              |
+| RV1005          | HTML nesting the parser would repair (`<div>` in `<p>`)                                     | valid nesting                                           |
+| RV1012          | Unknown native event (`onclick`, `onTransitionend`)                                         | `on` + PascalCase                                       |
+| RV1015          | Handler is a literal, not a function                                                        | pass a function                                         |
+| RV1016          | Handler expression reads state when it binds                                                | wrap in an arrow                                        |
+| RV1101          | Unsafe / unsupported attribute or URL (`innerHTML`, `javascript:`)                          | remove; build-time assets                               |
+| RV1102          | Invalid `preload` value                                                                     | `eager` / `idle` / `visible` / `intent` / `interaction` |
+| RV2001          | Browser global read during server rendering                                                 | handler / `clientEffect` / `clientEvent` / `clientOnly` |
+| RV2002          | Ref callback must assign a local                                                            | `ref={(el) => (local = el)}` or `ref()`                 |
+| RV2003          | Captured class instance                                                                     | pass data; inside handler; `reconstruct(…)`             |
+| RV2102          | Captured instance of a module class that is not a data class (`#private`, base, resource)   | inside handler; `reconstruct(…)`; plain fields          |
+| RV2006          | JSX inside handler / effect / computed                                                      | JSX in component + signal                               |
+| RV2007          | Resumable code captures `this`                                                              | `event.currentTarget`                                   |
+| RV2009          | Two module references share a browser name                                                  | rename one import                                       |
+| RV2011          | Mutually recursive functions split by an early exit                                         | move them together before the exit                      |
+| RV2012–RV2014   | (warning; error on a provable function) `.bind` that may not resume                         | `const g = f.bind(t, …)`; arrow for other callees       |
+| RV2015          | (warning) component returns a function that cannot resume (anon default / wrapper / `let`)  | `export function Name(props) { return () => …; }`       |
+| RV2101          | (warning) captured value not serializable (type-aware)                                      | as RV2003                                               |
+| RV3003 / RV3004 | Structural helper namespace import / alias                                                  | `import { For } from "@rivetjs/runtime/dom"`            |
+| RV3006          | `clientOnly` erasure shape                                                                  | inline `() => import("…")`                              |
+| RV3007          | Route module server export shape (`export *` in a route)                                    | declare server exports directly                         |
+| RV3008          | Server-only code reached from browser code                                                  | keep in `serverLoad` / `*.server.ts`                    |
+| RV3101          | (warning) Link matches no route                                                             | fix the path                                            |
+| RV4001–4004     | i18n key / param / argument / tag errors                                                    | see section 5                                           |
+| RV5001–5003     | ``css`…` `` syntax / usage; invalid or unsafe class / style (style string, two class attrs) | style object, one `class`                               |
+| RV6001–6004     | Slot errors (`<slot>`, `r:name`, `r:slot`)                                                  | see JSX reference, slots                                |
+| RV7101 / RV7102 | `.rivet/editor.json` missing / stale                                                        | `rivet sync`                                            |
+| RV9000 / RV9001 | Unclassified / internal compiler error                                                      | report it                                               |
+
+- Not a code: render-time `… is not serializable` (see section 3).
+
+## 11. Links
+
+- MCP server `@rivetjs/mcp` (stdio, offline; docs of all three sites bundled): `npx -y @rivetjs/mcp`, or `npx rivet mcp` when installed in the app. Tools: `search_docs(query, site?)`, `get_doc(path)`, `list_components(package?)`, `get_component(name)` (import path, props / parts, example source), `check_code(code, filename?)`, `explain_diagnostic(code)`. Loop: look up → write → `check_code` → fix every RV error → `npm run check`.
+
+```json
+{ "mcpServers": { "rivet": { "command": "npx", "args": ["-y", "@rivetjs/mcp"] } } }
+```
+
+- Claude Code: `claude mcp add rivet -- npx -y @rivetjs/mcp`. Cursor: the JSON above in `.cursor/mcp.json`. VS Code: `.vscode/mcp.json` with `{ "servers": { "rivet": { "type": "stdio", "command": "npx", "args": ["-y", "@rivetjs/mcp"] } } }`.
+- Docs for models: every Rivet docs site (framework, cdk, ui) serves `/llms.txt` (index), `/llms-full.txt` (every page, examples as source) and `<page>.md` next to each HTML page. Guide: "AI assistants" (`docs:/guides/tooling/ai/` in the MCP server).
+- Skills (`.agents/skills/` for Codex/Cursor, `.claude/skills/` for Claude Code) and editor rules (`.cursor/rules/`, `.github/copilot-instructions.md`) in this project cover common tasks: UI/CDK design, add a route, form in a drawer, port a React component, page with `@rivetjs/ui` components, fix a resumability error. `rivet-ui-design` covers color roles, spacing, typography, structure, app layouts, composition and interactions; its references work without MCP. Portable bundles are distributed from the Rivet repository's `skills/` directory.
+
+## Checklist before reporting done
+
+- `npm run check` exits 0; `npm run build` passes (prerender / SSR catches non-serializable captures).
+- No destructured props in components that receive changing values; lists that change use `For` with `by`.
+- No browser globals outside handlers / `clientEffect` / `clientEvent` / `clientOnly`.
+- Icons only via `<Icon icon={…} />` + lucide.
+- Never edit `.rivet/`, `src/rivet-i18n.d.ts` or other `Generated … Do not edit` files.

package/templates/starter-static/README.md

@@ -0,0 +1,30 @@
+# Rivet static starter
+
+Pages in `src/routes` become HTML files at build time. Interactive parts keep working in the browser without re-running your components.
+
+```sh
+npm install
+npm run dev       # dev server with hot reload
+npm run build     # HTML files in dist/client
+npm run preview   # serve dist/client
+npm run check     # Rivet compiler diagnostics (CI)
+```
+
+- `npm run dev` resumes pages like production until you edit a file; after an edit the page renders in the browser so hot reload keeps state. Code is not bundled, and client-rendered parts use the dev DOM output (production builds use a faster one). Use `npm run build && npm run preview` to judge speed and size.
+- Deploy `dist/client` to any static host.
+
+## Next steps
+
+- Edit `src/routes/index.tsx` (home) and `src/routes/about.tsx`; `src/routes/_layout.tsx` wraps every page. `npm run dev` reloads them.
+- Add a page: a new file in `src/routes/` (`blog.tsx` → `/blog`, `blog/[slug].tsx` → `/blog/:slug`). Docs "File routes" (`guides/routing/file-routes`).
+- Deploy: `npm run build`, then upload `dist/client` to any static host (docs "Deploy", `guides/deploy/static-hosts`). Vercel / Netlify / Cloudflare: docs `guides/deploy/<target>` (one `adapter` option in `vite.config.ts`; new projects: `npm create rivet@latest -- --deploy <target>`).
+- Learn the model: docs "Signals" (`learn/signals`), "Resuming" (`learn/resuming`), "Server first" (`learn/server-first`).
+- Docs: https://github.com/rivetjs/rivet/tree/main/apps/docs/content (guides, reference, recipes).
+
+## Tooling
+
+- Node.js 24 or newer (`engines` in `package.json`).
+- `npm run check` runs `rivet sync` (writes the gitignored `.rivet/` route types + editor manifest from `vite.config.ts`; also run it before `tsc` on a fresh clone) then `rivet-check`: the Rivet compiler's diagnostics (browser globals read during server rendering, handlers that cannot resume, …) for every `.tsx` file of `tsconfig.json`. Exits 1 on an error; use it in CI.
+- `@rivetjs/devtools` is a dev dependency, so `npm run dev` shows the DevTools panel (Alt+Shift+R or the round **R** button). Builds never include it. Turn it off with `rivetRouter({ devtools: false })`.
+- `tsconfig.json` lists `@rivetjs/typescript-plugin`: editors that use the project's TypeScript show compiler errors while you type. `tsc` ignores the entry.
+- `vite.config.ts` passes options to `rivetRouter()`: `mode`, `styles`, `resume`, `devtools`, `dev.resume`, `transitions`, … All options: the docs page "Configuration" (`reference/config`).

package/templates/starter-static/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.rivet/

package/templates/starter-static/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "rivet-starter-static",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && vite build --ssr && node prerender.js",
+    "preview": "node serve.js",
+    "check": "rivet sync && rivet-check"
+  },
+  "dependencies": {
+    "@rivetjs/reactivity": "experimental",
+    "@rivetjs/router": "experimental",
+    "@rivetjs/runtime": "experimental"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@rivetjs/compiler": "experimental",
+    "@rivetjs/devtools": "experimental",
+    "@rivetjs/language-core": "experimental",
+    "@rivetjs/typescript-plugin": "experimental",
+    "@tailwindcss/vite": "^4.3.3",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.2"
+  }
+}

package/templates/starter-static/prerender.js

@@ -0,0 +1,5 @@
+// Render every page to an HTML file in dist/client (run after `vite build` and `vite build --ssr`).
+import { prerenderBuild } from "@rivetjs/router/static";
+
+const report = await prerenderBuild({ dist: "dist" });
+console.log(`Prerendered ${report.pages.length} page(s) into dist/client`);

package/templates/starter-static/serve.js

@@ -0,0 +1,21 @@
+// Preview the built site: serves dist/client like a static host (folders → index.html, 404.html).
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { serve } from "@rivetjs/router/node";
+
+const client = resolve("dist/client");
+const page = (path) => readFile(resolve(client, "." + path)).catch(() => null);
+
+const serving = await serve({
+  client,
+  port: Number(process.env.PORT ?? 4173),
+  handler: async (request) => {
+    const { pathname } = new URL(request.url);
+    // Files are served before the handler; here only folders and missing paths arrive.
+    if (!pathname.endsWith("/") && (await page(pathname + "/index.html"))) return Response.redirect(new URL(pathname + "/", request.url), 308);
+    const html = (await page(pathname.replace(/\/?$/, "/") + "index.html")) ?? null;
+    if (html) return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } });
+    return new Response((await page("/404.html")) ?? "Not found", { status: 404, headers: { "content-type": "text/html; charset=utf-8" } });
+  },
+});
+console.log(`Preview: ${serving.url}`);

package/templates/starter-static/src/components/Counter.tsx

@@ -0,0 +1,15 @@
+import { signal } from "@rivetjs/reactivity";
+
+/** A button that counts clicks. Its code loads when you first point at it. */
+export function Counter() {
+  const count = signal(0);
+  return (
+    <button
+      type="button"
+      class="mt-4 rounded-md bg-teal-700 px-4 py-2 font-semibold text-white"
+      onClick={() => count.update((n) => n + 1)}
+    >
+      Clicked {count()} times
+    </button>
+  );
+}

package/templates/starter-static/src/document.ts

@@ -0,0 +1,14 @@
+import { headTags, type DocumentShell } from "@rivetjs/router/server";
+
+/**
+ * The HTML around every page. The route `head` (title, meta, links, scripts) is written in full; `input` carries the
+ * stylesheets, the CSP nonce (server pages) and the client-managed marks of `@rivetjs/kit` head components.
+ */
+const document: DocumentShell = (input) => ({
+  start:
+    '<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">' +
+    headTags({ ...input.head, title: input.head?.title ?? "Rivet app" }, input) +
+    "</head><body>",
+  end: "</body></html>",
+});
+export default document;

package/templates/starter-static/src/routes/_layout.tsx

@@ -0,0 +1,18 @@
+import type { LayoutProps } from "@rivetjs/router";
+
+/** Wraps every page. */
+export default function Layout({ children }: LayoutProps) {
+  return (
+    <div class="mx-auto max-w-2xl p-6">
+      <nav class="mb-6 flex gap-4 text-sm">
+        <a class="text-teal-700 underline" href="/">
+          Home
+        </a>
+        <a class="text-teal-700 underline" href="/about">
+          About
+        </a>
+      </nav>
+      <main>{children}</main>
+    </div>
+  );
+}

package/templates/starter-static/src/routes/about.tsx

@@ -0,0 +1,11 @@
+export const head = { title: "About" };
+
+/** The page at `/about`. */
+export default function About() {
+  return (
+    <>
+      <h1 class="text-2xl font-bold">About</h1>
+      <p class="mt-2 text-slate-600">Each file in src/routes is a page. This one is src/routes/about.tsx.</p>
+    </>
+  );
+}