@webjsdev/cli 0.10.42 → 0.10.44

package/lib/create.js

@@ -18,6 +18,7 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
+import { leanComponentSource } from './lean-copy.js';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -120,12 +121,16 @@ async function readUiComponent(name) {
   const raw = await readFile(src, 'utf8');
   // The registry component imports cn() via a relative `../lib/utils.ts`; rewrite
   // it to the scaffolded app's aliased path (cn lives at lib/utils/cn.ts).
-  return raw
+  const rewritten = raw
     .replaceAll("'../lib/utils.ts'", "'#lib/utils/cn.ts'")
     .replaceAll('"../lib/utils.ts"', '"#lib/utils/cn.ts"')
     // onBeforeCache lives in its own client-only module so cn() stays pure (#819).
     .replaceAll("'../lib/dom.ts'", "'#lib/utils/dom.ts'")
     .replaceAll('"../lib/dom.ts"', '"#lib/utils/dom.ts"');
+  // Strip the worked @example from a Tier-1 helper (same as `webjs ui add`), so
+  // the scaffolded component is lean and the example is served on demand. The
+  // shared helper is used by the saas-template copier too, so they cannot drift.
+  return leanComponentSource(rewritten, name);
 }
 
 /**
@@ -1346,6 +1351,7 @@ const FEATURES = [
   { href: '/features/caching', title: 'Caching', blurb: 'export const revalidate caches the page HTML per URL, with the safety rule for when a shared cache is allowed.' },
   { href: '/features/env', title: 'Env vars', blurb: 'The server-only vs WEBJS_PUBLIC_ boundary, read during SSR so secrets never reach the browser.' },
   { href: '/features/client-router', title: 'Client router', blurb: 'Automatic soft navigation: fragment-only fetches, hover prefetch, scroll restore, and graceful no-JS fallback.' },
+  { href: '/features/frames', title: 'Frames', blurb: 'A webjs-frame region that swaps a filtered sub-list in place from a link, shipping zero component JS, with a no-JS full-nav fallback.' },
   { href: '/features/service-worker', title: 'Service worker', blurb: 'The opt-in offline enhancement, registered from a browser-only lifecycle hook (never a page or layout).' },
   { href: '/features/websockets', title: 'WebSockets', blurb: 'A WS(ws, req) route endpoint plus the connectWS() client, echoing messages over a live socket.' },
   { href: '/features/broadcast', title: 'Broadcast', blurb: 'Fan a message out to every connected client on a WebSocket path, so all open tabs stay in sync.' },

package/lib/lean-copy.js

@@ -0,0 +1,43 @@
+/**
+ * The scaffold's lean-copy of a ui component (#983).
+ *
+ * `webjs create` copies a few `@webjsdev/ui` registry components into a
+ * generated app. To match what `webjs ui add` writes, a Tier-1 helper's worked
+ * `@example` is stripped (the example is served on demand by `webjs ui view` /
+ * the MCP `ui` tool), while a Tier-2 element file is kept whole. Both scaffold
+ * copiers (`create.js` and `saas-template.js`) go through THIS one helper so
+ * they cannot drift.
+ *
+ * The strip primitives live in `@webjsdev/ui/registry/extract`; if that subpath
+ * cannot be resolved, this degrades to a no-op (keep the example) so the strip
+ * is never a reason `webjs create` fails.
+ *
+ * @module lean-copy
+ */
+
+let _mod = null;
+
+async function loadPrimitives() {
+  if (_mod) return _mod;
+  try {
+    const m = await import('@webjsdev/ui/registry/extract');
+    _mod = { stripExample: m.stripExample, isCustomElementSource: m.isCustomElementSource };
+  } catch {
+    _mod = { stripExample: (s) => s, isCustomElementSource: () => true };
+  }
+  return _mod;
+}
+
+/**
+ * Return the component source as `webjs ui add` would write it: a Tier-1 helper
+ * has its worked `@example` stripped and a pointer left; a Tier-2 element is
+ * returned unchanged.
+ *
+ * @param {string} source  the component source (imports already rewritten)
+ * @param {string} name    the component name (for the pointer)
+ * @returns {Promise<string>}
+ */
+export async function leanComponentSource(source, name) {
+  const { stripExample, isCustomElementSource } = await loadPrimitives();
+  return isCustomElementSource(source) ? source : stripExample(source, name);
+}

package/lib/saas-template.js

@@ -5,6 +5,7 @@
 
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { bunifyProse } from './runtime-rewrite.js';
+import { leanComponentSource } from './lean-copy.js';
 import { existsSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -25,7 +26,7 @@ async function readUiComponent(name) {
   const raw = await readFile(src, 'utf8');
   // The registry component imports cn() via a relative `../lib/utils.ts`; rewrite
   // it to the scaffolded app's aliased path (cn lives at lib/utils/cn.ts).
-  return raw
+  const rewritten = raw
     .replaceAll("'../lib/utils.ts'", "'#lib/utils/cn.ts'")
     .replaceAll('"../lib/utils.ts"', '"#lib/utils/cn.ts"')
     // onBeforeCache lives in its own client-only module so cn() stays pure (#819).
@@ -33,6 +34,9 @@ async function readUiComponent(name) {
     // (which resolves to a nonexistent components/lib/dom.ts) and fails typecheck.
     .replaceAll("'../lib/dom.ts'", "'#lib/utils/dom.ts'")
     .replaceAll('"../lib/dom.ts"', '"#lib/utils/dom.ts"');
+  // Strip a Tier-1 helper's worked @example (same as create.js + `webjs ui add`)
+  // so switch / checkbox are lean, not just the full-stack base set (#983).
+  return leanComponentSource(rewritten, name);
 }
 
 /** Copy named registry components into `<appDir>/components/ui/`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.42",
+  "version": "0.10.44",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/skills/webjs/SKILL.md

@@ -44,6 +44,7 @@ Classify the task first, then load the smallest useful reference set. Each refer
 | Tailwind, light-DOM tag-prefix rule, tokens, fixed headers, no-reflow layout | `references/styling.md`                        |
 | Client router, prefetch, frames, view transitions, Suspense streaming        | `references/client-router-and-streaming.md`   |
 | Optimistic UI for a user-facing mutation                                     | `references/optimistic-ui.md`                 |
+| The `@webjsdev/ui` component kit (a `components.json` is present): class helpers, tokens, `add` / `view`, the MCP `ui` tool | `references/ui-kit.md`                         |
 | TypeScript at runtime, erasable syntax, full-stack types                     | `references/typescript.md`                     |
 | Unit, browser, e2e tests, the `handle()` harness, Bun parity                 | `references/testing.md`                        |
 | Auth, caching, env vars, rate limit, file storage, the `webjs` config block  | `references/built-ins.md`                      |

package/templates/.agents/skills/webjs/references/client-router-and-streaming.md

@@ -17,6 +17,8 @@ Read this when a task touches client navigation, prefetch, partial-page swaps, s
 
 The router auto-enables the moment `@webjsdev/core` loads in the browser, which is any page that ships a component. There is nothing to import or opt into. It intercepts same-origin `<a>` clicks (including inside shadow DOM), fetches the target HTML, and replaces only the inside of the deepest shared layout. Outer header, sidenav, and footer DOM is never re-rendered, so scroll positions, input values, and `<details>` state survive a navigation.
 
+**Browser resilience: a dropped layout-marker comment.** SSR wraps each layout's children in a `<!--wj:children:<path>-->...<!--/wj:children-->` comment pair, and the deepest-shared-layout swap matches on those markers. Browsers intermittently DROP the trailing `<!--/wj:children-->` comment while parsing a soft-nav response (the open marker survives, the close does not), which leaves the router with no pairable slot and forces the destructive full-body swap that wipes the outer layout (the top navbar). This is a parse/timing race, not a browser-specific quirk: it surfaced first on Android Chrome (far more frequent under mobile CPU/memory pressure) and was later reproduced on desktop Chromium, so treat it as universal. The router recovers an orphaned open marker (treating the children as running to the end of the containing element), so a lost close comment still takes the correct scoped swap and the outer chrome keeps its DOM identity. The fix keys off the symptom (a missing close), never a user-agent check, so it covers every engine. A page whose sole or outermost close was dropped also omits that layout from its `X-Webjs-Have` request, so the server returns the FULL page (with its trailing chrome) rather than a reduced marker-pair-only fragment, and the swap is bounded against that full page's trailing-sibling count so a `<footer>` in the marker's OWN parent is preserved rather than swept. Wrapping `${children}` in a container element (the shipped idiom, `<main>${children}</main>` with the footer a sibling outside it) keeps this trivially correct, since the close marker is then the parent's last child, and it is the safe pattern for the remaining unhandled shape (a dropped INNER close in a nested layout, which mispairs and could otherwise sweep outer trailing content). Like the iOS-WebKit repaint note in [styling.md](./styling.md), this is a real-browser divergence from headless Chromium, but because it reproduces across engines the deterministic dropped-close browser test is the reliable way to guard it (a single desktop or device pass can miss the race).
+
 **Opting out.** App-wide with config, or per moment at runtime.
 
 ```jsonc

package/templates/.agents/skills/webjs/references/ui-kit.md

@@ -0,0 +1,68 @@
+# The `@webjsdev/ui` component kit
+
+Load this when the app has a `components.json` (it uses `@webjsdev/ui`, the
+shadcn-style kit for WebJs). The source is copied into your repo (`components/ui/`),
+so you own and edit it. Two tiers:
+
+- **Tier 1, class helpers (23 components).** Pure functions returning Tailwind
+  class strings (`buttonClass({ variant })`, `cardClass()`), composed with
+  whatever native element you write. Reach for these instead of expanding
+  Tailwind by hand: the call site is a fraction of the tokens and the class list
+  cannot drift.
+- **Tier 2, stateful custom elements (9 components).** `<ui-dialog>`, `<ui-tabs>`,
+  `<ui-dropdown-menu>`, and friends own their ARIA (focus trap, roving tabindex,
+  `aria-controls` / `inert`, live regions). Write the tag and the accessible
+  behaviour comes with it. Do NOT hand-roll these; the wiring is easy to get
+  subtly wrong.
+
+## The workflow: query for the structure, do not guess it
+
+`add` copies a Tier-1 component's class helpers plus a lean header (what each
+helper is, the accessibility obligations) and a one-line pointer. It does NOT
+copy the worked structural example, because that example is guidance you consume
+once while composing, not code that should sit in your repo. Get the full
+paste-ready structure on demand:
+
+- **MCP `ui` tool** (preferred when available): call `ui` with no args for the
+  kit inventory (each component's tier, helper signatures, npm deps); pass
+  `{ name: "accordion" }` for one component's helper signatures, the paste-ready
+  structural example, the accessibility header, and deps.
+- **CLI**: `webjs ui list` (inventory), `webjs ui view <name>` (the projected
+  view plus the full source). Same data as the MCP tool (one shared projector).
+
+So the loop is: `add` the component, then query `ui <name>` (MCP) or
+`webjs ui view <name>` for the accessible structure, paste it, and fill it in.
+
+## Setup and resolution
+
+- `webjs ui init` writes `components.json`, `lib/utils.ts`, and the CSS design
+  tokens the helpers render against (`--background`, `--foreground`,
+  `--destructive`, ...). It HARD-FAILS if the tokens cannot be written, so a
+  clean exit means the kit is styled. `add` self-heals the tokens if they go
+  missing.
+- Resolution is LOCAL-FIRST: `init` / `add` / `list` / `view` read the registry
+  that ships inside the installed `@webjsdev/ui`, with no network. This pins you
+  to the installed version; run `webjs ui diff` to see where your local copies
+  drift from the upstream (that command alone compares against the live registry).
+
+## Inventory (run `webjs ui list` or the MCP `ui` tool for the authoritative, current set)
+
+**Tier 1 (class helpers):** accordion, alert, aspect-ratio, avatar, badge,
+breadcrumb, button, card, checkbox, collapsible, input, kbd, label,
+native-select, pagination, popover, progress, radio-group, separator, skeleton,
+switch, table, textarea.
+
+**Tier 2 (custom elements, own their ARIA):** alert-dialog, dialog,
+dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
+(these two register an element AND export a `*Class` helper).
+
+## Idioms
+
+- A helper is a function, so compose it: `class=${buttonClass({ variant: 'outline' })}`.
+  The unquoted `${...}` is a normal `html` attribute hole.
+- Tier-1 helpers assume the design tokens exist; if a component paints unstyled,
+  the tokens are missing (re-run `webjs ui init` or let `add` self-heal them).
+- Custom elements are display-only-safe at SSR and hydrate in the browser, the
+  standard WebJs component model (`references/components.md`).
+
+Full per-package reference lives in the installed `@webjsdev/ui/AGENTS.md`.

package/templates/gallery/app/features/frames/page.ts

@@ -0,0 +1,71 @@
+// <webjs-frame> is a URL-addressable region that swaps ON ITS OWN, driven by a
+// link targeting its id, shipping zero component JS. It is WebJs's take on Turbo
+// Frames. Unlike the client router (which swaps the whole page's children when
+// you navigate to a DIFFERENT url), a frame refreshes just ONE sub-region in
+// place. The filter links below live INSIDE the frame, so a click walks
+// closest('webjs-frame'), refetches THIS same page with the new ?status, and the
+// server returns ONLY the <webjs-frame id="tasks"> subtree (open the network tab
+// to see it). The router swaps that subtree in; everything outside the frame,
+// the heading and the intro copy, never re-renders.
+//
+// Progressive enhancement: with JS off, each filter link is a normal full-page
+// navigation to ?status=..., which re-renders the whole page with the same
+// filtered list. The frame is an enhancement on top of a working page, never a
+// requirement. The frame element itself upgrades because the root layout ships a
+// component (the theme toggle), so @webjsdev/core and the router load app-wide.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import { filterTasks, normalizeStatus, type Status } from '#modules/frames/utils/tasks.ts';
+
+export const metadata: Metadata = { title: 'Frames (webjs-frame partial swap) | features' };
+
+// One filter tab. The href targets THIS page with a new ?status. Because it sits
+// inside the frame, the router scopes the swap to the frame id automatically. A
+// link OUTSIDE the frame would drive it from anywhere via data-webjs-frame="tasks".
+function filterTab(current: Status, status: Status, label: string) {
+  const active = current === status;
+  const base = 'px-3 py-1.5 rounded-lg font-semibold text-sm no-underline transition-colors';
+  const cls = active
+    ? base + ' bg-primary text-primary-foreground'
+    : base + ' bg-card border border-border text-foreground font-medium hover:border-border-strong';
+  return html`<a href="/features/frames?status=${status}" class=${cls}>${label}</a>`;
+}
+
+export default function FramesExample({ searchParams }: { searchParams: Record<string, string | undefined> }) {
+  const status = normalizeStatus(searchParams?.status);
+  const tasks = filterTasks(status);
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Frames</h1>
+    <p class="text-muted-foreground mb-4">
+      Filter the list. With JS on, only the framed region swaps (the response is
+      just the frame's subtree, not the whole page) and the heading above never
+      re-renders. With JS off, the same links do full-page navigations. It is one
+      region refreshing independently of a navigation, which a page cannot express.
+    </p>
+    <webjs-frame id="tasks" class="block p-4 rounded-2xl bg-card border border-border">
+      <div class="flex gap-2 mb-4">
+        ${filterTab(status, 'all', 'All')}
+        ${filterTab(status, 'active', 'Active')}
+        ${filterTab(status, 'done', 'Done')}
+      </div>
+      <ul class="grid gap-2 m-0 p-0 list-none">
+        ${tasks.map(
+          (t) => html`
+            <li class="flex items-center gap-2 text-foreground">
+              <span class=${t.done ? 'text-primary' : 'text-muted-foreground'}>${t.done ? '✓' : '○'}</span>
+              <span class=${t.done ? 'line-through text-muted-foreground' : ''}>${t.title}</span>
+            </li>
+          `,
+        )}
+      </ul>
+    </webjs-frame>
+    <p class="text-muted-foreground text-sm mt-6">
+      A frame can also self-load with <code class="font-mono">src</code>
+      (<code class="font-mono">loading="lazy"</code> defers the fetch to viewport
+      entry), or be driven from outside via
+      <code class="font-mono">data-webjs-frame="tasks"</code>.
+      <code class="font-mono">data-webjs-frame="_top"</code> breaks out to a
+      full-page navigation.
+    </p>
+  `;
+}

package/templates/gallery/app/features/server-actions/page.ts

@@ -8,6 +8,14 @@ export default function ServerActionsExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Server actions</h1>
     <p class="text-muted-foreground mb-4">A 'use server' action is RPC-callable from the client; a plain .server.ts is a server-only utility you never import into a component.</p>
+    <p class="text-muted-foreground mb-4">
+      This action also declares <code class="font-mono">export const middleware</code>: a
+      chain that runs around it on every boundary. The auth middleware sets the
+      caller on the request context (read back with <code class="font-mono">actionContext()</code>)
+      or 401s before the action runs. The action threads
+      <code class="font-mono">actionSignal()</code>, the request AbortSignal, through
+      its work so a client disconnect or a superseded render stops it early.
+    </p>
     <server-greeter></server-greeter>
   `;
 }

package/templates/gallery/modules/frames/utils/tasks.ts

@@ -0,0 +1,27 @@
+// Pure data plus a filter for the frames demo. No server-only deps and no
+// 'use server', so it is a plain browser-safe .ts the page reads during SSR to
+// render the frame's current contents. The frame swap re-renders THIS list in
+// place from the ?status query, shipping no component JS.
+export type Status = 'all' | 'active' | 'done';
+export interface Task {
+  title: string;
+  done: boolean;
+}
+
+const TASKS: Task[] = [
+  { title: 'Draft the release notes', done: true },
+  { title: 'Review the frames demo', done: false },
+  { title: 'Ship the gallery update', done: false },
+  { title: 'Reply on the tracking issue', done: true },
+];
+
+// Coerce an untrusted ?status value to a known Status (defaults to 'all').
+export function normalizeStatus(raw: unknown): Status {
+  return raw === 'active' || raw === 'done' ? raw : 'all';
+}
+
+export function filterTasks(status: Status): Task[] {
+  if (status === 'active') return TASKS.filter((t) => !t.done);
+  if (status === 'done') return TASKS.filter((t) => t.done);
+  return TASKS;
+}

package/templates/gallery/modules/server-actions/actions/greet.server.ts

@@ -1,20 +1,51 @@
 'use server';
 // A 'use server' action IS the API: a client import is rewritten to a typed RPC
 // stub POSTing to the server. It may use server-only utilities (they run here,
-// server-side), which is why the util above stays off the client.
+// server-side), which is why the shout() util stays off the client.
 import { shout } from '../utils/format.server.ts';
 import { actionContext, actionSignal } from '@webjsdev/server';
 import type { ActionResult } from '@webjsdev/server';
+import { requireAuth, type AuthUser } from '../middleware/require-auth.server.ts';
 
-export async function greet(input: { name: string }): Promise<ActionResult<{ message: string }>> {
-  // actionSignal() is the request's AbortSignal (fires on client disconnect or a
-  // superseded render); bail early on long work instead of finishing wasted work.
-  if (actionSignal().aborted) return { success: false, error: 'Request cancelled.', status: 499 };
-  // actionContext() is the per-action middleware context (e.g. actionContext().user
-  // set by an auth middleware via `export const middleware`). Empty here, no middleware.
-  const who = (actionContext().user as { name?: string } | undefined)?.name;
+// `export const middleware` is a reserved sibling config export the framework
+// reads statically (the same way a page declares `export const revalidate`). The
+// chain runs around greet() on every boundary: requireAuth either short-circuits
+// (the action never runs) or stashes the caller on the request context.
+export const middleware = [requireAuth];
 
-  const name = String(input?.name ?? who ?? '').trim();
+export async function greet(input: { name: string; signedOut?: boolean }): Promise<ActionResult<{ message: string }>> {
+  // actionContext() is populated ONLY on a boundary that runs the middleware
+  // chain (the RPC stub here, or a route() adapter). requireAuth runs there and
+  // guarantees a user, so `caller` is set on every real call. A DIRECT
+  // server-to-server greet() call skips middleware and leaves it undefined, so
+  // GUARD rather than assume the cast (from server code, pass the caller in
+  // explicitly instead of relying on the context).
+  const caller = actionContext().user as AuthUser | undefined;
+  if (!caller) return { success: false, error: 'Unauthorized.', status: 401 };
+
+  const name = String(input?.name ?? '').trim();
   if (!name) return { success: false, error: 'Name required.', status: 400 };
-  return { success: true, data: { message: shout('hello ' + name) } };
+
+  // actionSignal() is the request's AbortSignal (fires on a client disconnect or a
+  // superseded render). Thread it into the slow work so the work itself aborts
+  // (a real fetch(url, { signal: actionSignal() }) or a DB driver rejects on
+  // abort). lookupGreeting models that, and we map an abort to a cancelled
+  // envelope. A guard BEFORE any await can never fire, since nothing has been
+  // awaited yet, which is why the re-check lives after the await.
+  try {
+    const message = await lookupGreeting(name, caller.name, actionSignal());
+    return { success: true, data: { message } };
+  } catch (e) {
+    if (actionSignal().aborted) return { success: false, error: 'Request cancelled.', status: 499 };
+    throw e;
+  }
+}
+
+// A private (non-exported) stand-in for a slow lookup or upstream fetch, so the
+// file still has exactly one action (the one-action-per-configured-file rule). A
+// real fetch / DB call rejects with an AbortError when the request aborts; greet()
+// catches that and returns the 499 envelope.
+async function lookupGreeting(name: string, who: string, signal: AbortSignal): Promise<string> {
+  if (signal.aborted) throw new DOMException('Aborted', 'AbortError');
+  return shout('hello ' + name) + ' (greeted by ' + who + ')';
 }

package/templates/gallery/modules/server-actions/actions/greet.test.ts

@@ -7,7 +7,7 @@
 // URL against it, params included. See the testing docs.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { createRequestHandler, buildRouteTable, matchPage, matchApi, rawActionRequest } from '@webjsdev/server';
+import { createRequestHandler, buildRouteTable, matchPage, matchApi, rawActionRequest, invokeActionForTest } from '@webjsdev/server';
 
 const appDir = process.cwd();
 
@@ -35,3 +35,36 @@ test('rawActionRequest fires the greet action through the pipeline', async () =>
   );
   assert.equal(res.status, 200);
 });
+
+test('the middleware sets the caller on the context and greet reads it via actionContext()', async () => {
+  const app = await createRequestHandler({ appDir, dev: true });
+  if (app.warmup) await app.warmup();
+  // invokeActionForTest returns the deserialized result as unknown; cast to the
+  // action's ActionResult shape to read it.
+  const r = (await invokeActionForTest(
+    app,
+    'modules/server-actions/actions/greet.server.ts',
+    'greet',
+    [{ name: 'Bob' }],
+  )) as { success: boolean; data?: { message: string }; error?: string; status?: number };
+  assert.equal(r.success, true);
+  // The message carries BOTH the input (Bob) and the middleware-set caller (Ada).
+  assert.match(r.data?.message ?? '', /BOB/);
+  assert.match(r.data?.message ?? '', /Ada/);
+});
+
+test('the auth middleware short-circuits a signed-out request before greet runs', async () => {
+  const app = await createRequestHandler({ appDir, dev: true });
+  if (app.warmup) await app.warmup();
+  // A middleware short-circuit rides as a normal failure envelope (200 with the
+  // status inside), so read the result rather than expecting a thrown non-2xx.
+  const r = (await invokeActionForTest(
+    app,
+    'modules/server-actions/actions/greet.server.ts',
+    'greet',
+    [{ name: 'Bob', signedOut: true }],
+    { throwOnError: false },
+  )) as { success: boolean; data?: { message: string }; error?: string; status?: number };
+  assert.equal(r.success, false);
+  assert.equal(r.status, 401);
+});

package/templates/gallery/modules/server-actions/components/greeter.ts

@@ -5,11 +5,16 @@ import { greet } from '../actions/greet.server.ts';
 
 export class Greeter extends WebComponent {
   private msg = signal('');
+  // Drives the requireAuth middleware on the action: when true the request is
+  // treated as signed-out, so the middleware 401s BEFORE greet() runs.
+  private signedOut = signal(false);
+
   async run(e: SubmitEvent) {
     e.preventDefault();
     const name = String(new FormData(e.target as HTMLFormElement).get('name') ?? '');
-    const r = await greet({ name });
-    // Narrow on r.success so TS knows `data` (success) vs `error` (failure).
+    const r = await greet({ name, signedOut: this.signedOut.get() });
+    // Narrow on r.success so TS knows `data` (success) vs `error` (failure). A
+    // middleware short-circuit arrives here as a normal failure envelope.
     this.msg.set(r.success ? (r.data?.message ?? '') : (r.error ?? 'error'));
   }
   render() {
@@ -22,6 +27,10 @@ export class Greeter extends WebComponent {
           <button type="submit"
             class="shrink-0 px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Greet</button>
         </form>
+        <label class="flex items-center gap-2 text-sm text-muted-foreground cursor-pointer select-none">
+          <input type="checkbox" @change=${(e: Event) => this.signedOut.set((e.target as HTMLInputElement).checked)} />
+          Simulate a signed-out visitor (the middleware 401s before the action runs)
+        </label>
         ${this.msg.get() ? html`<p class="m-0 font-semibold text-foreground">${this.msg.get()}</p>` : ''}
       </div>
     `;

package/templates/gallery/modules/server-actions/middleware/require-auth.server.ts

@@ -0,0 +1,42 @@
+// Per-action middleware. An action opts in with `export const middleware =
+// [requireAuth]` (a reserved sibling config export), and the framework runs this
+// around the action on EVERY boundary (the RPC stub and a route.ts adapter). The
+// signature is `async (ctx, next) => result`, where ctx = { request, args,
+// signal, context }. Whatever it writes onto ctx.context is exactly what the
+// action reads back via actionContext(). This is a server-only utility (a
+// .server.ts with NO 'use server'): the action imports it server-side; it never
+// ships to the browser.
+import type { ActionResult } from '@webjsdev/server';
+
+export interface AuthUser {
+  id: string;
+  name: string;
+}
+
+// The context object the framework passes each middleware. `context` is the
+// shared mutable bag actionContext() returns to the action; `args` is the
+// action's argument list; `signal` is the request AbortSignal.
+interface ActionMiddlewareCtx {
+  request: Request;
+  args: unknown[];
+  signal: AbortSignal;
+  context: Record<string, unknown>;
+}
+
+export async function requireAuth(ctx: ActionMiddlewareCtx, next: () => Promise<unknown>): Promise<unknown> {
+  // A REAL guard reads the signed session or JWT off ctx.request, because auth
+  // belongs to the request, not the payload. This gallery has no login backend on
+  // the action path, so to keep BOTH branches exercisable the demo treats the
+  // caller as signed in UNLESS the request asks to simulate a signed-out visitor
+  // (the checkbox in the component sends { signedOut: true } in the action input).
+  const [input] = ctx.args as [{ signedOut?: boolean } | undefined];
+  const user: AuthUser | null = input?.signedOut ? null : { id: 'u_1', name: 'Ada' };
+
+  // Short-circuit: return an ActionResult WITHOUT calling next(), so the action
+  // never runs. On the RPC boundary the short-circuit rides as the result with its
+  // status inside the envelope, and a denied call is served no-store (never cached).
+  if (!user) return { success: false, error: 'Sign in to continue.', status: 401 } satisfies ActionResult<never>;
+
+  ctx.context.user = user; // what actionContext().user reads inside the action
+  return next(); // run the next middleware, ending at the action
+}

package/templates/scripts/clear-gallery.mjs

@@ -40,8 +40,8 @@ const galleryPaths = [
 // 2) The gallery's feature modules (by name, so saas auth modules survive).
 const galleryModules = [
   'async-render', 'broadcast', 'caching', 'client-router', 'components',
-  'directives', 'file-storage', 'optimistic-ui', 'rate-limit', 'route-handler',
-  'server-actions', 'sessions', 'todo', 'websockets',
+  'directives', 'file-storage', 'frames', 'optimistic-ui', 'rate-limit',
+  'route-handler', 'server-actions', 'sessions', 'todo', 'websockets',
 ].map((m) => `modules/${m}`);
 
 let removed = 0;