@webjsdev/mcp 0.1.2 → 0.1.4

package/resources/agent-docs/lit-muscle-memory-gotchas.md

@@ -77,14 +77,14 @@ lit form unless the vanilla API is genuinely unavoidable.
 
 | Vanilla muscle memory | Lit-style webjs form |
 |---|---|
-| `this.getAttribute('x')` / `this.hasAttribute('x')` for own config | a reactive prop: `static properties = { x: {...} }` + `declare x`, read `this.x` (the prop rides the `x` attribute) |
+| `this.getAttribute('x')` / `this.hasAttribute('x')` for own config | a reactive prop declared in the factory: `extends WebComponent({ x: String })`, read `this.x` (the prop rides the `x` attribute) |
 | `this.setAttribute('x', v)` / `removeAttribute` to reflect own state | a reactive prop with `reflect: true`, or for non-attribute state a `signal` |
 | `state: true` reactive prop for internal state | a `signal` (instance signal in the constructor, or module-scope) |
 | `this.classList.add/toggle(...)` on self | a `class=${...}` binding in `render()` |
 | `this.innerHTML = ...` / `appendChild` / `document.createElement` | return the markup from `render()` as `` html`...` `` |
 | `this.addEventListener('click', ...)` on own/child elements | a `@click=${...}` binding in the template |
 | `this.querySelector(...)` to reach own rendered DOM | the `ref()` directive + `createRef()`, or read a `<form>` with `new FormData(form)` |
-| manual `observedAttributes` + `attributeChangedCallback` | `static properties` (the framework derives both) |
+| manual `observedAttributes` + `attributeChangedCallback` | a factory-declared reactive prop `WebComponent({ ... })` (the framework derives both) |
 | manual `customElements.define('x', C)` | `C.register('x')` |
 
 Emitting an event with `this.dispatchEvent(new CustomEvent(...))` is the
@@ -244,8 +244,8 @@ the event methods (`addEventListener` / `removeEventListener` /
 `dispatchEvent`), and `this.attachInternals()` ARE backed by a server shim,
 so reading an attribute in `render()`, wiring a delegated listener in the
 constructor, or reflecting a property during the SSR update cycle all work.
-Reading attributes that drive render through a reactive property
-(`static properties` + `declare`) is still the idiomatic path, but
+Reading attributes that drive render through a factory-declared reactive
+property (`WebComponent({ ... })`) is still the idiomatic path, but
 `this.hasAttribute(...)` no longer crashes.
 
 Two guards catch the browser-only cases. `webjs check` flags browser
@@ -278,20 +278,20 @@ connectedCallback() {
 
 ### 5. Class-field initializers for reactive properties
 
-This looks fine in TypeScript. It silently breaks the framework's
-accessor.
+In Lit, class-field initializers (like `student: Student = { name: '', email: '' }`) are commonly used. In webjs, the base class installs reactive accessors on `this` inside the constructor via `Object.defineProperty` (to support SSR property hydration and signals). Under modern V8 class-field semantics, a class-field initializer compiles to an assignment after `super()`, which uses `[[Define]]` and overwrites the accessor, silently breaking reactivity. The footgun is still live with factory-declared props, so it stays a gotcha.
 
-```ts
-// wrong (the initializer overwrites the framework accessor after super())
-class StudentCard extends WebComponent {
-  static properties = { student: { type: Object } };
-  student: Student = { name: '', email: '' };
-}
+The fix is to declare the prop in the base-class factory `WebComponent({ ... })` (which types it automatically, no `declare` line) and set its default via the `default` option or in the constructor after `super()`, never as a class-field initializer:
 
-// right
-class StudentCard extends WebComponent {
-  static properties = { student: { type: Object } };
-  declare student: Student;
+```ts
+// default via the option (a function default = fresh object per instance)
+class StudentCard extends WebComponent({
+  student: prop<Student>(Object, { default: () => ({ name: '', email: '' }) }),
+}) {}
+
+// or set the default in the constructor (fully typed, no declare needed)
+class StudentCard extends WebComponent({
+  student: prop<Student>(Object),
+}) {
   constructor() {
     super();
     this.student = { name: '', email: '' };
@@ -299,17 +299,11 @@ class StudentCard extends WebComponent {
 }
 ```
 
-`webjs check` flags this via the `reactive-props-use-declare` rule, but
-AI agents emit the broken form on autopilot. The convention check is
-the safety net, not the primary defense. Authoring code should use
-`declare` plus constructor defaults from the start.
+`webjs check` flags a class-field initializer on a factory-declared prop via the `reactive-props-no-class-field` rule.
 
-### 6. The `@property()` decorator
+### 6. The `@property()` decorator and a direct `static properties` block
 
-Banned by framework invariant 10 (erasable TS). The replacement is
-`static properties = { ... }` plus a matching `declare` for the typed
-accessor, as shown above. Decorators are non-erasable, so they would
-force the framework to depend on a build step.
+The `@property()` decorator is banned by framework invariant 10 (erasable TS): decorators are non-erasable, so they would force the framework to depend on a build step. A direct `static properties = { ... }` block is also gone, and webjs THROWS at runtime if a class body declares one (flagged by the `no-static-properties` rule). The single replacement for both is the declare-free base-class factory `WebComponent({ ... })` (the `prop()` helper carries options), as shown above.
 
 ## Patterns that produce different visual output
 
@@ -463,8 +457,8 @@ must move with it, use `repeat()` with a stable key.
 | `Task` for client-time async | `Task` (no change, that's its job) |
 | `window.X` or `document.X` in constructor or `render()` | Move to `connectedCallback` |
 | Top-level `import` of browser-only library | Dynamic `import()` inside `connectedCallback` |
-| `student: Student = { ... }` field initializer | `declare student: Student` plus constructor default |
-| `@property()` decorator | `static properties = { ... }` plus `declare` |
+| `student: Student = { ... }` field initializer | Base-class factory `WebComponent({ student: Object })`, default via the `default` option or the constructor |
+| `@property()` decorator / `static properties` block | Base-class factory `WebComponent({ ... })` (the `prop()` helper carries options) |
 | `static styles = css` / inline `<style>` with semantic class names in a light-DOM component | Tailwind utilities (the default); or `static shadow = true` for genuinely scoped CSS |
 | Plain `.map()` for an interactive/stateful list | Works (reconciles in place, keeps node identity); use `repeat(items, key, t)` only when the list **reorders** |
 | `willUpdate` for SSR-visible derived state | Works (runs at SSR); keep it a pure derivation |

package/resources/agent-docs/recipes.md

@@ -13,41 +13,36 @@ schema with the real domain models, then build features on top. This is the
 transition agents most often get wrong, so it is the first recipe.
 
 > **Two non-negotiables.** NEVER leave the example `User` model in
-> `schema.prisma` if the app does not actually have users (delete or replace
-> it). NEVER persist app data in JSON files (`data/todos.json`, `db.json`), in
-> a module-scope array or `Map`, or in `localStorage`. Those reset on every
-> reload and cannot scale. Every piece of stored data is a Prisma model.
-
-1. **Edit `prisma/schema.prisma`** to the real domain. Replace the example
-   `User` model with the models the app needs.
-
-   ```prisma
-   // prisma/schema.prisma
-   model Post {
-     id        String   @id @default(cuid())
-     title     String
-     body      String
-     published Boolean  @default(false)
-     createdAt DateTime @default(now())
-   }
-   ```
+> `db/schema.server.ts` if the app does not actually have users (delete or
+> replace it). NEVER persist app data in JSON files (`data/todos.json`,
+> `db.json`), in a module-scope array or `Map`, or in `localStorage`. Those
+> reset on every reload and cannot scale. Every piece of stored data is a
+> Drizzle table.
+
+1. **Edit `db/schema.server.ts`** to the real domain. Replace the example
+   `User` model with the models the app needs (the helpers come from
+   `db/columns.server.ts`).
 
-   Start the dev server with `npm run dev` (the canonical command), NOT a bare
-   `webjs dev`: `npm run dev` runs the `predev` hook (`prisma generate`) first,
-   while `webjs dev` skips it and boots against an ungenerated client. A bare
-   `webjs dev` will now warn and point you back at `npm run dev`, but use the
-   npm script from the start.
+   ```ts
+   // db/schema.server.ts
+   import { table, pk, text, bool, createdAt, index } from './columns.server.ts';
+   export const posts = table('posts', {
+     id: pk(),
+     title: text().notNull(),
+     body: text().notNull(),
+     published: bool().notNull().default(false),
+     createdAt: createdAt(),
+   }, (t) => [index(t.createdAt)]);
+   ```
 
-2. **Migrate.** Run the npm script (not the `webjs`/`prisma` binary directly,
-   so the `predev` / `db:*` hooks fire):
+2. **Generate + migrate.** Drizzle has no codegen; `generate` turns the schema
+   into SQL, `migrate` applies it:
 
    ```sh
-   npm run db:migrate -- --name add_post
+   npm run db:generate      # schema -> SQL migration (drizzle-kit)
+   npm run db:migrate       # apply it to the dev SQLite database
    ```
 
-   This creates the migration, applies it to the dev SQLite database, and
-   regenerates the Prisma client.
-
 3. **Generate one query and one action per operation**, one exported function
    per file, named after the file, under the feature module. Reads go in
    `queries/`, mutations in `actions/`. Both are `.server.ts` with
@@ -56,27 +51,28 @@ transition agents most often get wrong, so it is the first recipe.
    ```ts
    // modules/posts/queries/list-posts.server.ts
    'use server';
-   import { prisma } from '../../../lib/prisma.server.ts';
+   import { db } from '../../../db/connection.server.ts';
    export async function listPosts() {
-     return prisma.post.findMany({ where: { published: true }, orderBy: { createdAt: 'desc' } });
+     return db.query.posts.findMany({ where: { published: true }, orderBy: { createdAt: 'desc' } });
    }
    ```
 
    ```ts
    // modules/posts/actions/create-post.server.ts
    'use server';
-   import { prisma } from '../../../lib/prisma.server.ts';
+   import { db } from '../../../db/connection.server.ts';
+   import { posts } from '../../../db/schema.server.ts';
    export async function createPost(input: { title: string; body: string }) {
      const title = String(input?.title || '').trim();
      if (!title) return { success: false, error: 'title required', status: 400 };
-     const post = await prisma.post.create({ data: { title, body: String(input?.body || '') } });
+     const [post] = await db.insert(posts).values({ title, body: String(input?.body || '') }).returning();
      return { success: true, data: post };
    }
    ```
 
 4. **Wire it into a page** by calling the query (the page runs on the server,
    so it imports the `.server` query directly and awaits it). Never import
-   `@prisma/client` into a page; reach the database through the query.
+   the DB driver into a page; reach the database through the query.
 
    ```ts
    // app/posts/page.ts
@@ -118,11 +114,13 @@ export default async function User({ params }: { params: { id: string } }) {
 ```ts
 // modules/users/actions/update-profile.server.ts
 'use server';
-import { prisma } from '../../../lib/prisma.server.ts';
+import { eq } from 'drizzle-orm';
+import { db } from '../../../db/connection.server.ts';
+import { users } from '../../../db/schema.server.ts';
 export async function updateProfile(input: { name: string }) {
   const name = String(input?.name || '').trim();
   if (!name) return { success: false, error: 'name required', status: 400 };
-  const row = await prisma.user.update({ where: { id: me.id }, data: { name } });
+  const [row] = await db.update(users).set({ name }).where(eq(users.id, me.id)).returning();
   return { success: true, data: row };
 }
 ```
@@ -143,7 +141,8 @@ validator is a plain function (or a three-line zod adapter).
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
-import { prisma } from '../../../lib/prisma.server.ts';
+import { db } from '../../../db/connection.server.ts';
+import { posts } from '../../../db/schema.server.ts';
 
 // the validator: receives the action's FIRST argument
 export const validate = (input: any) => {
@@ -157,7 +156,7 @@ export const validate = (input: any) => {
 
 // the action body: runs ONLY when validation passes
 export async function createPost(input: { title: string; body: string }) {
-  const row = await prisma.post.create({ data: input });
+  const [row] = await db.insert(posts).values(input).returning();
   return { success: true, data: row };
 }
 ```
@@ -201,6 +200,53 @@ option: `export const POST = route(createPost, { validate })`. A
 validator that THROWS (the classic `Schema.parse` style) becomes a 400, and a
 non-envelope return transforms the input.
 
+## HTTP verbs, caching, streaming, and cancellation (#488, #489, #490, #492)
+
+A `'use server'` action is a POST by default. Reserved sibling exports, read
+statically (the same way a page reads `export const revalidate`), change its
+HTTP semantics WITHOUT changing the call site (you still write `await
+getUser(7)`). One callable function per configured file (a second callable is a
+`webjs check` error).
+
+```ts
+// modules/users/queries/get-user.server.ts: a cached, tagged GET read
+'use server';
+export const method = 'GET';                       // absent = POST
+export const cache = 60;                            // seconds, or { maxAge, swr, public }
+export const tags = (id: number) => ['user:' + id];
+export async function getUser(id: number) { return db.query.users.findFirst({ where: { id } }); }
+```
+
+```ts
+// a mutation evicts the tags it touches
+'use server';
+export const invalidates = (id: number) => ['user:' + id];
+export const middleware = [requireAuth];           // #490: async (ctx, next) => result; actionContext()
+export async function updateUser(id: number, patch: Partial<User>) { /* ... */ }
+```
+
+- A **GET** rides args in the URL (POST fallback over a 4KB cap), is CSRF-exempt,
+  and carries `Cache-Control` + a weak `ETag` (304 on `If-None-Match`) +
+  `X-Webjs-Tags`. A **mutation** (POST/PUT/PATCH/DELETE) sends the rich body
+  (DELETE rides the URL), is CSRF-protected, and on success evicts its
+  `invalidates` tags and reports them via `X-Webjs-Invalidate`. A method mismatch
+  is a `405` + `Allow`.
+- **SAFETY:** `cache` with `public: true` SHARES one response across all users,
+  keyed only by URL + args. Use it ONLY for data identical for every visitor (the
+  same rule as a page's `export const revalidate`).
+- **Streaming (#489):** return a `ReadableStream` / async iterable / async
+  generator (any verb) and the call site does `for await (const c of await
+  streamTokens(8))`. Each chunk is rich-serialized as yielded, back-pressured,
+  and the source is cancelled on disconnect. A streamed result is never cached /
+  ETagged / seeded.
+- **Cancellation (#492):** read the request `AbortSignal` via `actionSignal()`
+  (from `@webjsdev/server`) to stop work on disconnect; a superseded client
+  `async render()` auto-aborts the previous in-flight fetch.
+- **SSR seeding (#472):** an action result invoked during a non-streamed SSR
+  render is serialized into the page; the stub reads that seed on its first client
+  call, so a shipping component does not re-fetch on hydration (consume-once,
+  fail-open; opt out with `"webjs": { "seed": false }`).
+
 ## Add a component
 
 ```ts
@@ -218,9 +264,7 @@ A leaf component fetches its own server data into the first paint, co-located, w
 
 ```ts
 // (a) blocking async render: real data in the first paint, the common case
-class UserProfile extends WebComponent {
-  static properties = { uid: { type: String } };
-  declare uid: string;
+class UserProfile extends WebComponent({ uid: String }) {
   async render() {
     const u = await getUser(this.uid);
     return html`<h3>${u.name}</h3>`;
@@ -236,9 +280,7 @@ html`
 `;
 
 // (c) renderFallback() = the CLIENT re-fetch loading state (never the first paint)
-class UserActivity extends WebComponent {
-  static properties = { uid: { type: String } };
-  declare uid: string;
+class UserActivity extends WebComponent({ uid: String }) {
   renderFallback() { return html`<div class="skeleton h-24"></div>`; }
   async render() {
     const items = await getActivity(this.uid);
@@ -410,7 +452,9 @@ the user-supplied filename as a key; `generateKey` makes an opaque one.
 // modules/avatar/actions/save-avatar.server.ts
 'use server';
 import { getFileStore, generateKey } from '@webjsdev/server';
-import { prisma } from '../../../lib/prisma.server.ts';
+import { eq } from 'drizzle-orm';
+import { db } from '../../../db/connection.server.ts';
+import { users } from '../../../db/schema.server.ts';
 
 export async function saveAvatar(file: File) {
   const key = generateKey(file.name);                // <uuid>.<ext>, safe
@@ -419,7 +463,7 @@ export async function saveAvatar(file: File) {
     await getFileStore().delete(key);
     return { success: false, fieldErrors: { avatar: 'Max 5 MB' }, status: 422 };
   }
-  await prisma.user.update({ where: { id: 'me' }, data: { avatarKey: key } });
+  await db.update(users).set({ avatarKey: key }).where(eq(users.id, 'me'));
   return { success: true, data: { key, contentType } };
 }
 ```

package/resources/agent-docs/testing.md

@@ -108,6 +108,51 @@ cross-package suite (`packages/*/test/` + `test/`). They do NOT walk the in-repo
 apps' own test dirs (`website/test/`, `examples/blog/test/`), so those run from
 each app's OWN `webjs test` script, not the root runner.
 
+### The Bun test matrix (#509)
+
+webjs runs on Node 24+ or Bun (#508). The **Node suite (`npm test`) is the
+source of truth**; a separate, additive **Bun matrix** re-runs the
+runtime-sensitive suite under Bun to catch the long tail of cross-runtime
+incompatibilities (a `node:*` API Bun implements differently, a crypto/stream
+edge case, an error-message-format quirk).
+
+- `node scripts/run-bun-tests.js` (needs `bun` on PATH; `BUN=…` overrides) runs
+  the `node:test` files under `test/`, `packages/core/test/`, and
+  `packages/server/test/` (excluding `browser/`, `e2e/`, the network-bound
+  `vendor/`) file by file via `bun test <file>`, and CLASSIFIES each result:
+  **pass**, **skip(node-only)** (a documented file that asserts Node-only
+  behavior or trips a Bun-test-runner quirk, listed with a reason in the
+  script's `DENYLIST`, its Bun behavior covered elsewhere), **skip(harness)**
+  (a Bun `node:test` compat gap, auto-detected by error signature),
+  **skip(env)** (needs Redis / a DOM), and **genuine fail** (a real Bun
+  failure, which fails the job). Set `WEBJS_BUN_TESTS=<substr,…>` to scope a
+  local run.
+- CI runs it in the `bun` job alongside `test/bun/smoke.mjs` (#508) and
+  `test/bun/listener.mjs` (#511, the listener-shell parity).
+- Two cross-runtime test scripts also run under BOTH runtimes: `test/bun/smoke.mjs`
+  (boot + SSR + TS strip + a server-action RPC) and `test/bun/listener.mjs`
+  (`startServer` over a real socket: SSR + route + SSE + WebSocket). Plain assert
+  scripts (not `node:test`) so the same file runs identically on each runtime.
+
+**Dev hot-reload of server modules (cross-runtime, #514).** webjs's dev server
+re-imports a `route.ts` / `.server.ts` / page module per request with a
+`?t=<timestamp>` query cache-bust to pick up edits. Node honors that query and
+re-imports, so under `node --watch` an edit is picked up live. Bun's ESM loader
+IGNORES the query string and exposes no module-eviction API, so that mechanism
+alone leaves a server-side edit stale on Bun. The CLI closes the gap by
+re-execing `webjs dev` under `bun --hot` on Bun (vs `node --watch` on Node),
+whose file-watching cache invalidation makes the next re-import fresh with no
+restart (`Bun.serve` is reused across hot reloads, so the listener is not
+duplicated). The cross-runtime test `test/bun/dev-hot-reload.mjs` proves the
+edit-picked-up behaviour on BOTH runtimes (and runs as a dedicated CI step on
+Bun). The `api` dev-cache-bust UNIT test asserts the bare server-level `?t=`
+mechanism directly (no supervisor), which Bun ignores by design, so it stays on
+the Bun-matrix denylist; the user-facing hot reload it underpins is covered on
+Bun by the dev-hot-reload script instead. A `--no-hot` flag opts out of the
+supervisor on either runtime (run the server in-process, edits need a manual
+restart). Component / page / layout SOURCE edits already hot-reload on both
+runtimes (the served `.ts`/`.js` is read from disk per request, not imported).
+
 ### In-repo app tests in CI (#342)
 
 Each in-repo app (`website`, `examples/blog`) carries its own test suite under
@@ -116,7 +161,7 @@ its `test/` dir and runs it through its own `webjs test` script (the website's
 not discover these, so a dedicated `.github/workflows/ci.yml` job, **In-repo app
 tests (website + blog)**, runs `npm test --workspace=@webjsdev/website` and
 `npm test --workspace=@webjsdev/example-blog` (with Playwright installed for the
-website browser tests and the Prisma DB prepared for the blog, the same setup
+website browser tests and the SQLite DB prepared for the blog, the same setup
 the `unit` + `e2e` jobs use). It is a required status check, so a regression in
 an app's tests gates the merge. The app test dirs are not walked by the root
 runner, so the framework-package tests never double-run. `docs` and the
@@ -307,8 +352,8 @@ test/
 
 App-side runners:
 
-- `webjs test` → node tests (everything not under `browser/` or `e2e/`).
-- `webjs test --browser` → web-test-runner against `test/**/browser/**`.
+- `webjs test` → the runtime's test runner over everything not under `browser/` or `e2e/` (#570): `node --test` on Node, `bun test` on Bun (dispatched on `process.versions.bun`, since `bun --test` is invalid).
+- `webjs test --browser` → web-test-runner against `test/**/browser/**` (the app's resolved `wtr` bin, spawned with the current runtime, no `npx`).
 - `WEBJS_E2E=1 webjs test` adds e2e.
 
 App AI agents read this convention through the scaffold's

package/resources/agent-docs/typescript.md

@@ -6,12 +6,13 @@ run is part of the user-visible workflow, no separate build step:
 
 - **Editor** (VS Code) runs the TypeScript language server continuously. Red-squiggle on wrong types, including non-erasable syntax (see below).
 - **CI** (optional) runs `tsc --noEmit` against `tsconfig.json`. Type-check only. Also catches non-erasable syntax via `erasableSyntaxOnly`.
-- **Dev + prod server** (runtime, both directions): Node 24+'s built-in TypeScript type-stripping handles server-side `.ts` imports automatically (`process.features.typescript === 'strip'`). Browser-bound `.ts` requests go through `module.stripTypeScriptTypes` on the dev server, which performs whitespace replacement: every (line, column) in the source maps to the same position in the stripped output, so no sourcemap needs to be shipped and stack traces are byte-exact. The transform is cached by mtime (~microseconds per cache hit). Implementation backing: Node ships the [`amaro`](https://github.com/nodejs/amaro) package internally, which wraps SWC's WASM TypeScript transform in a position-preserving strip-only mode. If the framework ever needs to run on a non-Node runtime (Bun, Deno) we will install `amaro` directly or an equivalent position-preserving stripper (Sucrase preserves lines but not columns; SWC's strip mode also works).
+- **Dev + prod server** (runtime, both directions): the runtime's TypeScript type-stripping handles server-side `.ts` imports automatically (on Node, `process.features.typescript === 'strip'`; Bun runs `.ts` natively). Browser-bound `.ts` requests go through the pluggable stripper in `packages/server/src/ts-strip.js` (#508) on the dev server, which performs whitespace replacement: every (line, column) in the source maps to the same position in the stripped output, so no sourcemap needs to be shipped and stack traces are byte-exact. The transform is cached by mtime (~microseconds per cache hit). Implementation backing: on **Node 24+** it is the built-in `module.stripTypeScriptTypes` (which itself wraps the [`amaro`](https://github.com/nodejs/amaro) package, SWC's WASM TypeScript transform in position-preserving strip-only mode); on **Bun** (no such built-in) it is `amaro` loaded directly, an `optionalDependency` of `@webjsdev/server`, producing byte-identical output. `WEBJS_TS_STRIPPER=builtin|amaro` forces a backend. Edge runtimes without a filesystem are a separate, later target.
 
 ## TypeScript feature support: erasable only
 
-The framework uses Node 24+'s built-in `module.stripTypeScriptTypes`,
-which only supports **erasable TypeScript**: type annotations,
+The framework strips with Node 24+'s built-in `module.stripTypeScriptTypes`
+(or `amaro` on Bun, the same engine), which only supports **erasable
+TypeScript**: type annotations,
 `interface`, `type`, `declare`, generics, `import type`, `as` casts,
 and `satisfies`. Non-erasable syntax is rejected.
 
@@ -62,15 +63,15 @@ off so you catch the configuration drift before runtime.
 
 ## Import convention
 
-Use explicit `.ts` extensions in imports. Node 24+'s built-in
-type-stripping and the dev server's HTTP handler both key on the
+Use explicit `.ts` extensions in imports. The runtime's type-stripping
+and the dev server's HTTP handler both key on the
 file URL ending in `.ts` / `.mts`. For mixed codebases, `.js` imports
 that point at a `.ts` sibling also resolve in the dev server. Still
 prefer explicit `.ts`.
 
 ```ts
 // modules/posts/queries/list-posts.server.ts
-import { prisma } from '../../../lib/prisma.js';         // JS file unchanged
+import { db } from '../../../db/connection.server.js';   // .js specifier resolves the .ts sibling
 import { formatPost } from '../utils/slugify.ts';         // TS file
 ```
 
@@ -385,7 +386,7 @@ A single plugin with its OWN in-template intelligence (no Lit dependency; the `w
 Gives you, inside `` html`` `` templates:
 - **Go-to-definition** from `<my-counter>` to the class registered via `MyCounter.register('my-counter')`, from an attribute / property / event name to its class member, and from a CSS class in `class="…"` to its `` css`` `` rule.
 - **Completions**: reachable custom-element tag names after `<`, and binding-aware attribute completions: `.` offers property names, plain / `?` offer hyphenated attribute names (`maxLength` → `max-length`), `@event` is permissive.
-- **Diagnostics**: attribute / property value type-checks (`<my-counter .count=${expr}>` assignability-checks `typeof expr` against `declare count: T`; `@click=${fn}` must be callable), unquoted `@`/`.`/`?` bindings (invariant 4), and expressionless `.prop` bindings.
+- **Diagnostics**: attribute / property value type-checks (`<my-counter .count=${expr}>` assignability-checks `typeof expr` against the property's type from the `WebComponent({ count: Number })` factory shape, and `@click=${fn}` must be callable), unquoted `@`/`.`/`?` bindings (invariant 4), and expressionless `.prop` bindings.
 - **Hover**: a tag shows its component class; an attribute / property / event shows its declared type.
 
 Every feature is gated on import-graph reachability: a tag is recognized only if the file registering it is reachable from the file you're editing. There is deliberately no blanket "unknown tag / attribute" diagnostic (webjs has no element type map, so it would false-positive on third-party custom elements).

package/src/mcp-docs.js

@@ -333,11 +333,13 @@ const PROMPT_BODIES = {
     '```ts',
     '// modules/<feature>/actions/<name>.server.ts',
     "'use server';",
-    "import { prisma } from '../../../lib/prisma.server.ts';",
+    "import { db } from '../../../db/connection.server.ts';",
+    "import { things } from '../../../db/schema.server.ts';",
     'export async function doThing(input: { name: string }) {',
     "  const name = String(input?.name || '').trim();",
     "  if (!name) return { success: false, error: 'name required', status: 400 };",
-    '  return { success: true, data: await prisma.thing.create({ data: { name } }) };',
+    '  const [row] = await db.insert(things).values({ name }).returning();',
+    '  return { success: true, data: row };',
     '}',
     '```',
     '',
@@ -363,16 +365,14 @@ const PROMPT_BODIES = {
     'Tag MUST contain a hyphen (invariant 3). Event/property/boolean holes are',
     'unquoted (invariant 4). Read `webjs-docs://lit-muscle-memory-gotchas` first:',
     'a class-field initializer that overwrites a reactive accessor breaks reactivity',
-    '(use `declare` + `static properties`).',
+    '(declare reactive props via the `extends WebComponent({ … })` factory).',
   ].join('\n'),
   fetch_data_in_component: [
     'Fetch server data IN the component that needs it, with an async render() (#469).',
     'No prop-drilling: SSR awaits the render, so the DATA is in the first paint.',
     '',
     '```ts',
-    'class UserProfile extends WebComponent {',
-    '  static properties = { uid: { type: String } };',
-    '  declare uid: string;',
+    'class UserProfile extends WebComponent({ uid: String }) {',
     '  async render() {',
     '    const u = await getUser(this.uid); // a `use server` action: real fn at SSR, RPC stub on the client',
     '    return html`<h3>${u.name}</h3>`;',

package/src/mcp.js

@@ -155,7 +155,7 @@ const TOOL_DEFS = [
 /**
  * Lexically extract the names exported from a module source. Recognises the
  * common forms a server-action / route file uses without LOADING the module
- * (loading would run its top-level side effects: Prisma init, DB connects).
+ * (loading would run its top-level side effects: DB init, connections).
  *
  *   export async function foo() {}   export function foo() {}
  *   export const foo = ...           export let/var foo = ...
@@ -216,7 +216,7 @@ export function extractRouteMethods(src) {
 /**
  * Lexically extract the HTTP-verb action config declared as reserved sibling
  * exports in a `'use server'` file (#488). Reads source text only (no module
- * load) so there are no DB-init or Prisma side effects.
+ * load) so there are no DB-init side effects.
  *
  * Returned shape:
  *   {
@@ -343,7 +343,7 @@ export function makeToolRunners(deps) {
 
     async list_actions(appDir) {
       // buildActionIndex is a pure file -> hash mapping that imports no module,
-      // so this stays truly read-only (no Prisma/DB init, and no stray stdout
+      // so this stays truly read-only (no DB init, and no stray stdout
       // from a loaded module corrupting the JSON-RPC channel). The RPC hash is
       // over the file path only, so no module load is needed.
       const idx = await buildActionIndex(appDir, false);