@webjsdev/mcp 0.1.5 → 0.1.7

package/resources/agent-docs/components.md

@@ -59,7 +59,7 @@ class Dialog extends WebComponent({
 }
 ```
 
-Set defaults in the constructor after `super()`. A declarative `default` option also exists (lit-parity, a function default runs per instance for a fresh object / array), but the constructor is the recommended way. **Never** use a class-field initializer (e.g., `count = 0` or `student: Student = { ... }`): the framework installs reactive getter/setter on `this` inside the constructor via `Object.defineProperty`, and a class-field initializer compiles to an assignment after `super()` that uses `[[Define]]` to overwrite the accessor, silently breaking reactivity. The `reactive-props-no-class-field` rule catches this.
+Set defaults in the constructor after `super()`. A declarative `default` option also exists (lit-parity, a function default runs per instance for a fresh object / array), but the constructor is the recommended way. **Never** use a class-field declaration OR initializer (e.g., `count = 0`, `student: Student = { ... }`, or `todos!: Todo[]`): even a type-only declaration like `todos!: Todo[]` compiles under modern TS configurations (with `useDefineForClassFields: true`) to define a property on the instance after `super()`, which shadows and clobbers the prototype's reactive accessor, silently breaking reactivity. Only declare properties in the factory, and read/write them directly off `this`. The `reactive-props-no-class-field` rule catches this.
 
 ```ts
 // set defaults in the constructor after super()
@@ -96,7 +96,7 @@ The SSR pipeline runs the **pre-render value-deriving hooks** before `render()`:
 
 For component-local state, create an instance signal in the constructor and call `signal.set(...)` to mutate. The built-in `SignalWatcher` re-runs `render()` on the next microtask; the same lifecycle hooks fire as for reactive-property changes.
 
-See [`/docs/lifecycle`](https://docs.webjs.com/docs/lifecycle) for per-hook usage examples.
+See [`/docs/lifecycle`](https://docs.webjs.dev/docs/lifecycle) for per-hook usage examples.
 
 ## Async render: bare-await data fetch (#469)
 
@@ -244,10 +244,23 @@ patterns, treat the component as interactive.
 
 The detection lists live in `packages/server/src/component-elision.js`
 and are the single source of truth. They are kept in lockstep with the
-lifecycle table above by `packages/server/test/elision/lifecycle-coverage.test.js`,
-which fails if a new `WebComponent` hook is added without teaching the
-analyser about it. If you add an interactivity feature to the framework,
-update that file.
+framework's interactivity surface by two drift guards, which fail the build
+if a new interactivity feature ships without teaching the analyser about it
+(a silent over-elision otherwise). `packages/server/test/elision/lifecycle-coverage.test.js`
+introspects the live `WebComponent` prototype and covers hooks and methods.
+`packages/server/test/elision/sigil-coverage.test.js` covers the two surfaces
+that are not prototype members: template binding sigils and interactivity
+static fields. The renderers' sigil set is single-sourced in core's
+`BINDING_PREFIXES` (`packages/core/src/binding-prefixes.js`); the analyser
+classifies each sigil as a client-behaviour ship signal (`SSR_DROPPED_PREFIXES`,
+`@event`, drops at SSR) or an SSR-safe round-trip (`ROUND_TRIP_PREFIXES`,
+`.prop` / `?bool`, survives into the served HTML). The guard asserts that
+classification partitions `BINDING_PREFIXES` exactly, so a new sigil cannot be
+added without a deliberate ship-or-round-trip decision. Interactivity static
+fields live in the `INTERACTIVITY_STATIC_FIELDS` registry (`shadow`, `refresh`).
+If you add an interactivity feature to the framework, update the matching list
+in `component-elision.js` (and add a new static convention to both the
+`INTERACTIVITY_STATIC_FIELDS` registry and this lifecycle table).
 
 ## Pages and layouts: keep them carriers, out of the network tab
 
@@ -325,19 +338,28 @@ suggests is the three legitimate shapes: gate the route in
 `'use server'` ACTION (its browser stub is a working RPC, so it is
 exempt), or register the component in a `layout.{ts,js}` so the page
 elides again. Server-to-server imports (`.server.ts` importing
-`.server.ts`) and `middleware.ts` / `route.ts` are never flagged.
+`.server.ts`) and `middleware.ts` / `route.ts` are never flagged. A
+TYPE-ONLY `import type { Row } from './x.server.ts'` is exempt too,
+because the stripper erases it before it reaches the browser, so sharing
+a derived row type from a `.server.ts` is safe (a mixed
+`import { type Row, value }` still ships the runtime `value` binding, so
+it is still flagged).
 
 The rule covers every module the build ships, not just pages: a shipping
 component, and `error.{ts,js}` / `loading.{ts,js}` / `not-found.{ts,js}`
 modules, are checked too. Those three boundaries always ship and are
 never elided (only an elidable component import is ever stripped), so a
 personalized 404 that does `await auth()` is the same throw-at-load crash
-and is flagged. One known gap: a DYNAMIC `import('./x.server.ts')` is not
-caught, because the framework's import scanner tracks only static
-`import` / `export … from`, not the `import(` call form. That is
-consistent with the rest of the framework (a dynamic import is also not
-elided framework-wide, and its crash is deferred to call time, not module
-load), so the rule leaves it to the runtime.
+and is flagged. Scope note for dynamic imports: a string-literal
+`import('./widget.ts')` IS tracked by the authorization gate (#751), so a
+lazily-imported app module is servable instead of 404ing, but it is kept
+out of elision and the modulepreload set (a dynamic import is lazy by
+author intent, fetched at call time). The `no-server-import-in-browser-module`
+rule still operates on STATIC edges only, so a dynamic
+`import('./x.server.ts')` of a no-`'use server'` utility is not flagged at
+check time, its throw-at-load is deferred to call time; and a computed
+`import(expr)` cannot be resolved statically, so `webjs check` warns on it
+in a shipping module (it would 404 if it targets an app module).
 
 ### Turning elision off
 

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

@@ -11,9 +11,9 @@ user-facing reference is the docs-site page `/docs/runtime`; keep the two in syn
 
 | Area | Node 24+ | Bun |
 |---|---|---|
-| Install | `npm install` (required) | optional (zero-install via Bun auto-install) |
+| 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` |
@@ -29,52 +29,26 @@ correctness (the modulepreload hints still ship in the document head).
 `webjs create <name>` defaults to Node. `webjs create <name> --runtime bun` (or
 `bun create webjs <name>`, auto-detected from the invoking package manager,
 #541) emits a Bun-flavored app: `bun.lock`, a pure `oven/bun:1` Dockerfile +
-bun-install CI, bun-command agent docs, and the zero-install bootstrap below.
-`--runtime` is orthogonal to `--template`.
+bun-install CI, and bun-command agent docs. `--runtime` is orthogonal to
+`--template`.
 
-## Bun zero-install (#675)
+## Bun
 
-A Bun app's `dev` / `start` / `db` scripts run through a generated app-local
-`webjs-bun.mjs` bootstrap under `bun --bun`:
+A Bun app installs with `bun install` (like Node), then its `dev` / `start` /
+`db` scripts force `bun --bun` so the server runs on Bun:
 
-```js
-// webjs-bun.mjs
-await import('@webjsdev/cli/bin/webjs.js');
+```sh
+bun install
+bun run dev      # or: bun run start
 ```
 
-`bun --bun` overrides the `webjs` bin's Node shebang so the server runs on Bun;
-importing the CLI by bare specifier lets Bun auto-install resolve `@webjsdev/*`
-and the app's deps on demand, so a fresh app serves with **no `bun install`**.
-The CLI's `start` is in-process and `dev` re-execs via `process.execPath` (which
-is `bun` here), so the server stays on Bun once the CLI does. `bunx
-@webjsdev/cli` is deliberately NOT used (it runs on Node via the shebang AND
-eager-installs the whole tree). The `start.before` migrate also routes through
-the bootstrap, so the boot-time `webjs db migrate` needs no `webjs` bin in
-`node_modules`. `bun install` stays optional: run it for editor type
-intelligence (no `node_modules` means no local type files) or a pinned offline
-install. The Node-targeted tooling scripts (`test` / `check` / `typecheck`)
-stay plain `webjs` on Node and still expect an install.
-
-**Version pinning (#685).** Bun's auto-install fetches `latest` for a bare
-`import 'zod'`, ignoring package.json and `bun.lock` (it consults neither the
-manifest, the lockfile, nor an `onResolve` plugin, verified in #684). webjs
-closes that gap with an `onLoad` transform: it rewrites a declared dep's bare
-specifier to an inline-versioned one (`zod` to `zod@3.22.4`), which Bun's
-auto-install DOES honor. The version is the EXACT one from `bun.lock` when
-present, else an exact `package.json` pin. Bun resolves an exact inline version
-but ENOENTs on a range or dist-tag (`zod@^3`, `zod@latest`), so a dep declared
-as a RANGE without a `bun.lock` is left bare and resolves to latest as before:
-commit a `bun.lock` (or pin exact versions) to get pinned zero-install. The
-rewrite is server-runtime only (it shapes what Bun fetches for SSR and server
-actions). The browser is still served bare specifiers resolved via the importmap
-/ jspm, unchanged. Only declared deps are rewritten (a transitive dep follows
-from its pinned parent's manifest), and it is a no-op when `node_modules` exists
-(Bun uses the installed copy). Default on. Opt out with `WEBJS_PIN=0` or
-`{ "webjs": { "pin": false } }`.
-
-**Reproducibility:** dev resolves on demand (now at the pinned versions), and the
-scaffold's Bun Dockerfile still keeps an explicit `bun install` so a prod image
-is immutable and self-contained with no registry fetch at boot.
+`bun --bun` overrides the `webjs` bin's Node shebang so the server runs on Bun
+(selecting the native `Bun.serve` listener and `amaro` type stripping); the app's
+deps resolve from `node_modules`, the same as Node. The `start.before` migrate
+(`webjs db migrate`) runs under Bun too. Commit a `bun.lock` (the Bun analog of
+`package-lock.json`) for reproducible, offline installs; the scaffold's Bun
+Dockerfile runs `bun install` and serves via `CMD ["bun", "--bun", "run",
+"start"]`.
 
 ## SQLite busy_timeout (#674)
 

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