@webjsdev/mcp 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "The webjs Model Context Protocol server: live app introspection (routes / actions / components / check) plus the framework knowledge layer (docs, recipes, source) for AI coding agents",
   "bin": {

package/resources/AGENTS.md

@@ -14,10 +14,9 @@ reference there.
 | `agent-docs/components.md` | WebComponent deep-dive (controllers, hooks, light/shadow DOM, slots) |
 | `agent-docs/styling.md` | Tailwind helpers + vanilla-CSS opt-out conventions |
 | `agent-docs/built-ins.md` | Auth, sessions, env vars, caching (cache(), HTTP cache, asset-hash, conditional GET), rate-limit, broadcast, file storage |
-| `agent-docs/configuration.md` | The `package.json` `"webjs"` block (security headers, CSP, redirects, trailing-slash, basePath, ingress caps) + observability |
+| `agent-docs/configuration.md` | The `package.json` `"webjs"` block (security headers, CSP, redirects, trailing-slash, basePath, ingress caps, dev/start task orchestration) + observability |
 | `agent-docs/advanced.md` | Suspense streaming, performance, bundling, client router (prefetch, frames, view transitions, stream actions), WebSockets |
 | `agent-docs/typescript.md` | TS at runtime + full-stack type safety |
-| `agent-docs/deployment.md` | Production, runtime targets, embedded use |
 | `agent-docs/service-worker.md` | The opt-in progressive-enhancement service worker (`public/sw.js`) |
 | `agent-docs/testing.md` | Unit, browser, convention validation, the `handle()` test harness (`@webjsdev/server/testing`) |
 | `agent-docs/framework-dev.md` | Monorepo dev (only when editing webjs itself): commands, repo-health git config, changelog flow, dev error overlay |
@@ -40,7 +39,7 @@ Claude Code enforces step 1 via `.claude/hooks/guard-branch-context.sh`. Other a
 
 ### Skills are routed deterministically, never skipped
 
-A Skill is model-invoked, so it fires only when the model judges a match. The `.claude/hooks/route-skills.sh` `UserPromptSubmit` hook makes routing deterministic: it keyword-matches each prompt against every skill's documented triggers and injects a directive to invoke the matched skill before other work. Check the available skills and invoke a matching one before starting. Tests in `test/hooks/route-skills.test.mjs`.
+A Skill is model-invoked, so it fires only when the model judges a match. The `.claude/hooks/route-skills.sh` `UserPromptSubmit` hook makes routing deterministic: it keyword-matches each prompt against every skill's documented triggers and injects a directive to invoke the matched skill before other work. Check the available skills and invoke a matching one before starting. The skills themselves are committed under `.claude/skills/` (alongside the hooks), so a fresh clone has both the router and the skills it routes to (no machine-local dependency). Tests in `test/hooks/route-skills.test.mjs`, which also asserts every skill the hook references is committed in-repo.
 
 ### Autonomous mode (sandbox / bypass permissions)
 
@@ -78,7 +77,7 @@ See `agent-docs/framework-dev.md` for monorepo commands, workspace layout, per-f
 
 An **AI-first, web-components-first** framework inspired by NextJs, Lit, and Rails. The component runtime API matches lit (reactive `static properties`, the lit lifecycle hooks, ReactiveControllers, the `lit-html` directive set, `html` / `css` templates) so lit training data transfers directly, but webjs ships its own no-build implementation under `packages/core/src/`. Decorators are the one lit exception (invariant 10); use `declare` + `static properties`.
 
-- **No build step.** Source files are served as native ES modules. JSDoc `.js` is default; `.ts` / `.mts` is stripped via Node 24+'s `module.stripTypeScriptTypes` (invariant 10 + `agent-docs/typescript.md`). Node 24+ is required, enforced by an early `assertNodeVersion()` preflight.
+- **No build step.** Source files are served as native ES modules. JSDoc `.js` is default; `.ts` / `.mts` is stripped through a pluggable stripper (#508): Node 24+'s built-in `module.stripTypeScriptTypes`, or `amaro` on Bun (byte-identical, position-preserving) (invariant 10 + `agent-docs/typescript.md`). **Runs on Node 24+ or Bun** (run a Bun app with `bun --bun run dev` / `start`); the early `assertNodeVersion()` preflight enforces the Node floor and admits Bun. On Bun, `startServer` selects a native `Bun.serve` listener shell instead of the node:http one (skipping the compat bridge for ~1.9x more req/s on the listening path, at near-complete feature parity, the one node-only gap being 103 Early Hints since `Bun.serve` has no informational-response API), via a runtime-neutral seam that also sets up future `Deno.serve` / embedded adapters. Edge runtimes (no filesystem) are a separate, later target.
 - **SSR + CSR by default.** Pages are server-rendered HTML; components render light DOM by default, shadow DOM opt-in via `static shadow = true` with DSD SSR.
 - **Progressive enhancement is the default architecture.** Pages and components are SSR'd; with JS off, content reads, `<a>` navigates, `<form>` server actions submit, display-only elements render. JS is opt-in *per interactive behaviour* (`@click`, a reactive property assignment, a signal mutation). Never write a first paint that depends on hydration; never use `fetch` + JS where a `<form>` + server action would do.
 - **Display-only components are elided from the browser.** A component with no interactivity signal renders identical HTML with or without its JS, so the framework strips its import (and any vendor reachable only through it, importmap entry included) from the served source. Automatic, conservative, verified differentially. Disable with `"webjs": { "elide": false }` or `WEBJS_ELIDE=0`. See `agent-docs/components.md`.
@@ -101,7 +100,7 @@ A page/layout module still **loads** in the browser for its top-level side effec
 
 `route.{js,ts}` is the one routing file that is NOT isomorphic: a server-only HTTP handler (named `GET` / `POST` exports), the webjs equivalent of a Next route handler. It never ships to the client.
 
-**`.server.{js,ts}` is the one server boundary, an RPC + source-protection mechanism, NOT an RSC component.** With `'use server'` exports are RPC-callable (the browser import becomes a stub POSTing to `/__webjs/action/<hash>/<fn>`); without it the file is a server-only utility whose browser import **throws at module load** (Prisma, secrets, `node:*`, hashing). Consequence: **never import a no-`'use server'` util directly into a page, layout, or component** (it works at SSR but the client stub crashes on load); use it inside `'use server'` actions, `route.{js,ts}`, or `middleware`, and reach it from a page by importing a `'use server'` action (whose RPC stub loads safely client-side). This boundary, not a component annotation, is how a dependency is kept off the client (a date library used only during SSR belongs in `lib/format.server.ts`). See `agent-docs/components.md`.
+**`.server.{js,ts}` is the one server boundary, an RPC + source-protection mechanism, NOT an RSC component.** With `'use server'` exports are RPC-callable (the browser import becomes a stub POSTing to `/__webjs/action/<hash>/<fn>`); without it the file is a server-only utility whose browser import **throws at module load** (the DB driver, secrets, `node:*`, hashing). Consequence: **never import a no-`'use server'` util directly into a page, layout, or component** (it works at SSR but the client stub crashes on load); use it inside `'use server'` actions, `route.{js,ts}`, or `middleware`, and reach it from a page by importing a `'use server'` action (whose RPC stub loads safely client-side). This boundary, not a component annotation, is how a dependency is kept off the client (a date library used only during SSR belongs in `lib/format.server.ts`). See `agent-docs/components.md`.
 
 ---
 
@@ -135,7 +134,7 @@ lib/                        app-wide code (lib/*.server.js infra, lib/utils/ bro
 modules/<feature>/          feature-scoped: actions/ (mutations), queries/ (reads), components/, utils/, types.js
 components/*.js             SHARED presentational primitives
 public/*                    static assets, served at /<name>
-prisma/schema.prisma        data models
+db/*.server.{js,ts}         data layer (Drizzle: schema, columns, connection)
 ```
 
 Every file is a plain ES module.
@@ -259,7 +258,7 @@ One custom element per file; call `Class.register('tag')` at module top level. S
 ## Modules architecture (preferred for non-trivial apps)
 
 - **`modules/<feature>/actions/*.server.{js,ts}`** mutations, **`queries/*.server.{js,ts}`** reads (one function per file), **`components/*.{js,ts}`** feature-owned components (shared UI in top-level `components/`), **`utils/*.{js,ts}`** pure helpers (no `'use server'`, no DB), **`types.{js,ts}`** typedefs.
-- **`lib/`** cross-cutting: `lib/*.server.{js,ts}` server-only infra (Prisma, session, hashing), `lib/utils/*` browser-safe helpers, `lib/*.ts` app-wide values.
+- **`lib/`** cross-cutting: `lib/*.server.{js,ts}` server-only infra (session, hashing; the DB connection lives in `db/connection.server.ts`), `lib/utils/*` browser-safe helpers, `lib/*.ts` app-wide values.
 
 ### The `ActionResult<T>` envelope
 
@@ -294,7 +293,7 @@ The advanced client-router surface is in `agent-docs/advanced.md`: **link prefet
 
 > Hit one of these as a runtime error? The [Troubleshooting page](https://docs.webjs.com/docs/troubleshooting) is keyed by symptom (the throw-at-load server import, the backtick-in-template 500, the TypeScript strip failure, the SSR browser-global crash, the missing-frame swap) and maps each back to the invariant and the `webjs check` rule below.
 
-1. **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** The `.server.{js,ts}` extension is the path-level boundary (the file router refuses to serve the source); a `'use server'` directive additionally makes exports RPC-callable, else the file is a server-only utility whose browser import is a throw-at-load stub. Importing `@prisma/client`, `node:*`, or any server-only dep from a component or an `app/**` page / layout / loading / error / not-found file crashes the browser at module load.
+1. **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** The `.server.{js,ts}` extension is the path-level boundary (the file router refuses to serve the source); a `'use server'` directive additionally makes exports RPC-callable, else the file is a server-only utility whose browser import is a throw-at-load stub. Importing a DB driver (`better-sqlite3` / `pg`), `node:*`, or any server-only dep from a component or an `app/**` page / layout / loading / error / not-found file crashes the browser at module load.
 2. **Every `*.server.{js,ts}` file with `'use server'` exports must be `async` functions returning serializer-safe values.** Args and results round-trip via webjs's wire. Files without `'use server'` (server-only utilities) can export anything, including singletons.
 3. **Custom element tag names must contain a hyphen** (HTML spec). Pass the tag to `Class.register('tag-name')`, not a static field. Any short-string quote works: `'tag-name'`, `"tag-name"`, or `` `tag-name` `` (single-line, no interpolation).
 4. **Event (`@`), property (`.`), boolean (`?`) holes in `html` must be unquoted**, e.g. `@click=${fn}`, never `@click="${fn}"`.
@@ -311,17 +310,17 @@ The advanced client-router surface is in `agent-docs/advanced.md`: **link prefet
 
 ## Scaffolding
 
-Three scaffolds exist (do not invent template names): `webjs create <name>` (full-stack: layout, page, components, modules, Prisma+SQLite), `webjs create <name> --template api` (backend-only routes + modules + Prisma, no SSR), `webjs create <name> --template saas` (auth + login/signup + protected dashboard + User model). Pick from the request: default for any product with UI (todo, blog, dashboard, marketplace, social, e-commerce), `api` for an HTTP/JSON API with no UI, `saas` for accounts/login/signup; default to full-stack when ambiguous.
+Three scaffolds exist (do not invent template names): `webjs create <name>` (full-stack: layout, page, components, modules, Drizzle+SQLite), `webjs create <name> --template api` (backend-only routes + modules + Drizzle, no SSR), `webjs create <name> --template saas` (auth + login/signup + protected dashboard + User model). The `--db sqlite|postgres` flag (default sqlite) picks the dialect; the schema/queries/actions are identical across dialects (see #563). Pick from the request: default for any product with UI (todo, blog, dashboard, marketplace, social, e-commerce), `api` for an HTTP/JSON API with no UI, `saas` for accounts/login/signup; default to full-stack when ambiguous.
 
-Rules: **always scaffold via `webjs create`** (never hand-roll). **Default to a real database (Prisma + SQLite); NEVER use JSON files, in-memory arrays, or localStorage for persistence.** Update `prisma/schema.prisma` to real models FIRST, then `webjs db migrate <name>`, then build pages/actions/queries. **Treat the scaffold as REFERENCE, not the final product:** replace the example page / `User` model / components and adapt `app/layout.ts` (brand, nav, content width; the default `<main class="max-w-[760px]">` reading column needs widening for a full-bleed app). ENFORCED: examples carry a `webjs-scaffold-placeholder` comment and `no-scaffold-placeholder` fails until the content is replaced and the marker deleted. Docs at https://docs.webjs.com.
+Rules: **always scaffold via `webjs create`** (never hand-roll). **Default to a real database (Drizzle + SQLite); NEVER use JSON files, in-memory arrays, or localStorage for persistence.** Update `db/schema.server.ts` to real models FIRST, then `webjs db generate` + `webjs db migrate`, then build pages/actions/queries. **Treat the scaffold as REFERENCE, not the final product:** replace the example page / `User` model / components and adapt `app/layout.ts` (brand, nav, content width; the default `<main class="max-w-[760px]">` reading column needs widening for a full-bleed app). ENFORCED: examples carry a `webjs-scaffold-placeholder` comment and `no-scaffold-placeholder` fails until the content is replaced and the marker deleted. Docs at https://docs.webjs.com.
 
 ---
 
 ## CLI reference
 
 ```sh
-webjs dev    [--port N]            # dev server with live reload
-webjs start  [--port N]            # prod server; source IS the runtime, plain HTTP/1.1 (reverse-proxy for TLS + HTTP/2)
+webjs dev    [--port N] [--no-hot] # dev server with live reload (node --watch on Node, bun --hot on Bun). --no-hot runs in-process. Runs webjs.dev.before + webjs.dev.parallel (#550)
+webjs start  [--port N]            # prod server; source IS the runtime, plain HTTP/1.1 (reverse-proxy for TLS + HTTP/2). Runs webjs.start.before first (#550)
 webjs test   [--server] [--browser] [--watch]
 webjs check  [--rules] [--json]    # correctness validator (report-only, no autofix); --json for an agent loop
 webjs mcp                          # read-only MCP: routes, actions (RPC hashes), components, check
@@ -329,19 +328,19 @@ webjs doctor                       # project-health checklist; non-zero exit on
 webjs types                        # generate .webjs/routes.d.ts (typed Route union + per-route params, #258)
 webjs typecheck [tsc args...]      # the project's own tsc --noEmit
 webjs create <name> [--template api|saas]
-webjs db <prisma-subcommand> [...]
+webjs db <generate|migrate|push|studio|seed>   # wraps drizzle-kit (+ runs db/seed.server.ts)
 webjs ui init | add <names...> | list | view <name>
 webjs vendor pin|unpin|list|audit|outdated|update [--from PROVIDER]   # importmap pinning, .webjs/vendor/importmap.json
 ```
 
-`--from PROVIDER` accepts `jspm` (default), `jsdelivr`, `unpkg`, `skypack` and is persisted in the pin file. `PORT` is honoured when `--port` is absent; `webjs dev` emits `routes.d.ts` automatically. Running this repo's own apps (`website/`, `docs/`, `examples/blog/`, `packages/ui/packages/website/`): always `cd` in and use **its** `npm run dev` / `npm start`, never `webjs dev` / `webjs start` directly (each composes extra watchers via `npm`).
+`--from PROVIDER` accepts `jspm` (default), `jsdelivr`, `unpkg`, `skypack` and is persisted in the pin file. `PORT` is honoured when `--port` is absent; `webjs dev` emits `routes.d.ts` automatically. Running this repo's own apps (`website/`, `docs/`, `examples/blog/`, `packages/ui/packages/website/`): `cd` in and use **its** `npm run dev` / `npm start`; as of #550 a bare `webjs dev` / `webjs start` is equivalent (the per-app orchestration moved into the `webjs.dev` / `webjs.start` tasks config, which the primitive runs), so the npm scripts are now just thin aliases.
 
 ---
 
 ## Environment, server config, caching, observability
 
 - **Env vars.** `process.env.X` reads are server-only; `WEBJS_PUBLIC_`-prefixed names are exposed in the browser via an inline `<script>` (no build); `NODE_ENV` is defined both sides. See `agent-docs/built-ins.md`.
-- **The `package.json` `"webjs"` block.** Security headers (on by default, per-path `webjs.headers` overrides), CSP (opt-in nonce, `webjs.csp`), declarative `webjs.redirects` (#254), `webjs.trailingSlash` (#255), `webjs.basePath` (#256), and ingress caps (`maxBodyBytes` / `maxMultipartBytes` / server timeouts). Type it with `WebjsConfig` + the JSON Schema. See `agent-docs/configuration.md`.
+- **The `package.json` `"webjs"` block.** Security headers (on by default, per-path `webjs.headers` overrides), CSP (opt-in nonce, `webjs.csp`), declarative `webjs.redirects` (#254), `webjs.trailingSlash` (#255), `webjs.basePath` (#256), ingress caps (`maxBodyBytes` / `maxMultipartBytes` / server timeouts), and dev/start task orchestration (`webjs.dev.before` / `webjs.dev.parallel` / `webjs.start.before`, #550, the orchestration `webjs dev`/`start` run so they match `npm run dev`/`start`). Type it with `WebjsConfig` + the JSON Schema. See `agent-docs/configuration.md`.
 - **Caching + file storage** (`agent-docs/built-ins.md`). HTTP `Cache-Control`, the `cache()` query helper + `revalidateTag`, the server HTML response cache (`export const revalidate` + `revalidatePath`, #241), content-hash asset URLs (`?v=`, #243), conditional GET (ETag, #240), and `FileStore` + `diskStore` (streaming, traversal-safe, signed URLs, S3-pluggable, #247).
 - **Observability** (`agent-docs/configuration.md`). Access log, `requestId()` + `X-Request-Id`, the `onError` APM hook, `GET /__webjs/version` (#239).
 
@@ -386,11 +385,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 };
 }
 ```
@@ -406,4 +407,4 @@ Not in v1. Do not implement as part of other tasks:
 - **Bundling and per-route code splitting.** webjs is **no-build** (the Rails 7 + importmap model); prod perf comes from HTTP/2 multiplex + `<link rel="modulepreload">` hints, not concatenation. **Do not propose a bundler or `webjs build`.**
 - **Vite-grade HMR with state preservation.** Custom elements only `define` once, so full reload is necessary; data reloads are near-instant via `fs.watch` to SSE.
 - **React Server Components Flight.** Server actions + `Suspense` streaming cover the need.
-- **Edge-runtime bundling / full portability** (see `agent-docs/deployment.md`), **i18n, image optimization** (layer libraries on top).
+- **Edge-runtime bundling / full portability** (deployment guidance lives in the docs site at `/docs/deployment`), **i18n, image optimization** (layer libraries on top).

package/resources/agent-docs/built-ins.md

@@ -13,7 +13,7 @@ layer to debug.
 ```js
 // route handler
 export async function GET() {
-  const posts = await prisma.post.findMany();
+  const posts = await db.query.posts.findMany();
   return new Response(JSON.stringify(posts), {
     headers: {
       'Cache-Control': 'public, max-age=60, stale-while-revalidate=300',
@@ -51,10 +51,10 @@ until the TTL expires:
 // modules/posts/queries/list-posts.server.ts
 'use server';
 import { cache } from '@webjsdev/server';
-import { prisma } from '../../../lib/prisma.server.ts';
+import { db } from '../../../db/connection.server.ts';
 
 export const listPosts = cache(
-  async () => prisma.post.findMany({ orderBy: { createdAt: 'desc' } }),
+  async () => db.query.posts.findMany({ orderBy: { createdAt: 'desc' } }),
   { key: 'posts', ttl: 60 }
 );
 ```
@@ -65,12 +65,12 @@ wrapper), add `tags`. It is either a static `string[]` or a function
 
 ```ts
 export const postById = cache(
-  async (id: string) => prisma.post.findUnique({ where: { id } }),
+  async (id: string) => db.query.posts.findFirst({ where: { id } }),
   { key: 'post', ttl: 300, tags: (id) => ['post:' + id] } // per-entity tag
 );
 
 export const listPosts = cache(
-  async () => prisma.post.findMany(),
+  async () => db.query.posts.findMany(),
   { key: 'posts', ttl: 60, tags: ['posts'] } // static tag
 );
 ```
@@ -83,9 +83,11 @@ no import of the wrapper):
 // modules/comments/actions/create-comment.server.ts
 'use server';
 import { revalidateTag, revalidatePath } from '@webjsdev/server';
+import { db } from '../../../db/connection.server.ts';
+import { comments } from '../../../db/schema.server.ts';
 
 export async function createComment(input) {
-  await prisma.comment.create({ data: input });
+  await db.insert(comments).values(input);
   await revalidateTag('post:' + input.postId); // postById(postId) recomputes
   await revalidateTag('posts');                 // listPosts recomputes
   await revalidatePath('/blog');                // also evict the cached HTML
@@ -163,7 +165,7 @@ Evict on a write with `revalidatePath`:
 import { revalidatePath } from '@webjsdev/server';
 
 export async function publishPost(input) {
-  // ... persist via Prisma ...
+  // ... persist via Drizzle ...
   await revalidatePath('/blog');   // next /blog request re-renders fresh
   return { success: true };
 }
@@ -248,7 +250,7 @@ export const { auth, signIn, signOut, handlers } = createAuth({
   providers: [
     Credentials({
       async authorize(credentials) {
-        const user = await prisma.user.findUnique({ where: { email: credentials.email } });
+        const user = await db.query.users.findFirst({ where: { email: credentials.email } });
         if (!user || !verifyPassword(credentials.password, user.passwordHash)) return null;
         return { id: user.id, name: user.name, email: user.email, role: user.role };
       },

package/resources/agent-docs/components.md

@@ -116,7 +116,9 @@ class Report extends WebComponent {
 
 **Elision (#474).** A **bare** `async render()` (no other client signal, light DOM) is **elided** like any display-only component: the SSR'd data is the complete first paint, so the framework drops the module and the redundant on-hydration re-fetch (a common content / docs leaf shape). It ships only when it ALSO carries an independent signal (an `@event`, a non-`state` reactive prop, a signal / reactive import, a lifecycle hook including `renderFallback()`, a `<slot>`, cross-module observation, or a transitively-reachable interactive child). Two carve-outs always ship. `static shadow = true` ships because Declarative Shadow DOM attaches only during HTML parsing, so a streamed (`<webjs-suspense>`) or soft-navigated shadow component arrives via a JS DOM insertion and needs its module to re-run `attachShadow`. `static refresh = true` is the explicit opt-in to keep the stale-while-revalidate on-load re-fetch that eliding drops (moot for request-stable data, the default; reach for it only when fresh-on-load matters). The only behaviour eliding removes is that on-load refresh; the first paint is byte-identical, verified by the differential-elision guard.
 
-**SSR action seeding (#472).** For a SHIPPING async component (one that hydrates because it carries an interactivity signal), the on-hydration re-fetch is eliminated without eliding the module. Each `'use server'` action result invoked during a (non-streamed) SSR render is serialized into the page as one `<script type="application/json" id="__webjs-seeds">` block, keyed by the action's hash + function name + serialized args. The generated client RPC stub reads that seed on its FIRST call: a hit resolves synchronously (no network, no hydration flicker), a later refetch or arg-change misses (consume-once) and goes to RPC as normal. So `const u = await getUser(this.id)` runs once, server-side, and its result is reused on the client's first render. The capture is a transparent server-side facade over the `'use server'` module (a synchronous `module.registerHooks` load hook wraps each export in a recording `Proxy`), so there is **no source transform and no build step**: the browser source tab and the on-disk files are byte-unchanged, and the RPC stub the browser fetches is the same shape as before (it just consults the seed first). Fail-open by construction: a key miss is always a normal RPC, never wrong data. Default on; opt out with `"webjs": { "seed": false }` or `WEBJS_SEED=0` (then the client re-fetches on hydration, hidden by stale-while-revalidate as before). A soft navigation carries the seed too: the client router ingests the incoming page's payload (`applySwap` -> `scanSeeds`) before its components hydrate, so a navigated async component also skips the refetch. Streamed regions (`<webjs-suspense>`) are NOT seeded (their data resolves after the first flush), so a slow boundary keeps the stale-while-revalidate refetch.
+**SSR action seeding (#472).** For a SHIPPING async component (one that hydrates because it carries an interactivity signal), the on-hydration re-fetch is eliminated without eliding the module. Each `'use server'` action result invoked during a (non-streamed) SSR render is serialized into the page as one `<script type="application/json" id="__webjs-seeds">` block, keyed by the action's hash + function name + serialized args. The generated client RPC stub reads that seed on its FIRST call: a hit resolves synchronously (no network, no hydration flicker), a later refetch or arg-change misses (consume-once) and goes to RPC as normal. So `const u = await getUser(this.id)` runs once, server-side, and its result is reused on the client's first render. The capture is a transparent server-side facade over the `'use server'` module (a synchronous load hook wraps each export in a recording `Proxy`), so there is **no source transform and no build step**: the browser source tab and the on-disk files are byte-unchanged, and the RPC stub the browser fetches is the same shape as before (it just consults the seed first). The install mechanism is runtime-neutral (#529): Node uses `module.registerHooks`, Bun uses a `Bun.plugin` `onLoad` (Bun has no `module.registerHooks`), and both emit the identical seed, so a page seeds the same on either runtime. Fail-open by construction: a key miss is always a normal RPC, never wrong data. Default on; opt out with `"webjs": { "seed": false }` or `WEBJS_SEED=0` (then the client re-fetches on hydration, hidden by stale-while-revalidate as before). A soft navigation carries the seed too: the client router ingests the incoming page's payload (`applySwap` -> `scanSeeds`) before its components hydrate, so a navigated async component also skips the refetch. Streamed regions (`<webjs-suspense>`) are NOT seeded (their data resolves after the first flush), so a slow boundary keeps the stale-while-revalidate refetch.
+
+**Interactivity during a COLD on-hydration re-fetch (#528).** Seeding matters for more than a wasted round trip. When a SHIPPING async component DOES re-fetch on hydration (seeding off via `WEBJS_SEED=0`, a `static refresh = true` leaf, or a seed miss), its FIRST client commit is deferred until that re-fetch resolves, and that commit is the step that binds the component's event listeners. So for the fetch's duration the SSR'd markup is visible but NOT yet interactive: an `@click` does nothing until the data lands (the window equals the action's latency, not a constant). Seeding erases this by resolving the first render synchronously, so the component hydrates and binds its listeners immediately, which is the default and works on both Node and Bun (#529, seeding is no longer Node-only). The component is fully reactive once that first commit lands: this is purely a cold-start window, NOT a lost signal subscription (a bump after the commit re-renders normally). To keep an async leaf interactive from the first paint regardless, give it a synchronous first render (read request-known data from a prop / the constructor) and move the async work to a signal-driven `Task` or an `@event` handler.
 
 ### Streaming a slow region with `<webjs-suspense>` (#471)
 

package/resources/agent-docs/configuration.md

@@ -208,6 +208,37 @@ Returns JSON describing the live build, alongside the `/__webjs/health` and `/__
 
 ---
 
+## Dev/start task orchestration: `webjs.dev` / `webjs.start` (#550)
+
+`webjs dev` and `webjs start` run an app's per-environment orchestration
+themselves, read from the `package.json` `"webjs"` block, so the framework
+primitive is not a degraded run versus `npm run dev` / `npm start`. The npm
+scripts become thin aliases (`"dev": "webjs dev"`), and both forms behave
+identically. This replaces the old `predev` / `prestart` npm hooks +
+`concurrently` watchers (which a bare `webjs dev` silently skipped, #452).
+
+```jsonc
+"webjs": {
+  "dev": {
+    "before":   ["webjs db migrate"],                                  // one-shot, runs to completion first
+    "parallel": ["tailwindcss -i ./public/input.css -o ./public/tailwind.css --watch"]  // long-lived, runs alongside the server
+  },
+  "start": {
+    "before":   ["webjs db migrate"]                                   // one-shot, before serving
+  }
+}
+```
+
+- **`before`** (dev and start): commands run sequentially to completion BEFORE the server boots (the old `predev` / `prestart`: `webjs db migrate`, a registry copy). A non-zero exit ABORTS the boot with a clear message, so a failed migration never serves stale code/schema.
+- **`parallel`** (dev only): long-lived child processes that run ALONGSIDE the server (the old `concurrently` watchers: the Tailwind CLI `--watch`). They are spawned once in the parent (not on every hot-reload restart) and TORN DOWN on exit (SIGINT / SIGTERM / server exit), so a watcher cannot leak past the dev server.
+- Each command runs through a shell, so a normal command line works. An empty / absent block means `webjs dev` / `start` run unchanged, so a plain app with no Tailwind/DB needs no config.
+- The scaffold uses the Tailwind browser runtime (no CSS build step), so it ships only `dev.before` / `start.before` (the Drizzle migration apply); an app that adds the Tailwind CLI puts its `--watch` under `webjs.dev.parallel`. The in-repo apps (`examples/blog`, `website`, `docs`, ui-website) show the Tailwind `parallel` watcher pattern.
+- **Prod note:** `before` runs at boot, so `webjs start` runs `webjs db migrate` in-process to apply pending migrations. Drizzle has no client-codegen step (the schema IS the types, inferred at compile time), so there is nothing to run at image-BUILD time. Authoring a new migration from a schema change is a dev-time `webjs db generate`, committed to source control, not a boot step. So `CMD ["npm", "start"]` and `CMD ["webjs", "start"]` are equivalent.
+
+Read by `readAppTasks` in `packages/cli/lib/app-tasks.js` (pure, unit-tested); orchestrated in `packages/cli/bin/webjs.js` (`runBeforeSteps` / `startParallelTasks`).
+
+---
+
 ## Server port resolution (`--port` / `PORT` / `.env`) (#447)
 
 Both `webjs dev` and `webjs start` resolve the listen port with a single

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

@@ -1,6 +1,6 @@
 # Framework development (editing webjs itself)
 
-Read this only when editing the webjs monorepo (this repo), not a scaffolded app. The repo is buildless: `packages/` is plain `.js` with JSDoc (never add `.ts` there); TypeScript is fine in `examples/`, `docs/`, `website/`. Each in-repo app (`website/`, `docs/`, `examples/blog/`, `packages/ui/packages/website/`) is run via its OWN `npm run dev` / `npm start`, never `webjs dev` directly, since each composes extra watchers. The sections below cover the repo-health git config, the changelog flow, and the dev error overlay.
+Read this only when editing the webjs monorepo (this repo), not a scaffolded app. The repo is buildless: `packages/` is plain `.js` with JSDoc (never add `.ts` there); TypeScript is fine in `examples/`, `docs/`, `website/`. Each in-repo app (`website/`, `docs/`, `examples/blog/`, `packages/ui/packages/website/`) is run from its OWN dir via `npm run dev` / `npm start`; as of #550 a bare `webjs dev` / `webjs start` is equivalent (each app's per-environment orchestration, the Tailwind watcher, `webjs db migrate`, the registry copy, moved into its `webjs.dev` / `webjs.start` tasks config, which `webjs dev`/`start` run). The sections below cover the repo-health git config, the changelog flow, and the dev error overlay.
 
 ---
 

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 };
 }
 ```
@@ -410,7 +409,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 +420,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

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
 ```
 

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 };',
     '}',
     '```',
     '',

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);

package/resources/agent-docs/ssr-partial-nav-design.md

@@ -1,214 +0,0 @@
-# SSR partial navigation: design note
-
-**Status:** SHIPPED (feature/nested-layout-partial-swap, 2026-05-16).
-The mechanism described below is implemented and tested. This document
-is preserved as the design record. Runtime reference for callers lives
-in `agent-docs/advanced.md` (Client router section) and the framework
-API table in `AGENTS.md`.
-
-**Motivating bug (resolved):** ui-website docs sidenav lost scroll on
-every link click because the docs layout sat 2 levels deep under the
-root layout, beyond `findLayoutShell`'s body-direct-child probe.
-**Previous workaround (now deleted):** `app/docs/layout.ts` saved /
-restored `.docs-sidenav` `scrollTop` via `sessionStorage` on every
-`webjs:navigate` event. Removed in the same PR as the framework fix.
-
----
-
-**What actually shipped vs. what's below:**
-- The recommendation in this doc was `<webjs-frame>` as the primary
-  primitive. During design discussion the decision evolved to make
-  layout-marker discovery **auto-derived from folder structure**, so
-  layout authors write nothing. `<webjs-frame>` ships as the escape
-  hatch for non-layout partial-swap regions (rare).
-- The marker format is `<!--wj:children:<segment-path>-->` comment
-  pairs (Remix v3 lineage), not the `<webjs-frame>`-element approach
-  sketched below.
-- Wire-byte optimization, snapshot cache, keyed DOM diff with live-
-  attribute preservation, and per-segment `<template id="wj-loading:...">`
-  cloning all shipped in the same PR (originally deferred as v2+).
-
-The original `<webjs-frame>`-centric sketch below is preserved as
-historical context.
-
----
-
-## Goal
-
-Preserve the DOM of any layout, at any depth, across same-origin navigations. Re-render only the deepest segment that actually changed.
-
-## Non-goals
-
-- Per-segment data fetching (Remix v3 `<Frame src>` style). Wire model stays one SSR response per nav.
-- React-style reconciler with full keyed-DOM diff inside the swap region. Out of scope for v1, can come later.
-- Parallel routes / intercepting routes (Next.js feature). Separate design.
-
-## Background: how the four references handle this
-
-| Framework | Mechanism | Wire format | Scope decided by |
-|---|---|---|---|
-| **Turbo** | `<turbo-frame id="X">` (flat DOM element) | full HTML response, server may optimize via `Turbo-Frame: X` header | Innermost enclosing `<turbo-frame>` of the click (`closest()`) |
-| **Remix v3** | `<!--rmx:f:id-->...<!--/rmx:f-->` comment markers + per-frame `src` | per-frame HTML or `<template id>` streams | Author-declared `<Frame name="...">` + `rmx-target` on link |
-| **Next.js App Router** | Recursive `FlightRouterState` tuple + per-segment `CacheNode` tree | RSC Flight (`react-server-dom-webpack`) | Server walks the tree, returns from divergence point |
-| **Lit Labs** | `Routes` controller with `outlet()` + child controllers via `RoutesConnectedEvent` | full template re-render (no partial scoping) | N/A (full subtree re-render every nav) |
-
-**Closest fit to webjs's current router:** Turbo. webjs already mirrors Turbo Drive (link interception, body swap, `pushState`, `data-no-router` ≡ `data-turbo="false"`).
-
-## Recommendation
-
-Adopt a Turbo-style frame primitive: `<webjs-frame id="...">`. Layouts that want partial-swap behavior wrap their replaceable region:
-
-```ts
-// app/docs/layout.ts
-import { html } from '@webjsdev/core';
-import { sidenav } from './sidenav.ts';
-
-export default function DocsLayout({ children }) {
-  return html`
-    <div class="docs-grid">
-      ${sidenav()}
-      <webjs-frame id="docs-content">${children}</webjs-frame>
-    </div>
-  `;
-}
-```
-
-### Algorithm: `packages/core/src/router-client.js` delta
-
-Existing `findLayoutShell(body)` stays as a fallback. Add `findActiveFrame(linkEl)`:
-
-```js
-function findActiveFrame(linkEl) {
-  // Walk up through shadow boundaries and into light DOM via composedPath at call site.
-  const frame = linkEl.closest('webjs-frame');
-  return frame ? frame.id : null;
-}
-
-async function navigate(url, event) {
-  const frameId = event ? findActiveFrame(event.target) : null;
-
-  const res = await fetch(url, {
-    headers: frameId ? { 'X-Webjs-Frame': frameId } : {},
-  });
-  if (!res.headers.get('content-type')?.startsWith('text/html')) {
-    // existing fallback: full nav
-    window.location.href = url;
-    return;
-  }
-
-  const html = await res.text();
-  const incoming = Document.parseHTMLUnsafe(html);
-
-  // 1. Frame path: preferred if active frame exists in both.
-  if (frameId) {
-    const target = document.querySelector(`webjs-frame#${CSS.escape(frameId)}`);
-    const source = incoming.querySelector(`webjs-frame#${CSS.escape(frameId)}`);
-    if (target && source) {
-      target.replaceChildren(...source.childNodes);
-      mergeHead(incoming.head);
-      runFrameScripts(target);
-      customElements.upgrade(target);
-      history.pushState({}, '', url);
-      document.dispatchEvent(new CustomEvent('webjs:navigate', { detail: { url, frameId } }));
-      return;
-    }
-  }
-
-  // 2. Existing layout-shell path (one level deep).
-  const shell = findLayoutShell(document.body);
-  const incomingShell = shell ? findLayoutShell(incoming.body) : null;
-  if (shell && incomingShell && shellsMatch(shell, incomingShell)) {
-    swapShellContent(shell, incomingShell);
-    /* existing path... */
-    return;
-  }
-
-  // 3. Full body swap (existing fallback).
-  document.body.replaceChildren(...incoming.body.childNodes);
-  /* existing path... */
-}
-```
-
-That's the entire detection delta: a `querySelector` keyed by the active frame's id, with the existing logic preserved as fallback.
-
-### `<webjs-frame>` element: ~30 lines
-
-```js
-// packages/core/src/webjs-frame.js
-import { WebComponent, html } from './index.js';
-
-export class WebjsFrame extends WebComponent {
-  static properties = { id: { type: String, reflect: true } };
-  render() { return html`<slot></slot>`; }
-}
-WebjsFrame.register('webjs-frame');
-```
-
-Light DOM (default): no shadow boundary, no slot mechanics. The element exists purely as a swap anchor with an addressable `id`. Children are normal light-DOM children that the router replaces via `replaceChildren`.
-
-### Server side: `X-Webjs-Frame` request header (optional optimization)
-
-When set, the SSR pipeline can return only the matching frame's HTML wrapped in a minimal stub document, skipping the rest of the layout chain. Wire is still plain HTML (no new format). v1 ships **without** this optimization. Full SSR response, client extracts what it needs. The header is forward-compat for the perf pass.
-
-### Head merging
-
-Same as today's `mergeHead`: replace `<title>`, merge `<meta>` tags by `name`/`property`, append new `<link>`/`<style>` elements, dedupe.
-
-### Script handling inside the swap region
-
-Re-execute `<script>` elements that match the existing one-level-shell path's `runScripts` logic. Idempotent registration via `Class.register()` makes this safe. The framework already handles `customElements.define` collisions.
-
-## Edge cases
-
-| Case | Behavior |
-|---|---|
-| Click on a link inside `<webjs-frame>` but `data-no-router` | Full browser navigation (existing semantics) |
-| Click on a link *outside* any frame, both pages share a `findLayoutShell` match | Falls through to existing layout-shell path |
-| Frame in old page but not in new (route change leaves the layout tree) | Frame lookup fails → fall to layout-shell or full body swap. Correct. |
-| Nested `<webjs-frame>`s | Innermost wins: `closest('webjs-frame')` returns the nearest enclosing frame. Mirrors Turbo behavior. |
-| Form submission inside a frame | Same. POST response gets the same frame-extract treatment. (Implement in form-submit path alongside link-click.) |
-| Hash-fragment-only navigation | Existing behavior. No fetch, browser handles. |
-| `data-frame="_top"` on a link | Escapes the enclosing frame, full nav. (Turbo precedent.) |
-
-## What this fixes
-
-- **ui-website docs sidenav scroll**: docs layout wraps content in `<webjs-frame id="docs-content">`. Sidenav lives *outside* the frame. Navigation between `/docs/components/a` → `/docs/components/b` only swaps frame children. The sidenav DOM is untouched, and `<aside>` scroll position is preserved natively. The `sessionStorage` workaround in `app/docs/layout.ts` can be deleted.
-- **Any nested-layout app**: the same primitive works whether the partial-swap region is 2, 3, or 5 levels deep.
-- **Mixed layouts**: pages that don't opt-in fall through to the existing one-level shell detection or full body swap. No regression risk.
-
-## What's deliberately deferred (future passes)
-
-1. **Keyed `data-key` DOM diff inside the frame.** Adopt Remix v3's `diff-dom.ts` algorithm to preserve input values, `<details>` open state, popover state, scroll positions on inner scroll containers across nav. Today's `replaceChildren` is coarse, but fine for v1 since the frame *itself* is preserved (outer scroll, sidenav, etc.).
-2. **`X-Webjs-Frame` server optimization** to avoid re-rendering layouts the client already has.
-3. **Server-pushed partial updates** (turbo-stream equivalent) via `<webjs-stream action="replace" target="...">`. Separate feature, useful for SSE/WebSocket-driven UI.
-4. **Frame-scoped error boundaries.** If a frame fetch 5xxs, render only the frame's `error.ts`, not the whole page.
-
-## Implementation plan
-
-1. **`packages/core/src/webjs-frame.js`**: new file, the custom element.
-2. **`packages/core/index.js`**: export `WebjsFrame`. Re-export `<webjs-frame>` via auto-registration import (so any app that imports `@webjsdev/core` gets it).
-3. **`packages/core/src/router-client.js`**: add `findActiveFrame()`, frame-swap branch in `navigate()`. Preserve existing `findLayoutShell` and full-body fallback.
-4. **`packages/core/src/router-client.js` (form path)**: apply the same frame-extract to form submit responses.
-5. **`packages/server/src/dev.js`**: accept `X-Webjs-Frame` header in dev mode (no-op for v1 but adds the request signal for telemetry).
-6. **Tests:**
-   - `packages/core/test/routing/router-client.test.js`: frame detection, querySelector with various ids, fallback when source frame missing.
-   - `test/e2e/nested-layout-partial-swap.test.mjs`: load `/docs/components/a`, scroll sidenav, click `/docs/components/b`, assert scroll preserved AND only frame children swapped.
-7. **Docs:**
-   - `AGENTS.md`: add `<webjs-frame>` to the public API table.
-   - `agent-docs/advanced.md`: new "Frames" section under the client-router doc.
-   - `docs/` app: a new docs page showing the pattern.
-8. **`packages/cli/templates/`**: none for v1 (frames are opt-in, no scaffold change needed).
-9. **ui-website cleanup**: remove the `sessionStorage` workaround in `app/docs/layout.ts` after the frame lands and tests prove scroll preservation.
-
-## Open questions
-
-1. **Should `<webjs-frame>` ship a `src=""` attribute** for lazy loading like turbo-frame does? Probably yes eventually, but not for v1. The motivating use case is layout-scope, not lazy data.
-2. **Should there be a sub-element registry** (something like `data-layout="docs"` as a shorthand)? Keep it explicit for v1: one mechanism. Consider sugar later.
-3. **`X-Webjs-Frame` header naming.** `Webjs-Frame` (like `Turbo-Frame`) is shorter. Either works, and v1 implements neither for response routing so the bikeshed is deferred.
-
-## References
-
-- Turbo source: `frame_controller.js:132-148` (response parse), `frame_renderer.js:5-16` (swap), `link_interceptor.js:48` (innermost-frame rule)
-- Remix v3 source: `packages/component/src/lib/frame.ts:1134-1146` (comment markers), `diff-dom.ts:124-162` (live-attr preservation list)
-- Next.js source: `packages/next/src/client/components/router-reducer/ppr-navigations.ts:230,251,292,354,486` (cache reuse vs create), `walk-tree-with-flight-router-state.tsx:106-112` (server-side tree walk)
-- webjs current: `packages/core/src/router-client.js` (`findLayoutShell`, single body-children scan)