@webjsdev/mcp 0.1.6 → 0.1.7

package/resources/agent-docs/configuration.md

@@ -213,7 +213,7 @@ export async function GET() {
 
 ### `onError` hook (APM / Sentry integration point)
 
-Register an error sink via `createRequestHandler({ onError })` (and `startServer({ onError })`). It is called with `(error, { request, requestId, phase })` whenever the request pipeline catches an unhandled error: the 500 path (a thrown route handler / middleware / page render, labeled phase `handle` / `middleware` / `ssr` / `metadata`) or a server action that throws unexpectedly (phase `action`). **The contract is best-effort:** a throwing `onError` is caught and ignored so it can never crash the response, and the hook is purely additive (webjs's existing sanitized 500, with only `error.message` in prod and never the stack, is unchanged). The hook fires BEFORE the sanitized response is sent, so the sink sees the original error. The `requestId` ties the report to the access-log line.
+Register an error sink via `createRequestHandler({ onError })` (and `startServer({ onError })`). It is called with `(error, { request, requestId, phase })` whenever the request pipeline catches an unhandled error: the 500 path (a thrown route handler / middleware / page render, labeled phase `handle` / `middleware` / `ssr` / `metadata`) or a server action that throws unexpectedly (phase `action`). **The contract is best-effort:** a throwing `onError` is caught and ignored so it can never crash the response, and the hook is purely additive (webjs's existing sanitized response is unchanged: a thrown route handler / page render returns a generic 500, and a thrown server action returns a generic message + a correlation `digest` (#749), never the raw message or the stack in prod). The hook fires BEFORE the sanitized response is sent, so the sink sees the original error. The `requestId` ties the report to the access-log line.
 
 ```ts
 const app = await createRequestHandler({

package/resources/agent-docs/framework-dev.md

@@ -28,6 +28,12 @@ This repo uses git worktrees (the review subagents spawn throwaway ones under `.
 
 Because the pin lives in the main worktree's `config.worktree`, `git worktree add` copies it into each linked worktree, so a commit made inside a throwaway review worktree also runs the framework `.hooks/pre-commit`. That is harmless (the hook only blocks main and auto-generates a changelog on a version bump), and review subagents are read-only so they do not commit; the inheritance is noted here only so the behavior is not surprising.
 
+### Merged worktrees are auto-removed (`cleanup-merged-worktree.sh`)
+
+Per-task worktrees pile up when a session merges its PR but never runs `git worktree remove` (a skipped step, or a crash mid-task). The `.claude/hooks/cleanup-merged-worktree.sh` PostToolUse hook (matcher `Bash`, wired in `.claude/settings.json`) closes that gap: after any `gh pr merge`, it sweeps every linked worktree and removes the ones that are safe to drop, so cleanup is deterministic rather than a thing an agent has to remember.
+
+It is conservative. A worktree is removed ONLY when it is a linked (non-primary) checkout, on a non-`main`/`master` branch, whose branch is MERGED (an ancestor of `origin/main`, OR a merged GitHub PR for that head branch, which is how squash-merges are detected via `gh`) AND whose working tree is clean apart from untracked `node_modules` / `.webjs`. It KEEPS anything dirty, unmerged, the primary checkout, or the worktree the merge was run from (you cannot remove your current directory; `cd` out and remove it manually), reporting each kept/removed worktree back to the model via `hookSpecificOutput`. It never blocks the tool (always exits 0). Escape hatch: `WEBJS_NO_WORKTREE_CLEANUP=1`. Regression test: `test/hooks/cleanup-merged-worktree.test.mjs`.
+
 The fix only repairs the LOCAL checkout. Commits and branches are always safe on GitHub regardless.
 
 ---
@@ -56,6 +62,8 @@ npm runs first; if it fails (auth, network, transient registry error), the GitHu
 
 The workflow uses `NPM_TOKEN` (repo secret) and the auto-provisioned `GITHUB_TOKEN`. Free for public repos.
 
+**Update the global CLI after the publish lands.** The maintainer scaffolds and dogfoods with the globally installed `webjs` CLI, which lags a release until refreshed. So once `release.yml` has published (verify `npm view @webjsdev/cli version` matches the released version), run BOTH `npm update -g webjsdev` and `bun add -g webjsdev`. Run them AFTER the publish, never at merge time (they pull the LATEST PUBLISHED version). This is reminded automatically by the `.claude/hooks/release-global-update.sh` PostToolUse hook, which fires when a `chore/release-*` PR merges (escape hatch `WEBJS_NO_RELEASE_GLOBAL_UPDATE=1`, regression test `test/hooks/release-global-update.test.mjs`).
+
 ---
 
 ## Dev error overlay: rich, pushed live over SSE (dev-only) (#264)

package/resources/agent-docs/orm.md

@@ -0,0 +1,198 @@
+# ORM: the Drizzle query surface (rc.3)
+
+The scaffold pins **`drizzle-orm@^1.0.0-rc.3`** (`db/columns.server.ts` header
+records this, research #562). rc.3 is the 1.0 release candidate with the new
+Relational Query Builder v2 (RQBv2) wired up in `db/connection.server.ts` via
+`drizzle({ client, relations })`. Several method overloads that older Drizzle
+tutorials rely on do NOT exist in rc.3, so training-data patterns from
+Drizzle 0.29 through 0.36 trip real TypeScript errors here. This page codifies
+the shapes that compile against the installed version.
+
+Ground rules for this version.
+
+1. **Reads go through the relational query API** (`db.query.<table>.findFirst`
+   / `.findMany`), not `db.select().from()`. Relations are pre-registered in
+   `db/connection.server.ts`, so `with` joins work with zero boilerplate.
+2. **`db.select()` takes no argument in rc.3.** The projection overload
+   (`db.select({ ... })`) was removed. Passing a projection object is a
+   `TS2554` compile error.
+3. **`.returning()` takes no argument in rc.3.** It always returns the full
+   inserted / updated / deleted rows (columns only, no relations). Passing a
+   field object is a `TS2554` compile error.
+
+All examples assume the scaffold imports.
+
+```ts
+import { eq, and, inArray, desc } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { posts, users } from '#db/schema.server.ts';
+```
+
+These belong in a `*.server.ts` query or action (never a page or component,
+invariant 1). Reads live in `modules/<feature>/queries/*.server.ts`, mutations
+in `modules/<feature>/actions/*.server.ts`, one function per file.
+
+---
+
+## Reads: use the relational query API
+
+`db.query.<table>` reads a whole row by default, filters with a **plain object**
+`where` (the RQBv2 shape, not a `sql` expression), orders with an `orderBy`
+object, and pulls relations with `with`. This is the shape every scaffold query
+uses.
+
+```ts
+// RIGHT: single row by a unique column
+const post = await db.query.posts.findFirst({
+  where: { slug: input.slug },
+  with: { author: { columns: { name: true, email: true } } },
+});
+
+// RIGHT: a list, newest first, with a projected column set
+const rows = await db.query.posts.findMany({
+  orderBy: { createdAt: 'desc' },
+  where: { authorId: me.id },
+  columns: { id: true, slug: true, title: true },
+  with: { author: { columns: { name: true } } },
+});
+
+// RIGHT: existence check, pull only the id
+const exists = await db.query.posts.findFirst({
+  where: { slug },
+  columns: { id: true },
+});
+```
+
+The `where` object supports equality directly (`{ slug }`), nested operators
+(`{ createdAt: { gt: cutoff } }`), and `AND` by listing multiple keys. Reach for
+the imported `eq` / `and` / `inArray` operators only on the `db.select` /
+`db.delete` / `db.update` builders below, where the `.where()` clause is an SQL
+expression rather than the RQBv2 object.
+
+### Pitfall: the `db.select({ ... })` projection overload is gone
+
+Older Drizzle let you project columns by passing an object to `select`. rc.3
+removed that overload, so the argument no longer type-checks.
+
+```ts
+// WRONG (rc.3): TS2554 "Expected 0 arguments, but got 1"
+const rows = await db
+  .select({ id: posts.id, title: posts.title })
+  .from(posts);
+```
+
+If you genuinely need the query-builder (a manual join, a `groupBy`, an
+aggregate the RQB does not express), call `select` with **no arguments** to get
+the full row, then narrow in JS.
+
+```ts
+// RIGHT: full-row select, no projection argument
+const rows = await db.select().from(posts).where(eq(posts.authorId, me.id));
+```
+
+For anything the relational API covers (by-id lookups, ordered lists, relation
+joins, column subsets), prefer `db.query.*`. It is the shorter, typed,
+relation-aware path and it sidesteps the removed overload entirely.
+
+---
+
+## Mutations: `insert` / `update` / `delete` with a no-arg `.returning()`
+
+Mutations use the query-builder, filter with the imported SQL operators, and
+read back rows with `.returning()`. In rc.3 `.returning()` has **only the
+no-argument overload**, so it yields the full row set every time.
+
+```ts
+// RIGHT: insert, read back the created row
+const [row] = await db
+  .insert(posts)
+  .values({ title, body, slug, authorId: me.id })
+  .returning();
+
+// RIGHT: update by id, read back the updated row
+const [row] = await db
+  .update(posts)
+  .set({ title, body })
+  .where(eq(posts.id, id))
+  .returning();
+
+// RIGHT: delete by id (no read-back needed)
+await db.delete(posts).where(eq(posts.id, id));
+```
+
+### Pitfall: `.returning({ ... })` with a field argument
+
+The older field-selecting `.returning({ id: posts.id })` overload does not exist
+in rc.3.
+
+```ts
+// WRONG (rc.3): TS2554 "Expected 0 arguments, but got 1"
+const [row] = await db
+  .insert(posts)
+  .values({ title, body, slug, authorId: me.id })
+  .returning({ id: posts.id, slug: posts.slug });
+```
+
+Call `.returning()` bare and destructure or map the fields you need in JS.
+
+```ts
+// RIGHT: full row back, then pick fields
+const [row] = await db.insert(posts).values({ ... }).returning();
+const created = { id: row.id, slug: row.slug };
+```
+
+### `.returning()` yields columns only, never relations
+
+A `.returning()` row is the table's own columns. It does NOT carry `with`
+relations the way a `db.query.*` read does. When the caller expects a joined
+shape (an author name alongside the post), insert then re-read, or splice the
+already-known related value in by hand.
+
+```ts
+// RIGHT: insert returns columns; add the known author locally
+const [row] = await db.insert(posts).values({ title, body, slug, authorId: me.id }).returning();
+return { success: true, data: { ...formatPost(row), authorName: me.name } };
+```
+
+---
+
+## Column helpers live in `db/columns.server.ts` (the one dialect seam)
+
+The schema is written against helpers (`table`, `pk`, `uuidPk`, `uuid`, `bool`,
+`timestamp`, `createdAt`, `updatedAt`, `index`) rather than raw drizzle
+builders, so the same `db/schema.server.ts` runs on SQLite and Postgres. Only
+`db/columns.server.ts` differs per dialect. Two of those helpers exist because
+rc.3 has not yet exposed a stable no-arg overload.
+
+- **`table`** wraps `sqliteTableCreator((name) => name, 'snake_case')`. In rc.3
+  the snake_case casing lives on the table factory, so column keys map to
+  snake_case SQL names automatically. Do not restate a `snake_case` casing
+  option on `drizzle()`.
+- **`index(...cols)`** wraps rc.3's `index(name)`, which still requires a name
+  argument the runtime auto-fills. The helper synthesizes drizzle-kit's own
+  collision-free name, so schema authors call `index(t.createdAt)` with no name.
+  Replace it with a bare `index()` once 1.0 stable ships the no-arg overload.
+
+When you add a table, use the helpers (`pk()` for an integer autoincrement id,
+`uuidPk()` for an app-generated uuid string id, `createdAt()` for a
+default-to-now timestamp) rather than reaching for raw `integer(...).primaryKey(...)`
+call sites, so the Postgres swap stays a one-file change.
+
+---
+
+## Where each query shape belongs
+
+| Task | API | File |
+|---|---|---|
+| Row by unique column | `db.query.t.findFirst({ where })` | `queries/*.server.ts` |
+| Ordered / filtered list | `db.query.t.findMany({ orderBy, where, with })` | `queries/*.server.ts` |
+| Manual join / aggregate | `db.select().from(t)` (no projection arg) | `queries/*.server.ts` |
+| Create | `db.insert(t).values(...).returning()` | `actions/*.server.ts` |
+| Update | `db.update(t).set(...).where(eq(...)).returning()` | `actions/*.server.ts` |
+| Delete | `db.delete(t).where(eq(...))` | `actions/*.server.ts` |
+
+Cross-references. Derived row TYPES and the `ActionResult<T>` envelope belong in
+a browser-safe `modules/<feature>/types.ts` (see `agent-docs/types-and-mutations.md`).
+Full page / action / query recipes live in `agent-docs/recipes.md`. The
+server-only boundary that keeps `db` off the client is in the root `AGENTS.md`
+(invariant 1).

package/resources/agent-docs/recipes.md

@@ -407,6 +407,142 @@ for `fetch` + a JS submit handler would break the no-JS baseline. Use a
 See `agent-docs/advanced.md` for the client-router side (how the enhanced
 303/422 swap works) and the rest of the form-submission behavior.
 
+## Snappy UX: Form mutation with Optimistic UI updates
+
+When building interactive applications (like a Todo app, chat app, or likes toggle), using Optimistic UI creates a Snappy UX by immediately updating the UI state in the browser before the server confirms the operation. **Default to `optimistic()` from `@webjsdev/core` for every mutation where the client can predict the result.** Only skip it when the result is unpredictable (AI-generated content), the user must wait for side effects (payment, email), or the mutation is destructive with no undo.
+
+To support progressive enhancement, write a baseline `<form>` that works without JS, then enhance the component in the browser using JS.
+
+### Optimistic UI Recipe
+
+1. **The Server Action**:
+   Create a standard server action that performs the database write and returns the new database entity.
+
+   ```ts
+   // modules/todos/actions/create-todo.server.ts
+   'use server';
+   import { db } from '../../../db/connection.server.ts';
+   import { todos } from '../../../db/schema.server.ts';
+
+   export async function createTodo(input: { title: string }) {
+     const title = String(input.title || '').trim();
+     if (!title) return { success: false, error: 'Title is required', status: 400 };
+     
+     const [todo] = await db.insert(todos).values({ title, completed: false }).returning();
+     return { success: true, data: todo };
+   }
+   ```
+
+2. **The Component with `optimistic()` (preferred)**:
+   Use the declarative `optimistic(host, { source, update })` API. It tracks a queue of pending updates, computes the combined value via a reducer, and auto-releases when the promise settles. No try-catch, no manual rollback, no temp-ID bookkeeping.
+
+   ```ts
+   // components/todo-list.ts
+   import { html, WebComponent, prop, optimistic } from '@webjsdev/core';
+   import { createTodo } from '../modules/todos/actions/create-todo.server.ts';
+   import { Todo } from '../modules/todos/types.ts';
+
+   export class TodoList extends WebComponent({
+     todos: prop<Todo[]>(Array),
+   }) {
+     private optimisticTodos = optimistic(this, {
+       source: () => this.todos,
+       update: (state, title: string) => [
+         ...state,
+         { id: crypto.randomUUID() as any, title, completed: false, pending: true },
+       ],
+     });
+
+     async handleSubmit(e: SubmitEvent) {
+       e.preventDefault();
+       const form = e.target as HTMLFormElement;
+       const title = String(new FormData(form).get('title') || '').trim();
+       if (!title) return;
+
+       form.reset();
+
+       const promise = createTodo({ title });
+       this.optimisticTodos.add(title, promise);
+
+       const result = await promise;
+       if (result.success && result.data) {
+         this.todos = [
+           ...this.todos.filter(t => t.pending),
+           result.data,
+           ...this.todos.filter(t => !t.pending),
+         ];
+       }
+     }
+
+     render() {
+       return html`
+         <form @submit=${this.handleSubmit}>
+           <input type="text" name="title" placeholder="New todo..." required />
+           <button type="submit">Add</button>
+         </form>
+
+         <ul>
+           ${this.optimisticTodos.value.map(
+             (todo) => html`
+               <li class=${todo.pending ? 'opacity-50 pointer-events-none' : ''}>
+                 ${todo.title}
+               </li>
+             `
+           )}
+         </ul>
+       `;
+     }
+   }
+   TodoList.register('todo-list');
+   ```
+
+   For simple boolean flips, the imperative `optimistic(signal, value, action)` is cleaner:
+
+   ```ts
+   import { signal, optimistic } from '@webjsdev/core';
+   import { likePost } from '#actions/like-post.server.ts';
+
+   const liked = signal(false);
+   // in an @click handler:
+   await optimistic(liked, true, () => likePost(postId));
+   ```
+
+3. **Manual optimistic (when you cannot use `optimistic()`)**:
+   If you need fine-grained control (custom loading states, partial rollbacks, multi-step reconciliation), write the manual pattern:
+
+   - Declare a reactive property to hold the list.
+   - Generate a temporary ID, construct the optimistic item, update state immediately.
+   - Run the server action.
+   - Reconcile: replace the optimistic item on success, revert on failure.
+
+   ```ts
+   async handleSubmit(e: SubmitEvent) {
+     e.preventDefault();
+     const form = e.target as HTMLFormElement;
+     const title = String(new FormData(form).get('title') || '').trim();
+     if (!title) return;
+     form.reset();
+
+     const tempId = `temp-${crypto.randomUUID()}`;
+     const previousTodos = this.todos;
+     this.todos = [
+       { id: tempId as any, title, completed: false, pending: true },
+       ...this.todos,
+     ];
+
+     try {
+       const result = await createTodo({ title });
+       if (result.success && result.data) {
+         this.todos = this.todos.map((t) => (t.id === tempId ? result.data! : t));
+       } else {
+         this.todos = previousTodos;
+       }
+     } catch {
+       this.todos = previousTodos;
+     }
+   }
+   ```
+
 ## Receive and persist an uploaded file
 
 A file upload is just a `<form enctype="multipart/form-data">` posting to a page

package/resources/agent-docs/runtime.md

@@ -13,7 +13,7 @@ user-facing reference is the docs-site page `/docs/runtime`; keep the two in syn
 |---|---|---|
 | Install | `npm install` (required) | `bun install` (required, like Node) |
 | Run | `npm run dev` / `npm run start` | `bun run dev` / `bun run start` |
-| Listener | `node:http` shell | native `Bun.serve` (about 1.9x req/s on the listening path) |
+| Listener | `node:http` shell | native `Bun.serve` (about 1.9x req/s on the LISTENING PATH only, a trivial-handler microbenchmark, NOT end-to-end: for a real SSR page the render dominates and the delta is small, see `scripts/bench-listener.mjs`) |
 | TS strip | built-in `module.stripTypeScriptTypes` | `amaro` (byte-identical, position-preserving) |
 | SQLite | built-in `node:sqlite` + `drizzle-orm/node-sqlite` | built-in `bun:sqlite` + `drizzle-orm/bun-sqlite` |
 | Hot reload | `node --watch` | `bun --hot` |

package/resources/agent-docs/service-worker.md

@@ -39,7 +39,11 @@ and emit `<script nonce="${cspNonce()}">…`.
 ## What the worker does (scope + strategy)
 
 Registered from `/sw.js`, the worker's scope is the site root (`/`), so it sees
-every navigation and same-origin asset request.
+every navigation and same-origin asset request. Your worker file lives at
+`public/sw.js`, and although most `public/*` assets serve at `/public/<name>`,
+the framework serves this one (and `public/offline.html`) at the SITE ROOT with a
+`Service-Worker-Allowed: /` header, so `register('/sw.js')` resolves to a 200 and
+the worker controls the whole origin (#830).
 
 - **Navigations are network-first.** The worker always tries the network first,
   so the user sees fresh server-rendered HTML, and caches each successful page

package/resources/agent-docs/testing.md

@@ -24,7 +24,7 @@ app work.
 | Kind | Location | What it does | Runner |
 |---|---|---|---|
 | **unit + integration** (node) | `test/<feature>/<name>.test.{js,ts,mjs}` | Imports modules and asserts. No spawned process, no network. Includes both true unit tests and in-process integration. | `node --test` |
-| **browser** | `test/<feature>/browser/<name>.test.js` | Runs in real Chromium with Playwright. Real DOM, events, `adoptedStyleSheets`, `IntersectionObserver`, shadow / light DOM. | web-test-runner (`wtr`) |
+| **browser** | `test/<feature>/browser/<name>.test.js` | Runs in real Chromium, Firefox, AND WebKit via Playwright (#774). Real DOM, events, `adoptedStyleSheets`, `IntersectionObserver`, shadow / light DOM. WebKit is the engine behind the iOS-only repaint bugs (the #610 class), so it runs in CI now, not just by hand on-device. | web-test-runner (`wtr`) |
 | **e2e** | `test/<feature>/e2e/<name>.test.{ts,mjs}` | Boots a real process (dev server, CLI binary) and drives it through its public interface (HTTP, browser, stdout). Opt in with `WEBJS_E2E=1`. | `node --test` (driver) |
 | **smoke** | `test/<feature>/smoke/<name>.test.{js,ts}` | Fast deploy-time sanity check. A subset of e2e in spirit, kept separate so it runs on every deploy. | `node --test` |
 
@@ -33,6 +33,35 @@ Some packages will only have one or two of these kinds (e.g.
 a kind subfolder when there's at least one test of that kind.
 Empty `e2e/` folders are anti-patterns.
 
+### App browser tests import your REAL components (#806)
+
+In a scaffolded app, a browser test (`test/<feature>/browser/<name>.test.js`)
+can `import` your real `.ts` components, **including ones that call a
+`'use server'` action**, and they load in a real browser. `webjs test --browser`
+runs each test through the same pipeline as `webjs dev`: the `.ts` is type-
+stripped, a `.server.ts` action import is rewritten to its RPC stub, `#` aliases
+and `@webjsdev/core` resolve via the injected importmap. So you write:
+
+```js
+// test/todos/browser/todo-list.test.js
+import { ssrFixture } from '@webjsdev/core/testing';
+import { html } from '@webjsdev/core';
+
+suite('todo-list', () => {
+  test('adds a row', async () => {
+    await import('../../../components/todo-list.ts'); // imports create-todo.server.ts
+    const el = await ssrFixture(html`<todo-list></todo-list>`);
+    el.querySelector('button')?.click();              // fires the action RPC
+    // assert on the DOM...
+  });
+});
+```
+
+The wiring lives in the scaffolded `web-test-runner.config.js` (you don't set it
+up). Keep the browser test file itself `.js`; the components + modules it imports
+are `.ts` and are served transformed. This is why a component that talks to the
+server can be tested in a real browser, not just in a node test.
+
 ---
 
 ## Framework layout (this repo)
@@ -99,8 +128,18 @@ package, it goes in that package's `test/`.
 - `npm run test:browser` → `wtr`: globs
   `packages/*/test/**/browser/**/*.test.js` and
   `test/**/browser/**/*.test.js`. The blog browser e2e is
-  excluded (it needs the blog dev server up first).
-- `npm run test:e2e` → `WEBJS_E2E=1 node --test test/e2e/e2e.test.mjs`.
+  excluded (it needs the blog dev server up first). Runs on Chromium,
+  Firefox, and WebKit concurrently; narrow to one engine for a fast local
+  loop with `WEBJS_BROWSERS=chromium npx wtr` (comma-separate for a subset).
+- `npm run test:e2e` → `WEBJS_E2E=1 node --test test/e2e/e2e.test.mjs`. In CI
+  this runs as two PARALLEL jobs (#774): the Node-served suite (the required
+  merge-gate check) and a Bun-served run (`WEBJS_E2E_RUNTIME=bun`) in a
+  separate `e2e-bun` job, so the cross-runtime e2e no longer serializes behind
+  the Node run.
+- `npm run test:coverage` → `WEBJS_COVERAGE=1 npm test`: the node suite with
+  Node's built-in coverage reporter (#774). Opt-in, kept off the default
+  `npm test` so the common path stays fast; excludes test files and the
+  `scripts/` harness so the numbers reflect shipped source.
 - `npm run test:all` runs node + browser (not e2e).
 
 The root drivers above ONLY discover the framework packages and the root
@@ -195,7 +234,7 @@ ui-website ship no test suite yet, so they are not in the job.
 
 ## Component test helpers (`@webjsdev/core/testing`)
 
-`import { fixture, ssrFixture, waitForUpdate, assertNoA11yViolations, click, shadowQuery, shadowQueryAll } from '@webjsdev/core/testing'`. The mount + hydrate + a11y helpers run in the WTR Chromium session (real DOM), thin wrappers over the browser already running.
+`import { fixture, ssrFixture, waitForUpdate, assertNoA11yViolations, click, shadowQuery, shadowQueryAll } from '@webjsdev/core/testing'`. The mount + hydrate + a11y helpers run in the WTR browser session (real DOM, on each of Chromium / Firefox / WebKit), thin wrappers over the browser already running.
 
 ### `fixture()` vs `ssrFixture()`
 
@@ -330,8 +369,9 @@ enforces:
 - **the wire serializer** (a `Date` / `Map` / `BigInt` arg or return is
   genuinely encoded + decoded, not passed by reference),
 - **CSRF** (a missing token is a 403),
-- **prod error sanitization** (a thrown error surfaces as a sanitized
-  message-only payload, never the stack or extra error fields).
+- **prod error sanitization** (#749: a thrown error surfaces as a GENERIC
+  message plus a correlation `digest`, never the raw message, stack, or extra
+  error fields; the thrown error carries `.digest`).
 
 So `invokeActionForTest` catches a serializer / CSRF / error-sanitization
 regression a direct import cannot see. For the negative cases (assert a 403 on
@@ -406,6 +446,7 @@ a feature, the test is probably testing too many things at once.
   Kind is a child of feature, not the other way around.
 - **Don't create empty kind folders.** If `e2e/` has no tests
   yet, leave it absent.
+- **Don't attempt to run full browser-based tests (WTR/Playwright) inside headless VM sandboxes** if they lack compiler transformation plugins (e.g. for TypeScript components or RPC action stubbing) or have missing native browser OS libraries. Instead, extract components' reconciliation or optimistic UI update logic into pure, browser-safe utilities and cover them using server-side Node.js unit tests.
 - **Don't put package-only tests under root `test/`.** It hurts
   the per-package `npm test --workspace=…` workflow.
 - **Don't import from another package's `test/` directory.**

package/resources/agent-docs/types-and-mutations.md

@@ -0,0 +1,171 @@
+# Types and mutations: sharing server-derived shapes with the browser
+
+An interactive component that ships to the browser almost always needs the
+shape of the data it renders (`Todo`, `Post`, the `ActionResult<T>` envelope a
+mutation returns). Those shapes are DERIVED from server-only modules (the
+Drizzle schema, the action files), so the reflex is to import them straight from
+`db/schema.server.ts` or a `*.server.ts` action. That reflex pins a server
+module to a browser closure and breaks the build. This page codifies where the
+types live so a shipping component consumes them safely.
+
+The one rule. **A type crossing to the browser is a TYPE, never a runtime
+value.** Keep the shape in a browser-safe `modules/<feature>/types.ts` with no
+runtime import from a `.server.ts` file or from `db/`. A `import type { ... }`
+is erased by the TypeScript stripper before the module reaches the browser, so
+it is safe. A plain `import { ... }` (a value import) is NOT erased, so it pins
+the server module and trips the `no-server-import-in-browser-module` check.
+
+---
+
+## Why a value import breaks and a type import does not
+
+webjs strips TypeScript at runtime with no bundler. The stripper erases every
+`import type` and every type-only specifier, so those imports never exist in the
+served JavaScript. A value import survives stripping and becomes a real browser
+`import`. When the target is a `.server.ts` module, its browser stub throws at
+module load (invariant 1), and the `no-server-import-in-browser-module` check
+flags it statically for any module the framework determines actually ships.
+
+```ts
+// SAFE: type-only, erased before it reaches the browser.
+import type { Post } from '#db/schema.server.ts';
+
+// UNSAFE: a runtime value import of the server schema. Survives stripping,
+// pins db/schema.server.ts into the browser closure, throws at load.
+import { posts } from '#db/schema.server.ts';
+```
+
+The subtle trap is deriving a type from a value with a value import. `typeof
+posts.$inferSelect` needs the `posts` binding, and `import { posts }` is a value
+import even though you only use it at the type level. Write `import type` (rc.3
+schemas already `export type Post = typeof posts.$inferSelect`, so import the
+ready-made type), or hand-write the DTO in `types.ts`.
+
+---
+
+## The wrong chain: a types module re-exporting a runtime value
+
+The classic failure is a `types.ts` that looks type-only but carries a runtime
+re-export. A browser-shipped page or component imports it, and the whole server
+schema is dragged along.
+
+```ts
+// modules/posts/types.ts   WRONG
+// A star or value re-export carries the runtime `posts`, `users` table
+// bindings, not just their types.
+export * from '#db/schema.server.ts';           // re-exports VALUES
+export { posts } from '#db/schema.server.ts';    // re-exports a VALUE
+```
+
+```ts
+// components/post-card.ts   (an interactive component, ships to the browser)
+import type { Post } from '#modules/posts/types.ts';
+// Because types.ts value-re-exports the schema, the browser module graph now
+// reaches db/schema.server.ts. no-server-import-in-browser-module fails, and
+// at runtime the server stub throws the moment post-card.ts loads.
+```
+
+The check fires on the component (a shipping browser module), even though the
+mistake is in `types.ts`. The re-export made a server value reachable from a
+browser closure.
+
+---
+
+## The right chain: a browser-safe DTO in `types.ts`
+
+Define the wire shape as a plain interface (or a `type`) in `types.ts` with no
+runtime import. This is the DTO the query / action returns and the component
+consumes. It has zero server dependency, so it crosses the boundary freely.
+
+```ts
+// modules/posts/types.ts   RIGHT
+// A hand-written DTO. No import from db/ or any *.server.ts. Pure types.
+export type PostFormatted = {
+  id: number;
+  slug: string;
+  title: string;
+  body: string;
+  authorId: number;
+  authorName: string | null;
+  createdAt: string;   // serialized for the wire
+};
+
+export type CreatePostInput = { title: string; body: string };
+
+// The mutation envelope every action returns. Browser-safe, no server import.
+export type ActionResult<T> =
+  | { success: true; data?: T; redirect?: string }
+  | { success: false; error?: string; fieldErrors?: Record<string, string>;
+      values?: Record<string, string>; status?: number };
+```
+
+```ts
+// modules/posts/queries/list-posts.server.ts   (server: may touch db)
+import { db } from '#db/connection.server.ts';
+import type { PostFormatted } from '#modules/posts/types.ts';
+export async function listPosts(): Promise<PostFormatted[]> {
+  const rows = await db.query.posts.findMany({ orderBy: { createdAt: 'desc' } });
+  return rows.map(formatPost);   // maps the row to the DTO
+}
+```
+
+```ts
+// components/post-card.ts   (browser: consumes the DTO type only)
+import type { PostFormatted } from '#modules/posts/types.ts';
+```
+
+If you want the DTO to track the schema automatically rather than restating it,
+use a **type-only** derivation and keep it in `types.ts`.
+
+```ts
+// modules/posts/types.ts   RIGHT (type-only derivation, still erased)
+import type { Post } from '#db/schema.server.ts';   // type-only, erased
+export type PostFormatted = Omit<Post, 'createdAt'> & { createdAt: string };
+```
+
+Either form ships nothing server-side to the browser. The `import type` is the
+seam. A value import is the leak.
+
+---
+
+## Carrier choice: register an interactive component in `layout.ts`
+
+An interactive component reaches the browser because SOME module imports it and
+that module ships. A `page.ts` and a `layout.ts` never hydrate, but they DO load
+in the browser to register the components they import. When a page's ONLY reason
+to ship is registering a component, prefer registering that component in
+`app/layout.ts` (or a section layout), not `app/page.ts`.
+
+The reason is elision economics. A `page.ts` whose sole client job is
+registering a component is dropped by the framework, and the browser fetches the
+component leaf directly (the import-only page optimization). But when you have a
+component shared across a section (a header search box, a theme toggle, a cart
+button), the layout is the natural single carrier. Register it once there and
+every page under it gets the upgraded element with no per-page import.
+
+```ts
+// app/layout.ts   RIGHT: the section carrier registers shared interactive UI
+import '#components/theme-toggle.ts';   // registers <theme-toggle> for every page
+import '#components/ui/dialog.ts';      // registers the Tier-2 <ui-dialog> element
+
+export default function RootLayout({ children }) {
+  return html`... <theme-toggle></theme-toggle> ${children} ...`;
+}
+```
+
+```ts
+// app/page.ts   RIGHT: page stays a pure server function, no client import
+export default function Home() {
+  return html`<h1>Home</h1><theme-toggle></theme-toggle>`;   // tag already registered by the layout
+}
+```
+
+Register in `page.ts` only when the component is page-specific (used on that one
+route). A shared element registered per page duplicates the import intent across
+routes and muddies which module is the carrier. Keep pages pure server functions
+where you can, and let the nearest layout carry the shared interactive tags.
+
+Cross-references. The server-only boundary and the type-only-import exception
+are invariant 1 in the root `AGENTS.md`. The Drizzle query surface that produces
+these rows is in `agent-docs/orm.md`. The optimistic mutation flow that consumes
+`ActionResult<T>` on the client is in `agent-docs/advanced.md`.