@webjsdev/mcp 0.1.3 → 0.1.5

package/README.md

@@ -34,7 +34,9 @@ subcommand) delegates to this same server, so both routes run identical code.
   MCP `resources` (the `agent-docs/*` corpus + `AGENTS.md` as `webjs-docs://*`),
   and `prompts` (the recipes as guided workflows).
 - **`source` tool**: reads the framework's own no-build source from
-  `node_modules/@webjsdev/*/src` (read-only, traversal-guarded).
+  `node_modules/@webjsdev/*/src` (read-only, traversal-guarded). Under Bun
+  zero-install (no `node_modules`) it falls back to Bun's global cache, where the
+  packages live, so it works without an install.
 
 The docs corpus is bundled into the package at `prepack`, so `npx @webjsdev/mcp`
 is self-contained; in the monorepo it falls back to the live repo-root docs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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,7 +14,8 @@ 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, dev/start task orchestration) + observability |
+| `agent-docs/configuration.md` | The `package.json` `"webjs"` block (security headers, CSP, redirects, trailing-slash, basePath, client-router opt-out, ingress caps, dev/start task orchestration) + observability |
+| `agent-docs/runtime.md` | Node vs Bun (commands, the zero-install Bun bootstrap, the listener/stripper/SQLite/WebSocket differences) + the future-Deno seam |
 | `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/service-worker.md` | The opt-in progressive-enhancement service worker (`public/sw.js`) |
@@ -37,6 +38,18 @@ reference there.
 
 Claude Code enforces step 1 via `.claude/hooks/guard-branch-context.sh`. Other agents check manually.
 
+### One task per git worktree when agents run concurrently
+
+webjs is worked by MULTIPLE agents at once. If more than one agent (or more than one in-flight task) shares ONE working checkout, they collide: a `git checkout` in one moves `HEAD` under the other, so the next commit lands on the WRONG branch. This has happened (a `chore: release` commit landed on an unrelated `feat/` branch, with a contaminated changelog). So give each task its own worktree:
+
+```sh
+git worktree add -b <prefix>/<slug> ../<repo>-<slug> origin/main
+cd ../<repo>-<slug>          # do ALL work for the task here
+# ... commit + push from this worktree; after merge: git worktree remove ../<repo>-<slug>
+```
+
+Git enforces one-branch-per-worktree, so separate worktrees make the collision impossible. Before any commit in a shared checkout, confirm `git branch --show-current` is still the branch you created; if it moved, you are colliding, switch to a worktree. A lone agent in a clean checkout may still use a plain branch. The repo's `.hooks/pre-commit` additionally BLOCKS a published-library (`core`/`server`/`cli`/`mcp`/`ui`/`intellisense`) version bump on any non-`chore/release-*` branch, the canonical wrong-branch-release symptom.
+
 ### 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. 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.
@@ -49,8 +62,8 @@ When interactive approval is disabled, never block on questions. Auto-decide: on
 
 Every code change MUST include, automatically:
 
-1. **Tests, every applicable layer (not just unit).** Ship the tests that prove the change across EVERY layer it touches: **unit** (`packages/*/test/**`, `test/**`, including the counterfactual that fails when reverted), **browser** (`*/test/**/browser/*` via `npm run test:browser`, for hydration / DOM / slots / client router / custom-element upgrade), **e2e** (`test/e2e/*.test.mjs` via `WEBJS_E2E=1`, including network probes / navigation / streaming), and **smoke** (`test/examples/*/smoke/*`). A unit test is NECESSARY BUT NOT SUFFICIENT for any client-router / component / browser-facing change (the headline behaviour is a browser/e2e assertion). `npm test` does NOT run browser or e2e; run them yourself and report the result. Never report work done with failing or missing tests. See `agent-docs/testing.md`. Enforced by `.claude/hooks/require-tests-with-src.sh` (the scaffold variant WARNS unless `WEBJS_TEST_GATE=block`).
-2. **Documentation.** Update `AGENTS.md` for new API surface, `CONVENTIONS.md` for new conventions, `docs/` or `website/` for user-facing features.
+1. **Tests, every applicable layer (not just unit).** Ship the tests that prove the change across EVERY layer it touches: **unit** (`packages/*/test/**`, `test/**`, including the counterfactual that fails when reverted), **browser** (`*/test/**/browser/*` via `npm run test:browser`, for hydration / DOM / slots / client router / custom-element upgrade), **e2e** (`test/e2e/*.test.mjs` via `WEBJS_E2E=1`, including network probes / navigation / streaming), and **smoke** (`test/examples/*/smoke/*`). A unit test is NECESSARY BUT NOT SUFFICIENT for any client-router / component / browser-facing change (the headline behaviour is a browser/e2e assertion). **Bun parity is part of the task, not an afterthought:** webjs runs on Node 24+ AND Bun (#508), so a change to a runtime-sensitive surface (the serializer, the node:http vs `Bun.serve` listener + request path, SSR / action / CSRF dispatch, streams, `node:crypto`, the TS stripper, auth / session / cors) MUST be proven on Bun (`node scripts/run-bun-tests.js` + the touched `test/bun/*.mjs` under `bun`) AND ship an added/updated `test/bun/<feature>.mjs` cross-runtime assertion. `npm test` does NOT run browser, e2e, or Bun; run them yourself and report the result. Never report work done with failing or missing tests. See `agent-docs/testing.md`. Enforced by `.claude/hooks/require-tests-with-src.sh` (the scaffold variant WARNS unless `WEBJS_TEST_GATE=block`) and `.claude/hooks/require-bun-parity-with-runtime-src.sh` (BLOCKS a commit that stages runtime-sensitive source with no `test/bun/**` test; escape hatch `WEBJS_BUN_VERIFIED=1`).
+2. **Documentation, part of the definition of done (not optional).** A task is NOT done until EVERY doc surface its change touches is in sync: `AGENTS.md` + `agent-docs/*.md` for new API surface, `CONVENTIONS.md` (and per-package `AGENTS.md`) for new conventions, the docs site (`docs/app/docs/<topic>`), the marketing `website/`, the scaffold templates (`packages/cli/templates/` per-agent rule files), and `README.md` for a headline capability. Updating `AGENTS.md` alone reproduces the #488 gap (docs site left stale). Invoke the `webjs-doc-sync` skill to sync every applicable surface. Enforced by `.claude/hooks/require-docs-with-src.sh`, which BLOCKS a commit that stages public `packages/*/src` source with no doc surface alongside it (a genuinely internal refactor / CI / release / perf change with no behaviour change bypasses with `WEBJS_NO_DOC_GATE=1`).
 3. **Convention validation.** Run `webjs check` and fix violations.
 
 ### Git workflow (mandatory)
@@ -75,9 +88,9 @@ See `agent-docs/framework-dev.md` for monorepo commands, workspace layout, per-f
 
 ## What webjs is
 
-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`.
+An **AI-first, web-components-first** framework inspired by NextJs, Lit, and Rails. The component runtime API matches lit (reactive 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/`. Reactive properties are the one deliberate divergence (invariant 10): instead of lit's `@property()` decorator or a `static properties` block, webjs declares them through the declare-free base-class factory `extends WebComponent({ count: Number })`.
 
-- **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.
+- **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. See `agent-docs/runtime.md` for the Node vs Bun command + difference reference (and the zero-install Bun bootstrap).
 - **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`.
@@ -96,7 +109,13 @@ webjs has **no server/client component split.** There is no RSC render tree, no
 - **Components hydrate.** The module loads in the browser, registers the custom element, the browser upgrades the SSR'd tag, and `render()` / lifecycle / `@event` / signals run client-side. Per-element, islands-style. **All interactivity lives here.**
 - **Pages and layouts do NOT hydrate.** Their function runs only on the server to produce HTML and is never re-invoked in the browser. So a page/layout cannot be interactive in its own markup (an `@click` in a page template is dropped at SSR; a signal read in a page body never re-renders). For interactivity, render a component's tag.
 
-A page/layout module still **loads** in the browser for its top-level side effects: registering imported components (so their tags upgrade) and, for a layout, enabling the client router via `import '@webjsdev/core/client-router'`. That load is also how its imports reach the client (`import dayjs` at the top of a page fetches dayjs when the module loads, not via hydration). An inert page/layout is dead weight, which is exactly when elision drops it.
+A page/layout module still **loads** in the browser for its top-level side effects: registering imported components (so their tags upgrade). The client router is automatic and needs no import: it auto-enables when `@webjsdev/core` loads in the browser (the bundle every component pulls), so any page that ships a component gets client navigation for free (#620). That load is also how its imports reach the client (`import dayjs` at the top of a page fetches dayjs when the module loads, not via hydration). An inert page/layout is dead weight, which is exactly when elision drops it. A page/layout that is non-inert ONLY because it imports interactive components is **import-only** (#605): since it never hydrates, the boot emits its component modules directly and drops the page/layout module, so the browser fetches just the interactive leaves (it still ships whole when it has its own client side effect: a `client-router` import, a module-scope call, or a self-registering bare import).
+
+**Keep pages and layouts as pure carriers (#621), so their modules stay out of the network tab.** A page/layout drops from the boot (import-only / inert) only while its sole browser-relevant job is registering the components it imports. It starts SHIPPING its own module the moment its closure does any OTHER client work, which is invisible in `npm test` (an elision verdict, not a behaviour change) and easy to introduce by accident. Avoid, in a page/layout (and in any util it imports):
+- module-scope client work: a top-level call, a `new SomethingNonData()`, a browser-global (`window` / `document` / `customElements`) access, or a bare side-effect import of a non-component or `@webjsdev/core/client-router` (routing is automatic). A page-template `@event` / inline-`<script>` is fine (it is SSR output, never module client work, #623 / #634).
+- importing a client-effecting NON-component util. A helper that touches a client global or self-executes drags the whole page in. Put client-only behaviour inside a component; put server-only work in `.server.{js,ts}` (it never reaches the client closure); and if a util MIXES a pure helper with client-global code (the `cn.ts` shape, #619), split the client part into its own module so the pure helper does not pin every importer.
+
+Self-check: `page.ts` / `layout.ts` should NOT appear in the network tab or the boot `<script type="module">`; if one does, something in its closure does client work and is not a component.
 
 `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.
 
@@ -139,12 +158,30 @@ db/*.server.{js,ts}         data layer (Drizzle: schema, columns, connection)
 
 Every file is a plain ES module.
 
+### Imports: prefer the `#` root alias over deep relatives (#555)
+
+App-internal imports use the **`#` path alias** instead of deep `../../../`
+relatives: `import { db } from '#db/connection.server.ts'`, `import { Button }
+from '#components/ui/button.ts'`, `#lib/...`, `#modules/...`. It is Node's native
+`package.json "imports"` field (the scaffold ships the single catch-all `"#*":
+"./*"`, so any top-level folder is aliased with no config change), resolved at
+runtime by Node 24+ AND Bun with **no build step and no tsconfig `paths`**. The
+sigil is `#` (not `@`) and there is **no slash after it** (`#lib/...`, not
+`#/lib/...`): a `#/`-prefixed key does not resolve on Bun. The webjs server
+expands the same map for the import graph / auth gate / elision / browser
+importmap, so a `#`-aliased `.server.ts` still trips the server-only boundary.
+A same-directory import stays relative (`./sibling.ts`); only deep relatives
+become `#`. The alias addresses a top-level SUBDIRECTORY (`#lib/...`,
+`#components/...`); a bare root-level file (`./env.ts`) is imported relatively
+(the browser importmap scope is per-directory, so a `#`-imported root file has
+no browser mapping in dev). Opt out anywhere by writing a plain relative import.
+
 ---
 
 ## Public API of `@webjsdev/core`
 
 ```js
-import { html, css, WebComponent, render } from '@webjsdev/core';
+import { html, css, WebComponent, prop, render } from '@webjsdev/core';
 import { renderToString } from '@webjsdev/core/server';
 ```
 
@@ -153,7 +190,8 @@ The bare `@webjsdev/core` specifier resolves to a BROWSER bundle dropping server
 | Export | Purpose |
 |---|---|
 | `html` / `css` | Tagged template literals. `css` goes in `static styles`. |
-| `WebComponent` | Base class for interactive components. |
+| `WebComponent` | Base class for interactive components. Called as `WebComponent({ ... })` it returns a typed base declaring reactive properties. |
+| `prop(type?, opts?)` | Declares one reactive property inside the `WebComponent({ ... })` factory with options (`reflect`, `state`, `attribute`, `default`, `converter`, `hasChanged`) and a narrowable TS type (`prop<Student>(Object)`). |
 | `register(tag, C)` | Tag binding. Auto-called by `Class.register('tag')`. |
 | `render(v, el)` | Client-side render into a DOM element. |
 | `renderToString` | Server-side async render to HTML with DSD (from `/server`). |
@@ -179,18 +217,27 @@ lit-html parity: `repeat` (keyed lists), `unsafeHTML(str)` (trusted raw HTML, **
 ## `WebComponent` essentials
 
 ```ts
-class MyThing extends WebComponent {
+// Reactive properties are declared in the base-class factory (declare-free)
+class MyThing extends WebComponent({
+  count: prop(Number, { reflect: true })
+}) {
   static shadow = false;     // default light DOM; true = scoped shadow DOM
   static lazy = false;       // true = load module on viewport entry
-  static properties = { count: { type: Number, reflect: true } };
-  declare count: number;     // TS only, typed accessor
   static styles = css`…`;
+
+  constructor() {
+    super();
+    this.count = 0;          // Fully typed, no declare!
+  }
+
   render() { return html`…`; }
 }
 MyThing.register('my-thing');
 ```
 
-**Signals are the default state primitive.** Import `signal` / `computed` from `@webjsdev/core`, read with `signal.get()` inside `render()`, and the built-in `SignalWatcher` re-renders on change. Module-scope signals share state across components and survive navigations; instance signals (constructor) are component-local. `static properties` is reserved for values that ride an HTML attribute, reflect to one, or arrive via `.prop=${value}` SSR hydration. **Typed props in TS use the `declare` pattern** (a `student: Student = {…}` class-field initializer overwrites the reactive accessor after `super()` and breaks reactivity; instead declare the runtime in `static properties`, the type via `declare student: Student`, and set defaults in the constructor, enforced by `reactive-props-use-declare`). Property options: `type` (default `String`), `reflect`, `state`, `hasChanged`, `converter`.
+**Signals are the default state primitive.** Import `signal` / `computed` from `@webjsdev/core`, read with `signal.get()` inside `render()`, and the built-in `SignalWatcher` re-renders on change. Module-scope signals share state across components and survive navigations; instance signals (constructor) are component-local.
+
+**Reactive properties ride HTML attributes, reflect to them, or arrive via SSR hydration.** They are declared ONLY by passing the property shape into the base-class factory `WebComponent({ ... })`. There is no `static properties` block and no `declare` line. The bare form takes a type constructor (`count: Number`, `label: String`, `open: Boolean`); the `prop()` helper carries options (`count: prop(Number, { reflect: true })`, `name: prop(String, { attribute: 'show-close-button' })`, internal state `prop({ state: true })` with no type), and narrows the TS type (`student: prop<Student>(Object)`, `mode: prop<'a' | 'b'>(String, { reflect: true })`). The types flow automatically to `this.<prop>`. Set defaults in the constructor after `super()` (a declarative `default` option also exists for lit-parity, a function default running per instance for a fresh object / array, but the constructor is the recommended way). NEVER use a class-field initializer (e.g., `count = 0`), which clobbers the reactive accessor (caught by `reactive-props-no-class-field`). Declaring your own `static properties` THROWS at runtime and is flagged by `no-static-properties`. Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`): the two share one JSON converter so neither crashes, but `Array` states the prop's shape and `array-prop-uses-array-type` flags the `Object` form. Property options: `type` (default `String`), `reflect`, `state`, `hasChanged`, `converter`, `default`, `attribute`.
 
 **Lifecycle (lit-aligned), in order:** `shouldUpdate`, `willUpdate`, controllers' `hostUpdate()`, `update` (calls `render()` + commits), controllers' `hostUpdated()`, `firstUpdated`, `updated`, `updateComplete`, each receiving a `changedProperties` Map. **SSR runs only the constructor, attribute application, the pre-render hooks (`willUpdate` / `hostUpdate`), `reflect: true` reflection, and `render()`; it does NOT call `connectedCallback`, `firstUpdated`, `updated`, or any browser-only hook.** So defaults for first paint go in the constructor; browser-only data (localStorage, viewport, `navigator.*`) goes in `connectedCallback` writing a signal; server-known data arrives via the page function. Never ship a placeholder first paint that fetches in `connectedCallback`. A browser-only global in the constructor/`render()` throws at SSR (flagged by `no-browser-globals-in-render`; attribute methods and `closest()` are shimmed).
 
@@ -247,7 +294,7 @@ Server actions export named async functions whose args + returns round-trip thro
 
 ### RPC + REST endpoint security
 
-Client to action RPC posts `x-webjs-csrf` matching the cookie issued on first SSR (mismatch 403); prod errors are sanitized to `message` only. A `route.ts` REST endpoint (hand-written or via the `route()` adapter) is NOT CSRF-protected: authenticate every mutating endpoint, use `validate`, log without secrets, rate-limit. For CORS use the `cors()` middleware from `@webjsdev/server`; **`credentials: true` REQUIRES an explicit origin allowlist, never `'*'`.** See `agent-docs/advanced.md`.
+Action RPC CSRF is an **Origin / `Sec-Fetch-Site` check** (the Remix 3 / Go 1.25 model), NOT a token cookie: a state-changing verb passes only when `Sec-Fetch-Site` is `same-origin` / `none`, or (older browsers, no `Sec-Fetch-Site`) the `Origin` host matches the request host, or the source is in `webjs.allowedOrigins`; otherwise 403. **No `Set-Cookie` rides the SSR HTML**, which is why a page that opts into a public `Cache-Control` (via `metadata.cacheControl`, e.g. on a root layout for a whole visitor-identical app) is CDN-edge-cacheable. A safe GET action is CSRF-exempt. Prod errors are sanitized to `message` only. A `route.ts` REST endpoint (hand-written or via the `route()` adapter) is NOT covered by this check: authenticate every mutating endpoint, use `validate`, log without secrets, rate-limit. For CORS use the `cors()` middleware from `@webjsdev/server`; **`credentials: true` REQUIRES an explicit origin allowlist, never `'*'`.** See `agent-docs/advanced.md`.
 
 ### Components (`components/*.{js,ts}`)
 
@@ -277,15 +324,15 @@ type ActionResult<T> =
 
 ## Styling: Tailwind-first
 
-**Tailwind is the strong default for pages AND light-DOM components.** The lit reflex to scope CSS in a shadow root with `static styles` is the habit to resist in light DOM. When a class bundle repeats, extract it into a `lib/utils/ui.ts` helper returning an `` html`...` `` fragment (SSR-time), NOT a CSS class (no `@apply`). Reserve raw CSS for what utilities cannot express (design tokens / `@theme`, `@property` + `@keyframes`, scrollbar, `prefers-reduced-motion`, complex `color-mix()` / gradients); in light DOM the tag-prefix invariant (#7) still holds, and shadow-DOM components legitimately use `static styles = css\`\``. See `agent-docs/styling.md`.
+**Tailwind is the strong default for pages AND light-DOM components.** The lit reflex to scope CSS in a shadow root with `static styles` is the habit to resist in light DOM. When a class bundle repeats, extract it into a `lib/utils/ui.ts` helper returning an `` html`...` `` fragment (SSR-time), NOT a CSS class (no `@apply`). Reserve raw CSS for what utilities cannot express (design tokens / `@theme`, `@property` + `@keyframes`, scrollbar, `prefers-reduced-motion`, complex `color-mix()` / gradients); in light DOM the tag-prefix invariant (#7) still holds, and shadow-DOM components legitimately use `static styles = css\`\``. **Pin a header with `position: fixed`, never `position: sticky`** (a sticky header flickers on iOS WebKit during a client-router nav, #610, because the preserved header plus the scroll-to-top trips a WebKit sticky-repaint bug that the GPU-promotion hacks do NOT fix, so reserve the header height on the content with a `--header-height` offset). See `agent-docs/styling.md`.
 
 ---
 
 ## Client navigation: automatic, nothing to opt into
 
-Nested layouts auto-emit `<!--wj:children:<segment-path>-->` markers; the client router walks both DOMs and replaces only the deepest shared layout's children slot, preserving outer-layout DOM identity. Form submissions ride the same pipeline (`data-no-router` opts out). Wire bytes are minimized via the `X-Webjs-Have` header (the server returns only the divergent fragment); scroll is restored on back/forward. A non-GET `<form>` whose target page exports an `action` is the no-JS write-path (with JS the router applies the response in place: a `422` swaps without reload, a `303` is followed via fetch). A failed navigation recovers in place (a cancelable `webjs:navigation-error` event, else a minimal in-place alert), never a destructive full reload.
+The router auto-enables when `@webjsdev/core` loads (any page with a component), so there is nothing to opt INTO. An app that wants plain full-page (MPA) navigation can opt OUT app-wide with `{ "webjs": { "clientRouter": false } }` (#629), or per-moment at runtime with `disableClientRouter()`. Nested layouts auto-emit `<!--wj:children:<segment-path>-->` markers; the client router walks both DOMs and replaces only the deepest shared layout's children slot, preserving outer-layout DOM identity. Form submissions ride the same pipeline (`data-no-router` opts out). Wire bytes are minimized via the `X-Webjs-Have` header (the server returns only the divergent fragment); scroll is restored on back/forward. A non-GET `<form>` whose target page exports an `action` is the no-JS write-path (with JS the router applies the response in place: a `422` swaps without reload, a `303` is followed via fetch). A failed navigation recovers in place (a cancelable `webjs:navigation-error` event, else a minimal in-place alert), never a destructive full reload.
 
-The advanced client-router surface is in `agent-docs/advanced.md`: **link prefetch** (on by default, `intent` strategy, per-link `data-prefetch`), **`<webjs-frame>`** partial-swap regions, **View Transitions** (opt-in via `<meta name="view-transition">`, plus `data-webjs-permanent` to persist a live element), and **stream actions** (`<webjs-stream>` element-level updates, #248). Production benefits from HTTP/2 at the edge; `npm run start` speaks plain HTTP/1.1 (put a reverse proxy in front for TLS + HTTP/2).
+The advanced client-router surface is in `agent-docs/advanced.md`: **link prefetch** (on by default, device-adaptive default: `intent` on a hover pointer, `viewport` (dwell-gated, cancel-on-scroll-out) on touch, per-link `data-prefetch` override), **`<webjs-frame>`** partial-swap regions, **View Transitions** (opt-in via `<meta name="view-transition">`, plus `data-webjs-permanent` to persist a live element), **stream actions** (`<webjs-stream>` element-level updates, #248), and the **opt-in nav-loading indicator** (`<html data-webjs-nav-progress>` exposes a `data-navigating` attribute during a nav so you can style a CSS-only progress affordance, off by default because toggling a root attribute re-resolves `oklch()` tokens to a one-frame repaint flash on iOS WebKit, #610). Production benefits from HTTP/2 at the edge; `npm run start` speaks plain HTTP/1.1 (put a reverse proxy in front for TLS + HTTP/2).
 
 ---
 
@@ -293,11 +340,11 @@ 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 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.
+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 (`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}"`.
-5. **Signals are the default state primitive.** Import `signal` / `computed` from `@webjsdev/core` and read via `signal.get()` inside `render()`; the built-in SignalWatcher tracks the reads and re-renders. Module-scope signals share state across components; instance-scope signals (constructor) are component-local. `static properties` (with a sibling `declare`) is reserved for values riding an HTML attribute, reflected to one, or arriving via `.prop=${value}` SSR hydration. For fine-grained DOM swap use `${watch(signal)}` from `@webjsdev/core/directives`.
+5. **Signals are the default state primitive.** Import `signal` / `computed` from `@webjsdev/core` and read via `signal.get()` inside `render()`; the built-in SignalWatcher tracks the reads and re-renders. Module-scope signals share state across components; instance-scope signals (constructor) are component-local. The factory `WebComponent({ ... })` is reserved for values riding an HTML attribute, reflected to one, or arriving via `.prop=${value}` SSR hydration. For fine-grained DOM swap use `${watch(signal)}` from `@webjsdev/core/directives`.
 6. **Page and layout default exports must be functions.** They return a value (usually `TemplateResult`). They do not call `render()` themselves.
 7. **Light-DOM components with custom CSS MUST prefix every class selector with their tag name.** Tailwind utilities are unique by construction, so prefer them.
 8. **Non-root layouts and pages MUST NOT** write `<!doctype>` / `<html>` / `<head>` / `<body>`. Only the root layout may.
@@ -310,7 +357,7 @@ 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, 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.
+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). The `--runtime node|bun` flag (default node, #541) is ORTHOGONAL to the template and re-flavors any of the three for Bun (the dev/start/db scripts run through a generated `webjs-bun.mjs` bootstrap under `bun --bun`, so the SERVER runs on Bun AND Bun auto-install resolves deps on demand at the package.json/`bun.lock` versions (an `onLoad` specifier rewrite pins them so zero-install fetches the declared version, not latest, #685), so a Bun app serves with NO `bun install`, install optional for editor types / offline, #675; `bun.lock`, a pure `oven/bun:1` Dockerfile (#595; safe since cli@0.10.20's npx-free `webjs db migrate` (#570) needs no Node in the image) + bun-install CI, bun-command agent docs; the test/check/typecheck tooling stays plain `webjs` on Node and still expects an install); `bun create webjs <name>` auto-detects it. 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 (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.
 
@@ -324,7 +371,7 @@ webjs start  [--port N]            # prod server; source IS the runtime, plain H
 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
-webjs doctor                       # project-health checklist; non-zero exit on a hard fail
+webjs doctor                       # project-health checklist (incl. a page/layout elision advisory, #646); non-zero exit on a hard fail
 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]

package/resources/agent-docs/advanced.md

@@ -380,7 +380,7 @@ The warning is informational; the request still proceeds. Treat it as a prompt t
 
 ## Client router: nested-layout-aware partial swap
 
-`import '@webjsdev/core/client-router'` enables SPA-style navigation that
+The client router auto-enables when `@webjsdev/core` loads in the browser (any page that ships a component), no import needed (#620). It gives SPA-style navigation that
 preserves outer-layout DOM identity at any depth. Intercepts same-origin
 `<a>` clicks (incl. inside shadow DOM via `composedPath()`), fetches the
 target HTML, and replaces only the inside of the deepest shared layout.
@@ -570,20 +570,30 @@ affects a cached page.
 ### Link prefetch
 
 Same-origin in-app links are prefetched speculatively so a click
-resolves from a warm cache with no round-trip. On by default with the
-`intent` strategy (no per-link opt-in needed), the way Next / Nuxt /
-SvelteKit ship auto-prefetch. The prefetch request carries the same
-`X-Webjs-Have` header a real navigation sends, so the server returns the
-same divergent fragment; that fragment lands in a dedicated prefetch
-cache (separate from the back/forward snapshot cache) and `fetchAndApply`
-consumes it via `prefetchTake` before falling back to the network.
+resolves from a warm cache with no round-trip. On by default (no per-link
+opt-in needed), the way Next / Nuxt / SvelteKit ship auto-prefetch. The
+prefetch request carries the same `X-Webjs-Have` header a real navigation
+sends, so the server returns the same divergent fragment; that fragment
+lands in a dedicated prefetch cache (separate from the back/forward
+snapshot cache) and `fetchAndApply` consumes it via `prefetchTake` before
+falling back to the network.
+
+The default strategy is DEVICE-ADAPTIVE, because one strategy cannot serve
+both input modalities. On a hover-capable fine pointer (mouse / trackpad)
+the default is `intent` (warm on hover / focus, a real head-start before
+the click). On touch the default is `viewport` (warm as links settle
+on-screen), because a touch device has no hover and `touchstart` fires at
+tap time, too late to front-run the navigation. The modality is detected
+with `matchMedia('(hover: hover) and (pointer: fine)')`, not a user-agent
+sniff. A per-link `data-prefetch` always overrides the adaptive default.
 
 Per link, set `data-prefetch` (a valid-HTML `data-*` attribute, the shape
 SvelteKit and Astro use; Next / Nuxt / Remix use a component prop, which
 webjs has no equivalent for since links are plain `<a href>`):
 
 ```html
-<a href="/dashboard">intent: hover / focus / touch (default)</a>
+<a href="/dashboard">adaptive: intent on pointer, viewport on touch (default)</a>
+<a href="/dashboard" data-prefetch="intent">hover / focus / touch</a>
 <a href="/dashboard" data-prefetch="render">eager on insert</a>
 <a href="/dashboard" data-prefetch="viewport">on scroll-into-view</a>
 <a href="/dashboard" data-prefetch="none">never</a>
@@ -591,9 +601,14 @@ webjs has no equivalent for since links are plain `<a href>`):
 
 Next-style aliases are accepted: `true` = `render`, `auto` = `viewport`,
 `false` = `none`. `intent` waits a short dwell (~100ms) after hover/focus
-so a pointer passing over a link does not fetch it; `viewport` uses an
-IntersectionObserver at threshold 0.5; `render` and `viewport` are
-applied by a document scan on enable and after each navigation.
+so a pointer passing over a link does not fetch it. `viewport` uses an
+IntersectionObserver at threshold 0.5 and waits a ~250ms dwell, cancelled
+the instant the link scrolls back out, so a fast scroll through a long
+list spends no requests (the same gate Astro / Next / Nuxt / Remix /
+TanStack / Turbo apply). On touch, `touchstart` additionally warms the
+tapped link itself (a single request for a link about to be navigated).
+`render` and `viewport` are applied by a document scan on enable and after
+each navigation.
 
 Only internal links qualify, using the same eligibility as a click:
 cross-origin, `download`, `target` other than `_self`, non-HTML
@@ -602,7 +617,9 @@ Opt out with `data-prefetch="none"`, `data-no-prefetch`, or
 `rel="external"`. Speculation is bounded by a concurrency cap (excess
 requests queue and drain as slots free, rather than being dropped),
 in-flight de-dupe, and an LRU + TTL cache, and is disabled entirely under
-`Save-Data` or `prefers-reduced-data`. A mutating form submission and
+`Save-Data`, `prefers-reduced-data`, or a 2g `effectiveType` connection.
+The guiding rule: snappy, but never at the cost of bloating the client
+network tab; when the two conflict, the gate under-fetches. A mutating form submission and
 `revalidate(url)` both evict the prefetch cache alongside the snapshot
 cache, so a fragment prefetched before a mutation is never served stale.
 
@@ -851,6 +868,17 @@ revalidation fetch that follows does **not** scroll, so the restored
 position survives the refresh. Cache miss → browser-native scroll
 restoration takes over.
 
+Every programmatic nav scroll (the popstate restore and the
+scroll-to-top on a forward nav) is issued with `behavior: 'instant'`, so
+an app-level `html { scroll-behavior: smooth }` does not animate it. The
+restore matches a native page load (an instant jump), not a visible
+slide. The one nav scroll left smooth is a hash-anchor (`#section`)
+target, where smooth scrolling is the intent. So `scroll-behavior:
+smooth` on `<html>` only affects in-page anchors, not route
+transitions. In development the router logs a one-time console hint when
+it detects that setting (and notes that pairing it with a sticky
+`backdrop-filter` header can flash on iOS during navigation).
+
 Inner scroll containers (e.g. `.docs-sidenav`) are preserved
 automatically by the outer-layout-DOM-identity invariant. They stay
 mounted across nav and keep their `scrollTop` natively.
@@ -1094,7 +1122,7 @@ more parts in a `Response` with the stream content type. A page `action` may
 return `streamResponse(...)` directly (it is honored verbatim); on the no-JS
 branch return a normal `ActionResult` instead. `renderStream` is auto-registered
 by the client router, so it (and the `<webjs-stream>` element) is available
-wherever a layout imports `@webjsdev/core/client-router`.
+on any page that loads `@webjsdev/core` (the router auto-enables there).
 
 ### Streaming RPC results: an action returns a stream (#489)
 
@@ -1158,7 +1186,23 @@ Use `data-no-router` for:
 
 ### Loading indicator
 
-`<html>` gets `data-navigating` during fetch. Style a progress bar off that attribute.
+**When to use it.** You want a CSS-only progress affordance (a top bar, a `cursor: progress`) while a client navigation is in flight, with no JavaScript. For a JS-driven indicator, skip this and listen for the `webjs:navigate` event (and `webjs:submit-start` for forms) instead, which always fires.
+
+**How to use it.** It is OPT-IN. Add `data-webjs-nav-progress` to your `<html>` element (once, in the root layout), and the router then sets a `data-navigating` attribute on `<html>` while a nav is in flight (deferred 150ms, so quick sub-150ms navs never trigger it). Style off that attribute:
+
+```html
+<html data-webjs-nav-progress>   <!-- opt in once -->
+```
+
+```css
+html[data-navigating] { cursor: progress; }
+html[data-navigating]::after {
+  content: ''; position: fixed; top: 0; left: 0; right: 0; height: 2px;
+  background: var(--accent); animation: progress 1s ease-in-out infinite;
+}
+```
+
+**Why it is opt-in, not default (#610).** Toggling an attribute on `<html>` re-runs global style resolution, and on WebKit (so every iOS browser) that re-resolves the page's `oklch()` / `color-mix()` design tokens to an equivalent oklab representation and repaints them for one frame. On a token-driven theme that is a visible background flash, worst on a slow mobile forward nav (which exceeds the 150ms defer). So without the opt-in the attribute is never written and the flash cannot happen. Enable it only when your theme does not lean on wide-gamut color tokens, or use the event-based path above.
 
 ## WebSockets
 

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

@@ -137,10 +137,10 @@ The cache is keyed by the FULL URL (path + search) only, with no per-user
 keying, so a page that reads `cookies()` / a session / per-user data MUST
 NOT set `revalidate`. The framework also refuses to cache (defense in
 depth) any response that is not a `200`, is a streamed Suspense body,
-sets a non-framework `Set-Cookie` (the framework `webjs_csrf` cookie is
-re-minted per response on a hit and does not block), or runs under CSP
-(its body carries a per-request nonce). A cached page served to a brand
-new visitor still gets a fresh CSRF cookie, so it stays correct.
+sets any `Set-Cookie`, or runs under CSP (its body carries a per-request
+nonce). SSR responses no longer carry a CSRF cookie (action CSRF is an
+Origin / `Sec-Fetch-Site` check, not a token cookie), so a cacheable page
+is cookieless and safe to share.
 
 **Framework defense, not just the contract.** When the render reads
 per-user state through a framework helper (`cookies()`, `headers()`,
@@ -221,7 +221,7 @@ The ETag is WEAK (`W/"..."`). It hashes the UNCOMPRESSED body and the prod compr
 | A `route.{js,ts}` handler returning a `ReadableStream` (incl. an SSE `text/event-stream`) | The body is not marked buffered, so the funnel never reads it. Buffering a stream would blow up memory, and an SSE stream never ends so the read would hang forever |
 | Non-GET / non-HEAD, and any status other than 200 | A validator is only meaningful for a successful, replayable read |
 
-**Stable-body handling.** The ETag is computed over the response's OWN body bytes, so an identical body yields an identical ETag across requests. Per-response varying bits that ride RESPONSE HEADERS (the `x-webjs-build` id, the `set-cookie` CSRF token, the CSP nonce on the header) are NOT part of the body hash, so they do not destabilise the ETag. The one body-level varying input is the CSP nonce stamped INTO the inline boot script: with CSP enabled the HTML body changes every request, so its ETag changes every request and a 304 is simply never produced for that page (correct, not a bug). CSP is off by default, so the common cacheable-page case has a stable body and a stable ETag. The 304 preserves the validators and caching headers (`ETag`, `Cache-Control`, `Vary`, plus the framework's `X-Webjs-Build` / `X-Request-Id` and any `Set-Cookie`) and drops only the body-describing headers (`Content-Length`, `Content-Type`, `Content-Encoding`), so a shared cache and the client router behave identically to a 200.
+**Stable-body handling.** The ETag is computed over the response's OWN body bytes, so an identical body yields an identical ETag across requests. Per-response varying bits that ride RESPONSE HEADERS (the `x-webjs-build` id, the CSP nonce on the header) are NOT part of the body hash, so they do not destabilise the ETag. The one body-level varying input is the CSP nonce stamped INTO the inline boot script: with CSP enabled the HTML body changes every request, so its ETag changes every request and a 304 is simply never produced for that page (correct, not a bug). CSP is off by default, so the common cacheable-page case has a stable body and a stable ETag. The 304 preserves the validators and caching headers (`ETag`, `Cache-Control`, `Vary`, plus the framework's `X-Webjs-Build` / `X-Request-Id` and any `Set-Cookie`) and drops only the body-describing headers (`Content-Length`, `Content-Type`, `Content-Encoding`), so a shared cache and the client router behave identically to a 200.
 
 ## Sessions
 

package/resources/agent-docs/components.md

@@ -4,9 +4,15 @@
 
 | Option | Type | Default | Meaning |
 |---|---|---|---|
-| `type` | `Number\|String\|Boolean\|Object\|Array` | `String` | Used by the default attribute converter |
+These options are passed to the `prop()` helper inside the `WebComponent({ ... })` factory (e.g. `count: prop(Number, { reflect: true })`); the bare form `count: Number` is shorthand for `prop(Number)`.
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `type` | `Number\|String\|Boolean\|Object\|Array` | `String` | Used by the default attribute converter (the first `prop()` argument) |
 | `reflect` | `boolean` | `false` | Property changes write back to the HTML attribute |
 | `state` | `boolean` | `false` | Internal-only. No attribute, not in `observedAttributes` |
+| `attribute` | `string` | derived from the prop name | The HTML attribute name the property rides |
+| `default` | value or `() => value` | none | Declarative initial value (a function runs per instance for a fresh object / array) |
 | `hasChanged` | `(newVal, oldVal) => boolean` | strict `!==` | Custom change detection |
 | `converter` | `{ fromAttribute?, toAttribute? }` | type-based | Custom attribute ↔ property serialization |
 
@@ -14,18 +20,60 @@ Built-in constructors (`String`, `Number`, `Boolean`, `Array`, `Object`) feed
 the default attribute coercion. For anything the default can't parse correctly
 (Date, Map, Set, discriminated unions) supply a custom `converter`.
 
-## Why `declare` is required in TypeScript
+For an array-typed prop, pass `Array`, not `Object` (`items: prop<Tag[]>(Array)`).
+The default converter handles both identically (each JSON-encodes the value), so
+`Object` does not break anything, but `Array` states the prop's shape to the next
+reader. The `array-prop-uses-array-type` `webjs check` rule flags an array-typed
+generic (`T[]`, `readonly T[]`, `Array<T>`, `ReadonlyArray<T>`) declared with the
+`Object` constructor.
 
-The framework installs reactive getter/setter on `this` inside the
-constructor via `Object.defineProperty`. Without `declare`, TypeScript
-emits `student = undefined` after `super()`, which under modern class-
-field semantics uses `[[Define]]` to overwrite the accessor. Result:
-`this.student = …` no longer goes through the setter, no `requestUpdate`,
-no `hasChanged`, no reflect, and reactivity silently breaks.
+## Declaring reactive properties: the base-class factory
 
-The `.d.ts` overlay shipped with the framework makes every other class
-member fully typed, so only the reactive properties need the `declare`
-line, and only in TypeScript files.
+Reactive properties are declared by passing the property shape into the **base-class factory** `WebComponent({ ... })`. The types flow automatically to `this.<prop>`, so there is no `static properties` block and no `declare` line. A direct `static properties` block throws at runtime (caught statically by the `no-static-properties` rule).
+
+```ts
+class Counter extends WebComponent({
+  count: Number
+}) {
+  constructor() {
+    super();
+    this.count = 0; // fully typed, no declare needed
+  }
+}
+```
+
+The bare form takes a type constructor (`count: Number`, `label: String`, `open: Boolean`). The `prop()` helper carries options and narrows the TS type:
+
+```ts
+class Dialog extends WebComponent({
+  open: prop(Boolean, { reflect: true }),                 // reflects to the `open` attribute
+  showClose: prop(Boolean, { attribute: 'show-close-button' }), // custom attribute name
+  variant: prop<'info' | 'danger'>(String, { reflect: true }),  // narrowed union type
+  student: prop<Student>(Object),                          // narrowed object type
+  internal: prop({ state: true }),                         // internal state, no attribute, no type
+}) {
+  constructor() {
+    super();
+    this.student = { name: '', email: '' };
+  }
+}
+```
+
+Set defaults in the constructor after `super()`. A declarative `default` option also exists (lit-parity, a function default runs per instance for a fresh object / array), but the constructor is the recommended way. **Never** use a class-field initializer (e.g., `count = 0` or `student: Student = { ... }`): the framework installs reactive getter/setter on `this` inside the constructor via `Object.defineProperty`, and a class-field initializer compiles to an assignment after `super()` that uses `[[Define]]` to overwrite the accessor, silently breaking reactivity. The `reactive-props-no-class-field` rule catches this.
+
+```ts
+// set defaults in the constructor after super()
+class Counter extends WebComponent({
+  count: prop(Number, { reflect: true }),
+  items: prop(Array),
+}) {
+  constructor() {
+    super();
+    this.count = 0;
+    this.items = [];
+  }
+}
+```
 
 ## Lifecycle hooks (lit-aligned)
 
@@ -55,9 +103,7 @@ See [`/docs/lifecycle`](https://docs.webjs.com/docs/lifecycle) for per-hook usag
 A component can fetch its own server data into the first paint. `render()` may be `async`, so you write the natural line directly:
 
 ```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>`;
@@ -75,9 +121,7 @@ Writing `await` makes the function async by the JS rule, and every render path a
 3. **`renderFallback()` is the OPTIONAL re-fetch loading UI.** Define it to OVERRIDE the stale-while-revalidate default with a loading state (skeleton / spinner) shown DURING a client re-fetch. It is shown ONLY on a re-fetch, NEVER on the first paint, and it does NOT create a server-streaming boundary. It is a prop-aware method (not a static field), so it can branch on the component's current state.
 
 ```ts
-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>`; }  // shown only while a re-fetch is in flight
   async render() {
     const items = await getActivity(this.uid);
@@ -153,11 +197,11 @@ server/client split to reason about. A component stays elidable as long
 as it has none of the following.
 
 - An `@event` binding in a template (`@click=${...}`), or a native event-handler property (`.onclick=${...}`).
-- A reactive property in `static properties` that is not `{ state: true }`. Attribute-driven or `.prop`-driven values are the channel a parent uses to push client updates.
+- A factory-declared reactive property (`WebComponent({ ... })`) that is not `{ state: true }`. Attribute-driven or `.prop`-driven values are the channel a parent uses to push client updates.
 - An overridden lifecycle hook (anything in the table above), as a method or an arrow class field.
 - A `signal` / `computed` / `watch` / `Task` / `ref` / `live` / streaming directive imported from `@webjsdev/core`, OR a transitive import of a module that reads shared module-scope signal state.
 - An `addController(...)` or `requestUpdate()` call.
-- Any code that runs at module load. A display-only module's top level may only *declare* things (imports, the `WebComponent` class, `const` / `let` / `var`, pure initializers like `css\`...\``) and *register* the component (`X.register(...)` / `customElements.define(...)`). Any other top-level call, `new`, dynamic `import(...)`, or top-level `await` is client work and ships (a top-level `fetch('/track')`, `new WebSocket(...)`, `setTimeout(...)`, `someInit()`). This is checked structurally as an allowlist of safe top-level forms, not a denylist of global names, so a brand-new browser API is caught automatically with no code change. Code inside a method, `render()`, or an uninvoked function does not count (it does not run at load), nor do these words in rendered template text or a `.fetch` / `.location` member access.
+- Any code that runs at module load. A display-only module's top level may only *declare* things (imports, the `WebComponent` class, `const` / `let` / `var`, pure initializers like `css\`...\``) and *register* the component (`X.register(...)` / `customElements.define(...)`). Any other top-level call, a non-data `new`, dynamic `import(...)`, or top-level `await` is client work and ships (a top-level `fetch('/track')`, `new WebSocket(...)`, `setTimeout(...)`, `someInit()`). A module-scope pure-DATA constructor is the one exception (`const TAGS = new Set([...])`, a compiled `new RegExp(...)`, a parsed `new URL(...)`, a typed array): it produces inert data with no side effect, so it does not force shipping. This is checked structurally as an allowlist of safe top-level forms, not a denylist of global names, so a brand-new browser API is caught automatically with no code change. Code inside a method, `render()`, or an uninvoked function does not count (it does not run at load), nor do these words in rendered template text or a `.fetch` / `.location` member access.
 - A rendered `<slot>`. Light-DOM slots rely on the client projection runtime, and proving a slot is purely native (shadow DOM) is beyond static analysis, so any `<slot>` ships.
 - Being rendered or imported by a component that itself ships (an interactive parent can re-create the child on the client).
 
@@ -205,6 +249,56 @@ which fails if a new `WebComponent` hook is added without teaching the
 analyser about it. If you add an interactivity feature to the framework,
 update that file.
 
+## Pages and layouts: keep them carriers, out of the network tab
+
+The same elision applies to whole routes, and it is what keeps `page.ts`
+and `layout.ts` out of the browser's network tab. A page/layout NEVER
+hydrates: it loads in the browser only to register the components it
+imports (so their tags upgrade). When that registration is its sole
+browser-relevant job, the framework drops the page/layout module and the
+boot script imports those components directly. It is **import-only** (the
+page/layout is dropped but reaches shipping components, #605) or **inert**
+(it reaches none, so zero application JS, #179).
+
+A page/layout starts SHIPPING its own module the moment its closure does
+any OTHER client work. Because that is an elision verdict, not a behaviour
+change, it is invisible in `npm test` and easy to introduce by accident
+(a code sample mistaken for real code, #634; a util that touches a client
+global, #619). To keep a route's modules out of the network tab:
+
+- Do not give a page/layout its own module-scope client work: no top-level
+  call, no `new SomethingNonData()`, no browser-global access
+  (`window` / `document` / `customElements`) at module scope, no bare
+  side-effect import of a non-component, and no
+  `import '@webjsdev/core/client-router'` (routing is automatic, #620). A
+  page-template `@event` or inline `<script>` is fine: it is SSR output,
+  never module client work (the analyser scans route-module template
+  content as inert, #623 / #634).
+- Do not import a client-effecting NON-component util into a page/layout
+  (or into a component chain a page reaches). A helper that touches a
+  client global or self-executes drags the whole page in. Put client-only
+  behaviour inside a component; put server-only work in `.server.{js,ts}`
+  (it never enters the client closure); and if a util MIXES a pure helper
+  with client-global code (the `cn.ts` shape, #619), split the client part
+  into its own module so the pure helper does not pin every importer.
+
+Self-check: `page.ts` / `layout.ts` should NOT appear in the network tab
+or the boot `<script type="module">`. If one does, something in its
+closure does client work and is not a component; that is the thing to move
+into a component or a `.server.{js,ts}` file.
+
+`webjs doctor` names this for you (#646). Its "Page/layout elision (carrier
+hygiene)" check runs the same elision verdict and, for every page/layout
+that ships whole, prints the FIRST client-effecting blocker by name, for
+example `app/page.ts ships whole. Its first client-effecting blocker is
+lib/track.ts, which references a browser global at module scope, runs code
+at module scope, or has a bare side-effect import and is not a component`.
+It names the first blocker only; if a module has several, it stays shipped
+until each is moved out. It is ADVISORY (a `warn`, never a hard fail): a page
+legitimately MAY ship, and the analyser is biased toward shipping by design,
+so this is a "you may not have intended this" hint. When the module's own
+code is the cause, it prints `ships whole because it <reason>`.
+
 ### Elision is what keeps a server import off a display-only page (and `webjs check` guards the seam)
 
 Elision is also why a page can call a server-only utility and stay

package/resources/agent-docs/configuration.md

@@ -1,6 +1,6 @@
 # Server configuration (the `package.json` `"webjs"` block) + observability
 
-The full reference for the `package.json` `"webjs"` config block (security headers, CSP, redirects, trailing-slash, basePath, ingress caps) plus the observability surfaces. Moved out of `AGENTS.md` to keep it lean. Env vars live in `agent-docs/built-ins.md`.
+The full reference for the `package.json` `"webjs"` config block (security headers, CSP, redirects, trailing-slash, basePath, allowedOrigins, client-router opt-out, ingress caps) plus the observability surfaces. Moved out of `AGENTS.md` to keep it lean. Env vars live in `agent-docs/built-ins.md`.
 
 ---
 
@@ -123,6 +123,34 @@ An app served under a sub-path (`example.com/app/`) behind a proxy that does NOT
 
 Mechanism: `normalizeBasePath` / `readBasePath` / `withBasePath` / `stripBasePath` in `packages/server/src/base-path.js`; the ingress strip is in `dev.js`'s `produce()` (before `applyRedirects`), the importmap-target prefix in `importmap.js` (`setBasePath`), the boot / preload / reload prefix in `ssr.js`.
 
+## Cross-origin allowlist: `webjs.allowedOrigins` in package.json (#659)
+
+Server-action RPC CSRF is an Origin / `Sec-Fetch-Site` check (the Remix 3 / Go 1.25 model, see `agent-docs/built-ins.md` and the docs-site Security page): a state-changing request passes when `Sec-Fetch-Site` is `same-origin` / `none`, or (older browsers) the `Origin` host equals the request host. A legitimate CROSS-site caller (a reverse proxy serving the app under several hostnames, an admin panel on a sibling domain) is rejected unless its origin is allowlisted:
+
+```json
+{ "webjs": { "allowedOrigins": ["admin.example.com", "https://studio.example.com"] } }
+```
+
+- A bare host (`admin.example.com`) or a full origin (`https://studio.example.com`) are both accepted; only the host is compared.
+- The check honors `x-forwarded-host`, so it works behind a CDN / reverse proxy (the Cloudflare-in-front-of-Railway setup) without extra config.
+- Default `[]` (same-origin only). This is the CSRF allowlist ONLY; it does not configure CORS (use the `cors()` middleware for cross-origin `route.ts` reads).
+
+Because the check needs nothing on the page (no token cookie), SSR HTML carries no `Set-Cookie`, so a visitor-identical page that opts into a public `Cache-Control` (via `metadata.cacheControl`, e.g. on a root layout) is CDN-edge-cacheable. Mechanism: `verifyOrigin` / `readAllowedOrigins` in `packages/server/src/csrf.js`, threaded through `invokeAction` (`actions.js`) from `dev.js`.
+
+---
+
+## Client-router opt-out: `webjs.clientRouter` in package.json (#629)
+
+The client router is automatic: it auto-enables in the browser whenever `@webjsdev/core` loads (any page that ships a component), so SPA-style navigation needs no import (#620). `webjs.clientRouter: false` opts the WHOLE app out, for an app that genuinely wants plain full-page (MPA) navigation despite shipping interactive components.
+
+```jsonc
+{ "webjs": { "clientRouter": false } }   // pure MPA, full-page navigation
+```
+
+Default `true` (and any value other than the literal `false`), so an existing app is byte-identical. When off, the render path emits a tiny inline `<script>window.__WEBJS_CLIENT_ROUTER__=false</script>` BEFORE the deferred boot module; the core bundle's module-end auto-enable reads that flag and skips, so the components on the page still upgrade and stay interactive while link clicks and form submits fall back to native browser navigation. `disableClientRouter()` (from `@webjsdev/core`) stays the per-page programmatic escape hatch, and `enableClientRouter()` turns it back on.
+
+Mechanism: `readClientRouterEnabled` (`packages/server/src/dev.js`) reads the key at boot and on every rebuild and calls `setClientRouterEnabled` (`ssr.js`); `wrapHead` emits the flag; the module-end gate lives in `packages/core/src/router-client.js`.
+
 ---
 
 ## Request ingress hardening: body-size limit (413) + server timeouts (on by default)

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,15 @@ 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 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
+// 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 +294,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 +452,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 in the constructor after `super()` |
+| `@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

@@ -200,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
@@ -217,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>`;
@@ -235,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);

package/resources/agent-docs/runtime.md

@@ -0,0 +1,91 @@
+# Runtime: Node and Bun (and future Deno)
+
+webjs runs on **Node 24+** or **Bun**. The app source is identical on either; only
+the listener shell, the type stripper, and a few built-ins differ. The selection
+is a runtime-neutral seam in `startServer` (it picks the `node:http` shell on
+Node and the `Bun.serve` shell on Bun), designed to also host a future
+`Deno.serve` / embedded adapter. Deno is planned, not yet supported. The
+user-facing reference is the docs-site page `/docs/runtime`; keep the two in sync.
+
+## Node vs Bun
+
+| Area | Node 24+ | Bun |
+|---|---|---|
+| Install | `npm install` (required) | optional (zero-install via Bun auto-install) |
+| Run | `npm run dev` / `npm run start` | `bun run dev` / `bun run start` |
+| Listener | `node:http` shell | native `Bun.serve` (about 1.9x req/s on the listening path) |
+| TS strip | built-in `module.stripTypeScriptTypes` | `amaro` (byte-identical, position-preserving) |
+| SQLite | built-in `node:sqlite` + `drizzle-orm/node-sqlite` | built-in `bun:sqlite` + `drizzle-orm/bun-sqlite` |
+| Hot reload | `node --watch` | `bun --hot` |
+| WebSocket | the `ws` library | native `Bun.serve` + the `BunWsAdapter` bridge |
+| 103 Early Hints | yes | no (`Bun.serve` has no informational-response API) |
+
+The bytes the browser fetches are identical across runtimes. The 103 Early Hints
+gap costs only a small first-load latency edge where an edge forwards 103, never
+correctness (the modulepreload hints still ship in the document head).
+
+## Scaffolding the runtime
+
+`webjs create <name>` defaults to Node. `webjs create <name> --runtime bun` (or
+`bun create webjs <name>`, auto-detected from the invoking package manager,
+#541) emits a Bun-flavored app: `bun.lock`, a pure `oven/bun:1` Dockerfile +
+bun-install CI, bun-command agent docs, and the zero-install bootstrap below.
+`--runtime` is orthogonal to `--template`.
+
+## Bun zero-install (#675)
+
+A Bun app's `dev` / `start` / `db` scripts run through a generated app-local
+`webjs-bun.mjs` bootstrap under `bun --bun`:
+
+```js
+// webjs-bun.mjs
+await import('@webjsdev/cli/bin/webjs.js');
+```
+
+`bun --bun` overrides the `webjs` bin's Node shebang so the server runs on Bun;
+importing the CLI by bare specifier lets Bun auto-install resolve `@webjsdev/*`
+and the app's deps on demand, so a fresh app serves with **no `bun install`**.
+The CLI's `start` is in-process and `dev` re-execs via `process.execPath` (which
+is `bun` here), so the server stays on Bun once the CLI does. `bunx
+@webjsdev/cli` is deliberately NOT used (it runs on Node via the shebang AND
+eager-installs the whole tree). The `start.before` migrate also routes through
+the bootstrap, so the boot-time `webjs db migrate` needs no `webjs` bin in
+`node_modules`. `bun install` stays optional: run it for editor type
+intelligence (no `node_modules` means no local type files) or a pinned offline
+install. The Node-targeted tooling scripts (`test` / `check` / `typecheck`)
+stay plain `webjs` on Node and still expect an install.
+
+**Version pinning (#685).** Bun's auto-install fetches `latest` for a bare
+`import 'zod'`, ignoring package.json and `bun.lock` (it consults neither the
+manifest, the lockfile, nor an `onResolve` plugin, verified in #684). webjs
+closes that gap with an `onLoad` transform: it rewrites a declared dep's bare
+specifier to an inline-versioned one (`zod` to `zod@3.22.4`), which Bun's
+auto-install DOES honor. The version is the EXACT one from `bun.lock` when
+present, else an exact `package.json` pin. Bun resolves an exact inline version
+but ENOENTs on a range or dist-tag (`zod@^3`, `zod@latest`), so a dep declared
+as a RANGE without a `bun.lock` is left bare and resolves to latest as before:
+commit a `bun.lock` (or pin exact versions) to get pinned zero-install. The
+rewrite is server-runtime only (it shapes what Bun fetches for SSR and server
+actions). The browser is still served bare specifiers resolved via the importmap
+/ jspm, unchanged. Only declared deps are rewritten (a transitive dep follows
+from its pinned parent's manifest), and it is a no-op when `node_modules` exists
+(Bun uses the installed copy). Default on. Opt out with `WEBJS_PIN=0` or
+`{ "webjs": { "pin": false } }`.
+
+**Reproducibility:** dev resolves on demand (now at the pinned versions), and the
+scaffold's Bun Dockerfile still keeps an explicit `bun install` so a prod image
+is immutable and self-contained with no registry fetch at boot.
+
+## SQLite busy_timeout (#674)
+
+Both `node:sqlite` and `bun:sqlite` default `busy_timeout` to 0, so a contended
+write throws `database is locked` immediately (better-sqlite3, used before the
+built-in drivers, defaulted to 5000ms). The generated connection sets `PRAGMA
+busy_timeout = 5000` + `PRAGMA journal_mode = WAL` on the raw client before
+drizzle wraps it, on both runtime branches.
+
+## Future runtimes
+
+The listener seam is runtime-neutral, so a `Deno.serve` shell (or an embedded
+adapter) slots in at the same point when added. Edge runtimes with no filesystem
+are a separate, later target. Until then, treat Deno as planned, not supported.

package/resources/agent-docs/styling.md

@@ -234,3 +234,46 @@ More files you write, more discipline required, slight rename cost (2
 textual edits when a route folder moves). In exchange: no browser-
 runtime script, no `@theme` block, idiomatic CSS, plain cascade you can
 debug with any tool.
+
+## Gotcha: a sticky header flickers on iOS, use `position: fixed`
+
+A `position: sticky` header (the common `sticky top-0` pattern) flickers its
+background for one frame on iOS WebKit (every iOS browser, since they all use
+WebKit) during a client-router FORWARD navigation. The scroll-to-top the router
+runs after the content swap drives a sticky stuck-to-static recompute that
+WebKit mis-repaints. It is iOS-only (fine on desktop and Android, and invisible
+in DevTools device emulation, so it shows only on a real device). #610 confirmed
+on-device that neither compositor promotion (`translateZ(0)` / `will-change`)
+nor changing the swap paint timing fixes it.
+
+The fix is `position: fixed` instead of sticky. A fixed header is always pinned
+and never does the scroll-relative recompute, so the repaint bug never fires.
+There is no reliable CSS-only fix that KEEPS `position: sticky` (the GPU-promotion
+hacks `translateZ(0)` / `translate3d` / `will-change` / a wrapper element are all
+variants that do NOT reliably work, confirmed on-device for #610). Preserving the
+header across nav is correct and standard (Next.js, Remix, SvelteKit all preserve
+nested layouts); only the `sticky` positioning is the problem.
+
+Because fixed leaves normal flow, reserve the header height on the content below.
+Use a single `--header-height` custom property as the source of truth rather than
+a hardcoded number, and keep it exact with a `ResizeObserver` so it tracks
+responsive / dynamic headers (degrades fine with no JS via the default):
+
+```css
+:root  { --header-h: 56px; }              /* sane SSR first-paint default */
+header { position: fixed; inset-inline: 0; top: 0; }
+body   { padding-top: var(--header-h); }
+```
+```js
+// refine the default to the header's real height (and on resize)
+const hdr = document.querySelector('header');
+const apply = () => document.documentElement.style.setProperty('--header-h', hdr.offsetHeight + 'px');
+apply();
+new ResizeObserver(apply).observe(hdr);
+```
+
+The example blog's root layout does exactly this (`examples/blog/app/layout.ts`).
+For an app/dashboard layout, an alternative is an app-shell scroll container (a
+non-scrolling `100dvh` flex column with `<main>` as the internal scroller), which
+needs no offset at all but changes the scroll model (the window no longer
+scrolls, so the iOS URL bar stays visible).

package/resources/agent-docs/testing.md

@@ -116,6 +116,17 @@ 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).
 
+**Bun parity is part of the definition of done, not an afterthought.** A change
+to a runtime-sensitive surface (the serializer, the node:http vs `Bun.serve`
+listener + request path, SSR / action / CSRF dispatch, streams, `node:crypto`,
+the TS stripper, auth / session / cors) is NOT done until you have run the Bun
+matrix green AND added or updated a `test/bun/<feature>.mjs` cross-runtime
+assertion for the surface. This is enforced at commit time by
+`.claude/hooks/require-bun-parity-with-runtime-src.sh`, which BLOCKS a commit
+that stages runtime-sensitive `packages/*/src` with no `test/bun/**` test (the
+escape hatch `WEBJS_BUN_VERIFIED=1` is only for when an existing `test/bun`
+script already covers the surface AND you ran it under Bun).
+
 - `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
@@ -127,8 +138,10 @@ edge case, an error-message-format quirk).
   **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).
+- CI runs it in the `bun` job alongside `test/bun/smoke.mjs` (#508),
+  `test/bun/listener.mjs` (#511, the listener-shell parity), and
+  `test/bun/timeouts.mjs` (#663, the `Bun.serve` `idleTimeout` wiring; the pure
+  ms-to-seconds mapping is unit-tested under the matrix too).
 - 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
@@ -249,7 +262,7 @@ test exercises the production contract, never a parallel fake).
 
 ```js
 import { createRequestHandler } from '@webjsdev/server';
-import { testRequest, getCsrf, invokeActionForTest, loginAndGetCookies, withSessionCookie }
+import { testRequest, invokeActionForTest, rawActionRequest, loginAndGetCookies, withSessionCookie }
   from '@webjsdev/server/testing';
 
 const app = await createRequestHandler({ appDir: process.cwd(), dev: true });
@@ -267,12 +280,13 @@ A bare path (`/about`) is prefixed with a dummy origin (the pipeline only reads
 `pathname` + `search`); a full URL string or a pre-built `Request` works too.
 The optional third arg is a standard `RequestInit` (method, headers, body).
 
-### getCsrf + the auth/session helpers
+### The auth/session helpers
 
-The action RPC endpoint requires a `x-webjs-csrf` header matching the
-`webjs_csrf` cookie issued on the first SSR response. `getCsrf(handle)` does the
-initial GET and returns `{ token, cookie, header }` so a test can send a
-CSRF-valid request. `loginAndGetCookies(handle, { email, password })` drives the
+Server-action CSRF is an Origin / `Sec-Fetch-Site` check, so a test needs no
+CSRF setup: `invokeActionForTest` models a same-origin browser POST and passes
+the check automatically, and `rawActionRequest(app, file, fn, args, {
+crossOrigin: true })` models a cross-site request to assert the 403.
+`loginAndGetCookies(handle, { email, password })` drives the
 REAL credentials login through `handle()` (the `createAuth` route handler) and
 captures the genuine signed session `Set-Cookie`, so a follow-up request can hit
 a protected route as the logged-in user:
@@ -302,8 +316,9 @@ const out = await invokeActionForTest(app, 'modules/posts/actions/create.server.
 
 `invokeActionForTest` serializes `args` with the webjs serializer (exactly as
 the generated client stub does), POSTs them to the REAL
-`/__webjs/action/<hash>/<fn>` endpoint with a valid CSRF cookie + header, and
-parses the response with the serializer. The action is addressed by the SHA-256
+`/__webjs/action/<hash>/<fn>` endpoint as a same-origin request (so it passes
+the Origin / Sec-Fetch-Site CSRF check), and parses the response with the
+serializer. The action is addressed by the SHA-256
 hash of its `.server.{js,ts}` file path (absolute or appDir-relative) plus the
 function name, the same scheme the stub uses (`actionEndpoint(appDir, file, fn)`
 returns that path if you need it directly).
@@ -352,8 +367,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

@@ -386,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

@@ -365,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-source.js

@@ -48,8 +48,15 @@ const MAX_FILES = 4000;
  * reliable. The source dir is `src/`, or `lib/` for the cli. A package that is
  * not installed is skipped (not every app depends on every `@webjsdev/*`).
  *
+ * Under Bun ZERO-INSTALL (no `node_modules`, #675) the packages live only in
+ * Bun's global install cache (`<bunCacheDir>/@webjsdev/<pkg>@<version>@@@<n>/`,
+ * which holds the full source). When the `node_modules` walk finds nothing and a
+ * `bunCacheDir` + `readdir` are supplied, fall back to scanning that scope dir
+ * for the package's versioned entry (highest version wins, best-effort), so the
+ * tool works whether the package is installed OR resolved from the Bun cache.
+ *
  * @param {string} cwd
- * @param {{ exists: (p: string) => boolean }} fsDeps
+ * @param {{ exists: (p: string) => boolean, readdir?: (d: string) => Array<{ name: string, isDir: boolean }>, bunCacheDir?: string | null }} fsDeps
  * @returns {Array<{ pkg: string, root: string, src: string }>}
  */
 export function resolveFrameworkRoots(cwd, fsDeps) {
@@ -69,6 +76,8 @@ export function resolveFrameworkRoots(cwd, fsDeps) {
       const cand = join(base, '@webjsdev', pkg);
       if (fsDeps.exists(join(cand, 'package.json'))) { root = cand; break; }
     }
+    // Zero-install fallback: no node_modules, so look in Bun's global cache.
+    if (!root) root = resolveFromBunCache(pkg, fsDeps);
     if (!root) continue;
     // Most packages keep source in `src/`; the cli keeps it in `lib/`. Use
     // whichever exists so every framework package's source is reachable.
@@ -82,6 +91,69 @@ export function resolveFrameworkRoots(cwd, fsDeps) {
   return out;
 }
 
+/**
+ * Locate `@webjsdev/<pkg>` in Bun's global install cache (the zero-install
+ * fallback). Bun caches a scoped package at `<bunCacheDir>/@webjsdev/<pkg>@<ver>@@@<n>/`
+ * (the versioned dir holds the full source; a sibling unversioned `<pkg>/` dir is
+ * metadata, skipped). Picks the highest cached version (semver-aware, so
+ * `0.10.0` beats `0.9.0`), and returns its path only if it carries a
+ * `package.json`. Returns '' when there is no cache dir, no `readdir`, or no
+ * matching entry.
+ *
+ * @param {string} pkg
+ * @param {{ exists: (p: string) => boolean, readdir?: (d: string) => Array<{ name: string, isDir: boolean }>, bunCacheDir?: string | null }} fsDeps
+ * @returns {string}
+ */
+function resolveFromBunCache(pkg, fsDeps) {
+  const { bunCacheDir, readdir, exists } = fsDeps;
+  if (!bunCacheDir || typeof readdir !== 'function') return '';
+  const scopeDir = join(bunCacheDir, '@webjsdev');
+  if (!exists(scopeDir)) return '';
+  let entries;
+  try { entries = readdir(scopeDir); } catch { return ''; }
+  const prefix = `${pkg}@`;
+  // A cache dir is `<pkg>@<version>@@@<n>`; extract <version> (between the name
+  // and the `@@@` cache-key suffix) and sort by it, highest first.
+  const versioned = entries
+    .filter((e) => e.isDir && e.name.startsWith(prefix) && e.name.includes('@@@'))
+    .map((e) => ({ name: e.name, version: e.name.slice(prefix.length).split('@@@')[0] }))
+    .sort((a, b) => compareVersions(b.version, a.version));
+  for (const { name } of versioned) {
+    const cand = join(scopeDir, name);
+    if (exists(join(cand, 'package.json'))) return cand;
+  }
+  return '';
+}
+
+/**
+ * Compare two semver-ish version strings numerically (so `0.10.0` > `0.9.0`),
+ * with a release ranking ABOVE its prerelease (`1.0.0` > `1.0.0-rc.1`). Compares
+ * the release core (`major.minor.patch`) segment by segment numerically; on a
+ * tie, a version WITHOUT a prerelease tag sorts higher, else the prerelease tags
+ * compare lexically. The build suffix (`+...`) is ignored, per semver. Returns
+ * negative / 0 / positive like a comparator.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const [core, pre = ''] = v.split('+')[0].split('-');
+    return { nums: core.split('.').map(Number), pre };
+  };
+  const A = parse(a);
+  const B = parse(b);
+  for (let i = 0; i < Math.max(A.nums.length, B.nums.length); i++) {
+    const x = A.nums[i] || 0;
+    const y = B.nums[i] || 0;
+    if (x !== y) return x - y;
+  }
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1; // a release outranks any prerelease of the same core
+  if (!B.pre) return -1;
+  return A.pre < B.pre ? -1 : 1;
+}
+
 /**
  * Recursively list text-source files under `dir` (absolute paths), skipping
  * `node_modules` / `dist` and bounded by {@link MAX_FILES}.

package/src/mcp.js

@@ -21,7 +21,8 @@
  */
 
 import { createInterface } from 'node:readline';
-import { relative } from 'node:path';
+import { relative, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
 
 import {
   resolveDocsLocation,
@@ -36,6 +37,29 @@ import { resolveFrameworkRoots, runSourceTool } from './mcp-source.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
 
+/**
+ * Best-effort path to Bun's global install cache, for the zero-install `source`
+ * fallback (#687): under Bun zero-install an app has no `node_modules`, so
+ * `@webjsdev/*` lives only in this cache. Prefers `bun pm cache` (authoritative),
+ * then `$BUN_INSTALL/install/cache`, then `~/.bun/install/cache`. Returns null
+ * when none exists (e.g. Bun is not installed), which leaves the tool on the
+ * node_modules path with no behavior change.
+ * @param {(p: string) => boolean} exists
+ * @returns {string | null}
+ */
+function resolveBunCacheDir(exists) {
+  try {
+    const out = spawnSync('bun', ['pm', 'cache'], { encoding: 'utf8' });
+    const dir = out && out.status === 0 && out.stdout ? out.stdout.trim() : '';
+    if (dir && exists(dir)) return dir;
+  } catch { /* bun not on PATH */ }
+  const candidates = [];
+  if (process.env.BUN_INSTALL) candidates.push(join(process.env.BUN_INSTALL, 'install', 'cache'));
+  if (process.env.HOME) candidates.push(join(process.env.HOME, '.bun', 'install', 'cache'));
+  for (const c of candidates) { if (exists(c)) return c; }
+  return null;
+}
+
 // Mirrors packages/server/src/action-config.js. A drift test in
 // packages/mcp/test/mcp.test.mjs asserts these stay in sync with the source.
 /** HTTP verbs an action may declare (mirrors RPC_VERBS in action-config.js). */
@@ -485,7 +509,7 @@ export async function runMcpServer(opts) {
     const { readdirSync, existsSync, realpathSync } = await import('node:fs');
     const readdir = (d) => readdirSync(d, { withFileTypes: true }).map((e) => ({ name: e.name, isDir: e.isDirectory() }));
     sourceDeps = {
-      roots: resolveFrameworkRoots(cwd, { exists: existsSync }),
+      roots: resolveFrameworkRoots(cwd, { exists: existsSync, readdir, bunCacheDir: resolveBunCacheDir(existsSync) }),
       readFile,
       readdir,
       realpath: realpathSync,