@webjsdev/mcp 0.1.0 → 0.1.2

package/README.md

@@ -25,9 +25,11 @@ subcommand) delegates to this same server, so both routes run identical code.
 ## What it exposes
 
 - **Introspection tools** (read-only, scoped to an `appDir`): `list_routes`,
-  `list_actions` (with the `/__webjs/action/<hash>/<fn>` RPC endpoints),
-  `list_components`, `check` (the structured `webjs check` violations). Each
-  projects an existing `@webjsdev/server` data function and mutates nothing.
+  `list_actions` (RPC endpoints plus the full data contract: HTTP verb, cache
+  config, and boolean flags for tags/invalidates/validate/middleware; reserved
+  config exports are excluded from the callable-action list), `list_components`,
+  `check` (the structured `webjs check` violations). Each projects an existing
+  `@webjsdev/server` data function and mutates nothing.
 - **Knowledge layer**: an `init` mental-model primer, a `docs` retrieval tool,
   MCP `resources` (the `agent-docs/*` corpus + `AGENTS.md` as `webjs-docs://*`),
   and `prompts` (the recipes as guided workflows).

package/package.json

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

@@ -107,7 +107,7 @@ A page/layout module still **loads** in the browser for its top-level side effec
 
 ## Framework source: where to find it
 
-Plain JS with JSDoc lives in `node_modules/@webjsdev/` (`core/`, `server/`, `cli/`, `mcp/`, `ts-plugin/`, `ui/`); what you read is what runs. Starting points: SSR `@webjsdev/server/src/ssr.js`, client hydration `@webjsdev/core/src/render-client.js`, client router `@webjsdev/core/src/router-client.js`, convention rules `@webjsdev/server/src/check.js`. For UI debugging use the Playwright MCP server; for live introspection the scaffold wires the read-only `@webjsdev/mcp` server (`npx @webjsdev/mcp`, also reachable as `webjs mcp`): `list_routes`, `list_actions`, `list_components`, `check`, plus a knowledge layer (docs / recipes / framework source).
+Plain JS with JSDoc lives in `node_modules/@webjsdev/` (`core/`, `server/`, `cli/`, `mcp/`, `intellisense/`, `ui/`); what you read is what runs. Starting points: SSR `@webjsdev/server/src/ssr.js`, client hydration `@webjsdev/core/src/render-client.js`, client router `@webjsdev/core/src/router-client.js`, convention rules `@webjsdev/server/src/check.js`. For UI debugging use the Playwright MCP server; for live introspection the scaffold wires the read-only `@webjsdev/mcp` server (`npx @webjsdev/mcp`, also reachable as `webjs mcp`): `list_routes`, `list_actions`, `list_components`, `check`, plus a knowledge layer (docs / recipes / framework source).
 
 ---
 
@@ -149,7 +149,7 @@ import { html, css, WebComponent, render } from '@webjsdev/core';
 import { renderToString } from '@webjsdev/core/server';
 ```
 
-The bare `@webjsdev/core` specifier resolves to a BROWSER bundle dropping server-only modules (`render-server.js`, `expose.js`, `setCspNonceProvider`); `renderToString` / `renderToStream` live at `@webjsdev/core/server` for Node-side consumers.
+The bare `@webjsdev/core` specifier resolves to a BROWSER bundle dropping server-only modules (`render-server.js`, `setCspNonceProvider`); `renderToString` / `renderToStream` live at `@webjsdev/core/server` for Node-side consumers.
 
 | Export | Purpose |
 |---|---|
@@ -158,10 +158,9 @@ 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)` | Throw to return 404, or 307/308 redirect. |
-| `expose(p, fn)` | Tag a server action ALSO reachable at a REST path. Server-side only. |
-| `validateInput(fn, validate)` | Attach an input validator running on BOTH the RPC and `expose()` REST paths (#245). Server-side only. See Server actions. |
-| `Suspense({fallback, children})` | Streaming boundary. `repeat` keyed-list directive is also re-exported. |
+| `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 })`. |
+| `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 }`. |
@@ -196,7 +195,9 @@ MyThing.register('my-thing');
 
 **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).
 
-**Light DOM (default) vs Shadow DOM.** Light DOM applies global CSS and Tailwind directly (default; for Tailwind/global CSS + simple composition). Shadow DOM (`static shadow = true`) is for `static styles` scoped CSS and third-party isolation; `<slot>` works in either. A light-DOM component authoring custom CSS MUST prefix every class selector with its tag name (invariant 7); prefer Tailwind. Install the `webjs` VSCode extension (`packages/editors/vscode`, VS Marketplace + Open VSX; also covers Cursor / Antigravity / Windsurf) or `webjs.nvim` (`packages/editors/nvim`, via lazy.nvim) for template highlighting + editor intelligence with no Lit plugin, or add the standalone `@webjsdev/ts-plugin` to `tsconfig.json` `plugins` manually (JetBrains). Full deep-dive in `agent-docs/components.md` + `agent-docs/lit-muscle-memory-gotchas.md`.
+**Async render (`async render()`), bare-await data fetch (#469).** A component may write `async render() { const u = await getUser(this.id); return html\`<h3>${u.name}</h3>\`; }`. Writing `await` makes the function async by JS rule, and every render path awaits a promise-returning `render()` automatically (no flag). This co-locates the fetch in the leaf component (no prop-drilling). The model is decoupled into three separate concerns. (1) **SSR always blocks**, so the resolved DATA is in the first paint with no fallback markup (PE-safe, JS-off reads it). (2) **The client re-fetch default is stale-while-revalidate**: when a prop / dependency change re-runs `async render()`, the current content stays until the new render resolves (no blank, no flash). (3) **`renderFallback()` is the OPTIONAL re-fetch loading UI**, a prop-aware method shown ONLY during a client re-fetch, NEVER on the first paint, and it does NOT trigger SSR streaming. **Errors are isolated per component by default** (no user code): a thrown `await getData()` renders a component-scoped error state while siblings render, and `renderError()` optionally customizes it (dev surfaces the message, prod stays silent). `getData()` is already isomorphic (a `'use server'` action is the real function during SSR and an RPC stub on the client), so the same line works both sides. Use `async render()` for request-time-known SERVER data that should be in the first paint; keep `Task` / signals for genuinely client-only data (a `Task` shows its pending state at SSR, losing first-paint data). A **bare** async-render component (an `async render()` with no other client signal, light DOM) is **elided** like any display-only component (#474): its SSR'd HTML is the complete output, so the framework drops the module AND the redundant on-hydration re-fetch. It SHIPS only when it also carries an independent signal (an `@event`, a non-`state` reactive prop, a signal / reactive import, a lifecycle hook including `renderFallback()`, a `<slot>`, `static shadow = true`, `static refresh = true`, cross-module observation, or a transitively-reachable interactive child). Two carve-outs always ship: `static shadow = true` (Declarative Shadow DOM attaches only during HTML parsing, so a streamed or soft-navigated shadow component needs its module to re-run `attachShadow`) and `static refresh = true` (the explicit opt-in keeping the stale-while-revalidate on-load re-fetch that eliding drops, moot for request-stable data). **For SLOW data where blocking the first byte hurts, wrap the region in `<webjs-suspense .fallback=${html\`…\`}>` to STREAM it** (the fallback flushes on the first byte, the data streams in; multiple boundaries fetch concurrently). This is the only way to show a first-paint fallback, a deliberate choice for slow regions, and it streams progressively on soft navigation too. A throwing component inside a boundary is isolated (renders its error state, siblings stream). **The on-hydration re-fetch is itself eliminated by SSR action seeding (#472):** each `'use server'` action result invoked during a (non-streamed) SSR render is serialized into the page, and the generated RPC stub reads that seed on its first client call, so a shipping async component does NOT re-issue the RPC on hydration (a later refetch / arg-change still goes to the network). Keyed by action-hash + fn + serialized args, consume-once, fail-open (a miss degrades to a normal RPC, never wrong data). Captured via a transparent server-side `'use server'` facade (no source transform, no build step; the browser source tab and on-disk files are unchanged), default on, opt out with `"webjs": { "seed": false }` or `WEBJS_SEED=0`.
+
+**Light DOM (default) vs Shadow DOM.** Light DOM applies global CSS and Tailwind directly (default; for Tailwind/global CSS + simple composition). Shadow DOM (`static shadow = true`) is for `static styles` scoped CSS and third-party isolation; `<slot>` works in either. A light-DOM component authoring custom CSS MUST prefix every class selector with its tag name (invariant 7); prefer Tailwind. Install the `webjs` VSCode extension (`packages/editors/vscode`, VS Marketplace + Open VSX; also covers Cursor / Antigravity / Windsurf) or `webjs.nvim` (`packages/editors/nvim`, via lazy.nvim) for template highlighting + editor intelligence with no Lit plugin, or add the standalone `@webjsdev/intellisense` to `tsconfig.json` `plugins` manually (JetBrains). Full deep-dive in `agent-docs/components.md` + `agent-docs/lit-muscle-memory-gotchas.md`.
 
 ---
 
@@ -239,11 +240,15 @@ 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. |
 
-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()`). **Expose as REST:** `expose('METHOD /path', fn, { validate? })`. **Input validation runs on BOTH call paths (#245),** declared via `validateInput(fn, validate)` or `expose(..., { validate })`; 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`.
+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.
+
+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`.
+
+**HTTP-verb actions via config exports (#488).** A `'use server'` action declares its HTTP semantics through RESERVED sibling exports the framework reads statically, the same way a page declares `export const revalidate`: `export const method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'` (absent = POST, so existing actions are unchanged), `export const cache = 60` (seconds, or `{ maxAge, swr, public }`, default `private`; **`public: true` SHARES the response across users keyed only by URL + args, so use it ONLY for data identical for every visitor, never for a session / per-user read, the same safety rule as a page's `export const revalidate`**), `export const tags = (id) => [\`user:${id}\`]` (a GET's cache tags), `export const invalidates = (id) => [...]` (a mutation's tags to evict), `export const validate = (input) => ...` (the boundary validator), and `export const middleware = [mw1, mw2]` (#490: per-action middleware, each `async (ctx, next) => result`, run around the action on BOTH the RPC and `route.ts` (including the `route()` adapter) boundaries; a middleware short-circuits by returning an `ActionResult` instead of calling `next()`, and accumulates context the action reads via `actionContext()` from `@webjsdev/server`, no signature change). The function stays a plain `export async function`; **one function per file** (a configured file with more than one callable function is a `webjs check` error). The call site never changes (`await getUser(7)`); the verb only changes the transport: a **GET** rides args in the URL (`?a=`, with a POST fallback over a 4KB cap), is CSRF-exempt, carries `Cache-Control` + a weak ETag (answering `If-None-Match` with a 304) and `X-Webjs-Tags`, and reads the SSR seed (#472) first; a **mutation** (POST/PUT/PATCH/DELETE) sends the rich body (DELETE rides the URL), is CSRF-protected, and on completion (the action did not throw) evicts its `invalidates` tags from the server `cache()` (`revalidateTags`) and reports them via `X-Webjs-Invalidate` so the client browser-cache coordinator revalidates a later read. A mismatched request method is a `405` + `Allow`. Why webjs needs this and Next does not: webjs has no RSC server/client split, so reads and writes both flow through the one action mechanism (Next's reads are Server Component fetches, so its actions stay POST-only). `validate` is a BOUNDARY concern (the RPC endpoint and a `route.ts`), not a direct server-to-server call. A public REST endpoint is a `route.ts` that imports and calls the action (optionally via the `route()` adapter). **Cancellation (#492):** an action reads the request's `AbortSignal` via `actionSignal()` (from `@webjsdev/server`) to stop work on a client disconnect / abort (a never-aborting signal outside an action keeps the line safe server-to-server); on the client, a superseded `async render()` automatically ABORTS the previous render's in-flight action fetch (not just drops it), via a per-render `AbortController` the stub binds each fetch to. **Streaming results (#489):** an action that RETURNS a `ReadableStream` / async iterable / async generator (any verb) streams its chunks over the single RPC response instead of buffering; the call site does `for await (const chunk of await streamTokens(8))` and each rich-serialized chunk arrives as it is yielded (back-pressure respected, the source generator cancelled on a client disconnect / superseded render). Detection is purely on the return value (no config export); a streamed result is never cached / ETagged / seeded (a mutation still emits `X-Webjs-Invalidate`). A mid-stream throw surfaces as an error from the iterable (the HTTP status is already 200), the author message in prod.
 
-### RPC + expose security
+### RPC + REST endpoint security
 
-Client to action RPC posts `x-webjs-csrf` matching the cookie issued on first SSR (mismatch 403); prod errors are sanitized to `message` only. `expose()`d REST endpoints are NOT CSRF-protected: authenticate every mutating endpoint, use `validate`, log without secrets, rate-limit. For CORS use the `cors()` middleware from `@webjsdev/server`; **`credentials: true` REQUIRES an explicit origin allowlist, never `'*'`.** See `agent-docs/advanced.md`.
+Client to action RPC posts `x-webjs-csrf` matching the cookie issued on first SSR (mismatch 403); prod errors are sanitized to `message` only. A `route.ts` REST endpoint (hand-written or via the `route()` adapter) is NOT CSRF-protected: authenticate every mutating endpoint, use `validate`, log without secrets, rate-limit. For CORS use the `cors()` middleware from `@webjsdev/server`; **`credentials: true` REQUIRES an explicit origin allowlist, never `'*'`.** See `agent-docs/advanced.md`.
 
 ### Components (`components/*.{js,ts}`)
 

package/resources/agent-docs/advanced.md

@@ -18,6 +18,25 @@ fallback flushes immediately, and the resolved content streams in as a
 `<template>` + inline `__webjsResolve('id')` script when the promise
 lands. Nested Suspense supported.
 
+### Component-level streaming: `<webjs-suspense>` (#471)
+
+`Suspense({ fallback, children })` above is the page/region-level primitive (a promise passed as `children`). With **async render** (`agent-docs/components.md`), a COMPONENT is the suspending unit: a component doing `async render() { const u = await getUser(this.uid); … }` BLOCKS the first byte by default (real data in the first paint). To STREAM a slow component, wrap it in the renderer-recognized `<webjs-suspense>` element:
+
+```js
+html`
+  <webjs-suspense .fallback=${html`<p>Loading section…</p>`}>
+    <user-profile uid="42"></user-profile>
+    <user-activity uid="42"></user-activity>
+  </webjs-suspense>
+`;
+```
+
+`.fallback` is read at SSR as the inline placeholder (`render-server.js`'s `processSuspenseElements` carries it via `data-webjs-fallback`, since a `TemplateResult` is not serializer-safe) and flushed on the first byte; the children push to `ctx.pending` and stream in via the same `<template data-webjs-resolve>` engine. Multiple boundaries resolve via `Promise.all`, so they fetch concurrently (no server waterfall). One boundary groups several components under one fallback (the boundary `.fallback` wins over a contained component's `renderFallback()`), and a throwing component inside is isolated to its own error state while siblings stream. Without a streaming context (`renderToString`) the children render inline (blocking).
+
+### Progressive soft-nav streaming (#473)
+
+On a client-router navigation to a streamed page, the router applies the response PROGRESSIVELY: the SSR stream flushes the shell (with fallbacks) plus a `<!--wj-stream-shell-->` sentinel, the router's `readStreamedShell` swaps the shell in immediately and advances the URL, then `streamBoundariesProgressively` applies each resolved boundary into the live DOM as it streams (fast-before-slow), upgrading the custom elements inside. So a soft nav matches the initial-load experience instead of buffering the whole response. A non-streaming page is read to completion and applied once; a navigation superseded mid-stream stops and cancels the reader; a mid-stream transport failure leaves the applied boundaries in place (non-destructive).
+
 ## First-paint performance without a build step
 
 Five stacked zero-build optimizations:
@@ -42,10 +61,20 @@ Five stacked zero-build optimizations:
    `connectedCallback` activation. Ideal for below-the-fold widgets.
 5. **Auto-vendor via jspm.io (Rails 7 + importmap-rails posture).** At
    startup the server scans client-reachable source for bare npm import
-   specifiers. Each `pkg@version` is resolved through `api.jspm.io/generate`
-   to a CDN URL (`https://ga.jspm.io/npm:<pkg>@<version>/...`) and added
-   to the import map; the browser fetches each package directly from
-   the CDN. **SRI integrity (SHA-384) is computed on BOTH paths.** A
+   specifiers. The WHOLE scanned set is resolved in ONE
+   `api.jspm.io/generate` call (a single `install[]` array) so jspm
+   computes one mutually-consistent dependency graph: a directly-imported
+   package and a transitive that needs a newer version of the same package
+   agree on one CDN URL, instead of skewing (a direct dep pinned to its
+   local version while a transitive floats to jspm-latest, which crashed
+   the browser with a missing export). Each resolved entry is a CDN URL
+   (`https://ga.jspm.io/npm:<pkg>@<version>/...`) added to the import map;
+   the browser fetches each package directly from the CDN. If the unified
+   call fails because some install is unresolvable (a 401 for a private or
+   server-only dep), the resolver falls back to per-package isolation for
+   the offending install(s) and re-resolves the resolvable survivors as one
+   graph, so one bad dep can never collapse the whole map.
+   **SRI integrity (SHA-384) is computed on BOTH paths.** A
    live-resolved (unpinned) app hashes each cross-origin bundle at warmup
    and emits `integrity` + `crossorigin` on the importmap and modulepreload
    tags, so a swapped or compromised CDN response is rejected by the browser
@@ -60,7 +89,19 @@ Five stacked zero-build optimizations:
    stable boot-time build id with no warmup fetch); `webjs vendor pin
    --download` also caches the bundle bytes locally under
    `.webjs/vendor/<pkg>@<version>.js` for air-gapped / strict-CSP
-   deployments. No bundler runs at any point.
+   deployments. No bundler runs at any point. **`webjs doctor` validates
+   importmap coherence** (#450): for each resolved package it checks that the
+   version pinned for every OTHER resolved package it depends on satisfies the
+   declared dependency / peer range, and WARNS naming both packages, the range,
+   and the pinned version when they skew (the class of bug where a pinned
+   package needs a newer minor of another pinned package than is pinned, so a
+   symbol it expects is missing at runtime). It is a validation over the
+   produced importmap, not a re-resolution and not bundling, and it runs the
+   SAME check with the SAME verdict over the live importmap and the vendored
+   `.webjs/vendor/importmap.json` (vendoring freezes the runtime-resolved
+   graph, so a coherent live graph stays coherent vendored). It reads
+   dependency metadata from the installed `node_modules` (no network of its
+   own) and degrades to "could not verify" when a manifest is unavailable.
 
 ## No-build production model
 
@@ -70,9 +111,10 @@ production. The Rails 7+ / Hotwire pattern:
 
 - **Importmap-driven**: bare-specifier imports (`from "react"`) are
   resolved via `<script type="importmap">` emitted into the document
-  head. By default each package resolves through `api.jspm.io/generate`
-  to a `https://ga.jspm.io/npm:<pkg>@<version>/...` URL and the browser
-  fetches it from the CDN directly, with an `integrity` SRI hash on every
+  head. By default the whole scanned set resolves through one
+  `api.jspm.io/generate` call (one consistent graph, see point 5 above)
+  to `https://ga.jspm.io/npm:<pkg>@<version>/...` URLs and the browser
+  fetches them from the CDN directly, with an `integrity` SRI hash on every
   cross-origin entry (computed live at warmup for an unpinned app, or read
   from the pin file for a pinned one). `webjs vendor pin` commits the
   resolved URLs + SHA-384 integrity hashes to `.webjs/vendor/importmap.json`
@@ -80,7 +122,12 @@ production. The Rails 7+ / Hotwire pattern:
   caches each bundle to `.webjs/vendor/<pkg>@<version>.js` and rewrites
   the importmap to `/__webjs/vendor/<pkg>@<version>.js` so the server
   serves the bytes from disk (air-gapped / strict-CSP path). No bundler
-  runs at any point.
+  runs at any point. Because the pins are meant to be committed,
+  `webjs vendor pin` makes its output committable: the scaffold already
+  un-ignores `.webjs/vendor/`, and if a `.gitignore` would swallow the
+  pins it heals it (or prints how to commit them when the ignore is not
+  in the app's own `.gitignore`). A no-vendor app, which never pins, is
+  unaffected.
 - **Per-file ESM serving**: every app `.js` / `.ts` becomes its own HTTP
   resource. The browser walks the import graph and fetches each module
   on demand.
@@ -313,7 +360,7 @@ export async function GET(req) {
 ### Behavior
 
 - **Preflight.** An `OPTIONS` request carrying `Access-Control-Request-Method` short-circuits with a `204` carrying the Allow-Methods / Allow-Headers / Max-Age headers. `next()` is NOT called. A disallowed-origin preflight returns a bare `204` with no CORS headers, so the browser blocks the follow-up.
-- **Actual request.** `next()` runs, then `Access-Control-Allow-Origin` (plus credentials / exposed headers) is attached. A disallowed origin gets NO `Access-Control-Allow-Origin`, and the browser blocks the cross-origin read, but the server still serves the response (CORS is browser-enforced, not a server gate; this matches the `expose()` path, which never 403s a mismatched actual request).
+- **Actual request.** `next()` runs, then `Access-Control-Allow-Origin` (plus credentials / exposed headers) is attached. A disallowed origin gets NO `Access-Control-Allow-Origin`, and the browser blocks the cross-origin read, but the server still serves the response (CORS is browser-enforced, not a server gate, so a mismatched actual request is never 403'd server-side).
 - **`Vary: Origin`.** Appended (never clobbering an existing `Vary`) whenever the allowed origin is dynamic (a reflected, per-origin value), so a shared cache keys on `Origin` and cannot poison one origin's response onto another. A constant `*` (no credentials) does not vary, so no `Vary` is added.
 
 ### `credentials: true` requires an explicit origin allowlist (spec, enforced, warned)
@@ -760,16 +807,24 @@ The action receives `{ request, params, searchParams, url, formData }`
 and returns an `ActionResult`. The server interprets the result:
 
 - **Success** (`{ success: true, redirect? }`, or any non-`false`
-  result, or a thrown `redirect()`): a `303 See Other` to
-  `result.redirect` if present, else the page's own path
-  (Post/Redirect/Get, so a reload does not resubmit).
+  result): a `303 See Other` to `result.redirect` if present, else the
+  page's own path (Post/Redirect/Get, so a reload does not resubmit).
+  This 303 is the success-result path only; a `redirect()` *thrown* from
+  the action is a separate case (see below).
 - **Failure** (`{ success: false, fieldErrors?, values?, status? }`):
   re-SSR the SAME page with `status` (default `422`) and the result on
   `ctx.actionData`. The page reads `actionData.fieldErrors.<field>` for
   messages and `actionData.values.<field>` to repopulate native
   `<input value=...>`, so the user's typed input survives.
-- A thrown `notFound()` yields a 404, a thrown `redirect()` keeps its
-  own 307/308 status (PRG uses 303 only for the success-result path).
+- A thrown `notFound()` yields a 404. A thrown `redirect()` carries no
+  baked-in status; the catching site picks the convention: thrown from an
+  action (a POST) it defaults to `307 Temporary Redirect`
+  (method-preserving, so the bounce keeps the POST's intent), thrown
+  during a GET page/layout render or gate it defaults to `302 Found` (the
+  code an auth bounce conventionally wants). An explicit status overrides
+  either default, in both the positional `redirect(url, 308)` and the
+  options `redirect(url, { status })` forms. PRG's 303 (above) is only
+  the success-result path, distinct from these thrown defaults.
 
 A page WITHOUT an `action` export keeps the old behavior, a non-GET to
 it 404s. There is no form library: native input repopulation plus the
@@ -802,6 +857,20 @@ mounted across nav and keep their `scrollTop` natively.
 
 ### `<webjs-frame>` escape hatch
 
+`<webjs-frame>` is webjs's take on **Turbo Frames** (Hotwire Turbo), so the
+mental model and most `<turbo-frame>` muscle memory transfer directly: a lazy,
+URL-addressable region that swaps on its own, driven by a link or form
+targeting its id. It is the unit for a region that loads or refreshes
+INDEPENDENTLY of a full-page navigation (something a page/layout, which
+re-renders only at the route level, cannot express), and it ships zero
+component JS. A frame's route can itself use `<webjs-suspense>`, so a deferred
+(`loading="lazy"`) frame whose data is slow streams that data behind a fallback
+inside the frame (one caveat: a streamed framed route skips the byte-saving
+subtree extraction, so the full page renders and the client slices out the
+region). See the data-fetching doc page (`docs/app/docs/data-fetching/page.ts`)
+for the async-render vs `<webjs-suspense>` vs `<webjs-frame>` vs `<webjs-stream>`
+decision boundary.
+
 For partial-swap regions NOT tied to a folder layout (a marketing-page
 widget, tabbed UI, etc.), wrap the region in a frame:
 
@@ -954,6 +1023,13 @@ those fallback children).
 
 ### Stream actions: surgical element-level updates (#248)
 
+`<webjs-stream>` is webjs's take on **Turbo Streams** (Hotwire Turbo); the
+action set (`append` / `prepend` / `before` / `after` / `replace` / `update` /
+`remove`) mirrors `<turbo-stream>`, so that muscle memory transfers directly. It
+is the ONLY surgical single-element update primitive (and the live-channel
+applier); a region swap or a `<webjs-frame>` reload redraws a whole region, and
+`<webjs-suspense>` is for streaming, so none of them cover "append one row".
+
 A region swap (a layout marker or a `<webjs-frame>`) is the right tool for "this
 part of the page changed". It is too coarse for "append ONE comment", "remove
 ONE row", "bump a count", or "insert a toast". For those, a server response can
@@ -1020,6 +1096,47 @@ branch return a normal `ActionResult` instead. `renderStream` is auto-registered
 by the client router, so it (and the `<webjs-stream>` element) is available
 wherever a layout imports `@webjsdev/core/client-router`.
 
+### Streaming RPC results: an action returns a stream (#489)
+
+`<webjs-stream>` above is the SERVER-PUSHED render-side primitive (the server
+decides what changes and ships HTML actions). Streaming RPC is the complementary
+PULL-side primitive: a `'use server'` action that RETURNS a `ReadableStream`, an
+async iterable, or an async generator streams its chunks over the single RPC
+response, and the client gets back an async iterable to `for await`. This is the
+token-stream / progress / incremental-result case a component consumes
+imperatively after an interaction.
+
+```ts
+// modules/ai/actions/stream-answer.server.ts
+'use server';
+export async function* streamAnswer(prompt: string) {
+  for await (const token of llm.complete(prompt)) yield token;
+}
+```
+
+```ts
+// inside a component
+for await (const token of await streamAnswer(q)) {
+  this.text.set(this.text.get() + token);   // renders incrementally
+}
+```
+
+The wire is a sequence of length-prefixed frames (`application/vnd.webjs+stream`):
+each chunk is rich-serialized (a `Date` / `Map` / `BigInt` round-trips), then a
+terminal frame closes the stream. Detection is purely on the RETURN value, so any
+verb (#488) can stream and there is no config export to declare. Back-pressure is
+respected (a slow consumer throttles a fast producer), and the request
+`AbortSignal` (#492) cancels the source generator on a client disconnect or a
+superseded `async render()`. A streamed result is never cached, ETagged, or
+seeded (#472); a mutation that streams still emits its `X-Webjs-Invalidate`
+header. A mid-stream throw surfaces as an error from the iterable (the HTTP status
+is already 200, so wrap the `for await` in `try/catch`), the author message in
+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.
+
 ### Opt out per link
 
 ```html

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

@@ -277,6 +277,16 @@ if (!session) throw redirect('/login');
 
 JWT sessions by default (stateless, scales horizontally). OAuth providers handle the full redirect flow.
 
+`auth()` resolves `{ user }` where `user` is `Record<string, unknown>` by default. To read the custom fields the callbacks set (`session.user.id`, `session.user.role`) without a cast and with typo-checking, type the session. Augment `AuthUser` for global typing, or use `createAuth<AppUser>(...)` for per-instance typing:
+
+```ts
+declare module '@webjsdev/server' {
+  interface AuthUser { id: string; role: 'admin' | 'member'; }
+}
+```
+
+Both are opt-in and types-only. See `agent-docs/typescript.md` and the auth recipe.
+
 ## File storage (`FileStore` + `diskStore`)
 
 webjs round-trips a native `File` / `Blob` / `FormData` over the wire, and the file-storage primitive decides WHERE the bytes land. The model mirrors the cache / session adapters: a documented `FileStore` interface, a default local-disk adapter (`diskStore`), and a module singleton (`setFileStore` / `getFileStore`) so an app swaps the backend in one call without touching any call site.
@@ -351,7 +361,7 @@ See the "Receive and persist an uploaded file" recipe in `agent-docs/recipes.md`
 | `AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET` | GitHub OAuth (optional) |
 | `SESSION_SECRET` | Cookie session signing |
 | `REDIS_URL` | When set, sessions + rate limit + cache use Redis |
-| `PORT` | Server port (default 8080) |
+| `PORT` | Server port. Precedence `--port` > `PORT` (real env or `.env`) > 8080 (#447) |
 
 ## Scaling to multiple instances
 

package/resources/agent-docs/components.md

@@ -50,6 +50,96 @@ For component-local state, create an instance signal in the constructor and call
 
 See [`/docs/lifecycle`](https://docs.webjs.com/docs/lifecycle) for per-hook usage examples.
 
+## Async render: bare-await data fetch (#469)
+
+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;
+  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>`;
+  }
+}
+UserProfile.register('user-profile');
+```
+
+Writing `await` makes the function async by the JS rule, and every render path awaits a promise-returning `render()` automatically. There is no flag. Plain sync `render()` stays the zero-cost default.
+
+**Three concerns, decoupled. Do not conflate them.**
+
+1. **SSR always blocks by default.** The server awaits `async render()`, so the resolved DATA is baked into the first paint. There is no fallback on first paint, ever. JS-off reads the data (a progressive-enhancement UPGRADE over a client-fetched `Task`, which shows nothing without JS).
+2. **The client re-fetch default is stale-while-revalidate.** When a prop / dependency change re-runs `async render()`, the previously rendered content stays until the new render resolves. No blank, no flash, no user code.
+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;
+  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);
+    return html`<ul>${items.map((i) => html`<li>${i.label}</li>`)}</ul>`;
+  }
+}
+```
+
+**Errors are isolated per component by default, no user code.** A thrown `await getData()` (or any render throw) renders a component-scoped error state while its siblings render normally; it never bubbles to the route `error.js`. The default surfaces the tag and message in dev and renders a silent empty element in prod (no leak). Override `renderError(error)` only to customize the error UI:
+
+```ts
+class Report extends WebComponent {
+  async render() { return html`<pre>${await getReport()}</pre>`; }
+  renderError(error) { return html`<p class="error">Could not load the report.</p>`; }  // optional
+}
+```
+
+`Task` and a signal cannot replace this: a `Task` renders its pending state at SSR (it loses the first-paint data), and you cannot wrap a signal around your own `await` inside `render()`. So `async render()` plus `renderFallback()` is the only way to get SSR-first-paint data AND a custom re-fetch loading state.
+
+**Decision rules (which tool to reach for):**
+
+1. Server data knowable at request time: fetch it IN the component with `async render()`. Co-located, no prop-drilling, data in the first paint. The default, simplest case.
+2. Client re-fetch where stale content would mislead: add `renderFallback()` for a loading state during the re-fetch.
+3. Genuinely CLIENT-ONLY data (depends on a click, viewport, localStorage, or live updates, and does NOT need to be in the first paint): use `Task` / signals plus an RPC action.
+4. Slow server data where blocking the first byte hurts: stream it. Wrap the component in `<webjs-suspense .fallback=${html\`…\`}>` to flush the fallback on the first byte and stream the data in (the only way to show a first-paint fallback; concurrent across boundaries; progressive on soft nav). Do it deliberately for slow regions, not by default.
+
+**Anti-patterns (likely footguns):**
+
+- Do NOT prop-drill server data through layers when the leaf component can fetch it itself.
+- Do NOT put `await getData()` in a page / layout function if it can live in a component (page / layout fetches run sequentially, a route-level waterfall).
+- Do NOT fetch in `connectedCallback` / `Task` for data that is knowable server-side (that yields a fallback-then-RPC, not first-paint data).
+- Do NOT expect `renderFallback()` to affect the first paint (it is the CLIENT re-fetch loading state).
+- Do NOT add `renderError()` on every component (isolation is automatic).
+
+**How it works.** On the server the SSR walker already awaits a promise-returning `render()` and bakes the data in; a throw is caught per component and rendered as the error state. On the client, `update()` detects a thenable from `render()` and routes to a stale-while-revalidate commit: the current DOM stays until the promise resolves, a monotonic render token drops a superseded resolution (an out-of-order fetch never commits stale DOM), and a rejection routes to `renderError()`. `firstUpdated` / `updated` / `updateComplete` fire after the async commit lands. Only signal reads BEFORE the first `await` establish reactive dependencies.
+
+**Elision (#474).** A **bare** `async render()` (no other client signal, light DOM) is **elided** like any display-only component: the SSR'd data is the complete first paint, so the framework drops the module and the redundant on-hydration re-fetch (a common content / docs leaf shape). It ships only when it ALSO carries an independent signal (an `@event`, a non-`state` reactive prop, a signal / reactive import, a lifecycle hook including `renderFallback()`, a `<slot>`, cross-module observation, or a transitively-reachable interactive child). Two carve-outs always ship. `static shadow = true` ships because Declarative Shadow DOM attaches only during HTML parsing, so a streamed (`<webjs-suspense>`) or soft-navigated shadow component arrives via a JS DOM insertion and needs its module to re-run `attachShadow`. `static refresh = true` is the explicit opt-in to keep the stale-while-revalidate on-load re-fetch that eliding drops (moot for request-stable data, the default; reach for it only when fresh-on-load matters). The only behaviour eliding removes is that on-load refresh; the first paint is byte-identical, verified by the differential-elision guard.
+
+**SSR action seeding (#472).** For a SHIPPING async component (one that hydrates because it carries an interactivity signal), the on-hydration re-fetch is eliminated without eliding the module. Each `'use server'` action result invoked during a (non-streamed) SSR render is serialized into the page as one `<script type="application/json" id="__webjs-seeds">` block, keyed by the action's hash + function name + serialized args. The generated client RPC stub reads that seed on its FIRST call: a hit resolves synchronously (no network, no hydration flicker), a later refetch or arg-change misses (consume-once) and goes to RPC as normal. So `const u = await getUser(this.id)` runs once, server-side, and its result is reused on the client's first render. The capture is a transparent server-side facade over the `'use server'` module (a synchronous `module.registerHooks` load hook wraps each export in a recording `Proxy`), so there is **no source transform and no build step**: the browser source tab and the on-disk files are byte-unchanged, and the RPC stub the browser fetches is the same shape as before (it just consults the seed first). Fail-open by construction: a key miss is always a normal RPC, never wrong data. Default on; opt out with `"webjs": { "seed": false }` or `WEBJS_SEED=0` (then the client re-fetches on hydration, hidden by stale-while-revalidate as before). A soft navigation carries the seed too: the client router ingests the incoming page's payload (`applySwap` -> `scanSeeds`) before its components hydrate, so a navigated async component also skips the refetch. Streamed regions (`<webjs-suspense>`) are NOT seeded (their data resolves after the first flush), so a slow boundary keeps the stale-while-revalidate refetch.
+
+### Streaming a slow region with `<webjs-suspense>` (#471)
+
+`async render()` BLOCKS the first byte by default (the SSR HTML waits for the data). For a SLOW region where that wait hurts time-to-first-byte, wrap it in `<webjs-suspense>` to stream it: the fallback flushes immediately, the resolved content streams in.
+
+```ts
+html`
+  <webjs-suspense .fallback=${html`<p>Loading section…</p>`}>
+    <user-profile uid="42"></user-profile>
+    <user-activity uid="42"></user-activity>
+  </webjs-suspense>
+`;
+```
+
+- **The fallback is on the first byte, the content streams in.** This is the ONLY way a fallback appears on the first paint. It is a deliberate choice for slow data (fast TTFB, accepting a fallback-then-content swap), exactly like page-level `Suspense`. PE-critical content stays unwrapped (blocking) so it is in the first paint with no JS.
+- **Grouping + override.** One boundary wraps several components under ONE fallback. The boundary `.fallback` wins over a contained component's `renderFallback()`.
+- **Concurrent.** Multiple `<webjs-suspense>` boundaries on a page fetch their data in parallel (each is a non-blocking boundary resolved together), so they stream fast-before-slow with no server waterfall.
+- **Error-isolated.** A throwing component inside a boundary renders its component-scoped error state (via `renderError()` or the default) while its siblings stream normally.
+- **Progressive on soft navigation (#473).** A client-router navigation to a streamed page applies the shell (with fallbacks) immediately, advances the URL, then streams each boundary in, matching the initial-load experience instead of buffering the whole response.
+- **`.fallback` is special-cased at SSR:** the renderer reads it inline as the placeholder, never through the `data-webjs-prop-*` path (a `TemplateResult` is not serializer-safe). It must be an UNQUOTED property hole (`.fallback=${...}`, invariant 4).
+
+Decision: a bare `async render()` for request-time data that should be in the first paint (the default); `<webjs-suspense>` ONLY when the data is slow enough that blocking the first byte is the worse tradeoff.
+
 ## Display-only components are elided from the browser
 
 A component that does no client-side work renders the same SSR'd HTML
@@ -113,6 +203,46 @@ 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.
 
+### Elision is what keeps a server import off a display-only page (and `webjs check` guards the seam)
+
+Elision is also why a page can call a server-only utility and stay
+browser-safe, and why the same code crashes once the page gains client
+work. A page that does `const s = await auth()` (where `auth` comes from
+a `lib/auth.server.ts` UTILITY, no `'use server'`) is fine while the page
+is display-only: the framework elides the page, strips the server import,
+and the browser never sees it. The moment the page also imports a
+component to register it (`import '../components/workspace.ts'`), enables
+the client router, or uses a reactive primitive, the page stops being
+display-only, must load in the browser to do that work, and drags the
+server import with it. In the browser that import is a throw-at-load
+stub, so the page crashes the instant its module loads. `webjs typecheck`
+and the rest of `webjs check` pass; only the running page fails. This was
+the single biggest source of extra AI iterations when porting a real app.
+
+`webjs check`'s `no-server-import-in-browser-module` rule catches it
+statically. It reuses the SAME elision verdict described above (over the
+module graph, scanned components, and route table), so it flags ONLY a
+module that genuinely ships: a display-only page the framework elides is
+never flagged, because its server import really is stripped. The fix it
+suggests is the three legitimate shapes: gate the route in
+`middleware.ts` (server-only, never shipped), call the server through a
+`'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.
+
+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.
+
 ### Turning elision off
 
 Elision is on by default. To disable it app-wide, set `elide` to `false`

package/resources/agent-docs/configuration.md

@@ -205,3 +205,21 @@ Returns JSON describing the live build, alongside the `/__webjs/health` and `/__
 ```
 
 `version` is the `@webjsdev/server` framework version (read from its own `package.json`), `build` is the published importmap build id (the same fingerprint the client router reads from `data-webjs-build`; empty until the vendor map resolves), `node` is the running Node version, `uptime` is process uptime in seconds. Mechanism: `requestId()` / `setRequestId` in `packages/server/src/context.js`, `buildInfo` / `buildInfoResponse` in `packages/server/src/build-info.js`, all wired in `packages/server/src/dev.js`.
+
+---
+
+## Server port resolution (`--port` / `PORT` / `.env`) (#447)
+
+Both `webjs dev` and `webjs start` resolve the listen port with a single
+precedence: **`--port` flag > `PORT` (a real exported env var OR a `PORT`
+in the app's `.env`) > `8080`**. A real exported `PORT` still wins over a
+`.env` `PORT`, matching the `.env` auto-load's shell-wins-over-file rule
+(`process.loadEnvFile` does not clobber an already-set var).
+
+The CLI loads `<appDir>/.env` BEFORE resolving the port, so a `PORT` set
+only in `.env` is honored (it previously was not: the port was computed
+from `process.env.PORT || 8080` before the server's own `.env` load ran,
+so the file's `PORT` never reached the comparison and the server always
+bound 8080). Mechanism: `loadAppEnv(appDir)` + the pure
+`resolvePort(portFlag, env)` in `packages/cli/lib/port.js`, called by the
+`dev` and `start` bins before listening.

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

@@ -181,7 +181,32 @@ client then renders the resolved state, causing a flash.
 
 `Task` is still useful for client-time async (interaction-triggered
 mutations, polling, websocket reactions). For initial-paint data, fetch
-in the page function instead.
+in the page function OR in the component itself with an `async render()`
+(see the next entry), which Lit does not have.
+
+### 2b. Lit has no async render; webjs does (#469)
+
+Lit keeps `render()` synchronous (its async-SSR work signals a promise the
+renderer awaits BEFORE a still-sync render). webjs lets `render()` itself be
+`async`, so you write `const u = await getUser(this.id)` directly in the
+component and SSR bakes the resolved data into the first paint. Three things
+trip up Lit muscle memory:
+
+- **SSR blocks by default. Streaming is NOT automatic.** A bare `async
+  render()` (no wrapper) renders real data in the first paint with no
+  fallback. There is no skeleton flash. To STREAM slow data (fallback on
+  first byte), wrap the region in `<webjs-suspense .fallback=${html`…`}>`.
+  Do not reach for a fallback expecting it to show on first load; the
+  unwrapped default is block-real-data, and streaming is the deliberate
+  opt-in for slow regions.
+- **`renderFallback()` is NOT a first-paint concern.** It is the OPTIONAL
+  client re-fetch loading UI, shown only when a prop / dependency change
+  re-runs `async render()`, never on the first paint. The first-paint and
+  re-fetch defaults are both no-flash: SSR has the data, and a re-fetch keeps
+  the stale content (stale-while-revalidate) until the new render resolves.
+- **You do not need an error boundary.** A thrown `await getData()` is
+  isolated to that component automatically (siblings render, the page does
+  not blank). Add `renderError()` only to customize the error UI.
 
 ### 3. Browser-only APIs in the constructor or `render()`
 

package/resources/agent-docs/recipes.md

@@ -32,6 +32,12 @@ transition agents most often get wrong, so it is the first recipe.
    }
    ```
 
+   Start the dev server with `npm run dev` (the canonical command), NOT a bare
+   `webjs dev`: `npm run dev` runs the `predev` hook (`prisma generate`) first,
+   while `webjs dev` skips it and boots against an ungenerated client. A bare
+   `webjs dev` will now warn and point you back at `npm run dev`, but use the
+   npm script from the start.
+
 2. **Migrate.** Run the npm script (not the `webjs`/`prisma` binary directly,
    so the `predev` / `db:*` hooks fire):
 
@@ -124,12 +130,12 @@ export async function updateProfile(input: { name: string }) {
 Call it from a client component via a normal import. The dev server
 rewrites the import to a typed RPC stub.
 
-## Validate a server action's input once, for both call paths (#245)
+## Validate a server action's input (#245)
 
-`validateInput(fn, validate)` attaches an input validator that runs
-SERVER-SIDE before the action body on EVERY call path (the RPC path a
-client component import takes AND the `expose()` REST route if the action
-has one). On failure it returns a structured `ActionResult`
+Declare a `validate` config export beside the action (#488). It runs
+SERVER-SIDE before the action body on the RPC boundary (the path a client
+component import takes), receiving the action's FIRST argument. On failure
+it returns a structured `ActionResult`
 (`{ success: false, fieldErrors, status: 422 }`) the client reads as
 `result.fieldErrors`. The framework ships no validation library; the
 validator is a plain function (or a three-line zod adapter).
@@ -137,25 +143,23 @@ validator is a plain function (or a three-line zod adapter).
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
-import { validateInput } from '@webjsdev/core';
 import { prisma } from '../../../lib/prisma.server.ts';
 
-export const createPost = validateInput(
-  // the action body: runs ONLY when validation passes
-  async (input: { title: string; body: string }) => {
-    const row = await prisma.post.create({ data: input });
-    return { success: true, data: row };
-  },
-  // the validator: receives the action's FIRST argument
-  (input) => {
-    const fieldErrors: Record<string, string> = {};
-    const title = String(input?.title || '').trim();
-    if (!title) fieldErrors.title = 'Title is required';
-    if (String(input?.body || '').length < 10) fieldErrors.body = 'Too short';
-    if (Object.keys(fieldErrors).length) return { success: false, fieldErrors };
-    return { success: true, data: { title, body: String(input.body) } }; // coerced input
-  },
-);
+// the validator: receives the action's FIRST argument
+export const validate = (input: any) => {
+  const fieldErrors: Record<string, string> = {};
+  const title = String(input?.title || '').trim();
+  if (!title) fieldErrors.title = 'Title is required';
+  if (String(input?.body || '').length < 10) fieldErrors.body = 'Too short';
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors };
+  return { success: true, data: { title, body: String(input.body) } }; // coerced input
+};
+
+// the action body: runs ONLY when validation passes
+export async function createPost(input: { title: string; body: string }) {
+  const row = await prisma.post.create({ data: input });
+  return { success: true, data: row };
+}
 ```
 
 Reading the structured failure in a client component is just a property
@@ -181,23 +185,21 @@ result becomes the contract envelope.
 import { z } from 'zod';
 const Schema = z.object({ title: z.string().min(1), body: z.string().min(10) });
 
-export const createPost = validateInput(
-  async (input) => { /* ... */ },
-  (i) => {
-    const r = Schema.safeParse(i);
-    return r.success
-      ? { success: true, data: r.data }
-      : { success: false, fieldErrors: r.error.flatten().fieldErrors };
-  },
-);
+export const validate = (i: any) => {
+  const r = Schema.safeParse(i);
+  return r.success
+    ? { success: true, data: r.data }
+    : { success: false, fieldErrors: r.error.flatten().fieldErrors };
+};
+export async function createPost(input) { /* ... */ }
 ```
 
-To ALSO expose the action as REST with the SAME validator, pass `validate`
-to `expose()` instead of using `validateInput`:
-`expose('POST /api/posts', fn, { validate })`. A `{ success: false,
-fieldErrors }` return becomes a 422 JSON response there; a validator that
-THROWS (the classic `Schema.parse` style) becomes a 400, and a non-envelope
-return transforms the input (back-compat).
+To ALSO expose the action over REST with the SAME validator, put it behind
+a `route.ts` and pass the validator as the `route()` adapter's `{ validate }`
+option: `export const POST = route(createPost, { validate })`. A
+`{ success: false, fieldErrors }` return becomes a 422 JSON response there; a
+validator that THROWS (the classic `Schema.parse` style) becomes a 400, and a
+non-envelope return transforms the input.
 
 ## Add a component
 
@@ -210,6 +212,48 @@ export class HelloWorld extends WebComponent {
 HelloWorld.register('hello-world');
 ```
 
+## Fetch data in a component (async render, #469)
+
+A leaf component fetches its own server data into the first paint, co-located, with no prop-drilling. Make `render()` async and call a `'use server'` action directly (real fn at SSR, RPC stub on the client). SSR awaits it, so the data is in the first paint.
+
+```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;
+  async render() {
+    const u = await getUser(this.uid);
+    return html`<h3>${u.name}</h3>`;
+  }
+}
+UserProfile.register('user-profile');
+
+// (b) stream a SLOW region (fallback on the first byte, content streams in)
+html`
+  <webjs-suspense .fallback=${html`<p>Loading…</p>`}>
+    <user-profile uid="42"></user-profile>
+  </webjs-suspense>
+`;
+
+// (c) renderFallback() = the CLIENT re-fetch loading state (never the first paint)
+class UserActivity extends WebComponent {
+  static properties = { uid: { type: String } };
+  declare uid: string;
+  renderFallback() { return html`<div class="skeleton h-24"></div>`; }
+  async render() {
+    const items = await getActivity(this.uid);
+    return html`<ul>${items.map((i) => html`<li>${i.label}</li>`)}</ul>`;
+  }
+}
+
+// (d) errors are isolated by default: NO renderError() needed (add it only to customize)
+class Report extends WebComponent {
+  async render() { return html`<pre>${await getReport()}</pre>`; }
+}
+```
+
+The client re-fetch default is stale-while-revalidate (the current content stays until the new render resolves). Use `<webjs-suspense>` only for genuinely slow data; keep `Task` / signals for client-only data that should NOT be in the first paint. Full decision guide in `agent-docs/components.md` and the `data-fetching` doc page.
+
 ## Form mutation with server-side validation (no JS required)
 
 This is webjs's progressive-enhancement write-path. A `<form method="POST">`
@@ -265,7 +309,7 @@ export default function Contact({ actionData }: {
 | Action outcome | HTTP response |
 |---|---|
 | success result (see the failure rule below) | `303 See Other` to a same-site `redirect` if present, else the page's own path (Post/Redirect/Get) |
-| thrown `redirect('/x')` | `307`/`308` (keeps the status `redirect()` was called with) |
+| thrown `redirect('/x')` | `307` (method-preserving, the action default since it is a POST), or the explicit status if `redirect('/x', 308)` / `redirect('/x', { status })` was used. A redirect thrown during a plain GET page render instead defaults to `302`. |
 | thrown `notFound()` | `404` rendered via `not-found.{js,ts}` |
 | failure result (`success: false`, or `fieldErrors`, or an `error`) | re-SSR the SAME page with `status` (default `422`) and the result on `ctx.actionData` |
 

package/resources/agent-docs/styling.md

@@ -171,7 +171,7 @@ Naming convention: derive the scope class from the file path. Slashes
 
 Styles colocate with the markup as `const STYLES = css\`…\`` and
 interpolate via `<style>${STYLES.text}</style>`. The standalone
-`@webjsdev/ts-plugin` (and the `webjs` editor extension) resolves class
+`@webjsdev/intellisense` (and the `webjs` editor extension) resolves class
 go-to-definition inside those blocks.
 
 ### Example: a page

package/resources/agent-docs/testing.md

@@ -71,10 +71,10 @@ packages/
   cli/test/                        scaffold validation only
   ui/test/                         schema, resolver, project-detect, components
     components/browser/            real-browser tests for the kit
-  ts-plugin/test/plugin/           tsserver plugin tests (.test.mjs)
+  intellisense/test/plugin/        tsserver plugin tests (.test.mjs)
 test/                              cross-package only
   ssr/                             SSR pipeline (core + server)
-  actions/                         expose() (core + server)
+  actions/                         server actions (core + server)
   serialization/                   json-negotiation (core + server)
   scaffolds/                       full app boots from CLI scaffolds
   blog/                            examples/blog smoke + browser e2e
@@ -131,7 +131,7 @@ ui-website ship no test suite yet, so they are not in the job.
 3. Drop the test in directly when it's a node test; nest it
    inside `browser/` / `e2e/` / `smoke/` when it's that kind.
 4. Use `.test.js` for ESM packages, `.test.mjs` when the
-   surrounding package is CJS (e.g. `@webjsdev/ts-plugin`).
+   surrounding package is CJS (e.g. `@webjsdev/intellisense`).
 
 ---
 
@@ -162,6 +162,12 @@ assert.ok(el.innerHTML.includes('10'));
 
 **Hydration-mismatch pattern.** To assert SSR and the hydrated DOM agree, normalise the SSR string (strip the `<!--webjs-hydrate-->` marker, `data-webjs-prop-*` attributes, part comments) and compare against the live `el.innerHTML`. The counterfactual is a component whose `render()` is non-deterministic across the SSR call and the hydration render; `ssrFixture` returns the live hydrated element, so the divergence is detectable. The worked tests live in `packages/core/test/testing/browser/ssr-fixture.test.js`, alongside the broader SSR-vs-client parity corpus in `packages/core/test/rendering/browser/ssr-client-parity.test.js`.
 
+**Testing async render + streaming + error isolation (#469 / #471 / #473).** Split by layer:
+- **SSR async render + error isolation** (unit, node, `renderToString`): assert an `async render()` bakes the resolved DATA into the HTML with no fallback markup, and that a throwing component renders a component-scoped error state while siblings render (worked in `packages/core/test/suspense/async-render-ssr.test.js`).
+- **`<webjs-suspense>` streaming** (unit, node, `renderToStream` + a `suspenseCtx`): collect the stream and assert the fallback flushes first, then the `<template data-webjs-resolve>` boundaries, and that multiple boundaries fetch concurrently via a timing assertion that fails if serial (worked in `packages/core/test/suspense/webjs-suspense-ssr.test.js`).
+- **Client async render** (browser, WTR): mount a component and `await el.updateComplete`, then assert stale-while-revalidate keeps prior content during a gated re-fetch, `renderFallback()` shows only on a re-fetch (never first paint), a rejected render commits `renderError()`, and the race guard drops a superseded resolution. Use a gate promise inside `render()` to control timing (worked in `packages/core/test/suspense/browser/async-render-client.test.js`).
+- **Progressive soft-nav streaming** (e2e, `WEBJS_E2E=1`): soft-navigate to a streamed page and assert the fallback is live in the DOM at the moment the URL advances (a buffered swap would only advance the URL once the boundary already resolved), then that the boundary streams in. The DOM-free reader helpers are unit-tested in `packages/core/test/routing/progressive-stream.test.js`.
+
 ### `assertNoA11yViolations(el, opts?)` (opt-in)
 
 An OPT-IN accessibility assertion that runs the standard axe-core engine against an element's subtree in the WTR Chromium session. Nothing calls it for you, it is never a forced gate.

package/resources/agent-docs/typescript.md

@@ -128,6 +128,31 @@ Supported: `Date`, `Map`, `Set`, `BigInt`, `Error`, `undefined`,
 instances come through as plain objects, with prototypes lost and methods
 gone (matches React Server Actions).
 
+#### Catching a non-serializable signature at compile time (`SerializableActionFn`)
+
+The class-instance / function caveat above is a silent runtime surprise: a
+method-valued field or a function argument typechecks fine but vanishes on the
+wire. The opt-in `SerializableActionFn` annotation turns it into a compile-time
+error. webjs actions stay plain `export async function`s (the framework rewrites
+the client import to an RPC stub at runtime, it does not wrap the authored
+function), so the guard is an OPTIONAL type annotation the author applies when
+they want it:
+
+```ts
+import type { SerializableActionFn } from '@webjsdev/core';
+
+export const getUser: SerializableActionFn<(id: number) => Promise<User>> =
+  async (id) => db.user.find(id);
+//  ^ if User carries a method (or any arg is a function), this is a type error
+//    pointing at the offending member, instead of a value that silently loses
+//    it on the wire.
+```
+
+`Serializable<T>` (also exported) maps a fully serializable `T` to itself and a
+non-serializable position (a function / method) to a branded `NonSerializable`
+marker; `SerializableArgs` / `SerializableResult` apply it across an action's
+parameters and (promise-unwrapped) return. All types-only, erased at runtime.
+
 ### API routes: opt in via content negotiation
 
 `route.ts` handlers use standard JSON by default so external consumers
@@ -304,13 +329,47 @@ core prop / metadata types rather than redefining them. The runtime stays plain
 `.js` + JSDoc; the overlay is types-only with zero runtime cost. A drift test
 keeps `index.d.ts` in lockstep with `index.js`'s runtime exports.
 
+### Typing the `auth()` session user
+
+`auth()` resolves `{ user }`, and by default `user` is `Record<string,
+unknown>`, so reading a custom field your `session`/`jwt` callbacks set
+(such as `session.user.id`) needs a cast and a typo is not caught. Two
+opt-in ways make `user` typed, both types-only.
+
+Augment the `AuthUser` interface (NextAuth/Auth.js style) to type every
+`auth()` call across the app:
+
+```ts
+declare module '@webjsdev/server' {
+  interface AuthUser {
+    id: string;
+    role: 'admin' | 'member';
+  }
+}
+```
+
+Or parameterise the factory to type one instance without a global
+augmentation. `createAuth<AppUser>(...)` returns an `auth()` whose `user`
+is `AppUser`:
+
+```ts
+const { auth } = createAuth<AppUser>({ secret, providers });
+const session = await auth();
+session?.user.role; // typed, no cast
+```
+
+Un-augmented and un-parameterised, `AuthUser` is empty and resolves back
+to `Record<string, unknown>`, so pre-existing untyped code keeps
+compiling. The declared fields should mirror what the callbacks write
+onto `session.user`.
+
 ### TypeScript is not required
 
 JS + JSDoc gets the same call-site type safety. The TypeScript language
 server reads `@typedef` / `@param` / `@returns` identically to `.ts`
 syntax. Add `"checkJs": true` to enforce types in editor + CI.
 
-## Editor plugin: `@webjsdev/ts-plugin`
+## Editor plugin: `@webjsdev/intellisense`
 
 **Editor-only. Not required for the framework to run.** The runtime
 has no dependency on it.
@@ -319,7 +378,7 @@ A single plugin with its OWN in-template intelligence (no Lit dependency; the `w
 
 ```jsonc
 "plugins": [
-  { "name": "@webjsdev/ts-plugin" }
+  { "name": "@webjsdev/intellisense" }
 ]
 ```
 

package/src/mcp-docs.js

@@ -284,6 +284,7 @@ export const PROMPTS = [
   { name: 'add_dynamic_route', description: 'Scaffold a dynamic page reading params, e.g. app/users/[id]/page.ts.', arguments: [{ name: 'route', description: 'URL path with a [param], e.g. /users/[id]', required: false }] },
   { name: 'add_server_action', description: 'Scaffold a server action (.server.ts + use server) called from a component.', arguments: [{ name: 'feature', description: 'Feature/module name', required: false }] },
   { name: 'add_component', description: 'Scaffold an interactive WebComponent (signals, light DOM, register).', arguments: [{ name: 'tag', description: 'Custom-element tag, e.g. my-thing', required: false }] },
+  { name: 'fetch_data_in_component', description: 'Fetch server data IN a component with async render() (co-located, first-paint data), plus webjs-suspense streaming and renderFallback.', arguments: [{ name: 'tag', description: 'Custom-element tag, e.g. user-profile', required: false }] },
   { name: 'add_module', description: 'Scaffold a modules/<feature>/ slice (actions/queries/components/utils).', arguments: [{ name: 'feature', description: 'Feature name', required: false }] },
 ];
 
@@ -364,6 +365,30 @@ const PROMPT_BODIES = {
     'a class-field initializer that overwrites a reactive accessor breaks reactivity',
     '(use `declare` + `static properties`).',
   ].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;',
+    '  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>`;',
+    '  }',
+    '}',
+    "UserProfile.register('user-profile');",
+    '```',
+    '',
+    'Decoupled model: SSR BLOCKS by default (real data, no fallback). The client',
+    're-fetch default is stale-while-revalidate. `renderFallback()` is the OPTIONAL',
+    're-fetch loading state (re-fetch only, NEVER first paint). Errors are isolated',
+    'per component by default (add `renderError()` only to customize). For SLOW data,',
+    'wrap in `<webjs-suspense .fallback=${html`...`}>` to STREAM it (fallback first).',
+    'Keep `Task` / signals for client-only data (it shows pending at SSR). Read',
+    '`webjs-docs://components` for the full decision guide and anti-patterns.',
+  ].join('\n'),
   add_module: [
     'Add a feature module. `modules/<feature>/` holds `actions/*.server.ts` (mutations),',
     '`queries/*.server.ts` (reads), `components/*.ts` (feature UI), `utils/*.ts` (pure),',

package/src/mcp-source.js

@@ -28,7 +28,7 @@ import { createRequire } from 'node:module';
 import { join, resolve, sep, relative } from 'node:path';
 
 /** The published framework packages whose source an agent may want to read. */
-export const FRAMEWORK_PACKAGES = ['core', 'server', 'cli', 'ts-plugin', 'ui'];
+export const FRAMEWORK_PACKAGES = ['core', 'server', 'cli', 'intellisense', 'ui'];
 
 /** Source file extensions worth grepping / reading (text, not assets). */
 const TEXT_EXT = /\.(?:js|ts|mjs|mts|cjs|cts|json|md)$/i;

package/src/mcp.js

@@ -36,6 +36,13 @@ import { resolveFrameworkRoots, runSourceTool } from './mcp-source.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
 
+// Mirrors packages/server/src/action-config.js. A drift test in
+// packages/mcp/test/mcp.test.mjs asserts these stay in sync with the source.
+/** HTTP verbs an action may declare (mirrors RPC_VERBS in action-config.js). */
+const RPC_VERBS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+/** Reserved config export names in a 'use server' file (mirrors RESERVED_CONFIG in action-config.js). */
+const RESERVED_CONFIG = new Set(['method', 'cache', 'tags', 'invalidates', 'validate', 'middleware']);
+
 /**
  * The four read-only tools. Each takes an optional `{ appDir }` (default the
  * server's cwd) and projects an EXISTING `@webjsdev/server` function's output
@@ -87,7 +94,7 @@ const SOURCE_SCHEMA = {
     },
     package: {
       type: 'string',
-      description: 'Limit a no-args listing to one package (core, server, cli, ts-plugin, ui).',
+      description: 'Limit a no-args listing to one package (core, server, cli, intellisense, ui).',
     },
   },
   required: [],
@@ -128,7 +135,7 @@ const TOOL_DEFS = [
   {
     name: 'list_actions',
     description:
-      'List registered server actions (the .server.{js,ts} files with "use server"): file, exported function name, and the /__webjs/action/<hash>/<fn> RPC endpoint. Read-only.',
+      'List registered server actions (the .server.{js,ts} files with "use server"): file, exported function name, the /__webjs/action/<hash>/<fn> RPC endpoint, HTTP verb (method), cache config, and boolean flags for tags/invalidates/validate/middleware. Config-only exports (method, cache, tags, invalidates, validate, middleware) are NOT listed as actions. Read-only.',
     inputSchema: APPDIR_SCHEMA,
   },
   {
@@ -206,6 +213,67 @@ export function extractRouteMethods(src) {
   return METHODS.filter((m) => exported.has(m));
 }
 
+/**
+ * Lexically extract the HTTP-verb action config declared as reserved sibling
+ * exports in a `'use server'` file (#488). Reads source text only (no module
+ * load) so there are no DB-init or Prisma side effects.
+ *
+ * Returned shape:
+ *   {
+ *     method: 'GET'|'POST'|'PUT'|'PATCH'|'DELETE',  // default 'POST'
+ *     cache: string | null,    // raw RHS literal when present, else null
+ *     tags: boolean,           // whether the tags export is declared
+ *     invalidates: boolean,    // whether the invalidates export is declared
+ *     validate: boolean,       // whether the validate export is declared
+ *     middleware: boolean,     // whether the middleware export is declared
+ *   }
+ *
+ * @param {string} src
+ * @returns {{ method: string, cache: string|null, tags: boolean, invalidates: boolean, validate: boolean, middleware: boolean }}
+ */
+export function extractActionConfig(src) {
+  // Extract `method` from: export const method = 'GET'  (single/double/backtick)
+  const methodMatch = /\bexport\s+const\s+method\s*=\s*(['"`])([A-Za-z]+)\1/.exec(src);
+  let method = 'POST';
+  if (methodMatch) {
+    const upper = methodMatch[2].toUpperCase();
+    if (RPC_VERBS.has(upper)) method = upper;
+  }
+
+  // Extract `cache` RHS. Single-line: `export const cache = 60` -> '60'
+  // Multi-line object: capture balanced braces across lines.
+  let cache = null;
+  const cacheMatch = /\bexport\s+const\s+cache\s*=\s*/.exec(src);
+  if (cacheMatch) {
+    const rest = src.slice(cacheMatch.index + cacheMatch[0].length);
+    if (rest.startsWith('{')) {
+      // Capture the balanced-brace object (may span lines).
+      let depth = 0;
+      let end = 0;
+      for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '{') depth++;
+        else if (rest[i] === '}') { depth--; if (depth === 0) { end = i; break; } }
+      }
+      cache = rest.slice(0, end + 1).trim();
+    } else {
+      // Single-line: read up to the first newline or semicolon.
+      const lineMatch = /^([^\n;]+)/.exec(rest);
+      if (lineMatch) cache = lineMatch[1].trim();
+    }
+  }
+
+  // Boolean presence of the remaining config names.
+  const exported = new Set(extractExportNames(src));
+  return {
+    method,
+    cache,
+    tags: exported.has('tags'),
+    invalidates: exported.has('invalidates'),
+    validate: exported.has('validate'),
+    middleware: exported.has('middleware'),
+  };
+}
+
 /**
  * The literal URL path for a page/api directory: `blog/[slug]` -> `/blog/[slug]`,
  * the root `.` -> `/`. Route groups `(group)` and `_private` segments drop, the
@@ -274,23 +342,33 @@ export function makeToolRunners(deps) {
     },
 
     async list_actions(appDir) {
-      // `skipExposeLoad` builds the file -> hash maps WITHOUT importing any
-      // `expose()` module, so this stays truly read-only (no Prisma/DB init, and
-      // no stray stdout from a loaded module corrupting the JSON-RPC channel).
-      // The RPC hash is over the file path only, so no module load is needed.
-      const idx = await buildActionIndex(appDir, false, { skipExposeLoad: true });
-      /** @type {Array<{ file: string, fn: string, endpoint: string }>} */
+      // buildActionIndex is a pure file -> hash mapping that imports no module,
+      // so this stays truly read-only (no Prisma/DB init, and no stray stdout
+      // from a loaded module corrupting the JSON-RPC channel). The RPC hash is
+      // over the file path only, so no module load is needed.
+      const idx = await buildActionIndex(appDir, false);
+      /** @type {Array<{ file: string, fn: string, endpoint: string, method: string, cache: string|null, tags: boolean, invalidates: boolean, validate: boolean, middleware: boolean }>} */
       const actions = [];
       for (const [file, hash] of idx.fileToHash) {
-        let names = [];
+        let src = '';
         try {
-          names = extractExportNames(await readFile(file, 'utf8'));
+          src = await readFile(file, 'utf8');
         } catch {}
+        const names = extractExportNames(src);
+        const config = extractActionConfig(src);
         for (const fn of names) {
+          // Skip reserved config export names: they are config, not callable actions.
+          if (RESERVED_CONFIG.has(fn)) continue;
           actions.push({
             file: relative(appDir, file),
             fn,
             endpoint: `/__webjs/action/${hash}/${fn}`,
+            method: config.method,
+            cache: config.cache,
+            tags: config.tags,
+            invalidates: config.invalidates,
+            validate: config.validate,
+            middleware: config.middleware,
           });
         }
       }