@webjsdev/server 0.8.23 → 0.8.25

package/index.d.ts

@@ -844,3 +844,11 @@ export declare function GitHub(opts?: Record<string, unknown>): ProviderConfig;
 // ---------------------------------------------------------------------------
 
 export type { LayoutProps, PageProps, RouteHandlerContext };
+
+/** The current action request AbortSignal (#492), or a never-aborting signal outside an action. */
+export declare function actionSignal(): AbortSignal;
+/** Run a function with a request AbortSignal available to actionSignal() (#492). */
+export declare function runWithActionSignal<T>(signal: AbortSignal | undefined, fn: () => T): T;
+
+/** The accumulated per-action middleware context (#490), or {} outside an action. */
+export declare function actionContext(): Record<string, unknown>;

package/index.js

@@ -48,6 +48,8 @@ export { cors, resolveOrigin, applyCorsHeaders } from './src/cors.js';
 export { memoryStore, redisStore, getStore, setStore } from './src/cache.js';
 export { cache } from './src/cache-fn.js';
 export { revalidateTag, revalidateTags } from './src/cache-tags.js';
+export { actionSignal, runWithActionSignal } from './src/action-signal.js';
+export { actionContext } from './src/action-middleware.js';
 export { revalidatePath, revalidateAll } from './src/html-cache.js';
 export { Session, session, cookieSessionStorage, storeSessionStorage, cookieSession, storeSession, getSession } from './src/session.js';
 export { broadcast } from './src/broadcast.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.23",
+  "version": "0.8.25",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/action-config.js

@@ -0,0 +1,162 @@
+/**
+ * HTTP-verb server actions (#488): read the per-action configuration declared as
+ * RESERVED sibling exports in a `'use server'` action file, and the helpers that
+ * turn that config into transport + caching behavior.
+ *
+ * The function stays a plain `export async function`; the framework reads these
+ * statically-named exports the same way a page declares `export const
+ * revalidate` / `metadata`:
+ *
+ *   'use server';
+ *   export const method = 'GET';                 // 'GET'|'POST'|'PUT'|'PATCH'|'DELETE'; absent => POST
+ *   export const cache = 60;                      // seconds, or { maxAge, swr, public }
+ *   export const tags = (id) => [`user:${id}`];   // GET: tags the cached read
+ *   export const invalidates = (id) => [...];     // mutation: tags to evict
+ *   export const validate = (input) => ...;       // boundary validator
+ *   export async function getUser(id) { ... }     // THE action (one per file)
+ *
+ * No folder automation: an action with no `method` export stays a POST, exactly
+ * as before this feature (additive, non-breaking).
+ */
+
+/** The HTTP verbs an action may declare. */
+export const RPC_VERBS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+
+/** Reserved config export names (special only in a `'use server'` file). */
+export const RESERVED_CONFIG = new Set(['method', 'cache', 'tags', 'invalidates', 'validate', 'middleware']);
+
+/** Verbs whose args ride the URL (so the read is cacheable / the URL is the key). */
+export const URL_ARG_VERBS = new Set(['GET', 'DELETE']);
+
+/** Verbs that are CSRF-exempt (safe, no state change). */
+export const SAFE_VERBS = new Set(['GET']);
+
+/**
+ * Max length of the URL-encoded args for a URL-arg verb before the client stub
+ * falls back to a POST with the args in the body (uncacheable). Conservative so
+ * the URL stays within common browser / CDN limits. TanStack Start uses 1MB for
+ * its server-side GET cap; the browser/CDN URL ceiling is the tighter bound.
+ */
+export const MAX_URL_ARGS = 4096;
+
+/**
+ * The exported function names that are ACTIONS (callable), i.e. every function
+ * export whose name is not a reserved config key. With one-function-per-file
+ * there is exactly one; the framework still returns the list so a misconfigured
+ * multi-function file is detectable (a `webjs check` rule).
+ * @param {Record<string, unknown>} mod
+ * @returns {string[]}
+ */
+export function actionFunctionNames(mod) {
+  const names = Object.keys(mod).filter(
+    (k) => typeof mod[k] === 'function' && !RESERVED_CONFIG.has(k),
+  );
+  if (typeof mod.default === 'function' && !names.includes('default')) names.push('default');
+  return names;
+}
+
+/**
+ * The action's HTTP method: the declared `method` export uppercased and
+ * validated against {@link RPC_VERBS}, defaulting to POST (an unknown value
+ * falls back to POST rather than throwing, the #232 fail-safe posture).
+ * @param {Record<string, unknown>} mod
+ * @returns {string}
+ */
+export function actionMethod(mod) {
+  const raw = mod && mod.method;
+  if (typeof raw !== 'string') return 'POST';
+  const m = raw.trim().toUpperCase();
+  return RPC_VERBS.has(m) ? m : 'POST';
+}
+
+/**
+ * Normalize the `cache` export to `{ maxAge, swr, public }` or null (no
+ * caching). A number is `maxAge` seconds; an object carries `maxAge` / `swr`
+ * (stale-while-revalidate) / `public`. Default `private` (a read is per-user
+ * safe unless the author opts into shared caching with `public: true`).
+ * @param {Record<string, unknown>} mod
+ * @returns {{ maxAge: number, swr: number, public: boolean } | null}
+ */
+export function actionCache(mod) {
+  const raw = mod && mod.cache;
+  if (raw == null) return null;
+  if (typeof raw === 'number' && Number.isFinite(raw) && raw >= 0) {
+    return { maxAge: Math.floor(raw), swr: 0, public: false };
+  }
+  if (typeof raw === 'object') {
+    const maxAge = Number.isFinite(raw.maxAge) && raw.maxAge >= 0 ? Math.floor(raw.maxAge) : 0;
+    const swr = Number.isFinite(raw.swr) && raw.swr >= 0 ? Math.floor(raw.swr) : 0;
+    return { maxAge, swr, public: raw.public === true };
+  }
+  return null;
+}
+
+/**
+ * The action's per-action middleware chain (#490): the `middleware` export, an
+ * array of `(ctx, next) => result` functions, or [] when absent / malformed.
+ * @param {Record<string, unknown>} mod
+ * @returns {Function[]}
+ */
+export function actionMiddleware(mod) {
+  const raw = mod && mod.middleware;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((m) => typeof m === 'function');
+}
+
+/**
+ * Resolve the `tags` / `invalidates` / `validate` config functions off the
+ * module (each is a function or absent).
+ * @param {Record<string, unknown>} mod
+ * @param {'tags'|'invalidates'|'validate'} name
+ * @returns {Function | null}
+ */
+export function actionConfigFn(mod, name) {
+  return mod && typeof mod[name] === 'function' ? mod[name] : null;
+}
+
+/**
+ * Compute the tag list for a `tags` / `invalidates` config given the call args.
+ * A function is invoked with the args (so `(id) => [`user:${id}`]` works); an
+ * array is used verbatim. Never throws into the caller; a bad tag fn yields [].
+ * @param {Function | unknown[] | null} tagsConfig
+ * @param {unknown[]} args
+ * @returns {string[]}
+ */
+export function resolveTags(tagsConfig, args) {
+  try {
+    const out = typeof tagsConfig === 'function' ? tagsConfig(...args) : tagsConfig;
+    if (!Array.isArray(out)) return [];
+    return out.filter((t) => typeof t === 'string' && t.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The `Cache-Control` value for a GET action response, or null (caller emits
+ * `no-store`). A cached GET is `public|private, max-age=N[, stale-while-
+ * revalidate=M]`; a GET with no `cache` config is uncached (null -> no-store).
+ * @param {string} method
+ * @param {{ maxAge: number, swr: number, public: boolean } | null} cache
+ * @returns {string | null}
+ */
+export function cacheControlFor(method, cache) {
+  if (method !== 'GET' || !cache) return null;
+  const scope = cache.public ? 'public' : 'private';
+  let h = `${scope}, max-age=${cache.maxAge}`;
+  if (cache.swr > 0) h += `, stale-while-revalidate=${cache.swr}`;
+  return h;
+}
+
+/**
+ * The set of request methods the action endpoint accepts for an action whose
+ * declared method is `method`. A URL-arg verb (GET/DELETE) ALSO accepts POST as
+ * the too-large-args fallback; a body verb accepts only itself.
+ * @param {string} method
+ * @returns {Set<string>}
+ */
+export function allowedRequestMethods(method) {
+  const s = new Set([method]);
+  if (URL_ARG_VERBS.has(method)) s.add('POST');
+  return s;
+}

package/src/action-middleware.d.ts

@@ -0,0 +1,21 @@
+/** Per-action middleware (#490). */
+
+/** The context object middleware accumulate and the action reads via actionContext(). */
+export interface ActionContext { [key: string]: unknown }
+
+/** A middleware's ctx: the request, the action args, the abort signal, and the shared context. */
+export interface ActionMiddlewareCtx {
+  request?: Request;
+  args?: unknown[];
+  signal?: AbortSignal;
+  context: ActionContext;
+}
+
+/** A per-action middleware: run `next()` to proceed, or return a value to short-circuit. */
+export type ActionMiddleware = (ctx: ActionMiddlewareCtx, next: () => Promise<unknown>) => unknown;
+
+/** The accumulated middleware context for the current action, or {} outside one. */
+export declare function actionContext(): ActionContext;
+
+/** Run an action through its middleware chain (framework-internal). */
+export declare function runActionChain(middleware: ActionMiddleware[], baseCtx: Partial<ActionMiddlewareCtx>, finalFn: () => unknown): Promise<unknown>;

package/src/action-middleware.js

@@ -0,0 +1,68 @@
+/**
+ * Per-action middleware (#490). An action file declares `export const middleware
+ * = [mw1, mw2]` (a reserved config export). Each middleware is
+ * `async (ctx, next) => result`, run around the action on BOTH the RPC endpoint
+ * and the `route.ts`/`expose()` boundary, like `validate`.
+ *
+ *   - `ctx` carries `{ request, args, signal, context }`. `context` is a shared
+ *     mutable object the chain accumulates; the action reads it via
+ *     `actionContext()` (no signature change, the same plumbing as
+ *     `actionSignal()`).
+ *   - `next()` runs the next middleware, ending at the action; its return value
+ *     flows back up. A middleware SHORT-CIRCUITS by returning a value (an
+ *     `ActionResult` envelope, e.g. `{ success: false, status: 401 }`) WITHOUT
+ *     calling `next()`, so the action never runs. A short-circuit is NOT a
+ *     completion: a GET short-circuit is served `no-store` (never cached) and a
+ *     mutation short-circuit does not run `invalidates`. On the RPC boundary the
+ *     short-circuit must be an `ActionResult` (serialized as the result, the
+ *     `status` riding inside per the #245 contract); on the `route.ts` / REST
+ *     boundary it may also be a `Response`, and an `ActionResult`'s `status`
+ *     maps to the HTTP status.
+ *
+ * The framework ships no middleware; it only runs the chain. Server-only.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/** Per-request accumulated context, readable by the action via actionContext(). */
+const als = new AsyncLocalStorage();
+
+/** Shared empty context returned outside an action (a direct server-to-server call). */
+const EMPTY = Object.freeze({});
+
+/**
+ * The accumulated middleware context for the current action, or a frozen empty
+ * object outside an action. The action reads `actionContext().user` etc.
+ * @returns {Record<string, unknown>}
+ */
+export function actionContext() {
+  return als.getStore() || EMPTY;
+}
+
+/**
+ * Run `finalFn` (the action) through the middleware chain, with a fresh shared
+ * `context` available to `actionContext()` for the whole chain. A middleware
+ * that does not call `next()` short-circuits (its return is the result). Guards
+ * against a middleware calling `next()` more than once.
+ * @param {Function[]} middleware
+ * @param {{ request?: Request, args?: unknown[], signal?: AbortSignal }} baseCtx
+ * @param {() => unknown} finalFn
+ * @returns {Promise<unknown>}
+ */
+export function runActionChain(middleware, baseCtx, finalFn) {
+  if (!middleware || middleware.length === 0) return finalFn();
+  const context = {};
+  const ctx = { ...baseCtx, context };
+  return als.run(context, () => {
+    let lastCalled = -1;
+    const dispatch = (i) => {
+      if (i <= lastCalled) {
+        return Promise.reject(new Error('next() called multiple times in a webjs action middleware'));
+      }
+      lastCalled = i;
+      const mw = middleware[i];
+      if (!mw) return finalFn();
+      return mw(ctx, () => dispatch(i + 1));
+    };
+    return dispatch(0);
+  });
+}

package/src/action-seed.js

@@ -0,0 +1,308 @@
+/**
+ * SSR action-result seeding (#472), follow-up to async render (#469).
+ *
+ * When a component's `async render()` does a bare `const u = await getUser(id)`
+ * during SSR, the action runs server-side and its result is baked into the
+ * first paint. On HYDRATION the client re-runs `async render()`, which re-calls
+ * the action over RPC. Stale-while-revalidate (#470) hides the flicker, but the
+ * redundant round-trip still happens once per async component on first load.
+ *
+ * This module captures each `'use server'` action result invoked DURING SSR and
+ * serializes it into the page (one `<script type="application/json">` block).
+ * The generated client RPC stub (`actions.js`) reads that seed on its FIRST call
+ * with matching args and resolves without the RPC; a later refetch / arg-change
+ * goes to the network as normal.
+ *
+ * ## How the capture works (no source transform, no build step)
+ *
+ * The framework promise is "what you write is what you see in the browser source
+ * tab", not "what you write is the exact function object that runs server-side"
+ * (the RPC stub already replaces the action on the client). So we install a
+ * SERVER-SIDE transparent facade via Node's synchronous `module.registerHooks`
+ * (Node 24+, main-thread): for a `'use server'` `*.server.*` module, the load
+ * hook returns a facade that re-exports each function wrapped in a `Proxy`. The
+ * Proxy records `(file, fn, args) -> result` into an ambient `AsyncLocalStorage`
+ * collector WHENEVER a collector is active, and is a pure passthrough otherwise.
+ *
+ * Recording is gated entirely by the ALS collector, which is established ONLY
+ * around the SSR page render (`collectSeeds`). The RPC endpoint path runs with
+ * NO collector, so the Proxy is a transparent passthrough there. The browser
+ * NEVER sees this module (it sees the RPC stub), and the on-disk source is
+ * unchanged, so the source-fidelity promise holds.
+ *
+ * ## Safety
+ *
+ * A key HIT returns the exact SSR value (correct by construction); a key MISS
+ * degrades to a normal RPC (never wrong data, only a missed optimization). The
+ * whole feature is therefore fail-open: any failure in the hook, the facade, or
+ * the serializer simply skips seeding and the client re-fetches as before.
+ *
+ * Disabled by default-off of the flag removes the hook entirely, so module
+ * loading is byte-identical to before the feature.
+ */
+
+import * as nodeModule from 'node:module';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { stringify } from '@webjsdev/core';
+import { hashFile } from './actions.js';
+
+/** Ambient per-render seed collector. `Map<key, value>` or undefined. */
+const als = new AsyncLocalStorage();
+
+/** Set once the load hook is installed (the flag is on at boot). */
+let _enabled = false;
+/** Idempotency guard: `module.registerHooks` must run at most once. */
+let _registered = false;
+
+/** Memoized `absPath -> hash` so a hot action call does not re-hash per call. */
+const _hashCache = new Map();
+
+/** This module's own URL, embedded into the generated facade's import. */
+const SELF_URL = import.meta.url;
+
+/**
+ * Whether seeding is active (the load hook is installed). The SSR emitter
+ * (`ssr.js`) checks this so a disabled app does ZERO extra work and produces
+ * byte-identical output.
+ * @returns {boolean}
+ */
+export function seedingEnabled() {
+  return _enabled;
+}
+
+/**
+ * Compute (and memoize) the action file's hash the SAME way the RPC stub /
+ * action index do (`hashFile` over the absolute path string), so the seed key
+ * the server emits matches the key the client stub looks up. A path mismatch
+ * (e.g. a symlinked appDir whose realpath differs) only yields a key MISS,
+ * which safely degrades to a normal RPC.
+ * @param {string} absPath
+ * @returns {Promise<string>}
+ */
+async function hashFor(absPath) {
+  let h = _hashCache.get(absPath);
+  if (h === undefined) {
+    h = await hashFile(absPath);
+    _hashCache.set(absPath, h);
+  }
+  return h;
+}
+
+/**
+ * Record one action call's resolved result into the active collector, keyed
+ * `hash/fn/stringify(args)`. The args key uses the SAME serializer the client
+ * stub uses to form its lookup key, so they match for identical args. Never
+ * throws into the caller's render: a serialization failure just drops the seed
+ * (the client re-fetches).
+ * @param {Map<string, unknown>} collector
+ * @param {string} file absolute action file path
+ * @param {string} fnName
+ * @param {unknown[]} args
+ * @param {unknown} value resolved action result
+ */
+async function recordSeed(collector, file, fnName, args, value) {
+  try {
+    const hash = await hashFor(file);
+    const argsKey = await stringify(args);
+    collector.set(`${hash}/${fnName}/${argsKey}`, value);
+  } catch {
+    // Drop the seed; the client stub falls back to a normal RPC.
+  }
+}
+
+/**
+ * Wrap one exported action function so that, when a collector is active, its
+ * resolved result is recorded. Outside a collector (the RPC endpoint path) it is
+ * a transparent passthrough. Non-functions (a `const VERSION = '1.0'` export)
+ * pass through untouched, and the Proxy forwards property reads, so `expose()` /
+ * `validateInput()` metadata stored on the function (`__webjsHttp`) still
+ * resolves through `getExposed()`.
+ * @param {string} file absolute action file path
+ * @param {string} fnName
+ * @param {unknown} orig
+ * @returns {unknown}
+ */
+export function __seedWrap(file, fnName, orig) {
+  if (typeof orig !== 'function') return orig;
+  return new Proxy(orig, {
+    apply(target, thisArg, args) {
+      const collector = als.getStore();
+      const result = Reflect.apply(target, thisArg, args);
+      if (!collector) return result;
+      if (result && typeof result.then === 'function') {
+        // Record the RESOLVED value, and return the same value to the caller so
+        // the awaiting `async render()` gets its data unchanged.
+        return result.then(async (value) => {
+          await recordSeed(collector, file, fnName, args, value);
+          return value;
+        });
+      }
+      // A synchronous return (rare for an action): record best-effort. The
+      // record is async but fire-and-forget here; collectSeeds awaits the
+      // render's own microtasks, and a sync action that the render awaits will
+      // have settled the record before the render resolves.
+      recordSeed(collector, file, fnName, args, result);
+      return result;
+    },
+  });
+}
+
+/**
+ * Extract the names of every named export from an action module's source, used
+ * to generate the facade's `export const NAME = wrap(...)` lines. Conservative:
+ * a name it misses simply is not wrapped (no seed for it, RPC fallback). A
+ * `export *` re-export cannot be enumerated statically, so its presence makes
+ * the caller skip faceting that module entirely (passthrough = no seeding for
+ * it), never producing a broken facade.
+ * @param {string} src
+ * @returns {{ names: string[], hasDefault: boolean, hasStar: boolean } }
+ */
+export function extractExportNames(src) {
+  const names = new Set();
+  let m;
+  const reFn = /\bexport\s+(?:async\s+)?function\s*\*?\s+([A-Za-z_$][\w$]*)/g;
+  while ((m = reFn.exec(src))) names.add(m[1]);
+  const reVar = /\bexport\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/g;
+  while ((m = reVar.exec(src))) names.add(m[1]);
+  const reClass = /\bexport\s+(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/g;
+  while ((m = reClass.exec(src))) names.add(m[1]);
+  const reList = /\bexport\s*\{([^}]*)\}/g;
+  while ((m = reList.exec(src))) {
+    for (const part of m[1].split(',')) {
+      const seg = part.trim();
+      if (!seg) continue;
+      // `a` or `a as b` (the EXPORTED name is what an importer binds).
+      const as = seg.split(/\s+as\s+/);
+      const exported = (as[1] || as[0]).trim();
+      if (/^[A-Za-z_$][\w$]*$/.test(exported) && exported !== 'default') names.add(exported);
+      else if (exported === 'default') names.add('__default__');
+    }
+  }
+  const hasDefault = /\bexport\s+default\b/.test(src) || names.delete('__default__');
+  const hasStar = /\bexport\s*\*/.test(src);
+  return { names: [...names], hasDefault, hasStar };
+}
+
+/**
+ * Build the facade module source for a `'use server'` action module: it imports
+ * the REAL module via a `?webjs-seed-orig` query (which the hook passes through
+ * unwrapped) and re-exports each function wrapped through `__seedWrap`.
+ * @param {string} origUrl the real module URL, WITHOUT the seed query
+ * @param {string} absPath the real module's absolute file path (the hash basis)
+ * @param {{ names: string[], hasDefault: boolean }} exports
+ * @returns {string}
+ */
+function buildFacade(origUrl, absPath, exports) {
+  const sep = origUrl.includes('?') ? '&' : '?';
+  const origSpec = JSON.stringify(origUrl + sep + 'webjs-seed-orig');
+  const file = JSON.stringify(absPath);
+  let out = `import * as __orig from ${origSpec};\n`;
+  out += `import { __seedWrap as __w } from ${JSON.stringify(SELF_URL)};\n`;
+  for (const n of exports.names) {
+    const k = JSON.stringify(n);
+    out += `export const ${n} = __w(${file}, ${k}, __orig[${k}]);\n`;
+  }
+  if (exports.hasDefault) {
+    out += `export default __w(${file}, 'default', __orig.default);\n`;
+  }
+  return out;
+}
+
+/** Match `*.server.{js,ts,mjs,mts}` (optionally with a query). */
+const SERVER_FILE_RE = /\.server\.m?[jt]s(\?|$)/;
+/** The `'use server'` directive in the file head. */
+const USE_SERVER_RE = /^\s*(['"])use server\1\s*;?\s*$/m;
+
+/**
+ * The synchronous `module.registerHooks` load hook. For a `'use server'`
+ * `*.server.*` module it returns a wrapping facade; for everything else
+ * (including the `?webjs-seed-orig` passthrough of the real module) it defers to
+ * `nextLoad`. Fail-open: any error defers to `nextLoad`, so a load that the hook
+ * cannot facade simply runs unwrapped (no seeding for it).
+ * @param {string} url
+ * @param {object} context
+ * @param {(u: string, c: object) => any} nextLoad
+ */
+function seedLoadHook(url, context, nextLoad) {
+  try {
+    if (!SERVER_FILE_RE.test(url)) return nextLoad(url, context);
+    // The facade's own `?webjs-seed-orig` import must load the REAL module.
+    if (url.includes('webjs-seed-orig')) return nextLoad(url, context);
+    const absPath = fileURLToPath(url.split('?')[0]);
+    const src = readFileSync(absPath, 'utf8');
+    const head = src.split('\n').slice(0, 5).join('\n');
+    if (!USE_SERVER_RE.test(head)) return nextLoad(url, context);
+    const exports = extractExportNames(src);
+    // A `export *` re-export cannot be enumerated; skip faceting (passthrough)
+    // so we never emit a facade that silently drops re-exported bindings.
+    if (exports.hasStar) return nextLoad(url, context);
+    if (exports.names.length === 0 && !exports.hasDefault) return nextLoad(url, context);
+    const source = buildFacade(url, absPath, exports);
+    return { source, format: 'module', shortCircuit: true };
+  } catch {
+    return nextLoad(url, context);
+  }
+}
+
+/**
+ * Install the seed load hook (idempotent). Called once at boot from `dev.js`
+ * when seeding is enabled, BEFORE any action module is imported (ESM caches by
+ * URL, so a module loaded before the hook would never be faceted). A no-op on a
+ * second call.
+ */
+export function registerSeedHooks() {
+  _enabled = true;
+  if (_registered) return;
+  _registered = true;
+  nodeModule.registerHooks({ load: seedLoadHook });
+}
+
+/**
+ * Run `fn` (the page render) inside a fresh ambient seed collector and return
+ * both its value and the collected seeds. Every action call made during the
+ * render (however deeply nested in the SSR walker / async render chain) records
+ * into this collector via the ambient ALS.
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<{ value: T, collector: Map<string, unknown> }>}
+ */
+export async function collectSeeds(fn) {
+  const collector = new Map();
+  const value = await als.run(collector, fn);
+  return { value, collector };
+}
+
+/**
+ * Serialize a collector into a `<script type="application/json">` block to embed
+ * in the page. Returns '' for an empty collector (so a render with no seeded
+ * action is byte-identical to before). The payload is rich-serialized (same wire
+ * format the RPC stub's `parse` reads) and HTML-escaped so it can never break out
+ * of the script element. A `type="application/json"` script is DATA, not
+ * executable JS, so it needs no CSP nonce.
+ * @param {Map<string, unknown>} collector
+ * @returns {Promise<string>}
+ */
+export async function buildSeedScript(collector) {
+  if (!collector || collector.size === 0) return '';
+  try {
+    const obj = {};
+    for (const [k, v] of collector) obj[k] = v;
+    const payload = await stringify(obj);
+    const safe = payload
+      .replace(/</g, '\\u003c')
+      .replace(/>/g, '\\u003e')
+      .replace(/&/g, '\\u0026')
+      .replace(/\u2028/g, '\\u2028')
+      .replace(/\u2029/g, '\\u2029');
+    return `<script type="application/json" id="__webjs-seeds">${safe}</script>`;
+  } catch {
+    return '';
+  }
+}
+
+/** Test seam: clear the per-file hash memo (e.g. between fixtures). */
+export function __clearSeedHashCache() {
+  _hashCache.clear();
+}

package/src/action-signal.js

@@ -0,0 +1,39 @@
+/**
+ * Server-side action AbortSignal (#492). The RPC endpoint runs an action inside
+ * `runWithActionSignal(req.signal, fn)`, so the action can read the request's
+ * AbortSignal via `actionSignal()` and stop expensive work (a DB query, an
+ * upstream fetch) when the client disconnects or aborts the call.
+ *
+ * Isomorphic-friendly: `actionSignal()` returns a never-aborting signal when
+ * called outside an action (e.g. a direct server-to-server call), so the same
+ * `fetch(url, { signal: actionSignal() })` line is safe everywhere.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const als = new AsyncLocalStorage();
+
+/** A shared signal that never aborts, returned outside an action. */
+const NEVER = (() => {
+  const c = new AbortController();
+  return c.signal;
+})();
+
+/**
+ * Run `fn` with `signal` available to `actionSignal()` for its async extent.
+ * @template T
+ * @param {AbortSignal | undefined} signal
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function runWithActionSignal(signal, fn) {
+  return als.run(signal || NEVER, fn);
+}
+
+/**
+ * The current action's request AbortSignal (fires on client disconnect / abort),
+ * or a never-aborting signal outside an action.
+ * @returns {AbortSignal}
+ */
+export function actionSignal() {
+  return als.getStore() || NEVER;
+}

package/src/actions.js

@@ -8,6 +8,15 @@ import { verify as verifyCsrf, CSRF_COOKIE, CSRF_HEADER } from './csrf.js';
 import { getSerializer } from './serializer.js';
 import { resolveOrigin } from './cors.js';
 import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
+import {
+  actionMethod, actionFunctionNames, actionCache, actionConfigFn, resolveTags,
+  cacheControlFor, allowedRequestMethods, URL_ARG_VERBS, SAFE_VERBS, MAX_URL_ARGS,
+  RESERVED_CONFIG, actionMiddleware,
+} from './action-config.js';
+import { revalidateTags } from './cache-tags.js';
+import { runWithActionSignal } from './action-signal.js';
+import { runActionChain } from './action-middleware.js';
+import { ifNoneMatchSatisfied } from './conditional-get.js';
 import { getBodyLimits } from './context.js';
 import { basePath } from './importmap.js';
 import { withBasePath } from './base-path.js';
@@ -327,54 +336,116 @@ throw new Error(${JSON.stringify(msg)});
 export async function serveActionStub(idx, absFile) {
   const mod = await loadModule(absFile, idx.dev);
   const hash = idx.fileToHash.get(absFile) || await hashFile(absFile);
-  const fnNames = Object.keys(mod).filter((k) => typeof mod[k] === 'function');
-  if (typeof mod.default === 'function' && !fnNames.includes('default')) {
-    fnNames.push('default');
-  }
+  // HTTP-verb actions (#488): the file declares its verb via `export const
+  // method` (default POST). The function exports are the actions; the reserved
+  // config exports (method/cache/tags/invalidates/validate/middleware) are excluded.
+  const fnNames = actionFunctionNames(mod);
+  const method = actionMethod(mod);
   // The RPC endpoint is a framework-emitted same-origin URL, so it must
   // carry the basePath prefix under a sub-path deploy (#256), exactly like
   // the importmap targets and the boot module specifiers. Without this the
   // stub would POST to a bare /__webjs/action/... that the ingress strip
   // 404s, breaking every server action when webjs.basePath is set.
   const actionUrl = withBasePath(`/__webjs/action/${hash}/`, basePath());
-  const body = `// webjs: generated server-action stub for ${relative(idx.appDir, absFile)}\n` +
-    `import { stringify as __wjStringify, parse as __wjParse } from '@webjsdev/core';\n` +
-    `function __csrf() {\n` +
-    `  const m = document.cookie.match(/(?:^|;\\s*)${CSRF_COOKIE}=([^;]+)/);\n` +
-    `  return m ? decodeURIComponent(m[1]) : '';\n` +
-    `}\n` +
-    `async function __rpc(fn, args) {\n` +
-    `  const body = await __wjStringify(args);\n` +
-    `  const res = await fetch(${JSON.stringify(actionUrl)} + fn, {\n` +
-    `    method: 'POST',\n` +
-    `    headers: {\n` +
-    `      'content-type': ${JSON.stringify(RPC_CONTENT_TYPE)},\n` +
-    `      ${JSON.stringify(CSRF_HEADER)}: __csrf()\n` +
-    `    },\n` +
-    `    credentials: 'same-origin',\n` +
-    `    body\n` +
-    `  });\n` +
-    `  const ct = res.headers.get('content-type') || '';\n` +
-    `  const text = await res.text();\n` +
-    `  const parsed = ct.includes(${JSON.stringify(RPC_CONTENT_TYPE)})\n` +
-    `    ? __wjParse(text)\n` +
-    `    : (ct.includes('application/json') ? JSON.parse(text) : text);\n` +
-    `  if (!res.ok) {\n` +
-    `    const msg = (parsed && parsed.error) || ('webjs action ' + fn + ' -> ' + res.status);\n` +
-    `    throw new Error(msg);\n` +
-    `  }\n` +
-    `  return parsed;\n` +
-    `}\n` +
-    fnNames
-      .map((name) =>
-        name === 'default'
-          ? `export default (...args) => __rpc('default', args);`
-          : `export const ${name} = (...args) => __rpc(${JSON.stringify(name)}, args);`
-      )
-      .join('\n') + '\n';
+  const body = buildStubBody({ hash, method, fnNames, actionUrl });
   return body;
 }
 
+/**
+ * Build the generated client stub source for a `'use server'` action file. The
+ * transport depends on the file's declared `method`:
+ *   - GET: args ride the URL (`?a=`), the SSR seed (#472) is read first, the
+ *     browser HTTP cache is consulted, and a tag-invalidated key revalidates;
+ *     CSRF-exempt (a safe read). Over-large args fall back to a POST.
+ *   - DELETE: args ride the URL, CSRF-protected, over-large args fall back to a
+ *     POST.
+ *   - POST / PUT / PATCH: rich body, CSRF-protected.
+ * Every path reads `X-Webjs-Invalidate` (mark tags stale) and a GET reads
+ * `X-Webjs-Tags` (register the key's tags), so a later read sees a mutation.
+ * @param {{ hash: string, method: string, fnNames: string[], actionUrl: string }} opts
+ * @returns {string}
+ */
+function buildStubBody({ hash, method, fnNames, actionUrl }) {
+  const URL_ARG = URL_ARG_VERBS.has(method);
+  const SAFE = SAFE_VERBS.has(method);
+  const J = JSON.stringify;
+  const lines = [];
+  lines.push(`// webjs: generated server-action stub (${method})`);
+  // Every verb reads the SSR seed (#472) first: an async-render READ invoked
+  // during SSR is seeded regardless of its declared verb (a read with no
+  // `method` is a default POST), so the first client call resolves from the
+  // seed with no hydration round-trip. The browser-cache staleness check is
+  // GET-only (only a GET is browser-cached).
+  const imports = ['stringify as __s', 'parse as __p', 'takeSeed as __seedTake', 'SEED_MISS as __MISS', 'markStale as __markStale', 'parseTagHeader as __tagHdr', 'activeActionSignal as __sig'];
+  if (method === 'GET') {
+    imports.push('registerKeyTags as __regTags', 'consumeStale as __stale', 'fetchMark as __mark');
+  }
+  lines.push(`import { ${imports.join(', ')} } from '@webjsdev/core';`);
+  lines.push(`const __URL = ${J(actionUrl)};`);
+  lines.push(`const __HASH = ${J(hash)};`);
+  lines.push(`const __METHOD = ${J(method)};`);
+  lines.push(`const __MAX = ${MAX_URL_ARGS};`);
+  lines.push(`const __CT = ${J(RPC_CONTENT_TYPE)};`);
+  lines.push(`function __csrf() { const m = document.cookie.match(/(?:^|;\\s*)${CSRF_COOKIE}=([^;]+)/); return m ? decodeURIComponent(m[1]) : ''; }`);
+  // Shared: parse a response, surface invalidation, register a GET's tags
+  // (stamped with the clock SAMPLED BEFORE the fetch, so a mutation in flight is
+  // caught on the next read).
+  lines.push(`async function __handle(res, fn, key, since) {`);
+  lines.push(`  const inv = __tagHdr(res.headers.get('x-webjs-invalidate')); if (inv.length) __markStale(inv);`);
+  lines.push(`  if (key != null) { const t = __tagHdr(res.headers.get('x-webjs-tags')); if (t.length) __regTags(key, t, since); }`);
+  lines.push(`  const ct = res.headers.get('content-type') || '';`);
+  lines.push(`  const text = await res.text();`);
+  lines.push(`  const parsed = ct.includes(__CT) ? __p(text) : (ct.includes('application/json') ? JSON.parse(text) : text);`);
+  lines.push(`  if (!res.ok) throw new Error((parsed && parsed.error) || ('webjs action ' + fn + ' -> ' + res.status));`);
+  lines.push(`  return parsed;`);
+  lines.push(`}`);
+  // Body sender (POST/PUT/PATCH, and the URL-arg too-large fallback). `sig` is
+  // captured SYNCHRONOUSLY at __call entry (#492): the active render signal must
+  // be read before the stub's first await (stringify), or the render's
+  // synchronous window has already closed and cleared it.
+  lines.push(`async function __body(fn, body, m, csrf, sig) {`);
+  lines.push(`  const headers = { 'content-type': __CT }; if (csrf) headers[${J(CSRF_HEADER)}] = __csrf();`);
+  lines.push(`  const res = await fetch(__URL + fn, { method: m, headers, credentials: 'same-origin', body, signal: sig });`);
+  lines.push(`  return __handle(res, fn, null);`);
+  lines.push(`}`);
+  if (URL_ARG) {
+    // GET/DELETE: args in the URL, with a POST fallback when too large.
+    lines.push(`async function __call(fn, args) {`);
+    lines.push(`  const sig = __sig();`); // sync capture before any await
+    lines.push(`  const key = await __s(args);`);
+    lines.push(`  const seeded = __seedTake(__HASH, fn, key); if (seeded !== __MISS) return seeded;`);
+    lines.push(`  if (key.length > __MAX) return __body(fn, key, 'POST', ${SAFE ? 'false' : 'true'}, sig);`);
+    if (method === 'GET') {
+      lines.push(`  const bypass = __stale(key);`);
+      lines.push(`  const since = __mark();`);
+      lines.push(`  const res = await fetch(__URL + fn + '?a=' + encodeURIComponent(key), { method: 'GET', credentials: 'same-origin', cache: bypass ? 'no-cache' : 'default', signal: sig });`);
+      lines.push(`  return __handle(res, fn, key, since);`);
+    } else {
+      lines.push(`  const res = await fetch(__URL + fn + '?a=' + encodeURIComponent(key), { method: __METHOD, headers: { ${J(CSRF_HEADER)}: __csrf() }, credentials: 'same-origin', signal: sig });`);
+      lines.push(`  return __handle(res, fn, null);`);
+    }
+    lines.push(`}`);
+  } else {
+    // POST/PUT/PATCH: rich body. The seed read makes a default-POST async-render
+    // read resolve from the SSR seed on hydration (#472); a true mutation is
+    // never SSR-invoked, so the seed simply misses.
+    lines.push(`async function __call(fn, args) {`);
+    lines.push(`  const sig = __sig();`); // sync capture before any await
+    lines.push(`  const key = await __s(args);`);
+    lines.push(`  const seeded = __seedTake(__HASH, fn, key); if (seeded !== __MISS) return seeded;`);
+    lines.push(`  return __body(fn, key, __METHOD, true, sig);`);
+    lines.push(`}`);
+  }
+  for (const name of fnNames) {
+    lines.push(
+      name === 'default'
+        ? `export default (...args) => __call('default', args);`
+        : `export const ${name} = (...args) => __call(${J(name)}, args);`,
+    );
+  }
+  return lines.join('\n') + '\n';
+}
+
 /**
  * Invoke a server action via the internal RPC wire format.
  * @param {ActionIndex} idx
@@ -387,34 +458,62 @@ export async function serveActionStub(idx, absFile) {
  *   it so a throwing sink can never affect the response.
  */
 export async function invokeAction(idx, hash, fnName, req, onError) {
-  if (!verifyCsrf(req)) {
-    return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
-  }
   const file = idx.hashToFile.get(hash);
   if (!file) return rpcResponse({ error: 'Unknown action' }, { status: 404 });
-  // Bounded read (issue #237): reject an over-limit RPC body with 413 without
-  // buffering it whole (Content-Length fast-reject, plus a streaming cap for a
-  // chunked body with no declared length).
-  const { tooLarge, text: body } = await readTextBounded(req, jsonBodyLimit());
-  if (tooLarge) return payloadTooLarge();
+  const mod = await loadModule(file, idx.dev);
+  const fn = fnName === 'default' ? mod.default : mod[fnName];
+  // A reserved config export (method/cache/tags/invalidates/validate/middleware) is never
+  // a callable action even though some are functions (#488).
+  if (typeof fn !== 'function' || RESERVED_CONFIG.has(fnName)) {
+    return rpcResponse({ error: `Unknown action ${fnName}` }, { status: 404 });
+  }
+
+  // HTTP-verb dispatch (#488). The action declares its method (default POST). A
+  // URL-arg verb (GET/DELETE) also accepts a POST fallback for over-large args.
+  const method = actionMethod(mod);
+  const reqMethod = req.method.toUpperCase();
+  const allowed = allowedRequestMethods(method);
+  if (!allowed.has(reqMethod)) {
+    return rpcResponse(
+      { error: `expected ${method} for ${fnName}, got ${reqMethod}` },
+      { status: 405, headers: { allow: [...allowed].join(', ') } },
+    );
+  }
+  // CSRF: required for every verb except a safe GET (a read with no state
+  // change, which is also browser-cacheable so it cannot carry a fresh token).
+  if (!SAFE_VERBS.has(method) && !verifyCsrf(req)) {
+    return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
+  }
+
+  // Args ride the URL for a URL-arg request (GET / DELETE), else the body.
   let args = [];
+  const fromUrl = reqMethod === 'GET' || reqMethod === 'DELETE';
   try {
-    args = body ? getSerializer().deserialize(body) : [];
+    if (fromUrl) {
+      const a = new URL(req.url).searchParams.get('a');
+      args = a ? getSerializer().deserialize(a) : [];
+    } else {
+      const { tooLarge, text: body } = await readTextBounded(req, jsonBodyLimit());
+      if (tooLarge) return payloadTooLarge();
+      args = body ? getSerializer().deserialize(body) : [];
+    }
     if (!Array.isArray(args)) args = [args];
   } catch {
     return rpcResponse({ error: 'Invalid request body' }, { status: 400 });
   }
-  const mod = await loadModule(file, idx.dev);
-  const fn = fnName === 'default' ? mod.default : mod[fnName];
-  if (typeof fn !== 'function') return rpcResponse({ error: `Unknown action ${fnName}` }, { status: 404 });
   // Input validation (#245): a validator attached via `validateInput(fn, ...)`
   // or `expose(spec, fn, { validate })` runs SERVER-SIDE before the body on
   // this RPC path too, not just the REST path. The RPC stub sends an args
   // array; an action conventionally takes one input object, so validate the
   // FIRST arg (matching how the REST path validates its single merged object).
+  // Validation is a BOUNDARY concern (#488): the validator is the `validate`
+  // config export (the new model), or the legacy `expose`/`validateInput`
+  // attachment. It runs on this RPC boundary on the FIRST arg (the conventional
+  // single input object), never on a direct server-to-server call.
   const attached = getExposed(fn);
-  if (attached && typeof attached.validate === 'function') {
-    const v = runValidate(attached.validate, args[0]);
+  const validate = actionConfigFn(mod, 'validate') || (attached && attached.validate);
+  if (typeof validate === 'function') {
+    const v = runValidate(validate, args[0]);
     if (!v.ok) {
       if (v.thrown !== undefined) {
         // A THROWN validator behaves like a thrown action: a sanitized error
@@ -432,14 +531,67 @@ export async function invokeAction(idx, hash, fnName, req, onError) {
     args = [v.value, ...args.slice(1)];
   }
   try {
-    const result = await fn(...args);
-    return rpcResponse(result ?? null);
+    // Run inside the request's AbortSignal scope (#492) and the per-action
+    // middleware chain (#490): the chain wraps the action, can short-circuit
+    // (an auth middleware returning an ActionResult), and accumulates context
+    // the action reads via actionContext(). `ranAction` distinguishes a real
+    // action completion from a middleware short-circuit (the action never ran).
+    const middleware = actionMiddleware(mod);
+    let ranAction = false;
+    const result = await runWithActionSignal(req.signal, () =>
+      runActionChain(middleware, { request: req, args, signal: req.signal }, () => { ranAction = true; return fn(...args); }));
+    if (method === 'GET') {
+      // A short-circuit (the action did not run, e.g. an auth denial) is NEVER
+      // cached: serve the envelope no-store so a denial is not stored or shared.
+      if (!ranAction) return rpcResponse(result ?? null, { headers: { 'cache-control': 'no-store' } });
+      return await getActionResponse(result, mod, args, req);
+    }
+    // A mutation (POST/PUT/PATCH/DELETE): only a COMPLETED action evicts its
+    // `invalidates` tags; a short-circuit (the action never ran) does not.
+    const headers = {};
+    if (ranAction) {
+      const inv = resolveTags(actionConfigFn(mod, 'invalidates'), args);
+      if (inv.length) {
+        await revalidateTags(inv);
+        headers['x-webjs-invalidate'] = inv.join(',');
+      }
+    }
+    return rpcResponse(result ?? null, { headers });
   } catch (e) {
     if (typeof onError === 'function') onError(e);
     return actionErrorResponse(e, idx.dev);
   }
 }
 
+/**
+ * Build a GET action's response (#488): the serialized body plus a weak ETag
+ * (content hash), the `Cache-Control` from the `cache` config (else `no-store`),
+ * and `X-Webjs-Tags`. Answers `If-None-Match` with a 304 itself rather than
+ * relying on the conditional-GET funnel, which EXCLUDES `private` responses (the
+ * default here); a per-user browser cache may still revalidate to a 304.
+ * @param {unknown} result
+ * @param {Record<string, unknown>} mod
+ * @param {unknown[]} args
+ * @param {Request} req
+ * @returns {Promise<Response>}
+ */
+async function getActionResponse(result, mod, args, req) {
+  const s = getSerializer();
+  const bodyStr = await s.serialize(result ?? null);
+  const cache = actionCache(mod);
+  const etag = `W/"${(await digestHex('SHA-256', bodyStr)).slice(0, 16)}"`;
+  const headers = new Headers({ 'content-type': s.contentType, etag });
+  headers.set('cache-control', cacheControlFor('GET', cache) || 'no-store');
+  if (cache) {
+    const tags = resolveTags(actionConfigFn(mod, 'tags'), args);
+    if (tags.length) headers.set('x-webjs-tags', tags.join(','));
+  }
+  if (ifNoneMatchSatisfied(req.headers.get('if-none-match'), etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(bodyStr, { status: 200, headers });
+}
+
 /**
  * Match an incoming request against an expose()d action route.
  * Returns the single matched route+params for normal methods.
@@ -591,8 +743,21 @@ export async function invokeExposedAction(idx, route, params, req, onError) {
   const fn = mod[route.fnName];
   if (typeof fn !== 'function') return new Response(`Unknown action ${route.fnName}`, { status: 404 });
   try {
-    const result = await fn(arg, { req, params });
+    // The REST boundary wires the request signal (#492) and the per-action
+    // middleware chain (#490) too, symmetric with the RPC path. `ranAction`
+    // marks whether the action ran (vs a middleware short-circuit).
+    const middleware = actionMiddleware(mod);
+    let ranAction = false;
+    const result = await runWithActionSignal(req.signal, () =>
+      runActionChain(middleware, { request: req, args: [arg], signal: req.signal }, () => { ranAction = true; return fn(arg, { req, params }); }));
     if (result instanceof Response) return result;
+    // A middleware short-circuit on the REST boundary maps the envelope's
+    // `status` to the HTTP status (like the validate failure above), so a
+    // non-webjs REST client sees the real status, not a 200 with it in the body.
+    if (!ranAction && result && typeof result === 'object' && typeof result.status === 'number') {
+      const { status, ...payload } = result;
+      return Response.json(payload, { status });
+    }
     return Response.json(result ?? null);
   } catch (e) {
     if (typeof onError === 'function') onError(e);

package/src/check.js

@@ -10,6 +10,7 @@ import { buildModuleGraph, transitiveDeps } from './module-graph.js';
 import { scanComponents } from './component-scanner.js';
 import { buildRouteTable } from './router.js';
 import { analyzeElision } from './component-elision.js';
+import { RESERVED_CONFIG } from './action-config.js';
 
 /**
  * Convention validator for webjs apps.
@@ -107,6 +108,11 @@ export const RULES = [
     description:
       'A page / layout / component module that SHIPS to the browser (the build does NOT elide it) must not transitively import a server-only `.server.{ts,js}` module. The server module is replaced by a stub in the browser, so the import is fine while the page is display-only and elided (its server import is stripped), but the moment the page also does client work (it imports a component to register, enables the client router, uses a reactive primitive, …) it stops being elided and must load in the browser, dragging the server import with it. The stub then throws (or a server-only export like `auth` is missing) the instant the module loads, a runtime browser crash that `webjs typecheck` and the rest of `webjs check` miss. The rule reuses the build\'s own elision verdict, so it ONLY fires on modules that genuinely ship; a display-only page the framework elides is never flagged. The fix is to keep the server call off the browser-shipped module: gate the route in `middleware.ts`, call the server through a `\'use server\'` action, or register the component in a layout so the page elides again. Server-to-server imports (`.server.ts` importing `.server.ts`) and `middleware.ts` / `route.ts` (never shipped) are never flagged.',
   },
+  {
+    name: 'one-action-per-configured-file',
+    description:
+      'A `\'use server\'` action file that declares HTTP-verb config (any of `method` / `cache` / `tags` / `invalidates` / `validate`, #488) must export exactly ONE callable action function. The config is file-level (it applies to the action in the file), so a second exported function would silently inherit the same verb / cache, which is almost never intended and makes the contract ambiguous. Move the extra function to its own `.server.ts` file (the one-function-per-file convention), or, if it is a private helper, do not export it. Files with no verb config are unaffected.',
+  },
   {
     name: 'no-scaffold-placeholder',
     description:
@@ -727,6 +733,37 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: one-action-per-configured-file (#488) ---
+  // A `'use server'` file that declares HTTP-verb config (method/cache/tags/
+  // invalidates/validate) must export exactly one callable action; the config
+  // is file-level, so a second exported function would silently inherit it.
+  {
+    for (const { rel, content, scan } of files) {
+      if (!/\.server\.m?[jt]s$/.test(rel)) continue;
+      if (!hasUseServerDirective(content)) continue;
+      if (!/\bexport\s+const\s+(?:method|cache|tags|invalidates|validate|middleware)\b/.test(scan)) continue;
+      const names = new Set();
+      let m;
+      const reFn = /\bexport\s+(?:async\s+)?function\s*\*?\s+([A-Za-z_$][\w$]*)/g;
+      while ((m = reFn.exec(scan))) names.add(m[1]);
+      // An arrow-const action: `export const x = (...) => ...`, the paren-less
+      // `export const x = id => ...`, or a function expression. The `=>` /
+      // `function` anchor keeps a plain `export const N = 5` from counting.
+      const reArrow = /\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?(?:function\b|(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>)/g;
+      while ((m = reArrow.exec(scan))) names.add(m[1]);
+      if (/\bexport\s+default\b/.test(scan)) names.add('default');
+      const actions = [...names].filter((n) => !RESERVED_CONFIG.has(n));
+      if (actions.length > 1) {
+        violations.push({
+          rule: 'one-action-per-configured-file',
+          file: rel,
+          message: `Configured action file exports ${actions.length} callable functions (${actions.join(', ')}); the verb/cache config is file-level, so only one action per file is allowed.`,
+          fix: 'Move the extra function to its own .server.{js,ts} file, or keep it private (do not export it).',
+        });
+      }
+    }
+  }
+
   // --- Rule: tag-name-has-hyphen ---
   {
     for (const { rel, scan } of files) {

package/src/dev.js

@@ -65,6 +65,7 @@ import {
   hasUseServerDirective,
   hashFile,
 } from './actions.js';
+import { registerSeedHooks } from './action-seed.js';
 import { defaultLogger } from './logger.js';
 import { assertNodeVersion } from './node-version.js';
 import { applyEnvValidation } from './env-schema.js';
@@ -253,6 +254,48 @@ export async function readElideEnabled(appDir) {
   return true;
 }
 
+/**
+ * Read the `WEBJS_SEED` environment override, if set. Same grammar as
+ * `WEBJS_ELIDE`: `0`/`false`/`off`/`no` force seeding OFF, `1`/`true`/`on`/`yes`
+ * force it ON, anything else (or unset) falls through to the package.json
+ * switch. The deploy-time / ops escape hatch and the seam tests use to render
+ * an app with seeding on and off in one process.
+ * @returns {boolean | undefined}
+ */
+function seedEnvOverride() {
+  const raw = process.env.WEBJS_SEED;
+  if (raw == null || raw === '') return undefined;
+  const v = String(raw).trim().toLowerCase();
+  if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false;
+  if (v === '1' || v === 'true' || v === 'on' || v === 'yes') return true;
+  return undefined;
+}
+
+/**
+ * Read the project-level SSR action-seeding switch (#472). Precedence: the
+ * `WEBJS_SEED` env override wins when set, otherwise the package.json
+ * `{ "webjs": { "seed": false } }` switch disables it (the client re-fetches on
+ * hydration as it did before the feature). Default ON (opt-out), mirroring
+ * elision: any value other than the literal `false` keeps seeding enabled.
+ *
+ * Seeding installs a process-global `module.registerHooks` load hook, so unlike
+ * elision it is read ONCE at boot (not re-read per rebuild): toggling it needs a
+ * restart, like a deploy.
+ * @param {string} appDir
+ * @returns {Promise<boolean>}
+ */
+export async function readSeedEnabled(appDir) {
+  const override = seedEnvOverride();
+  if (override !== undefined) return override;
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && pkg.webjs && pkg.webjs.seed === false) return false;
+  } catch {
+    // No package.json, malformed JSON, or unreadable. Keep the default.
+  }
+  return true;
+}
+
 /**
  * Read the per-path response-header config (`webjs.headers`) from the
  * app's package.json and compile it to URLPattern rules. A missing,
@@ -484,6 +527,14 @@ export async function createRequestHandler(opts) {
   // id is a stable deploy fingerprint independent of per-file content hashes.
   setAssetRoots({ appDir, coreDir, enabled: !dev });
 
+  // SSR action-result seeding (#472). Install the process-global module load
+  // hook NOW, at boot, before any `'use server'` action module is imported (ESM
+  // caches by URL, so a module loaded before the hook would never be faceted).
+  // Read once (not per-rebuild): the hook is global and cannot be cleanly
+  // un-installed, so toggling needs a restart. Disabled -> no hook, no ambient
+  // collector wrap in ssr.js, and module loading stays byte-identical.
+  if (await readSeedEnabled(appDir)) registerSeedHooks();
+
   // When an app commits a vendor pin (.webjs/vendor/importmap.json) it carries a
   // deterministic vendor map that is cheap to read (one file, no analysis, no
   // network). Resolve it AT BOOT and publish the build id immediately so the
@@ -1644,7 +1695,12 @@ async function handleCore(req, ctx) {
   // Internal server-action RPC endpoint
   const actMatch = /^\/__webjs\/action\/([a-f0-9]+)\/([A-Za-z0-9_$]+)$/.exec(path);
   if (actMatch) {
-    if (method !== 'POST') return new Response('POST only', { status: 405 });
+    // HTTP-verb actions (#488): any RPC verb may hit the endpoint; invokeAction
+    // enforces the action's DECLARED method (405 + Allow on a mismatch) and
+    // reads args from the URL (GET/DELETE) or the body (POST/PUT/PATCH).
+    if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+      return new Response('method not allowed', { status: 405 });
+    }
     // Pass the onError sink (issue #239): a server action that throws
     // unexpectedly is reported to the APM hook before the sanitized 500.
     const onActionError = reportError ? (e) => reportError(e, req, 'action') : undefined;

package/src/ssr.js

@@ -7,6 +7,7 @@ import { withAssetHash } from './asset-hash.js';
 import { jsonForScriptTag } from './script-tag-json.js';
 import { readToken, newToken, cookieHeader } from './csrf.js';
 import { transitiveDeps } from './module-graph.js';
+import { seedingEnabled, collectSeeds, buildSeedScript } from './action-seed.js';
 import { BUFFERED_MARKER, STREAM_MARKER } from './conditional-get.js';
 import {
   readRevalidate,
@@ -94,7 +95,21 @@ export async function ssrPage(route, params, url, opts) {
     const have = haveHeader
       ? new Set(haveHeader.split(',').map((s) => s.trim()).filter(Boolean))
       : null;
-    const body = await renderChain(route, ctx, opts.dev, suspenseCtx, have, opts.pageModule);
+    // SSR action-result seeding (#472). When enabled, run the whole render
+    // inside an ambient seed collector so every `'use server'` action a
+    // component awaits in `async render()` records its (args -> result) for the
+    // hydration payload. Disabled -> the plain render, byte-identical to before.
+    let seedCollector = null;
+    let body;
+    if (seedingEnabled()) {
+      const seeded = await collectSeeds(() =>
+        renderChain(route, ctx, opts.dev, suspenseCtx, have, opts.pageModule),
+      );
+      body = seeded.value;
+      seedCollector = seeded.collector;
+    } else {
+      body = await renderChain(route, ctx, opts.dev, suspenseCtx, have, opts.pageModule);
+    }
 
     // Frame subtree render (#253). A `<webjs-frame src>` self-load (or a
     // click-driven frame nav) sends `x-webjs-frame: <id>` and applies ONLY the
@@ -170,9 +185,20 @@ export async function ssrPage(route, params, url, opts) {
     // shell. Either way the returned `prefix` ends just past the open <body>
     // and `closer` is the matching `</body></html>`.
     const { prefix, streamBody, closer } = buildDocumentParts(body, wrapOpts);
+    // Append the SSR action-seed payload (#472) to the non-streamed body so the
+    // client's first render reads it instead of re-issuing the RPC. Only for a
+    // fully-buffered (non-streaming) render: a streamed page's deferred
+    // boundaries resolve AFTER the first flush, so their seeds cannot ride this
+    // block (those slow regions keep the stale-while-revalidate refetch). An
+    // empty collector yields '' so the output stays byte-identical.
+    let outBody = streamBody;
+    if (seedCollector && suspenseCtx.pending.length === 0) {
+      const seedScript = await buildSeedScript(seedCollector);
+      if (seedScript) outBody = streamBody + seedScript;
+    }
     const res = streamingHtmlResponse(
       prefix,
-      streamBody,
+      outBody,
       closer,
       suspenseCtx,
       // Normally 200. After a failed page `action` submission the caller passes

package/webjs-config.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://webjs.dev/schemas/webjs-config.schema.json",
   "title": "webjs config block",
   "description": "Schema for the `webjs` object in a webjs app's package.json. Each key maps to a documented server reader. An unknown key is flagged (additionalProperties is false) so a typo no longer silently falls back to the default.",
-  "$comment": "Single source of truth lives in THREE co-located places that must stay in lockstep: this schema, the TS type at packages/core/src/webjs-config.d.ts, and the server reader functions (readElideEnabled in dev.js, compileHeaderRules in headers.js, compileRedirectRules / readTrailingSlashPolicy in redirects.js, readBasePath in base-path.js, readCspConfig in csp.js, readBodyLimits / computeServerTimeouts in body-limit.js). Adding a webjs.* key means updating all three. See packages/server/AGENTS.md for the one documented procedure.",
+  "$comment": "Single source of truth lives in THREE co-located places that must stay in lockstep: this schema, the TS type at packages/core/src/webjs-config.d.ts, and the server reader functions (readElideEnabled in dev.js, readSeedEnabled in dev.js, compileHeaderRules in headers.js, compileRedirectRules / readTrailingSlashPolicy in redirects.js, readBasePath in base-path.js, readCspConfig in csp.js, readBodyLimits / computeServerTimeouts in body-limit.js). Adding a webjs.* key means updating all three. See packages/server/AGENTS.md for the one documented procedure.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -12,6 +12,11 @@
       "type": "boolean",
       "default": true
     },
+    "seed": {
+      "description": "SSR action-result seeding switch (#472). Default true. When on, a 'use server' action's SSR result is serialized into the page so an async-render component does not re-fetch it over RPC on hydration. Set to false to disable (the client re-fetches as before). Read by readSeedEnabled in dev.js; the WEBJS_SEED env override wins over this.",
+      "type": "boolean",
+      "default": true
+    },
     "headers": {
       "description": "Per-path response-header rules, shaped like Next's. Each rule pairs a URLPattern source against header directives. Read by compileHeaderRules in headers.js.",
       "type": "array",