@kitr/mocks 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Platon Podkopov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @kitr/mocks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Mocks.** Fake your API while you build the frontend or run tests.
+
+```sh
+pnpm kitr add mocks
+```
+
+`kitr add` installs the package and wires it into your app: the provider in `kitrrc.ts`, its config file and its `AGENTS.md` section. Import it from `@kitr/mocks`.
+
+Built on msw.
+
+Read the guide at https://kitr.dev/packages/mocks.
+
+Part of [kitr](https://kitr.dev), the TypeScript framework where everything is an add-on. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { HttpResponse, RequestHandler, http } from "msw";
+/** One route of a kitr route table, as `routes.toJSON()` and `kitr api:sync` describe it. */
+export interface RouteDescriptor {
+  /** The route name that `mockRoutes` resolvers are keyed by, such as `orders.show`. */
+  name: string;
+  /** The HTTP method, in any case: `GET`, `post`. */
+  method: string;
+  /** The path pattern with `:params`, such as `/api/orders/:id`. */
+  path: string;
+}
+type Resolver = (info: {
+  params: Record<string, string | readonly string[] | undefined>;
+  request: Request;
+  body: () => Promise<unknown>;
+}) => unknown | Promise<unknown>;
+/**
+ * MSW handlers from a kitr route table (`routes.toJSON()`) or an OpenAPI-ish list.
+ * Unhandled routes get a 501 so a missing mock is loud, not silent.
+ *
+ *   const handlers = mockRoutes(routeTable, 'http://localhost:3000', {
+ *     'projects.index': () => [{ id: '1', name: 'Alpha' }],
+ *     'projects.show': ({ params }) => ({ id: params.id, name: 'Alpha' }),
+ *   })
+ */
+export declare function mockRoutes(table: RouteDescriptor[], baseUrl: string, resolvers: Record<string, Resolver | unknown>): RequestHandler[];
+/**
+ * Turns anything thrown into the JSON response a kitr server sends for it: a `KitrError` keeps its
+ * code and status, anything else becomes `INTERNAL` with status 500.
+ */
+export declare function kitrErrorResponse(error: unknown): HttpResponse<import("msw").JsonBodyType>;
+/** A handler that throws a kitr validation error, to test form error mapping. */
+export declare function mockValidationError(method: 'post' | 'put' | 'patch', url: string, fieldErrors: Record<string, string[]>): import("msw").HttpHandler;
+/**
+ * Starts MSW in Node for tests: `const mocks = await setupNodeMocks(handlers)`. Requests no handler
+ * matches go to the real network. Returns MSW's server, so `use`, `resetHandlers` and `close` work.
+ */
+export declare function setupNodeMocks(handlers: RequestHandler[]): Promise<import("msw/node").SetupServer>;
+/**
+ * Starts MSW's service worker in the browser for development: `await setupBrowserMocks(handlers)`.
+ * Needs `mockServiceWorker.js` in the public folder. Pass `quiet: false` to see MSW's console messages.
+ */
+export declare function setupBrowserMocks(handlers: RequestHandler[], options?: {
+  quiet?: boolean;
+}): Promise<import("msw/browser").SetupWorker>;
+export { HttpResponse, http };

package/dist/index.js

@@ -0,0 +1,71 @@
+import { KitrError } from "@kitr/core";
+import { HttpResponse, http } from "msw";
+// src/index.ts
+/**
+* MSW handlers from a kitr route table (`routes.toJSON()`) or an OpenAPI-ish list.
+* Unhandled routes get a 501 so a missing mock is loud, not silent.
+*
+*   const handlers = mockRoutes(routeTable, 'http://localhost:3000', {
+*     'projects.index': () => [{ id: '1', name: 'Alpha' }],
+*     'projects.show': ({ params }) => ({ id: params.id, name: 'Alpha' }),
+*   })
+*/
+function mockRoutes(table, baseUrl, resolvers) {
+	const base = baseUrl.replace(/\/$/, "");
+	return table.map((route) => {
+		const method = route.method.toLowerCase();
+		const pattern = `${base}${route.path}`;
+		const resolver = resolvers[route.name];
+		return http[method](pattern, async ({ params, request }) => {
+			if (resolver === void 0) return kitrErrorResponse(new KitrError("UNAVAILABLE", `No mock for ${route.name}`, { status: 501 }));
+			try {
+				const value = typeof resolver === "function" ? await resolver({
+					params,
+					request,
+					body: () => request.json()
+				}) : resolver;
+				if (value instanceof Response) return value;
+				if (value === void 0) return new HttpResponse(null, { status: 204 });
+				return HttpResponse.json(value);
+			} catch (error) {
+				return kitrErrorResponse(error);
+			}
+		});
+	});
+}
+/**
+* Turns anything thrown into the JSON response a kitr server sends for it: a `KitrError` keeps its
+* code and status, anything else becomes `INTERNAL` with status 500.
+*/
+function kitrErrorResponse(error) {
+	const e = error instanceof KitrError ? error : new KitrError("INTERNAL", String(error?.message ?? error));
+	return HttpResponse.json(e.toJSON(), { status: e.status });
+}
+/** A handler that throws a kitr validation error, to test form error mapping. */
+function mockValidationError(method, url, fieldErrors) {
+	return http[method](url, () => kitrErrorResponse(KitrError.validation(fieldErrors)));
+}
+/**
+* Starts MSW in Node for tests: `const mocks = await setupNodeMocks(handlers)`. Requests no handler
+* matches go to the real network. Returns MSW's server, so `use`, `resetHandlers` and `close` work.
+*/
+async function setupNodeMocks(handlers) {
+	const { setupServer } = await import("msw/node");
+	const server = setupServer(...handlers);
+	server.listen({ onUnhandledFrame: "bypass" });
+	return server;
+}
+/**
+* Starts MSW's service worker in the browser for development: `await setupBrowserMocks(handlers)`.
+* Needs `mockServiceWorker.js` in the public folder. Pass `quiet: false` to see MSW's console messages.
+*/
+async function setupBrowserMocks(handlers, options = {}) {
+	const { setupWorker } = await import("msw/browser");
+	const worker = setupWorker(...handlers);
+	await worker.start({
+		onUnhandledFrame: "bypass",
+		quiet: options.quiet ?? true
+	});
+	return worker;
+}
+export { HttpResponse, http, kitrErrorResponse, mockRoutes, mockValidationError, setupBrowserMocks, setupNodeMocks };

package/dist/kitr.d.ts

@@ -0,0 +1,11 @@
+/** `kitr add mocks`: MSW handlers from route tables and contracts, for dev without a backend and for tests. */
+declare const _default: {
+  readonly name: "mocks";
+  readonly client: true;
+  readonly add: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly remove: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly eject: {
+    readonly '@kitr/mocks': "msw";
+  };
+};
+export { _default as default };

package/dist/kitr.js

@@ -0,0 +1,27 @@
+import { definePackage } from "@kitr/core/package";
+// src/kitr.ts
+/** `kitr add mocks`: MSW handlers from route tables and contracts, for dev without a backend and for tests. */
+var kitr_default = definePackage({
+	name: "mocks",
+	client: true,
+	add(ctx) {
+		ctx.deps.add({
+			name: "msw",
+			dev: true
+		});
+		ctx.write("app/mocks/handlers.ts", `import { HttpResponse, http } from '@kitr/mocks'\n\nexport const handlers = [\n  http.get('*/me', () => HttpResponse.json({ id: 'u1', email: 'dev@example.com', role: 'admin' })),\n]\n`);
+		ctx.write("app/mocks/browser.ts", `import { setupBrowserMocks } from '@kitr/mocks'\nimport { handlers } from './handlers'\n\n/**\n * \`await enableMocks()\` in the client entry. Env values are strings, so only \`VITE_MOCKS=true\`\n * turns mocks on (\`false\` would be truthy), and only in dev.\n */\nexport async function enableMocks() {\n  if (import.meta.env.DEV && import.meta.env.VITE_MOCKS === 'true') await setupBrowserMocks(handlers)\n}\n`);
+		ctx.packageJson.set("msw", { workerDirectory: ["public"] });
+		ctx.scripts.add("mocks:init", "msw init public");
+		ctx.env.add({ VITE_MOCKS: "false" }, "Set true to serve app/mocks/handlers.ts in the browser");
+		ctx.agents.add("mocks", `- Mocks live in \`app/mocks/handlers.ts\` (MSW). \`VITE_MOCKS=true\` enables them in dev (run \`npm run mocks:init\` once if public/mockServiceWorker.js is missing); tests use \`setupNodeMocks(handlers)\`. Mock a kitr route table with \`mockRoutes(routes.toJSON(), baseUrl, { 'projects.index': () => [...] })\`.`);
+	},
+	remove(ctx) {
+		ctx.deps.remove("msw");
+		ctx.packageJson.remove("msw", { workerDirectory: ["public"] });
+		ctx.scripts.remove("mocks:init", "msw init public");
+		ctx.agents.remove("mocks");
+	},
+	eject: { "@kitr/mocks": "msw" }
+});
+export { kitr_default as default };

package/docs/api.md

@@ -0,0 +1,83 @@
+---
+title: API reference
+description: Every export of @kitr/mocks, with its signature.
+order: 2
+---
+
+# API reference
+
+Every export of `@kitr/mocks`, read from the published type definitions. The [guide](/packages/mocks/guide) shows them in use.
+
+## @kitr/mocks
+
+Re-exports `msw` unchanged, plus the following.
+
+### kitrErrorResponse
+
+```ts
+function kitrErrorResponse(error: unknown): HttpResponse<import("msw").JsonBodyType>;
+```
+
+Turns anything thrown into the JSON response a kitr server sends for it: a `KitrError` keeps its
+code and status, anything else becomes `INTERNAL` with status 500.
+
+### mockRoutes
+
+```ts
+function mockRoutes(table: RouteDescriptor[], baseUrl: string, resolvers: Record<string, Resolver | unknown>): RequestHandler[];
+```
+
+MSW handlers from a kitr route table (`routes.toJSON()`) or an OpenAPI-ish list.
+Unhandled routes get a 501 so a missing mock is loud, not silent.
+
+```ts
+const handlers = mockRoutes(routeTable, 'http://localhost:3000', {
+  'projects.index': () => [{ id: '1', name: 'Alpha' }],
+  'projects.show': ({ params }) => ({ id: params.id, name: 'Alpha' }),
+})
+```
+
+### mockValidationError
+
+```ts
+function mockValidationError(method: 'post' | 'put' | 'patch', url: string, fieldErrors: Record<string, string[]>): import("msw").HttpHandler;
+```
+
+A handler that throws a kitr validation error, to test form error mapping.
+
+### setupBrowserMocks
+
+```ts
+function setupBrowserMocks(handlers: RequestHandler[], options?: {
+  quiet?: boolean;
+}): Promise<import("msw/browser").SetupWorker>;
+```
+
+Starts MSW's service worker in the browser for development: `await setupBrowserMocks(handlers)`.
+Needs `mockServiceWorker.js` in the public folder. Pass `quiet: false` to see MSW's console messages.
+
+### setupNodeMocks
+
+```ts
+function setupNodeMocks(handlers: RequestHandler[]): Promise<import("msw/node").SetupServer>;
+```
+
+Starts MSW in Node for tests: `const mocks = await setupNodeMocks(handlers)`. Requests no handler
+matches go to the real network. Returns MSW's server, so `use`, `resetHandlers` and `close` work.
+
+### RouteDescriptor
+
+```ts
+interface RouteDescriptor {
+  /** The route name that `mockRoutes` resolvers are keyed by, such as `orders.show`. */
+  name: string;
+  /** The HTTP method, in any case: `GET`, `post`. */
+  method: string;
+  /** The path pattern with `:params`, such as `/api/orders/:id`. */
+  path: string;
+}
+```
+
+One route of a kitr route table, as `routes.toJSON()` and `kitr api:sync` describe it.
+
+<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->

package/docs/index.md

@@ -0,0 +1,527 @@
+---
+title: Mocks
+description: Fake your API while you build the frontend or run tests.
+order: 1
+---
+
+# Mocks
+
+Frontend work shouldn't wait for the backend. The invoices screen is designed, the API that feeds it is still a ticket, and the tests for its empty and error states need answers the real server rarely gives. `@kitr/mocks` answers your app's HTTP requests with fake data, in the browser while you develop and in Node while your tests run.
+
+> [!SUMMARY]
+> Fake your API with Mock Service Worker, in the browser and in tests. Add it with `kitr add mocks`; the overview is at [/packages/mocks](/packages/mocks).
+
+It is [Mock Service Worker](https://mswjs.io) (MSW), with `http` and `HttpResponse` re-exported unchanged. It adds `mockRoutes()`, which builds one handler per route of a kitr route table, and helpers that send errors in the shape a kitr server sends them.
+
+In the browser a service worker intercepts `fetch`; in Node MSW patches it. Requests the server makes while rendering never reach the browser, so they are not mocked. To test your own API routes rather than fake them, use [testing](/packages/testing)'s `createTestClient`.
+
+The examples follow Acme's billing team building the invoices screen at `app.acme.com` before the `/api/invoices` routes exist. Ada is an admin; Grace and Linus are customers.
+
+## Install
+
+```sh
+kitr add mocks
+```
+
+<details>
+<summary>Everything kitr add changes</summary>
+
+What `kitr add` does:
+
+- Adds `@kitr/mocks` to `dependencies` and `msw` to `devDependencies`, and installs them. Pass `--no-install` to skip the install.
+- Adds `'@kitr/mocks'` to `packages` in `kitrrc.ts`. It registers no provider: mocks start only when your code calls them.
+- Writes `app/mocks/handlers.ts` with one handler for `*/me`, unless the file exists.
+- Writes `app/mocks/browser.ts`, which exports `enableMocks()`, unless the file exists. It starts the worker only in development and only when `VITE_MOCKS` is exactly `'true'`.
+- Sets `"msw": { "workerDirectory": ["public"] }` in `package.json`, so MSW's own install step writes and refreshes `public/mockServiceWorker.js`.
+- Adds a `mocks:init` script (`msw init public`) that writes the worker on demand.
+- Adds `VITE_MOCKS=false` to `.env.example`, and to `.env` when it exists, under the comment `# Set true to serve app/mocks/handlers.ts in the browser`.
+- Adds a `## kitr: mocks` section to `AGENTS.md`: handlers live in `app/mocks/handlers.ts`, `VITE_MOCKS=true` turns them on in development, tests use `setupNodeMocks(handlers)`, and a kitr route table is mocked with `mockRoutes(routes.toJSON(), baseUrl, { ... })`.
+
+The `app`, `desktop` and `mobile` kits include it. `kitr remove mocks` reverses the `package.json`, `kitrrc.ts` and `AGENTS.md` changes and lists files that still import `@kitr/mocks`. It leaves `app/mocks/`, the `VITE_MOCKS` line and `public/mockServiceWorker.js` for you to delete.
+
+</details>
+
+> [!WARNING] Client packages only
+> In a project without React, `kitr add` skips mocks with a warning.
+
+## Configure
+
+`@kitr/mocks` has no config file: you configure the handler list and one env variable. `kitr add` writes these two files:
+
+```ts
+// app/mocks/handlers.ts
+import { HttpResponse, http } from '@kitr/mocks'
+
+export const handlers = [
+  http.get('*/me', () => HttpResponse.json({ id: 'u1', email: 'dev@example.com', role: 'admin' })),
+]
+```
+
+```ts
+// app/mocks/browser.ts
+import { setupBrowserMocks } from '@kitr/mocks'
+import { handlers } from './handlers'
+
+/**
+ * `await enableMocks()` in the client entry. Env values are strings, so only `VITE_MOCKS=true`
+ * turns mocks on (`false` would be truthy), and only in dev.
+ */
+export async function enableMocks() {
+  if (import.meta.env.DEV && import.meta.env.VITE_MOCKS === 'true') await setupBrowserMocks(handlers)
+}
+```
+
+| Variable | Used for |
+| --- | --- |
+| `VITE_MOCKS` | `true` serves `app/mocks/handlers.ts` in the browser during `kitr dev`. Anything else leaves the real network alone. |
+
+The functions that start mocks take these options:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `setupBrowserMocks(handlers)` | required | The handlers to serve in the browser. |
+| `setupBrowserMocks(_, { quiet })` | `true` | `false` lets MSW log `[MSW] Mocking enabled` and every request it handles to the console. |
+| `setupNodeMocks(handlers)` | required | The handlers to serve in Node. Starts listening immediately. |
+| `mockRoutes(table)` | required | The route table: `{ name, method, path }` entries, from `routes.toJSON()` or `kitr api:sync`. |
+| `mockRoutes(_, baseUrl)` | required | Prefixed to every path. `'*'` matches any origin; `'http://localhost:3333'` matches only that one. A trailing slash is removed. |
+| `mockRoutes(_, _, resolvers)` | required | The answers, keyed by route name. A route without one answers `501`. |
+
+A request that no handler matches goes to the real network, so you can fake one endpoint and keep the rest.
+
+## Fake your first endpoint
+
+Add a handler for the request your screen makes. This one answers the invoice list with three invoices:
+
+```ts
+// app/mocks/handlers.ts
+import { HttpResponse, http } from '@kitr/mocks'
+
+export const handlers = [
+  http.get('*/api/me', () =>
+    HttpResponse.json({ id: 'u_ada', email: 'ada@acme.com', name: 'Ada', role: 'admin' }),
+  ),
+  http.get('*/api/invoices', () =>
+    HttpResponse.json([
+      { id: 'inv_1001', customer: 'Grace', amount: 120, status: 'paid' },
+      { id: 'inv_1002', customer: 'Linus', amount: 300, status: 'open' },
+      { id: 'inv_1003', customer: 'Grace', amount: 80, status: 'draft' },
+    ]),
+  ),
+]
+```
+
+Set `VITE_MOCKS=true` in `.env`, restart `kitr dev`, and open the invoices page. The network panel shows each request answered `from service worker`.
+
+The leading `*` matches any origin, in development or in a preview. `http` and `HttpResponse` are MSW's own, so [MSW's docs](https://mswjs.io/docs/http) apply.
+
+## Turn mocks on in the browser
+
+MSW needs its worker script served from your site's root. The install writes `public/mockServiceWorker.js`; if it is missing, for example after `--no-install`, write it and commit it:
+
+```sh
+pnpm mocks:init
+```
+
+Then start the worker in `app/client.tsx`, before the app boots:
+
+```tsx
+// app/client.tsx
+import { StartClient } from '@tanstack/react-start/client'
+import { StrictMode, startTransition } from 'react'
+import { hydrateRoot } from 'react-dom/client'
+import { app } from './app'
+
+async function start() {
+  if (import.meta.env.DEV && import.meta.env.VITE_MOCKS === 'true') {
+    const { enableMocks } = await import('#app/mocks/browser')
+    await enableMocks()
+  }
+  await app.boot()
+  startTransition(() => {
+    hydrateRoot(
+      document,
+      <StrictMode>
+        <StartClient />
+      </StrictMode>,
+    )
+  })
+}
+
+start()
+```
+
+The dynamic `import()` keeps MSW and your fake data out of the production bundle, and `import.meta.env.DEV` is `false` in every production build.
+
+> [!WARNING] Compare to the string
+> Don't write `if (import.meta.env.VITE_MOCKS)`: env values are strings, and `'false'` is truthy.
+
+In a server-rendered app, loaders that fetch during the first render hit the real API. Requests after hydration, and every request in a single-page app, go through the mocks.
+
+## Write handlers
+
+A handler pairs a method and URL pattern with a function that returns a response. Use `:name` for path params, `request.url` for the query string and `request.json()` for the body:
+
+```ts
+// app/mocks/handlers.ts
+import { HttpResponse, http } from '@kitr/mocks'
+
+export const handlers = [
+  http.get('*/api/invoices/:id', ({ params }) =>
+    HttpResponse.json({ id: params.id, customer: 'Grace', amount: 120, status: 'paid' }),
+  ),
+
+  http.get('*/api/invoices', ({ request }) => {
+    const status = new URL(request.url).searchParams.get('status')
+    return HttpResponse.json([{ id: 'inv_1002', customer: 'Linus', amount: 300, status }])
+  }),
+
+  http.post('*/api/invoices', async ({ request }) => {
+    const input = (await request.json()) as { customer: string; amount: number }
+    return HttpResponse.json(
+      { id: 'inv_1004', status: 'draft', ...input },
+      { status: 201, headers: { location: '/api/invoices/inv_1004' } },
+    )
+  }),
+
+  http.delete('*/api/invoices/:id', () => new HttpResponse(null, { status: 204 })),
+]
+```
+
+`HttpResponse.json()`, `.text()`, `.xml()` and a plain `new HttpResponse(body, init)` cover the response types. When two handlers match, the first in the list wins.
+
+## Keep fake data in one place
+
+Handlers with literal objects drift apart. Put the records in one module and have the handlers read and write it, so a created invoice appears in the list:
+
+```ts
+// app/mocks/data.ts
+export interface Invoice {
+  id: string
+  customer: string
+  amount: number
+  status: 'draft' | 'open' | 'paid'
+}
+
+export const invoices: Invoice[] = [
+  { id: 'inv_1001', customer: 'Grace', amount: 120, status: 'paid' },
+  { id: 'inv_1002', customer: 'Linus', amount: 300, status: 'open' },
+  { id: 'inv_1003', customer: 'Grace', amount: 80, status: 'draft' },
+]
+```
+
+```ts
+// app/mocks/handlers.ts
+import { HttpResponse, http } from '@kitr/mocks'
+import { type Invoice, invoices } from './data'
+
+export const handlers = [
+  http.get('*/api/invoices', () => HttpResponse.json(invoices)),
+
+  http.post('*/api/invoices', async ({ request }) => {
+    const input = (await request.json()) as Pick<Invoice, 'customer' | 'amount'>
+    const invoice: Invoice = { id: `inv_${1001 + invoices.length}`, status: 'draft', ...input }
+    invoices.push(invoice)
+    return HttpResponse.json(invoice, { status: 201 })
+  }),
+]
+```
+
+The array lives as long as the page or test file; reload and it starts over.
+
+## Mock a whole route table
+
+With the [API](/packages/api) package, every route has a name. `mockRoutes` builds one handler per route; you write only the answers, keyed by name:
+
+```ts
+// app/mocks/handlers.ts
+import { KitrError } from 'kitr/app'
+import { HttpResponse, mockRoutes } from '@kitr/mocks'
+import { routeTable } from '#app/api/routes.gen'
+import { type Invoice, invoices } from './data'
+
+export const handlers = mockRoutes([...routeTable], '*', {
+  'invoices.index': ({ request }) => {
+    const status = new URL(request.url).searchParams.get('status')
+    return status ? invoices.filter((invoice) => invoice.status === status) : invoices
+  },
+  'invoices.show': ({ params }) => {
+    const invoice = invoices.find((i) => i.id === params.id)
+    if (!invoice) throw KitrError.notFound(`Invoice ${params.id}`)
+    return invoice
+  },
+  'invoices.store': async ({ body }) => {
+    const input = (await body()) as Pick<Invoice, 'customer' | 'amount'>
+    const invoice: Invoice = { id: `inv_${1001 + invoices.length}`, status: 'draft', ...input }
+    invoices.push(invoice)
+    return HttpResponse.json(invoice, { status: 201 })
+  },
+  'invoices.destroy': () => undefined,
+  'auth.me': { id: 'u_ada', email: 'ada@acme.com', role: 'admin' },
+})
+```
+
+`routeTable` is the file `kitr api:sync` writes: names, methods and paths, with no server code. In a test, `routes.toJSON()` from `#server/routes` gives the same list.
+
+What a resolver can be, and what the request gets back:
+
+| Resolver | Response |
+| --- | --- |
+| A value, not a function: `{ id: 'u_ada' }` | `200` with that value as JSON, for every request. |
+| A function returning a value | `200` with the value as JSON. |
+| A function returning `undefined` | `204` with no body. |
+| A function returning a `Response` | That response, as is. Use it for other statuses and headers. |
+| A function that throws a `KitrError` | That error's status and JSON, as the real server sends it. |
+| A function that throws anything else | `500` with `code: 'INTERNAL'` and the error's message. |
+| No entry for the route | `501` with `code: 'UNAVAILABLE'` and `No mock for invoices.update`. |
+
+A resolver function receives `params`, `request` and `body()`, which reads the JSON body. An entry whose value is `undefined` counts as no entry; write `() => undefined` for a `204`. The `501` is on purpose: a route you forgot to mock fails loudly with its name.
+
+## Send an error response
+
+`kitrErrorResponse()` turns any error into the JSON response a kitr server would send, so the [http](/packages/http) client turns it back into the `KitrError` your error handling expects:
+
+```ts
+// app/mocks/handlers.ts
+import { KitrError } from 'kitr/app'
+import { http, kitrErrorResponse } from '@kitr/mocks'
+
+export const handlers = [
+  http.post('*/api/invoices/:id/refund', () =>
+    kitrErrorResponse(KitrError.forbidden('Only admins can refund')),
+  ),
+  http.get('*/api/invoices/export', () =>
+    kitrErrorResponse(new KitrError('RATE_LIMITED', 'Try again in a minute')),
+  ),
+  http.get('*/api/ledger', () => kitrErrorResponse(new Error('Ledger offline'))),
+]
+```
+
+The three responses:
+
+```json
+{ "code": "FORBIDDEN", "message": "Only admins can refund", "status": 403 }
+{ "code": "RATE_LIMITED", "message": "Try again in a minute", "status": 429 }
+{ "code": "INTERNAL", "message": "Ledger offline", "status": 500 }
+```
+
+A `KitrError` keeps its code, message, status, `fieldErrors` and `data`; anything else becomes `INTERNAL` (500). Inside `mockRoutes`, throwing does the same.
+
+## Show server validation errors in a form
+
+`mockValidationError(method, url, fieldErrors)` answers with a `422`, the quickest way to check that a form shows server messages under the right fields:
+
+```ts
+// app/mocks/handlers.ts
+import { mockValidationError } from '@kitr/mocks'
+
+export const handlers = [
+  mockValidationError('post', '*/api/invoices', {
+    customer: ['Customer is required'],
+    amount: ['Amount must be greater than 0'],
+  }),
+]
+```
+
+```json
+{
+  "code": "VALIDATION",
+  "message": "Validation failed",
+  "status": 422,
+  "fieldErrors": {
+    "customer": ["Customer is required"],
+    "amount": ["Amount must be greater than 0"]
+  }
+}
+```
+
+`method` is `'post'`, `'put'` or `'patch'`. With [forms](/packages/forms), each message appears under its field. Keys can be nested paths such as `'lines.0.amount'`.
+
+## Simulate a slow or failed request
+
+MSW's `delay` pauses a handler; `HttpResponse.error()` makes `fetch` reject as if the network were down. Import `delay` from `msw`:
+
+```ts
+// app/mocks/handlers.ts
+import { HttpResponse, http } from '@kitr/mocks'
+import { delay } from 'msw'
+import { invoices } from './data'
+
+export const handlers = [
+  http.get('*/api/invoices', async () => {
+    await delay(1500)
+    return HttpResponse.json(invoices)
+  }),
+  http.get('*/api/invoices/:id/pdf', () => HttpResponse.error()),
+]
+```
+
+`delay()` with no argument waits a realistic random time; `delay('infinite')` never answers, for testing a spinner.
+
+## Mock a third-party API
+
+Handlers match full URLs too, so the same file can fake services you don't own:
+
+```ts
+// app/mocks/handlers.ts
+import { HttpResponse, http } from '@kitr/mocks'
+
+export const handlers = [
+  http.get('https://api.exchangerate.host/latest', ({ request }) => {
+    const base = new URL(request.url).searchParams.get('base') ?? 'EUR'
+    return HttpResponse.json({ base, rates: { USD: 1.08, GBP: 0.85 } })
+  }),
+]
+```
+
+
+## Use mocks in tests
+
+`setupNodeMocks(handlers)` starts MSW in Node and returns MSW's server. Start it once per file, reset overrides after each test, and close it at the end:
+
+```ts
+// app/lib/invoices/invoices.test.ts
+import { setupNodeMocks } from '@kitr/mocks'
+import { afterAll, afterEach, beforeAll, expect, it } from 'vitest'
+import { handlers } from '#app/mocks/handlers'
+
+let mocks: Awaited<ReturnType<typeof setupNodeMocks>>
+beforeAll(async () => {
+  mocks = await setupNodeMocks(handlers)
+})
+afterEach(() => mocks.resetHandlers())
+afterAll(() => mocks.close())
+
+it('lists open invoices', async () => {
+  const res = await fetch('https://app.acme.com/api/invoices?status=open')
+  expect(await res.json()).toEqual([
+    { id: 'inv_1002', customer: 'Linus', amount: 300, status: 'open' },
+  ])
+})
+```
+
+Any code that calls `fetch` sees the mocks. Under `happy-dom` a relative URL such as `/api/invoices` resolves against `http://localhost:3000`; in the `node` environment use absolute URLs.
+
+To render a component against these mocks, combine them with `renderWithKitr` from [testing](/packages/testing#fake-the-network-for-components).
+
+## Override a handler for one test
+
+`mocks.use()` puts handlers in front of the list until the next `resetHandlers()`, giving one test the empty state or error it needs:
+
+```ts
+// app/lib/invoices/invoices.test.ts
+import { KitrError } from 'kitr/app'
+import { HttpResponse, http, kitrErrorResponse, setupNodeMocks } from '@kitr/mocks'
+import { afterAll, afterEach, beforeAll, expect, it } from 'vitest'
+import { handlers } from '#app/mocks/handlers'
+
+let mocks: Awaited<ReturnType<typeof setupNodeMocks>>
+beforeAll(async () => {
+  mocks = await setupNodeMocks(handlers)
+})
+afterEach(() => mocks.resetHandlers())
+afterAll(() => mocks.close())
+
+it('shows the empty state', async () => {
+  mocks.use(http.get('*/api/invoices', () => HttpResponse.json([])))
+  expect(await (await fetch('/api/invoices')).json()).toEqual([])
+})
+
+it('shows the permission error', async () => {
+  mocks.use(http.get('*/api/invoices', () => kitrErrorResponse(KitrError.forbidden())))
+  const res = await fetch('/api/invoices')
+  expect(res.status).toBe(403)
+})
+
+it('is back to the shared handlers', async () => {
+  expect((await fetch('/api/invoices')).status).toBe(200)
+})
+```
+
+> [!WARNING] Start once per file
+> Call `setupNodeMocks` in `beforeAll`, not in each test, and override with `use()`. See MSW's [server API](https://mswjs.io/docs/api/setup-server).
+
+## Turn mocks off
+
+Set `VITE_MOCKS=false` in `.env` and restart `kitr dev`; the real API answers. To mock one endpoint only, keep `VITE_MOCKS=true` and delete the other handlers. Production builds never start the worker.
+
+## Errors
+
+The responses `@kitr/mocks` builds itself:
+
+| Code | When | What to do |
+| --- | --- | --- |
+| `UNAVAILABLE` (501) | `mockRoutes` got a request for a route with no resolver: `No mock for invoices.update`. | Add a resolver under that route name, or remove the route from the table you pass. |
+| `INTERNAL` (500) | A resolver threw something that is not a `KitrError`, or `kitrErrorResponse` got a plain error. | Throw a `KitrError` with the code you mean, or fix the resolver. |
+| `VALIDATION` (422) | `mockValidationError` answered. | Expected: the form should show `fieldErrors`. |
+
+When the browser shows `Failed to register a ServiceWorker` or a 404 for `/mockServiceWorker.js`, the worker file is missing. Run `pnpm mocks:init`.
+
+## Testing
+
+Your handlers are the contract the frontend is built against, so test them like code. This starts the real `app/mocks/handlers.ts` in Node and checks the answers the invoices screen relies on:
+
+```ts
+// app/mocks/handlers.test.ts
+import { setupNodeMocks } from '@kitr/mocks'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { handlers } from './handlers'
+
+const api = 'https://app.acme.com/api'
+let mocks: Awaited<ReturnType<typeof setupNodeMocks>>
+
+beforeAll(async () => {
+  mocks = await setupNodeMocks(handlers)
+})
+afterAll(() => mocks.close())
+
+describe('invoice mocks', () => {
+  it('filters the list by status', async () => {
+    const res = await fetch(`${api}/invoices?status=draft`)
+    expect(await res.json()).toEqual([
+      { id: 'inv_1003', customer: 'Grace', amount: 80, status: 'draft' },
+    ])
+  })
+
+  it('answers 404 in the kitr error shape', async () => {
+    const res = await fetch(`${api}/invoices/inv_9999`)
+    expect(res.status).toBe(404)
+    expect(await res.json()).toEqual({
+      code: 'NOT_FOUND',
+      message: 'Invoice inv_9999 not found',
+      status: 404,
+    })
+  })
+
+  it('adds a created invoice to the list', async () => {
+    const created = await fetch(`${api}/invoices`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ customer: 'Ada', amount: 45 }),
+    })
+    expect(created.status).toBe(201)
+    expect(await created.json()).toEqual({
+      id: 'inv_1004',
+      status: 'draft',
+      customer: 'Ada',
+      amount: 45,
+    })
+
+    const list = (await (await fetch(`${api}/invoices`)).json()) as Array<{ id: string }>
+    expect(list.map((invoice) => invoice.id)).toContain('inv_1004')
+  })
+
+  it('fails loudly for a route nobody mocked', async () => {
+    const res = await fetch(`${api}/invoices/inv_1001`, { method: 'PATCH', body: '{}' })
+    expect(res.status).toBe(501)
+    expect(await res.json()).toMatchObject({ message: 'No mock for invoices.update' })
+  })
+})
+```
+
+The test uses the handlers from [Mock a whole route table](#mock-a-whole-route-table). The third test's invoice stays in the list for the rest of the file; Vitest gives each file a fresh copy.
+
+## Next steps
+
+- [API reference](/packages/mocks/api): every export of `@kitr/mocks`.
+- [Testing](/packages/testing): `createTestApp`, `renderWithKitr` and the API test client.
+- [API](/packages/api): route names and `kitr api:sync`, which feed `mockRoutes`.

package/docs/overview.md

@@ -0,0 +1,63 @@
+---
+title: Overview
+description: Fake your API while you build the frontend or run tests.
+order: 0
+---
+
+# Mocks
+
+## What it is
+
+`@kitr/mocks` fakes your API. Write a handler per endpoint, or hand `mockRoutes()` your route table, and the app's real HTTP client gets realistic responses, including errors in the shape a kitr server sends. Turn them on in development with `VITE_MOCKS=true`, or in Vitest with `setupNodeMocks()`.
+
+Runs in the browser and in tests. To test your own API routes, use [testing](/packages/testing).
+
+## Install
+
+```sh
+kitr add mocks
+```
+
+Adds `@kitr/mocks` and MSW, `app/mocks/handlers.ts`, the service worker in `public/` and `VITE_MOCKS=false` in `.env.example`. No provider. [Every change](/packages/mocks/guide#install).
+
+## Quick start
+
+Add a handler for the request your screen makes:
+
+```ts
+// app/mocks/handlers.ts
+import { HttpResponse, http } from '@kitr/mocks'
+
+export const handlers = [
+  http.get('*/api/me', () =>
+    HttpResponse.json({ id: 'u_ada', email: 'ada@acme.com', name: 'Ada', role: 'admin' }),
+  ),
+  http.get('*/api/invoices', () =>
+    HttpResponse.json([
+      { id: 'inv_1001', customer: 'Grace', amount: 120, status: 'paid' },
+      { id: 'inv_1002', customer: 'Linus', amount: 300, status: 'open' },
+    ]),
+  ),
+]
+```
+
+Set `VITE_MOCKS=true`, restart `kitr dev`, and the page shows the two invoices. The network panel says `from service worker`. `*` matches any origin. Next in the guide: [Fake your first endpoint](/packages/mocks/guide#fake-your-first-endpoint).
+
+## Built on
+
+kitr adds `mockRoutes()`, error responses in kitr's shape and the two setup helpers.
+
+## Problems it solves
+
+- **Building screens before the API exists.** [Fake your first endpoint](/packages/mocks/guide#fake-your-first-endpoint).
+- **Writing one handler per route by hand.** [Mock a whole route table](/packages/mocks/guide#mock-a-whole-route-table).
+- **Error states that are hard to reach.** [Send an error response](/packages/mocks/guide#send-an-error-response).
+- **Tests that hit the network.** [Use mocks in tests](/packages/mocks/guide#use-mocks-in-tests).
+- **Third-party APIs in development.** [Mock a third-party API](/packages/mocks/guide#mock-a-third-party-api).
+
+## Further reading
+
+- [Guide](/packages/mocks/guide).
+- [API reference](/packages/mocks/api).
+- [MSW docs](https://mswjs.io/docs).
+- [Testing](/packages/testing), [API](/packages/api) and [HTTP](/packages/http).

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@kitr/mocks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "@kitr/mocks: MSW handlers from kitr contracts, for dev and tests.",
+  "kitr": {
+    "name": "mocks",
+    "title": "Mocks",
+    "summary": "Fake your API while you build the frontend or run tests.",
+    "category": "dev-tools",
+    "runsOn": "client",
+    "builtOn": [
+      "msw"
+    ],
+    "client": true,
+    "docs": "docs",
+    "setup": "./kitr"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitrjs/kitr.git",
+    "directory": "packages/mocks"
+  },
+  "homepage": "https://kitr.dev/packages/mocks",
+  "bugs": "https://github.com/kitrjs/kitr/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./kitr": {
+      "types": "./dist/kitr.d.ts",
+      "default": "./dist/kitr.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "dependencies": {
+    "@kitr/core": "0.2.1"
+  },
+  "peerDependencies": {
+    "msw": ">=2.0.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.23.7",
+    "typescript": "^5.9.3",
+    "msw": "^3.0.4",
+    "@types/node": "^22.19.0"
+  },
+  "keywords": [
+    "kitr",
+    "kitr-package"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }