@webjsdev/mcp 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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

@@ -22,6 +22,9 @@ reference there.
 | `agent-docs/testing.md` | Unit, browser, convention validation, the `handle()` test harness (`@webjsdev/server/testing`) |
 | `agent-docs/framework-dev.md` | Monorepo dev (only when editing webjs itself): commands, repo-health git config, changelog flow, dev error overlay |
 | `agent-docs/recipes.md` | Page / route / action / component recipes |
+| `agent-docs/orm.md` | Drizzle rc.3 query surface: `db.query` reads, the removed `db.select({...})` projection overload, no-arg `.returning()` (#804) |
+| `agent-docs/types-and-mutations.md` | Where server-derived types live so a shipping module does not pin `db/*.server.ts` (`import type` vs value import, the carrier rule) (#804) |
+| `agent-docs/components-shadowing.md` | Inherited `WebComponent` members app code must not shadow (`title`, `remove`, ...) and the `TS2415`/`TS2416` each produces (#804) |
 | `agent-docs/lit-muscle-memory-gotchas.md` | **READ FIRST** when writing components. Lit patterns that break webjs SSR or reactivity, with the webjs-shaped fix for each |
 
 ---
@@ -50,6 +53,8 @@ cd ../<repo>-<slug>          # do ALL work for the task here
 
 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.
 
+**Cleanup is automatic after a merge.** The `.claude/hooks/cleanup-merged-worktree.sh` PostToolUse hook fires after any `gh pr merge` and removes each linked worktree whose branch is merged AND whose tree is clean, so a merged branch's worktree never leaks (accumulated stale worktrees are exactly what it prevents). It is conservative: it KEEPS anything with uncommitted changes, an unmerged branch, or the worktree you ran the merge from (you cannot remove your current directory, so `cd` out and `git worktree remove` it yourself), and never touches the primary checkout. Disable with `WEBJS_NO_WORKTREE_CLEANUP=1`. Test: `test/hooks/cleanup-merged-worktree.test.mjs`.
+
 ### 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.
@@ -64,7 +69,8 @@ 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). **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.
+3. **Scaffold sync, part of the definition of done (not optional).** The scaffold is webjs's PRIMARY teaching surface for AI agents: they learn the framework by reading the generated gallery/showcase and its comments, then build the real app by adapting them. So when a webjs FEATURE is added or changed, the scaffold that teaches it must move too, the same way the docs must. Ask on EVERY feature change: does a UI feature-gallery demo (`packages/cli/templates/gallery/`, shipped in full-stack + saas), an api backend-showcase endpoint (`packages/cli/lib/api-gallery.js`), a generator surface (`packages/cli/lib/{create,saas-template}.js` for the home/theme/schema/wiring), a scaffold convention (the per-agent rule files in lockstep), or a scaffold test (`test/scaffolds/**`) need to change? Invoke the `webjs-scaffold-sync` skill to walk every surface AND run its mandatory generate + boot + `webjs check` verification (the generators emit strings, so an escaping bug only shows in a freshly generated app). Enforced by `.claude/hooks/require-scaffold-with-src.sh`, which BLOCKS a commit that stages `packages/(core|server|cli)/src` feature source with no scaffold surface (`packages/cli/templates` or `packages/cli/lib`) alongside it (a bug fix, an internal refactor, or a tweak to an already-demoed feature that needs no scaffold change bypasses with `WEBJS_NO_SCAFFOLD_GATE=1`).
+4. **Convention validation.** Run `webjs check` and fix violations.
 
 ### Git workflow (mandatory)
 
@@ -95,7 +101,7 @@ An **AI-first, web-components-first** framework inspired by NextJs, Lit, and Rai
 - **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`.
 - **Server actions with rich types.** A `*.server.{js,ts}` file with `'use server'` exports functions importable from the client (the import is rewritten to a typed RPC stub); the wire round-trips `Date` / `Map` / `Set` / `BigInt` / `Error` / typed arrays / `Blob` / `File` / `FormData` / Symbols / cycles. The source is never served to the browser (invariant 1).
-- **Only files reachable from a browser-bound entry are servable.** The dev server walks the static import graph from every page / layout / error / loading / not-found / component file (lazily on first request, re-derived after each `fs.watch` rebuild); that Set is the authorisation gate, so anything no client code imports returns 404.
+- **Only files reachable from a browser-bound entry are servable.** The dev server walks the import graph from every page / layout / error / loading / not-found / component file (lazily on first request, re-derived after each `fs.watch` rebuild); that Set is the authorisation gate, so anything no client code imports returns 404. The walk follows static `import` / `export … from` AND string-literal dynamic `import('./x.ts')` edges (#751), so a lazily-imported app module is servable (it is NOT eagerly preloaded, since a dynamic import is lazy by intent). A computed `import(expr)` cannot be resolved statically and 404s with a dev hint.
 - **Sensible defaults, overridable.** Memory store in dev, Redis when configured. Built-in auth, sessions, caching, rate limiting, file storage (all pluggable). Tailwind is the default styling. See `agent-docs/built-ins.md`.
 
 ---
@@ -111,9 +117,7 @@ webjs has **no server/client component split.** There is no RSC render tree, no
 
 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.
+- 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. Note: if a page imports a client-effecting utility (like `cn.ts` which accesses client globals), the page module is marked as client-effecting and will be browser-shipped. When this happens, importing any bare server-only utility (like `*.server.ts` queries) inside that page will trigger a `no-server-import-in-browser-module` check violation. To fix this, convert the query to a `'use server'` action or fetch it through a route handler.
 
 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.
 
@@ -152,7 +156,7 @@ sitemap.js robots.js manifest.js icon.js opengraph-image.js twitter-image.js app
 lib/                        app-wide code (lib/*.server.js infra, lib/utils/ browser-safe helpers)
 modules/<feature>/          feature-scoped: actions/ (mutations), queries/ (reads), components/, utils/, types.js
 components/*.js             SHARED presentational primitives
-public/*                    static assets, served at /<name>
+public/*                    static assets, served at /public/<name> (favicon, sw.js, offline.html serve at root)
 db/*.server.{js,ts}         data layer (Drizzle: schema, columns, connection)
 ```
 
@@ -195,12 +199,12 @@ The bare `@webjsdev/core` specifier resolves to a BROWSER bundle dropping server
 | `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`). |
-| `notFound()` / `redirect(url[, status])` | Throw to return 404, or a redirect. No-status default is convention-picked at the catching site: 302 for a GET page-render gate, 307 (method-preserving) for a server-action redirect. Override with `redirect(url, 308)` or `redirect(url, { status })`. |
+| `notFound()` / `redirect(url[, status])` | Throw to return 404, or a redirect. No-status default is convention-picked at the catching site: 302 for a GET page-render gate, 307 (method-preserving) for a server-action redirect. Override with `redirect(url, 308)` or `redirect(url, { status })`. **NEVER** throw `redirect()` inside API route handlers (`route.ts`), as they must return a standard `Response.redirect(url, 303)` response object instead. |
 | `Suspense({fallback, children})` | Page/region-level streaming boundary (a value in a hole). `repeat` keyed-list directive is also re-exported. |
 | `<webjs-suspense .fallback=${html\`…\`}>` | Component-level streaming boundary element (#471): wraps one or more components, flushes `.fallback` on the first byte, streams the resolved content in (concurrently across boundaries, progressively on soft nav). The renderer-recognized opt-in for SLOW async-render data. |
 | `connectWS(url, handlers)` / `richFetch<T>` | Client WebSocket (auto-reconnect, queued sends); content-negotiated rich-type fetch. |
 | `navigate(url, opts?)` / `revalidate(url?)` | Programmatic client-router nav; evict the BROWSER snapshot cache. |
-| `optimistic(signal, value, action)` | Set `signal` immediately, run `action`, roll back on error or `{ success: false }`. |
+| `optimistic(signal, value, action)` / `optimistic(host, { source, update })` | Imperative: set `signal` immediately, run `action`, roll back on error. Declarative (preferred): queue optimistic updates with auto-release via `.add(payload, promise?)`. See `agent-docs/advanced.md`. |
 | `renderStream(payload)` / `WebjsFrame` | `<webjs-stream>` element-level updates (#248); `<webjs-frame>` partial-swap regions (#253). See `agent-docs/advanced.md`. |
 | `Metadata` / `PageProps<R>` / `LayoutProps<R>` / `RouteHandlerContext<R>` / `WebjsConfig` (type-only) | Types for metadata, page/layout/route args (`R` narrows `params` against the `webjs types` route union), and the `webjs` config block. See `agent-docs/metadata.md` + `agent-docs/configuration.md`. |
 
@@ -237,7 +241,7 @@ 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.
 
-**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`.
+**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 declaration OR initializer (e.g., `count = 0` or `todos!: Todo[]`), which compiles to define an own property on the instance and 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).
 
@@ -286,7 +290,7 @@ Optional app-root file default-exporting a **schema object** (env-var names to a
 | Plain `.ts` | yes | **Lint violation** (`use-server-needs-extension`). Rename to add `.server.`. |
 | Plain `.ts` | no | Browser-safe; standard. |
 
-The server-only-utility row (`.server.ts`, no `'use server'`) is a runtime trap: its browser stub throws at module load, so a page / layout / component that ends up SHIPPING to the browser and transitively imports one crashes the moment the module loads, while `webjs typecheck` and the rest of `webjs check` pass. `webjs check`'s `no-server-import-in-browser-module` rule catches this statically by reusing the build's elision verdict (it only flags modules that genuinely ship; a display-only page the framework elides is fine, because the framework strips its server import). A `'use server'` action is exempt: its browser stub is a working RPC, which is the intended way to call the server from a shipping module.
+The server-only-utility row (`.server.ts`, no `'use server'`) is a runtime trap: its browser stub throws at module load, so a page / layout / component that ends up SHIPPING to the browser and transitively imports one crashes the moment the module loads, while `webjs typecheck` and the rest of `webjs check` pass. `webjs check`'s `no-server-import-in-browser-module` rule catches this statically by reusing the build's elision verdict (it only flags modules that genuinely ship; a display-only page the framework elides is fine, because the framework strips its server import). A `'use server'` action is exempt: its browser stub is a working RPC, which is the intended way to call the server from a shipping module. A TYPE-ONLY `import type { Row } from './x.server.ts'` is exempt too, because the TypeScript stripper erases it before it can reach the browser, so sharing a derived row type from a `.server.ts` into a shipping component is safe and is not flagged (#805).
 
 Server actions export named async functions whose args + returns round-trip through the serializer. **Importing from a client component IS the API** (rewritten to an RPC stub; never hand-write `fetch()`). **REST over HTTP is a `route.ts`** that imports and calls the action (optionally via the `route(action, opts?)` adapter from `@webjsdev/server`, which merges query + route params + JSON body into one input object and JSON-responds). **Input validation (#245)** is declared via the `export const validate` config export (read on the RPC boundary); a `route()` endpoint passes the same validator as its `{ validate }` option. The framework only CALLS the validator (ships no validation library) and reads its return (`{ success: true, data? }` runs the action, `{ success: false, fieldErrors }` returns a `422` without running the body, a THROW is a sanitized error, any other value is transformed input). The validator stays server-side and receives the action's first argument. Full reference in `agent-docs/recipes.md`.
 
@@ -294,7 +298,7 @@ Server actions export named async functions whose args + returns round-trip thro
 
 ### RPC + REST endpoint security
 
-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`.
+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 action errors are sanitized to a GENERIC message plus a short `digest`** (#749): a thrown action never returns its raw message to the client (a DB-driver message, an internal IP, an fs path are not author-controlled), the full error is logged server-side keyed by that digest, and the streaming error frame is sanitized the same way; `redirect()` / `notFound()` control-flow throws pass through, and a user-facing message belongs on the `ActionResult` `{ success: false, error }` envelope, not on a throw. 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}`)
 
@@ -336,9 +340,86 @@ The advanced client-router surface is in `agent-docs/advanced.md`: **link prefet
 
 ---
 
+## Mutations: default to optimistic UI
+
+**Use `optimistic()` from `@webjsdev/core` for every user-facing mutation** (create, update, delete, like, toggle, reorder) where the client can predict the result. The UI should feel instant; roll back automatically on failure.
+
+### Preferred: declarative API
+
+```ts
+import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { createTodo } from '#modules/todos/actions/create-todo.server.ts';
+
+class TodoList extends WebComponent({
+  todos: prop<Todo[]>(Array),
+}) {
+  private optimisticTodos = optimistic(this, {
+    source: () => this.todos,
+    update: (state, title: string) => [
+      ...state,
+      { id: crypto.randomUUID() as any, title, completed: false, pending: true },
+    ],
+  });
+
+  async handleSubmit(e: SubmitEvent) {
+    e.preventDefault();
+    const title = new FormData(e.target as HTMLFormElement).get('title') as string;
+    if (!title) return;
+    (e.target as HTMLFormElement).reset();
+
+    const promise = createTodo({ title });
+    this.optimisticTodos.add(title, promise);
+
+    const result = await promise;
+    if (result.success && result.data) {
+      this.todos = [...this.todos.filter(t => t.pending), result.data, ...this.todos.filter(t => !t.pending)];
+    }
+  }
+
+  render() {
+    return html`<ul>${this.optimisticTodos.value.map(todo => html`
+      <li class=${todo.pending ? 'opacity-50' : ''}>${todo.title}</li>
+    `)}</ul>`;
+  }
+}
+TodoList.register('todo-list');
+```
+
+`.add(payload, promise)` auto-releases when the promise settles (resolve or reject). No try-catch, no manual rollback, no temp-ID bookkeeping.
+
+### Simple flips: imperative API
+
+For boolean toggles where the value itself is the mutation:
+
+```ts
+import { signal, optimistic } from '@webjsdev/core';
+import { likePost } from '#actions/like-post.server.ts';
+
+const liked = signal(false);
+// in an @click handler:
+const result = await optimistic(liked, true, () => likePost(postId));
+```
+
+### When to skip optimistic UI
+
+- The result is unpredictable (AI-generated content, server-computed values the client cannot guess).
+- The mutation has side effects the user must wait for (payment processing, email sending, OAuth).
+- The action validates against data that may have changed server-side (unique constraints, race conditions).
+- The mutation is destructive and irreversible with no undo (confirm-first UX is better).
+
+### When optimistic UI is appropriate
+
+- Todo items, comments, posts, likes, follows, toggles, reorders, renames, status changes.
+- Any mutation where the client can construct the expected result from the input.
+- CRUD operations where the server returns the same shape the client already has.
+
+**Never write manual try-catch / cache-and-restore / temp-ID reconciliation** when `optimistic()` covers the pattern. See `agent-docs/advanced.md` for the full reference and `agent-docs/recipes.md` for complete examples.
+
+---
+
 ## Invariants (for both humans and agents)
 
-> 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.
+> Hit one of these as a runtime error? The [Troubleshooting page](https://docs.webjs.dev/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 (`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.
@@ -359,7 +440,7 @@ The advanced client-router surface is in `agent-docs/advanced.md`: **link prefet
 
 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 (`bun --bun` dev/start scripts so the SERVER runs on Bun, `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/db/check tooling stays on Node); `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.
+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. **The scaffold IS the primary teaching surface:** every UI scaffold (full-stack AND saas) ships a densely commented feature gallery (one webjs concept per demo under `app/features/`, logic in `modules/`, plus a whole example app under `app/examples/`), and the `api` template ships a backend-features showcase under `app/api/features/` (the `route()` adapter + validation, rate limiting, streaming, file storage, WebSockets + broadcast) listed in the root `app/route.ts` index; read the demos to learn the idioms, then prune per-feature. Docs at https://docs.webjs.dev.
 
 ---
 

package/resources/agent-docs/advanced.md

@@ -41,10 +41,13 @@ On a client-router navigation to a streamed page, the router applies the respons
 
 Five stacked zero-build optimizations:
 
-1. **`<link rel="modulepreload">` per used component + transitive deps.**
+1. **`<link rel="modulepreload">` per used component + transitive deps + reached vendors.**
    The SSR pass knows every custom element in the final HTML. A startup
-   module-graph scan adds their transitive import dependencies too. All
-   preload hints are deduplicated and emitted in `<head>`.
+   module-graph scan adds their transitive import dependencies too, AND the
+   npm vendor URLs those shipped modules import (#754, flattening the
+   cross-origin CDN waterfall one level; see the no-build model below for the
+   shallow-dependency caveat). All preload hints are deduplicated and emitted
+   in `<head>`, vendor hints carrying their SRI `integrity` + `crossorigin`.
 2. **HTTP/2 multiplex at the edge.** The production server (`npm run start`) speaks plain
    HTTP/1.1. PaaS edges (Railway, Fly, Render, Vercel, Cloudflare Pages,
    Heroku) and reverse proxies (nginx, Caddy, Traefik) speak
@@ -132,9 +135,23 @@ production. The Rails 7+ / Hotwire pattern:
   resource. The browser walks the import graph and fetches each module
   on demand.
 - **`<link rel="modulepreload">` hints at SSR time**: for every component
-  the route uses + its transitive deps from the module graph. The
-  browser parallelizes fetches instead of waterfalling through nested
-  imports. This is what eliminates the perceived gap vs a bundle.
+  the route uses + its transitive deps from the module graph, AND for the
+  npm **vendor** URLs those shipped modules reach (#754). The browser
+  parallelizes fetches instead of waterfalling through nested imports. This
+  is what closes most of the perceived gap vs a bundle. **The honest caveat:**
+  a bundle still wins on a DEEP vendor tree. webjs flattens the FIRST level
+  (the vendor entries your code imports are hinted up front, with their SRI
+  `integrity`, byte-identical to the importmap target so there is no double
+  fetch), but a vendor's OWN transitive deps are still discovered by parsing
+  each fetched CDN module in turn, level by level, over the cross-origin CDN
+  connection. So the complementary mitigation is **shallow-dependency
+  discipline**: prefer few, shallow ESM dependencies (a library with a flat
+  or one-level graph fully benefits; a deep tree still waterfalls past level
+  one). Only REACHED vendors are hinted: a vendor imported solely by an
+  elided display-only component, by a page/layout module dropped from the boot
+  (an inert or import-only page whose binding vendor import is used only during
+  SSR, the canonical SSR-only-dependency case), by a `.server.*` file, or
+  pinned-but-unimported, is never preloaded (no over-fetch).
 - **HTTP/2 multiplex** is what makes per-file serving competitive: one
   TCP+TLS handshake, many module fetches in parallel over the same
   connection. The production server (`npm run start`) speaks plain HTTP/1.1.
@@ -486,10 +503,56 @@ the events + `aria-busy` are a client-only enhancement.
 
 ### Optimistic mutations (`optimistic()`)
 
-`optimistic(signal, value, action)` from `@webjsdev/core` shows a mutation's
-expected result IMMEDIATELY (the UI feels instant), runs the real server action,
-and ROLLS BACK on failure. It is a thin wrapper over the signal primitive, no
-state machine.
+`optimistic()` from `@webjsdev/core` shows a mutation's expected result IMMEDIATELY (the UI feels instant), runs the real server action, and ROLLS BACK on failure. **Use it for every user-facing mutation where the client can predict the result** (create, update, delete, like, toggle, reorder). See `agent-docs/recipes.md` for complete examples.
+
+#### Declarative API (preferred)
+
+`optimistic(host, { source, update })` returns an `OptimisticState<State, Action>` with a `.value` getter and `.add(payload, promise?)` method. The reducer transforms the current state with each payload; `.add()` pushes an update and schedules a re-render. When a `promise` is passed, the update auto-releases on settlement (`.finally()` or a `.then()` fallback for thenables lacking `.finally`).
+
+```ts
+import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { createTodo } from '#modules/todos/actions/create-todo.server.ts';
+
+class TodoList extends WebComponent({
+  todos: prop<Todo[]>(Array),
+}) {
+  private optimisticTodos = optimistic(this, {
+    source: () => this.todos,
+    update: (state, title: string) => [
+      ...state,
+      { id: crypto.randomUUID() as any, title, completed: false, pending: true },
+    ],
+  });
+
+  async handleSubmit(e: SubmitEvent) {
+    e.preventDefault();
+    const title = new FormData(e.target as HTMLFormElement).get('title') as string;
+    if (!title) return;
+    (e.target as HTMLFormElement).reset();
+
+    const promise = createTodo({ title });
+    this.optimisticTodos.add(title, promise);
+
+    const result = await promise;
+    if (result.success && result.data) {
+      this.todos = [...this.todos.filter(t => t.pending), result.data, ...this.todos.filter(t => !t.pending)];
+    }
+  }
+
+  render() {
+    return html`<ul>${this.optimisticTodos.value.map(todo => html`
+      <li class=${todo.pending ? 'opacity-50' : ''}>${todo.title}</li>
+    `)}</ul>`;
+  }
+}
+TodoList.register('todo-list');
+```
+
+Multiple `.add()` calls stack independently; each `release()` removes its own update by ID. When `update` is omitted, the payload replaces the state directly (`Action = State`), matching the simple `useOptimistic(setState)` pattern.
+
+#### Imperative API (simple flips)
+
+`optimistic(signal, value, action)` is a thin wrapper over the signal primitive for simple boolean flips:
 
 ```ts
 import { signal, optimistic } from '@webjsdev/core';
@@ -505,9 +568,7 @@ const result = await optimistic(liked, true, () => likePost(postId));
 // to the authoritative value from `result` if you need it.
 ```
 
-It rolls back on a thrown error OR an `ActionResult` `{ success: false }`
-envelope, and never on success. Client-only (it mutates a signal), so a
-component importing it is never elided as display-only.
+It rolls back on a thrown error OR an `ActionResult` `{ success: false }` envelope, and never on success. Client-only (it mutates a signal), so a component importing it is never elided as display-only.
 
 ### Wire-byte optimization
 
@@ -642,6 +703,28 @@ document.addEventListener('webjs:prefetch', (e) => {
 });
 ```
 
+### `webjs:before-cache` (strip transient state before a back/forward snapshot)
+
+The router keeps a URL-keyed snapshot cache (Turbo's SnapshotCache pattern) so
+Back/Forward restores instantly. Because a snapshot is a raw `outerHTML` clone of
+the live page, anything OPEN at navigate-away time (a hover-card, a dropdown, a
+toast) is captured open and **restored open** on Forward. To prevent that, the
+router dispatches `webjs:before-cache` on `document` **synchronously, on the page
+being cached, immediately before the `outerHTML` read** (detail `{ url }`). A
+handler's DOM mutations are captured in the snapshot; the live edits are
+invisible because the page is being navigated away from (Turbo's
+`turbo:before-cache` contract). Reset transient state here:
+
+```ts
+document.addEventListener('webjs:before-cache', () => {
+  document.querySelectorAll('[data-transient]').forEach((el) => el.remove());
+  // close open menus, clear in-progress toasts, reset a wizard step, ...
+});
+```
+
+The kit's overlays (hover-card, tooltip, dropdown-menu, dialog, alert-dialog,
+sonner) already listen and reset their open state, so they come back closed.
+
 ### View Transitions (opt-in, all three swap paths)
 
 The router can wrap a client navigation's DOM mutation in the native
@@ -1163,7 +1246,7 @@ prod. A truncated stream (a server crash, a dropped connection) also throws
 rather than completing silently: a healthy stream always ends in an explicit
 terminal frame, so a missing one is an error. For a slow region you want behind a fallback on the FIRST paint, use
 `<webjs-suspense>` instead; streaming RPC is for an imperative stream consumed
-after an interaction. Full reference: the [Data fetching](https://docs.webjs.com/docs/data-fetching) page.
+after an interaction. Full reference: the [Data fetching](https://docs.webjs.dev/docs/data-fetching) page.
 
 ### Opt out per link
 

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

@@ -59,6 +59,13 @@ export const listPosts = cache(
 );
 ```
 
+Cached values round-trip through the same rich serializer as the RPC wire
+(`Date` / `Map` / `Set` / `BigInt` / typed arrays / cycles), so a warm cache
+hit returns the exact same value shape as a cold miss (a row's `createdAt`
+stays a `Date`, never degrades to a string). Cache keys are rich-serialized
+too, so a `Map` / `Set` argument is a distinct key per value instead of
+colliding. You do not need cached values to be JSON-plain.
+
 To invalidate a read from an UNRELATED mutation (without importing the
 wrapper), add `tags`. It is either a static `string[]` or a function
 `(...args) => string[]` so a per-entity read tags with the id:
@@ -105,13 +112,16 @@ exact id by tag. An untagged `cache()` is untouched by any `revalidateTag`.
 evicts cached HTML. Together they are the **server cache invalidation
 surface**, both imported from `@webjsdev/server`.
 
-**Multi-instance note.** The tag index is a thin, non-atomic
-read-modify-write of a JSON array in the store. With a shared Redis store,
-`revalidateTag` reaches every instance for the keys it can see, but two
-instances appending to one tag concurrently can lose an append, so a
-freshly-stored key on a peer might miss eviction and live until its TTL.
-The index entry carries the cache TTL so it self-prunes. For strict
-cross-instance invalidation, prefer a short `ttl` as the floor.
+**Multi-instance note.** On the built-in memory and Redis stores the tag
+index is a real set (a native `Set` in memory, a Redis `SADD` set), so
+adding a cache key to a tag is an atomic insert. Two mutations appending to
+the same tag concurrently (across Redis instances, or interleaved in one
+process) no longer lose an entry, so `revalidateTag` reliably evicts every
+tagged key (#752). A custom store that does not implement the optional
+atomic-set methods (`setAdd` / `setMembers`) falls back to the older
+non-atomic JSON path, where a concurrent append can be lost; there, prefer a
+short `ttl` as the cross-instance floor. The index entry carries the cache
+TTL so it self-prunes either way.
 
 ### Server HTML response cache (`export const revalidate`, ISR for no-build)
 

package/resources/agent-docs/components-shadowing.md

@@ -0,0 +1,87 @@
+# Component member shadowing: names a WebComponent must not reuse
+
+A `WebComponent` inherits two layers of members. In the browser it extends
+`HTMLElement` (so every DOM property and method is present), and it extends the
+framework base that owns the reactivity lifecycle (`render`, `update`,
+`requestUpdate`, and the lit-aligned hooks). SSR swaps `HTMLElement` for an
+`ElementShim`-style stand-in with the same public surface. When app code
+declares a reactive property (via the `WebComponent({ ... })` factory) or a
+method whose NAME collides with one of those inherited members, one of two
+things happens.
+
+- **Type-incompatible collision.** TypeScript refuses the class. A reactive
+  property that shadows a native property of a different type raises **`TS2415`**
+  on the `class X extends WebComponent({ ... })` line ("Class 'X' incorrectly
+  extends base class ...; types of property 'y' are incompatible"). A method or
+  field in the class body whose signature differs from the inherited one raises
+  **`TS2416`** on that member ("Property 'y' in type 'X' is not assignable to the
+  same property in base type").
+- **Type-compatible collision.** It compiles, then silently hijacks the native
+  member at runtime (a `title` reactive prop overrides the element's tooltip /
+  `title`-attribute reflection, a `hidden` prop overrides native hide behavior).
+  No error, wrong behavior.
+
+The fix for every row below is the same. **Rename the field or method** to a
+name that is not an inherited member (`postTitle` instead of `title`,
+`removeItem` instead of `remove`). Only override an inherited lifecycle method
+deliberately and with its exact signature (override `render` / `connectedCallback`
+on purpose, never repurpose the name for unrelated app logic).
+
+## Members not to shadow
+
+| Member | Origin | Base type or signature | Shadow with an app prop / method | Error | Fix (rename to) |
+|---|---|---|---|---|---|
+| `title` | HTMLElement | `string` | `title: prop<Post>(Object)` (a post object) | `TS2415` | `post`, `heading` |
+| `id` | HTMLElement | `string` | `id: prop(Number)` (a numeric row id) | `TS2415` | `postId`, `rowId` |
+| `slot` | HTMLElement | `string` | `slot: prop<Slot>(Object)` | `TS2415` | `bookingSlot` |
+| `role` | HTMLElement | `string \| null` | `role: prop<Role>(Object)` (a user role) | `TS2415` | `userRole` |
+| `hidden` | HTMLElement | `boolean` | `hidden: prop(String)` | `TS2415` | `isHidden` (or keep `boolean`) |
+| `dir` | HTMLElement | `string` | `dir: prop<Direction>(Object)` | `TS2415` | `direction` |
+| `lang` | HTMLElement | `string` | `lang: prop<Lang>(Object)` | `TS2415` | `language` |
+| `translate` | HTMLElement | `boolean` | `translate: prop(String)` | `TS2415` | `translationKey` |
+| `draggable` | HTMLElement | `boolean` | `draggable: prop(String)` | `TS2415` | `isDraggable` |
+| `tabIndex` | HTMLElement | `number` | `tabIndex: prop(String)` | `TS2415` | `tabOrder` |
+| `className` | HTMLElement | `string` | `className: prop<string[]>(Array)` | `TS2415` | `variantClasses` |
+| `dataset` | HTMLElement | `DOMStringMap` | `dataset: prop<Data>(Object)` | `TS2415` | `payload`, `meta` |
+| `remove` | Element | `(): void` | `remove(id: number): Promise<void>` | `TS2416` | `removeItem`, `deleteRow` |
+| `closest` | Element | `(sel: string) => Element \| null` | `closest(n: number)` | `TS2416` | `nearest` |
+| `matches` | Element | `(sel: string) => boolean` | `matches(other: T)` | `TS2416` | `isMatch` |
+| `focus` | HTMLElement | `(opts?) => void` | `focus(field: string)` | `TS2416` | `focusField` |
+| `blur` | HTMLElement | `(): void` | `blur(amount: number)` | `TS2416` | `applyBlur` |
+| `click` | HTMLElement | `(): void` | `click(e: Event)` | `TS2416` | `handleClick` |
+| `append` / `prepend` | Element | `(...nodes) => void` | `append(item: T)` | `TS2416` | `appendItem` |
+| `before` / `after` | Element | `(...nodes) => void` | `after(cb: () => void)` | `TS2416` | `runAfter` |
+| `render` | WebComponent | `() => TemplateResult \| Promise<...>` | `render(data: T)` (arg added) | `TS2416` | override with the real signature |
+| `update` | WebComponent | `(changed: Map) => void` | `update(input: T)` | `TS2416` | `applyUpdate`, `save` |
+| `requestUpdate` | WebComponent | `(name?, old?) => void` | `requestUpdate(payload: T)` | `TS2416` | `queueUpdate` |
+| `updated` / `firstUpdated` | WebComponent | `(changed: Map) => void` | `updated(row: T)` | `TS2416` | `onUpdated` |
+| `willUpdate` / `shouldUpdate` | WebComponent | `(changed: Map) => boolean \| void` | repurposed for app logic | `TS2416` | rename or override correctly |
+| `connectedCallback` | WebComponent | `(): void` | `connectedCallback(user: T)` | `TS2416` | override with no args |
+| `renderError` / `renderFallback` | WebComponent | `(err?) => TemplateResult` | `renderFallback(id: number)` | `TS2416` | override with the real signature |
+| `addController` / `removeController` | WebComponent | `(c: Controller) => void` | app method of the same name | `TS2416` | rename |
+| `updateComplete` | WebComponent | `get(): Promise<boolean>` | `updateComplete: prop(Boolean)` | `TS2415` | `isComplete` |
+
+Framework-private fields are all underscore-prefixed (`_renderRoot`,
+`_connected`, `_changedProperties`, `_updatePromise`, `_isUpdating`). Never
+declare a reactive prop or field with a leading underscore that matches one, and
+never write to them from app code. Use a plainly-named reactive prop or a signal
+instead.
+
+## Names that are safe (not inherited)
+
+Common component prop names that do NOT collide, so they need no rename.
+
+`label`, `open`, `count`, `value` (declare it, native `HTMLElement` has none),
+`name`, `items`, `todos`, `active`, `variant`, `size`, `checked`, `selected`,
+`heading`, `caption`, `message`, `status`.
+
+Note. `open`, `value`, `checked`, and `selected` ARE native properties on
+specific built-in elements (`<details>`, `<input>`, `<option>`), but a
+`WebComponent` extends the generic `HTMLElement`, which does not define them, so
+they are free on a custom element. When in doubt, grep the base surface in
+`packages/core/src/component.js` (or `node_modules/@webjsdev/core/src/component.js`
+in an app) rather than guessing.
+
+Cross-references. Reactive property declaration is in the root `AGENTS.md`
+(`WebComponent` essentials) and `agent-docs/components.md`. The lit patterns that
+break webjs reactivity are in `agent-docs/lit-muscle-memory-gotchas.md`.

package/resources/agent-docs/components.md

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