@webjsdev/mcp 0.1.3 → 0.1.4

package/package.json

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

@@ -37,6 +37,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.
@@ -75,7 +87,7 @@ 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.
 - **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.
@@ -139,12 +151,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 +183,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 +210,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 via the `default` option (`prop(Number, { default: 0 })`, a function default for a fresh object / array per instance) OR in the constructor after `super()`. 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`. 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).
 
@@ -285,7 +325,7 @@ type ActionResult<T> =
 
 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), 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).
 
 ---
 
@@ -297,7 +337,7 @@ The advanced client-router surface is in `agent-docs/advanced.md`: **link prefet
 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 +350,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 (`bun --bun` dev/start scripts so the SERVER runs on Bun, `trustedDependencies`, `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.
 

package/resources/agent-docs/advanced.md

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

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,47 @@ 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
+## Declaring reactive properties: the base-class factory
+
+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 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.
+The bare form takes a type constructor (`count: Number`, `label: String`, `open: Boolean`). The `prop()` helper carries options and narrows the TS type:
 
-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.
+```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 via the `default` option (a function default runs per instance for a fresh object / array) or in the constructor after `super()`. **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
+// default via the option (no constructor needed)
+class Counter extends WebComponent({
+  count: prop(Number, { default: 0 }),
+  items: prop(Array, { default: () => [] }), // function default = fresh array per instance
+}) {}
+```
 
 ## Lifecycle hooks (lit-aligned)
 
@@ -55,9 +90,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 +108,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,7 +184,7 @@ 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.

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

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

package/resources/agent-docs/recipes.md

@@ -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/testing.md

@@ -352,8 +352,8 @@ test/
 
 App-side runners:
 
-- `webjs test` → node tests (everything not under `browser/` or `e2e/`).
-- `webjs test --browser` → web-test-runner against `test/**/browser/**`.
+- `webjs test` → the runtime's test runner over everything not under `browser/` or `e2e/` (#570): `node --test` on Node, `bun test` on Bun (dispatched on `process.versions.bun`, since `bun --test` is invalid).
+- `webjs test --browser` → web-test-runner against `test/**/browser/**` (the app's resolved `wtr` bin, spawned with the current runtime, no `npx`).
 - `WEBJS_E2E=1 webjs test` adds e2e.
 
 App AI agents read this convention through the scaffold's

package/resources/agent-docs/typescript.md

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